Link Search Menu Expand Document

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 --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 = ""   
threads = 9


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. [[calculation.constraints]] sub-blocks
  3. [dynamics] block
    1. [[dynamics.meta]] sub-blocks

General settings

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

KeyValues / Description
Specify the atomic input coordinate file as a string
Specify an ensemble input file as a string
Specify the number of CPU threads to be used as an integer
bin, binary
Specify a xtb binary as a string. Used for legacy runtypes of CREST. For new integrations use the binary option within the [calculation.level] block.
Select the CREST runtype, specify as as string.
The possible values are:
  • none - do nothing
  • ancopt,optimize - optimize the input structure
  • ancopt_ensemble,optimize_ensemble - optimize the input ensemble, similar to the --mdopt function.
  • md,mtd,dynamics,metadynamics - perform a (meta)dynamics simulation.
  • mecp,mecp_search - MECP search algorithm
Activate/Deactivate pre-optimization.
Specify as boolean (true/false)
Activate/Deactivate topology checks.
Specify as boolean (true/false)

[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.

KeyValues / Description
Instruction on how to process energies and gradients. Can be specified as string or integer. Possible values are:
  • any integer > 0 - Select the respective [[calculation.level]] block (see below ) to be used (if multiple have been defined). By default the first one is taken.
  • mecp - Take the first two specified levels and average energy and gradients.
Specify a file as a string to which energies are logged, e.g., in each optimization step.
Activate/Deactivate the energy printout via elog.
Specify as boolean (true/false)
Select the Hessian update method for ANCOPT as a string. Note, that for regular optimizations with ANCOPT only BFGS works well.
  • bfgs - Use the default BFGS update
  • powell - Use the Powell update method
  • sr1 - Use the symmetric rank one (SR1) update method
  • bofill - Use the Bofill type update
  • schlegel - Use the Farkas-Schlegel type update

[[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.

KeyValues / Description
Specify the method or type of theory to be used in this calculation as a string. This will instruct CREST on the format of energies and gradients that shall be read. Possible values are:
  • xtb,gfn,gfn-xtb - Select GFNn-xTB method calculations performed via the xtb program
  • generic - Call a generic script. The script should process the coordinates that crest writes into a file and you must know how to obtain the gradient (see options gradtype and gradfile below)`
bin, binary
Select the program/binary/script name to be executed by CREST in order to generate energies and gradients. Can be a full path. Specify as a string.
Specify any arguments that are passed to the selected binary as a string. This must exclude arguments generated by CREST, such as the molecular charge for xtb calculations. Be careful not to abuse this option!
dir, calcspace
Specify the directory in which CREST shall perform this calculation as a string. Note, this is can be a relative OR absolute path to the directory.
chrg, charge
Specify the molecular charge as an integer.
Specify multiplicity information as an integer. For xtb calculations this number must be Δn = Nα - Nβ electrons.
Activate/Deactivate reading of bond orders for each singlepoint at the chosen level. Specify as boolean (true/false)
Activate/Deactivate reading of molecular dipole moments for each singlepoint at the chosen level. Specify as boolean (true/false)
Activate/Deactivate reading of the Cartesian gradient of the molecular dipole moments for each singlepoint at the chosen level. Specify as boolean (true/false)
Name the file from which each singlepoint in the generic method interface obtains the energy and gradient information. Specify as string
Name the gradient file format for each singlepoint in the generic method interface. Specify as string. Available options are:
  • engrad - the .engrad format used by e.g. xtb and ORCA.

[[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.

KeyValues / Description
bond, bonds
Introduce automatic bond constraints either as a string keyword, or with a mixed-type list. Available values are:
  • all - put a constraint on all (automatically identified) bonds
Define a spherical wall potential around the system. The argument is a list of reals of the format [ a, b, c], where a is the potential prefactor, b is the exponent, and c is the radius (in atomic units, i.e., Bohr).
Define a spherical logfermi-type wall potential around the system. The argument is a list of reals of the format [ a, b, c], where a is the logfermi temperature in K, b is the exponent factor, and c is the sphere radius (in atomic units, i.e., Bohr).
Introduce a simple constraint to the gap between two potentials ([[calculation.level]] objects) in the MECP mode. The argument is a list of reals of the format [ σ, α], where σ is a potential prefactor and α is a confinement parameter.
mecp, gapfiff2
Introduce a modified constraint to the gap between two potentials ([[calculation.level]] objects) in the MECP mode. The argument is a list of reals of the format [ σ, α, c], where σ is a potential prefactor, α is a confinement parameter, and c is a shift in the exponential scaling function.

[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.

KeyValues / Description
Set the simulation length in ps. The argument is specified as a real.
Set the time step in fs. The argument is specified as a real.
Set the trajectory snapshot dump frequency in fs. The argument is specified as a real.
Set the hydrogen mass in amu. The argument is specified as a real. Increasing the hydrogen mass helps the simulation to run more stable.

[[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).

KeyValues / Description
Set the metadynamics type with regards to the employed collective variable. Specify the argument as a string. Available types are:
  • rmsd - Use the Cartesian RMSD between the snapshot and a reference structure list as collective variables.
Set the exponent of the Gaussian metadynamics potential. Specify as a real.
Set the Gaussian metadynamics potential prefactor in Eh. Specify as a real.
Specify the reference structure dump frequency for RMSD-based metadynamics in fs (or ps for dump_ps) as a real.

Table of contents

Back to top

Copyright © 2022-2024 Philipp Pracht.

CREST is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.