httk.atomistic.models.structure.semantics¶

Shared OPTIMADE structure semantics for native atomistic representations.

Attributes¶

OptimizationType

Classes¶

`StructureSymmetry`	Store optional, explicitly supplied symmetry metadata for a unit-cell structure.
`StructureSemanticsMixin`	Provide semantics shared by unit-cell, fundamental-domain, and ASU structures.

Functions¶

`validate_optimization_type`(value)	Validate an OPTIMADE optimization type.
`validate_hill_formula`(formula, composition)	Validate an explicitly assigned Hill formula without inventing its molecular scale.
`validate_descriptive_formula`(formula)	Validate the permissive OPTIMADE descriptive-formula token and bracket grammar.
`initialize_semantics`(owner, *, nsites, molecular, ...)	Validate and store shared structure semantics on an owner.

Module Contents¶

httk.atomistic.models.structure.semantics.OptimizationType[source]¶

class httk.atomistic.models.structure.semantics.StructureSymmetry[source]¶

Store optional, explicitly supplied symmetry metadata for a unit-cell structure.

Parameters:

space_group_it_number – Optional International Tables space-group number.
space_group_symbol_hall – Optional Hall symbol.
space_group_symbol_hermann_mauguin – Optional short Hermann–Mauguin symbol.
space_group_symbol_hermann_mauguin_extended – Optional extended Hermann–Mauguin symbol.
space_group_symmetry_operations_xyz – Optional declared raw xyz operations.
wyckoff_positions – Optional Wyckoff letters aligned with represented sites.

Raises:

TypeError – If a symbol is not a string.
ValueError – If the metadata is invalid or mutually inconsistent.

space_group_it_number: int | None = None[source]¶

space_group_symbol_hall: str | None = None[source]¶

space_group_symbol_hermann_mauguin: str | None = None[source]¶

space_group_symbol_hermann_mauguin_extended: str | None = None[source]¶

space_group_symmetry_operations_xyz: tuple[str, Ellipsis] | None = None[source]¶

wyckoff_positions: tuple[str, Ellipsis] | None = None[source]¶

matched_settings: ClassVar[tuple[collections.abc.Mapping[str, Any], Ellipsis]][source]¶

httk.atomistic.models.structure.semantics.validate_optimization_type(value)[source]¶

Validate an OPTIMADE optimization type.

Parameters:: value (str | None) – The optimization type to validate, or None.
Returns:: The validated value.
Raises:: ValueError – If the value is not one of the supported optimization types.
Return type:: str | None

httk.atomistic.models.structure.semantics.validate_hill_formula(formula, composition)[source]¶

Validate an explicitly assigned Hill formula without inventing its molecular scale.

Parameters:

formula (str | None) – The formula to validate, or None.
composition (httk.atomistic.models.formula.composition.Composition | None) – Optional complete composition to cross-check.

Returns:

The unchanged formula, or None.

Raises:

ValueError – If the formula syntax, order, elements, or ratios are invalid.

Return type:

str | None

httk.atomistic.models.structure.semantics.validate_descriptive_formula(formula)[source]¶

Validate the permissive OPTIMADE descriptive-formula token and bracket grammar.

Parameters:: formula (str | None) – The formula to validate, or None.
Returns:: The unchanged formula, or None.
Raises:: ValueError – If the formula is empty, malformed, or contains unknown tokens.
Return type:: str | None

class httk.atomistic.models.structure.semantics.StructureSemanticsMixin[source]¶

Provide semantics shared by unit-cell, fundamental-domain, and ASU structures.

property type: str[source]¶

Expose the logical OPTIMADE entry family.

Returns:: "structures".
Return type:: str

property id: str[source]¶

Expose the stable content identity of this exact representation.

Returns:: The content identifier.
Return type:: str

property immutable_id: str | None[source]¶

Expose the immutable source identifier.

Returns:: The identifier, or None when it is unstated.
Return type:: str | None

property last_modified: datetime.datetime | None[source]¶

Expose the source modification timestamp.

Returns:: The timestamp, or None when it is unstated.
Return type:: datetime.datetime | None

property assemblies: tuple[httk.atomistic.composition.Assembly, Ellipsis] | None[source]¶

Expose site assemblies.

Returns:: The assemblies, or None when they are unstated.
Return type:: tuple[httk.atomistic.composition.Assembly, Ellipsis] | None

property chemical_composition: httk.atomistic.composition.ChemicalComposition | None[source]¶

Expose the supplied chemical composition.

Returns:: The composition, or None when it is unstated.
Return type:: httk.atomistic.composition.ChemicalComposition | None

property composition: httk.atomistic.models.formula.composition_view.CompositionView[source]¶

Present a lazy view over this structure’s projected composition.

isinstance(self.composition, Composition) holds, and projection runs on first data access.

Returns:: The lazy composition view of this structure.
Return type:: httk.atomistic.models.formula.composition_view.CompositionView

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

Expose the composition’s element symbols.

Returns:: Element symbols in composition order.
Return type:: tuple[str, Ellipsis]

property nelements: int[source]¶

Expose the number of composition elements.

Returns:: The number of distinct elements.
Return type:: int

