<h1 align="center">CREST</h1> <h3 align="center">Conformer-Rotamer Ensemble Sampling Tool</h3> <div align="center">

</div>

CREST (abbreviated from Conformer-Rotamer Ensemble Sampling Tool) is a program for the automated exploration of the low-energy molecular chemical space. It functions as an OMP scheduler for calculations with efficient force-field and semiempirical quantum mechanical methods such as xTB, and provides a variety of capabilities for creation and analysis of structure ensembles.<br> See our recent publication in J. Chem. Phys. for a feature overview: https://doi.org/10.1063/5.0197592

Documentation

The CREST documentation with installation instructions and application examples is hosted at: <br>

</div>

Installation quick guide

There are multiple possible ways of installing CREST. Detailed build instructions can be found at https://crest-lab.github.io/crest-docs/page/installation.

[!WARNING]
For any installation make sure that you have correctly installed and sourced the xtb program before attempting any calculations with CREST. While xtb is technically not needed for the primary runtypes of CREST versions >3.0 thanks to an integration of tblite, some functionalities, like QCG, still require it!

Option 1: Precompiled binaries

The statically linked binaries can be found at the release page of this repository. The most recent program version is automatically build (both Meson/Intel and CMake/GNU) from the main branch and can be found at the continous release page, or directly download them here:

Simply unpack the binary and add it to your PATH variable.

tar -xf crest-gnu-12-ubuntu-latest.tar.xz

tar -xf crest-intel-2023.1.0-ubuntu-latest.tar.xz

The program should be directly executable.

Option 2: Conda

A conda-forge feedstock is maintained at https://github.com/conda-forge/crest-feedstock.

Installing CREST from the conda-forge channel can be done via:

conda install conda-forge::crest

The conda-forge distribution is based on a dynamically linked CMake/GNU build.

[!WARNING] When using OpenBLAS as shared library backend for the linear algebra in CREST, please set the system variable export OPENBLAS_NUM_THREADS=1, as there may be an ugly warning in the concurrent (nested) parallel code parts otherwise.

Option 3: Compiling from source

<h4>Tested builds</h4>

Working and tested builds of CREST (mostly on Ubuntu 20.04 LTS):

| Build System | Compiler | Linear Algebra Backend | Build type | Status | Note | |--------------|----------|------------------------|:--------------:|:----------:|:----:| | CMake 3.30.2 | GNU (gcc 14.1.0) | libopenblas 0.3.27 | dynamic | ✅ || | CMake 3.30.2 | GNU (gcc 12.3.0) | libopenblas-dev | static | ✅ | | | CMake 3.28.3 | Intel (ifort/icc 2021.9.0) | MKL static (oneAPI 2023.1) | dynamic | ⚠️ | OpenMP/MKL problem (#285) | | Meson 1.2.0 | Intel (ifort/icx 2023.1.0) | MKL static (oneAPI 2023.1) | static | ✅ | |

Generally, subprojects should be initialized for the default build options, which can be done by

git submodule init
git submodule update

For more information about builds including subprojects see here.

Some basic build instructions can be found in the following dropdown tabs:

<details open> <summary><h4><code>CMake</code> build</h4></summary>

Building CREST with CMake works with the following chain of commands (in this example with gfortran/gcc compilers):

export FC=gfortran CC=gcc
cmake -B _build

and then to build the CREST binary

make -C _build

Optionally, the build can be tested via

make test -C _build

The CMake build typically requires access to shared libraries of LAPACK and OpenMP. They must be present in the library paths at compile and runtime. Alternatively, a static build can be selected by using -DSTATICBUILD=true in the CMake setup step. The current static build with GNU compilers is available from the continous release page.

</details> <details> <summary><h4><code>meson</code> build</h4></summary>

For the setup an configuration of meson see also the meson setup page hosted at the xtb repository. The chain of commands to build CREST with meson is:

export FC=ifort CC=icc
meson setup _build --prefix=$PWD/_dist
meson install -C _build

The meson build of CREST is mainly focused on and tested with the Intel ifort/icc compilers. When using newer versions of Intel's oneAPI, replacing icc with icx should work. Please refrain from using ifx instead of ifort, however. When attempting to build with gfortran and gcc, add -Dla_backend=mkl to the meson setup command. Compatibility with the GNU compilers might be limited. We recommend the CMake build (see the corresponding section) in this instance.

By default the meson build will create a statically linked binary.

</details>

Citations

P. Pracht, F. Bohle, S. Grimme, Phys. Chem. Chem. Phys., 2020, 22, 7169-7192. DOI: 10.1039/C9CP06869D
S. Grimme, J. Chem. Theory Comput., 2019, 155, 2847-2862. DOI: 10.1021/acs.jctc.9b00143
P. Pracht, S. Grimme, Chem. Sci., 2021, 12, 6551-6568. DOI: 10.1039/d1sc00621e
P. Pracht, C.A. Bauer, S. Grimme, J. Comput. Chem., 2017, 38, 2618-2631. DOI: 10.1002/jcc.24922
S. Spicher, C. Plett, P. Pracht, A. Hansen, S. Grimme, J. Chem. Theory Comput., 2022, 18, 3174-3189. DOI: 10.1021/acs.jctc.2c00239
P. Pracht, C. Bannwarth, J. Chem. Theory Comput., 2022, 18 (10), 6370-6385. DOI: 10.1021/acs.jctc.2c00578
P. Pracht, S. Grimme, C. Bannwarth, F. Bohle, S. Ehlert, G. Feldmann, J. Gorges, M. Müller, T. Neudecker, C. Plett, S. Spicher, P. Steinbach, P. Wesołowski, F. Zeller, J. Chem. Phys., 2024, 160, 114110. DOI: 10.1063/5.0197592

<details> <summary><h4>BibTex entries</h4></summary>

@article{Pracht2020,
  author ="Pracht, Philipp and Bohle, Fabian and Grimme, Stefan",
  title  ="Automated exploration of the low-energy chemical space w

Crest

Install / Use

README