Start using graph "rewriting" instead of "optimization" in the docs

doc/core_development_guide.rst

@@ -17,7 +17,7 @@ some of them might be outdated though:
   describing how Aesara works internally; it talks about views and inplace
   operations.
 
-* :ref:`optimization` -- Tutorial on how optimization work in Aesara.
+* :ref:`graph_rewriting` -- Tutorial on how graph rewriting works in Aesara.
 
 * :ref:`pipeline` -- Describes the steps of compiling an Aesara Function.
 

doc/extending/optimization.rst → doc/extending/graph_rewriting.rst

 
-.. _optimization:
+.. _graph_rewriting:
 
-==================
-Graph optimization
-==================
+===============
+Graph Rewriting
+===============
 
-In this document we will explain how optimizations work and construct a couple examples.
+In this document we will explain how graph rewriting works and how graph
+optimizations can be constructed using graph rewriting.
 
 .. todo::
+   The old "optimization" nomenclature is still in use throughout these documents
+   and the codebase; however, this is being changed to more accurately distinguish
+   between general graph rewriting for any purpose and the kind that is explicitly
+   intended to "optimize" a graph in some way.
 
-   This tutorial goes way too far under the hood, for someone who just wants
-   to add yet another pattern to the libraries in :py:mod:`aesara.tensor.basic_opt` for example.
-
-   We need another tutorial that covers the decorator syntax, and explains how
-   to register your optimization right away.  That's what you need to get
-   going.
-
-   Later, the rest is more useful for when that decorator syntax type thing
-   doesn't work. (There are optimizations that don't fit that model).
-
-.. note::
-
-   The optimization tag ``cxx_only`` is used for optimizations that insert
-   :class:`Op`\s which have no Python implementation (so they only have C code).
-   Optimizations with this tag are skipped when there is no C++ compiler
-   available.
 
 Global and Local Optimizations
 ==============================
@@ -147,7 +136,7 @@ simplification described above:
    requirements we might want to  know about?
 
 Here's how it works: first, in :meth:`add_requirements`, we add the
-:class:`ReplaceValidate` :ref:`libdoc_graph_fgraphfeature` located in
+:class:`ReplaceValidate` :class:`Feature` located in
 :ref:`libdoc_graph_features`. This feature adds the :meth:`replace_validate`
 method to ``fgraph``, which is an enhanced version of :meth:`replace` that
 does additional checks to ensure that we are not messing up the
@@ -155,9 +144,7 @@ computation graph (note: if :class:`ReplaceValidate` was already added by
 another optimizer, ``extend`` will do nothing). In a nutshell,
 :class:`ReplaceValidate` grants access to :meth:`fgraph.replace_validate`,
 and :meth:`fgraph.replace_validate` allows us to replace a :class:`Variable` with
-another while respecting certain validation constraints. You can
-browse the list of :ref:`libdoc_graph_fgraphfeaturelist` and see if some of
-them might be useful to write optimizations with. For example, as an
+another while respecting certain validation constraints. As an
 exercise, try to rewrite ``Simplify`` using :class:`NodeFinder`. (Hint: you
 want to use the method it publishes instead of the call to toposort!)
 
@@ -391,6 +378,11 @@ as well as informative tags such as 'stable', 'buggy' or
 'cpu_intensive', all this without compromising the structure of the
 optimizations.
 
+For instance, the optimization tag ``cxx_only`` is used for optimizations that
+insert :class:`Op`\s that have no Python implementation (i.e. they only have C
+implementations).  Optimizations with this tag can be skipped when the C backend
+is not being used.
+
 
 Definition of :obj:`optdb`
 --------------------------

doc/extending/graphstructures.rst

@@ -417,10 +417,8 @@ twice or reformulate parts of the graph to a GPU specific version.
 For example, one (simple) optimization that Aesara uses is to replace
 the pattern :math:`\frac{xy}{y}` by *x.*
 
-Further information regarding the optimization
-:ref:`process<optimization>` and the specific :ref:`optimizations<optimizations>` that are applicable
-is respectively available in the library and on the entrance page of the documentation.
 
+See :ref:`graph_rewriting` and :ref:`optimizations` for more information.
 
 **Example**
 

doc/extending/index.rst

@@ -32,6 +32,7 @@ with Aesara itself.
 
 .. toctree::
 
+    graph_rewriting
     extending_aesara
     extending_aesara_c
     pipeline
@@ -44,7 +45,6 @@ with Aesara itself.
     ctype
     cop
     using_params
-    optimization
     tips
     unittest
     scan

doc/extending/scan.rst

@@ -39,7 +39,7 @@ The following sections assumes the reader is familiar with the following :
 Additionally, the :ref:`scan_internals_optimizations` section below assumes
 knowledge of:
 
-3. Aesara's :ref:`graph optimizations <optimization>`
+3. Aesara's :ref:`graph rewriting <graph_rewriting>`
 
 
 Relevant code files

doc/glossary.rst

@@ -112,13 +112,18 @@ Glossary
         See also :term:`Variable`, :term:`Type`, and :term:`Apply`,
         or read more about :ref:`graphstructures`.
 
+    Rewriter
+        A function or class that transforms an Aesara :term:`graph`.
+
     Optimizer
-        An instance of :class:`Optimizer`, which has the capacity to provide
-        an :term:`optimization` (or optimizations).
+        An instance of a :term:`rewriter` that has the capacity to provide
+        an improvement to the performance of a graph.
 
     Optimization
         A :term:`graph` transformation applied by an :term:`optimizer` during
-        the compilation of a :term:`graph` by :term:`aesara.function`.
+        the compilation of a :term:`graph` by :term:`aesara.function`.  These
+        are graph rewrites that are intended to improve the performance of
+        a compiled :term:`Graph`.
 
     Pure
         An :term:`Op` is *pure* if it has no :term:`destructive` side-effects.

doc/optimizations.rst

@@ -13,8 +13,7 @@ The optimizations are listed in roughly chronological order.  The table below
 gives a quick summary of the optimizations included in the default modes.
 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 Aesara.
+If you would like to add an additional optimization, see :ref:`graph_rewriting`.
 
 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.