Skip to content

Change dynamic documentation for geos-mesh to static documentation #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 29, 2024
Merged

Change dynamic documentation for geos-mesh to static documentation #37

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 183 additions & 22 deletions docs/geos-mesh.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,59 @@ 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 src/geos/mesh/doctor/mesh_doctor.py --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py --help
usage: mesh_doctor.py [-h] [-v] [-q] -i VTK_MESH_FILE
{collocated_nodes,element_volumes,fix_elements_orderings,generate_cube,generate_fractures,generate_global_ids,non_conformal,self_intersecting_elements,supported_elements}
...

Inspects meshes for GEOSX.

positional arguments:
{collocated_nodes,element_volumes,fix_elements_orderings,generate_cube,generate_fractures,generate_global_ids,non_conformal,self_intersecting_elements,supported_elements}
Modules
collocated_nodes
Checks if nodes are collocated.
element_volumes
Checks if the volumes of the elements are greater than "min".
fix_elements_orderings
Reorders the support nodes for the given cell types.
generate_cube
Generate a cube and its fields.
generate_fractures
Splits the mesh to generate the faults and fractures. [EXPERIMENTAL]
generate_global_ids
Adds globals ids for points and cells.
non_conformal
Detects non conformal elements. [EXPERIMENTAL]
self_intersecting_elements
Checks if the faces of the elements are self intersecting.
supported_elements
Check that all the elements of the mesh are supported by GEOSX.

options:
-h, --help
show this help message and exit
-v Use -v 'INFO', -vv for 'DEBUG'. Defaults to 'WARNING'.
-q Use -q to reduce the verbosity of the output.
-i VTK_MESH_FILE, --vtk-input-file VTK_MESH_FILE

Note that checks are dynamically loaded.
An option may be missing because of an unloaded module.
Increase verbosity (-v, -vv) to get full information.

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 src/geos/mesh/doctor/mesh_doctor.py collocated_nodes --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py collocated_nodes --help
usage: mesh_doctor.py collocated_nodes [-h] --tolerance TOLERANCE

options:
-h, --help show this help message and exit
--tolerance TOLERANCE [float]: The absolute distance between two nodes for them to be considered collocated.

``mesh-doctor`` loads its module dynamically.
If a module can't be loaded, ``mesh-doctor`` will proceed and try to load other modules.
Expand All @@ -44,17 +89,29 @@ Here is a list and brief description of all the modules available.
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 src/geos/mesh/doctor/mesh_doctor.py collocated_nodes --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py collocated_nodes --help
usage: mesh_doctor.py collocated_nodes [-h] --tolerance TOLERANCE

options:
-h, --help show this help message and exit
--tolerance TOLERANCE [float]: The absolute distance between two nodes for them to be considered collocated.

``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 src/geos/mesh/doctor/mesh_doctor.py element_volumes --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py element_volumes --help
usage: mesh_doctor.py element_volumes [-h] --min 0.0

options:
-h, --help show this help message and exit
--min 0.0 [float]: The minimum acceptable volume. Defaults to 0.0.

``fix_elements_orderings``
""""""""""""""""""""""""""
Expand All @@ -63,8 +120,29 @@ It sometimes happens that an exported mesh does not abide by the ``vtk`` orderin
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 src/geos/mesh/doctor/mesh_doctor.py fix_elements_orderings --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py fix_elements_orderings --help
usage: mesh_doctor.py fix_elements_orderings [-h] [--Hexahedron 1,6,5,4,7,0,2,3] [--Prism5 8,2,0,7,6,9,5,1,4,3]
[--Prism6 11,2,8,10,5,0,9,7,6,1,4,3] [--Pyramid 3,4,0,2,1]
[--Tetrahedron 2,0,3,1] [--Voxel 1,6,5,4,7,0,2,3]
[--Wedge 3,5,4,0,2,1] --output OUTPUT [--data-mode binary, ascii]

options:
-h, --help show this help message and exit
--Hexahedron 1,6,5,4,7,0,2,3
[list of integers]: node permutation for "Hexahedron".
--Prism5 8,2,0,7,6,9,5,1,4,3
[list of integers]: node permutation for "Prism5".
--Prism6 11,2,8,10,5,0,9,7,6,1,4,3
[list of integers]: node permutation for "Prism6".
--Pyramid 3,4,0,2,1 [list of integers]: node permutation for "Pyramid".
--Tetrahedron 2,0,3,1 [list of integers]: node permutation for "Tetrahedron".
--Voxel 1,6,5,4,7,0,2,3 [list of integers]: node permutation for "Voxel".
--Wedge 3,5,4,0,2,1 [list of integers]: node permutation for "Wedge".
--output OUTPUT [string]: The vtk output file destination.
--data-mode binary, ascii
[string]: For ".vtu" output format, the data mode can be binary or ascii. Defaults to binary.

