Command Line Keyword Documentation
This page contains the documentation of all available command line keywords for CREST. The command line arguments are grouped according to different functions. For the general command line usage see the parent page. This page specifies the [OPTIONS]. Required arguments will be marked with < >, optional arguments are marked by brackets [ ].
Table of contents
- General and Technical Options
- Runtype Options
- Ensemble Sorting Options
- Constraining Options
- Standalone Tools
- Quantum Cluster Growth (QCG) Options
- MSREACT mode Options
General and Technical Options
| Command | Description |
|---|---|
-h, --help | Print an overview of most available options (i.e., more or less this site completely). |
--version | Print only the program header and disclaimer. |
--cite | Print the most relevant CREST citations. |
-xnam <BIN> | Specify the name (and path) of the xtb binary that should be used as <BIN>. The [default] is xtb. |
--scratch <DIR> | Performs the entire calculation in the specified <DIR>. If <DIR> does not exist, it will be created. |
--niceprint | In-line progress bar printout for optimizations. |
--T <threads> | Specify the number of CPU <threads> that shall be used. CREST automatically adjusts the number of processes according to this variable in each step, in order to achieve optimal parallelization of the calculations. |
--dry | Perform a “dry” run, i.e., nothing is actually done but instead an overview of the settings that would be applied in the calculation is given. |
--input <INPUTFILE> | CREST 3.0 Specify a CREST input file from which the calculation settings are read. For more information see the Input File Documentation . |
--legacy | CREST 3.0 Attempt (where possible) to switch the program behavior back to previous program versions (<3.0). |
Runtype Options
The general runtype selection as specified in the following table will set the program into the respective runtype. Only one of these options can be selected!
| Runtype | Command | Description |
|---|---|---|
| Singlepoint energy and gradient evaluation | --sp | CREST 3.0 Standalone energy and gradient evaluation of the given input structure. |
| Geometry optimization | --opt [level],--ancopt [level] | CREST 3.0 Standalone geometry optimization of the given input structure via the ANCOPT algorithm. The optional [level] argument can be used to select predefined convergence criteria (see Table IV in https://doi.org/10.1063/5.0197592). |
| MF-MD-GC sampling (outdated) | --v1 | First generation of the GFNn-xTB driven conformational search algorithm, consisting out of mode following, molecular dynamics sampling and genetic structure crossing. This workflow is deprecated. |
| MTD-GC sampling (outdated) | --v2 | Second generation of the GFNn-xTB driven conformational search algorithm, consisting out of a metadynamics approach and genetic structure crossing. This workflow is deprecated. |
| iMTD-GC sampling | --v2i, --v3 | Iterative version of the MTD-GC workflow, which is the [default] runtype of CREST. See here. |
| iMTD-sMTD sampling | --v4 | Iterative workflow making use of static metadynamics simulations. See here. |
| Confromational Entropy Algorithm | --entropy | Specialized version of the iMTD-sMTD workflow, used in the calculation of conformational entropy. See here. |
| Protonation site sampling | --protonate | Workflow for sampling protonation sites. |
| Deprotonation site sampling | --deprotonate | Workflow for sampling protonation sites. This is related to the --protonate option. |
| Prototropic Tautomer sampling | --tautomerize | Workflow for sampling prototropic tautomers. This is related to the --protonate option. |
| CREGEN ensemble sorting routine | --cregen <FILE> | The standalone option for sorting an ensemble or a trajectory into conformers and rotamers. See below. |
| QCG tool | --qcg | Use the Quantum Cluster Growth functionalities. QCG has several individual runtypes. See QCG keywords. |
| MSREACT tool | --msreact | CREST 3.0 Use the mass spectral fragment generator. MSREACT has several individual runtypes. See MSREACT keywords. |
Level-of-Theory Options
These are the options related to the level of theory and settings for xtb through CREST.
| Command | Description |
|---|---|
| GFNn-xTB method selection | |
--gfn1 | Use GFN1-xTB |
--gfn2 | Use GFN2-xTB |
--gff, --gfnff | Use GFN-FF |
--gfn2//gfnff | Use the GFN2-xTB//GFN-FF composite method. Sampling and optimizations are done at GFN-FF level, which is appended by a GFN2-xTB singlepoint calculation. |
Charge and multiplicity selection | |
--chrg <INT> | Set molecular charge to <INT>. Only required if <INT>≠0. |
--uhf <INT> | Set the number of \(N_\alpha - N_\beta\) electrons. For example, <INT>=0 for the neutral S0 state, <INT>=2 for an S1 state, etc. Only required if <INT>≠0. |
Implicit solvation | |
--gbsa <SOLVENT> | Use the Generalized Born (GB) and solvent accessible surface area (SASA) model. For available <SOLVENT> options see the xtb documentation. The solvent input is not case-sensitive. |
--alpb <SOLVENT> | Use the ALPB model, an improved version of GBSA. For available <SOLVENT> options see the xtb documentation. The solvent input is not case-sensitive. |
Geometry optimization | |
--optlev <LEVEL> | Set the optimization accuracy for ANCOPT optimizations. In CREST’s multilevel approach, only the final geometry optimization is affected by this setting. For available <LEVEL> see the xtb documentation. The [default] is <LEVEL>=vtight. |
Molecular Dynamics and Metadynamics Options
The following options can be used to modify settings for the MD and MTD simulations during the conformational sampling.
| Command | Description |
|---|---|
--len <REAL>, --mdlen <REAL> | The length of the metadynamics simulations in CREST is usually determined automatically, but with this flag it can be set to <REAL> (in ps). It is also possible to set a multiple of the automatically determined length by using x<REAL> instead, where <REAL> then is a multiplicative factor (e.g. <REAL>=x0.5 for half the default simulation length). |
--shake <INT> | Set SHAKE mode for MD. <INT> can be any of 0 (= off), 1 (= H-only), or 2 (= all bonds). The [default] is <INT>=2. |
--tstep <REAL> | Set MD time step to <REAL> fs. The [default] is 5 fs for GFNn-xTB calculations (requires SHAKE), and 1.5 fs for GFN-FF. The timestep is also automatically checked with a trial simulation at the beginning of the conformational search. |
--mddump <INT> | Set dump frequency in which coordinates are written to the trajectory file to <INT> fs. The [default] is 100 fs. |
--vbdump <INT> | Set frequency in which coordinates are dumped to the collective variable reference structure list to <INT> ps. The [default] is 1.0 ps. |
Conformational Search Settings
The following options modify some algorithmic aspects of the conformational searches and concern mainly the runtypes --v3 and --v4.
| Command | Description |
|---|---|
| Z-matrix sorting | |
--zs | Perform ZSORT prior to conformational sampling. Input coordinates will be overwritten. |
--nosz | Skip ZSORT. [default] |
Genertic z-matrix crossing (only for iMTD-GC) | |
--cross | Perform GC step. [default] |
--nocross | Do not perform GC z-matrix crossing. |
Sampling behavior | |
--norotmd | Turn off the additional MDs on the lowest conformers after the MTD step in iMTD-GC. |
--tnmd <REAL> | Set temperature for the additional normal MDs on the lowest conformers after the MTD step. The [default] is 400 K. |
--mrest <INT> | Adjust the iterative behaviorof iMTD-GC by setting the maximum number of possible MTD restart cycles. The [default] is 5 cycles. |
--hflip/--noflip | Turn on/off a small enhancement routine to rotate XH groups after MTD in iMTD- GC. The [default] is ON. |
--maxflip <INT> | To be used with --hflip. Maximum number of new structures by the above mentioned enhancement routine. The [default] is 1000 structures. |
--quick | Perform an iMTD-GC search with reduced settings for a crude conformer ensemble. |
--squick | Perform an iMTD-GC search with even further reduced settings than --quick. |
--mquick | Perform an iMTD-GC search with even further reduced settings than --quick or --squick. |
Conformer sampling for non-covalent systems | |
--nci | Specialized NCI mode that can be used to find aggregates of NCI complexes. The option generates an ellipsoid potential around the input structure and adds it to the MTD simulation. Also, MTD bias parameters are adjusted and some settings are reduced in order to achieve lower computation times. See Example 3. |
--wscal <REAL> | Scale the ellipsoid potential axes generated by the --nci mode by factor<REAL>. |
Property appendix | |
--prop hess | Performs a hessian calculation for all conformers and re-weights the ensemble on free energies after the conformational sampling. |
--prop reopt | Reoptimization of the ensemble with vtight thresholds after conformational sampling (useful for --quick runs). |
--prop autoIR | Calculate vibrational modes for all conformers and average them (weighted by Boltzmann populations) in a single crest.vibspectrum file. Note that the autoIR command is case-sensitive! |
--prop singlepoint | Calculate a singlepoint energy for all structures in the ensemble and reorder the ensemble accordingly. Not particulary useful after sampling, but effective with the --for command, see below. |
Technical settings | |
--origin | Track conformer origins. [default] |
--keepdir | Keep sub-directories created during the simulations. |
--noreftopo | Turn off only the initial topology check prior to the conformational search. Do not confuse with --notopo |
--noopt,--nopreopt | Turn of automatic pre-optimization of the input geometry at the beinning of a run. |
--wall,--wallxl,--wallxxl | Automatically set up a wall potential (3 different sizes are available) for the calculation, independent of any NCI mode. |
Entropy Mode Settings
The following options modify some algorithmic aspects and thresholds of the conformational entropy runtype --entropy. Partially also applies for --v4.
| Command | Description |
|---|---|
--scthr <REAL> | Specify the ensemble growth threshold (% new conformers) for --entropy and --v4 convergence. The [default] is 0.02 (=2%) for the entropy mode and 0.05 (=5%) for --v4. |
--ssthr <REAL> | Specify the entropy growth threshold (% entropy gain) for --entropy and --v4 convergence. The [default] is 0.005 (=0.5%) for the entropy mode and 0.01 (=1%) for --v4. |
--trange <from> <to> <step> | Entropies from the --entropy mode are always printed for a range of temperatures. The respective temperatures can be specified with this option. <from> and <to> specify the range, <step> deterimines which temperatures in this range are printed. |
--tread <FILE> | Intended for similiar use as --trange. Read a <FILE> containing temperatures (one temperature per line) for which the entropies shall be evaluated explicitly instead of using the range option. |
--ptot <REAL> | The rovibrational average \(\overline{S}\)msRRHO requires frequency calculations at GFN level. To reduce computational cost, only the specified <REAL> fraction of structures are calculated, and the rest is averaged. The [default] is 0.9 (=90%) most populated structures. |
--fscal <REAL> | Scale vibrational frequencies for SmsRRHO by a given factor. The [default] is 1.0. Also works with the --thermo option, see below. |
--sthr <REAL> | Specify the RR-HO interpolation threshold for SmsRRHO (i.e., τ in cm-1). The [default] is 25.0 cm-1. Also works with the --thermo option, see below. |
--ithr <REAL> | Define an imaginary mode cutoff for vibrational frequency evaluation. The [default] is -50.0 cm-1. Also works with the --thermo option, see below. |
Ensemble Sorting Options
The options in this section are used to modify the CREGEN sorting algorithm, in both the standalone version (--cregen <FILE>) and tied in to the conformational sampling. An application of the standalone CREGEN application is shown in Example 2.
| Command | Description |
|---|---|
--ewin <REAL> | Set the energy threshold to <REAL> kcal/mol. This affects several runtypes. The [default] is depending on the application (e.g., 6 kcal/mol conformational searches, 30 kcal/mol protonation site tools). |
--rthr <REAL> | Set RMSD threshold to <REAL> Ångström. The [default] is 0.125 Å. |
--ethr <REAL> | Set energy threshold between conformer pairs in kcal/mol. The [default] is 0.05 kcal/mol. |
--bthr <REAL> | Set lower bound for the rotational constant threshold to <REAL>. The [default] is 0.01 (= 1%). The threshold is dynamically adjusted between this value and 2.5%, based on an anisotropy of the rotational constants in the enesemble. |
--pthr <REAL> | Boltzmann population threshold. Currently unused. |
--nmr, --eqv | Activate determination and printout of NMR-equivalencies for the ensemble. Writes the files anmr_rotamer and anmr_nucinfo, which are required by the CENSO python script. |
--athr <REAL> | Similarity threshold to determine internal rotation of equal atoms for NMR (to be used in conjunction with --nmr). The [default] is 0.04. |
--temp <REAL> | Temperature used for Boltzmann populations in CREGEN. The [default] is 298.15 K. |
--esort | Sort only based on energy, i.e., no RMSD and rotational constant comparison. |
--nowr | Skip writing new ensemble files (crest_rotamers_*.xyz, crest_conformers.xyz). |
--subrmsd | Compare only those parts of the structure that were also included in the metadynamics bias potential. Can be important for constrained conformational searches. See Example 4. |
--notopo [atomlist] | Turn off the topology checks in CREGEN for structures in the ensemble. The optional [atomlist] argument can be used to select specific atoms that should be ignored in the topology checks. For the atomlist format see the Input Formats section. Do not confuse with --noreftopo |
PCA Clustering Options
An extension to the CREGEN sorting is an automatic principle component analysis (PCA) and k-Means sorting clustering algorithm. It can be invoked with the --cluster command.
Tip: The
--cluster option serves as an extension for regular conformational searches, the --cregen <FILE> standalone usage, or the --for <FILE> command and can be used with any of these. Note: This algorithm currently does not work well for non-covalent complexes or molecular clusters and should only be applied to singular molecules.
| Command | Description |
|---|---|
--cluster [ARG] | Perform a clustering on an ensemble to identify the most representative structures, based on dihedral angles. [ARG] is an unspecified optional argument. If [ARG] is an integer, e.g., [ARG]=5, that many clusters will be produced. If [ARG] is omitted, the routine will try to determine the best number of clusters by itself. This autonomous mode can also be accessed with different setting if [ARG] is an of loose, normal, tight, or vtight. Here, cluster sizes are tested one-by-one, which can be expensive for large ensembles. To speed things up, some incremental variants are accessible via incr, tightincr, and vtightincr. The [default], i.e., omitting [ARG], corresponds to --cluster normal. See also Example: Conformational Entropy. |
--pccap <INT> | Limit the number of automatically identified principle components to the <INT> most contributing ones. |
--nopcmin | Remove lower bound for principal component contribution, i.e., more principle components might be considerd for the clustering. |
--pcaex <atomlist> | Ignore atoms listed in <atomlist> in principle component setup. For the format of <atomlist> see this page. |
Constraining Options
CREST offers an interface to xtb’s constraints by passing the respective arguments, e.g. manually via the --cinp option, or by an automatic setup like --cbonds. Constrainment syntax for the xtb can be found here. Some examples for constrained CREST calculations are presented here.
| Command | Description |
|---|---|
--cinp <FILE> | Specify a <FILE> with additional constraints in the xTB syntax. |
--constrain <atomlist> | Set up an example file in which the atoms in <atom list> shall be constrained. The file will be called .xcontrol.sample. No calculations will be performed and the run is aborted after this sample is written. The written file can be read with the --cinp option. For specifications on the atomlist format see the Input Formats section. |
--cbonds [REAL] | Set up a constraint on all bonds (as detected in the input coordinates topology), where [REAL] optionally can be used to set the force constant (default value 0.02 Eh). |
--nocbonds | Turn off -cbonds (mainly for GFN-FF) |
--cmetal [REAL] | Set up a constraint on all M-X bonds (as detected in the input coordinates, M = transition metal atom), where [REAL] optionally can be used to set the force constant (default value 0.02 Eh) |
--cheavy [REAL] | Set up a constraint on all heavy atom bonds (i.e., X-H bonds will be not constrained), where [REAL] optionally can be used to set the force constant (default value 0.02 Eh) |
--clight [REAL] | Set up a constraint on all X-H bonds (as detected in the input coordinates), where [REAL] optionally can be used to set the force constant (default value 0.02 Eh) |
--fc <REAL> | Specify a force constant for the applied constraints (default value 0.02 Eh). Note: Only one force constant is applied for all constraints! |
Standalone Tools
The following tools can be used as as standalone application in CREST, similar to the main runtype options.
| Runtype | Command | Description |
|---|---|---|
| ZSORT z-matrix sorting | --zsort | The atom order of the given input file is sorted in order to yield a more consistent z-matrix, i.e., atoms are grouped together according to the molecular structure (e.g. methyl groups). |
| MDOPT ensemble optimization | --mdopt <FILE> | Optimize each point on a given trajectory or ensemble file <FILE> with GFNn–xTB. |
| SCREEN ensemble optimization | --screen <FILE> | Optimize each point on a given trajectory or ensemble file <FILE> with GFNn–xTB. The resulting ensemble is sorted using the CREGEN routine. |
| Thermostatistical frequency contribution for ensembles | --rrhoav <FILE> | Calculate the \(\overline{S}\)msRRHO contribution for a given ensemble (similar to the --mdopt and --screen functions). The number of structures taken from the ensemble for this calculation is determined dynamically based on their respective Boltzmann population. The calculation can be modified similar to the entropy mode, see |
| Atomic RMSD calculation | --rmsd <FILE1> <FILE2>, --rmsdheavy <FILE1> <FILE2> | Calculate the RMSD or heavy atom RMSD between two given structures. Input format of the two structures can be any of the formats that can be read by CREST, output will always be the RMSD in Ångström. |
| Topology information | --testtopo <FILE> | Calculate the topology (neighbour lists) for a given input structure and print info (coordination numbers, neighbors for each atom) to screen. |
| Thermostatistical calculations from frequencies | --thermo <FILE> | Calculate thermo data for given structure. Also requires vibrational frequencies in the Turbomole format, saved as file called vibspectrum. The calculation can be modified by --fscal and --sthr, see |
| Ensemble processing | --for <FILE>, --forall <FILE> | Calculate some things for the ensemble specified as <FILE>. This option is to be used with the --prop ... option (see above ). Also applicable for a standalone use of the --cluster option. |
| Ensemble file splitting | --splitfile <FILE> [from] [to] | Split an ensemble from <FILE> into separate directories for each structure. [from] and [to] can optionally be used to select specific structures from the file or a range of structures. The new directories are collected in a directory called SPLIT. |
| xTB nanoreactor setup | --reactor | This function provides a utility function to set up an xTB nanoreactor calculation as specified in JCTC, 2019, 15, 2847-2862.. For instructions on how to use it see Example: xTB Nanoreactor. |
Quantum Cluster Growth (QCG) Options
The QCG keyword section can be found on the next page:
Go to Quantum Cluster Growth Keyword Documentation
MSREACT mode Options
Options for the MSREACT mode can be found here:
Go to MSREACT Keyword Documentation