TTConf Conformer Search

The tensor-train (TTConf) conformer search: what it is, how to tune it, and a worked example.

Table of contents

1. What is TTConf?
2. Comparison with the default iMTD-GC search
3. Basic usage
4. Choosing a setting
   1. Presets: accuracy vs. speed
   2. Brute-force oracle
   3. Singlepoints only
   4. Ring sampling
   5. User-defined TT variables (TOML only)
   6. Reproducibility
5. A fully specified input file

What is TTConf?

The -ttconf runtype is CREST’s reimplementation of the tensor-train (TT) conformer search originally introduced by Zurek et al., J. Chem. Theory Comput. 2025. It reproduces the algorithm of that publication within CREST, so that it plugs into the usual CREST level-of-theory and ensemble-handling machinery, with one deliberate deviation: ring conformations are handled by a GFN-FF metadynamics generator (see Ring sampling below), a drop-in replacement for the ring treatment of the original method.

Instead of sampling conformers with (meta)dynamics, TTConf works on a discrete grid: each rotatable dihedral (and, optionally, each flexible ring) is treated as a variable that can take a small number of grid values. The full grid of all dihedral combinations is astronomically large, so it is never enumerated. Instead, the low-energy region is located directly with a TT-cross sweep, which reconstructs the important part of the energy tensor from a small number of oracle (energy) evaluations. Optimized grid minima are then collected, sorted with CREGEN, and written out as the standard CREST ensemble.

Because the search is guided by the tensor structure rather than by diffusion through phase space, TTConf typically needs far fewer energy evaluations than the default metadynamics-based search to reach the same low-energy conformers; most of its speed advantage comes from this.

The final output files are the standard CREST ensemble files crest_conformers.xyz, crest_rotamers.xyz and crest_best.xyz.

Comparison with the default iMTD-GC search

The figure below compares the TTConf search against CREST’s default iMTD-GC workflow on the CD25 drug-molecule benchmark. Both methods were run with the same GFN-FF level of theory, so the comparison isolates the search algorithm itself. The figure labels the tensor-train search TTConf-light, which is the -ttconf reimplementation described here.

Panels (a), (b) and (d) show that TTConf is consistently faster, with a median speedup of about 5.8× and larger gains for the more flexible molecules. Panel (c) shows that this speed does not come at the cost of quality: for most molecules TTConf locates the same global minimum as iMTD-GC (ΔE ≈ 0), and in several cases it finds a lower one. A handful of molecules land on a slightly higher minimum; for those, a larger preset or grid recovers the reference (see below).

Basic usage

TTConf is selected with the -ttconf runtype (command line) or runtype = "ttconf" (TOML input file). For a molecule in struc.xyz, run at GFN-FF:

crest struc.xyz -ttconf --gfnff -T 8

crest input.toml

# TTConf with the default preset
input = "struc.xyz"
runtype = "ttconf"
threads = 8

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

The full list of command line flags is documented under TTConf Options , and the equivalent TOML keys under the [ttconf] block .

Choosing a setting

Presets: accuracy vs. speed

The quickest way to trade cost against thoroughness is a preset, which sets the TT rank r (how much of the energy tensor is reconstructed) and the number of TT-cross sweeps s:

A preset is passed directly after -ttconf (or as preset = "..." in TOML). If a normal run lands on a slightly high minimum, moving up to accurate and/or increasing -ttgrid is usually enough to recover it:

crest struc.xyz -ttconf accurate -ttgrid 12 --gfnff -T 8

Brute-force oracle

For small molecules, or to obtain a reference result, the TT-cross sweep can be replaced by an exhaustive brute-force oracle that evaluates every grid point. This is exact on the chosen grid but scales exponentially with the number of variables, so it is only practical for a few rotatable bonds. Select it with the bruteforce keyword (aliases brute, oracle):

crest struc.xyz -ttconf bruteforce --gfnff

Singlepoints only

By default TTConf geometry-optimizes the grid minima. With -ttsp (singlepoint = true) the whole run uses singlepoints only, with no geometry optimization anywhere. This is much faster and useful for a fast ranking on a fixed grid, at the cost of unrelaxed geometries.

Ring sampling

Rotatable single bonds are detected automatically. Flexible rings are only sampled when requested with -ttrings (ringsample = true), which adds ring conformations as extra TT sites. The ring generator is chosen with -ttringmethod: mtd (GFN-FF metadynamics on an isolated ring cut-out, the default) or template. In-ring bonds can additionally be promoted to TT variables with -ttringbonds.

This is the one place where the CREST reimplementation deliberately deviates from the original publication: the mtd generator is a drop-in replacement for the way the original method treated rings, sampling ring conformations with a short GFN-FF metadynamics on the isolated ring rather than the original scheme.

input = "macrocycle.xyz"
runtype = "ttconf"
threads = 8

[ttconf]
preset = "accurate"
ringsample = true
ringmethod = "mtd"

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

User-defined TT variables (TOML only)

To force a specific set of rotatable bonds to be the TT variables, list them in the bonds key of the [ttconf] block. This has no command line equivalent (atom-pair arrays are awkward on the command line). Each entry is an atom pair [A, B], or [A, B, npoints] to give that bond its own grid resolution:

[ttconf]
bonds = [[1, 2], [3, 4, 12]]   # bond 1–2 on the default grid, bond 3–4 on a 12-point grid
# bonds = [1, 2]               # single pair, flat form

Reproducibility

TTConf seeds a few random initial tails, so runs are non-deterministic by default. Fix the RNG seed with -ttseed <int> (seed = <int>) to make a run reproducible.

A fully specified input file

The following input.toml collects the most common settings (an accurate preset on a finer grid, singlepoint-only evaluation, and ring sampling), all at the GFN-FF level:

input = "struc.xyz"
runtype = "ttconf"
threads = 8

[ttconf]
preset = "accurate"
grid = 12
ewin = 8.0
singlepoint = true
ringsample = true
ringmethod = "mtd"
# bonds = [[1, 2], [2, 3, 12]]   # optional: user-defined TT variables

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

Run it with:

crest input.toml > crest.out

The resulting conformer ensemble is written to crest_conformers.xyz (conformers), crest_rotamers.xyz (conformers and rotamers) and crest_best.xyz (the lowest structure), exactly as for the other CREST search runtypes.