Skip to content

API Reference

The public API mirrors the Rust crate layout: base (crystal structures and operation containers), dataset (symmetry analysis results), data (crystallographic classification tables), and identify (group identification primitives). The moyopy.interface adapters provide conversion helpers to/from pymatgen and ASE.

This page documents the core types and the space-group API. Layer-group and magnetic-space-group APIs live on additional pages:

Core types

Lattice + sites, the non-magnetic operation container, and the unimodular transformation type used across all group families.

moyopy.Cell 

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

A crystal structure: a lattice plus fractional positions and atomic numbers.

Create a new Cell.

Parameters:

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

Row-wise basis vectors of the lattice. basis[i] is the i-th basis vector.

 required
positions list[list[float]]

Fractional coordinates of each site.

 required
numbers list[int]

Atomic number of each site. Must have the same length as positions.

 required

basis property 

basis: list[list[float]]

Row-wise basis vectors of the lattice.

num_atoms property 

num_atoms: int

Number of atoms in the 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) -> Cell

Deserialize an object from a JSON string.

from_dict classmethod 

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

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

moyopy.Operations

A list of crystallographic symmetry operations (rotation + translation).

num_operations property 

num_operations: int

Number of symmetry operations.

rotations property 

rotations: list[list[list[float]]]

Rotation parts of the symmetry operations.

translations property 

translations: list[list[float]]

Translation parts of the 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) -> Operations

Deserialize an object from a JSON string.

from_dict classmethod 

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

Create an object from a dictionary.

serialize_json 

serialize_json() -> str

Serialize this object to a JSON string.

moyopy.UnimodularTransformation

A unimodular transformation: an integer linear part with determinant +-1 plus an origin shift.

linear property 

linear: list[list[int]]

Linear part (integer 3x3 matrix with determinant +-1).

origin_shift property 

origin_shift: list[float]

Origin shift (fractional coordinates).

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.

Symmetry datasets

Run a symmetry analysis on a moyopy.Cell and inspect the result.

moyopy.MoyoDataset 

MoyoDataset(cell: Cell, *, symprec: float = 0.0001, angle_tolerance: float | None = None, setting: Setting | None = None, rotate_basis: bool = True)

A dataset containing symmetry information of the input crystal structure.

Parameters:

Name Type Description Default
cell Cell

Input crystal structure.

 required
symprec float

Symmetry search tolerance in the unit of cell.basis.

 0.0001
angle_tolerance float | None

Symmetry search tolerance in the unit of radians.

 None
setting Setting | None

Preference for the setting of the space group.

 None
rotate_basis bool

Whether to rotate the basis vectors of the input cell to those of the standardized cell.

 True

angle_tolerance property 

angle_tolerance: float | None

Actually used angle_tolerance in iterative symmetry search.

hall_number property 

hall_number: int

Hall symbol number.

mapping_std_prim property 

mapping_std_prim: list[int]

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

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

number property 

number: int

Space group number.

operations property 

operations: Operations

Symmetry operations in the input cell.

orbits property 

orbits: list[int]

Spglib's crystallographic_orbits not equivalent_atoms.

The i-th atom in the input cell is equivalent to the orbits[i]-th atom in the input 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.

pearson_symbol property 

pearson_symbol: str

Pearson symbol for standardized cell.

prim_std_cell property 

prim_std_cell: Cell

Primitive standardized cell.

Same transformation convention as the standardized cell above::

prim_std_cell.basis.T = std_rotation_matrix @ cell.basis.T @ prim_std_linear
x_prim_std = np.linalg.inv(prim_std_linear) @ (x_input - prim_std_origin_shift)

prim_std_linear property 

prim_std_linear: list[list[float]]

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

prim_std_origin_shift property 

prim_std_origin_shift: list[float]

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

site_symmetry_symbols property 

site_symmetry_symbols: list[str]

Site symmetry symbols for each site in the input cell.

The orientation of the site symmetry is w.r.t. the standardized cell.

std_cell property 

std_cell: Cell

Standardized cell.

The input cell is related to the standardized cell by (std_linear, std_origin_shift) and std_rotation_matrix:

Lattice::

std_cell.basis.T = std_rotation_matrix @ cell.basis.T @ std_linear

Fractional positions::

x_std = np.linalg.inv(std_linear) @ (x_input - std_origin_shift)

std_rotation_matrix is a rigid rotation (orthogonal matrix) applied only to the Cartesian lattice basis. It does not affect fractional coordinates.

std_linear property 

std_linear: list[list[float]]

Linear part of transformation from the input cell to the standardized cell.

std_origin_shift property 

std_origin_shift: list[float]

Origin shift of transformation from the input cell to the standardized cell.

std_rotation_matrix property 

std_rotation_matrix: list[list[float]]

Rigid rotation (orthogonal matrix) applied to the lattice basis.

symprec property 

symprec: float

Actually used symprec in iterative symmetry search.

wyckoffs property 

wyckoffs: list[str]

Wyckoff letters for each site in the input cell.

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.

normalizer_wyckoff_positions 

normalizer_wyckoff_positions(*, preserve_chirality: bool = False, primitive: bool = False) -> NormalizerWyckoffPositions

Wyckoff positions of the standardized cell under the action of the Euclidean normalizer, decomposed into the stabilizer of the Wyckoff sequence and coset representatives of the distinct sequences.

Parameters:

Name Type Description Default
preserve_chirality bool

If True, restrict to the chirality-preserving subgroup of the Euclidean normalizer.

 False
primitive bool

If True, the returned operations are expressed in the primitive standardized basis; otherwise they are expressed in the conventional standardized basis, in which they act directly on std_cell.

 False

serialize_json 

serialize_json() -> str

Serialize an object to a JSON string.

Crystallographic data

Hall symbols, settings, centering, classification tables, and helpers to fetch operations by ITA number.

moyopy.Setting

Preference for the setting of the space group.

as_dict 

as_dict() -> dict[str, Any]

Convert an object to a dictionary

hall_number classmethod 

hall_number(hall_number: int) -> Setting

Specific Hall number from 1 to 530.

serialize_json 

serialize_json() -> str

Serialize an object to a JSON string

spglib classmethod 

spglib() -> Setting

The setting of the smallest Hall number.

standard classmethod 

standard() -> Setting

Unique axis b, cell choice 1 for monoclinic, hexagonal axes for rhombohedral, and origin choice 2 for centrosymmetric space groups.

moyopy.Centering

lattice_points property 

lattice_points: list[list[float]]

Unique lattice points.

linear property 

linear: list[list[int]]

Transformation matrix.

order property 

order: int

Order of the centering.

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.HallSymbolEntry 

HallSymbolEntry(hall_number: int)

An entry containing space-group information for a specified hall_number.

arithmetic_number property 

arithmetic_number: int

Number for arithmetic crystal classes (1 - 73).

centering property 

centering: Centering

Centering.

hall_number property 

hall_number: int

Number for Hall symbols (1 - 530).

hall_symbol property 

hall_symbol: str

Hall symbol.

hm_full property 

hm_full: str

Hermann-Mauguin symbol in full notation.

hm_short property 

hm_short: str

Hermann-Mauguin symbol in short notation.

number property 

number: int

ITA number for space group types (1 - 230).

setting property 

setting: Setting

Setting.

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.SpaceGroupType 

SpaceGroupType(number: int)

Space-group type information.

arithmetic_number property 

arithmetic_number: int

Number for arithmetic crystal classes (1 - 73).

arithmetic_symbol property 

arithmetic_symbol: str

Symbol for arithmetic crystal class.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/arithmetic_crystal_class.rs for string values.

bravais_class property 

bravais_class: str

Bravais class.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/classification.rs for string values.

crystal_family property 

crystal_family: str

Crystal family.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/classification.rs for string values.

crystal_system property 

crystal_system: str

Crystal system.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/classification.rs for string values.

geometric_crystal_class property 

geometric_crystal_class: str

Geometric crystal class.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/classification.rs for string values.

hm_full property 

hm_full: str

Hermann-Mauguin symbol in full notation.

hm_short property 

hm_short: str

Hermann-Mauguin symbol in short notation.

lattice_system property 

lattice_system: str

Lattice system.

See https://github.com/spglib/moyo/blob/main/moyo/src/data/classification.rs for string values.

number property 

number: int

ITA number for space group types (1 - 230).

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.ArithmeticCrystalClass 

ArithmeticCrystalClass(arithmetic_number: int)

Arithmetic crystal class information.

arithmetic_number property 

arithmetic_number: int

Number for arithmetic crystal classes (1 - 73).

arithmetic_symbol property 

arithmetic_symbol: str

Symbol for arithmetic crystal class.

bravais_class property 

bravais_class: str

Bravais class.

geometric_crystal_class property 

geometric_crystal_class: str

Geometric crystal class.

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.operations_from_number 

operations_from_number(number: int, *, setting: Setting | None = None, primitive: bool = False) -> Operations

Group identification

Identify point groups and space groups from a primitive list of symmetry operations.

moyopy.PointGroup 

PointGroup(prim_rotations: list[list[int]], *, basis: list[list[float]] | None = None)

Point group identified from a list of rotation matrices.

Identify the point group of the given primitive rotations.

Parameters:

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

Rotation matrices in the primitive cell.

 required
basis list[list[float]] | None

Row-wise basis vectors of the primitive lattice. If None, an identity basis is assumed.

 None

arithmetic_number property 

arithmetic_number: int

Number for the arithmetic crystal class (1 - 73).

prim_trans_mat property 

prim_trans_mat: list[list[int]]

Transformation matrix from the input primitive basis to the standardized basis.

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.

moyopy.SpaceGroup 

SpaceGroup(prim_rotations: list[list[int]], prim_translations: list[list[float]], *, basis: list[list[float]] | None = None, setting: Setting | None = None, epsilon: float = 0.0001)

Space group identified from a list of primitive symmetry operations.

Identify the space group from primitive rotations and translations.

Parameters:

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

Rotation matrices of the symmetry operations of the primitive cell.

 required
prim_translations list[list[float]]

Translation vectors of the symmetry operations of the primitive cell.

 required
basis list[list[float]] | None

Row-wise basis vectors of the primitive lattice. If None, an identity basis is assumed.

 None
setting Setting | None

Preference for the standardized setting of the detected space-group type.

 None
epsilon float

Numerical tolerance for matching translations.

 0.0001

hall_number property 

hall_number: int

Hall symbol number (1 - 530) for the chosen setting.

linear property 

linear: list[list[int]]

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

number property 

number: int

ITA number for the identified space group (1 - 230).

origin_shift property 

origin_shift: list[float]

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

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.

moyopy.integral_normalizer 

integral_normalizer(prim_rotations: list[list[list[int]]], prim_translations: list[list[float]], *, prim_generators: list[int] | None = None, epsilon: float = 0.0001) -> list[UnimodularTransformation]

Compute the integral normalizer of a space group.

Returns the unimodular transformations that conjugate the given space group into itself.

Parameters:

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

Rotation matrices of the symmetry operations of the primitive cell.

 required
prim_translations list[list[float]]

Translation vectors of the symmetry operations of the primitive cell.

 required
prim_generators list[int] | None

Optional indices of operations to use as generators. If None, a small generating set is derived automatically.

 None
epsilon float

Numerical tolerance for matching translations.

 0.0001

Adapters

Convert between moyopy.Cell and pymatgen Structure / ASE Atoms. Requires the optional dependencies installed via pip install moyopy[interface]. The magnetic counterpart moyopy.interface.MoyoNonCollinearMagneticAdapter lives on the Magnetic Space Group page.

moyopy.interface.MoyoAdapter

from_disordered_structure staticmethod 

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

Convert a disordered pymatgen Structure to a Moyo Cell.

Parameters:

Name Type Description Default
structure Structure

A pymatgen Structure object, which may contain disordered sites.

 required

Returns:

Name Type Description
cell Cell

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

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

from_py_obj staticmethod 

from_py_obj(struct: Structure | Atoms | MSONAtoms) -> Cell

Convert a Python atomic structure object to a Moyo Cell.

Args: struct: Currently supports pymatgen Structure, ASE Atoms, and MSONAtoms

Returns: moyopy.Cell: The converted Moyo cell

from_structure staticmethod 

from_structure(structure: Structure) -> Cell

Convert a pymatgen Structure to a Moyo Cell.

get_structure staticmethod 

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

Convert a Moyo Cell to a pymatgen Structure.

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

Parameters:

Name Type Description Default
cell Cell

The Moyo Cell to convert.

 required
unique_species_mapping dict[int, Composition] | None

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

 None

Returns:

Name Type Description
structure Structure

The converted pymatgen Structure object.