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--productreport as text.
Isotropy subgroups (crystod-group --parent):
isotropy_subgroups– subgroups of an irrep (or of coupled irreps) asIsotropySubgrouprecords: the data-level entry point.isotropy_subgroups_at_kpoint– the same for every irrep of one special k point (--parent SG --kpoint K), as aKpointIsotropySubgroupsmapping from irrep label to records.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.find_isotropy_irreps– the reverse lookup (--parent G --child H): every special-point irrep stratum whose isotropy subgroup has type H, asIsotropyMatchrecords.find_coupled_isotropy_irreps– the coupled reverse lookup (--child H --coupled): the pairs of irreps and directions whose coupled isotropy subgroup has type H, asCoupledIsotropyMatchrecords.isotropy_table– every stratum of every special-point irrep of a parent with its setting, as anIsotropyTable(cached on disk below$CRYSTOD_CACHE_DIRor~/.cache/crystod).subgroup_graph– the group-subgroup graph of the isotropy subgroups of one irrep or of a direct sum (--parent SG --irrep IR [IR2 ...] --graph), as aSubgroupGraphofGraphNodeandGraphEdgerecords.
Invariant polynomials (crystod-group --parent SG --irrep IR --invariants):
invariant_polynomials– the invariant polynomials (Landau free-energy terms) of an irrep degree by degree, as anInvariantBasis, checked against the Molien series.landau_lifshitz– the Landau (no cubic invariant) and Lifshitz conditions of an irrep, as aLandauLifshitzrecord.coupling_terms– the lowest-order coupling term of a direct sum of irreps (e.g. the trilinearQ1 Q2 Pof hybrid improper ferroelectrics), as aCouplingTerm.secondary_order_parameters– the irreps with a nonzero component fixed by the isotropy subgroup of a given order-parameter direction (--secondary), asSecondaryOrderParameterrecords.
Correlation of irreps (crystod-group --correlate):
correlation_table– the irreps of a point group restricted to every inequivalent orientation of a subgroup type (--correlate --pg G --subgroup H), as aCorrelationTable;format_correlation_tablerenders it.subgroup_correlation– for every special k point of the space group G of a supergroup structure, the small irreps of the space group H of a subgroup structure that every irrep of G becomes (--correlate --supergroup-poscar P --subgroup-poscar C, the counterpart of DCORREL), as aSubgroupCorrelationofKpointCorrelationblocks ofIrrepCorrelationrows;format_subgroup_correlationrenders them.compatibility_relations– the small irreps of two special points restricted to the symmetry line joining them (--correlate-kpath --sg), asCompatibilityrecords;format_compatibilityrenders them.spin_orbit_relations– the double-valued (spinor) small irreps that each single-valued small irrep at k becomes with spin-orbit coupling, Gamma x D(1/2) (--correlate-double-group --sg), asSpinOrbitRelationrecords;format_spin_orbit_relationsrenders them.
Symmetry-mode analysis (crystod-group --supergroup-cif):
SymmetryModeAnalysis– AMPLIMODES-style decomposition of the distortion between a parent and a child structure into parent irreps.
Property tensors (crystod-group --tensor):
tensor_form– the symmetry-allowed form of a property tensor (Neumann’s principle) in a point group, a space group’s point group or a structure’s point group, by name (dielectric,piezoelectric,elastic, …) or Jahn symbol, as aTensorForm(independent components, matrix form, relations);format_tensor_formrenders it.raman_forms– the Raman tensors of every Raman-active irrep of a point group (Mulliken labels).
Response tensors of a VASP run (crystod --check-symmetry):
vasp_symmetry_report– the Born effective charges, dielectric, piezoelectric (e), elastic and internal-strain tensors of avasprun.xml/OUTCARprojected onto their symmetry-allowed forms, as aVaspSymmetryReport(independent components raw and symmetrized, residuals, sum rules);format_vasp_symmetryrenders it.symmetrize_tensor– the group average of any tensor (or of one tensor per atom) over the point group, a site-symmetry group or the space group of a structure.
Point-group tools (--table, --decompose, --product --pg,
--ligand-field):
get_character_table– phonopy character table of a point group;format_irrep_tablerenders it.decompose,decompose_representation– reduce a character vector into irreps;direct_product_charactermultiplies irreps.symmetric_square,antisymmetric_square– the squares[IR x IR]and{IR x IR}(--product IR IR --symmetric);jahn_teller_modes– Jahn-Teller active modes and symmetry-allowed pseudo-Jahn-Teller coupling modes as aJahnTellerModesrecord (--jahn-teller). The space-group squares areSpaceGroupIrrepAlgebra.decompose_square.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.list_space_group_settings– every axis setting (Hall symbol) of the space group of a cell with the cell’s lattice parameters in it (--cif-axis), as aSettingTableofSpaceGroupSettingrecords;resolve_settingpicks one by symbol, No. or choice andtransform_to_settingreturns its conventional cell (--cif2poscar --spacegroup-set).
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_irrepsreads 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.Compatibility(k0_label, k0_irrep, line_label, line_irreps, dimension=0, k_point=(), k_delta=(), fixed_dimension=1)[source]#
Bases:
objectA small irrep at a special point restricted to a symmetry line.
- Variables:
k0_label (str) – Name of the special point (
GM,X, …).k0_irrep (str) – ISO-IR label of the small irrep at that point.
line_label (str) – ISO-IR name of the line (
DT,SM, …).line_irreps (list) – The small irreps on the line, as
(ISO-IR label, multiplicity)pairs.dimension (int) – Dimension of the small irrep at the point.
k_point (tuple) – The arm of the point the line starts from, primitive basis, as
Fractionvalues.k_delta (tuple) – The point of the line at which the line irreps are labeled, primitive basis, as
Fractionvalues.fixed_dimension (int) – Dimension of the k subspace fixed by the little co-group of
k_delta: 1 for a symmetry line, 2 for a symmetry plane, 3 for a general point (possible only when two points are given that no line joins).
- dimension: int = 0#
- fixed_dimension: int = 1#
- k0_irrep: str#
- k0_label: str#
- k_delta: tuple = ()#
- k_point: tuple = ()#
- line_irreps: list#
- line_label: str#
- class crystod.group.CorrelationTable(parent, subgroup, orientations, rows, conjugates=<factory>, settings=<factory>, axes=<factory>, parent_order=0, subgroup_order=0, hexagonal_axes=False)[source]#
Bases:
objectThe correlation table of a point group G and one subgroup type H.
- Variables:
parent (str) – The point group G (phonopy’s symbol, e.g.
"m-3m").subgroup (str) – The subgroup type H (
"4/mmm").orientations (list) – One
(description, rotations)pair per conjugacy class of subgroups of type H in G (the inequivalent orientations): the column header ("4/mmm (4 || z)") and the rotation matrices of the representative subgroup, in the axes of the table of G, as an(|H|, 3, 3)integer array.rows (dict) –
{irrep of G: decompositions}in the order of the table of G, with one decomposition per orientation: a list of(Mulliken symbol of H, multiplicity)pairs in the order of the table of H. A complex-conjugate pair that phonopy’s table merges into one realEkeeps that symbol.conjugates (list) – Number of subgroups conjugate to each representative.
settings (list) – The setting of phonopy’s table of H each orientation is labeled with (
"-4m2";""for the groups with one setting).axes (list) – Per orientation, the classes of H that fix its orientation about the principal axis, with their elements in the axes of G (
"C2' = 2_x, 2_y; C2'' = 2_[110], 2_[1-10]"); the symbols B1/B2/B3 refer to them.parent_order (int) – Order of G.
subgroup_order (int) – Order of H.
hexagonal_axes (bool) –
Truewhen the table of G uses hexagonal axes (trigonal and hexagonal G): directions are then[uvw]in those axes, otherwisex/y/zalong the cell axes.
- axes: list#
- conjugates: list#
- hexagonal_axes: bool = False#
- orientations: list#
- parent: str#
- parent_order: int = 0#
- rows: dict#
- settings: list#
- subgroup: str#
- subgroup_order: int = 0#
- class crystod.group.CoupledIsotropyMatch(label1, kname1, direction1, label2, kname2, direction2, number, symbol, size, index, basis=None, origin=None, vector=None, projector=None)[source]#
Bases:
objectOne answer of the coupled reverse lookup: two irreps giving type H.
A coupled stratum of the direct sum of two irreps (both amplitudes nonzero) whose isotropy subgroup has type H, where neither irrep alone (with the other one as a secondary order parameter) has that isotropy subgroup.
- Variables:
label1 (str) – ISO-IR label of the first irrep (table order), e.g.
"R4+".kname1 (str) – Its special k point.
direction1 (str) – Its part of the direction, e.g.
"(0,a,a)".label2 (str) – Label of the second irrep, e.g.
"M3+".kname2 (str) – Its special k point.
direction2 (str) – Its part of the direction, e.g.
"(d;0;0)"(the letters continue after those of the first irrep, as incrystod-group --parent SG --irrep IR1 IR2).number (int) – Space-group number of the isotropy subgroup (H, or its enantiomorphic partner).
symbol (str) – Its international short symbol.
size (int) – Primitive-cell multiplication relative to the parent.
index (int) – Index of the subgroup in the parent.
basis (numpy.ndarray | None) – Conventional basis of the subgroup (rows, parent conventional units), or
None.origin (numpy.ndarray | None) – Origin of the subgroup cell (parent conventional coordinates), or
None.vector (numpy.ndarray | None) – A generic order-parameter vector of the stratum (the first irrep’s components, then the second’s).
projector (numpy.ndarray | None) – The orthogonal projector onto the stratum subspace in the direct sum.
- basis: ndarray | None = None#
- property direction: str#
The coupled direction, e.g.
"R4+(0,a,a) M3+(d;0;0)".
- direction1: str#
- direction2: str#
- index: int#
- kname1: str#
- kname2: str#
- label1: str#
- label2: str#
- number: int#
- origin: ndarray | None = None#
- projector: ndarray | None = None#
- property same_k: bool#
Truewhen both irreps belong to the same special k point.
- size: int#
- symbol: str#
- vector: ndarray | None = None#
- class crystod.group.CoupledRepresentation(algebra, irrep_labels)[source]#
Bases:
objectDirect 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 whatcrystod-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
SpaceGroupIrrepAlgebraof the space group.irrep_labels (list[str]) – ISO-IR labels of the coupled irreps, e.g.
["X3-", "X2+"].
- Variables:
parts – The
InducedRepresentationof every irrep, in input order.dims – Dimension of every part;
dimensionis 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.
- classmethod from_parts(algebra, parts)[source]#
Direct sum of already-built representations.
- Parameters:
algebra (SpaceGroupIrrepAlgebra) – The
SpaceGroupIrrepAlgebrathe parts were built from.parts (list) –
InducedRepresentationobjects (or anything withelements,dimension,grid_nandlabel).
- Returns:
A
CoupledRepresentationidentical to the one built from the parts’ labels (InducedRepresentationis deterministic).
- image_elements()[source]#
All group elements of the coupled representation.
- Returns:
The
elementslist of(i, t, matrix)triples.
- property rep_cache: _RepCache#
The element matrices as arrays (built on first use, then kept).
- class crystod.group.CouplingTerm(multidegree, polynomials, trilinear=False)[source]#
Bases:
objectLowest-order coupling term of a direct sum of irreps.
A coupling term is an invariant whose multidegree has every entry at least 1, i.e. one that involves the components of every part.
- Variables:
multidegree (tuple) – Degree in the variables of every part, e.g.
(1, 1, 1)for a trilinear term.polynomials (list) – Every invariant of that multidegree (products of lower-degree invariants first, then the new ones), as
InvariantPolynomialrecords; their number is the Molien count of the multidegree.trilinear (bool) –
Truewhen the multidegree is(1, 1, ..., 1)(for three parts, the hybrid-improper termQ1 Q2 P).
- multidegree: tuple#
- polynomials: list#
- trilinear: bool = False#
- class crystod.group.GraphEdge(parent, child, dashed=False, index_ratio=1)[source]#
Bases:
objectOne edge of the graph:
childis a maximal subgroup ofparentamong the nodes (up to conjugacy in the parent space group).- Variables:
parent (int) –
idof the larger group.child (int) –
idof the subgroup.dashed (bool) –
Truefor an edge from the parent whose primary irrep violates the Landau or the Lifshitz condition (or that needs several irreps), so that the transition cannot be continuous.index_ratio (int) –
index(child) / index(parent).
- child: int#
- dashed: bool = False#
- index_ratio: int = 1#
- parent: int#
- class crystod.group.GraphNode(id, kind, number, symbol, size, index, direction='', n_free=0, irreps=(), primary=(), basis=None, origin=None, projector=None)[source]#
Bases:
objectOne node of the group-subgroup graph.
- Variables:
id (int) – Position of the node in
SubgroupGraph.nodes(0-based; the command line prints it 1-based).kind (str) –
"parent"(the root),"stratum", or"kernel"(the stratum of the generic order parameter, the bottom of the graph).number (int) – Space-group number of the (isotropy) subgroup.
symbol (str) – Its international short symbol.
size (int) – Primitive-cell multiplication relative to the parent.
index (int) – Index of the subgroup in the parent.
direction (str) – Order-parameter direction with the labels of the condensing irreps, e.g.
"R4+(0,a,a) M3+(d;0;0)";""for the parent.n_free (int) – Number of free order-parameter parameters.
irreps (tuple) – Labels of the irreps that condense (nonzero amplitude).
primary (tuple) – Labels of the irreps whose amplitude alone already has this isotropy subgroup (the others are secondary); empty when the stratum needs several irreps at once.
basis (numpy.ndarray | None) – Conventional basis of the subgroup (rows, parent conventional units), or
None.origin (numpy.ndarray | None) – Origin of the subgroup cell (parent conventional coordinates), or
None.projector (numpy.ndarray | None) – Orthogonal projector onto the fixed space of the subgroup in the representation (zero for the parent).
- basis: ndarray | None = None#
- direction: str = ''#
- id: int#
- index: int#
- irreps: tuple = ()#
- kind: str#
- property label: str#
"I4/mcm (140)".
- n_free: int = 0#
- number: int#
- origin: ndarray | None = None#
- primary: tuple = ()#
- projector: ndarray | None = None#
- size: int#
- symbol: str#
- class crystod.group.InducedRepresentation(algebra, irrep_label)[source]#
Bases:
objectFull (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(throughIsotropyAnalyzer) and by the symmetry-mode analysis. The basis index is(arm a, small-irrep row p)and the group elements are parametrized as (coset representativei, lattice translationt):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 asP1P2).- Parameters:
algebra (SpaceGroupIrrepAlgebra) – The
SpaceGroupIrrepAlgebraof the space group.irrep_label (str) – ISO-IR irrep label, e.g.
"R4+", or the pair label of a complex-type irrep as the tables print it ("H1H2","P1PA1"): an alias of the doubled real form, built from the member listed first in the ISO-IR tables (the member the--kpointtable builds the pair from).
- Variables:
algebra – The algebra the representation was built from.
irrep – The tabulated irrep record (
name,dim,kpname); for a pair label, the record of the member it was built from.k – k vector of the irrep (primitive basis, units of
1/DEN).arms – Star arms, shape
(n_arms, 3);representativesholds 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_iof the coset representatives, before realification.elements – All distinct group elements as
(i, t, matrix)with the real matrix ofD(g_i + t);truns over the translation grid of periodgrid_n.doubled –
Truewhen the physically irreducible form isD + D*;fs_typethen 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, a pair label whose two members are not complex-conjugate partners, 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 the other tabulated irrep with the same physically irreducible real form
D + D*, i.e. the same real part of the character on every group element, lattice translations included. (The characters of the coset representatives alone do not decide it: at H of P6_3/m, P of I4/mcm or K of P3 several irreps share them and differ only on the translations.)- Returns:
The partner label, or
Nonewhen 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
elementslist, 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 ofblocks.- 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.
- property rep_cache: _RepCache#
The element matrices as arrays (built on first use, then kept).
- class crystod.group.InvariantBasis(variables, parts, degrees, counts, polynomials, products, labels=<factory>, arm_chunks=<factory>, multidegree_counts=<factory>)[source]#
Bases:
objectInvariant polynomials of a representation, degree by degree.
- Variables:
variables (list) – Names of the order-parameter components (
Q1, … for one irrep;<label>_<n>for a direct sum).parts (list) – Dimension of every block of the representation.
degrees (list) – The total degrees computed (1 .. the requested degree).
counts (dict) – Number of linearly independent invariants of every total degree (the Molien count, equal to the nullspace dimension).
polynomials (dict) – For every total degree, the new invariants (not products of lower-degree ones) as
InvariantPolynomial.products (dict) – For every total degree, the independent products of lower-degree invariants that complete the basis.
labels (list) – Irrep label of every part (empty for a bare matrix group).
arm_chunks (list) – Components per star arm of every part (for the direction-pattern letters).
multidegree_counts (dict) – Molien count of every multidegree.
- arm_chunks: list#
- counts: dict#
- degrees: list#
- labels: list#
- multidegree_counts: dict#
- parts: list#
- polynomials: dict#
- products: dict#
- variables: list#
- class crystod.group.IrrepCorrelation(parent_irrep, parent_dim, arms_merged, child_irreps, mulliken=<factory>, parent_mulliken=None, double_valued=False)[source]#
Bases:
objectOne irrep of the supergroup G and the irreps of the subgroup H it becomes.
One row of
crystod-group --correlate --supergroup-poscar P --subgroup-poscar C: the components of the parent irrep that belong to one arm of a k star of H, decomposed into the small irreps of H there.- Variables:
parent_irrep (str) – ISO-IR label of the parent irrep (
R4+; the pair label of a complex-type irrep,GM2+GM3+; on a symmetry line the ISO-IR line label,LD1).parent_dim (int) – Dimension of the parent small irrep (doubled for a complex- or pseudoreal-type pair), i.e. the components of one parent arm.
arms_merged (int) – Number of parent arms that fall onto one arm of H (the
m xprefix of the printed row; 1 when nothing merges).child_irreps (list) – The small irreps of H at that arm, as
(ISO-IR label, multiplicity, dimension); a complex-conjugate pair of equal multiplicity is one term with the pair label and the dimension of the pair.mulliken (dict) –
{label: Mulliken symbol}of the Gamma irreps of H amongchild_irreps(empty away from Gamma).parent_mulliken (str | None) – Mulliken symbol of the parent irrep at Gamma, or None.
double_valued (bool) –
Truefor a row of double-valued (spinor) irreps (--spinor): the names ofcrystod --spinoron both sides (-R8+), a time-reversal pair asA/Band an irrep doubled by time reversal asA/A, with the dimension of the pair.
- arms_merged: int#
- child_irreps: list#
- double_valued: bool = False#
- mulliken: dict#
- parent_dim: int#
- parent_irrep: str#
- parent_mulliken: str | None = None#
- class crystod.group.IsoIRLabeler(sgnum, transformation_matrix=None, origin_shift=None, cell=None, symprec=1e-05)[source]#
Bases:
objectLabel 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 conventionexp(+2 pi i k.t)and spgrepexp(-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
Pinto the ISO-IR setting (x_conventional = P x_primitive + origin_shift); give it together withorigin_shiftwhencellis 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
cellis given.
- Variables:
sgnum – The space-group number.
P – The transformation matrix into the ISO-IR setting;
Pinvits inverse andorigin_shiftthe accompanying shift.irreps – The
IsoIrreprecords of the space group, fromload_isoir_irreps.
- Raises:
ValueError – spglib could not standardize
cellto 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^-1as 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), ...]withR_c = P R P^-1andt_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. As in
label_characters, the -k partner of a tabulated star gets ISOTROPY’s partner names (PA1, LE1).- 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), orNonewhen 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)orNonewhen no consistent decomposition exists.- Return type:
list[tuple[list[tuple[str, int, int]], str] | None]
- kpoint_name(k_primitive, minus_k=True)[source]#
Most specific ISO-IR k-vector type label containing a k point.
- Parameters:
k_primitive – k vector in the primitive reciprocal basis.
minus_k (bool) – Name a point whose -k partner is tabulated more specifically by the partner’s name (
"PA", seeminus_k_type).
- Returns:
The type label with the fewest free parameters, e.g.
"T"for(1/2, 1/2, 0.4)in Pm-3m;Nonewhen no entry matches.- Return type:
str | None
- label_characters(k_primitive, little_rotations, little_translations, spgrep_characters, atol=1e-05, minus_k=True)[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.
minus_k (bool) – When k has no assignment, label it through -k: the small irreps at k are the complex conjugates of those at -k, and only one star of such a pair is tabulated (P of I-4, not PA). The labels then carry ISOTROPY’s partner name (
"PA1"is the conjugate of"P1"). The -k partner of a line, plane or general point is named that way in any case ("LE1"for the conjugate of"LD1";_minus_side).
- Returns:
({spgrep irrep index: ISO-IR label}, k-type label), e.g.({0: "R1+", ...}, "R"), orNonewhen no consistent assignment exists.- Return type:
tuple[dict[int, str], str] | None
- representative_k(k_primitive, little_rotations, little_translations, spgrep_characters, atol=1e-05, minus_k=True)[source]#
The representative arm of the tabulated star whose irreps name k.
The search is that of
label_characters()(same families in the same order, same -k branches and checks); instead of the labels it returns the k vector of arm 0 of the family that matched, at the matched parameters – the arm the ISO-IR table lists first. k lies in the star of that vector, or, when the labels came from the complex conjugates of the tabulated irreps (the -k partner of a line, plane or general point,_minus_side, and a star tabulated only through -k), in the star of its negative; the irreps at -k0 are then the complex conjugates of those at k0, under the same index. A name that has to be the same on every arm of a star (the double-valued names ofcrystod.wavecar_irreps) is fixed at this vector and carried to k by conjugation.- 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 (phase convention
exp(-2 pi i k.t)).atol (float) – Tolerance of the character comparison.
minus_k (bool) – As in
label_characters().
- Returns:
arm 0 of the matched family in the primitive reciprocal basis (
arm_k(0, params) @ P), and whether k lies in the star of -k0 (the labels are conjugates);Nonewherelabel_characters()returnsNone.- Return type:
(k0_primitive, conjugate)
- class crystod.group.IsotropyAnalyzer(space_group, irrep_labels)[source]#
Bases:
objectIsotropy 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 functioncrystod.group.isotropy_subgroupsreturns the same results asIsotropySubgrouprecords; 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
SpaceGroupIrrepAlgebraof the parent space group.representation – The
InducedRepresentation(one label) orCoupledRepresentation(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
SpaceGroupIrrepAlgebrathe representation was built from.representation – An
InducedRepresentationorCoupledRepresentation(anything withimage_elements(),dimensionandgrid_n).
- Returns:
A new
IsotropyAnalyzersharing the algebra.
- canonical_projector(projector)[source]#
The representative of the group orbit of a subspace.
The images
g P g^Tof a subspace under the group are the domain-equivalent directions of one stratum; the representative is the image with the simplest direction label, the rule by whichenumerate_directionsnames every stratum (the row ofcrystod-group --parent SG --irrep IR). The decomposition of a structure (crystod-group --supergroup-cif) applies the same rule (_orbit_representative, on the orbits it has already built): it shows its largest mode with domain-equivalent directions on the representative, so that both commands print the same label for that stratum, and names the representative of every other mode’s stratum in a note when the domain shown puts the mode on another image.- Parameters:
projector (ndarray) – Orthogonal projector onto the subspace, shape
(dimension, dimension).- Returns:
The orthogonal projector onto the representative subspace (the input itself, up to rounding, when it is the representative).
- Return type:
ndarray
- 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);Nonewhen 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: its stabilizer is the group of elements fixing the whole subspace, and for coupled irreps the part of every irrep is generic in the same sense for that irrep’s share of the subspace (the(d;d;e)part ofL1+(a;a;b) L1-(d;d;e)has no extra symmetry of its own). The label depends on the subspace only, never on the vector.- Return type:
(label, generic)- Raises:
RuntimeError – No trial vector is generic (an internal error).
- enumerate_directions(method='fast')[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,canonical_projector). This is the listing ofcrystod-group --parentwithout--order-parameter.The default enumerator intersects every new subspace with the seeds only (every member of the closure is an intersection of seeds), with batched SVDs over the cached element matrices (
representation.rep_cache); the strata are then visited in the order in which the pairwise closure discovers them, so that the result, including the order and the representative of every stratum, equals that of the pairwise closure (method="legacy", kept for comparison).- Parameters:
method (str) –
"fast"(default) or"legacy"(the original pairwise closure, slower by a factor of 5-50 on large representations).- 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).- Raises:
ValueError – An unknown
method.
- fixed_space(members)[source]#
Common fixed subspace of a set of group elements.
- Parameters:
members –
(i, t)pairs as returned bystabilizer_of.- Returns:
An orthonormal basis of the fixed subspace as columns, shape
(dimension, n_free); the identity whenmembersis empty.- Return type:
ndarray
- resolve_direction(tokens)[source]#
Order parameter from
--order-parametertokens.- 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, an exact rational factor scales a parameter (2a,-0.5a,1/2a), and a component may be a sum of such terms (a+b-c-d,2a-1/2b), as the tables print them.- Returns:
A representative order-parameter vector of length
dimension: a generic point of the direction (its stabilizer fixes every parameter’s coefficient vector, see_generic_vector).- Raises:
SystemExit – Wrong number of components, an all-zero order parameter, a parameter factor that is a rounded decimal (
0.282a,-0.4g+0.917h: the tables print irrational factors as rounded decimals, and the rounded value is a different direction), or a component that cannot be read.- 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 (fromstabilizer_oforenumerate_directions).- Returns:
the spglib space-group type of the subgroup (
number,international_short, …), the primitive-cell multiplicationsize, the index of the subgroup in the parent, the sublattice basisB(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.IsotropyMatch(label, kname, direction, number, symbol, size, index, basis=None, origin=None)[source]#
Bases:
objectOne answer of the reverse lookup: an irrep stratum giving type H.
- Variables:
label (str) – ISO-IR label of the irrep, e.g.
"R4+".kname (str) – Its special k point, e.g.
"R".direction (str) – Order-parameter direction, e.g.
"(0,0,a)".number (int) – Space-group number of the isotropy subgroup (H, or its enantiomorphic partner).
symbol (str) – International short symbol of the subgroup.
size (int) – Primitive-cell multiplication relative to the parent.
index (int) – Index of the subgroup in the parent.
basis (numpy.ndarray | None) – Conventional basis of the subgroup (rows, parent conventional units), or
None.origin (numpy.ndarray | None) – Origin of the subgroup cell (parent conventional coordinates), or
None.
- basis: ndarray | None = None#
- direction: str#
- index: int#
- kname: str#
- label: str#
- number: int#
- origin: ndarray | None = None#
- size: int#
- symbol: str#
- class crystod.group.IsotropySubgroup(irrep, direction, label, number, symbol, size, index, n_free, basis=None, origin=None)[source]#
Bases:
objectOne isotropy subgroup of a space-group irrep.
One row of the
crystod-group --parenttable, as returned byisotropy_subgroups()and carried bycrystod.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;Nonewhen the setting could not be standardized orwith_settings=Falsewas passed.origin (numpy.ndarray | None) – Origin of that cell in parent conventional coordinates, or
Nonelikewise.
- 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.IsotropyTable(space_group, number, version, kpoints, irreps, strata, errors, sohncke=False, fingerprint='', cache_path=None, from_cache=False)[source]#
Bases:
objectEvery single-irrep stratum of a parent space group.
Returned by
isotropy_table().- Variables:
space_group (str) – International short symbol of the parent.
number (int) – Its number.
version (str) – The CrystOD version that built the table.
kpoints (dict) – Maps every special k-point name, in table order, to a dict with
coordinates(the tabulated arm, primitive reciprocal basis),arms(all arms),n_armsandlisted_at(the k points under which its irreps are listed: itself, or the first star of a pair that spans both the k and the -k star).irreps (list) –
(label, kname, dimension)of every analyzed irrep, in table order.strata (list) – Every
IsotropyStratum, irrep by irrep, each irrep in the order of the--parenttable.errors (dict) – Maps the label of an irrep that could not be enumerated to the reason.
sohncke (bool) –
Truewhen the parent has no improper operation (then an enantiomorphic partner type is not a match).fingerprint (str) – Hash of the sources the table was built with; a cached table with another fingerprint is rebuilt.
cache_path (str | None) – The cache file read or written, or
None.from_cache (bool) –
Truewhen the table was read fromcache_path.
- classmethod from_dict(data)[source]#
Inverse of
to_dict().- Raises:
ValueError – The data is not a table of the current format or was built from other sources.
- Return type:
- select(numbers=None, size=None, index=None, kpoints=None)[source]#
The strata passing every given filter.
- Parameters:
numbers – Subgroup numbers to keep (any iterable), or
None.size – Cell size to keep, or
None.index – Index to keep, or
None.kpoints – k-point names to keep, or
None.
- Returns:
The matching
IsotropyStratumrecords, in table order.- Return type:
list
- cache_path: str | None = None#
- errors: dict#
- fingerprint: str = ''#
- from_cache: bool = False#
- irreps: list#
- kpoints: dict#
- number: int#
- sohncke: bool = False#
- space_group: str#
- strata: list#
- version: str#
- class crystod.group.JahnTellerModes(point_group, irreps, pseudo, product, identity, active=<factory>, first_order=None)[source]#
Bases:
objectJahn-Teller modes of a degenerate level, or the symmetry-allowed pseudo-Jahn-Teller coupling modes of two levels.
- Variables:
point_group (str) – Point-group label.
irreps (tuple[str, ...]) –
(IR,)for the Jahn-Teller effect of a degenerate level,(IR1, IR2)for the pseudo-Jahn-Teller mixing of two levels.pseudo (bool) –
Truefor two irreps.product (dict[str, int]) – Decomposition of
[IR x IR](Jahn-Teller) or of the plain productIR1 x IR2(pseudo-Jahn-Teller), nonzero terms only, in table order.identity (str) – Label of the totally symmetric irrep.
active (dict[str, int]) –
productwithout the totally symmetric irrep. For one irrep: the Jahn-Teller active modes, which couple linearly to the degenerate level and lower its symmetry (the Jahn-Teller theorem). For two irreps: the symmetry-allowed coupling modes only (also available asallowed), a necessary condition for the pseudo-Jahn-Teller effect; whether the mixing destabilizes the structure depends on the energy gap and the vibronic coupling strength, which symmetry does not give.first_order (dict[str, int] | None) – For two identical labels,
[IR x IR]without the identity irrep (the first-order Jahn-Teller modes of that level, empty for a nondegenerate irrep);Noneotherwise.
- active: dict[str, int]#
- property allowed: dict[str, int]#
The symmetry-allowed coupling modes (same as
active).
- first_order: dict[str, int] | None = None#
- identity: str#
- irreps: tuple[str, ...]#
- point_group: str#
- product: dict[str, int]#
- pseudo: bool#
- class crystod.group.KpointCorrelation(parent_k_name, parent_k, parent_kind, parent_arms, parent_arms_in_block, child_k_name, child_k, child_k_conventional, child_arms, arms_merged, rows=<factory>)[source]#
Bases:
objectThe rows of one parent k star and one k star of the subgroup.
- Variables:
parent_k_name (str) – ISO-IR name of the parent k point (
X;LDfor a point of a symmetry line).parent_k (tuple) – The parent arm shown, primitive basis of G, as
Fractionvalues in (-1/2, 1/2].parent_kind (str) –
"point"for a tabulated special point of G,"line","plane"or"general point"otherwise.parent_arms (int) – Number of arms of the parent star.
parent_arms_in_block (int) – How many of them fall onto this star of H.
child_k_name (str) – ISO-IR name of the k point of H (
M).child_k (tuple) – Its arm shown, primitive basis of H as
crystod-bz --show-kpointprints it (the tabulated arm for a special point), asFractionvalues.child_k_conventional (tuple | None) – The same in the conventional basis of H, or None for a primitive lattice.
child_arms (int) – Number of arms of the star of H.
arms_merged (int) – Parent arms per arm of H.
rows (list) – One
IrrepCorrelationper parent irrep of the star.
- arms_merged: int#
- child_arms: int#
- child_k: tuple#
- child_k_conventional: tuple | None#
- child_k_name: str#
- parent_arms: int#
- parent_arms_in_block: int#
- parent_k: tuple#
- parent_k_name: str#
- parent_kind: str#
- rows: list#
- class crystod.group.KpointIsotropySubgroups(tables=(), *, space_group='', space_group_number=0, kpoint='', coordinates=(), n_arms=0, errors=None)[source]#
Bases:
dictIsotropy subgroups of every irrep of one special k point.
The
crystod-group --parent SG --kpoint Ktable as data, returned byisotropy_subgroups_at_kpoint(): adictthat maps the label of every irrep of the k point to the list of itsIsotropySubgrouprecords, in the order of the ISO-IR tables (GM1+,GM2+, …); each list is whatisotropy_subgroups()returns for that irrep. The two members of a complex-conjugate pair share one physically irreducible order parameter and appear once, under the pair label ("GM2+GM3+"of Pm-3); the records are those of the member that comes first in the tables (isotropy_subgroups(space_group, "GM2+")), and theirdirectioncomponents refer to the basis built from that member, so pass its label, not the partner’s, when a direction of the table is resolved again.- Variables:
space_group – International short symbol of the parent space group.
space_group_number – Its number.
kpoint – ISO-IR name of the k point, e.g.
"GM"or"X".coordinates – The tabulated arm of its star in the primitive reciprocal basis, three floats.
n_arms – Number of arms of the star.
errors – Maps the label of an irrep that could not be enumerated to the reason; such an irrep has no entry in the mapping itself. Empty on success.
- class crystod.group.LandauLifshitz(n_cubic, n_lifshitz, continuous_allowed)[source]#
Bases:
objectLandau and Lifshitz conditions of an irrep.
- Variables:
n_cubic (int) – Number of cubic invariants (Landau condition: zero).
n_lifshitz (int) – Multiplicity of the identity in the antisymmetric square of D times the polar-vector representation (Lifshitz condition: zero).
continuous_allowed (bool) –
Truewhen both conditions hold, so a continuous (second-order) transition is allowed by symmetry.
- continuous_allowed: bool#
- n_cubic: int#
- n_lifshitz: int#
- class crystod.group.SecondaryOrderParameter(label, kname, k, dimension, n_free, direction_pattern, coupling, coupling_degree, coupling_multidegrees=<factory>, kind='other')[source]#
Bases:
objectOne irrep allowed by the isotropy subgroup of a direction.
- Variables:
label (str) – ISO-IR label (pair label such as
R4R5for a doubled irrep).kname (str) – Name of its k point (
GM,R, …).k (tuple) – The tabulated k vector of the star, primitive basis, as
Fractionvalues.dimension (int) – Dimension of the (physically irreducible) irrep.
n_free (int) – Number of free parameters of the irrep fixed by the subgroup (dimension of its fixed space).
direction_pattern (str) – The fixed space as an ISOTROPY-style direction pattern, e.g.
(a,0).coupling (str) – The lowest coupling term to the primary order parameter as text:
Q^2 etafor one primary irrep,Q1^1 Q2^1 etafor two (several lowest multidegrees are separated by, ``), ``> Nwhen there is none up to total degree N,> N (monomial limit)when the search stopped at degree N + 1 because its linear problem exceedsMONOMIAL_LIMIT, and an empty string for a primary irrep. “Does not vanish” is tested on the fixed space of the subgroup in the primary irreps (the stratum of the direction; for a non-generic direction such as Fm-3m W1(a;0;0;0;0;0)it is larger than the direction).coupling_degree (int | None) – Total degree of that term (
m + 1), orNone.coupling_multidegrees (list) – The multidegrees of the lowest coupling terms (primary degrees, then 1 for the secondary irrep).
kind (str) –
"primary","polar"(a non-identity Gamma irrep in the polar-vector representation),"strain"(the identity irrep, or a Gamma irrep in the symmetric square of the vector representation) or"other".
- coupling: str#
- coupling_degree: int | None#
- coupling_multidegrees: list#
- dimension: int#
- direction_pattern: str#
- k: tuple#
- kind: str = 'other'#
- kname: str#
- label: str#
- n_free: int#
- class crystod.group.SettingTable(number, symbol, settings, input_index, tolerance, input_parameters)[source]#
Bases:
objectEvery setting of the space group of a structure.
- Variables:
number (int) – Space-group number.
symbol (str) – Hermann-Mauguin symbol of the default setting (spglib’s symbol of the input).
settings (list) – The
SpaceGroupSettingrecords in Hall-number order.input_index (int | None) – 1-based index of the (first) setting the input cell is in, or None (a primitive cell, a supercell or a shifted origin).
tolerance (float) – Symmetry tolerance (symprec, Angstrom).
input_parameters (tuple) –
(a, b, c, alpha, beta, gamma)of the input cell.
- input_index: int | None#
- input_parameters: tuple#
- number: int#
- settings: list#
- symbol: str#
- tolerance: float#
- class crystod.group.SpaceGroupIrrepAlgebra(space_group_symbol)[source]#
Bases:
objectSpace-group operations and ISO-IR irrep tables in the primitive basis.
The algebra behind
crystod-group --product IRREP... --sg SGand 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 of1/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 of1/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 hasname,dim,kpnameandcharacters.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 conditionk1_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:
factorsare the resolved irrep records;termsis a list of(kname, irrep, multiplicity)whereirrephasname,dimandkpname(a tabulated ISO-IR irrep or a computed line irrep);leftoverslists the k vectors (units of1/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)]
- decompose_square(label, kind='symmetric')[source]#
Decompose the symmetric or antisymmetric square of a full irrep.
The computation behind
crystod-group --product IR IR --sg SG --symmetric|--antisymmetric. The order-parameter matrices ofInducedRepresentation(the physically irreducible real form:D + D*for complex- and pseudoreal-type irreps) give the characters(chi(g)^2 +- chi(g^2)) / 2withchi(g^2) = tr M(g)^2on every element of the finite factor groupG / T_N; these are reduced by character inner products with the induced characters of the irreps at the stars ofk_a + k_b(tabulated special points first, other stars computed with spgrep and named from the ISO-IR tables, as indecompose_product).- Parameters:
label (str) – ISO-IR label of the irrep, e.g.
"R4+".kind (str) –
"symmetric"or"antisymmetric".
- Returns:
A
SquareDecompositionrecord.- Raises:
SystemExit – The label is not tabulated, or its order-parameter matrices are not available (
InducedRepresentation).- Return type:
SquareDecomposition
Example
>>> from crystod import group >>> algebra = group.SpaceGroupIrrepAlgebra("Pm-3m") >>> square = algebra.decompose_square("R4+", "symmetric") >>> [(irrep.name, n) for _, irrep, n in square.terms] [('GM1+', 1), ('GM3+', 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
termsofdecompose_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_irreporirreps_by_kname).- Returns:
(arms, C)withC[i, a] = chi_small(s_a^-1 g_i s_a)when operationg_ifixes armaand0otherwise; the full character of(g_i, t)issum_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 asinduced_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.
SMas(a,a,0)rather than(0,a,a));canonicalitself 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
iwhose q-actionk . W_i^-1leaves 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-conventionq_a = k . W_{s_a}^-1(units of1/DEN), and the index of the coset representatives_agenerating every arm.- Return type:
(arms, representatives)
- class crystod.group.SpaceGroupSetting(index, hall_number, symbol, full_symbol, choice, axes_text, transformation, origin_shift, lattice, parameters, is_input, shared_symbol, std_lattice, std_positions, std_numbers)[source]#
Bases:
objectOne setting (Hall-symbol entry) of a space group, seen from a structure.
- Variables:
index (int) – 1-based position in the list of settings of the group (Hall-number order: the order of VESTA and the International Tables).
hall_number (int) – spglib Hall number (1-530).
symbol (str) – Hermann-Mauguin symbol of the setting, e.g.
AmamorP2_1/n.full_symbol (str) – Full Hermann-Mauguin symbol, e.g.
A 2_1/m 2/a 2/m.choice (str) – spglib’s choice string, e.g.
-cba,b2,2,R(empty for the single or default setting of a group).axes_text (str) – The choice in words, e.g.
(-c, b, a)or(unique axis b, cell choice 2).transformation (numpy.ndarray) –
Pofx_setting = P x_input + p, shape(3, 3).origin_shift (numpy.ndarray) –
p, shape(3,), wrapped into[0, 1).lattice (numpy.ndarray) – Lattice vectors of the setting as rows, in the input’s Cartesian frame and not idealized (Angstrom).
parameters (tuple) –
(a, b, c, alpha, beta, gamma)oflattice(Angstrom, degrees).is_input (bool) – True when the input cell is the conventional cell of this setting (same symmetry operations, origin included; two rows of No. 68 share one Hall symbol and are marked together).
shared_symbol (bool) – True when another setting of the group has the same
symbol(it is then told apart bychoice).std_lattice (numpy.ndarray) – The idealized conventional lattice of the setting (rows; a along x, b in the xy plane): spglib’s conventional cell carried into the setting by
Pandp.std_positions (numpy.ndarray) – Fractional coordinates in
std_lattice.std_numbers (numpy.ndarray) – Atomic numbers of
std_positions.
- axes_text: str#
- choice: str#
- full_symbol: str#
- hall_number: int#
- index: int#
- is_input: bool#
- property label: str#
Symbol and axes, e.g.
Amam (-c, b, a).
- lattice: ndarray#
- origin_shift: ndarray#
- parameters: tuple#
- std_lattice: ndarray#
- std_numbers: ndarray#
- std_positions: ndarray#
- symbol: str#
- property tag: str#
the symbol without
/and_, plus_<choice>when the symbol is shared (Amam,P21n_b2,Fd-3m_2,R-3c_R).- Type:
File-name tag
- transformation: ndarray#
- class crystod.group.SpinOrbitRelation(k_label, k_kind, k_point, irrep, dimension, double_irreps, double_dimensions=<factory>, notes=<factory>)[source]#
Bases:
objectA single-valued small irrep and the double-valued ones it becomes.
One line of
crystod-group --correlate-double-group: when spin-orbit coupling is switched on, a level of the single-valued (spinless) small irrep Gamma at k becomes the double-valued (spinor) small irreps of Gamma x D(1/2) = sum_j m_j Delta_j.- Variables:
k_label (str) – ISO-IR name of the k point (
GM,R, …); for coordinates off the special points, the ISO-IR name of the line, plane or general point they lie on (DT,GP).k_kind (str) –
"point"for a tabulated special point, otherwise"line","plane"or"general point"(the dimension of the k subspace fixed by the little co-group).k_point (tuple) – k in the primitive basis, as
Fractionvalues: the tabulated arm of a special point (whatever arm was given); otherwise the coordinates given, reduced into (-1, 1) by an integer and snapped onto fractions with denominators up to 48 within 1e-6, as the little group is computed (the header prints any other coordinate with three decimals).irrep (str) – ISO-IR label of the single-valued small irrep (
R4+).dimension (int) – Its dimension.
double_irreps (list) – The double-valued small irreps of irrep x D(1/2), as
(name, multiplicity)pairs in natural order (-R6+,-R8+: the names ofcrystod --spinor,crystod.wavecar_irreps.double_valued_names).double_dimensions (dict) –
{name: dimension}of every double-valued small irrep at k.notes (list) – The NOTE lines of the k point (without the
NOTE:prefix), the same in every record of one k point: where the names differ from Bradley & Cracknell (1972), or why they are generic.
- dimension: int#
- double_dimensions: dict#
- double_irreps: list#
- irrep: str#
- k_kind: str#
- k_label: str#
- k_point: tuple#
- notes: list#
- class crystod.group.SubgroupCorrelation(parent_symbol, parent_number, child_symbol, child_number, parent_file, child_file, size, index, basis, frame_basis, frame_origin, frame_source, transformation, blocks=<factory>, unreached=<factory>, notes=<factory>, spinor=False, spinor_notes=<factory>, parent_formula='')[source]#
Bases:
objectThe correlation of the irreps of a group-subgroup pair of structures.
Returned by
subgroup_correlation(crystod-group --correlate --supergroup-poscar P --subgroup-poscar C).- Variables:
parent_symbol (str) – International symbol of the supergroup G (
parent_numberits number);child_symbolandchild_numberlikewise for the subgroup H, the space group of the child structure.parent_file (str) – The supergroup structure file as given;
child_filethe subgroup one.size (int) – Primitive-cell multiplication of H relative to G.
index (int) – Index of H in G.
basis (numpy.ndarray) – Rows of the primitive basis of H in parent primitive units (the sublattice basis of
SymmetryModeAnalysis.mapping.S).frame_basis (numpy.ndarray) – Rows of the conventional basis of the ISO-IR frame of H the labels of H refer to, in parent conventional units.
frame_origin (numpy.ndarray) – Its origin in parent conventional units.
frame_source (str) –
"structure"when that frame is the ISO-IR frame of the subgroup structure file (the one every other command uses for that file),"orbit"when it is the frame of a generic orbit of H (fallback).transformation (object) – The
SettingTransformation(P, p) printed in the* Transformation matrix (parent -> child) *block.blocks (list) – One
KpointCorrelationper (parent star, star of H): the special points of G in the order of the ISO-IR tables, then the parent line or plane points that are the only source of a special point of H.unreached (list) – The special points of H that no parent special point reaches, as
(name, k of H, parent k, parent k name, kind)with k asFractiontuples (empty when every one is reached).notes (list) – The NOTE lines of the command (without
NOTE:).spinor (bool) – Whether the double-valued rows were computed (
--spinor).spinor_notes (list) – The NOTE lines of
spinor_numbering_notesof the k points of G and H (where the double-valued names differ from Bradley & Cracknell), withoutNOTE:.parent_formula (str) – Reduced chemical formula of the supergroup structure (
SymmetryModeAnalysis.parent_formula, the name ofsym_mode_<formula>), e.g."YMnO3"; the command names its report fileCORREL_<formula>_<G>_<H>after it.
- basis: ndarray#
- blocks: list#
- child_file: str#
- child_number: int#
- child_symbol: str#
- frame_basis: ndarray#
- frame_origin: ndarray#
- frame_source: str#
- index: int#
- notes: list#
- parent_file: str#
- parent_formula: str = ''#
- parent_number: int#
- parent_symbol: str#
- size: int#
- spinor: bool = False#
- spinor_notes: list#
- transformation: object#
- unreached: list#
- class crystod.group.SubgroupGraph(space_group, number, irreps, dimensions, nodes, edges, inclusions=<factory>, landau=<factory>)[source]#
Bases:
objectThe group-subgroup graph of the isotropy subgroups of some irreps.
Returned by
subgroup_graph().- Variables:
space_group (str) – International short symbol of the parent.
number (int) – Its number.
irreps (list) – The irrep labels, in input order.
dimensions (list) – Order-parameter dimension of every irrep.
nodes (list) – The
GraphNoderecords, the parent first, then by index, number of free parameters and type.edges (list) – The
GraphEdgerecords of the transitive reduction.inclusions (set) – Every pair
(a, b)of node ids withba proper subgroup of a conjugate ofa(the full relation, before the reduction).landau (dict) – Maps every irrep label to its
LandauLifshitzrecord.
- contains(a, b)[source]#
Truewhen nodebis a proper subgroup of a conjugate of nodea(both given byid).- Return type:
bool
- dimensions: list#
- edges: list#
- inclusions: set#
- irreps: list#
- landau: dict#
- nodes: list#
- number: int#
- space_group: str#
- class crystod.group.SymmetryModeAnalysis(parent_file, child_file, tolerance)[source]#
Bases:
objectSymmetry-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_symbolits Hermann-Mauguin symbol);child_numberandchild_symbollikewise for the child.algebra – The
SpaceGroupIrrepAlgebraof 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_numberstheir 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) andmapping.u_frac(displacements, parent primitive fractional). Among the symmetry-equivalent sublattice settings of a symmetric parent,Sis 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).mapping_note – None, or the NOTE (printed by the command with the cell relation) that the minimum-distortion mapping was not a group-subgroup setting and the atoms were re-paired in a setting in which every child operation is a parent operation.
core_size – Multiplication of the invariant-core analysis cell; its atoms are
ref_frac(n_atomsof them) with atomic numbersref_zand Cartesian displacementsu_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) andkind("tabulated"or"computed").modes – One entry per parent irrep with a nonzero number of modes (a complex-type irrep and its conjugate form one entry, the physically irreducible pair,
irrep_namejoining both labels as inGM3+GM4+; a pseudoreal irrep keeps its single name), carryingkname,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)),label_info(), which returns(direction label, subgroup info, index),domain_labelandrepresentative_label. The direction labels of all rows describe one domain of the child (one parent operation applied to all modes,_common_domain): the domain-equivalent child in which the modes, in order of decreasing amplitude, sit on the simplest directions left to them, so that the largest mode with domain-equivalent directions sits on the ISOTROPY representative of its stratum, the row ofcrystod-group --parent SG --irrep IR(IsotropyAnalyzer.canonical_projector), while the rows together remain one coupled order-parameter direction (crystod-group --parent SG --irrep IR1 IR2 --order-parameter ...) whose isotropy subgroup is conjugate to the child’s (for an enantiomorphic type, possibly its partner).representative_labelis the representative of each mode’s stratum on its own (a smaller mode can sit on another image in that domain),domain_labelthe direction the child sits on as given; the command names both in a note under the table when they differ from the direction shown. The subgroup info and index are those of the isotropy subgroup of the direction the input child sits on in that irrep (domain_label; 74 Imma for R4+ of a Pnma child, not Pnma itself), conjugate to the one of the direction shown: the same index and type, except that a child on a mirror-image domain of a stratum of an enantiomorphic type (ENANTIOMORPHIC_PAIRS) has the partner of that type, which the note names as well. The sublattice setting, the mode fields and the files follow the input child. A complex pair whose conjugate irrep lives on the -k star (a parent with no operation taking k to -k) is one entry on the first of the two stars; its field and amplitude include the -k Fourier components, andpartner_kname/partner_kvecname the -k star (None for every other entry).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>report after it).setting_transformation() – The transformation (P, p) from the parent to the child conventional setting in the AMPLIMODES convention (
SettingTransformation); the command prints it before the decomposition table; the command saves its whole terminal report insym_mode_<formula>.
- Raises:
SystemExit – The child cell is not an integer multiple of the parent cell, the child cannot be mapped onto the parent (no sublattice setting carries the child point group, the translation parts of the child operations fit no origin, a Wyckoff conflict, or no symmetry-consistent pairing within 1.8 A), 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))
- setting_transformation(frame='input')[source]#
The transformation (P, p) from the parent to the child conventional setting.
The convention of AMPLIMODES and of the International Tables: the columns of
Pare the child conventional basis vectors in units of the parent conventional basis,(a', b', c') = (a, b, c) P, andpis the origin of the child cell in parent fractional coordinates, so that a point with child coordinatesx'has parent coordinatesx = P x' + p. The child basis is the sublattice setting the analysis uses (mapping.S, the one closest to the orientation of the input files among the equivalent ones).- Parameters:
frame (str) –
"input"(default): the conventional cells as the two input files set them up, which is what AMPLIMODES reports for the same files;"standard": spglib’s standard settings of both structures (the same as"input"for files in the standard setting)."input"falls back to"standard"when spglib gives no setting transformation for one of the input cells; the result says which frame it is in.- Returns:
SettingTransformationwithmatrix((3, 3), the columns being the child basis vectors),origin(reduced into[0, 1)) andframe; entries that are rational numbers with a denominator up to 48 are snapped exactly.
Example
>>> from crystod import group >>> analysis = group.SymmetryModeAnalysis("221.cif", "140.cif", 0.01) >>> t = analysis.setting_transformation() >>> t.matrix.tolist(), t.origin.tolist() # SrTiO3 Pm-3m -> I4/mcm ([[1.0, 1.0, 0.0], [-1.0, 1.0, 0.0], [0.0, 0.0, 2.0]], [0.5, 0.5, 0.5])
- class crystod.group.TensorForm(kind, jahn, description, letter, voigt, layout, setting, components, basis, independent, relations, matrix, tensors, forbidden_by_time_reversal=False)[source]#
Bases:
objectThe symmetry-allowed form of a property tensor in one point group.
- Variables:
kind (str) – The kind as given (
"piezoelectric") or the Jahn symbol.jahn (crystod.tensor_form.JahnSymbol) – The parsed
JahnSymbol.description (str) – What the tensor is.
letter (str) – Component letter (
"d";"T"for a bare Jahn symbol).voigt (str) – Matrix-notation factors:
""(none),"strain"(Nye’sd_iL = 2 d_ijkfor L = 4-6) or"compliance"(Nye’ss_LMwith factors 2 and 4).layout (str) –
"vector","matrix"(3x3),"3x6","6x6"or"list"(components listed one by one).setting (crystod.tensor_form.PointGroupSetting) – The
PointGroupSetting.components (tuple) – Names of all components that do not vanish by intrinsic symmetry, in matrix-notation order.
basis (numpy.ndarray) – Array
(n_independent, n_components): the reduced row-echelon basis of the allowed tensors in matrix notation.independent (tuple) – Names of the independent components (the pivots).
relations (tuple) –
"d24 = d15": every other nonzero component in terms of the independent ones.matrix (tuple) – The matrix form, rows of entry texts (one row for a vector; for the
listlayout,(component, entry)pairs of the nonzero components).tensors (numpy.ndarray) – The allowed tensors as full Cartesian arrays of shape
(n_independent, 3, ..., 3): tensorkis the one with independent componentkequal to 1 and the others 0.forbidden_by_time_reversal (bool) – True for a time-odd tensor in a non-magnetic (grey) point group.
- basis: ndarray#
- components: tuple#
- description: str#
- forbidden_by_time_reversal: bool = False#
- independent: tuple#
- jahn: JahnSymbol#
- kind: str#
- layout: str#
- letter: str#
- matrix: tuple#
- property n_independent: int#
Number of independent components.
- relations: tuple#
- setting: PointGroupSetting#
- tensors: ndarray#
- voigt: str#
- class crystod.group.VaspSymmetryReport(vasprun, outcar, structure, formula, reduced_formula, run, symmetry, tensors, missing=(), notes=())[source]#
Bases:
objectEvery tensor of a VASP run against the symmetry of its structure.
- Variables:
vasprun (str | None) – Path of the
vasprun.xmlread, or None.outcar (str | None) – Path of the
OUTCARread, or None.structure (str) – Where the structure came from.
formula (str) – Formula of the cell (
"Sr2Ti2O6").reduced_formula (str) – Reduced formula (
"SrTiO3"), used in the YAML file name.run (dict) – Run parameters (
IBRION,ISIF,NSW,LEPSILON,ISPIN,LNONCOLLINEAR,ISYM,SYMPREC) and VASP’s own symmetry (n_operations,point_group) where the files give them.symmetry (crystod.vasp_symmetry.CrystalSymmetry) – The
CrystalSymmetryof the structure.tensors (tuple) –
TensorCheckandSiteTensorCheckrecords in the printed order.missing (tuple) –
(quantity, reason)for every selected quantity that the files do not hold.notes (tuple) – Extra lines for the run block.
- to_dict()[source]#
The content of the YAML file as plain Python data (floats rounded to 10 significant digits).
- Return type:
dict
- formula: str#
- missing: tuple = ()#
- notes: tuple = ()#
- outcar: str | None#
- reduced_formula: str#
- run: dict#
- structure: str#
- symmetry: CrystalSymmetry#
- tensors: tuple#
- vasprun: str | None#
- crystod.group.antisymmetric_square(ct, point_group, irrep)[source]#
Decomposition of the antisymmetrized square
{Gamma x Gamma}.The computation behind
crystod-group --product IR IR --pg PG --antisymmetric: the character(chi(g)^2 - chi(g^2)) / 2of the antisymmetric part ofGamma x Gamma(the orbital part of two-electron spin triplets; for a vector irrep it contains the axial vector), reduced into the irreps of the point group.- Parameters:
ct (dict) – Character table from
crystod.group.get_character_table.point_group (str) – Point-group label (used in the error message only).
irrep (str) – Label of the irrep, e.g.
"T2g".
- Returns:
{irrep label: multiplicity}over every irrep of the table (zeros included).- Raises:
SystemExit – The irrep label is not in the table (
ValueErrorwhen called throughcrystod.group).- Return type:
dict[str, int]
Example
>>> from crystod import group >>> ct = group.get_character_table("m-3m") >>> {k: n for k, n in group.antisymmetric_square(ct, "m-3m", "T2g").items() if n} {'T1g': 1}
- 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 compactx,y,zstrings, 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_operationsandn_sites.- Return type:
(lines, info)- Raises:
SystemExit – spglib could not determine the symmetry at this tolerance (
ValueErrorwhen called throughcrystod.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.compatibility_relations(sg, k0, k1=None, line=None)[source]#
Compatibility relations between special points along symmetry lines.
The computation behind
crystod-group --correlate-kpath --sg SG --kpoint K0 K1 [--line L].- Parameters:
sg – Space-group number or international symbol.
k0 – The first special point: ISO-IR name (
"GM","X";GandGAMMAmeanGM) or three primitive coordinates.k1 – The second special point, in the same forms;
Nonetakes every other tabulated special point joined to k0 by a symmetry line.line – ISO-IR name of the line (
"DT") when several lines join the two points;Nonetakes the line with the largest little group (then the shortest).
- Returns:
for every line, the small irreps at k0 and then those at the other end, in table order.
- Return type:
Compatibilityrecords- Raises:
SystemExit – Unknown space group or k point, the same point twice, or no symmetry line (of the requested name) between the points (
ValueErrorthroughcrystod.group).RuntimeError – An internal consistency check failed (a restriction that does not decompose, or dimensions that do not add up).
Example
>>> from crystod import group >>> rows = group.compatibility_relations("Pm-3m", "GM", "X") >>> [(r.k0_irrep, r.line_irreps) for r in rows if r.k0_irrep == "GM4-"] [('GM4-', [('DT1', 1), ('DT5', 1)])]
- crystod.group.compute_star(rotations, translations, kpoint)[source]#
Compute the star of k: the orbit of a k point under the rotations.
Every rotation
Rof the space group sendsktok' = k R; the distinct images modulo reciprocal-lattice vectors are the arms of the star, and the rotations sendingkto one arm form a coset of the little group ofk. This is the computation behindcrystod --star-of-k;crystod-phonon --modulationuses 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 exampleSymmetryAdaptedOrbitalBasis.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 iskitself and its"operation_indices"are the little group ofk.- 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 Energiesblock ofcrystod-group --multiplet CONFIG --pg PG --orbital ORB: exact diagonal energies of the electron-electron interaction as linear combinations of the Racah parametersA, B, C(d shells) or of the reduced Slater-Condon parameters (F0, F2for p,F0, F2, F4, F6for 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 (
0to3); the occupied irrep shells must occur in its ligand-field splitting.shells (list[tuple[str, int]]) –
[(irrep, n_electrons), ...]fromcrystod.group.parse_config.terms (list[tuple[Fraction, str, int]]) – Terms
(S, irrep, count)of the configuration, fromcrystod.group.shell_terms/couple_shells.
- Returns:
the parameter names (
["A", "B", "C"]for d), oneTermEnergyper term in the order ofterms(linearholds the exact coefficients of a unique term,ci_meanandci_quadraticthe closed-form CI block of a doubly occurring term,numericthe eigenvalues at the reference point;describe()formats them), the reference parameter values, and a note describing them (C/B = 4.5for d).- Return type:
(params, energies, reference, reference_note)- Raises:
SystemExit – A projector rank or the trace identity disagrees with the term list, or
lis above 3 (ValueErrorwhen called throughcrystod.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.correlation_table(pg, subgroup)[source]#
The correlation table of a point group and a subgroup type.
The computation behind
crystod-group --correlate --pg G --subgroup H: every subgroup of G (from phonopy’s table, order at most 48) is generated, the ones of type H (spglib.get_pointgroup) are grouped into conjugacy classes under G, and the irreps of G are restricted to one representative of each class. The restricted characters are reduced with phonopy’s table of H after the elements are carried onto the elements of that table (in the axes of G when they match one of its settings, else with spglib’s transformation to the standard orientation, else by a conjugation found for the generators).- Parameters:
pg (str) – The point group G, as phonopy names it (
"m-3m","6/mmm").subgroup (str) – The subgroup type H (
"4/mmm","3m").
- Returns:
A
CorrelationTablewith one orientation per conjugacy class of subgroups of type H, ordered by the principal axis (z first).- Raises:
SystemExit – Unknown point group, or H not a subgroup of G (
ValueErrorthroughcrystod.group).RuntimeError – A restriction does not decompose into the irreps of H or the dimensions do not add up (internal check).
- Return type:
Example
>>> from crystod import group >>> table = group.correlation_table("m-3m", "4/mmm") >>> [header for header, _ in table.orientations] ['4/mmm (4 || z)'] >>> table.rows["T2g"] [[('B2g', 1), ('Eg', 1)]]
- 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 additionS = |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.coupling_terms(space_group, irreps, max_degree=4)[source]#
Lowest-order coupling term of a direct sum of irreps.
The invariants of the direct sum are computed up to total degree
max_degreeand the first multidegree with every entry at least 1 (lowest total degree, then descending lexicographic order) is returned. For the hybrid improper mechanism, give two order parameters and a polar Gamma irrep: a trilinear termQ1 Q2 Phas the multidegree(1, 1, 1).- Parameters:
space_group – Space-group number or international symbol.
irreps – Two or more ISO-IR labels, e.g.
["X2+", "X3-", "GM5-"].max_degree (int) – Highest total degree searched (default 4).
- Returns:
A
CouplingTerm, orNonewhen no coupling term exists up tomax_degree.- Raises:
SystemExit – Fewer than two labels, or an unknown space group or irrep (
ValueErrorthroughcrystod.group).- Return type:
CouplingTerm | None
Example
>>> from crystod import group >>> term = group.coupling_terms("I4/mmm", ["X2+", "X3-", "GM5-"], 3) >>> term.multidegree, len(term.polynomials), term.trilinear ((1, 1, 1), 1, True)
- crystod.group.decompose(characters, character_table, multiplicities=None)[source]#
Multiplicity of every irrep in a reducible representation.
The reduction formula
n_i = sum_C |C| chi_i(C) chi(C) / sum_C |C| chi_i(C)^2over the classesC(real characters); the computation behindcrystod-group --decomposeand the last step of--ligand-fieldand--multiplet. The denominator is|G|for an ordinary irrep and2|G|for the entries that the tables store as physically irreducible real pairs of complex-conjugate irreps (E of 3, 4, -4, 23, E1/E2 of 6, …), so such a pair counts once per real copy. The representation must be real (orbital, product and polynomial spaces are).- 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] | None) – Class sizes in the same order; by default
class_sizes(character_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") >>> group.decompose([3, 0, 1], ct) {'A1': 1, 'A2': 0, 'E': 1} >>> group.decompose([2, 0, -2], group.get_character_table("4")) {'A': 0, 'B': 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 --productwith a point group, and the reduction used by--basis: the reduction formula with the class sizes taken from the table, divided by the norm of each irrep character, so that an entry combining a complex-conjugate pair of irreps (norm 2, e.g. E of 4 or Eg of m-3) counts once per real copy. The representation must be real (products and polynomial spaces are).- 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 (
ValueErrorwhen called throughcrystod.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.find_coupled_isotropy_irreps(parent, child, size=None, index=None, kpoints=None, *, use_cache=True)[source]#
Irrep pairs and directions whose coupled isotropy subgroup has type H.
The coupled reverse lookup of
crystod-group --parent G --child H --coupled: every stratum of the direct sum of two special-point irreps of G, with both amplitudes nonzero, whose isotropy subgroup has type H while neither irrep alone has it. The pairs are searched at the same k point first, then at different k points; the single strata of the cachedisotropy_table()are the candidates.- Parameters:
parent – Symbol or number of the parent space group G.
child – Symbol or number of the subgroup type H.
size – Keep only this primitive-cell multiplication.
index – Keep only this index [G:H].
kpoints – Use only the irreps of these special k points.
use_cache (bool) – Read the cached table when it exists.
- Returns:
A list of
CoupledIsotropyMatch, sorted by index, then by size, then in the order of the irrep pairs.- Raises:
ValueError – Unknown parent or child, or a k point that is not a special point of the parent.
- Return type:
list
Example
>>> from crystod import group >>> for match in group.find_coupled_isotropy_irreps("Pm-3m", "Pnma", size=4): ... print(match) R4+(0,a,a) M3+(d;0;0) -> Pnma (No. 62), size 4, index 24
- crystod.group.find_isotropy_irreps(parent, child, size=None, index=None, kpoints=None, *, coupled=False, use_cache=True)[source]#
Irreps and directions whose isotropy subgroup is of a given type.
The reverse lookup of
crystod-group --parent G --child H: every stratum of every special-point irrep of G whose isotropy subgroup is of type H, read from the cachedisotropy_table(). When G has an improper operation, a stratum listed with the enantiomorphic partner type of H is a match too (an improper operation of G maps its order parameter to one of the same stratum with a stabilizer of type H); in a Sohncke parent the two types are different strata and only H counts.- Parameters:
parent – Symbol or number of the parent space group G.
child – Symbol (
"I4/mcm") or number (140) of the subgroup type H.size – Keep only this primitive-cell multiplication.
index – Keep only this index [G:H].
kpoints – Keep only these special k points (names, or one point as three coordinates).
coupled (bool) – Also search the pairs of irreps (
--coupled) and append theCoupledIsotropyMatchrecords offind_coupled_isotropy_irreps()after the single-irrep ones.use_cache (bool) – Read the cached table when it exists.
- Returns:
A list of
IsotropyMatch, in table order (k point, irrep, then the order of the--parenttable); several rows of one type are distinct embeddings (conventional basis and origin). Empty when no single irrep gives type H: the subgroup may need coupled irreps (coupled=True).- Raises:
ValueError – Unknown parent or child, or a k point that is not a special point of the parent.
- Return type:
list
Example
>>> from crystod import group >>> for match in group.find_isotropy_irreps("Pm-3m", "R-3c", size=2): ... print(match) R4+(a,a,a) (R) -> R-3c (No. 167), size 2, index 8 R5-(a,a,a) (R) -> R-3c (No. 167), size 2, index 8
- crystod.group.format_compatibility(records)[source]#
The
* Compatibility relations *block as text.- Parameters:
records (list[Compatibility]) – The records returned by
compatibility_relations.- Returns:
per line a header naming the line, its end points and kdelta, then one line per small irrep of each end point, e.g.
GM4- -> DT1 + DT5.- Return type:
The text block (no trailing newline)
- crystod.group.format_correlation_table(table)[source]#
The
* Point group *,* Subgroup *and* Correlation table *blocks of--correlate --pg G --subgroup Has text.- Parameters:
table (CorrelationTable) – The record returned by
correlation_table.- Returns:
G and its order, H with its orientations (number of conjugate subgroups and the classes that fix the orientation), the table with one row per irrep of G and one column per orientation, and a note on the axes.
- Return type:
The text (no leading blank line, no trailing newline)
- crystod.group.format_irrep_table(point_group, ct)[source]#
Character table of a crystallographic point group as text.
What
crystod-group --table --pg PGprints (and what--show-irrep-tableadds to--productand--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, squares=())[source]#
Text report of a space-group direct product.
Exactly what
crystod-group --product IRREP... --sg SGprints: 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. Withsquares(two identical labels,--symmetric/--antisymmetric), the blocks offormat_square_blockfollow the dimension check and the reference comes last.- Parameters:
algebra (SpaceGroupIrrepAlgebra) – The
SpaceGroupIrrepAlgebraof the space group.labels (list[str]) – ISO-IR labels of the factors, e.g.
["R4-", "R5+"].squares (tuple[str, ...]) –
"symmetric"and/or"antisymmetric"; requires two identical labels.
- Returns:
The report as one string (no trailing newline).
- Raises:
SystemExit – A label is not tabulated for this space group (
ValueErrorwhen called throughcrystod.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 KZprints: 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 (
ValueErrorwhen called throughcrystod.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_spin_orbit_relations(records)[source]#
The
* Compatibility relations *blocks of the spin-orbit relations.- Parameters:
records (list[SpinOrbitRelation]) – The records returned by
spin_orbit_relations.- Returns:
one block per k point, separated by a blank line, each with a header naming the k point and its coordinates (primitive basis), one line per single-valued small irrep with the dimension after every label, e.g.
R4+(3) -> -R6+(2) + -R8+(4)(a multiplicity in front, asGM1(1) -> 2 -GM2(1)), and the NOTE lines of the k point.- Return type:
The text (no trailing newline)
- 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
rotationsgiven tocompute_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.format_subgroup_correlation(result)[source]#
The
* Correlation of the irreps at the special k points *block.- Parameters:
result (SubgroupCorrelation) – The
SubgroupCorrelationofsubgroup_correlation.- Returns:
The text (no trailing newline) the command prints after the transformation block: per parent star and star of H a header (the parent k, its arms, the k of H, its arms), one row per parent irrep with the dimension after every label,
R4+(3) [T1g] -> GM1+(1) [A1g] + GM5+(2) [Eg](2 x LD1(1) -> N1(2)when two parent arms fall onto one arm of H), then the NOTE and note lines.- Return type:
str
- crystod.group.format_tensor_form(form)[source]#
The report
crystod-group --tensorprints.- Parameters:
form (TensorForm) – A
TensorForm.- Returns:
The blocks
* Point group *,* Tensor *,* Independent components *,* Matrix form *and* Relations *.- Return type:
str
- crystod.group.format_vasp_symmetry(report)[source]#
The report
crystod --check-symmetryprints.- Parameters:
report (VaspSymmetryReport) – A
VaspSymmetryReport.- Returns:
The
* Title *blocksVASP run,Space groupand one block per tensor group read:Born effective charges,Dielectric tensor,Piezoelectric tensor,Elastic tensor,Internal strain. Independent components are named and valued in the tensor axes ofcrystod-group --tensor -c; residuals are Frobenius norms of the full Cartesian tensors.- Return type:
str
- 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-groupstarts 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 (
ValueErrorwhen called throughcrystod.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, input_cell=None, minus_k=True)[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
IsoIRLabelerof the cell and calls itslabel_characters. Never raises: any failure yieldsNoneso 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)).input_cell – The cell the user gave, when
cellwas derived from it; the labels then refer to the ISO-IR frame of that cell (seeget_cached_labeler).minus_k (bool) – Label a k point without a tabulated star through its -k partner, with ISOTROPY’s partner names (see
IsoIRLabeler.label_characters).
- Returns:
({spgrep irrep index: label}, k-type label)such as({0: "Q1"}, "Q"), orNonewhen 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 PGdecomposes into irreps (the crystal-field / ligand-field splitting of the orbital). Uses the angular-momentum character formulaschi(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)andchi(sigma) = 1.- Parameters:
orbital (str) – Orbital letter, one of
s,p,d,f,g,h,i(ORBITAL_AZIMUTHAL_NUMBERmaps it tol).character_table (dict) – Table from
crystod.group.get_character_table.
- Returns:
{class label: character}in the order ofcharacter_table["rotation_list"]; passlist(result.values())tocrystod.group.decomposefor 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) >>> counts = group.decompose(list(chi.values()), ct) >>> {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 Symbolblock ofcrystod-group --multiplet --orbital.- Parameters:
results – The
TermEnergylist fromcompute_term_energies.reference – The reference parameter values from the same call.
- Returns:
the
TermEnergyentries with the lowest energy at the reference point, and whether that ordering is provably independent of the parameters (Truewhen 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 ofcrystod-group --multipletwithout--orbital: maximal2S+1first, 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)fromshell_termsorcouple_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.invariant_polynomials(space_group, irreps, degree=4)[source]#
Invariant polynomials of one space-group irrep or of a direct sum.
- Parameters:
space_group – Space-group number or international symbol (
"Pm-3m",221).irreps – ISO-IR label(s): one label (
"R4+") or a list; several labels give the invariants of the direct sum, with variables<label>_<n>.degree (int) – Highest total degree (default 4).
- Returns:
An
InvariantBasis. For one irrep the variablesQ1 .. Qdfollow the real basis ofInducedRepresentation(arm by arm; doubled complex-type irreps: real rows, then imaginary rows of each arm), the order of the direction patterns of--parent.- Raises:
SystemExit – Unknown space group or irrep (
ValueErrorthroughcrystod.group).RuntimeError – The nullspace disagrees with the Molien series.
- Return type:
Example
>>> from crystod import group >>> basis = group.invariant_polynomials("Pm-3m", "M1+", degree=3) >>> basis.polynomials[3][0].expression 'Q1*Q2*Q3'
- 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 withcrystod.group.IsotropyAnalyzer, and each direction is returned with the space group it condenses into. No phonopy object is needed; the function is also exported ascrystod.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/originof each subgroup in the parent convention (slightly slower; on by default).
- Returns:
List of
IsotropySubgroup, sorted like the--parenttable (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.isotropy_subgroups_at_kpoint(space_group, kpoint, *, with_settings=True)[source]#
Isotropy subgroups of every irrep of one special k point, as data.
Programmatic counterpart of
crystod-group --parent SG --kpoint K:isotropy_subgroups()run over all irreps of the k point, in the order of the ISO-IR tables. No phonopy object is needed; the function is also exported ascrystod.group.isotropy_subgroups_at_kpoint.- Parameters:
space_group (str | int) – International short symbol (e.g.
"Pm-3m") or number (e.g.221) of the parent.kpoint (str | sequence) – The ISO-IR name of a special k point (
"GM","R","X", …; the case is ignored and"G"/"GAMMA"mean"GM"), or its three coordinates in the primitive reciprocal basis (numbers, or strings such as"1/2"; a decimal within 0.0005 of a special point is taken for it). Coordinates may be those of any arm of the star and may differ from it by a reciprocal lattice vector. The names of a space group are the keys ofcrystod.group.SpaceGroupIrrepAlgebra(space_group).k_by_kname.with_settings (bool) – Also compute the conventional
basis/originof each subgroup in the parent convention (slightly slower; on by default).
- Returns:
a
dictmapping every irrep label to its list ofIsotropySubgrouprecords (each sorted like the--parenttable), with the k-point name, its coordinates and the failed irreps as attributes. An irrep whose enumeration fails is reported inerrorsand does not stop the others.- Return type:
- Raises:
ValueError – For an unknown space group, an unknown k-point name, or coordinates that are not a tabulated special point (symmetry lines and planes and general points have no isotropy subgroups in the tables); the message lists the k points of the space group.
Example
>>> from crystod import group >>> table = group.isotropy_subgroups_at_kpoint("Pm-3m", "GM") >>> list(table) ['GM1+', 'GM2+', 'GM3+', 'GM4+', 'GM5+', 'GM1-', 'GM2-', 'GM3-', 'GM4-', 'GM5-'] >>> for sub in table["GM3+"]: ... print(sub) GM3+(a,0) -> P4/mmm (No. 123), size 1, index 3 GM3+(a,b) -> Pmmm (No. 47), size 1, index 6 >>> table.kpoint, table.coordinates, table.n_arms, table.errors ('GM', [0.0, 0.0, 0.0], 1, {}) >>> group.isotropy_subgroups_at_kpoint(221, [0, 0.5, 0.5]).kpoint 'M'
- crystod.group.isotropy_table(parent, *, use_cache=True, write_cache=True, progress=True)[source]#
The isotropy table of a parent space group, cached on disk.
Every stratum of every irrep at every special k point of the ISO-IR tables, as
crystod-group --parent SG --kpoint Klists them for all K, with the conventional settings of the subgroups. The first call for a parent builds the table (seconds for most groups, minutes for the large stars of the face-centred cubic groups) and writes it tocache_path(); later calls read the file.- Parameters:
parent – Symbol (
"Pm-3m") or number (221) of the parent.use_cache (bool) – Read the cache file when it exists (
Falserebuilds the table; the file is still written).write_cache (bool) – Write the table to the cache file after building it.
progress (bool) – Print one line per k point to stderr while building.
- Returns:
An
IsotropyTable.- Raises:
ValueError – Unknown space group.
- Return type:
Example
>>> from crystod import group >>> table = group.isotropy_table("Pm-3m") >>> [(s.label, s.direction, s.symbol) for s in table.select([167], size=2)] [('R4+', '(a,a,a)', 'R-3c'), ('R5-', '(a,a,a)', 'R-3c')]
- crystod.group.jahn_teller_modes(point_group, irrep, irrep2=None)[source]#
Jahn-Teller active modes of a degenerate level, or the symmetry-allowed pseudo-Jahn-Teller coupling modes of two levels.
The computation behind
crystod-group --jahn-teller IR [IR2] --pg PG: a vibrational mode Q couples linearly to a degenerate level of symmetryGammawhenGamma_Qoccurs in the symmetric square[Gamma x Gamma](spinless levels); the totally symmetric part does not lower the symmetry, so the Jahn-Teller active modes are[Gamma x Gamma]minus the identity irrep (the Jahn-Teller theorem). For two levels a mode Q can mix them whenGamma_Qoccurs in the plain productGamma1 x Gamma2; the non-totally-symmetric irreps of the product are the symmetry-allowed pseudo-Jahn-Teller coupling modes. This is a necessary condition only: the mixing lowers the curvature of the energy along Q toK0 - 2|F|^2/Delta(vibronic constant F, gap Delta), and whether the high-symmetry structure becomes unstable depends on F and Delta, which symmetry does not give. Which of these symmetries actually occur among the vibrations depends on the structure.- Parameters:
point_group (str) – Point-group label, e.g.
"m-3m".irrep (str) – Label of the (degenerate) level, e.g.
"Eg".irrep2 (str | None) – Label of a second level for the pseudo-Jahn-Teller product, or
None.
- Returns:
A
JahnTellerModesrecord.- Raises:
SystemExit – Unknown point group or irrep label (
ValueErrorwhen called throughcrystod.group).- Return type:
Example
>>> from crystod import group >>> group.jahn_teller_modes("m-3m", "T1u").active {'Eg': 1, 'T2g': 1} >>> group.jahn_teller_modes("m-3m", "Eg").active {'Eg': 1}
- crystod.group.landau_lifshitz(space_group, irrep)[source]#
Landau (no cubic invariant) and Lifshitz conditions of an irrep.
- Parameters:
space_group – Space-group number or international symbol.
irrep (str) – ISO-IR irrep label (the physically irreducible, possibly doubled real representation is used).
- Returns:
A
LandauLifshitzrecord;continuous_allowedisTruewhen neither a cubic nor a Lifshitz invariant exists.- Return type:
Example
>>> from crystod import group >>> group.landau_lifshitz("Pm-3m", "R4+") LandauLifshitz(n_cubic=0, n_lifshitz=0, continuous_allowed=True)
- crystod.group.list_space_group_settings(cell, symprec=0.01)[source]#
Every setting of the space group of a cell, with its lattice parameters.
The first setting is spglib’s standardization of the cell (the cell itself when it is the conventional cell of one of the settings). The other settings of a monoclinic or orthorhombic group are reached from it with the matrices of the International Tables: the axis permutation of the choice string (
-cba: a’ = -c, b’ = b, c’ = a) and the cell-choice matrices (cell choice 2: a’ = -a - c, c’ = a; cell choice 3: a’ = c, c’ = -a - c), so that the listed lengths follow the axes text. The settings of the other groups (origin choices, hexagonal/rhombohedral axes) are spglib’s standardization into each Hall setting.- Parameters:
cell –
(lattice, frac, numbers)as spglib takes it (lattice vectors as rows, Angstrom).symprec (float) – Symmetry tolerance (Angstrom).
- Returns:
one
SpaceGroupSettingper Hall number of the space group, in Hall-number order.- Return type:
A
SettingTable- Raises:
ValueError – spglib finds no symmetry at this tolerance, or the tolerance is not positive.
Example
>>> from crystod import group >>> table = group.list_space_group_settings( ... ([[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[0, 0, 0]], [1])) >>> table.number, len(table.settings), table.settings[0].label (47, 1, 'Pmmm (a, b, c)')
- 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
IsoIrreprecord per irrep, in table order, withlabel("GM4-","DT5", …),dim(full dimension),narms,small_dim,ktype,num_free_params, the arrayskvecs,rotations,translations,irtransandmatrices, and the methodsarm_k,match_k,small_characterandin_little_group.- Raises:
ValueError –
kindis 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: acceptsIRREP^N,(IRREP)^N, the quoting-freeIRREPN(T2g2; an unquoted^is a glob character in zsh) and a bareIRREPfor 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 (
ValueErrorwhen called throughcrystod.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,directcoordinates, 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.raman_forms(point_group=None, *, space_group=None, setting=None)[source]#
Raman tensors of every Raman-active irrep of a point group.
The point-group route of
crystod-phonon --raman-tensor: the same projection (crystod.phonon_activity.raman_tensor_basis(), Loudon’s forms with shared constants for a repeated degenerate irrep) on the operations of the point group, with the Mulliken labels of phonopy’s character table, for every irrep (not only those of the phonons of a structure).- Parameters:
point_group (str | None) – Hermann-Mauguin symbol; or
space_group(its point group in the default setting); or a readysetting.space_group – Space-group symbol or number.
setting (PointGroupSetting | None) – A
PointGroupSetting.
- Returns:
crystod.phonon_activity.RamanTensorsrecords in the order of the character table, labelled with Mulliken symbols, in the Cartesian axes of the setting.- Return type:
list
Example
>>> from crystod.tensor_form import raman_forms >>> [(r.label, len(r.tensors)) for r in raman_forms("m-3m")] [('A1g', 1), ('Eg', 2), ('T2g', 3)]
- crystod.group.resolve_kpoint_input(structure, raw_kpoint)[source]#
Resolve a
--kpointargument 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 as1/2allowed) – 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 (GPfor a general point). This is whatcrystod --star-of-kandcrystod --visualizedo with--kpoint. When the label lookup itself fails (seekpath unavailable), three coordinates are still accepted and labelledcustom.- Parameters:
structure (SymmetryOnlyVibrations) – A
SymmetryOnlyVibrationsof the cell, or a subclass such asSymmetryAdaptedOrbitalBasis; itsresolve_qpointdoes 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
ValueErrorfrom the implementation module as well as throughcrystod.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.resolve_setting(table, spec)[source]#
The setting a user names.
- Parameters:
table (SettingTable) – The settings of the group (
list_space_group_settings()).spec – The 1-based No. of the setting, its choice string (
-cba,b2,2,R,2ba-c), its symbol (spaces ignored, also without/and_:Amam,A m a m,P21n), its full symbol, or its file-name tag (P21n_b2).
- Returns:
The matching
SpaceGroupSetting.- Raises:
ValueError – The symbol is shared by several settings (the message lists them: give the No. or the choice), or nothing matches (the message lists every setting).
- Return type:
Example
>>> from crystod import group >>> table = group.list_space_group_settings( ... ([[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[0, 0, 0]], [1])) >>> group.resolve_setting(table, "1").symbol 'Pmmm'
- crystod.group.secondary_order_parameters(space_group, irreps, direction, max_degree=4)[source]#
Secondary order parameters of an order-parameter direction.
- Parameters:
space_group – Parent space-group number or international symbol.
irreps – One ISO-IR label (
"R4+") or a list for coupled order parameters (["R4+", "M3+"]).direction – The order-parameter components, as
--order-parametertakes them: a string ("a 0 0","a;0;0") or a list of tokens, one per component (all primary irreps, in order).max_degree (int) – Highest total degree of the coupling terms searched (default 4).
- Returns:
A list of
SecondaryOrderParameterrecords (the primary irreps included, withkind == "primary"), Gamma first, then the other tabulated special k points.- Raises:
SystemExit – Unknown space group or irrep, or a direction with the wrong number of components (
ValueErrorthroughcrystod.group).
Example
>>> from crystod import group >>> rows = group.secondary_order_parameters( ... "I4/mmm", ["X2+", "X3-"], "0 a 0 c") >>> [(r.label, r.coupling) for r in rows if r.kind == "polar"] [('GM5-', 'Q1^1 Q2^1 eta')]
- 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 spinS = 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 ofcrystod.group.get_character_table(the same object thatparse_configtakes).irrep (str) – Label of the shell irrep, e.g.
"T2g".n_electrons (int) – Number of electrons in the shell,
1to twice the irrep dimension.
- Returns:
Terms as
(S, irrep, count)with the total spinSaFraction(2S+1is the multiplicity of the term symbol) andcountthe number of times the term occurs.- Raises:
SystemExit –
n_electronsoutside1 .. 2 * dim(ValueErrorwhen called throughcrystod.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.spin_orbit_relations(sg, k=None)[source]#
Single-valued small irreps and the double-valued ones they become.
The computation behind
crystod-group --correlate-double-group --sg SG [--kpoint K]: for every single-valued (spinless) small irrep Gamma at k, the double-valued (spinor) small irreps of Gamma x D(1/2), i.e. what a level of a scalar-relativistic band structure becomes when spin-orbit coupling is switched on. The single-valued labels are the ISO-IR labels of every othercrystod-groupmode and the double-valued names those ofcrystod --spinor(-R6+; Bradley & Cracknell’s numbering with the exceptions ofcrystod.wavecar_irreps.double_valued_names).- Parameters:
sg – Space-group number or international symbol.
k – The ISO-IR name of a special point (
"R";GandGAMMAmeanGM), three primitive coordinates (numbers, or strings such as"1/2"; any arm of a star, any k + G), orNonefor every tabulated special point of the group. Coordinates off the special points give the relations on that symmetry line or plane or at that general point, at the coordinates given, reduced into (-1, 1) by an integer and snapped onto fractions with denominators up to 48 within 1e-6 (0.1000001is 1/10).
- Returns:
k point by k point in the order of the ISO-IR tables, and in table order at each special point (natural order off them).
- Return type:
SpinOrbitRelationrecords, one per single-valued small irrep- Raises:
SystemExit – Unknown space group or k-point name, or a malformed k point (
ValueErrorthroughcrystod.group).RuntimeError – An internal consistency check failed (labels of another k point or another frame, multiplicities that violate the dimension or reciprocity checks).
Example
>>> from crystod import group >>> rows = group.spin_orbit_relations("Pm-3m", "R") >>> [(r.irrep, r.dimension, r.double_irreps) for r in rows][3] ('R4+', 3, [('-R6+', 1), ('-R8+', 1)])
- crystod.group.subgroup_correlation(supergroup_file, subgroup_file, tolerance=0.01, spinor=False)[source]#
Correlation of the irreps of a supergroup and a subgroup structure.
The computation behind
crystod-group --correlate --supergroup-poscar P --subgroup-poscar C(the offline counterpart of DCORREL of the Bilbao Crystallographic Server): for every special k point of the supergroup G (the points ofcrystod-bz --show-kpoint), the small irreps of the subgroup H, the space group of the subgroup structure, that every irrep of G becomes.How it works:
SymmetryModeAnalysismaps the subgroup structure onto the supergroup structure (sublattice basis B, origin, the operations of H as parent operations); H is re-expressed in the basis B (isotropy_subgroup.sublattice_operations) and identified by spglib through a generic orbit (it must be the space group of the file).The labels of H refer to the ISO-IR frame of the subgroup structure file (
crystod.isoir.canonical_iso_frame, the frame of every other command on that file), carried onto the basis B; when the frame cannot be carried over, that of a generic orbit of H.Arm a of a parent irrep (the full induced irrep of
InducedRepresentation, complex matrices before realification) carries k’_a = B q_a of H; the arms with equal k’ modulo the reciprocal lattice of H form a sector, the sectors are grouped into stars of H, and the character tr(P_sector D(g)) on the little group of k’ in H (evaluated at the parent operation whose translation is the one given to the labeler) is decomposed into the small irreps of H withIsoIRLabeler.decompose_characters.Checks: the character at the identity is the sector dimension, the dimensions add up per sector and over all stars of H to that of the parent irrep, every label carries the k name of its sector, and all sectors of one star of H give the same decomposition.
- Parameters:
supergroup_file – The high-symmetry structure (POSCAR or CIF).
subgroup_file – The low-symmetry structure of the same compound (POSCAR or CIF), whose space group is H.
tolerance – Symmetry tolerance (symprec, Angstrom) for both files.
spinor – Also correlate the double-valued (spinor) irreps (
--spinor): after the single-valued rows of every block, oneIrrepCorrelationwithdouble_valued=Trueper double-valued irrep of G (a time-reversal pair once, asA/B), named ascrystod --spinorand--correlate-double-groupname them (G in the frame of that command, H in the frame of the single-valued labels of H). Characters only: the arm characters chi(g^-1 h g) of the double-valued small irreps of G (spgrep, with the SU(2) sign of the conjugation) summed over a sector are decomposed into the double-valued small irreps of H, whose SU(2) matrices are those of G (one Cartesian frame, checked per operation). Checks as for the single-valued rows, and Res_H(Gamma x D(1/2)) = Res_H(Gamma) x D(1/2) for every single-valued irrep Gamma of G on every arm of H.
- Returns:
A
SubgroupCorrelation.- Raises:
SystemExit – A file is missing or unreadable, or the subgroup structure cannot be mapped onto the supergroup structure (
ValueErrorthroughcrystod.group).RuntimeError – An internal consistency check failed.
- Return type:
Example
>>> from crystod import group >>> result = group.subgroup_correlation("POSCAR_SrTiO3_Pm-3m", ... "POSCAR_SrTiO3_I4mcm") >>> rows = {(b.parent_k_name, b.child_k_name, r.parent_irrep): r.child_irreps ... for b in result.blocks for r in b.rows} >>> rows["R", "GM", "R4+"] [('GM1+', 1, 1), ('GM5+', 1, 2)] >>> rows["X", "M", "X1+"] [('M3+', 1, 1)]
- crystod.group.subgroup_graph(parent, irreps)[source]#
The group-subgroup graph of the isotropy subgroups of some irreps.
The data behind
crystod-group --parent SG --irrep IR [IR2 ...] --graph: the parent, every stratum of the (direct sum) representation, including those in which only some irreps condense, and the kernel, joined by the group-subgroup inclusions up to conjugacy, transitively reduced.- Parameters:
parent – Symbol (
"Pm-3m") or number of the parent space group.irreps – One ISO-IR label (
"R4+") or a list of labels (["R4+", "M3+"]).
- Returns:
- Raises:
SystemExit – Unknown space group or irrep (
ValueErrorthroughcrystod.group).- Return type:
Example
>>> from crystod import group >>> graph = group.subgroup_graph("Pm-3m", "R4+") >>> [node.label for node in graph.nodes] ['Pm-3m (221)', 'I4/mcm (140)', 'R-3c (167)', 'Imma (74)', 'C2/m (12)', 'C2/c (15)', 'P-1 (2)'] >>> len(graph.edges) 10
- crystod.group.symmetric_square(ct, point_group, irrep)[source]#
Decomposition of the symmetrized square
[Gamma x Gamma].The computation behind
crystod-group --product IR IR --pg PG --symmetric: the character(chi(g)^2 + chi(g^2)) / 2of the symmetric part ofGamma x Gamma(the irreps of quadratic forms in the components ofGamma, of the Jahn-Teller coupling of a degenerate level, and of the orbital part of two-electron spin singlets), reduced into the irreps of the point group.- Parameters:
ct (dict) – Character table from
crystod.group.get_character_table.point_group (str) – Point-group label (used in the error message only).
irrep (str) – Label of the irrep, e.g.
"T2g".
- Returns:
{irrep label: multiplicity}over every irrep of the table (zeros included), asdecompose_representationreturns it.- Raises:
SystemExit – The irrep label is not in the table (
ValueErrorwhen called throughcrystod.group).- Return type:
dict[str, int]
Example
>>> from crystod import group >>> ct = group.get_character_table("m-3m") >>> {k: n for k, n in group.symmetric_square(ct, "m-3m", "T2g").items() if n} {'A1g': 1, 'Eg': 1, 'T2g': 1}
- crystod.group.symmetrize_tensor(tensor, kind, cell, site=None, *, symprec=1e-05)[source]#
Project a tensor onto its symmetry-allowed form (group average).
The average
(1/|G|) sum_g g.T(with the intrinsic index symmetry ofkind) is the orthogonal projection onto the allowed tensors in the Frobenius metric, soT - symmetrize_tensor(T)is the part ofTthat breaks the symmetry. The tensor is given, and returned, as a full Cartesian array in the frame ofcell.- Parameters:
tensor – The tensor, shape
(3,) * rank; or one tensor per atom of the cell, shape(n_atoms,) + (3,) * rank(Born effective charges, internal-strain tensors), averaged over the space group with the atoms mapped by every operation.kind (str) – A kind of
crystod-group --tensor(dielectric,piezoelectric-e,elastic, …) or a Jahn symbol (V2,V[V2],[[V2]2]; prefixeaxial). A time-odd kind (prefixa) vanishes: the group of a non-magnetic crystal contains time reversal.cell – A POSCAR path, a
PhonopyAtoms, a(lattice, positions, symbols)tuple, or atensor_form.PointGroupSetting(the point group alone, e.g.point_group_setting("6mm"); the tensor is then in its axes, or in the input frame of a setting made from a structure).site – None for a crystal tensor; an atom index (0-based) to average one site tensor over the site-symmetry group of that atom.
symprec (float) – spglib tolerance (Angstrom) for a structure.
- Returns:
The symmetrized tensor, same shape as
tensor.- Raises:
ValueError – The shape does not fit the kind, or the structure cannot be analysed (
SystemExitfor an unknown kind is reported asValueErrorthroughcrystod.group).
Example
>>> import numpy as np >>> from crystod.tensor_form import point_group_setting >>> from crystod.vasp_symmetry import symmetrize_tensor >>> eps = np.array([[2.0, 0.1, 0.0], [0.1, 2.2, 0.0], [0.0, 0.0, 3.0]]) >>> symmetrize_tensor(eps, "dielectric", point_group_setting("4/mmm")).round(3) array([[2.1, 0. , 0. ], [0. , 2.1, 0. ], [0. , 0. , 3. ]])
- crystod.group.tensor_form(point_group=None, kind='dielectric', *, space_group=None, cell=None, symprec=1e-05)[source]#
The symmetry-allowed form of a property tensor (Neumann’s principle).
- Parameters:
point_group (str | None) – Hermann-Mauguin point-group symbol (
"4mm"); or givespace_grouporcellinstead.kind (str) –
dielectric,pyroelectric,piezoelectric(Nye’s d),piezoelectric-e(e, no factor 2),elastic,compliance,gyrationor a Jahn symbol ("V[V2]","e[V2]","[[V2]2]"; prefixafor a time-odd tensor, which vanishes in every non-magnetic point group).ramangives the symmetric second-rank form; the per-irrep Raman tensors areraman_forms().space_group – Space-group symbol or number; its point group in the default setting.
cell – POSCAR path or
PhonopyAtoms; its point group in the standard conventional setting (the axes ofPointGroupSetting.input_axes).symprec (float) – Symmetry tolerance of the structure route.
- Returns:
A
TensorForm(independent,relations,matrix).- Raises:
SystemExit – Unknown point group or kind, or not exactly one group source (
ValueErrorthroughcrystod.group).- Return type:
Example
>>> from crystod import group >>> form = group.tensor_form("6/mmm", "elastic") >>> form.independent, form.relations[-1] (('c11', 'c12', 'c13', 'c33', 'c44'), 'c66 = (c11-c12)/2')
- crystod.group.transform_to_setting(cell, spec, symprec=0.01)[source]#
The conventional cell of a structure in a chosen setting.
- Parameters:
cell –
(lattice, frac, numbers)as spglib takes it.spec – The setting, as
resolve_setting()takes it.symprec (float) – Symmetry tolerance (Angstrom).
- Returns:
the
SpaceGroupSettingand the idealized conventional cell of it (the cell--cif2poscar --spacegroup-setwrites).- Return type:
(setting, std_lattice, std_positions, std_numbers)- Raises:
ValueError – As
list_space_group_settings()andresolve_setting().
Example
>>> from crystod import group >>> setting, lattice, positions, numbers = group.transform_to_setting( ... ([[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[0, 0, 0]], [1]), "Pmmm") >>> len(numbers) 1
- crystod.group.vasp_symmetry_report(path, *, outcar=None, cell=None, only=None, symprec=1e-05)[source]#
Check the response tensors of a VASP run against the symmetry of its structure.
- Parameters:
path (str) – The
vasprun.xmlor theOUTCARof the run (either may be gzipped).vasprun.xmlholds Z* and the dielectric tensors; the piezoelectric, elastic and internal-strain tensors are only in theOUTCAR.outcar (str | None) – The
OUTCARthat completes avasprun.xml(its Z* and dielectric tensors are compared with those of thevasprun.xml, which win).cell – The structure: a POSCAR path or a
PhonopyAtomswith the atoms in the order of the run. Default: the initial structure of thevasprun.xml, or thePOSCARnext to theOUTCAR.only – Tensor groups to check, any of
born,dielectric,piezo,elastic,strain(a list or a comma-separated string; default all).symprec (float) – spglib tolerance (Angstrom).
- Returns:
- Raises:
SystemExit – Missing or unreadable files, a structure that does not match the run, or none of the selected tensors in the files (
ValueErrorthroughcrystod.group).- Return type: