add README file for the Python API

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**

python/.gitignore

@@ -1,6 +1,5 @@
 AUTHORS
 LICENSE
-README.md
 src/
 
 build/

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.
+

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}