GEOS-DEV · alexbenedicto · Apr 17, 2025 · Dec 24, 2024 · Jan 22, 2025 · Jan 22, 2025
diff --git a/docs/conf.py b/docs/conf.py
@@ -17,7 +17,8 @@
 
 # Add python modules to be documented
 python_root = '..'
-python_modules = ( 'geos-ats', 'geos-geomechanics', 'geos-mesh', 'geos-posp', 'geos-pv', 'geos-timehistory', 'geos-utils', 'geos-xml-tools', 'geos-xml-viewer', 'hdf5-wrapper', 'pygeos-tools' )
+python_modules = ( 'geos-ats', 'geos-geomechanics', 'geos-mesh', 'geos-posp', 'geos-pv', 'geos-timehistory',
+                   'geos-utils', 'geos-xml-tools', 'geos-xml-viewer', 'hdf5-wrapper', 'pygeos-tools' )
 
 
 for m in python_modules:
@@ -49,7 +50,9 @@
 ]
 
 autoclass_content = 'both'
-autodoc_mock_imports = [ "ats", "colorcet", "h5py", "lxml", "matplotlib", "meshio", "mpi4py", "scipy", "pandas", "paraview", "pygeosx", "pylvarray", "vtk", "xmlschema", "xsdata", ]
+autodoc_mock_imports = [ "ats", "colorcet", "h5py", "lxml", "matplotlib", "meshio", "mpi4py", "numba", "pandas",
+                         "paraview", "pygeosx", "pyevtk", "pylvarray", "scipy", "segyio", "vtk", "xmlschema",
+                         "xmltodict", "xsdata" ]
 autodoc_typehints = 'none'
 autodoc_typehints_format = 'short'
 suppress_warnings = [ "autodoc.mocked_object" ]

diff --git a/docs/pygeos-tools.rst b/docs/pygeos-tools.rst
@@ -1,24 +1,47 @@
 
 PyGEOS Tools
---------------------------
+=============
 
 The `pygeos-tools` python package adds a variety of tools for working with pygeosx objects.
 These include common operations such as setting the value of geosx wrappers with python functions, parallel communication, and file IO.
 Examples using these tools can be found here: `PYGEOSX Examples <https://geosx-geosx.readthedocs-hosted.com/en/latest/docs/sphinx/advancedExamples/pygeosxExamples/Index.html>`_ .
 
+To get the pygeosx objects, you need to build your GEOS with pygeosx, using this command in your cmake file.
 
-API
-^^^^^
+.. code-block:: cmake
 
-.. automodule:: geos.pygeos_tools.wrapper
-    :members:
+   set(ENABLE_PYGEOSX ON CACHE BOOL "")
 
-.. automodule:: geos.pygeos_tools.file_io
-    :members:
 
-.. automodule:: geos.pygeos_tools.mesh_interpolation
-    :members:
+**The python used to build GEOS with pygeosx will be the python to build the pygeos-tools.**
+Once the correct python is selected, you need to run in your virtual environment.
 
-.. automodule:: geos.pygeos_tools.well_log
-    :members:
+.. code-block:: console
 
+   python -m pip install ./pygeos-tools/
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents
+
+   ./pygeos_tools_docs/api.rst
+
+   ./pygeos_tools_docs/acquisition_library.rst
+
+   ./pygeos_tools_docs/input.rst
+
+   ./pygeos_tools_docs/mesh.rst
+
+   ./pygeos_tools_docs/model.rst
+
+   ./pygeos_tools_docs/output.rst
+
+   ./pygeos_tools_docs/solvers.rst
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Example
+
+   ./pygeos_tools_docs/Example/reservoir.rst
diff --git a/docs/pygeos_tools_docs/Example/reservoir.rst b/docs/pygeos_tools_docs/Example/reservoir.rst
@@ -0,0 +1,166 @@
+#################################################################################
+ Driving a reservoir simulation with Pygeos
+#################################################################################
+
+
+**Context**
+
+In this example, we will use pygeos to control a CompositionalMultiphaseFVM solver throughout a GEOS simulation.
+The goal is to reproduce the same results as if the simulation was launched directly through the XML file.
+
+For the rest of this example, every part highlighting Python snippets will represent what is used to control pygeos and
+how it is linked to the XML file.
+
+The example python script for this documentation is the following:
+
+.. code-block:: console
+
+   pygeos-tools/examples/solvers/reservoir_modeling.py
+
+
+------------------------------------------------------------------
+ XML file and initialization of Solver object
+------------------------------------------------------------------
+
+
+The xml input file for the test case is located at:
+
+.. code-block:: console
+
+   /path/to/your/GEOS/src/inputFiles/compositionalMultiphaseFlow/2ph_cap_1d_ihu.xml
+
+
+After setting up the MPI communication and parsing all the args, we can set the XML object that has parsed our XML file.
+
+.. code-block:: python
+
+   xmlfile = args.xml
+   xml = XML( xmlfile )
+
+
+**Solver**
+
+The simulation is performed using the GEOS general-purpose multiphase flow solver.
+The solver can be found in the ``Solvers`` block.
+
+.. code-block:: xml
+
+   <Solvers gravityVector="{0.38268, 0., -0.92388}">
+
+     <CompositionalMultiphaseFVM
+       name="compflow"
+       logLevel="1"
+       discretization="fluidTPFA"
+       targetRegions="{ Region1 }"
+       temperature="297.15">
+
+       <NonlinearSolverParameters
+         newtonTol="5e-4"
+         lineSearchAction="None"
+         newtonMaxIter="15"/>
+
+       <LinearSolverParameters
+         directParallel="0"/>
+
+     </CompositionalMultiphaseFVM>
+
+   </Solvers>
+
+
+The important thing to note here is the solver type ``CompositionalMultiphaseFVM``.
+Because we are dealing with a flow solver, which is not coupled, we can use the ``ReservoirSolver`` class to pilot the simulation.
+
+.. code-block:: python
+
+   solver = ReservoirSolver( "CompositionalMultiphaseFVM" )
+   solver.initialize( rank=rank, xml=xml )
+   solver.applyInitialConditions()
+
+
+**Events**
+
+To trigger the timestepping of the solver and the different outputs to perform, the "Events" block is the following:
+
+.. code-block:: xml
+
+   <Events
+     maxTime="1.0368e8">
+
+     <PeriodicEvent
+       name="outputs"
+       timeFrequency="1.728e6"
+       target="/Outputs/vtkOutput"/>
+
+     <PeriodicEvent
+       name="solverApplications1"
+       forceDt="1.728e6"
+       target="/Solvers/compflow"/>
+
+     <PeriodicEvent
+       name="restarts"
+       timeFrequency="3e7"
+       targetExactTimestep="0"
+       target="/Outputs/restartOutput"/>
+
+   </Events>
+
+
+The first attribute to use is ``maxTime`` which will be the limit for the simulation.
+The ``solverApplications1`` event targets the ``CompositionalMultiphaseFVM`` solver that we are using.
+This block contains a ``forceDt`` attribute that will be used later to choose as the timestep of the simulation.
+
+.. code-block:: python
+
+   solver.setDtFromTimeVariable( "forceDt" )                    # solver.dt = 1.728e6
+   solver.setMaxTime( solver.getTimeVariables()[ "maxTime" ] )  # solver.maxTime = 1.0368e8
+
+
+The "outputs" event triggers the output of the vtk files. The attribute "timeFrequency" has the same value as "forceDt"
+so we can use the same timestep for the solver and the outputs.
+To start, we will set the time to 0.0 and trigger one output of the vtk files.
+
+.. code-block:: python
+
+   time = 0.0
+   solver.outputVtk( time )
+
+
+------------------------------------------------------------------
+ Iterations process and simulation end
+------------------------------------------------------------------
+
+The iterative process organizes the execution of the solver at each timestep while not exceeding the maxTime of the simulation.
+Once done, the simulation is ended by calling the ``cleanup`` method.
+
+.. code-block:: python
+
+   while time < solver.maxTime:
+       solver.execute( time )
+       solver.outputVtk( time )
+       time += solver.dt
+   solver.cleanup( time )
+
+
+More complex timestepping strategies can be implemented by modifying the timestep duration and the outputs.
+
+
+------------------------------------------------------------------
+ How to run that script
+------------------------------------------------------------------
+
+Using the same python used to build your GEOS installation with, run this command:
+
+.. code-block:: console
+
+   python pygeos-tools/examples/solvers/reservoir_modeling.py
+          --xml /path/to/your/GEOS/src/inputFiles/compositionalMultiphaseFlow/2ph_cap_1d_ihu.xml
+
+
+------------------------------------------------------------------
+ To go further
+------------------------------------------------------------------
+
+
+**Feedback on this example**
+
+For any feedback on this example, please submit a `GitHub issue on the project's GitHub page <https://github.com/GEOS-DEV/geosPythonPackages/issues>`_.
diff --git a/docs/pygeos_tools_docs/acquisition_library.rst b/docs/pygeos_tools_docs/acquisition_library.rst
@@ -0,0 +1,37 @@
+Acquisition library
+===================
+
+This package contain utilities for seismic acquisition.
+
+
+Acquisition
+-----------
+
+.. automodule:: geos.pygeos_tools.acquisition_library.Acquisition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+EquispacedAcquisition
+---------------------
+
+.. automodule:: geos.pygeos_tools.acquisition_library.EquispacedAcquisition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+SegyAcquisition
+---------------
+
+.. automodule:: geos.pygeos_tools.acquisition_library.SegyAcquisition
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Shot
+----
+
+.. automodule:: geos.pygeos_tools.acquisition_library.Shot
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pygeos_tools_docs/api.rst b/docs/pygeos_tools_docs/api.rst
@@ -0,0 +1,35 @@
+API
+====
+
+
+Wrapper
+-------
+
+.. automodule:: geos.pygeos_tools.wrapper
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+File IO
+-------
+
+.. automodule:: geos.pygeos_tools.file_io
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Mesh Interpolation
+------------------
+
+.. automodule:: geos.pygeos_tools.mesh_interpolation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Well Log
+--------
+
+.. automodule:: geos.pygeos_tools.well_log
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pygeos_tools_docs/input.rst b/docs/pygeos_tools_docs/input.rst
@@ -0,0 +1,23 @@
+Input
+=====
+
+This packages has utilities for handling the two principal arguments of GEOS:
+- the XML file that will be used to setup GEOS simulation
+- the Geos args which are -i input, partitions ...
+
+
+GeosxArgs
+---------
+
+.. automodule:: geos.pygeos_tools.input.GeosxArgs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Xml
+---
+
+.. automodule:: geos.pygeos_tools.input.Xml
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pygeos_tools_docs/mesh.rst b/docs/pygeos_tools_docs/mesh.rst
@@ -0,0 +1,23 @@
+Mesh
+====
+
+This packages has utilities to handle the two different mesh formats to use in GEOS:
+- InternalMesh that is provided by GEOS
+- VtkMesh that is imported by GEOS
+
+
+InternalMesh
+------------
+
+.. automodule:: geos.pygeos_tools.mesh.InternalMesh
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+VtkMesh
+-------
+
+.. automodule:: geos.pygeos_tools.mesh.VtkMesh
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/pygeos_tools_docs/model.rst b/docs/pygeos_tools_docs/model.rst
@@ -0,0 +1,27 @@
+Model
+=====
+
+
+pyevtk_tools
+------------
+
+.. automodule:: geos.pygeos_tools.model.pyevtk_tools
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+SepModel
+--------
+
+.. automodule:: geos.pygeos_tools.model.SepModel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+VtkModel
+--------
+
+.. automodule:: geos.pygeos_tools.model.VtkModel
+   :members:
+   :undoc-members:
+   :show-inheritance: