TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-10-02 06:21:05 +02:00
Code Issues Projects Releases Wiki Activity

better documentation

Browse Source
This commit is contained in:
q-posev 2021-09-12 12:27:08 +02:00
parent b1f1aee7ab
commit 97f1d3b723
2 changed files with 23 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
python/README.md
View File

@ -1,18 +1,18 @@
## TREXIO Python API
# TREXIO Python API
TREXIO provides a Python API, which enables interactive calls to the library.
It facilitates the development of interfaces between different codes and
can be used to convert data from one input/output file format into another.
### Requirements
## Requirements
- python3 (>= 3.6)
- numpy
- C compiler (gcc/icc)
### Installation from PyPI
## Installation from PyPI
Run `pip3 install trexio`
@ -20,18 +20,19 @@ Run `pip3 install trexio`
For more details, see the corresponding part of the [Python documentation](https://docs.python.org/3/library/venv.html#creating-virtual-environments).
### Additional requirements (for installation from source)
## Additional requirements (for installation from source)
- HDF5 library (>= 1.8)
- pkgconfig (TODO: CHECK THIS by installing wheels)
- pkgconfig (Python package)
### Installation from source
## 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 python dependencies)
4. Export custom environment variables needed for the installation. Steps 1 and 2 can be skipped if HDF5 is properly configured for `pkg-config` (i.e. if executing `pkg-config --libs hdf5` returns a list of options).
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.
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`
@ -40,8 +41,14 @@ For more details, see the corresponding part of the [Python documentation](https
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.
### Examples
## 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.
@ -49,14 +56,14 @@ It demonstrates some basic use cases of the TREXIO library in general and of the
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).
#### Running the notebook
### Running the notebook
The example notebook can be launched using the following command:
`jupyter notebook tutorial_benzene.ipynb`
#### Additional steps needed to run a custom virtual environment in Jupyter notebooks
### Additional steps needed to run a custom virtual environment in Jupyter notebooks
In some cases, it may happen that the Jupyter kernels in the activated virtual environment (e.g. `myvenv`) still point to the system-wide python binaries and not to the environment ones.
This will result in `ImportError` when importing `trexio` in the notebook cell. In order to avoid this, the `myvenv` has to be installed as an additional kernel.

7
python/install_pytrexio.sh
View File

@ -15,9 +15,12 @@ done
# check that both variables are set
if [[ -z ${H5_LDFLAGS_LOCAL} ]] || [[ -z ${H5_CFLAGS_LOCAL} ]]; then
echo "Paths to the HDF5 installation are not found. pkgconfig Python package will try to detect them."
if [[ -z ${H5_LDFLAGS} ]] || [[ -z ${H5_CFLAGS} ]]; then
echo "Paths to the HDF5 installation are not provided. pkgconfig will try to detect them."
else
echo "Using exported H5_LDFLAGS and H5_CFLAGS environment variables."
fi
else
# additional explicit export was needed on MacOS
export H5_LDFLAGS=${H5_LDFLAGS_LOCAL}
export H5_CFLAGS=${H5_CFLAGS_LOCAL}
fi