httk.atomistic¶

Provide crystal structure representations for httk v2.

Provides the UnitcellStructure domain and its component families (Cell, Sites, Species), each following the httk-core view/backend pattern. A UnitcellStructure holds a cell, a sites, a tuple of species, and a species_at_sites; each component has a class representation and a primitive representation convertible through views.

Crystal symmetry is modelled exactly over the rationals: Spacegroup carries a space-group setting with its symmetry operations and Wyckoff table, and SettingTransform relates any setting to the International Tables standard one, so a structure in an arbitrary non-standard setting can be represented without loss. The underlying tables ship in httk.atomistic.data.

Submodules¶

Attributes¶

`CellLike`
`SitesLike`
`SiteMomentsLike`
`SpeciesLike`
`StructureLike`
`TrajectoryLike`
`ChemicalFormulaLike`
`AnonymousStructureLike`
`PrototypeLike`
`ProtostructureLike`
`DEFAULT_TOLERANCE`

Classes¶

`Cell`	A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held exactly.
`CellParams`	Backend for a cell backed by cell parameters `(a, b, c, alpha, beta, gamma)`.
`CellParamsView`	A view presenting an underlying cell backend as cell parameters.
`CellView`	A view presenting an underlying cell backend as a `Cell`.
`Sites`	The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held exactly.
`SitesView`	A view presenting an underlying sites backend as a `Sites` object.
`CartesianSiteMoments`	Per-site Cartesian magnetic moments, exactly held in Bohr magnetons.
`CartesianSiteMomentsView`	A lazy Cartesian site-moments presentation of any site-moments backend.
`CollinearSiteMoments`	Signed per-site scalar moments with no assigned Cartesian axis.
`CrystalAxisSiteMoments`	Moments along the unit lattice axes `â`, `b̂`, `ĉ`, in Bohr magnetons.
`CrystalAxisSiteMomentsView`	A lazy crystal-axis site-moments presentation with an eagerly checked frame hint.
`PlainSpeciesView`	A view presenting an underlying species backend as an OPTIMADE species dict.
`Species`	A chemical species occupying one or more sites, mirroring the OPTIMADE `species` object.
`SpeciesView`	A view presenting an underlying species backend as a `Species`.
`ASEAtoms`	Import ASE `Atoms` and compatible duck-typed objects.
`ASEAtomsProtocol`	Describe the minimal method surface needed to read ASE `Atoms`.
`PymatgenStructure`	Import a pymatgen-compatible structure eagerly.
`PymatgenStructureProtocol`	The three native attributes that identify a pymatgen structure.
`VASPStructure`	Load a VASP POSCAR structure lazily.
`VASPTrajectory`	Read VASP OUTCAR and/or XDATCAR data lazily.
`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.
`ASUStructureView`	Present an underlying structure backend as a lazy `ASUStructure`.
`DatastreamStructure`	Represent a structure source parsed only when its data is first accessed.
`ModulatedStructure`	Retain raw mCIF data that standard structure classes cannot represent.
`NumericUnitcellStructureView`	A plain-numpy presentation of a `UnitcellStructure`.
`OptimadeStructure`	Represent an OPTIMADE structure resource as a lazy structure backend.
`PlainStructureView`	A view presenting an underlying structure backend as a primitive triple.
`StructureSymmetry`	Store optional, explicitly supplied symmetry metadata for a unit-cell structure.
`SymopsStructure`	Represent a magCIF cell, listed sites, and its complete symmetry-operation list.
`UnitcellStructure`	Represent a crystal structure in the Unitcell representation.
`UnitcellStructureView`	A view presenting an underlying structure backend as a `UnitcellStructure`.
`JsonlTrajectory`	Stream a neutral `httk-trajectory-jsonl` payload or path lazily.
`PlainTrajectory`	Represent a mapping whose structure properties have a frame axis.
`Trajectory`	Store an immutable trajectory in the native backend.
`TrajectoryView`	Present any trajectory backend through the canonical trajectory API.
`PlaneWaveFunctions`	Provide a zero-based, NumPy-native collection of plane-wave coefficients.
`StructureEntry`	Define the non-instantiable OPTIMADE structure entry family.
`StructureEntryProvider`	Serve complete OPTIMADE v1.3 structure records from atomistic structures.
`TrajectoryEntry`	Define the non-instantiable OPTIMADE trajectory entry family.
`TrajectoryEntryProvider`	Serve trajectory metadata and bounded frame projections.
`ASUStructureRecord`	Represent the native durable backing for an asserted asymmetric unit.
`FundamentalDomainStructureRecord`	Represent the native durable backing for a symmetry fundamental domain.
`ProtostructureRecord`	Represent the durable backing for a geometry-free protostructure.
`PrototypeRecord`	Represent the durable backing for a standard-setting dummy-species prototype.
`UnitcellStructureRecord`	Represent the native durable backing for an explicit unit-cell structure.
`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.
`AnonymousFormula`	Store a strictly canonical OPTIMADE anonymous chemical formula.
`AnonymousFormulaView`	Present a complete composition as an eager canonical anonymous formula.
`Composition`	Store an immutable projected composition and its formula diagnostics.
`CompositionView`	Present any chemical-formula backend as a lazy composition.
`ChemicalFormula`	Store a strictly canonical reduced chemical formula.
`ChemicalFormulaView`	Present a complete composition as an eager canonical reduced formula.
`AnonymousStructure`	Store a unit cell whose site identities are consecutive dummy labels.
`AnonymousStructureView`	Present an anonymous or ordinary structure lazily as an anonymous structure.
`Prototype`	Store a standard-setting fundamental domain with dummy species labels.
`PrototypeView`	Recognize a lazy standard-setting prototype view from a structure.
`WyckoffOccupation`	Store one Wyckoff orbit occupied by one possibly disordered species.
`Protostructure`	Store a standard-setting space group and its occupied Wyckoff positions.
`ProtostructureView`	Recognize a lazy standard-setting protostructure view.
`AffineOperation`	Represent an exact affine map `x -> W x + w` on fractional coordinates.
`SettingTransform`	Represent an exact rational change of basis from the IT standard setting.
`Spacegroup`	Represent a tabulated space-group setting from the vendored symmetry data.
`PrimitiveCellResult`	Store a structure in the fixed primitive cell of its conventional cell.
`ConventionalCellResult`	Store a structure in its space group's IT standard-setting conventional cell.
`SubgroupRepresentationResult`	Store an exact asymmetric-unit representation in a subgroup.
`LiftResult`	One exact or tolerance-accepted parent representation.
`StructurePath`	A finite exact interpolation path between two aligned asymmetric units.
`WyckoffPosition`	Represent a Wyckoff position of one space-group setting.
`Assembly`	Represent one site-disorder assembly without normalizing its probabilities.
`ChemicalComposition`	Store explicit elemental amounts as additional or authoritative composition.
`SupercellResult`	Store a materialized supercell with its exact construction metadata.
`NiggliReducedStructureResult`	Store a structure whose cell and fractional coordinates are in Niggli form.
`NiggliReductionResult`	Store a cell in exact Niggli-reduced form.

Functions¶

`same_crystal`(first, second)	Compare two structures as crystallographic descriptions.
`save_vesta`(basename, structure, wave, *[, cols])	Save real and imaginary wave components as VASP volumetric files.
`wavefunction_overlap`(phi1, phi2)	Return the complex overlap of two wavefunctions.
`validate_structure_record`(record)	Validate a hand-built root record against native structure semantics.
`recognize_asu`(structure, *[, setting, standard, ...])	Build an `ASUStructure` from a full structure.
`structure_tolerance`(structure, *[, fallback])	Derive a matching tolerance from how precisely the structure was stated.
`wyckoff_letter_map`(standard, target)	Map standard-setting Wyckoff letters to their names in another setting.
`primitive_cell`(structure, *[, tolerance, ...])	Return `structure` in the spglib-convention primitive cell.
`conventional_cell`(structure, *[, tolerance, ...])	Return `structure` in its space group's IT standard-setting conventional cell.
`maximal_subgroups`(spacegroup)	Return the distinct tabulated maximal-subgroup IT numbers.
`minimal_supergroups`(spacegroup)	Return the distinct tabulated minimal-supergroup IT numbers.
`subgroup_closure`(spacegroup, *[, include_self])	Return the graph-derived transitive subgroup closure.
`subgroup_representation`(structure, subgroup)	Express an exact ASU in a subgroup's IT standard setting.
`supergroup_closure`(spacegroup, *[, include_self])	Return the graph-derived transitive supergroup closure.
`canonical_asu`(structure, *[, tolerance, factors, lift])	Return the canonical `ASUStructure` of a measured structure's symmetry.
`backward_lift`(structure, supergroup, *[, tolerance])	Return all exact or tolerance-accepted lifts into one minimal supergroup.
`canonicalize`(structure, *[, tolerance])	Return the first deterministic highest-symmetry representation.
`highest_symmetry`(structure, *[, tolerance, all_paths])	Return all terminal upward lifts reached by breadth-first search.
`lift_candidates`(structure, *[, tolerance])	Return all one-hop parent lifts in deterministic order.
`rerepresent`(structure, target, *[, tolerance])	Express a structure in a reachable subgroup or supergroup setting.
`canonicalize_full`(structure, target, *[, tolerance])	Return the canonically least representation of a crystal in a target group's standard setting.
`interpolate_structures`(start, end, *, steps[, tolerance])	Build an exact symmetry-preserving linear interpolation.
`list_representations`(structure, target, *[, tolerance])	Return every distinct representation of one crystal in a target group's standard setting.
`represent_like`(structure, reference, *[, tolerance])	Represent a structure in a reference's group and setting.
`wyckoff_positions`(record)	Build the Wyckoff positions of a setting record, most specific first.
`asu_structure_from_cif`(data, *[, tolerance, ...])	Build an exact `ASUStructure` from a neutral CIF mapping.
`asu_structures_from_cif`(payload, *[, autocorrect])	Return every structure in a loaded CIF payload, one per structural data block.
`cif_setting`(data, *[, trust_declared_symmetry])	The space-group setting a CIF block is written in.
`atomic_number`(symbol)	Return the atomic number of an element symbol.
`symbol_of`(z)	Return the element symbol for an atomic number.
`build_supercell`(structure, transformation, *[, max_sites])	Build the exact supercell selected by an integer transformation matrix.
`cubic_supercell`(structure[, multiplier, tolerance, ...])	Build the most cubic supercell in the bounded candidate set.
`orthogonal_supercell`(structure[, multiplier, ...])	Build the most orthogonal supercell in the bounded candidate set.
`is_niggli_reduced`(cell)	Return whether a fully periodic cell satisfies the complete exact Niggli conditions.
`niggli_reduce`(cell)	Return the exact Niggli reduction of a fully periodic cell.
`niggli_reduced`(structure)	Return a structure remapped into the exact Niggli-reduced cell.

Package Contents¶

class httk.atomistic.Cell(basis, scale=1, precision=None, periodicity=None)[source]¶

Bases: httk.atomistic.models.cell.backend.CellBackend

A crystallographic cell: its basis, the 3x3 matrix of cell vectors, held exactly.

The lattice vectors are the rows of basis. Internally a Cell factors that basis into a positive SurdScalar scale times an unscaled_basis (a SurdVector of shape (3, 3)), with basis == scale * unscaled_basis. The split lets an overall length factor be carried symbolically: a hexagonal cell of lattice parameter a and ratio c/a is the exact unscaled rows (1, 0, 0), (-1/2, sqrt(3)/2, 0), (0, 0, c/a) scaled by a — so the sqrt(3) stays exact regardless of a. A cell built from an absolute basis simply has scale == 1.

Numbers embed exactly: rationals (and rational-valued floats) stay rational, and a SurdVector basis keeps its radicals. Derived quantities retain exact forms where the underlying operation stays in the supported exact fields, including the usual metric-rational crystallographic case: lengths use sqrt_of() for rational squared row lengths when the rational radicand is a perfect square or stays below the deterministic small-radicand threshold, angles (degrees) use the exact reverse-Niven acos_degrees() where possible, volume comes from the exact determinant, and metric is the exact Gram matrix, which may itself contain surds. For larger rational or irrational squared lengths, lengths/angles fall back to a deterministic rational approximation (documented per accessor). Exact accessors return vector objects — render them with .to_floats() (nested plain-float lists, numpy-free), float(...) on scalars, numeric() (true numpy arrays), or a view of your choice.

A cell also records its periodicity, which defaults to periodic in all three directions. Where it is not, the basis stops being purely a lattice and becomes partly a coordinate frame: see periodicity for what that means and periodic_measure for the quantity that replaces volume.

Parameters:

basis (httk.core.VectorLike) – The three cell vectors, one per row.
scale (Any) – The positive factor separated from basis.
precision (Any) – The absolute precision carried from the source, if known.
periodicity (Any) – Flags identifying which basis rows are lattice translations.

property scale: httk.core.SurdScalar¶

The overall (strictly positive) length factor.

Returns:: The factor applied to unscaled_basis.
Return type:: httk.core.SurdScalar

property unscaled_basis: httk.core.SurdVector¶

The 3x3 cell vectors before applying scale.

Returns:: The unscaled lattice vectors.
Return type:: httk.core.SurdVector

property basis: httk.core.SurdVector¶

The 3x3 lattice vectors scale * unscaled_basis.

Returns:: The scaled lattice vectors.
Return type:: httk.core.SurdVector

property precision: fractions.Fraction | None¶

How precisely this basis was stated, as an absolute length, or None if unknown.

In the same units as the basis itself, so for ordinary crystallographic data it is an ångström. Derived from the source’s written digits and any stated uncertainty — a CIF cell edge of 5.6402(3) is precise to 3e-4, not to the 1e-4 its four decimals alone would suggest.

None means unknown, which is not the same as exact. It is what a cell built by hand or from a bare matrix reports.

Returns:: The absolute precision, or None when it is unknown.
Return type:: fractions.Fraction | None

property periodicity: tuple[bool, bool, bool]¶

Which of the three basis rows is a genuine lattice translation.

(True, True, True) — the default, and what every ordinary crystal is. A slab is (True, True, False), a nanowire has one True, and an isolated molecule is (False, False, False).

A row flagged False is not a lattice vector. It is only a frame: it says what a fractional coordinate means along that direction, and nothing more. Coordinates there are unbounded — freely below 0 or above 1 — and are never wrapped into [0, 1). There is no vacuum and no padding involved, so making that row a unit vector simply means the coordinate along it is a length in the basis’s units.

This is the same notion, in the same order, as OPTIMADE’s dimension_types.

Returns:: Flags identifying the periodic basis rows.
Return type:: tuple[bool, bool, bool]

property nperiodic_dimensions: int¶

How many of the three directions are periodic.

Returns:: The number of periodic directions.
Return type:: int

numeric()[source]¶

Return a plain-numpy presentation of this cell.

Returns:: The numpy-backed presentation.
Raises:: ImportError – If numpy is unavailable.
Return type:: httk.atomistic.models.cell.numeric.NumericCell

metric()[source]¶

Return the exact, potentially surd-valued Gram matrix matrix * matrix^T.

Returns:: The Gram matrix of the cell vectors.
Return type:: httk.core.SurdVector

property lengths: tuple[httk.core.SurdScalar, Ellipsis]¶

The lengths of the three cell vectors (the scaled row norms).

Exact via sqrt_of() when the row’s squared length is a perfect-square rational or a rational with numerator times denominator at most 10**18. Larger rational radicands and irrational squared lengths use a deterministic rational approximation at _FALLBACK_PREC.

Returns:: The three cell-vector lengths.
Return type:: tuple[httk.core.SurdScalar, Ellipsis]

property angles: tuple[fractions.Fraction, Ellipsis]¶

The cell angles (alpha, beta, gamma) in degrees, as exact Fraction values.

Following the crystallographic convention, alpha is the angle between rows b and c, beta between a and c, and gamma between a and b. Angles are scale-independent, so they are computed from the unscaled basis. The cosine is formed exactly in the surd field and reversed through the Niven table (acos_degrees()) for an exact answer; a non-Niven angle falls back to a deterministic acos() at _FALLBACK_PREC.

Returns:: (alpha, beta, gamma) in degrees.
Return type:: tuple[fractions.Fraction, Ellipsis]

property volume: httk.core.SurdScalar¶

The cell volume, the exact absolute determinant of basis.

Defined only for a fully periodic cell, and raises ValueError otherwise. For anything less, the determinant mixes real lattice vectors with frame vectors, so it is not a volume: it changes when a frame vector is rescaled, even though nothing about the material did. Any density or packing fraction derived from it would inherit that. See periodic_measure for the quantity that is defined.

Returns:: The absolute determinant of the basis.
Raises:: ValueError – If the cell is not periodic in all three directions.
Return type:: httk.core.SurdScalar

property periodic_measure: httk.core.SurdScalar¶

The size of the repeating unit, whatever its dimension.

A volume for a crystal, an area for a slab, a length for a nanowire. For a fully non-periodic cell there is no repeating unit and this is the empty product, 1, which is dimensionless rather than a length of any kind.

Exact in the crystallographic case. The 3D case is the determinant and needs no square root at all; the 2D and 1D cases take the same square root that lengths does, so they are exact whenever the squared measure is a rational with a small radicand and fall back to a deterministic rational approximation otherwise.

Returns:: The measure of the periodic sublattice.
Return type:: httk.core.SurdScalar

type httk.atomistic.CellLike = httk.atomistic.models.cell.backend.CellBackend | httk.atomistic.models.cell.view_base.CellViewBase | httk.atomistic.models.cell.cell.Cell | httk.core.VectorLike[source]¶

class httk.atomistic.CellParams(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.backend.CellBackend

Backend for a cell backed by cell parameters (a, b, c, alpha, beta, gamma).

The native representation is a flat length-6 vector-like of the cell-vector lengths a/b/c and the angles alpha/beta/gamma in degrees, stored as exact Fraction values (parsed via any_to_fraction()). The exact basis is derived lazily and cached using the standard crystallographic orientation convention (first cell vector along x, second in the xy-plane); for the common Niven angles it is exact (radicals intact). Since parameters carry no separate length factor, scale is the exact 1 and unscaled_basis == basis. Parameters carry neither orientation nor periodicity, so a cell → parameters → cell round-trip reproduces lengths and angles, and reproduces volume only for a fully periodic source. Reconstruction uses the fully periodic default and therefore discards any non-3D periodicity as well as the original orientation. unwrap returns the original raw object.

Parameters:

obj (Any) – The six cell parameters in crystallographic order.
**hints (Any) – Backend-selection hints.

property basis: httk.core.SurdVector¶

Return the basis derived from the stored parameters.

Returns:: The standard-orientation cell vectors.
Return type:: httk.core.SurdVector

property scale: httk.core.SurdScalar¶

Return the unit scale factor.

Returns:: The factor applied to unscaled_basis.
Return type:: httk.core.SurdScalar

property unscaled_basis: httk.core.SurdVector¶

Return the parameter-derived basis before scaling.

Returns:: The cell vectors.
Return type:: httk.core.SurdVector

property lengths: tuple[httk.core.SurdScalar, Ellipsis]¶

Return the natively stored cell-vector lengths.

Returns:: The exact stored a, b, and c lengths.
Return type:: tuple[httk.core.SurdScalar, Ellipsis]

property angles: tuple[fractions.Fraction, Ellipsis]¶

Return the natively stored cell angles in degrees.

Returns:: The exact stored alpha, beta, and gamma angles.
Return type:: tuple[fractions.Fraction, Ellipsis]

property params: tuple[fractions.Fraction, Ellipsis]¶

The stored (a, b, c, alpha, beta, gamma) in degrees.

Returns:: The exact cell parameters.
Return type:: tuple[fractions.Fraction, Ellipsis]

unwrap()[source]¶

Return the original parameter object.

Returns:: The raw parameter representation.
Return type:: Any

class httk.atomistic.CellParamsView(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.view_base.CellViewBase, tuple

A view presenting an underlying cell backend as cell parameters.

This view is a genuine flat 6-tuple (a, b, c, alpha, beta, gamma) with the angles in degrees, built eagerly and immutable, with the elements also available as the named properties a/b/c/alpha/beta/gamma. Parameters carry no orientation, so converting a cell to parameters is lossy: reconstructing a cell from this view reproduces the lengths and angles, and reproduces volume only for a fully periodic source. The reconstruction inherits the fully periodic default, so this view discards the source periodicity as well as the original cell-vector orientation.

Parameters:

obj (httk.atomistic.models.cell.like.CellLike) – The cell-like object to present.
**hints (Any) – Backend-selection hints.

property a: float¶

The length of the first cell vector.

Returns:: The first vector length.
Return type:: float

property b: float¶

The length of the second cell vector.

Returns:: The second vector length.
Return type:: float

property c: float¶

The length of the third cell vector.

Returns:: The third vector length.
Return type:: float

property alpha: float¶

The angle between the second and third cell vectors, in degrees.

Returns:: The alpha angle.
Return type:: float

property beta: float¶

The angle between the first and third cell vectors, in degrees.

Returns:: The beta angle.
Return type:: float

property gamma: float¶

The angle between the first and second cell vectors, in degrees.

Returns:: The gamma angle.
Return type:: float

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the presented parameters as a plain tuple.

Returns:: The six cell parameters.
Return type:: tuple[float, Ellipsis]

class httk.atomistic.CellView(obj, **hints)[source]¶

Bases: httk.atomistic.models.cell.view_base.CellViewBase, httk.atomistic.models.cell.cell.Cell

A view presenting an underlying cell backend as a Cell.

This view is a genuine Cell, so it can be passed anywhere a Cell is accepted. Its state is built lazily on first access from the backend.

Parameters:

obj (httk.atomistic.models.cell.like.CellLike) – The cell-like object to present.
**hints (Any) – Backend-selection hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return this presentation as a standalone cell.

Returns:: The exact cell representation.
Return type:: httk.atomistic.models.cell.cell.Cell

type httk.atomistic.SitesLike = httk.atomistic.models.sites.backend.SitesBackend | httk.atomistic.models.sites.view_base.SitesViewBase | httk.atomistic.models.sites.sites.Sites | httk.core.VectorLike[source]¶

class httk.atomistic.Sites(reduced_coords, precision=None)[source]¶

Bases: httk.atomistic.models.sites.backend.SitesBackend

The sites of a crystal structure: the Nx3 matrix of reduced coordinates, held exactly.

Reduced (fractional) coordinates are the symmetry-native frame: point-group operations are integer matrices and translations are rationals, so no radicals ever appear. They are therefore stored as an exact rational FracVector of shape (N, 3). A Sites object is iterable and indexable over its length-3 coordinate rows (each a FracVector), with len giving the number of sites.

Inputs embed exactly: rationals (and rational-valued floats), rational strings, and numpy arrays all land on their exact rational value. An irrational SurdVector input is rejected; the exact Cartesian frame — where radicals belong — is obtained instead via cartesian_sites().

Parameters:

reduced_coords (httk.core.VectorLike) – The reduced coordinates, one site per row.
precision (Any) – The fractional precision carried from the source, if known.

property reduced_coords: httk.core.FracVector¶

The Nx3 reduced site coordinates as an exact FracVector (one site per row).

property precision: fractions.Fraction | None¶

How precisely these coordinates were stated, in fractional units, or None.

Fractional and therefore dimensionless: reduced coordinates are fractions of a cell edge, and a Sites carries no cell to convert with. Use cartesian_precision() for the corresponding length, which is the number an interatomic tolerance or an spglib symprec actually wants.

It is the coarsest precision among the coordinates, since a structure is only as precisely stated as its least precisely stated number. None means unknown.

Returns:: The fractional precision, or None when unknown.
Return type:: fractions.Fraction | None

numeric()[source]¶

Return a plain-numpy presentation of these sites.

Returns:: The numpy-backed presentation.
Raises:: ImportError – If numpy is unavailable.
Return type:: httk.atomistic.models.sites.numeric.NumericSites

class httk.atomistic.SitesView(obj, **hints)[source]¶

Bases: httk.atomistic.models.sites.view_base.SitesViewBase, httk.atomistic.models.sites.sites.Sites

A view presenting an underlying sites backend as a Sites object.

This view is a genuine Sites, so it can be passed anywhere a Sites is accepted. Its state is built lazily on first access from the backend.

Parameters:

obj (httk.atomistic.models.sites.like.SitesLike) – The sites-like object to present.
**hints (Any) – Backend-selection hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return this presentation as standalone exact sites.

Returns:: The exact sites representation.
Return type:: httk.atomistic.models.sites.sites.Sites

class httk.atomistic.CartesianSiteMoments(moments, precision=None)[source]¶

Bases: httk.atomistic.models.moments.backend.SiteMomentsBackend

Per-site Cartesian magnetic moments, exactly held in Bohr magnetons.

kind = 'cartesian'¶

property cartesian_moments: httk.core.SurdVector¶

The exact Nx3 Cartesian moments, one row per site.

property precision: fractions.Fraction | None¶

How precisely the moments were stated, in Bohr magnetons, or None.

Concrete rather than abstract, so a backend with no source of precision inherits None instead of breaking.

class httk.atomistic.CartesianSiteMomentsView(obj, **hints)[source]¶

Bases: httk.atomistic.models.moments.view_base.SiteMomentsViewBase, httk.atomistic.models.moments.cartesian.CartesianSiteMoments

A lazy Cartesian site-moments presentation of any site-moments backend.

unview()[source]¶

Return the view’s presented representation as a plain, non-View instance.

Concrete views that mimic a value type override this to shed the httk wrapper; the result may alias the view’s storage (no copy is promised). The default raises TypeError, which is the correct behavior for views that only adapt an interface and have no faithful standalone value.

Returns:: The presented value as a plain, non-View instance.
Raises:: TypeError – If this interface-only view has no standalone plain value.
Return type:: httk.atomistic.models.moments.cartesian.CartesianSiteMoments

class httk.atomistic.CollinearSiteMoments(moments, precision=None)[source]¶

Bases: httk.atomistic.models.moments.backend.SiteMomentsBackend

Signed per-site scalar moments with no assigned Cartesian axis.

kind = 'collinear'¶

property collinear_moments: httk.core.FracVector¶

The exact signed scalar moment for each site.

property cartesian_moments: httk.core.SurdVector¶

property precision: fractions.Fraction | None¶

How precisely the moments were stated, in Bohr magnetons, or None.

Concrete rather than abstract, so a backend with no source of precision inherits None instead of breaking.

class httk.atomistic.CrystalAxisSiteMoments(moments, cell, precision=None)[source]¶

Bases: httk.atomistic.models.moments.backend.SiteMomentsBackend

Moments along the unit lattice axes â, b̂, ĉ, in Bohr magnetons.

kind = 'crystalaxis'¶

property crystalaxis_moments: httk.core.SurdVector¶

The exact Nx3 moments along the cell’s unit lattice axes.

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

The cell defining the crystal-axis frame.

property cartesian_moments: httk.core.SurdVector¶

The exact Cartesian moments, using rows moments * U.

property precision: fractions.Fraction | None¶

How precisely the moments were stated, in Bohr magnetons, or None.

Concrete rather than abstract, so a backend with no source of precision inherits None instead of breaking.

class httk.atomistic.CrystalAxisSiteMomentsView(obj, *, cell=None, **hints)[source]¶

Bases: httk.atomistic.models.moments.view_base.SiteMomentsViewBase, httk.atomistic.models.moments.crystalaxis.CrystalAxisSiteMoments

A lazy crystal-axis site-moments presentation with an eagerly checked frame hint.

unview()[source]¶

Return the view’s presented representation as a plain, non-View instance.

Returns:: The presented value as a plain, non-View instance.
Raises:: TypeError – If this interface-only view has no standalone plain value.
Return type:: httk.atomistic.models.moments.crystalaxis.CrystalAxisSiteMoments

type httk.atomistic.SiteMomentsLike = httk.atomistic.models.moments.backend.SiteMomentsBackend | httk.atomistic.models.moments.view_base.SiteMomentsViewBase[source]¶

type httk.atomistic.SpeciesLike = httk.atomistic.models.species.backend.SpeciesBackend | httk.atomistic.models.species.view_base.SpeciesViewBase | httk.atomistic.models.species.species.Species | dict[str, Any] | str | int[source]¶

class httk.atomistic.PlainSpeciesView(obj, **hints)[source]¶

Bases: httk.atomistic.models.species.view_base.SpeciesViewBase, dict

A view presenting an underlying species backend as an OPTIMADE species dict.

This view is a genuine dict carrying the OPTIMADE species fields (optional fields that are None are omitted; list-valued fields are plain lists). Unlike the immutable-subclass views, a dict is mutable, so this view is a detached copy: mutating it does not affect the underlying backend.

Parameters:

obj (httk.atomistic.models.species.like.SpeciesLike) – The species-like object to present.
**hints (Any) – Backend-selection hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the presented species as a plain mapping.

Returns:: The detached presentation mapping.
Return type:: dict[str, Any]

class httk.atomistic.Species(name, chemical_symbols, concentration, mass=None, original_name=None, attached=None, nattached=None, concentration_precision=None, charges=None, spins=None, labels=None)[source]¶

Bases: httk.atomistic.models.species.backend.SpeciesBackend

A chemical species occupying one or more sites, mirroring the OPTIMADE species object.

A species has a name (unique within a structure; it need not be a chemical symbol), a list of chemical_symbols composing it, and a matching list of concentration values. Each chemical symbol is an element symbol, or one of the pseudo-symbols "X" (unknown) or "vacancy". The optional mass, attached, nattached, and original_name fields carry the remaining OPTIMADE species information; attached and nattached must be given together and share their length.

charges, spins, and labels are optional aligned decorations. An all-None decoration is canonicalized to None. Repeated chemical symbols are accepted only when the complete decoration distinguishes them.

Parameters:

name (str) – The species name.
chemical_symbols (collections.abc.Sequence[str]) – The constituent chemical symbols.
concentration (collections.abc.Sequence[ExactInput]) – The constituent occupancies.
mass (collections.abc.Sequence[float | int] | None) – The constituent masses, if stated.
original_name (str | None) – The source name, if stated.
attached (collections.abc.Sequence[str] | None) – The attached constituent symbols, if stated.
nattached (collections.abc.Sequence[int] | None) – The counts corresponding to attached, if stated.
concentration_precision (collections.abc.Sequence[PrecisionInput] | None) – The precision of each occupancy, if stated.
charges (collections.abc.Sequence[DecorationInput] | None) – The charge decoration, if stated.
spins (collections.abc.Sequence[DecorationInput] | None) – The spin decoration, if stated.
labels (collections.abc.Sequence[str | None] | None) – The label decoration, if stated.

name: str = ''¶

chemical_symbols: tuple[str, Ellipsis] = ()¶

concentration: tuple[fractions.Fraction, Ellipsis] = ()¶

mass: tuple[float, Ellipsis] | None = None¶

original_name: str | None = None¶

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

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

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

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

Assigned charge numbers for the constituents, or None if unstated.

A None element means the charge of that constituent is unstated; whole- None means no constituent charges are stated. Values use elementary-charge units, for example a formal oxidation state.

Returns:: The constituent charges, or None when unstated.

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

Idealized signed spins assigned to the constituents, or None if unstated.

A None element means the spin of that constituent is unstated; whole-None means no constituent spins are stated. This is distinct from a calculated site magnetic moment.

Returns:: The constituent spins, or None when unstated.

labels: tuple[str | None, Ellipsis] | None = None¶

Free-form per-constituent labels, or None if unstated.

A None element means that constituent has no stated label; whole-None means no constituent labels are stated.

Returns:: The constituent labels, or None when unstated.

property normalized: bool¶

Whether the stated concentration interval contains one.

Returns:: Whether the concentrations are normalized within their precision.
Return type:: bool

property normalization_status: str¶

Report the concentration normalization status.

Returns:: exact, within_precision, or outside_precision.
Return type:: str

property normalization_diagnostic: Any¶

Return a structured normalization diagnostic when needed.

Returns:: The diagnostic, or None when the concentrations are normalized.
Return type:: Any

property is_single_element: bool¶

Whether this species is a single, unattached, real chemical element.

True only for a species composed of exactly one element symbol (not "X" or "vacancy") with no attached particles. Such species are the ones that can be represented as a bare atomic number in the primitive representation.

Returns:: Whether this is a single real element.
Return type:: bool

without_charges()[source]¶

Return an EXPLICIT lossy projection that drops declared oxidation states.

The other species fields, including spins and labels, are preserved. A species without declared charges is returned by identity.

Returns:: A charge-free species, or this species when already charge-free.
Return type:: Species

classmethod from_object(obj, **hints)[source]¶

Return a Species from an existing Species, bare symbol or atomic number, or OPTIMADE species dict.

A bare element symbol, "X", or "vacancy" denotes a fully occupied single-symbol species. A bare atomic number denotes the corresponding element.

Parameters:

obj (Species | dict[str, Any] | str | int) – An existing species, symbol, atomic number, or species mapping.
**hints (Any) – Backend-selection hints.

Returns:

The canonical species.

Raises:

ValueError – If an atomic number is boolean or the input is invalid.

Return type:

Species

class httk.atomistic.SpeciesView(obj, **hints)[source]¶

Bases: httk.atomistic.models.species.view_base.SpeciesViewBase, httk.atomistic.models.species.species.Species

A view presenting an underlying species backend as a Species.

This view is a genuine frozen Species, so it can be passed anywhere a Species is accepted. Its fields are built eagerly from the backend on construction, with full Species validation applied at that point.

Parameters:

obj (httk.atomistic.models.species.like.SpeciesLike) – The species-like object to present.
**hints (Any) – Backend-selection hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return this presentation as standalone species.

Returns:: The exact species representation.
Return type:: httk.atomistic.models.species.species.Species

class httk.atomistic.ASEAtoms(obj, **hints)[source]¶

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

Import ASE Atoms and compatible duck-typed objects.

Conversion is eager because reading the four methods and normalizing their values is real work. The original object remains available through unwrap().

Initial magnetic moments become site moments and nonzero initial charges become charged single-element species. All-zero ASE defaults remain unstated.

Parameters:

obj (ASEAtomsProtocol) – An ASE Atoms object or compatible duck-typed object.
**hints (Any) – Backend-selection hints.

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

Return the exact cell converted from native cell rows.

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

Return the exact reduced coordinates converted from native positions.

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

Return distinct single-element species in first-appearance order.

property species_at_sites: tuple[str, Ellipsis]¶

Return the species name occupying each site.

property site_moments: Any¶

Return per-site moments, or None for absent and all-zero ASE defaults.

unwrap()[source]¶

Return the original Atoms-like object.

class httk.atomistic.ASEAtomsProtocol[source]¶

Bases: Protocol

Describe the minimal method surface needed to read ASE Atoms.

This is a runtime-checkable, duck-typed protocol. ASE is not required: any object providing these four methods qualifies for ASEAtoms.

get_cell()[source]¶

Return the cell vectors as rows.

Returns:: The native cell rows.
Return type:: Any

get_scaled_positions()[source]¶

Return the reduced positions.

Returns:: One reduced coordinate row per site.
Return type:: Any

get_atomic_numbers()[source]¶

Return one atomic number per site.

Returns:: The atomic numbers.
Return type:: Any

get_pbc()[source]¶

Return one periodicity flag per cell row.

Returns:: The periodicity flags.
Return type:: Any

class httk.atomistic.PymatgenStructure(obj, **hints)[source]¶

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

Import a pymatgen-compatible structure eagerly.

Pymatgen properties, site labels, and site properties other than magmom are intentionally discarded because they have no exact httk structure-family counterpart. Pymatgen DummySpecies values with the default zero oxidation state are imported with an unstated charge because pymatgen cannot distinguish that default from an explicitly supplied zero; nonzero dummy oxidation states remain exact charges.

Partial occupancy and its exact Fraction values are retained. An occupancy shortfall becomes an explicit vacancy constituent, which views omit when exporting to pymatgen. The original object remains available through unwrap().

Parameters:

obj (PymatgenStructureProtocol) – A pymatgen Structure object or compatible duck-typed object.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'pymatgen'¶

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

Return the converted cell and periodicity.

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

Return the converted reduced coordinates.

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

Return the imported distinct species and occupancies.

property species_at_sites: tuple[str, Ellipsis]¶

Return the imported species name at each site.

property site_moments: Any¶

Return imported collinear or Cartesian site moments, if present.

property charge: fractions.Fraction | None¶

Return the exact structure charge, or None when unstated.

unwrap()[source]¶

Return the original pymatgen-compatible object.

class httk.atomistic.PymatgenStructureProtocol[source]¶

Bases: Protocol

The three native attributes that identify a pymatgen structure.

lattice supplies the cell and periodicity, frac_coords supplies the reduced coordinates, and species_and_occu supplies one per-site composition mapping. This small surface is disjoint from ASE Atoms and httk structure objects while allowing pymatgen-compatible duck-typed inputs without importing pymatgen.

lattice: Any¶

frac_coords: Any¶

species_and_occu: Any¶

class httk.atomistic.VASPStructure(obj, **hints)[source]¶

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

Load a VASP POSCAR structure lazily.

This backend is explicitly constructed because a generic structure source should not silently claim every POSCAR path.

It is not registered in backend_classes. Constructing it from a view whose unwrapped value is already a VASPStructure returns that backend by identity. The payload’s raw channel preserves the source representation for byte-exact saving.

Parameters:

obj (Any) – A POSCAR path, neutral payload, or serializer-supported source.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'vasp'¶

property payload: collections.abc.Mapping[str, Any]¶

Return the original, loaded, or synthesized neutral POSCAR payload.

property comment: Any¶

Return the POSCAR comment, if present.

property selective_dynamics: Any¶

Return selective-dynamics flags, if present.

resolve()[source]¶

Build and memoize the canonical structure from the POSCAR payload.

Returns:: The resolved unit-cell structure.
Return type:: httk.atomistic.models.structure.unitcell.UnitcellStructure

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

Return the resolved cell.

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

Return the resolved reduced coordinates.

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

Return the resolved distinct species.

property species_at_sites: tuple[str, Ellipsis]¶

Return the resolved species name at each site.

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

Return resolved site moments, or None.

property charge: Any¶

Return the resolved structure charge, if present.

unwrap()[source]¶

Return the original POSCAR source.

class httk.atomistic.VASPTrajectory(source, **hints)[source]¶

Bases: httk.atomistic.models.trajectory.backend.TrajectoryBackend

Read VASP OUTCAR and/or XDATCAR data lazily.

XDATCAR supplies geometry when present. OUTCAR observables use the per-frame energy_sigma0, parsed as a float, plus temperature and stress_gpa_voigt(). One bounded pass caches those three scalar/6-tuple sequences; frame geometry is never cached.

XDATCAR geometry is preferred when both files are available. Cartesian coordinates are reduced exactly against the frame cell. A mismatch between OUTCAR and XDATCAR frame counts raises an error.

Parameters:

source (Any) – A VASP trajectory path, directory, payload, or VASP-outputs-like object.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'vasp'¶

property nframes: int¶

Return the validated number of frames.

property species: tuple[Any, Ellipsis]¶

Return the composition inferred from POSCAR, XDATCAR, or OUTCAR.

property species_at_sites: tuple[str, Ellipsis]¶

Return the species name at each site.

property reference_frames: None¶

Return None because VASP frames are not bounded references.

frame(i)[source]¶

Read one VASP frame by index.

Parameters:

i (int) – Frame index; negative indexes count from the end.

Returns:

The requested unit-cell structure.

Raises:

IndexError – If the frame index is out of range.
ValueError – If the source has no complete frame geometry.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Stream VASP frame geometry without caching full frames.

Yields:: Unit-cell structures in source order.

property observable_names: tuple[str, Ellipsis]¶

Return available OUTCAR observable names.

observable(name)[source]¶

Return one OUTCAR observable in frame order.

Parameters:: name (str) – Observable name.
Returns:: The observable values.
Raises:: KeyError – If the observable is unavailable.
Return type:: tuple[Any, Ellipsis]

unwrap()[source]¶

Return the original VASP trajectory source.

property source_locator: str | None¶

Return the source path, if one is available.

class httk.atomistic.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.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:

cell (httk.atomistic.models.cell.like.CellLike) – The cell in the structure’s own setting.
spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The setting that names the stored Wyckoff data.
wyckoff_sites (collections.abc.Sequence[WyckoffSite]) – The symmetry-distinct site definitions.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike]) – The species referenced by the site definitions.
transform (httk.atomistic.symmetry.setting_transform.SettingTransform | None) – The change of basis from the stored setting to the structure’s setting.
coordinate_precision (Any) – The precision recorded for the reduced coordinates.
molecular (bool) – Whether the structure describes molecular entities.
assemblies (collections.abc.Sequence[Any] | None) – Optional correlations among domain sites.
chemical_composition (Any) – Optional chemical composition metadata.
chemical_formula_descriptive (str | None) – Optional descriptive chemical formula.
chemical_formula_hill (str | None) – Optional Hill chemical formula.
optimization_type (str | None) – Optional optimization provenance.
immutable_id (str | None) – Optional immutable source identifier.
last_modified (datetime.datetime | None) – Optional source modification timestamp.
charge (fractions.Fraction | int | str | None) – An explicitly assigned charge for the expanded cell content; it is not derived from the species.
_validated_proof (_ValidatedASUProof | None) – Internal proof that the supplied CIF expansion already validates the representatives.

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.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.ASUStructureView(obj, *, setting=None, standard=None, transform=None, tolerance=None, immutable_id=_METADATA_UNSET, last_modified=_METADATA_UNSET, **hints)[source]¶

Bases: httk.atomistic.models.structure.view.StructureView, httk.atomistic.models.structure.asu.ASUStructure

Present an underlying structure backend as a lazy ASUStructure.

Resolver-backed and non-native sources are retained without recognition until the first asymmetric-unit access. The view then publishes the complete validated ASU state on itself, so its inherited API remains the genuine ASUStructure interface. Pickling retains the source backend and view options; once resolved, it also retains the validated derived ASU state while preserving that backend as the source returned by unwrap().

Parameters:

obj (httk.atomistic.models.structure.like.StructureLike) – The structure backend or source to recognize and present.
setting (httk.atomistic.symmetry.spacegroup.Spacegroup | None) – The source structure’s tabulated space-group setting.
standard (httk.atomistic.symmetry.spacegroup.Spacegroup | None) – The IT-standard space group for an untabulated setting.
transform (httk.atomistic.symmetry.setting_transform.SettingTransform | None) – The standard-to-source setting transform.
tolerance (float | None) – The Cartesian recognition tolerance.
immutable_id (str | None | object) – The optional immutable source identifier override.
last_modified (Any) – The optional source modification timestamp override.
**hints (Any) – Backend-selection and reader hints.

resolve()[source]¶

Resolve and return the complete standalone asymmetric unit.

unwrap()[source]¶

Return the original source without resolving it.

unview()[source]¶

Return the resolved standalone asymmetric-unit structure.

property sites: Any¶

Expose the representative sites retained by the asymmetric-unit view.

property species_at_sites: tuple[str, Ellipsis]¶

Expose species names for the representative sites retained by the view.

property assemblies: Any¶

Expose correlations among the retained domain sites.

property asu: httk.atomistic.models.structure.asu.FundamentalDomainStructure¶

Expose this view as its own resolved fundamental domain.

httk.atomistic.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:

first (httk.atomistic.models.structure.like.StructureLike) – The first structure-like value.
second (httk.atomistic.models.structure.like.StructureLike) – The second structure-like value.

Returns:

Whether the structures describe the same crystal.

Return type:

bool

class httk.atomistic.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.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.ModulatedStructure(payload)[source]¶

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

Retain raw mCIF data that standard structure classes cannot represent.

Future magnetic-structure support may interpret the modulation. Standard structure properties raise ValueError; the immutable source mapping remains available through payload.

Parameters:: payload (collections.abc.Mapping[str, Any]) – The raw mCIF data to retain.

kind: ClassVar[str] = 'modulated-mcif'¶

property payload: collections.abc.Mapping[str, Any]¶

Expose the immutable raw mCIF payload.

Returns:: The source mapping.
Return type:: collections.abc.Mapping[str, Any]

property mod_dim: Any¶

Expose the incommensurate modulation dimension when supplied.

Returns:: The raw mod_dim value, or None when absent.
Return type:: Any

property structural_q: Any¶

Expose the structural modulation vector when supplied.

Returns:: The raw structural_q value, or None when absent.
Return type:: Any

property magnetic_q: Any¶

Expose the magnetic modulation vector when supplied.

Returns:: The raw magnetic_q value, or None when absent.
Return type:: Any

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

Reject projection to a standard cell.

Raises:: ValueError – Always, because modulation is not representable here.

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

Reject projection to standard sites.

Raises:: ValueError – Always, because modulation is not representable here.

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

Reject projection to standard species.

Raises:: ValueError – Always, because modulation is not representable here.

property species_at_sites: tuple[str, Ellipsis]¶

Reject projection to standard site species.

Raises:: ValueError – Always, because modulation is not representable here.

property site_moments: Any¶

Reject projection to standard site moments.

Raises:: ValueError – Always, because modulation is not representable here.

class httk.atomistic.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:

obj (httk.atomistic.models.structure.like.StructureLike) – The structure backend or source to present.
**hints (Any) – Backend-selection hints passed to structure coercion.

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

obj (httk.core.optimade.OptimadeResource | None) – The OPTIMADE resource to retain.
**hints (Any) – Backend-selection hints, including optional resource or kind.

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

obj (httk.atomistic.models.structure.like.StructureLike) – The structure backend or source to present.
**hints (Any) – Backend-selection hints passed to structure coercion.

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

class httk.atomistic.SymopsStructure(cell, sites, species, species_at_sites, symops, *, site_moments=None, bns_number=None, bns_label=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 magCIF cell, listed sites, and its complete symmetry-operation list.

The operations are taken as declared. They are not checked for group closure: magCIF lists complete coset representatives, and an incomplete list consequently under-expands. Expansion is exact and deduplicates only by normalized fractional coordinates, species, and exact transformed moments.

Parameters:

cell (httk.atomistic.models.cell.like.CellLike) – The cell geometry.
sites (httk.atomistic.models.sites.like.SitesLike) – The listed site coordinates.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike]) – The distinct species definitions.
species_at_sites (collections.abc.Sequence[str]) – The species name occupying each listed site.
symops (collections.abc.Sequence[str | httk.atomistic.symmetry.affine_operation.AffineOperation | tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, int]]) – The declared spatial or magnetic symmetry operations.
site_moments (httk.atomistic.models.moments.like.SiteMomentsLike | None) – Optional moments aligned with the listed sites.
bns_number (str | None) – Optional Belov–Neronova–Smirnova number.
bns_label (str | None) – Optional Belov–Neronova–Smirnova label.
chemical_composition (Any) – Optional chemical composition metadata.
chemical_formula_descriptive (str | None) – Optional descriptive chemical formula.
chemical_formula_hill (str | None) – Optional Hill chemical formula.
optimization_type (str | None) – Optional optimization provenance.
immutable_id (str | None) – Optional immutable source identifier.
last_modified (datetime.datetime | None) – Optional source modification timestamp.
charge (fractions.Fraction | int | str | None) – An explicitly assigned charge for the cell content.

Raises:

TypeError – If an input component or magnetic label has the wrong kind.
ValueError – If component lengths, operations, or semantic values are invalid.

kind: ClassVar[str] = 'symops'¶

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

Expose the cell geometry.

Returns:: The exact cell.
Return type:: httk.atomistic.models.cell.cell.Cell

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

Expose the sites before symmetry expansion.

Returns:: The listed site coordinates.
Return type:: httk.atomistic.models.sites.sites.Sites

property listed_species_at_sites: tuple[str, Ellipsis]¶

Expose species names before symmetry expansion.

Returns:: Listed site species names in input order.
Return type:: tuple[str, Ellipsis]

property listed_site_moments: httk.atomistic.models.moments.backend.SiteMomentsBackend | None¶

Expose moments before symmetry expansion.

Returns:: Listed site moments, or None when unstated.
Return type:: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

property symops: tuple[tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, int], Ellipsis]¶

Expose normalized spatial and time-reversal operations.

Returns:: Operation and time-reversal pairs in declaration order.
Return type:: tuple[tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, int], Ellipsis]

property bns_number: str | None¶

Expose the Belov–Neronova–Smirnova number.

Returns:: The BNS number, or None when unstated.
Return type:: str | None

property bns_label: str | None¶

Expose the Belov–Neronova–Smirnova label.

Returns:: The BNS label, or None when unstated.
Return type:: str | None

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

Expose the distinct species.

Returns:: Species referenced by the listed sites.
Return type:: tuple[httk.atomistic.models.species.species.Species, Ellipsis]

property coordinate_precision: Any¶

Expose the listed-coordinate precision.

Returns:: The fractional coordinate precision.
Return type:: Any

property basis_precision: Any¶

Expose the cell-basis precision.

Returns:: The basis precision.
Return type:: Any

property periodicity: tuple[bool, bool, bool]¶

Expose the cell periodicity flags.

Returns:: Periodicity flags for the three cell directions.
Return type:: tuple[bool, bool, bool]

property molecular: bool¶

Expose whether the structure is molecular.

Returns:: Always False for this backend.
Return type:: bool

property site_coordinate_span: str¶

Expose the coordinate span of the listed sites.

Returns:: "unit_cell".
Return type:: str

property charge: fractions.Fraction | None¶

Expose the explicitly assigned charge.

Returns:: The charge, or None when unstated.
Return type:: fractions.Fraction | None

cartesian_sites()[source]¶

Compute exact Cartesian positions for the expanded sites.

Returns:: Cartesian positions in the exact surd representation.
Return type:: httk.core.SurdVector

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

Expose the symmetry-expanded sites.

Returns:: Expanded site coordinates.
Return type:: httk.atomistic.models.sites.sites.Sites

property species_at_sites: tuple[str, Ellipsis]¶

Expose species names for the expanded sites.

Returns:: Expanded site species names in site order.
Return type:: tuple[str, Ellipsis]

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

Expose moments transformed onto the expanded sites.

Returns:: Expanded site moments, or None when moments were unstated.
Return type:: httk.atomistic.models.moments.backend.SiteMomentsBackend | None

class httk.atomistic.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:

cell (httk.atomistic.models.cell.like.CellLike) – The unit-cell geometry.
sites (httk.atomistic.models.sites.like.SitesLike) – The reduced coordinates of the sites.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The distinct species definitions. Omit this to infer them from species_at_sites.
species_at_sites (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The species name occupying each site; this value is required.
site_moments (httk.atomistic.models.moments.like.SiteMomentsLike | None) – Optional magnetic moments aligned with the sites.
molecular (bool) – Whether the structure describes a molecular unit cell.
assemblies (collections.abc.Sequence[httk.atomistic.composition.Assembly] | None) – Optional correlations among sites.
symmetry (httk.atomistic.models.structure.semantics.StructureSymmetry | None) – Optional symmetry metadata.
chemical_composition (ChemicalComposition | None) – Optional chemical composition metadata.
chemical_formula_descriptive (str | None) – Optional descriptive chemical formula.
chemical_formula_hill (str | None) – Optional Hill chemical formula.
optimization_type (str | None) – Optional optimization provenance.
immutable_id (str | None) – Optional immutable source identifier.
last_modified (datetime.datetime | None) – Optional source modification timestamp.
charge (fractions.Fraction | int | str | None) – An explicitly assigned charge for the cell content; it is not derived from the species, and an explicit zero remains distinct from an unstated charge.

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

obj (httk.atomistic.models.structure.like.StructureLike) – The structure backend or source to present.
**hints (Any) – Backend-selection and metadata options passed to construction.

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.JsonlTrajectory(source, **hints)[source]¶

Bases: httk.atomistic.models.trajectory.backend.TrajectoryBackend

Stream a neutral httk-trajectory-jsonl payload or path lazily.

Frame data remains in the JSONL container and is read as requested.

Parameters:

source (Any) – A JSONL payload or path to one.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'jsonl'¶

property nframes: int¶

Return the number of frames in the container.

property header: collections.abc.Mapping[str, Any]¶

Return the neutral JSONL header mapping.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]¶

Return the constant species name at each site.

property reference_frames: tuple[int, Ellipsis] | None¶

Return stored reference-frame indexes, or None.

property observable_names: tuple[str, Ellipsis]¶

Return the names of available per-frame observables.

observable(name)[source]¶

Read one observable’s values in frame order.

Parameters:: name (str) – Observable name.
Returns:: The observable values.
Raises:: KeyError – If the observable is unavailable.
Return type:: tuple[Any, Ellipsis]

frame(i)[source]¶

Read one frame from the JSONL container.

Parameters:: i (int) – Frame index.
Returns:: The requested unit-cell structure.
Raises:: IndexError – If the frame index is out of range.
Return type:: httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Stream all frames from the JSONL container.

Yields:: Unit-cell structures in container order.

unwrap()[source]¶

Return the original JSONL source payload or path.

property source_locator: str | None¶

Return the JSONL path, if the source has one.

class httk.atomistic.PlainTrajectory(obj, **hints)[source]¶

Bases: httk.atomistic.models.trajectory.backend.TrajectoryBackend

Represent a mapping whose structure properties have a frame axis.

A compact constant property is represented by a one-element leading axis, e.g. nelements=[2] for any number of frames. Only properties declaring constant on that axis accept this compact form.

Parameters:

obj (collections.abc.Mapping[str, Any]) – A trajectory property mapping.
**hints (Any) – Backend-selection hints.

kind: ClassVar[str] = 'plain'¶

frame(i)[source]¶

Return one frame from the property mapping.

Parameters:

i (int) – Frame index; negative indexes count from the end.

Returns:

The requested unit-cell structure.

Raises:

IndexError – If the frame index is out of range.
KeyError – If a required trajectory property is absent.
TypeError – If the frame index is not an integer.
ValueError – If the frame cannot be represented as a structure.

Return type:

httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Iterate over all frames in source order.

Returns:: An iterator of unit-cell structures.
Return type:: collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property nframes: int¶

Return the number of frames.

property reference_frames: tuple[int, Ellipsis] | None¶

Return normalized reference-frame indexes, or None.

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

Return the constant distinct species from the first frame.

property species_at_sites: tuple[str, Ellipsis]¶

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]¶

Return names outside the recognized trajectory and structure properties.

observable(name)[source]¶

Return one mapped observable’s values in frame order.

Parameters:: name (str) – Observable property name.
Returns:: The observable values.
Raises:: KeyError – If the property is not an observable.
Return type:: tuple[Any, Ellipsis]

unwrap()[source]¶

Return the original property mapping.

class httk.atomistic.Trajectory(frames, observables=None, reference_frames=None)[source]¶

Bases: httk.atomistic.models.trajectory.backend.TrajectoryBackend

Store an immutable trajectory in the native backend.

A trajectory requires at least one frame and keeps one constant composition across all frames.

Parameters:

frames (collections.abc.Sequence[httk.atomistic.models.structure.like.StructureLike]) – Unit-cell structures to coerce and store.
observables (collections.abc.Mapping[str, collections.abc.Sequence[Any]] | None) – Optional per-frame observable values.
reference_frames (collections.abc.Sequence[int] | None) – Optional indexes of bounded reference frames.

kind: ClassVar[str] = 'native'¶

property nframes: int¶

Return the number of stored frames.

frame(i)[source]¶

Return one stored frame by index.

Parameters:: i (int) – Frame index.
Returns:: The requested unit-cell structure.
Raises:: IndexError – If the index is out of range.
Return type:: httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Iterate over the stored frames.

Returns:: An iterator of unit-cell structures.
Return type:: collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property reference_frames: tuple[int, Ellipsis] | None¶

Return the bounded reference-frame indexes, or None.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]¶

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]¶

Return the names of stored observables.

observable(name)[source]¶

Return one observable’s values in frame order.

Parameters:: name (str) – Observable name.
Returns:: The observable values.
Raises:: KeyError – If the observable is unavailable.
Return type:: tuple[Any, Ellipsis]

type httk.atomistic.TrajectoryLike = TrajectoryBackend | TrajectoryView | Trajectory | PlainTrajectory | Mapping[str, Any][source]¶

class httk.atomistic.TrajectoryView(obj, **hints)[source]¶

Bases: httk.core.View[httk.atomistic.models.trajectory.backend.TrajectoryBackend], httk.atomistic.models.trajectory.api.TrajectoryAPI

Present any trajectory backend through the canonical trajectory API.

Parameters:

obj (Any) – A trajectory backend or another accepted trajectory value.
**hints (Any) – Backend-selection hints.

property nframes: int¶

Return the number of frames.

frame(i)[source]¶

Return one frame by index.

Parameters:: i (int) – Frame index.
Returns:: The requested unit-cell structure.
Return type:: httk.atomistic.models.structure.unitcell.UnitcellStructure

frames()[source]¶

Iterate over the frames.

Returns:: An iterator of unit-cell structures.
Return type:: collections.abc.Iterator[httk.atomistic.models.structure.unitcell.UnitcellStructure]

property reference_frames: tuple[int, Ellipsis] | None¶

Return stored reference-frame indexes, or None.

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

Return the constant distinct species.

property species_at_sites: tuple[str, Ellipsis]¶

Return the constant species name at each site.

property observable_names: tuple[str, Ellipsis]¶

Return the names of available per-frame observables.

property observable_summaries: tuple[Any, Ellipsis]¶

Return backend-provided observable summaries, if any.

property immutable_id: str | None¶

Return the backend immutable identifier, if available.

property last_modified: Any¶

Return the backend modification marker, if available.

property source_locator: str | None¶

Return the source locator, if available.

observable(name)[source]¶

Return one observable’s values in frame order.

Parameters:: name (str) – Observable name.
Returns:: The observable values.
Raises:: KeyError – If the observable is unavailable.
Return type:: tuple[Any, Ellipsis]

unwrap()[source]¶

Return the original value wrapped by the backend.

class httk.atomistic.PlaneWaveFunctions(source=None, *, cell=None, encut=None, kpoints=None, eigenvalues=None, occupations=None, coefficients=None, nplanewaves=None, double_precision=None, gamma_half=None)[source]¶

Provide a zero-based, NumPy-native collection of plane-wave coefficients.

This is an eager NumPy representation, not a backend or view family. NumPy is required at construction time; install the httk-atomistic[numpy] extra when it is absent.

A WAVECAR does not store whether gamma compression used the x or z half-space. The default interpretation is x; pass gamma_half="z" to load() when loading a z-half gamma WAVECAR. Gamma compression is detected from the k-point and plane-wave count during construction.

Parameters:

source (Any) – A WAVECAR source or neutral WAVECAR payload, or None for in-memory data.
cell (Any) – The real-space cell used by the in-memory coefficients.
encut (Any) – The plane-wave energy cutoff used to generate reciprocal vectors.
kpoints (Any) – The k-points used by the in-memory coefficients.
eigenvalues (Any) – The band eigenvalues.
occupations (Any) – The band occupations.
coefficients (Any) – The coefficient vectors keyed by zero-based spin, k-point, and band.
nplanewaves (Any) – The number of plane waves for each k-point, or None to infer it.
double_precision (Any) – Whether to retain double-precision complex coefficients.
gamma_half (Any) – The gamma-compression half-space, "x" or "z", if applicable.

Raises:

ImportError – If NumPy is unavailable.

property nspins: int¶

Return the number of spin channels.

property nkpts: int¶

Return the number of k-points.

property nbands: int¶

Return the number of bands.

property encut: float¶

Return the plane-wave energy cutoff.

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

Return the real-space cell.

property kpoints: Any¶

Return the k-point coordinates.

property eigenvalues: Any¶

Return the band eigenvalues.

property occupations: Any¶

Return the band occupations.

property nplanewaves: Any¶

Return the plane-wave count for each k-point.

property double_precision: bool¶

Return whether coefficients use double precision.

property is_gamma: bool¶

Return whether the coefficients use gamma compression.

property gamma_half: str | None¶

Return the detected gamma-compression half-space, if applicable.

property kgrid_size: Any¶

Return the reciprocal-grid dimensions used for transforms.

close()[source]¶

Close a file-backed source while retaining cached coefficients and metadata.

property closed: bool¶

Report whether the file-backed source is closed.

coefficients(spin, kpt, band, *, cache=True)[source]¶

Return one coefficient vector, using an existing cache even when cache=False.

An uncached source read occurs once and is not stored; cached coefficients remain available after a file-backed source is closed.

Parameters:

spin (int) – The zero-based spin index.
kpt (int) – The zero-based k-point index.
band (int) – The zero-based band index.
cache (bool) – Whether to cache a coefficient vector read from the source.

Returns:

The selected coefficient vector.

Raises:

ValueError – If an index is out of range or source coefficients have the wrong length.

Return type:

Any

gvectors(kpt=0, *, gamma=None, gamma_half=None)[source]¶

Return the reciprocal grid vectors for a k-point.

Parameters:

kpt (int) – The zero-based k-point index.
gamma (bool | None) – Whether to use gamma compression, or the construction default when None.
gamma_half (str | None) – The gamma-compression half-space, if gamma compression is requested.

Returns:

The reciprocal grid vectors selected by the cutoff.

Raises:

ValueError – If the k-point, gamma flag, or half-space is invalid.

Return type:

Any

realspace_wave(spin, kpt, band, *, norm=True)[source]¶

Transform coefficients to a real-space wave using NumPy FFTs.

The transform uses numpy.fft with norm="ortho". Gamma-compressed coefficients are expanded according to the detected half-space before the transform.

Parameters:

spin (int) – The zero-based spin index.
kpt (int) – The zero-based k-point index.
band (int) – The zero-based band index.
norm (bool) – Whether to normalize the resulting wave to unit norm.

Returns:

The real-space wave on the reciprocal grid.

Raises:

ValueError – If an index is out of range or the stored gamma metadata is invalid.

Return type:

Any

select(spins=None, kpts=None, bands=None, *, format=None, gamma_half='x')[source]¶

Select spins, k-points, and bands, optionally converting coefficient format.

Indices are zero-based and must be unique. Converting standard coefficients to gamma format derives a signed real wave from the standard complex wave and therefore destroys phase information; converting gamma coefficients to standard format expands the stored half-space. A gamma selection must contain exactly one gamma-point k-point.

Parameters:

spins (collections.abc.Sequence[int] | None) – The zero-based spin indices to retain, or all spins when None.
kpts (collections.abc.Sequence[int] | None) – The zero-based k-point indices to retain, or all k-points when None.
bands (collections.abc.Sequence[int] | None) – The zero-based band indices to retain, or all bands when None.
format (str | None) – The requested coefficient format, "std", "gamma", or None.
gamma_half (str) – The target gamma-compression half-space.

Returns:

A new in-memory collection containing the selected data.

Raises:

ValueError – If indices, format, gamma selection, or half-space conversion is invalid.

Return type:

PlaneWaveFunctions

httk.atomistic.save_vesta(basename, structure, wave, *, cols=10)[source]¶

Save real and imaginary wave components as VASP volumetric files.

The files are written as <basename>_r.vasp and <basename>_i.vasp.

Parameters:

basename (str) – The output filename prefix.
structure (Any) – The structure supplying the volumetric-file cell and species metadata.
wave (Any) – The three-dimensional complex wave to write.
cols (int) – The number of values written per output line.

Raises:

ImportError – If NumPy is not installed.
ValueError – If wave is not a three-dimensional complex array.

httk.atomistic.wavefunction_overlap(phi1, phi2)[source]¶

Return the complex overlap of two wavefunctions.

Parameters:

phi1 (Any) – The first wavefunction.
phi2 (Any) – The second wavefunction.

Returns:

The conjugate-inner-product overlap.

Raises:

ValueError – If the wavefunctions do not have matching shapes.

Return type:

complex

class httk.atomistic.StructureEntry[source]¶

Define the non-instantiable OPTIMADE structure entry family.

type = 'structures'¶

definition_id = 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/structures'¶

classmethod entry_type_definition()[source]¶

Load the standard structure definition with atomistic extensions.

Returns:: The extended OPTIMADE structures definition.
Return type:: httk.core.EntryTypeDefinition

class httk.atomistic.StructureEntryProvider(entries, *, extra_definitions=None, properties=None)[source]¶

Bases: httk.core.EntryProvider

Serve complete OPTIMADE v1.3 structure records from atomistic structures.

A mapping keeps the convenient {"example": structure} form and its explicit served ids. An iterable of natural structures uses each representation’s structural content id. Entry metadata lives on the structures themselves.

Custom properties may extend the schema, but standard OPTIMADE fields are a pure projection of the entry and structure and cannot be replaced by custom values.

Parameters:

entries (collections.abc.Mapping[str, httk.atomistic.models.structure.like.StructureLike | None] | collections.abc.Iterable[httk.atomistic.models.structure.like.StructureLike]) – Entries keyed by explicit ids, or entries whose ids are derived from their representations; explicit entries may be None.
extra_definitions (collections.abc.Mapping[str, httk.core.PropertyDefinition] | None) – Additional property definitions to expose.
properties (collections.abc.Mapping[str, collections.abc.Mapping[str, Any]] | None) – Per-entry custom property values validated against the definition.

entry_types()[source]¶

Return the structure entry type served by this provider.

Returns:: The structures entry-type definition.
Return type:: collections.abc.Mapping[str, httk.core.EntryTypeDefinition]

property_keys(entry_type)[source]¶

Map served structure properties to storage keys.

Parameters:: entry_type (str) – The entry type to inspect.
Returns:: Served-property to storage-key mappings.
Raises:: KeyError – If entry_type is not structures.
Return type:: collections.abc.Mapping[str, str]

records(entry_type)[source]¶

Project the provider’s structures into OPTIMADE records.

None entries produce rows with null structure properties.

Parameters:: entry_type (str) – The entry type to project.
Returns:: The projected records.
Raises:: KeyError – If entry_type is not structures.
Return type:: collections.abc.Iterable[collections.abc.Mapping[str, Any]]

class httk.atomistic.TrajectoryEntry[source]¶

Define the non-instantiable OPTIMADE trajectory entry family.

type = 'trajectories'¶

definition_id = 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/trajectories'¶

classmethod entry_type_definition()[source]¶

Load the trajectory definition with httk extensions.

Returns:: The extended OPTIMADE trajectories definition.
Return type:: httk.core.EntryTypeDefinition

class httk.atomistic.TrajectoryEntryProvider(entries, *, extra_definitions=None, properties=None)[source]¶

Bases: httk.core.EntryProvider

Serve trajectory metadata and bounded frame projections.

Native frame lists are materialized only through httk.atomistic.entries.trajectories.TRAJECTORY_FRAME_MATERIALIZATION_LIMIT (100) frames. Larger or record-backed trajectories still serve the entry, frame count, references, and null frame properties. Recover their frame data by re-reading the original source files or the JSONL container; partial-data serving is planned.

Parameters:

entries (collections.abc.Mapping[str, httk.atomistic.models.trajectory.like.TrajectoryLike | None] | collections.abc.Iterable[httk.atomistic.models.trajectory.like.TrajectoryLike]) – Entries keyed by explicit ids, or entries whose ids are derived from their representations; explicit entries may be None.
extra_definitions (collections.abc.Mapping[str, httk.core.PropertyDefinition] | None) – Additional property definitions to expose.
properties (collections.abc.Mapping[str, collections.abc.Mapping[str, Any]] | None) – Per-entry custom property values validated against the definition.

entry_types()[source]¶

Return the trajectory entry type served by this provider.

Returns:: The trajectories entry-type definition.
Return type:: collections.abc.Mapping[str, httk.core.EntryTypeDefinition]

property_keys(entry_type)[source]¶

Map served trajectory properties to storage keys.

Parameters:: entry_type (str) – The entry type to inspect.
Returns:: Served-property to storage-key mappings.
Raises:: KeyError – If entry_type is not trajectories.
Return type:: collections.abc.Mapping[str, str]

records(entry_type)[source]¶

Project trajectories into OPTIMADE records.

Native frame lists are served only for trajectories up to the materialization limit; larger and record-backed trajectories serve null frame properties.

Parameters:: entry_type (str) – The entry type to project.
Returns:: The projected records.
Raises:: KeyError – If entry_type is not trajectories.
Return type:: collections.abc.Iterable[collections.abc.Mapping[str, Any]]

class httk.atomistic.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.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.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.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.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

httk.atomistic.validate_structure_record(record)[source]¶

Validate a hand-built root record against native structure semantics.

Parameters:

record (UnitcellStructureRecord | FundamentalDomainStructureRecord | ASUStructureRecord) – The exact root structure record to validate.

Returns:

None after successful validation.

Raises:

TypeError – If record is not an exact supported root record.
ValueError – If the record’s normalized composition contradicts its native fields.

Return type:

None

class httk.atomistic.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.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.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.AnonymousFormula(backend, **hints)[source]¶

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend, str

Store a strictly canonical OPTIMADE anonymous chemical formula.

Parameters:: formula – The canonical anonymous formula text.

property is_anonymous: bool¶

Return whether the formula uses anonymous labels.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]¶

Return the anonymous coefficients as exact amounts.

class httk.atomistic.AnonymousFormulaView(obj, **hints)[source]¶

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.anonymous.AnonymousFormula

Present a complete composition as an eager canonical anonymous formula.

Parameters:

obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.
**hints (Any) – Backend-selection hints.

property amounts¶: Return the presented amounts using anonymous labels.

property uncertainties¶: Return the presented amount precisions using anonymous labels.

property complete¶: Return whether the presented composition is complete.

property exact¶: Return whether the presented amounts are exact.

property normalized¶: Return whether the presented composition is normalized.

property normalization_status¶: Return the presented composition’s normalization status.

property diagnostics¶: Return diagnostics associated with the presented composition.

property is_anonymous¶: Return whether this formula uses anonymous labels.

unview()[source]¶

Return the presented formula as a standalone value.

Returns:: The canonical anonymous formula value.
Return type:: httk.atomistic.models.formula.anonymous.AnonymousFormula

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

class httk.atomistic.Composition(amounts, uncertainties=None, complete=True, exact=None, normalized=True, normalization_status=None, diagnostics=())[source]¶

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend

Store an immutable projected composition and its formula diagnostics.

Parameters:

amounts (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]]) – The projected elemental amounts in symbol order.
uncertainties (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]] | None) – The corresponding amount precisions, if known.
complete (bool) – Whether the projection contains no unknown elemental content.
exact (bool | None) – Whether all projected amounts are exact.
normalized (bool) – Whether all contributing probabilities and concentrations normalize.
normalization_status (str | None) – The combined normalization status.
diagnostics (collections.abc.Iterable[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic]) – The non-fatal issues found during projection.

amounts: tuple[tuple[str, fractions.Fraction], Ellipsis] = ()¶

Ordered (label, exact amount) pairs for this chemical formula.

Labels are element symbols in alphabetical order unless is_anonymous, in which case they are OPTIMADE anonymous symbols in canonical (descending-coefficient) order.

uncertainties: tuple[tuple[str, fractions.Fraction | None], Ellipsis] = ()¶: Per-amount absolute uncertainties, or None where exactness is unstated.

complete: bool = True¶: Whether the formula accounts for all represented elemental material.

exact: bool = True¶: Whether all formula amounts are exact rather than precision-bounded.

normalized: bool = True¶: Whether the formula is normalized within the stated precision.

normalization_status: str = 'exact'¶: The formula’s normalization status derived from exactness and normalization.

diagnostics: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, Ellipsis] = ()¶: Non-fatal structured diagnostics associated with the formula.

property amount_mapping: collections.abc.Mapping[str, fractions.Fraction]¶

Return the projected amounts as a read-only mapping.

property uncertainty_mapping: collections.abc.Mapping[str, fractions.Fraction | None]¶

Return the projected amount precisions as a read-only mapping.

property elements: tuple[str, Ellipsis]¶

Return the projected element symbols in amount order.

property nelements: int¶

Return the number of projected elements.

property elements_ratios: tuple[fractions.Fraction, Ellipsis]¶

Return the projected amounts normalized by their total.

property chemical_formula_reduced: str | None¶

Return the reduced chemical formula, if the composition is complete.

property chemical_formula_anonymous: str | None¶

Return the anonymous formula, if the composition is complete.

class httk.atomistic.CompositionView(obj, **hints)[source]¶

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.composition.Composition

Present any chemical-formula backend as a lazy composition.

Parameters:

obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.
**hints (Any) – Backend-selection hints.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]¶

Return the lazily materialized elemental amounts.

property uncertainties: tuple[tuple[str, fractions.Fraction | None], Ellipsis]¶

Return the lazily materialized amount precisions.

property complete: bool¶

Return whether the presented composition is complete.

property exact: bool¶

Return whether the presented amounts are exact.

property normalized: bool¶

Return whether the presented composition is normalized.

property normalization_status: str¶

Return the presented composition’s normalization status.

property diagnostics: tuple[httk.atomistic.models.formula.diagnostics.CompositionDiagnostic, Ellipsis]¶

Return diagnostics associated with the presented composition.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the presented composition as a standalone value.

Returns:: The materialized composition value.
Return type:: httk.atomistic.models.formula.composition.Composition

class httk.atomistic.ChemicalFormula(backend, **hints)[source]¶

Bases: httk.atomistic.models.formula.backend.ChemicalFormulaBackend, str

Store a strictly canonical reduced chemical formula.

Parameters:: formula – The alphabetical formula text with greatest common divisor one.

property amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]¶

Return the formula coefficients as exact amounts.

class httk.atomistic.ChemicalFormulaView(obj, **hints)[source]¶

Bases: httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase, httk.atomistic.models.formula.formula.ChemicalFormula

Present a complete composition as an eager canonical reduced formula.

Parameters:

obj (httk.atomistic.models.formula.like.ChemicalFormulaLike) – The chemical-formula-like object to present.
**hints (Any) – Backend-selection hints.

property amounts¶: Return the presented elemental amounts.

property uncertainties¶: Return the presented amount precisions.

property complete¶: Return whether the presented composition is complete.

property exact¶: Return whether the presented amounts are exact.

property normalized¶: Return whether the presented composition is normalized.

property normalization_status¶: Return the presented composition’s normalization status.

property diagnostics¶: Return diagnostics associated with the presented composition.

property is_anonymous¶: Return whether this formula uses anonymous labels.

unview()[source]¶

Return the presented formula as a standalone value.

Returns:: The canonical reduced formula value.
Return type:: httk.atomistic.models.formula.formula.ChemicalFormula

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

type httk.atomistic.ChemicalFormulaLike = httk.atomistic.models.formula.backend.ChemicalFormulaBackend | httk.atomistic.models.formula.view_base.ChemicalFormulaViewBase | httk.atomistic.models.formula.composition.Composition | httk.atomistic.models.formula.formula.ChemicalFormula | httk.atomistic.models.formula.anonymous.AnonymousFormula | httk.atomistic.models.prototype.backend.AnonymousStructureBackend | httk.atomistic.models.prototype.view_base.AnonymousStructureViewBase | httk.atomistic.models.prototype.anonymous.AnonymousStructure | httk.atomistic.models.prototype.prototype.Prototype | httk.atomistic.models.protostructure.backend.ProtostructureBackend | httk.atomistic.models.protostructure.view_base.ProtostructureViewBase | httk.atomistic.models.protostructure.protostructure.Protostructure | httk.atomistic.storage.records.NormalizedCompositionRecord | httk.atomistic.models.structure.backend.StructureBackend | httk.atomistic.models.structure.view.StructureView | str | Mapping[str, Any][source]¶

class httk.atomistic.AnonymousStructure(cell, sites, species=None, species_at_sites=None)[source]¶

Bases: httk.atomistic.models.prototype.backend.AnonymousStructureBackend

Store a unit cell whose site identities are consecutive dummy labels.

Parameters:

cell (httk.atomistic.models.cell.like.CellLike) – The unit-cell geometry.
sites (httk.atomistic.models.sites.like.SitesLike) – The reduced coordinates of the sites.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The distinct dummy species definitions.
species_at_sites (collections.abc.Sequence[str] | None) – The dummy species name occupying each site.

kind: ClassVar[str] = 'anonymous'¶

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

Return the unit cell.

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

Return the reduced sites.

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

Return the distinct dummy species.

property species_at_sites: tuple[str, Ellipsis]¶

Return dummy species names in site order.

property periodicity: tuple[bool, bool, bool]¶

Return the periodic directions.

property nperiodic_dimensions: int¶

Return the number of periodic directions.

property nsites: int¶

Return the number of sites.

cartesian_sites()[source]¶

Return the exact Cartesian site positions.

Returns:: The Cartesian positions in the cell’s exact vector representation.
Return type:: Any

property coordinate_precision¶: Return the reduced-coordinate precision.

property basis_precision¶: Return the cell-basis precision.

class httk.atomistic.AnonymousStructureView(obj, **hints)[source]¶

Bases: httk.atomistic.models.prototype.view_base.AnonymousStructureViewBase, httk.atomistic.models.prototype.anonymous.AnonymousStructure

Present an anonymous or ordinary structure lazily as an anonymous structure.

Parameters:

obj (Any) – The anonymous-structure-like or structure-like object to present.
**hints (Any) – Backend-selection hints.

property periodicity¶: Return the presented periodic directions.

property nperiodic_dimensions¶: Return the number of presented periodic directions.

property nsites¶: Return the number of presented sites.

cartesian_sites()[source]¶: Return the exact Cartesian presented site positions.

property coordinate_precision¶: Return the presented coordinate precision.

property basis_precision¶: Return the presented basis precision.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the presented structure as a standalone value.

Returns:: The anonymous structure value.
Return type:: httk.atomistic.models.prototype.anonymous.AnonymousStructure

type httk.atomistic.AnonymousStructureLike = httk.atomistic.models.prototype.backend.AnonymousStructureBackend | httk.atomistic.models.prototype.view_base.AnonymousStructureViewBase | httk.atomistic.models.prototype.anonymous.AnonymousStructure | httk.atomistic.models.prototype.prototype.Prototype[source]¶

type httk.atomistic.PrototypeLike = AnonymousStructureLike | httk.atomistic.models.protostructure.like.ProtostructureLike[source]¶

class httk.atomistic.Prototype(cell, spacegroup, wyckoff_sites, species=None, coordinate_precision=None)[source]¶

Bases: httk.atomistic.models.prototype.backend.AnonymousStructureBackend

Store a standard-setting fundamental domain with dummy species labels.

Parameters:

cell (httk.atomistic.models.cell.like.CellLike) – The standard-setting cell geometry.
spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The standard-setting space group.
wyckoff_sites (collections.abc.Sequence[httk.atomistic.models.structure.asu.WyckoffSite]) – The symmetry-distinct site definitions.
species (collections.abc.Sequence[httk.atomistic.models.species.like.SpeciesLike] | None) – The distinct dummy species definitions.
coordinate_precision (Any) – The precision recorded for the reduced coordinates.

kind: ClassVar[str] = 'prototype'¶

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

Return the standard-setting cell.

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

Return the standard-setting space group.

property wyckoff_sites: tuple[httk.atomistic.models.structure.asu.WyckoffSite, Ellipsis]¶

Return the symmetry-distinct site definitions.

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

Return the distinct dummy species.

property coordinate_precision¶: Return the reduced-coordinate precision.

property basis_precision¶: Return the cell-basis precision.

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

Return the expanded standard-setting sites.

property species_at_sites: tuple[str, Ellipsis]¶

Return dummy species names in expanded site order.

property periodicity: tuple[bool, bool, bool]¶

Return the periodic directions.

property nperiodic_dimensions: int¶

Return the number of periodic directions.

property nsites: int¶

Return the number of expanded sites.

cartesian_sites()[source]¶

Return the exact Cartesian expanded site positions.

multiplicities()[source]¶

Return the standard-setting multiplicity for each Wyckoff site.

property nsites_conventional: int¶

Return the number of sites in the conventional cell.

property prototype: Self¶

Return this prototype value.

class httk.atomistic.PrototypeView(obj, **hints)[source]¶

Bases: httk.atomistic.models.prototype.view_base.AnonymousStructureViewBase, httk.atomistic.models.prototype.prototype.Prototype

Recognize a lazy standard-setting prototype view from a structure.

Recognition accepts optional tolerance and limit_denominator values through the recognition hints.

Parameters:

obj (Any) – The anonymous-structure-like or structure-like source.
**hints (Any) – Backend-selection and recognition hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the recognized prototype as a standalone value.

Returns:: The prototype value.
Return type:: httk.atomistic.models.prototype.prototype.Prototype

type httk.atomistic.ProtostructureLike = httk.atomistic.models.protostructure.backend.ProtostructureBackend | httk.atomistic.models.protostructure.view_base.ProtostructureViewBase | httk.atomistic.models.protostructure.protostructure.Protostructure[source]¶

class httk.atomistic.WyckoffOccupation[source]¶

Store one Wyckoff orbit occupied by one possibly disordered species.

Parameters:

wyckoff – The Wyckoff letter in the standard setting.
species – The real species occupying the orbit.

wyckoff: str¶

species: httk.atomistic.models.species.species.Species¶

class httk.atomistic.Protostructure(spacegroup, occupations)[source]¶

Bases: httk.atomistic.models.protostructure.backend.ProtostructureBackend

Store a standard-setting space group and its occupied Wyckoff positions.

This is a provenance-independent value: multiplicities, composition, and formula derivations are defined at the standard-setting conventional-cell scale, even when the source used to recognize it was stored in a volume-scaled setting.

Parameters:

spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The standard-setting space group or its IT number.
occupations (collections.abc.Sequence[httk.atomistic.models.protostructure.occupation.WyckoffOccupation | tuple[str, Any]]) – The occupied Wyckoff positions and their species.

kind: ClassVar[str] = 'protostructure'¶

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

Return the standard-setting space group.

property occupations: tuple[httk.atomistic.models.protostructure.occupation.WyckoffOccupation, Ellipsis]¶

Return the canonical occupied Wyckoff positions.

class httk.atomistic.ProtostructureView(obj, **hints)[source]¶

Bases: httk.atomistic.models.protostructure.view_base.ProtostructureViewBase, httk.atomistic.models.protostructure.protostructure.Protostructure

Recognize a lazy standard-setting protostructure view.

Recognition accepts optional setting, standard, transform, tolerance, and limit_denominator values through the recognition hints.

Parameters:

obj (Any) – The structure-like or protostructure-like source.
**hints (Any) – Backend-selection and recognition hints.

unwrap()[source]¶

Return the raw object behind the backend.

Returns:: The unwrapped source object.
Return type:: Any

unview()[source]¶

Return the recognized protostructure as a standalone value.

Returns:: The protostructure value.
Return type:: httk.atomistic.models.protostructure.protostructure.Protostructure

class httk.atomistic.AffineOperation(matrix, vector=(0, 0, 0))[source]¶

Represent an exact affine map x -> W x + w on fractional coordinates.

Two operations compare equal when their matrix and translation are exactly equal. Equality is not modulo lattice translations — use wrapped() first when comparing symmetry operations as members of a space group, since x+1/2 and x+3/2 are the same operation there but different objects here.

Parameters:

matrix (Any) – The 3x3 rotation part in the column-vector convention, or a comma-separated "x,y,z" operation string (as emitted by to_xyz() and repr), in which case vector is ignored.
vector (Any) – The translation part in fractional coordinates.

classmethod identity()[source]¶

Return the identity operation.

Returns:: The identity affine operation.
Return type:: Self

classmethod from_record(record)[source]¶

Build an operation from either vendored affine-record shape.

The record’s matrix and vector hold exact rational strings ("1/2", "-1"), which embed exactly.

Parameters:: record (collections.abc.Mapping[str, Any]) – The affine record, or a mapping containing one under "affine_transformation".
Returns:: The corresponding affine operation.
Return type:: Self

property matrix: httk.core.FracVector¶

Return the 3x3 rotation part W in the column-vector convention.

Returns:: The exact rotation matrix.
Return type:: httk.core.FracVector

property vector: httk.core.FracVector¶

Return the translation part w.

Returns:: The exact translation vector.
Return type:: httk.core.FracVector

determinant()[source]¶

Return the determinant of the rotation part exactly.

For a symmetry operation this is +1 (proper) or -1 (improper). For a change of basis it is the ratio of cell volumes, so a value other than ±1 means the operation changes the lattice.

Returns:: The exact determinant.
Return type:: fractions.Fraction

is_identity()[source]¶

Report whether this operation is the identity.

Returns:: Whether the matrix and translation are both identity values.
Return type:: bool

apply(coords)[source]¶

Map reduced coordinates through this operation exactly.

coords is a single (3,) coordinate or an (N, 3) block of them; the result has the same shape. No wrapping is applied — see apply_wrapped().

Parameters:: coords (Any) – A single reduced coordinate or a block of reduced coordinates.
Returns:: The transformed coordinates with the same shape as coords.
Raises:: ValueError – If coords is neither a length-three coordinate nor an (N, 3) block.
Return type:: httk.core.FracVector

apply_wrapped(coords)[source]¶

Map coordinates and wrap every component into [0, 1).

Parameters:: coords (Any) – A single reduced coordinate or a block of reduced coordinates.
Returns:: The transformed and wrapped coordinates.
Raises:: ValueError – If coords has an unsupported shape.
Return type:: httk.core.FracVector

inverse()[source]¶

Return the inverse map exactly.

Returns:: The inverse affine operation.
Raises:: ZeroDivisionError – If the rotation part is singular.
Return type:: AffineOperation

conjugated_by(change)[source]¶

Rewrite this operation through a change of basis.

If self is a symmetry operation expressed in one setting and change maps that setting’s coordinates into another, the result is the same symmetry operation expressed in the other setting.

Parameters:: change (AffineOperation) – The affine operation defining the coordinate change.
Returns:: This operation conjugated by change.
Return type:: AffineOperation

wrapped()[source]¶

Return this operation with its translation reduced into [0, 1).

Two symmetry operations of a space group are the same element modulo lattice translations exactly when their wrapped forms are equal, which is what makes symop sets comparable.

Returns:: An operation with a normalized translation.
Return type:: AffineOperation

to_xyz()[source]¶

Render the operation in x,y,z notation.

For example, return "-x+1/2,y,-z+1/2".

Returns:: The crystallographic operation string.
Return type:: str

httk.atomistic.DEFAULT_TOLERANCE = 0.001[source]¶

httk.atomistic.recognize_asu(structure, *, setting=None, standard=None, transform=None, tolerance=None, limit_denominator=None)[source]¶

Build an ASUStructure from a full structure.

The space group can be supplied three ways, in decreasing order of preference:

setting — the structure’s own tabulated setting, as when a CIF names its group. Nothing is searched for and spglib is not involved.
standard together with transform — for a structure in a setting that appears in no table. Also spglib-free.
neither — the symmetry is found with spglib, which must be installed (pip install httk-atomistic[default]).

tolerance is a Cartesian distance, measured in the real cell, so it means the same thing along a short axis and a long one; a fractional tolerance would not. Left unspecified it is derived from how precisely the structure was stated — see structure_tolerance() — falling back to DEFAULT_TOLERANCE for a structure that does not say. Pass a value to override that.

Raises ValueError if a site cannot be placed on any Wyckoff position within the tolerance, or if the sites do not group into complete orbits — both of which mean the structure does not actually have the symmetry it was said to have.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The full structure to recognize.
setting (httk.atomistic.symmetry.spacegroup.Spacegroup | None) – The structure’s own tabulated setting, if known.
standard (httk.atomistic.symmetry.spacegroup.Spacegroup | None) – The IT standard setting for an untabulated own setting.
transform (httk.atomistic.symmetry.setting_transform.SettingTransform | None) – The stored standard-to-own transform for an untabulated setting.
tolerance (float | None) – The Cartesian matching tolerance in the real cell, or None to derive it from the structure’s stated precision.
limit_denominator (int | None) – The largest denominator allowed when idealising free parameters, or None to retain their exact stated values.

Returns:

The recognized asymmetric-unit structure.

Raises:

ImportError – If symmetry must be searched and the optional spglib dependency is unavailable.
TypeError – If the supplied setting arguments are incomplete or mutually exclusive.
ValueError – If the structure is not fully periodic, the standard setting is invalid, or the sites cannot be placed into complete Wyckoff orbits within the tolerance.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.structure_tolerance(structure, *, fallback=DEFAULT_TOLERANCE)[source]¶

Derive a matching tolerance from how precisely the structure was stated.

This is the point of recording precision at all: instead of a constant somebody guessed, the tolerance follows the data. Coordinates written to four decimals in a 5 A cell are good to about 5e-4, and the tolerance comes out near 1e-3; the same coordinates in a 30 A cell justify a tolerance six times larger, and coordinates written to two decimals justify one a hundred times larger.

Returns fallback when the structure does not state a precision — a structure built by hand, or read from a format that does not write its numbers to a definite number of digits. A caller that needs to know whether that happened can compare the result against the structure’s own cartesian_precision().

The value is capped so that it can never reach half the smallest distance between two sites, which is what would let genuinely distinct atoms be merged. Minimum separation bounds a tolerance from above; treating it as precision could make a structure with accidentally close atoms look far more precisely stated than it is.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The structure whose stated precision determines the tolerance.
fallback (float) – The tolerance to use when the structure has no stated precision.

Returns:

The Cartesian matching tolerance in the structure’s cell units.

Return type:

float

class httk.atomistic.SettingTransform(matrix, vector=(0, 0, 0), *, hall_entry=None)[source]¶

Represent an exact rational change of basis from the IT standard setting.

Wraps an AffineOperation and gives it the standard-to-own reading described in the module docstring, plus the cell-basis and symmetry-operation transformations that follow from it.

Parameters:

matrix (Any) – The 3x3 matrix M mapping standard coordinates to the own setting.
vector (Any) – The origin shift v in the own setting.
hall_entry (str | None) – The normalized Hall entry associated with a tabulated transform, if known.

classmethod identity()[source]¶

Return the transform of a structure already in its IT standard setting.

Returns:: The identity setting transform.
Return type:: Self

classmethod from_hall_entry(hall_entry)[source]¶

Return the tabulated transform for one of the 527 known settings.

hall_entry is the normalized Hall symbol of the setting, which names it unambiguously — symbol, axes, and origin choice together.

Parameters:: hall_entry (str) – The normalized Hall symbol naming the setting.
Returns:: The stored standard-to-own transform.
Raises:: KeyError – If hall_entry is not in the vendored setting table.
Return type:: Self

property operation: httk.atomistic.symmetry.affine_operation.AffineOperation¶

Return the underlying affine map from standard to own setting.

Returns:: The underlying affine operation.
Return type:: httk.atomistic.symmetry.affine_operation.AffineOperation

property matrix: httk.core.FracVector¶

Return the 3x3 rotation part M.

Returns:: The exact change-of-basis matrix.
Return type:: httk.core.FracVector

property vector: httk.core.FracVector¶

Return the origin shift v.

Returns:: The exact origin-shift vector.
Return type:: httk.core.FracVector

property hall_entry: str | None¶

Return the Hall entry used to look up this transform, if any.

Returns:: The normalized Hall entry, or None for a caller-supplied transform.
Return type:: str | None

determinant()[source]¶

Return the signed inverse volume factor det M.

Its magnitude satisfies abs(det M) = V_standard / V_own; the sign records orientation reversal.

1 for 520 of the 527 tabulated settings. The exceptions are the seven rhombohedral-axes settings (IT numbers 146, 148, 155, 160, 161, 166, 167) where it is 3, because the standard hexagonal cell holds three primitive rhombohedral cells. A caller-supplied transform may have any non-zero value.

Returns:: The exact determinant of M.
Return type:: fractions.Fraction

is_identity()[source]¶

Report whether the transform is the identity.

Returns:: Whether the matrix and origin shift leave the standard setting unchanged.
Return type:: bool

to_setting(coords)[source]¶

Map standard-setting reduced coordinates into this setting without wrapping.

Parameters:: coords (Any) – A reduced coordinate or block of reduced coordinates in the standard setting.
Returns:: The corresponding coordinates in the own setting.
Return type:: httk.core.FracVector

to_standard(coords)[source]¶

Map own-setting reduced coordinates into the standard setting without wrapping.

Parameters:: coords (Any) – A reduced coordinate or block of reduced coordinates in the own setting.
Returns:: The corresponding coordinates in the standard setting.
Return type:: httk.core.FracVector

symop_to_setting(operation)[source]¶

Rewrite a standard-setting symmetry operation in this setting.

Parameters:: operation (httk.atomistic.symmetry.affine_operation.AffineOperation) – The symmetry operation expressed in the standard setting.
Returns:: The conjugated symmetry operation in the own setting.
Return type:: httk.atomistic.symmetry.affine_operation.AffineOperation

symop_to_standard(operation)[source]¶

Rewrite an own-setting symmetry operation in the standard setting.

Parameters:: operation (httk.atomistic.symmetry.affine_operation.AffineOperation) – The symmetry operation expressed in the own setting.
Returns:: The conjugated symmetry operation in the standard setting.
Return type:: httk.atomistic.symmetry.affine_operation.AffineOperation

basis_to_setting(basis)[source]¶

Map a standard-setting cell basis into this setting.

Follows from coordinate invariance: if f_own = f_std * M.T() then B_own = inv(M).T() * B_std, so that f * B is the same Cartesian point either way. The transform is rational, so an exact basis stays exact — a hexagonal cell keeps its sqrt(3).

Parameters:: basis (Any) – The standard-setting cell basis with lattice vectors as rows.
Returns:: The own-setting cell basis with lattice vectors as rows.
Return type:: httk.core.SurdVector

basis_to_standard(basis)[source]¶

Map this setting’s cell basis into the standard setting.

Parameters:: basis (Any) – The own-setting cell basis with lattice vectors as rows.
Returns:: The standard-setting cell basis with lattice vectors as rows.
Return type:: httk.core.SurdVector

lattice_cosets()[source]¶

Return the translations of this setting’s cell that are standard-lattice translations.

Expanding an orbit generates points from the standard setting’s symmetry operations, which carry the standard lattice’s periodicity. When this setting’s cell is larger than the standard one, that is not enough: points related by a standard lattice translation are genuinely distinct sites here, and the missing ones are recovered by also applying each translation returned by this method.

The result is the finite subgroup of (Q/Z)^3 generated by the columns of M reduced modulo 1, always including the zero translation. It is trivial (just zero) whenever M is an integer matrix, which covers all 527 tabulated settings — including the seven with det M == 3, where this setting’s cell is smaller and the surplus points collapse under wrapping instead. So this only ever does work for a caller-supplied transform to a supercell setting.

Returns:: The normalized finite set of translations, including zero.
Return type:: tuple[httk.core.FracVector, Ellipsis]

inverse()[source]¶

Return the transform in the opposite direction.

Returns:: The transform from this setting to the standard setting.
Return type:: SettingTransform

class httk.atomistic.Spacegroup(record)[source]¶

Represent a tabulated space-group setting from the vendored symmetry data.

Parameters:: record (collections.abc.Mapping[str, Any]) – The read-only vendored mapping describing one space-group setting.

classmethod standard(it_number)[source]¶

Return the IT standard setting for a space-group number.

Parameters:: it_number (int) – The International Tables space-group number.
Returns:: The IT standard setting for it_number.
Return type:: Self

classmethod from_hall_entry(hall_entry)[source]¶

Return the setting named by a normalized Hall symbol.

For example, "-c_2yc" names one setting.

Parameters:: hall_entry (str) – The normalized Hall symbol naming the setting.
Returns:: The corresponding space-group setting.
Return type:: Self

classmethod from_setting(setting_it_nc)[source]¶

Return the setting named by an IT number and coordinate-system code.

For example, "15:c1" names one setting.

Parameters:: setting_it_nc (str) – The IT setting identifier.
Returns:: The corresponding space-group setting.
Return type:: Self

classmethod from_hm_entry(hm_entry)[source]¶

Return the setting named by a Hermann-Mauguin entry.

For example, "C 1 2/c 1" names one setting.

Parameters:: hm_entry (str) – The Hermann-Mauguin symbol naming the setting.
Returns:: The corresponding space-group setting.
Return type:: Self

property record: collections.abc.Mapping[str, Any]¶

Return the raw vendored record for fields this class does not model.

Returns:: The source record for this setting.
Return type:: collections.abc.Mapping[str, Any]

property it_number: int¶

Return the International Tables space-group number.

Returns:: The space-group number from 1 through 230.
Return type:: int

property setting: str¶

Return the setting name, such as "15:c1".

Returns:: The IT number and coordinate-system code.
Return type:: str

property hall_entry: str¶

Return the normalized Hall symbol naming the setting unambiguously.

Returns:: The normalized Hall symbol.
Return type:: str

property hall_symbol: str¶

Return the Hall symbol as conventionally written.

Returns:: The conventional Hall symbol.
Return type:: str

property hermann_mauguin: str¶

Return the short Hermann-Mauguin symbol for this setting.

Returns:: The short Hermann-Mauguin symbol.
Return type:: str

property hermann_mauguin_full: str¶

Return the full Hermann-Mauguin symbol for this setting.

Returns:: The full Hermann-Mauguin symbol.
Return type:: str

property crystal_system: str¶

Return the crystal system, such as "monoclinic".

Returns:: The crystal-system name.
Return type:: str

property centring_type: str¶

Return the lattice centring letter, such as "P", "C", or "F".

Returns:: The centring letter.
Return type:: str

property is_standard_setting: bool¶

Report whether this is the IT standard setting for its space-group number.

Returns:: Whether this setting is the IT reference setting.
Return type:: bool

property symmetry_operations: tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, Ellipsis]¶

Return every symmetry operation of the group in this setting’s coordinates.

The full set with centring translations already folded in, so its length is the group order and no separate centring pass is needed.

Returns:: The complete tuple of symmetry operations.
Return type:: tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, Ellipsis]

property centering_translations: tuple[httk.core.FracVector, Ellipsis]¶

Return the lattice centring translations, including zero.

Returns:: The centring translations in this setting.
Return type:: tuple[httk.core.FracVector, Ellipsis]

property wyckoff: tuple[httk.atomistic.symmetry.wyckoff.WyckoffPosition, Ellipsis]¶

Return the Wyckoff positions ordered most specific first.

Sorted by (free_count, multiplicity, letter), so identifying a coordinate by walking this order returns the most specific position it lies on.

Returns:: The ordered Wyckoff positions for this setting.
Return type:: tuple[httk.atomistic.symmetry.wyckoff.WyckoffPosition, Ellipsis]

wyckoff_position(letter)[source]¶

Return the Wyckoff position with the given letter.

For example, "e" selects the position with letter e.

Parameters:: letter (str) – The bare Wyckoff letter.
Returns:: The matching Wyckoff position.
Raises:: KeyError – If this setting has no position with letter.
Return type:: httk.atomistic.symmetry.wyckoff.WyckoffPosition

identify_wyckoff(coordinate)[source]¶

Identify the most specific Wyckoff position holding an exact coordinate.

Returns None when the coordinate lies on no position, which for a complete table means the input was not an exact rational site of this group. Matching is exact: an approximate coordinate must be snapped first (see ASUStructure’s recognition path), never passed here in the hope that it lands.

Parameters:: coordinate (Any) – The exact reduced coordinate to identify.
Returns:: The matching position and free parameters, or None when no position matches exactly.
Return type:: tuple[httk.atomistic.symmetry.wyckoff.WyckoffPosition, httk.core.FracVector] | None

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

Return the change of basis from the IT standard setting to this one.

The identity exactly when this is the standard setting.

Returns:: The stored standard-to-own setting transform.
Return type:: httk.atomistic.symmetry.setting_transform.SettingTransform

standard_setting()[source]¶

Return the IT standard setting for this space-group number.

Returns:: The IT standard setting.
Return type:: Spacegroup

httk.atomistic.wyckoff_letter_map(standard, target)[source]¶

Map standard-setting Wyckoff letters to their names in another setting.

Almost always the identity — but not always, and the exception is silent. Across all 3210 non-reference (setting, letter) pairs in the vendored tables, exactly one setting permutes letters: in 224:1 the standard setting’s j is that setting’s i and vice versa. So a CIF that declares site 24i in setting 224:1 does not mean standard-setting letter i, and taking the letter at face value across a setting boundary produces the wrong structure with no error.

Computed rather than hard-coded, so it survives a data refresh: each standard position is evaluated at generic parameters, mapped through the setting transform, and identified in the target’s own Wyckoff table.

Parameters:

standard (Spacegroup) – The IT standard setting whose letters are being mapped.
target (Spacegroup) – The setting receiving the mapped letters.

Returns:

A mapping from standard-setting letters to target-setting letters.

Raises:

ValueError – If the settings belong to different space groups or the mapping is not bijective.

Return type:

dict[str, str]

class httk.atomistic.PrimitiveCellResult[source]¶

Store a structure in the fixed primitive cell of its conventional cell.

transform is the row-convention matrix actually applied to the conventional basis: basis_primitive = transform * basis_conventional. The matrices are the transposes of spglib’s documented column-vector matrices, where B_p = B_s P_c; fractional row coordinates therefore transform as f_p = f_s * transform.inv() and are wrapped into [0, 1). See the spglib primitive-cell definition.

multiplier is the exact ratio of primitive-cell site count to input site count.

Parameters:

structure – The resulting primitive-cell structure.
spacegroup – The space group of the standardized input.
conventional – The conventional-cell result used as input.
transform – The row-convention matrix applied to the conventional basis.
multiplier – The exact ratio of result site count to input site count.

structure: httk.atomistic.models.structure.unitcell.UnitcellStructure¶

spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup¶

conventional: httk.atomistic.symmetry.standardization.ConventionalCellResult¶

transform: httk.core.FracVector¶

multiplier: fractions.Fraction¶

httk.atomistic.primitive_cell(structure, *, tolerance=None, limit_denominator=None)[source]¶

Return structure in the spglib-convention primitive cell.

The input is first recognized or, when it already contains an asymmetric unit, used exactly as stored. Recognition arguments are rejected for an existing ASU. The recognized structure is converted to its IT standard-setting conventional cell by conventional_cell(), then the fixed matrix for its centring type is applied exactly. Site moments and assemblies are refused because this operation cannot yet transform their frame or preserve correlated site groups through the centring collapse. This operation does not perform Niggli reduction.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The structure to express in a primitive cell.
tolerance (float | None) – The Cartesian recognition tolerance, or None to derive it.
limit_denominator (int | None) – The maximum denominator for idealised free parameters, or None to retain their exact stated values.

Returns:

The primitive-cell structure and transform metadata.

Raises:

ImportError – If recognition is needed and the optional spglib dependency is unavailable.
ValueError – If recognition arguments are invalid for the input, the structure has unsupported moments or assemblies, is not fully periodic, or has an unsupported centring type.

Return type:

PrimitiveCellResult

class httk.atomistic.ConventionalCellResult[source]¶

Store a structure in its space group’s IT standard-setting conventional cell.

asu is the new standard-setting ASU that was expanded to make structure. transform is the standard-to-own transform from the ASU that was supplied to, or recognized from, the operation; its orientation is \(f_own = f_std M^T + v\), so this operation undoes it for the cell basis. multiplier is the exact ratio of conventional-cell site count to input-cell site count. For the 527 vendored settings it is at least one; an untabulated, caller-supplied supercell transform may still produce a ratio below one.

Parameters:

structure – The resulting full conventional-cell structure.
asu – The resulting asymmetric-unit structure in the standard setting.
spacegroup – The space group represented by the result.
transform – The standard-to-own transform used for the input structure.
multiplier – The exact ratio of result site count to input site count.

structure: httk.atomistic.models.structure.unitcell.UnitcellStructure¶

asu: httk.atomistic.models.structure.asu.ASUStructure¶

spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup¶

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

multiplier: fractions.Fraction¶

httk.atomistic.conventional_cell(structure, *, tolerance=None, limit_denominator=None)[source]¶

Return structure in its space group’s IT standard-setting conventional cell.

An existing ASUStructure (including an ASUStructureView, an ASU backend, or a full-cell view backed by one) is used exactly as stored. Supplying tolerance or limit_denominator for that path raises ValueError, because those arguments belong to recognition. Any other StructureLike is first passed to recognize_asu(). That tolerant step may snap measured coordinates onto symmetry positions and chooses the transform recorded in the result; it does not preserve an unstated input transform or promise a same_crystal() match to noisy input coordinates. The optional tolerance is a Cartesian matching distance and the optional denominator limit idealises free parameters.

The returned transform is the existing ASU’s transform, or the transform chosen by recognition for a plain input; the returned asu has an identity transform. Construction and expansion are exact, including the rhombohedral case where the standard hexagonal cell contains three primitive cells. Basis precision is multiplied by M.T() and coordinate precision by the maximum absolute column sum of inv(M.T()); unknown precision remains unknown. Requires a fully 3D-periodic structure.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike | httk.atomistic.models.structure.asu.ASUStructure) – The structure or asymmetric-unit structure to standardize.
tolerance (float | None) – The Cartesian recognition tolerance, or None to derive it.
limit_denominator (int | None) – The maximum denominator for idealised free parameters, or None to retain their exact stated values.

Returns:

The standardized structure and transform metadata.

Raises:

ImportError – If recognition is needed and the optional spglib dependency is unavailable.
ValueError – If recognition arguments are supplied for an existing ASU, the structure is not fully periodic, or unsupported site moments are present.

Return type:

ConventionalCellResult

httk.atomistic.maximal_subgroups(spacegroup)[source]¶

Return the distinct tabulated maximal-subgroup IT numbers.

Self-referencing isomorphic entries are excluded from graph navigation.

Parameters:: spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – A space group or IT number identifying the parent.
Returns:: Sorted unique target IT numbers, excluding spacegroup itself.
Raises:: KeyError – If the IT number has no vendored subgroup record.
Return type:: tuple[int, Ellipsis]

httk.atomistic.minimal_supergroups(spacegroup)[source]¶

Return the distinct tabulated minimal-supergroup IT numbers.

Self-referencing isomorphic entries are excluded from graph navigation.

Parameters:: spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – A space group or IT number identifying the subgroup.
Returns:: Sorted unique parent IT numbers, excluding spacegroup itself.
Raises:: KeyError – If the IT number has no vendored subgroup record.
Return type:: tuple[int, Ellipsis]

class httk.atomistic.SubgroupRepresentationResult[source]¶

Store an exact asymmetric-unit representation in a subgroup.

Parameters:

asu – The subgroup-standard-setting asymmetric unit with identity transform.
spacegroup – The subgroup space group in its standard setting.
path – The selected maximal-subgroup transforms, in parent-first order.
multiplier – The exact child-to-parent cell-content ratio.

asu: httk.atomistic.models.structure.asu.ASUStructure¶

spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup¶

path: tuple[SubgroupTransform, Ellipsis]¶

multiplier: fractions.Fraction¶

httk.atomistic.subgroup_closure(spacegroup, *, include_self=False)[source]¶

Return the graph-derived transitive subgroup closure.

Parameters:

spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – A space group or IT number identifying the parent.
include_self (bool) – Include the root IT number in the result.

Returns:

Sorted reachable subgroup IT numbers.

Raises:

KeyError – If the IT number has no vendored subgroup record.

Return type:

tuple[int, Ellipsis]

httk.atomistic.subgroup_representation(structure, subgroup)[source]¶

Express an exact ASU in a subgroup’s IT standard setting.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The fully periodic parent asymmetric-unit structure.
subgroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The target subgroup space group or IT number.

Returns:

The child ASU, selected maximal-subgroup path, and exact multiplier.

Raises:

TypeError – If structure is not an ASUStructure.
ValueError – If the structure is not fully periodic, carries site moments, assemblies, or molecular semantics, or if the target is not reachable.

Return type:

SubgroupRepresentationResult

httk.atomistic.supergroup_closure(spacegroup, *, include_self=False)[source]¶

Return the graph-derived transitive supergroup closure.

Parameters:

spacegroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – A space group or IT number identifying the subgroup.
include_self (bool) – Include the root IT number in the result.

Returns:

Sorted reachable supergroup IT numbers.

Raises:

KeyError – If the IT number has no vendored subgroup record.

Return type:

tuple[int, Ellipsis]

httk.atomistic.canonical_asu(structure, *, tolerance=None, factors=(Fraction(1, 5), 1, 5), lift=False)[source]¶

Return the canonical ASUStructure of a measured structure’s symmetry.

This is the noisy-input counterpart to canonicalize(): it recognizes the symmetry of a measured structure with spglib and then canonicalizes the result exactly.

An ASUStructure input is expanded to its unit cell first and the symmetry is re-recognized from the actual coordinates – always from the geometry, never the declared label. Re-recognition can raise a declared symmetry (a hand-written low-symmetry cell whose coordinates in fact support more) and can also lower it (a declared symmetry the coordinates do not support at the derived tolerance).

Recognition is swept over the base * factor symprecs from loosest to tightest. A member is accepted only when its recognized model reproduces every input site within the base tolerance (never the swept one), by an injective same-species match, and matches the per-species site counts. The first accepted member wins – by the same operation-count monotonicity the loosest fitting member is the highest-symmetry one – so recognition (and the expensive stage) runs once in the common case, and a looser member still rescues a tolerance-boundary flip a tighter one fails.

lift selects the expensive stage applied to that winner:

lift=False (default): it is mapped to the deterministic canonical representative within its recognized group – the exact terminal representation (setting, origin, orbit representatives, basis orientation all fixed), returned without searching upward. The result is the canonical form of the recognized symmetry; no pseudosymmetry above it is sought. Per-structure cost is essentially recognition-bound.
lift=True: it is additionally run through the exact upward search (canonicalize()) to find higher pseudosymmetry the recognition missed. This is exact but can be expensive – minutes and beyond for low-symmetry, many-atom cells.

Tolerance bound: the recognition stage is held to the base tolerance – every returned atom sits within base of the input. Under lift=False that is the whole bound (no further hops). Under lift=True each lift hop can move coordinates and snap the metric by up to another base and the residual/path are not re-checked here, so the returned structure’s distance from the input is bounded roughly by base * (1 + hops).

Determinism: the recognition stage is floating-point/spglib-based, so its outcome is reproducible on one platform but may differ across floating-point architectures or spglib builds. The exact stage is platform-independent and erases spglib’s representational freedom, so cross-platform variation is confined to which symmetry is accepted near a tolerance boundary, never to how an accepted symmetry is represented. Free-parameter values are least-squares fits of the measured coordinates, so two noisy measurements of the same crystal reach the same Wyckoff choices but slightly different rational parameter values.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The measured structure, UnitcellStructure or ASUStructure.
tolerance (float | None) – The base Cartesian tolerance, or None to derive it from the structure’s stated precision (structure_tolerance()).
factors (tuple[fractions.Fraction | float | int, Ellipsis]) – Multipliers for the recognition symprec sweep; each candidate symprec is base * factor.
lift (bool) – Whether to search upward for pseudosymmetry above the recognized group (default False: return the canonical representative of the recognized symmetry).

Returns:

The canonical asymmetric unit.

Raises:

ImportError – If spglib is unavailable when symmetry must be searched (the error names the httk-atomistic[default] extra).
ValueError – If recognition fails or is rejected at every swept tolerance.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

class httk.atomistic.LiftResult[source]¶

One exact or tolerance-accepted parent representation.

Parameters:

asu – The parent-standard-setting asymmetric unit.
spacegroup – The parent space group in standard setting.
path – Child-first tabulated parent-to-child subgroup transforms used.
shift – The continuous-normalizer origin shift from the final hop, expressed in that hop’s parent standard frame. path and shift document the lift route; they do not by themselves reconstruct asu, since highest_symmetry() additionally passes each state through an unrecorded normal form and canonical orientation. asu is authoritative.
residual – The largest wrapped fractional residual accepted.

asu: httk.atomistic.models.structure.asu.ASUStructure¶

spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup¶

path: tuple[httk.atomistic.symmetry.subgroups.SubgroupTransform, Ellipsis]¶

shift: httk.core.FracVector¶

residual: fractions.Fraction¶

httk.atomistic.backward_lift(structure, supergroup, *, tolerance=None)[source]¶

Return all exact or tolerance-accepted lifts into one minimal supergroup.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The child-group asymmetric unit to lift.
supergroup (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The one-hop parent space group or IT number.
tolerance (float | None) – Cartesian acceptance tolerance, or the recognition-derived default.

Returns:

Distinct parent representations in table order and canonical order.

Raises:

ValueError – If the input is unsupported or the target is not one hop above it.

Return type:

tuple[LiftResult, Ellipsis]

A bounded normalizer retry applies tabulated cosets to child fractional coordinates and maps successful results back with the exact inverse, in tabulated coset order.

httk.atomistic.canonicalize(structure, *, tolerance=None)[source]¶

Return the first deterministic highest-symmetry representation.

The result is the normalizer-canonical representative of the input’s crystal: the same exact (it_number, sorted (species, wyckoff, free_params), cell basis) for any origin shift, cell-basis choice (relabeling/shear), or site ordering of that crystal, and coherent with direct entry at its own space group. See highest_symmetry() for the full contract; for a P1/unit-cell start build the ASU in SG 1 and pass it here.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The structure to canonicalize.
tolerance (float | None) – Cartesian acceptance tolerance, or the recognition-derived default.

Returns:

The canonical terminal lift.

Return type:

LiftResult

httk.atomistic.highest_symmetry(structure, *, tolerance=None, all_paths=False)[source]¶

Return all terminal upward lifts reached by breadth-first search.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The starting asymmetric-unit structure.
tolerance (float | None) – Cartesian acceptance tolerance, or the recognition-derived default.
all_paths (bool) – When False (default) the visited set collapses alternate Bärnighausen routes to one entry per state, so each terminal appears once. When True the visited set also keys on the accumulated path, so every distinct (terminal, path) pair is returned; the .asu representatives of the extra results are identical, only path differs. The state cap therefore binds sooner under the flag.

Returns:

Deterministically ordered highest-symmetry representations.

Raises:

ValueError – If the input is unsupported, or if the breadth-first search exceeds its visited-state cap. A per-parent modular-solver branch-cap failure is not raised: that parent target is skipped and reported through the "symmetry" warning channel, so in that rare case the returned symmetry may be lower than the true maximum. The noisy least-squares fallback is capped the same way – a candidate whose integer-wrap box exceeds the noisy cap is skipped (also on the "symmetry" warning channel), which could likewise lower the returned symmetry for a genuinely noisy large-box lift.

Return type:

tuple[LiftResult, Ellipsis]

An exact P1 supercell entry is first collapsed to its unique primitive description (any multiplicity or sublattice orientation), and a triclinic (SG 1 or 2) entry is then Niggli-reduced so the search is independent of the input basis choice. Each search state is then reduced to its normalizer-canonical normal form – special-site demotion plus the continuous- and discrete-Euclidean-normalizer translation quotients and the affine-normalizer coset quotient – collapsing origin-, basis- and normalizer-equivalent representations to one visited entry so the search terminates from a raw P1 input. The returned asu is that normalizer-canonical representative, its cell placed in the standard orientation of its metric, so the result is invariant under origin shift, cell-basis choice, and site order for the same crystal. path records the tabulated hops of the route that reached it, and a bounded normalizer retry along that route applies tabulated cosets to child coordinates and maps results back with the exact inverse, in tabulated coset order.

httk.atomistic.lift_candidates(structure, *, tolerance=None)[source]¶

Return all one-hop parent lifts in deterministic order.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The child-group asymmetric unit to lift.
tolerance (float | None) – Cartesian acceptance tolerance, or the recognition-derived default.

Returns:

Results ordered by parent IT number, table order, and exact key.

Return type:

tuple[LiftResult, Ellipsis]

httk.atomistic.rerepresent(structure, target, *, tolerance=None)[source]¶

Express a structure in a reachable subgroup or supergroup setting.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The input asymmetric-unit structure.
target (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The target space group or IT number.
tolerance (float | None) – Cartesian acceptance tolerance for upward lifts.

Returns:

The target-group asymmetric unit.

Raises:

ValueError – If the target is unrelated, an upward hop has no lift, or a cross-group rerepresentation requires descending or lifting a structure with site moments, assemblies, or molecular semantics.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

class httk.atomistic.StructurePath[source]¶

A finite exact interpolation path between two aligned asymmetric units.

Parameters:

frames – The endpoint-inclusive asymmetric-unit frames.
spacegroup – The shared space group and setting of all frames.
start – The first frame.
end – The last frame.

frames: tuple[httk.atomistic.models.structure.asu.ASUStructure, Ellipsis]¶

spacegroup: httk.atomistic.symmetry.spacegroup.Spacegroup¶

start: httk.atomistic.models.structure.asu.ASUStructure¶

end: httk.atomistic.models.structure.asu.ASUStructure¶

httk.atomistic.canonicalize_full(structure, target, *, tolerance=None)[source]¶

Return the canonically least representation of a crystal in a target group’s standard setting.

The least element, by exact orbit-canonical site key then cell gram, of list_representations(). On the crystal’s own group this is a normalizer-canonical form: it selects the same representative the upward search’s normal form does, over the same discrete normalizer crossing and modulo the continuous quotient. It is idempotent – re-running it on its own result in the same target returns that result.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The crystal, as an asymmetric-unit structure.
target (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The target space group or IT number.
tolerance (float | None) – Cartesian acceptance tolerance passed to any upward lift; None derives it.

Returns:

The canonically least representation in target’s standard setting.

Raises:

ValueError – If target is unrelated, or the input is unsupported.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.interpolate_structures(start, end, *, steps, tolerance=None)[source]¶

Build an exact symmetry-preserving linear interpolation.

Free parameters follow the wrapped shortest rational displacement and cell bases are linearly interpolated in the shared setting. Every intermediate frame is expanded so a collision with an already occupied orbit is reported with its step index. Frames carry the start structure’s setting transform, while their Wyckoff parameters remain standard- setting values.

Parameters:

start (httk.atomistic.models.structure.asu.ASUStructure) – The first endpoint.
end (httk.atomistic.models.structure.asu.ASUStructure) – The second endpoint.
steps (int) – Number of endpoint-inclusive frames, at least two.
tolerance (float | None) – Cartesian tolerance passed to upward rerepresentation.

Returns:

The exact interpolation path.

Raises:

ValueError – If endpoints cannot be aligned, charges differ, or an intermediate frame is invalid.

Return type:

StructurePath

httk.atomistic.list_representations(structure, target, *, tolerance=None)[source]¶

Return every distinct representation of one crystal in a target group’s standard setting.

The crystal is first expressed once in target by rerepresent() – an exact descent for a subgroup target, a round-trip-gated lift for a supergroup target, itself for the same group – and the full discrete affine-normalizer orbit of that one realization is then enumerated. Every representation is returned in its continuous-translation normal form (otherwise a polar or triclinic target would have infinitely many), deduplicated by exact orbit-canonical site key and cell gram, and sorted by that key.

Scope. When target is the crystal’s own full symmetry group, two representations differ only by an element of that group’s affine normalizer, so this one orbit is the complete set – modulo the continuous normalizer and limited only by the bounded tabulated coset table. For a PROPER-SUBGROUP (or supergroup) target only the normalizer orbit of the single rerepresent() embedding is returned; inequivalent embeddings reachable by other descent chains – the same crystal at the same cell size but a genuinely different site placement – are deliberately out of scope and are NOT returned, because enumerating every chain is combinatorially explosive for deep targets (many tabulated chains), so a single canonical embedding is chosen. Representations needing an untabulated conventional-cell re-choice (the A.5 recell-class freedom) are likewise not generated. A supercell description is the same crystal in a larger cell; it too is not enumerated – the exclusion there is “not a distinct representation at the same cell size”, not “not the same crystal”.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The crystal, as an asymmetric-unit structure.
target (httk.atomistic.symmetry.spacegroup.Spacegroup | int) – The target space group or IT number.
tolerance (float | None) – Cartesian acceptance tolerance passed to any upward lift; None derives it.

Returns:

The distinct representations in target’s standard setting, sorted by canonical key.

Raises:

ValueError – If target is unrelated to the crystal’s group, or the input is unsupported by the exact symmetry machinery.

Return type:

tuple[httk.atomistic.models.structure.asu.ASUStructure, Ellipsis]

httk.atomistic.represent_like(structure, reference, *, tolerance=None)[source]¶

Represent a structure in a reference’s group and setting.

The input is first sent through rerepresent(), then equivalent affine-normalizer coset images of that one descent realization are scored against the reference. This is deliberately bounded: tabulated variants of alternate multi-hop descent paths are not enumerated because rerepresent() exposes only its deterministic selected realization. Site pairing is brute force and capped at 40,320 permutations per class; larger classes require a future assignment solver.

Parameters:

structure (httk.atomistic.models.structure.asu.ASUStructure) – The structure to represent.
reference (httk.atomistic.models.structure.asu.ASUStructure) – The structure supplying the group, setting, and alignment target.
tolerance (float | None) – Cartesian tolerance passed to upward rerepresentation.

Returns:

The input represented in the reference’s group and setting.

Raises:

ValueError – If the groups are unrelated, signatures differ, or the input is unsupported by the exact symmetry machinery.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

class httk.atomistic.WyckoffPosition(record)[source]¶

Represent a Wyckoff position of one space-group setting.

Parameters:: record (collections.abc.Mapping[str, Any]) – The vendored record describing the Wyckoff position.

classmethod from_record(record)[source]¶

Build a Wyckoff position from a vendored record.

Parameters:: record (collections.abc.Mapping[str, Any]) – The vendored Wyckoff-position record.
Returns:: The corresponding Wyckoff position.
Return type:: Self

property letter: str¶

Return the bare Wyckoff letter, such as "e".

Returns:: The Wyckoff letter without a multiplicity prefix.
Return type:: str

property multiplicity: int¶

Return the number of sites generated by one parameter set.

Returns:: The position multiplicity in the unit cell.
Return type:: int

property site_symmetry: str¶

Return the site-symmetry group in Hermann-Mauguin notation.

Returns:: The site-symmetry symbol.
Return type:: str

property free: tuple[int, Ellipsis]¶

Return the indices of the free parameters in (x, y, z).

Returns:: The free-parameter indices.
Return type:: tuple[int, Ellipsis]

property free_count: int¶

Return the number of degrees of freedom of the position.

Returns:: The number of free parameters, from zero through three.
Return type:: int

property branches: tuple[WyckoffBranch, Ellipsis]¶

Return the complete, deduplicated orbit branches.

Returns:: One branch for each equivalent site.
Return type:: tuple[WyckoffBranch, Ellipsis]

property representative: WyckoffBranch¶

Return the first orbit member printed as first_orbit in the tables.

Returns:: The representative orbit branch.
Return type:: WyckoffBranch

coordinates(parameters)[source]¶

Compute every coordinate of the orbit as an exact (multiplicity, 3) block.

Not wrapped and not deduplicated: within one setting the tabulated orbit is already distinct, so wrapping is the caller’s business (and matters only once a setting transform enters).

Parameters:: parameters (Any) – The free-parameter values for the position.
Returns:: The unwrapped coordinates of all orbit branches.
Raises:: ValueError – If the number of parameters does not match a branch.
Return type:: httk.core.FracVector

parameters_of(coordinate)[source]¶

Recover free parameters placing some branch on coordinate, if possible.

Tries every branch, not only the representative. That matters: across the vendored tables, 11673 of the 20639 non-representative orbit members lie on a different branch than the representative, so a matcher that only tested first_orbit would reject a majority of legitimate orbit points.

Parameters:: coordinate (Any) – The exact reduced coordinate to match.
Returns:: The normalized free parameters, or None when no branch matches.
Return type:: httk.core.FracVector | None

httk.atomistic.wyckoff_positions(record)[source]¶

Build the Wyckoff positions of a setting record, most specific first.

Ordered by (free_count, multiplicity, letter) so that the first match found when identifying a coordinate is the most specific position it lies on. Ties do not arise: positions are affine subspaces, so a coordinate on two distinct positions of the same dimension also lies on their lower-dimensional intersection, which is covered by an earlier entry.

Parameters:: record (collections.abc.Mapping[str, Any]) – The vendored space-group setting record.
Returns:: The setting’s ordered Wyckoff positions.
Return type:: tuple[WyckoffPosition, Ellipsis]

httk.atomistic.asu_structure_from_cif(data, *, tolerance=None, limit_denominator=None, trust_declared_symmetry=True, allow_large_cif_uncertainty=False, autocorrect=False)[source]¶

Build an exact ASUStructure from a neutral CIF mapping.

data is one block of the mapping returned by httk.atomistic.io.cif (its format must be "cif").

The cell is built exactly from the file’s a, b, c, alpha, beta, gamma rather than from the pre-multiplied floating-point basis, so a cubic cell keeps exact right angles and a hexagonal one keeps its sqrt(3) instead of inheriting rounding noise.

Coordinates are embedded as the rational the file literally wrote — 0.3333 is 3333/10000, not the binary value of float("0.3333") — and are then snapped onto the Wyckoff position they lie within tolerance of. That snapping is the only tolerant step; see recognition for the full contract.

tolerance left unspecified is derived from the precision the file’s own digits imply, so a coarsely written file is matched loosely and a carefully written one tightly, without anybody choosing a constant.

Site occupancies become the composition of the corresponding Species, so a half-occupied site survives into the structure instead of being dropped.

trust_declared_symmetry=False ignores the file’s declared Hall symbol or space-group number and identifies the setting from its symmetry operations alone; see cif_setting() for when that is the right thing to do.

Parameters:

data (collections.abc.Mapping[str, Any]) – One loaded CIF data block.
tolerance (float | None) – The Cartesian matching tolerance, or None to derive it from the CIF.
limit_denominator (int | None) – The maximum denominator for snapped free parameters, if supplied.
trust_declared_symmetry (bool) – Whether to validate the declared symmetry before matching operations.
allow_large_cif_uncertainty (bool) – Whether to allow positional uncertainty at or above one angstrom.
autocorrect (bool) – Apply documented CIF input repairs with warnings.

Returns:

The exact asymmetric-unit structure.

Raises:

ValueError – If the block format, symmetry, coordinates, occupancies, or Wyckoff matches are invalid.

Return type:

httk.atomistic.models.structure.asu.ASUStructure

httk.atomistic.asu_structures_from_cif(payload, *, autocorrect=False, **options)[source]¶

Return every structure in a loaded CIF payload, one per structural data block.

Accepts either a whole loaded payload (with blocks) or a single block.

Reading a CIF is tolerant — a file may hold blocks that are not structures at all — but asking it for structures is not. If the file yielded none, the reasons the reader recorded are raised here rather than returning an empty list, so a file that could not be interpreted does not read as a file that contained nothing.

Parameters:

payload (collections.abc.Mapping[str, Any]) – The loaded whole-CIF payload or one loaded CIF block.
autocorrect (bool) – Apply documented CIF input repairs, also enabled by a stamped payload.
**options (Any) – Options forwarded to asu_structure_from_cif().

Returns:

One asymmetric-unit structure for each structural data block.

Raises:

ValueError – If the payload has no interpretable structural data or a block is invalid.

Return type:

list[httk.atomistic.models.structure.asu.ASUStructure]

httk.atomistic.cif_setting(data, *, trust_declared_symmetry=True)[source]¶

The space-group setting a CIF block is written in.

The setting is identified from the file’s symmetry operations, by exact set comparison against the tabulated settings. That is what makes a file written in a non-standard setting come out as itself rather than being silently reinterpreted.

What the file declares — a Hall symbol, an International Tables number, or a recognized H-M symbol — is treated as a claim to be checked, not a hint to be taken or dropped. A declaration that names no known setting, or that names one whose operations are not the file’s, is a genuine inconsistency in the file and raises rather than being worked around: the two halves of the file disagree, and quietly believing one of them is how a wrong structure gets built. An unrecognized H-M spelling is the exception and remains ignored.

Pass trust_declared_symmetry=False to ignore the declaration entirely and identify the setting from the operations alone. That is the escape hatch for a file whose symbols are known to be wrong but whose operations are good.

A Hermann-Mauguin symbol is consulted, when neither a Hall symbol nor an International Tables number is declared, only if its normalized spelling is recognized. A recognized symbol narrows the candidate IT number; the operations still identify the exact setting and a contradiction fails like a contradicting IT-number declaration. Unrecognized H-M spellings are ignored for compatibility with the previous operations-only behavior.

Raises ValueError when the block states no operations, when a declaration is inconsistent with them, or when the operations match no tabulated setting at all. In the last case the transform to the standard setting genuinely cannot be derived — infinitely many are equally valid and they describe different crystals — so such a file has to be built with an explicit SettingTransform.

Parameters:

data (collections.abc.Mapping[str, Any]) – The loaded CIF data block.
trust_declared_symmetry (bool) – Whether to check the declared Hall, IT, or H-M symbol.

Returns:

The tabulated space-group setting matching the block’s operations.

Raises:

ValueError – If operations are absent, inconsistent with the declaration, or unknown.

Return type:

httk.atomistic.symmetry.spacegroup.Spacegroup

class httk.atomistic.Assembly[source]¶

Represent one site-disorder assembly without normalizing its probabilities.

Parameters:

sites_in_groups – The non-overlapping site-index groups in the assembly.
group_probabilities – The probability assigned to each group.
group_probabilities_precision – The precision of each group probability, if known.

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

group_probabilities: tuple[fractions.Fraction, Ellipsis]¶

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

property normalized: bool¶

Whether the group probabilities sum to one within their precision.

property normalization_status: str¶

Return the probability normalization status.

property normalization_diagnostic: httk.atomistic.models.formula.diagnostics.CompositionDiagnostic | None¶

Return the normalization diagnostic, if the probabilities are outside precision.

class httk.atomistic.ChemicalComposition(amounts, mode='implicit', amounts_precision=None)[source]¶

Store explicit elemental amounts as additional or authoritative composition.

implicit amounts supplement the site-derived composition; full amounts replace it while still recording a mismatch diagnostic when the two disagree.

Parameters:

amounts (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]]) – The positive amounts for named chemical elements.
mode (Literal['implicit', 'full']) – Whether the amounts are "implicit" or authoritative "full" values.
amounts_precision (collections.abc.Mapping[str, Any] | collections.abc.Iterable[tuple[str, Any]] | None) – The precision of the stated amounts, if known.

amounts: tuple[tuple[str, fractions.Fraction], Ellipsis]¶

amounts_precision: tuple[tuple[str, fractions.Fraction | None], Ellipsis]¶

mode: Literal['implicit', 'full']¶

property elements: tuple[str, Ellipsis]¶

Return the element symbols in the stored amount order.

property amount_mapping: collections.abc.Mapping[str, fractions.Fraction]¶

Return the elemental amounts as a read-only mapping.

property precision_mapping: collections.abc.Mapping[str, fractions.Fraction | None]¶

Return the amount precisions as a read-only mapping.

httk.atomistic.atomic_number(symbol)[source]¶

Return the atomic number of an element symbol.

The pseudo-symbols "X" and "vacancy" are not elements here.

Parameters:: symbol (str) – The IUPAC element symbol.
Returns:: The element’s atomic number.
Raises:: ValueError – If symbol is not one of the 118 element symbols.
Return type:: int

httk.atomistic.symbol_of(z)[source]¶

Return the element symbol for an atomic number.

Parameters:: z (int) – The atomic number in the range 1 through 118.
Returns:: The corresponding IUPAC element symbol.
Raises:: ValueError – If z is outside the range 1 through 118.
Return type:: str

class httk.atomistic.SupercellResult[source]¶

Store a materialized supercell with its exact construction metadata.

orthogonality_score is the sum of the squared pairwise cosines between cell vectors. cubicity_score is the squared Frobenius distance between the trace-normalized Gram matrix and the identity. Both are exact SurdScalar values; zero proves the ideal shape exactly.

Parameters:

structure – The resulting full-periodic unit-cell structure.
transformation – The integer row-convention transformation applied to the source basis.
multiplier – The exact number of source cells represented in the result.
orthogonality_score – The exact orthogonality score of the result.
cubicity_score – The exact cubicity score of the result.

structure: httk.atomistic.models.structure.unitcell.UnitcellStructure¶

transformation: httk.core.FracVector¶

multiplier: int¶

orthogonality_score: httk.core.SurdScalar¶

cubicity_score: httk.core.SurdScalar¶

httk.atomistic.build_supercell(structure, transformation, *, max_sites=DEFAULT_MAX_SITES)[source]¶

Build the exact supercell selected by an integer transformation matrix.

Lattice vectors are rows and the returned basis is transformation * basis. Reduced coordinates are transformed by the inverse matrix and wrapped into [0, 1). Any input representation is first presented as a full UnitcellStructure. Crystal-axis site moments are converted to Cartesian moments because the supercell has new crystal axes; Cartesian and collinear moments retain their representation. Structure charge and explicit composition amounts are scaled by the exact cell-content multiplier.

Requires a fully 3D-periodic structure. Repeating a slab within its own plane is a perfectly sensible operation, but it is not this one: the transformation matrix here mixes all three rows and the coordinates are wrapped in all three directions, so applied to a reduced-periodicity cell it would generate images along a direction that has no lattice translation. Refused rather than half-supported.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The structure to replicate.
transformation (httk.core.VectorLike | int) – A nonsingular integer transformation matrix, or a positive integer selecting a diagonal repetition.
max_sites (int | None) – The maximum allowed resulting site count, or None for no limit.

Returns:

The materialized supercell and its exact construction metadata.

Raises:

ValueError – If the transformation, site limit, cell, or periodicity is invalid.

Return type:

SupercellResult

httk.atomistic.cubic_supercell(structure, multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=DEFAULT_MAX_SITES)[source]¶

Build the most cubic supercell in the bounded candidate set.

Exactly one of multiplier and tolerance must be provided. With multiplier, it is the exact number of source cells in the result. With tolerance, the multiplier is increased from one until the exact cubicity score is at most the given bound, up to max_multiplier. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most search_radius (0–2); diagonal factorizations provide guaranteed determinant-matching fallbacks.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The structure to replicate.
multiplier (int | None) – The exact positive cell-content multiplier, or None to search.
tolerance (fractions.Fraction | str | float | None) – The maximum cubicity score, or None to use multiplier.
max_multiplier (int | None) – The largest multiplier considered during a tolerance search.
search_radius (int) – The integer-entry radius around the ideal candidate transform.
max_sites (int | None) – The maximum resulting site count, or None for no limit.

Returns:

The selected supercell and its exact construction metadata.

Raises:

ValueError – If the arguments are inconsistent, invalid, or no candidate meets the bound.

Return type:

SupercellResult

httk.atomistic.orthogonal_supercell(structure, multiplier=None, *, tolerance=None, max_multiplier=None, search_radius=1, max_sites=DEFAULT_MAX_SITES)[source]¶

Build the most orthogonal supercell in the bounded candidate set.

Exactly one of multiplier and tolerance must be provided. With multiplier, it is the exact number of source cells in the result. With tolerance, the multiplier is increased from one until the exact orthogonality score is at most the given bound, up to max_multiplier. Candidate matrices are centered on the ideal cubic real-valued transform and vary each integer entry by at most search_radius (0–2); diagonal factorizations provide guaranteed determinant-matching fallbacks. Exact orthogonality is ranked first and cubicity breaks equal-shape ties.

Parameters:

structure (httk.atomistic.models.structure.like.StructureLike) – The structure to replicate.
multiplier (int | None) – The exact positive cell-content multiplier, or None to search.
tolerance (fractions.Fraction | str | float | None) – The maximum orthogonality score, or None to use multiplier.
max_multiplier (int | None) – The largest multiplier considered during a tolerance search.
search_radius (int) – The integer-entry radius around the ideal candidate transform.
max_sites (int | None) – The maximum resulting site count, or None for no limit.

Returns:

The selected supercell and its exact construction metadata.

Raises:

ValueError – If the arguments are inconsistent, invalid, or no candidate meets the bound.

Return type:

SupercellResult

class httk.atomistic.NiggliReducedStructureResult[source]¶

Store a structure whose cell and fractional coordinates are in Niggli form.

transform uses the row-vector convention basis_reduced = transform * basis; site coordinates are remapped by its exact inverse and wrapped into [0, 1).

Parameters:

structure – The structure expressed in the reduced cell.
cell – The reduced cell.
transform – The integer row-convention transform from the source basis.

structure: httk.atomistic.models.structure.unitcell.UnitcellStructure¶

cell: httk.atomistic.models.cell.cell.Cell¶

transform: httk.core.FracVector¶

class httk.atomistic.NiggliReductionResult[source]¶

Store a cell in exact Niggli-reduced form.

transform uses the row-vector convention basis_reduced = transform * basis. Its entries are integers and its determinant is +1. parameters contains the reduced (A, B, C, xi, eta, zeta) metric parameters as exact fractions.

Parameters:

cell – The reduced cell.
transform – The integer row-convention transform from the source basis.
parameters – The reduced exact metric parameters.

cell: httk.atomistic.models.cell.cell.Cell¶

transform: httk.core.FracVector¶

parameters: tuple[fractions.Fraction, Ellipsis]¶

httk.atomistic.is_niggli_reduced(cell)[source]¶

Return whether a fully periodic cell satisfies the complete exact Niggli conditions.

Parameters:: cell (httk.atomistic.models.cell.like.CellLike) – The cell to inspect.
Returns:: Whether the cell satisfies the exact Niggli conditions.
Raises:: ValueError – If the cell is not fully periodic or its Gram matrix is not rational.
Return type:: bool

httk.atomistic.niggli_reduce(cell)[source]¶

Return the exact Niggli reduction of a fully periodic cell.

The calculation uses the rational Gram matrix with no tolerance. The returned integer transform follows basis_reduced = transform * basis and has determinant +1.

Parameters:: cell (httk.atomistic.models.cell.like.CellLike) – The fully periodic cell to reduce.
Returns:: The reduced cell, transform, and exact metric parameters.
Raises:: ValueError – If the cell is not fully periodic or its Gram matrix is not rational.
Return type:: NiggliReductionResult

httk.atomistic.niggli_reduced(structure)[source]¶

Return a structure remapped into the exact Niggli-reduced cell.

The site order and count are unchanged. With row-vector fractional coordinates, the exact remapping is f_reduced = f_original * transform.inv() followed by periodic normalization. Species, species-at-sites order, Cartesian site moments, molecular information, assemblies, chemical composition, formulas, optimization type, charge, and precision are carried unchanged or propagated. Symmetry is invalidated because its operations are basis-relative; immutable identifiers and last-modified metadata are invalidated because this operation creates a derived structure.

Parameters:: structure (httk.atomistic.models.structure.like.StructureLike) – The structure to express in a Niggli-reduced cell.
Returns:: The reduced structure and its exact reduction metadata.
Raises:: ValueError – If the structure cell is not fully periodic or its Gram matrix is not rational.
Return type:: NiggliReducedStructureResult