httk.atomistic.models.structure

Submodules

Attributes

StructureLike

OptimizationType

Classes

StructureAPI

Define the canonical structure interface.

ASUStructure

Assert that a fundamental domain is a true asymmetric unit.

FundamentalDomainStructure

Represent a crystal structure by one exact site per symmetry orbit.

WyckoffSite

Represent one symmetry-distinct site.

StructureBackend

Define the base class for crystal-structure backends.

DatastreamStructure

Represent a structure source parsed only when its data is first accessed.

NumericUnitcellStructure

Backend recognizing the plain-numpy structure quartet.

NumericUnitcellStructureView

A plain-numpy presentation of a UnitcellStructure.

OptimadeStructure

Represent an OPTIMADE structure resource as a lazy structure backend.

PlainStructure

Represent a crystal structure backed by an spglib-like triple.

PlainStructureView

A view presenting an underlying structure backend as a primitive triple.

RecordStructure

Expose a storage record through the existing structure view family.

StructureSemanticsMixin

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

StructureSymmetry

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

UnitcellStructure

Represent a crystal structure in the Unitcell representation.

UnitcellStructureView

A view presenting an underlying structure backend as a UnitcellStructure.

StructureView

Define the base class for crystal-structure views.

Functions

same_crystal(first, second)

Compare two structures as crystallographic descriptions.

initialize_semantics(owner, *, nsites, molecular, ...)

Validate and store shared structure semantics on an owner.

validate_descriptive_formula(formula)

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

validate_hill_formula(formula, composition)

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

validate_optimization_type(value)

Validate an OPTIMADE optimization type.

Package Contents

class httk.atomistic.models.structure.StructureAPI[source]

Bases: abc.ABC

Define the canonical structure interface.

It declares the Unitcell quartet that every structure backend produces from its own native representation and every structure view builds its presentation from: cell, sites, species, and species_at_sites. This is the single interchange format; there is no pairwise conversion between backends.

property cell: httk.atomistic.models.cell.cell.Cell
Abstractmethod:

Expose the structure’s cell.

property sites: httk.atomistic.models.sites.sites.Sites
Abstractmethod:

Expose the structure’s site coordinates.

property species: tuple[httk.atomistic.models.species.species.Species, Ellipsis]
Abstractmethod:

Expose the structure’s distinct species.

property species_at_sites: tuple[str, Ellipsis]
Abstractmethod:

Expose the species occupying each site.

property charge: fractions.Fraction | None

Expose the explicitly assigned net charge of the cell content.

None means unstated and is never derived from the species; it is distinct from an explicit zero.

Returns:

The assigned charge, or None when it is unstated.

Return type:

fractions.Fraction | None

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose optional per-site magnetic moments in sites order.

None means “nothing stated”, not “zero moments”.

Returns:

The site moments, or None when they are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

without_charges()[source]

Return an EXPLICIT lossy projection that drops declared oxidation states.

The canonical structure components and semantic metadata are preserved. A structure without species charges is returned by identity; charged structures are rebuilt in the canonical unit-cell family.

Returns:

A charge-free structure, or this structure when already charge-free.

Return type:

StructureAPI

property composition: httk.atomistic.models.formula.composition.Composition

Project the canonical components into an elemental composition.

property elements: tuple[str, Ellipsis] | None

Expose the complete composition’s element symbols, if available.

property nelements: int | None

Expose the complete composition’s element count, if available.

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

Expose complete composition ratios, if available.

property chemical_formula_reduced: str | None

Expose the reduced formula derived from a complete composition.

property chemical_formula_anonymous: str | None

Expose the anonymous formula derived from a complete composition.

property chemical_formula_descriptive: str | None

Expose an explicitly supplied descriptive formula, when available.

property chemical_formula_hill: str | None

Expose an explicitly supplied Hill formula, when available.

property dimension_types: tuple[int, Ellipsis] | None

Expose cell periodicity as OPTIMADE dimension flags.

property nperiodic_dimensions: int | None

Expose the number of periodic cell directions.

property nsites: int | None

Expose the number of canonical site-coordinate rows.

multiplicities()[source]

Return how many unit-cell sites each represented site contributes.

The canonical structure interface presents a unit cell, so each row contributes once. Symmetry-reduced representations override this with their orbit counts.

Returns:

One multiplicity per represented site.

Return type:

tuple[int, Ellipsis]

property structure_features: tuple[str, Ellipsis] | None

Expose composition-related features derived from canonical components.

class httk.atomistic.models.structure.ASUStructure(cell, spacegroup, wyckoff_sites, species, transform=None, coordinate_precision=None, *, molecular=False, assemblies=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None, _validated_proof=None)[source]

Bases: FundamentalDomainStructure

Assert that a fundamental domain is a true asymmetric unit.

property site_coordinate_span: str

Expose the asymmetric-unit coordinate span.

class httk.atomistic.models.structure.FundamentalDomainStructure(cell, spacegroup, wyckoff_sites, species, transform=None, coordinate_precision=None, *, molecular=False, assemblies=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None, _validated_proof=None)[source]

Bases: httk.atomistic.models.structure.semantics.StructureSemanticsMixin, httk.atomistic.models.structure.backend.StructureBackend

Represent a crystal structure by one exact site per symmetry orbit.

Holds the cell in the structure’s own setting, the space-group setting that names its Wyckoff data, an optional transform from that setting to the structure’s own, one WyckoffSite per symmetry-distinct site, and the species they name. On first expansion, a site whose orbit contributes no new points raises ValueError because it duplicates an earlier site’s orbit.

Parameters:
kind: ClassVar[str] = 'asu'
property cell: httk.atomistic.models.cell.cell.Cell

Expose the cell in the structure’s own setting.

property spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup

Expose the setting that names the stored Wyckoff data.

property transform: httk.atomistic.symmetry.setting_transform.SettingTransform

Expose the transform from the stored setting to the structure’s setting.

property transform_from_standard: httk.atomistic.symmetry.setting_transform.SettingTransform

Return the exact transform from the IT standard setting to this structure.

property wyckoff_sites: tuple[WyckoffSite, Ellipsis]

Expose the symmetry-distinct sites.

property domain_sites: tuple[WyckoffSite, Ellipsis]

Expose the directly stored fundamental-domain sites.

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

Expose the species referenced by the sites.

property coordinate_precision: fractions.Fraction | None

Expose the recorded precision of the reduced coordinates.

Fractional, and expressed in this structure’s own setting — the frame the data arrived in — so it needs no transforming on the way to the expanded sites. Recording it here is what lets an asymmetric unit say how good the data behind it was, rather than leaving that to be guessed again downstream.

It is provenance, never an operating parameter: expansion remains exact and uses no tolerance at all.

Returns:

The fractional precision, or None when it is unknown.

Return type:

fractions.Fraction | None

property asu: FundamentalDomainStructure

Expose this structure as its own fundamental domain.

property periodicity: tuple[bool, bool, bool]

Expose the cell’s periodic directions.

property molecular: bool

Expose whether molecular semantics are enabled.

property domain_species_at_sites: tuple[str, Ellipsis]

Expose species names for the directly represented domain sites.

cartesian_sites()[source]

Compute the exact Cartesian positions of the represented sites.

Returns:

The Cartesian representative positions in the exact surd representation.

Return type:

httk.core.SurdVector

property fractional_site_positions: list[list[float]]

Expose representative positions as floating-point coordinates.

property nsites: int

Expose the number of directly represented sites.

property site_coordinate_span: str

Expose the fundamental-domain coordinate span.

property space_group_it_number: int

Expose the space group’s International Tables number.

property space_group_symbol_hall: str | None

Expose the Hall symbol for the active setting.

property space_group_symbol_hermann_mauguin: str | None

Expose the Hermann–Mauguin symbol for the active setting.

property space_group_symbol_hermann_mauguin_extended: str | None

Expose the extended Hermann–Mauguin symbol for the active setting.

property space_group_symmetry_operations_xyz: tuple[str, Ellipsis]

Expose the active setting’s symmetry operations in xyz notation.

property wyckoff_positions: tuple[str, Ellipsis] | None

Expose Wyckoff positions in the active setting.

property is_standard_setting: bool

Expose whether the structure uses its space group’s standard setting.

setting()[source]

The tabulated setting this structure is written in, or None if untabulated.

A structure in an arbitrary setting is perfectly representable but has no tabulated name; that is the point of storing the transform rather than a setting label.

A transform looked up from the tables remembers which setting it came from, but one that was constructed directly does not, so an equal transform is also matched against the group’s tabulated settings. An identity transform means the stored tabulated setting is already the structure’s own setting.

Returns:

The matching tabulated setting, or None when untabulated.

Return type:

httk.atomistic.symmetry.spacegroup.Spacegroup | None

expand_sites()[source]

Every site of the unit cell, as exact reduced coordinates in this structure’s setting.

The orbit of each asymmetric-unit site is generated directly from its stored setting’s table, wrapped into [0, 1), and deduplicated by exact equality. Only an untabulated setting uses the stored transform. Deduplication then also handles a transform that shrinks the cell; the opposite case, a transform onto a larger cell, is covered by lattice_cosets().

Returns:

All unit-cell sites in the structure’s exact setting.

Return type:

httk.atomistic.models.sites.sites.Sites

expand_species_at_sites()[source]

Expose the species names produced by expand_sites().

Returns:

Species names in expanded site order.

Return type:

tuple[str, Ellipsis]

expand_site_moments()[source]

Expand one exact moment for every represented site.

Returns:

Expanded site moments, or None when moments are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

multiplicities()[source]

How many cell sites each asymmetric-unit site generates, in order.

Usually the Wyckoff position’s tabulated multiplicity, but not always: a setting transform that changes the cell volume changes the count too, by a factor of three for the rhombohedral-axes settings.

Returns:

The number of expanded sites generated by each domain site.

Return type:

tuple[int, Ellipsis]

property sites: httk.atomistic.models.sites.sites.Sites

Expose representative or expanded sites according to the semantics.

property species_at_sites: tuple[str, Ellipsis]

Expose representative or expanded species names according to the semantics.

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose representative or expanded site moments.

property charge: fractions.Fraction | None

Expose the explicitly assigned exact charge of the expanded cell.

Returns:

The assigned charge, or None when it is unstated.

Return type:

fractions.Fraction | None

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

Expose correlations among the domain sites.

class httk.atomistic.models.structure.WyckoffSite[source]

Represent one symmetry-distinct site.

wyckoff is a bare letter ("e", not "4e") naming a position of the structure’s stored setting, and free_params holds one exact value per degree of freedom of that position — none at all for a fixed position such as an inversion centre. species names one of the owning structure’s species.

Moment data uses verbatim-copy semantics: every expanded orbit image carries the same moment. This is physically meaningful only when the site symmetry preserves that moment; magnetic structures that break it must be represented as a unit cell (or via SymopsStructure, coming later).

Partial occupancy needs nothing special here: it lives in the referenced Species, which already carries a composition.

Parameters:

  • wyckoff – The Wyckoff letter in the structure’s stored setting.

  • free_params – The free values for the Wyckoff position.

  • species – The name of the owning structure’s species.

  • representative – An optional retained representative coordinate.

  • moment – An optional moment assigned to the site.

wyckoff: str
free_params: httk.core.FracVector
species: str
representative: httk.core.FracVector | None = None
moment: httk.atomistic.models.moments.backend.SiteMomentsBackend | None = None
property free_count: int

How many free parameters this site carries.

class httk.atomistic.models.structure.StructureBackend(backend, **hints)[source]

Bases: httk.core.Backend[StructureBackend], httk.atomistic.models.structure.api.StructureAPI

Define the base class for crystal-structure backends.

Concrete backends carry a native representation and produce the canonical Unitcell quartet declared by StructureAPI from it.

backend_classes: ClassVar[list[type[httk.core.Backend[Any]]]]
httk.atomistic.models.structure.same_crystal(first, second)[source]

Compare two structures as crystallographic descriptions.

True when they have the same cell and the same multiset of occupied sites, comparing each site by its species and its reduced coordinate wrapped into [0, 1). Site order is ignored, and so is which lattice translate of a site was written down.

The explicitly assigned cell charge and the site moments also participate in the comparison. Recorded coordinate, basis, and moment precision do not, nor do other semantic metadata such as formulas, assemblies, or source identifiers.

The comparison is exact, not approximate: reduced coordinates are exact rationals and cell bases are exact, so two structures that differ by any amount at all compare unequal. There is deliberately no tolerance parameter — a tolerant comparison belongs with the recognition step that snaps a measured structure onto an idealised one, not here.

Periodicity takes part in two ways. Cells must agree on it, so a slab is never the same crystal as the bulk with the same lattice vectors. And only the periodic directions are wrapped, since along the others there is no lattice translate to be indifferent about — an atom at 1.05 really is somewhere else than one at 0.05. The comparison stays exact in the frame as written: two descriptions of the same slab that differ in their non-periodic frame vector compare unequal, because reconciling them would need an origin convention this function deliberately does not have.

Accepts anything structure-like on either side, so a UnitcellStructure may be compared directly against an ASUStructure without expanding it by hand.

Parameters:
Returns:

Whether the structures describe the same crystal.

Return type:

bool

class httk.atomistic.models.structure.DatastreamStructure(obj, **hints)[source]

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

Represent a structure source parsed only when its data is first accessed.

Requests are intentionally reader-only: an OPTIMADE-shaped Request is declined so its headers are never lost by replacing it with fetch(url). Open streams are one-shot sources; a failed parse is not cached, but consumed data cannot be replayed. Network URL strings require core network consent; wrapping a URL in DatastreamURL supplies that consent explicitly.

Parameters:

  • obj (Any) – A path, URL, stream, request, or core datastream source.

  • **hints (Any) – Backend-selection and reader-name hints.

kind: ClassVar[str] = 'datastream'
resolve()[source]

Resolve and return the memoized native structure.

Returns:

The parsed native structure.

Return type:

httk.atomistic.models.structure.backend.StructureBackend

property cell: httk.atomistic.models.cell.cell.Cell

Expose the source structure’s cell.

Returns:

The resolved cell.

Return type:

httk.atomistic.models.cell.cell.Cell

property sites: httk.atomistic.models.sites.sites.Sites

Expose the source structure’s sites.

Returns:

The resolved sites.

Return type:

httk.atomistic.models.sites.sites.Sites

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

Expose the source structure’s species.

Returns:

The resolved distinct species.

Return type:

tuple[httk.atomistic.models.species.species.Species, Ellipsis]

property species_at_sites: tuple[str, Ellipsis]

Expose the species occupying each resolved site.

Returns:

Site species names in site order.

Return type:

tuple[str, Ellipsis]

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose optional moments from the resolved structure.

Returns:

Site moments, or None when they are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

property charge: Any

Expose the resolved structure’s assigned charge.

Returns:

The assigned charge, or None when it is unstated.

Return type:

Any

unwrap()[source]

Return the original lazy source.

Returns:

The path, URL, request, or stream supplied at construction.

Return type:

Any

type httk.atomistic.models.structure.StructureLike = httk.atomistic.models.structure.backend.StructureBackend | httk.atomistic.models.structure.view.StructureView | httk.atomistic.models.structure.unitcell.UnitcellStructure | httk.atomistic.storage.records.UnitcellStructureRecord | httk.atomistic.storage.records.FundamentalDomainStructureRecord | httk.atomistic.storage.records.ASUStructureRecord | httk.atomistic.models.structure.asu.FundamentalDomainStructure | httk.core.optimade.OptimadeResource | str | os.PathLike[str] | httk.core.DatastreamURL | urllib.request.Request | io.IOBase | httk.core.datastream.TextstreamBackend | httk.core.datastream.TextstreamView | httk.core.datastream.BytestreamBackend | httk.core.datastream.BytestreamView | httk.atomistic.integrations.ase.models.ASEAtomsProtocol | httk.atomistic.integrations.pymatgen.models.PymatgenStructureProtocol | tuple[httk.core.VectorLike, httk.core.VectorLike, Any] | list[Any][source]
class httk.atomistic.models.structure.NumericUnitcellStructure(obj, **hints)[source]

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

Backend recognizing the plain-numpy structure quartet.

The wrapped object must expose NumericCell/NumericSites values through cell/sites and the usual species/species_at_sites attributes. Its exact quartet is taken from an exact UnitcellStructure when available, then from the component presentations’ exact values. If neither component carries an exact value, the numeric basis and reduced_coords arrays are passed through the vector family into Cell and Sites. That last route is exact embedding of the floats: their binary float64 values, rather than their decimal spellings, become the exact values.

Parameters:

  • obj (Any) – The numeric structure presentation to wrap.

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

property cell: httk.atomistic.models.cell.cell.Cell

Expose the exact cell quartet component.

property sites: httk.atomistic.models.sites.sites.Sites

Expose the exact sites quartet component.

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

Expose the exact structure’s distinct species.

property species_at_sites: tuple[str, Ellipsis]

Expose the exact species name for each site.

property charge: fractions.Fraction | None

Expose the explicitly assigned exact charge.

unwrap()[source]

Return the wrapped numeric presentation object.

class httk.atomistic.models.structure.NumericUnitcellStructureView(obj, **hints)[source]

Bases: httk.atomistic.models.structure.semantics.StructureSemanticsMixin, httk.atomistic.models.structure.view.StructureView

A plain-numpy presentation of a UnitcellStructure.

Where a UnitcellStructure holds its geometry exactly (a surd cell basis, rational reduced coordinates, and an exact Cartesian frame), this view mirrors that interface but returns plain numpy numbers: its cell is a NumericCell, its sites a NumericSites, and cartesian_sites() a float64 numpy array. The species/species_at_sites are passed through unchanged. It is for callers who do not need exact arithmetic and just want numpy arrays.

The presentation is numpy-backed, so constructing it requires numpy (the httk-atomistic[numpy] extra) and raises ImportError eagerly when it is unavailable. The exact object is always one hop away via exact.

This is a view, not a UnitcellStructure subclass. Its exact UnitcellStructure is built lazily on first access to exact geometry.

Parameters:
property cell: httk.atomistic.models.cell.numeric.NumericCell

The cell as a NumericCell.

property sites: httk.atomistic.models.sites.numeric.NumericSites

The sites as a NumericSites.

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

The distinct species, passed through unchanged.

property species_at_sites: tuple[str, Ellipsis]

The species name occupying each site, passed through unchanged.

property charge: float | None

Expose the explicitly assigned charge as a floating-point value.

property site_moments: httk.core.NumericVector | None

Expose Cartesian site moments as numeric values.

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

Expose site correlations.

cartesian_sites()[source]

The Cartesian site positions as an (N, 3) float64 numpy array.

property periodicity: tuple[bool, bool, bool]

Expose the cell’s periodic directions.

property nperiodic_dimensions: int

Expose the number of periodic directions.

property site_coordinate_span: str

Expose the presented structure’s coordinate span.

property lattice_vectors: list[list[float]]

Expose the cell vectors as numeric coordinates.

property fractional_site_positions: list[list[float]]

Expose reduced site positions as numeric coordinates.

property cartesian_site_positions: list[list[float]]

Expose Cartesian site positions as numeric coordinates.

property exact: httk.atomistic.models.structure.unitcell.UnitcellStructure

The exact UnitcellStructure this view presents.

unwrap()[source]

Return the raw object wrapped by the backend.

unview()[source]

Reject conversion to a standalone plain numeric value.

Returns:

Never; this view has no standalone plain value.

Raises:

TypeError – Always, because this view has no standalone plain value.

Return type:

Any

class httk.atomistic.models.structure.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:
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()[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]

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.

Returns:

The timestamp, or None when absent.

Return type:

datetime.datetime | None

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

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

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

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

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

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]

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

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

class httk.atomistic.models.structure.PlainStructure(obj, **hints)[source]

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

Represent a crystal structure backed by an spglib-like triple.

The native representation is a length-3 (lattice, positions, numbers) list or tuple, where lattice is 3x3, positions is Nx3 reduced coordinates, and numbers is the length-N sequence of atomic numbers. The quartet is derived lazily and cached: cell is a Cell, sites a Sites, species one single-element Species per distinct atomic number, and unwrap returns the original triple. :param obj: The primitive structure triple to wrap. :param **hints: Backend-selection hints.

property cell: httk.atomistic.models.cell.cell.Cell

Expose the cell derived from the lattice.

property sites: httk.atomistic.models.sites.sites.Sites

Expose the reduced coordinates derived from the positions.

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

Expose one species definition for each distinct atomic number.

property species_at_sites: tuple[str, Ellipsis]

Expose the species name occupying each site.

unwrap()[source]

Return the original primitive structure triple.

Returns:

The wrapped lattice, positions, and atomic numbers.

Return type:

Any

class httk.atomistic.models.structure.PlainStructureView(obj, **hints)[source]

Bases: httk.atomistic.models.structure.view.StructureView, tuple

A view presenting an underlying structure backend as a primitive triple.

This view is a genuine (lattice, positions, numbers) tuple, built eagerly and immutable. Because the primitive representation carries only bare atomic numbers, every site’s species must be a single, unattached chemical element (see Species.is_single_element); otherwise a TypeError is raised.

Parameters:
unwrap()[source]

Return the raw value wrapped by the backend.

Returns:

The original source value.

Return type:

Any

unview()[source]

Return this presentation as an ordinary primitive triple.

Returns:

The lattice, positions, and atomic numbers.

Return type:

tuple

class httk.atomistic.models.structure.RecordStructure(obj, **hints)[source]

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

Expose a storage record through the existing structure view family.

Unit-cell records expose their stored components directly; fundamental-domain and asymmetric-unit records expand through the native domain structure when a unit-cell view is requested.

Parameters:
property composition: httk.atomistic.models.formula.composition_view.CompositionView

Expose the record’s authoritative normalized composition.

property cell: httk.atomistic.models.cell.cell.Cell

Expose the record-backed cell.

Returns:

The cell, directly from a unit-cell record or from the expanded domain.

Return type:

httk.atomistic.models.cell.cell.Cell

property sites: httk.atomistic.models.sites.sites.Sites

Expose the record-backed sites.

Returns:

The sites, directly from a unit-cell record or from the expanded domain.

Return type:

httk.atomistic.models.sites.sites.Sites

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

Expose the record-backed distinct species.

Returns:

The species referenced by the structure.

Return type:

tuple[httk.atomistic.models.species.species.Species, Ellipsis]

property species_at_sites: tuple[str, Ellipsis]

Expose the species occupying each record-backed site.

Returns:

Site species names in site order.

Return type:

tuple[str, Ellipsis]

property site_moments: Any

Expose optional record-backed site moments.

Returns:

Site moments, or None when they are unstated.

Return type:

Any

property charge: Any

Expose the record’s explicitly assigned charge.

Returns:

The assigned charge, or None when it is unstated.

Return type:

Any

property molecular: bool

Expose whether the record describes a molecular unit cell.

Returns:

Whether molecular semantics are enabled.

Return type:

bool

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

Expose the record’s site assemblies.

Returns:

Assemblies, or None when they are unstated.

Return type:

tuple[httk.atomistic.composition.Assembly, Ellipsis] | None

property symmetry: httk.atomistic.models.structure.semantics.StructureSymmetry | None

Expose the record’s symmetry metadata.

Returns:

Symmetry metadata, or None when it is absent.

Return type:

httk.atomistic.models.structure.semantics.StructureSymmetry | None

property chemical_composition: Any

Expose the record’s chemical composition.

Returns:

Chemical composition, or None when it is absent.

Return type:

Any

property chemical_formula_descriptive: str | None

Expose the record’s descriptive chemical formula.

Returns:

The descriptive formula, or None when it is absent.

Return type:

str | None

property chemical_formula_hill: str | None

Expose the record’s Hill chemical formula.

Returns:

The Hill formula, or None when it is absent.

Return type:

str | None

property optimization_type: str | None

Expose the record’s optimization provenance.

Returns:

The optimization type, or None when it is absent.

Return type:

str | None

property immutable_id: str | None

Expose the record’s immutable source identifier.

Returns:

The identifier, or None when it is absent.

Return type:

str | None

property last_modified: Any

Expose the record’s modification timestamp.

Returns:

The timestamp, or None when it is absent.

Return type:

Any

property asu: httk.atomistic.models.structure.asu.ASUStructure | httk.atomistic.models.structure.asu.FundamentalDomainStructure | None

Expose the native domain structure when the record stores one.

Returns:

The native asymmetric or fundamental domain, or None for unit-cell records.

Return type:

httk.atomistic.models.structure.asu.ASUStructure | httk.atomistic.models.structure.asu.FundamentalDomainStructure | None

unwrap()[source]

Return the exact fetched record rather than a reconstructed structure.

Returns:

The original storage record.

Return type:

httk.atomistic.storage.records.UnitcellStructureRecord | httk.atomistic.storage.records.FundamentalDomainStructureRecord | httk.atomistic.storage.records.ASUStructureRecord

httk.atomistic.models.structure.OptimizationType[source]
class httk.atomistic.models.structure.StructureSemanticsMixin[source]

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

property type: str

Expose the logical OPTIMADE entry family.

Returns:

"structures".

Return type:

str

property id: str

Expose the stable content identity of this exact representation.

Returns:

The content identifier.

Return type:

str

property immutable_id: str | None

Expose the immutable source identifier.

Returns:

The identifier, or None when it is unstated.

Return type:

str | None

property last_modified: datetime.datetime | None

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

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

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

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]

Expose the composition’s element symbols.

Returns:

Element symbols in composition order.

Return type:

tuple[str, Ellipsis]

property nelements: int

Expose the number of composition elements.

Returns:

The number of distinct elements.

Return type:

int

property elements_ratios: tuple[fractions.Fraction, Ellipsis]

Expose normalized composition element ratios.

Returns:

Element ratios in elements order.

Return type:

tuple[fractions.Fraction, Ellipsis]

property chemical_formula_reduced: str | None

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

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

Expose the anonymous composition formula.

Returns:

The anonymous formula, or None when unavailable.

Return type:

str | None

property chemical_formula_descriptive: str | None

Expose the descriptive chemical formula.

Returns:

The formula, or None when it is unstated.

Return type:

str | None

property chemical_formula_hill: str | None

Expose the Hill chemical formula.

Returns:

The formula, or None when it is unstated.

Return type:

str | None

property optimization_type: str | None

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]

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

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

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

Expose Cartesian site positions at the float presentation boundary.

Returns:

Cartesian positions as float rows.

Return type:

list[list[float]]

property nsites: int

Expose the number of represented sites.

Returns:

The site count.

Return type:

int

property structure_features: tuple[str, Ellipsis]

Expose derived OPTIMADE structure-feature flags.

Returns:

Feature flags in canonical order.

Return type:

tuple[str, Ellipsis]

property site_coordinate_span_description: str | None

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

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

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

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

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

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

Expose the site-aligned Wyckoff positions.

Returns:

Wyckoff letters, or None when they are unstated.

Return type:

tuple[str, Ellipsis] | None

class httk.atomistic.models.structure.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
space_group_symbol_hall: str | None = None
space_group_symbol_hermann_mauguin: str | None = None
space_group_symbol_hermann_mauguin_extended: str | None = None
space_group_symmetry_operations_xyz: tuple[str, Ellipsis] | None = None
wyckoff_positions: tuple[str, Ellipsis] | None = None
matched_settings: ClassVar[tuple[collections.abc.Mapping[str, Any], Ellipsis]]
httk.atomistic.models.structure.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.

httk.atomistic.models.structure.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

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

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

Parameters:
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.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

class httk.atomistic.models.structure.UnitcellStructure(cell, sites, species=None, species_at_sites=None, *, site_moments=None, molecular=False, assemblies=None, symmetry=None, chemical_composition=None, chemical_formula_descriptive=None, chemical_formula_hill=None, optimization_type=None, immutable_id=None, last_modified=None, charge=None)[source]

Bases: httk.atomistic.models.structure.semantics.StructureSemanticsMixin, httk.atomistic.models.structure.backend.StructureBackend

Represent a crystal structure in the Unitcell representation.

A UnitcellStructure holds a cell (a Cell of 3x3 cell vectors), sites (a Sites of Nx3 reduced coordinates), a list of species (each a Species), and a length-N species_at_sites giving the species name occupying each site. Inputs are normalized on construction through the component families: the cell, sites, and each species are passed through their *Like unions, and every species_at_sites name must match one of the (uniquely named) species. When species is omitted, species_at_sites may itself contain species-like values; the distinct species table is then inferred in first-occurrence order.

The numeric model is exact and split by purpose. The fractional frame — reduced coordinates and symmetry — is rational and lives in sites as a FracVector. The Cartesian frame — where radicals such as the hexagonal sqrt(3) appear — is exact in the squarefree-radical field: cell.basis is a SurdVector and cartesian_sites() returns the exact Cartesian positions. Pure magnitudes (bond-length comparisons) stay rational-exact via cell.metric(). Floats appear only at the presentation and JSON boundaries.

Parameters:
kind: ClassVar[str] = 'unitcell'
property cell: httk.atomistic.models.cell.cell.Cell

Expose the cell geometry.

Returns:

The cell in the structure’s exact representation.

Return type:

httk.atomistic.models.cell.cell.Cell

property sites: httk.atomistic.models.sites.sites.Sites

Expose the reduced site coordinates.

Returns:

The sites in the structure’s exact representation.

Return type:

httk.atomistic.models.sites.sites.Sites

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

Expose the distinct species.

Returns:

The species referenced by the structure.

Return type:

tuple[httk.atomistic.models.species.species.Species, Ellipsis]

property species_at_sites: tuple[str, Ellipsis]

Expose the species name occupying each site.

Returns:

Site species names in site order.

Return type:

tuple[str, Ellipsis]

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose optional per-site magnetic moments in sites order.

Returns:

Site moments, or None when they are unstated.

Return type:

httk.atomistic.models.moments.backend.SiteMomentsBackend | None

property charge: fractions.Fraction | None

Expose the explicitly assigned exact charge of the cell.

Returns:

The assigned charge, or None when it is unstated.

Return type:

fractions.Fraction | None

property coordinate_precision: fractions.Fraction | None

Expose the precision recorded for the reduced coordinates.

Read through from sites. Dimensionless — see cartesian_precision() for the corresponding length.

Returns:

The fractional precision, or None when it is unknown.

Return type:

fractions.Fraction | None

property basis_precision: fractions.Fraction | None

Expose the precision recorded for the cell basis.

Read through from cell.

Returns:

The absolute precision, or None when it is unknown.

Return type:

fractions.Fraction | None

property periodicity: tuple[bool, bool, bool]

Expose which cell directions are periodic.

Read through from cell, where the full account lives. (True, True, True) for an ordinary crystal, which is what a structure built without saying otherwise is.

Returns:

The periodicity flags for the cell directions.

Return type:

tuple[bool, bool, bool]

property site_coordinate_span: str

Expose the coordinate span asserted by this representation.

Returns:

unit_cell or molecular_unit_cell.

Return type:

str

property molecular: bool

Expose whether this structure describes a molecular unit cell.

Returns:

Whether molecular semantics are enabled.

Return type:

bool

property symmetry: httk.atomistic.models.structure.semantics.StructureSymmetry | None

Expose the optional symmetry metadata.

Returns:

The symmetry metadata, or None when it is absent.

Return type:

httk.atomistic.models.structure.semantics.StructureSymmetry | None

cartesian_precision()[source]

The coordinate precision as a length, or None if it is unknown.

This is the number a real tolerance wants — an interatomic matching tolerance or an spglib symprec is a distance, and a fractional precision is not. A coordinate good to 1e-4 of a cell edge means something quite different in a 3 Å cell and a 30 Å one.

Computed as the fractional precision times the longest cell edge, which is the conservative choice: it is the largest displacement that fractional uncertainty can produce along any axis. The cell’s own precision is folded in as well, since a cell stated to 1e-3 cannot place an atom better than that however many digits the coordinates carry.

Returns:

The conservative Cartesian precision, or None when the coordinate precision is unknown.

Return type:

fractions.Fraction | None

cartesian_sites()[source]

Compute the exact Cartesian site positions.

Under the row-vector convention this is reduced_coords * cell.basis (each Cartesian position is the sum over lattice vectors sum_k reduced[k] * basis[k]). The reduced coordinates are rational (a FracVector), the cell basis carries the radicals (a SurdVector), so the product is exact in the surd field — the hexagonal sqrt(3) survives into the Cartesian positions.

Returns:

The Cartesian positions in the exact surd representation.

Return type:

httk.core.SurdVector

numeric()[source]

Create a plain-numpy presentation of this structure.

Returns:

The numpy-backed structure view.

Raises:

ImportError – If numpy is unavailable.

Return type:

httk.atomistic.models.structure.numeric_view.NumericUnitcellStructureView

supercell(transformation, *, max_sites=100000)[source]

Build an exact supercell from an integer transformation.

Parameters:

  • transformation (httk.core.VectorLike) – The lattice transformation to apply.

  • max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

orthogonal_supercell(multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=100000)[source]

Build a deterministically selected orthogonal supercell.

Parameters:

  • multiplier (int | None) – The requested volume multiplier, or None to search.

  • tolerance (fractions.Fraction | str | float | None) – The geometric tolerance used during the search.

  • max_multiplier (int | None) – The largest multiplier considered when searching.

  • search_radius (int) – The integer search radius for candidate transformations.

  • max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

cubic_supercell(multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=100000)[source]

Build a deterministically selected cubic supercell.

Parameters:

  • multiplier (int | None) – The requested volume multiplier, or None to search.

  • tolerance (fractions.Fraction | str | float | None) – The geometric tolerance used during the search.

  • max_multiplier (int | None) – The largest multiplier considered when searching.

  • search_radius (int) – The integer search radius for candidate transformations.

  • max_sites (int | None) – The maximum permitted number of sites, or None for no limit.

Returns:

The generated supercell and transformation metadata.

Return type:

httk.atomistic.supercell.SupercellResult

conventional_cell(*, tolerance=None, limit_denominator=None)[source]

Express this structure in its conventional standard-setting cell.

Parameters:

  • tolerance (float | None) – The tolerance used when standardizing the structure.

  • limit_denominator (int | None) – The denominator limit used for rationalizing measured coordinates.

Returns:

The standardized structure and its transformation metadata.

Return type:

httk.atomistic.symmetry.standardization.ConventionalCellResult

class httk.atomistic.models.structure.UnitcellStructureView(obj, **hints)[source]

Bases: httk.atomistic.models.structure.view.StructureView, httk.atomistic.models.structure.unitcell.UnitcellStructure

A view presenting an underlying structure backend as a UnitcellStructure.

This view is a genuine UnitcellStructure, so it can be passed anywhere a UnitcellStructure is accepted. Each component is normalized lazily on first access. For an ASU-backed view, accessing cell or species never triggers expansion.

An ASU backend is expanded when unit-cell sites, species-at-sites, moments, or assemblies are requested. Assembly correlations that cannot be mapped from the fundamental domain to the full cell raise an error.

Parameters:
Raises:

httk.core.optimade.entries.IncompleteOptimadeResourceError – If the source declares a coordinate span that cannot be projected as a native unit cell.

property site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

Expose the site’s magnetic moments.

property charge: fractions.Fraction | None

Expose the explicitly assigned charge.

unwrap()[source]

Return the raw value wrapped by the backend.

Returns:

The original source value.

Return type:

Any

unview()[source]

Materialize this presentation as a standalone unit-cell structure.

Returns:

The exact unit-cell structure represented by this view.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

property immutable_id: str | None

Expose the immutable source identifier.

property last_modified: Any

Expose the source modification timestamp.

property molecular: bool

Expose whether the presented structure is molecular.

property site_coordinate_span: str

Expose the unit-cell coordinate span.

property symmetry: Any

Expose the optional symmetry metadata.

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

Expose site correlations in the presented unit cell.

property chemical_composition: Any

Expose the optional chemical composition metadata.

property chemical_formula_descriptive: str | None

Expose the optional descriptive chemical formula.

property chemical_formula_hill: str | None

Expose the optional Hill chemical formula.

property optimization_type: str | None

Expose the optional optimization provenance.

property site_coordinate_span_description: str | None

Expose the optional coordinate-span description.

property space_group_it_number: int | None

Expose the optional space-group number.

property space_group_symbol_hall: str | None

Expose the optional Hall symbol.

property space_group_symbol_hermann_mauguin: str | None

Expose the optional Hermann–Mauguin symbol.

property space_group_symbol_hermann_mauguin_extended: str | None

Expose the optional extended Hermann–Mauguin symbol.

property space_group_symmetry_operations_xyz: tuple[str, Ellipsis] | None

Expose the optional symmetry operations in xyz notation.

property wyckoff_positions: tuple[str, Ellipsis] | None

Expose the optional Wyckoff positions.

class httk.atomistic.models.structure.StructureView[source]

Bases: httk.core.View[httk.atomistic.models.structure.backend.StructureBackend]

Define the base class for crystal-structure views.