Composite calculators

Combining a fast workhorse method with a higher level of theory for refinement.

CREST 3.1

Why composite setups?
Command line notation
1. Example
Post-search refinement
The same thing in TOML

Why composite setups?

A conformational search is dominated by the sheer number of energy and gradient evaluations, not by the cost of a single one. The small example at the bottom of this page, a conformer search for alanineglycine with all of 20 atoms, needs about 2.8 × 10⁵ energy+gradient calls. At GFN-FF this takes 18 seconds; at a DFT level it would take weeks.

The way out is to split the workflow between two levels of theory:

a fast workhorse method that drives the metadynamics, the optimizations and the ensemble generation, and
a more accurate quality method that is applied only where it changes the result, namely to the (comparatively few) structures that survive the search.

CREST supports this directly, both through short command line arguments and through [[calculation.level]] blocks of a TOML input file.

Command line notation

Composite methods are requested as a single argument that combines both levels, --<A><separator><B>, where A is always the higher level and B the workhorse. The separator selects when the quality level is applied:

Argument	Refinement stage	What happens
`--<A>//<B>` `--<A>/sp/<B>`	inline single-point	after every optimization within the workflow, the ensemble energies are recomputed at `<A>`; geometries stay at `<B>`
`--<A>/opt/<B>`	inline geometry optimization	the surviving structures are re-optimized at `<A>` during the workflow
`--<A>@<B>`	post-search optimization	the search runs entirely at `<B>`; all final conformers are re-optimized at `<A>` afterwards

For all three forms, <A> and <B> must be one of the built-in method tokens gfn0, gfn1, gfn2, gxtb, gfnff. Arbitrary calculators (ORCA, MLIPs, …) can be combined the same way through a TOML input file, see below .

Note: A composite argument selects the levels, not the workflow. The runtype still has to be given, e.g. --imtdgc for the iMTD-GC conformer search or --opt for a geometry optimization.

Example

The following runs the iMTD-GC conformer search of alanineglycine at GFN-FF and re-ranks the ensemble with GFN2-xTB single-points:

crest struc.xyz --imtdgc --gfn2//gfnff -T 8

20

C     2.081440     0.615100    -0.508430
C     2.742230     1.824030    -1.200820
N     4.117790     1.799870    -1.190410
C     4.943570     2.827040    -1.822060
C     6.440080     2.569360    -1.637600
O     7.351600     3.252270    -2.069090
N     0.610100     0.695090    -0.538780
O     2.095560     2.724940    -1.739670
O     6.705220     1.463410    -0.897460
H     0.303080     1.426060     0.103770
H     0.338420     1.050680    -1.460480
C     2.488753    -0.593400    -1.198448
H     2.416500     0.557400     0.532050
H     4.614100     1.081980    -0.670550
H     4.699850     3.794460    -1.373720
H     4.722890     2.844690    -2.894180
H     7.687400     1.448620    -0.860340
H     2.029201    -1.457008    -0.719999
H     2.170233    -0.542411    -2.238576
H     3.572730    -0.688405    -1.154998

   Command line input:
 $ crest struc.xyz --imtdgc --gfn2//gfnff -T 8

  --imtdgc : iMTD-GC
  gfn2//gfnff : inline singlepoint re-ranking
  -T 8 (CPUs/Threads selected)

> All CLI arguments successfully processed.
 ----------------
 Calculation info
 ----------------
> User-defined calculation level 1:
 : GFN-FF calculation via GFNFF lib
 :   Molecular charge    : 0
> User-defined calculation level 2:
 : xTB calculation via tblite lib
 : GFN2-xTB level
 :   refinement stage    : singlepoint
 :   Molecular charge    : 0
 :   Fermi temperature   : 300.00000
 :   Accuracy            : 1.00000
 :   max SCC cycles      : 500
 
> Energy and gradient processing:
 Energies and gradients of all calculation levels will be added according to their weights
 
 
 -----------------------------
 Initial Geometry Optimization
 -----------------------------
 Geometry successfully optimized.
 

                            [ ... sampling ... ]

 -------------------
 ensemble refinement
 -------------------
