Reference Energies

The aenet.reference_energies module provides helper routines for constructing atomic reference energies used in cohesive- and formation-energy-based workflows.

Both ReferenceEnergies.from_regression() and ReferenceEnergies.from_reference_compounds() consume lightweight (composition, energy) samples directly, so callers can stream data from custom parsers without materializing full structure objects. For file-backed workflows, the module also provides a lazy helper that yields those samples from paths readable by aenet.io.structure.

class aenet.reference_energies.ReferenceEnergies(_atomic_energies: dict[str, float], method: str, _metadata: dict[str, ~typing.Any] = <factory>)

Bases: object

Resolved atomic reference energies with provenance metadata.

Parameters:

• _atomic_energies (dict[str, float]) – Internal storage for the resolved species-energy mapping.

• method (str) – Name of the construction workflow.

• _metadata (dict, optional) – Workflow metadata and diagnostics.

property atomic_energies: dict[str, float]

Return a copy of the resolved atomic reference energies.

classmethod from_reference_compounds(samples, *, reference_compounds: Sequence[Any], fixed_atomic_energies: dict[str, float] | None = None) → ReferenceEnergies

Construct atomic energies from user-chosen reference compounds.

Parameters:

• samples (iterable) – Iterable of (composition, energy) pairs. composition must be a mapping from species labels to integer counts, and energy must be a finite total energy. The iterable may be lazy.

• reference_compounds (sequence) – Requested reference compositions, specified either as formula strings such as "TiO2" or as explicit composition mappings. If multiple matching samples exist for one requested composition, the lowest-energy sample is used.

• fixed_atomic_energies (dict[str, float], optional) – User-specified species energies held fixed during the solve.

Returns:

Resolved atomic reference energies and solver metadata.

Return type:

ReferenceEnergies

Raises:

ValueError – If the inputs are empty, contain invalid samples, request missing or duplicate reference compounds, contain unknown fixed species, or remain underdetermined after applying user constraints.

classmethod from_regression(samples, *, fixed_atomic_energies: dict[str, float] | None = None, subset_size: int | None = None, subset_fraction: float | None = None, random_seed: int | None = None) → ReferenceEnergies

Estimate atomic energies from total-energy regression.

Parameters:

• samples (iterable) – Iterable of (composition, energy) pairs. composition must be a mapping from species labels to integer counts, and energy must be a finite total energy. The iterable may be lazy.

• fixed_atomic_energies (dict[str, float], optional) – User-specified species energies held fixed during the fit. This is required for underdetermined composition spaces unless the user explicitly chooses a different reference convention upstream.

• subset_size (int, optional) – Number of regression samples to draw uniformly without replacement before fitting. Mutually exclusive with subset_fraction.

• subset_fraction (float, optional) – Fraction of regression samples to draw uniformly without replacement before fitting. Mutually exclusive with subset_size.

• random_seed (int, optional) – Seed used for deterministic subset selection.

Returns:

Resolved atomic reference energies and fit metadata.

Return type:

ReferenceEnergies

Raises:

ValueError – If the inputs are empty, contain invalid samples, specify invalid subset arguments, contain unknown fixed species, or remain underdetermined after applying user constraints.

property metadata: dict[str, Any]

Return a copy of the workflow metadata and diagnostics.

method: str

aenet.reference_energies.iter_composition_energy_samples_from_files(paths: PathLike[str] | str | Iterable[PathLike[str] | str], *, frmt: str | None = None, **read_kwargs) → Iterator[tuple[dict[str, int], float]]

Yield lazy (composition, energy) samples from structure files.

Parameters:

• paths (path-like or iterable of path-like) – One path or an iterable of paths readable by aenet.io.structure.read(). Files containing multiple frames yield one sample per frame.

• frmt (str, optional) – Explicit input format forwarded to aenet.io.structure.read().

• **read_kwargs – Additional keyword arguments forwarded to aenet.io.structure.read().

Yields:

tuple[dict[str, int], float] – One (composition, energy) pair per frame.