README.md

Welcome to the GEOS Python Package Repository!

This repository contains a set of python packages that are used alongside GEOS.

Package summary

WARNING: This repository is currently under refactoring to improve package organization, maintainability, and dependency management. The following describes the final package organisation. Some packages may still miss or contain code that will be move later.

• geos-ats package includes tools for managing integrated tests for GEOS.
• pygeos-tools package adds a variety of tools for working with pygeosx objects.

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`

See the documentation for additional details about the packages and how to use them.

Installation

• Automatic installation for GEOS developpers:

  GEOS Python packages can be automatically installed after having build GEOS by running make geosx_python_tools in the GEOS build directory.

• 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
  

  For the complete installation of GEOS pre- and post-processing packages, 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
  

  You can test the installation by running the commands:

  python -m pip install pytest
  python -m pytest ./*
  

NOTE: geos-pv package cannot be build alone, but together with Paraview (see Paraview compilation guide). 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).

Contributions

GEOS Python packages repository gathers python scripts from any GEOS developpers and users. Feel free to share any scripts that may benefit to the GEOS community.

If you would like to report a bug, please submit an issue.

If you would like to contribute to GEOS Python packages, please respect the following guidelines:

1. Create a new branch named from this template: [CONTRIBUTOR]/[TYPE]/[TITLE] where CONTRIBUTOR is the name of the contributor, TYPE is the type of contribution among 'feature', 'refactor', 'doc', 'ci', TITLE is a short title for the branch.
2. Add your code trying to integrate into the current code architecture.
3. Push the branch, open a new PR, and add reviewers

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.

Release

For release details and restrictions, please read the LICENSE file.

For copyrights, please read the COPYRIGHT file.

For contributors, please read the CONTRIBUTORS file.

For acknowledgements, please read the ACKNOWLEDGEMENTS file.

For notice, please read the NOTICE file.