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 an assigned-species classification key.
`FundamentalDomainTemplateRecord`	Represent the durable backing for a standard-setting dummy-species fundamental domain.
`PrototypeRecord`	Represent the durable backing for an anonymous 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.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.
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¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

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

property type: str¶

Expose the OPTIMADE entry type.

Returns:: structures.
Return type:: str

class httk.atomistic.storage.records.FundamentalDomainStructureRecord¶

Represent the native durable backing for a symmetry fundamental domain.

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.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.
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¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

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

property type: str¶

Expose the OPTIMADE entry type.

Returns:: structures.
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

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.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.
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¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

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

property type: str¶

Expose the OPTIMADE entry type.

Returns:: trajectories.
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 an assigned-species classification key.

The record carries exactly the value identity of Protostructure: its standard-setting space group and its occupied Wyckoff positions with real species, in canonical order, plus an optional exact representative and/or discriminator. 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.
representative – The optional durable exact class anchor.
discriminator – The optional external class discriminator.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.

spacegroup_it_number: int¶

spacegroup_hall_entry: str¶

occupations: tuple[WyckoffOccupationRecord, Ellipsis]¶

representative: FundamentalDomainStructureRecord | None = None¶

discriminator: str | None = None¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

property label: str¶

Expose the httk protostructure label as a deterministic query column.

The label is the httk protostructure label ("AB_cF8_225_a_b:Na-Cl" for rocksalt): the prototype label of the erased template followed by : and the class species names. 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 httk protostructure label.
Return type:: str

class httk.atomistic.storage.records.FundamentalDomainTemplateRecord¶

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

The record carries the geometric per-structure fundamental-domain template: 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 templates 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.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.

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¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

class httk.atomistic.storage.records.PrototypeRecord¶

Represent the durable backing for an anonymous prototype.

The record carries anonymous class-partitioned Wyckoff occupations, plus an optional exact fundamental-domain-template representative and/or discriminator. Base-only values are valid. The discriminator is species-independent and is not part of the label.

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 anonymous class labels.
representative – The durable class representative, if one is held.
discriminator – The externally assigned class discriminator, if one is held.
id – The human-readable entry id shared by all revisions; minted by the store when None.
immutable_id – The per-revision immutable id; minted by the store when None.

spacegroup_it_number: int¶

spacegroup_hall_entry: str¶

occupations: tuple[httk.atomistic.models.prototype.occupation.PrototypeOccupation, Ellipsis]¶

representative: FundamentalDomainTemplateRecord | None = None¶

discriminator: str | None = None¶

id: Annotated[str | None, IdentitySkip(), Indexed()] = None¶

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

property label: str¶

Expose the httk prototype label as a deterministic query column.

The discriminator names the geometrical class and is not part of the label, so prototypes that share occupations but differ in class collide on this column; it is a convenience and query column only, not the record’s identity (the content id is).

Returns:: The httk prototype label.
Return type:: str