httk.atomistic.asu_recognition

Recognizing the asymmetric unit of a full structure.

This is the direction where tolerance lives, and the only one. A measured or file-read structure gives coordinates like 0.3333 that lie near a symmetric arrangement rather than on one, so recognizing it means deciding which Wyckoff position each site is meant to occupy. Once decided, the position supplies exact values for its fixed components and everything downstream — expansion, comparison, round-tripping — is exact again.

The contract, stated once so the asymmetry is not a surprise:

• Expansion (expand_sites()) is lossless.

• Recognition is lossy at the tolerance level: it snaps a measured structure onto an idealised symmetric one.

• Therefore expand -> recognize -> expand is idempotent, while recognize -> expand is not the identity on the input coordinates and must not be advertised as such.

A file’s decimals are embedded as the exact rational they literally say — 0.3333 is 3333/10000, never silently 1/3. Free parameters keep that value; only the fixed components of the chosen position are replaced. Idealising the free parameters too is available on request through limit_denominator, but it is not the default, because inventing 1/3 from a file that said 0.3333 is a claim about the data that only the caller can make.

Attributes

DEFAULT_TOLERANCE

Functions

structure_tolerance(→ float)	A matching tolerance derived from how precisely the structure was stated.
recognize_asu(→ httk.atomistic.asu_structure.ASUStructure)	Build an ASUStructure from a full structure.

Module Contents

httk.atomistic.asu_recognition.DEFAULT_TOLERANCE = 0.001

httk.atomistic.asu_recognition.structure_tolerance(structure: httk.atomistic.structure_like.StructureLike, *, fallback: float = DEFAULT_TOLERANCE) → float

A matching tolerance derived 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.

httk.atomistic.asu_recognition.recognize_asu(structure: httk.atomistic.structure_like.StructureLike, *, setting: httk.atomistic.spacegroup.Spacegroup | None = None, standard: httk.atomistic.spacegroup.Spacegroup | None = None, transform: httk.atomistic.setting_transform.SettingTransform | None = None, tolerance: float | None = None, limit_denominator: int | None = None) → httk.atomistic.asu_structure.ASUStructure

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.