conformer_generator

The central orchestrator for generating TS-constrained conformer ensembles.

from racerts import ConformerGenerator
cg = ConformerGenerator(verbose=False, randomSeed=12, num_threads=1)

Settings

  • verbose : print additional information on the progress and diagnostics
  • randomSeed : seed for randomization
  • num_threads : multithreading

The conformer generator object is initialized with this default configuration with default parameters:

cg.mol_getter = MolGetterSMILES()
cg.embedder = CmapEmbedder()
cg.optimizer = MMFFOptimizer()
cg.energy_pruner = EnergyPruner()
cg.rmsd_pruner = RMSDPruner()

You can swap components via properties, for example:

cg.mol_getter = MolGetterBonds(assignBonds=True, allowChargedFragments=True)
cg.embedder = BoundsMatrixEmbedder(...)
cg.optimizer = UFFOptimizer(...)
# optional dependency:
# pip install racerts[ase]
cg.optimizer = ASEOptimizer(...)
cg.energy_pruner = EnergyPruner(threshold=20.0, ...)
cg.rmsd_pruner = RMSDPruner(threshold=0.125, ...)

You can manually swap in ASE optimization as well:

from ase.calculators.lj import LennardJones
from racerts.optimizer import ASEOptimizer

cg.optimizer = ASEOptimizer(calculator=LennardJones())

Functions

generate_conformers(file_name, charge=0, reacting_atoms=[], frozen_atoms=[], input_smiles=[], number_of_conformers=-1, conf_factor=30, auto_fallback=True)

End-to-end ensemble generation:

  1. Build mol (get_mol)
  2. Embed conformers (embed_TS)
  3. Refine conformers with a force field (optimize)
  4. Prune by force field energy and RMSD (prune)

Main parameters:

  • reacting_atoms : (0-based) indices of atoms whose connectivity changes; drives constraints
  • file_name : .xyz file path with a single TS geometry (3D)
  • charge : total molecular charge (important for MolGetterBonds)
  • input_smiles : optional SMILES fragments to define topology (used by MolGetterSMILES)

Additional options to configure the workflow:

  • number_of_conformers : number of generated conformers (see embed_TS(...))
  • conf_factor : tunes the number of generated conformers (see embed_TS(...))
  • auto_fallback : activate fallback (see get_mol(...))
  • frozen_atoms : optional way to override the set to constrained atoms
    (if omitted, reacting_atoms and neighboring atoms are used)

get_mol(file_name, charge, reacting_atoms, input_smiles=[], auto_fallback=True)

Builds the starting molecule using the configured getter. If that fails (and auto_fallback=True) a fallback mechanism automatically tries alternative options in with priority:

  1. MolGetterSMILES
  2. MolGetterBonds
  3. MolGetterConnectivity

embed_TS(mol_ts, new_mol, reacting_atoms, frozen_atoms, number_of_conformers=-1, conf_factor=30)

Embeds conformers with the configured embedder variant.
The number of conformers can be set with the number_of_conformers parameter. Otherwise, it is calculated using the conf_factor, proportional to the number of rotatable bonds of the molecule, #rotatable_bonds:

number_of_conformers = #rotatable_bonds * conf_factor + 30.

force_field(new_mol, mol_ts, frozen_atoms, auto_fallback=True)

Refines conformers with constraints on frozen_atoms. If the MMFFOptimizer fails, it automatically falls back to UFFOptimizer.

prune(mol)

Runs energy_pruner then rmsd_pruner to reduce the number of conformers.

write_xyz(file_name, use_energy=False, comment="0 1")

Writes the ensemble as a combined .xyz file. If use_energy=True, the per-conformer energy is written in Hartree (converted from the internal kcal/mol energy property). The comment is added to the second line of the .xyz file. As default, the charge and spin multiplicity of 1 is used.