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)

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:
resource: httk.core.optimade.OptimadeResource
kind: ClassVar[str] = 'optimade'
entry_type_definition_id: ClassVar[str] = 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/structures'
unwrap()

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]

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

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

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

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

Returns:

The resource identifier.

Return type:

str

property type: str

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

Expose the portable immutable source identifier.

Returns:

The identifier, or None when absent.

Return type:

str | None

property last_modified: datetime.datetime | None

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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, ...]

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, ...]

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

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