httk.atomistic.storage¶

Submodules¶

Classes¶

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

Package Contents¶

class httk.atomistic.storage.AssemblyGroupRecord[source]¶

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.AssemblyRecord[source]¶

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.ASUStructureRecord[source]¶

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.CellRecord[source]¶

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.ChemicalCompositionRecord[source]¶

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.CompositionAmountRecord[source]¶

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.FundamentalDomainStructureRecord[source]¶

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.NormalizedCompositionAmountRecord[source]¶

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.NormalizedCompositionRecord[source]¶

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.ObservableSummaryRecord[source]¶

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.ProtostructureRecord[source]¶

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.PrototypeRecord[source]¶

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

class httk.atomistic.storage.SettingTransformRecord[source]¶

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.SitesRecord[source]¶

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.SpeciesConstituentRecord[source]¶

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.SpeciesRecord[source]¶

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.SymmetryRecord[source]¶

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.TrajectoryRecord[source]¶

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.UnitcellStructureRecord[source]¶

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

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.WyckoffOccupationRecord[source]¶

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.WyckoffSiteRecord[source]¶

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¶