httk.atomistic.symmetry.wyckoff¶

Exact rational Wyckoff-position algebra.

A Wyckoff position is a family of symmetry-equivalent sites parameterised by a few free coordinates: SG 15 letter e is 0,y,1/4, so one free parameter y places four symmetry-equivalent atoms. This module goes both ways between free parameters and coordinates, entirely over the rationals.

Two properties of the vendored tables make this much simpler than it looks, both asserted in tests/test_symmetry_data.py:

Each Wyckoff position’s orbit is already the complete, deduplicated list of affine maps, of length exactly multiplicity, with centering translations folded in. Generating an orbit is therefore a plain loop with no coincidence testing and no tolerance.
hasfreedom marks which of x, y, z are free, and the columns of every orbit matrix for the non-free variables are identically zero, with sum(hasfreedom) == rank. So the free parameters are read straight off, and the first_orbit strings ("1/8,y,-y+1/4") never need parsing — the same information is already present as an exact affine map.

Everything is expressed in the coordinates of whichever setting the record came from.

Classes¶

`WyckoffBranch`	Represent one member of a Wyckoff orbit as an affine parameter map.
`WyckoffPosition`	Represent a Wyckoff position of one space-group setting.

Functions¶

wyckoff_positions(record)

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

Module Contents¶

class httk.atomistic.symmetry.wyckoff.WyckoffBranch(operation, free)[source]¶

Represent one member of a Wyckoff orbit as an affine parameter map.

A position of multiplicity m has m branches. The representative branch is the first, but a coordinate may lie on any of them, which is why WyckoffPosition.parameters_of() tries them all.

Parameters:

operation (httk.atomistic.symmetry.affine_operation.AffineOperation) – The affine map for this orbit branch.
free (collections.abc.Sequence[int]) – The indices of the free parameters in (x, y, z).

property operation: httk.atomistic.symmetry.affine_operation.AffineOperation[source]¶

Return the affine map from (x, y, z) to this branch’s coordinate.

Returns:: The branch’s affine operation.
Return type:: httk.atomistic.symmetry.affine_operation.AffineOperation

property free: tuple[int, Ellipsis][source]¶

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

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

coordinate(parameters)[source]¶

Compute the coordinate this branch places at given free-parameter values.

parameters has one entry per free parameter. Because the non-free columns of the matrix are zero, the values placed at the non-free positions are irrelevant.

Parameters:: parameters (Any) – The free-parameter values for this branch.
Returns:: The exact reduced coordinate generated by the branch.
Raises:: ValueError – If the number of parameters does not match the branch.
Return type:: httk.core.FracVector

parameters_of(coordinate)[source]¶

Recover the free parameters putting this branch on coordinate, if possible.

None means the coordinate does not lie on this branch — for any lattice translation, not merely the one given. That completeness is what the row-Hermite form buys: with U unimodular over the integers, A t = d (mod Z^3) holds iff U A t = U d (mod Z^3), and the zero rows of U A turn the lattice-membership question into “are these components integers?” with no search over translations.

The returned parameters are reduced into [0, 1), which is canonical: the pivot block has determinant ±1 throughout the vendored tables, so the solution is unique modulo one. The result is verified by re-evaluating the branch, so a table that ever violated that assumption would yield a clean miss rather than a wrong answer.

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

nearest_parameters(coordinate)[source]¶

Compute free parameters that put this branch as close to coordinate as possible.

Unlike parameters_of() this always returns a value: the free directions are solved exactly and any discrepancy is left in the fixed directions, where the branch’s own coordinates win. It is the projection used when recognizing a measured structure, whose coordinates carry rounding and do not lie exactly on any position.

The projection is taken along the branch’s own lattice basis rather than being minimised in the cell metric, so for a strongly oblique cell it is a near-optimal rather than provably optimal choice. That is safe because the caller measures the resulting Cartesian displacement and rejects anything beyond its tolerance — the method can cost a match, never grant a wrong one.

Parameters:: coordinate (Any) – The reduced coordinate to approximate.
Returns:: The normalized free parameters for the nearest branch point.
Return type:: httk.core.FracVector

nearest_parameters_float(coordinate)[source]¶

Project a coordinate onto this branch in floating point for screening.

This deliberately mirrors nearest_parameters() without its exact verification. It is only a candidate-screening aid; callers must calculate and compare the final distance with the exact methods before accepting a match.

Parameters:: coordinate (collections.abc.Sequence[float]) – A reduced coordinate as three floating-point values.
Returns:: The normalized floating-point free parameters.
Return type:: tuple[float, Ellipsis]

coordinate_float(parameters)[source]¶

Evaluate this branch in floating point for candidate screening.

Parameters:: parameters (collections.abc.Sequence[float]) – One floating-point value for every free parameter.
Returns:: The unwrapped floating-point reduced coordinate.
Raises:: ValueError – If the parameter count is wrong.
Return type:: tuple[float, float, float]

class httk.atomistic.symmetry.wyckoff.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[source]¶

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

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

property multiplicity: int[source]¶

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

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

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

property free: tuple[int, Ellipsis][source]¶

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

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

Return the complete, deduplicated orbit branches.

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

property representative: WyckoffBranch[source]¶

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.symmetry.wyckoff.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]