TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2025-01-05 11:00:30 +01: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. TREXIO provides a Python API, which enables interactive calls to the library.
It facilitates the development of interfaces between different codes and It facilitates the development of interfaces between different codes and
can be used to convert data from one input/output file format into another. can be used to convert data from one input/output file format into another.
### Requirements ## Requirements
- python3 (>= 3.6) - python3 (>= 3.6)
- numpy - numpy
- C compiler (gcc/icc) - C compiler (gcc/icc)
### Installation from PyPI ## Installation from PyPI
Run `pip3 install trexio` 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). 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) - 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 1. Download the latest source code distribution (in `.tar.gz` format) of the TREXIO Python API
2. Unpack and `cd` in the output directory 2. Unpack and `cd` in the output directory
3. Run `pip3 install -r requirements.txt` (this installs all python dependencies) 3. Run `pip3 install -r requirements.txt` (this installs all required 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). 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` 1. `export H5_CFLAGS=-I/path/to/hdf5/include`
2. `export H5_LDFLAGS=-L/path/to/hdf5/lib` 2. `export H5_LDFLAGS=-L/path/to/hdf5/lib`
3. `source tools/set_NUMPY_INCLUDEDIR.sh` 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! 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. 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. 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). 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: The example notebook can be launched using the following command:
`jupyter notebook tutorial_benzene.ipynb` `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. 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. 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 # check that both variables are set
if [[ -z ${H5_LDFLAGS_LOCAL} ]] || [[ -z ${H5_CFLAGS_LOCAL} ]]; then 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 else
# additional explicit export was needed on MacOS
export H5_LDFLAGS=${H5_LDFLAGS_LOCAL} export H5_LDFLAGS=${H5_LDFLAGS_LOCAL}
export H5_CFLAGS=${H5_CFLAGS_LOCAL} export H5_CFLAGS=${H5_CFLAGS_LOCAL}
fi fi