Skip to content

Magnetic Space Group API

Magnetic crystal structures, symmetry analysis, classification tables, and group identification for the 1,651 magnetic space groups. Shared types such as moyopy.Cell, moyopy.Operations, moyopy.UnimodularTransformation, and moyopy.PointGroup are documented on the API Reference hub.

Magnetic core types

Lattice + sites with magnetic moments, plus the magnetic operation container.

moyopy.CollinearMagneticCell 

CollinearMagneticCell(basis: list[list[float]], positions: list[list[float]], numbers: list[int], magnetic_moments: list[float])

A crystal structure with collinear magnetic moments.

Create a new CollinearMagneticCell.

Parameters:

Name Type Description Default
basis list[list[float]]

Row-wise basis vectors of the lattice.

 required
positions list[list[float]]

Fractional coordinates of each site.

 required
numbers list[int]

Atomic number of each site.

 required
magnetic_moments list[float]

Scalar magnetic moment of each site (collinear).

 required

basis property 

basis: list[list[float]]

Row-wise basis vectors of the lattice.

magnetic_moments property 

magnetic_moments: list[float]

Scalar magnetic moment of each site.

num_atoms property 

num_atoms: int

Number of atoms in the magnetic cell.

numbers property 

numbers: list[int]

Atomic number of each site.

positions property 

positions: list[list[float]]

Fractional coordinates of each site.

as_dict 

as_dict() -> dict[str, Any]

Convert this object to a dictionary.

deserialize_json classmethod 

deserialize_json(json_str: str) -> CollinearMagneticCell

Deserialize an object from a JSON string.

from_dict classmethod 

from_dict(data: dict[str, Any]) -> CollinearMagneticCell

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

moyopy.NonCollinearMagneticCell 

NonCollinearMagneticCell(basis: list[list[float]], positions: list[list[float]], numbers: list[int], magnetic_moments: list[list[float]])

A crystal structure with non-collinear (vector) magnetic moments.

Create a new NonCollinearMagneticCell.

Parameters:

Name Type Description Default
basis list[list[float]]

Row-wise basis vectors of the lattice.

 required
positions list[list[float]]

Fractional coordinates of each site.

 required
numbers list[int]

Atomic number of each site.

 required
magnetic_moments list[list[float]]

Three-component magnetic moment vector of each site.

 required

basis property 

basis: list[list[float]]

Row-wise basis vectors of the lattice.

magnetic_moments property 

magnetic_moments: list[list[float]]

Three-component magnetic moment vector of each site.

num_atoms property 

num_atoms: int

Number of atoms in the magnetic cell.

numbers property 

numbers: list[int]

Atomic number of each site.

positions property 

positions: list[list[float]]

Fractional coordinates of each site.

as_dict 

as_dict() -> dict[str, Any]

Convert this object to a dictionary.

deserialize_json classmethod 

deserialize_json(json_str: str) -> NonCollinearMagneticCell

Deserialize an object from a JSON string.

from_dict classmethod 

from_dict(data: dict[str, Any]) -> NonCollinearMagneticCell

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

moyopy.MagneticOperations

A list of magnetic symmetry operations (rotation + translation + time reversal).

num_operations property 

num_operations: int

Number of magnetic symmetry operations.

rotations property 

rotations: list[list[list[int]]]

Rotation parts of the magnetic symmetry operations.

time_reversals property 

time_reversals: list[bool]

Time-reversal flag for each magnetic symmetry operation.

translations property 

translations: list[list[float]]

Translation parts of the magnetic symmetry operations (fractional coordinates).

as_dict 

as_dict() -> dict[str, Any]

Convert this object to a dictionary.

deserialize_json classmethod 

deserialize_json(json_str: str) -> MagneticOperations

Deserialize an object from a JSON string.

from_dict classmethod 

from_dict(data: dict[str, Any]) -> MagneticOperations

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

Symmetry datasets

Run a symmetry analysis on a magnetic cell and inspect the result.

moyopy.MoyoCollinearMagneticDataset 

MoyoCollinearMagneticDataset(magnetic_cell: CollinearMagneticCell, *, symprec: float = 0.0001, angle_tolerance: float | None = None, mag_symprec: float | None = None, is_axial: bool = False, rotate_basis: bool = True)

A dataset containing magnetic symmetry information of the input collinear magnetic structure.

Parameters:

Name Type Description Default
magnetic_cell CollinearMagneticCell

Input collinear magnetic structure.

 required
symprec float

Symmetry search tolerance in the unit of magnetic_cell.basis.

 0.0001
angle_tolerance float | None

Symmetry search tolerance in the unit of radians.

 None
mag_symprec float | None

Symmetry search tolerance in the unit of magnetic moments.

 None
is_axial bool

Whether the magnetic moments are axial on improper operations.

 False
rotate_basis bool

Whether to apply the canonical Cartesian orientation to the refined lattice. Lattice, positions, and magnetic moments are refined for either value.

 True

angle_tolerance property 

angle_tolerance: float | None

Actually used angle_tolerance in iterative symmetry search.

mag_symprec property 

mag_symprec: float | None

Actually used mag_symprec in iterative symmetry search.

magnetic_operations property 

magnetic_operations: MagneticOperations

Magnetic symmetry operations in the input cell.

mapping_std_prim property 

mapping_std_prim: list[int]

Mapping sites in the input magnetic cell to those in the primitive standardized magnetic cell.

The i-th atom in the input magnetic cell is mapped to the mapping_to_std_prim[i]-th atom in the primitive standardized magnetic cell.

orbits property 

orbits: list[int]

The i-th atom in the input magnetic cell is equivalent to the orbits[i]-th atom in the input magnetic cell. For example, orbits=[0, 0, 2, 2, 2, 2] means the first two atoms are equivalent and the last four atoms are equivalent to each other.

prim_std_linear property 

prim_std_linear: list[list[float]]

Linear part of the transformation from the input magnetic cell to prim_std_mag_cell.

Its determinant has the same sign as the input basis determinant.

prim_std_mag_cell property 

prim_std_mag_cell: CollinearMagneticCell

Primitive standardized magnetic cell.

Its basis is right-handed for either input handedness and either rotate_basis value.

Uses prim_std_linear and prim_std_origin_shift with the same pre-refinement coordinate convention as std_mag_cell.

prim_std_origin_shift property 

prim_std_origin_shift: list[float]

Origin shift of the transformation from the input magnetic cell to prim_std_mag_cell.

std_linear property 

std_linear: list[list[float]]

Linear part of the transformation from the input magnetic cell to std_mag_cell.

Its determinant has the same sign as the input basis determinant.

std_mag_cell property 

std_mag_cell: CollinearMagneticCell

Standardized magnetic cell.

Its basis is right-handed for either input handedness and either rotate_basis value.

Uses the same pre-refinement coordinate convention as MoyoDataset.std_cell. Magnetic moments are rotated by std_rotation_matrix, then averaged under the magnetic group using the refined lattice. Lattice stretch is not applied to magnetic moments. Passive basis changes leave Cartesian magnetic moments unchanged.

std_origin_shift property 

std_origin_shift: list[float]

Origin shift of the transformation from the input magnetic cell to std_mag_cell.

std_rotation_matrix property 

std_rotation_matrix: list[list[float]]

Proper Cartesian rotation applied to the refined lattice and magnetic moments.

Identity when rotate_basis is false; it does not encode the lattice stretch.

symprec property 

symprec: float

Actually used symprec in iterative symmetry search.

uni_number property 

uni_number: int

UNI number for magnetic space-group type.

as_dict 

as_dict() -> dict[str, Any]

Convert an object to a dictionary.

deserialize_json classmethod 

deserialize_json(json_str: str) -> Self

Deserialize an object from a JSON string.

from_dict classmethod 

from_dict(obj: dict[str, Any]) -> Self

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize an object to a JSON string.

moyopy.MoyoNonCollinearMagneticDataset 

MoyoNonCollinearMagneticDataset(magnetic_cell: NonCollinearMagneticCell, *, symprec: float = 0.0001, angle_tolerance: float | None = None, mag_symprec: float | None = None, is_axial: bool = True, rotate_basis: bool = True)

A dataset containing magnetic symmetry information of the input non-collinear magnetic structure.

Parameters:

Name Type Description Default
magnetic_cell NonCollinearMagneticCell

Input non-collinear magnetic structure.

 required
symprec float

Symmetry search tolerance in the unit of magnetic_cell.basis.

 0.0001
angle_tolerance float | None

Symmetry search tolerance in the unit of radians.

 None
mag_symprec float | None

Symmetry search tolerance in the unit of magnetic moments.

 None
is_axial bool

Whether the magnetic moments are axial on improper operations.

 True
rotate_basis bool

Whether to apply the canonical Cartesian orientation to the refined lattice. Lattice, positions, and magnetic moments are refined for either value.

 True

angle_tolerance property 

angle_tolerance: float | None

Actually used angle_tolerance in iterative symmetry search.

mag_symprec property 

mag_symprec: float | None

Actually used mag_symprec in iterative symmetry search.

magnetic_operations property 

magnetic_operations: MagneticOperations

Magnetic symmetry operations in the input cell.

mapping_std_prim property 

mapping_std_prim: list[int]

Mapping sites in the input magnetic cell to those in the primitive standardized magnetic cell.

The i-th atom in the input magnetic cell is mapped to the mapping_to_std_prim[i]-th atom in the primitive standardized magnetic cell.

orbits property 

orbits: list[int]

The i-th atom in the input magnetic cell is equivalent to the orbits[i]-th atom in the input magnetic cell. For example, orbits=[0, 0, 2, 2, 2, 2] means the first two atoms are equivalent and the last four atoms are equivalent to each other.

prim_std_linear property 

prim_std_linear: list[list[float]]

Linear part of the transformation from the input magnetic cell to prim_std_mag_cell.

Its determinant has the same sign as the input basis determinant.

prim_std_mag_cell property 

prim_std_mag_cell: NonCollinearMagneticCell

Primitive standardized magnetic cell.

Its basis is right-handed for either input handedness and either rotate_basis value.

Uses prim_std_linear and prim_std_origin_shift with the same pre-refinement coordinate convention as std_mag_cell.

prim_std_origin_shift property 

prim_std_origin_shift: list[float]

Origin shift of the transformation from the input magnetic cell to prim_std_mag_cell.

std_linear property 

std_linear: list[list[float]]

Linear part of the transformation from the input magnetic cell to std_mag_cell.

Its determinant has the same sign as the input basis determinant.

std_mag_cell property 

std_mag_cell: NonCollinearMagneticCell

Standardized magnetic cell.

Its basis is right-handed for either input handedness and either rotate_basis value.

Uses the same pre-refinement coordinate convention as MoyoDataset.std_cell. Magnetic moments are rotated by std_rotation_matrix, then averaged under the magnetic group using the refined lattice. Lattice stretch is not applied to magnetic moments. Passive basis changes leave Cartesian magnetic moments unchanged.

std_origin_shift property 

std_origin_shift: list[float]

Origin shift of the transformation from the input magnetic cell to std_mag_cell.

std_rotation_matrix property 

std_rotation_matrix: list[list[float]]

Proper Cartesian rotation applied to the refined lattice and magnetic moments.

Identity when rotate_basis is false; it does not encode the lattice stretch.

symprec property 

symprec: float

Actually used symprec in iterative symmetry search.

uni_number property 

uni_number: int

UNI number for magnetic space-group type.

as_dict 

as_dict() -> dict[str, Any]

Convert an object to a dictionary.

deserialize_json classmethod 

deserialize_json(json_str: str) -> Self

Deserialize an object from a JSON string.

from_dict classmethod 

from_dict(obj: dict[str, Any]) -> Self

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize an object to a JSON string.

Crystallographic data

Classification tables and helpers to fetch operations by UNI number.

moyopy.MagneticSpaceGroupType 

MagneticSpaceGroupType(uni_number: int)

Magnetic space-group type information.

bns_number property 

bns_number: str

BNS number e.g. '151.32'

construct_type property 

construct_type: int

Construct type of magnetic space group from 1 to 4.

litvin_number property 

litvin_number: int

Serial number in Litvin's Magnetic group tables <https://www.iucr.org/publ/978-0-9553602-2-0>_.

number property 

number: int

ITA number for reference space group in BNS setting.

og_number property 

og_number: str

OG number e.g. '153.4.1270'

uni_number property 

uni_number: int

Serial number of UNI (and BNS) symbols.

as_dict 

as_dict() -> dict[str, Any]

Convert an object to a dictionary

serialize_json 

serialize_json() -> str

Serialize an object to a JSON string

moyopy.magnetic_operations_from_uni_number 

magnetic_operations_from_uni_number(uni_number: int, *, primitive: bool = False) -> MagneticOperations

Group identification

Identify magnetic space groups from a primitive list of magnetic symmetry operations.

moyopy.MagneticSpaceGroup 

MagneticSpaceGroup(prim_rotations: list[list[list[int]]], prim_translations: list[list[float]], prim_time_reversals: list[bool], *, basis: list[list[float]] | None = None, epsilon: float = 0.0001)

Magnetic space group identified from a list of primitive magnetic operations.

Identify the magnetic space group from primitive magnetic operations.

Parameters:

Name Type Description Default
prim_rotations list[list[list[int]]]

Rotation matrices of the magnetic operations of the primitive cell.

 required
prim_translations list[list[float]]

Translation vectors of the magnetic operations of the primitive cell.

 required
prim_time_reversals list[bool]

Time-reversal flag for each magnetic operation of the primitive cell.

 required
basis list[list[float]] | None

Row-wise basis vectors of the primitive lattice, of either handedness. When given, the lattice is reduced to a right-handed basis before matching; the returned transformation refers to the original input basis. If None, operations must already use a reduced primitive basis with a right-handed reference orientation. Matching then uses only proper transformations; the actual Cartesian handedness cannot be inferred.

 None
epsilon float

Numerical tolerance for matching translations.

 0.0001

linear property 

linear: list[list[int]]

Linear part of the transformation from the input primitive basis to the standardized basis.

origin_shift property 

origin_shift: list[float]

Origin shift of the transformation from the input primitive basis to the standardized basis.

uni_number property 

uni_number: int

Serial number of UNI (and BNS) symbols.

as_dict 

as_dict() -> dict[str, Any]

Convert this object to a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

Adapters

Convert between moyopy.NonCollinearMagneticCell and pymatgen Structure / ASE Atoms. Requires the optional dependencies installed via pip install moyopy[interface].

moyopy.interface.MoyoNonCollinearMagneticAdapter

from_disordered_structure staticmethod 

from_disordered_structure(structure: Structure) -> tuple[NonCollinearMagneticCell, dict[int, Composition]]

Convert a disordered pymatgen Structure with non-collinear magnetic moments to a Moyo NonCollinearMagneticCell.

Parameters:

Name Type Description Default
structure Structure

A pymatgen Structure object, which may contain disordered sites. Must have non-collinear magnetic moments in site_properties['magmom'].

 required

Returns:

Name Type Description
magnetic_cell NonCollinearMagneticCell

The converted Moyo NonCollinearMagneticCell object.
unique_species_mapping dict[int, Composition]

A mapping from integer indices used in the Moyo NonCollinearMagneticCell to the original pymatgen SpeciesLike objects.

from_structure staticmethod 

from_structure(structure: Structure) -> NonCollinearMagneticCell

Convert a pymatgen Structure with non-collinear magnetic moments to a Moyo NonCollinearMagneticCell.

get_structure staticmethod 

get_structure(magnetic_cell: NonCollinearMagneticCell, *, unique_species_mapping: dict[int, Composition] | None = None) -> Structure

Convert a Moyo NonCollinearMagneticCell to a pymatgen Structure.

If the NonCollinearMagneticCell was created from a disordered Structure, the unique_species_mapping should be provided to reconstruct the original species.

Parameters:

Name Type Description Default
magnetic_cell NonCollinearMagneticCell

The Moyo NonCollinearMagneticCell to convert.

 required
unique_species_mapping dict[int, Composition] | None

A mapping from integer indices used in the Moyo NonCollinearMagneticCell to the original pymatgen SpeciesLike objects. If None, assumes the NonCollinearMagneticCell was created from an ordered Structure.

 None

Returns:

Name Type Description
structure Structure

The converted pymatgen Structure object with magnetic moments in site_properties['magmom'].