mirror of
https://github.com/TREX-CoE/trexio.git
synced 2024-08-24 22:21:43 +02:00
better README + Binder badge
This commit is contained in:
parent
7c0b7a36ba
commit
71f4006987
@ -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).
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user