crystallography

Modules:

Name	Description
crystallography
space_groups	Space group reference data.

Classes

Functions

Modules

crystallography

Classes:

Name	Description
WyckoffPosition	A resolved Wyckoff position and the orbit representative matched.

Functions:

Name	Description
apply_cell_symmetry_constraints	Apply symmetry constraints to unit cell parameters.
cell_symmetry_constrained_flags	Return cell-parameter symmetry-constraint flags.
apply_atom_site_symmetry_constraints	Apply symmetry constraints to atom site coordinates.
atom_site_symmetry_constrained_flags	Return atom-site symmetry-constraint flags.
snap_to_wyckoff_template	Project a coordinate onto a Wyckoff orbit-representative manifold.
detect_wyckoff_position	Detect the Wyckoff position a fractional coordinate occupies.
wyckoff_position_info	Look up a Wyckoff letter and optionally its representative.
space_group_wyckoff_table	Return the Wyckoff-position table for a space group, or None.
apply_atom_site_aniso_symmetry_constraints	Apply symmetry constraints to anisotropic ADP tensor components.
orthogonalization_matrix	Build the fractional-to-Cartesian orthogonalization matrix.
fractional_to_cartesian	Convert fractional coordinates to Cartesian using a cell matrix.
adp_principal_axes	Diagonalise a Cartesian ADP tensor into principal axes.
symmetry_operators	Return general-position symmetry operators for a space group.

Classes

WyckoffPosition(letter, multiplicity, site_symmetry, coord_template) dataclass

A resolved Wyckoff position and the orbit representative matched.

Attributes:

Name	Type	Description
letter	str	Wyckoff letter (e.g. 'h').
multiplicity	int	Site multiplicity (the full orbit size).
site_symmetry	str	International Tables site-symmetry symbol.
coord_template	str | None	Nearest matched orbit representative (e.g. '(x,-x,z)'), or None for a table lookup made without coordinates. This is what coordinate snapping and constrained-axis flags consume.

Functions

apply_cell_symmetry_constraints(cell, name_hm)

Apply symmetry constraints to unit cell parameters.

Parameters:

Name	Type	Description	Default
cell	dict[str, float]	Dictionary containing lattice parameters.	required
name_hm	str	Hermann-Mauguin symbol of the space group.	required

Returns:

Type	Description
dict[str, float]	The cell dictionary with applied symmetry constraints.

cell_symmetry_constrained_flags(name_hm)

Return cell-parameter symmetry-constraint flags.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required

Returns:

Type	Description
dict[str, bool]	Mapping of cell key to True when the parameter is constrained by symmetry (dependent on another parameter or set to a fixed angle), False when it is independent. Returns all keys False when the space group cannot be resolved.

apply_atom_site_symmetry_constraints(atom_site, name_hm, coord_code, wyckoff_letter)

Apply symmetry constraints to atom site coordinates.

Parameters:

Name	Type	Description	Default
atom_site	dict[str, Any]	Dictionary containing atom position data.	required
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	int	Coordinate system code.	required
wyckoff_letter	str	Wyckoff position letter.	required

Returns:

Type	Description
dict[str, Any]	The atom_site dictionary with applied symmetry constraints.

atom_site_symmetry_constrained_flags(name_hm, coord_code, wyckoff_letter)

Return atom-site symmetry-constraint flags.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	int	Coordinate system code.	required
wyckoff_letter	str	Wyckoff position letter.	required

Returns:

Type	Description
dict[str, bool]	Mapping 'fract_x' / 'fract_y' / 'fract_z' to True if the axis is fully determined by site symmetry. Returns all False when the Wyckoff position cannot be resolved.

snap_to_wyckoff_template(coord_template, fract_xyz)

Project a coordinate onto a Wyckoff orbit-representative manifold.

Solves the free Wyckoff parameters from the free (refinable) axes only — keeping those axes' values, so a minimizer's refined free coordinate is preserved — then derives the constrained axes from the template. Replaces per-axis symbol substitution: it handles coupled axes (e.g. (x,-x,z): keep fract_x, set fract_y=-fract_x) and off-canonical representatives (e.g. (0,x,0): keep fract_y, set fract_x=fract_z=0).

Parameters:

Name	Type	Description	Default
coord_template	str	Selected orbit representative, e.g. '(x,-x,z)' or '(0,x,0)'.	required
fract_xyz	tuple[float, float, float]	Current fractional coordinate.	required

Returns:

Type	Description
tuple[tuple[float, float, float], dict[str, bool]]	The snapped (x, y, z) (free axes kept, constrained axes derived; not reduced mod 1), and the per-axis constraint flags.

detect_wyckoff_position(name_hm, coord_code, fract_xyz, tol=_WYCKOFF_DETECTION_TOL)

Detect the Wyckoff position a fractional coordinate occupies.

