Command-line interface¶

The racerts CLI mirrors the core functionality of the Python API. It has three subcommands, racerts ts, racerts gs and racerts constrained, and keeps the legacy racerts form racerts filename.xyz [options] (also racerts run filename.xyz [options]), which is described in the rest of this page. With the same settings, racerts ts and the legacy form write the same ensemble.

racerts ts / racerts gs / racerts constrained¶

$ racerts ts ts.xyz --reacting-atoms 3 4 5 --smiles "CCCCCC=C" [options]
$ racerts gs "OC(=O)[C@@H]1CCCN1C(C)=C" [options]
$ racerts gs molecule.xyz [options]
$ racerts constrained complex.xyz --hard 0 1 2 3 [options]

racerts constrained samples a structure around atoms that stay where they are in the file, e.g. a binding motif or a core (the task Constrained of the Python API).

racerts gs takes the molecule as a SMILES or as a structure file. From a file it keeps the configuration of the geometry (stereocentres and double bonds). The graph of an xyz file comes from the SMILES (-s) if given, then from the perceived bonds, and from the connectivity alone only with --graph connect: without bond orders the search would run on a different molecule.

Option	Explanation
-r, --reacting-atoms (ts)	0-based indices of the atoms whose bonds form or break
--frozen-atoms (ts)	frozen atoms instead of the reacting atoms and their neighbours
--hard (constrained)	0-based indices of the atoms held at the geometry of the file
-s, --smiles (ts, constrained, gs with a file)	SMILES of the TS topology or of the molecule, one per fragment
--graph (ts, constrained, gs with a file)	first method for the graph: smiles, bonds or connect
-c, --charge	total charge (default 0; gs with a SMILES: from the SMILES)
--multiplicity	spin multiplicity (default: the lowest for the electrons)
--config	PipelineConfig as JSON or YAML; the options below override it
-n, --n-conformers, --conf-factor	conformers to embed
--embed	cmap or bounds
--etkdg, --no-etkdg	ETKDGv3 instead of plain distance geometry (default: only for gs)
--refine	mmff or uff
--no-fallback	no fallback for the graph (bonds, connectivity) or MMFF (UFF)
--seed, --num-threads
--energy-threshold, --rmsd-threshold	pruning
-o, --output	output file (default conformer_ensemble.xyz)
--crest-energies	only the energy (Hartree) on each comment line, as CREST does
-v, -vv	progress (INFO) or details (DEBUG) on stderr

racerts filename.xyz (legacy)¶

The command is:

$ racerts filename.xyz [options]

where the filename.xyz is the path to an .xyz file containing a single TS conformer.

General inputs¶

Command	Options	Explanation
-c --charge	<INT> [0]	Overall molecular charge
-mult --multiplicity	<INT>	Spin multiplicity; the lowest for the number of electrons (1 or 2) if omitted
-smiles --input_smiles	<STR...>	One (or multiple) SMILES for either product or starting material to define topology
-atoms --reacting_atoms	<INT...>	List of (0-based) indices of reacting atoms
-frozen --frozen_atoms	<INT...>	Optional: overwrite of atoms to freeze; if omitted, neighbors of reacting atoms are inferred

Ensemble size¶

Command	Options	Explanation
-cf --conf_factor	<INT> [80]	Number of initially generated conformers: NumRotatableBonds × conf_factor + 30
-n --number_of_conformers	<INT> [-1]	Specify number of initially generated conformers (and overwrite conf_factor)

Conformer Generation Configuration¶

Command	Options	Explanation
-m --mol	<smiles|bonds|connect>	Method to infer molecular graph from .xyz: smiles use MolGetterSMILES; bonds use MolGetterBonds; connect use MolGetterConnectivity
-e --embed	<dm|cmap> [cmap]	Embedding method: dm = bounds-matrix; uses BoundsMatrixEmbedder; cmap = coordinate map; uses CmapEmbedder
-ff --ff	<mmff|uff> [mmff]	Force-field refinement: ; mmff uses MMFFOptimizer; uff uses UFFOptimizer

Output¶

Command	Options	Explanation
-o --output	<STR> [conformer_ensemble.xyz]	Output .xyz filename; the comment lines are in extended XYZ format (energy in eV, charge, spin; readable with ase.io.read)
--out_energies	-	Instead, write only the energy in Eh on each comment line (as in CREST ensembles); conformer property remains in kcal/mol
-v --verbose	-	Progress on stderr (-vv: details)

Performance and reproducibility¶

Command	Options	Explanation
--num_threads	<INT> [1]	Threads for embedding/optimization
--seed	<INT> [12]	Random seed
--no_fallback	-	Disable automatic fallback (see below)

molgetter options¶

Command	Explanation
--no_assignbonds	For bonds getter: don’t assign bonds [default: True]
--disallow_charged_fragments	For bonds getter: disallow charged fragments [default: True]

embedder options¶

Command	Explanation
--no_random_coords	Disable random coordinates

optimizer options¶

Command	Explanation
--force_constant	<FLOAT> [1e6]

RMSDPruner options¶

Command	Options	Explanation
-rmsd --rmsd_thres	<FLOAT> [0.125]	RMSD threshold in Å
-rmsd_hs --rmsd_include_hs	-	Include hydrogens when computing RMSDs [default: False]
--no_filter_energies	-	Disable energy-based dissimilarity prefilter [default: True]
--no_filter_rotations	-	Disable rotational-profile prefilter [default: True]
--rmsd_energy	<FLOAT> [0.1]	Energy difference threshold (kcal/mol) for the prefilter
--rmsd_rot_fraction	<FLOAT> [0.03]	Rotational-difference fraction threshold
-rmsd_match --rmsd_max_matches	<INT> [10000]	Max substructure matches for RMSD calculation

EnergyPruner options¶

Command	Options	Explanation
-energy --energy_thres	<FLOAT> [20.0]	Energy window for pruning (kcal/mol)

Common recipes¶

Basic run

$ racerts example.xyz --charge 0 --reacting_atoms 2 3 4

Use SMILES-defined topology and coordinate-map embedding

$ racerts example.xyz --charge 0 \
  --reacting_atoms 2 3 4 \
  --input_smiles "C1=CC=CC=C1" "O" \
  --mol smiles --embed cmap --ff mmff --out_energies

Increase diversity by allowing more initial conformers

$ racerts example.xyz --charge 0 --reacting_atoms 2 3 4 --conf_factor 120

Faster refinement on many conformers with threads (if using multithreaded optimizers)

$ racerts example.xyz --charge 0 --reacting_atoms 2 3 4 --num_threads 4