property elements_ratios: tuple[fractions.Fraction, Ellipsis][source]¶

Expose normalized composition element ratios.

Returns:: Element ratios in elements order.
Return type:: tuple[fractions.Fraction, Ellipsis]

property chemical_formula_reduced: str | None[source]¶

Expose the reduced composition formula.

Returns:: The reduced formula, or None when unavailable.
Return type:: str | None

property formula: httk.atomistic.models.formula.formula_view.ChemicalFormulaView[source]¶

Present the reduced formula as a genuine str subclass view.

unwrap() recovers this structure.

Returns:: The reduced formula as a ChemicalFormulaView.
Raises:: ValueError – If the composition is incomplete (including any "X" species) or empty.
Return type:: httk.atomistic.models.formula.formula_view.ChemicalFormulaView

property chemical_formula_anonymous: str | None[source]¶

Expose the anonymous composition formula.

Returns:: The anonymous formula, or None when unavailable.
Return type:: str | None

property chemical_formula_descriptive: str | None[source]¶

Expose the descriptive chemical formula.

Returns:: The formula, or None when it is unstated.
Return type:: str | None

property chemical_formula_hill: str | None[source]¶

Expose the Hill chemical formula.

Returns:: The formula, or None when it is unstated.
Return type:: str | None

property optimization_type: str | None[source]¶

Expose the optimization provenance.

Returns:: The optimization type, or None when it is unstated.
Return type:: str | None

property dimension_types: tuple[int, int, int][source]¶

Expose periodicity as OPTIMADE dimension flags.

Returns:: Three 0/1 flags for the cell directions.
Return type:: tuple[int, int, int]

property lattice_vectors: list[list[float]][source]¶

Expose the cell basis at the float presentation boundary.

Returns:: The three lattice vectors as float rows.
Return type:: list[list[float]]

property fractional_site_positions: list[list[float]][source]¶

Expose reduced site positions at the float presentation boundary.

Returns:: Fractional positions as float rows.
Return type:: list[list[float]]

property cartesian_site_positions: list[list[float]][source]¶

Expose Cartesian site positions at the float presentation boundary.

Returns:: Cartesian positions as float rows.
Return type:: list[list[float]]

property nsites: int[source]¶

Expose the number of represented sites.

Returns:: The site count.
Return type:: int

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

Expose derived OPTIMADE structure-feature flags.

Returns:: Feature flags in canonical order.
Return type:: tuple[str, Ellipsis]

property site_coordinate_span_description: str | None[source]¶

Expose the optional description for a non-standard coordinate span.

Returns:: The span description, or None when unavailable.
Return type:: str | None

property space_group_it_number: int | None[source]¶

Expose the International Tables space-group number.

Returns:: The number, or None when symmetry is unstated.
Return type:: int | None

property space_group_symbol_hall: str | None[source]¶

Expose the Hall space-group symbol.

Returns:: The Hall symbol, or None when symmetry is unstated.
Return type:: str | None

property space_group_symbol_hermann_mauguin: str | None[source]¶

Expose the short Hermann–Mauguin symbol.

Returns:: The symbol, or None when symmetry is unstated.
Return type:: str | None

property space_group_symbol_hermann_mauguin_extended: str | None[source]¶

Expose the extended Hermann–Mauguin symbol.

Returns:: The symbol, or None when symmetry is unstated.
Return type:: str | None

property space_group_symmetry_operations_xyz: tuple[str, Ellipsis] | None[source]¶

Expose the declared raw xyz symmetry operations.

Returns:: The operation strings, or the identity for a periodic structure without explicit operations.
Return type:: tuple[str, Ellipsis] | None

property wyckoff_positions: tuple[str, Ellipsis] | None[source]¶

Expose the site-aligned Wyckoff positions.

Returns:: Wyckoff letters, or None when they are unstated.
Return type:: tuple[str, Ellipsis] | None

httk.atomistic.models.structure.semantics.initialize_semantics(owner, *, nsites, molecular, assemblies, symmetry, chemical_composition, chemical_formula_descriptive, chemical_formula_hill, optimization_type, immutable_id=None, last_modified=None)[source]¶

Validate and store shared structure semantics on an owner.

Parameters:

owner (Any) – The structure receiving the semantic fields.
nsites (int) – The number of represented sites.
molecular (bool) – Whether the structure describes a molecular unit cell.
assemblies (tuple[httk.atomistic.composition.Assembly, Ellipsis] | list[httk.atomistic.composition.Assembly] | None) – Optional site assemblies.
symmetry (StructureSymmetry | None) – Optional structure symmetry metadata.
chemical_composition (httk.atomistic.composition.ChemicalComposition | None) – Optional supplied chemical composition.
chemical_formula_descriptive (str | None) – Optional descriptive formula.
chemical_formula_hill (str | None) – Optional Hill formula.
optimization_type (str | None) – Optional optimization provenance.
immutable_id (str | None) – Optional immutable source identifier.
last_modified (datetime.datetime | None) – Optional timezone-aware source timestamp.

Raises:

TypeError – If a supplied semantic value has the wrong kind.
ValueError – If supplied semantics are invalid or inconsistent.