Skip to content

docs: Update README #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexbenedicto merged 4 commits into from
Oct 31, 2025
Merged

docs: Update README #160

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1751b9e
DBG
paloma-martinez Oct 2, 2025
355275b
Merge branch 'main' into docs/pmartinez/updateReadme
paloma-martinez Oct 29, 2025
1b5deec
More modifications
paloma-martinez Oct 29, 2025
80a0ae7
Fix typo
paloma-martinez Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 64 additions & 74 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,103 +3,94 @@
[![CI](https://github.com/GEOS-DEV/GEOS/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/GEOS-DEV/geosPythonPackages/actions?query=branch%3Adevelop)
[![docs](https://readthedocs.com/projects/geosx-geosx/badge/?version=latest)](https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/)

Welcome to the GEOS Python Package Repository!
==============================================
Welcome to the GEOS Python Package Repository !
===============================================

This repository contains a set of python packages that are used alongside [GEOS](https://github.com/GEOS-DEV/GEOS).
The `geosPythonPackages` repository contains a set of python tools that are used alongside [GEOS](https://github.com/GEOS-DEV/GEOS). They include testing tools, pre- and post-processing filters and plugins, as well as diverse executables. You will find below a brief description of the different packages, please refer to the [Python Tools documentation](https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/) for more details.


Package summary
---------------
Packages organization
---------------------

**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.**
> [!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 moved 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.
* Data structures and processing packages
* `geos-ats`: tools for managing integrated tests for GEOS.
* `pygeos-tools`: variety of tools for working with *pygeosx* objects.
* `geos-utils`: basic utilities
* `geos-geomechanics`: geomechanics functions and data model
* `geos-mesh`: generic mesh processing tools
* `hdf5-wrapper`: wrapper to load hdf5 files
* `geos-xml-tools`: xml reader and writer dedicated to GEOS xml file
* User-oriented API packages
* `geos-processing`: GEOS pre- and post-processing VTK filters
* `xml-vtk`: conversion of GEOS xml to VTK objects and conversely
* Hands-on executables that can be used through command line
* `mesh-doctor`: GEOS pre-processing mesh validation application
* `geos-timehistory`: load and plot hdf5 files
* `geos-trame`: web interface to check, display objects, and edit GEOS xml file (see [Trame documentation](https://kitware.github.io/trame/guide/tutorial/))
* Paraview plugins (see [Paraview](https://docs.paraview.org/) documentation)
* `geos-pv`: plugins that wrap GEOS Python tools

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`

GEOS Python packages dependency tree (inter-dependency and main external dependencies) is the following:

```
├── geos-ats
├── pygeos-tools
│ ├── geos-utils
│ ├── geos-xml-tools
│ ├── geos-mesh
│ ├── vtk
│ └── h5py
|
├── geos-utils
|
├── geos-geomechanics
│ └── geos-utils
|
├── geos-mesh
│ ├── geos-utils
│
│ └── vtk
|
├── hdf5-wrapper
│ ├── h5py
│
│ └── h5py
|
├── geos-xml-tools
│ ├── lxml
│
├── geos-mesh
│ ├── geos-utils
│ ├── vtk
│
├── geos-prep
│ └── lxml
|
├── geos-processing
│ ├── geos-mesh
│ ├── geos-xml-tools
│
├── geos-posp
│ └── geos-geomechanics
|
├── xml-vtk
│ ├── geos-mesh
│ ├── geos-geomechanics
│
├── time-history
│ ├── hdf5-wrapper
| └── geos-xml-tools
│
├── geos-timehistory
│ └── hdf5-wrapper
|
├── mesh-doctor
│ ├── geos-prep
│ ├── pyvista
│
│ └── pyvista
|
├── geos-trame
│ ├── geos-xml-tools
│ ├── geos-mesh
│ ├── pyvista
│ ├── trame
│ └── trame
│
├── geos-xml-viewer
│ ├── geos-xml-tools
│ ├── geos-mesh
│ ├── pyvista
│
├── geos-pv
├── geos-prep
├── geos-posp
└── geos-pv
├── geos-processing
├── geos-mesh
├── geos-geomechanics
├── geos-utils
├── geos-xml-tools
├── paraview
└── 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.


Installation
-------------
Expand All @@ -112,8 +103,7 @@ Installation

GEOS Python packages can be manually installed with pip using `python` >= 3.10.

To install any package, 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
Expand All @@ -122,16 +112,16 @@ Installation
```

You can test installed package by running the commands:

```
python -m pip install pytest
python -m pytest ./<PACKAGE_NAME>
```

[!WARNING]
>[!WARNING]
Due to local package conflicts with `pip install`, it is recommended to use the `--upgrade` option when building packages, or to use the script `install_packages.sh` located at the root of the repository.
[!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/src/geos/pv/plugins` 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.13+, which is based on python 3.10+. Alternatively, plugins from `geos-pv/src/geos/pv/plugins` can be manually loaded into Paraview ([see documentation](https://docs.paraview.org/en/latest/ReferenceManual/pythonProgrammableFilter.html#python-algorithm)).


Contributions
Expand Down Expand Up @@ -180,8 +170,8 @@ dependencies = [
]
```

[!IMPORTANT]
geos-pv dependencies are managed using a `requirements.txt` (together with the `setup.py`) file where all internal (and external if needed) dependencies are present. It ensures that internal dependency paths are correctly set when plugins are manually loaded into Paraview.
>[!IMPORTANT]
`geos-pv` dependencies are managed using a `requirements.txt` (together with the `setup.py`) file where all internal (and external if needed) dependencies are present. It ensures that internal dependency paths are correctly set when plugins are manually loaded into Paraview.

Release
-------
Expand Down