crystod.group

crystod.group#

Group-theory API of CrystOD: the crystod-group command as Python objects.

crystod.group covers the representation theory that the crystod-group command exposes: direct products and character tables of point and space groups, the reduction of reducible representations, ligand-field splittings and multi-electron terms, isotropy subgroups and symmetry-mode analysis, and the ISO-IR (ISOTROPY) irrep tables behind every label CrystOD prints. Every name below is the implementation object of the corresponding command mode, so the vocabulary (irrep labels, order-parameter directions, k-point names) is the same as in the printed output.

Usage:

from crystod import group

subs = group.isotropy_subgroups("Pm-3m", "R4+")
algebra = group.SpaceGroupIrrepAlgebra("Pm-3m")
print(group.format_product_report(algebra, ["R4-", "R5+"]))

Space-group irreps (crystod-group --product --sg):

SpaceGroupIrrepAlgebra – space-group operations and ISO-IR irreps in the primitive basis; stars, induced characters, direct products.
format_product_report – the --product report as text.

Isotropy subgroups (crystod-group --parent):

isotropy_subgroups – subgroups of an irrep (or of coupled irreps) as IsotropySubgroup records: the data-level entry point.
IsotropyAnalyzer – the full machinery: directions, stabilizers, subgroup identification, conventional settings.
InducedRepresentation, CoupledRepresentation – the real matrices of the order parameter of one irrep or of several coupled irreps.

Symmetry-mode analysis (crystod-group --supergroup-cif):

SymmetryModeAnalysis – AMPLIMODES-style decomposition of the distortion between a parent and a child structure into parent irreps.

Point-group tools (--table, --decompose, --product --pg, --ligand-field):

get_character_table – phonopy character table of a point group; format_irrep_table renders it.
decompose, decompose_representation – reduce a character vector into irreps; direct_product_character multiplies irreps.
get_orbital_characters – the (2l+1)-dimensional orbital representation (ligand-field splitting).
format_spacegroup_table – the character table of the little group of k with ISO-IR labels (--table --sg --kpoint).

Multiplets (crystod-group --multiplet):

parse_config, shell_terms, couple_shells, hund_candidates – term symbols of an electron configuration over irrep shells.
compute_term_energies, ground_state – exact Coulomb multiplet energies in Racah / Slater parameters and the resulting ground term.

Structure files (crystod-group --poscar2cif, --cif2poscar):

bilbao_cif_lines, poscar_lines – Bilbao-style CIF and POSCAR writers.

Star of k (crystod --star-of-k; also in crystod.salc):

compute_star, format_star_lines, resolve_kpoint_input.

ISO-IR tables:

IsoIRLabeler, get_isoir_label_map – label spgrep small irreps with ISO-IR (Miller-Love) labels; load_isoir_irreps reads the tables.

Attributes resolve lazily (PEP 562): import crystod.group is instant and pulls in phonopy, spgrep and spglib only when a name is first used. Functions reached through this namespace report bad input as ValueError; the classes are the implementation classes themselves and raise SystemExit as the command line does.

class crystod.group.CoupledRepresentation(algebra, irrep_labels)[source]#

Bases: object

Direct sum of several induced irreps (coupled order parameters).

A distortion condensing several irreps simultaneously transforms as this reducible representation; its isotropy subgroups are the stabilizers of the coupled order parameter (eta_1, eta_2, ...). This is what crystod-group --parent SG --irrep X3- X2+ analyzes. The components group irrep by irrep (then arm by arm within each irrep), and because the matrices are block diagonal every fixed subspace is a direct sum of per-irrep subspaces: the amplitudes of different irreps are always independent free parameters.

Parameters:

algebra (SpaceGroupIrrepAlgebra) – The SpaceGroupIrrepAlgebra of the space group.
irrep_labels (list[str]) – ISO-IR labels of the coupled irreps, e.g. ["X3-", "X2+"].

Variables:

parts – The InducedRepresentation of every irrep, in input order.
dims – Dimension of every part; dimension is their sum.
name – The combined label, e.g. "X3- + X2+".
grid_n – Period of the common lattice-translation grid (least common multiple of the parts’ periods).
elements – All distinct group elements as (i, t, matrix) with the block-diagonal real matrix.

Raises:

SystemExit – A label is not tabulated for this space group.

image_elements()[source]#

All group elements of the coupled representation.

Returns:: The elements list of (i, t, matrix) triples.

class crystod.group.InducedRepresentation(algebra, irrep_label)[source]#

Bases: object

Full (induced) irrep of a space group as explicit real matrices.

The representation of the order parameter of one ISO-IR irrep, used by crystod-group --parent (through IsotropyAnalyzer) and by the symmetry-mode analysis. The basis index is (arm a, small-irrep row p) and the group elements are parametrized as (coset representative i, lattice translation t):

D(g_i + t) = T(t) B_i,   T(t) = diag_a exp(SIGMA*2j*pi q_a.t) (x) 1_d

The small-irrep matrices come from spgrep and are matched to the tabulated ISO-IR characters (with an origin-shift search where the conventions differ); the induced blocks are verified against the independently induced characters. The matrices are finally brought to the real, physically irreducible form: real-type irreps by a similarity transform, complex- and pseudoreal-type irreps as the doubled real form of D + D* (the paired ISOTROPY entries such as P1P2).

Parameters:

algebra (SpaceGroupIrrepAlgebra) – The SpaceGroupIrrepAlgebra of the space group.
irrep_label (str) – ISO-IR irrep label, e.g. "R4+".

Variables:

algebra – The algebra the representation was built from.
irrep – The tabulated irrep record (name, dim, kpname).
k – k vector of the irrep (primitive basis, units of 1/DEN).
arms – Star arms, shape (n_arms, 3); representatives holds the coset-representative index generating each arm.
n_arms – Number of star arms.
dim_small – Dimension of the small irrep.
dimension – Dimension of the order parameter (n_arms * dim_small, doubled for complex- and pseudoreal-type irreps).
blocks – The matrices B_i of the coset representatives, before realification.
elements – All distinct group elements as (i, t, matrix) with the real matrix of D(g_i + t); t runs over the translation grid of period grid_n.
doubled – True when the physically irreducible form is D + D*; fs_type then names the type ("complex" or "pseudoreal").
grid_n – Period of the lattice-translation grid on which the matrices are distinct.

Raises:

SystemExit – Unknown irrep label, or a tabulated entry that cannot be matched to any spgrep small irrep.

Example

>>> from crystod import group
>>> algebra = group.SpaceGroupIrrepAlgebra("Pm-3m")
>>> rep = group.InducedRepresentation(algebra, "R4+")
>>> rep.dimension, rep.n_arms, rep.dim_small, rep.label, rep.doubled
(3, 1, 3, 'R4+', False)

conjugate_partner()[source]#

ISO-IR label of the complex-conjugate partner irrep.

The partner lives at the same k star, or at the -k star for +-k pairs such as P/PA; it is identified through the induced characters (ours taken directly from the induced blocks).

Returns:: The partner label, or None when the irrep is self-conjugate or no partner is tabulated.
Return type:: str | None

image_elements()[source]#

All group elements of the representation.

Returns:: The elements list, one (i, t, matrix) triple per group element (coset-representative index, lattice translation, real matrix).

translation_phases(t)[source]#

Diagonal of T(t) for a lattice translation.

Parameters:: t (ndarray) – Lattice translation, integer vector in primitive units.
Returns:: The phases exp(SIGMA * 2j * pi * q_a . t), one entry per (arm, small-irrep row) in the basis order of blocks.
Return type:: ndarray

property arm_chunks: list[int]#

Number of order-parameter components per star arm.

ISOTROPY separates arms by ; and components within one arm by , in the direction labels.

property label: str#: Irrep label; the ISOTROPY-style pair label (P1P2) when doubled.

class crystod.group.IsoIRLabeler(sgnum, transformation_matrix=None, origin_shift=None, cell=None, symprec=1e-05)[source]#

Bases: object

Label spgrep small representations with ISO-IR (Miller-Love) labels.

The labeling engine shared by every CrystOD command (crystal orbitals, phonons, spin bases, crystod-group --table --sg): spgrep computes the small irreps of the little group of k in the primitive basis of the user’s cell, and this class matches their characters against the ISO-IR tables in the ISOTROPY standard setting (origin choice 2, orthorhombic axes abc, monoclinic axes a(b)c cell choice 1, hexagonal axes), at tabulated k points as well as on symmetry lines, planes and the general point. Because ISO-IR uses the phase convention exp(+2 pi i k.t) and spgrep exp(-2 pi i k.t), spgrep characters are compared with the complex conjugate of the ISO-IR characters.

Parameters:

sgnum (int) – Space-group number (1-230).
transformation_matrix – spglib-style transformation P into the ISO-IR setting (x_conventional = P x_primitive + origin_shift); give it together with origin_shift when cell is omitted.
origin_shift – The origin shift of that transformation.
cell – Alternatively, the primitive cell (lattice, scaled_positions, numbers) whose operations feed spgrep; the transformation is then computed with spglib for the Hall number of the ISO-IR setting.
symprec (float) – Symmetry tolerance for spglib when cell is given.

Variables:

sgnum – The space-group number.
P – The transformation matrix into the ISO-IR setting; Pinv its inverse and origin_shift the accompanying shift.
irreps – The IsoIrrep records of the space group, from load_isoir_irreps.

Raises:

ValueError – spglib could not standardize cell to the ISO-IR setting.
FileNotFoundError – The ISO-IR data file is not available.

Example

>>> import numpy as np
>>> from crystod import group
>>> labeler = group.IsoIRLabeler(221, transformation_matrix=np.eye(3),
...                              origin_shift=np.zeros(3))
>>> labeler.kpoint_name([0.5, 0.5, 0.4]), labeler.kpoint_name([0, 0, 0])
('T', 'GM')

conventional_k(k_primitive)[source]#

k vector in the ISO-IR conventional reciprocal basis.

Parameters:: k_primitive – k vector in the primitive reciprocal basis.
Returns:: k_primitive @ P^-1 as a float array.
Return type:: ndarray

conventional_operations(rotations, translations)[source]#

Map primitive-basis operations into the ISO-IR conventional setting.

Parameters:

rotations – Integer rotation matrices in the primitive basis.
translations – Their fractional translations.

Returns:

[(R_c, t_c), ...] with R_c = P R P^-1 and t_c = P t + (1 - R_c) origin_shift.

decompose_characters(k_primitive, little_rotations, little_translations, reducible_characters, atol=0.001)[source]#

Decompose a reducible character vector into ISO-IR irreps.

Used for phonopy band sets, whose characters can be reducible under accidental degeneracy.

Parameters:

k_primitive – k vector in the primitive reciprocal basis.
little_rotations – Rotations of the little group of k in the primitive basis.
little_translations – Their fractional translations.
reducible_characters – The character vector, aligned with the little-group operations, in the spgrep/phonopy phase convention exp(-2 pi i k.t).
atol (float) – Tolerance of the multiplicity check.

Returns:

([(label, multiplicity, small_dim), ...], k-type label), or None when no consistent decomposition exists.

Return type:

tuple[list[tuple[str, int, int]], str] | None

decompose_characters_many(k_primitive, little_rotations, little_translations, character_vectors, atol=0.001)[source]#

Decompose several reducible character vectors at one k point.

Same as decompose_characters, but the candidate-family search (the expensive part) is done once and shared by all vectors; use this for phonopy band sets, which all live at the same q.

Parameters:

k_primitive – k vector in the primitive reciprocal basis.
little_rotations – Rotations of the little group of k in the primitive basis.
little_translations – Their fractional translations.
character_vectors – The reducible character vectors, each aligned with the little-group operations (phase convention exp(-2 pi i k.t)).
atol (float) – Tolerance of the multiplicity check.

Returns:

One entry per input vector, each ([(label, multiplicity, small_dim), ...], k-type label) or None when no consistent decomposition exists.

Return type:

list[tuple[list[tuple[str, int, int]], str] | None]

kpoint_name(k_primitive)[source]#

Most specific ISO-IR k-vector type label containing a k point.

Parameters:: k_primitive – k vector in the primitive reciprocal basis.
Returns:: The type label with the fewest free parameters, e.g. "T" for (1/2, 1/2, 0.4) in Pm-3m; None when no entry matches.
Return type:: str | None

label_characters(k_primitive, little_rotations, little_translations, spgrep_characters, atol=1e-05)[source]#

Match spgrep small-irrep characters against the ISO-IR tables.

Parameters:

k_primitive – k vector in the primitive reciprocal basis.
little_rotations – Rotations of the little group of k in the primitive basis.
little_translations – Their fractional translations.
spgrep_characters – One character vector per spgrep irrep, aligned with the little-group operations and computed with the spgrep phase convention exp(-2 pi i k.t).
atol (float) – Tolerance of the character comparison.

Returns:

({spgrep irrep index: ISO-IR label}, k-type label), e.g. ({0: "R1+", ...}, "R"), or None when no consistent assignment exists.

Return type:

tuple[dict[int, str], str] | None

class crystod.group.IsotropyAnalyzer(space_group, irrep_labels)[source]#

Bases: object

Isotropy subgroups of a space-group irrep (or of coupled irreps).

The machinery behind crystod-group --parent SG --irrep IR: it builds the real induced representation of the order parameter, enumerates the order-parameter directions (the strata of the representation), finds the stabilizer of any direction, and identifies the resulting space group with spglib, including the conventional basis and origin of the subgroup in the parent convention. The data-level function crystod.group.isotropy_subgroups returns the same results as IsotropySubgroup records; use this class when the matrices, the subgroup elements or a custom direction are needed.

Parameters:

space_group (str) – International short symbol ("Pm-3m") or number ("221") of the parent space group.
irrep_labels (str | list[str]) – One ISO-IR label ("R4+") or a list of labels for coupled order parameters (["X3-", "X2+"]).

Variables:

algebra – The SpaceGroupIrrepAlgebra of the parent space group.
representation – The InducedRepresentation (one label) or CoupledRepresentation (several labels) of the order parameter.
elements – The group elements (i, t, matrix) of the representation (representation.image_elements()).

Raises:

SystemExit – Unknown space group, or an irrep label that is not tabulated for it (the labels of symmetry lines and planes, e.g. DT5, have no entries in the tables).

Example

>>> from crystod import group
>>> analyzer = group.IsotropyAnalyzer("Pm-3m", "R4+")
>>> for projector, members in analyzer.enumerate_directions():
...     label, _ = analyzer.direction_label(projector)
...     info, size, index, *_ = analyzer.subgroup_of(members)
...     print(label, info.number, info.international_short, size, index)
(a,b,c) 2 P-1 2 48
(0,0,a) 140 I4/mcm 2 6
(0,a,b) 12 C2/m 2 24
(a,a,a) 167 R-3c 2 8
(0,a,a) 74 Imma 2 12
(a,a,b) 15 C2/c 2 24

classmethod from_representation(algebra, representation)[source]#

Analyzer over an already-built representation.

Parameters:

algebra – The SpaceGroupIrrepAlgebra the representation was built from.
representation – An InducedRepresentation or CoupledRepresentation (anything with image_elements(), dimension and grid_n).

Returns:

A new IsotropyAnalyzer sharing the algebra.

conventional_setting(B, rotations, translations, lattice, info)[source]#

Conventional basis and origin of the subgroup (parent convention).

Built from a generic-orbit structure with exactly the subgroup symmetry, standardized by spglib.

Parameters:

B – Sublattice basis from subgroup_of.
rotations – Subgroup rotations from subgroup_of.
translations – Subgroup translations from subgroup_of.
lattice – Sublattice vectors from subgroup_of.
info – Space-group type from subgroup_of.

Returns:

the rows of the child conventional basis and its origin, both in parent conventional units (as printed by --order-parameter); None when spglib could not standardize the subgroup.

Return type:

(basis, origin) rounded to six decimals

direction_label(projector, letter_offset=0)[source]#

Direction label of a stratum and a generic representative.

Parameters:

projector (ndarray) – Orthogonal projector onto the subspace of the stratum.
letter_offset (int) – Shift of the free-parameter letters (used for the single-irrep tables of a coupled run, so that every irrep keeps its own letters: X3-(a,b) + X2-(c,d)).

Returns:

the ISOTROPY-style pattern such as "(a,a,0)" (; separates star arms, , components within one arm; coupled runs give "X3-(a,b) X2-(c,d)") and a generic order-parameter vector inside the stratum.

Return type:

(label, generic)

enumerate_directions()[source]#

Enumerate the order-parameter direction types (strata).

Seeds the search with the fixed spaces of every group element and closes the set under pairwise intersection; keeps the isotropy subspaces (V == Fix(Stab(V))) and one representative per group orbit (the one with the simplest direction label). This is the listing of crystod-group --parent without --order-parameter.

Returns:: A list of (projector, members) pairs, one per stratum, with the orthogonal projector onto the subspace of the stratum and the (i, t) elements of its stabilizer (the isotropy subgroup).

fixed_space(members)[source]#

Common fixed subspace of a set of group elements.

Parameters:: members – (i, t) pairs as returned by stabilizer_of.
Returns:: An orthonormal basis of the fixed subspace as columns, shape (dimension, n_free); the identity when members is empty.
Return type:: ndarray

resolve_direction(tokens)[source]#

Order parameter from --order-parameter tokens.

Parameters:: tokens (list[str]) – One token per component, e.g. ["0", "0", "a"] or ["a", "a", "0"]; letters are free parameters (equal letters mean equal components), numbers and fractions are taken literally, a leading - flips the sign.
Returns:: A representative order-parameter vector of length dimension.
Raises:: SystemExit – Wrong number of components, or an all-zero order parameter.
Return type:: ndarray

stabilizer_of(projector)[source]#

Group elements acting as the identity on a subspace.

Parameters:: projector (ndarray) – Orthogonal projector onto the subspace of order parameters, shape (dimension, dimension).
Returns:: The (i, t) pairs (coset-representative index, lattice translation) whose matrices fix every vector of the subspace.

subgroup_of(members)[source]#

Space-group type of the isotropy subgroup with the given elements.

The pure lattice translations among the members span the sublattice of the subgroup; the operations are re-expressed in that sublattice basis and identified with spglib through a generic-orbit structure.

Parameters:: members – (i, t) pairs of the subgroup (from stabilizer_of or enumerate_directions).
Returns:: the spglib space-group type of the subgroup (number, international_short, …), the primitive-cell multiplication size, the index of the subgroup in the parent, the sublattice basis B (rows, parent primitive units), the subgroup operations in that basis, and the sublattice vectors (rows, Cartesian, in an invariant parent lattice).
Return type:: (info, size, index, B, rotations, translations, lattice)
Raises:: SystemExit – spglib could not identify the subgroup.

class crystod.group.IsotropySubgroup(irrep, direction, label, number, symbol, size, index, n_free, basis=None, origin=None)[source]#

Bases: object

One isotropy subgroup of a space-group irrep.

One row of the crystod-group --parent table, as returned by isotropy_subgroups() and carried by crystod.phonon.ImaginaryModeResult.

Variables:

irrep (str) – ISO-IR label of the irrep, e.g. "R4+" ("X3-+X2+" for a coupled order parameter).
direction (str) – Order-parameter direction, e.g. "(a,0,0)"; the components are grouped arm by arm ("," inside an arm, ";" between arms).
label (str) – Full label, e.g. "R4+(a,0,0)".
number (int) – Space-group number of the subgroup.
symbol (str) – International short symbol of the subgroup, e.g. "I4/mcm".
size (int) – Primitive-cell multiplication of the subgroup relative to the parent.
index (int) – Index of the subgroup in the parent, [G:H].
n_free (int) – Number of free order-parameter components.
basis (numpy.ndarray | None) – Rows of the conventional cell of the subgroup in parent conventional units, exactly as printed by crystod-group --parent --order-parameter; None when the setting could not be standardized or with_settings=False was passed.
origin (numpy.ndarray | None) – Origin of that cell in parent conventional coordinates, or None likewise.

basis: ndarray | None = None#

direction: str#

index: int#

irrep: str#

label: str#

n_free: int#

number: int#

origin: ndarray | None = None#

size: int#

symbol: str#

class crystod.group.SpaceGroupIrrepAlgebra(space_group_symbol)[source]#

Bases: object

Space-group operations and ISO-IR irrep tables in the primitive basis.

The algebra behind crystod-group --product IRREP... --sg SG and the isotropy-subgroup and symmetry-mode machinery: it holds the coset representatives of the space group (rotations and translations in the primitive basis, translations as integers in units of 1/DEN), the tabulated ISO-IR small irreps grouped by k-point name, and the induced (full) characters over the star of every k point. Every convention is verified at run time (group closure, little-group match against the tables), and the tables are extended on the fly with spgrep for k points that are not tabulated (symmetry lines and planes reached by sums of star arms).

Parameters:

space_group_symbol (str) – International short symbol ("Pm-3m", "P6_3/mmc") or space-group number ("221").

Variables:

sg_type – spglib space-group type record (number, international_short, hall_number, …).
table – The ISO-IR irrep table of the space group (irreps, symmetries).
primitive_matrix – Conventional-to-primitive transformation matrix (phonopy convention for the centring).
rotations – Integer rotation parts of the coset representatives in the primitive basis, shape (n_ops, 3, 3).
translations – Translation parts, shape (n_ops, 3), integers in units of 1/DEN (DEN = 24), reduced modulo lattice translations.
n_ops – Number of coset representatives (order of the point group).
irreps_by_kname – Tabulated irreps grouped by k-point name, in table order ({"GM": [...], "R": [...], ...}); each irrep record has name, dim, kpname and characters.
k_by_kname – k vector of every tabulated k point in the primitive basis, integers in units of 1/DEN.

Raises:

SystemExit – Unknown space-group symbol or number, or a table whose conventions cannot be reconciled with the primitive setting.

Example

>>> from crystod import group
>>> algebra = group.SpaceGroupIrrepAlgebra("Pm-3m")
>>> algebra.n_ops, list(algebra.k_by_kname)
(48, ['GM', 'R', 'X', 'M'])
>>> [irrep.name for irrep in algebra.irreps_by_kname["R"]]
['R1+', 'R2+', 'R3+', 'R4+', 'R5+', 'R1-', 'R2-', 'R3-', 'R4-', 'R5-']

computed_irreps_at(k_int)[source]#

Small irreps at an arbitrary k point, computed with spgrep.

Parameters:: k_int (ndarray) – k vector in the primitive basis, integers in units of 1/DEN.
Returns:: A list with one dict per small irrep. Each dict holds "chi" ({op_index: character}), "dim" (the dimension) and "small" ({op_index: matrix}), keyed by this algebra’s operation indices (the little group of k).
Raises:: SystemExit – spgrep could not compute the irreps at this k point, or its little group disagrees with the q-convention one.
Return type:: list

decompose_product(labels)[source]#

Decompose the direct product of the full irreps named by labels.

The computation behind crystod-group --product IRREP... --sg SG: the reduction coefficients are character inner products over the finite factor group, with the momentum-conservation condition k1_a + k2_b = k3_c (modulo the reciprocal lattice) over the star arms. Product terms at non-tabulated k points are computed with spgrep and named from the ISO-IR tables.

Parameters:: labels (list[str]) – ISO-IR labels of the factors, e.g. ["R4-", "R5+"].
Returns:: factors are the resolved irrep records; terms is a list of (kname, irrep, multiplicity) where irrep has name, dim and kpname (a tabulated ISO-IR irrep or a computed line irrep); leftovers lists the k vectors (units of 1/DEN) that could not be decomposed at all.
Return type:: (factors, terms, leftovers)
Raises:: SystemExit – A label is not tabulated for this space group.

Example

>>> from crystod import group
>>> algebra = group.SpaceGroupIrrepAlgebra("Pm-3m")
>>> factors, terms, left = algebra.decompose_product(["R4-", "R5+"])
>>> [(irrep.name, n) for _, irrep, n in terms]
[('GM2-', 1), ('GM3-', 1), ('GM4-', 1), ('GM5-', 1)]

find_irrep(label)[source]#

Tabulated irrep record with the given ISO-IR label.

Parameters:: label (str) – ISO-IR irrep label, e.g. "R4+".
Returns:: The irrep record (attributes name, dim, kpname, characters) of the ISO-IR table.
Raises:: SystemExit – The label is not tabulated for this space group; the message lists the available labels.

full_dimension(irrep)[source]#

Dimension of a full space-group irrep (star size times small dim).

Parameters:: irrep – A tabulated irrep record or a computed line irrep (as returned in the terms of decompose_product).
Returns:: The number of star arms times the small-irrep dimension.
Return type:: int

induced_characters(irrep)[source]#

Characters of the full (induced) irrep, arm by arm.

Parameters:: irrep – A tabulated irrep record (from find_irrep or irreps_by_kname).
Returns:: (arms, C) with C[i, a] = chi_small(s_a^-1 g_i s_a) when operation g_i fixes arm a and 0 otherwise; the full character of (g_i, t) is sum_a C[i, a] exp(SIGMA * 2j * pi * q_a . t).
Raises:: SystemExit – The tabulated characters do not match any small representation allowed at that k point (convention mismatch).
Return type:: tuple[ndarray, ndarray]

induced_characters_at(k_int, small)[source]#

Induced characters of a computed small irrep at an arbitrary k.

Parameters:

k_int (ndarray) – k vector in the primitive basis, integers in units of 1/DEN.
small (dict) – One entry of computed_irreps_at(k_int) (only its "chi" is used).

Returns:

(arms, C) with the same structure as induced_characters.

Return type:

tuple[ndarray, ndarray]

isoir_display_arm(canonical)[source]#

Star arm in the tabulated ISO-IR parametrization, for display.

Parameters:: canonical (ndarray) – Representative arm of a non-tabulated star (units of 1/DEN).
Returns:: The arm matching arm 0 of the ISO-IR k-vector type (e.g. SM as (a,a,0) rather than (0,a,a)); canonical itself when no ISO-IR entry matches.
Return type:: ndarray

little_group(k)[source]#

Indices of the coset representatives in the little group of k.

Parameters:: k (ndarray) – k vector in the primitive basis, integers in units of 1/DEN.
Returns:: The operation indices i whose q-action k . W_i^-1 leaves k invariant modulo the reciprocal lattice.
Return type:: list[int]

star(kname)[source]#

Arms of the star of a tabulated k point.

Parameters:: kname (str) – k-point name of the ISO-IR table, e.g. "X".
Returns:: the arms as an integer array of shape (n_arms, 3) in the q-convention q_a = k . W_{s_a}^-1 (units of 1/DEN), and the index of the coset representative s_a generating every arm.
Return type:: (arms, representatives)

class crystod.group.SymmetryModeAnalysis(parent_file, child_file, tolerance)[source]#

Bases: object

Symmetry-mode decomposition of a parent-child structure pair.

The analysis behind crystod-group --supergroup-cif PARENT --subgroup-cif CHILD: the displacive distortion between a high-symmetry (parent) structure and a low-symmetry (child) structure of the same compound is decomposed into symmetry-adapted modes of the parent space group, giving for every parent irrep the k vector, the order-parameter direction, the isotropy subgroup, the number of independent modes and the amplitude in Angstrom (AMPLIMODES convention). All the work happens in the constructor; the results are read from the attributes.

Parameters:

parent_file (str) – High-symmetry structure file (CIF or POSCAR).
child_file (str) – Low-symmetry (distorted) structure file (CIF or POSCAR); its primitive cell must be an integer multiple of the parent’s.
tolerance (float) – Symmetry-detection tolerance (symprec, Angstrom) for both structures; the command’s default is 0.01.

Variables:

parent_number – Space-group number of the parent (parent_symbol its Hermann-Mauguin symbol); child_number and child_symbol likewise for the child.
algebra – The SpaceGroupIrrepAlgebra of the parent.
L_parent – Parent primitive lattice vectors (rows, Angstrom) of the strain-free reference in which every displacement is measured.
parent_positions – Parent atoms in the primitive setting of the ISO-IR tables (fractional); parent_numbers their atomic numbers.
size – Primitive-cell multiplication of the child relative to the parent.
mapping – The atom pairing: mapping.S (child primitive basis in parent primitive units, rows), mapping.p (origin shift), mapping.ref_frac (reference atoms), mapping.child_z (atomic numbers) and mapping.u_frac (displacements, parent primitive fractional). Among the symmetry-equivalent sublattice settings of a symmetric parent, S is the one whose child axes are rotated least against the parent axes as the input files orient them (setting_rotation, the residual rotation in degrees, None when the input orientation could not be recovered; equivalent_settings, how many settings tied).
core_size – Multiplication of the invariant-core analysis cell; its atoms are ref_frac (n_atoms of them) with atomic numbers ref_z and Cartesian displacements u_cart.
subgroup_members – The (i, t) parent operations that leave the distorted structure invariant.
stars – The parent k stars folding to the child Gamma point, one dict per star with kname, kvec (primitive basis) and kind ("tabulated" or "computed").
modes – One entry per parent irrep with a nonzero number of modes, carrying kname, kvec, irrep_name, dim (number of independent modes), amplitude (Angstrom), projected_u (the irrep-projected displacement field on the core cell, shape (n_atoms, 3)) and label_info(), which returns (direction label, subgroup info, index).
total_distortion – Total distortion amplitude (Angstrom), normalized within the primitive cell of the distorted structure.
parent_formula – Reduced chemical formula of the parent (the command names its sym_mode_<formula> table after it).

Raises:

SystemExit – The child cell is not an integer multiple of the parent cell, the child cannot be mapped onto the parent, or an internal consistency check (mode completeness) fails.

Example

>>> from crystod import group
>>> analysis = group.SymmetryModeAnalysis("221.cif", "140.cif", 0.01)
>>> for mode in analysis.modes:
...     label, info, index = mode.label_info()
...     print(mode.irrep_name, label, info.international_short,
...           mode.dim, round(mode.amplitude, 4))

crystod.group.bilbao_cif_lines(structure, tolerance, title)[source]#

Bilbao-style CIF of a structure, as lines.

The conversion behind crystod-group --poscar2cif -c POSCAR: the structure is brought to the spglib-standardized (idealized) conventional cell, which follows the International Tables (ITA) setting and origin – the convention of the Bilbao Crystallographic Server – and written with 4-decimal lattice parameters, the space-group number and symbol, the full list of conventional-cell operations as compact x,y,z strings, and one representative site per Wyckoff orbit.

Parameters:

structure – A pymatgen Structure (e.g. Structure.from_file).
tolerance (float) – Symmetry-detection tolerance (symprec, Angstrom); the command’s default is 0.01. A distortion below it is symmetrized away.
title (str) – The data_ block name (the command uses the POSCAR file name).

Returns:

the CIF lines without line terminators, and a dict with number, symbol, n_operations and n_sites.

Return type:

(lines, info)

Raises:

SystemExit – spglib could not determine the symmetry at this tolerance (ValueError when called through crystod.group).

Example

>>> from pymatgen.core import Structure
>>> from crystod import group
>>> from crystod.examples import example_path
>>> structure = Structure.from_file(example_path("221_PPOSCAR_ScF3"))
>>> lines, info = group.bilbao_cif_lines(structure, 0.01, "ScF3")
>>> info
{'number': 221, 'symbol': 'Pm-3m', 'n_operations': 48, 'n_sites': 2}
>>> lines[10]
'_symmetry_Int_Tables_number        221'

crystod.group.compute_star(rotations, translations, kpoint)[source]#

Compute the star of k: the orbit of a k point under the rotations.

Every rotation R of the space group sends k to k' = k R; the distinct images modulo reciprocal-lattice vectors are the arms of the star, and the rotations sending k to one arm form a coset of the little group of k. This is the computation behind crystod --star-of-k; crystod-phonon --modulation uses it to combine the arms of a multi-q modulation.

Parameters:

rotations (ndarray[tuple[Any, ...], dtype[int64]]) – Integer rotation matrices of the space group in the primitive basis, shape (n_ops, 3, 3) – for example SymmetryAdaptedOrbitalBasis.rotations.
translations (ndarray[tuple[Any, ...], dtype[float64]]) – The matching fractional translations, shape (n_ops, 3). Accepted for a uniform call signature; the star depends on the rotations only.
kpoint (list[float]) – Three primitive reciprocal coordinates of k.

Returns:

"kpoint" (the arm wrapped into [-0.5, 0.5)), "representative_index" (index of the first rotation reaching the arm, the coset representative) and "operation_indices" (indices of every rotation reaching the arm). With the identity listed first, as spglib does, the first arm is k itself and its "operation_indices" are the little group of k.

Return type:

One dict per arm, in order of first appearance along rotations

Example

>>> from phonopy.interface.calculator import read_crystal_structure
>>> from crystod import salc
>>> from crystod.examples import example_path
>>> cell, _ = read_crystal_structure(
...     str(example_path("221_PPOSCAR_ScF3")), interface_mode="vasp")
>>> basis = salc.SymmetryAdaptedOrbitalBasis(cell=cell)
>>> arms = salc.compute_star(basis.rotations, basis.translations,
...                          [0.5, 0.5, 0])
>>> [arm["kpoint"].tolist() for arm in arms]
[[0.5, 0.5, 0.0], [0.5, 0.0, 0.5], [0.0, 0.5, 0.5]]
>>> len(arms[0]["operation_indices"])
16

crystod.group.compute_term_energies(character_table, l, shells, terms)[source]#

Coulomb multiplet energies of every term of a configuration.

The Multiplet Energies block of crystod-group --multiplet CONFIG --pg PG --orbital ORB: exact diagonal energies of the electron-electron interaction as linear combinations of the Racah parameters A, B, C (d shells) or of the reduced Slater-Condon parameters (F0, F2 for p, F0, F2, F4, F6 for f), from two-electron integrals over the real orbitals of the shell, Slater determinants, and spin and point-group projectors. A term occurring more than once mixes (configuration interaction): for two occurrences the eigenvalues are given in closed form, for more numerically at the reference parameter point.

Parameters:

character_table (dict) – Table from crystod.group.get_character_table.
l (int) – Azimuthal quantum number of the parent atomic shell (0 to 3); the occupied irrep shells must occur in its ligand-field splitting.
shells (list[tuple[str, int]]) – [(irrep, n_electrons), ...] from crystod.group.parse_config.
terms (list[tuple[Fraction, str, int]]) – Terms (S, irrep, count) of the configuration, from crystod.group.shell_terms / couple_shells.

Returns:

the parameter names (["A", "B", "C"] for d), one TermEnergy per term in the order of terms (linear holds the exact coefficients of a unique term, ci_mean and ci_quadratic the closed-form CI block of a doubly occurring term, numeric the eigenvalues at the reference point; describe() formats them), the reference parameter values, and a note describing them (C/B = 4.5 for d).

Return type:

(params, energies, reference, reference_note)

Raises:

SystemExit – A projector rank or the trace identity disagrees with the term list (ValueError when called through crystod.group).

Example

>>> from crystod import group
>>> from crystod.multiplet import _GroupClasses
>>> ct = group.get_character_table("m-3m")
>>> classes = _GroupClasses(ct)
>>> shells = group.parse_config(["T2g3"], classes)
>>> terms = group.shell_terms(classes, "T2g", 3)
>>> params, energies, reference, note = group.compute_term_energies(
...     ct, 2, shells, terms)
>>> for (spin, irrep, _), entry in zip(terms, energies):
...     print(f"^{int(2 * spin + 1)}{irrep}:", entry.describe()[0])
^4A2g: 3A - 15B
^2Eg: 3A - 6B + 3C
^2T1g: 3A - 6B + 3C
^2T2g: 3A + 5C

crystod.group.couple_shells(classes, terms_a, terms_b)[source]#

Couple the term sets of two inequivalent shells.

The multi-shell step of crystod-group --multiplet T2g2 Eg1 --pg PG: electrons in different shells carry no mutual Pauli restriction, so the spatial parts couple by the direct product and the spins by angular-momentum addition S = |S1 - S2|, ..., S1 + S2.

Parameters:

classes (_GroupClasses) – Conjugacy classes of the point group (see shell_terms).
terms_a (list[tuple[Fraction, str, int]]) – Terms of the first shell, as returned by shell_terms.
terms_b (list[tuple[Fraction, str, int]]) – Terms of the second shell.

Returns:

Terms (S, irrep, count) of the coupled configuration; couple a third shell by calling again with this result.

Return type:

list[tuple[Fraction, str, int]]

crystod.group.decompose(characters, character_table, multiplicities)[source]#

Multiplicity of every irrep in a reducible representation.

The reduction formula n_i = (1/|G|) sum_C |C| chi_i(C) chi(C) over the classes C (real characters); the computation behind crystod-group --decompose and the last step of --ligand-field and --multiplet.

Parameters:

characters (list[float]) – Characters of the reducible representation, one per class in the order of character_table["rotation_list"].
character_table (dict) – The table from get_character_table.
multiplicities (list[int]) – Class sizes in the same order (the lengths of the entries of character_table["mapping_table"]).

Returns:

{irrep label: multiplicity} over every irrep of the table (zeros included), rounded to integers.

Return type:

dict[str, int]

Example

>>> from crystod import group
>>> ct = group.get_character_table("3m")
>>> sizes = [len(ops) for ops in ct["mapping_table"].values()]
>>> group.decompose([3, 0, 1], ct, sizes)
{'A1': 1, 'A2': 0, 'E': 1}

crystod.group.decompose_representation(ct, reducible_character)[source]#

Reduce a character vector into the irreps of a point group.

The second step of crystod-group --product with a point group, and the reduction used by --basis: the reduction formula with the class sizes taken from the table (same result as crystod.group.decompose, which takes the class sizes explicitly).

Parameters:

ct (dict) – Character table from crystod.group.get_character_table.
reducible_character (ndarray) – Characters of the reducible representation, one per class in the order of ct["rotation_list"].

Returns:

{irrep label: multiplicity} over every irrep of the table (zeros included).

Return type:

dict[str, int]

crystod.group.direct_product_character(ct, point_group, irreps)[source]#

Characters of the direct product of point-group irreps.

The first step of crystod-group --product IRREP... --pg PG: the character of a direct product is the product of the characters, class by class.

Parameters:

ct (dict) – Character table from crystod.group.get_character_table.
point_group (str) – Point-group label (used in the error message only).
irreps (list[str]) – Irrep labels to multiply, e.g. ["T2g", "T2g", "T1u"].

Returns:

The product characters, one per class in the order of ct["rotation_list"].

Raises:

SystemExit – An irrep label is not in the table; the message lists the available labels (ValueError when called through crystod.group).

Return type:

ndarray

Example

>>> from crystod import group
>>> ct = group.get_character_table("m-3m")
>>> chi = group.direct_product_character(ct, "m-3m", ["T2g", "T2g"])
>>> chi
array([9., 0., 1., 1., 1., 9., 1., 0., 1., 1.])
>>> {k: n for k, n in group.decompose_representation(ct, chi).items() if n}
{'A1g': 1, 'Eg': 1, 'T1g': 1, 'T2g': 1}

crystod.group.format_irrep_table(point_group, ct)[source]#

Character table of a point group as the --table text block.

What crystod-group --table --pg PG prints (and what --show-irrep-table adds to --product and --basis): one row per irrep, one column per class with the class size in parentheses.

Parameters:

point_group (str) – Point-group label, printed in the header.
ct (dict) – Character table from crystod.group.get_character_table.

Returns:

The table as one string (leading and trailing newline).

Return type:

str

Example

>>> from crystod import group
>>> ct = group.get_character_table("3m")
>>> print(group.format_irrep_table("3m", ct).strip())
* Point group *
3m

* IrRep Table *
table:
irrep  E(1)  C3(2)  sgv(3)
   A1     1      1       1
   A2     1      1      -1
    E     2     -1       0

crystod.group.format_product_report(algebra, labels)[source]#

Text report of a space-group direct product.

Exactly what crystod-group --product IRREP... --sg SG prints: the space group, the k points and star sizes involved, the decomposition line, a dimension check (star size times small dimension on both sides) and the DIRPRO cross-validation reference.

Parameters:

algebra (SpaceGroupIrrepAlgebra) – The SpaceGroupIrrepAlgebra of the space group.
labels (list[str]) – ISO-IR labels of the factors, e.g. ["R4-", "R5+"].

Returns:

The report as one string (no trailing newline).

Raises:

SystemExit – A label is not tabulated for this space group (ValueError when called through crystod.group).

Return type:

str

Example

>>> from crystod import group
>>> algebra = group.SpaceGroupIrrepAlgebra("Pm-3m")
>>> print(group.format_product_report(algebra, ["R4-", "R5+"]))
* Space group *
Pm-3m (No. 221)

* K points (primitive basis) *
R: (1/2, 1/2, 1/2)   star of 1 arm(s)
GM: (0, 0, 0)   star of 1 arm(s)

* Direct product (full space-group irreps) *
R4- x R5+ = GM2- + GM3- + GM4- + GM5-
...

crystod.group.format_spacegroup_table(space_group_symbol, kpoint)[source]#

Character table of the little group of k for a space group.

What crystod-group --table --sg SG --kpoint KX KY KZ prints: the space-group analogue of the point-group character table, with the Seitz symbols of the little-group operations as columns and ISO-IR (ISOTROPY, Miller-Love) labels for the small irreps, both at tabulated k points and on symmetry lines, planes and general points (computed with spgrep and labeled from the bundled ISO-IR tables).

Parameters:

space_group_symbol (str) – International symbol in the standard setting ("Pm-3m") or space-group number ("221").
kpoint (list[float]) – k point in the primitive basis, e.g. [0.5, 0.5, 0.5].

Returns:

The table as one string.

Raises:

SystemExit – Unknown space group (ValueError when called through crystod.group).

Return type:

str

Example

>>> from crystod import group
>>> print(group.format_spacegroup_table("Pm-3m", [0.5, 0.5, 0.5]))

* Space group *
Pm-3m (221)

* k-point (primitive) *
 R [0.5, 0.5, 0.5]

* IrRep Table *
little group: Pm-3m (221)
table:
               irrep  1  2_100  2_010  2_001  3^+_111 ...
 irrep_1(1) = R1+(1)  1      1      1      1        1 ...
...

crystod.group.format_star_lines(arms, seitz_symbols=None, indent=' ')[source]#

Format the arms of a star as the report lines of crystod --star-of-k.

Parameters:

arms (list[dict]) – The list returned by compute_star().
seitz_symbols (list[str] | None) – Seitz symbols of all rotations, indexed like the rotations given to compute_star(); when present, each line names the coset-representative operation.
indent (str) – Text put in front of every line.

Returns:

One string per arm, "arm 1: k = [+0.5, +0.5, +0]" and so on, with "(representative: 2_001)" appended when symbols are given.

Return type:

list[str]

Example

>>> for line in salc.format_star_lines(arms):   # arms of compute_star
...     print(line)
 arm 1: k = [+0.5, +0.5, +0]
 arm 2: k = [+0.5, +0, +0.5]
 arm 3: k = [+0, +0.5, +0.5]

crystod.group.get_character_table(point_group)[source]#

Character table of a crystallographic point group (phonopy data).

The table every point-group mode of crystod-group starts from (--table, --decompose, --ligand-field, --product --pg, --multiplet).

Parameters:: point_group (str) – Hermann-Mauguin point-group label as used by phonopy, e.g. "m-3m", "4/mmm", "3m".
Returns:: The phonopy character-table dict with the keys "rotation_list" (class labels in order), "character_table" ({irrep: characters per class}) and "mapping_table" ({class label: rotation matrices}, whose lengths are the class sizes).
Raises:: SystemExit – Unknown point-group label; the message lists the available labels (ValueError when called through crystod.group).
Return type:: dict

Example

>>> from crystod import group
>>> ct = group.get_character_table("m-3m")
>>> ct["rotation_list"]
('E', 'C3', 'C2', 'C4', 'C4^2', 'i', 'S4', 'S6', 'sgh', 'sgd')
>>> ct["character_table"]["T2g"]
(3, 0, 1, -1, -1, 3, -1, 0, -1, 1)

crystod.group.get_isoir_label_map(sgnum, cell, symprec, kpoint, little_rotations, little_translations, spgrep_characters)[source]#

Label spgrep small irreps at a k point with ISO-IR labels.

One-stop entry point shared by every labeling path of CrystOD (crystal orbitals, orbital hybridization, spin bases, phonons): builds (and caches) the IsoIRLabeler of the cell and calls its label_characters. Never raises: any failure yields None so that callers can fall back to generic labels.

Parameters:

sgnum (int) – Space-group number (1-230).
cell – Primitive cell as an spglib tuple (lattice, scaled_positions, numbers) whose operations feed spgrep.
symprec (float) – Symmetry tolerance for spglib.
kpoint – k vector in the primitive reciprocal basis.
little_rotations – Rotations of the little group of k in the primitive basis.
little_translations – Their fractional translations.
spgrep_characters – One character vector per spgrep irrep, aligned with the little-group operations (phase convention exp(-2 pi i k.t)).

Returns:

({spgrep irrep index: label}, k-type label) such as ({0: "Q1"}, "Q"), or None when the ISO-IR data are unavailable or no consistent assignment exists.

Return type:

tuple[dict[int, str], str] | None

crystod.group.get_orbital_characters(orbital, character_table)[source]#

Characters of the (2l+1)-dimensional representation of an atomic orbital.

The reducible representation that crystod-group --ligand-field ORB --pg PG decomposes into irreps (the crystal-field / ligand-field splitting of the orbital). Uses the angular-momentum character formulas chi(C(a)) = sin((l+1/2)a)/sin(a/2), chi(S(a)) = cos((l+1/2)a)/cos(a/2), chi(E) = 2l+1, chi(i) = (-1)^l (2l+1) and chi(sigma) = 1.

Parameters:

orbital (str) – Orbital letter, one of s, p, d, f, g, h, i (ORBITAL_AZIMUTHAL_NUMBER maps it to l).
character_table (dict) – Table from crystod.group.get_character_table.

Returns:

{class label: character} in the order of character_table["rotation_list"]; pass list(result.values()) to crystod.group.decompose for the splitting.

Raises:

KeyError – Unknown orbital letter.
ValueError – A class label the formulas do not recognize.

Return type:

dict[str, int]

Example

>>> from crystod import group
>>> ct = group.get_character_table("m-3m")
>>> chi = group.get_orbital_characters("d", ct)
>>> sizes = [len(ops) for ops in ct["mapping_table"].values()]
>>> counts = group.decompose(list(chi.values()), ct, sizes)
>>> {name: n for name, n in counts.items() if n}
{'Eg': 1, 'T2g': 1}

crystod.group.ground_state(results, reference)[source]#

Lowest term(s) of a configuration at the reference parameter point.

The Ground-state Term Symbol block of crystod-group --multiplet --orbital.

Parameters:

results – The TermEnergy list from compute_term_energies.
reference – The reference parameter values from the same call.

Returns:

the TermEnergy entries with the lowest energy at the reference point, and whether that ordering is provably independent of the parameters (True when a unique linear winner has coefficients no larger than those of every other linear term in every parameter beyond the first).

Return type:

(winners, unconditional)

Example

>>> from crystod import group
>>> from crystod.multiplet import _GroupClasses
>>> ct = group.get_character_table("m-3m")
>>> classes = _GroupClasses(ct)
>>> terms = group.shell_terms(classes, "T2g", 3)
>>> params, energies, reference, note = group.compute_term_energies(
...     ct, 2, [("T2g", 3)], terms)
>>> winners, unconditional = group.ground_state(energies, reference)
>>> [(str(w.spin), w.irrep) for w in winners], unconditional
([('3/2', 'A2g')], True)

crystod.group.hund_candidates(classes, terms)[source]#

Hund’s-rule ground-state candidates among the terms.

