Homogenizing geometry API

doc/Makefile

@@ -46,3 +46,7 @@ linkcheck:
 	@echo
 	@echo "Check finished. Report is in $(LINKCHECKDIR)."
 
+html-noexamples:
+	@$(SPHINXBUILD) -D plot_gallery=0 -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)."

doc/source/api/geometry.rst

@@ -9,3 +9,4 @@ Geometry
    :toctree: _autosummary
 
    mapdl_geometry.Geometry
+   mapdl_geometry.LegacyGeometry

doc/source/user_guide/mesh_geometry.rst

@@ -1,11 +1,40 @@
+.. role:: py(code)
+   :language: python
+
+
+.. |np-array| replace:: :class:`Numpy.array <numpy.array>`
+
+.. |pv-polydata| replace:: :class:`pyvista.PolyData <pyvista.PolyData>`
+.. |pv-multiblock| replace:: :class:`pyvista.MultiBlock <pyvista.MultiBlock>`
+
+.. |get_keypoints| replace:: :meth:`Geometry.get_keypoints() <ansys.mapdl.core.mapdl_geometry.Geometry.get_keypoints>`
+.. |get_keypoints-return_as_array| replace:: :meth:`Geometry.get_keypoints(return_as_array=True) <ansys.mapdl.core.mapdl_geometry.Geometry.get_keypoints>`
+.. |get_lines| replace:: :meth:`Geometry.get_lines() <ansys.mapdl.core.mapdl_geometry.Geometry.get_lines>`
+.. |get_areas| replace:: :meth:`Geometry.get_areas() <ansys.mapdl.core.mapdl_geometry.Geometry.get_areas>`
+.. |get_volumes| replace:: :meth:`Geometry.get_volumes() <ansys.mapdl.core.mapdl_geometry.Geometry.get_volumes>`
+
+.. |list-pv-polydata| replace:: :class:`List[pyvista.PolyData] <pyvista.PolyData>`
+.. |list-pv-unstruc| replace:: :class:`List[pyvista.UnstructuredGrid] <pyvista.UnstructuredGrid>`
+
+.. |geo-key| replace:: :attr:`Geometry.keypoints <ansys.mapdl.core.mapdl_geometry.Geometry.keypoints>`
+.. |geo-lines| replace:: :attr:`Geometry.lines <ansys.mapdl.core.mapdl_geometry.Geometry.lines>`
+.. |geo-areas| replace:: :attr:`Geometry.areas <ansys.mapdl.core.mapdl_geometry.Geometry.areas>`
+.. |geo-volumes| replace:: :attr:`Geometry.volumes <ansys.mapdl.core.mapdl_geometry.Geometry.volumes>`
+
+.. |leggeo-keypoints| replace:: :meth:`LegacyGeometry.keypoints() <ansys.mapdl.core.mapdl_geometry.LegacyGeometry.keypoints>`
+.. |leggeo-lines| replace:: :meth:`LegacyGeometry.lines() <ansys.mapdl.core.mapdl_geometry.LegacyGeometry.lines>`
+.. |leggeo-areas| replace:: :meth:`LegacyGeometry.areas() <ansys.mapdl.core.mapdl_geometry.LegacyGeometry.areas>`
+
+
 Mesh and geometry
 =================
-The :class:`Mapdl <ansys.mapdl.core.Mapdl>` class allows you to access
+The :class:`Mapdl <ansys.mapdl.core.mapdl._MapdlCore>` class allows you to access
 the mesh and geometry without writing to an intermediate file or
 interpreting the text output from various MAPDL commands. For
 example, to access the nodes and elements of a model, normally you
-would list the nodes within MAPDL using the :func:`Mapdl.nlist()
-<ansys.mapdl.core.Mapdl.nlist` method. However, this generates a string.
+would list the nodes within MAPDL using the 
+:func:`Mapdl.nlist() <ansys.mapdl.core.Mapdl.nlist>` method. 
+However, this generates a string.
 Array access requires either cumbersome MAPDL GET commands or that the
 nodes be written to an archive file and then read in with other
 software:
@@ -22,9 +51,9 @@ software:
         3   0.2500        0.0000        0.0000          0.00     0.00     0.00
 
 
-However, with the :class:`Mapdl.mesh <ansys.mapdl.core.mesh_grpc.Mesh>` class,
+However, with the :attr:`Mapdl.mesh <ansys.mapdl.core.mesh_grpc.MeshGrpc>` class,
 you can interface with a current instance of the 
-:class:`Mapdl <ansys.mapdl.core.Mapdl>` class and access the current nodes coordinates
+:class:`Mapdl <ansys.mapdl.core.mapdl._MapdlCore>` class and access the current nodes coordinates
 with this code:
 
 .. code:: pycon
@@ -38,8 +67,8 @@ with this code:
      [0.75, 0.5, 4.5]]
 
 
