diff --git a/README.md b/README.md index 4c5aaf2..74fda47 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ TREX library for efficient I/O. ## Minimal requirements (for users): -- Autotools (autoconf, automake, libtool) +- Autotools (autoconf >= 2.69, automake >= 1.11, libtool >= 2.2) - C compiler (gcc/icc/clang) - Fortran compiler (gfortran/ifort) - HDF5 library (>= 1.8) @@ -64,6 +64,11 @@ There is no naming conflict when, for example, `num` variable exists both in the These quantities can be accessed using the corresponding `trexio_[has|read|write]_nucleus_num` and `trexio_[has|read|write]_mo_num`, respectively. +## Python API + +For more details regarding the installation and usage of the TREXIO Python API, see [this page](python/README.md). + + ## Tutorial **TODO** diff --git a/python/.gitignore b/python/.gitignore index a4b23d2..f1c8046 100644 --- a/python/.gitignore +++ b/python/.gitignore @@ -1,6 +1,5 @@ AUTHORS LICENSE -README.md src/ build/ diff --git a/python/README.md b/python/README.md new file mode 100644 index 0000000..64fa49c --- /dev/null +++ b/python/README.md @@ -0,0 +1,65 @@ +## TREXIO Python API + +TREXIO provides a Python API for interactive calls to the library. +It allows to simplify interfacing between different codes and can +be used to convert between different input/output file formats. + + +### Requirements + +- python3 (>= 3.6) +- numpy +- C compiler (gcc/icc) + +- HDF5 library (when compiling from source) +- pkgconfig (when compiling from source ----------> TODO: CHECK THIS by installing wheels) + + +### Installation from PyPI + +Run `pip3 install trexio` + +**Note:** we highly recommend to use virtual environments to avoid compatibility issues. + + +### 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. Run `pip3 install .` (this install `trexio` in your environment) +5. Run `cd test && python3 test_api.py` (this executes several tests that check the installation) + +You are ready to go! + + +### Examples + +An interactive `Jupyter` notebook called `tutorial_benzene.ipynb` can be found in the `examples` directory or on Binder (TODO: link). +It's goal is to demonstrate some basic use cases of the `trexio` Python API. + + +#### Additional requirements to run Jupyter notebooks with TREXIO + +`Jupyter` can be installed using `pip install jupyter`. + +If you have installed `trexio` in the virtual environemnt called, e.g. `myvenv`, make sure to also install it as a kernel for `ipython` (requires `ipykernel` to be installed) by executing the following: + +`python3 -m ipykernel install --user --name=myvenv` + + +#### Running the notebook + +The example notebook can be launched using the following command + +`jupyter-notebook tutorial_benzene.ipynb` + +Once the notebook is open, make sure that your virtual environment is selected as the current kernel. +If this is not the case: + +1. Press the `Kernel` button in the navigation panel +2. In the output list of options select `Change kernel` +3. Find the name of your virtual environment (e.g. `myvenv`) in the list and select it + +That's it, you have activated the virtual environment and can now run the cells of the `tutorial_benzene.ipynb` notebook. + diff --git a/tools/prepare_python.sh b/tools/prepare_python.sh index 4808d15..be35d36 100755 --- a/tools/prepare_python.sh +++ b/tools/prepare_python.sh @@ -30,5 +30,5 @@ cp ${SRC}/*.h ${PYDIR}/src cp ${INCLUDIR}/trexio.h ${PYDIR}/src # Copy additional info -cp ${TREXIO_ROOT}/AUTHORS ${TREXIO_ROOT}/LICENSE ${TREXIO_ROOT}/README.md ${PYDIR} +cp ${TREXIO_ROOT}/AUTHORS ${TREXIO_ROOT}/LICENSE ${PYDIR}