From 71f40069871cd121be4fce8581322f344f01f7fb Mon Sep 17 00:00:00 2001 From: q-posev Date: Mon, 13 Sep 2021 17:21:34 +0200 Subject: [PATCH] better README + Binder badge --- python/README.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/python/README.md b/python/README.md index 01d73a3..23bcc09 100644 --- a/python/README.md +++ b/python/README.md @@ -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-.tar.gz` file with the latest Python API +2. `gzip -cd trexio-.tar.gz | tar xvf -` +3. `cd trexio-` +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).