mirror of
https://github.com/TREX-CoE/trexio.git
synced 2024-11-03 12:43:55 +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
|
||||
|
||||
<img src="https://trex-coe.eu/sites/default/files/styles/responsive_no_crop/public/2022-01/TREXIO%20Code.png" width=200>
|
||||
|
||||
[](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-<version>.tar.gz` file from the GitHub release page
|
||||
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
|
||||
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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user