Documentation for mesh_doctor (#2684)

* First shot

* Finish all the modules

* log message

* debug

* add programoutput

* Install program-output!

* Define cwd

* correct cwd

* Use command-output instead of program-output

* Improve the messages a tad

* Apply suggestions from code review

Co-authored-by: Jian Huang <[email protected]>

* Refine explaination after review comments.

src/conf.py

@@ -108,6 +108,7 @@
     'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.napoleon',
     'sphinxcontrib.plantuml',
+    'sphinxcontrib.programoutput'
 ]
 
 plantuml = "/usr/bin/plantuml"

src/coreComponents/python/modules/geosx_mesh_doctor/parsing/self_intersecting_elements_parsing.py

@@ -27,7 +27,7 @@ def fill_subparser(subparsers) -> None:
                    required=False,
                    metavar=__TOLERANCE_DEFAULT,
                    default=__TOLERANCE_DEFAULT,
-                   help=f"[float]: The tolerance in the computation. Defaults to machine precision {__TOLERANCE_DEFAULT}")
+                   help=f"[float]: The tolerance in the computation. Defaults to your machine precision {__TOLERANCE_DEFAULT}.")
 
 
 def display_results(options: Options, result: Result):

src/coreComponents/python/modules/geosx_mesh_doctor/parsing/supported_elements_parsing.py

@@ -34,7 +34,7 @@ def fill_subparser(subparsers) -> None:
                    required=False,
                    metavar=__NUM_PROC_DEFAULT,
                    default=__NUM_PROC_DEFAULT,
-                   help=f"[int]: Number of threads used for parallel processing. Defaults to {__NUM_PROC_DEFAULT}")
+                   help=f"[int]: Number of threads used for parallel processing. Defaults to your CPU count {__NUM_PROC_DEFAULT}.")
 
 
 def display_results(options: Options, result: Result):

src/docs/sphinx/pythonTools/mesh_doctor.rst

@@ -0,0 +1,124 @@
+``mesh_doctor``
+---------------
+
+``mesh_doctor`` is a ``python`` executable that can be used through the command line to perform various checks, validations, and tiny fixes to the ``vtk`` mesh that are meant to be used in ``geos``.
+``mesh_doctor`` is organized as a collection of modules with their dedicated sets of options.
+The current page will introduce those modules, but the details and all the arguments can be retrieved by using the ``--help`` option for each module.
+
+Modules
+^^^^^^^
+
+To list all the modules available through ``mesh_doctor``, you can simply use the ``--help`` option, which will list all available modules as well as a quick summary.
+
+.. command-output:: python mesh_doctor.py --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+Then, if you are interested in a specific module, you can ask for its documentation using the ``mesh_doctor module_name --help`` pattern.
+For example
+
+.. command-output:: python mesh_doctor.py collocated_nodes --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``mesh_doctor`` loads its module dynamically.
+If a module can't be loaded, ``mesh_doctor`` will proceed and try to load other modules.
+If you see a message like
+
+.. code-block:: bash
+
+    [1970-04-14 03:07:15,625][WARNING] Could not load module "collocated_nodes": No module named 'vtkmodules'
+
+then most likely ``mesh_doctor`` could not load the ``collocated_nodes`` module, because the ``vtk`` python package was not found.
+Thereafter, the documentation for module ``collocated_nodes`` will not be displayed.
+You can solve this issue by installing the dependencies of ``mesh_doctor`` defined in its ``requirements.txt`` file (``python -m pip install -r requirements.txt``).
+
+Here is a list and brief description of all the modules available.
+
+``collocated_nodes``
+""""""""""""""""""""
+
+Displays the neighboring nodes that are closer to each other than a prescribed threshold.
+It is not uncommon to define multiple nodes for the exact same position, which will typically be an issue for ``geos`` and should be fixed.
+
+.. command-output:: python mesh_doctor.py collocated_nodes --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``element_volumes``
+"""""""""""""""""""
+
+Computes the volumes of all the cells and displays the ones that are below a prescribed threshold.
+Cells with negative volumes will typically be an issue for ``geos`` and should be fixed.
+
+.. command-output:: python mesh_doctor.py element_volumes --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``fix_elements_orderings``
+""""""""""""""""""""""""""
+
+It sometimes happens that an exported mesh does not abide by the ``vtk`` orderings.
+The ``fix_elements_orderings`` module can rearrange the nodes of given types of elements.
+This can be convenient if you cannot regenerate the mesh.
+
+.. command-output:: python mesh_doctor.py fix_elements_orderings --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``generate_cube``
+"""""""""""""""""
+
+This module conveniently generates cubic meshes in ``vtk``.
+It can also generate fields with simple values.
+This tool can also be useful to generate a trial mesh that will later be refined or customized.
+
+.. command-output:: python mesh_doctor.py generate_cube --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``generate_fractures``
+""""""""""""""""""""""
+
+For a conformal fracture to be defined in a mesh, ``geos`` requires the mesh to be split at the faces where the fracture gets across the mesh.
+The ``generate_fractures`` module will split the mesh and generate the multi-block ``vtk`` files.
+
+.. command-output:: python mesh_doctor.py generate_fractures --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``generate_global_ids``
+"""""""""""""""""""""""
+
+When running ``geos`` in parallel, `global ids` can be used to refer to data across multiple ranks.
+The ``generate_global_ids`` can generate `global ids` for the imported ``vtk`` mesh.
+
+.. command-output:: python mesh_doctor.py generate_global_ids --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``non_conformal``
+"""""""""""""""""
+
+This module will detect elements which are close enough (there's a user defined threshold) but which are not in front of each other (another threshold can be defined).
+`Close enough` can be defined in terms or proximity of the nodes and faces of the elements.
+The angle between two faces can also be precribed.
+This module can be a bit time consuming.
+
+.. command-output:: python mesh_doctor.py non_conformal --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``self_intersecting_elements``
+""""""""""""""""""""""""""""""
+
+Some meshes can have cells that auto-intersect.
+This module will display the elements that have faces intersecting.
+
+.. command-output:: python mesh_doctor.py self_intersecting_elements --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor
+
+``supported_elements``
+""""""""""""""""""""""
+
+``geos`` supports a specific set of elements.
+Let's cite the standard elements like `tetrahedra`, `wedges`, `pyramids` or `hexahedra`.
+But also prismes up to 11 faces.
+``geos`` also supports the generic ``VTK_POLYHEDRON``/``42`` elements, which are converted on the fly into one of the elements just described.
+
+The ``supported_elements`` check will validate that no unsupported element is included in the input mesh.
+It will also verify that the ``VTK_POLYHEDRON`` cells can effectively get converted into a supported type of element.
+
+.. command-output:: python mesh_doctor.py supported_elements --help
+   :cwd: ../../../coreComponents/python/modules/geosx_mesh_doctor

src/docs/sphinx/pythonTools/pythonAPI.rst

@@ -51,3 +51,4 @@ Packages
 
     timehistory
 
+    mesh_doctor

src/docs/sphinx/requirements.txt

@@ -8,3 +8,7 @@ pandas
 # using plantuml for diagrams
 sphinxcontrib-plantuml
 sphinx-argparse
+# Running CLI programs and capture outputs
+sphinxcontrib-programoutput==0.17
+# Installing the mesh_doctor requirements to be able to load all the modules and run the help.
+-r ../../coreComponents/python/modules/geosx_mesh_doctor/requirements.txt