Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

Docs: Python tutorials doc fixes #17435

Merged
merged 13 commits into from
Feb 4, 2020
8 changes: 4 additions & 4 deletions docs/python_docs/python/api/gluon/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Tutorials

.. card::
:title: Gluon Guide
:link: ../../guide/packages/gluon/
:link: ../tutorials/packages/gluon/index.html

The Gluon guide. Start here!

Expand Down Expand Up @@ -99,13 +99,13 @@ Training

.. card::
:title: gluon.Parameter
:link: mxnet.gluon.Parameter.html
:link: parameter.html

Parameter getting and setting functions.

.. card::
:title: gluon.Trainer
:link: mxnet.gluon.Trainer.html
:link: trainer.html

Functions for applying an optimizer on a set of parameters.

Expand All @@ -128,7 +128,7 @@ Data

.. card::
:title: gluon.model_zoo.vision
:link: model_zoo/index.vision.html
:link: model_zoo/index.html

A module for loading pre-trained neural network models.

Expand Down
5 changes: 2 additions & 3 deletions docs/python_docs/python/tutorials/extend/custom_layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,9 @@ In this article, I will cover how to create a new layer from scratch, how to use

## The simplest custom layer

To create a new layer in Gluon API, one must create a class that inherits from [Block](https://github.com/apache/incubator-mxnet/blob/master/python/mxnet/gluon/block.py#L123) class. This class provides the most basic functionality, and all pre-defined layers inherit from it directly or via other subclasses. Because each layer in Apache MxNet inherits from `Block`, words "layer" and "block" are used interchangeable inside of the Apache MxNet community.
To create a new layer in Gluon API, one must create a class that inherits from [Block](https://github.com/apache/incubator-mxnet/blob/c9818480680f84daa6e281a974ab263691302ba8/python/mxnet/gluon/block.py#L128) class. This class provides the most basic functionality, and all pre-defined layers inherit from it directly or via other subclasses. Because each layer in Apache MxNet inherits from `Block`, words "layer" and "block" are used interchangeable inside of the Apache MxNet community.

- MXNet [7b24137](https://github.com/apache/incubator-mxnet/commit/7b24137ed45df605defa4ce72ec91554f6e445f0). See Instructions in [Setup and Installation]({{'/get_started'|relative_url}}).
The only instance method needed to be implemented is [forward(self, x)](https://github.com/apache/incubator-mxnet/blob/master/python/mxnet/gluon/block.py#L415), which defines what exactly your layer is going to do during forward propagation. Notice, that it doesn't require to provide what the block should do during back propogation. Back propogation pass for blocks is done by Apache MxNet for you.
The only instance method needed to be implemented is [forward(self, x)](https://github.com/apache/incubator-mxnet/blob/c9818480680f84daa6e281a974ab263691302ba8/python/mxnet/gluon/block.py#L909), which defines what exactly your layer is going to do during forward propagation. Notice, that it doesn't require to provide what the block should do during back propogation. Back propogation pass for blocks is done by Apache MxNet for you.

In the example below, we define a new layer and implement `forward()` method to normalize input data by fitting it into a range of [0, 1].

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

One of the reasons for the success of deep learning can be found in the wide range of re-usable layers that can be used in a deep network. This allows for a tremendous degree of customization and adaptation. Sooner or later you will encounter a layer that doesn't exist yet in Gluon or one that you want to create. This is when it's time to build a custom layer. This section shows you how.

Defining a layer is as easy as subclassing [`nn.Block`](/api/gluon/mxnet.gluon.nn.Block.html#mxnet.gluon.nn.Block) or [`nn.HybridBlock`](/api/gluon/mxnet.gluon.nn.HybridBlock.html#mxnet.gluon.nn.HybridBlock) and implementing `forward` or `hybrid_forward`, respectively. To take advantage of the performance gains with `nn.HybridBlock` see the section on [Hybridization](hybridize.html).
Defining a layer is as easy as subclassing [nn.Block](/api/gluon/mxnet.gluon.nn.Block.html#mxnet.gluon.nn.Block) or [nn.HybridBlock](/api/gluon/mxnet.gluon.nn.HybridBlock.html#mxnet.gluon.nn.HybridBlock) and implementing `forward` or `hybrid_forward`, respectively. To take advantage of the performance gains with `nn.HybridBlock` see the section on [Hybridization](hybridize.html).

Note that we've gone through rationale for defining layers, but `nn.Block`'s work even for non-sequential network. In fact, you can use a `Block` to encapsualte any re-usable architecture you want.

Expand Down Expand Up @@ -71,7 +71,7 @@ y.mean().asscalar()

## Layers with Parameters

Now that we know how to define layers in principle, let's define layers with parameters. These can be adjusted through training. In order to simplify things for an avid deep learning researcher, the [`Parameter`](/api/gluon/mxnet.gluon.parameter.html) class and the `ParameterDict` dictionary provide some basic housekeeping functionality. In particular, they govern access, initialization, sharing, saving and loading model parameters. For instance, this way we don't need to write custom serialization routines for each new custom layer.
Now that we know how to define layers in principle, let's define layers with parameters. These can be adjusted through training. In order to simplify things for an avid deep learning researcher, the [Parameter](/api/gluon/mxnet.gluon.parameter.html) class and the `ParameterDict` dictionary provide some basic housekeeping functionality. In particular, they govern access, initialization, sharing, saving and loading model parameters. For instance, this way we don't need to write custom serialization routines for each new custom layer.

We can access the parameters via the `params` variable of the `ParameterDict` in `Block`. The parameter dictionary is just that - a dictionary that maps string type parameter names to model parameters in the `Parameter` type. We can create a `Parameter` instance from `ParameterDict` via the `get` function which attempts to retrieve a parameter, or create it if not found.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ We can see that the three lines of print statements defined in the `hybrid_forwa

## Key differences and limitations of hybridization

The difference between a purely imperative `Block` and hybridizable `HybridBlock` can superficially appear to be simply the injection of the `F` function space (resolving to [`mx.nd`](/api/python/docs/api/ndarray/index.html) or [`mx.sym`](/api/python/docs/api/symbol/index.html)) in the forward function that is renamed from `forward` to `hybrid_forward`. However there are some limitations that apply when using hybrid blocks. In the following section we will review the main differences, giving example of code snippets that generate errors when such blocks get hybridized.
The difference between a purely imperative `Block` and hybridizable `HybridBlock` can superficially appear to be simply the injection of the `F` function space (resolving to [mx.nd](/api/python/docs/api/ndarray/index.html) or [mx.sym](/api/python/docs/api/symbol/index.html)) in the forward function that is renamed from `forward` to `hybrid_forward`. However there are some limitations that apply when using hybrid blocks. In the following section we will review the main differences, giving example of code snippets that generate errors when such blocks get hybridized.

### Indexing

Expand All @@ -234,7 +234,7 @@ Would generate the following error:

`TypeError: Symbol only support integer index to fetch i-th output`

There are however several operators that can help you with array manipulations like: [`F.split`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.split), [`F.slice`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.slice), [`F.take`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.take),[`F.pick`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.pick), [`F.where`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.where), [`F.reshape`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.reshape) or [`F.reshape_like`](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.reshape_like).
There are however several operators that can help you with array manipulations like: [F.split](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.split), [F.slice](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.slice), [F.take](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.take),[F.pick](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.pick), [F.where](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.where), [F.reshape](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.reshape) or [F.reshape_like](/api/python/docs/api/ndarray/ndarray.html#mxnet.ndarray.reshape_like).

### Data Type

Expand Down
10 changes: 5 additions & 5 deletions docs/python_docs/python/tutorials/packages/gluon/blocks/nn.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ net(x)

This generates a network with a hidden layer of $256$ units, followed by a ReLU
activation and another $10$ units governing the output. In particular, we used
the [`nn.Sequential`](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Sequential)
the [nn.Sequential](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Sequential)
constructor to generate an empty network into which we then inserted both
layers. What exactly happens inside `nn.Sequential`
has remained rather mysterious so far. In the following we will see that this
Expand Down Expand Up @@ -81,7 +81,7 @@ layers to defining blocks (of one or more layers):

## A Sequential Block

The [`Block`](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block) class is a generic component
The [Block](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block) class is a generic component
describing data flow. When the data flows through a sequence of blocks, each
block applied to the output of the one before with the first block being
applied on the input data itself, we have a special kind of block, namely the
Expand Down Expand Up @@ -173,7 +173,7 @@ requisite layers. This attaches the coresponding layers and the required
parameters to the class. Note that there is no need to define a backpropagation
method in the class. The system automatically generates the `backward` method
needed for back propagation by automatically finding the gradient (see the tutorial on [autograd](/api/python/docs/tutorials/packages/autograd/index.html)). The same
applies to the [`initialize`](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block.initialize) method, which is generated automatically. Let's try
applies to the [initialize](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block.initialize) method, which is generated automatically. Let's try
this out:

```{.python .input n=2}
Expand All @@ -193,10 +193,10 @@ great flexibility.
## Coding with `Blocks`

### Blocks
The [`Sequential`](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Sequential) class
The [Sequential](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Sequential) class
can make model construction easier and does not require you to define the
`forward` method; however, directly inheriting from
its parent class, [`Block`](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block), can greatly
its parent class, [Block](/api/python/docs/api/gluon/nn/index.html#mxnet.gluon.nn.Block), can greatly
expand the flexibility of model construction. For example, implementing the
`forward` method means you can introduce control flow in the network.

Expand Down
Loading