Refactor doc.extending

doc/extending/aesara_vs_c.rst

-
-.. _aesara_vs_c:
-
-============
-Aesara vs. C
-============
-
-We describe some of the patterns in Aesara, and present their closest
-analogue in a statically typed language such as C:
-
-=============== ===========================================================
-Aesara          C
-=============== ===========================================================
-Apply           function application / function call
-Variable        local function data / variable
-Shared Variable global function data / variable
-Op              operations carried out in computation / function definition
-Type            data types
-=============== ===========================================================
-
-For example:
-
-.. code-block:: c
-
-   int d = 0;
-
-   int main(int a) {
-       int b = 3;
-       int c = f(b)
-       d = b + c;
-       return g(a, c);
-   }
-
-
-Based on this code snippet, we can relate ``f`` and ``g`` to Ops, ``a``,
-``b`` and ``c`` to Variables, ``d`` to Shared Variable, ``g(a, c)``,
-``f(b)`` and ``d = b + c`` (taken as meaning
-the action of computing ``f``, ``g`` or ``+`` on their respective inputs) to
-Applies. Lastly, ``int`` could be interpreted as the Aesara Type of the
-Variables ``a``, ``b``, ``c`` and ``d``.

doc/extending/jax_op.rst → doc/extending/creating_a_numba_jax_op.rst

@@ -14,7 +14,7 @@ Find the source for the Aesara :class:`Op` you’d like to be supported in JAX,
 identify the function signature and return values.  These can be determined by
 looking at the :meth:`Op.make_node` implementation.  In general, one needs to be familiar
 with Aesara :class:`Op`\s in order to provide a conversion implementation, so first read
-:ref:`extending_aesara` if you are not familiar.
+:ref:`creating_an_op` if you are not familiar.
 
 For example, the :class:`Eye`\ :class:`Op` current has an :meth:`Op.make_node` as follows:
 

doc/extending/extending_aesara.rst → doc/extending/creating_an_op.rst

 
-.. _extending_aesara:
+.. _creating_an_op:
 
 Creating a new :class:`Op`: Python implementation
 =================================================
@@ -13,17 +13,10 @@ has no bugs, and potentially profits from optimizations that have already been
 implemented.
 
 However, if you cannot implement an :class:`Op` in terms of an existing :class:`Op`, you have to
-write a new one. Don't worry, Aesara was designed to make it easy to add a new
-:class:`Op`, :class:`Type`, and :class:`Optimization`.
+write a new one.
 
-.. These first few pages will walk you through the definition of a new :ref:`type`,
-.. ``double``, and a basic arithmetic :ref:`operations <op>` on that :class:`Type`.
-
-As an illustration, this tutorial shows how to write a simple Python-based
-:ref:`operations <op>` which performs operations on
-:ref:`type`, ``double<Double>``.
-.. It also shows how to implement tests that
-.. ensure the proper working of an :class:`Op`.
+As an illustration, this tutorial will demonstrate how a simple Python-based
+:class:`Op` that performs operations on ``np.float64``\s is written.
 
 .. note::
 
@@ -31,15 +24,15 @@ As an illustration, this tutorial shows how to write a simple Python-based
     an :class:`Op` that returns a view or modifies the values in its inputs. Thus, all
     :class:`Op`\s created with the instructions described here MUST return newly
     allocated memory or reuse the memory provided in the parameter
-    ``output_storage`` of the :func:`perform` function. See
+    ``output_storage`` of the :meth:`Op.perform` method. See
     :ref:`views_and_inplace` for an explanation on how to do this.
 
     If your :class:`Op` returns a view or changes the value of its inputs
     without doing as prescribed in that page, Aesara will run, but will
     return correct results for some graphs and wrong results for others.
 
-    It is recommended that you run your tests in DebugMode (Aesara *flag*
-    ``mode=DebugMode``) since it verifies if your :class:`Op` behaves correctly in this
+    It is recommended that you run your tests in :class:`DebugMode`, since it
+    can help verify whether or not your :class:`Op` behaves correctly in this
     regard.
 
 
@@ -50,7 +43,7 @@ Aesara Graphs refresher
     :width: 500 px
 
 Aesara represents symbolic mathematical computations as graphs. Those graphs
-are bi-partite graphs (graphs with 2 types of nodes), they are composed of
+are bi-partite graphs (graphs with two types of nodes), they are composed of
 interconnected :ref:`apply` and :ref:`variable` nodes.
 :class:`Variable` nodes represent data in the graph, either inputs, outputs or
 intermediary values. As such, inputs and outputs of a graph are lists of Aesara
@@ -168,7 +161,7 @@ or :func:`make_thunk`.
 
   An :class:`Op`\s implementation can be defined in other ways, as well.
   For instance, it is possible to define a C-implementation via :meth:`COp.c_code`.
