TREXIO is an open-source file format and library developed for the storage and manipulation of data produced by quantum chemistry calculations. It is designed with the goal of providing a reliable and efficient method of storing and exchanging wave function parameters and matrix elements. The library consists of a front-end implemented in the C programming language and two different back-ends: a text back-end and a binary back-end utilizing the HDF5 library 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.
Below is the list of codes that adopted TREXIO for reading and/or writing single- and/or multi-reference wave functions:
| Software | Single-reference | Multi-reference |
|---|---|---|
| Quantum Package | Write/Read | Write/Read |
| PySCF | Write/Read | Write/Read |
| ElemCo.jl | Write/Read | Write/Read |
| VeloxChem | Write | --- |
| FHI-aims | Write | --- |
| CP2K | Write | --- |
| CHAMP | Read | Read |
| GammCor | Read | Read |
| ipie | Read | Read |
| moltui | Read | --- |
| TurboRVB | Read | --- |
| Spicy | Read | --- |
| QMC=Chem | Read | --- |
| QMCkl | Read | --- |
| Dirac | Write | --- |
| pymolpro | Write | --- |
| tblite | Write | --- |
- Installation
- Using TREXIO
- APIs for other languages
- Citation
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.
Note that both parallel (see mpi_openmpi prefix) and serial (nompi) variants are provided.
The official releases >=2.0.0 and the development version of TREXIO can be installed using the
Spack package manager.
The 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
The official releases of TREXIO >=2.0.0 can be installed using the
GNU Guix functional package manager.
The 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
The official releases of TREXIO >=2.5. can be used and installed via Nix.
This repository provides a Nix Flake, where tools/nix/trexio.nix provides the build specification.
You can inspect the flake or build the package with
nix flake show github:TREX-CoE/trexio
nix build github:TREX-CoE/trexio
TREXIO is also part of NixPkgs and can be used via that channel.
nix build nixpkgs#trexio
The official release of TREXIO 2.2.0 is available as a Debian (.deb) package thanks to the Debichem Team.
The source code is hosted here and
the pre-built binary files are available via the Debian package registry.
TREXIO is also available on Ubuntu 23.04 (Lunar Lobster) and newer and can be installed as follows:
sudo apt-get update && sudo apt-get install libtrexio-dev
- Autotools (autoconf >= 2.69, automake >= 1.11, libtool >= 2.2) or CMake (>= 3.19)
- C compiler (gcc/icc/clang)
- Fortran compiler (gfortran/ifort)
- HDF5 library (>= 1.8) [optional, recommended for high performance]
- Download the
trexio-<version>.tar.gzfile from the GitHub release page gzip -cd trexio-<version>.tar.gz | tar xvf -cd trexio-<version>./configuremake -j 4make -j $(nproc) checksudo make install
In environments where sudo access is unavailable, a common workaround for
executing make install/uninstall commands without requiring superuser
privileges involves a modification to the ./configure command.
This modification typically includes specifying an installation prefix within
the user's home directory to circumvent the need for system-wide installation
permissions. For instance, ./configure prefix=$HOME/.local can be employed,
where $HOME/.local is often recommended for user-space software installations.
However, this is merely a suggestion, and users are free to choose any suitable
directory as their installation prefix, depending on their specific
requirements and system configurations.
Regarding the integration with an MPI (Message Passing Interface) enabled HDF5
library, it's typical to specify the MPI compiler wrapper for the C compiler.
This is done by appending a directive like CC=mpicc to the ./configure
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.
Building the library on Windows is possible through CMake from the release tarball
(not in developer mode from repository). Use cmake -S. -Bbuild -GNinja -DTREXIO_FORTRAN=OFF and cmake --build build --target install, as well as any
other options. Tested with clang-cl, HDF5, and no Fortran.
By default, the configuration step proceeds to search for the HDF5 library.
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 -DTREXIO_USE_HDF5=OFF option to cmake. For example,
./configure --without-hdf5cmake -S. -Bbuild -DTREXIO_USE_HDF5=OFF
Additional requirements:
- Python3 (>= 3.8)
- Emacs (>= 26.0)
- SWIG (>= 4.0) [required for the Python API]
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.
git clone https://github.com/TREX-CoE/trexio.gitcd trexio./autogen.sh./configuremake -j 4make -j $(nproc) checksudo make install
The aforementioned instructions rely on Autotools build system. CMake users can achieve the same with the following steps (an example of out-of-source build):
cmake -S. -Bbuildcd buildmake -j 4ctest -j $(nproc)sudo make install
By default, CMake builds a shared TREXIO library. Pass
-DBUILD_SHARED_LIBS=OFF to build a static library instead.
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.
The primary TREXIO API is composed of the following functions:
trexio_opentrexio_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 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.
TREXIO tutorials in Jupyter notebook format can be found in the corresponding GitHub repository or on Binder.
For example, the tutorial covering TREXIO basics using benzene molecule as an example can be viewed and executed online by clicking on this badge:
If you generate TREXIO files in your own code, we recommend checking them with the TREXIO validator. It helps verify that the produced files are consistent with the TREXIO format and can catch missing or malformed data before the files are shared or used in production workflows.
Documentation generated from TREXIO org-mode files.
The make install command takes care of installing the TREXIO library on the user machine.
After installation, append -ltrexio to the list of compiler ($LIBS) options.
In some cases (e.g. when using custom installation prefix during configuration), the TREXIO library might end up installed in a directory, which is absent in the default $LD_LIBRARY_PATH.
In order to link the program against TREXIO, the search path can be modified as follows:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path_to_trexio>/lib
where the <path_to_trexio> has to be replaced by the prefix used during the installation.
For CMake projects, use the package configuration installed by TREXIO:
find_package(trexio CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE trexio::trexio)This will make CMake detect and use trexio-config.cmake, which also exposes TREXIO_WITH_HDF5,
TREXIO_HDF5_IS_PARALLEL, and TREXIO_WITH_FORTRAN so downstream projects can inspect the installed
TREXIO configuration when necessary. You will need to make sure the path to TREXIO CMake config files
and target files are included in environment variable CMAKE_PREFIX_PATH if it is not in the standard
locations.
Hint: Instead of leveraging trexio-config.cmake, downstream can also use their custom Find-module
file for package discovery. For example, one can create a FindTREXIO.cmake in their CMake module path,
and use find_package(TREXIO REQUIRED) (dropping CONFIG makes CMake use custom Find-module first if
it exists). However, this way is usually not as robust as leveraging upstream config files.
In Fortran applications, make sure that the trexio_f.f90 module file is included in the source tree.
You might have to manually copy it into your program source directory.
The trexio_f.f90 module file can be found in the include/ directory of the TREXIO source code distribution.
Note: there is no need to include trexio.h header file during compilation of Fortran programs.
Only the installed library and the Fortran module file are required.
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.
For more details regarding the installation and usage of the TREXIO Python API, see this page.
The instructions on that page are for installing the Python API on its own, with
pip, from the source distribution published on PyPI. That build compiles its
own copy of the TREXIO library, because a wheel cannot run configure.
The Python interface can also be built and installed together with the rest of
the library, in which case the extension module links against the libtrexio
built alongside it instead of compiling the sources a second time. It is off by
default; enable it with
./configure --enable-pythoncmake -S. -Bbuild -DTREXIO_PYTHON=ON
make then builds the extension with the other objects, and make install
installs a single trexio package under the installation prefix, in the
directory the interpreter uses for platform-specific packages — typically
$prefix/lib/python<X.Y>/site-packages or $prefix/lib64/...:
<prefix>/<site-packages>/trexio/__init__.py the API
<prefix>/<site-packages>/trexio/pytrexio.py the SWIG wrapper
<prefix>/<site-packages>/trexio/_pytrexio.so
<prefix>/<site-packages>/trexio/_version.py
So import trexio is all that is needed, and the wrapper is reachable as
trexio.pytrexio. Since the prefix is usually not on the default module search
path, add it to PYTHONPATH, or point the installation at the interpreter's own
directory:
./configure --enable-python pythondir=... pyexecdir=...cmake -S. -Bbuild -DTREXIO_PYTHON=ON -DTREXIO_INSTALL_PYTHONDIR=...
Building this way needs the Python development headers and NumPy. SWIG is needed only when the generated wrapper has to be regenerated, which is the case in a Git checkout but not in a release tarball, where it is shipped.
The older
make python-install
target is still available. It builds a wheel with pip and installs it into the
active Python environment, using the HDF5 flags that configure already found.
Note: this implies that SWIG is installed and available.
We rely on the pytest package for unit testing. It can be installed via pip install pytest. To test the installation, run
make python-test
We highly recommend to use virtual environments to avoid compatibility issues and to improve reproducibility.
The Rust API is available on Crates.io, so you can simply run
cargo add trexio
to your Rust project.
The TREXIO OCaml API is available in OPAM:
opam install trexio
The Haskell bindings are available at https://github.com/TREX-CoE/trexio-hs and published on Hackage https://hackage.haskell.org/package/trexio-hs.
cabal update
cabal install trexio-hs
The journal article reference describing TREXIO can be cited as follows:
@article{10.1063/5.0148161,
author = {Posenitskiy, Evgeny and Chilkuri, Vijay Gopal and Ammar, Abdallah and Hapka, Michał and Pernal, Katarzyna and Shinde, Ravindra and Landinez Borda, Edgar Josué and Filippi, Claudia and Nakano, Kosuke and Kohulák, Otto and Sorella, Sandro and de Oliveira Castro, Pablo and Jalby, William and Ríos, Pablo López and Alavi, Ali and Scemama, Anthony},
title = "{TREXIO: A file format and library for quantum chemistry}",
journal = {The Journal of Chemical Physics},
volume = {158},
number = {17},
year = {2023},
month = {05},
issn = {0021-9606},
doi = {10.1063/5.0148161},
url = {https://doi.org/10.1063/5.0148161},
note = {174801},
eprint = {https://pubs.aip.org/aip/jcp/article-pdf/doi/10.1063/5.0148161/17355866/174801\_1\_5.0148161.pdf},
}
Journal paper:
ArXiv paper:
The code should be compliant with the C99
CERT C coding standard.
This can be checked with the cppcheck tool.
If you loaded an HDF5 module and the configure script can't find the HDF5 library,
it is probably because the path to the HDF5 library is missing from your $LIBRARY_PATH
variable. It happens that when building the HDF5 modules, the system
administrators only append the path to the libraries to the $LD_LIBRARY_PATH
variable, but forget to append it also to $LIBRARY_PATH, which is required
for linking. A simple workaround for the user is to do
export LIBRARY_PATH=$LD_LIBRARY_PATH
before running configure, but it is preferable to inform the system administators
of the problem.
