pytensor 3.1.3__tar.gz → 3.2.0__tar.gz

{pytensor-3.1.3/pytensor.egg-info → pytensor-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytensor
-Version: 3.1.3
+Version: 3.2.0
 Summary: Optimizing compiler for evaluating mathematical expressions on CPUs and GPUs.
 Author-email: pymc-devs <pymc.devs@gmail.com>
 License-Expression: BSD-3-Clause
@@ -32,10 +32,6 @@ Requires-Dist: scipy<2,>=1
 Requires-Dist: numpy>=2.0
 Requires-Dist: numba<=0.65.1,>=0.58
 Requires-Dist: filelock>=3.15
-Requires-Dist: etuples
-Requires-Dist: logical-unification
-Requires-Dist: miniKanren
-Requires-Dist: cons
 Provides-Extra: complete
 Requires-Dist: pytensor[jax]; extra == "complete"
 Requires-Dist: pytensor[numba]; extra == "complete"
@@ -51,6 +47,7 @@ Requires-Dist: coverage>=5.1; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
 Requires-Dist: pytest-mock; extra == "tests"
 Requires-Dist: pytest-sphinx; extra == "tests"
+Requires-Dist: pytensor[kanren]; extra == "tests"
 Provides-Extra: rtd
 Requires-Dist: sphinx<6,>=5.1.0; extra == "rtd"
 Requires-Dist: pygments; extra == "rtd"
@@ -61,6 +58,11 @@ Requires-Dist: jaxlib; extra == "jax"
 Provides-Extra: numba
 Requires-Dist: numba<=0.65.1,>=0.58; extra == "numba"
 Requires-Dist: llvmlite; extra == "numba"
+Provides-Extra: kanren
+Requires-Dist: etuples; extra == "kanren"
+Requires-Dist: logical-unification; extra == "kanren"
+Requires-Dist: miniKanren; extra == "kanren"
+Requires-Dist: cons; extra == "kanren"
 Dynamic: license-file
 
 .. image:: https://cdn.rawgit.com/pymc-devs/pytensor/main/doc/images/PyTensor_RGB.svg

{pytensor-3.1.3 → pytensor-3.2.0}/doc/extending/creating_a_c_op.rst

@@ -713,322 +713,6 @@ C code.
             return c_code % locals()
 
 
-Alternate way of defining C :class:`Op`\s
-=========================================
-
-The two previous examples have covered the standard way of implementing C :class:`Op`\s
-in PyTensor by inheriting from the class :class:`Op`. This process is mostly
-simple but it still involves defining many methods as well as mixing, in the
-same file, both Python and C code which tends to make the result less
-readable.
-
-To help with this, PyTensor defines a class, `ExternalCOp`, from which new C :class:`Op`\s
-can inherit. The class `ExternalCOp` aims to simplify the process of implementing
-C :class:`Op`\s by doing the following :
-
-*      It allows you to define the C implementation of your :class:`Op` in a distinct
-       C code file. This makes it easier to keep your Python and C code
-       readable and well indented.
-
-*      It can automatically handle all the methods that return C code,
-       in addition to :meth:`Op.c_code_cache_version` based on the
-       provided external C implementation.
-
-To illustrate how much simpler the class `ExternalCOp` makes the process of defining
-a new :class:`Op` with a C implementation, let's revisit the second example of this
-tutorial, the `VectorTimesVector`\ :class:`Op`. In that example, we implemented an :class:`Op`
-to perform the task of element-wise vector-vector multiplication. The two
-following blocks of code illustrate what the :class:`Op` would look like if it was
-implemented using the `ExternalCOp` class.
-
-The new :class:`Op` is defined inside a Python file with the following code :
-
-.. testcode::
-
-    import pytensor
-    from pytensor.link.c.op import ExternalCOp
-
-    class VectorTimesVector(ExternalCOp):
-        __props__ = ()
-
-        func_file = "./vectorTimesVector.c"
-        func_name = "APPLY_SPECIFIC(vector_times_vector)"
-
-        def __init__(self):
-            super().__init__(self.func_file, self.func_name)
-
-        def make_node(self, x, y):
-            # Validate the inputs' type
-            if x.type.ndim != 1:
-                raise TypeError('x must be a 1-d vector')
-            if y.type.ndim != 1:
-                raise TypeError('y must be a 1-d vector')
-
-            # Create an output variable of the same type as x
-            output_var = pytensor.tensor.type.TensorType(
-                            dtype=pytensor.scalar.upcast(x.dtype, y.dtype),
-                            shape=(None,))()
-
-            return Apply(self, [x, y], [output_var])
-
-And the following is the C implementation of the :class:`Op`, defined in an external
-C file named ``vectorTimesVector.c``:
-
-.. code-block:: c
-
-    #section support_code
-
-    // Support code function
-    bool vector_same_shape(PyArrayObject* arr1, PyArrayObject* arr2)
-    {
-        return (PyArray_DIMS(arr1)[0] == PyArray_DIMS(arr2)[0]);
-    }
-
-
-    #section support_code_apply
-
-    // Apply-specific support function
-    void APPLY_SPECIFIC(vector_elemwise_mult)(
-        DTYPE_INPUT_0* x_ptr, int x_str,
-        DTYPE_INPUT_1* y_ptr, int y_str,
-        DTYPE_OUTPUT_0* z_ptr, int z_str, int nbElements)
-    {
-        for (int i=0; i < nbElements; i++){
-            z_ptr[i * z_str] = x_ptr[i * x_str] * y_ptr[i * y_str];
-        }
-    }
-
-    // Apply-specific main function
-    int APPLY_SPECIFIC(vector_times_vector)(PyArrayObject* input0,
-                                            PyArrayObject* input1,
-                                            PyArrayObject** output0)
-    {
-        // Validate that the inputs have the same shape
-        if ( !vector_same_shape(input0, input1))
-        {
-            PyErr_Format(PyExc_ValueError, "Shape mismatch : "
-                        "input0.shape[0] and input1.shape[0] should "
-                        "match but x.shape[0] == %i and "
-                        "y.shape[0] == %i",
-                        PyArray_DIMS(input0)[0], PyArray_DIMS(input1)[0]);
-            return 1;
-        }
-
-        // Validate that the output storage exists and has the same
-        // dimension as x.
-        if (NULL == *output0 || !(vector_same_shape(input0, *output0)))
-        {
-            /* Reference received to invalid output variable.
-            Decrease received reference's ref count and allocate new
-            output variable */
-            Py_XDECREF(*output0);
-            *output0 = (PyArrayObject*)PyArray_EMPTY(1,
-                                                    PyArray_DIMS(input0),
-                                                    TYPENUM_OUTPUT_0,
-                                                    0);
-
-            if (!*output0) {
-                PyErr_Format(PyExc_ValueError,
-                            "Could not allocate output storage");
-                return 1;
-            }
-        }
-
-        // Perform the actual vector-vector multiplication
-        APPLY_SPECIFIC(vector_elemwise_mult)(
-                                (DTYPE_INPUT_0*)PyArray_DATA(input0),
-                                PyArray_STRIDES(input0)[0] / ITEMSIZE_INPUT_0,
-                                (DTYPE_INPUT_1*)PyArray_DATA(input1),
-                                PyArray_STRIDES(input1)[0] / ITEMSIZE_INPUT_1,
-                                (DTYPE_OUTPUT_0*)PyArray_DATA(*output0),
-                                PyArray_STRIDES(*output0)[0] / ITEMSIZE_OUTPUT_0,
-                                PyArray_DIMS(input0)[0]);
-
-        return 0;
-    }
-
-As you can see from this example, the Python and C implementations are nicely
-decoupled which makes them much more readable than when they were intertwined
-in the same file and the C code contained string formatting markers.
-
-Now that we have motivated the `ExternalCOp` class, we can have a more precise look at
-what it does for us. For this, we go through the various elements that make up
-this new version of the `VectorTimesVector`\ `Op` :
-
-*       Parent class : instead of inheriting from the class :class:`Op`,
-        VectorTimesVector inherits from the class `ExternalCOp`.
-
-*       Constructor : in our new `COp`, the :meth:`COp.__init__` method has an
-        important use; to inform the constructor of the `ExternalCOp` class
-        of the location, on the filesystem of the C implementation of
-        this `COp`. To do this, it gives a list of file paths containing
-        the C code for this `COp`.  To auto-generate the c_code method
-        with a function call you can specify the function name as the
-        second parameter.  The paths should be given as a relative
-        path from the folder where the descendant of the `ExternalCOp` class
-        is defined.
-
-*       :meth:`ExternalCOp.make_node` : this method is absolutely
-        identical to the one in our old example. Using the `ExternalCOp`
-        class doesn't change anything here.
-
-*       External C code : the external C code implements the various
-        functions associated with the `COp`.  Writing this C code
-        involves a few subtleties which deserve their own respective
-        sections.
-
-Main function
--------------
-
-If you pass a function name to :meth:`ExternalCOp.__init___`, it must respect
-the following constraints:
-
-*       It must return an int. The value of that int indicates whether
-        the `Op` could perform its task or not. A value of 0 indicates
-        success while any non-zero value will interrupt the execution
-        of the PyTensor function.  When returning non-zero the function
-        must set a python exception indicating the details of the
-        problem.
-
-*       It must receive one argument for each input to the `Op` followed
-        by one pointer to an argument for each output of the `Op`.  The
-        types for the argument is dependent on the Types (that is
-        pytensor Types) of your inputs and outputs.
-
-*       You can specify the number of inputs and outputs for your `Op`
-        by setting the ``_cop_num_inputs`` and ``_cop_num_outputs``
-        attributes on your `COp`.  The main function will always be
-        called with that number of arguments, using NULL to fill in
-        for missing values at the end.  This can be used if your `COp`
-        has a variable number of inputs or outputs, but with a fixed
-        maximum.
-
-For example, the main C function of an `COp` that takes two TensorTypes
-(which has ``PyArrayObject *`` as its C type) as inputs and returns
-both their sum and the difference between them would have four
-parameters (two for the `COp`'s inputs and two for its outputs) and it's
-signature would look something like this :
-
-.. code-block:: c
-
-    int sumAndDiffOfScalars(PyArrayObject* in0, PyArrayObject* in1,
-                            PyArrayObject** out0, PyArrayObject** out1)
-
-Macros
-------
-
-For certain section tags, your C code can benefit from a number of
-pre-defined macros.  These section tags have no macros: ``init_code``,
-``support_code``. All other tags will have the support macros
-discussed below.
-
-*      ``APPLY_SPECIFIC(str)`` which will automatically append a name
-       unique to the :ref:`apply` node that applies the `Op` at the end
-       of the provided ``str``. The use of this macro is discussed
-       further below.
-
-For every input which has a :attr:`dtype` attribute (this means
-Tensors), the following macros will be
-defined unless your `Op` class has an :attr:`Op.check_input` attribute
-defined to False. In these descriptions 'i' refers to the position
-(indexed from 0) in the input array.
-
-*       ``DTYPE_INPUT_{i}`` : NumPy dtype of the data in the array.
-        This is the variable type corresponding to the NumPy dtype, not the
-        string representation of the NumPy dtype. For instance, if the `Op`'s
-        first input is a float32 :class:`ndarray`, then the macro ``DTYPE_INPUT_0``
-        corresponds to ``npy_float32`` and can directly be used to declare a
-        new variable of the same dtype as the data in the array :
-
-        .. code-block:: c
-
-            DTYPE_INPUT_0 myVar = someValue;
-
-*       ``TYPENUM_INPUT_{i}`` : Typenum of the data in the array
-
-*       ``ITEMSIZE_INPUT_{i}`` : Size, in bytes, of the elements in
-        the array.
-
-In the same way, the macros ``DTYPE_OUTPUT_{i}``,
-``ITEMSIZE_OUTPUT_{i}`` and ``TYPENUM_OUTPUT_{i}`` are defined for
-every output 'i' of the `Op`.
-
-In addition to these macros, the ``init_code_struct``, ``code``, and
-``code_cleanup`` section tags also have the following macros:
-
-*     ``FAIL`` : Code to insert at error points.  A python exception
-      should be set prior to this code.  An invocation look like this:
-
-      .. code-block:: c
-
-        if (error) {
-          // Set python exception
-          FAIL
-        }
-
-      You can add a semicolon after the macro if it makes your editor
-      happy.
-
-*     ``PARAMS`` : Name of the params variable for this node.  (only
-      for `Op`\s which have params, which is discussed elsewhere)
-
-Finally the tag ``code`` and ``code_cleanup`` have macros to
-pass the inputs and output names.  These are name ``INPUT_{i}`` and
-``OUTPUT_{i}`` where `i` is the 0-based index position in the input
-and output arrays respectively.
-
-Support code
-------------
-
-Certain section are limited in what you can place in them due to
-semantic and syntactic restrictions of the C++ language.  Most of
-these restrictions apply to the tags that end in ``_struct``.
-
-When we defined the ``VectorTimesVector`` `Op` without using the ``ExternalCOp``
-class, we had to make a distinction between two types of support_code
-: the support code that was apply-specific and the support code that
-wasn't. The apply-specific code was defined in the
-``c_support_code_apply`` method and the elements defined in that
-code (global variables and functions) had to include the name of the
-Apply node in their own names to avoid conflicts between the different
-versions of the apply-specific code. The code that wasn't
-apply-specific was simply defined in the ``c_support_code`` method.
-
-To make indentifiers that include the :ref:`apply` node name use the
-``APPLY_SPECIFIC(str)`` macro. In the above example, this macro is
-used when defining the functions ``vector_elemwise_mult`` and
-``vector_times_vector`` as well as when calling function
-``vector_elemwise_mult`` from inside ``vector_times_vector``.
-
-When using the ``ExternalCOp`` class, we still have to make the distinction
-between C code for each of the methods of a C class. These sections of
-code are separated by ``#section <tag>`` markers. The tag determines
-the name of the method this C code applies to with the rule that
-``<tag>`` applies to `c_<tag>`. Unknown tags are an error and will be
-reported. Duplicate tags will be merged together in the order the
-appear in the C files.
-
-The rules for knowing if where a piece of code should be put can be
-sometimes tricky.  The key thing to remember is that things that can
-be shared between instances of the `Op` should be apply-agnostic and go
-into a section which does not end in ``_apply`` or ``_struct``.  The
-distinction of ``_apply`` and ``_struct`` mostly hinghes on how you
-want to manage the lifetime of the object.  Note that to use an
-apply-specific object, you have to be in a apply-specific section, so
-some portions of the code that might seem apply-agnostic may still be
-apply-specific because of the data they use (this does not include
-arguments).
-
-In the above example, the ``function vector_same_shape`` is
-apply-agnostic because it uses none of the macros defined by the class
-``ExternalCOp`` and it doesn't rely on any apply-specific code. The function
-``vector_elemwise_mult`` is apply-specific because it uses the
-macros defined by ``ExternalCOp``. Finally, the function
-``vector_times_vector`` is apply-specific because it uses those same
-macros and also because it calls ``vector_elemwise_mult`` which is
-an apply-specific function.
-
-
 Using GDB to debug :class:`COp`'s C code
 ========================================
 

{pytensor-3.1.3 → pytensor-3.2.0}/doc/extending/graph_rewriting.rst

@@ -324,229 +324,14 @@ or :class:`PatternNodeRewriter`, it is highly recommended to use them.
 
 .. _unification:
 
-Unification and reification
-===========================
-
-The :class:`PatternNodeRewriter` class uses `unification and reification
-<https://en.wikipedia.org/wiki/Unification_(computer_science)>`_ to implement a
-more succinct and reusable form of "pattern matching and replacement".
-In general, *use of the unification and reification tools is preferable when
-a rewrite's matching and replacement are non-trivial*, so we will briefly explain
-them in the following.
-
-PyTensor's unification and reification tools are provided by the
-`logical-unification <https://github.com/pythological/unification>`_ package.
-The basic tools are :func:`unify`, :func:`reify`, and :class:`var`.  The class :class:`var`
-construct *logic variables*, which represent the elements to be unified/matched, :func:`unify`
-performs the "matching", and :func:`reify` performs the "replacements".
-
-See :mod:`unification`'s documentation for an introduction to unification and reification.
-
-In order to use :func:`unify` and :func:`reify` with PyTensor graphs, we need an intermediate
-structure that will allow us to represent PyTensor graphs that contain :class:`var`\s, because
-PyTensor :class:`Op`\s and :class:`Apply` nodes will not accept these foreign objects as inputs.
-
-:class:`PatternNodeRewriter` uses Python ``tuple``\s to effectively represent :class:`Apply` nodes and
-``str``\s to represent logic variables (i.e. :class:`var`\s in the :mod:`unification` library).
-Behind the scenes, these ``tuple``\s are converted to a ``tuple`` subclass called :class:`ExpressionTuple`\s,
-which behave just like normal ``tuple``\s except for some special caching features that allow for easy
-evaluation and caching.  These :class:`ExpressionTuple`\s are provided by the
-`etuples <https://github.com/pythological/etuples>`_ library.
-
-Here is an illustration of all the above components used together:
-
->>> from unification import unify, reify, var
->>> from etuples import etuple
->>> y_lv = var()  # Create a logic variable
->>> y_lv
-~_1
->>> s = unify(add(x, y), etuple(add, x, y_lv))
->>> s
-{~_1: y}
-
-In this example, :func:`unify` matched the PyTensor graph in the first argument with the "pattern"
-given by the :func:`etuple` in the second.  The result is a ``dict`` mapping logic variables to
-the objects to which they were successfully unified.  When a :func:`unify` doesn't succeed, it will
-return ``False``.
-
-:func:`reify` uses ``dict``\s like the kind produced by :func:`unify` to replace
-logic variables within structures:
-
->>> res = reify(etuple(add, y_lv, y_lv), s)
->>> res
-e(<pytensor.scalar.basic.Add at 0x7f54dfa5a350>, y, y)
-
-Since :class:`ExpressionTuple`\s can be evaluated, we can produce a complete PyTensor graph from these
-results as follows:
-
->>> res.evaled_obj
-add.0
->>> pytensor.dprint(res.evaled_obj)
-add [id A] ''
- |y [id B]
- |y [id B]
-
-
-Because :class:`ExpressionTuple`\s effectively model `S-expressions
-<https://en.wikipedia.org/wiki/S-expression>`_, they can be used with the `cons
-<https://github.com/pythological/python-cons>`_ package to unify and reify
-graphs structurally.
-
-Let's say we want to match graphs that use the :class:`add`\ :class:`Op` but could have a
-varying number of arguments:
-
->>> from cons import cons
->>> op_lv = var()
->>> args_lv = var()
->>> s = unify(cons(op_lv, args_lv), add(x, y))
->>> s
-{~_2: <pytensor.scalar.basic.Add at 0x7f54dfa5a350>, ~_3: e(x, y)}
->>> s = unify(cons(op_lv, args_lv), add(x, y, z))
->>> s
-{~_2: <pytensor.scalar.basic.Add at 0x7f54dfa5a350>, ~_3: e(x, y, z)}
-
-From here, we can check ``s[op_lv] == add`` to confirm that we have the correct :class:`Op` and
-proceed with our rewrite.
-
->>> res = reify(cons(mul, args_lv), s)
->>> res
-e(<pytensor.scalar.basic.Mul at 0x7f54dfa5ae10>, x, y, z)
->>> pytensor.dprint(res.evaled_obj)
-mul [id A] ''
- |x [id B]
- |y [id C]
- |z [id D]
-
-
-.. _miniKanren_rewrites:
-
-miniKanren
-==========
-
-Given that unification and reification are fully implemented for PyTensor objects via the :mod:`unificiation` package,
-the `kanren <https://github.com/pythological/kanren>`_ package can be used with PyTensor graphs, as well.
-:mod:`kanren` implements the `miniKanren <http://minikanren.org/>`_ domain-specific language for relational programming.
-
-Refer to the links above for a proper introduction to miniKanren, but suffice it to say that
-miniKanren orchestrates the unification and reification operations described in :ref:`unification`, and
-it does so in the context of relational operators (e.g. equations like :math:`x + x = 2 x`).
-This means that a relation that--say--represents :math:`x + x = 2 x` can be
-utilized in both directions.
-
-Currently, the node rewriter :class:`KanrenRelationSub` provides a means of
-turning :mod:`kanren` relations into :class:`NodeRewriter`\s; however,
-:mod:`kanren` can always be used directly from within a custom :class:`Rewriter`, so
-:class:`KanrenRelationSub` is not necessary.
-
-The following is an example that distributes dot products across additions.
-
-.. code::
-
-    import pytensor
-    import pytensor.tensor as pt
-    from pytensor.graph.rewriting.kanren import KanrenRelationSub
-    from pytensor.graph.rewriting.basic import EquilibriumGraphRewriter
-    from pytensor.graph.rewriting.utils import rewrite_graph
-    from pytensor.tensor.math import _dot
-    from etuples import etuple
-    from kanren import conso, eq, fact, heado, tailo
-    from kanren.assoccomm import assoc_flatten, associative
-    from kanren.core import lall
-    from kanren.graph import mapo
-    from unification import vars as lvars
-
-
-    # Make the graph pretty printing results a little more readable
-    pytensor.pprint.assign(
-        _dot, pytensor.printing.OperatorPrinter("@", -1, "left")
-    )
-
-    # Tell `kanren` that `add` is associative
-    fact(associative, pt.add)
-
-
-    def dot_distributeo(in_lv, out_lv):
-        """A `kanren` goal constructor relation for the relation ``A.dot(a + b ...) == A.dot(a) + A.dot(b) ...``."""
-        A_lv, add_term_lv, add_cdr_lv, dot_cdr_lv, add_flat_lv = lvars(5)
-
-        return lall(
-            # Make sure the input is a `_dot`
-            eq(in_lv, etuple(_dot, A_lv, add_term_lv)),
-            # Make sure the term being `_dot`ed is an `add`
-            heado(pt.add, add_term_lv),
-            # Flatten the associative pairings of `add` operations
-            assoc_flatten(add_term_lv, add_flat_lv),
-            # Get the flattened `add` arguments
-            tailo(add_cdr_lv, add_flat_lv),
-            # Add all the `_dot`ed arguments and set the output
-            conso(pt.add, dot_cdr_lv, out_lv),
-            # Apply the `_dot` to all the flattened `add` arguments
-            mapo(lambda x, y: conso(_dot, etuple(A_lv, x), y), add_cdr_lv, dot_cdr_lv),
-        )
-
-
-    dot_distribute_rewrite = EquilibriumGraphRewriter([KanrenRelationSub(dot_distributeo)], max_use_ratio=10)
-
-
-Below, we apply `dot_distribute_rewrite` to a few example graphs.  First we create simple test graph:
-
->>> x_at = pt.vector("x")
->>> y_at = pt.vector("y")
->>> A_at = pt.matrix("A")
->>> test_at = A_pt.dot(x_at + y_at)
->>> print(pytensor.pprint(test_at))
-(A @ (x + y))
-
-Next we apply the rewrite to the graph:
-
->>> res = rewrite_graph(test_at, include=[], custom_rewrite=dot_distribute_rewrite, clone=False)
->>> print(pytensor.pprint(res))
-((A @ x) + (A @ y))
-
-We see that the dot product has been distributed, as desired.  Now, let's try a
-few more test cases:
-
->>> z_at = pt.vector("z")
->>> w_at = pt.vector("w")
->>> test_at = A_pt.dot((x_at + y_at) + (z_at + w_at))
->>> print(pytensor.pprint(test_at))
-(A @ ((x + y) + (z + w)))
->>> res = rewrite_graph(test_at, include=[], custom_rewrite=dot_distribute_rewrite, clone=False)
->>> print(pytensor.pprint(res))
-(((A @ x) + (A @ y)) + ((A @ z) + (A @ w)))
-
->>> B_at = pt.matrix("B")
->>> w_at = pt.vector("w")
->>> test_at = A_pt.dot(x_at + (y_at + B_pt.dot(z_at + w_at)))
->>> print(pytensor.pprint(test_at))
-(A @ (x + (y + ((B @ z) + (B @ w)))))
->>> res = rewrite_graph(test_at, include=[], custom_rewrite=dot_distribute_rewrite, clone=False)
->>> print(pytensor.pprint(res))
-((A @ x) + ((A @ y) + ((A @ (B @ z)) + (A @ (B @ w)))))
-
-
-This example demonstrates how non-trivial matching and replacement logic can
-be neatly expressed in miniKanren's DSL, but it doesn't quite demonstrate miniKanren's
-relational properties.
-
-To do that, we will create another :class:`Rewriter` that simply reverses the arguments
-to the relation :func:`dot_distributeo` and apply it to the distributed result in ``res``:
-
->>> dot_gather_rewrite = EquilibriumGraphRewriter([KanrenRelationSub(lambda x, y: dot_distributeo(y, x))], max_use_ratio=10)
->>> rev_res = rewrite_graph(res, include=[], custom_rewrite=dot_gather_rewrite, clone=False)
->>> print(pytensor.pprint(rev_res))
-(A @ (x + (y + (B @ (z + w)))))
-
-As we can see, the :mod:`kanren` relation works both ways, just like the underlying
-mathematical relation does.
-
-miniKanren relations can be used to explore rewrites of graphs in sophisticated
-ways.  It also provides a framework that more directly maps to the mathematical
-identities that drive graph rewrites.  For some simple examples of relational graph rewriting
-in :mod:`kanren` see `here <https://github.com/pythological/kanren/blob/master/doc/graphs.md>`_.  For a
-high-level overview of miniKanren's use as a tool for symbolic computation see
-`"miniKanren as a Tool for Symbolic Computation in Python" <https://arxiv.org/abs/2005.11644>`_.
+Unification, reification and miniKanren
+=======================================
 
+For non-trivial pattern matching and replacement, PyTensor optionally exposes
+:func:`unify` / :func:`reify` over :mod:`logical-unification` and miniKanren
+relations via :class:`KanrenRelationSub`. These rely on a set of optional
+packages (:mod:`logical-unification`, :mod:`kanren`, :mod:`etuples`,
+:mod:`cons`) and are documented separately in :ref:`unification_kanren`.
 
 .. _testing_rewrites:
 

{pytensor-3.1.3 → pytensor-3.2.0}/doc/extending/index.rst

@@ -34,6 +34,7 @@ with PyTensor itself.
 
     graphstructures
     graph_rewriting
+    unification_kanren
     op
     creating_an_op
     creating_a_c_op