Merge pull request #136 from TREX-CoE/readme

Readme
TREX-CoE · Jan 11, 2024 · e22b480 · e22b480
2 parents d1196d7 + 3689ba3
commit e22b480
Showing 1 changed file with 134 additions and 102 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
-
 # TREXIO
+
 <img src="https://trex-coe.eu/sites/default/files/styles/responsive_no_crop/public/2022-01/TREXIO%20Code.png" width=200>
 
 [![build](https://github.com/TREX-CoE/trexio/actions/workflows/actions.yml/badge.svg)](https://github.com/TREX-CoE/trexio/actions/workflows/actions.yml)
@@ -15,26 +15,96 @@ which enables fast read and write operations. It is compatible with a variety
 of platforms and has interfaces for the Fortran, Python, OCaml and Rust
 programming languages.
 
-## Distributing TREXIO with your code
+* [TREXIO](#trexio)
+   * [Installation](#installation)
+      * [Installation using a package manager](#installation-using-a-package-manager)
+         * [Debian/Ubuntu](#debianubuntu)
+         * [Conda](#conda)
+         * [Spack](#spack)
+         * [Guix](#guix)
+      * [Installation from source](#installation-from-source)
+         * [Minimal requirements (for users):](#minimal-requirements-for-users)
+         * [Recommended: Installation from the release tarball](#recommended-installation-from-the-release-tarball)
+         * [Compilation without the HDF5 library](#compilation-without-the-hdf5-library)
+         * [For TREXIO developers: from the GitHub repo clone](#for-trexio-developers-from-the-github-repo-clone)
+         * [Using CMake instead of Autotools](#using-cmake-instead-of-autotools)
+   * [Using TREXIO](#using-trexio)
+      * [Naming convention](#naming-convention)
+      * [Tutorial](#tutorial)
+      * [Documentation](#documentation)
+      * [Linking to your program](#linking-to-your-program)
+      * [Distributing TREXIO with your code](#distributing-trexio-with-your-code)
+   * [APIs for other languages](#apis-for-other-languages)
+      * [Python](#python)
+      * [Rust](#rust)
+      * [OCaml](#ocaml)
+   * [Citation](#citation)
+      * [Miscellaneous](#miscellaneous)
+
+
+## Installation
+### Installation using a package manager
+#### Conda
 
-The TREXIO software is distributed under the 3-clause BSD license, renowned for
-its permissiveness. Consequently, it is entirely acceptable for you to
-provide the TREXIO release tarball in conjunction with your own code.
-Should you opt to include TREXIO with your software, it is recommended to
-distribute the release tarball, instead of the content of the git repository.
-The release tarballs contain pre-generated source files. This not only
-accelerates the compilation process but also significantly reduces dependency
-requirements.
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/trexio/badges/version.svg)](https://anaconda.org/conda-forge/trexio)
+[![Anaconda-Server Badge](https://anaconda.org/conda-forge/trexio/badges/platforms.svg)](https://anaconda.org/conda-forge/trexio)
+
+The official releases of TREXIO `>2.0.0` are also available via the `conda-forge` channel.
+The pre-compiled stable binaries of `trexio` can be installed as follows:
+
+```
+conda install -c conda-forge trexio
+```
+
+More details can be found in the corresponding [trexio-feedstock](https://github.com/conda-forge/trexio-feedstock).
+Note that both parallel (see `mpi_openmpi` prefix) and serial (`nompi`) variants are provided.
+
+#### Spack
+
+The official releases `>=2.0.0` and the development version of TREXIO can be installed using the
+[Spack](https://spack.io/) package manager.
+The [trexio/package.py](https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/trexio/package.py)
+file contains the Spack specifications required to build different variants of `trexio` library.
+It can be installed as follows
+
+```
+spack install --jobs `getconf _NPROCESSORS_ONLN` trexio
+```
+
+#### Guix
+
+The official releases of TREXIO `>=2.0.0` can be installed using the
+[GNU Guix](https://guix.gnu.org) functional package manager.
+The [trexio.scm](https://github.com/TREX-CoE/trexio/blob/master/tools/trexio.scm)
+Schema file contains the manifest specification for the `trexio` package.
+It can be installed as follows:
 
-## Minimal requirements (for users):
+```
+guix package --cores=`getconf _NPROCESSORS_ONLN` --install-from-file=trexio.scm
+```
+
+#### Debian/Ubuntu
+
+The official release of TREXIO `2.2.0` is available as a Debian (`.deb`) package thanks to the [Debichem Team](https://wiki.debian.org/Debichem).
+The source code is hosted [here](https://salsa.debian.org/debichem-team/libtrexio) and
+the pre-built binary files are available via the [Debian package registry](https://packages.debian.org/bookworm/libtrexio-dev).
+
+TREXIO is also available on [Ubuntu 23.04 (Lunar Lobster)](https://packages.ubuntu.com/lunar/libtrexio-dev) and newer and can be installed as follows:
+
+```
+sudo apt-get update && sudo apt-get install libtrexio-dev
+```
+
+### Installation from source
+#### Minimal requirements (for users):
 
 - Autotools             (autoconf >= 2.69, automake >= 1.11, libtool >= 2.2) or CMake (>= 3.16)
 - C compiler            (gcc/icc/clang)
 - Fortran compiler      (gfortran/ifort)
 - HDF5 library          (>= 1.8) [optional, recommended for high performance]
 
 
-## Installation procedure from the release tarball (for users):
+#### Recommended: Installation from the release tarball
 
 1. Download the `trexio-<version>.tar.gz` file from the GitHub release page
 2. `gzip -cd trexio-<version>.tar.gz | tar xvf -`
@@ -62,16 +132,25 @@ command. However, as TREXIO does not utilize MPI features, it is advisable to
 link against a non-MPI (serial) version of the HDF5 library for the sake of
 simplicity.
 
-## Additional requirements (for developers):
+#### Compilation without the HDF5 library
+
+By default, the configuration step proceeds to search for the [HDF5 library](https://portal.hdfgroup.org/display/HDF5/HDF5).
+This search can be disabled if HDF5 is not present/installable on the user machine.
+To build TREXIO without HDF5 back end, append `--without-hdf5` option to `configure` script or `-DENABLE_HDF5=OFF` option to `cmake`. For example,
+
+- `./configure --without-hdf5`
+- `cmake -S. -Bbuild -DENABLE_HDF5=OFF`
+
+#### For TREXIO developers: from the GitHub repo clone
+
+Additional requirements:
 
 - Python3       (>= 3.6)
 - Emacs         (>= 26.0)
 - SWIG          (>= 4.0)   [required for the Python API]
 
 **Note:** The source code is auto-generated from the Emacs org-mode (`.org`) files following the literate programming approach. This is why the `src` directory is initially empty.
 
-## Installation procedure from the GitHub repo clone (for developers):
-
 1. `git clone https://github.com/TREX-CoE/trexio.git`
 2. `cd trexio`
 3. `./autogen.sh`
@@ -80,7 +159,7 @@ simplicity.
 6. ```make -j 4 check```
 7. `sudo make install`
 
-## Installation procedure for CMake users (from the tarball or GitHub repo clone):
+#### Using CMake instead of Autotools
 
 The aforementioned instructions rely on [Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html) build system.
 [CMake](https://cmake.org) users can achieve the same with the following steps (an example of out-of-source build):
@@ -91,71 +170,46 @@ The aforementioned instructions rely on [Autotools](https://www.gnu.org/software
 4. ```ctest -j 4```
 5. `sudo make install`
 
-**Note: on systems with no `sudo` access, one can add `-DCMAKE_INSTALL_PREFIX=build` as an argument to the `cmake` command so that `make install/uninstall` can be run without `sudo` privileges.**
-
-**Note: when linking against an MPI-enabled HDF5 library one usually has to specify the MPI wrapper for the C compiler by adding, e.g., `-DCMAKE_C_COMPILER=mpicc` to the `cmake` command.**
-
-## Installation procedure for conda users
-
-[![Anaconda-Server Badge](https://anaconda.org/conda-forge/trexio/badges/version.svg)](https://anaconda.org/conda-forge/trexio)
-[![Anaconda-Server Badge](https://anaconda.org/conda-forge/trexio/badges/platforms.svg)](https://anaconda.org/conda-forge/trexio)
-
-The official releases of TREXIO `>2.0.0` are also available via the `conda-forge` channel.
-The pre-compiled stable binaries of `trexio` can be installed as follows:
-
-```
-conda install -c conda-forge trexio
-```
+**Note**: on systems with no `sudo` access, one can add `-DCMAKE_INSTALL_PREFIX=build` as an argument to the `cmake` command so that `make install/uninstall` can be run without `sudo` privileges.
 
-More details can be found in the corresponding [trexio-feedstock](https://github.com/conda-forge/trexio-feedstock).
-Note that both parallel (see `mpi_openmpi` prefix) and serial (`nompi`) variants are provided.
+**Note**: when linking against an MPI-enabled HDF5 library one usually has to specify the MPI wrapper for the C compiler by adding, e.g., `-DCMAKE_C_COMPILER=mpicc` to the `cmake` command.
 
-## Installation procedure for Guix users
+## Using TREXIO
+### Naming convention
 
-The official releases of TREXIO `>=2.0.0` can be installed using the
-[GNU Guix](https://guix.gnu.org) functional package manager.
-The [trexio.scm](https://github.com/TREX-CoE/trexio/blob/master/tools/trexio.scm)
-Schema file contains the manifest specification for the `trexio` package.
-It can be installed as follows:
+The primary TREXIO API is composed of the following functions:
 
-```
-guix package --cores=`getconf _NPROCESSORS_ONLN` --install-from-file=trexio.scm
-```
+- `trexio_open`
+- `trexio_write_[group]_[variable]`
+- `trexio_read_[group]_[variable]`
+- `trexio_has_[group]_[variable]`
+- `trexio_close`
 
-## Installation procedure for Spack users
+where `[group]` and `[variable]` substitutions correspond to the contents of the `trex.json` configuration file
+(for more details, see the corresponding [documentation](https://trex-coe.github.io/trexio/trex.html) page).
+For example, consider the `coord` variable (array), which belongs to the `nucleus` group. The TREXIO user can write or read it using `trexio_write_nucleus_coord` or `trexio_read_nucleus_coord` functions, respectively.
 
-The official releases `>=2.0.0` and the development version of TREXIO can be installed using the
-[Spack](https://spack.io/) package manager.
-The [trexio/package.py](https://github.com/spack/spack/blob/develop/var/spack/repos/builtin/packages/trexio/package.py)
-file contains the Spack specifications required to build different variants of `trexio` library.
-It can be installed as follows
+Note: the `[variable]` names have to be unique only within the corresponding parent `[group]`.
+There is no naming conflict when, for example, `num` variable exists both in the `nucleus` group (i.e. the number of nuclei) and in the `mo` group (i.e. the number of molecular orbitals).
+These quantities can be accessed using the corresponding `trexio_[has|read|write]_nucleus_num` and `trexio_[has|read|write]_mo_num`, respectively.
 
-```
-spack install --jobs `getconf _NPROCESSORS_ONLN` trexio
-```
 
-## Installation procedure for Debian/Ubuntu users
+### Tutorial
 
-The official release of TREXIO `2.2.0` is available as a Debian (`.deb`) package thanks to the [Debichem Team](https://wiki.debian.org/Debichem).
-The source code is hosted [here](https://salsa.debian.org/debichem-team/libtrexio) and 
-the pre-built binary files are available via the [Debian package registry](https://packages.debian.org/bookworm/libtrexio-dev).
+TREXIO tutorials in Jupyter notebook format can be found in the
+[corresponding GitHub repository](https://github.com/TREX-CoE/trexio-tutorials)
+or on [Binder](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD).
 
-TREXIO is also available on [Ubuntu 23.04 (Lunar Lobster)](https://packages.ubuntu.com/lunar/libtrexio-dev) and newer and can be installed as follows:
+For example, the tutorial covering TREXIO basics using benzene molecule as an example can be viewed and executed online by clicking on this badge:
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD?filepath=notebooks%2Ftutorial_benzene.ipynb)
 
-```
-sudo apt-get update && sudo apt-get install libtrexio-dev
-```
 
-## Compilation without the HDF5 library
+### Documentation
 
-By default, the configuration step proceeds to search for the [HDF5 library](https://portal.hdfgroup.org/display/HDF5/HDF5).
-This search can be disabled if HDF5 is not present/installable on the user machine.
-To build TREXIO without HDF5 back end, append `--without-hdf5` option to `configure` script or `-DENABLE_HDF5=OFF` option to `cmake`. For example,
+[Documentation generated from TREXIO org-mode files.](https://trex-coe.github.io/trexio/)
 
-- `./configure --without-hdf5`
-- `cmake -S. -Bbuild -DENABLE_HDF5=OFF`
 
-## Linking to your program
+### Linking to your program
 
 The `make install` command takes care of installing the TREXIO shared library on the user machine.
 After installation, append `-ltrexio` to the list of compiler  (`$LIBS`) options.
@@ -179,26 +233,19 @@ The `trexio_f.f90` module file can be found in the `include/` directory of the T
 Only the installed library and the Fortran module file are required.
 
 
-## Naming convention
-
-The primary TREXIO API is composed of the following functions:
-
-- `trexio_open`
-- `trexio_write_[group]_[variable]`
-- `trexio_read_[group]_[variable]`
-- `trexio_has_[group]_[variable]`
-- `trexio_close`
-
-where `[group]` and `[variable]` substitutions correspond to the contents of the `trex.json` configuration file
-(for more details, see the corresponding [documentation](https://trex-coe.github.io/trexio/trex.html) page).
-For example, consider the `coord` variable (array), which belongs to the `nucleus` group. The TREXIO user can write or read it using `trexio_write_nucleus_coord` or `trexio_read_nucleus_coord` functions, respectively.
-
-Note: the `[variable]` names have to be unique only within the corresponding parent `[group]`.
-There is no naming conflict when, for example, `num` variable exists both in the `nucleus` group (i.e. the number of nuclei) and in the `mo` group (i.e. the number of molecular orbitals).
-These quantities can be accessed using the corresponding `trexio_[has|read|write]_nucleus_num` and `trexio_[has|read|write]_mo_num`, respectively.
+### Distributing TREXIO with your code
 
+The TREXIO software is distributed under the 3-clause BSD license, renowned for
+its permissiveness. Consequently, it is entirely acceptable for you to
+provide the TREXIO release tarball in conjunction with your own code.
+Should you opt to include TREXIO with your software, it is recommended to
+distribute the release tarball, instead of the content of the git repository.
+The release tarballs contain pre-generated source files. This not only
+accelerates the compilation process but also significantly reduces dependency
+requirements.
 
-## Python API
+## APIs for other languages
+### Python
 
 [![PyPI version](https://badge.fury.io/py/trexio.svg)](https://badge.fury.io/py/trexio)
 
@@ -223,9 +270,9 @@ make python-test
 We highly recommend to use virtual environments to avoid compatibility issues and to improve reproducibility.
 
 
-## Rust API
+### Rust
 
-The Rust API is available on Crates.io, so you can simply run 
+The Rust API is available on Crates.io, so you can simply run
 ```
 cargo add trexio
 ```
@@ -236,7 +283,7 @@ If you prefer to install the Rust API provided with this repository:
 cargo add --path /path/to/trexio/rust/trexio
 ```
 
-## OCaml API
+### OCaml
 
 The TREXIO OCaml API is available in OPAM:
 ```
@@ -251,21 +298,6 @@ make
 opam install .
 ```
 
-## Tutorial
-
-TREXIO tutorials in Jupyter notebook format can be found in the
-[corresponding GitHub repository](https://github.com/TREX-CoE/trexio-tutorials)
-or on [Binder](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD).
-
-For example, the tutorial covering TREXIO basics using benzene molecule as an example can be viewed and executed online by clicking on this badge:
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD?filepath=notebooks%2Ftutorial_benzene.ipynb)
-
-
-## Documentation
-
-[Documentation generated from TREXIO org-mode files.](https://trex-coe.github.io/trexio/)
-
-
 ## Citation
 
 The journal article reference describing TREXIO can be cited as follows: