diff --git a/README.md b/README.md
index 626851f..1ed308f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
# TREXIO
+
[](https://github.com/TREX-CoE/trexio/actions/workflows/actions.yml)
@@ -15,18 +15,88 @@ 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 from a package](#installation-from-a-package)
+ * [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)
-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.
-## Minimal requirements (for users):
+## Installation
+### Installation from a package
+#### 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
+```
+
+#### Conda
+
+[](https://anaconda.org/conda-forge/trexio)
+[](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:
+
+```
+guix package --cores=`getconf _NPROCESSORS_ONLN` --install-from-file=trexio.scm
+```
+
+### 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)
@@ -34,7 +104,7 @@ requirements.
- 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-.tar.gz` file from the GitHub release page
2. `gzip -cd trexio-.tar.gz | tar xvf -`
@@ -62,7 +132,18 @@ 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)
@@ -70,8 +151,6 @@ simplicity.
**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):
@@ -95,67 +174,42 @@ The aforementioned instructions rely on [Autotools](https://www.gnu.org/software
**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
+## Using TREXIO
+### Naming convention
-[](https://anaconda.org/conda-forge/trexio)
-[](https://anaconda.org/conda-forge/trexio)
+The primary TREXIO API is composed of the following functions:
-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:
+- `trexio_open`
+- `trexio_write_[group]_[variable]`
+- `trexio_read_[group]_[variable]`
+- `trexio_has_[group]_[variable]`
+- `trexio_close`
-```
-conda install -c conda-forge trexio
-```
+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.
-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: 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.
-## Installation procedure for Guix users
-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:
+### Tutorial
-```
-guix package --cores=`getconf _NPROCESSORS_ONLN` --install-from-file=trexio.scm
-```
+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).
-## Installation procedure for Spack users
+For example, the tutorial covering TREXIO basics using benzene molecule as an example can be viewed and executed online by clicking on this badge:
+[](https://mybinder.org/v2/gh/TREX-CoE/trexio-tutorials/HEAD?filepath=notebooks%2Ftutorial_benzene.ipynb)
-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
-```
+### Documentation
-## Installation procedure for Debian/Ubuntu users
+[Documentation generated from TREXIO org-mode files.](https://trex-coe.github.io/trexio/)
-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
-```
-
-## 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`
-
-## 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
+### Distributing TREXIO with your code
-The primary TREXIO API is composed of the following functions:
+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.
-- `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.
-
-
-## Python API
+## APIs for other languages
+### Python
[](https://badge.fury.io/py/trexio)
@@ -223,7 +270,7 @@ 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
```
@@ -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:
-[](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: