Create geos-utils package

README.md

@@ -19,33 +19,84 @@ Package summary
 
 The next packages are dedicated to pre- and post-process GEOS inputs/outputs. 
 
-    The following packages contain basic utilities used by the other ones:
-
-    * `geos-utils`: basic utilities
-    * `geos-geomecanics`: geomechanics functions and data model
-
-
-    The following packages define data models, vtk filters, and user-oriented API:
-
-    * `geos-xml-tools`: xml reader and writer dedicated to GEOS xml file
-    * `hdf5-wrapper`: wrapper to load hdf5 files
-    * `geos-mesh`: general mesh processing tools
-    * `geos-prep`: GEOS pre-processing tools
-    * `geos-posp`: GEOS post-processing tools
-
-
-    The following packages define hands-on executables that can be used through the command line:
-
-    * `mesh-doctor`: GEOS pre-processing application
-    * `time-history`: load and plot hdf5 files
-    * `geos-xml-viewer`: load GEOS xml file and display geometrical objects (mesh, boxes, wells)
-    * `geos-trame`: web interface to check, display objects, and edit GEOS xml file (see [Trame documentation](https://kitware.github.io/trame/guide/tutorial/))
-
-
-    The following package defines [Paraview](https://docs.paraview.org/) plugins that wrap GEOS Python tools
-
-    * `geos-pv`
-
+The following packages contain basic utilities used by the other ones:
+
+* `geos-utils`: basic utilities
+* `geos-geomecanics`: geomechanics functions and data model
+
+
+The following packages define data models, vtk filters, and user-oriented API:
+
+* `geos-xml-tools`: xml reader and writer dedicated to GEOS xml file
+* `hdf5-wrapper`: wrapper to load hdf5 files
+* `geos-mesh`: general mesh processing tools
+* `geos-prep`: GEOS pre-processing tools
+* `geos-posp`: GEOS post-processing tools
+
+
+The following packages define hands-on executables that can be used through the command line:
+
+* `mesh-doctor`: GEOS pre-processing application
+* `time-history`: load and plot hdf5 files
+* `geos-xml-viewer`: load GEOS xml file and display geometrical objects (mesh, boxes, wells)
+* `geos-trame`: web interface to check, display objects, and edit GEOS xml file (see [Trame documentation](https://kitware.github.io/trame/guide/tutorial/))
+
+
+The following package defines [Paraview](https://docs.paraview.org/) plugins that wrap GEOS Python tools
+
+* `geos-pv`
+
+GEOS Python packages dependency tree (inter-dependency and main external dependencies) is the following:
+
+```
+|-- geos-ats
+|-- pygeos-tools
+|-- geos-utils
+|-- geos-geomechanics
+|   |-- geos-utils
+|
+|-- hdf5-wrapper
+|   |-- h5py
+|
+|-- geos-xml-tools
+|   |-- lxml
+|
+|-- geos-mesh
+|   |-- geos-utils
+|   |-- vtk
+|
+|-- geos-prep
+|   |-- geos-mesh
+|   |-- geos-xml-tools
+|
+|-- geos-posp
+|   |-- geos-mesh
+|   |-- geos-geomechanics
+|
+|-- time-history
+|   |-- hdf5-wrapper
+|
+|-- mesh-doctor
+|   |-- geos-prep
+|   |-- pyvista
+|
+|-- geos-trame
+|   |-- geos-xml-tools
+|   |-- geos-mesh
+|   |-- pyvista
+|   |-- trame
+|
+|-- geos-xml-viewer
+|   |-- geos-xml-tools
+|   |-- geos-mesh
+|   |-- pyvista
+|
+|-- geos-pv
+    |-- geos-prep
+    |-- geos-posp
+    |-- geos-xml-tools
+    |-- paraview
+```
 
 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.
 
@@ -59,80 +110,25 @@ Installation
 
 * *Manual installation:*
 
-  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.
-
-    GEOS Python packages dependency tree (inter-dependency and main external dependencies) is the following:
-
-    ```
-    |-- geos-ats
-    |-- pygeos-tools
-    |-- geos-utils
-    |-- geos-geomechanics
-    |   |-- geos-utils
-    |
-    |-- hdf5-wrapper
-    |   |-- h5py
-    |
-    |-- geos-xml-tools
-    |   |-- lxml
-    |
-    |-- geos-mesh
-    |   |-- geos-utils
-    |   |-- vtk
-    |
-    |-- geos-prep
-    |   |-- geos-mesh
-    |   |-- geos-xml-tools
-    |
-    |-- geos-posp
-    |   |-- geos-mesh
-    |   |-- geos-geomechanics
-    |
-    |-- time-history
-    |   |-- hdf5-wrapper
-    |
-    |-- mesh-doctor
-    |   |-- geos-prep
-    |   |-- pyvista
-    |
-    |-- geos-trame
-    |   |-- geos-xml-tools
-    |   |-- geos-mesh
-    |   |-- pyvista
-    |   |-- trame
-    |
-    |-- geos-xml-viewer
-    |   |-- geos-xml-tools
-    |   |-- geos-mesh
-    |   |-- pyvista
-    |
-    |-- geos-pv
-        |-- geos-prep
-        |-- geos-posp
-        |-- geos-xml-tools
-        |-- paraview
-    ```
+  GEOS Python packages can be manually installed with pip using `python` >= 3.10. 
 
-    For the complete installation of GEOS pre- and post-processing packages, run the following commands from the geosPythonPackage directory:
+    To install any package, run the following commands from the geosPythonPackage directory:
 
     ```
     python -m venv .venv
     source .venv/bin/activate
     python -m pip install --upgrade pip
-    python -m pip install ./geos-utils
-    python -m pip install ./geos-geomechanics ./time-history ./geos-xml-tools ./geos-mesh
-    python -m pip install ./geos-prep ./geos-posp
-    python -m pip install ./time-history ./mesh-doctor ./geos-xml-viewer ./mesh-doctor
+    python -m pip install ./<PACKAGE_NAME>
     ```
 
-    You can test the installation by running the commands:
+    You can test installed package by running the commands:
 
     ```
     python -m pip install pytest
-    python -m pytest ./*
+    python -m pytest ./<PACKAGE_NAME>
     ```
 
-**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)).**
+**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)).**
 
 
 Contributions
@@ -150,6 +146,46 @@ If you would like to contribute to GEOS Python packages, please respect the foll
 
 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.
 
+Any new package must have the following architecture:
+
+```
+package-name
+|-- pyproject.toml
+|-- setup.py
+|-- src
+|   |-- geos
+|       |-- package_name
+|           |-- file1.py
+|           |-- file1.py
+|-- tests
+    |-- test1.py
+    |-- test2.py
+```
+
+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):
+
+* in the *package1/pyproject.py*, replace the tag `dependencies = ["external_packageX", "external_packageY",]` with `dynamic = ["dependencies"]`
+* create the *package1/setup.py* file
+* copy the following lines in the *setup.py* and update the dependencies
+  ```
+  from pathlib import Path
+  from setuptools import setup
+
+  # This is where you add any fancy path resolution to the local lib:
+  package_name = "geos-utils"
+  geos_utils_path: str = (Path(__file__).parent.parent / package_name).as_uri()
+
+  setup(
+      install_requires=[
+          "vtk >= 9.3",
+          "numpy >= 1.26",
+          "pandas >= 2.2",
+          "typing_extensions >= 4.12",
+          f"{package_name} @ {geos_utils_path}",
+      ]
+  )
+  ```
+
 
 Release
 -------

docs/conf.py

@@ -17,8 +17,8 @@
 
 # Add python modules to be documented
 python_root = '..'
-python_modules = ( 'geos-ats', 'geos-mesh', 'geos-posp', 'geos-timehistory', 'geos-xml-tools', 'hdf5-wrapper',
-                   'pygeos-tools' )
+python_modules = ( 'geos-ats', 'geos-mesh', 'geos-posp', 'geos-timehistory', 'geos-utils', 'geos-xml-tools', 
+                   'hdf5-wrapper', 'pygeos-tools' )
 for m in python_modules:
     sys.path.insert( 0, os.path.abspath( os.path.join( python_root, m, 'src' ) ) )
 
@@ -72,7 +72,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = [ u'_build', 'Thumbs.db', '.DS_Store', 'cmake/*' ]
+exclude_patterns = [ u'_build', 'Thumbs.db', '.DS_Store', 'cmake/*', '' ]
 
 todo_include_todos = True
 

docs/geos-posp.rst

@@ -5,8 +5,8 @@ GEOS Post-Processing tools
    :maxdepth: 5
    :caption: Contents:
 
-   ./posp_rst/home.rst
+   ./geos_posp_docs/home.rst
 
-   ./posp_rst/modules.rst
+   ./geos_posp_docs/modules.rst
 
-   ./posp_rst/visualization.rst
+   ./geos_posp_docs/visualization.rst

docs/geos-utils.rst

@@ -0,0 +1,73 @@
+
+GEOS Utilities
+===============
+
+The `geos-utils` python package defines utilities for all GEOS python packages including a logger, GEOS constants, basic functions, and unit management tools.
+
+
+API
+^^^
+
+geos.utils.ConnectionSet module
+--------------------------------
+
+.. automodule:: geos.utils.ConnectionSet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.enumUnits module
+--------------------------------
+
+.. automodule:: geos.utils.enumUnits
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.geometryFunctions module
+------------------------------------
+
+.. automodule:: geos.utils.geometryFunctions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.GeosOutputsConstants module
+-------------------------------------------
+
+.. automodule:: geos.utils.GeosOutputsConstants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.algebraFunctions module
+-------------------------------------------
+
+.. automodule:: geos.utils.algebraFunctions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.Logger module
+------------------------------
+
+.. automodule:: geos.utils.Logger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.PhysicalConstants module
+-----------------------------------------
+
+.. automodule:: geos.utils.PhysicalConstants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+geos.utils.UnitRepository module
+-------------------------------------
+
+.. automodule:: geos.utils.UnitRepository
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/posp_rst/modules.rst → docs/geos_posp_docs/modules.rst

@@ -11,5 +11,3 @@ Processing
    processing
 
    pyvistaTools
-
-   utils

docs/posp_rst/processing.rst → docs/geos_posp_docs/processing.rst

@@ -4,14 +4,6 @@ Processing functions
 This package define functions to process data.
 
 
-geos_posp.processing.ConnectionSet module
----------------------------------------------
-
-.. automodule:: geos_posp.processing.ConnectionSet
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 geos_posp.processing.geomechanicsCalculatorFunctions module
 ---------------------------------------------------------------
 
@@ -20,14 +12,6 @@ geos_posp.processing.geomechanicsCalculatorFunctions module
    :undoc-members:
    :show-inheritance:
 
-geos_posp.processing.geometryFunctions module
--------------------------------------------------
-
-.. automodule:: geos_posp.processing.geometryFunctions
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 geos_posp.processing.geosLogReaderFunctions module
 ------------------------------------------------------