Conformer Workflow

End-to-end conformer ensemble generation, refinement, ranking, and thermochemistry.

This job chains multiple building blocks into a single composite workflow:

1. Ensemble generation — an initial conformer ensemble is built from the input structure
2. Ensemble optimisation — every conformer is geometry-optimised at the chosen level of theory
3. Clustering — duplicate or near-duplicate conformers are removed by structural similarity
4. Single-point energy ranking — the clustered conformers are ranked by absolute single-point energy
5. Frequencies & MSRRHO — (optional, enabled by default) a Hessian calculation and MSRRHO thermochemistry evaluation are performed on each conformer to obtain Gibbs free-energy corrections at 298.15 K
6. Energy-window filter — high-energy conformers are discarded according to the selected mode

import atomiverse
from atomiverse import Atoms, ConformerWorkflow, ConformerWorkflowMode
from atomiverse.levels import GFN2_XTB, B97_3C

atomiverse.configure(api_key="your-api-key")

atoms = Atoms.from_smiles("CCCO")

job = ConformerWorkflow(
    atoms=atoms,
    charge=0,
    multiplicity=1,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=B97_3C,
    mode=ConformerWorkflowMode.STANDARD,
    use_msrrho=True,
)
job.submit()

result = job.require_result()
print(f"{result.n_output} conformers after filtering "
      f"(from {result.n_generated} generated, "
      f"{result.n_optimized} optimised, "
      f"{result.n_clustered} clustered, "
      f"{result.n_ranked} ranked)")

for i, (conformer, energy) in enumerate(
    zip(result.conformers, result.energies_hartree)
):
    print(f"  Conformer {i + 1}: energy = {energy:.8f} Eₕ")

Inputs

Field	Type	Default	Description
atoms	Atoms	(required)	Input molecular geometry
charge	int	0	Total charge of the system
multiplicity	int	1	Spin multiplicity (2S + 1)
optimization_level_of_theory	LevelOfTheory	(required)	Method for geometry optimisations and Hessians
single_point_energy_level_of_theory	LevelOfTheory	(required)	Method for single-point energy ranking
mode	ConformerWorkflowMode	STANDARD	Controls thresholds from generation through the final energy filter
use_msrrho	bool	True	Whether to compute MSRRHO free-energy corrections
is_transition_state	bool	False	Switch to transition-state conformer search
active_atoms	list[int]	None	Atom indices for transition-state mode (required when is_transition_state=True)

Modes

The mode parameter controls the tightness of the conformer search and the final energy-window filter. More aggressive presets keep fewer conformers and use tighter tolerances throughout the pipeline.

Mode	Energy window (kcal/mol)	Use case
LOOSE	10.0	Exploratory searches; keep most conformers
STANDARD	6.0	General-purpose conformer analysis
TIGHT	3.0	Focused studies near the global minimum
VERYTIGHT	2.0	Only the most stable conformer(s)

The energy window is measured from the lowest-energy conformer. Conformers whose relative energy exceeds the window are discarded.

MSRRHO Corrections

When use_msrrho=True (the default), each clustered conformer receives a Hessian calculation followed by an MSRRHO thermochemistry evaluation at 298.15 K. The reported energies are free energies (electronic energy

• Gibbs free-energy correction) and the final ranking uses these corrected values.

When use_msrrho=False, the workflow skips Hessians and MSRRHO, and the energies are bare electronic single-point values.

# Fast mode without thermochemistry
job = ConformerWorkflow(
    atoms=atoms,
    charge=0,
    multiplicity=1,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=GFN2_XTB,
    mode=ConformerWorkflowMode.STANDARD,
    use_msrrho=False,
)

Setting use_msrrho=False significantly reduces walltime since Hessian calculations are the most expensive step in the pipeline.

Transition-State Conformers

Set is_transition_state=True and provide active_atoms to run the conformer search in transition-state mode:

job = ConformerWorkflow(
    atoms=ts_guess,
    charge=0,
    multiplicity=1,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=B97_3C,
    mode=ConformerWorkflowMode.TIGHT,
    is_transition_state=True,
    active_atoms=[1, 4, 7],
)

active_atoms uses zero-based atom indices and identifies the atoms participating in the bond-breaking/forming event. This guides the transition-state conformer generation.

Results

job.require_result() returns a ConformerWorkflowResult with:

Field	Type	Description
conformers	list[Atoms]	Filtered conformer geometries, ranked by free energy
energies_hartree	list[float]	Energies in Hartree corresponding to each conformer
mode	ConformerWorkflowMode	The workflow mode used
use_msrrho	bool	Whether MSRRHO corrections were applied
temperature_k	float	Temperature used for MSRRHO (298.15 K)
n_generated	int	Number of conformers from the generation step
n_optimized	int	Number after geometry optimisation
n_clustered	int	Number after clustering
n_ranked	int	Number after SPE + MSRRHO ranking (before filtering)
n_output	int	Final count after energy-window filtering
steps	ConformerWorkflowSteps or None	Intermediate results (may be omitted in API responses)

When use_msrrho=True, energies_hartree contains MSRRHO-corrected free energies. When False, it contains electronic single-point energies.

Step details

The optional steps field provides per-conformer detail when available:

Field	Type	Description
generated_conformers	list[EnsembleConformer]	Raw conformers from generation
optimized_conformers	list[EnsembleConformer]	Conformers after optimisation
clustered_conformers	list[EnsembleConformer]	Conformers after clustering
spe_ranked_conformers	list[EnsembleConformer]	Conformers after SPE ranking
spe_ranked_energies_hartree	list[float]	SPE energies in Hartree
free_energy_ranked_conformers	list[EnsembleConformer]	Conformers after free-energy ranking
frequencies_cm1	list[list[float]]	Harmonic frequencies for each conformer
gibbs_corrections_hartree	list[float]	Gibbs corrections added to SPE energies
free_energies_hartree	list[float]	Final free energies

Non-blocking Submission

job.submit(wait=False)
print(job.job_id)

# do other work …

job.refresh()
if job.state == State.DONE:
    result = job.require_result()
    print(f"Lowest energy: {result.energies_hartree[0]:.6f} Eₕ")

See Single Point Energy — Non-blocking Submission for the full pattern including save/load, cancellation, and BYOC capacity waits.

Choosing Levels of Theory

A common pattern is to use a fast semi-empirical method for the geometry optimisation and Hessian steps, and a higher-level DFT method for the single-point ranking:

from atomiverse.levels import GFN2_XTB, B97_3C

job = ConformerWorkflow(
    atoms=molecule,
    charge=0,
    multiplicity=1,
    optimization_level_of_theory=GFN2_XTB,
    single_point_energy_level_of_theory=B97_3C,
    mode=ConformerWorkflowMode.STANDARD,
)

This combination keeps the expensive Hessian calculations at the GFN2-xTB level while obtaining accurate relative energies from DFT.

Caching

Each sub-step (generation, optimisation, clustering, single-point ranking) is cached independently by canonical chemistry identity. Repeating the workflow with different modes, levels of theory, or MSRRHO settings may benefit from partial cache hits.

Compute Resources

The conformer workflow is assigned to the medium tier for small molecules and is automatically promoted for larger systems or tighter modes. The walltime budget scales with the mode: VERYTIGHT > TIGHT > STANDARD > LOOSE.

When use_msrrho=True, an additional walltime multiplier is applied to account for the per-conformer Hessian calculations.

See Also

• Ensemble Generation — raw conformer generation
• Ensemble Optimization — geometry refinement
• Ensemble Clustering — remove duplicates
• Ensemble Energy Ranking — single-point ranking
• MSRRHO Thermochemistry — finite-temperature corrections
• Tautomer Workflow — tautomers + conformers
• Levels of Theory — available computational methods
• Job Management — rename and delete jobs