Doc tradeoff comp run (#5910)

doc/optimizations.txt

@@ -16,47 +16,67 @@ The descriptions are brief and point to further reading.
 If you would like to add an additional optimization, refer to
 :ref:`optimization` in the guide to extending Theano.
 
+When compiling, we can make a tradeoff between compile-time and run-time.
+Faster compile times will result in fewer optimizations being applied, hence generally slower run-times.
+For making this tradeoff when compiling, we provide a set of 4 optimization modes, 'o1' to 'o4', where 'o1' leads to fastest compile-time and 'o4' leads to fastest run-time in general.
+For an even faster run-time, we could disable assertions (which could be time comsuming) for valid user inputs, using the optimization mode 'unsafe', but this is, as the name suggests, unsafe.
+(Also see note at :ref:`unsafe_optimization`.)
+
 ..  note::
 
     This list is partial.
 
-    The print_summary method allows several OpDBs and optimizers to list the executed optimizations.
-    This makes it possible to have an up-to-date list.
-
-    python -c 'import theano; theano.compile.FAST_RUN.optimizer.print_summary()'
-
-    python -c 'import theano; theano.compile.FAST_COMPILE.optimizer.print_summary()'
-
-========================================================= ========= ============ =============
-Optimization                                              FAST_RUN  FAST_COMPILE Stabilization
-========================================================= ========= ============ =============
-:term:`merge`                                             x         x
-:term:`constant folding<constant folding>`                x         x
-:term:`GPU transfer`                                      x         x
-:term:`shape promotion<shape promotion>`                  x
-:term:`fill cut<fill cut>`                                x
-:term:`inc_subtensor srlz.<inc_subtensor serialization>`  x
-:term:`reshape_chain`                                     x
-:term:`const. elimination<constant elimination>`          x
-:term:`add canonical. <add canonicalization>`             x
-:term:`mul canonical. <mul canonicalization>`             x
-:term:`dot22`                                             x
-:term:`sparse_dot`                                        x
-:term:`sum_scalar_mul`                                    x
-:term:`neg_neg`                                           x
-:term:`neg_div_neg`                                       x
-:term:`add specialize <add specialization>`               x
-:term:`mul specialize <mul specialization>`               x
-:term:`pow specialize <pow specialization>`               x
-:term:`inplace_setsubtensor`                              x
-:term:`gemm`                                              x
-:term:`inplace_elemwise`                                  x
-:term:`inplace_random`                                    x
-:term:`elemwise fusion`                                   x
-:term:`local_log_softmax`                                 x                      x
-:term:`local_remove_all_assert`                                                   
-========================================================= ========= ============ =============
+    The print_summary method allows several OpDBs and optimizers to list the
+    executed optimizations.  This makes it possible to have an up-to-date list.
+
+    .. code-block:: bash
+
+        python -c "import theano; theano.compile.optdb.query(theano.compile.predefined_optimizers['<OPT_ID>']).print_summary()"
+
+    where <OPT_ID> can be one of o1 (:ref:`† <o1=>`), o2, o3, o4 (:ref:`* <o4=>`), 
+    Stabilization or unsafe.
+
+
+========================================================= ============== === === ================= ============= ======
+Optimization                                              o4             o3  o2  o1                Stabilization unsafe  
+                                                          :ref:`* <o4=>`         :ref:`† <o1=>` 
+========================================================= ============== === === ================= ============= ======
+:term:`merge`                                             x              x   x    x                              x   
+:term:`constant folding<constant folding>`                x              x   x    x                              x   
+:term:`GPU transfer`                                      x              x   x    x                              x   
+:term:`shape promotion<shape promotion>`                  x              x                                       x
+:term:`fill cut<fill cut>`                                x              x                                       x
+:term:`inc_subtensor srlz.<inc_subtensor serialization>`  x              x                                       x
+:term:`reshape_chain`                                     x              x                                       x
+:term:`const. elimination<constant elimination>`          x              x                                       x
+:term:`add canonical. <add canonicalization>`             x              x                                       x
+:term:`mul canonical. <mul canonicalization>`             x              x                                       x
+:term:`dot22`                                             x              x                                       x
+:term:`sparse_dot`                                        x              x                                       x
+:term:`sum_scalar_mul`                                    x              x                                       x
+:term:`neg_neg`                                           x              x                                       x
+:term:`neg_div_neg`                                       x              x                                       x
+:term:`add specialize <add specialization>`               x              x                                       x
+:term:`mul specialize <mul specialization>`               x              x                                       x
+:term:`pow specialize <pow specialization>`               x              x                                       x
+:term:`inplace_setsubtensor`                              x                                                      
+:term:`gemm`                                              x              x                                       x
+:term:`inplace_elemwise`                                  x                                                          
+:term:`inplace_random`                                    x                                                      
+:term:`elemwise fusion`                                   x              x   x                                   x   
+:term:`local_log_softmax`                                 x              x                         x             x   
+:term:`local_remove_all_assert`                                                                                  x
+========================================================= ============== === === ================= ============= ======
+
+..  note::
+
+    .. _o4=:
+
+    \*) o4 is equivalent to fast_run
+
+    .. _o1=:
 
+    †) o1 is equivalent to fast_compile
 
 .. glossary::
 

doc/tutorial/modes.txt

@@ -197,6 +197,36 @@ DebugMode      no         yes                VERY HIGH  Make many checks on what
 
 For more detail, see :ref:`Mode<libdoc_compile_mode>` in the library.
 
+.. _optimizers:
+
+Optimizers
+==========
+
+Theano allows compilations with a number of predefined optimizers.
+An optimizer consists of a particular set of optimizations, that speed
+up execution of Theano programs.
+
+The optimizers Theano provides are summarized below to indicate the trade-offs
+one might make between compilation time and execution time.
+
+These optimizers can be enabled globally with the Theano flag: ``optimizer=name``
+or per call to theano functions with ``theano.function(...mode=theano.Mode(optimizer="name"))``.
+
+=================  ============  ==============  ==================================================
+optimizer          Compile time  Execution time  Description
+=================  ============  ==============  ==================================================
+None               "++++++"      "+"             Applies none of Theano's opts
+o1 (fast_compile)  "+++++"       "++"            Applies only basic opts
+o2                 "++++"        "+++"           Applies few basic opts and some that compile fast
+o3                 "+++"         "++++"          Applies all opts except ones that compile slower
+o4 (fast_run)      "++"          "+++++"         Applies all opts
+unsafe             "+"           "++++++"        Applies all opts, and removes safety checks
+stabilize          "+++++"       "++"            Only applies stability opts
+=================  ============  ==============  ==================================================
+
+For a detailed list of the specific optimizations applied for each of these
+optimizers, see :ref:`optimizations`. Also, see :ref:`unsafe_optimization`.
+
 
 .. _using_debugmode:
 

theano/compile/mode.py

@@ -65,13 +65,26 @@ OPT_FAST_RUN_STABLE.name = 'OPT_FAST_RUN_STABLE'
 OPT_FAST_COMPILE.name = 'OPT_FAST_COMPILE'
 OPT_STABILIZE.name = 'OPT_STABILIZE'
 
+OPT_O2 = OPT_FAST_COMPILE.including('fusion')
+OPT_O3 = OPT_FAST_RUN.excluding('inplace')
+OPT_UNSAFE = OPT_O3.including('unsafe')
+
+OPT_O2.name = 'OPT_O2'
+OPT_O3.name = 'OPT_O3'
+OPT_UNSAFE.name = 'OPT_UNSAFE'
+
 predefined_optimizers = {
     None: OPT_NONE,
     'None': OPT_NONE,
     'merge': OPT_MERGE,
+    'o4': OPT_FAST_RUN,
+    'o3': OPT_O3,
+    'o2': OPT_O2,
+    'o1': OPT_FAST_COMPILE,
+    'unsafe': OPT_UNSAFE,
+    'fast_compile': OPT_FAST_COMPILE,
     'fast_run': OPT_FAST_RUN,
     'fast_run_stable': OPT_FAST_RUN_STABLE,
-    'fast_compile': OPT_FAST_COMPILE,
     'stabilize': OPT_STABILIZE}
 
 

theano/configdefaults.py

@@ -505,7 +505,7 @@ AddConfigVar('allow_gc',
 AddConfigVar(
     'optimizer',
     "Default optimizer. If not None, will use this optimizer with the Mode",
-    EnumStr('fast_run', 'merge', 'fast_compile', 'None'),
+    EnumStr('o4', 'o3', 'o2', 'o1', 'unsafe', 'fast_run', 'fast_compile', 'merge', 'None'),
     in_c_key=False)
 
 AddConfigVar('optimizer_verbose',