-Both the :attr:`Mapdl.geometry <ansys.mapdl.core.Mapdl.geometry>` and
-:attr:`Mapdl.mesh <ansys.mapdl.core.Mapdl.mesh>` attributes support
+Both the :attr:`Mapdl.geometry <ansys.mapdl.core.mapdl_geometry.Geometry>` and
+:attr:`Mapdl.mesh <ansys.mapdl.core.mesh_grpc.MeshGrpc>` attributes support
 additional, lower-level access to MAPDL data. You can use this code
 to access them:
 
@@ -61,9 +90,202 @@ To view the current mesh status, you can use this code:
       Number of Element Components: 0
 
 
-Geometry commands
-~~~~~~~~~~~~~~~~~
-For additional MAPDLcommands for creating geometries, see the
+Geometry
+--------
+
+Starting from PyMAPDL v0.66.0, by default, all the geometry entities are returned
+as a |pv-multiblock|  object. For instance:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas
+   MultiBlock (0x147ca7640)
+     N Blocks    28
+     X Bounds    -0.016, 0.016
+     Y Bounds    -0.008, 0.018
+     Z Bounds    -0.003, 0.015
+
+Or for example:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.keypoints
+   MultiBlock (0x147a78220)
+     N Blocks    26
+     X Bounds    -0.016, 0.016
+     Y Bounds    -0.008, 0.018
+     Z Bounds    -0.003, 0.015
+
+As you can see, in the new API it is not needed to call the entities.
+
+For more differences between the new Geometry API and the old one, see
+:ref:`migration_geometry_api_066`. 
+
+
+The selection now is easier, allowing you to use indexing:
+
+.. code:: pycon
+
+   >>> volume0 = mapdl.geometry.volumes[0]
+   >>> volume0
+   UnstructuredGrid (0x149107340)
+     N Cells:    34
+     N Points:   36
+     X Bounds:   0.000e+00, 1.588e-02
+     Y Bounds:   -7.620e-03, 1.778e-02
+     Z Bounds:   -3.180e-03, 0.000e+00
+     N Arrays:   3
+
+
+Or using the entity name:
+
+.. code:: pycon
+
+   >>> volume1 = mapdl.geometry.volumes["volume 1"]
+   >>> volume1
+   UnstructuredGrid (0x149107340)
+     N Cells:    34
+     N Points:   36
+     X Bounds:   0.000e+00, 1.588e-02
+     Y Bounds:   -7.620e-03, 1.778e-02
+     Z Bounds:   -3.180e-03, 0.000e+00
+     N Arrays:   3
+
+
+You can now plot the different entities by just issuing plot after them:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas.plot()
+
+
+.. figure:: ../images/multiblock_pic1.png
+
+
+Or you can just plot a single entity:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas["area 1"].plot()
+
+
+.. figure:: ../images/multiblock_pic2.png
+
+
+Or multiple entities using slices:
+
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas[2:12:2].plot()
+
+
+.. figure:: ../images/multiblock_pic3.png
+
+
+Furthermore, the following methods are provided to return the geometry entities as other Python objects:
+
+.. _Table-1:
+
+**Table 1. Get_ENTITY methods.**
+
++------------------------+--------------------------+-------------------------------+---------------------------------+-------------------------------------+
+|                        | **Default output**       | :py:`return_as_list=True`     | :py:`return_as_array=True`      | :py:`return_ids_in_array=True`      |
++========================+==========================+===============================+=================================+=====================================+
+| |get_keypoints|        | |pv-polydata|            | |list-pv-polydata|            | |np-array|                      | |np-array|                          |
++------------------------+--------------------------+-------------------------------+---------------------------------+-------------------------------------+
+| |get_lines|            | |pv-polydata|            | |list-pv-polydata|            | **Not Applicable**              | **Not Applicable**                  |
++------------------------+--------------------------+-------------------------------+---------------------------------+-------------------------------------+
+| |get_areas|            | |pv-polydata|            | |list-pv-unstruc|             | **Not Applicable**              | **Not Applicable**                  |
++------------------------+--------------------------+-------------------------------+---------------------------------+-------------------------------------+
+| |get_volumes|          | |pv-polydata|            | |list-pv-unstruc|             | **Not Applicable**              | **Not Applicable**                  |
++------------------------+--------------------------+-------------------------------+---------------------------------+-------------------------------------+
+
+.. _migration_geometry_api_066:
+
+Migration to the new Geometry API
+---------------------------------
+
+Several changes need to be addressed in older to update your script
+from the old API to the new API.
+
+One of the most important is that now, you don't need to call the entities like in the old API:
+
+.. code:: pycon
+
+   # Old API
+   >>> mapdl.geometry.areas()
+   [UnstructuredGrid (0x7f14add95040)
+     N Cells:	12
+     N Points:	20
+     X Bounds:	-2.000e+00, 2.000e+00
+     Y Bounds:	0.000e+00, 1.974e+00
+     Z Bounds:	0.000e+00, 0.000e+00
+     N Arrays:	4,
+   UnstructuredGrid (0x7f14add95ca0)
+     N Cells:	12
+     N Points:	20
+     X Bounds:	-2.000e+00, 2.000e+00
+     Y Bounds:	0.000e+00, 1.974e+00
+     Z Bounds:	5.500e-01, 5.500e-01
+     N Arrays:	4,
+   ...
+
+Whereas in the new API:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas
+   MultiBlock (0x147ca7640)
+     N Blocks    28
+     X Bounds    -0.016, 0.016
+     Y Bounds    -0.008, 0.018
+     Z Bounds    -0.003, 0.015
+
+In addition, the type of entities returned by those methods are different.
+For comparison between the new and old geometry API, the following table is provided.
+
+.. _Table-2:
+
+**Table 2. Comparison between objects returned by both geometry APIs.**
+
++--------------------+------------------------------------------+--------------------------------------------------+
+| **Function**       | **Old API**                              | **New API**                                      |
+|                    | (Function based - Needs to called)       | (Property based - Doesn't need to be called)     |
++====================+==========================================+==================================================+
+|  |geo-key|         | |np-array|                               | |pv-multiblock|                                  |
++--------------------+------------------------------------------+--------------------------------------------------+
+| |geo-lines|        | |pv-polydata|                            | |pv-multiblock|                                  |
++--------------------+------------------------------------------+--------------------------------------------------+
+| |geo-areas|        | |pv-polydata|                            | |pv-multiblock|                                  |
++--------------------+------------------------------------------+--------------------------------------------------+
+| |geo-volumes|      | **Not existent**                         | |pv-multiblock|                                  |
++--------------------+------------------------------------------+--------------------------------------------------+
+
+
+For equivalence between the new and old geometry API, the following table is provided.
+
+
+.. _Table-3:
+
+**Table 3. Equivalence between both API methods.**
+
++-------------------------------+--------------------------------------+
+| **Old API**                   | **New API** equivalent               |
++===============================+======================================+
+| |leggeo-keypoints|            | |get_keypoints-return_as_array|      |
++-------------------------------+--------------------------------------+
+| |leggeo-lines|                | |get_lines|                          |
++-------------------------------+--------------------------------------+
+| |leggeo-areas|                | |get_areas|                          |
++-------------------------------+--------------------------------------+
+| **Not existent**              | |geo-volumes|                        |
++-------------------------------+--------------------------------------+
+
+
+MAPDL geometry commands
+~~~~~~~~~~~~~~~~~~~~~~~
+For additional MAPDL commands for creating geometries, see the
 :ref:`ref_prep_commands` commands.
 
 

examples/01-geometry/00-keypoints.py

@@ -67,11 +67,20 @@
 knum = mapdl.geometry.knum
 knum
 
+###############################################################################
+# Keypoints geometry
+# ~~~~~~~~~~~~~~~~~~
+# Get the VTK ``MultiBlock`` containing keypoints.  This VTK mesh can be
+# saved or plotted.  For more details, visit `Pyvista documentation <pyvista_docs_>`_
+keypoints = mapdl.geometry.keypoints
+keypoints
+
+
 ###############################################################################
 # Keypoint Coordinates
 # ~~~~~~~~~~~~~~~~~~~~
 # Return an array of the keypoint locations
-kloc = mapdl.geometry.keypoints
+kloc = mapdl.geometry.get_keypoints()
 kloc
 
 

examples/01-geometry/01-lines.py

@@ -231,7 +231,7 @@
 ###############################################################################
 # Line Geometry
 # ~~~~~~~~~~~~~
-# Get the VTK ``PolyData`` containing lines.  This VTK mesh can be
+# Get the VTK ``MultiBlock`` containing lines.  This VTK mesh can be
 # saved or plotted.  For more details, visit `Pyvista documentation <pyvista_docs_>`_
 lines = mapdl.geometry.lines
 lines

examples/01-geometry/02-areas.py

@@ -92,20 +92,23 @@
 ###############################################################################
 # Area Geometry
 # ~~~~~~~~~~~~~
-# Get the VTK ``PolyData`` containing lines.  This VTK mesh can be
+# Get the VTK ``Multiblock`` containing lines.  This VTK mesh can be
 # saved or plotted.  For more details, visit `Pyvista documentation <pyvista_docs_>`_
 #
-# Note that this is a method so you can select the quality of the
-# areas (mesh density), and if you would like a merged output or
-# individual meshes.
-areas = mapdl.geometry.areas(quality=3)
+areas = mapdl.geometry.areas
 areas
 
 
 ###############################################################################
 # Merged Area Geometry
 # ~~~~~~~~~~~~~~~~~~~~
-area = mapdl.geometry.areas(quality=3, merge=True)
+# You can also obtain the areas as ``pyvista.PolyData`` objects.
+#
+# Note that this is a method so you can select the quality of the
+# areas (mesh density), and if you would like a merged output or
+# individual meshes.
+
+area = mapdl.geometry.get_areas(quality=3)
 area
 
 # optionally save the area, or plot it

examples/01-geometry/03-volumes.py

@@ -200,8 +200,8 @@
 ###############################################################################
 # Volume Geometry
 # ~~~~~~~~~~~~~~~
-# Volume geometry can be accessed from the ``geometry.areas`` method.
-volume_mesh = mapdl.geometry.areas(merge=True)
+# Volume geometry can be accessed from the ``geometry.volumes`` method.
+volume_mesh = mapdl.geometry.volumes
 volume_mesh