crystod.mag

Contents

crystod.mag#

Public magnetism API of CrystOD: the crystod-mag domain.

This module covers the symmetry analysis of spin arrangements. The spins on the sites of one element are treated as axial-vector degrees of freedom, the 3N-dimensional spin space is decomposed into irreps of the space group at a q point, and the resulting symmetry-adapted spin bases (cluster multipoles / symmetry-adapted multipole moments, SAMM, after M.-T. Suzuki et al., Phys. Rev. B 95, 094406 (2017) and Phys. Rev. B 99, 174407 (2019)) are classified as ferromagnetic (cluster dipole) or antiferromagnetic (net moment zero). At q = 0 an AFM basis is named after the next rank at which its irrep occurs in the magnetic multipole representations: octupole, 32pole, … for an irrep even under the inversion, quadrupole, hexadecapole, … for an odd one (the magnetic multipole of rank p has parity (-1)**(p + 1); Cr2O3, Cr: GM1- quadrupole, GM2- hexadecapole, GM1+ octupole). It mirrors the crystod-mag command, whose spin listings, VESTA exports and noncollinear magnetization input (VASP MAGMOM, Quantum ESPRESSO starting_magnetization/angle1/angle2) are built from these functions; the implementation lives in crystod.spin_basis.

Spin representation (crystod-mag --qpoint, and the survey over all special k points when --qpoint is omitted)

  • get_spin_representation: the little-group irreps at q and the axial-vector representation on the selected sites, ready for spgrep.representation.project_to_irrep.

Multipole classification (crystod-mag at q = 0)

  • get_multipole_rank_lists: for every irrep, the ranks of the magnetic multipoles (dipole, quadrupole, octupole, …) in which it appears.

  • separate_ferro_combination: splits the net-moment combination (FM, cluster dipole) off the projected spaces of one irrep; the rest are AFM. analyze_spin_basis falls back on the real form of the irrep when the copies spgrep gives (in a complex basis for the E irreps of trigonal and hexagonal crystals) do not separate cleanly, and turns the partners of all copies onto directions that symmetry fixes.

  • MULTIPOLE_NAMES: rank-to-name table (1: "dipole", 3: "octupole", …).

Magnetic groups and collinear classes (crystod-mag --qpoint, every exported component; --classify-only for the table alone)

  • analyze_spin_basis: the whole q-point analysis as data (SpinBasisAnalysis: decomposition, bases, the real spin field of every component and its magnetic group, responses and class); magnetic_summary_rows gives the rows of the summary table and magnetic_summary_notes the notes under it. At q != 0 SpinBasisAnalysis.directions lists the order-parameter directions of every basis in the magnetic cell (OrderParameterDirection: ISOTROPY’s label, magnetic isotropy subgroup, size, index, free parameters, the exported component, the coefficients in the basis components); direction_table_rows and format_direction_table give the * Order-parameter directions * block. With analyze_spin_basis(..., subgroup_poscar=CHILD) (crystod-mag --subgroup-poscar CHILD), SpinBasisAnalysis.subgroup places the bases at q != 0 on a distorted structure whose cell is a magnetic cell of q (SubgroupAlignment: the transformation of crystod-group --correlate, the folding of every basis onto the GM irreps of CHILD) and aligns every one-parameter direction with its structural domain (SubgroupSpinField rows: the irreps of CHILD a field is made of, its magnetic space group on CHILD, the angle of an aligned domain from the exported component, the moments on the atoms of CHILD); subgroup_table_rows and format_subgroup_alignment give the * Spin bases on the subgroup structure * blocks.

  • magnetic_space_group: magnetic space group of a spin arrangement (spglib): BNS number and symbol, OG number, type I-IV, the magnetic point group derived from the BNS symbol and checked against the operations, and the unified (UNI) symbols of both (MagneticGroupInfo).

  • macroscopic_responses: net magnetization, electric polarization (with a note when the crystal without spins is not polar), linear magnetoelectric and piezomagnetic tensors allowed by the magnetic point group (MagneticResponses); format_magnetic_responses prints them.

  • classify_collinear: ferromagnet, ferrimagnet, conventional antiferromagnet or altermagnet (d/g/i-wave, spin-splitting form, spin-degenerate planes) from the sign pattern of a collinear arrangement (CollinearClass), after L. Smejkal, J. Sinova and T. Jungwirth, Phys. Rev. X 12, 031042 (2022).

  • magnetic_point_group_symbol: the MPG symbol of a BNS symbol.

  • unified_symbol: the UNI symbol of a BNS number (B. J. Campbell, H. T. Stokes, J. M. Perez-Mato and J. Rodriguez-Carvajal, Acta Cryst. A78, 99 (2022)); unified_point_group_symbol: the UNI symbol of an MPG.

Phonon angular momentum (crystod-mag --qpoint ... --phonon-angular-momentum)

  • phonon_angular_momentum: the texture of the phonon angular momentum l(q) near GM that a magnetic point group allows, from l(A q) = B l(q): for each Cartesian component the lowest degree of a q-polynomial (s, p, d, f, g, … wave), its polynomials and the nodal planes single operations enforce (PhononAngularMomentum, AngularMomentumComponent); plane_normal= restricts q to a plane (a layer: nodal lines); phonon_angular_momentum_degrees: every degree at which a component is allowed (the orders of the angular-momentum current response to a temperature gradient), after L. Zhang and Q. Niu, Phys. Rev. Lett. 112, 085503 (2014).

  • phonon_angular_momentum_rows and format_phonon_angular_momentum: the * Phonon angular momentum allowed by symmetry * block of --classify-only (the paramagnetic crystal first, paramagnetic_point_group, then every component).

Several magnetic elements and superpositions (crystod-mag --element A B --qpoint ..., --superpose N ... --coefficients c ...)

  • analyze_multi_element(cell, ["Al", "Ni"], "GM"): the spin bases of every element (as the single-element runs), the decomposition per element and in total, the copies of one irrep on different elements compared through their representation matrices (CopyRelation), and one copy per element combined along every direction with the relative signs (+,+), (+,-), … (CombinedArrangement with its magnetic space group, responses and class) in a MultiElementAnalysis; multi_summary_rows, format_multi_summary and format_copy_relations print them.

  • superpose_bases(analysis, [1, 16], [1.0, 0.5]): any listed bases (of a single- or multi-element analysis, numbered as the rows of the table of magnetic groups), of any irreps, superposed, with their irrep content and classification (Superposition); component_magmoms gives the moments of one basis on the atoms of the magnetic cell.

Magnetic isotropy subgroups (crystod-mag --parent SG --qpoint K / --irrep IR; no structure file)

  • magnetic_isotropy_subgroups(parent, irrep): every order-parameter direction of one magnetic (time-odd) irrep of the paramagnetic group SG1' with its magnetic isotropy subgroup (MagneticIsotropySubgroup: BNS number and symbol, type, UNI symbol, magnetic point group, unitary subgroup, cell size, index); magnetic_isotropy_subgroups_at_kpoint(parent, kpoint) does every irrep of one k point; MagneticIsotropyAnalyzer exposes the representation, the strata and the stabilizers.

  • coupled_magnetic_isotropy_subgroups(parent, ["R4+", "M3+"]): several irreps at once (--irrep R4+ M3+): the table of every irrep alone and the coupled table, the stabilizers in SG1' of the vectors of the direct sum in which every irrep condenses (CoupledMagneticIsotropySubgroups of CoupledMagneticIsotropySubgroup rows); parities=[+1, -1] makes an irrep time-even (a distortion; theta acts as +D on it), so that a distortion and a magnetic order can be combined (Python only). coupled_magnetic_order_parameter(parent, irreps, tokens) gives the subgroup of one direction (--order-parameter).

Magnetic arrangements of given irreps (crystod-mag -c POSCAR --element EL --irrep IR [IR2 ...])

  • magnetic_irrep_arrangements(cell, ["Mn"], ["R4-", "M3-"]): every row of the table of --parent SG --irrep ... (several irreps: the coupled rows) placed on the sites of the elements: the spin modes that transform with the table’s matrices (one IrrepCopy per copy of the irrep, split by element, Wyckoff orbit and, at q = 0, FM/AFM), the row’s order parameter, the moments in the common magnetic cell and the magnetic group found again on the structure (MagneticIrrepAnalysis of MagneticArrangement rows; order_parameter= builds one direction instead). Writes no files.

A session mirrors the command:

from phonopy.interface.vasp import read_vasp
from spgrep.representation import project_to_irrep
from crystod import mag, phonon

vib = phonon.SymmetryOnlyVibrations(read_vasp("POSCAR"), standardize=False)
sites = [i for i, s in enumerate(vib.primitive_cell.symbols) if s == "Ni"]
q = [0, 0, 0]
irreps, spin_rep, mapping = mag.get_spin_representation(vib, sites, q)
labels = vib.get_irrep_labels(q, irreps, mapping)
ranks = mag.get_multipole_rank_lists(vib, vib.rotations[mapping], irreps)
for irrep, label, rank_list in zip(irreps, labels, ranks):
    spaces = [s.real for s in project_to_irrep(spin_rep, irrep)]
    if spaces:
        ferro, afm = mag.separate_ferro_combination(spaces, spin_rep, len(sites))

Attributes resolve lazily (PEP 562): importing this module is instant, and phonopy/spgrep are loaded on the first attribute access. Bad input raises ValueError here, where the implementation module raises SystemExit.

class crystod.mag.AngularMomentumComponent(axis, degree=None, forms=(), nodal=(), zero_reason='', two_dimensional=False, max_degree=9)[source]#

Bases: object

One Cartesian component l_i(q) of the phonon angular momentum near Gamma, as a magnetic point group allows it.

Variables:
  • axis (str) – "x", "y" or "z" (Cartesian axes of the operations).

  • degree (int | None) – The lowest degree n of a homogeneous polynomial in q that symmetry allows for this component, or None when it vanishes (or no form exists up to the degree searched).

  • forms (tuple) – The polynomials of that degree, one per basis vector of the reduced row-echelon basis of the space of i-th components (("q_x q_y",); ("const",) at degree 0).

  • nodal (tuple) – Unit vectors of the nodes symmetry enforces through Gamma: the normals of the planes (three dimensions) or the directions of the lines (two dimensions), as Cartesian directions (("[100]", "[010]")).

  • zero_reason (str) – Why the component vanishes at every q: "P T", or in two dimensions "the mirror of the layer" / "2' along the layer normal"; empty when it does not vanish.

  • two_dimensional (bool) – True when q is restricted to a plane.

  • max_degree (int) – The highest degree searched.

nodal_text()[source]#

"zero on the planes perpendicular to [100], [010]" ("zero on the lines along ..." in two dimensions), empty without nodes.

Return type:

str

text()[source]#

"l_z ~ q_x q_y (d-wave; zero on the planes perpendicular to [100], [010])", "l_x = 0 (P T)".

Return type:

str

axis: str#
degree: int | None = None#
forms: tuple = ()#
property letter: str#

The wave letter ("s" .. "j"), the degree as a number beyond j ("8"), "-" when the component vanishes.

max_degree: int = 9#
property n_nodal: int#

Number of enforced nodal planes (lines in two dimensions).

nodal: tuple = ()#
property short_name: str#

"d-wave", "degree 8", "none (P T)" or "none up to degree 9".

two_dimensional: bool = False#
zero_reason: str = ''#
class crystod.mag.CollinearClass(name, wave=None, order=None, spin_splitting=(), degenerate_planes=(), degenerate_lines=(), axis=None, n_preserving=0, n_swapping=0, net_moment=None)[source]#

Bases: object

Nonrelativistic class of a collinear spin arrangement.

