Restructure the tutorial for creating a custom operator

Author: PProfizi

doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operator_example.py

@@ -1,6 +1,6 @@
 from ansys.dpf import core as dpf
 from ansys.dpf.core.changelog import Changelog
-from ansys.dpf.core.custom_operator import CustomOperatorBase, record_operator  # noqa: F401
+from ansys.dpf.core.custom_operator import CustomOperatorBase
 from ansys.dpf.core.operator_specification import CustomSpecification, SpecificationProperties, \
     PinSpecification
 
@@ -28,12 +28,12 @@ def specification(self) -> CustomSpecification:
         spec.description = "What the Operator does. You can use MarkDown and LaTeX in descriptions."
         # Define the inputs of the operator if any
         spec.inputs = {
-            0: PinSpecification(name="name_of_input_0", type_names=[dpf.Field, dpf.FieldsContainer],
+            0: PinSpecification(name="input_0", type_names=[dpf.Field, dpf.FieldsContainer],
                                 document="Describe input pin 0."),
         }
         # Define the outputs of the operator if any
         spec.outputs = {
-            0: PinSpecification(name="name_of_output_0", type_names=[dpf.Field], document="Describe output pin 0."),
+            0: PinSpecification(name="output_0", type_names=[dpf.Field], document="Describe output pin 0."),
         }
         # Define the properties of the operator if any
         spec.properties = SpecificationProperties(
@@ -73,7 +73,7 @@ def run(self):
         # # If the input is optional, set its default value
         # # If the input is not optional and empty, raise an error
         if field is None:
-            raise ValueError("my_custom_operator: mandatory input name_of_input_0 is empty or of an unsupported type.")
+            raise ValueError("my_custom_operator: mandatory input 'input_0' is empty or of an unsupported type.")
 
         # Perform some operations on the data
         field.name = "new_field_name"
@@ -83,3 +83,8 @@ def run(self):
 
         # And declare the operator run a success
         self.set_succeeded()
+
+
+def load_operators(*args):
+    from ansys.dpf.core.custom_operator import record_operator
+    record_operator(operator_type=CustomOperator, *args)

doc/source/user_guide/tutorials/custom_operators_and_plugins/custom_operators.rst

@@ -4,115 +4,153 @@
 Custom operators
 ================
 
-In Ansys 2023 R1 and later, you can create custom operators in CPython. Creating custom operators
-consists of wrapping Python routines in a DPF-compliant way so that you can access them in the same way
-as you access the native operators in the :class:`Operator <ansys.dpf.core.dpf_operator.Operator>` class in
-PyDPF-Core or in any supported client API.
+This tutorial shows the basics of creating a custom operator in Python and loading it ont a server for use.
 
-With support for custom operators, PyDPF-Core becomes a development tool offering:
+.. note:
+    You can create custom operators in CPython using PyDPF-Core for use with DPF in Ansys 2023 R1 and later.
 
-- **Accessibility:** A simple script can define a basic operator plugin.
+It first presents how to :ref:`create a custom DPF operator<tutorials_custom_operators_and_plugins_custom_operator_create_custom_operator>`
+in Python using PyDPF-Core.
 
-- **Componentization:** Operators with similar applications can be grouped in Python plug-in packages.
+It then shows how to :ref:`make a plugin<tutorials_custom_operators_and_plugins_custom_operator_create_custom_plugin>`
+out of this single operator.
 
-- **Easy distribution:** Standard Python tools can be used to package, upload, and download custom operators.
+The next step is to :ref:`load the plugin on the server<tutorials_custom_operators_and_plugins_custom_operator_load_the_plugin>` to record its operators.
 
-- **Dependency management:** Third-party Python modules can be added to the Python package.
+The final step is to instantiate the custom operator from the client API and :ref:`use it<tutorials_custom_operators_and_plugins_custom_operator_use_the_custom_operator>`.
 
-- **Reusability:** A documented and packaged operator can be reused in an infinite number of workflows.
+.. note:
+    In this tutorial the DPF client API used is PyDPF-Core but, once recorded on the server,
+    you can call the operators of the plugin using any of the DPF client APIs
+    (C++, CPython, IronPython), as you would any other operator.
 
-- **Remotable and parallel computing:** Native DPF capabilities are inherited by custom operators.
 
-The only prerequisite for creating custom operators is to be familiar with native operators.
-For more information, see :ref:`ref_user_guide_operators`.
+:jupyter-download-script:`Download tutorial as Python script<custom_operators>`
+:jupyter-download-notebook:`Download tutorial as Jupyter notebook<custom_operators>`
 
-Install module
---------------
 
-Once an Ansys-unified installation is complete, you must install the ``ansys-dpf-core`` module in the Ansys
-installer's Python interpreter.
+.. _tutorials_custom_operators_and_plugins_custom_operator_create_custom_operator:
 
-#. Download the script for you operating system:
+Create a custom operator
+------------------------
 
-   - For Windows, download this :download:`PowerShell script </user_guide/tutorials/enriching_dpf_capabilities/install_ansys_dpf_core_in_ansys.ps1>`.
-   - For Linux, download this :download:`Shell script </user_guide/tutorials/enriching_dpf_capabilities/install_ansys_dpf_core_in_ansys.sh>`
+To create a custom DPF operator using PyDPF-Core, define a custom operator class inheriting from
+the :class:`CustomOperatorBase <ansys.dpf.core.custom_operator.CustomOperatorBase>` class in a dedicated Python file.
 
-#. Run the downloaded script for installing with optional arguments:
+The following are sections of a file named `custom_operator_example.py`.
 
-   - ``-awp_root``: Path to the Ansys root installation folder. For example, the 2023 R1 installation folder ends
-     with ``Ansys Inc/v231``, and the default environment variable is ``AWP_ROOT231``.
-   - ``-pip_args``: Optional arguments to add to the ``pip`` command. For example, ``--extra-index-url`` or
-     ``--trusted-host``.
+First, create the custom operator class, with necessary imports and a first property to define the operator scripting name:
 
-If you ever want to uninstall the ``ansys-dpf-core`` module from the Ansys installation, you can do so.
+.. literalinclude:: custom_operator_example.py
+    :end-at: return "my_custom_operator"
+
+Next, set the `specification` property of your operator with:
+- a description of what the operator does
+- a dictionary for each input and output pin. This dictionary includes the name, a list of supported types, a description,
+  and whether it is optional and/or ellipsis (meaning that the specification is valid for pins going from pin
+  number *x* to infinity)
+- a list for operator properties, including name to use in the documentation and code generation and the
+  operator category. The optional ``license`` property lets you define a required license to check out
+  when running the operator. Set it equal to ``any_dpf_supported_increments`` to allow any license
+  currently accepted by DPF (see :ref:`here<target_to_ansys_license_increments_list>`)
+
+.. literalinclude:: custom_operator_example.py
+    :start-after: return "my_custom_operator"
+    :end-at: return spec
 
-#. Download the script for your operating system:
+Next, implement the operator behavior in its `run` method:
+
+.. literalinclude:: custom_operator_example.py
+    :start-after: return spec
+    :end-at: self.set_succeeded()
 
-   - For Windows, download this :download:`PowerShell script </user_guide/tutorials/enriching_dpf_capabilities/uninstall_ansys_dpf_core_in_ansys.ps1>`.
-   - For Linux, download this :download:`Shell script </user_guide/tutorials/enriching_dpf_capabilities/uninstall_ansys_dpf_core_in_ansys.sh>`.
-  
-#. Run the downloaded script for uninstalling with the optional argument:
+The `CustomOperator` class is now ready for packaging into any DPF Python plugin.
 
-   - ``-awp_root``: Path to the Ansys root installation folder.  For example, the 2023 R1 installation folder ends
-     with ``Ansys Inc/v231``, and the default environment variable is ``AWP_ROOT231``.
+.. _tutorials_custom_operators_and_plugins_custom_operator_create_custom_plugin:
 
+Package as a plugin
+-------------------
 
-Create operators
-----------------
+You must package your custom operator as a `plugin`,
+which is what you can later load onto a running DPF server,
+or configure your installation to automatically load when starting a DPF server.
 
-Creating a basic operator plugin consists of writing a single Python script. An operator implementation
-derives from the :class:`CustomOperatorBase <ansys.dpf.core.custom_operator.CustomOperatorBase>` class and a call to
-the :func:`record_operator() <ansys.dpf.core.custom_operator.record_operator>` method.
+A DPF plugin contains Python modules with declarations of custom Python operators such as seen above.
+However, it also has to define an entry-point for the DPF server to call,
+which records the operators of the plugin into the server registry of available operators.
 
-This example script shows how you create a basic operator plugin:
+This is done by defining a function (DPF looks for a function named ``load_operators`` by default)
+somewhere in the plugin with signature ``*args`` and a call to the
+:func:`record_operator() <ansys.dpf.core.custom_operator.record_operator>` method for each custom operator.
+
+In this tutorial, the plugin is made of a single operator, in a single Python file.
+You can transform this single Python file into a DPF Python plugin very easily by adding
+``load_operators(*args)`` function with a call to the
+:func:`record_operator() <ansys.dpf.core.custom_operator.record_operator>` method at the end of the file.
 
 .. literalinclude:: custom_operator_example.py
+    :start-at: def load_operators(*args):
 
+PS: You can declare several custom operator classes in the same file, with as many calls to
+:func:`record_operator() <ansys.dpf.core.custom_operator.record_operator>` as necessary.
 
-.. code-block::
+.. _tutorials_custom_operators_and_plugins_custom_operator_load_the_plugin:
 
-        def load_operators(*args):
-            record_operator(CustomOperator, *args)
+Load the plugin
+---------------
 
+First, start a server in gRPC mode, which is the only server type supported for custom Python plugins.
 
-In the various properties for the class, you specify the following:
+.. jupyter-execute::
 
-- Name for the custom operator
-- Description of what the operator does
-- Dictionary for each input and output pin, which includes the name, a list of supported types, a description,
-  and whether it is optional and/or ellipsis (meaning that the specification is valid for pins going from pin
-  number *x* to infinity)
-- List for operator properties, including name to use in the documentation and code generation and the
-  operator category. The optional ``license`` property allows to define a required license to check out
-  when running the operator. Set it equal to ``any_dpf_supported_increments`` to allow any license
-  currently accepted by DPF (see :ref:`here<target_to_ansys_license_increments_list>`)
+    import ansys.dpf.core as dpf
 
-For specific examples on writing operator plugins, see :ref:`python_operators`.
+    # Python plugins are not supported in process.
+    server = dpf.start_local_server(config=dpf.AvailableServerConfigs.GrpcServer)
 
-Load the plug-in
-----------------
 
-Once a custom operator is created, you can use the :func:`load_library() <ansys.dpf.core.core.load_library>` method to load it.
+With the server and custom plugin ready, use the :func:`load_library() <ansys.dpf.core.core.load_library>` method in a PyDPF-Core script to load it.
 
 - The first argument is the path to the directory with the plugin.
-- The second argument is ``py_<plugin>``, where <plugin> is the name identifying the plug-in (same name of the Python file).
-- The third argument is the function name for recording operators.
+- The second argument is ``py_<plugin>``, where <plugin> is the name identifying the plugin (the name of the Python file for a single file).
+- The third argument is the name of the function in the plugin which records operators (``load_operators`` by default).
 
-.. code::
+.. jupyter-execute::
 
     dpf.load_library(
-    r"path/to/plugins",
-    "py_custom_plugin", #if the load_operators function is defined in path/to/plugins/custom_plugin.py
-    "load_operators")
+        filename=r".",  # Look into the current directory
+        name="py_custom_operator_example",  # Look for a Python file named 'custom_operator_example.py'
+        symbol="load_operators",  # Look for the entry-point where operators are recorded
+        server=server,  # Load the plugin on the server previously started
+        generate_operators=False,  # Do not generate the Python module for this operator
+    )
+
+.. _tutorials_custom_operators_and_plugins_custom_operator_use_the_custom_operator:
+
+Use the custom operator
+-----------------------
+
+Once the plugin is loaded, you can instantiate the custom operator based on its name.
+
+.. jupyter-execute::
 
-Use custom operators
---------------------
+    my_custom_op = dpf.Operator(name="my_custom_operator") # as returned by the ``name`` property
+    print(my_custom_op)
 
-Once the plugin is loaded, you can instantiate the custom operator:
+Finally, run it as any other operator.
 
-.. code::
+.. jupyter-execute::
 
-    new_operator = dpf.Operator("custom_operator") # if "custom_operator" is what is returned by the ``name`` property
+    # Create a bogus field to use as input
+    in_field = dpf.Field()
+    # Give it a name
+    in_field.name = "initial name"
+    print(in_field)
+    # Set it as input of the operator
+    my_custom_op.inputs.input_0.connect(in_field)
+    # Run the operator by requesting its output
+    out_field = my_custom_op.outputs.output_0()
+    print(out_field)
 
 References
 ----------

doc/source/user_guide/tutorials/custom_operators_and_plugins/index.rst

@@ -28,6 +28,8 @@ For more information, see :ref:`ref_user_guide_operators`.
 
 The following tutorials demonstrate how to develop such plugins using PyDPF-Core (CPython based) and how to use them.
 
+For comprehensive examples on writing operator plugins, see :ref:`python_operators`.
+
 .. grid:: 1 1 3 3
     :gutter: 2
     :padding: 2