httk.atomistic.storage.records

Frozen storage records for complete atomistic structures.

Classes

SpeciesConstituentRecord	Represent one aligned, optionally decorated species constituent.
SpeciesRecord	Represent a frozen storable snapshot of an atomistic species.
AssemblyGroupRecord	Represent one exact site-index group in a stored assembly.
AssemblyRecord	Represent the exact durable form of an assembly.
WyckoffSiteRecord	Represent an exact Wyckoff site with its retained representative.
SettingTransformRecord	Represent an exact stored-setting-to-own transform.
SymmetryRecord	Represent optional symmetry metadata for a unit-cell structure.
CompositionAmountRecord	Represent one exact declared element amount.
ChemicalCompositionRecord	Represent a durable authoritative or implicit composition declaration.
NormalizedCompositionRecord	Represent the authoritative exact elemental composition of a structure.
NormalizedCompositionAmountRecord	Represent one exact normalized composition ratio.
CellRecord	Represent an exact durable cell basis, precision, and periodicity.
SitesRecord	Represent exact durable reduced coordinates and their stated precision.
UnitcellStructureRecord	Represent the native durable backing for an explicit unit-cell structure.
FundamentalDomainStructureRecord	Represent the native durable backing for a symmetry fundamental domain.
ASUStructureRecord	Represent the native durable backing for an asserted asymmetric unit.
ObservableSummaryRecord	Represent a bounded numeric summary for one trajectory observable.
TrajectoryRecord	Represent bounded trajectory identity and reference-frame summary.
WyckoffOccupationRecord	Represent one occupied standard-setting Wyckoff orbit and its real species.
ProtostructureRecord	Represent the durable backing for a geometry-free protostructure.
PrototypeRecord	Represent the durable backing for a standard-setting dummy-species prototype.

Module Contents

class httk.atomistic.storage.records.SpeciesConstituentRecord

Represent one aligned, optionally decorated species constituent.

Parameters:

• chemical_symbol – The constituent’s chemical symbol.

• concentration – The constituent occupancy.

• mass – The constituent mass, if stated.

• charge – The constituent charge, if stated.

• spin – The constituent spin, if stated.

• label – The constituent label, if stated.

• concentration_precision – The occupancy precision, if stated.

chemical_symbol: str

concentration: fractions.Fraction

mass: float | None = None

charge: fractions.Fraction | None = None

spin: fractions.Fraction | None = None

label: str | None = None

concentration_precision: fractions.Fraction | None = None

class httk.atomistic.storage.records.SpeciesRecord

Represent a frozen storable snapshot of an atomistic species.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook.

Parameters:

• name – The species name.

• constituents – The aligned constituent records.

• original_name – The source species name, if stated.

• attached – The attached constituent symbols, if stated.

• nattached – The counts corresponding to attached, if stated.

name: str

constituents: tuple[SpeciesConstituentRecord, Ellipsis]

original_name: str | None = None

attached: tuple[str, Ellipsis] | None = None

nattached: tuple[int, Ellipsis] | None = None

property chemical_symbols: tuple[str, Ellipsis]

Expose the constituent chemical symbols.

Returns:

The chemical symbols in constituent order.

Return type:

tuple[str, Ellipsis]

property concentration: tuple[fractions.Fraction, Ellipsis]

Expose the constituent occupancies.

Returns:

The concentrations in constituent order.

Return type:

tuple[fractions.Fraction, Ellipsis]

property mass: tuple[float, Ellipsis] | None

Expose the constituent masses.

Returns:

The masses in constituent order, or None when unstated.

Return type:

tuple[float, Ellipsis] | None

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

Expose the constituent occupancy precision.

Returns:

The precisions in constituent order, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

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

Expose the constituent charges.

Returns:

The charges in constituent order, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

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

Expose the constituent spins.

Returns:

The spins in constituent order, or None when unstated.

Return type:

tuple[fractions.Fraction | None, Ellipsis] | None

property labels: tuple[str | None, Ellipsis] | None

Expose the constituent labels.

Returns:

The labels in constituent order, or None when unstated.

Return type:

tuple[str | None, Ellipsis] | None

class httk.atomistic.storage.records.AssemblyGroupRecord

Represent one exact site-index group in a stored assembly.

Parameters:

sites – The distinct non-negative site indexes in the group.

sites: tuple[int, Ellipsis]

class httk.atomistic.storage.records.AssemblyRecord

Represent the exact durable form of an assembly.

Parameters:

• groups – The site-index groups.

• group_probabilities – The probability of each group.

• group_probabilities_precision – The probability precision, if stated.

groups: tuple[AssemblyGroupRecord, Ellipsis]

group_probabilities: tuple[fractions.Fraction, Ellipsis]

group_probabilities_precision: tuple[fractions.Fraction, Ellipsis] | None = None

property sites_in_groups: tuple[tuple[int, Ellipsis], Ellipsis]

Expose the site indexes grouped by assembly value.

Returns:

The site indexes in group order.

Return type:

tuple[tuple[int, Ellipsis], Ellipsis]

class httk.atomistic.storage.records.WyckoffSiteRecord

Represent an exact Wyckoff site with its retained representative.

The owning record’s domain_sites field is storage-visible and deliberately unchanged.

Parameters:

• wyckoff – The Wyckoff letter.

• free_parameters – The exact free-parameter values.

• species – The owning species name.

• representative – The retained representative coordinate, if present.

• moment_kind – The site-moment kind, if present.

• moment – The flattened exact site-moment components, if present.

• moment_precision – The site-moment precision, if present.

wyckoff: str

free_parameters: tuple[fractions.Fraction, Ellipsis]

species: str

representative: tuple[fractions.Fraction, Ellipsis] | None = None

moment_kind: str | None = None

moment: tuple[httk.core.SurdScalar, Ellipsis] | None = None

moment_precision: fractions.Fraction | None = None

class httk.atomistic.storage.records.SettingTransformRecord

Represent an exact stored-setting-to-own transform.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook.

Parameters:

• matrix – The stored-setting-to-own fractional coordinate matrix.

• vector – The stored-setting-to-own fractional origin shift.

• hall_entry – The normalized Hall entry, if known.

matrix: Annotated[httk.core.FracVector, httk.core.storage.markers.Shape(3, 3)]

vector: tuple[fractions.Fraction, Ellipsis]

hall_entry: Annotated[str | None, IdentitySkip()] = None

class httk.atomistic.storage.records.SymmetryRecord

Represent optional symmetry metadata for a unit-cell structure.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook.

Parameters:

• space_group_it_number – The International Tables space-group number, if known.

• space_group_symbol_hall – The Hall symbol, if known.

• space_group_symbol_hermann_mauguin – The Hermann-Mauguin symbol, if known.

• space_group_symbol_hermann_mauguin_extended – The extended Hermann-Mauguin symbol, if known.

• space_group_symmetry_operations_xyz – The symmetry operations in xyz form, if known.

• wyckoff_positions – The Wyckoff position symbols, if known.

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

class httk.atomistic.storage.records.CompositionAmountRecord

Represent one exact declared element amount.

Parameters:

• element – The element symbol.

• amount – The exact element amount.

• precision – The amount precision, if stated.

element: str

amount: fractions.Fraction

precision: fractions.Fraction | None = None

class httk.atomistic.storage.records.ChemicalCompositionRecord

Represent a durable authoritative or implicit composition declaration.

Parameters:

• amounts – The exact element amounts.

• mode – The composition declaration mode.

amounts: tuple[CompositionAmountRecord, Ellipsis]

mode: str

class httk.atomistic.storage.records.NormalizedCompositionRecord

Represent the authoritative exact elemental composition of a structure.

This relation is semantic normalized data, not a rendered-formula cache. It retains each exact central element amount together with its source precision, and makes the same complete-composition facts available to every durable structure backing for response construction and exact filtering.

Parameters:

• amounts – The normalized element amounts.

• complete – Whether the composition accounts for all structure content.

amounts: tuple[NormalizedCompositionAmountRecord, Ellipsis]

complete: bool

class httk.atomistic.storage.records.NormalizedCompositionAmountRecord

Represent one exact normalized composition ratio.

Parameters:

• element – The element symbol.

• ratio – The exact normalized element ratio.

• amount – The exact source element amount.

• precision – The source amount precision, if stated.

element: str

ratio: fractions.Fraction

amount: fractions.Fraction

precision: fractions.Fraction | None = None

class httk.atomistic.storage.records.CellRecord

Represent an exact durable cell basis, precision, and periodicity.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary.

Parameters:

• basis – The row-major exact cell basis values.

• precision – The absolute basis precision, if stated.

• periodicity – The flags identifying periodic basis rows.

basis: tuple[httk.core.SurdScalar, Ellipsis]

precision: fractions.Fraction | None

periodicity: tuple[bool, Ellipsis]

class httk.atomistic.storage.records.SitesRecord

Represent exact durable reduced coordinates and their stated precision.

Parameters:

• reduced_coords – The exact reduced coordinates, one site per row.

• precision – The fractional coordinate precision, if stated.

reduced_coords: Annotated[httk.core.FracVector, httk.core.storage.markers.Shape(0, 3)]

precision: fractions.Fraction | None

class httk.atomistic.storage.records.UnitcellStructureRecord

Represent the native durable backing for an explicit unit-cell structure.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook. The record’s content identity is independent of its storage layout.

Parameters:

• cell – The durable cell record.

• sites – The durable site-coordinate record.

• species – The distinct durable species records.

• species_at_sites – The species name occupying each site.

• normalized_composition – The authoritative normalized composition.

• charge – The explicitly assigned cell charge, if stated.

• site_moments_kind – The site-moment kind, if stated.

• site_moments – The flattened exact site-moment components, if stated.

• site_moments_precision – The site-moment precision, if stated.

• molecular – Whether the structure describes molecular entities.

• assemblies – The site assemblies, if stated.

• symmetry – The symmetry metadata, if stated.

• chemical_composition – The chemical composition declaration, if stated.

• chemical_formula_descriptive – The descriptive formula, if stated.

• chemical_formula_hill – The Hill formula, if stated.

• optimization_type – The optimization provenance, if stated.

• immutable_id – The immutable source identifier, if stated.

• last_modified – The source modification timestamp, if stated.

cell: CellRecord

sites: SitesRecord

species: tuple[SpeciesRecord, Ellipsis]

species_at_sites: tuple[str, Ellipsis]

normalized_composition: NormalizedCompositionRecord

charge: fractions.Fraction | None = None

site_moments_kind: str | None = None

site_moments: tuple[httk.core.SurdScalar, Ellipsis] | None = None

site_moments_precision: fractions.Fraction | None = None

molecular: bool = False

assemblies: tuple[AssemblyRecord, Ellipsis] | None = None

symmetry: SymmetryRecord | None = None

chemical_composition: ChemicalCompositionRecord | None = None

chemical_formula_descriptive: str | None = None

chemical_formula_hill: str | None = None

optimization_type: str | None = None

immutable_id: Annotated[str | None, IdentitySkip()] = None

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None

property type: str

Expose the OPTIMADE entry type.

Returns:

structures.

Return type:

str

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str

class httk.atomistic.storage.records.FundamentalDomainStructureRecord

Represent the native durable backing for a symmetry fundamental domain.

Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook. The record’s content identity is independent of its storage layout.

Parameters:

• cell – The durable cell record.

• domain_sites – The symmetry-distinct durable site records.

• species – The distinct durable species records.

• spacegroup_it_number – The International Tables space-group number.

• spacegroup_hall_entry – The setting that names the stored Wyckoff data.

• setting_transform – The stored-setting-to-own transform.

• coordinate_precision – The reduced-coordinate precision, if stated.

• normalized_composition – The authoritative normalized composition.

• charge – The explicitly assigned cell charge, if stated.

• molecular – Whether the structure describes molecular entities.

• assemblies – The site assemblies, if stated.

• chemical_composition – The chemical composition declaration, if stated.

• chemical_formula_descriptive – The descriptive formula, if stated.

• chemical_formula_hill – The Hill formula, if stated.

• optimization_type – The optimization provenance, if stated.

• immutable_id – The immutable source identifier, if stated.

• last_modified – The source modification timestamp, if stated.

cell: CellRecord

domain_sites: tuple[WyckoffSiteRecord, Ellipsis]

species: tuple[SpeciesRecord, Ellipsis]

spacegroup_it_number: int

spacegroup_hall_entry: str

setting_transform: SettingTransformRecord

coordinate_precision: fractions.Fraction | None

normalized_composition: NormalizedCompositionRecord

charge: fractions.Fraction | None = None

molecular: bool = False

assemblies: tuple[AssemblyRecord, Ellipsis] | None = None

chemical_composition: ChemicalCompositionRecord | None = None

chemical_formula_descriptive: str | None = None

chemical_formula_hill: str | None = None

optimization_type: str | None = None

immutable_id: Annotated[str | None, IdentitySkip()] = None

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None

property type: str

Expose the OPTIMADE entry type.

Returns:

structures.

Return type:

str

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str

class httk.atomistic.storage.records.ASUStructureRecord

Bases: FundamentalDomainStructureRecord

Represent the native durable backing for an asserted asymmetric unit.

Inherit the fundamental-domain constructor fields and validation contract while retaining the asymmetric-unit record identity.

property type: str

Expose the OPTIMADE entry type.

Returns:

structures.

Return type:

str

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str

class httk.atomistic.storage.records.ObservableSummaryRecord

Represent a bounded numeric summary for one trajectory observable.

Parameters:

• name – The observable name.

• first – The first finite value, if available.

• last – The last finite value, if available.

• minimum – The minimum finite value, if available.

• maximum – The maximum finite value, if available.

name: str

first: float | None = None

last: float | None = None

minimum: float | None = None

maximum: float | None = None

class httk.atomistic.storage.records.TrajectoryRecord

Represent bounded trajectory identity and reference-frame summary.

Frame data is never stored in this record. Hand-built records are shape-checked on construction and semantically validated at the storage boundary or explicitly through the validation hook.

Parameters:

• nframes – The total number of trajectory frames.

• species – The distinct durable species records.

• species_at_sites – The species name occupying each site.

• reference_frame_indexes – The sorted indexes of retained reference frames.

• reference_frame_structures – The retained reference-frame records.

• observable_summaries – The summaries of trajectory observables.

• source_locator – The source locator, if stated.

• immutable_id – The immutable source identifier, if stated.

• last_modified – The source modification timestamp, if stated.

nframes: int

species: tuple[SpeciesRecord, Ellipsis]

species_at_sites: tuple[str, Ellipsis]

reference_frame_indexes: tuple[int, Ellipsis]

reference_frame_structures: tuple[UnitcellStructureRecord, Ellipsis]

observable_summaries: tuple[ObservableSummaryRecord, Ellipsis]

source_locator: Annotated[str | None, IdentitySkip()] = None

immutable_id: Annotated[str | None, IdentitySkip()] = None

last_modified: Annotated[datetime.datetime | None, IdentitySkip()] = None

property type: str

Expose the OPTIMADE entry type.

Returns:

trajectories.

Return type:

str

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str

class httk.atomistic.storage.records.WyckoffOccupationRecord

Represent one occupied standard-setting Wyckoff orbit and its real species.

The occupation carries a real (possibly disordered) SpeciesRecord; it is the durable analogue of WyckoffOccupation.

Parameters:

• wyckoff – The Wyckoff letter in the standard setting.

• species – The durable real species occupying the orbit.

wyckoff: str

species: SpeciesRecord

class httk.atomistic.storage.records.ProtostructureRecord

Represent the durable backing for a geometry-free protostructure.

The record carries exactly the value identity of Protostructure: its standard-setting space group and its occupied Wyckoff positions with real species, in the protostructure’s canonical order (sorted by species name then Wyckoff letter). It has no cell or coordinates. The record’s content identity is independent of its storage layout, and two equal protostructures produce the same content identity.

Parameters:

• spacegroup_it_number – The International Tables space-group number.

• spacegroup_hall_entry – The standard-setting Hall entry that names the stored Wyckoff data.

• occupations – The occupied Wyckoff positions and their real species.

spacegroup_it_number: int

spacegroup_hall_entry: str

occupations: tuple[WyckoffOccupationRecord, Ellipsis]

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str

property label: str

Expose a compact, deterministic query label for this protostructure.

The format is "<it_number>/<wyckoff>:<species_name>,..." listing the occupations in the record’s stored canonical order. It is a convenience and query column only; it is not the record’s identity (the content id is), and it is NOT unique across distinct protostructures: species that share a name but differ in any other Species field (concentration, charges, spins, mass, precision, …) collide on the same label, so a GROUP BY label may under-count distinct protostructures — count and deduplicate by row (content id), never by label.

Returns:

The compact protostructure label.

Return type:

str

class httk.atomistic.storage.records.PrototypeRecord

Represent the durable backing for a standard-setting dummy-species prototype.

The record carries the geometric per-structure prototype: its standard-setting space group, its cell (surd-capable), the symmetry-distinct Wyckoff sites with their exact free parameters, and the distinct dummy species. Distinct prototypes with different free parameters are distinct values, so no content deduplication is expected; the content identity remains deterministic.

Parameters:

• cell – The durable standard-setting cell record.

• wyckoff_sites – The symmetry-distinct durable Wyckoff site records.

• species – The distinct durable dummy species records.

• spacegroup_it_number – The International Tables space-group number.

• spacegroup_hall_entry – The standard-setting Hall entry that names the stored Wyckoff data.

• coordinate_precision – The reduced-coordinate precision, if stated.

cell: CellRecord

wyckoff_sites: tuple[WyckoffSiteRecord, Ellipsis]

species: tuple[SpeciesRecord, Ellipsis]

spacegroup_it_number: int

spacegroup_hall_entry: str

coordinate_precision: fractions.Fraction | None = None

property id: str

Expose the layout-independent content identifier.

Returns:

The content identifier for this record.

Return type:

str