docs

doc/library/compile/profilemode.txt

 
 .. _profilemode:
 
-=========================================
-ProfileMode
-=========================================
+================================================
+:mod:`profilemode` -- profiling theano functions
+================================================
+
+Guide
+=====
 
 To profile a Theano graph, a special mode called ProfileMode, must be passed as
 an argument when compiling your graph. Using ProfileMode is a three-step
@@ -118,6 +121,34 @@ generates the following output:
     """
 
 
+
+.. note::
+
+    ***TODO***
+
+    The following text was recovered from a recent version of the source
+    file... hopefully things haven't gotten too out-of-sync!
+
+    The first show an Apply-wise summary, the second show an Op-wise summary, the third show an type-Op-wise summary.
+
+    The Apply-wise summary print the timing information for the worst
+    offending Apply nodes. This corresponds to individual Op applications
+    within your graph which take the longest to execute (so if you use dot
+    twice, you will see two entries there). 
+
+    The Op-wise summary print the execution time of all Apply nodes
+    executing the same Op are grouped together and the total execution
+    time per Op is shown (so if you use dot twice, you will see only one
+    entry there corresponding to the sum of the time spent in each of
+    them). If two Op have different hash value, they will be separate.
+
+    The type-Op-wise summary group the result by type of op. So event if
+    two Op have different hash value, they will be merged.
+
+    Their is an hack with the Op-wise summary. Go see it if you want to know more.
+
+
+
 The summary has two components to it. In the first section called the
 Apply-wise summary, timing information is provided for the worst
 offending Apply nodes. This corresponds to individual Op applications
@@ -131,7 +162,43 @@ there corresponding to the sum of the time spent in each of them).
 Note that the ProfileMode also shows which Ops were running a c
 implementation.
 
-Developers wishing to optimize the performance of their graph, should
-focus on the worst offending Ops. If no C implementation exists for
-this op, consider writing a C implementation yourself or use the
-mailing list, to suggest that a C implementation be provided.
+Developers wishing to optimize the performance of their graph should
+focus on the worst offending Ops and Apply nodes -- either by optimizing an
+implementation, providing a missing C implementation, or by writing a graph
+optimization that eliminates the offending Op altogether.
+You should strongly consider emailing one of our lists about your issue before
+spending too much time on this.
+
+
+Reference
+=========
+
+.. class:: ProfileMode(Mode)
+
+    .. method:: print_summary(n_apply_to_print=None, n_ops_to_print=None)
+
+        Print three summaries to stdout that show where cpu time is spent during theano function executions (for all functions using this object instance).
+
+        :param n_apply_to_print: the number of apply nodes to print. 
+           The default 15, but can be configured via ``ProfileMode.n_ops_to_print`` in :ref:`THEANO_FLAGS`.
+
+        :param n_ops_to_print: the number of ops to print.
+           Default 20, or but can be configured via ``ProfileMode.n_apply_to_print`` in :ref:`THEANO_FLAGS`.
+
+        :returns: None
+
+    .. method:: print_diff_summary(self, other, n_apply_to_print=None, n_ops_to_print=None):
+        """ As print_summary, but print the difference on two different profile mode.
+        TODO: Also we don't print the Apply-wise summary as it don't work for now.
+        TODO: make comparaison with gpu code.
+        
+        :param other: the other instance of ProfileMode that we want to be compared to.
+        
+        :param n_apply_to_print: the number of apply nodes to print. 
+           The default 15, but can be configured via ``ProfileMode.n_ops_to_print`` in :ref:`THEANO_FLAGS`.
+
+        :param n_ops_to_print: the number of ops to print.
+           Default 20, or but can be configured via ``ProfileMode.n_apply_to_print`` in :ref:`THEANO_FLAGS`.
+
+        :returns: None
+

doc/library/index.txt

@@ -8,7 +8,7 @@ Library Documentation
 This documentation covers Theano module-wise.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    tensor/index
    gradient
@@ -20,3 +20,9 @@ This documentation covers Theano module-wise.
    scalar/index
    gof/index
 
+There are also some top-level imports that you might find more convenient:
+
+* **theano.function**  - :func:`compile.function.function`
+* **theano.Param** - :class:`compile.function.Param`
+* **theano.dot** - works like :func:`tensor.dot` for both sparse and dense matrix products
+

doc/sandbox/features.txt

-
-.. _envfeaturelist:
-
-====================
-List of Env Features
-====================
-
-See :api:`gof.env.Env`.
-
-WRITEME
-
-.. _nodefinder:
-
-NodeFinder
-==========
-
-See :api:`gof.toolbox.NodeFinder`.
-
-WRITEME

doc/sandbox/numpy.txt

-
-.. _numpy::
-
-===============
-NumPy refresher
-===============
-
-Give summary of type(x) vs x.type vs x.dtype

doc/sandbox/thinking_in_theano.txt

-
-.. thinking_in_theano:
-
-==================
-Thinking in Theano
-==================
-
-Theano offers quite a bit of flexibility.
-How should you write your algorithm to make the most of what Theano can do?
-
-A few tips
-----------
-
-- Remember that your code builds a graph that theano compiles, and you cannot
-  literally put loops into that graph.
-
-- Remember that Variables are symbolic of computations, not
-  storage.  It does not make sense to *reassign* to a Variable.
-
-
-Limitations
------------
-
-- Conditional control flow is possible but not efficient.  In essence, both
-  sides of an if (see ``switch``) will be evaluated.
-
-- Loops are not supported, but soon will be.
-  (A ``scan`` op is in the works, but not included yet.)
-
-- Recursion is not supported within a graph.
-
-
-A few examples
---------------
-
-**DO WE WANT SOMETHING HERE?**
-
-These are intended to illustrate good ways of formulating an algorithm for
-Theano.
-For complete, usable implementations of these algorithms see WRITEME.
-
-- Short-time Fourier Transform
-
-- Contrastive Divergence for Restricted Boltzmann Machine
-
-- Kalman Filter
-
-- Logistic Regression
-
-- Training a neural network with sigmoidal hidden layer by backpropagation
-
-- Learning an Echo-State Network
-

doc/tutorial/index.txt

@@ -24,6 +24,7 @@ installation (see :ref:`install`).
     adding
     examples
     loading_and_saving
+    remarks
     debug_faq
     tools
 

doc/tutorial/remarks.txt

+
+.. _tutorial_general_remarks:
+
+=====================
+Some general Remarks
+=====================
+
+Theano offers quite a bit of flexibility, but has some limitations too.
+How should you write your algorithm to make the most of what Theano can do?
+
+Limitations
+-----------
+
+- Conditional control flow is possible but currently not efficient.  The current implementation will evaluate both sides of an ``if`` construct (see :func:`tensor.switch`).
+
+- While- or for-Loops within an expression graph are not supported, but soon will be.
+  A ``scan`` op is in ``theano.sandbox``, but not quite ready for mainstream yet.
+
+- Neither ``goto`` nor recursion is supported or planned within expression graphs.
+
+
+A few tips
+----------
+
+* Remember that your code builds a graph that theano compiles, and you cannot
+  literally put loops into that graph.
+
+* Remember that Variables are symbolic of computations, not
+  storage.  It does not make sense to *reassign* to a Variable.
+
+