Improve creating an op documentation page #1086

ricardoV94 · 2024-11-13T13:09:00Z

See commit message for list of changes.

The changes are based on feedback from helping other devs and users

Tagging @OriolAbril because I'm 100% sure I messed up some sphinx stuff (sorry)

📚 Documentation preview 📚: https://pytensor--1086.org.readthedocs.build/en/1086/

ricardoV94 · 2024-11-13T13:10:04Z

doc/extending/creating_an_op.rst

@@ -165,35 +151,6 @@ or :meth:`Op.make_thunk`.
  :meth:`COp.c_code` and other related ``c_**`` methods. Note that an
  :class:`Op` can provide both Python and C implementations.

-  :meth:`Op.make_thunk` method is another alternative to :meth:`Op.perform`.


This is outdated, and tbh I don't think it's necessary for 99.9999% of the people reading this page

Changes: 1. Remove references to c-code which apply to `COp` but not `Op` 2. Fix failing doctests 3. Improve explanation of `make_node` 4. Emphasize distinction between itypes/otypes and make-node 5. Show `L_op` instead of `grad` 6. Show how to test `L_op` and `infer_shape` implementation 7. Simplify explanation of `__props__` and illustrate in example. 8. Introduce more complex multi-output Op to drive these details home 9. Remove old references to numba/ random variable Ops

OriolAbril · 2024-11-19T14:28:48Z

doc/extending/creating_an_op.rst

@@ -1,40 +1,18 @@

 .. _creating_an_op:

-Creating a new :class:`Op`: Python implementation
+Creating a new :ref:`op`: Python implementation


Where do you want the :ref:`op`/:class:`Op` to point to? To https://pytensor--1086.org.readthedocs.build/en/1086/extending/op.html or to https://pytensor--1086.org.readthedocs.build/en/1086/extending/graphstructures.html#op?

I think many of the broken cross-references come from this page: https://pytensor--1086.org.readthedocs.build/en/1086/extending/op.html, which is wildly inconsistent with itself. If the cross-reference would ideally point there we should fix this page first.

Will check. I just wanted it to point somewhere, it wasn't before

@OriolAbril extending op seems much more useful than the graphstructures#op, so I guess there.

fonnesbeck · 2024-12-18T14:08:25Z

doc/extending/creating_an_op.rst

 =================================================

-So suppose you have looked through the library documentation and you don't see
-a function that does what you want.
+You may have looked through the library documentation and you don't see a function that does what you want.


NIT: "... documentation but don't see ..."

fonnesbeck · 2024-12-18T14:11:37Z

doc/extending/creating_an_op.rst

-has no bugs, and potentially profits from rewrites that have already been
-implemented.
+Odds are your function that uses existing PyTensor expressions is short, has no bugs, can be differentiated,
+and may even work in non-default backends and benefit from optimization rewrites.


Suggestion: "A PyTensor function that builds upon existing expressions tends to be concise, reliable, and automatically differentiable, while often working seamlessly across different backends, thereby benefiting from optimization."

fonnesbeck · 2024-12-18T14:13:07Z

doc/extending/creating_an_op.rst

+:ref:`variable` nodes. :ref:`apply` nodes perform computation on these
+variables to produce new variables. Each :ref:`apply` node has a link to an
+instance of :ref:`op` which describes the computation to perform. This tutorial
+details how to write such an :ref:`op` instance. Please refers to


"Please refer to"

fonnesbeck · 2024-12-18T14:14:30Z

doc/extending/creating_an_op.rst

 ---------------------------

-An :class:`Op` is any Python object which inherits from :class:`Op`.
+An :ref:`op` is any Python object which inherits from :ref:`op`.


"that inherits"

fonnesbeck · 2024-12-19T00:47:46Z

doc/extending/creating_an_op.rst

+:meth:`make_node` method creates an :ref:`apply` node representing the application
+of the :ref:`op` on the inputs provided. This method is responsible for three things:
+
+- Checks that the inputs can be converted or are symbolic :ref:`variable`\s whose types are compatible with the current :ref:`op`.


converted to what?

fonnesbeck · 2024-12-19T00:49:15Z

doc/extending/creating_an_op.rst

+- Checks that the inputs can be converted or are symbolic :ref:`variable`\s whose types are compatible with the current :ref:`op`.
+  If the :ref:`op` cannot be applied on the provided input types, it must raises an exception (such as :class:`TypeError`).
+- Creates new output :ref:`variable`\s of a suitable symbolic :class:`Type` to serve as the outputs of this :ref:`op`'s application.
+- Returns an :ref:`apply` instance with the input and output :ref:`variable`\s, and itself an the :ref:`op`.


Something is up with the end of this sentence.

fonnesbeck · 2024-12-19T00:57:17Z

doc/extending/creating_an_op.rst

+  hold a value of ``None``.  It can also pre-allocate some memory
+  for the :ref:`op` to use.  This feature can allow ``perform`` to reuse
+  memory between calls, for example. If there is something
+  preallocated in the ``output_storage``, it will be of the good


"of the correct dtype"

