TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-11-03 20:54:07 +01:00
Code Issues Projects Releases Wiki Activity

better README + Binder badge

Browse Source
This commit is contained in:
q-posev 2021-09-13 17:21:34 +02:00
parent 7c0b7a36ba
commit 71f4006987
1 changed files with 21 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
python/README.md
View File

@ -1,3 +1,6 @@
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD)
# TREXIO Python API
TREXIO provides a Python API, which enables interactive calls to the library.
@ -14,9 +17,15 @@ can be used to convert data from one input/output file format into another.
## Installation from PyPI
Run `pip3 install trexio`
In short, you can run the following command:
**Note: we highly recommend to use virtual environments to avoid compatibility issues.**
`pip install trexio`
However, it is good practice to first check for updates of the build-system packages. This can be achieved by running
`python3 -m pip install --upgrade pip setuptools wheel`
**Note: we highly recommend to use virtual environments to avoid compatibility issues and to improve reproducibility.**
For more details, see the corresponding part of the [Python documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments).
@ -28,30 +37,31 @@ For more details, see the corresponding part of the [Python documentation](https
## Installation from source
1. Download the latest source code distribution (in `.tar.gz` format) of the TREXIO Python API
2. Unpack and `cd` in the output directory
3. Run `pip3 install -r requirements.txt` (this installs all required python dependencies)
4. Export custom environment variables needed for the installation following the procedure below and replacing `/path/to/hdf5/` with your paths.
1. Download the `trexio-<version>.tar.gz` file with the latest Python API
2. `gzip -cd trexio-<version>.tar.gz | tar xvf -`
3. `cd trexio-<version>`
4. `pip3 install -r requirements.txt` (this installs all required python dependencies)
5. Export custom environment variables needed for the installation following the procedure below and replacing `/path/to/hdf5/` with your paths.
Steps (i) and (ii) can be skipped if HDF5 is properly configured for `pkg-config` (i.e. if executing `pkg-config --libs hdf5` returns a list of options).
1. `export H5_CFLAGS=-I/path/to/hdf5/include`
2. `export H5_LDFLAGS=-L/path/to/hdf5/lib`
3. `source tools/set_NUMPY_INCLUDEDIR.sh`
5. Run `pip3 install .` (this installs `trexio` in your environment)
6. Run `cd test && python3 test_api.py` (this executes several tests that verify the installation)
6. `pip3 install .` (this installs `trexio` in your environment)
7. `cd test && python3 test_api.py` (this executes several tests that verify the installation)
You are ready to go!
**Note:**
installation based on `pip` compiles its own C extension (shared library) called `pytrexio`.
This extension is built from the TREXIO source files coupled to the wrapper code generated by [SWIG](http://www.swig.org/).
The compiler options during such installation may differ from the ones used to compile the primary TREXIO API in C.
Furthermore, custom compiler flags provided to `./configure` or `make` are not applicable to the Python API.
The compiler options during this installation may differ from the ones used to compile the primary TREXIO API in C.
Furthermore, custom compiler flags provided to `./configure` or `make` are not applied to the Python API.
## Examples
An interactive Jupyter notebook called `tutorial_benzene.ipynb` is provided in the `examples` directory.
It demonstrates some basic use cases of the TREXIO library in general and of the Python API in particular.
The notebook can be lauched either locally (see [next section](#Running-the-notebook) for details) or using [pre-built environment on Binder](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD?filepath=notebooks%2Ftutorial_benzene.ipynb).
Jupyter can be installed using `pip install jupyter`. If you are not familiar with it, feel free to consult the [Jupyter documentation](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html).