Skip to content
Snippets Groups Projects
Commit 91fa38e9 authored by Jerome Duriez's avatar Jerome Duriez Committed by Sacha Duverger
Browse files

README update

parent 85e80684
No related branches found
No related tags found
No related merge requests found
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5179973.svg)](https://doi.org/10.5281/zenodo.5179973)
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.
**Downloading PyCBG**
You can download the package with `git`:
```
git clone git@forgemia.inra.fr:mpm-at-recover/pycbg.git
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`:
```console
$ git clone git@forgemia.inra.fr:mpm-at-recover/pycbg.git
```
Alternativly, you can download it manually from [ForgeMia](https://forgemia.inra.fr/mpm-at-recover/pycbg).
Without SSH access, you can download it from command line with
```console
$ git clone https://forgemia.inra.fr/mpm-at-recover/pycbg.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.
## Complete description
```console
$ pycbg -h
usage: pycbg [-h] [-v] [-i] [-n] [-d [BUILD_DIR]] [PYCBG_SCRIPT]
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`.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment