Ensemble Optimization

Optimize an existing conformer ensemble using repeated optimization “meta-cycles” with filtering between cycles.

This is typically used after Ensemble Generation to refine the geometries and remove duplicate conformers without spending a full optimization budget on every structure.

All input geometries are optimized. The only filtering performed between meta-cycles is near-duplicate pruning.

from atomiverse import (
    Atoms,
    EnsembleGeneration,
    EnsembleOptimization,
)
from atomiverse.levels import GFN2_XTB

atoms = Atoms.from_smiles("CCO")

seed = EnsembleGeneration(
    atoms=atoms,
    charge=0,
    multiplicity=1,
)
seed.submit()
seed_result = seed.require_result()

job = EnsembleOptimization(
    conformers=seed_result.conformers,
    charge=0,
    multiplicity=1,
    level_of_theory=GFN2_XTB,
)
job.submit()

result = job.require_result()
for conformer in result.conformers:
    print(conformer.rank, conformer.energy)

Inputs

conformers is the input ensemble. The job expects at least one conformer.

charge and multiplicity describe the total charge and spin multiplicity.

level_of_theory selects the method used to evaluate energies and optimize geometries.

mode controls optimization precision (for example: standard, tight, verytight).

is_transition_state=True switches to transition-state optimization behavior.

constraints optionally applies geometry constraints to every conformer during optimization.

Modes

Ensemble optimization offers four preset modes:

• loose: fastest, lowest precision
• standard: default balance of speed and quality
• tight: higher precision, more work per conformer
• verytight: highest precision

The exact numerical thresholds are worker-defined and may improve over time without requiring an SDK update.

Constraints

Constraints use the same models as Optimization:

from atomiverse import ConstrainBond, EnsembleOptimization

job = EnsembleOptimization(
    conformers=seed_result.conformers,
    charge=0,
    multiplicity=1,
    level_of_theory=GFN2_XTB,
    constraints=[ConstrainBond(0, 1)],
)

Results

result.conformers is an ordered list. Each conformer contains:

• atoms: the optimized conformer geometry
• energy: relative energy (kcal/mol) with respect to the minimum in the returned set
• rank: the one-based rank in the returned ensemble

The result also includes bookkeeping fields:

• n_input, n_converged, n_filtered, n_meta_cycles

Completed ensembles are cached by the input conformers, charge, multiplicity, level of theory, mode, constraints, and the workflow version.