httk.atomistic.composition¶

Exact, precision-aware chemical composition projection.

Classes¶

`CompositionDiagnostic`	Record a non-fatal issue encountered while projecting composition.
`Assembly`	Represent one site-disorder assembly without normalizing its probabilities.
`ChemicalComposition`	Store explicit elemental amounts as additional or authoritative composition.

Functions¶

`validate_assemblies`(assemblies[, nsites])	Validate global assembly site ownership for a structure.
`derive_structure_features`(structure)	Return the exact-composition features present on a structure.
`project_composition`(structure)	Project a structure to exact elemental amounts without normalization.

Module Contents¶

class httk.atomistic.composition.CompositionDiagnostic[source]¶

Record a non-fatal issue encountered while projecting composition.

Parameters:

code – The stable diagnostic code.
message – The human-readable diagnostic message.
subject – The composition subject involved, if any.
total – The calculated total, if applicable.
width – The precision width used for the diagnostic, if applicable.

code: str¶

message: str¶

subject: str | None = None¶

total: fractions.Fraction | None = None¶

width: fractions.Fraction | None = None¶

class httk.atomistic.composition.Assembly[source]¶

Represent one site-disorder assembly without normalizing its probabilities.

Parameters:

sites_in_groups – The non-overlapping site-index groups in the assembly.
group_probabilities – The probability assigned to each group.
group_probabilities_precision – The precision of each group probability, if known.

sites_in_groups: tuple[tuple[int, Ellipsis], Ellipsis][source]¶

group_probabilities: tuple[fractions.Fraction, Ellipsis][source]¶

group_probabilities_precision: tuple[fractions.Fraction | None, Ellipsis] | None = None[source]¶

property normalized: bool[source]¶

Whether the group probabilities sum to one within their precision.

property normalization_status: str[source]¶

Return the probability normalization status.

property normalization_diagnostic: httk.atomistic.models.formula.diagnostics.CompositionDiagnostic | None[source]¶

Return the normalization diagnostic, if the probabilities are outside precision.

class httk.atomistic.composition.ChemicalComposition(amounts, mode='implicit', amounts_precision=None)[source]¶

Store explicit elemental amounts as additional or authoritative composition.

implicit amounts supplement the site-derived composition; full amounts replace it while still recording a mismatch diagnostic when the two disagree.

Parameters:

amounts (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]]) – The positive amounts for named chemical elements.
mode (Literal['implicit', 'full']) – Whether the amounts are "implicit" or authoritative "full" values.
amounts_precision (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]] | None) – The precision of the stated amounts, if known.

amounts: tuple[tuple[str, fractions.Fraction], Ellipsis][source]¶

amounts_precision: tuple[tuple[str, fractions.Fraction | None], Ellipsis][source]¶

mode: Literal['implicit', 'full'][source]¶

property elements: tuple[str, Ellipsis][source]¶

Return the element symbols in the stored amount order.

property amount_mapping: collections.abc.Mapping[str, fractions.Fraction][source]¶

Return the elemental amounts as a read-only mapping.

property precision_mapping: collections.abc.Mapping[str, fractions.Fraction | None][source]¶

Return the amount precisions as a read-only mapping.

httk.atomistic.composition.validate_assemblies(assemblies, nsites=None)[source]¶

Validate global assembly site ownership for a structure.

Parameters:

assemblies (collections.abc.Iterable[Assembly]) – The assemblies to validate.
nsites (int | None) – The structure site count used to bound site indices, if supplied.

Returns:

The validated assemblies in their input order.

Raises:

TypeError – If an item is not an Assembly.
ValueError – If a site index is out of bounds or occurs in multiple assemblies.

Return type:

tuple[Assembly, Ellipsis]

httk.atomistic.composition.derive_structure_features(structure)[source]¶

Return the exact-composition features present on a structure.

Parameters:: structure (Any) – The structure whose composition-related features are inspected.
Returns:: The feature names in alphabetical order.
Return type:: tuple[str, Ellipsis]

httk.atomistic.composition.project_composition(structure)[source]¶

Project a structure to exact elemental amounts without normalization.

Site multiplicities, disorder, assemblies, attached elements, and explicit composition semantics are combined without silently renormalizing their stated values.

Parameters:

structure (Any) – The unit-cell or asymmetric-unit structure to project.

Returns:

The projected composition and its completeness, precision, and diagnostics.

Raises:

TypeError – If the structure has an invalid explicit chemical composition.
ValueError – If a structure site refers to an unknown species or has invalid assemblies.

Return type:

httk.atomistic.models.formula.composition.Composition