Tests the coordinate for membership in every Wyckoff orbit of the resolved space group and returns the matched position with its nearest representative template. The winner is chosen by multiplicity ascending, then residual ascending (the most special site first); a rare same-multiplicity tie within tol is reported with a warning.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	str | None	Coordinate-system code.	required
fract_xyz	tuple[float, float, float]	Fractional coordinate to classify.	required
tol	float	Maximum residual for orbit membership.	_WYCKOFF_DETECTION_TOL

Returns:

Type	Description
WyckoffPosition | None	The matched position, or None when the space group is absent from SPACE_GROUPS.

wyckoff_position_info(name_hm, coord_code, letter, fract_xyz=None)

Look up a Wyckoff letter and optionally its representative.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	str | None	Coordinate-system code.	required
letter	str	Wyckoff letter to look up.	required
fract_xyz	tuple[float, float, float] | None	When given, the nearest orbit representative for letter is selected as coord_template; otherwise coord_template is None.	None

Returns:

Type	Description
WyckoffPosition | None	The position record, or None when the group or letter is absent.

space_group_wyckoff_table(name_hm, coord_code)

Return the Wyckoff-position table for a space group, or None.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	str | None	Coordinate-system code.	required

Returns:

Type	Description
dict[str, dict] | None	Mapping of Wyckoff letter to its multiplicity, site_symmetry, and coords_xyz record, or None when the space group is absent from SPACE_GROUPS.

apply_atom_site_aniso_symmetry_constraints(atom_site_aniso, name_hm, coord_code, _wyckoff_letter, site_fract)

Apply symmetry constraints to anisotropic ADP tensor components.

Uses the Peterse-Palm probe technique to determine which tensor components are constrained by the site symmetry, then delegates to cryspy's vibration_constraints to enforce them.

Parameters:

Name	Type	Description	Default
atom_site_aniso	dict[str, float]	Dictionary with keys 'adp_11' … 'adp_23'. Modified in place.	required
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	str | None	IT coordinate system code.	required
_wyckoff_letter	str	Wyckoff position letter (unused, reserved).	required
site_fract	tuple[float, float, float]	Fractional coordinates of the atom site.	required

Returns:

Type	Description
tuple[dict[str, float], tuple[bool, ...]]	The atom_site_aniso dictionary with constrained values, and a 6-tuple of booleans indicating which components remain free for refinement (True = free, False = fixed by symmetry).

orthogonalization_matrix(a, b, c, alpha, beta, gamma)

Build the fractional-to-Cartesian orthogonalization matrix.

Uses the standard crystallographic convention with the Cartesian x axis along a and b in the x-y plane (the IUCr / Busing-Levy setting). Edge lengths are in angstrom and angles in degrees.

Parameters:

Name	Type	Description	Default
a	float	Unit-cell edge length a (angstrom).	required
b	float	Unit-cell edge length b (angstrom).	required
c	float	Unit-cell edge length c (angstrom).	required
alpha	float	Unit-cell angle alpha (degrees).	required
beta	float	Unit-cell angle beta (degrees).	required
gamma	float	Unit-cell angle gamma (degrees).	required

Returns:

Type	Description
np.ndarray	The (3, 3) matrix M with r_cartesian = M @ r_fractional.

fractional_to_cartesian(frac, matrix)

Convert fractional coordinates to Cartesian using a cell matrix.

Parameters:

Name	Type	Description	Default
frac	object	A single (3,) fractional vector or an (n, 3) stack.	required
matrix	np.ndarray	The (3, 3) orthogonalization matrix from :func:orthogonalization_matrix.	required

Returns:

Type	Description
np.ndarray	Cartesian coordinates with the same shape as frac.

adp_principal_axes(tensor)

Diagonalise a Cartesian ADP tensor into principal axes.

Expects a symmetric (3, 3) U-type (mean-square displacement) tensor already in the Cartesian frame; conversion from the crystal frame and from B to U (U = B / (8 pi**2)) is the caller's responsibility. Returned semi-axes are RMS displacements (sqrt-eigenvalue); scaling to a probability level is done by the caller.

Parameters:

Name	Type	Description	Default
tensor	np.ndarray	Symmetric (3, 3) Cartesian U tensor.	required

Returns:

Type	Description
tuple[np.ndarray, np.ndarray]	semi_axes : (3,) RMS principal semi-axis lengths. orientation : (3, 3) matrix whose columns are the principal directions.

symmetry_operators(name_hm, coord_code=None)

Return general-position symmetry operators for a space group.

Thin public wrapper over the general-position lookup, resolving the International Tables number from the Hermann-Mauguin symbol. Falls back to the identity operator (so the asymmetric unit is still drawn) when the space group cannot be resolved.

Parameters:

Name	Type	Description	Default
name_hm	str	Hermann-Mauguin symbol of the space group.	required
coord_code	str | None	IT coordinate system code, when one applies.	None

Returns:

Type	Description
list[tuple[np.ndarray, np.ndarray]]	(rotation, translation) pairs; rotation a (3, 3) integer array, translation a (3,) fractional vector.

space_groups

Space group reference data.

Loads gzipped, packaged JSON with crystallographic space-group information. The file is part of the distribution; user input is not involved.