mirror of
https://github.com/TREX-CoE/trexio.git
synced 2024-12-23 04:43:57 +01:00
Restructured README, and added TOC
This commit is contained in:
parent
9ac9ad1eb8
commit
4650e9ea7b
230
README.md
230
README.md
@ -1,5 +1,5 @@
|
|||||||
|
|
||||||
# TREXIO
|
# TREXIO
|
||||||
|
|
||||||
<img src="https://trex-coe.eu/sites/default/files/styles/responsive_no_crop/public/2022-01/TREXIO%20Code.png" width=200>
|
<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)
|
[![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
|
of platforms and has interfaces for the Fortran, Python, OCaml and Rust
|
||||||
programming languages.
|
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)
|
- Autotools (autoconf >= 2.69, automake >= 1.11, libtool >= 2.2) or CMake (>= 3.16)
|
||||||
- C compiler (gcc/icc/clang)
|
- C compiler (gcc/icc/clang)
|
||||||
@ -34,7 +104,7 @@ requirements.
|
|||||||
- HDF5 library (>= 1.8) [optional, recommended for high performance]
|
- 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
|
1. Download the `trexio-<version>.tar.gz` file from the GitHub release page
|
||||||
2. `gzip -cd trexio-<version>.tar.gz | tar xvf -`
|
2. `gzip -cd trexio-<version>.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
|
link against a non-MPI (serial) version of the HDF5 library for the sake of
|
||||||
simplicity.
|
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)
|
- Python3 (>= 3.6)
|
||||||
- Emacs (>= 26.0)
|
- 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.
|
**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`
|
1. `git clone https://github.com/TREX-CoE/trexio.git`
|
||||||
2. `cd trexio`
|
2. `cd trexio`
|
||||||
3. `./autogen.sh`
|
3. `./autogen.sh`
|
||||||
@ -80,7 +159,7 @@ simplicity.
|
|||||||
6. ```make -j 4 check```
|
6. ```make -j 4 check```
|
||||||
7. `sudo make install`
|
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.
|
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):
|
[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.**
|
**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)
|
The primary TREXIO API is composed of the following functions:
|
||||||
[![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.
|
- `trexio_open`
|
||||||
The pre-compiled stable binaries of `trexio` can be installed as follows:
|
- `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
|
||||||
conda install -c conda-forge trexio
|
(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: the `[variable]` names have to be unique only within the corresponding parent `[group]`.
|
||||||
Note that both parallel (see `mpi_openmpi` prefix) and serial (`nompi`) variants are provided.
|
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
|
### Tutorial
|
||||||
[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:
|
|
||||||
|
|
||||||
```
|
TREXIO tutorials in Jupyter notebook format can be found in the
|
||||||
guix package --cores=`getconf _NPROCESSORS_ONLN` --install-from-file=trexio.scm
|
[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
|
|
||||||
|
|
||||||
```
|
### Documentation
|
||||||
spack install --jobs `getconf _NPROCESSORS_ONLN` trexio
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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:
|
### Linking to your program
|
||||||
|
|
||||||
```
|
|
||||||
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
|
|
||||||
|
|
||||||
The `make install` command takes care of installing the TREXIO shared library on the user machine.
|
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.
|
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.
|
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`
|
## APIs for other languages
|
||||||
- `trexio_write_[group]_[variable]`
|
### Python
|
||||||
- `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
|
|
||||||
|
|
||||||
[![PyPI version](https://badge.fury.io/py/trexio.svg)](https://badge.fury.io/py/trexio)
|
[![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.
|
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
|
||||||
```
|
```
|
||||||
@ -236,7 +283,7 @@ If you prefer to install the Rust API provided with this repository:
|
|||||||
cargo add --path /path/to/trexio/rust/trexio
|
cargo add --path /path/to/trexio/rust/trexio
|
||||||
```
|
```
|
||||||
|
|
||||||
## OCaml API
|
### OCaml
|
||||||
|
|
||||||
The TREXIO OCaml API is available in OPAM:
|
The TREXIO OCaml API is available in OPAM:
|
||||||
```
|
```
|
||||||
@ -251,21 +298,6 @@ make
|
|||||||
opam install .
|
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
|
## Citation
|
||||||
|
|
||||||
The journal article reference describing TREXIO can be cited as follows:
|
The journal article reference describing TREXIO can be cited as follows:
|
||||||
|
Loading…
Reference in New Issue
Block a user