Skip to content

Commit 5a0f75e

Browse files
alexbenedictoav-novikovVictor-M-Gomes
authored
feat: Python interfaces to geos from Makutu repo (refactoring) (#74)
* Created utils repository and updated every import for mesh_doctor * Messages correction in io * All the initial files from the Makutu PR are added for future refactoring * Refactoring mesh files * Moved solverutils to utils * Modified model directory structure + renamed vtkUtils into pyevtk_tools * Adding acoustic / elastic modeling tools * Correction exports and module names for pygeos-tools * Change imports for geos-mesh * Support processing of included XML files * Fix to wave prop modeling in p4 and p3. Also fix to allow use of python < 3.9 * Bug fix for io with VtkOutput * Format update io and GeosxArgs * Error handling for class methods * Update XML class * Update Solver base class with also the use of wrapper file * Update WaveSolver * Update AcousticSolver * bug fix * Add minTime and maxTime handling * Update ElasticSolver * Update ReservoirSolver * Update GeomechanicsSolver * Update hinting of variables and methods * Add examples of scripts to pilot a GEOS simulation through pygeos using the Solver classes * Add __doc__ at the beginning of scritps * Moved examples inside utilities * Change examples folder to solvers-examples * Moved all files outside of "utilities" folder and remove utilities folder * Update format of acquisition_library files * Update format of Trace outputs * Update pyproject.toml * Added .rst documentation * yapf formatting * yapf formatting + change minimum python version to 3.8 * For pygeos-tools: update documentation, removed geos-utils/pygeos-tools files to be in pygeos-tools, few corrections * Move geos.utils.vtk to geos.mesh.vtk * Update geos-mesh tests * Update docs for pygeos-tools to remove warnings * Exclude build directory when processing mypy checks + removed ruff checking + typing correction for classes.py * Bugfix for tests + yapf formatting * Remove conflict between ruff and mypy checking in classes.py * Fix build projects with invalid path * Update documentation * Move checking of xml file from __init__ to initialize method * Add examples for ReactiveCompositionalMultiphaseOBL solver * Upgrade python version to 3.10 * Remove examples to check if CI cache build error still occurs * Readded the examples for obl provided by Aleks Novikov + moved all examples outside of src + update docs * Fix name of the *.xml in 2ph_comp example * Fix timestepping in OBL solver examples * Rename folder with OBL examples * Updated example.rst and yapf formatting * Fix write_mesh --------- Co-authored-by: Aleks Novikov <[email protected]> Co-authored-by: Victor-M-Gomes <[email protected]>
1 parent e7583e5 commit 5a0f75e

File tree

90 files changed

+24470
-466
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

90 files changed

+24470
-466
lines changed

‎docs/conf.py

+5-2
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,8 @@
1717

1818
# Add python modules to be documented
1919
python_root = '..'
20-
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' )
20+
python_modules = ( 'geos-ats', 'geos-geomechanics', 'geos-mesh', 'geos-posp', 'geos-pv', 'geos-timehistory',
21+
'geos-utils', 'geos-xml-tools', 'geos-xml-viewer', 'hdf5-wrapper', 'pygeos-tools' )
2122

2223

2324
for m in python_modules:
@@ -49,7 +50,9 @@
4950
]
5051

5152
autoclass_content = 'both'
52-
autodoc_mock_imports = [ "ats", "colorcet", "h5py", "lxml", "matplotlib", "meshio", "mpi4py", "scipy", "pandas", "paraview", "pygeosx", "pylvarray", "vtk", "xmlschema", "xsdata", ]
53+
autodoc_mock_imports = [ "ats", "colorcet", "h5py", "lxml", "matplotlib", "meshio", "mpi4py", "numba", "pandas",
54+
"paraview", "pygeosx", "pyevtk", "pylvarray", "scipy", "segyio", "vtk", "xmlschema",
55+
"xmltodict", "xsdata" ]
5356
autodoc_typehints = 'none'
5457
autodoc_typehints_format = 'short'
5558
suppress_warnings = [ "autodoc.mocked_object" ]

