Merge pull request #137 from pascanur/op_documentations

doc/cifarSC2011/extending_theano.txt

@@ -10,8 +10,8 @@ Theano graphs
 
 - Theano works with symbolic graphs
 - Those graphs are bi-partite graphs (graph with 2 types of nodes)
-- Those 2 nodes types are Apply and Variable nodes
-- Apply node have a link to the Op that it execute
+- The 2 types are Apply nodes and Variable nodes
+- Apply nodes have a link to the Op they execute
 
 Inputs and Outputs are lists of Theano variables
 
@@ -50,33 +50,35 @@ Op contract
 
 .. ../extending/op.txt
 
-There is 2 mandatory function. The first is :func:`make_node`. The
-second is the one that do/tell the computation to do at run
-time. Currently you have 4 posibility: implement the :func:`perform`
-and/or :func:`c_code <Op.c_code>` (and other related :ref:`c functions
-<cop>`), or the :func:`make_thunk` function. The ``perform`` allow you
-to easily wrap an existing python function in Theano. The ``c_code``
-and related function allow you to have your op generate c code and
-have Theano compile and link to it. The ``make_thunk`` function will
-be called during compilation and should generate a ``thunk``: a
-function that when called will do the wanted computation. This is
-usefull if you want to generate code and compile it yourself. For
-example, this allow you to use PyCUDA to compile gpu code.
-
-There is 2 mandatory/highly suggested function. They are needed to for a basic
-optimization that merge duplicate computation in a Theano function. So
-if you don't want Theano to do you computation multiple time for no
-good reason, implement them! Those function are :func:`__eq__` and
+There are 2 mandatory methods that one needs to implement.
+The first one is :func:`make_node`. The second one 
+would describe the computations that are required to be done
+at run time. Currently there are 2 different possibilites:
+implement the :func:`perform`
+and/or :func:`c_code <Op.c_code>` (and other related :ref:`c methods
+<cop>`), or the :func:`make_thunk` method. The ``perform`` allows
+to easily wrap an existing python function into Theano. The ``c_code``
+and related methods allow the op to generate c code that will be 
+compiled and linked by Theano. On the other hand, the ``make_thunk``
+method will be called only once during compilation and should generate
+a ``thunk``: a standalone function that when called will do the wanted computations.
+This is usefull if you want to generate code and compile it yourself. For
+example, this allows you to use PyCUDA to compile gpu code.
+
+Also there are 2 methods that are highly recommended to be implemented. They are
+needed in order to merge duplicate computations involving your op. So if you
+do not want Theano to execute your op multiple times with the same inputs,
+do implement them. Those methods are :func:`__eq__` and
 :func:`__hash__`.
 
-The :func:`infer_shape` method allow some very interesting
-optimization like don't performing the computation of your op just to
-take the shape your Op's output.
+The :func:`infer_shape` method allows to infer shape of some variable, somewhere in the
+middle of the computational graph without actually computing the outputs (when possible).
+This could be helpful if one only needs the shape of the output instead of the actual outputs.
 
-The :func:`grad` method is needed you want want differentiation to
-work with your op.
+The :func:`grad` method is required if you want to differentiate some cost whose expression
+includes your op.
 
-The :func:`__str__` is usefull to have a better printing of you op.
+The :func:`__str__` is usefull to generate a better name for your op when printing.
 
 The :func:`R_op` is needed if you want theano.tensor.Rop to work with your op.
 

doc/extending/op.txt

@@ -142,13 +142,14 @@ following methods:
    Optional.
 
    This function is needed for shape optimization. ``shapes`` is a
-   list with one tuple for each input the Apply node linked to this op
-   have.  Each tuple contain 1 element for each dimensions of the
-   corresponding inputs.  The value is the the corresponding
-   dimensions shape of the corresponding inputs.
+   list with one tuple for each input of the Apply node (which corresponds
+   to the inputs of the op).  Each tuple contains 1 element for 
+   each dimension of the corresponding input. The value is the 
+   shape (number of elements) along the corresponding dimension of that
+   specific input.
 
-   This sound complicated, but this is just the corresponding inputs
-   shape in symbolic variable.
+   While this might sound complicated, it is nothing more then the shape
+   of each input as symbolic variables (one per dimension).
 
    The function should return a list with one tuple for each output.
    Each tuple should contain the corresponding output's shape.
@@ -161,9 +162,30 @@ following methods:
 
    Optional.
 
-   This function is needed for theano.tensor.Rop to work with this op.
-
-   TODO: add more detail.
+   This function implements the application of the R-operator on the
+   function represented by your op. Let assume that function is :math:`f`,
+   with input :math:`x`, applying the R-operator means computing the 
+   Jacobian of :math:`f` and right-multiplying it by :math:`v`, the evaluation 
+   point, namely: :math:`\frac{\partial f}{\partial x} v`. 
+
+   ``inputs`` are the symbolic variables corresponding to the value of 
+   the input where you want to evaluate the jacobian, and ``eval_points``
+   are the symbolic variables corresponding to the value you want to
+   right multiply the jacobian with. 
+
+   Same conventions as for the grad method hold. If your op is not
+   differentiable, you can return None. Note that in contrast to 
+   the method :func:`grad`, for :func:`R_op` you need to return the
+   same number of outputs as there are ouputs of the op. You can think
+   of it in the following terms. You have all your inputs concatenated
+   into a single vector :math:`x`. You do the same with the evaluation 
+   points (which are as many as inputs and of the shame shape) and obtain
+   another vector :math:`v`. For each output, you reshape it into a vector, 
+   compute the jacobian of that vector with respect to :math:`x` and 
+   multiply it by :math:`v`. As a last step you reshape each of these
+   vectors you obtained for each outputs (that have the same shape as 
+   the outputs) back to their corresponding shapes and return them as the 
+   output of the :func:`R_op` method.
 
 .. attribute:: default_output
 
@@ -180,15 +202,15 @@ following methods:
   Syntactic shortcut to make_node which returns the output
   Variables of the Op.
 
-  *Default:* this is done for you by Op.
+  *Default:* this is implemented in the parent class and you do not need to change it.
 
 .. function:: __str__()
 
    *Default:* python default: module_path_to_your_class.CLASSNAME
 
-   This allow you to have a better printing of Op. If an Op have parameter
-   it is highly recommented that it make the ``__str__`` function
-   print the name of the op and the Op's parameters values.
+   This allows for better printing of the Op. If the Op parameterizable, it is highly
+   recommended to implement this method, showing the value of the different parameters
+   in the current instance's name.
 
 At a bare minimum, a new Op must define ``make_node`` and ``perform``, which have no defaults.