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.

Returns:: The timestamp, or None when absent.
Return type:: datetime.datetime | None

property elements: tuple[str, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | None

property lattice_vectors: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction] | None, Ellipsis] | 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, Ellipsis] | None

property fractional_site_positions: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], Ellipsis] | 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], Ellipsis] | None

property cartesian_site_positions: tuple[tuple[fractions.Fraction, fractions.Fraction, fractions.Fraction], Ellipsis] | 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], Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | 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, Ellipsis] | None

property wyckoff_positions: tuple[str, Ellipsis] | 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, Ellipsis] | 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, Ellipsis][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, Ellipsis]

property species_at_sites: tuple[str, Ellipsis][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, Ellipsis]

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