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,208 @@ 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
+--------
+
+In PyMAPDL 0.66.0 and later, by default, all geometry entities are returned
+as a |pv-multiblock|  object.
+
+**Example 1**
+
+.. 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
+
+**Example 2**:
+
+.. 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, you do not need to call the entitities in the new API.
+
+For more differences between the new Geometry API and the old one, see
+:ref:`migration_geometry_api_066`. 
+
+
+The selection now is easier.
+
+You can 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
+
+
+You can use 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 plot different entities by calling the :meth:`plot() <ansys.mapdl.core.mapdl_geometry.Geometry.keypoints.plot>` method:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas.plot()
+
+
+.. figure:: ../images/multiblock_pic1.png
+
+
+You can plot a single entity:
+
+.. code:: pycon
+
+   >>> mapdl.geometry.areas["area 1"].plot()
+
+
+.. figure:: ../images/multiblock_pic2.png
+
+
+You can plot 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 must be addressed in older scripts to update them
+from the old API to the new API.
+
+One of the most important is that you no longer need to call the entities like you did in the old API.
+
+**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,
+   ...
+
+**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.
+This table compares the objects returned by the old and new APIs:
+
+.. _Table-2:
+
+**Table 2. Comparison between objects returned by both APIs.**
+
++--------------------+------------------------------------------+--------------------------------------------------+
+| **Function**       | **Old API**                              | **New API**                                      |
+|                    | (Function based - Must be 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|                                  |
++--------------------+------------------------------------------+--------------------------------------------------+
+
+
+This table shows the equivalence between the old and new APIs:
+
+
+.. _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 information, 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,8 +231,8 @@
 ###############################################################################
 # Line Geometry
 # ~~~~~~~~~~~~~
-# Get the VTK ``PolyData`` containing lines.  This VTK mesh can be
-# saved or plotted.  For more details, visit `Pyvista documentation <pyvista_docs_>`_
+# Get the VTK ``MultiBlock`` containing lines.  This VTK mesh can be
+# saved or plotted.  For more information, see the `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
-# saved or plotted.  For more details, visit `Pyvista documentation <pyvista_docs_>`_
+# Get the VTK ``Multiblock`` containing lines. This VTK mesh can be
+# saved or plotted.  For more information, see the `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. You can select the quality of the
+# areas (mesh density) and whether you want 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