Variables:
  • name (str) – One of "ferromagnet", "ferrimagnet", "compensated, sublattices not related by symmetry", "antiferromagnet (conventional: a translation exchanges the sublattices, T tau)", "antiferromagnet (conventional: inversion exchanges the sublattices, P T)", "altermagnet" or "noncollinear (not classified)".

  • wave (str | None) – "d-wave", "g-wave" or "i-wave" for an altermagnet, else None.

  • order (int | None) – The even degree l of the wave (2, 4, 6) or None.

  • spin_splitting (tuple) – The lowest-order polynomials in (k_x, k_y, k_z) that symmetry allows for the spin splitting of an altermagnet, in the Cartesian axes of the cell given (("k_x k_y",)).

  • degenerate_planes (tuple) – Normals of the spin-degenerate planes of an altermagnet as Cartesian directions (("[100]", "[010]")).

  • degenerate_lines (tuple) – Spin-degenerate lines that do not lie in one of the planes, as Cartesian directions.

  • axis (numpy.ndarray | None) – The common spin axis (unit Cartesian vector) or None.

  • n_preserving (int) – Number of space-group operations (in the magnetic cell) that keep the sign pattern.

  • n_swapping (int) – Number of operations that reverse it (exchange the sublattices).

  • net_moment (numpy.ndarray | None) – The net moment over the magnetic cell.

text()[source]#

The description printed after collinear order:.

Example: "altermagnet (d-wave; spin splitting allowed by symmetry ~ k_x k_y; spin-degenerate planes perpendicular to [100], [010])".

Return type:

str

axis: ndarray | None = None#
degenerate_lines: tuple = ()#
degenerate_planes: tuple = ()#
n_preserving: int = 0#
n_swapping: int = 0#
name: str#
net_moment: ndarray | None = None#
order: int | None = None#
property short_name: str#

"altermagnet (d-wave)", "antiferromagnet (P T)", "ferromagnet".

Type:

Short form for tables

spin_splitting: tuple = ()#
wave: str | None = None#
class crystod.mag.CombinedArrangement(label, copies, tag, signs, magmoms, field, net_moment, group=None, responses=None, collinear=None, direction_label=None, vesta_name='')[source]#

Bases: object

One copy per element of one irrep, along one order-parameter direction, with relative signs.

Variables:
  • label (str) – The irrep label.

  • copies (tuple) – (element, header) of the copy of every element.

  • tag (str) – The direction: the tag of the component of the representative copy it follows ("x", "111", "comp1", "dir2").

  • signs (tuple) – +1 / -1 of every element’s copy (the first +1).

  • magmoms (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Moments of every atom of the magnetic cell, (n_atoms, 3) (each element’s part with largest moment 1, times its sign).

  • field (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – The same on the selected sites, (n_cells, n_sites, 3) (sites in the order of MultiElementAnalysis.site_indices).

  • net_moment (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Net moment over the magnetic cell.

  • group (object) – crystod.magnetic_group.MagneticGroupInfo or None.

  • responses (object) – crystod.magnetic_group.MagneticResponses or None.

  • collinear (object) – crystod.magnetic_group.CollinearClass or None.

  • direction_label (str | None) – ISOTROPY’s label of the direction at q != 0 (that of the representative component), else None.

  • vesta_name (str) – The VESTA file written, empty when none (beyond COMBINED_FILE_CAP).

collinear: object = None#
property component_text: str#

"x (+,-)".

copies: tuple#
direction_label: str | None = None#
property elements_text: str#

"Al+Ni".

field: ndarray[tuple[Any, ...], dtype[float64]]#
group: object = None#
property header: str#

"GM4+(3) [Al FM, dipole + Ni AFM, octupole]".

label: str#
magmoms: ndarray[tuple[Any, ...], dtype[float64]]#
net_moment: ndarray[tuple[Any, ...], dtype[float64]]#
responses: object = None#
property sign_text: str#

"(+,-)".

signs: tuple#
tag: str#
vesta_name: str = ''#
class crystod.mag.CopyRelation(label, reference, copy, map, identity, residual)[source]#

Bases: object

How the basis rows of one copy of an irrep relate to those of the representative copy (the first element that has the irrep).

Variables:
  • label (str) – The irrep label ("GM4+(3)").

  • reference (tuple) – (element, header) of the representative copy.

  • copy (tuple) – (element, header) of this copy.

  • map (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – The (d, d) matrix T with D_copy(g) T = T D_reference(g) for every operation (c -> T c takes the coefficients of a direction in the rows of the reference to those in the rows of this copy), normalized to the largest entry 1; None when no intertwining map was found.

  • identity (bool) – True when the copy has the same matrices on its rows (T is the identity).

  • residual (float) – Largest deviation of D_copy T - T D_reference (and of the row spans from being invariant).

text()[source]#

"same matrices on the rows" or "rows mapped by (x, y, -z)".

Return type:

str

copy: tuple#
identity: bool#
label: str#
map: ndarray[tuple[Any, ...], dtype[float64]] | None#
reference: tuple#
residual: float#
class crystod.mag.CoupledMagneticIsotropySubgroup(irreps, direction, components, bns_number, bns_symbol, msg_type, uni_symbol, og_number, magnetic_point_group, unitary_number, unitary_symbol, size, index, n_free, n_operations)[source]#

Bases: object

One row of a coupled (or single-irrep) magnetic table.

Variables:
bns_number: str#
bns_symbol: str#
components: tuple#
direction: str#
index: int#
irreps: tuple#
property label: str#

The first column of the table (the direction label).

magnetic_point_group: str#
msg_type: int#
n_free: int#
n_operations: int#
og_number: str#
size: int#
property subgroup: str#

"127.394 P4/m'bm", the second column of the table.

property type_name: str#

The type as a Roman numeral.

uni_symbol: str#
unitary_number: int#
unitary_symbol: str#
class crystod.mag.CoupledMagneticIsotropySubgroups(parent, parent_number, irreps, parities, dimensions, singles, coupled, parts=<factory>)[source]#

Bases: object

The result of coupled_magnetic_isotropy_subgroups().

Variables:
  • parent (str) – Short symbol of the parent space group.

  • parent_number (int) – Its number.

  • irreps (list) – The irrep labels as printed (with m for the time-odd ones when the parities are mixed).

  • parities (list) – -1 (time-odd) or +1 (time-even) per irrep.

  • dimensions (list) – The order-parameter dimension of every irrep.

  • singles (dict) – {label: [rows]}, the table of every irrep alone (letters shifted so that every irrep keeps its own range).

  • coupled (list) – The rows of the coupled table (every irrep condensed); for one irrep, its single table.

  • parts (list) – The representations of the irreps (for the report).

coupled: list#
dimensions: list#
irreps: list#
parent: str#
parent_number: int#
parities: list#
parts: list#
singles: dict#
class crystod.mag.CoupledMagneticOrderParameter(direction, row, basis)[source]#

Bases: object

The magnetic isotropy subgroup of one given (coupled) direction.

Variables:
basis: ndarray#
direction: str#
row: CoupledMagneticIsotropySubgroup#
class crystod.mag.IrrepCopy(irrep, number, element, orbit, kind, rank_name, intertwiner)[source]#

Bases: object

One copy of an irrep in the spin representation of the chosen sites.

Variables:
  • irrep (str) – The irrep label as the tables print it ("GM4+").

  • number (int) – The copy number within the irrep, from 1.

  • element (str) – The element whose sites carry the copy.

  • orbit (str) – The element, with the Wyckoff position when the element has more than one orbit ("La(4e)").

  • kind (str) – "FM" (the cluster dipole at q = 0), "AFM" (net moment zero at q = 0) or "AFM (q != 0)".

  • rank_name (str | None) – The multipole name at q = 0 ("dipole", "octupole"), as the --qpoint report names the bases; None at q != 0.

  • intertwiner (numpy.ndarray) – The spin modes, shape (n_cells, n_sites, 3, d): column j is the field of the j-th order-parameter component, O(g) Psi = Psi D(g), Psi^T Psi proportional to 1.

element: str#
intertwiner: ndarray#
irrep: str#
kind: str#
number: int#
orbit: str#
rank_name: str | None#
property text: str#

the description printed for the copy.

Type:

"Mn [FM, dipole]"

class crystod.mag.MagneticArrangement(number, row, copies, tag, order_parameter, letters=<factory>, coefficients=(), field=None, magmoms=None, net_moment=None, group=None, responses=None, collinear=None, check='', note=None, n_fixing_field=0, n_fixing_order_parameter=0, moment_text='', vesta_name='', fixing_translations=<factory>, weight_reason=None, reproduce=None)[source]#

Bases: object

The magnetic arrangement of one table row (one choice of copies).

Variables:
  • number (int) – The row number of the table, from 1.

  • row (object) – The table row (crystod.magnetic_isotropy_coupled.CoupledMagneticIsotropySubgroup or crystod.magnetic_isotropy.MagneticIsotropySubgroup).

  • copies (tuple) – One IrrepCopy per irrep.

  • tag (str) – "" when every irrep has one copy, else the copy numbers ("c1", "c2-1").

  • order_parameter (numpy.ndarray) – The order parameter used (the irreps’ parts concatenated), the table’s generic representative.

  • letters (dict) – {letter: value} of the free parameters in that vector (least squares on the printed direction label).

  • coefficients (tuple) – The weight of every irrep’s part (--coefficients).

  • field (numpy.ndarray) – The spins on the magnetic sites of the diagonal magnetic cell (supercell_sizes), (n_cells, n_sites, 3), largest moment 1, rounded as written.

  • magmoms (numpy.ndarray) – The moments of every atom of the written cell (POSCAR order of the written supercell; with conventional the conventional cell, the field re-tiled).

  • net_moment (numpy.ndarray) – The sum of the moments over the written cell.

  • group (object) – The magnetic space group found by spglib on the structure (crystod.magnetic_group.MagneticGroupInfo), or None.

  • responses (object) – The responses allowed by its magnetic point group.

  • collinear (object) – Its collinear class.

  • check (str) – "same" (spglib finds the row’s BNS group), "enantiomorph" (the partner type), "different" or "not identified".

  • note (str | None) – A NOTE for the row, or None.

  • n_fixing_order_parameter (n_fixing_field,) – Elements of G1’/T_S that fix the field and the order parameter (equal by construction).

  • moment_text (str) – The line on the sizes of the moments.

  • vesta_name (str) – The VESTA file name.

  • fixing_translations (list) – The translations of the written cell that fix the written moments (fractional, written cell).

check: str = ''#
property check_text: str#

the BNS number found on the structure and the verdict ("139.540 same").

Type:

The check column

coefficients: tuple = ()#
collinear: object = None#
copies: tuple#
field: ndarray = None#
fixing_translations: list#
group: object = None#
letters: dict#
magmoms: ndarray = None#
moment_text: str = ''#
n_fixing_field: int = 0#
n_fixing_order_parameter: int = 0#
net_moment: ndarray = None#
note: str | None = None#
number: int#
order_parameter: ndarray#
reproduce: ndarray = None#
responses: object = None#
row: object#
tag: str#
vesta_name: str = ''#
weight_reason: str | None = None#
class crystod.mag.MagneticGroupInfo(uni_number, bns_number, bns_symbol, og_number, msg_type, parent_number, magnetic_point_group, point_group_checked, n_operations, n_primed, rotations, translations, time_reversals, uni_symbol=None, uni_point_group=None, crystal_rotations=None, confirmed=True)[source]#

Bases: object

The magnetic space group of a spin arrangement.

Variables:
  • uni_number (int | None) – spglib’s serial number of the MSG (1-1651).

  • bns_number (str | None) – BNS number, "136.499".

  • bns_symbol (str | None) – BNS symbol from pymatgen, "P4_2'/mnm'" (a type IV symbol carries the lattice subscript, "P_I4/mnc").

  • og_number (str | None) – Opechowski-Guccione number, "136.5.1161".

  • msg_type (int | None) – 1-4 (type I: no operation with time reversal; II: grey group; III: half of the operations with time reversal, no pure antitranslation; IV: black-white lattice).

  • parent_number (int | None) – The space-group number of the type that spglib reports (for types I, II and III the space group of the unprimed and primed operations together; for type IV the family space group of the BNS symbol).

  • magnetic_point_group (str | None) – The MPG symbol derived from the BNS symbol; followed by "?" when it disagrees with the operations. uni_number, bns_number, bns_symbol, og_number, msg_type, parent_number and magnetic_point_group are None when spglib finds the operations but cannot identify the group (identified False).

  • point_group_checked (bool) – True when the derived symbol generates the same rotations, with the same time-reversal flags, as the operations.

  • n_operations (int) – Number of operations in the cell given (centring and magnetic-cell translations counted).

  • n_primed (int) – Number of those operations combined with time reversal.

  • rotations (numpy.ndarray) – Cartesian rotation matrices, (n_operations, 3, 3), in the frame of the lattice given.

  • translations (numpy.ndarray) – Fractional translations in the cell given.

  • time_reversals (numpy.ndarray) – Boolean time-reversal flag of every operation.

  • uni_symbol (str | None) – The unified (UNI) symbol of B. J. Campbell et al., Acta Cryst. A78, 99 (2022), in the same standard BNS setting: "P4_2'/mnm'" (type III, as BNS), "Pnma.1" (type I), "Pnma.1'" (type II), "P4/mnc.1'_I[I4/mmm]" (type IV: the anti-translation (1/2,1/2,1/2)' and the family space group). Unrelated to uni_number, spglib’s serial number.

  • uni_point_group (str | None) – The UNI symbol of the MPG ("4/mmm.1'", "mmm.1", "4'/mmm'").

  • crystal_rotations (numpy.ndarray | None) – Distinct Cartesian rotations of the point group of the same structure without moments (same tolerance), or None when unknown; macroscopic_responses() compares the electric polarization with it.

  • confirmed (bool) – False when the lattice of the cell given is not invariant under the point group of the crystal and the group could not be identified again in the cell of the translations without time reversal (magnetic_space_group()): it can then be a subgroup of the true group (unconfirmed_note()).

bns_number: str | None#
bns_symbol: str | None#
confirmed: bool = True#
crystal_rotations: ndarray | None = None#
property identified: bool#

False when spglib returned the operations but could not name the group (the identification fields are then None).

magnetic_point_group: str | None#
msg_type: int | None#
n_operations: int#
property n_point_operations: int#

the distinct (rotation, time-reversal) pairs of the operations.

Type:

Order of the magnetic point group

property n_point_primed: int#

Primed elements of the magnetic point group.

n_primed: int#
og_number: str | None#
parent_number: int | None#
point_group_checked: bool#
rotations: ndarray#
time_reversals: ndarray#
translations: ndarray#
property type_name: str#

The type as a Roman numeral ("III"), "-" when the group is not identified.

uni_number: int | None#
uni_point_group: str | None = None#
uni_symbol: str | None = None#
class crystod.mag.MagneticIrrepAnalysis(formula, elements, space_group, space_group_number, irreps, dimensions, kpoints, decompositions, multiplicities, copies, singles, rows, arrangements, coefficients, cell_matrix, supercell_sizes, cell_translations, supercell_lattice, supercell_symbols, supercell_positions, supercell_site_of_atom, supercell_cell_of_atom, site_indices, site_elements, residuals=<factory>, order_parameter_input=None, stratum=None, copy_note=None, unlabelled_kpoints=<factory>, parts=<factory>, conventional_centring=None, conventional_multiples=None, internal_cell_translations=<factory>, conventional_note=None)[source]#

Bases: object

The magnetic arrangements of given irreps on a crystal (crystod-mag -c POSCAR --element EL --irrep IR [IR2 ...]).

Variables:
  • formula (str) – Reduced formula of the primitive cell.

  • elements (list) – The magnetic elements, in the order given.

  • space_group (str) – International symbol; space_group_number its number.

  • irreps (list) – The irrep labels as the tables print them.

  • dimensions (list) – The order-parameter dimension of every irrep.

  • kpoints (dict) – {irrep: (k name, q)}, q one arm in the primitive reciprocal basis of the POSCAR.

  • decompositions (dict) – {k name: [(element or "total", text), ...]}, the survey’s decomposition at the k points of the irreps.

  • multiplicities (dict) – {irrep: {element: m}}.

  • copies (dict) – {irrep: [IrrepCopy, ...]}.

  • singles (dict) – {irrep: [rows]}, the table of every irrep alone (only with several irreps; not exported).

  • rows (list) – The rows exported (the coupled table with several irreps).

  • arrangements (list) – One MagneticArrangement per row and choice of copies, in table order.

  • coefficients (tuple) – The weight of every irrep.

  • cell_translations (cell_matrix,) – The written cell (rows in primitive units) and its primitive translations, common to every row: the diagonal magnetic cell diag(supercell_sizes), or with conventional the conventional cell times conventional_multiples.

  • supercell_sizes (numpy.ndarray) – The diagonal magnetic cell in which the spin modes, the weights and the counts of G1’/T_S are computed (primitive cells along each axis); internal_cell_translations its translations, in the order of the first axis of MagneticArrangement.field.

  • supercell_positions (supercell_lattice, supercell_symbols,) – The atoms of the written cell, atom-major (phonopy’s SPOSCAR order).

  • supercell_cell_of_atom (supercell_site_of_atom,) – Magnetic-site index (or None) and index in cell_translations of every atom.

  • conventional_centring (str | None) – The centring letter with conventional ("I"), else None.

  • conventional_multiples (numpy.ndarray | None) – Conventional cells along each axis of the written cell with conventional, else None.

  • conventional_note (str | None) – With conventional, the NOTE of crystod.spin_basis.conventional_cell_note() when the written cell is not the conventional cell (an input primitive cell off the standard primitive setting); else None.

  • site_indices (list) – The magnetic sites in the primitive cell (element by element).

  • site_elements (list) – The element of every magnetic site.

  • residuals (dict) – The largest |O(g) Psi - Psi D(g)| over all copies and elements ("intertwining") and the largest deviation of Psi^T Psi / c from the unit matrix ("orthonormality").

  • order_parameter_input (list | None) – The tokens of --order-parameter, or None.

  • stratum (int | None) – With --order-parameter, the number of the table row whose stratum (G1’-orbit of directions) holds the given vector.

arrangements: list#
cell_matrix: ndarray#
cell_translations: list#
coefficients: tuple#
conventional_centring: str | None = None#
conventional_multiples: ndarray | None = None#
conventional_note: str | None = None#
copies: dict#
copy_note: str | None = None#
decompositions: dict#
dimensions: list#
elements: list#
formula: str#
internal_cell_translations: list#
irreps: list#
kpoints: dict#
multiplicities: dict#
property n_cells: int#

Number of primitive cells of the written cell.

order_parameter_input: list | None = None#
parts: list#
residuals: dict#
rows: list#
singles: dict#
site_elements: list#
site_indices: list#
space_group: str#
space_group_number: int#
stratum: int | None = None#
supercell_cell_of_atom: list#
supercell_lattice: ndarray#
supercell_positions: ndarray#
supercell_site_of_atom: list#
supercell_sizes: ndarray#
supercell_symbols: list#
unlabelled_kpoints: list#
class crystod.mag.MagneticIsotropyAnalyzer(space_group, irrep_label)[source]#

Bases: IsotropyAnalyzer

Magnetic isotropy subgroups of one irrep of a space group.

The machinery behind crystod-mag --parent SG --irrep IR (and, irrep by irrep, --qpoint K): the IsotropyAnalyzer of crystod-group --parent over the time-odd representation (MagneticRepresentation), whose strata are the magnetic order-parameter directions, with magnetic_subgroup_of() in place of the space-group identification. The stabilizer members are (i, t) pairs where i >= algebra.n_ops marks theta.

Parameters:
  • space_group (str) – Symbol ("Pm-3m") or number of the parent.

  • irrep_label (str) – ISO-IR label ("GM4+"), a pair label ("GM3+GM4+"), or the magnetic spelling of either with a leading m ("mGM4+").

classmethod from_representation(algebra, representation)[source]#

Analyzer over an already-built representation of G (wrapped in a MagneticRepresentation unless it is one).

magnetic_subgroup_of(members)[source]#

Magnetic space group of the stabilizer members.

The translations without theta span the lattice of the subgroup; the operations, one per (coset representative, theta), are expressed in that basis (an anti-translation is the identity with theta and its translation) and identified by spglib on a structure of two generic orbits carrying generic axial moments (moment (-1)^theta det(R) R m).

Parameters:

members – (i, t) pairs of the stabilizer (i >= n_ops: with theta).

Returns:

the crystod.magnetic_group.MagneticGroupInfo, the cell size, [G1’ : H] and the number of operations modulo the unitary translations.

Return type:

(group, size, index, n_operations)

Raises:

SystemExit – spglib finds more or fewer operations than the stabilizer has, or cannot identify the group.

subgroup_of(members)[source]#

The unitary part (the members without theta) as IsotropyAnalyzer.subgroup_of() identifies it.

class crystod.mag.MagneticIsotropySubgroup(irrep, direction, bns_number, bns_symbol, msg_type, uni_symbol, og_number, magnetic_point_group, unitary_number, unitary_symbol, size, index, n_free, n_operations)[source]#

Bases: object

One row of crystod-mag --parent: a magnetic isotropy subgroup.

Variables:
  • irrep (str) – The irrep label ("GM4+"; the pair label of a complex irrep and its conjugate, "GM3+GM4+").

  • direction (str) – The order-parameter direction ("(0,0,a)", ; between the arms of the star).

  • bns_number (str) – BNS number ("123.345").

  • bns_symbol (str) – BNS symbol ("P4/mm'm'"; type IV with the lattice subscript, "I_c4/mcm").

  • msg_type (int) – 1, 3 or 4 (a magnetic isotropy subgroup is never a grey group, type II).

  • uni_symbol (str) – The UNI symbol ("P4/mm'm'", "Pm-3m.1", "I4/mcm.1'_c[P4/mmm]").

  • og_number (str) – Opechowski-Guccione number.

  • magnetic_point_group (str) – Its magnetic point group ("4/mm'm'").

  • unitary_number (int) – Space-group number of the unitary subgroup (the operations without theta), the stabilizer of the order parameter in G.

  • unitary_symbol (str) – Its short Hermann-Mauguin symbol.

  • size (int) – Volume of the primitive cell of the unitary translations, in parent primitive cells.

  • index (int) – [G1’ : H], the number of domains.

  • n_free (int) – Free parameters of the direction.

  • n_operations (int) – Operations of H modulo its unitary translations (as many with theta as without for types III and IV).

bns_number: str#
bns_symbol: str#
direction: str#
index: int#
irrep: str#
property label: str#

"GM4+(0,0,a)", the first column of the table.

magnetic_point_group: str#
msg_type: int#
n_free: int#
n_operations: int#
og_number: str#
size: int#
property subgroup: str#

"123.345 P4/mm'm'", the second column of the table.

property type_name: str#

The type as a Roman numeral ("III").

uni_symbol: str#
unitary_number: int#
unitary_symbol: str#
class crystod.mag.MagneticResponses(magnetization, magnetoelectric, piezomagnetic, magnetization_direction, polarization=None, polarization_direction='none', polarization_note='')[source]#

Bases: object

Macroscopic responses allowed by a magnetic point group.

Variables:
  • magnetization (object) – crystod.tensor_form.TensorForm of the net magnetization (Jahn aeV).

  • magnetoelectric (object) – Form of the linear magnetoelectric tensor P_i = alpha_ij H_j (Jahn aeV2).

  • piezomagnetic (object) – Form of the piezomagnetic tensor M_i = Lambda_ijk sigma_jk (Jahn aeV[V2]).

  • magnetization_direction (str) – "none", "along z", "in the xy plane", "any direction" (directions in the Cartesian axes of the cell given).

  • polarization (object) – Form of the electric polarization (Jahn V, time-even: allowed when the point group of the spatial parts is polar); None when not computed.

  • polarization_direction (str) – Its direction, in the words of magnetization_direction.

  • polarization_note (str) – " (induced by the spin order)" when the crystal without spins allows no polarization, " (the crystal without spins: along z)" when it allows fewer components, else empty (also when the crystal is not known).

summary()[source]#

One-line summary: "net magnetization along z; electric polarization none; linear magnetoelectric effect none; piezomagnetism 2 components".

Return type:

str

magnetization: object#
magnetization_direction: str#
magnetoelectric: object#
property n_magnetization: int#

Independent components of the net magnetization.

property n_magnetoelectric: int#

Independent components of the linear magnetoelectric tensor.

property n_piezomagnetic: int#

Independent components of the piezomagnetic tensor.

property n_polarization: int#

Independent components of the electric polarization.

piezomagnetic: object#
polarization: object = None#
polarization_direction: str = 'none'#
polarization_note: str = ''#
class crystod.mag.MultiElementAnalysis(elements, analyses, site_indices, decomposition, relations=<factory>, combined=<factory>, numbered=<factory>, notes=<factory>)[source]#

Bases: object

The spin bases of several elements at one q point.

Variables:
  • elements (list) – The elements, in the order given.

  • analyses (list) – One crystod.spin_basis.SpinBasisAnalysis per element (the element-pure bases, as the single-element runs).

  • site_indices (list) – The selected sites of the primitive cell (all elements), in increasing order.

  • decomposition (dict) – {irrep label: multiplicity} of the direct sum.

  • relations (list) – CopyRelation of every copy of an irrep that occurs on two or more elements.

  • combined (list) – The CombinedArrangement list.

  • numbered (list) – (element, component) of every listed basis in the order of its number (1-based).

  • notes (list) – NOTE lines.

analysis_of(element)[source]#

The analysis of one element.

analyses: list#
property base#

The analysis of the first element (the magnetic cell, the q point and the crystal are those of every element).

combined: list#
decomposition: dict#
elements: list#
notes: list#
numbered: list#
relations: list#
site_indices: list#
class crystod.mag.OrderParameterDirection(entry_index, label, direction_label, bns_number, bns_symbol, size, index, n_free, component=None, coefficients=None, realized=True)[source]#

Bases: object

One order-parameter direction (stratum) of a spin basis at q != 0.

The rows of the * Order-parameter directions * block of crystod-mag --qpoint (SpinBasisAnalysis.directions).

Variables:
  • entry_index (int) – Index of the basis in SpinBasisAnalysis.entries (the first basis of the irrep for a table row that the magnetic cell does not realize).

  • label (str) – The irrep label of the basis ("K3(1)").

  • direction_label (str | None) – ISOTROPY’s label of the direction ("K3(a;0.974a)", several joined by " or " when the cell cannot tell them apart), or None when the q point has no table or no row matches.

  • bns_number (str | None) – BNS number of the magnetic isotropy subgroup ("193.255"): of the spin field of the exported component, or of the table row for a direction that is not exported; None for a direction with more than one free parameter that the table does not name, and without classification.

  • bns_symbol (str | None) – Its BNS symbol ("P6_3/m'cm"), or None.

  • size (int | None) – Volume of the lattice of the translations (without time reversal) that keep the direction, in primitive cells.

  • index (int | None) – Number of domains, [G1’ : H] (the whole paramagnetic group G1’, not only the operations that keep the star arm).

  • n_free (int) – Free parameters of the direction.

  • component (str | None) – Tag (file_tag) of the exported component in this stratum ("comp1", "aa0", "dir1"), else None (a direction with more than one free parameter, or a table row the magnetic cell does not realize).

  • coefficients (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Coefficients of the one-parameter direction in the basis of the exported basis components (comp1 .. comp<n> or x/y/z, as printed in the listing and the MAGMOM lines: spin field = sum_k c_k field_k), unit length; None for n_free >= 2.

  • realized (bool) – False for a table row that no direction of the magnetic cell realizes (a direction over several star arms whose arms are not all in the cell).

bns_number: str | None#
bns_symbol: str | None#
coefficients: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
component: str | None = None#
direction_label: str | None#
entry_index: int#
index: int | None#
label: str#
n_free: int#
realized: bool = True#
size: int | None#
property subgroup: str | None#

"193.255 P6_3/m'cm" or None.

class crystod.mag.PhononAngularMomentum(components, pt_symmetric, plane_normal=None, in_plane=(), max_degree=9)[source]#

Bases: object

The phonon angular momentum l(q) near Gamma allowed by a magnetic point group, component by component (phonon_angular_momentum()).

Variables:
  • components (tuple) – Three AngularMomentumComponent (l_x, l_y, l_z).

  • pt_symmetric (bool) – True when the group contains P T (l = 0 at every q).

  • plane_normal (numpy.ndarray | None) – The normal of the plane q is restricted to (two dimensions), or None.

  • in_plane (tuple) – The names and Cartesian unit vectors of the two in-plane coordinates in two dimensions ((("q_x", [1, 0, 0]), ...)), else empty.

  • max_degree (int) – The highest degree searched.

component(axis)[source]#

The component "x", "y" or "z".

Return type:

AngularMomentumComponent

text()[source]#

The three components joined by "; " (the line phonon angular momentum: of crystod-mag).

Return type:

str

components: tuple#
in_plane: tuple = ()#
max_degree: int = 9#
plane_normal: ndarray | None = None#
pt_symmetric: bool#
class crystod.mag.SpinBasisAnalysis(element, space_group, space_group_number, site_indices, site_positions, qpoint_label, qpoint, is_gamma, decomposition, total_dim, entries, supercell_sizes, cell_matrix, conventional_centring, conventional_multiples, cell_translations, supercell_lattice, supercell_symbols, supercell_positions, supercell_site_of_atom, components=<factory>, formula='', symbols=<factory>, pair_labels=<factory>, primitive_lattice=None, conventional_lattice=None, parent_rotations=None, parent_translations=None, supercell_cell_of_atom=<factory>, directions=<factory>, direction_notes=<factory>, subgroup=None, conventional_note=None)[source]#

Bases: object

The symmetry-adapted spin bases at one q point, with their magnetic groups and collinear classes (what crystod-mag --qpoint prints).

Variables:
  • element (str) – The magnetic element.

  • space_group (str) – International symbol of the space group.

  • space_group_number (int) – Its number.

  • site_indices (list) – Indices of the magnetic sites in the primitive cell.

  • site_positions (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Their fractional positions.

  • qpoint_label (str) – Name of the q point ("GAMMA", "X").

  • qpoint (list) – Its primitive reciprocal coordinates.

  • is_gamma (bool) – True at q = 0.

  • decomposition (dict) – {irrep label: multiplicity} of the spin representation, in the order of the irreps; at a time-reversal-invariant q a complex irrep and its conjugate count once under their pair label ("GM3+GM4+(2)").

  • total_dim (int) – Sum of the projected dimensions (3 N normally).

  • entries (list) – The bases: (label, kind, rank_name, space) with the basis array space of shape (dim, 3 N).

  • supercell_sizes (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.int64]]) – Diagonal of the commensurate magnetic supercell.

  • cell_matrix (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.int64]]) – The magnetic (display) cell in primitive units, rows.

  • conventional_centring (str | None) – The centring letter with conventional, else None.

  • conventional_multiples (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.int64]] | None) – Conventional cells along each axis, or None.

  • cell_translations (list) – Primitive translations inside the magnetic cell.

  • supercell_lattice (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Lattice of the magnetic cell (rows, Angstrom).

  • supercell_symbols (list) – Symbols of the atoms of the magnetic cell.

  • supercell_positions (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Their fractional positions.

  • supercell_site_of_atom (list) – Magnetic-site index of every atom, or None.

  • components (list) – The exported components (SpinBasisComponent), in output order.

  • formula (str) – Reduced formula (file names).

  • symbols (list) – Symbols of the primitive cell.

  • pair_labels (list) – The labels of the complex irreps merged with their conjugates ("GM3+GM4+(2)", "Z3+Z4+(2)") that have a basis.

  • primitive_lattice (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Lattice of the primitive cell (rows, Angstrom).

  • conventional_lattice (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Lattice of its conventional cell (rows), the frame of the operation symbols of parent_operations().

  • parent_rotations (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Cartesian rotations of the space group of the crystal, one per coset of its translations.

  • parent_translations (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Their Cartesian translations (Angstrom).

  • supercell_cell_of_atom (list) – Index into cell_translations of the cell of every atom of the magnetic cell. The atoms are atom-major (phonopy’s SPOSCAR order): each atom of the primitive cell followed by its images in the other cells.

  • directions (list) – At q != 0, the order-parameter directions (strata) of every basis in the magnetic cell (OrderParameterDirection), with ISOTROPY’s labels at a special point, followed for each irrep by the table rows the magnetic cell does not realize; empty at q = 0.

  • direction_notes (list) – Bases whose directions could not be enumerated.

  • subgroup (object) – With a subgroup structure (crystod-mag --subgroup-poscar CHILD, analyze_spin_basis(..., subgroup_poscar=CHILD)), the bases placed on it and aligned with its structural domain (SubgroupAlignment); else None.

  • conventional_note (str | None) – With conventional, the NOTE of conventional_cell_note() when the written cell is not the conventional cell (an input primitive cell off the standard primitive setting); else None.

cell_matrix: ndarray[tuple[Any, ...], dtype[int64]]#
cell_translations: list#
components: list#
conventional_centring: str | None#
conventional_lattice: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
conventional_multiples: ndarray[tuple[Any, ...], dtype[int64]] | None#
conventional_note: str | None = None#
decomposition: dict#
direction_notes: list#
directions: list#
element: str#
entries: list#
formula: str = ''#
is_gamma: bool#
property n_sites: int#

Number of magnetic sites in the primitive cell.

pair_labels: list#
parent_rotations: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
parent_translations: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
primitive_lattice: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
qpoint: list#
qpoint_label: str#
site_indices: list#
site_positions: ndarray[tuple[Any, ...], dtype[float64]]#
space_group: str#
space_group_number: int#
subgroup: object = None#
supercell_cell_of_atom: list#
supercell_lattice: ndarray[tuple[Any, ...], dtype[float64]]#
supercell_positions: ndarray[tuple[Any, ...], dtype[float64]]#
supercell_site_of_atom: list#
supercell_sizes: ndarray[tuple[Any, ...], dtype[int64]]#
supercell_symbols: list#
symbols: list#
total_dim: int#
class crystod.mag.SpinBasisComponent(entry_index, label, kind, rank_name, tag, field, net_moment=None, group=None, responses=None, collinear=None, file_tag='', vesta_name='', direction_label=None, direction_subgroup=None, direction=None, stratum=None)[source]#

Bases: object

One exported component of a symmetry-adapted spin basis.

Variables:
  • entry_index (int) – Index of the basis in SpinBasisAnalysis.entries.

  • label (str) – The ISO-IR irrep label ("GM4+(3)").

  • kind (str) – "FM", "AFM" or "AFM (q != 0)".

  • rank_name (str | None) – Multipole name at q = 0 ("dipole"), else None.

  • tag (str) – Component name as in the VESTA file name: "x", "y", "z", "111", "1m10" for collinear components, else "comp<N>" (the N-th basis vector of the space, counted from 1); a combination of the components of a two- or three-dimensional space is exported next to them (_combined_components()): its (a,a) or (a,a,0) direction where symmetry singles it out ("110" for x and y, "x" for 1m10 and 110, "aa" for two z components, "aa0" for comp1 and comp2), and the (a,a,a) direction ("111" for x + y + z, "aaa"). At a q that is not time-reversal invariant a d-dimensional copy has 2d basis components: the d rows w_k and their partners i w_k (the phase of the complex order parameter turned by 90 degrees), comp1 .. comp<2d> (a partner of a collinear row has its axis tag). "dir<k>": a one-parameter order-parameter direction at q != 0 that none of the other components lies on (k counted per basis).

  • field (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Real spin field (n_cells, N, 3) over the magnetic cell, largest moment 1; None when the real field vanishes.

  • net_moment (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Net moment over the magnetic cell.

  • group (object) – crystod.magnetic_group.MagneticGroupInfo of the arrangement (None without classification; its identified is False when spglib finds the operations but cannot name the group).

  • responses (object) – crystod.magnetic_group.MagneticResponses.

  • collinear (object) – crystod.magnetic_group.CollinearClass.

  • file_tag (str) – The tag made unique within the analysis as in the VESTA file name ("z", "z_2" for the second z of the same irrep and multipole); empty when the field vanishes.

  • vesta_name (str) – The VESTA file name crystod-mag writes for this component; empty when the field vanishes.

  • direction_label (str | None) – At q != 0, ISOTROPY’s label of the one-parameter order-parameter direction the component lies on ("K3(a;0.974a)"), when the q point has a table and a row matches; else None.

  • direction_subgroup (str | None) – The magnetic isotropy subgroup of that direction ("193.255 P6_3/m'cm", BNS number and symbol of the spin field), None when the component is not on a one-parameter direction or has no identified group.

  • direction (object) – The OrderParameterDirection (stratum) the component lies in at q != 0 (also when it has more than one free parameter), else None.

collinear: object = None#
direction: object = None#
direction_label: str | None = None#
direction_subgroup: str | None = None#
entry_index: int#
field: ndarray[tuple[Any, ...], dtype[float64]] | None#
file_tag: str = ''#
group: object = None#
property header: str#

"GM4+(3) [FM, dipole]" – the block title of crystod-mag.

kind: str#
label: str#
net_moment: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
rank_name: str | None#
responses: object = None#
stratum: int | None = None#
tag: str#
vesta_name: str = ''#
class crystod.mag.SubgroupAlignment(child_file, child_symbol, child_number, transformation, size, lattice, symbols, positions, site_atoms, site_sources, spin_matrix, folding=<factory>, identity_irrep=None, mulliken=<factory>, rows=<factory>, notes=<factory>)[source]#

Bases: object

The spin bases of a q != 0 analysis placed on a subgroup structure (SpinBasisAnalysis.subgroup, crystod-mag --subgroup-poscar).

Variables:
  • child_file (str) – The subgroup structure file as given.

  • child_symbol (str) – Its space group ("P6_3cm"); child_number the number.

  • transformation (object) – The SettingTransformation (P, p) of crystod-group --correlate --supergroup-poscar --subgroup-poscar: x_parent = P x_child + p between the fractional coordinates of the two input cells.

  • size (int) – Primitive cells of the crystal in the cell of the subgroup structure (|det P|).

  • lattice (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Lattice of the subgroup structure (rows, Angstrom); symbols and positions its atoms (as the file gives them).

  • site_atoms (list) – Indices of its atoms of the magnetic element.

  • site_sources (list) – (site, cell) of each: the magnetic site of the crystal and the index into SpinBasisAnalysis.cell_translations of the cell it sits in.

  • spin_matrix (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – The 3x3 map of the Cartesian spins of the crystal onto those of the subgroup structure (through the fractional components, S_parent = P S_child).

  • folding (list) – [(basis label, [irrep labels])]: the irreps of the subgroup structure at GM that the fields of each basis are made of (("K3(1)", ["GM1", "GM4"])).

  • identity_irrep (str | None) – The label of its identity irrep ("GM1").

  • mulliken (dict) – Mulliken symbols of its GM irreps ({"GM1": "A1"}).

  • rows (list) – The SubgroupSpinField rows, in the order of the directions of SpinBasisAnalysis.directions.

  • notes (list) – NOTE lines (without NOTE:).

child_spins(field)[source]#

The moments a spin field of the magnetic cell of the crystal, (n_cells, n_sites, 3), puts on the atoms of the subgroup structure (Cartesian, zero on the other atoms, not normalized).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

child_file: str#
child_number: int#
child_symbol: str#
folding: list#
identity_irrep: str | None = None#
lattice: ndarray[tuple[Any, ...], dtype[float64]]#
mulliken: dict#
notes: list#
positions: ndarray[tuple[Any, ...], dtype[float64]]#
rows: list#
site_atoms: list#
site_sources: list#
size: int#
spin_matrix: ndarray[tuple[Any, ...], dtype[float64]]#
symbols: list#
transformation: object#
class crystod.mag.SubgroupSpinField(entry_index, label, kind, direction, tag, child_irreps, reference=None, group=None, angle=None, coefficients=None, field=None, spins=None, vesta_name='')[source]#

Bases: object

One spin field of a basis on the subgroup structure: a row of the * Spin bases on the subgroup structure * block of crystod-mag --qpoint K --subgroup-poscar CHILD.

Variables:
  • entry_index (int) – Index of the basis in SpinBasisAnalysis.entries.

  • label (str) – Its irrep label ("K3(1)").

  • kind (str) – "component": an exported component as it is; "aligned": the domain of a one-parameter direction whose field is one irrep of the subgroup structure at GM; "generic": a generic field of a stratum, inside one irrep of the subgroup structure or over the whole basis; "none": no domain of the one-parameter direction is one such irrep.

  • direction (object) – The OrderParameterDirection (stratum) of the field, or None.

  • tag (str) – "comp1" (the component, its file_tag), "comp2_GM4" (aligned: the component of the direction and the irrep it is turned into, unique as in the VESTA file name), "generic" or "-".

  • child_irreps (list) – [(label, weight)]: the irreps of the subgroup structure at GM the field is made of, with the squared norms of its parts on the subgroup structure (sum 1; None for the generic rows, whose weights are arbitrary), e.g. [("GM1", 0.25), ("GM4", 0.75)].

  • reference (str | None) – The exported component an aligned row is turned from (the one on its direction), else None.

  • group (object) – crystod.magnetic_group.MagneticGroupInfo of the field on the subgroup structure (spglib on its cell with these moments), None without classification.

  • angle (float | None) – Degrees between an aligned field and reference in the real order-parameter space (the phase of the order parameter at a q that is not time-reversal invariant), else None.

  • coefficients (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Coefficients in the basis components (comp1 .. comp<n>, as in OrderParameterDirection.coefficients), unit length; None for the generic rows.

  • field (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – The spin field over the magnetic cell of the crystal (largest moment 1) of an aligned row, else None.

  • spins (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]] | None) – Moments on every atom of the subgroup structure (Cartesian, zero on the other atoms, largest 1) of an aligned row, else None.

  • vesta_name (str) – The VESTA file of an aligned row (in the cell of the subgroup structure), else empty.

angle: float | None = None#
property child_irrep_text: str#

"GM4", "0.25 GM1 + 0.75 GM4", "GM1 + GM4" (generic).

child_irreps: list#
coefficients: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
direction: object#
entry_index: int#
field: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
group: object = None#
kind: str#
label: str#
reference: str | None = None#
spins: ndarray[tuple[Any, ...], dtype[float64]] | None = None#
property subgroup: str | None#

"185.200 P6_3'cm'" (BNS number and symbol) or None.

tag: str#
vesta_name: str = ''#
class crystod.mag.Superposition(numbers, coefficients, parts, magmoms, field, net_moment, irrep_content=<factory>, group=None, responses=None, collinear=None, vesta_name='')[source]#

Bases: object

A superposition of listed bases (crystod-mag --superpose).

Variables:
  • numbers (tuple) – The numbers of the bases (1-based, as listed).

  • coefficients (tuple) – Their coefficients.

  • parts (list) – (number, element, header, tag, coefficient) of every term.

  • magmoms (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Moments of every atom of the magnetic cell (largest 1).

  • field (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – The same on the selected sites.

  • net_moment (numpy.ndarray[tuple[Any, ...], numpy.dtype[numpy.float64]]) – Net moment over the magnetic cell.

  • irrep_content (list) – (element, basis header, weight): the squared projection on the space of every basis (weights sum to 1).

  • collinear (group, responses,) – As for a basis.

  • vesta_name (str) – The VESTA file name.

irrep_text()[source]#

"Al GM4+(3) [FM, dipole] 0.500 + Ni GM5+(3) [AFM, octupole] 0.500".

Return type:

str

coefficients: tuple#
collinear: object = None#
field: ndarray[tuple[Any, ...], dtype[float64]]#
group: object = None#
irrep_content: list#
magmoms: ndarray[tuple[Any, ...], dtype[float64]]#
net_moment: ndarray[tuple[Any, ...], dtype[float64]]#
numbers: tuple#
parts: list#
responses: object = None#
vesta_name: str = ''#
crystod.mag.analyze_multi_element(cell=None, elements=(), qpoint=('GM',), *, symprec=1e-05, conventional=False, classify=True, vibrations=None)[source]#

Spin bases on the sites of several elements at one q point.

Parameters:
  • cell – The crystal (phonopy PhonopyAtoms); not needed with vibrations.

  • elements – Two or more elements (["Al", "Ni"]).

  • qpoint – As in crystod.spin_basis.analyze_spin_basis().

  • symprec (float) – Symmetry tolerance (Angstrom).

  • conventional (bool) – Use the conventional cell as the magnetic cell.

  • classify (bool) – Classify the bases and the combined arrangements.

  • vibrations – A prebuilt SymmetryOnlyVibrations(cell, standardize=False).

Returns:

A MultiElementAnalysis.

Raises:
  • SystemExit – An element not in the cell (ValueError through crystod.mag).

  • ValueError – An element given twice, or as in analyze_spin_basis.

Return type:

MultiElementAnalysis

Example

>>> from phonopy.interface.vasp import read_vasp
>>> from crystod import mag
>>> multi = mag.analyze_multi_element(read_vasp("221_PPOSCAR_AlNi3"), ["Al", "Ni"], "GM")
>>> multi.decomposition
{'GM4+(3)': 3, 'GM5+(3)': 1}
crystod.mag.analyze_spin_basis(cell=None, element='', qpoint=('GM',), *, symprec=1e-05, conventional=False, classify=True, vibrations=None, subgroup_poscar=None)[source]#

Symmetry-adapted spin bases at one q point, classified.

The computation behind crystod-mag --qpoint: the spin representation is projected onto the irreps of the little group, the FM/AFM combinations are separated at q = 0 (copies of an irrep that do not separate cleanly when made real one by one, or whose partners do not lie along directions symmetry fixes – in a trigonal or hexagonal crystal: not along the a axis of the input cell and perpendicular to it, _canonical_spin_partners() – are redone through the real form of the irrep with canonical partners: _canonical_spin_spaces(); an irrep that occurs more than once in a single moment is separated by the uniform moments, _uniform_moment_spaces(); a complex irrep and its conjugate are merged into one real two-dimensional space under their pair label, _merged_pair_spaces(), and so at the other time-reversal-invariant q points, where a pair of d-dimensional irreps gives a real 2d-dimensional space, _real_pair_rows()), every basis vector is resolved into its exported components (x/y/z/110/…, or comp<N>, with the (a,a) / (a,a,0) combination where symmetry singles it out and x+y+z of an x/y/z space: _combined_components()), the real spin field of each component over the magnetic cell is built (lattice gauge: the spin of site j in the cell at T is Re(w_j exp(2 pi i q.T)); global phase as in the VESTA export, largest moment 1), and with classify every component gets its magnetic space group (crystod.magnetic_group.magnetic_space_group()), the responses its magnetic point group allows (crystod.magnetic_group.macroscopic_responses()) and its collinear class (crystod.magnetic_group.classify_collinear()).

At a q that is not time-reversal invariant the order parameter of a d-dimensional copy is complex (the field Re[eta w exp(2 pi i q.T)] depends on the phase of eta), so a copy has 2d basis rows, w_1 .. w_d and i w_1 .. i w_d (comp1 .. comp<2d>; the global phase is fixed once per copy, from its first row, so the fields of the rows w_k are those of before, and each partner is signed with its largest moment component along the crystal axes positive); copies of an irrep that occurs more than once are first chosen so that the operations taking q to -q keep each of them (_resplit_copies()). At every q != 0 the order-parameter directions (strata) of every basis are enumerated in the magnetic cell: the operations of the crystal with the cell translations and time reversal act on the real span of the basis fields, and the strata of that matrix group are found as crystod-mag --parent finds them (IsotropyAnalyzer.enumerate_directions). Every component is assigned to its stratum; a one-parameter direction that no component lies on is exported as dir<k>; at a special point the directions get ISOTROPY’s labels from crystod.magnetic_isotropy.magnetic_isotropy_subgroups_at_kpoint() (matched by BNS number, index, free parameters and size), and the rows of the table that the magnetic cell does not realize are listed (SpinBasisAnalysis.directions).

Parameters:
  • cell – The crystal (phonopy PhonopyAtoms, e.g. from phonopy.interface.vasp.read_vasp); not needed when vibrations is given.

  • element (str) – Element whose sites carry the spins ("Ni").

  • qpoint – --qpoint tokens: one label ("GM", "X") or three coordinates in the primitive reciprocal basis (fractions such as "1/2" allowed); a single string is one label.

  • symprec (float) – Symmetry tolerance (spglib, Angstrom); the sites are matched within the tolerance of vibrations (this one when the cell is given).

  • conventional (bool) – Build the magnetic cell from the conventional cell (crystod-mag --conventional).

  • classify (bool) – Compute the magnetic groups, responses and classes.

  • vibrations (SymmetryOnlyVibrations | None) – A prebuilt SymmetryOnlyVibrations(cell, standardize=False) (the CLI passes its own).

  • subgroup_poscar (str | None) – A low-symmetry structure of the same compound (POSCAR or CIF, a primitive cell) whose cell is a magnetic cell of q (crystod-mag --subgroup-poscar CHILD): the bases are placed on it through the transformation of crystod-group --correlate --supergroup-poscar --subgroup-poscar and aligned with its structural domain (_align_with_subgroup(), SpinBasisAnalysis.subgroup). q != 0 only.

Returns:

A SpinBasisAnalysis.

Raises:
  • SystemExit – The element is not in the cell (ValueError through crystod.mag); the subgroup structure cannot be read or mapped onto the crystal.

  • ValueError – Unknown q-point label; the cell is not primitive; q is not commensurate with a magnetic cell of at most 12 cells along each axis (the message names the smallest commensurate supercell); a subgroup structure at q = 0, one that is not primitive, or one whose cell q does not fold onto Gamma of.

Return type:

SpinBasisAnalysis

Example

>>> from phonopy.interface.vasp import read_vasp
>>> from crystod import mag
>>> cell = read_vasp("example/test_POSCARs/136_PPOSCAR_TiO2")
>>> result = mag.analyze_spin_basis(cell, "Ti", "GM")
>>> [(c.header, c.tag, c.collinear.short_name) for c in result.components][-1]
('GM2+(1) [AFM, octupole]', 'z', 'altermagnet (d-wave)')
crystod.mag.classify_collinear(rotations, translations, positions, site_indices, cell_matrix, field, lattice, *, symprec=None)[source]#

Nonrelativistic class of one collinear spin arrangement.

The arrangement is reduced to its sign pattern s = +1 / -1 / 0 along the common spin axis (with the magnitudes); the space-group operations of the non-magnetic crystal, combined with every primitive translation inside the magnetic cell, are sorted into those that keep the pattern (H) and those that reverse every sign (A, the operations that exchange the two sublattices). Net moment nonzero: ferromagnet or ferrimagnet; A empty: compensated arrangement whose sublattices are not related by symmetry; A holding a pure translation or the inversion: conventional antiferromagnet; otherwise an altermagnet, whose wave type is the lowest even l at which the character chi_A (+1 on the rotation parts of H, -1 on those of A) occurs in the angular-momentum representation D_l (2: d-wave, 4: g-wave, 6: i-wave), after Smejkal, Sinova and Jungwirth, Phys. Rev. X 12, 031042 (2022).

Parameters:
  • rotations – Integer rotations of the space group of the primitive cell (SymmetryOnlyVibrations.rotations).

  • translations – Their fractional translations.

  • positions – Fractional positions of the primitive cell.

  • site_indices – Indices of the N magnetic sites.

  • cell_matrix – Integer (3, 3) magnetic cell in primitive units (rows).

  • field – The real spin field (n_cells, N, 3) over the magnetic cell, cells in the order of magnetic_cell_translations().

  • lattice – Primitive lattice vectors as rows (for the Cartesian rotations and directions).

  • symprec (float | None) – Distance tolerance (Angstrom) of the position matching: an image of a site matches the nearest site within it (the tolerance the operations were found with, --tolerance of crystod-mag). Sites within 1e-5 in every fractional coordinate always match; None (default) matches those only.

Returns:

A CollinearClass.

Return type:

CollinearClass

Example

>>> # bcc cell with a +z / -z pair: the body-centring translation
>>> # exchanges the two sublattices
>>> import numpy as np, spglib
>>> from crystod import mag
>>> lattice = np.eye(3) * 2.87
>>> positions = [[0, 0, 0], [0.5, 0.5, 0.5]]
>>> sym = spglib.get_symmetry_dataset((lattice, positions, [26, 26]))
>>> field = np.array([[[0, 0, 1], [0, 0, -1]]], dtype=float)
>>> klass = mag.classify_collinear(sym.rotations, sym.translations, positions,
...                                [0, 1], np.eye(3, dtype=int), field, lattice)
>>> klass.name
'antiferromagnet (conventional: a translation exchanges the sublattices, T tau)'
crystod.mag.component_magmoms(analysis, component)[source]#

Moments of every atom of the magnetic cell for one component of an analysis (zero on the atoms that are not its sites), (n_atoms, 3).

Return type:

ndarray[tuple[Any, …], dtype[float64]]

crystod.mag.coupled_magnetic_isotropy_subgroups(parent, irreps, parities=None)[source]#

Magnetic isotropy subgroups of several coupled irreps (crystod-mag --parent SG --irrep A B ...).

Parameters:
  • parent (str) – Symbol or number of the parent space group ("Pm-3m"); the paramagnetic parent is its grey group.

  • irreps (list) – ISO-IR labels (["R4+", "M3+"]; mR4+ and pair labels GM3+GM4+ accepted).

  • parities – Time-reversal parity of every irrep: -1 / "odd" (magnetic, the default) or +1 / "even" (structural).

Returns:

A CoupledMagneticIsotropySubgroups with the table of every irrep alone and the coupled table (every irrep condensed).

Raises:

ValueError – Unknown space group or irrep, or a wrong parity.

Return type:

CoupledMagneticIsotropySubgroups

crystod.mag.coupled_magnetic_order_parameter(parent, irreps, tokens, parities=None)[source]#

The magnetic isotropy subgroup of one coupled direction (crystod-mag --parent SG --irrep A B --order-parameter ...).

Parameters:
  • parent (str) – Symbol or number of the parent space group.

  • irreps (list) – ISO-IR labels.

  • tokens (list) – One component per order-parameter slot, irrep after irrep (the spellings of crystod-group --order-parameter: a, -a, 2a, a+b, 0); zero parts are allowed.

  • parities – As in coupled_magnetic_isotropy_subgroups().

Returns:

A CoupledMagneticOrderParameter.

Raises:

ValueError – Unknown group or irrep, wrong number of components, a zero order parameter.

Return type:

CoupledMagneticOrderParameter

crystod.mag.direction_table_rows(analysis)[source]#

Rows of the * Order-parameter directions * block.

Parameters:

analysis (SpinBasisAnalysis) – A SpinBasisAnalysis at q != 0.

Returns:

(direction, coefficients, subgroup, size, index, component), e.g. ("K3(a;0.974a)", "(1,0)", "193.255 P6_3/m'cm", "3", "6", "comp1"); the component is "free (2 parameters)" for a direction with more than one free parameter and "not in this magnetic cell" for a table row that the cell does not realize.

Return type:

One tuple per direction of SpinBasisAnalysis.directions

crystod.mag.format_copy_relations(multi)[source]#

The * Copies of one irrep on several elements * block.

Return type:

list[str]

crystod.mag.format_direction_table(analysis)[source]#

The * Order-parameter directions * block of crystod-mag --qpoint at q != 0 (no lines at q = 0).

Parameters:

analysis (SpinBasisAnalysis) – A SpinBasisAnalysis.

Returns:

title, the table (direction_table_rows()) and the notes.

Return type:

The block as lines

crystod.mag.format_magnetic_responses(responses, forms=True)[source]#

Lines describing the responses, in the wording “allowed by symmetry”.

Parameters:
  • responses (MagneticResponses) – A MagneticResponses.

  • forms (bool) – Also give the matrix forms of the allowed tensors (the magnetoelectric tensor as alpha, the piezomagnetic one in the 3x6 matrix notation as L).

Returns:

Lines indented by two spaces.

Return type:

list[str]

crystod.mag.format_multi_summary(multi)[source]#

The * Magnetic groups and collinear classes * block of a multi-element run (table and notes).

Return type:

list[str]

crystod.mag.format_phonon_angular_momentum(analysis, rows=None)[source]#

The * Phonon angular momentum allowed by symmetry * block of crystod-mag --classify-only --phonon-angular-momentum.

Parameters:
Returns:

title, unindented table (one row per phonon_angular_momentum_rows(); a second polynomial of a component goes on a continuation line) and the legend.

Return type:

The block as lines

crystod.mag.format_subgroup_alignment(analysis)[source]#

The blocks * Subgroup structure *, * Transformation matrix (parent -> child) * and * Spin bases on the subgroup structure * of crystod-mag --qpoint K --subgroup-poscar CHILD (no lines without a subgroup structure).

Parameters:

analysis (SpinBasisAnalysis) – A SpinBasisAnalysis.

Returns:

The blocks as lines, separated by blank lines.

Return type:

list[str]

crystod.mag.get_multipole_rank_lists(vibrations, little_rotations, irreps, max_rank=9)[source]#

Ranks at which each irrep occurs in the magnetic multipole representations.

crystod-mag uses these lists at q = 0 to name the symmetry-adapted spin bases: the spaces of an irrep are named in the order of the ranks in its list, so the ferromagnetic combination (cluster dipole, rank 1) comes first and the antiferromagnetic ones follow as octupole, … (the logic of Table III of M.-T. Suzuki et al., Phys. Rev. B 95, 094406). The rank-p magnetic (time-odd, axial) multipole transforms as the angular-momentum- p representation with parity (-1)**(p + 1) under inversion: the dipole (p = 1) and octupole (p = 3) are parity-even, the magnetic quadrupole (p = 2) is parity-odd, and so on. The multiplicity of every irrep is obtained by character orthogonality against the rotation characters sin((p + 1/2) theta) / sin(theta / 2) of the proper part of every little-group operation.

Parameters:
  • vibrations (SymmetryOnlyVibrations) – Symmetry container of the primitive cell (crystod.phonon.SymmetryOnlyVibrations); its lattice converts the integer rotations to Cartesian form.

  • little_rotations (ndarray[tuple[Any, ...], dtype[int64]]) – Integer rotation matrices of the little-group operations, in the order of the irrep matrices: normally vibrations.rotations[mapping] with the mapping returned by get_spin_representation.

  • irreps – The spgrep irreps of the little group, as returned by get_spin_representation.

  • max_rank (int) – Highest rank p included in the search.

Returns:

One list per irrep (same order as irreps), holding the ranks 1 <= p <= max_rank at which the irrep appears in the rank-p magnetic multipole representation, in increasing order and repeated according to the multiplicity. MULTIPOLE_NAMES translates ranks to names.

Return type:

list[list[int]]

Example

>>> # vib, sites, q: see get_spin_representation (O sites of SrTiO3)
>>> irreps, spin_rep, mapping = mag.get_spin_representation(vib, sites, q)
>>> labels = vib.get_irrep_labels(q, irreps, mapping)
>>> rotations = vib.rotations[mapping]
>>> ranks = mag.get_multipole_rank_lists(vib, rotations, irreps)
>>> dict(zip(labels, ranks))["GM4+(3)"]
[1, 3, 5, 5, 7, 7, 9, 9, 9]
crystod.mag.get_spin_representation(vibrations, site_indices, qpoint, *, symprec=None)[source]#

Irreps and the axial-vector (spin) representation on selected sites at q.

This is the first step of crystod-mag (at the --qpoint given, or at every special k point in survey mode): the spins of the site_indices atoms of the primitive cell are treated as axial vectors, and the little group of qpoint acts on the 3N-dimensional spin space by the same construction as the vibration (polar-vector) representation of crystod-phonon, with the Cartesian rotation R replaced by det(R) * R and the site permutation restricted to the selected sites. The Bloch-phase convention is that of spgrep, so the returned matrices can be projected onto the returned irreps directly with spgrep.representation.project_to_irrep.

Parameters:
  • vibrations (SymmetryOnlyVibrations) – Symmetry container of the primitive cell (crystod.phonon.SymmetryOnlyVibrations); its rotations, translations and primitive_cell define the space group.

  • site_indices (list[int]) – Indices (into vibrations.primitive_cell) of the N atoms that carry a spin, e.g. every atom of the magnetic element.

  • qpoint (list[float]) – The q point in primitive reciprocal coordinates, e.g. [0, 0, 0] or [0.5, 0.5, 0.5].

  • symprec (float | None) – Distance tolerance (Angstrom) within which an operation must map a site onto a site; None (default) takes the tolerance the space group was found with (vibrations.symprec, the --tolerance of crystod-mag), so that every operation spglib accepts permutes the sites. Sites within 1e-5 in every fractional coordinate always match. The Bloch phases are built from the site positions symmetrized by the space group, so a structure off its ideal positions within the tolerance gives the representation of the ideal structure (for a structure at its ideal positions they are the input positions).

Returns:

(irreps, spin_rep, mapping). irreps is the list of spgrep irreps of the little group at qpoint (each an array of shape (order, dim, dim)); spin_rep is the complex array of shape (order, 3N, 3N) holding the spin-representation matrix of every little-group operation, in the order of the irrep matrices; mapping is the integer array that indexes those operations in vibrations.rotations (what get_irrep_labels and get_multipole_rank_lists expect).

Return type:

tuple

Example

>>> from phonopy.interface.vasp import read_vasp
>>> from crystod import mag, phonon
>>> from crystod.examples import example_path
>>> cell = read_vasp(example_path("221_PPOSCAR_SrTiO3"))
>>> vib = phonon.SymmetryOnlyVibrations(cell, standardize=False)
>>> symbols = vib.primitive_cell.symbols
>>> sites = [i for i, s in enumerate(symbols) if s == "O"]   # 3 sites
>>> q = [0, 0, 0]
>>> irreps, spin_rep, mapping = mag.get_spin_representation(vib, sites, q)
>>> spin_rep.shape
(48, 9, 9)
>>> vib.get_irrep_labels(q, irreps, mapping)[6]
'GM4+(3)'
crystod.mag.macroscopic_responses(group_or_rotations, time_reversals=None, *, crystal_rotations=None)[source]#

Responses that a magnetic point group allows by symmetry.

Parameters:
  • group_or_rotations – A MagneticGroupInfo, or Cartesian rotation matrices (n, 3, 3) of the operations.

  • time_reversals – The time-reversal flags (needed with rotations).

  • crystal_rotations – Cartesian rotations of the point group of the crystal without spins, for the note on the electric polarization (with a MagneticGroupInfo, its crystal_rotations are used when this is None).

Returns:

A MagneticResponses with the forms of the net magnetization (aeV), the electric polarization (V), the linear magnetoelectric tensor (aeV2) and the piezomagnetic tensor (aeV[V2]).

Raises:

ValueError – Rotations given without flags.

Return type:

MagneticResponses

Example

>>> responses = mag.macroscopic_responses(group)   # see magnetic_space_group
>>> responses.summary()
'net magnetization none; electric polarization none; linear magnetoelectric effect none; piezomagnetism none'
crystod.mag.magnetic_irrep_arrangements(cell=None, elements=(), irreps=(), *, symprec=1e-05, coefficients=None, classify=True, vibrations=None, order_parameter=None, copies=None, conventional=False)[source]#

The magnetic arrangements of given irreps on a crystal.

The computation behind crystod-mag -c POSCAR --element EL [EL2 ...] --irrep IR [IR2 ...]: for every row of the table of crystod-mag --parent SG --irrep IR [IR2 ...] (one irrep: its table; several: the coupled table, every irrep condensed) the arrangement of moments on the sites of the chosen elements that the row’s order parameter describes (see the module docstring), with its magnetic space group identified again from the structure.

Parameters:
  • cell – The crystal (phonopy PhonopyAtoms, a primitive cell); not needed when vibrations is given.

  • elements – The magnetic elements (["Mn"], ["Al", "Ni"]).

  • irreps – ISO-IR labels (["R4-"], ["R4-", "M3-"]; mR4- and pair labels GM3+GM4+ accepted, as with --parent).

  • symprec (float) – Symmetry tolerance (spglib, Angstrom).

  • coefficients – The weight of every irrep’s part (each part has its largest moment 1 before weighting); default 1 each.

  • classify (bool) – Identify the magnetic group, the responses and the collinear class of every arrangement.

  • vibrations – A prebuilt SymmetryOnlyVibrations(cell, standardize=False).

  • order_parameter – --order-parameter tokens (irrep after irrep); then one arrangement, of that vector, is built instead of one per row (MagneticIrrepAnalysis.stratum names its row). The numbers are amplitudes: the field is sum_j c_j s_j Psi_j eta_j, s_j scaling one unit component of a copy to rms moment 1 over its sites, then scaled to largest moment 1.

  • copies – One copy number (from 1) per irrep (--copies): only that choice of copies is exported. By default every choice while there are at most MAX_COPY_CHOICES per row, else the first.

  • conventional (bool) – Write the arrangements in the conventional cell (--conventional): the cell of crystod.phonon_vector.get_conventional_matrix() for the centring letter of the space group, as crystod-mag --qpoint --conventional uses it, times the smallest multiples along its axes commensurate with every arm. The spin modes, weights and counts stay on the diagonal magnetic cell; the written moments are the field re-tiled onto the conventional cell (exact: the field is periodic under every translation T with k . T an integer for every arm), and the group check is made on them.

Returns:

A MagneticIrrepAnalysis.

Raises:

ValueError – An element not in the cell, an unknown or repeated irrep, an irrep the spin representation of the elements does not contain (the message lists the decomposition at its k point), a magnetic cell larger than MAX_CELLS primitive cells (with conventional: a conventional cell of more than MAX_MULTIPLE cells along one axis or 4 * MAX_CELLS primitive cells), a cell that is not primitive, a wrong --order-parameter.

Return type:

MagneticIrrepAnalysis

crystod.mag.magnetic_isotropy_subgroups(parent, irrep)[source]#

Magnetic isotropy subgroups of one irrep (crystod-mag --parent SG --irrep IR).

Parameters:
  • parent (str) – Symbol or number of the parent space group ("Pm-3m"); the paramagnetic parent is its grey group (Pm-3m1').

  • irrep (str) – ISO-IR label ("GM4+", a pair label "GM3+GM4+", or "mGM4+").

Returns:

One MagneticIsotropySubgroup per order-parameter direction, in the order of the table.

Raises:

ValueError – Unknown space group or irrep (the command’s message).

Return type:

list[MagneticIsotropySubgroup]

crystod.mag.magnetic_isotropy_subgroups_at_kpoint(parent, kpoint)[source]#

Magnetic isotropy subgroups of every irrep of one k point (crystod-mag --parent SG --qpoint K).

Parameters:
  • parent (str) – Symbol or number of the parent space group.

  • kpoint – Special-point name ("R", "GM") or three primitive coordinates.

Returns:

{irrep label: [MagneticIsotropySubgroup, ...]} in table order.

Raises:

ValueError – Unknown space group or k point, or an irrep that could not be enumerated (its reason).

Return type:

dict

crystod.mag.magnetic_point_group_symbol(bns_symbol, msg_type)[source]#

Magnetic point-group symbol derived from a BNS space-group symbol.

The lattice letter and its subscript are dropped, glide letters (a, b, c, n, d, e) become m, screw axes become plain rotations (4_2 -> 4) and every prime is kept; a type II or type IV group gives the non-magnetic point group followed by 1'.

Parameters:
  • bns_symbol (str) – BNS symbol in pymatgen’s spelling ("P4_2'/mnm'", "P_I4/mnc", "Pm-3m1'").

  • msg_type (int) – The type (1-4).

Returns:

The MPG symbol, e.g. "4'/mmm'" or "4/mmm1'".

Return type:

str

Example

>>> from crystod.magnetic_group import magnetic_point_group_symbol
>>> magnetic_point_group_symbol("Pn'ma'", 3)
"m'mm'"
crystod.mag.magnetic_space_group(lattice, positions, numbers, magmoms, symprec=1e-05, mag_symprec=None)[source]#

The magnetic space group of a spin arrangement (spglib).

spglib returns only the operations whose rotation maps the lattice of the cell given onto itself. When that lattice is not invariant under the point group of the crystal (a primitive cell off the standard setting taken with --conventional, a 2x1x1 cell of a cubic crystal), the group found directly can be a subgroup of the true one. The structure is then also identified in the cell of its translations without time reversal, T_U (built by unitary_cell() from the pure translations among the direct operations), whose lattice is invariant under every rotation of the magnetic group: the direct result is kept when it is complete (its number of operations is that of the T_U cell times the number of T_U cells in the cell given), else the result found in the T_U cell is returned, with its operations repeated over the translations of T_U in the cell given (Cartesian rotations, translations in the fractional coordinates of the cell given), so that the counts keep the convention of the cell given. MagneticGroupInfo.crystal_rotations then come from a primitive cell of the structure without moments. On a cell whose lattice is invariant under the point group of the crystal (every standard cell) the direct result is returned unchanged.

Parameters:
  • lattice – Lattice vectors as rows, (3, 3) in Angstrom.

  • positions – Fractional coordinates, (n_atoms, 3).

  • numbers – Atomic numbers (or any type labels), (n_atoms,).

  • magmoms – Moments as Cartesian axial vectors, (n_atoms, 3) (zero on the non-magnetic atoms).

  • symprec (float) – Distance tolerance of spglib.

  • mag_symprec (float | None) – Tolerance on the moments (spglib’s mag_symprec; None uses symprec).

Returns:

A MagneticGroupInfo.

Raises:

SystemExit – spglib finds no magnetic symmetry operations at all (ValueError through crystod.mag).

Return type:

MagneticGroupInfo

Example

>>> import numpy as np
>>> from crystod import mag
>>> # a ferromagnet on a simple cubic lattice, given in a 2x1x1 cell
>>> group = mag.magnetic_space_group(np.diag([5.74, 2.87, 2.87]),
...     [[0, 0, 0], [0.5, 0, 0]], [26, 26], [[0, 0, 1], [0, 0, 1]])
>>> group.bns_number, group.n_operations
('123.345', 32)
crystod.mag.magnetic_summary_notes(analysis)[source]#

The notes under the summary table (frames, tags, warnings).

Parameters:

analysis (SpinBasisAnalysis) – A classified SpinBasisAnalysis.

Returns:

how to read the columns, the frames of the symbols and directions, the pair labels of complex irreps merged with their conjugates, and a line when spglib could not identify a group.

Return type:

Note lines, unindented

crystod.mag.magnetic_summary_rows(analysis)[source]#

Rows of the table of magnetic groups and collinear classes.

Parameters:

analysis (SpinBasisAnalysis) – A classified SpinBasisAnalysis.

Returns:

(basis, component, MSG (BNS), type, MPG, net magnetization, class, MSG (UNI)), e.g. ("GM2+(1) [AFM, octupole]", "z", "P4_2'/mnm' (136.499)", "III", "4'/mmm'", "none", "altermagnet (d-wave)", "P4_2'/mnm'"); the last cell is the unified symbol of B. J. Campbell et al., Acta Cryst. A78, 99 (2022) ("P4/mnc.1'_I[I4/mmm]" for a type IV group). The component is the tag of the VESTA file name ("z_2" for the second z of the same basis). A group that spglib cannot identify, and an unclassified component (FM/AFM separation failed), give "-" in the cells concerned; no component is left out.

Return type:

One tuple per exported component with a nonvanishing field

crystod.mag.multi_summary_rows(multi)[source]#

Rows of the table of magnetic groups of a multi-element run: every listed basis (numbered) and every combined arrangement (-).

Return type:

list[tuple[str, …]]

crystod.mag.paramagnetic_point_group(analysis)[source]#

The grey magnetic point group of the crystal without spins.

Parameters:

analysis (SpinBasisAnalysis) – A SpinBasisAnalysis.

Returns:

the symbol ("4/mmm1'", "-" when the symbol derived from the space group does not match the operations) and every distinct Cartesian rotation of the crystal once without and once with time reversal.

Return type:

(symbol, rotations, time_reversals)

crystod.mag.phonon_angular_momentum(group_or_rotations, time_reversals=None, *, plane_normal=None, max_degree=9)[source]#

The phonon angular momentum texture near Gamma that a magnetic point group allows, component by component.

The angular momentum l(q) of a phonon branch is a real axial vector, odd under time reversal. An operation g = (R, t) (t: combined with time reversal, s = -1 if t else +1) acts on the wavevector by A = s R and on l by B = s det(R) R, and symmetry demands l(A q) = B l(q). For every degree n the homogeneous polynomial vector fields of degree n that obey this for all operations are found as a null space (in coordinates in which every substitution q -> A q is an orthogonal matrix). For each Cartesian component l_i the result holds the lowest degree with a nonzero i-th component (s, p, d, f, g, h, i, j for 0..7), the polynomials of that degree, and the nodal planes through Gamma that single operations enforce: those whose A is the reflection in the plane and whose B reverses e_i (a mirror without time reversal whose plane contains e_i; a 2' along the normal when e_i is along it). The number of planes can be smaller than the degree (4': l_z ~ q_z, no plane), so both are given. P T makes every component vanish; degree 0 is the net magnetization. When the planes pinned by single operations are fewer than the degree, the other nodes are not fixed in position by symmetry. Phonon angular momentum after L. Zhang and Q. Niu, Phys. Rev. Lett. 112, 085503 (2014).

Parameters:
  • group_or_rotations – A MagneticGroupInfo, or Cartesian rotation matrices (n, 3, 3) of the operations of the magnetic point group.

  • time_reversals – The time-reversal flags (needed with rotations).

  • plane_normal – For a two-dimensional system (a layer), the normal (Cartesian) of the plane q is restricted to: the polynomials are in the two in-plane coordinates (q_x, q_y for the normal along z; q_u, q_v for a normal along no Cartesian axis, see PhononAngularMomentum.in_plane) and the nodes are lines.

  • max_degree (int) – The highest degree searched (default 9).

Returns:

A PhononAngularMomentum.

Raises:

ValueError – Rotations given without flags, or an operation that does not map plane_normal to plus or minus itself.

Return type:

PhononAngularMomentum

Example

>>> import numpy as np
>>> from crystod import mag
>>> c4 = np.array([[0, -1, 0], [1, 0, 0], [0, 0, 1]], dtype=float)
>>> rotations = [np.eye(3), c4, c4 @ c4, c4.T]          # the group 4'
>>> result = mag.phonon_angular_momentum(rotations, [False, True, False, True])
>>> result.component("z").text()
'l_z ~ q_z (p-wave)'
crystod.mag.phonon_angular_momentum_degrees(group_or_rotations, time_reversals=None, *, component='z', max_degree=9, plane_normal=None)[source]#

The degrees n <= max_degree at which component l_i of the phonon angular momentum has a nonzero form allowed by symmetry (all of them, not only the lowest).

The N-th order response of an angular-momentum current to a temperature gradient, J ~ (grad T)^N, is allowed by symmetry exactly when the degree N + 1 is in this list (the current weights l(q) with the N-th power of the group velocity, one more power of q per order). Once a degree n occurs, n + 2, n + 4, ... occur too (times |q|^2).

Parameters:
Returns:

The degrees in increasing order (empty when the component vanishes).

Return type:

tuple[int, …]

Example

>>> mag.phonon_angular_momentum_degrees(rotations, [False, True, False, True])
(1, 2, 3, 4, 5, 6, 7, 8, 9)
crystod.mag.phonon_angular_momentum_rows(analysis)[source]#

Rows of the * Phonon angular momentum allowed by symmetry * block.

Parameters:

analysis (SpinBasisAnalysis) – A classified SpinBasisAnalysis.

Returns:

(basis, component, MPG, result) with the crystod.magnetic_group.PhononAngularMomentum of the magnetic point group (None when it is not known): first the paramagnetic crystal ("paramagnetic", "-", its grey group), then every exported component of the table of magnetic groups, in its order.

Return type:

list[tuple]

crystod.mag.separate_ferro_combination(spaces, representation, n_sites, realify_aligned=True)[source]#

Split the ferromagnetic combination off the spaces of one irrep.

At q = 0 an irrep can occur several times in the spin representation (2 x GM4+ for the three Ni sites of AlNi3); crystod-mag calls this function once per irrep label with all of its projected spaces. The spaces are first aligned to a common partner basis (an intertwiner with representation is found for every space, and complex circular bases are recombined into real ones), then the net moments sum_i S_i of the aligned spaces are combined into one unit vector: its unitary completion gives the unique combination that carries a net moment (the cluster dipole, printed as FM) and the orthogonal combinations with sum_i S_i = 0 (AFM, net moment zero). crystod-mag names the AFM combinations by the remaining entries of the irrep’s rank list (get_multipole_rank_lists): octupole, … for an irrep even under the inversion, quadrupole, hexadecapole, … for an odd one (Cr2O3, Cr: GM1- quadrupole, GM2- hexadecapole). When no space carries a net moment, or the completion does not separate cleanly, the aligned spaces are returned unchanged as antiferromagnetic.

Parameters:
  • spaces (list[ndarray[tuple[Any, ...], dtype[float64]]]) – Real basis arrays of shape (dim, 3N) (one row per partner of the irrep; 3N = three Cartesian components of N spins) that all carry the same irrep, e.g. the output of spgrep.representation.project_to_irrep for one irrep.

  • representation (ndarray[tuple[Any, ...], dtype[complex128]]) – The spin-representation matrices of shape (order, 3N, 3N) returned by get_spin_representation; used to align the spaces to a common basis.

  • n_sites (int) – The number N of spin-carrying sites.

  • realify_aligned (bool) – Rotate every aligned row by its own phase to make it real (needed for complex spaces). Pass False for spaces that are already real and transform with one set of real matrices, where a per-row phase would flip the sign of single partners.

Returns:

(ferro, afm). ferro is the basis array of shape (dim, 3N) with a net moment (None when no combination has one) and afm is the list of the remaining net-zero basis arrays; together they span the same space as the input.

Return type:

tuple

Example

>>> # spin_rep, irreps, sites: see get_spin_representation (SrTiO3, O)
>>> import numpy as np
>>> from spgrep.representation import project_to_irrep
>>> gm4p = irreps[6]                                     # GM4+, twice
>>> spaces = [np.real(s) for s in project_to_irrep(spin_rep, gm4p)]
>>> ferro, afm = mag.separate_ferro_combination(spaces, spin_rep, 3)
>>> ferro.shape, len(afm)
((3, 9), 1)
>>> bool(np.abs(afm[0].reshape(3, 3, 3).sum(axis=1)).max() < 1e-8)
True
crystod.mag.subgroup_table_rows(analysis)[source]#

Rows of the * Spin bases on the subgroup structure * block.

Parameters:

analysis (SpinBasisAnalysis) – A SpinBasisAnalysis with a subgroup structure.

Returns:

(direction, field, child irreps, MSG on the child, angle, coefficients), e.g. ("K3(0.282a;a)", "comp2_GM4", "GM4", "185.200 P6_3'cm'", "60", "(-0.866,0.5)"); empty without a subgroup structure.

Return type:

One tuple per SubgroupSpinField

crystod.mag.superpose_bases(listed, numbers, coefficients=None, *, vibrations=None, classify=True)[source]#

Superpose listed bases with given coefficients.

Parameters:
  • listed – A MultiElementAnalysis, or a single crystod.spin_basis.SpinBasisAnalysis (its bases numbered as the rows of its table of magnetic groups).

  • numbers – The numbers of the bases (1-based).

  • coefficients – One coefficient per number (default 1 each); every basis enters as listed (largest moment 1).

  • vibrations – The SymmetryOnlyVibrations of the crystal (needed to classify).

  • classify (bool) – Compute the magnetic space group, responses and class.

Returns:

A Superposition (moments scaled to largest 1).

Raises:

ValueError – A number out of range, a number given twice, a count of coefficients that differs from the count of numbers, or a vanishing superposition.

Return type:

Superposition

crystod.mag.unified_point_group_symbol(point_group, msg_type)[source]#

UNI symbol of a magnetic point group from its usual symbol.

Type I appends .1 (mmm -> mmm.1), types II and IV put a period before the final 1' (4/mmm1' -> 4/mmm.1'), type III is unchanged. A trailing "?" (a symbol that disagreed with the operations) is kept.

Parameters:
Returns:

The UNI symbol of the MPG.

Return type:

str

Example

>>> from crystod.magnetic_group import unified_point_group_symbol
>>> unified_point_group_symbol("4/mmm1'", 4)
"4/mmm.1'"
crystod.mag.unified_symbol(bns_number)[source]#

Unified (UNI) symbol of a magnetic space group from its BNS number.

The UNI symbol (B. J. Campbell, H. T. Stokes, J. M. Perez-Mato and J. Rodriguez-Carvajal, Acta Cryst. A78, 99 (2022)) is the BNS symbol in the standard BNS setting with the generator of {1, 1’} after a period: .1 for type I, .1' for type II, nothing for type III; a type IV group carries the anti-translation as the subscript of 1' and its family space group, oriented along the BNS axes, in brackets. Table from the ISOTROPY Software Suite (data_magnetic.txt), identical to Table S2 of the paper.

Parameters:

bns_number (str) – "128.410".

Returns:

"P4/mnc.1'_I[I4/mmm]".

Raises:

KeyError – bns_number is not one of the 1651 BNS numbers.

Return type:

str

Example

>>> from crystod.magnetic_group import unified_symbol
>>> unified_symbol("62.448"), unified_symbol("2.7")
("Pn'ma'", "P-1.1'_c[P-1]")
crystod.mag.MULTIPOLE_NAMES = {0: 'monopole', 1: 'dipole', 2: 'quadrupole', 3: 'octupole', 4: 'hexadecapole', 5: '32pole', 6: '64pole'}#

Names of the magnetic multipole ranks used in the crystod-mag output (rank p -> 2**p-pole): {1: "dipole", 3: "octupole", ...}.