> Singlepoint re-ranking for 826 structures
 ↳ singlepoints: 8 parallel jobs × 1 core/job  (8 threads)
 |>0.1% |>10.0% |>20.1% |>30.0% |>40.1% |>50.0% |>60.0% |>70.1% |>80.0% |>90.1% |>100.0%
 done.
> 826 of 826 structures successfully evaluated (100.0% success)
> Total runtime for 826 singlepoint calculations:
 * wall-time:     0 d,  0 h,  0 min,  0.593 sec
 *  cpu-time:     0 d,  0 h,  0 min,  4.704 sec
 * ratio c/w:     7.938 speedup
> Corresponding to approximately 0.001 sec per processed structure
 
                            [ ... ]

 number of doubles removed by rot/RMSD :       289 ( 33.92%)
 number of unique structures remaining :       563 ( 66.08%)
 number of unique conformers identified:       208 ( 36.94% of 563)
********************************************************************************
                            [ ... ]

 * wall-time:     0 d,  0 h,  0 min, 17.958 sec
 *  cpu-time:     0 d,  0 h,  2 min, 20.170 sec
 * ratio c/w:     7.806 speedup
 ------------------------------------------------------------------
 * Peak RSS:   145.96 MiB
 * Total number of energy+grad calls:  2.8463E+05
 
 CREST terminated normally.

The two levels are listed separately in the Calculation info block, and the second one is marked with its refinement stage. During the run, the refinement appears as its own ensemble refinement step.

Post-search refinement

The refinement can also be requested independently of the sampling level, which is useful to re-rank or re-optimize an ensemble at the end of an otherwise unchanged workflow:

Argument	Description
`--refine <METHOD>`	add an inline single-point refinement at `<METHOD>` (equivalent to the `//` form)
`--rerank <METHOD>`	re-compute single-point energies of the final ensemble at `<METHOD>` and re-sort; geometries unchanged
`--reopt <METHOD>`	re-optimize all conformers of the final ensemble at `<METHOD>` and re-sort via CREGEN
`--finalhess`	Hessian and free-energy re-ranking of the final ensemble, i.e., Boltzmann weights from ΔG instead of ΔE

The same thing in TOML

In a TOML input file, a composite setup is simply a second [[calculation.level]] block that carries a refine key. The level without refine is the workhorse; the level with it is applied at the given stage:

# GFN-FF sampling, GFN2-xTB re-ranking (identical to --gfn2//gfnff)
input   = "struc.xyz"
runtype = "imtd-gc"
threads = 8

[calculation]
[[calculation.level]]           # workhorse: drives MTD and optimizations
method = "gfnff"

[[calculation.level]]           # quality level, only used for refinement
method = "gfn2"
refine = "sp"

The refine key accepts:

Value	Meaning
`sp`, `singlepoint`	single-point re-ranking of the ensemble
`opt`, `optimization`	geometry re-optimization of the ensemble
`add`, `correction`	single-point energy of this level is added to the workhorse energy
`freq`, `deltag`	Hessian/free-energy (δG) correction

Since this is an ordinary [[calculation.level]] block, any calculator can serve as the quality level, including the ones that are far too expensive to drive a search themselves:

# GFN-FF sampling, DFT re-ranking through an ORCA subprocess
input   = "struc.xyz"
runtype = "imtd-gc"
threads = 12

[calculation]
[[calculation.level]]
method = "gfnff"

[[calculation.level]]
orca_input  = "! r2scan-3c def2/J TightSCF"
orca_cmd    = "/PATH/TO/ORCA/orca"
threads     = 4                 # cores per ORCA call
orca_memory = 3000
refine      = "sp"

Tip: This is the recommended way to use the ORCA and MLIP calculators: let a semiempirical method do the sampling and spend the expensive level only on the final ensemble. See the per-level threads settings in the input file documentation for how to parallelize such runs.