Skip to content

Commit 9a54df1

Browse files
mlemayTTEMartin LEMAY
mlemayTTE
and
Martin LEMAY
authored
Create geos-utils package (#64)
* Create geos-utils package and move files * Update doc geos-utils * harmonize package organization with existing packages * Create geos-utils package and move files * Update doc geos-utils * harmonize package organization with existing packages * Update geos-posp dependency to geos-utils * fix doc * Update installation doc * Update package dependency config instructions * Update doc requirements * update geos_posp import and doc * add pyvista in doc requirements * fix doc issues --------- Co-authored-by: Martin LEMAY <[email protected]>
1 parent 0d9fb62 commit 9a54df1

File tree

75 files changed

+385
-285
lines changed

Some content is hidden

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

75 files changed

+385
-285
lines changed

‎README.md

Lines changed: 124 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -19,33 +19,84 @@ Package summary
1919

2020
The next packages are dedicated to pre- and post-process GEOS inputs/outputs.
2121

22-
The following packages contain basic utilities used by the other ones:
23-
24-
* `geos-utils`: basic utilities
25-
* `geos-geomecanics`: geomechanics functions and data model
26-
27-
28-
The following packages define data models, vtk filters, and user-oriented API:
29-
30-
* `geos-xml-tools`: xml reader and writer dedicated to GEOS xml file
31-
* `hdf5-wrapper`: wrapper to load hdf5 files
32-
* `geos-mesh`: general mesh processing tools
33-
* `geos-prep`: GEOS pre-processing tools
34-
* `geos-posp`: GEOS post-processing tools
35-
36-
37-
The following packages define hands-on executables that can be used through the command line:
38-
39-
* `mesh-doctor`: GEOS pre-processing application
40-
* `time-history`: load and plot hdf5 files
41-
* `geos-xml-viewer`: load GEOS xml file and display geometrical objects (mesh, boxes, wells)
42-
* `geos-trame`: web interface to check, display objects, and edit GEOS xml file (see [Trame documentation](https://kitware.github.io/trame/guide/tutorial/))
43-
44-
45-
The following package defines [Paraview](https://docs.paraview.org/) plugins that wrap GEOS Python tools
46-
47-
* `geos-pv`
48-
22+
The following packages contain basic utilities used by the other ones:
23+
24+
* `geos-utils`: basic utilities
25+
* `geos-geomecanics`: geomechanics functions and data model
26+
27+
28+
The following packages define data models, vtk filters, and user-oriented API:
29+
30+
* `geos-xml-tools`: xml reader and writer dedicated to GEOS xml file
31+
* `hdf5-wrapper`: wrapper to load hdf5 files
32+
* `geos-mesh`: general mesh processing tools
33+
* `geos-prep`: GEOS pre-processing tools
34+
* `geos-posp`: GEOS post-processing tools
35+
36+
37+
The following packages define hands-on executables that can be used through the command line:
38+
39+
* `mesh-doctor`: GEOS pre-processing application
40+
* `time-history`: load and plot hdf5 files
41+
* `geos-xml-viewer`: load GEOS xml file and display geometrical objects (mesh, boxes, wells)
42+
* `geos-trame`: web interface to check, display objects, and edit GEOS xml file (see [Trame documentation](https://kitware.github.io/trame/guide/tutorial/))
43+
44+
45+
The following package defines [Paraview](https://docs.paraview.org/) plugins that wrap GEOS Python tools
46+
47+
* `geos-pv`
48+
49+
GEOS Python packages dependency tree (inter-dependency and main external dependencies) is the following:
50+
51+
```
52+
|-- geos-ats
53+
|-- pygeos-tools
54+
|-- geos-utils
55+
|-- geos-geomechanics
56+
| |-- geos-utils
57+
|
58+
|-- hdf5-wrapper
59+
| |-- h5py
60+
|
61+
|-- geos-xml-tools
62+
| |-- lxml
63+
|
64+
|-- geos-mesh
65+
| |-- geos-utils
66+
| |-- vtk
67+
|
68+
|-- geos-prep
69+
| |-- geos-mesh
70+
| |-- geos-xml-tools
71+
|
72+
|-- geos-posp
73+
| |-- geos-mesh
74+
| |-- geos-geomechanics
75+
|
76+
|-- time-history
77+
| |-- hdf5-wrapper
78+
|
79+
|-- mesh-doctor
80+
| |-- geos-prep
81+
| |-- pyvista
82+
|
83+
|-- geos-trame
84+
| |-- geos-xml-tools
85+
| |-- geos-mesh
86+
| |-- pyvista
87+
| |-- trame
88+
|
89+
|-- geos-xml-viewer
90+
| |-- geos-xml-tools
91+
| |-- geos-mesh
92+
| |-- pyvista
93+
|
94+
|-- geos-pv
95+
|-- geos-prep
96+
|-- geos-posp
97+
|-- geos-xml-tools
98+
|-- paraview
99+
```
49100

50101
See the [documentation](https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/) for additional details about the packages and how to use them.
51102

@@ -59,80 +110,25 @@ Installation
59110

60111
* *Manual installation:*
61112

62-
GEOS Python packages can be manually installed with pip using `python` >= 3.10. In this case, pay attention to package inter-dependencies. Start by installing the basic utilities, then the api and vtk filters, and finally the top level executables.
63-
64-
GEOS Python packages dependency tree (inter-dependency and main external dependencies) is the following:
65-
66-
```
67-
|-- geos-ats
68-
|-- pygeos-tools
69-
|-- geos-utils
70-
|-- geos-geomechanics
71-
| |-- geos-utils
72-
|
73-
|-- hdf5-wrapper
74-
| |-- h5py
75-
|
76-
|-- geos-xml-tools
77-
| |-- lxml
78-
|
79-
|-- geos-mesh
80-
| |-- geos-utils
81-
| |-- vtk
82-
|
83-
|-- geos-prep
84-
| |-- geos-mesh
85-
| |-- geos-xml-tools
86-
|
87-
|-- geos-posp
88-
| |-- geos-mesh
89-
| |-- geos-geomechanics
90-
|
91-
|-- time-history
92-
| |-- hdf5-wrapper
93-
|
94-
|-- mesh-doctor
95-
| |-- geos-prep
96-
| |-- pyvista
97-
|
98-
|-- geos-trame
99-
| |-- geos-xml-tools
100-
| |-- geos-mesh
101-
| |-- pyvista
102-
| |-- trame
103-
|
104-
|-- geos-xml-viewer
105-
| |-- geos-xml-tools
106-
| |-- geos-mesh
107-
| |-- pyvista
108-
|
109-
|-- geos-pv
110-
|-- geos-prep
111-
|-- geos-posp
112-
|-- geos-xml-tools
113-
|-- paraview
114-
```
113+
GEOS Python packages can be manually installed with pip using `python` >= 3.10.
115114

116-
For the complete installation of GEOS pre- and post-processing packages, run the following commands from the geosPythonPackage directory:
115+
To install any package, run the following commands from the geosPythonPackage directory:
117116

118117
```
119118
python -m venv .venv
120119
source .venv/bin/activate
121120
python -m pip install --upgrade pip
122-
python -m pip install ./geos-utils
123-
python -m pip install ./geos-geomechanics ./time-history ./geos-xml-tools ./geos-mesh
124-
python -m pip install ./geos-prep ./geos-posp
125-
python -m pip install ./time-history ./mesh-doctor ./geos-xml-viewer ./mesh-doctor
121+
python -m pip install ./<PACKAGE_NAME>
126122
```
127123
128-
You can test the installation by running the commands:
124+
You can test installed package by running the commands:
129125
130126
```
131127
python -m pip install pytest
132-
python -m pytest ./*
128+
python -m pytest ./<PACKAGE_NAME>
133129
```
134130
135-
**NOTE: geos-pv package cannot be build alone, but together with Paraview ([see Paraview compilation guide](https://gitlab.kitware.com/paraview/paraview/-/blob/master/Documentation/dev/build.md)). It is recommended to use Paraview v5.12+, which is based on python 3.10+. Alternatievly, plugins from geos-pv/PVplugins can be manually loaded into Paraview ([see documentation](https://docs.paraview.org/en/latest/ReferenceManual/pythonProgrammableFilter.html#python-algorithm)).**
131+
**NOTE: geos-pv package cannot be build alone, but together with Paraview ([see Paraview compilation guide](https://gitlab.kitware.com/paraview/paraview/-/blob/master/Documentation/dev/build.md)). It is recommended to use Paraview v5.12+, which is based on python 3.10+. Alternatively, plugins from geos-pv/PVplugins can be manually loaded into Paraview ([see documentation](https://docs.paraview.org/en/latest/ReferenceManual/pythonProgrammableFilter.html#python-algorithm)).**
136132
137133
138134
Contributions
@@ -150,6 +146,46 @@ If you would like to contribute to GEOS Python packages, please respect the foll
150146
151147
If you do not have the rights to push the code and open new PRs, consider opening a new issue to explain what you want to do and ask for the dev rights.
152148
149+
Any new package must have the following architecture:
150+
151+
```
152+
package-name
153+
|-- pyproject.toml
154+
|-- setup.py
155+
|-- src
156+
| |-- geos
157+
| |-- package_name
158+
| |-- file1.py
159+
| |-- file1.py
160+
|-- tests
161+
|-- test1.py
162+
|-- test2.py
163+
```
164+
165+
The *setup.py* file is optional. It is required if the package depends on another GEOS Python package located in the root directory. If you want a package1 to depend on package2, follow this [procedure](https://stackoverflow.com/questions/75159453/specifying-local-relative-dependency-in-pyproject-toml):
166+
167+
* in the *package1/pyproject.py*, replace the tag `dependencies = ["external_packageX", "external_packageY",]` with `dynamic = ["dependencies"]`
168+
* create the *package1/setup.py* file
169+
* copy the following lines in the *setup.py* and update the dependencies
170+
```
171+
from pathlib import Path
172+
from setuptools import setup
173+
174+
# This is where you add any fancy path resolution to the local lib:
175+
package_name = "geos-utils"
176+
geos_utils_path: str = (Path(__file__).parent.parent / package_name).as_uri()
177+
178+
setup(
179+
install_requires=[
180+
"vtk >= 9.3",
181+
"numpy >= 1.26",
182+
"pandas >= 2.2",
183+
"typing_extensions >= 4.12",
184+
f"{package_name} @ {geos_utils_path}",
185+
]
186+
)
187+
```
188+
153189
154190
Release
155191
-------

‎docs/conf.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@
1717

1818
# Add python modules to be documented
1919
python_root = '..'
20-
python_modules = ( 'geos-ats', 'geos-mesh', 'geos-posp', 'geos-timehistory', 'geos-xml-tools', 'hdf5-wrapper',
21-
'pygeos-tools' )
20+
python_modules = ( 'geos-ats', 'geos-mesh', 'geos-posp', 'geos-timehistory', 'geos-utils', 'geos-xml-tools',
21+
'hdf5-wrapper', 'pygeos-tools' )
2222
for m in python_modules:
2323
sys.path.insert( 0, os.path.abspath( os.path.join( python_root, m, 'src' ) ) )
2424

@@ -72,7 +72,7 @@
7272
# List of patterns, relative to source directory, that match files and
7373
# directories to ignore when looking for source files.
7474
# This pattern also affects html_static_path and html_extra_path .
75-
exclude_patterns = [ u'_build', 'Thumbs.db', '.DS_Store', 'cmake/*' ]
75+
exclude_patterns = [ u'_build', 'Thumbs.db', '.DS_Store', 'cmake/*', '' ]
7676

7777
todo_include_todos = True
7878

‎docs/geos-posp.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ GEOS Post-Processing tools
55
:maxdepth: 5
66
:caption: Contents:
77

8-
./posp_rst/home.rst
8+
./geos_posp_docs/home.rst
99

10-
./posp_rst/modules.rst
10+
./geos_posp_docs/modules.rst
1111

12-
./posp_rst/visualization.rst
12+
./geos_posp_docs/visualization.rst

‎docs/geos-utils.rst

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
2+
GEOS Utilities
3+
===============
4+
5+
The `geos-utils` python package defines utilities for all GEOS python packages including a logger, GEOS constants, basic functions, and unit management tools.
6+
7+
8+
API
9+
^^^
10+
11+
geos.utils.ConnectionSet module
12+
--------------------------------
13+
14+
.. automodule:: geos.utils.ConnectionSet
15+
:members:
16+
:undoc-members:
17+
:show-inheritance:
18+
19+
geos.utils.enumUnits module
20+
--------------------------------
21+
22+
.. automodule:: geos.utils.enumUnits
23+
:members:
24+
:undoc-members:
25+
:show-inheritance:
26+
27+
geos.utils.geometryFunctions module
28+
------------------------------------
29+
30+
.. automodule:: geos.utils.geometryFunctions
31+
:members:
32+
:undoc-members:
33+
:show-inheritance:
34+
35+
geos.utils.GeosOutputsConstants module
36+
-------------------------------------------
37+
38+
.. automodule:: geos.utils.GeosOutputsConstants
39+
:members:
40+
:undoc-members:
41+
:show-inheritance:
42+
43+
geos.utils.algebraFunctions module
44+
-------------------------------------------
45+
46+
.. automodule:: geos.utils.algebraFunctions
47+
:members:
48+
:undoc-members:
49+
:show-inheritance:
50+
51+
geos.utils.Logger module
52+
------------------------------
53+
54+
.. automodule:: geos.utils.Logger
55+
:members:
56+
:undoc-members:
57+
:show-inheritance:
58+
59+
geos.utils.PhysicalConstants module
60+
-----------------------------------------
61+
62+
.. automodule:: geos.utils.PhysicalConstants
63+
:members:
64+
:undoc-members:
65+
:show-inheritance:
66+
67+
geos.utils.UnitRepository module
68+
-------------------------------------
69+
70+
.. automodule:: geos.utils.UnitRepository
71+
:members:
72+
:undoc-members:
73+
:show-inheritance:

‎docs/posp_rst/PVplugins.rst renamed to ‎docs/geos_posp_docs/PVplugins.rst

File renamed without changes.

‎docs/posp_rst/filters.rst renamed to ‎docs/geos_posp_docs/filters.rst

File renamed without changes.

‎docs/posp_rst/home.rst renamed to ‎docs/geos_posp_docs/home.rst

File renamed without changes.

‎docs/posp_rst/modules.rst renamed to ‎docs/geos_posp_docs/modules.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,3 @@ Processing
1111
processing
1212

1313
pyvistaTools
14-
15-
utils

‎docs/posp_rst/processing.rst renamed to ‎docs/geos_posp_docs/processing.rst

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,6 @@ Processing functions
44
This package define functions to process data.
55

66

7-
geos_posp.processing.ConnectionSet module
8-
---------------------------------------------
9-
10-
.. automodule:: geos_posp.processing.ConnectionSet
11-
:members:
12-
:undoc-members:
13-
:show-inheritance:
14-
157
geos_posp.processing.geomechanicsCalculatorFunctions module
168
---------------------------------------------------------------
179

@@ -20,14 +12,6 @@ geos_posp.processing.geomechanicsCalculatorFunctions module
2012
:undoc-members:
2113
:show-inheritance:
2214

23-
geos_posp.processing.geometryFunctions module
24-
-------------------------------------------------
25-
26-
.. automodule:: geos_posp.processing.geometryFunctions
27-
:members:
28-
:undoc-members:
29-
:show-inheritance:
30-
3115
geos_posp.processing.geosLogReaderFunctions module
3216
------------------------------------------------------
3317

‎docs/posp_rst/pyvistaTools.rst renamed to ‎docs/geos_posp_docs/pyvistaTools.rst

File renamed without changes.

‎docs/posp_rst/readers.rst renamed to ‎docs/geos_posp_docs/readers.rst

File renamed without changes.

‎docs/posp_rst/visu.PVUtils.rst renamed to ‎docs/geos_posp_docs/visu.PVUtils.rst

File renamed without changes.

0 commit comments

Comments
 (0)