The Ground-state Term Symbol (Hund's rules) block of crystod-group --multiplet without --orbital: maximal 2S+1 first, then maximal orbital dimension.

Parameters:

classes (_GroupClasses) – Conjugacy classes of the point group (see shell_terms).
terms (list[tuple[Fraction, str, int]]) – Terms (S, irrep, count) from shell_terms or couple_shells.

Returns:

The candidate terms (more than one when the rules tie); the exact ordering needs the Coulomb energies of crystod.group.compute_term_energies.

Return type:

list[tuple[Fraction, str, int]]

crystod.group.isotropy_subgroups(space_group, irrep, order_parameter=None, *, with_settings=True)[source]#

Isotropy subgroups of a space-group irrep, as data.

Programmatic counterpart of crystod-group --parent: the order-parameter directions of the irrep (or of the coupled order parameter of several irreps) are enumerated with crystod.group.IsotropyAnalyzer, and each direction is returned with the space group it condenses into. No phonopy object is needed; the function is also exported as crystod.group.isotropy_subgroups.

Parameters:

space_group (str | int) – International short symbol (e.g. "Pm-3m") or number (e.g. 221) of the parent.
irrep (str | list[str]) – ISO-IR irrep label (e.g. "R4+"); a list of labels enumerates the subgroups of the coupled order parameter.
order_parameter (list[str] | None) – If given (e.g. ["a", "0", "0"]), resolve only this direction and return a single-element list. Components are plain numbers or parameter names; composite entries of the enumerated table such as "0.282a" are rejected.
with_settings (bool) – Also compute the conventional basis/origin of each subgroup in the parent convention (slightly slower; on by default).

Returns:

List of IsotropySubgroup, sorted like the --parent table (free components, index, subgroup number).

Raises:

ValueError – For an unknown space group, an irrep that is not tabulated for it (the labels of symmetry lines and planes, e.g. DT5, have no isotropy subgroups in the tables), or an invalid order parameter.

Example

>>> from crystod import phonon
>>> for sub in phonon.isotropy_subgroups("Pm-3m", "R4+"):
...     print(sub)
R4+(0,0,a) -> I4/mcm (No. 140), size 2, index 6
R4+(a,a,a) -> R-3c (No. 167), size 2, index 8
R4+(0,a,a) -> Imma (No. 74), size 2, index 12
R4+(0,a,b) -> C2/m (No. 12), size 2, index 24
R4+(a,a,b) -> C2/c (No. 15), size 2, index 24
R4+(a,b,c) -> P-1 (No. 2), size 2, index 48
>>> sub = phonon.isotropy_subgroups(221, "R4+", ["0", "0", "a"])[0]
>>> sub.symbol, sub.basis.tolist()
('I4/mcm', [[-1.0, 0.0, 1.0], [1.0, 0.0, 1.0], [0.0, 2.0, 0.0]])

crystod.group.load_isoir_irreps(sgnum, kind='cir', data_dir=None)[source]#

Parse all irreps of one space group from an ISO-IR data file.

Direct access to the tables behind every ISO-IR label that CrystOD prints: for each irrep the full space-group matrices over the coset representatives of the ISOTROPY standard setting, the (parametrized) k vectors of every star arm, and the operator translations. Results are cached per (file, space group).

Parameters:

sgnum (int) – Space-group number (1-230).
kind (str) – "cir" for the complex irreps (CIR_data, bundled with the package) or "pir" for the physically irreducible ones (PIR_data, not bundled).
data_dir (Path | None) – Directory holding the data file; by default the lookup order of find_isoir_data_dir (CRYSTOD_ISOIR_PATH, the package directory, <repository root>/ISOTROPY).

Returns:

One IsoIrrep record per irrep, in table order, with label ("GM4-", "DT5", …), dim (full dimension), narms, small_dim, ktype, num_free_params, the arrays kvecs, rotations, translations, irtrans and matrices, and the methods arm_k, match_k, small_character and in_little_group.

Raises:

ValueError – kind is neither "cir" nor "pir", or the file is malformed.
FileNotFoundError – No data directory or data file found.

Return type:

list[IsoIrrep]

Example

>>> from crystod import group
>>> irreps = group.load_isoir_irreps(221)
>>> len(irreps)
72
>>> [ir.label for ir in irreps if ir.ktype == "R"]
['R1+', 'R2+', 'R3+', 'R4+', 'R5+', 'R1-', 'R2-', 'R3-', 'R4-', 'R5-']

crystod.group.parse_config(tokens, classes)[source]#

Parse shell tokens into (irrep, n_electrons) pairs.

The argument parser of crystod-group --multiplet: accepts IRREP^N, (IRREP)^N, the quoting-free IRREPN (T2g2; an unquoted ^ is a glob character in zsh) and a bare IRREP for one electron.

Parameters:

tokens (list[str]) – Shell tokens, e.g. ["T2g2", "Eg1"].
classes (_GroupClasses) – Conjugacy classes of the point group (see shell_terms); its table supplies the valid irrep labels.

Returns:

[(irrep, n_electrons), ...] in input order.

Raises:

SystemExit – A token names no irrep of the point group, or is ambiguous (ValueError when called through crystod.group).

Return type:

list[tuple[str, int]]

Example

>>> from crystod import group
>>> from crystod.multiplet import _GroupClasses
>>> classes = _GroupClasses(group.get_character_table("m-3m"))
>>> group.parse_config(["T2g2", "Eg"], classes)
[('T2g', 2), ('Eg', 1)]

crystod.group.poscar_lines(lattice_matrix, positions, atomic_numbers)[source]#

POSCAR content of a cell, as lines.

The writer behind crystod-group --cif2poscar: the crystod test-file style (six decimals, direct coordinates, element tag on every coordinate line, species grouped by first appearance).

Parameters:

lattice_matrix – Lattice vectors as rows, Angstrom, shape (3, 3).
positions – Fractional coordinates, shape (n_atoms, 3).
atomic_numbers – Atomic number of every atom.

Returns:

The POSCAR lines without line terminators, the last one empty (so that joining with newlines ends the file with a newline).

Return type:

list[str]

Example

>>> from crystod import group
>>> lines = group.poscar_lines([[4, 0, 0], [0, 4, 0], [0, 0, 4]],
...                            [[0, 0, 0], [0.5, 0.5, 0.5]], [55, 17])
>>> lines[:2] + lines[5:8]
['Cs1 Cl1', '1.0', 'Cs Cl', '1 1', 'direct']
>>> lines[8:]
['0.000000 0.000000 0.000000 Cs', '0.500000 0.500000 0.500000 Cl', '']

crystod.group.resolve_kpoint_input(structure, raw_kpoint)[source]#

Resolve a --kpoint argument into a label and primitive coordinates.

The two command-line spellings of a k point – one high-symmetry label such as GM/X/M/R, or three primitive reciprocal coordinates (fractions such as 1/2 allowed) – become (label, coordinates) with the seekpath labels of the structure: coordinates that hit a special point (or an arm of its star) receive that point’s name, any other point the ISO-IR k-vector type letters (GP for a general point). This is what crystod --star-of-k and crystod --visualize do with --kpoint. When the label lookup itself fails (seekpath unavailable), three coordinates are still accepted and labelled custom.

Parameters:

structure (SymmetryOnlyVibrations) – A SymmetryOnlyVibrations of the cell, or a subclass such as SymmetryAdaptedOrbitalBasis; its resolve_qpoint does the work.
raw_kpoint (list[str]) – The tokens as typed: ["M"] or ["1/2", "1/2", "0"].

Returns:

the k-point name and its three primitive reciprocal coordinates as floats.

Return type:

(label, kpoint)

Raises:

ValueError – An unknown label, or a token count that is neither one nor three (a ValueError from the implementation module as well as through crystod.salc).

Example

>>> from phonopy.interface.calculator import read_crystal_structure
>>> from crystod import salc
>>> from crystod.examples import example_path
>>> cell, _ = read_crystal_structure(
...     str(example_path("221_PPOSCAR_ScF3")), interface_mode="vasp")
>>> basis = salc.SymmetryAdaptedOrbitalBasis(cell=cell)
>>> salc.resolve_kpoint_input(basis, ["M"])
('M', [0.5, 0.5, 0.0])
>>> salc.resolve_kpoint_input(basis, ["1/2", "1/2", "0"])
('M', [0.5, 0.5, 0.0])

crystod.group.shell_terms(classes, irrep, n_electrons)[source]#

Pauli-allowed terms of n equivalent electrons in one irrep shell.

The single-shell step of crystod-group --multiplet IRREP^N --pg PG: for every total spin S = n/2, n/2 - 1, ... the orbital part transforms as the Schur functor of the two-column partition, whose characters follow from the Frobenius formula with Murnaghan-Nakayama symmetric-group characters; each is reduced into point-group irreps.

Parameters:

classes (_GroupClasses) – Conjugacy classes of the point group, built as crystod.multiplet._GroupClasses(character_table) from the table of crystod.group.get_character_table (the same object that parse_config takes).
irrep (str) – Label of the shell irrep, e.g. "T2g".
n_electrons (int) – Number of electrons in the shell, 1 to twice the irrep dimension.

Returns:

Terms as (S, irrep, count) with the total spin S a Fraction (2S+1 is the multiplicity of the term symbol) and count the number of times the term occurs.

Raises:

SystemExit – n_electrons outside 1 .. 2 * dim (ValueError when called through crystod.group).

Return type:

list[tuple[Fraction, str, int]]

Example

>>> from crystod import group
>>> from crystod.multiplet import _GroupClasses
>>> classes = _GroupClasses(group.get_character_table("m-3m"))
>>> for spin, irrep, count in group.shell_terms(classes, "T2g", 2):
...     print(f"^{int(2 * spin + 1)}{irrep}", count)
^3T1g 1
^1A1g 1
^1Eg 1
^1T2g 1

crystod.group

Contents

crystod.group#