Python reference

symcrys: crystal classes

symcrys: crystallographic symmetry calculations, from Python.

A thin layer over the TypeScript library symcrys of the same version, which runs in an embedded JavaScript engine (quickjs-ng). Every function here calls the function of the same name in the library (camelCase there, snake_case here) and returns its result as plain Python data, matrices and vectors as NumPy arrays (rules in symcrys._convert; symcrys.plane converts its arrays itself, see its module docstring). The conventions, frames and print sources are documented once, for both languages: https://manganite.github.io/symcrys/conventions.html

This module is the crystallographic API: the 32 crystal classes, without time reversal. The magnetic point groups, time-odd tensors and operations with time reversal are in symcrys.magnetic, under the same function names; there "32" is the white group, and a crystal without magnetic order has the grey group of its class (quartz: "321'"). A question that involves time reversal raises SymcrysError here (docs/conventions.md, “Two entry points”). The plane groups and plane point groups are in symcrys.plane.

Each call costs about a millisecond or more (the forms of rank-4 tensors up to a few tenths of a second); fetch operations or forms once and compute with NumPy, rather than calling in a loop.

symcrys.CRYSTAL_FORM_TYPES: list[dict[str, Any]]

The 47 crystal forms of ITA Table 3.2.1.3 (6th ed., pp. 724–726) with ITA’s numbers, English names, numbers of faces and eigensymmetries: CRYSTAL_FORM_TYPES[n - 1] is form n. Each crystal form of crystal_forms names its form by this number (docs/conventions.md, “Crystal forms”).

symcrys.LATTICE_SYMMETRY_DIRECTIONS: dict[str, list[NDArray[int64]]]

The directions of each position of the full symbol, per family, as printed in ITA Table 2.1.3.1 (hexagonal family: the row “Hexagonal”, which also serves the trigonal classes with hexagonal axes). Monoclinic: the full symbol reads along a, b, c (ITA 6th ed. § 2.1.3.15, p. 171), the orthorhombic row. Triclinic: no symmetry direction.

In Python: family → one int64 array of shape (n, 3) per position, the n directions [uvw] as rows.

symcrys.POINT_GROUP_KEYS: tuple[str, ...]

Keys of the 32 crystal classes: the ITC short symbol of the class (docs/conventions.md, “Keys”).

symcrys.TENSOR_PROPERTIES: dict[str, dict[str, Any]]

The named tensor properties of the crystal classes: those of time-even tensors. 'gyrotropic' is optical activity. The properties of time-odd tensors ('ferromagnetic', …) are in the magnetic API.

symcrys.VERSION: str

The version of symcrys, the same for the TypeScript and the Python package.

exception symcrys.SymcrysError(message: str, js_name: str = 'Error')

An error raised by symcrys (e.g. an unknown key, setting or tensor specification).

js_name is the name of the JavaScript error (RangeError, TypeError, Error).

class symcrys.TensorForm
basis: NDArray[float64]

Of shape (number of parameters, 3**rank), in reduced row echelon form; flat index in C order.

parameters: NDArray[int64]

Of shape (number of parameters, rank); the components that are the free parameters.

relations: NDArray[float64]

Of shape (3**rank - number of parameters, 3**rank); rows r with r @ t = 0 for every allowed t.

class symcrys.TensorSpec

The kind of tensor.

symcrys.allowed_properties(key: str) → list[str]

The named properties the crystal class allows, in the order of TENSOR_PROPERTIES.

symcrys.allowed_properties_of(operations: Sequence[Mapping[str, Any]]) → list[str]

The named properties the group generated by operations allows. Checks the operations as allows_property_of.

