httk.atomistic.models.structure.optimade¶

Lazy, exact OPTIMADE-backed structure representation.

The transport spelling of an OPTIMADE property is deliberately never part of the conversion contract. The accompanying /info/structures snapshot maps each spelling to a property-definition IRI; only that IRI selects a local meaning.

Classes¶

OptimadeStructure

Represent an OPTIMADE structure resource as a lazy structure backend.

Module Contents¶

class httk.atomistic.models.structure.optimade.OptimadeStructure(obj=None, **hints)[source]¶

Bases: httk.atomistic.models.structure.backend.StructureBackend

Represent an OPTIMADE structure resource as a lazy structure backend.

Construction merely retains the resource. The canonical structure quartet is decoded one component at a time, so an incomplete remote resource is still storable, inspectable, and round-trippable.

OPTIMADE dictionaries are presented through exact local values and converted to floats only at presentation boundaries. Species dictionaries may retain the _httk_charges, _httk_spins, and _httk_labels extensions.

Parameters:

obj (httk.core.optimade.OptimadeResource | None) – The OPTIMADE resource to retain.
**hints (Any) – Backend-selection hints, including optional resource or kind.

resource: httk.core.optimade.OptimadeResource[source]¶

kind: ClassVar[str] = 'optimade'[source]¶

entry_type_definition_id: ClassVar[str] = 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/structures'[source]¶

unwrap()[source]¶

Return the exact authoritative source resource by identity.

Returns:: The original OPTIMADE resource.
Return type:: httk.core.optimade.OptimadeResource

property raw: collections.abc.Mapping[str, object][source]¶

Expose the immutable JSON API resource envelope.

Returns:: The decoded resource envelope, including source spelling and extensions.
Return type:: collections.abc.Mapping[str, object]

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

Project the source-backed composition, retaining implicit or source-only ratios.

Returns:: The projected composition.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If source composition fields are inconsistent.
Return type:: httk.atomistic.models.formula.composition.Composition

property formula: str[source]¶

Present the reduced formula as an eager str formula view.

Returns:: The reduced formula as a ChemicalFormulaView.
Raises:: ValueError – If the composition is incomplete or empty.
Return type:: str

property id: str[source]¶

Expose the JSON API resource identifier without inferring it from a remote label.

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

property type: str[source]¶

Expose the JSON API resource type identifier without inferring it from a remote label.

Returns:: The resource type.
Return type:: str

property immutable_id: str | None[source]¶

Expose the portable immutable source identifier.

Returns:: The identifier, or None when absent.
Return type:: str | None

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

Expose the portable source modification timestamp.

A supplied timestamp without a UTC offset violates RFC 3339 and denotes no defined instant, so it is reported once per service origin through the report channel and decoded as unknown (None) rather than assumed to be UTC.

Returns:: The offset-aware timestamp, or None when absent or offset-less.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the value is a non-null, unparseable timestamp.
Return type:: datetime.datetime | None

property elements: tuple[str, ...] | None[source]¶

Expose the validated portable element symbols.

Returns:: Alphabetically ordered element symbols, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If related source composition fields disagree.
Return type:: tuple[str, …] | None

property nelements: int | None[source]¶

Expose the validated portable element count.

Returns:: The element count, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If related source composition fields disagree.
Return type:: int | None

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

Expose exact portable element ratios.

Returns:: Non-negative ratios summing to one, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the ratios are invalid or inconsistent.
Return type:: tuple[fractions.Fraction, …] | None

property chemical_formula_descriptive: str | None[source]¶

Expose the validated descriptive chemical formula.

Returns:: The descriptive formula, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source formula is invalid.
Return type:: str | None

property chemical_formula_reduced: str | None[source]¶

Expose the validated reduced chemical formula.

Returns:: The reduced formula, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source formula is invalid or inconsistent.
Return type:: str | None

property chemical_formula_hill: str | None[source]¶

Expose the validated Hill chemical formula.

Returns:: The Hill formula, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source formula is invalid or inconsistent.
Return type:: str | None

property chemical_formula_anonymous: str | None[source]¶

Expose the validated anonymous chemical formula.

Returns:: The anonymous formula, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source formula is invalid or inconsistent.
Return type:: str | None

property dimension_types: tuple[int, ...] | None[source]¶

Expose portable periodicity flags.

Returns:: Three 0/1 flags, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the flags are invalid or inconsistent.
Return type:: tuple[int, …] | None

property nperiodic_dimensions: int | None[source]¶

Expose the portable periodic-dimension count.

Returns:: The count from zero through three, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the count is invalid or inconsistent.
Return type:: int | None

property nsites: int | None[source]¶

Expose the portable site count.

Returns:: The non-negative site count, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If related arrays disagree with the count.
Return type:: int | None

property structure_features: tuple[str, ...] | None[source]¶

Expose validated OPTIMADE structure-feature flags.

