msgjson package#
Submodules#
msgjson.build module#
Build data/msg_operators.json from spglib.
- Usage:
python -m msgjson.build python -m msgjson.build –output path/to/output.json
msgjson.query module#
Query the MSG operator table for magnetic symmetry analysis.
Workflow#
Given a parent space group number, a commensurate propagation vector k, and fractional coordinates of magnetic ion sites, this module:
Loads all MSGs whose parent SG matches.
Filters to those compatible with k (little-group condition).
For each compatible MSG and each input site, returns: - the orbit of the site (symmetry-equivalent positions) - the basis vectors for symmetry-allowed magnetic moments
Moment transformation rule#
Under operator (W, t, theta), a magnetic moment (axial vector) transforms
as m' = theta * det(W) * W @ m. A moment is site-symmetry-allowed if it
is invariant under all operators that fix the site modulo lattice translations.
k-compatibility condition#
Operator (W, t, theta) is compatible with propagation vector k if
W @ k ≡ theta * k (mod reciprocal lattice vectors), i.e. W maps k to
either +k (unitary) or -k (antiunitary), up to a reciprocal lattice vector.
For k = 0 all operators satisfy this.
- class MSGResult(uni_number: 'int', bns_number: 'str', og_number: 'str', msg_type: 'int', parent_sg: 'int', n_ops: 'int', origin_shift: 'tuple' = (0.0, 0.0, 0.0), sites: 'list[SiteResult]' = <factory>)[source]#
Bases:
object- sites: list[SiteResult][source]#
- class SiteResult(site: 'np.ndarray', orbit: 'list[np.ndarray]', moment_basis: 'np.ndarray', n_free: 'int')[source]#
Bases:
object
- analyze_msg(bns_number: str, sites: list[ndarray | list], *, site_tol: float = 0.0001) MSGResult | None[source]#
Compute site-symmetry moment basis for a specific MSG identified by BNS number.
This is the lower-symmetry entry point: the user has already identified the MSG (e.g. from Bilbao/Jana subgroup tables) and wants to know which moment directions are symmetry-allowed at each site.
Unlike
compatible_msgs, this function skips the k-compatibility filter — all operators of the MSG are used as site-symmetry candidates. Use this when the MSG already encodes the k-vector (e.g. a type-IV MSG whose anti-translation captures the magnetic doubling).- Parameters:
- bns_numberstr
BNS label of the target MSG, e.g.
"2.7"for P_S 1̄.- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites in the MSG’s cell.
- site_tolfloat
Tolerance for site-fixing comparisons.
- Returns:
- MSGResult with site data, or
Noneif the BNS number is not found.
- MSGResult with site data, or
- compatible_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[MSGResult][source]#
Find MSGs compatible with the given parent SG and k-vector.
- Parameters:
- parent_sgint
ITA number of the parent (non-magnetic) space group (1–230).
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- centeringstr
Lattice centering of the parent cell: “P”, “I”, “F”, “A”, “B”, “C”, “R”. Determines which difference vectors W@k - theta*k are considered reciprocal-lattice vectors. Defaults to “P” (primitive). For face-centred parents (e.g. Fm-3m, SG 225) pass centering=”F”.
- k_tolfloat
Tolerance for the k-compatibility check.
- site_tolfloat
Tolerance for orbit and site-symmetry comparisons.
- Returns:
- list of MSGResult, one per compatible MSG, sorted by uni_number.
- domain_operators(msg_bns: str, parent_sg: int, tol: float = 0.0001) list[dict][source]#
Return spatial operators of the parent SG that are absent from the MSG.
These are the “broken symmetry” operations — applying any one of them to a single-domain state generates a distinct but symmetry-equivalent domain. The number of domains equals
len(domain_operators(...)) + 1.This comparison is meaningful when the MSG is a subgroup of the parent SG in the same cell (type-I or type-III MSGs). For type-IV MSGs whose cell differs from the parent (e.g. P_S 1̄ derived from R-3), the function still returns a useful approximation by comparing only the rotational parts of the operators (ignoring translations that differ by the cell doubling).
- Parameters:
- msg_bnsstr
BNS number of the MSG (e.g.
"148.17").- parent_sgint
ITA number of the parent space group (e.g.
148for R-3).- tolfloat
Tolerance for rotation-matrix comparison.
- Returns:
- List of operator dicts from the parent SG type-I MSG whose rotation
- matrix does not appear (with any translation or theta) among the MSG
- operators.
Notes
The number of magnetic domains is:
n_domains = n_unique_W_in_parent / n_unique_W_in_MSG
where both counts use the point-group (unique rotation matrices, ignoring translations). For CrCl3 (R-3 → P_S1̄, BNS 2.7):
|S6| / |Ci| = 6 / 2 = 3domains, whilelen(domain_operators(...))returns 12 (4 distinct broken rotations × 3 R-centering copies).For type-III MSGs within the same parent SG, this function returns an empty list because every rotation matrix of the parent is still present in the MSG (some as antiunitary operations). Domains in that case arise from time-reversal symmetry breaking, not spatial symmetry lowering.
- find_by_bns(bns_number: str) MSGResult | None[source]#
Return an MSGResult (no site data) for the MSG with the given BNS number.
- Parameters:
- bns_numberstr
BNS label as a string, e.g.
"148.17","2.7". Leading/trailing whitespace is stripped.
- Returns:
- MSGResult with an empty
siteslist, orNoneif not found.
- MSGResult with an empty
- magnetic_structure_factors(site_moments: list[tuple[ndarray, ndarray]], hkl: list[tuple[int, int, int]], k: ndarray | list, *, lattice: ndarray | None = None, ion: str | None = None, c2: float = 0.0) ndarray[source]#
Return \(|F_M(Q)|^2\) for magnetic satellite reflections Q = hkl + k.
The magnetic structure factor is:
\[F_M(\mathbf{Q}) = \sum_j f(|Q|)\, \mathbf{m}_j\, e^{2\pi i \mathbf{Q} \cdot \mathbf{r}_j}\]where the sum runs over all orbit sites supplied in site_moments. For spin-only moments
f(|Q|) = <j0(|Q|)>; passing lattice and ion enables the form-factor correction.- Parameters:
- site_momentslist of (r, m) tuples
Output of
orbit_moments(). r in fractional coordinates, m in μ_B (or arbitrary consistent units).- hkllist of (h, k, l)
Nuclear reflection indices. The magnetic satellite is at Q = hkl + k.
- karray_like, shape (3,)
Propagation vector.
- latticendarray, shape (3, 3), optional
Real-space lattice matrix a = lattice[0], b = lattice[1], c = lattice[2] in Å. Required when ion is given.
- ionstr, optional
Ion label for the magnetic form factor (e.g.
"Mn2+","Cr3+"). Requires lattice. When omitted f(Q) = 1 for all reflections.- c2float
<j2>coefficient for the orbital form-factor correction (default 0).
- Returns:
- ndarray, shape (len(hkl),)
\(|F_M(\mathbf{Q})|^2\) in μ_B² (or the square of whatever unit m was given in). This does not include the geometric \(\sin^2\!\alpha\) factor; multiply by
1 − (m̂ · Q̂)²to obtain the physical neutron cross-section term.
- maximal_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], **kwargs) list[MSGResult][source]#
Return k-maximal compatible MSGs that allow a non-zero moment.
Implements the Bilbao MAXMAGN definition [1]: a MSG is k-maximal if no k-compatible supergroup exists anywhere in the subgroup lattice of G1’. Only commensurate 1k orderings are considered.
Each k-maximal MSG represents one conjugacy class of physically equivalent domain-related orderings. For type-IV MSGs the function additionally appends the τ-shifted origin variant — these two results correspond to what MAXMAGN calls “alternatives (domain-related)” within the same conjugacy class. All other domain variants (rotational domains from broken spatial symmetry) are accessible via
domain_operators().For k = 0 the little co-group equals the full parent SG point group, so
subgroup_msgswould include MSGs from unrelated SGs that happen to share the same point group.compatible_msgs(which restricts to the input parent SG) is used instead; it already enumerates both origin shifts for type-IV MSGs.For k ≠ 0 the little co-group is a strict subgroup of the parent SG point group.
subgroup_msgsis used so the true k-maximal MSG is found even when it has a different parent SG than the input — e.g. α-RuCl₃ (parent = 148) whose maximal MSG is BNS 2.7 (parent = 2). For each type-IV MSG at the maximum symmetry level, a second result with the primitive anti-translation origin shift τ is appended.- Parameters:
- parent_sgint
ITA number of the paramagnetic parent space group.
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- **kwargs
Passed to
compatible_msgs/subgroup_msgs:centering,k_tol,site_tol.
- Returns:
- list of MSGResult, sorted by (uni_number, origin_shift).
References
[1]Perez-Mato et al., Annu. Rev. Mater. Res. 45, 217 (2015).
- orbit_moments(msg_result: MSGResult, site_idx: int, m_ref: ndarray, k: ndarray | list, *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[tuple[ndarray, ndarray]][source]#
Return (position, moment) pairs for all orbit sites.
Starting from a reference moment m_ref at
msg_result.sites[site_idx], the function finds the k-compatible MSG operator that maps the reference site to each orbit position and applies the moment transformation rule:m' = θ · det(W) · W @ m
- Parameters:
- msg_resultMSGResult
Result from
maximal_msgs(),subgroup_msgs(), oranalyze_msg().- site_idxint
Index into
msg_result.sitesselecting the reference site.- m_refarray_like, shape (3,)
Moment vector at the reference site in μ_B (or any consistent unit). Must lie within the symmetry-allowed subspace; use
s.moment_basis @ amplitudesto build it from the basis.- karray_like, shape (3,)
Propagation vector in reciprocal-lattice units.
- centeringstr
Lattice centering symbol (
"P","F","I","R", etc.).- k_tolfloat
Tolerance for k-compatibility check.
- site_tolfloat
Tolerance for position matching.
- Returns:
- list of (r, m) tuples
r — fractional position in [0, 1)³, shape (3,) m — moment vector at that position, shape (3,) The list starts with the reference site.
- subgroup_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[MSGResult][source]#
Find all MSGs compatible with k that are geometric subgroups of the parent SG.
Inspired by the Bilbao k-SUBGROUPSMAG workflow [1] — searches across all parent SGs down to MSG 1.1, not just the input parent SG.
- Parameters:
- parent_sgint
ITA number of the parent space group (1–230).
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- centeringstr
Lattice centering of the parent cell (
"P","R","F", …).- k_tol, site_tolfloat
Tolerances for k-compatibility and site-fixing comparisons.
- Returns:
- list of MSGResult sorted by n_ops descending (highest-symmetry first).
- Includes all MSG types (I–IV) and all parent SGs in the subgroup lattice.
References
[1]Perez-Mato et al., Annu. Rev. Mater. Res. 45, 217 (2015).
msgjson.schema module#
Load and validate against the MSG operator JSON schema.
msgjson.spglib_source module#
Extract magnetic space group data from spglib 2.x.
spglib indexes MSGs by a UNI number (1–1651). For each UNI number we retrieve metadata and the abstract symmetry operations from the internal database without needing a concrete crystal structure.
Notes#
spglib 2.x uses attribute access (not dict) for MagneticSpaceGroupType.
time_reversals from get_magnetic_symmetry_from_database uses 0 (unitary) and 1 (antiunitary); we convert to theta = +1 / -1.
bns_symbol and og_symbol are not exposed by spglib 2.x; only the numbers.
- get_operators(uni_number: int) list[dict][source]#
Return general-position operators (W, t, theta) for a UNI number.
- Parameters:
- uni_numberint
UNI sequential index (1–1651).
- Returns:
- list of dict with keys:
W : 3x3 list of int – rotation matrix (row-major) t : list of 3 float – fractional translation theta : int (+1 or -1) – time-reversal factor
msgjson.validate module#
Validate an existing msg_operators.json file against the schema.
Module contents#
- class MSGResult(uni_number: 'int', bns_number: 'str', og_number: 'str', msg_type: 'int', parent_sg: 'int', n_ops: 'int', origin_shift: 'tuple' = (0.0, 0.0, 0.0), sites: 'list[SiteResult]' = <factory>)[source]#
Bases:
object- sites: list[SiteResult][source]#
- class SiteResult(site: 'np.ndarray', orbit: 'list[np.ndarray]', moment_basis: 'np.ndarray', n_free: 'int')[source]#
Bases:
object
- analyze_msg(bns_number: str, sites: list[ndarray | list], *, site_tol: float = 0.0001) MSGResult | None[source]#
Compute site-symmetry moment basis for a specific MSG identified by BNS number.
This is the lower-symmetry entry point: the user has already identified the MSG (e.g. from Bilbao/Jana subgroup tables) and wants to know which moment directions are symmetry-allowed at each site.
Unlike
compatible_msgs, this function skips the k-compatibility filter — all operators of the MSG are used as site-symmetry candidates. Use this when the MSG already encodes the k-vector (e.g. a type-IV MSG whose anti-translation captures the magnetic doubling).- Parameters:
- bns_numberstr
BNS label of the target MSG, e.g.
"2.7"for P_S 1̄.- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites in the MSG’s cell.
- site_tolfloat
Tolerance for site-fixing comparisons.
- Returns:
- MSGResult with site data, or
Noneif the BNS number is not found.
- MSGResult with site data, or
- available_ions(table: str = 'j0') list[str][source]#
Return ion labels available in the given table (
"j0"or"j2").
- compatible_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[MSGResult][source]#
Find MSGs compatible with the given parent SG and k-vector.
- Parameters:
- parent_sgint
ITA number of the parent (non-magnetic) space group (1–230).
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- centeringstr
Lattice centering of the parent cell: “P”, “I”, “F”, “A”, “B”, “C”, “R”. Determines which difference vectors W@k - theta*k are considered reciprocal-lattice vectors. Defaults to “P” (primitive). For face-centred parents (e.g. Fm-3m, SG 225) pass centering=”F”.
- k_tolfloat
Tolerance for the k-compatibility check.
- site_tolfloat
Tolerance for orbit and site-symmetry comparisons.
- Returns:
- list of MSGResult, one per compatible MSG, sorted by uni_number.
- domain_operators(msg_bns: str, parent_sg: int, tol: float = 0.0001) list[dict][source]#
Return spatial operators of the parent SG that are absent from the MSG.
These are the “broken symmetry” operations — applying any one of them to a single-domain state generates a distinct but symmetry-equivalent domain. The number of domains equals
len(domain_operators(...)) + 1.This comparison is meaningful when the MSG is a subgroup of the parent SG in the same cell (type-I or type-III MSGs). For type-IV MSGs whose cell differs from the parent (e.g. P_S 1̄ derived from R-3), the function still returns a useful approximation by comparing only the rotational parts of the operators (ignoring translations that differ by the cell doubling).
- Parameters:
- msg_bnsstr
BNS number of the MSG (e.g.
"148.17").- parent_sgint
ITA number of the parent space group (e.g.
148for R-3).- tolfloat
Tolerance for rotation-matrix comparison.
- Returns:
- List of operator dicts from the parent SG type-I MSG whose rotation
- matrix does not appear (with any translation or theta) among the MSG
- operators.
Notes
The number of magnetic domains is:
n_domains = n_unique_W_in_parent / n_unique_W_in_MSG
where both counts use the point-group (unique rotation matrices, ignoring translations). For CrCl3 (R-3 → P_S1̄, BNS 2.7):
|S6| / |Ci| = 6 / 2 = 3domains, whilelen(domain_operators(...))returns 12 (4 distinct broken rotations × 3 R-centering copies).For type-III MSGs within the same parent SG, this function returns an empty list because every rotation matrix of the parent is still present in the MSG (some as antiunitary operations). Domains in that case arise from time-reversal symmetry breaking, not spatial symmetry lowering.
- find_by_bns(bns_number: str) MSGResult | None[source]#
Return an MSGResult (no site data) for the MSG with the given BNS number.
- Parameters:
- bns_numberstr
BNS label as a string, e.g.
"148.17","2.7". Leading/trailing whitespace is stripped.
- Returns:
- MSGResult with an empty
siteslist, orNoneif not found.
- MSGResult with an empty
- form_factor(ion: str, Q_mag: float, *, c2: float = 0.0) float[source]#
Return the magnetic form factor f(|Q|) = <j0> + c2 * <j2>.
- Parameters:
- ionstr
Ion label, e.g.
"Mn2+","Cr3+","Ru1+".- Q_magfloat
|Q| in Å⁻¹.
- c2float
Coefficient of the <j2> correction. For spin-only moments
c2=0(default). For general momentsc2 = 2/g - 1 = L/(L+2S)where g is the Landé g-factor.
- Returns:
- float
Dimensionless form factor.
- j0(ion: str, Q_mag: float) float[source]#
Return <j0(|Q|)> for ion at scattering vector magnitude Q_mag (Å⁻¹).
- j2(ion: str, Q_mag: float) float[source]#
Return <j2(|Q|)> for ion at scattering vector magnitude Q_mag (Å⁻¹).
Uses the parameterization <j2(s)> = [A exp(-as²) + … + D] · s² where s = |Q|/(4π), which correctly gives <j2(0)> = 0.
- magnetic_structure_factors(site_moments: list[tuple[ndarray, ndarray]], hkl: list[tuple[int, int, int]], k: ndarray | list, *, lattice: ndarray | None = None, ion: str | None = None, c2: float = 0.0) ndarray[source]#
Return \(|F_M(Q)|^2\) for magnetic satellite reflections Q = hkl + k.
The magnetic structure factor is:
\[F_M(\mathbf{Q}) = \sum_j f(|Q|)\, \mathbf{m}_j\, e^{2\pi i \mathbf{Q} \cdot \mathbf{r}_j}\]where the sum runs over all orbit sites supplied in site_moments. For spin-only moments
f(|Q|) = <j0(|Q|)>; passing lattice and ion enables the form-factor correction.- Parameters:
- site_momentslist of (r, m) tuples
Output of
orbit_moments(). r in fractional coordinates, m in μ_B (or arbitrary consistent units).- hkllist of (h, k, l)
Nuclear reflection indices. The magnetic satellite is at Q = hkl + k.
- karray_like, shape (3,)
Propagation vector.
- latticendarray, shape (3, 3), optional
Real-space lattice matrix a = lattice[0], b = lattice[1], c = lattice[2] in Å. Required when ion is given.
- ionstr, optional
Ion label for the magnetic form factor (e.g.
"Mn2+","Cr3+"). Requires lattice. When omitted f(Q) = 1 for all reflections.- c2float
<j2>coefficient for the orbital form-factor correction (default 0).
- Returns:
- ndarray, shape (len(hkl),)
\(|F_M(\mathbf{Q})|^2\) in μ_B² (or the square of whatever unit m was given in). This does not include the geometric \(\sin^2\!\alpha\) factor; multiply by
1 − (m̂ · Q̂)²to obtain the physical neutron cross-section term.
- maximal_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], **kwargs) list[MSGResult][source]#
Return k-maximal compatible MSGs that allow a non-zero moment.
Implements the Bilbao MAXMAGN definition [1]: a MSG is k-maximal if no k-compatible supergroup exists anywhere in the subgroup lattice of G1’. Only commensurate 1k orderings are considered.
Each k-maximal MSG represents one conjugacy class of physically equivalent domain-related orderings. For type-IV MSGs the function additionally appends the τ-shifted origin variant — these two results correspond to what MAXMAGN calls “alternatives (domain-related)” within the same conjugacy class. All other domain variants (rotational domains from broken spatial symmetry) are accessible via
domain_operators().For k = 0 the little co-group equals the full parent SG point group, so
subgroup_msgswould include MSGs from unrelated SGs that happen to share the same point group.compatible_msgs(which restricts to the input parent SG) is used instead; it already enumerates both origin shifts for type-IV MSGs.For k ≠ 0 the little co-group is a strict subgroup of the parent SG point group.
subgroup_msgsis used so the true k-maximal MSG is found even when it has a different parent SG than the input — e.g. α-RuCl₃ (parent = 148) whose maximal MSG is BNS 2.7 (parent = 2). For each type-IV MSG at the maximum symmetry level, a second result with the primitive anti-translation origin shift τ is appended.- Parameters:
- parent_sgint
ITA number of the paramagnetic parent space group.
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- **kwargs
Passed to
compatible_msgs/subgroup_msgs:centering,k_tol,site_tol.
- Returns:
- list of MSGResult, sorted by (uni_number, origin_shift).
References
[1]Perez-Mato et al., Annu. Rev. Mater. Res. 45, 217 (2015).
- orbit_moments(msg_result: MSGResult, site_idx: int, m_ref: ndarray, k: ndarray | list, *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[tuple[ndarray, ndarray]][source]#
Return (position, moment) pairs for all orbit sites.
Starting from a reference moment m_ref at
msg_result.sites[site_idx], the function finds the k-compatible MSG operator that maps the reference site to each orbit position and applies the moment transformation rule:m' = θ · det(W) · W @ m
- Parameters:
- msg_resultMSGResult
Result from
maximal_msgs(),subgroup_msgs(), oranalyze_msg().- site_idxint
Index into
msg_result.sitesselecting the reference site.- m_refarray_like, shape (3,)
Moment vector at the reference site in μ_B (or any consistent unit). Must lie within the symmetry-allowed subspace; use
s.moment_basis @ amplitudesto build it from the basis.- karray_like, shape (3,)
Propagation vector in reciprocal-lattice units.
- centeringstr
Lattice centering symbol (
"P","F","I","R", etc.).- k_tolfloat
Tolerance for k-compatibility check.
- site_tolfloat
Tolerance for position matching.
- Returns:
- list of (r, m) tuples
r — fractional position in [0, 1)³, shape (3,) m — moment vector at that position, shape (3,) The list starts with the reference site.
- subgroup_msgs(parent_sg: int, k: ndarray | list, sites: list[ndarray | list], *, centering: str = 'P', k_tol: float = 0.0001, site_tol: float = 0.0001) list[MSGResult][source]#
Find all MSGs compatible with k that are geometric subgroups of the parent SG.
Inspired by the Bilbao k-SUBGROUPSMAG workflow [1] — searches across all parent SGs down to MSG 1.1, not just the input parent SG.
- Parameters:
- parent_sgint
ITA number of the parent space group (1–230).
- karray_like, shape (3,)
Commensurate propagation vector in fractional reciprocal coordinates.
- siteslist of array_like, shape (3,)
Fractional coordinates of the magnetic ion sites.
- centeringstr
Lattice centering of the parent cell (
"P","R","F", …).- k_tol, site_tolfloat
Tolerances for k-compatibility and site-fixing comparisons.
- Returns:
- list of MSGResult sorted by n_ops descending (highest-symmetry first).
- Includes all MSG types (I–IV) and all parent SGs in the subgroup lattice.
References
[1]Perez-Mato et al., Annu. Rev. Mater. Res. 45, 217 (2015).