fonnesbeck · 2024-12-19T14:11:38Z

doc/extending/creating_an_op.rst


+This function implements the application of the R-operator on the
+function represented by your :ref:`op`. Let assume that function is :math:`f`,


"Let's assume ..."

Suggested change

function represented by your :ref:`op`. Let assume that function is :math:`f`,

If we assume that function is :math:`f`,

with input :math:`x`, then applying the R-operator means computing the

Jacobian of :math:`f` and right-multiplying it by :math:`v` (the evaluation

point): :math:`\frac{\partial f}{\partial x} v`.

fonnesbeck · 2024-12-19T14:15:02Z

doc/extending/creating_an_op.rst

+
+At a high level, the code fragment declares a class (e.g., ``DoubleOp1``) and then creates one instance of that class (e.g., ``doubleOp1``).
+
+As you'll se below, you can then pass an instantiated :ref:`variable`, such as ``x = tensor.matrix("x")`` to the instantiated :ref:`op`,


fonnesbeck · 2024-12-19T15:23:31Z

doc/extending/creating_an_op.rst

-manually. It also generates a default :func:`__str__` method that prints the
-attribute names and their values.
+The use of :attr:`__props__` saves the user the trouble of implementing :meth:`__eq__` and :meth:`__hash__` manually.
+It also generates a default :meth:`__repr__` and :meth:`__str__` methods that prints the attribute names and their values.


"generates default ... methods that print the ..."

fonnesbeck · 2024-12-19T15:43:55Z

doc/extending/creating_an_op.rst

+Finally, the gradient expression:
+
+Again, we can use pytensor `verify_grad` function to test the gradient implementation.
+Due to the presence of multiple outputs we need to pass a Callable instead of the Op instance.


Callable instead of the Op (add backticks). There are a couple more below too.

ricardoV94 added the docs label Nov 13, 2024

ricardoV94 requested review from OriolAbril and jessegrabowski November 13, 2024 13:09

ricardoV94 changed the title ~~Improve creating_an_op.rst~~ Improve creating an op documentation page Nov 13, 2024

ricardoV94 commented Nov 13, 2024

View reviewed changes

ricardoV94 force-pushed the creating_an_op branch from 2f1a456 to 3a77d6b Compare November 13, 2024 13:41

ricardoV94 mentioned this pull request Nov 13, 2024

Run doctest in docs #1087

Open

ricardoV94 force-pushed the creating_an_op branch 3 times, most recently from 7e407f9 to d37103d Compare November 15, 2024 12:13

ricardoV94 force-pushed the creating_an_op branch from d37103d to 1d9bc2b Compare November 19, 2024 11:03

OriolAbril reviewed Nov 19, 2024

View reviewed changes

fonnesbeck reviewed Dec 18, 2024

View reviewed changes

This comment was marked as duplicate.

Sign in to view

fonnesbeck reviewed Dec 19, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve creating an op documentation page #1086

Improve creating an op documentation page #1086

ricardoV94 commented Nov 13, 2024 •

edited

Loading

ricardoV94 Nov 13, 2024

OriolAbril Nov 19, 2024 •

edited

Loading

ricardoV94 Nov 19, 2024 •

edited

Loading

ricardoV94 Dec 3, 2024

fonnesbeck Dec 18, 2024

fonnesbeck Dec 18, 2024

fonnesbeck Dec 18, 2024

fonnesbeck Dec 18, 2024

This comment was marked as duplicate.

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024

fonnesbeck Dec 19, 2024 •

edited

Loading

fonnesbeck Dec 19, 2024 •

edited

Loading


		This function implements the application of the R-operator on the
		function represented by your :ref:`op`. Let assume that function is :math:`f`,

-function represented by your :ref:`op`. Let assume that function is :math:`f`,
+If we assume that function is :math:`f`,
+with input :math:`x`, then applying the R-operator means computing the
+Jacobian of :math:`f` and right-multiplying it by :math:`v` (the evaluation
+point): :math:`\frac{\partial f}{\partial x} v`.


		At a high level, the code fragment declares a class (e.g., ``DoubleOp1``) and then creates one instance of that class (e.g., ``doubleOp1``).

		As you'll se below, you can then pass an instantiated :ref:`variable`, such as ``x = tensor.matrix("x")`` to the instantiated :ref:`op`,

Improve creating an op documentation page #1086

Are you sure you want to change the base?

Improve creating an op documentation page #1086

Conversation

ricardoV94 commented Nov 13, 2024 • edited Loading

Choose a reason for hiding this comment

OriolAbril Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

ricardoV94 Nov 19, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as duplicate.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fonnesbeck Dec 19, 2024 • edited Loading

Choose a reason for hiding this comment

fonnesbeck Dec 19, 2024 • edited Loading

Choose a reason for hiding this comment

ricardoV94 commented Nov 13, 2024 •

edited

Loading

OriolAbril Nov 19, 2024 •

edited

Loading

ricardoV94 Nov 19, 2024 •

edited

Loading

fonnesbeck Dec 19, 2024 •

edited

Loading

fonnesbeck Dec 19, 2024 •

edited

Loading