symcrys.allows_property(key: str, name: Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic']) → bool

True if the crystal class allows the named property, e.g. allows_property('-6m2', 'piezoelectric'): the tensor that describes it (TENSOR_PROPERTIES) has a non-zero form under the class. Symmetry only allows a property; whether a crystal shows it is a question of the material. It does not depend on setting or convention. Raises SymcrysError for an unknown key or name.

symcrys.allows_property_of(operations: Sequence[Mapping[str, Any]], name: Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic']) → bool

True if the group generated by operations allows the named property, e.g. for the site symmetry of a surface normal or the operations of a distorted crystal. The matrices must be Cartesian and orthogonal; a list that is not closed is closed first. Raises SymcrysError for a matrix that is not orthogonal.

symcrys.crystal_family(system: str) → str

The crystal family of a crystal system: trigonal and hexagonal form the hexagonal family.

symcrys.crystal_forms(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The crystal forms of a crystal class, as ITA 6th ed. Table 3.2.3.2 prints them: for each Wyckoff position (general position first) its basic form (two for the cubic faces (hhl) of -43m and m-3m), then its limiting forms. In the ITC convention only, like the Wyckoff positions (docs/conventions.md, “Crystal forms”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, representative has hkl (int64, shape (3,)) and cartesian (float64, shape (3,)).

symcrys.describe_operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

Each operation of the crystal class described geometrically, in the order of operations for the same key and options. Axes are named by the symmetry direction they lie along: in the ITC convention with the sign of ITA Table 2.1.3.1, in the Birss convention signed as birss-app signs them (first non-zero Cartesian component positive); the sign fixes what the sense refers to.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, axis (if present) has lattice (int64, shape (3,)) and cartesian (float64, shape (3,)).

symcrys.describe_operations_of(operations: Sequence[Mapping[str, Any]], *, tolerance: float | None = None) → list[dict[str, Any]]

Each operation of a list described geometrically, in the order of the list: kind, n, the Cartesian axis (rotation or rotoinversion axis, mirror normal) with its first non-zero component, in the order x, y, z, positive, and for n ≥ 3 the sense about that axis. The axes are not named by lattice directions, since the list need not belong to a setting; for a crystal class given by its key, describe_operations names them. Raises SymcrysError for a matrix that is not orthogonal or not a crystallographic operation (a rotation part by an angle other than 360°/n, n = 1, 2, 3, 4, 6), both within tolerance (default EPSILON, as for point_group_of).

Parameters:

tolerance (keyword-only, optional) – Two matrices are the same operation if no entry differs by this much or more, and a matrix counts as orthogonal and crystallographic within it. Default EPSILON (10⁻⁶); a caller whose matrices carry rounding errors passes a larger value, below 0.1.

Returns:

list of dict – In each, axis (if present) has cartesian (float64, shape (3,)).

symcrys.find_point_group(hm: str, convention: Literal['itc', 'birss'] | None = None) → dict[str, Any] | None

Finds a crystal class by a Hermann–Mauguin symbol in the given convention (default 'itc'): the short symbol of a setting, a full symbol, or the key (spaces are ignored). A symbol that names one setting gives that setting; the key, and a short symbol that several settings share (the monoclinic ones: 2 for unique axis b and c), give the default setting of the convention. Returns None if nothing matches, also for a value that is not a string and for the symbol of a magnetic group with time reversal. Symbols are written as in this library: - for the overbar, also in the Birss convention (m-3m, where Birss prints m3m; docs/conventions.md, “Where ITC and Birss differ”).

symcrys.generators(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

Generators of the crystal class in the requested setting (docs/conventions.md, “Generators”). ITC convention: ITA’s selected generators in printed order, without the identity and ITA’s lattice translations, so the list is empty for 1; for mm2 settings 2 and 3, which ITA does not list, those of setting 1 carried into their frame. Birss convention: birss-app’s generators (for 1 the identity, as in birss-app).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix"}; each matrix is a float64 array of shape (3, 3).

symcrys.holohedry(system: str) → str

The holohedry of a crystal system: the crystal class that is the point symmetry of a lattice of the system (ITA Table 2.1.1.1, the Laue groups in full boxes). For the trigonal system it is -3m, the symmetry of the rhombohedral lattice. The trigonal classes also occur with the hexagonal lattice, whose symmetry is 6/mmm: the holohedry of the crystal family is holohedry(crystal_family(system)), which is what the lattice basis of this library (lattice_basis, hexagonal axes for both systems) has.

symcrys.is_centrosymmetric_of(operations: Sequence[Mapping[str, Any]]) → bool

True if the group generated by operations contains the inversion, e.g. for the operations of a distorted crystal. A list that is not closed is closed first. For a crystal class, read point_group(key)["centrosymmetric"]. Raises SymcrysError for a matrix that is not orthogonal.

symcrys.is_chiral_of(operations: Sequence[Mapping[str, Any]]) → bool

True if the group generated by operations is chiral: proper rotations only. For a crystal class, read point_group(key)["chiral"]. Polar is the named property 'pyroelectric': allows_property_of(operations, 'pyroelectric'). Raises SymcrysError for a matrix that is not orthogonal.

symcrys.is_point_group_key(key: str) → bool

True if key is the key of one of the 32 crystal classes.

symcrys.lattice_operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

The operations of the crystal class in the conventional lattice basis (a, b, c; for the trigonal classes the hexagonal axes), in the order of operations for the same setting and convention: integer matrices W acting on the coordinates of a lattice direction [uvw], W = B⁻¹·R·B with the basis B of lattice_basis and the Cartesian matrix R of operations. They do not depend on the cell angles, so they exist for every family; for the monoclinic and triclinic families a, b, c are taken along x, y, z, as for the Wyckoff positions. In the ITC convention they are the matrices of ITA’s general position (6th ed., Table 3.2.3.2). Not orthogonal in general: pass them to no function that takes Cartesian operations (docs/conventions.md, “Lattice basis and orbits”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix"}; each matrix is a float64 array of shape (3, 3) holding integers (the fixed rule for matrices).

symcrys.lattice_basis(family: str) → NDArray[float64]

The conventional basis vectors a, b, c as the columns of a Cartesian matrix, with unit edge lengths. Hexagonal family (hexagonal axes): x ∥ a, z ∥ c, y = z × x, so b points at 120° from a. Orthorhombic, tetragonal, cubic: x ∥ a, y ∥ b, z ∥ c.

The edge lengths are set to 1 because the symmetry directions of these families, and so the point operations, do not depend on them. For a direction [uvw] that is not a symmetry direction, scale the columns by the real edge lengths first.

Returns:

numpy.ndarray – A float64 array of shape (3, 3), a new array on each call; a, b, c are its columns.

symcrys.lattice_from_parameters(parameters: Mapping[str, float]) → NDArray[float64]

The Cartesian basis of a cell as the columns of a 3×3 matrix, in the frame of this library for a general cell: a along x, b in the xy plane (y > 0 for γ < 180°), c towards +z. It is the frame of lattice_basis where that exists (hexagonal axes: x ∥ a, z ∥ c), so a cell with the angles of a family has that family’s basis scaled by the edge lengths. For the monoclinic family with unique axis b, b lies along y (docs/conventions.md, “Cell, metric and indices”). The basis is right-handed. Raises SymcrysError for an edge that is not positive and for angles that give no cell.

symcrys.lattice_parameters(basis: ArrayLike) → dict[str, float]

The lattice parameters of a basis given as the columns of a Cartesian matrix: the edge lengths and the angles in degrees. Independent of the orientation of the basis in the Cartesian frame (and of its handedness). Raises SymcrysError for a singular matrix.

symcrys.is_valid_cell(angles: Mapping[str, float], *, min_volume_ratio: float | None = None) → bool

Whether three angles (degrees) belong to a cell: each between 0° and 180°, and the three axes not in one plane (the volume radicand 1 − cos²α − cos²β − cos²γ + 2 cos α cos β cos γ exceeds 10⁻¹², i.e. V/(abc) > 10⁻⁶: a cell that is flat within rounding is refused). With min_volume_ratio (from 0 to 1, default 0) also refuses nearly flat cells, whose ratio V/(abc), the square root of the radicand, is smaller. Raises SymcrysError for a min_volume_ratio that is not a number from 0 to 1.

Parameters:

min_volume_ratio (keyword-only, optional) – The smallest accepted ratio V/(abc) of the cell volume to the volume of the box of its edge lengths, from 0 to 1 (1 only for orthogonal axes); default 0, which accepts every cell that is_valid_cell otherwise accepts. A ratio near 0 is a nearly flat cell.

symcrys.metric_tensor(basis: ArrayLike) → NDArray[float64]

The metric tensor G = AᵀA of a basis A (columns a, b, c): g_ij = a_i · a_j, in the unit of the edge lengths squared.

symcrys.reciprocal_basis(basis: ArrayLike) → NDArray[float64]

The reciprocal basis B = A⁻ᵀ of a basis A (columns a, b, c) as the columns a*, b*, c*, with a_i · a*_j = δ_ij (no factor 2π), in the inverse unit of the edge lengths.

symcrys.angle_between_directions(basis: ArrayLike, u: ArrayLike, v: ArrayLike) → float

The angle in degrees between two lattice directions [uvw] (coordinates in the basis, columns a, b, c), 0° to 180°. Raises SymcrysError for a zero vector.

symcrys.angle_between_planes(basis: ArrayLike, h: ArrayLike, k: ArrayLike) → float

The angle in degrees between the normals of two planes (hkl), 0° to 180°: the angle between the reciprocal vectors h·a* + k·b* + l·c*. For two faces this is 180° minus the interior dihedral angle. Raises SymcrysError for a zero vector.

symcrys.residual_operations(operations: Sequence[Mapping[str, Any]], basis: ArrayLike, *, tolerance: float | None = None) → list[Operation]

The operations of a list that keep the metric of a cell: W with WᵀGW = G, G the metric tensor of basis. The operations are integer matrices on lattice coordinates, as lattice_operations gives them; the list is taken as it is and the kept operations are the ones of the list, in its order. The deviation counts relative to the largest entry of G (tolerance, default EPSILON). An operation combined with time reversal belongs to the magnetic API.

Parameters:

tolerance (keyword-only, optional) – The largest accepted deviation of WᵀGW from G, relative to the largest entry of G; default EPSILON.

symcrys.reduce_indices(indices: ArrayLike) → NDArray[int64]

The indices divided by their greatest common divisor, signs kept. Raises SymcrysError for non-integers and for all zeros.

symcrys.plane_to_four_indices(hkl: ArrayLike) → NDArray[int64]

The plane (hkl) of hexagonal axes as (hkil) with i = −(h + k).

symcrys.plane_from_four_indices(hkil: ArrayLike) → NDArray[int64]

The plane (hkil) as (hkl); raises SymcrysError unless i = −(h + k).

symcrys.direction_to_four_indices(uvw: ArrayLike) → NDArray[int64]

The direction [uvw] of hexagonal axes as [UVTW], reduced: U = (2u − v)/3, V = (2v − u)/3, T = −(U + V), W = w, scaled to the smallest integers.

symcrys.direction_from_four_indices(uvtw: ArrayLike) → NDArray[int64]

The direction [UVTW] as [uvw], reduced: u = U − T, v = V − T, w = W; raises SymcrysError unless T = −(U + V).

symcrys.zone_axis(h1: ArrayLike, h2: ArrayLike) → NDArray[int64] | None

The zone axis [uvw] of two planes (hkl), which must not be zero vectors: the solution of the zone law hu + kv + lw = 0, the cross product h₁ × h₂ reduced (so its sign follows the order of the planes), or null for parallel planes.

symcrys.change_of_axes(p: ArrayLike) → dict[str, NDArray[float64]]

The transformation of indices for a change of basis (a′, b′, c′) = (a, b, c)·P (ITA Vol. A, 2006, Section 5.1.3): the columns of P are the new basis vectors in the old one. The coordinates of a direction transform with Q = P⁻¹, the indices of a plane with Pᵀ, so that hu + kv + lw is the same in both bases. Raises SymcrysError unless det P > 0 (a right-handed basis), and for a P that is singular within rounding (the absolute value of det P at most 10⁻⁹ times the product of its column lengths).

symcrys.operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

All operations of the crystal class in the requested setting (default: the convention’s default setting). ITC convention: in ITA’s order, identity first, then as ITA numbers the general position. Birss convention: in birss-app’s order (docs/conventions.md, “Order of the operations”). The matrices are Cartesian (docs/conventions.md, “Cartesian frame”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix"}; each matrix is a float64 array of shape (3, 3).

symcrys.orbit(key: str, indices: Mapping[str, ArrayLike], *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The orbit of a face (hkl) or of a lattice direction [uvw] under a crystal class, exactly, in the lattice basis: the distinct faces (directions), in the order in which the operations reach them (so in the ITC convention the given face first), each with the indices of the operations that map the given one onto it. A face transforms with the inverse transpose of a lattice operation, h’ = W⁻ᵀ·h, a direction with the operation itself, u’ = W·u. The number of entries is the multiplicity of the face (direction). Raises SymcrysError unless exactly one of hkl and uvw is given, as three integers not all zero (hexagonal axes: three indices, without i).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, hkl (or uvw) is an int64 array of shape (3,) and operations an int64 array of shape (n,); indices is a dict {"hkl": ...} or {"uvw": ...}.

symcrys.orbit_of(operations: Sequence[Mapping[str, Any]], direction: ArrayLike, *, tolerance: float | None = None) → list[dict[str, Any]]

The orbit of a direction (any non-zero vector, Cartesian, e.g. a face normal) under a list of operations, for instance those of a distorted crystal: the images of its unit vector under each operation, coinciding images merged (closer than tolerance, default EPSILON, as for site_symmetry), in the order in which the operations reach them, each with the indices of the operations that map the direction there. The list is taken as it is, not closed into a group. Raises SymcrysError for a zero vector and for a matrix that is not orthogonal (within tolerance, at least EPSILON).

Parameters:

tolerance (keyword-only, optional) – Two images count as one pole if their unit vectors are closer than this (Euclidean distance). Default 10⁻⁶; a caller whose directions carry rounding errors passes a larger value.

Returns:

list of dict – In each, direction is a float64 array of shape (3,) and operations an int64 array of shape (n,).

symcrys.point_group(key: str) → dict[str, Any]

The crystal class with this key. Raises SymcrysError for an unknown key.

symcrys.point_group_of(operations: Sequence[Mapping[str, Any]], *, tolerance: float | None = None) → dict[str, Any] | None

The crystal class generated by a list of Cartesian operations, for instance those left after distorting a crystal: its key, and the setting whose operations it equals in the frame of symcrys (absent if the group is the class in another orientation, e.g. a threefold axis along [111]). The list is closed into a group first, two matrices being equal when no entry differs by tolerance (default EPSILON) or more. Returns None if the operations generate no crystal class (an operation of order 5, a group larger than 48). Raises SymcrysError for a matrix that is not orthogonal (within tolerance, at least EPSILON). The classes 1 and -1 have no orientation, so they always have setting 1. The first call builds a table of the groups (about 0.1 s; docs/conventions.md, “Point group of a list of operations”).

Parameters:

tolerance (keyword-only, optional) – Two matrices are the same operation if no entry differs by this much or more, and a matrix counts as orthogonal and crystallographic within it. Default EPSILON (10⁻⁶); a caller whose matrices carry rounding errors passes a larger value, below 0.1.

symcrys.point_groups() → list[dict[str, Any]]

All 32 crystal classes, in the order of POINT_GROUP_KEYS (by crystal system, as in ITA).

symcrys.rotate_tensor(tensor: ArrayLike, rotation: ArrayLike, spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic']) → NDArray[float64]

The components of tensor (length 3^rank, flat index) in a frame rotated by the orthogonal matrix rotation: t′_{i…} = f·Σ R_{ia}…R_{…}·t_{a…}, with f = det(R) for an axial tensor and 1 for a polar one. To express a tensor in the frame of a surface, pass the matrix whose rows are the new axes in the old frame. The kind of tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES.

Returns:

numpy.ndarray – A float64 array of shape (3**rank,); tensor may have any shape with 3**rank entries (it is flattened in C order).

symcrys.settings(key: str, convention: Literal['itc', 'birss'] | None = None) → list[dict[str, Any]]

The settings of a crystal class, with symbols and the default of the given convention (default 'itc').

symcrys.site_symmetry(operations: Sequence[Mapping[str, Any]], direction: ArrayLike, *, tolerance: float | None = None) → SiteSymmetry

The site symmetry of direction (any non-zero vector, Cartesian) under operations, which may be any list of point operations (for instance those of a distorted crystal). The operations fixing the direction within the tolerance are closed under the products found in the list and the direction is set onto their fixed space, repeated until stable, so that for a group the result is a subgroup and the set direction lies exactly on its elements. For a list that is not a group, multiplicity may not be an integer. The matrices must be Cartesian and orthogonal (not those of lattice_operations). Raises SymcrysError for a matrix that is not orthogonal (within tolerance, at least EPSILON), for a zero vector, and if the closed operations fix no common direction (a tolerance far too large, e.g. 0.5).

Parameters:

tolerance (keyword-only, optional) – A direction counts as fixed by an operation if the operation moves its unit vector by less than this (Euclidean distance). Default 10⁻⁶; a caller whose directions carry rounding errors (e.g. read from a rounded link) passes a larger value.

Returns:

dict – operations int64 array of shape (n,), direction float64 array of shape (3,), multiplicity, general.

symcrys.symbol(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None, form: Literal['short', 'full', 'schoenflies'] | None = None) → str

A symbol of the crystal class in the requested convention and setting.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

  • form (keyword-only, optional) – 'short' (default): short symbol of the setting, e.g. 321 (ITC) for class 32. 'full': full symbol, positions separated by spaces, e.g. -3 2/m 1. 'schoenflies': Schoenflies symbol, subscripts written inline (C3v, D2d, Oh).

symcrys.symmetry_directions(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The positions of the full Hermann–Mauguin symbol in the requested convention and setting, each with its symmetry directions (ITA Table 2.1.3.1) and the symmetry elements along them. All positions of the crystal family are listed, also those the symbol of the class leaves out (then without symbol); the triclinic family has none. The directions keep the sign of Table 2.1.3.1 in both conventions; in the Birss convention an axis of describe_operations may be reversed, so match it to a direction whose dot product with it is ±1, not by identity.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Each entry of directions has lattice (int64, shape (3,)) and cartesian (float64, shape (3,)).

symcrys.tensor_form(key: str, spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic'], *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → TensorForm

The form of a tensor under a crystal class in the requested setting (default: the default setting of the convention, 'itc' unless given). The tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES ('piezoelectric'). The convention matters only through the setting: the same setting index gives the same form in both conventions (docs/conventions.md, “Tensors”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

dict – basis float64 array of shape (p, 3**rank), parameters int64 array of shape (p, rank), relations float64 array of shape (3**rank - p, 3**rank), rank; p is the number of free parameters. A row of basis reshaped to (3,) * rank is a tensor.

symcrys.tensor_form_of(operations: Sequence[Mapping[str, Any]], spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic']) → TensorForm

The form of a tensor under the group generated by operations, e.g. the site symmetry of a surface normal (site_symmetry) or the operations of a distorted crystal. The tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES. The operations are Cartesian and orthogonal; a list that is not closed is closed first. Raises SymcrysError for a matrix that is not orthogonal.

Returns:

dict – basis float64 array of shape (p, 3**rank), parameters int64 array of shape (p, rank), relations float64 array of shape (3**rank - p, 3**rank), rank; p is the number of free parameters.

symcrys.wyckoff_position_of(key: str, direction: ArrayLike, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None, tolerance: float | None = None) → dict[str, Any]

The Wyckoff position of a direction (Cartesian) in a crystal class: the position whose site symmetry is conjugate to that of the direction (ITA’s definition). tolerance as for site_symmetry.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

  • tolerance (keyword-only, optional) – A direction counts as fixed by an operation if the operation moves its unit vector by less than this (Euclidean distance). Default 10⁻⁶; a caller whose directions carry rounding errors (e.g. read from a rounded link) passes a larger value.

Returns:

dict – representative has hkl (int64, shape (3,)) and cartesian (float64, shape (3,)), site_symmetry_operations is an int64 array of shape (n,).

symcrys.wyckoff_positions(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The Wyckoff positions of a crystal class for directions, as ITA tabulates them (general position first), in the ITC convention only (docs/conventions.md, “Site symmetry and Wyckoff positions”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, representative has hkl (int64, shape (3,)) and cartesian (float64, shape (3,)), site_symmetry_operations is an int64 array of shape (n,).

symcrys.magnetic: magnetic point groups

symcrys.magnetic: the magnetic API, for the 122 magnetic point groups, with time reversal.

The functions have the names they have in symcrys, the crystallographic API; the module decides which reading a key has. Here a key of type 'I' ("32") is a white (colourless) group: the symmetry of a magnetically ordered crystal in which time reversal does not occur at all. A crystal without magnetic order has the grey group of its class (quartz: "321'"), which allows no time-odd property. Operations carry time_reversal, a tensor specification time_parity (docs/conventions.md, “Two entry points”).

symcrys.magnetic.LATTICE_SYMMETRY_DIRECTIONS: dict[str, list[NDArray[int64]]]

The directions of each position of the full symbol, per family, as printed in ITA Table 2.1.3.1 (hexagonal family: the row “Hexagonal”, which also serves the trigonal classes with hexagonal axes). Monoclinic: the full symbol reads along a, b, c (ITA 6th ed. § 2.1.3.15, p. 171), the orthorhombic row. Triclinic: no symmetry direction.

In Python: family → one int64 array of shape (n, 3) per position, the n directions [uvw] as rows.

symcrys.magnetic.POINT_GROUP_KEYS: tuple[str, ...]

Keys of the 122 magnetic point groups: the 32 crystal classes (white groups), the 32 grey groups and the 58 black-and-white groups, in this order (docs/conventions.md, “Keys”).

symcrys.magnetic.TENSOR_PROPERTIES: dict[str, dict[str, Any]]

The named tensor properties. For each name, the tensor that describes the property, what it is, and its print source. 'gyrotropic' is optical activity.

symcrys.magnetic.VERSION: str

The version of symcrys, the same for the TypeScript and the Python package.

class symcrys.magnetic.TensorSpec

The kind of tensor (keys also accepted in camelCase, e.g. timeParity).

symcrys.magnetic.allowed_properties(key: str) → list[str]

The named properties the point group allows, in the order of TENSOR_PROPERTIES.

symcrys.magnetic.allowed_properties_of(operations: Sequence[Mapping[str, Any]]) → list[str]

The named properties the group generated by operations allows. Checks the operations as allows_property_of.

symcrys.magnetic.allows_property(key: str, name: Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic', 'ferromagnetic', 'magnetoelectric', 'piezomagnetic']) → bool

True if the point group allows the named property, e.g. allows_property('-6m2', 'piezoelectric'). It does not depend on setting or convention. Raises SymcrysError for an unknown key or name.

symcrys.magnetic.allows_property_of(operations: Sequence[Mapping[str, Any]], name: Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic', 'ferromagnetic', 'magnetoelectric', 'piezomagnetic']) → bool

True if the group generated by operations allows the named property, e.g. for the site symmetry of a surface normal or the operations of a distorted crystal. The matrices must be Cartesian and orthogonal; a list that is not closed is closed first. Raises SymcrysError for a matrix that is not orthogonal and for an operation that does not say whether it is combined with time reversal.

symcrys.magnetic.crystal_family(system: str) → str

The crystal family of a crystal system: trigonal and hexagonal form the hexagonal family.

symcrys.magnetic.describe_operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

Each operation of the point group described geometrically, in the order of operations for the same key and options. Axes are named by the symmetry direction they lie along: in the ITC convention with the sign of ITA Table 2.1.3.1, in the Birss convention signed as birss-app signs them (first non-zero Cartesian component positive); the sign fixes what the sense refers to.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, axis (if present) has lattice (int64, shape (3,)) and cartesian (float64, shape (3,)).

symcrys.magnetic.describe_operations_of(operations: Sequence[Mapping[str, Any]], *, tolerance: float | None = None) → list[dict[str, Any]]

Each operation of a list described geometrically, in the order of the list: kind, n, the Cartesian axis (rotation or rotoinversion axis, mirror normal) with its first non-zero component, in the order x, y, z, positive, and for n ≥ 3 the sense about that axis. The axes are not named by lattice directions, since the list need not belong to a setting; for a point group given by its key, describe_operations names them. Raises SymcrysError for a matrix that is not orthogonal or not a crystallographic operation (a rotation part by an angle other than 360°/n, n = 1, 2, 3, 4, 6), both within tolerance (default EPSILON, as for point_group_of), and for an operation that does not say whether it is combined with time reversal.

Parameters:

tolerance (keyword-only, optional) – Two matrices are the same operation if no entry differs by this much or more, and a matrix counts as orthogonal and crystallographic within it. Default EPSILON (10⁻⁶); a caller whose matrices carry rounding errors passes a larger value, below 0.1.

Returns:

list of dict – In each, axis (if present) has cartesian (float64, shape (3,)).

symcrys.magnetic.find_point_group(hm: str, convention: Literal['itc', 'birss'] | None = None) → dict[str, Any] | None

Finds one of the 122 magnetic point groups (the 32 crystal classes included) by a symbol in the given convention (default 'itc'): the short symbol of a setting, a full symbol, or the key (spaces are ignored). A prime ' marks time reversal: 4'/mmm', 2221'. A symbol that names one setting gives that setting; the key, and a short symbol that several settings share (the monoclinic ones: 2' for unique axis b and c), give the default setting of the convention. In the Birss convention two keys are the Birss symbol of a setting that is not the default (mm'm' and 6'/mmm', setting 2; Birss prints m'm'm and 6'/mm'm for these groups) and give that setting, like any symbol. Returns None if nothing matches, also for a value that is not a string. Symbols are written as in this library: - for the overbar, also in the Birss convention (m'-3'm, where Birss prints m'3m; docs/conventions.md, “Where ITC and Birss differ”).

symcrys.magnetic.generators(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

Generators of the point group in the requested setting (docs/conventions.md, “Generators”). ITC convention: ITA’s selected generators in printed order, without the identity and ITA’s lattice translations, so the list is empty for 1; for mm2 settings 2 and 3, which ITA does not list, those of setting 1 carried into their frame; for a magnetic group, those of its class with the time reversal they have in the group, for a grey group followed by 1'. Birss convention: birss-app’s generators (for 1 the identity, as in birss-app).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix", "time_reversal"}; each matrix is a float64 array of shape (3, 3).

symcrys.magnetic.holohedry(system: str) → str

The holohedry of a crystal system: the crystal class that is the point symmetry of a lattice of the system (ITA Table 2.1.1.1, the Laue groups in full boxes). For the trigonal system it is -3m, the symmetry of the rhombohedral lattice. The trigonal classes also occur with the hexagonal lattice, whose symmetry is 6/mmm: the holohedry of the crystal family is holohedry(crystal_family(system)), which is what the lattice basis of this library (lattice_basis, hexagonal axes for both systems) has.

symcrys.magnetic.is_centrosymmetric_of(operations: Sequence[Mapping[str, Any]]) → bool

True if the group generated by operations contains the inversion, not combined with time reversal: e.g. for the operations of a distorted crystal. A list that is not closed is closed first. For a point group given by its key, read point_group(key)["centrosymmetric"]. Raises SymcrysError for a matrix that is not orthogonal and for an operation that does not say whether it is combined with time reversal.

symcrys.magnetic.is_chiral_of(operations: Sequence[Mapping[str, Any]]) → bool

True if the group generated by operations is chiral: proper rotations only, with or without time reversal (products of proper rotations are proper, so the list need not be closed). For a point group given by its key, read point_group(key)["chiral"]. Raises SymcrysError for a matrix that is not orthogonal and for an operation that does not say whether it is combined with time reversal.

symcrys.magnetic.is_point_group_key(key: str) → bool

True if key is the key of one of the 122 magnetic point groups (the 32 crystal classes included).

symcrys.magnetic.lattice_operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

The operations of a point group in the conventional lattice basis (a, b, c; for the trigonal classes the hexagonal axes), in the order and with the time reversal of operations for the same setting and convention: integer matrices W acting on the coordinates of a lattice vector [uvw], W = B⁻¹·R·B with the basis B of lattice_basis and the Cartesian matrix R. They do not depend on the cell angles, so they exist for every family; for the monoclinic and triclinic families a, b, c are taken along x, y, z, as for the Wyckoff positions. In the ITC convention they are the matrices of ITA’s general position (6th ed., Table 3.2.3.2). Not orthogonal in general: pass them to no function that takes Cartesian operations (docs/conventions.md, “Lattice basis and orbits”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix", "time_reversal"}; each matrix is a float64 array of shape (3, 3) holding integers (the fixed rule for matrices).

symcrys.magnetic.lattice_basis(family: str) → NDArray[float64]

The conventional basis vectors a, b, c as the columns of a Cartesian matrix, with unit edge lengths. Hexagonal family (hexagonal axes): x ∥ a, z ∥ c, y = z × x, so b points at 120° from a. Orthorhombic, tetragonal, cubic: x ∥ a, y ∥ b, z ∥ c.

The edge lengths are set to 1 because the symmetry directions of these families, and so the point operations, do not depend on them. For a direction [uvw] that is not a symmetry direction, scale the columns by the real edge lengths first.

Returns:

numpy.ndarray – A float64 array of shape (3, 3), a new array on each call; a, b, c are its columns.

symcrys.magnetic.lattice_from_parameters(parameters: Mapping[str, float]) → NDArray[float64]

The Cartesian basis of a cell as the columns of a 3×3 matrix, in the frame of this library for a general cell: a along x, b in the xy plane (y > 0 for γ < 180°), c towards +z. It is the frame of lattice_basis where that exists (hexagonal axes: x ∥ a, z ∥ c), so a cell with the angles of a family has that family’s basis scaled by the edge lengths. For the monoclinic family with unique axis b, b lies along y (docs/conventions.md, “Cell, metric and indices”). The basis is right-handed. Raises SymcrysError for an edge that is not positive and for angles that give no cell.

symcrys.magnetic.lattice_parameters(basis: ArrayLike) → dict[str, float]

The lattice parameters of a basis given as the columns of a Cartesian matrix: the edge lengths and the angles in degrees. Independent of the orientation of the basis in the Cartesian frame (and of its handedness). Raises SymcrysError for a singular matrix.

symcrys.magnetic.is_valid_cell(angles: Mapping[str, float], *, min_volume_ratio: float | None = None) → bool

Whether three angles (degrees) belong to a cell: each between 0° and 180°, and the three axes not in one plane (the volume radicand 1 − cos²α − cos²β − cos²γ + 2 cos α cos β cos γ exceeds 10⁻¹², i.e. V/(abc) > 10⁻⁶: a cell that is flat within rounding is refused). With min_volume_ratio (from 0 to 1, default 0) also refuses nearly flat cells, whose ratio V/(abc), the square root of the radicand, is smaller. Raises SymcrysError for a min_volume_ratio that is not a number from 0 to 1.

Parameters:

min_volume_ratio (keyword-only, optional) – The smallest accepted ratio V/(abc) of the cell volume to the volume of the box of its edge lengths, from 0 to 1 (1 only for orthogonal axes); default 0, which accepts every cell that is_valid_cell otherwise accepts. A ratio near 0 is a nearly flat cell.

symcrys.magnetic.metric_tensor(basis: ArrayLike) → NDArray[float64]

The metric tensor G = AᵀA of a basis A (columns a, b, c): g_ij = a_i · a_j, in the unit of the edge lengths squared.

symcrys.magnetic.reciprocal_basis(basis: ArrayLike) → NDArray[float64]

The reciprocal basis B = A⁻ᵀ of a basis A (columns a, b, c) as the columns a*, b*, c*, with a_i · a*_j = δ_ij (no factor 2π), in the inverse unit of the edge lengths.

symcrys.magnetic.angle_between_directions(basis: ArrayLike, u: ArrayLike, v: ArrayLike) → float

The angle in degrees between two lattice directions [uvw] (coordinates in the basis, columns a, b, c), 0° to 180°. Raises SymcrysError for a zero vector.

symcrys.magnetic.angle_between_planes(basis: ArrayLike, h: ArrayLike, k: ArrayLike) → float

The angle in degrees between the normals of two planes (hkl), 0° to 180°: the angle between the reciprocal vectors h·a* + k·b* + l·c*. For two faces this is 180° minus the interior dihedral angle. Raises SymcrysError for a zero vector.

symcrys.magnetic.residual_operations(operations: Sequence[Mapping[str, Any]], basis: ArrayLike, *, tolerance: float | None = None) → list[Operation]

The operations of a list that keep the metric of a cell: W with WᵀGW = G, G the metric tensor of basis. The operations are integer matrices on lattice coordinates, as lattice_operations gives them; the list is taken as it is and the kept operations are the ones of the list, in its order. The deviation counts relative to the largest entry of G (tolerance, default EPSILON). Every operation must say whether it is combined with time reversal (time_reversal), which is kept; one that does not (an operation of the crystallographic API) raises SymcrysError.

Parameters:

tolerance (keyword-only, optional) – The largest accepted deviation of WᵀGW from G, relative to the largest entry of G; default EPSILON.

symcrys.magnetic.reduce_indices(indices: ArrayLike) → NDArray[int64]

The indices divided by their greatest common divisor, signs kept. Raises SymcrysError for non-integers and for all zeros.

symcrys.magnetic.plane_to_four_indices(hkl: ArrayLike) → NDArray[int64]

The plane (hkl) of hexagonal axes as (hkil) with i = −(h + k).

symcrys.magnetic.plane_from_four_indices(hkil: ArrayLike) → NDArray[int64]

The plane (hkil) as (hkl); raises SymcrysError unless i = −(h + k).

symcrys.magnetic.direction_to_four_indices(uvw: ArrayLike) → NDArray[int64]

The direction [uvw] of hexagonal axes as [UVTW], reduced: U = (2u − v)/3, V = (2v − u)/3, T = −(U + V), W = w, scaled to the smallest integers.

symcrys.magnetic.direction_from_four_indices(uvtw: ArrayLike) → NDArray[int64]

The direction [UVTW] as [uvw], reduced: u = U − T, v = V − T, w = W; raises SymcrysError unless T = −(U + V).

symcrys.magnetic.zone_axis(h1: ArrayLike, h2: ArrayLike) → NDArray[int64] | None

The zone axis [uvw] of two planes (hkl), which must not be zero vectors: the solution of the zone law hu + kv + lw = 0, the cross product h₁ × h₂ reduced (so its sign follows the order of the planes), or null for parallel planes.

symcrys.magnetic.change_of_axes(p: ArrayLike) → dict[str, NDArray[float64]]

The transformation of indices for a change of basis (a′, b′, c′) = (a, b, c)·P (ITA Vol. A, 2006, Section 5.1.3): the columns of P are the new basis vectors in the old one. The coordinates of a direction transform with Q = P⁻¹, the indices of a plane with Pᵀ, so that hu + kv + lw is the same in both bases. Raises SymcrysError unless det P > 0 (a right-handed basis), and for a P that is singular within rounding (the absolute value of det P at most 10⁻⁹ times the product of its column lengths).

symcrys.magnetic.operations(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[Operation]

All operations of the point group in the requested setting (default: the convention’s default setting). ITC convention: in ITA’s order, identity first, then as ITA numbers the general position of the crystal class; an operation of a magnetic group has the number it has in the class, and a grey group lists the class first, then the same sequence with time reversal. Birss convention: in birss-app’s order (docs/conventions.md, “Order of the operations”). The matrices are Cartesian (docs/conventions.md, “Cartesian frame”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Dicts {"matrix", "time_reversal"}; each matrix is a float64 array of shape (3, 3).

symcrys.magnetic.orbit(key: str, indices: Mapping[str, ArrayLike], *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The orbit of a face (hkl) or of a lattice direction [uvw] under a point group, exactly, in the lattice basis: the distinct faces (directions), in the order in which the operations reach them (so in the ITC convention the given face first), each with the indices of the operations that map the given one onto it. A face transforms with the inverse transpose of a lattice operation, h’ = W⁻ᵀ·h, a direction with the operation itself, u’ = W·u. The number of entries is the multiplicity of the face (direction), and the operations of the first entry, if it is the given one, are its site symmetry. Time reversal plays no part. Raises SymcrysError unless exactly one of hkl and uvw is given, as three integers not all zero (hexagonal axes: three indices, without i).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – In each, hkl (or uvw) is an int64 array of shape (3,) and operations an int64 array of shape (n,); indices is a dict {"hkl": ...} or {"uvw": ...}.

symcrys.magnetic.orbit_of(operations: Sequence[Mapping[str, Any]], direction: ArrayLike, *, tolerance: float | None = None) → list[dict[str, Any]]

The orbit of a direction (any non-zero vector, Cartesian, e.g. a face normal) under a list of operations, for instance those of a distorted crystal: the images of its unit vector under each operation, coinciding images merged (closer than tolerance, default EPSILON, as for site_symmetry), in the order in which the operations reach them, each with the indices of the operations that map the direction there. The list is taken as it is, not closed into a group. Time reversal is ignored. Raises SymcrysError for a zero vector and for a matrix that is not orthogonal (Cartesian, not one of lattice_operations; within tolerance, at least EPSILON).

Parameters:

tolerance (keyword-only, optional) – Two images count as one pole if their unit vectors are closer than this (Euclidean distance). Default 10⁻⁶; a caller whose directions carry rounding errors passes a larger value.

Returns:

list of dict – In each, direction is a float64 array of shape (3,) and operations an int64 array of shape (n,).

symcrys.magnetic.point_group(key: str) → dict[str, Any]

The point group with this key: a crystal class or a magnetic point group. Raises SymcrysError for an unknown key.

symcrys.magnetic.point_group_of(operations: Sequence[Mapping[str, Any]], *, tolerance: float | None = None) → dict[str, Any] | None

The point group generated by a list of Cartesian operations, for instance those left after distorting a crystal: its key, and the setting whose operations it equals in the frame of symcrys (absent if the group is the point group in another orientation). The list is closed into a group first, two matrices being equal when no entry differs by tolerance (default EPSILON) or more. Time reversal counts: a list with time reversal gives a magnetic point group. Returns None if the operations generate no point group (an operation of order 5, a group larger than 96). Raises SymcrysError for a matrix that is not orthogonal (within tolerance, at least EPSILON) and for an operation that does not say whether it is combined with time reversal. The classes 1 and -1 have one setting and no orientation, so they always have setting 1.

Parameters:

tolerance (keyword-only, optional) – Two matrices are the same operation if no entry differs by this much or more, and a matrix counts as orthogonal and crystallographic within it. Default EPSILON (10⁻⁶); a caller whose matrices carry rounding errors passes a larger value, below 0.1.

symcrys.magnetic.point_groups() → list[dict[str, Any]]

All 122 magnetic point groups, in the order of POINT_GROUP_KEYS of the magnetic API: the 32 crystal classes (type I), the 32 grey groups (type II) in the same order, and the 58 black-and-white groups (type III) in the order of ITC Vol. D Table 1.5.2.3.

symcrys.magnetic.rotate_tensor(tensor: ArrayLike, rotation: ArrayLike, spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic', 'ferromagnetic', 'magnetoelectric', 'piezomagnetic']) → NDArray[float64]

The components of tensor (length 3^rank, flat index) in a frame rotated by the orthogonal matrix rotation: t′_{i…} = f·Σ R_{ia}…R_{…}·t_{a…}, with f = det(R) for an axial tensor and 1 for a polar one. To express a tensor in the frame of a surface, pass the matrix whose rows are the new axes in the old frame. Time parity plays no part. The kind of tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES.

Returns:

numpy.ndarray – A float64 array of shape (3**rank,); tensor may have any shape with 3**rank entries (it is flattened in C order).

symcrys.magnetic.settings(key: str, convention: Literal['itc', 'birss'] | None = None) → list[dict[str, Any]]

The settings of a point group, with symbols and the default of the given convention (default 'itc').

symcrys.magnetic.site_symmetry(operations: Sequence[Mapping[str, Any]], direction: ArrayLike, *, tolerance: float | None = None) → SiteSymmetry

The site symmetry of direction (any non-zero vector, Cartesian) under operations, which may be any list of point operations (for instance those of a distorted crystal). Time reversal is ignored: a direction or a face normal is not changed by it. The operations fixing the direction within the tolerance are closed under the products found in the list and the direction is set onto their fixed space, repeated until stable, so that for a group the result is a subgroup and the set direction lies exactly on its elements. For a list that is not a group, multiplicity may not be an integer. The matrices must be Cartesian and orthogonal (not those of lattice_operations). Raises SymcrysError for a matrix that is not orthogonal (within tolerance, at least EPSILON), for a zero vector, and if the closed operations fix no common direction (a tolerance far too large, e.g. 0.5).

Parameters:

tolerance (keyword-only, optional) – A direction counts as fixed by an operation if the operation moves its unit vector by less than this (Euclidean distance). Default 10⁻⁶; a caller whose directions carry rounding errors (e.g. read from a rounded link) passes a larger value.

Returns:

dict – operations int64 array of shape (n,), direction float64 array of shape (3,), multiplicity, general.

symcrys.magnetic.symbol(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None, form: Literal['short', 'full', 'schoenflies'] | None = None) → str

A symbol of the point group in the requested convention and setting.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

  • form (keyword-only, optional) – 'short' (default): short symbol of the setting, e.g. 321 (ITC) for class 32. 'full': full symbol, positions separated by spaces, e.g. -3 2/m 1. 'schoenflies': Schoenflies symbol, subscripts written inline (C3v, D2d, Oh).

symcrys.magnetic.symmetry_directions(key: str, *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → list[dict[str, Any]]

The positions of the full Hermann–Mauguin symbol in the requested convention and setting, each with its symmetry directions (ITA Table 2.1.3.1) and the symmetry elements along them. All positions of the crystal family are listed, also those the symbol of the class leaves out (then without symbol); the triclinic family has none. The directions keep the sign of Table 2.1.3.1 in both conventions; in the Birss convention an axis of describe_operations may be reversed, so match it to a direction whose dot product with it is ±1, not by identity.

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

list of dict – Each entry of directions has lattice (int64, shape (3,)) and cartesian (float64, shape (3,)).

symcrys.magnetic.tensor_form(key: str, spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic', 'ferromagnetic', 'magnetoelectric', 'piezomagnetic'], *, convention: Literal['itc', 'birss'] | None = None, setting: int | None = None) → TensorForm

The form of a tensor under a point group, a crystal class or a magnetic point group, in the requested setting (default: the default setting of the convention, 'itc' unless given). The tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES ('piezoelectric'). The convention matters only through the setting: the same setting index gives the same form in both conventions (docs/conventions.md, “Tensors”).

Parameters:
  • convention (keyword-only, optional) – Default 'itc'.

  • setting (keyword-only, optional) – 1-based setting index; default: the default setting of the convention.

Returns:

dict – basis float64 array of shape (p, 3**rank), parameters int64 array of shape (p, rank), relations float64 array of shape (3**rank - p, 3**rank), rank; p is the number of free parameters. A row of basis reshaped to (3,) * rank is a tensor.

symcrys.magnetic.tensor_form_of(operations: Sequence[Mapping[str, Any]], spec: TensorSpec | Mapping[str, Any] | Literal['pyroelectric', 'ferroaxial', 'piezoelectric', 'gyrotropic', 'ferromagnetic', 'magnetoelectric', 'piezomagnetic']) → TensorForm

The form of a tensor under the group generated by operations, e.g. the site symmetry of a surface normal (site_symmetry) or the operations of a distorted crystal. The tensor is given by its specification or by the name of a property in TENSOR_PROPERTIES. The operations are Cartesian and orthogonal, and each says whether it is combined with time reversal (time_reversal, True or False); a list that is not closed is closed first. Raises SymcrysError for a matrix that is not orthogonal and for an operation that does not say whether it is combined with time reversal.

Returns:

dict – basis float64 array of shape (p, 3**rank), parameters int64 array of shape (p, rank), relations float64 array of shape (3**rank - p, 3**rank), rank; p is the number of free parameters.

symcrys.magnetic.SymcrysError and symcrys.magnetic.TensorForm are those of symcrys above.

symcrys.plane: plane groups and plane point groups

symcrys.plane: the plane API, for the 17 plane groups and the 10 plane point groups.

Coordinates and operations are in the lattice basis (a, b), as ITA (6th ed., 2016) prints them in Chapter 2.2. Keys are the symbols ITA prints: "p2mg", "c2mm" for the plane groups, "2mm", "3m" for the plane point groups. A matrix is a float64 array of shape (2, 2) with integer entries, a translation, a point and a vertex float64 arrays of shape (2,); a direction of a line is an int64 array of shape (2,) (docs/conventions.md, “Plane groups”).

symcrys.plane.PLANE_GROUP_KEYS: tuple[str, ...]

The short symbols of the 17 plane groups, in ITA’s order (plane group n at index n − 1).

symcrys.plane.POINT_GROUP_KEYS: tuple[str, ...]

The keys of the 10 plane point groups, in the order of ITA Table 3.2.1.1.

symcrys.plane.VERSION: str

The version of symcrys, the same for the TypeScript and the Python package.

class symcrys.plane.Operation
symcrys.plane.asymmetric_unit(key: str) → dict[str, Any]

The asymmetric unit of a plane group as ITA prints it: a convex polygon given by its vertices and, per edge, the printed inequality that holds it. Raises SymcrysError for an unknown key.

Returns:

dict – vertices a float64 array of shape (n, 2), inequalities an int64 array of shape (n, 3).

symcrys.plane.describe_operations(key: str, *, setting: int | None = None) → list[dict[str, Any]]

Each operation of operations (same key and setting) described geometrically, index for index: what it is, its order and sense, where its symmetry element lies, its glide part. Raises SymcrysError for an unknown key or setting.

Parameters:

setting (keyword-only, optional) – 1-based setting: for the point group 3m 1 is 3m1 (default) and 2 is 31m; the other point groups have one, and a plane group takes only 1.

Returns:

list of dict – translation, location and glide (where present) are float64 arrays of shape (2,), direction an int64 array of shape (2,).

symcrys.plane.generators(key: str, *, setting: int | None = None) → list[Operation]

ITA’s selected generators, in printed order, without the identity and the integer translations: for a centred plane group the centring translation first. A point group: the linear parts of the generators of its symmorphic plane group. Raises SymcrysError for an unknown key or setting.

Parameters:

setting (keyword-only, optional) – 1-based setting: for the point group 3m 1 is 3m1 (default) and 2 is 31m; the other point groups have one, and a plane group takes only 1.

Returns:

list of dict – Dicts {"matrix", "translation"}: float64 arrays of shape (2, 2) and (2,).

symcrys.plane.operations(key: str, *, setting: int | None = None) → list[Operation]

The operations of a plane group or a plane point group, in ITA’s order, identity first. A plane group: one per coset of the integer translations, translations in [0, 1), the general position as numbered, then for a centred group the same sequence with the centring added (the “(1/2,1/2)+ set”). A point group: the linear parts of its symmorphic plane group (pm for m, p3m1 and p31m for the settings of 3m), translation zero. Raises SymcrysError for an unknown key or setting.

Parameters:

setting (keyword-only, optional) – 1-based setting: for the point group 3m 1 is 3m1 (default) and 2 is 31m; the other point groups have one, and a plane group takes only 1.

Returns:

list of dict – Dicts {"matrix", "translation"}: float64 arrays of shape (2, 2) and (2,).

symcrys.plane.orbit(key: str, point: ArrayLike, *, tolerance: float | None = None) → NDArray[float64]

The orbit of a point (lattice basis) under a plane group: its distinct images in the conventional cell, each in [0, 1), in the order of the operations that first give them; images that coincide within the tolerance are merged. Raises SymcrysError as site_symmetry.

Parameters:

tolerance (keyword-only, optional) – Two points count as the same, modulo the lattice, if each coordinate (lattice basis) differs by less than this from an integer. Default 10⁻⁶; must be below 1/2.

Returns:

numpy.ndarray – A float64 array of shape (n, 2), the images as rows.

symcrys.plane.plane_group(key: str) → dict[str, Any]

The plane group with this key (short symbol). Raises SymcrysError for an unknown key.

Returns:

dict – centring is a float64 array of shape (n, 2), n = 0 or 1.

symcrys.plane.point_group(key: str) → dict[str, Any]

The plane point group with this key. Raises SymcrysError for an unknown key.

symcrys.plane.settings(key: str) → list[dict[str, Any]]

The settings of a plane point group: two for 3m (3m1, the default, and 31m), one for the others. Raises SymcrysError for an unknown key.

symcrys.plane.site_symmetry(key: str, point: ArrayLike, *, tolerance: float | None = None) → dict[str, Any]

The site symmetry of a point (lattice basis) under a plane group: the operations that map it onto itself modulo the lattice within the tolerance, closed into a group, and the point set onto their fixed space. Raises SymcrysError for an unknown key, a point that is not two finite numbers, or a tolerance outside (0, 1/2).

Parameters:

tolerance (keyword-only, optional) – Two points count as the same, modulo the lattice, if each coordinate (lattice basis) differs by less than this from an integer. Default 10⁻⁶; must be below 1/2.

Returns:

dict – operations int64 array of shape (n,), point float64 array of shape (2,), multiplicity, general.

symcrys.plane.symbol(key: str, *, setting: int | None = None) → str

The symbol of a plane point group in a setting: '3m1' or '31m' for 3m, otherwise the key.

Parameters:

setting (keyword-only, optional) – 1-based setting: for the point group 3m 1 is 3m1 (default) and 2 is 31m; the other point groups have one, and a plane group takes only 1.

symcrys.plane.symmetry_elements(key: str) → dict[str, Any]

The symmetry elements of a plane group in its conventional cell [0, 1]², boundary included: every rotation centre with the highest order of a rotation about it, and every mirror and glide line that crosses the cell, with the segment inside it. Raises SymcrysError for an unknown key.

Returns:

dict – rotations: dicts {"order", "point"}, point a float64 array of shape (2,); lines: dicts {"kind", "direction", "glide", "segment"}, direction int64 of shape (2,), glide float64 of shape (2,), segment float64 of shape (2, 2), the two ends as rows.

symcrys.plane.wyckoff_position_of(key: str, point: ArrayLike, *, tolerance: float | None = None) → dict[str, Any]

The Wyckoff position of a point (lattice basis) under a plane group, as wyckoff_positions gives it: the printed position of the point’s multiplicity whose coordinates, with the centring, reach the point set onto its site symmetry. Raises SymcrysError as site_symmetry.

Parameters:

tolerance (keyword-only, optional) – Two points count as the same, modulo the lattice, if each coordinate (lattice basis) differs by less than this from an integer. Default 10⁻⁶; must be below 1/2.

symcrys.plane.wyckoff_positions(key: str) → list[dict[str, Any]]

The Wyckoff positions of a plane group as ITA prints them, general position first. Raises SymcrysError for an unknown key and for a plane point group, whose positions are not in symcrys yet.