httk.atomistic.symmetry¶

Submodules¶

Classes¶

`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.
`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_letter_map`(standard, target)	Map standard-setting Wyckoff letters to their names in another setting.
`wyckoff_positions`(record)	Build the Wyckoff positions of a setting record, most specific first.
`operation_from_xyz`(operation)	Parse an exact three-coordinate crystallographic operation.
`operation_from_xyzt`(operation)	Parse an exact magnetic operation and return its time-reversal flag.
`parse_linear_expression`(expression[, allowed_vars])	Parse one superspace linear expression into integer coefficients and a translation.

Package Contents¶

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

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

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

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.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.symmetry.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.symmetry.operation_from_xyz(operation)[source]¶

Parse an exact three-coordinate crystallographic operation.

Parameters:: operation (str) – The comma-separated x,y,z operation string.
Returns:: The exact affine operation.
Raises:: ValueError – If the operation does not contain three valid coordinate expressions.
Return type:: httk.atomistic.symmetry.affine_operation.AffineOperation

httk.atomistic.symmetry.operation_from_xyzt(operation)[source]¶

Parse an exact magnetic operation and return its time-reversal flag.

The first three comma-separated fields use crystallographic x,y,z grammar; the fourth field must be +1 or -1.

Parameters:: operation (str) – The comma-separated x,y,z,time-reversal operation string.
Returns:: The affine operation and its time-reversal sign.
Raises:: ValueError – If the operation does not contain three coordinate expressions and a valid time-reversal flag.
Return type:: tuple[httk.atomistic.symmetry.affine_operation.AffineOperation, int]

httk.atomistic.symmetry.parse_linear_expression(expression, allowed_vars=_SUPERSPACE_VARS)[source]¶

Parse one superspace linear expression into integer coefficients and a translation.

The parser accepts the six superspace variables x1 through x6 by default and preserves an exact rational translation.

Parameters:

expression (str) – The linear expression to parse.
allowed_vars (collections.abc.Sequence[str]) – The variable names accepted in expression.

Returns:

The integer coefficients in allowed_vars and the exact translation.

Raises:

ValueError – If the expression is empty, malformed, or has a non-integer variable coefficient.

Return type:

tuple[tuple[int, Ellipsis], fractions.Fraction]