From 4650e9ea7baf4541ddd762ae2dd0d8e168efb867 Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Wed, 13 Dec 2023 11:03:06 +0100 Subject: [PATCH 1/3] Restructured README, and added TOC --- README.md | 230 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 131 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index 626851f..1ed308f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ - # TREXIO + [![build](https://github.com/TREX-CoE/trexio/actions/workflows/actions.yml/badge.svg)](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 + +[![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: + +``` +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 -[![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 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: +[![Binder](https://mybinder.org/badge_logo.svg)](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 [![PyPI version](https://badge.fury.io/py/trexio.svg)](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: -[![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: From b91c1a853769254cc60365afbead263273761a60 Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Wed, 13 Dec 2023 11:04:40 +0100 Subject: [PATCH 2/3] Update README.md Bold text --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1ed308f..7dafbb4 100644 --- a/README.md +++ b/README.md @@ -170,9 +170,9 @@ 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**: 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.** +**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. ## Using TREXIO ### Naming convention From 3689ba33aca926f4f2d3e9cb5053276c7c552d4d Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Thu, 11 Jan 2024 14:56:00 +0100 Subject: [PATCH 3/3] Review --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 7dafbb4..1347d7f 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ programming languages. * [TREXIO](#trexio) * [Installation](#installation) - * [Installation from a package](#installation-from-a-package) + * [Installation using a package manager](#installation-using-a-package-manager) * [Debian/Ubuntu](#debianubuntu) * [Conda](#conda) * [Spack](#spack) @@ -43,19 +43,7 @@ programming languages. ## 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 -``` - +### Installation using a package manager #### Conda [![Anaconda-Server Badge](https://anaconda.org/conda-forge/trexio/badges/version.svg)](https://anaconda.org/conda-forge/trexio) @@ -95,6 +83,18 @@ It can be installed as follows: 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): @@ -272,7 +272,7 @@ We highly recommend to use virtual environments to avoid compatibility issues an ### 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 ```