Add plotting tutorials to the main tutorials branch (#1903)

* add new basic tutorial and jupyter_ sphinx extension

* add "plotting meshes" example

* add files for the others examples

* update index page for plotting tuts

* add "plotting data on the meshe" example

* update "plotting data on the meshe" example

* updates

* updates on the index page of the plotting section

* updates

* add plotting_data_on_specific_placements.rst tut

* updates

* add plotting_a_graph.rst tut

* updates

* add plot meshes container in plotting_meshes.rst tutorial

* add plot meshes container in plotting_meshes.rst tutorial update

* add plotting_data_on_deformed_mesh.rst tutorial

* updates

* erase the adapted examples

* add separate plotting_data_on_geometry_elements.rst and plotting_data_on_specific_path.rst tutorials

* update substitution text

* use only the jupyter sphinx extension

* updates the examples package references

* update the plotting_meshes.rst to the tutorials guidelines

* update the text of the plotting_meshes.rst to the tutorial

* update the plotting_data_on_the_mesh.rst to the tutorials guidelines

* update the text of the plotting_meshes.rst tutorial

* updates the text of the plotting_data_on_the_mesh.rst tutorial

* updates the text of the plotting_data_on_the_mesh.rst tutorial

* add the plotting_deformed_meshes.rst tutorial

* update the plotting_data_on_the_mesh.rst to the tutorials guidelines

* update the plotting_meshes.rst to the tutorials guidelines

* update the plotting_data_on_specific_path.rst to the tutorials guidelines

* update the plotting_data_on_deformed_mesh.rst to the tutorials guidelines

* update the plotting_data_on_geometry_elements.rst to the tutorials guidelines

* update the plotting_a_graph.rst to the tutorials guidelines

* add new links and substitution text to the links_and_refs.rst file

* update the card of the plotting a graph tutorial in the index.rst page

* delete file basic_tutorial.rst

* Revert "erase the adapted examples"

This reverts commit a2b474b.

* Apply suggestions from code review

Co-authored-by: Paul Profizi <[email protected]>

* updates the files names, references and titles

* updates the download buttons

* updates the text of the plot_mesh.rst tutorial

* updates the text of the plot_deformed_mesh.rst tutorial

* updates the text of the plot_data_on_a_mesh.rst tutorial

* updates the text of the plot_data_on_custom_geometry.rst tutorial

* updates the text of the plot_data_on_custom_path.rst tutorial

* Changes to tutorials/plot/index.rst

* Changes to tutorials/plot/index.rst

* Reword transform data tutorials

* Rework plot_a_graph.rst

* Fix create_a_mesh_from_scratch.rst

* Finish plot_a_graph.rst

* Update plot_mesh.rst

* Update plot_mesh.rst switch example file

* Update mesh plot tutorials

* Fix reference to plot_data_on_a_mesh.rst

* Refactor plot tutorials list -> one tutorial for contours, one for deformation

* Refactor plot tutorials list -> one tutorial for contours, one for deformation

* Rework plot_mesh.rst, plot_deformed_mesh.rst, and plot_contour.rst

* Fixes to links in plot_a_graph.rst

* Remove plot_data_on_custom_path.rst from plot tutorials (it is a mapping tutorial)

* Remove plot_data_on_custom_geometry.rst from plot tutorials (it is a mapping tutorial)

---------

Co-authored-by: Paul Profizi <[email protected]>
Co-authored-by: PProfizi <[email protected]>

Author: luisaFelixSalles

doc/source/links_and_refs.rst

@@ -32,6 +32,7 @@
 
 .. Other libraries repos
 .. _pyvista_github : https://github.com/pyvista/pyvista
+.. _matplotlib_github : https://github.com/matplotlib/matplotlib
 
 .. External links
 .. _sphinx: https://www.sphinx-doc.org/en/master/

doc/source/user_guide/index.rst

@@ -62,7 +62,7 @@ Troubleshooting
     tutorials/post_processing_basics/index.rst
     tutorials/import_data/index.rst
     tutorials/mesh/index.rst
-    tutorials/transform_data/index.rst
+    tutorials/operators_and_workflows/index.rst
     tutorials/export_data/index.rst
     tutorials/plot/index.rst
     tutorials/animate/index.rst

doc/source/user_guide/tutorials/index.rst

@@ -50,8 +50,8 @@ of our package background so you can understand how to work with it.
        transform simulation data into output data that can be used to
        visualize and analyze simulation results.
 
-:fa:`book-open-reader` Features usage
-*************************************
+:fa:`book-open-reader` Common topics
+************************************
 
 .. grid:: 1 1 3 3
     :gutter: 2
@@ -72,12 +72,12 @@ of our package background so you can understand how to work with it.
 
        Learn how to explore a mesh in DPF.
 
-    .. grid-item-card:: Transform data with PyDPF-Core
-       :link: ref_tutorials_transform_data
+    .. grid-item-card:: Manipulate data with operators and workflows
+       :link: ref_tutorials_operators_and_workflows
        :link-type: ref
        :text-align: center
 
-       Learn how to transform and operate on data to obtain the desired input.
+       Learn how to use operators to process your data and build workflows.
 
     .. grid-item-card:: Export data from DPF
        :link: ref_tutorials_export_data
@@ -100,6 +100,21 @@ of our package background so you can understand how to work with it.
 
        Explore the different approaches to visualise the data in an animation.
 
+    .. grid-item-card:: Mathematical operations
+       :link: ref_tutorials_mathematics
+       :link-type: ref
+       :text-align: center
+
+       Learn how to do mathematical operations using PyDPF-Core and data structures
+
+    .. grid-item-card:: Manipulating physics data
+       :link: ref_tutorials_manipulate_physics_data
+       :link-type: ref
+       :text-align: center
+
+       Learn how to manipulate the physics data associate to a
+       data storage structure. (Unit, homogeneity ...)
+
     .. grid-item-card:: Enriching DPF capabilities
        :link: ref_tutorials_enriching
        :link-type: ref
@@ -126,19 +141,4 @@ of our package background so you can understand how to work with it.
        :link-type: ref
        :text-align: center
 
-       Understand how to access the Entry and Premium licensing capabilities
-
-    .. grid-item-card:: Mathematical operations
-       :link: ref_tutorials_mathematics
-       :link-type: ref
-       :text-align: center
-
-       Learn how to do mathematical operations using PyDPF-Core API and data structures
-
-    .. grid-item-card:: Manipulating physics data
-       :link: ref_tutorials_manipulate_physics_data
-       :link-type: ref
-       :text-align: center
-
-       Learn how to manipulate the physics data associate to a
-       data storage structure. (Unit, homogeneity ...)
+       Understand how to access the Entry and Premium licensing capabilities

doc/source/user_guide/tutorials/mesh/create_a_mesh_from_scratch.rst

@@ -59,7 +59,7 @@ Here, we create a function that will find this connectivity.
 
     def search_sequence_numpy(arr, node):
         """Find the node location in an array of nodes and return its index."""
-        indexes = np.isclose(arr, seq)
+        indexes = np.isclose(arr, node)
         match = np.all(indexes, axis=1).nonzero()
         return int(match[0][0])
 

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

@@ -0,0 +1,41 @@
+.. _ref_tutorials_operators_and_workflows:
+
+=========================================
+Process data with operators and workflows
+=========================================
+
+An operator is the main object used to create, transform, and stream data in DPF.
+
+They can perform different modifications of the data: direct mathematical operations,
+averaging on the mesh, changes in the model locations.... They can also be chained together
+to create workflows for more complex operations and customizable results.
+
+The tutorials in this section present how to create and use these operators and workflows in PyDPF-Core.
+
+For more information on how to program with PyDPF-Core check the
+:ref:`ref_tutorials_language_and_usage` tutorial.
+
+
+.. grid:: 1 1 3 3
+    :gutter: 2
+    :padding: 2
+    :margin: 2
+
+    .. grid-item-card:: Use operators
+       :link: ref_tutorials
+       :link-type: ref
+       :text-align: center
+
+       This tutorial
+
+    .. grid-item-card:: Create workflows
+       :link: ref_tutorials
+       :link-type: ref
+       :text-align: center
+
+       This tutorial
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+

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

@@ -4,41 +4,46 @@
 Plot
 ====
 
-These tutorials demonstrate some different approaches to visualise the data in plots.
+These tutorials demonstrate different ways one can visualize the data in plots using PyDPF-Core.
 
 .. grid:: 1 1 3 3
     :gutter: 2
     :padding: 2
     :margin: 2
 
-    .. grid-item-card:: Plotting meshes
-       :link: ref_tutorials
+    .. grid-item-card:: Plot a mesh
+       :link: ref_tutorials_plot_mesh
        :link-type: ref
        :text-align: center
 
-       This tutorial
+       This tutorial shows several ways to plot meshes.
 
-    .. grid-item-card:: Plotting data on the mesh
-       :link: ref_tutorials
+    .. grid-item-card:: Add deformation
+       :link: ref_tutorials_plot_deformed_mesh
        :link-type: ref
        :text-align: center
 
-       This tutorial
+       This tutorial shows how to add deformation to plots.
 
-    .. grid-item-card:: Plotting data on specific placements
-       :link: ref_tutorials
+    .. grid-item-card:: Plot contours
+       :link: ref_tutorials_plot_contour
        :link-type: ref
        :text-align: center
 
-       This tutorial
+       This tutorial shows how to plot contours.
 
-    .. grid-item-card:: Plotting a graph
-       :link: ref_tutorials
+    .. grid-item-card:: Plot a graph
+       :link: ref_tutorials_plot_graph
        :link-type: ref
        :text-align: center
 
-       This tutorial
+       This tutorial shows how to plot graphs using matplotlib.
 
 .. toctree::
     :maxdepth: 2
     :hidden:
+
+    plot_mesh.rst
+    plot_deformed_mesh.rst
+    plot_contour.rst
+    plot_a_graph.rst