Skip to content

Commit 0d9fb62

Browse files
mlemayTTEmlemayTTE
authored
Update readme (#62)
1 parent c8663ab commit 0d9fb62

File tree

1 file changed

+159
-2
lines changed

1 file changed

+159
-2
lines changed

‎README.md

Lines changed: 159 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,165 @@
1+
[![DOI](https://zenodo.org/badge/131810578.svg)](https://zenodo.org/badge/latestdoi/131810578)
2+
[![codecov](https://codecov.io/github/GEOS-DEV/geosPythonPackages/graph/badge.svg?token=0VTEHPQG58)](https://codecov.io/github/GEOS-DEV/geosPythonPackages)
3+
[![CI](https://github.com/GEOS-DEV/GEOS/actions/workflows/ci_tests.yml/badge.svg)](https://github.com/GEOS-DEV/geosPythonPackages/actions?query=branch%3Adevelop)
4+
[![docs](https://readthedocs.com/projects/geosx-geosx/badge/?version=latest)](https://geosx-geosx.readthedocs-hosted.com/projects/geosx-geospythonpackages/en/latest/)
15

26
Welcome to the GEOS Python Package Repository!
3-
-----------------------------------------------
7+
==============================================
48

59
This repository contains a set of python packages that are used alongside [GEOS](https://github.com/GEOS-DEV/GEOS).
6-
They can be installed automatically by running "make geosx_python_tools" in the GEOS build directory, or can be installed manually with pip.
10+
11+
12+
Package summary
13+
---------------
14+
15+
**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.**
16+
17+
* `geos-ats` package includes tools for managing integrated tests for GEOS.
18+
* `pygeos-tools` package adds a variety of tools for working with *pygeosx* objects.
19+
20+
The next packages are dedicated to pre- and post-process GEOS inputs/outputs.
21+
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+
750
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.
851

52+
53+
Installation
54+
-------------
55+
56+
* *Automatic installation for GEOS developpers:*
57+
58+
GEOS Python packages can be automatically installed after having build GEOS by running `make geosx_python_tools` in the GEOS build directory.
59+
60+
* *Manual installation:*
61+
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+
```
115+
116+
For the complete installation of GEOS pre- and post-processing packages, run the following commands from the geosPythonPackage directory:
117+
118+
```
119+
python -m venv .venv
120+
source .venv/bin/activate
121+
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
126+
```
127+
128+
You can test the installation by running the commands:
129+
130+
```
131+
python -m pip install pytest
132+
python -m pytest ./*
133+
```
134+
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)).**
136+
137+
138+
Contributions
139+
-------------
140+
141+
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.
142+
143+
If you would like to report a bug, please submit an [issue](https://github.com/GEOS-DEV/geosPythonPackages/issues/new).
144+
145+
If you would like to contribute to GEOS Python packages, please respect the following guidelines:
146+
147+
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.
148+
1. Add your code trying to integrate into the current code architecture.
149+
1. Push the branch, open a new PR, and add reviewers
150+
151+
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.
152+
153+
154+
Release
155+
-------
156+
157+
For release details and restrictions, please read the [LICENSE](https://github.com/GEOS-DEV/LICENSE) file.
158+
159+
For copyrights, please read the [COPYRIGHT](https://github.com/GEOS-DEV/COPYRIGHT ) file.
160+
161+
For contributors, please read the [CONTRIBUTORS](https://github.com/GEOS-DEV/CONTRIBUTORS ) file.
162+
163+
For acknowledgements, please read the [ACKNOWLEDGEMENTS](https://github.com/GEOS-DEV/ACKNOWLEDGEMENTS ) file.
164+
165+
For notice, please read the [NOTICE](https://github.com/GEOS-DEV/NOTICE ) file.

0 commit comments

Comments
 (0)