PyCBG is a python module able to generate[CB-Geo MPM](https://github.com/cb-geo/mpm)'s input files.
PyCBG is a Python tool that should be helpful in running[CB-Geo MPM](https://github.com/cb-geo/mpm) simulations, either for generating expected input files at the preprocessing stage, or for postprocessing results.
Install PyCBG
=============
## From PyPI
`pycbg` can be installed using `pip` (the latter being itself installed on Debian-based systems with `sudo apt install python3-pip`) with different manners depending on the desired version.
The last upload of PyCBG on [PyPI](https://pypi.org/) can be simply installed using `pip`:
## Release version from PyPI
```
python3 -m pip install pycbg
The last release of PyCBG on [PyPI](https://pypi.org/) can be simply installed using:
```console
$python3 -m pip install pycbg
```
Installation automatically includes the following dependencies:
...
...
@@ -19,28 +21,82 @@ Installation automatically includes the following dependencies:
-`pandas`
-`matplotlib`
-`versioneer`
-`pyreadline`
-`sphinx` (at least version `3.3.1`)
-`sphinx_rtd_theme`
## Directly from the package
## Developer version
If you want to install a specific version of PyCBG (e.g. the most recent one), you can download the package and install it with `pip`.
If you want to install a specific version of PyCBG (e.g., the most recent one), you can download the sources for that specific version before running the installation.
If you have SSH access to the [ForgeMia](https://forgemia.inra.fr) GitLab instance of INRAE, you can download the sources in a read-write access with `git`:
or manually from the corresponding [ForgeMia repository](https://forgemia.inra.fr/mpm-at-recover/pycbg).
**Installing PyCBG**
From the root of the `pycbg` directory (the one you just downloaded), type the following command:
```console
$python3 -m pip install-e .
```
Command line usage
==================
While PyCBG is essentially a Python module, installation also provides a new Python executable `pycbg` (`pip` should automatically install it inside a directory in your `$PATH`) with all PyCBG features being already imported. The executable may serve to create a PyCBG interactive session, build the documentation or get PyCBG's version.
Manage CG-Geo MPM simulations using PyCBG Python module
positional arguments:
PYCBG_SCRIPT pycbg script to be run. By default, the following import lines are added at the top of the file: `from pycbg.preprocessing import *`, `from pycbg.postprocessing import *`. To
deactivate this behaviour, use the -n (or --no-import) option
optional arguments:
-h, --help show this help message and exit
-v, --version print pycbg version
-i, --interactive run in an interactive IPython session. Using both the -i and -n options simply creates a IPython interactive session
-n, --no-import deactivates automatic import of pycbg when running PYCBG_SCRIPT
-d [BUILD_DIR], --build-doc [BUILD_DIR]
build pycbg's documentation in BUILD_DIR, its path being relative to the current working directory. If the directory already exists, it is removed without prompt before building
the doc. If BUILD_DIR isn't specified, it will be set to `${PWD}/pycbg_doc`. If -d and PYCBG_SCRIPT are specified, the documentation is build before running the script
```
python3 -m pip install -e .
## Usage
One can easily run a PyCBG script:
```console
$pycbg my_script.py
```
Or experiment with PyCBG's functions and classes:
```console
$pycbg -i
Python 3.9.7 (default, Sep 3 2021, 12:45:31)
Type 'copyright', 'credits' or 'license' for more information
IPython 8.0.1 -- An enhanced Interactive Python. Type '?' for help.
In [1]: mesh = Mesh(...)
```
## Get version
To get the installed version of PyCBG, simply run:
```console
$pycbg -v
v1.0.2+107.g3997bd9
```
Documentation
...
...
@@ -50,17 +106,19 @@ Documentation
The latest build of the documentation at [ReadTheDocs](https://readthedocs.org/) is available online [here](https://pycbg.readthedocs.io/en/latest/). If nothing appears under `Classes overview` left of your screen, please reload the page (this is probably a small bug on ReadTheDocs).
## Local build
## Local build using the command line
The documentation can also be built locally using `sphinx`. From the root of PyCBG, run the following command:
The documentation can also be built locally using `sphinx`:
```
sh build_doc.sh
pycbg -d
```
This will execute a bash script that builds the documentation in a folder named `pycbg_doc`, located in the same directory as pycbg.
The documentation can then be accesed by opening `pycbg_doc/_build/html/index.html` in your browser.
This will create a folder in the current working directory named `pycbg_doc` containing the built documentation.
It can then be accesed by opening `pycbg_doc/_build/html/index.html` in your browser.
The pycbg_doc folder name can be modified if necessary when executing the bash script:
The `pycbg_doc` folder name can be modified if necessary when executing the bash script:
```
sh build_doc.sh my_folder_name
pycbg -d my_folder_name
```
Note: In the background `pycbg -d` is equivalent to a bash execution of source file `build_doc.sh`.