GEOS-DEV · alexbenedicto · May 9, 2025 · May 9, 2025 · May 12, 2025 · May 13, 2025
diff --git a/docs/geos-mesh.rst b/docs/geos-mesh.rst
@@ -9,6 +9,8 @@ GEOS Mesh tools
 
       ./geos_mesh_docs/doctor
 
+      ./geos_mesh_docs/doctor_filters
+
       ./geos_mesh_docs/converter
 
       ./geos_mesh_docs/io

diff --git a/docs/geos_mesh_docs/doctor.rst b/docs/geos_mesh_docs/doctor.rst
@@ -1,9 +1,9 @@
 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.
+| ``mesh-doctor`` is a ``python`` executable that can be used through the command line to perform various checks, validations, and tiny fixes to the ``vtkUnstructuredGrid`` 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.
 
 Prerequisites
 ^^^^^^^^^^^^^
@@ -310,8 +310,55 @@ It will also verify that the ``VTK_POLYHEDRON`` cells can effectively get conver
 .. code-block::
 
       $ mesh-doctor supported_elements --help
-      usage: mesh_doctor.py supported_elements [-h] [--chunck_size 1] [--nproc 8]
+      usage: mesh_doctor.py supported_elements [-h] [--chunk_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.
+      --chunk_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.
+
+
+Why only use vtkUnstructuredGrid?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| The mesh doctor is designed specifically for unstructured meshes used in GEOS.
+| All input files are expected to be ``.vtu`` (VTK Unstructured Grid) format.
+| What about other formats?
+
+VTK Hierarchy
+"""""""""""""
+
+Supposedly, other grid types that are part of the following VTK hierarchy could be used::
+
+      vtkDataObject
+      └── vtkDataSet
+      └── vtkCartesianGrid
+            └── vtkRectilinearGrid
+            └── vtkImageData
+                  └── vtkStructuredPoints
+                  └── vtkUniformGrid
+      └── vtkPointSet
+            └── vtkExplicitStructuredGrid
+            └── vtkPolyData
+            └── vtkStructuredGrid
+            └── vtkUnstructuredGrid
+
+And when looking at specific methods used in mesh-doctor, it could suggest that other formats could be used:
+
+* Points access: ``mesh.GetPoints()`` - Available in all vtkPointSet subclasses ✓
+* Cell iteration: ``mesh.GetNumberOfCells()``, ``mesh.GetCell()`` - Available in all vtkDataSet subclasses ✓
+* Cell types: ``mesh.GetCellType()`` - Available in all vtkDataSet subclasses ✓
+* Cell/Point data: ``mesh.GetCellData()``, ``mesh.GetPointData()`` - Available in all vtkDataSet subclasses ✓
+
+VTK Filter Compatibility
+""""""""""""""""""""""""
+
+| ``vtkCellSizeFilter``, ``vtkMeshQuality``, and other VTK filters used in the actions expect ``vtkDataSet`` or its subclasses
+  ``vtkUnstructuredGrid`` is compatible with all VTK filters used.
+| ``vtkPolyData`` has a different data structure, not suitable for 3D volumetric meshes.
+
+Specific Operations Require vtkUnstructuredGrid
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+* ``GetCellNeighbors()`` - Only available in vtkUnstructuredGrid
+* ``GetFaceStream()`` - Only available in vtkUnstructuredGrid (for polyhedron support)
+* ``GetDistinctCellTypesArray()`` - Only available in vtkUnstructuredGrid
diff --git a/docs/geos_mesh_docs/doctor_filters.rst b/docs/geos_mesh_docs/doctor_filters.rst
@@ -0,0 +1,19 @@
+VTK Filters
+===========
+
+In addition to the command-line interface, mesh-doctor functionality is also available as VTK filters for programmatic use in Python. These filters provide the same mesh validation and processing capabilities but can be integrated directly into Python workflows and visualization pipelines.
+
+The VTK filters offer several advantages:
+
+* **Integration**: Easy integration with existing VTK/ParaView workflows
+* **Scripting**: Programmatic access for batch processing and automation
+* **Visualization**: Direct output suitable for ParaView visualization
+* **Flexibility**: Configurable parameters and output options
+* **Chaining**: Ability to combine multiple filters in processing pipelines
+
+For detailed documentation on available filters, their parameters, and usage examples, see:
+
+.. toctree::
+   :maxdepth: 1
+
+   filters/index
diff --git a/docs/geos_mesh_docs/filters/Checks.rst b/docs/geos_mesh_docs/filters/Checks.rst
@@ -0,0 +1,18 @@
+AllChecks and MainChecks Filters
+================================
+
+.. automodule:: geos.mesh.doctor.filters.Checks
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+See Also
+--------
+
+* :doc:`CollocatedNodes <CollocatedNodes>` - Individual collocated nodes check
+* :doc:`ElementVolumes <ElementVolumes>` - Individual element volume check
+* :doc:`NonConformal <NonConformal>` - Individual non-conformal interface check
+* :doc:`SelfIntersectingElements <SelfIntersectingElements>` - Individual self-intersection check
+* :doc:`SupportedElements <SupportedElements>` - Individual supported elements check
+
+
diff --git a/docs/geos_mesh_docs/filters/CollocatedNodes.rst b/docs/geos_mesh_docs/filters/CollocatedNodes.rst
@@ -0,0 +1,50 @@
+CollocatedNodes Filter
+======================
+
+.. automodule:: geos.mesh.doctor.filters.CollocatedNodes
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Understanding the Results
+-------------------------
+
+**Collocated Node Buckets**
+
+Each bucket is a tuple containing node indices that are within the specified tolerance of each other:
+
+.. code-block:: python
+
+    # Example result: [(0, 15, 23), (7, 42), (100, 101, 102, 103)]
+    # This means:
+    # - Nodes 0, 15, and 23 are collocated
+    # - Nodes 7 and 42 are collocated
+    # - Nodes 100, 101, 102, and 103 are collocated
+
+**Wrong Support Elements**
+
+Cell element IDs where the same node appears multiple times in the element's connectivity. This usually indicates:
+
+* Degenerate elements
+* Mesh generation errors
+* Topology problems
+
+Common Use Cases
+----------------
+
+* **Mesh Quality Assessment**: Identify potential mesh issues before simulation
+* **Mesh Preprocessing**: Clean up meshes by detecting node duplicates
+* **Debugging**: Understand why meshes might have connectivity problems
+* **Validation**: Ensure mesh meets quality standards for specific applications
+
+I/O
+---
+
+* **Input**: vtkUnstructuredGrid
+* **Output**: vtkUnstructuredGrid with optional arrays marking problematic elements
+* **Additional Data**: When painting is enabled, adds "WrongSupportElements" array to cell data
+
+See Also
+--------
+
+* :doc:`AllChecks and MainChecks <Checks>` - Includes collocated nodes check among others
diff --git a/docs/geos_mesh_docs/filters/ElementVolumes.rst b/docs/geos_mesh_docs/filters/ElementVolumes.rst
@@ -0,0 +1,63 @@
+ElementVolumes Filter
+=====================
+
+.. automodule:: geos.mesh.doctor.filters.ElementVolumes
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Understanding Volume Issues
+---------------------------
+
+**Negative Volumes**
+
+Indicate elements with inverted geometry:
+
+* **Tetrahedra**: Nodes ordered incorrectly (clockwise instead of counter-clockwise)
+* **Hexahedra**: Faces oriented inward instead of outward
+* **Other elements**: Similar orientation/ordering issues
+
+**Zero Volumes**
+
+Indicate degenerate elements:
+
+* **Collapsed elements**: All nodes lie in the same plane (3D) or line (2D)
+* **Duplicate nodes**: Multiple nodes at the same location within the element
+* **Extreme aspect ratios**: Elements stretched to near-zero thickness
+
+**Impact on Simulations**
+
+Elements with non-positive volumes can cause:
+
+* Numerical instabilities
+* Convergence problems
+* Incorrect physical results
+* Solver failures
+
+Common Fixes
+------------
+
+**For Negative Volumes:**
+
+1. **Reorder nodes**: Correct the connectivity order
+2. **Flip elements**: Use mesh repair tools
+3. **Regenerate mesh**: If issues are widespread
+
+**For Zero Volumes:**
+
+1. **Remove degenerate elements**: Delete problematic cells
+2. **Merge collocated nodes**: Fix duplicate node issues
+3. **Improve mesh quality**: Regenerate with better settings
+
+I/O
+---
+
+* **Input**: vtkUnstructuredGrid
+* **Output**: vtkUnstructuredGrid with volume information added as cell data
+* **Volume Array**: "Volume" array added to cell data containing computed volumes
+* **Additional Data**: When returnNegativeZeroVolumes is enabled, provides detailed problematic element information
+
+See Also
+--------
+
+* :doc:`AllChecks and MainChecks <Checks>` - Includes element volumes check among others
diff --git a/docs/geos_mesh_docs/filters/GenerateFractures.rst b/docs/geos_mesh_docs/filters/GenerateFractures.rst
@@ -0,0 +1,78 @@
+GenerateFractures Filter
+========================
+
+.. automodule:: geos.mesh.doctor.filters.GenerateFractures
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Fracture Policies
+-----------------
+
+**Field Fractures Policy (field)**
+
+| Obtained by setting ``--policy field``.
+|
+| Creates fractures by using internal interfaces between cells regions.
+| These interfaces corresponds to a change in the values of a CellData array stored in your mesh.
+| Suppose you have a CellData array named "Regions" with 3 different values indicating geological layers. 1 is caprock, 2 is reservoir, and 3 is underburden as represented here (below is a 2D representation along Z for simplicity):
+|
+| 111111111111111111
+| 111111222222222222
+| 222222222223333333
+| 333333333333333333
+|
+| In this example, I define the interface between reservoir and caprock as a fracture, and the interface between reservoir and underburden as another fracture.
+| So when specifying your field values as ``--values 1,2:2,3``, the filter will create a fracture along the interface between these two regions. The result will be a new mesh with the fracture represented as a separate entity. The nodes will be split along these interfaces, allowing for discontinuities in the mesh:
+|
+| 111111111111111111
+| 111111------------
+| ------222222222222
+| 22222222222+++++++
+| +++++++++++3333333
+| 333333333333333333
+|
+| with ``----`` representing the first fracture and ``+++++++`` representing the second fracture.
+
+**Internal Fractures Policy (internal_surfaces)**
+
+| Obtained by setting ``--policy internal_surfaces``.
+|
+| Creates fractures by using tagged 2D cells that are identified as a fracture.
+| In VTK, ``2D cells`` are refering to ``VTK_TRIANGLE`` or ``VTK_QUAD`` cell types.
+| These 2D cells should be part of the input mesh and tagged with a specific CellData array value.
+| Suppose you have a CellData array named "isFault" with 3 different values to tag fractures. 0 is for all non fault cells, 1 is fault1, and 2 is fault2 as represented here (below is a 2D representation along Z for simplicity):
+|
+| 000000000000000000
+| 000000111111111111
+| 111111000000000000
+| 000000000002222222
+| 222222222220000000
+| 000000000000000000
+|
+| So when specifying your field values as ``--values 1:2``, the filter will create one fracture for each cells tagged with 1 and 2.
+
+Understanding Fracture Generation
+---------------------------------
+
+**Process**
+
+1. **Identification**: Find interfaces between cells with different field values
+2. **Node Duplication**: Create separate nodes for each side of the fracture
+3. **Mesh Splitting**: Update connectivity to use duplicated nodes
+4. **Fracture Extraction**: Generate separate meshes for fracture surfaces
+
+**Output Structure**
+
+* **Split Mesh**: Original mesh with fractures as discontinuities
+* **Fracture Meshes**: Individual surface meshes for each fracture
+
+I/O
+---
+
+* **Input**: vtkUnstructuredGrid with fracture identification field or tagged 2D cells
+* **Outputs**: 
+
+  * Split mesh with fractures as discontinuities
+  * Individual fracture surface meshes
+* **File Output**: Automatic writing of fracture meshes to specified directory
diff --git a/docs/geos_mesh_docs/filters/GenerateRectilinearGrid.rst b/docs/geos_mesh_docs/filters/GenerateRectilinearGrid.rst
@@ -0,0 +1,14 @@
+GenerateRectilinearGrid Filter
+==============================
+
+.. automodule:: geos.mesh.doctor.filters.GenerateRectilinearGrid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+I/O
+---
+
+* **Input**: Not needed
+* **Output**: vtkUnstructuredGrid
+* **Additional Data**: New fields on points or cells if user requests them.
diff --git a/docs/geos_mesh_docs/filters/MeshDoctorFilterBase.rst b/docs/geos_mesh_docs/filters/MeshDoctorFilterBase.rst
@@ -0,0 +1,14 @@
+MeshDoctorFilterBase
+====================
+
+.. automodule:: geos.mesh.doctor.filters.MeshDoctorFilterBase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+See Also
+--------
+
+* :doc:`AllChecks and MainChecks <Checks>` - Comprehensive mesh quality assessment using MeshDoctorFilterBase
+* :doc:`GenerateRectilinearGrid <GenerateRectilinearGrid>` - Grid generation using MeshDoctorGeneratorBase
+* :doc:`GenerateFractures <GenerateFractures>` - Fracture mesh generation using MeshDoctorFilterBase