httk.atomistic.models.formula

Submodules

• httk.atomistic.models.formula.anonymous
• httk.atomistic.models.formula.anonymous_string
• httk.atomistic.models.formula.anonymous_view
• httk.atomistic.models.formula.api
• httk.atomistic.models.formula.backend
• httk.atomistic.models.formula.composition
• httk.atomistic.models.formula.composition_view
• httk.atomistic.models.formula.diagnostics
• httk.atomistic.models.formula.formula
• httk.atomistic.models.formula.formula_string
• httk.atomistic.models.formula.formula_view
• httk.atomistic.models.formula.like
• httk.atomistic.models.formula.notation
• httk.atomistic.models.formula.plain
• httk.atomistic.models.formula.prototype
• httk.atomistic.models.formula.record
• httk.atomistic.models.formula.structure
• httk.atomistic.models.formula.view_base

Classes

AnonymousFormula	Store a strictly canonical OPTIMADE anonymous chemical formula.
AnonymousFormulaString	Wrap a canonical anonymous formula held as a plain string.
AnonymousFormulaView	Present a complete composition as an eager canonical anonymous formula.
ChemicalFormulaAPI	Abstract base class for the canonical chemical-formula interface.
ChemicalFormulaBackend	Abstract base class for all backends of chemical-formula data.
Composition	Store an immutable projected composition and its formula diagnostics.
CompositionView	Present any chemical-formula backend as a lazy composition.
CompositionDiagnostic	Record a non-fatal issue encountered while projecting composition.
ChemicalFormula	Store a strictly canonical reduced chemical formula.
FormulaString	Wrap a canonical reduced formula held as a plain string.
ChemicalFormulaView	Present a complete composition as an eager canonical reduced formula.
ChemicalFormulaViewBase	Abstract base class for all views of chemical-formula data.

Functions

anonymous_symbol(index)	Return the unbounded OPTIMADE anonymous symbol for a zero-based index.
parse_anonymous_formula(text)	Parse a strictly canonical OPTIMADE anonymous chemical formula.
parse_reduced_formula(text)	Parse a strictly canonical reduced OPTIMADE chemical formula.
reduced_coefficients(ratios)	Return the least common integer coefficients for exact elemental ratios.
render_anonymous(counts)	Render descending-sorted integer counts using OPTIMADE anonymous symbols.
render_reduced(coefficients)	Render element symbols and reduced integer coefficients in the given order.
try_parse_anonymous(text)	Return canonical anonymous coefficients, or None when text is not one.
try_parse_reduced(text)	Return canonical reduced coefficients, or None when text is not one.

Package Contents

class httk.atomistic.models.formula.AnonymousFormula(backend, **hints)

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend, str

Store a strictly canonical OPTIMADE anonymous chemical formula.

Parameters:

formula – The canonical anonymous formula text.

property is_anonymous: bool

Return whether the formula uses anonymous labels.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Return the anonymous coefficients as exact amounts.

class httk.atomistic.models.formula.AnonymousFormulaString(obj, **hints)

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend

Wrap a canonical anonymous formula held as a plain string.

Parameters:

• obj (str) – The canonical anonymous formula text.

• **hints (Any) – Backend-selection hints.

property is_anonymous: bool

Return whether the formula uses anonymous labels.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Return the anonymous coefficients as exact amounts.

unwrap()

Return the original formula text.

class httk.atomistic.models.formula.AnonymousFormulaView(obj, **hints)

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.anonymous.AnonymousFormula

Present a complete composition as an eager canonical anonymous formula.

Parameters:

• obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.

• **hints (Any) – Backend-selection hints.

property amounts

Return the presented amounts using anonymous labels.

property uncertainties

Return the presented amount precisions using anonymous labels.

property complete

Return whether the presented composition is complete.

property exact

Return whether the presented amounts are exact.

property normalized

Return whether the presented composition is normalized.

property normalization_status

Return the presented composition’s normalization status.

property diagnostics

Return diagnostics associated with the presented composition.

property is_anonymous

Return whether this formula uses anonymous labels.

unview()

Return the presented formula as a standalone value.

Returns:

The canonical anonymous formula value.

Return type:

httk.atomistic.models.formula.anonymous.AnonymousFormula

unwrap()

Return the raw object behind the backend.

Returns:

The unwrapped source object.

Return type:

Any

class httk.atomistic.models.formula.ChemicalFormulaAPI

Bases: abc.ABC

Abstract base class for the canonical chemical-formula interface.

The concrete defaults keep backends that do not have provenance for optional formula metadata interoperable without requiring them to implement every accessor.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Abstractmethod:

Ordered (label, exact amount) pairs for this chemical formula.

Labels are element symbols in alphabetical order unless is_anonymous, in which case they are OPTIMADE anonymous symbols in canonical (descending-coefficient) order.

property is_anonymous: bool

Whether the formula labels are OPTIMADE anonymous symbols.

A backend that carries anonymous notation overrides this; a backend without that distinction inherits False.

property uncertainties: tuple[tuple[str, fractions.Fraction | None], Ellipsis]

Per-amount absolute uncertainties, or None where exactness is unstated.

property complete: bool

Whether the formula accounts for all represented elemental material.

property exact: bool

Whether all formula amounts are exact rather than precision-bounded.

property normalized: bool

Whether the formula is normalized within the stated precision.

property normalization_status: str

The formula’s normalization status derived from exactness and normalization.

property diagnostics: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, Ellipsis]

Non-fatal structured diagnostics associated with the formula.

class httk.atomistic.models.formula.ChemicalFormulaBackend(backend, **hints)

Bases: httk.core.Backend[ChemicalFormulaBackend], httk.atomistic.models.formula.api.ChemicalFormulaAPI

Abstract base class for all backends of chemical-formula data.

Concrete backends carry a native representation and produce the canonical chemical-formula accessors declared by ChemicalFormulaAPI from it.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]

class httk.atomistic.models.formula.Composition(amounts, uncertainties=None, complete=True, exact=None, normalized=True, normalization_status=None, diagnostics=())

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend

Store an immutable projected composition and its formula diagnostics.

Parameters:

• amounts (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]]) – The projected elemental amounts in symbol order.

• uncertainties (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]] | None) – The corresponding amount precisions, if known.

• complete (bool) – Whether the projection contains no unknown elemental content.

• exact (bool | None) – Whether all projected amounts are exact.

• normalized (bool) – Whether all contributing probabilities and concentrations normalize.

• normalization_status (str | None) – The combined normalization status.

• diagnostics (collections.abc.Iterable[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic]) – The non-fatal issues found during projection.

amounts: tuple[tuple[str, fractions.Fraction], Ellipsis] = ()

Ordered (label, exact amount) pairs for this chemical formula.

Labels are element symbols in alphabetical order unless is_anonymous, in which case they are OPTIMADE anonymous symbols in canonical (descending-coefficient) order.

uncertainties: tuple[tuple[str, fractions.Fraction | None], Ellipsis] = ()

Per-amount absolute uncertainties, or None where exactness is unstated.

complete: bool = True

Whether the formula accounts for all represented elemental material.

exact: bool = True

Whether all formula amounts are exact rather than precision-bounded.

normalized: bool = True

Whether the formula is normalized within the stated precision.

normalization_status: str = 'exact'

The formula’s normalization status derived from exactness and normalization.

diagnostics: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, Ellipsis] = ()

Non-fatal structured diagnostics associated with the formula.

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

Return the projected amounts as a read-only mapping.

property uncertainty_mapping: collections.abc.Mapping[str, fractions.Fraction | None]

Return the projected amount precisions as a read-only mapping.

property elements: tuple[str, Ellipsis]

Return the projected element symbols in amount order.

property nelements: int

Return the number of projected elements.

property elements_ratios: tuple[fractions.Fraction, Ellipsis]

Return the projected amounts normalized by their total.

property chemical_formula_reduced: str | None

Return the reduced chemical formula, if the composition is complete.

property chemical_formula_anonymous: str | None

Return the anonymous formula, if the composition is complete.

class httk.atomistic.models.formula.CompositionView(obj, **hints)

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.composition.Composition

Present any chemical-formula backend as a lazy composition.

Parameters:

• obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.

• **hints (Any) – Backend-selection hints.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Return the lazily materialized elemental amounts.

property uncertainties: tuple[tuple[str, fractions.Fraction | None], Ellipsis]

Return the lazily materialized amount precisions.

property complete: bool

Return whether the presented composition is complete.

property exact: bool

Return whether the presented amounts are exact.

property normalized: bool

Return whether the presented composition is normalized.

property normalization_status: str

Return the presented composition’s normalization status.

property diagnostics: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, Ellipsis]

Return diagnostics associated with the presented composition.

unwrap()

Return the raw object behind the backend.

Returns:

The unwrapped source object.

Return type:

Any

unview()

Return the presented composition as a standalone value.

Returns:

The materialized composition value.

Return type:

httk.atomistic.models.formula.composition.Composition

class httk.atomistic.models.formula.CompositionDiagnostic

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.models.formula.ChemicalFormula(backend, **hints)

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend, str

Store a strictly canonical reduced chemical formula.

Parameters:

formula – The alphabetical formula text with greatest common divisor one.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Return the formula coefficients as exact amounts.

class httk.atomistic.models.formula.FormulaString(obj, **hints)

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend

Wrap a canonical reduced formula held as a plain string.

Parameters:

• obj (str) – The canonical reduced formula text.

• **hints (Any) – Backend-selection hints.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]

Return the formula coefficients as exact amounts.

unwrap()

Return the original formula text.

class httk.atomistic.models.formula.ChemicalFormulaView(obj, **hints)

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.formula.ChemicalFormula

Present a complete composition as an eager canonical reduced formula.

Parameters:

• obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.

• **hints (Any) – Backend-selection hints.

property amounts

Return the presented elemental amounts.

property uncertainties

Return the presented amount precisions.

property complete

Return whether the presented composition is complete.

property exact

Return whether the presented amounts are exact.

property normalized

Return whether the presented composition is normalized.

property normalization_status

Return the presented composition’s normalization status.

property diagnostics

Return diagnostics associated with the presented composition.

property is_anonymous

Return whether this formula uses anonymous labels.

unview()

Return the presented formula as a standalone value.

Returns:

The canonical reduced formula value.

Return type:

httk.atomistic.models.formula.formula.ChemicalFormula

unwrap()

Return the raw object behind the backend.

Returns:

The unwrapped source object.

Return type:

Any

httk.atomistic.models.formula.anonymous_symbol(index)

Return the unbounded OPTIMADE anonymous symbol for a zero-based index.

Parameters:

index (int) – The non-negative zero-based symbol index.

Returns:

The generated anonymous symbol.

Raises:

ValueError – If index is not a non-negative integer.

Return type:

str

httk.atomistic.models.formula.parse_anonymous_formula(text)

Parse a strictly canonical OPTIMADE anonymous chemical formula.

Parameters:

text (str) – The formula text to parse.

Returns:

The canonical anonymous-label and coefficient pairs.

Raises:

ValueError – If text is not a canonical anonymous formula.

Return type:

tuple[tuple[str, int], Ellipsis]

httk.atomistic.models.formula.parse_reduced_formula(text)

Parse a strictly canonical reduced OPTIMADE chemical formula.

The reduced and anonymous grammars are disjoint by construction: an anonymous label may have an arbitrary lowercase tail, while an element symbol has at most one.

Parameters:

text (str) – The formula text to parse.

Returns:

The canonical element and coefficient pairs.

Raises:

ValueError – If text is not a canonical reduced formula.

Return type:

tuple[tuple[str, int], Ellipsis]

httk.atomistic.models.formula.reduced_coefficients(ratios)

Return the least common integer coefficients for exact elemental ratios.

Parameters:

ratios (collections.abc.Sequence[fractions.Fraction]) – The exact elemental ratios in their desired output order.

Returns:

The reduced integer coefficients, or None for an empty sequence.

Return type:

tuple[int, Ellipsis] | None

httk.atomistic.models.formula.render_anonymous(counts)

Render descending-sorted integer counts using OPTIMADE anonymous symbols.

Parameters:

counts (collections.abc.Sequence[int]) – The coefficients in descending order.

Returns:

The canonical anonymous formula text.

Return type:

str

httk.atomistic.models.formula.render_reduced(coefficients)

Render element symbols and reduced integer coefficients in the given order.

Parameters:

coefficients (collections.abc.Sequence[tuple[str, int]]) – The element and coefficient pairs to render.

Returns:

The canonical reduced formula text.

Return type:

str

httk.atomistic.models.formula.try_parse_anonymous(text)

Return canonical anonymous coefficients, or None when text is not one.

Parameters:

text (str) – The formula text to test.

Returns:

The parsed coefficients, or None for invalid text.

Return type:

tuple[tuple[str, int], Ellipsis] | None

httk.atomistic.models.formula.try_parse_reduced(text)

Return canonical reduced coefficients, or None when text is not one.

Parameters:

text (str) – The formula text to test.

Returns:

The parsed coefficients, or None for invalid text.

Return type:

tuple[tuple[str, int], Ellipsis] | None

class httk.atomistic.models.formula.ChemicalFormulaViewBase

Bases: httk.core.View[httk.atomistic.models.formula.backend.ChemicalFormulaBackend]

Abstract base class for all views of chemical-formula data.