Merge pull request #5119 from nouiz/doc

NEWS_DEV.txt

@@ -18,7 +18,8 @@ Highlight:
 Computation and compilation speed up
 Multi-cores convolution and pooling on CPU
 More numerical stability by default for some graph.
-CuDNN: 5.1, batch normalization, (RNN soon)
+New 3d convolution and pooling interface
+CuDNN: 5.1, batch normalization, RNN
 Dilated convolution
 Multiple-GPU, synchrone update (via platoon, use NCCL)
 Partial function evaluation

doc/library/gpuarray/dnn.txt

 .. _libdoc_gpuarray_dnn:
 
 ===========================================
-:mod:`gpuarray.dnn` -- cuDNN
+:mod:`theano.gpuarray.dnn` -- cuDNN
 ===========================================
 
 .. moduleauthor:: LISA
@@ -43,7 +43,7 @@ To get an error if Theano can not use cuDNN, use this Theano flag:
 
 .. note::
 
-   cuDNN v5rc is supported in Theano master version. So it dropped cuDNN v3 support.
+   cuDNN v5.1 is supported in Theano master version. So it dropped cuDNN v3 support.
    Theano 0.8.0 and 0.8.1 support only cuDNN v3 and v4.
    Theano 0.8.2 will support only v4 and v5.
 
@@ -132,30 +132,24 @@ To get an error if Theano can not use cuDNN, use this Theano flag:
     cudnn.h must be readable by everybody.
 
 
-Functions
-=========
+- Convolution:
+    - :func:`theano.gpuarray.dnn.dnn_conv`, :func:`theano.gpuarray.dnn.dnn_conv3d`.
+    - :func:`theano.gpuarray.dnn.dnn_gradweight`, :func:`theano.gpuarray.dnn.dnn_gradweight3d`.
+    - :func:`theano.gpuarray.dnn.dnn_gradinput`, :func:`theano.gpuarray.dnn.dnn_gradinput3d`.
+- Pooling:
+    - :func:`theano.gpuarray.dnn.dnn_pool`.
+- Batch Normalization:
+    - :func:`theano.gpuarray.dnn.dnn_batch_normalization_train`
+    - :func:`theano.gpuarray.dnn.dnn_batch_normalization_test`.
+- RNN:
+    - :class:`theano.gpuarray.dnn.RNNBlock`
+- Softmax:
+    - You can manually use the op :class:`GpuDnnSoftmax
+      <theano.gpuarray.dnn.GpuDnnSoftmax>` to use its extra feature.
+
+List of Implemented Operations
+==============================
 
 .. automodule:: theano.gpuarray.dnn
-   :noindex:
-   :members: dnn_conv, dnn_pool
+   :members:
 
-Convolution Ops
-===============
-
-.. automodule:: theano.gpuarray.dnn
-   :noindex:
-   :members: GpuDnnConvDesc, GpuDnnConv, GpuDnnConvGradW, GpuDnnConvGradI
-
-Pooling Ops
-===========
-
-.. automodule:: theano.gpuarray.dnn
-   :noindex:
-   :members: GpuDnnPoolDesc, GpuDnnPool, GpuDnnPoolGrad
-
-Softmax Ops
-===========
-
-.. automodule:: theano.gpuarray.dnn
-   :noindex:
-   :members: GpuDnnSoftmax, GpuDnnSoftmaxGrad

doc/library/sandbox/cuda/dnn.txt

 .. _libdoc_cuda_dnn:
 
-================================
-:mod:`sandbox.cuda.dnn` -- cuDNN
-================================
+=======================================
+:mod:`theano.sandbox.cuda.dnn` -- cuDNN
+=======================================
 
 .. moduleauthor:: LISA
 
 `cuDNN <https://developer.nvidia.com/cuDNN>`_ is an NVIDIA library with
 functionality used by deep neural network. It provides optimized versions
 of some operations like the convolution. cuDNN is not currently
-installed with CUDA 6.5. You must download and install it
+installed with CUDA. You must download and install it
 yourself.
 
 To install it, decompress the downloaded file and make the ``*.h`` and