Returns:: Canonically ordered feature flags, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If flags are invalid or inconsistent.
Return type:: tuple[str, …] | None

property lattice_vectors: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction] | None, ...] | None[source]¶

Expose exact lattice vectors from the OPTIMADE source.

Returns:: Three vectors, with None for non-periodic directions, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If vectors conflict with periodicity.
Return type:: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction] | None, …] | None

property fractional_site_positions: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], ...] | None[source]¶

Expose exact fractional site positions.

Returns:: Fractional positions, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If supplied coordinate arrays disagree.
Return type:: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], …] | None

property cartesian_site_positions: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], ...] | None[source]¶

Expose exact Cartesian site positions.

Returns:: Cartesian positions, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If supplied coordinate arrays disagree.
Return type:: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], …] | None

property site_coordinate_span: str[source]¶

Expose the source coordinate span.

Returns:: The OPTIMADE coordinate-span value, defaulting to "unit_cell".
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the span is invalid or lacks required symmetry.
Return type:: str

property site_coordinate_span_description: str | None[source]¶

Expose the description for an "other" coordinate span.

Returns:: The span description, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If a description is invalid or used for another span.
Return type:: str | None

property molecular: bool[source]¶

Expose whether the native unit-cell projection carries molecular placement.

Returns:: Whether the coordinate span is "molecular_unit_cell".
Return type:: bool

property coordinate_precision: fractions.Fraction | None[source]¶

Expose the source precision for reduced coordinates.

Returns:: The fractional precision, or None when unavailable.
Return type:: fractions.Fraction | None

property basis_precision: fractions.Fraction | None[source]¶

Expose the source precision for lattice vectors.

Returns:: The basis precision, or None when unavailable.
Return type:: fractions.Fraction | None

property site_moments: httk.atomistic.models.moments.cartesian.CartesianSiteMoments | None[source]¶

Expose source Cartesian site moments.

Returns:: Cartesian moments, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If moment rows are invalid or cannot be aligned to sites.
Return type:: httk.atomistic.models.moments.cartesian.CartesianSiteMoments | None

property symmetry: httk.atomistic.models.structure.semantics.StructureSymmetry[source]¶

Build typed source symmetry metadata for the common unit-cell view layer.

Returns:: Validated symmetry metadata.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If supplied symmetry fields are inconsistent.
Return type:: httk.atomistic.models.structure.semantics.StructureSymmetry

property optimization_type: str | None[source]¶

Expose the source optimization provenance.

Returns:: The normalized optimization type, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source value is not a string.
Return type:: str | None

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

Expose validated source site assemblies.

Returns:: Assemblies, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If assemblies are invalid or inconsistent.
Return type:: tuple[httk.atomistic.composition.Assembly, …] | None

property space_group_symbol_hall: str | None[source]¶

Expose the source Hall space-group symbol.

Returns:: The symbol, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the symbol conflicts with source symmetry.
Return type:: str | None

property space_group_symbol_hermann_mauguin: str | None[source]¶

Expose the source short Hermann–Mauguin symbol.

Returns:: The symbol, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the symbol conflicts with source symmetry.
Return type:: str | None

property space_group_symbol_hermann_mauguin_extended: str | None[source]¶

Expose the source extended Hermann–Mauguin symbol.

Returns:: The symbol, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the symbol conflicts with source symmetry.
Return type:: str | None

property space_group_it_number: int | None[source]¶

Expose the source International Tables space-group number.

Returns:: The number, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the number conflicts with source symmetry.
Return type:: int | None

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

Expose the declared raw xyz symmetry-operation strings.

Returns:: The source operation strings, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If operations are invalid or inconsistent.
Return type:: tuple[str, …] | None

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

Expose source Wyckoff letters aligned with the represented sites.

Returns:: Wyckoff letters, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If letters are invalid or misaligned.
Return type:: tuple[str, …] | None

property cell: httk.atomistic.models.cell.cell.Cell[source]¶

Expose the projected exact cell.

Returns:: The native cell projection.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source cannot project a unit cell.
Return type:: httk.atomistic.models.cell.cell.Cell

property sites: httk.atomistic.models.sites.sites.Sites[source]¶

Expose the projected exact sites.

Returns:: The native site projection.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source cannot project site coordinates.
Return type:: httk.atomistic.models.sites.sites.Sites

property species: tuple[httk.atomistic.models.species.species.Species, ...][source]¶

Expose decoded species definitions.

Returns:: Distinct species definitions.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If source species dictionaries are invalid.
Return type:: tuple[httk.atomistic.models.species.species.Species, …]

property species_at_sites: tuple[str, ...][source]¶

Expose decoded species names for each site.

Returns:: Site species names in site order.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If names do not align with source sites.
Return type:: tuple[str, …]

property charge: fractions.Fraction | None[source]¶

Expose the private exact charge extension.

Returns:: The assigned charge, or None when absent.
Raises:: httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source charge is not numeric.
Return type:: fractions.Fraction | None