findspingroup 0.13.13

Spin space group (SSG) symmetry analysis toolkit for magnetic materials. Automatically identifies and classifies SSGs, generating symmetry operations, spin Wyckoff positions, and spin Brillouin zones. Designed for integration with first-principles and high-throughput computational workflows.

findspingroup

findspingroup is a Python toolkit for identifying and analyzing Spin Space Group (SSG) symmetry of magnetic crystal structures.
Given a magnetic CIF file, it determines the corresponding spin space group, constructs a standardized primitive magnetic cell, and provides symmetry- and property-related results for downstream first-principles workflows.

The project is designed for research use, high-throughput screening, and integration with DFT pipelines.

What it does

Given a magnetic structure, findspingroup can:

• identify the spin space group and index
• construct primitive and standardized settings
• expose symmetry operations and international-style symbols
• export repo-generated .scif snapshots for roundtrip and workflow use
• provide symmetry-constrained property outputs for downstream calculations

Installation

From PyPI

pip install findspingroup

Python version: >= 3.11

From source

git clone https://github.com/LiuQH-lab/FindSpinGroup.git
cd FindSpinGroup
pip install -e .

30-second example

from findspingroup import example_path, find_spin_group

result = find_spin_group(example_path("0.800_MnTe.mcif"))
print(result.index)
print(result.acc)
print(result.convention_ssg_international_linear)

Minimal smoke check:

python - <<'PY'
from findspingroup import example_path, find_spin_group
result = find_spin_group(example_path("0.800_MnTe.mcif"))
print(result.index)
print(result.convention_ssg_international_linear)
PY

Supported inputs

findspingroup accepts:

• standard .cif
• magnetic .mcif
• repo-generated .scif
• a narrow first-version magnetic POSCAR contract used by this project

Main API

def find_spin_group(
    cif: str,
    space_tol: float = 0.02,
    mtol: float = 0.02,
    meigtol: float = 0.00002,
    matrix_tol: float = 0.01,
) -> MagSymmetryResult

The function returns a MagSymmetryResult object containing the symmetry analysis result.

Common outputs

Useful fields on MagSymmetryResult include:

• index
• acc
• msg_num
• msg_symbol
• convention_ssg_international_linear
• gspg_symbol_linear
• scif

Example:

from findspingroup import example_path, find_spin_group

result = find_spin_group(example_path("1.237_VCl2.mcif"))

print("index:", result.index)
print("acc:", result.acc)
print("msg:", result.msg_symbol)
print("convention:", result.convention_ssg_international_linear)

Input details

findspingroup supports standard .cif, magnetic .mcif, the current repo-generated .scif files, and a narrow first-version POSCAR parser for repo-generated magnetic POSCAR text.

• Standard CIF: Uses structural positions.
• MCIF (Magnetic CIF): Supports files generated by FINDSYM, ISOTROPY, or Vesta.
  • The parser looks for _atom_site_moment tags.
  • It automatically handles magnetic vectors ($m_x, m_y, m_z$).
• SCIF: Supports the current repo-generated .scif contract for generator / parser roundtrip work.
• POSCAR: Currently supports the repo-generated CrystalCell.to_poscar(...) contract only.
  • official POSCAR structural variants:
    • Direct
    • Cartesian
    • optional Selective dynamics
    • one / three scale factors
    • negative target-volume scale
  • optional trailing # MAGMOM= line
    • if absent, moments default to zero
    • multiple #, tabs, and extra spaces around MAGMOM = are tolerated
  • if no inline MAGMOM is present, a sibling INCAR MAGMOM entry is also supported
    • repeated entries such as 6*0.0
    • ; inline statements
    • \\ continuation
    • # / ! comments
  • NIONS scalar form is currently promoted to the default z axis
  • basename POSCAR / CONTCAR or suffix .poscar / .vasp
  • species names are still required; VASP4 species-omitted files are not yet supported

.scif export and roundtrip

findspingroup can export a repo-generated spinCIF-style .scif snapshot from a MagSymmetryResult, and can also parse that generated .scif back through the same public input path.

from findspingroup import example_path, find_spin_group

result = find_spin_group(example_path("0.800_MnTe.mcif"))

# Default public `.scif` output: legacy profile in the oriented-G0 setting.
scif_text = result.scif

# The same output is also available explicitly.
assert scif_text == result.to_scif(profile="legacy", cell_mode="g0std_oriented")

# Additional export profiles / cell modes exist for audit and roundtrip work.
scif_working = result.to_scif(profile="spincif_working", cell_mode="g0std_oriented")
scif_primitive = result.to_scif(profile="legacy", cell_mode="magnetic_primitive")

Current .scif generator rules:

• repo-local FINDSPINGROUP metadata is emitted under CIF-legal _space_group_spin.fsg_* tags
• symmetry-operation and transform coefficients keep full precision by default
• values close to simple fractions or common square-root forms may be written as symbolic expressions such as 1/3, 2/3, or sqrt(6)/3
• repo-generated .scif files can be parsed back with find_spin_group(...) and are regression-tested to preserve the identified index

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.