@@ -46,7 +46,7 @@ get an error when cuDNN can not be used with them, use this flag:
 
 .. note::
 
-   cuDNN v5rc is supported in Theano master version. So it dropped cuDNN v3 support.
+   cuDNN v5.1 is supported in Theano master version. So it dropped cuDNN v3 support.
    Theano 0.8.0 and 0.8.1 support only cuDNN v3 and v4.
    Theano 0.8.2 will support only v4 and v5.
 
@@ -145,42 +145,24 @@ get an error when cuDNN can not be used with them, use this flag:
     cudnn.h must be readable by everybody.
 
 
-Functions
-=========
+- Convolution:
+    - :func:`theano.sandbox.cuda.dnn.dnn_conv`, :func:`theano.sandbox.cuda.dnn.dnn_conv3d`.
+    - :func:`theano.sandbox.cuda.dnn.dnn_gradweight`.
+    - :func:`theano.sandbox.cuda.dnn.dnn_gradinput`.
+- Pooling:
+    - :func:`theano.sandbox.cuda.dnn.dnn_pool`.
+- Batch Normalization:
+    - :func:`theano.sandbox.cuda.dnn.dnn_batch_normalization_train`
+    - :func:`theano.sandbox.cuda.dnn.dnn_batch_normalization_test`.
+- RNN:
+    - :class:`New back-end only! <theano.gpuarray.dnn.RNNBlock>`.
+- Softmax:
+    - You can manually use the op :class:`GpuDnnSoftmax
+      <theano.sandbox.cuda.dnn.GpuDnnSoftmax>` to use its extra feature.
 
-.. automodule:: theano.sandbox.cuda.dnn
-   :noindex:
-   :members: dnn_conv, dnn_pool, dnn_conv3d, dnn_gradweight, dnn_gradinput, dnn_pool, dnn_batch_normalization_train, dnn_batch_normalization_test
-
-Convolution Ops
-===============
-
-.. automodule:: theano.sandbox.cuda.dnn
-   :noindex:
-   :members: GpuDnnConvDesc, GpuDnnConv, GpuDnnConv3d, GpuDnnConvGradW,
-             GpuDnnConv3dGradW, GpuDnnConvGradI, GpuDnnConv3dGradI
-
-Pooling Ops
-===========
-
-.. automodule:: theano.sandbox.cuda.dnn
-   :noindex:
-   :members: GpuDnnPoolDesc, GpuDnnPool, GpuDnnPoolGrad
-
-Softmax Ops
-===========
-
-.. automodule:: theano.sandbox.cuda.dnn
-   :noindex:
-   :members: GpuDnnSoftmax, GpuDnnSoftmaxGrad
-
-
-
-.. _libdoc_cuda_dnn_bn:
 
-Batch Normalization
-===================
+List of Implemented Operations
+==============================
 
 .. automodule:: theano.sandbox.cuda.dnn
-   :noindex:
-   :members: dnn_batch_normalization_train, dnn_batch_normalization_test
+   :members:

doc/library/tensor/nnet/bn.txt

@@ -10,7 +10,6 @@
 .. moduleauthor:: LISA
 
 
-.. seealso:: :ref:`cuDNN batch normalization <libdoc_cuda_dnn_bn>`
-    must be added manually.
+.. seealso:: cuDNN batch normalization: :class:`theano.gpuarray.dnn.dnn_batch_normalization_train`, :class:`theano.gpuarray.dnn.dnn_batch_normalization_test>`. They must be added manually as they do not have the same user interface.
 
 .. autofunction:: theano.tensor.nnet.bn.batch_normalization

theano/gpuarray/dnn.py

