Skip to main content

Ensemble Energy Ranking

Evaluate every conformer in an ensemble with a single-point energy calculation and return the structures sorted by energy (lowest first).

This is useful when you already have a conformer ensemble — for example from Ensemble Generation — and want to rank the members by their absolute electronic energy without optimizing geometries. Each energy is stored in the global cache automatically, so re-running the same ensemble at the same level of theory is instantaneous.

from atomiverse import (
    Atoms,
    EnsembleEnergyRanking,
    EnsembleGeneration,
)
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 = EnsembleEnergyRanking(
    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.

compute_forces optionally requests nuclear gradients for every conformer. Defaults to False because force evaluation on a full ensemble is expensive.

Results​

result.conformers is the input ensemble sorted by absolute energy (lowest first). Each conformer contains:

  • atoms: the original conformer geometry
  • energy: absolute energy in Hartree
  • rank: the one-based rank in the sorted ensemble

result.energies is a parallel list of absolute energies in Hartree, in the same order as result.conformers.

result.n_input is the number of conformers that were submitted.

Compute Resources​

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

The walltime estimate scales with the number of conformers because each structure is evaluated sequentially.