Ensemble Clustering

Reduce a conformer ensemble by grouping similar geometries and selecting one representative per cluster.

This is useful when you have a large conformer ensemble — for example from Ensemble Generation — and want to reduce it to a manageable set of structurally distinct conformers for downstream calculations.

from atomiverse import (
    Atoms,
    EnsembleClustering,
    EnsembleClusteringMode,
    EnsembleGeneration,
)

atoms = Atoms.from_smiles("CCO")

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

job = EnsembleClustering(
    conformers=seed_result.conformers,
    mode=EnsembleClusteringMode.STANDARD,
)
job.submit()

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

Inputs

conformers is the input ensemble. The job expects at least two conformers; ensembles with a single conformer are returned unchanged.

mode controls the clustering strictness (default: STANDARD):

• LOOSE: broad structural grouping, retains more conformers
• STANDARD: balanced clustering, suitable for most ensembles
• TIGHT: stricter similarity thresholds, fewer representatives
• VERYTIGHT: most selective, minimal representative set

Results

result.conformers is the reduced ensemble. Each conformer contains:

• atoms: the conformer geometry (from the input)
• rank: the one-based rank in the output ensemble

result.n_input is the number of conformers submitted.

result.n_output is the number of conformers in the reduced set.

Compute Resources

CPU cores and memory are determined automatically based on the molecule size and number of input conformers. You do not need to configure any resource settings.

Ensemble clustering is lightweight — it runs a structural similarity analysis without electronic structure calculations.