``generate_cube``
"""""""""""""""""
Expand All @@ -73,26 +151,84 @@ 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 src/geos/mesh/doctor/mesh_doctor.py generate_cube --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py generate_cube --help
usage: mesh_doctor.py generate_cube [-h] [--x 0:1.5:3] [--y 0:5:10] [--z 0:1] [--nx 2:2] [--ny 1:1] [--nz 4]
[--fields name:support:dim [name:support:dim ...]] [--cells] [--no-cells]
[--points] [--no-points] --output OUTPUT [--data-mode binary, ascii]

options:
-h, --help show this help message and exit
--x 0:1.5:3 [list of floats]: X coordinates of the points.
--y 0:5:10 [list of floats]: Y coordinates of the points.
--z 0:1 [list of floats]: Z coordinates of the points.
--nx 2:2 [list of integers]: Number of elements in the X direction.
--ny 1:1 [list of integers]: Number of elements in the Y direction.
--nz 4 [list of integers]: Number of elements in the Z direction.
--fields name:support:dim
[name:support:dim ...]: Create fields on CELLS or POINTS, with given dimension (typically 1 or 3).
--cells [bool]: Generate global ids for cells. Defaults to true.
--no-cells [bool]: Don't generate global ids for cells.
--points [bool]: Generate global ids for points. Defaults to true.
--no-points [bool]: Don't generate global ids for points.
--output OUTPUT [string]: The vtk output file destination.
--data-mode binary, ascii
[string]: For ".vtu" output format, the data mode can be binary or ascii. Defaults to binary.

``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 src/geos/mesh/doctor/mesh_doctor.py generate_fractures --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py generate_fractures --help
usage: mesh_doctor.py generate_fractures [-h] --policy field, internal_surfaces [--name NAME] [--values VALUES]
--output OUTPUT [--data-mode binary, ascii] --fracture-output
FRACTURE_OUTPUT [--fracture-data-mode binary, ascii]

options:
-h, --help show this help message and exit
--policy field, internal_surfaces
[string]: The criterion to define the surfaces that will be changed into fracture zones.
Possible values are "field, internal_surfaces"
--name NAME [string]: If the "field" policy is selected, defines which field will be considered to
define the fractures. If the "internal_surfaces" policy is selected, defines the name of
the attribute will be considered to identify the fractures.
--values VALUES [list of comma separated integers]: If the "field" policy is selected, which changes of
the field will be considered as a fracture. If the "internal_surfaces" policy is
selected, list of the fracture attributes.
--output OUTPUT [string]: The vtk output file destination.
--data-mode binary, ascii
[string]: For ".vtu" output format, the data mode can be binary or ascii. Defaults to binary.
--fracture-output FRACTURE_OUTPUT
[string]: The vtk output file destination.
--fracture-data-mode binary, ascii
[string]: For ".vtu" output format, the data mode can be binary or ascii. Defaults to binary.

``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 src/geos/mesh/doctor/mesh_doctor.py generate_global_ids --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py generate_global_ids --help
usage: mesh_doctor.py generate_global_ids [-h] [--cells] [--no-cells] [--points] [--no-points] --output OUTPUT
[--data-mode binary, ascii]

options:
-h, --help show this help message and exit
--cells [bool]: Generate global ids for cells. Defaults to true.
--no-cells [bool]: Don't generate global ids for cells.
--points [bool]: Generate global ids for points. Defaults to true.
--no-points [bool]: Don't generate global ids for points.
--output OUTPUT [string]: The vtk output file destination.
--data-mode binary, ascii
[string]: For ".vtu" output format, the data mode can be binary or ascii. Defaults to binary.

``non_conformal``
"""""""""""""""""
Expand All @@ -102,17 +238,35 @@ This module will detect elements which are close enough (there's a user defined
The angle between two faces can also be precribed.
This module can be a bit time consuming.

.. command-output:: python src/geos/mesh/doctor/mesh_doctor.py non_conformal --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py non_conformal --help
usage: mesh_doctor.py non_conformal [-h] [--angle_tolerance 10.0] [--point_tolerance POINT_TOLERANCE]
[--face_tolerance FACE_TOLERANCE]

options:
-h, --help show this help message and exit
--angle_tolerance 10.0 [float]: angle tolerance in degrees. Defaults to 10.0
--point_tolerance POINT_TOLERANCE
[float]: tolerance for two points to be considered collocated.
--face_tolerance FACE_TOLERANCE
[float]: tolerance for two faces to be considered "touching".

``self_intersecting_elements``
""""""""""""""""""""""""""""""

Some meshes can have cells that auto-intersect.
This module will display the elements that have faces intersecting.

.. command-output:: python src/geos/mesh/doctor/mesh_doctor.py self_intersecting_elements --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py self_intersecting_elements --help
usage: mesh_doctor.py self_intersecting_elements [-h] [--min 2.220446049250313e-16]

options:
-h, --help show this help message and exit
--min 2.220446049250313e-16
[float]: The tolerance in the computation. Defaults to your machine precision 2.220446049250313e-16.

``supported_elements``
""""""""""""""""""""""
Expand All @@ -125,8 +279,15 @@ But also prismes up to 11 faces.
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 src/geos/mesh/doctor/mesh_doctor.py supported_elements --help
:cwd: ../geos-mesh
.. code-block::

$ python src/geos/mesh/doctor/mesh_doctor.py supported_elements --help
usage: mesh_doctor.py supported_elements [-h] [--chunck_size 1] [--nproc 8]

options:
-h, --help show this help message and exit
--chunck_size 1 [int]: Defaults chunk size for parallel processing to 1
--nproc 8 [int]: Number of threads used for parallel processing. Defaults to your CPU count 8.



Expand Down
Loading