Creating theano variables doc

doc/library/tensor/basic.txt

@@ -18,7 +18,145 @@ TensorType
 Creation
 ========
 
-A tensor variable can be created 
+Theano provides a list of predefined tensor types that can be used
+to create a tensor variables. The names of the predefined types follow
+a simple recipe : 
+
+``<dtype><dimensionality>``
+
+Where ``<dtype>`` is one of (note that this is not a complete list of
+possible ``<dtypes>``, it just covers thouse used by the predefined
+types):
+
+==== ========= ============== ================
+code type      domain         bits
+==== ========= ============== ================
+b    byte      signed integer 8
+w    word      signed integer 16
+i    integer   signed integer 32
+l    long      signed integer 64
+f    float     floating point 32
+d    double    floating point 64
+c    complex64 complex        64 (two float32) 
+==== ========= ============== ================
+
+``<dimensionality>`` is one of:
+
+======== ============= ================================================================= 
+ code     shape         :ref:`broadcastable <libdoc_tensor_broadcastable>` pattern   
+======== ============= ================================================================= 
+ scalar   []            [True,  True,  True,  True ]
+ vector   [n]           [True,  True,  True,  False] (vectors are used like row vectors)
+ row      [1, n]        [True,  True,  True,  False] 
+ col      [m, 1]        [True,  True,  False, True ]                            
+ matrix   [m, n]        [True,  True,  False, False]
+ tensor3  [m, n, k]     [True,  False, False, False]
+ tensor4  [m, n, k, l]  [False, False, False, False]
+======== ============= ================================================================= 
+
+So, if you want the type of a row of 32-bit floats, it is available
+as :ref:`theano.tensor.frow <libdoc_tensor_type>`.
+If you want a matrix of unsigned 32-bit integers it is available as
+:ref:`theano.tensor.imatrix <libdoc_tensor_type>`.
+
+Each of the types described above can be constructed by two methods:
+a singular version (e.g., :ref:`dmatrix <libdoc_tensor_creation>`)
+and a plural version (:ref:`dmatrices <libdoc_tensor_creation>`).
+When called, the singular version takes a single
+argument which is the name of the *Variable* we want to make and it
+makes a single Variable of that type. The plural version can either take
+an integer or several strings. If an integer is provided, the method
+will return that many Variables and if strings are provided, it will
+create one Variable for each string, using the string as the Variable's
+name. For example:
+
+.. code-block:: python
+
+   from theano.tensor import *
+
+   x = dmatrix() # creates one Variable with no name
+   x = dmatrix('x') # creates one Variable with name 'x'
+   xyz = dmatrix('xyz') # creates one Variable with name 'xyz'
+
+   x, y, z = dmatrices(3) # creates three Variables with no names
+   x, y, z = dmatrices('x', 'y', 'z') # creates three Variables named 'x', 'y' and 'z'
+
+
+Custom tensor types
+-------------------
+
+If you wish to use a type of tensor which is not already available 
+(for example, a 5D tensor) you can build an appropriate type using
+:ref:`theano.tensor.TensorType <libdoc_tensor_type>`.
+The first argument you pass is the `dtype` and the second is the
+`broadcastable pattern`.
+
+Where `dtype` is one of (a complete list of supported dtypes):
+
+=========== ================ =================
+dtype       domain           bits
+=========== ================ =================
+int8        signed integer   8
+int16       signed integer   16
+int32       signed integer   32
+int64       signed integer   64
+uint8       unsigned integer 8
+uint16      unsigned integer 16
+uint32      unsigned integer 32
+uint64      unsigned integer 64
+float32     floating point   32
+float64     floating point   64
+complex64   complex          64 (two float32)
+complex128  complex          128 (two float64)
+=========== ================ =================
+
+.. note::
+
+  Not that some `dtypes` are less used then others (for example
+  **complex128**) and as such not are equally tested and supported.
+
+
+The broadcastable pattern indicates both the number of dimensions and
+whether a particular dimension must have length 1.
+Here is a table mapping the :ref:`broadcastable <libdoc_tensor_broadcastable>` pattern to what kind of tensor it encodes:
+
+===================== =================================
+pattern               interpretation
+===================== =================================
+[]                    scalar
+[True]                1D scalar (vector of length 1)
+[True, True]          2D scalar (1x1 matrix)
+[False]               vector
+[False, False]        matrix
+[False] * n           nD tensor
+[True, False]         row (1xN matrix)
+[False, True]         column (Mx1 matrix)
+[False, True, False]  A Mx1xP tensor (a)
+[True, False, False]  A 1xNxP tensor (b)
+[False, False, False] A MxNxP tensor (pattern of a + b)
+===================== =================================
+
+For dimensions in which broadcasting is False, the length of this
+dimension can be 1 or more.  For dimensions in which broadcasting is True,
+the length of this dimension must be 1.
+
+When two tensors have a different number of dimensions, the broadcastable
+pattern is *expanded to the left*, by padding with ``True``. For example,
+a vector's pattern, ``[False]``, could be expanded to ``[True, False]``, and
+would behave like a row (1xN matrix). In the same way, a matrix (``[False,
+False]``) would behave like a 1xNxP tensor (``[True, False, False]``).
+
+If we wanted to create a type representing a 3D array of unsigned
+bytes, we would do:
+
+.. code-block:: python
+
+   # 3D tensor of signed bytes
+   mytype = theano.tensor.TensorType('uint8', [False]*3)
+
+   # complex types (based on complex64)
+   my_cscalar = theano.tensor.TensorType('complex64', [])
+   my_cmatrix = theano.tensor.TensorType('complex64', [False, False])
 
 
 Autocasting

doc/tutorial/tools.txt

@@ -3,7 +3,7 @@
 Basic Tutorial Mini-Reference
 =============================
 
-.. miniref_mode:
+      .. miniref_mode:
 
 Mode
 ====
@@ -17,12 +17,12 @@ FAST_RUN          ``compile.mode.Mode(linker='c|py', optimizer='fast_run')``
 DEBUG_MODE        ``compile.debugmode.DebugMode()``                               Both implementations where available, all available graph transformations.
 ================= =============================================================== ===============================================================================
 
-.. _tensortypes:
+      .. _tensortypes:
 
 Types
 =====
 
-.. _predefinedtypes:
+      .. _predefinedtypes:
 
 Predefined types
 ----------------