@@ -1142,6 +1142,9 @@ def dnn_conv3d(img, kerns, border_mode='valid', subsample=(1, 1, 1),
 
 def dnn_gradweight(img, topgrad, kerns_shp, border_mode='valid',
                    subsample=(1, 1), conv_mode='conv'):
+    """
+    TODO: document this
+    """
     ctx_name = infer_context_name(img, topgrad)
     img = as_gpuarray_variable(img, ctx_name)
     topgrad = as_gpuarray_variable(topgrad, ctx_name)
@@ -1156,6 +1159,9 @@ def dnn_gradweight(img, topgrad, kerns_shp, border_mode='valid',
 
 def dnn_gradweight3d(img, topgrad, kerns_shp, border_mode='valid',
                      subsample=(1, 1, 1), conv_mode='conv'):
+    """
+    TODO: document this
+    """
     ctx_name = infer_context_name(img, topgrad)
     img = as_gpuarray_variable(img, ctx_name)
     topgrad = as_gpuarray_variable(topgrad, ctx_name)
@@ -1170,6 +1176,9 @@ def dnn_gradweight3d(img, topgrad, kerns_shp, border_mode='valid',
 
 def dnn_gradinput(kerns, topgrad, img_shp, border_mode='valid',
                   subsample=(1, 1), conv_mode='conv'):
+    """
+    TODO: document this
+    """
     ctx_name = infer_context_name(kerns, topgrad)
     kerns = as_gpuarray_variable(kerns, ctx_name)
     topgrad = as_gpuarray_variable(topgrad, ctx_name)
@@ -1184,6 +1193,9 @@ def dnn_gradinput(kerns, topgrad, img_shp, border_mode='valid',
 
 def dnn_gradinput3d(kerns, topgrad, img_shp, border_mode='valid',
                     subsample=(1, 1, 1), conv_mode='conv'):
+    """
+    TODO: document this
+    """
     ctx_name = infer_context_name(kerns, topgrad)
     kerns = as_gpuarray_variable(kerns, ctx_name)
     topgrad = as_gpuarray_variable(topgrad, ctx_name)
@@ -2337,25 +2349,35 @@ class GpuDnnRNNGradWeights(DnnBase):
 
 
 class RNNBlock(object):
+    """
+    An object that allow us to use CuDNN v5 RNN implementation.
+    TODO: make an example how to use. You can check Theano tests
+    test_dnn_rnn_gru() and test_dnn_rnn_lstm() in the file
+    theano/gpuarray/tests/test_dnn.py for now.
+
+
+    Parameters
+    ----------
+    dtype : data type of computation
+    hidden_size : int
+    num_layers : int
+    rnn_mode : {'rnn_relu', 'rnn_tanh', 'lstm', 'gru'}
+        See cudnn documentation for ``cudnnRNNMode_t``.
+
+    input_mode : {'linear', 'skip'}
+        linear: input will be multiplied by a biased matrix
+        skip: No operation is performed on the input.  The size must match the hidden size.
+    direction_mode : {'unidirectional', 'bidirectional'}
+        unidirectional: The network operates recurrently from the
+                        first input to the last.
+
+        bidirectional: The network operates from first to last then from last to first and concatenates the results at each layer.
+
+    """
+
     def __init__(self, dtype, hidden_size, num_layers, rnn_mode,
                  input_mode='linear', direction_mode='unidirectional',
                  context_name=None):
-        """
-        dtype: data type of computation
-        hidden_size: int
-        num_layers: int
-        rnn_mode: {'rnn_relu', 'rnn_tanh', 'lstm', 'gru'}
-          See cudnn documentation for cudnnRNNMode_t.
-        input_mode: {'linear', 'skip'}
-          linear: input will be multiplied by a biased matrix
-          skip: No operation is performed on the input.  The size must match the hidden size.
-        direction_mode: {'unidirectional', 'bidirectional'}
-          unidirectional: The network operates recurrently from the
-                          first input to the last.
-
-          bidirectional: The network operates from first to last then from last to first and concatenates the results at each layer.
-
-        """
         # This is not supported for any value other than 0, so don't change it
         ddesc, states = _make_dropout_desc(0, 4242, context_name)
         self.ddesc = ddesc

theano/sandbox/cuda/dnn.py

@@ -1424,7 +1424,7 @@ class GpuDnnPoolDesc(GpuOp):
 
     Note
     ----
-    Not used anymore. Only needed to reload old pickled files.
+    Do not use anymore. Only needed to reload old pickled files.
 
     """