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 ofcrystal_formsnames 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_nameis 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
operationsallows. Checks the operations asallows_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
operationsallows 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,
representativehashkl(int64, shape (3,)) andcartesian(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
operationsfor 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) haslattice(int64, shape (3,)) andcartesian(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_operationsnames 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 withintolerance(defaultEPSILON, as forpoint_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) hascartesian(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:2for 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 printsm3m; 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; formm2settings 2 and 3, which ITA does not list, those of setting 1 carried into their frame. Birss convention: birss-app’s generators (for1the 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 is6/mmm: the holohedry of the crystal family isholohedry(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
operationscontains the inversion, e.g. for the operations of a distorted crystal. A list that is not closed is closed first. For a crystal class, readpoint_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
operationsis chiral: proper rotations only. For a crystal class, readpoint_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
keyis 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
operationsfor 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 oflattice_basisand the Cartesian matrix R ofoperations. 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_basiswhere 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 amin_volume_ratiothat 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_cellotherwise 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, aslattice_operationsgives 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, defaultEPSILON). 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
nullfor 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
Pare 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
hklanduvwis 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(oruvw) is an int64 array of shape (3,) andoperationsan int64 array of shape (n,);indicesis 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, defaultEPSILON, as forsite_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 (withintolerance, at leastEPSILON).- 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,
directionis a float64 array of shape (3,) andoperationsan 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(defaultEPSILON) 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 (withintolerance, at leastEPSILON). The classes1and-1have 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 matrixrotation: 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 inTENSOR_PROPERTIES.- Returns:
numpy.ndarray – A float64 array of shape (3**rank,);
tensormay 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) underoperations, 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,multiplicitymay not be an integer. The matrices must be Cartesian and orthogonal (not those oflattice_operations). Raises SymcrysError for a matrix that is not orthogonal (withintolerance, at leastEPSILON), 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 –
operationsint64 array of shape (n,),directionfloat64 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 class32.'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 ofdescribe_operationsmay 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
directionshaslattice(int64, shape (3,)) andcartesian(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 inTENSOR_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 –
basisfloat64 array of shape (p, 3**rank),parametersint64 array of shape (p, rank),relationsfloat64 array of shape (3**rank - p, 3**rank),rank; p is the number of free parameters. A row ofbasisreshaped to(3,) * rankis 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 inTENSOR_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 –
basisfloat64 array of shape (p, 3**rank),parametersint64 array of shape (p, rank),relationsfloat64 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).
toleranceas forsite_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 –
representativehashkl(int64, shape (3,)) andcartesian(float64, shape (3,)),site_symmetry_operationsis 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,
representativehashkl(int64, shape (3,)) andcartesian(float64, shape (3,)),site_symmetry_operationsis 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
operationsallows. Checks the operations asallows_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
operationsallows 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
operationsfor 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) haslattice(int64, shape (3,)) andcartesian(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_operationsnames 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 withintolerance(defaultEPSILON, as forpoint_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) hascartesian(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'and6'/mmm', setting 2; Birss printsm'm'mand6'/mm'mfor 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 printsm'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; formm2settings 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 by1'. Birss convention: birss-app’s generators (for1the 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 is6/mmm: the holohedry of the crystal family isholohedry(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
operationscontains 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, readpoint_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
operationsis 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, readpoint_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
keyis 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
operationsfor 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 oflattice_basisand 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_basiswhere 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 amin_volume_ratiothat 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_cellotherwise 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, aslattice_operationsgives 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, defaultEPSILON). 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
nullfor 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
Pare 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
hklanduvwis 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(oruvw) is an int64 array of shape (3,) andoperationsan int64 array of shape (n,);indicesis 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, defaultEPSILON, as forsite_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 oflattice_operations; withintolerance, at leastEPSILON).- 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,
directionis a float64 array of shape (3,) andoperationsan 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(defaultEPSILON) 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 (withintolerance, at leastEPSILON) and for an operation that does not say whether it is combined with time reversal. The classes1and-1have 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_KEYSof 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 matrixrotation: 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 inTENSOR_PROPERTIES.- Returns:
numpy.ndarray – A float64 array of shape (3**rank,);
tensormay 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) underoperations, 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,multiplicitymay not be an integer. The matrices must be Cartesian and orthogonal (not those oflattice_operations). Raises SymcrysError for a matrix that is not orthogonal (withintolerance, at leastEPSILON), 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 –
operationsint64 array of shape (n,),directionfloat64 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 class32.'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 ofdescribe_operationsmay 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
directionshaslattice(int64, shape (3,)) andcartesian(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 inTENSOR_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 –
basisfloat64 array of shape (p, 3**rank),parametersint64 array of shape (p, rank),relationsfloat64 array of shape (3**rank - p, 3**rank),rank; p is the number of free parameters. A row ofbasisreshaped to(3,) * rankis 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 inTENSOR_PROPERTIES. The operations are Cartesian and orthogonal, and each says whether it is combined with time reversal (time_reversal,TrueorFalse); 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 –
basisfloat64 array of shape (p, 3**rank),parametersint64 array of shape (p, rank),relationsfloat64 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 –
verticesa float64 array of shape (n, 2),inequalitiesan 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
3m1 is3m1(default) and 2 is31m; the other point groups have one, and a plane group takes only 1.- Returns:
list of dict –
translation,locationandglide(where present) are float64 arrays of shape (2,),directionan 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
3m1 is3m1(default) and 2 is31m; 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
3m1 is3m1(default) and 2 is31m; 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 –
centringis 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, and31m), 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 –
operationsint64 array of shape (n,),pointfloat64 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'for3m, otherwise the key.- Parameters:
setting (keyword-only, optional) – 1-based setting: for the point group
3m1 is3m1(default) and 2 is31m; 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_positionsgives it: the printed position of the point’s multiplicity whose coordinates, with the centring, reach the point set onto its site symmetry. Raises SymcrysError assite_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.