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 loosely 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
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.
Hierarchical structure of CREST input files
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:
|
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:
|
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.
|
[[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:
|
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:
|
[[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:
|
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:
|
alpha | Set the exponent of the Gaussian metadynamics potential. Specify as a real. |
kpush | Set the Gaussian metadynamics potential prefactor in Eh. 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. |