TREX/trexio
1
0
Fork 0
mirror of https://github.com/TREX-CoE/trexio.git synced 2024-11-03 12:43:55 +01:00
Code Issues Projects Releases Wiki Activity

Merge pull request #136 from TREX-CoE/readme

Browse Source 
Readme
This commit is contained in:
Evgeny Posenitskiy 2024-01-11 16:02:09 +01:00 committed by GitHub
commit e22b4807c1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 134 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
README.md
View File

@ -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 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)
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 using a package manager
#### 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
```
#### 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) - 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):
@ -91,71 +170,46 @@ The aforementioned instructions rely on [Autotools](https://www.gnu.org/software
4. ```ctest -j 4``` 4. ```ctest -j 4```
5. `sudo make install` 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.
## 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,9 +270,9 @@ 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
``` ```
cargo add trexio 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 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: