httk.atomistic.symmetry.affine_operation

Exact rational affine maps on fractional coordinates.

An AffineOperation is a rotation part and a translation part held exactly as FracVector values. The same object serves for the two things this package does with affine maps — a crystallographic symmetry operation, and a change-of-basis between space-group settings — because they are the same algebra; only their interpretation differs (see SettingTransform for the latter).

Everything here is closed over the rationals: composing, inverting, conjugating, and applying an operation to reduced coordinates all stay exact. That is the whole reason the ASU machinery needs no tolerance.

Convention. The stored matrix is written for column vectors, matching how crystallographic tables print an operation (x' = W x + w, i.e. -x+1/2,y,-z). httk holds coordinates as rows, so AffineOperation.apply() evaluates coords * matrix.T() + vector. Both spellings describe the same map; only one of them is ever written out in code here.

Classes

AffineOperation

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

Module Contents

class httk.atomistic.symmetry.affine_operation.AffineOperation(matrix, vector=(0, 0, 0))

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()

Return the identity operation.

Returns:

The identity affine operation.

Return type:

Self

classmethod from_record(record)

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()

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()

Report whether this operation is the identity.

Returns:

Whether the matrix and translation are both identity values.

Return type:

bool

apply(coords)

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)

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()

Return the inverse map exactly.

Returns:

The inverse affine operation.

Raises:

ZeroDivisionError – If the rotation part is singular.

Return type:

AffineOperation

conjugated_by(change)

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()

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()

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