Input File Documentation

This page contains a guide to CREST input files that can be used with program versions >3.0.

CREST program instructions via the various command line arguments can become quite lengthy and tedious. Therefore, following version 3.0 of CREST, input files will be available. Currently, the input files are based on the TOML format and are parsed using TOML-F.

CREST input files can be loaded with the --input command

crest struc.xyz --input input.toml

or simply be given as the first argument (the file extension .toml is mandatory)

crest input.toml

where the input.toml would look something like this

# CREST 3 input file
input = "struc.xyz"   
runtype="ancopt"
threads = 9

[calculation]
elog="energies.log"

[[calculation.level]]
method = "gfn2"
uhf = 0
chrg = 0

As can be seen from this example, the file is hierarchically structured. At the top level, things like the input coord file name, runtype, and parallelization are specified. The calculation group (defined by [ ]) includes some settings about the internal calculation settings and printouts, while its level subgroup (defined by [[ ]]) provides the actual method and calculation information.

Some more input file example can be found here:

Go to Example Input Files

The documentation of blocks and keywords can be found in the following.

Hierarchical structure of CREST input files

1. General settings
2. [calculation] block
   1. [[calculation.level]] sub-blocks
   2. Per-level thread reservation
   3. [[calculation.constraints]] sub-blocks
3. [dynamics] block
   1. [[dynamics.meta]] sub-blocks
4. [cregen] block
5. [ttconf] block

General settings

These settings are not part of any block and can be specified at the beginning of an input file.

[calculation] block

The [calculation] block contains information on how to get energies and gradients for all other interfaces, i.e., specification on which programs to run and how to process the input/output data from a given list of [[calculation.level]] objects (see below ). This block also contains settings for optimizations.

[[calculation.level]] sub-blocks

The [[calculation.level]] sub-blocks contain actual information about employed levels of theory, the used programs, and system specific data such as the molecular charge or number of α and β electrons.

Per-level thread reservation

CREST 3.1

Most CREST workflows (conformational sampling, ensemble optimizations, metadynamics) run many jobs at the same time, each of which requires energies and gradients. By default, CREST assumes that a single energy+gradient call uses one core and distributes the global threads over as many concurrent jobs as possible.

This assumption breaks down for calculators that are themselves parallelized, such as ORCA subprocesses or ML potentials served by fmlip-relay. For those, the threads (or ncores) key can be set inside a [[calculation.level]] block to reserve a fixed number of cores for each call of that level:

# CREST 3 input file
input   = "struc.xyz"
runtype = "imtd-gc"
threads = 12                 # total cores available to CREST

[[calculation.level]]
method      = "orca"
orca_cmd    = "/path/to/orca"
orca_input  = "! r2scan-3c def2/J TightSCF DefGrid3"
threads     = 4              # cores per ORCA call -> %pal nprocs 4 end
orca_memory = 3000           # -> %maxcore 3000 (per core, MB)

With this input CREST will run at most 3 concurrent jobs with 4 cores each instead of 12 single-core jobs, and each of those jobs starts an ORCA calculation that is allowed to use exactly 4 cores. In general, the number of parallel jobs is capped such that

where \(N_\text{threads}^\text{level}\) is the largest threads value among all active levels. Two things are worth keeping in mind:

• Levels that hand the reservation down explicitly (orca via %pal, mlip via --max-threads) are hard-capped: they will use exactly that many cores. If the total thread count is not a multiple of the reservation, the remaining cores stay idle and CREST prints a corresponding **NOTE** at the start of the run. Other calculators (internal ones, xtb, generic scripts) instead grow into the cores per job via OMP_NUM_THREADS and thus soak up the remainder.
• If a single level requests more cores than are available in total, CREST warns and falls back to one job using all available cores.

Leaving the per-level threads unset (the default) reproduces the behavior of earlier CREST versions exactly.

[[calculation.constraints]] sub-blocks

The [[calculation.constraints]] sub-blocks are used to introduce constraints. Constraints are calculated by CREST and added to the energies and gradients.

[dynamics] block

The [dynamics] block is used to define basic settings for CRESTs standalone molecular dynamics and metadynamics module. Note, that some [calculation] must have been defined.

[[dynamics.meta]] sub-blocks

The [[dynamics.meta]] sub-block is used to define metadynamics parameters for a MD simulation in CREST. Multiple metadynamics potentials can be defined (as separate [[dynamics.meta]] sub-blocks) and added to the same MD ([dynamics] block).

[cregen] block

The [cregen] block is used for defining global options related to the ensemble sorting procedures. For more information on the CREGEN procedure see our recent publication in J Chem Phys.

[ttconf] block

CREST 3.1

The [ttconf] block controls the TTConf tensor-train conformer search (a reimplementation of the method of Zurek et al.), selected with runtype = "ttconf" (or the -ttconf command line flag). All keys are optional; a preset can be used as a starting point and any individual key overrides it. Every key except bonds has an equivalent command line flag (see the TTConf Options ), and command line flags override the values read from the file. A worked example is given on the TTConf example page.

Table of contents

• Example Input Files - Examples for CREST input files in the TOML format.