-  Please refers to tutorial :ref:`extending_aesara_c` for a description of
+  Please refers to tutorial :ref:`creating_a_c_op` for a description of
   :meth:`COp.c_code` and other related ``c_**`` methods. Note that an
   :class:`Op` can provide both Python and C implementations.
 

doc/extending/index.rst

@@ -5,15 +5,15 @@
 Extending Aesara
 ================
 
-This advanced tutorial is for users who want to extend Aesara with new Types,
-new Operations (Ops), and new graph optimizations. This first page of the
-tutorial mainly focuses on the Python implementation of an Op and then
-proposes an overview of the most important methods that define an op.
-The second page of the tutorial (:ref:`extending_aesara_c`) provides then
-information on the C implementation of an Op. The rest of the tutorial
-goes more in depth on advanced topics related to Ops, such as how to write
-efficient code for an Op and how to write an optimization to speed up the
-execution of an Op.
+This advanced tutorial is for users who want to extend Aesara with new :class:`Type`\s,
+new Operations (:Class:`Op`\S), and new graph optimizations. This first page of the
+tutorial mainly focuses on the Python implementation of an :Class:`Op` and then
+proposes an overview of the most important methods that define an :class:`Op`.
+The second page of the tutorial (:ref:`creating_a_c_op`) provides then
+information on the C implementation of an :Class:`Op`. The rest of the tutorial
+goes more in depth on advanced topics related to :Class:`Op`\s, such as how to write
+efficient code for an :Class:`Op` and how to write an optimization to speed up the
+execution of an :Class:`Op`.
 
 Along the way, this tutorial also introduces many aspects of how Aesara works,
 so it is also good for you if you are interested in getting more under the hood
@@ -23,7 +23,7 @@ with Aesara itself.
 
     Before tackling this more advanced presentation, it is highly recommended
     to read the introductory :ref:`Tutorial<tutorial>`, especially the sections
-    that introduce the Aesara Graphs, as providing a novel Aesara op requires a
+    that introduce the Aesara Graphs, as providing a novel Aesara :class:`Op` requires a
     basic understanting of the Aesara Graphs.
 
     See also the :ref:`dev_start_guide` for information regarding the
@@ -32,21 +32,19 @@ with Aesara itself.
 
 .. toctree::
 
+    graphstructures
     graph_rewriting
-    extending_aesara
-    extending_aesara_c
+    op
+    creating_an_op
+    creating_a_c_op
+    creating_a_numba_jax_op
     pipeline
-    aesara_vs_c
-    graphstructures
     type
-    op
+    ctype
     inplace
+    scan
     other_ops
-    ctype
-    cop
     using_params
-    tips
     unittest
-    scan
     extending_faq
-    jax_op
+    tips

doc/extending/pipeline.rst

@@ -5,59 +5,40 @@
 Overview of the compilation pipeline
 ====================================
 
-The purpose of this page is to explain each step of defining and
-compiling an Aesara function.
+Once one has an Aesara graph, they can use :func:`aesara.function` to compile a
+function that will perform the computations modeled by the graph in Python, C,
+Numba, or JAX.
 
+More specifically, :func:`aesara.function` takes a list of input and output
+:ref:`Variables <variable>` that define the precise sub-graphs that
+correspond to the desired computations.
 
-Definition of the computation graph
------------------------------------
-
-By creating Aesara :ref:`Variables <variable>` using
-``aesara.tensor.lscalar`` or ``aesara.tensor.dmatrix`` or by using
-Aesara functions such as ``aesara.tensor.sin`` or
-``aesara.tensor.log``, the user builds a computation graph. The
-structure of that graph and details about its components can be found
-in the :ref:`graphstructures` article.
-
-
-
-Compilation of the computation graph
-------------------------------------
-
-Once the user has built a computation graph, they can use
-:func:`aesara.function` in order to make one or more functions that
-operate on real data. function takes a list of input :ref:`Variables
-<variable>` as well as a list of output :class:`Variable`\s that define a
-precise subgraph corresponding to the function(s) we want to define,
-compile that subgraph and produce a callable.
-
-Here is an overview of the various steps that are done with the
-computation graph in the compilation phase:
+Here is an overview of the various steps that are taken during the
+compilation performed by :func:`aesara.function`.
 
 
 Step 1 - Create a :class:`FunctionGraph`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The subgraph given by the end user is wrapped in a structure called
-:class:`FunctionGraph`. That structure defines several hooks on adding and
-removing (pruning) nodes as well as on modifying links between nodes
-(for example, modifying an input of an :ref:`apply` node) (see the
-article about :ref:`libdoc_graph_fgraph` for more information).
+The subgraph specified by the end-user is wrapped in a structure called
+:class:`FunctionGraph`. This structure defines several callback hooks for when specific
+changes are made to a :class:`FunctionGraph`--like adding and
+removing nodes, as well as modifying links between nodes
+(e.g. modifying an input of an :ref:`apply` node). See :ref:`libdoc_graph_fgraph`.
 
 :class:`FunctionGraph` provides a method to change the input of an :class:`Apply` node from one
-:class:`Variable` to another and a more high-level method to replace a :class:`Variable`
-with another. This is the structure that :ref:`Optimizers
-<optimization>` work on.
+:class:`Variable` to another, and a more high-level method to replace a :class:`Variable`
+with another. These are the primary means of performing :ref:`graph rewrites <graph_rewriting>`.
 
 Some relevant :ref:`Features <libdoc_graph_fgraphfeature>` are typically added to the
-:class:`FunctionGraph`, namely to prevent any optimization from operating inplace on
-inputs declared as immutable.
+:class:`FunctionGraph` at this stage.  Namely, :class:`Feature`\s that prevent
+rewrites from operating in-place on inputs declared as immutable.
 
 
-Step 2 - Execute main :class:`Optimizer`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Step 2 - Perform graph optimizations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Once the :class:`FunctionGraph` is made, an :term:`optimizer` is produced by
+Once the :class:`FunctionGraph` is constructed, an :term:`optimizer` is produced by
 the :term:`mode` passed to :func:`function` (the :class:`Mode` basically has two
 important fields, :attr:`linker` and :attr:`optimizer`). That optimizer is
 applied on the :class:`FunctionGraph` using its :meth:`Optimizer.optimize` method.

doc/extending/scan.rst

@@ -32,7 +32,7 @@ Pre-requisites
 
 The following sections assumes the reader is familiar with the following :
 
-1. Aesara's :ref:`graph structure <extending_aesara>` (`Apply` nodes, `Variable` nodes and `Op`\s)
+1. Aesara's :ref:`graph structure <graphstructures>` (`Apply` nodes, `Variable` nodes and `Op`\s)
 
 2. The interface and usage of Aesara's :ref:`scan <lib_scan>` function
 

doc/extending/tips.rst

@@ -3,10 +3,11 @@ Tips
 ====
 
 
-Reusing outputs
-===============
+..
+   Reusing outputs
+   ===============
 
-.. todo:: Write this.
+   .. todo:: Write this.
 
 
 Don't define new :class:`Op`\s unless you have to
@@ -17,7 +18,7 @@ implemented using other already existing :class:`Op`\s. For example, instead of
 writing a "sum_square_difference" :class:`Op`, you should probably just write a
 simple function:
 
-.. testcode::
+.. code::
 
    from aesara import tensor as aet
 
@@ -41,13 +42,14 @@ used to make transpose-like transformations. These higher order :class:`Op`\s
 are mostly tensor-related, as this is Aesara's specialty.
 
 
-.. _opchecklist:
+..
+   .. _opchecklist:
 
-:class:`Op` Checklist
-=====================
+   :class:`Op` Checklist
+   =====================
 
-Use this list to make sure you haven't forgotten anything when
-defining a new :class:`Op`. It might not be exhaustive but it covers a lot of
-common mistakes.
+   Use this list to make sure you haven't forgotten anything when
+   defining a new :class:`Op`. It might not be exhaustive but it covers a lot of
+   common mistakes.
 
-.. todo:: Write a list.
+   .. todo:: Write a list.

doc/glossary.rst

@@ -105,9 +105,10 @@ Glossary
         The ``.op`` of an :term:`Apply`, together with its symbolic inputs
         fully determines what kind of computation will be carried out for that
         :class:`Apply` at run-time.  Mathematical functions such as addition
-        (``T.add``) and indexing  ``x[i]`` are :class:`Op`\s in Aesara.  Much of the
-        library documentation is devoted to describing the various :class:`Op`\s that
-        are provided with Aesara, but you can add more.
+        (i.e. :func:`aesara.tensor.add`) and indexing ``x[i]`` are :class:`Op`\s
+        in Aesara.  Much of the library documentation is devoted to describing
+        the various :class:`Op`\s that are provided with Aesara, but you can add
+        more.
 
         See also :term:`Variable`, :term:`Type`, and :term:`Apply`,
         or read more about :ref:`graphstructures`.

doc/tutorial/extending_aesara.rst

-:orphan:
-
-This page has been moved. Please refer to: :ref:`extending_aesara`.

doc/tutorial/extending_aesara_c.rst

-:orphan:
-
-This page has been moved. Please refer to: :ref:`extending_aesara_c`.