Input File Documentation

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

CREST 3.0 preview

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 loosely based on the TOML format and we are planning on implementing a proper TOML parser at some point.

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

crest --input input.toml

where the input.toml would look something like this

input = "struc.xyz"
runtype="ancopt"
threads = 9

[calculation]
type = 1 
eprint = true
elog="energies.log"

[[calculation.level]]
method = "xtb"
binary = "xtb-6.5.0"
uhf = 0
flags = "--gfn 2 --grad"
dir = "s0"

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 xtb binary.

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

Note: Command line arguments that can be found in the Keyword Documentation will overwrite the settings read from CREST input files.

Hierarchical structure of CREST input files

General settings
[calculation] block
[dynamics] block
1. [[dynamics.meta]] sub-blocks

Important: The following lists are incomplete and will be expanded over time until the actual release of CREST 3.0

General settings

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

Key	Values / Description
`input`	Specify the atomic input coordinate file as a string
`input_ensemble`	Specify an ensemble input file as a string
`threads`	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.
`runtype`	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
`preopt`	Activate/Deactivate pre-optimization. Specify as boolean (`true`/`false`)
`topo`	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.

Key	Values / Description
`type`	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.
`elog`	Specify a file as a string to which energies are logged, e.g., in each optimization step.
`eprint`	Activate/Deactivate the energy printout via `elog`. Specify as boolean (`true`/`false`)
`hess_update`	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.

Key	Values / Description
`method`	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 `genericinp.xyz` 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.
`flags`	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.
`uhf`	Specify multiplicity information as an integer. For `xtb` calculations this number must be Δn = N_α - N_β electrons.
`rdwbo`	Activate/Deactivate reading of bond orders for each singlepoint at the chosen level. Specify as boolean (`true`/`false`)
`rddip`	Activate/Deactivate reading of molecular dipole moments for each singlepoint at the chosen level. Specify as boolean (`true`/`false`)
`dipgrad`	Activate/Deactivate reading of the Cartesian gradient of the molecular dipole moments for each singlepoint at the chosen level. Specify as boolean (`true`/`false`)
`gradfile`	Name the file from which each singlepoint in the `generic` method interface obtains the energy and gradient information. Specify as string
`gradtype`	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.mecp]]` sub-blocks

A special type of the [[calculation.level]] sub-block that is used only for the MECP screening workflow. Instead of setting up a single calculations, this block will set up two identical calculations that differ only with regards to their multiplicities (uhf parameter). Input arguments are identical to the [[calculation.level]] options but should not include any uhf or directory specifications.

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

Key	Values / 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
`sphere`	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).
`sphere_logfermi`	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).
`gapfiff`	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.

Key	Values / Description
`length`	Set the simulation length in ps. The argument is specified as a real.
`tstep`	Set the time step in fs. The argument is specified as a real.
`dump`	Set the trajectory snapshot dump frequency in fs. The argument is specified as a real.
`hmass`	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).

Key	Values / Description
`type`	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.
`alpha`	Set the exponent of the Gaussian metadynamics potential. Specify as a real.
`kpush`	Set the Gaussian metadynamics potential prefactor in E_h. Specify as a real.
`dump`,`dump_fs`, `dump_ps`	Specify the reference structure dump frequency for RMSD-based metadynamics in fs (or ps for `dump_ps`) as a real.

Input File Documentation

Hierarchical structure of CREST input files

General settings

[calculation] block

[[calculation.level]] sub-blocks

[[calculation.mecp]] sub-blocks

[[calculation.constraints]] sub-blocks

[dynamics] block

[[dynamics.meta]] sub-blocks