‎docs/pygeos-tools.rst

+34-11
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,47 @@
11

22
PyGEOS Tools
3-
--------------------------
3+
=============
44

55
The `pygeos-tools` python package adds a variety of tools for working with pygeosx objects.
66
These include common operations such as setting the value of geosx wrappers with python functions, parallel communication, and file IO.
77
Examples using these tools can be found here: `PYGEOSX Examples <https://geosx-geosx.readthedocs-hosted.com/en/latest/docs/sphinx/advancedExamples/pygeosxExamples/Index.html>`_ .
88

9+
To get the pygeosx objects, you need to build your GEOS with pygeosx, using this command in your cmake file.
910

10-
API
11-
^^^^^
11+
.. code-block:: cmake
1212
13-
.. automodule:: geos.pygeos_tools.wrapper
14-
:members:
13+
set(ENABLE_PYGEOSX ON CACHE BOOL "")
1514
16-
.. automodule:: geos.pygeos_tools.file_io
17-
:members:
1815
19-
.. automodule:: geos.pygeos_tools.mesh_interpolation
20-
:members:
16+
**The python used to build GEOS with pygeosx will be the python to build the pygeos-tools.**
17+
Once the correct python is selected, you need to run in your virtual environment.
2118

22-
.. automodule:: geos.pygeos_tools.well_log
23-
:members:
19+
.. code-block:: console
2420
21+
python -m pip install ./pygeos-tools/
22+
23+
24+
.. toctree::
25+
:maxdepth: 1
26+
:caption: Contents
27+
28+
./pygeos_tools_docs/api.rst
29+
30+
./pygeos_tools_docs/acquisition_library.rst
31+
32+
./pygeos_tools_docs/input.rst
33+
34+
./pygeos_tools_docs/mesh.rst
35+
36+
./pygeos_tools_docs/model.rst
37+
38+
./pygeos_tools_docs/output.rst
39+
40+
./pygeos_tools_docs/solvers.rst
41+
42+
43+
.. toctree::
44+
:maxdepth: 1
45+
:caption: Example
46+
47+
./pygeos_tools_docs/example.rst

‎docs/pygeos_tools_docs/acquisition_library.rst

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Acquisition library
2+
===================
3+
4+
This package contain utilities for seismic acquisition.
5+
6+
7+
Acquisition
8+
-----------
9+
10+
.. automodule:: geos.pygeos_tools.acquisition_library.Acquisition
11+
:members:
12+
:undoc-members:
13+
:show-inheritance:
14+
15+
EquispacedAcquisition
16+
---------------------
17+
18+
.. automodule:: geos.pygeos_tools.acquisition_library.EquispacedAcquisition
19+
:members:
20+
:undoc-members:
21+
:show-inheritance:
22+
23+
SegyAcquisition
24+
---------------
25+
26+
.. automodule:: geos.pygeos_tools.acquisition_library.SegyAcquisition
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:
30+
31+
Shot
32+
----
33+
34+
.. automodule:: geos.pygeos_tools.acquisition_library.Shot
35+
:members:
36+
:undoc-members:
37+
:show-inheritance:

‎docs/pygeos_tools_docs/api.rst

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
API
2+
====
3+
4+
5+
Wrapper
6+
-------
7+
8+
.. automodule:: geos.pygeos_tools.wrapper
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
13+
File IO
14+
-------
15+
16+
.. automodule:: geos.pygeos_tools.file_io
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:
20+
21+
Mesh Interpolation
22+
------------------
23+
24+
.. automodule:: geos.pygeos_tools.mesh_interpolation
25+
:members:
26+
:undoc-members:
27+
:show-inheritance:
28+
29+
Well Log
30+
--------
31+
32+
.. automodule:: geos.pygeos_tools.well_log
33+
:members:
34+
:undoc-members:
35+
:show-inheritance:

‎docs/pygeos_tools_docs/example.rst

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
#################################################################################
2+
Driving a reservoir simulation with Pygeos
3+
#################################################################################
4+
5+
6+
**Context**
7+
8+
In this example, we will use pygeos to control a CompositionalMultiphaseFVM solver throughout a GEOS simulation.
9+
The goal is to reproduce the same results as if the simulation was launched directly through the XML file.
10+
11+
For the rest of this example, every part highlighting Python snippets will represent what is used to control pygeos and
12+
how it is linked to the XML file.
13+
14+
The example python script for this documentation is the following:
15+
16+
.. code-block:: console
17+
18+
pygeos-tools/examples/solvers/reservoir_modeling.py
19+
20+
21+
------------------------------------------------------------------
22+
XML file and initialization of Solver object
23+
------------------------------------------------------------------
24+
25+
26+
The xml input file for the test case is located at:
27+
28+
.. code-block:: console
29+
30+
/path/to/your/GEOS/src/inputFiles/compositionalMultiphaseFlow/2ph_cap_1d_ihu.xml
31+
32+
33+
After setting up the MPI communication and parsing all the args, we can set the XML object that has parsed our XML file.
34+
35+
.. code-block:: python
36+
37+
xmlfile = args.xml
38+
xml = XML( xmlfile )
39+
40+
41+
**Solver**
42+
43+
The simulation is performed using the GEOS general-purpose multiphase flow solver.
44+
The solver can be found in the ``Solvers`` block.
45+
46+
.. code-block:: xml
47+
48+
<Solvers gravityVector="{0.38268, 0., -0.92388}">
49+
50+
<CompositionalMultiphaseFVM
51+
name="compflow"
52+
logLevel="1"
53+
discretization="fluidTPFA"
54+
targetRegions="{ Region1 }"
55+
temperature="297.15">
56+
57+
<NonlinearSolverParameters
58+
newtonTol="5e-4"
59+
lineSearchAction="None"
60+
newtonMaxIter="15"/>
61+
62+
<LinearSolverParameters
63+
directParallel="0"/>
64+
65+
</CompositionalMultiphaseFVM>
66+
67+
</Solvers>
68+
69+
70+
The important thing to note here is the solver type ``CompositionalMultiphaseFVM``.
71+
Because we are dealing with a flow solver, which is not coupled, we can use the ``ReservoirSolver`` class to pilot the simulation.
72+
73+
.. code-block:: python
74+
75+
solver = ReservoirSolver( "CompositionalMultiphaseFVM" )
76+
solver.initialize( rank=rank, xml=xml )
77+
solver.applyInitialConditions()
78+
79+
80+
**Events**
81+
82+
To trigger the timestepping of the solver and the different outputs to perform, the "Events" block is the following:
83+
84+
.. code-block:: xml
85+
86+
<Events
87+
maxTime="1.0368e8">
88+
89+
<PeriodicEvent
90+
name="outputs"
91+
timeFrequency="1.728e6"
92+
target="/Outputs/vtkOutput"/>
93+
94+
<PeriodicEvent
95+
name="solverApplications1"
96+
forceDt="1.728e6"
97+
target="/Solvers/compflow"/>
98+
99+
<PeriodicEvent
100+
name="restarts"
101+
timeFrequency="3e7"
102+
targetExactTimestep="0"
103+
target="/Outputs/restartOutput"/>
104+
105+
</Events>
106+
107+
108+
The first attribute to use is ``maxTime`` which will be the limit for the simulation.
109+
The ``solverApplications1`` event targets the ``CompositionalMultiphaseFVM`` solver that we are using.
110+
This block contains a ``forceDt`` attribute that will be used later to choose as the timestep of the simulation.
111+
112+
.. code-block:: python
113+
114+
solver.setDtFromTimeVariable( "forceDt" ) # solver.dt = 1.728e6
115+
solver.setMaxTime( solver.getTimeVariables()[ "maxTime" ] ) # solver.maxTime = 1.0368e8
116+
117+
118+
The "outputs" event triggers the output of the vtk files. The attribute "timeFrequency" has the same value as "forceDt"
119+
so we can use the same timestep for the solver and the outputs.
120+
To start, we will set the time to 0.0 and trigger one output of the vtk files.
121+
122+
.. code-block:: python
123+
124+
time = 0.0
125+
solver.outputVtk( time )
126+
127+
128+
------------------------------------------------------------------
129+
Iterations process and simulation end
130+
------------------------------------------------------------------
131+
132+
The iterative process organizes the execution of the solver at each timestep while not exceeding the maxTime of the simulation.
133+
Once done, the simulation is ended by calling the ``cleanup`` method.
134+
135+
.. code-block:: python
136+
137+
while time < solver.maxTime:
138+
solver.execute( time )
139+
solver.outputVtk( time )
140+
time += solver.dt
141+
solver.cleanup( time )
142+
143+
144+
More complex timestepping strategies can be implemented by modifying the timestep duration and the outputs.
145+
146+
147+
------------------------------------------------------------------
148+
How to run that script
149+
------------------------------------------------------------------
150+
151+
Using the same python used to build your GEOS installation with, run this command:
152+
153+
.. code-block:: console
154+
155+
python pygeos-tools/examples/solvers/reservoir_modeling.py
156+
--xml /path/to/your/GEOS/src/inputFiles/compositionalMultiphaseFlow/2ph_cap_1d_ihu.xml
157+
158+
159+
------------------------------------------------------------------
160+
To go further
161+
------------------------------------------------------------------
162+
163+
164+
**Feedback on this example**
165+
166+
For any feedback on this example, please submit a `GitHub issue on the project's GitHub page <https://github.com/GEOS-DEV/geosPythonPackages/issues>`_.

‎docs/pygeos_tools_docs/input.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Input
2+
=====
3+
4+
This packages has utilities for handling the two principal arguments of GEOS:
5+
- the XML file that will be used to setup GEOS simulation
6+
- the Geos args which are -i input, partitions ...
7+
8+
9+
GeosxArgs
10+
---------
11+
12+
.. automodule:: geos.pygeos_tools.input.GeosxArgs
13+
:members:
14+
:undoc-members:
15+
:show-inheritance:
16+
17+
Xml
18+
---
19+
20+
.. automodule:: geos.pygeos_tools.input.Xml
21+
:members:
22+
:undoc-members:
23+
:show-inheritance:

‎docs/pygeos_tools_docs/mesh.rst

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Mesh
2+
====
3+
4+
This packages has utilities to handle the two different mesh formats to use in GEOS:
5+
- InternalMesh that is provided by GEOS
6+
- VtkMesh that is imported by GEOS
7+
8+
9+
InternalMesh
10+
------------
11+
12+
.. automodule:: geos.pygeos_tools.mesh.InternalMesh
13+
:members:
14+
:undoc-members:
15+
:show-inheritance:
16+
17+
VtkMesh
18+
-------
19+
20+
.. automodule:: geos.pygeos_tools.mesh.VtkMesh
21+
:members:
22+
:undoc-members:
23+
:show-inheritance:

‎docs/pygeos_tools_docs/model.rst

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Model
2+
=====
3+
4+
5+
pyevtk_tools
6+
------------
7+
8+
.. automodule:: geos.pygeos_tools.model.pyevtk_tools
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
13+
SepModel
14+
--------
15+
16+
.. automodule:: geos.pygeos_tools.model.SepModel
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:
20+
21+
VtkModel
22+
--------
23+
24+
.. automodule:: geos.pygeos_tools.model.VtkModel
25+
:members:
26+
:undoc-members:
27+
:show-inheritance:

0 commit comments

Comments
 (0)