Skip to content

spinCIF

Read and write SpinForge's supported subset of the draft spinCIF format.

scif

Write spin-symmetry-adapted magnetic structures as spinCIF (.scif) files.

Follows the draft spinCIF dictionary (COMCIFS/spinCIF, core_spin.dic). A spinCIF file describes a magnetic structure under its spin space group (SSG) instead of a magnetic space group: each symmetry operation carries an independent spin-space operation (_space_group_symop_spin_operation.uvw) next to its spatial part (.xyzt), and moments are given in an explicitly defined spin basis (_atom_site_spin_moment.axis_u/v/w).

Conventions used by this writer:

  • The spin basis is the orthonormal crystal-Cartesian frame x || a, z || c* (y completing a right-handed set), declared via _space_group_spin.transform_spinframe_P_abc (the unit vectors written as linear combinations of the lattice vectors; the tag every COMCIFS reference file uses, for interoperability with readers tuned to them).
  • The nontrivial SSG operations are written in the supercell setting of the :class:~spinforge.configuration.SpinSymmetryAdaptedStructure; the spin translation coset goes into the optional _space_group_symop_spin_lattice loop.
  • The trivial spin-only group is not listed as operations (per the spec); it enters through _space_group_spin.collinear_direction_xyz / _space_group_spin.coplanar_perp_uvw, filled from the spinspg.spin.SpinOnlyGroup the structure was enumerated with.

The dictionary is explicitly preliminary upstream ("all dictionary aspects and file formats are subject to change"): the targeted revision is pinned as :data:SPINCIF_REVISION and stamped into every written file, so keep this writer aligned with https://github.com/COMCIFS/spinCIF when it evolves.

SPINCIF_REVISION module-attribute 

SPINCIF_REVISION = '2026-08-06 (COMCIFS/spinCIF@4142eb935045)'

Revision of the draft spinCIF dictionary this writer targets.

The upstream dictionary is preliminary and may change; bump this together with any format adjustments. The revision is stamped into every written file.

SpinCifReader 

SpinCifReader(text: str, *, symprec: float = 0.0001)

Read a spinCIF string written by :class:SpinCifWriter.

Attributes:

Name Type Description
operations, spin_lattice

Rows of the _space_group_symop_spin_operation / _space_group_symop_spin_lattice loops as (rotation, translation, time_reversal, spin_matrix) tuples, with the spin matrix in the declared spin basis.
sites

(label, symbol, frac_position, moment_uvw, multiplicity) per asymmetric-unit site (zero moment when the site has no _atom_site_spin_moment row).
lattice

:class:pymatgen.core.Lattice from the cell tags.
spin_basis

Unit vectors of the declared spin basis as rows (Cartesian, in the lattice's own frame); moments expand as components @ spin_basis.
collinear_direction_xyz, coplanar_perp_uvw

The spin-only tag values, "." when not applicable.

Parameters:

Name Type Description Default
text str

The spinCIF content.

 required
symprec float

Tolerance (fractional units) for merging symmetry-equivalent positions and for moment consistency when expanding the orbits.

 0.0001

collinear_direction_xyz instance-attribute 

collinear_direction_xyz = block.data['_space_group_spin.collinear_direction_xyz']

coplanar_perp_uvw instance-attribute 

coplanar_perp_uvw = block.data['_space_group_spin.coplanar_perp_uvw']

lattice instance-attribute 

lattice = Lattice.from_parameters(*(float(block.data[f'_cell_length_{name}']) for name in 'abc'), *(float(block.data[f'_cell_angle_{name}']) for name in ('alpha', 'beta', 'gamma')))

operations instance-attribute 

operations = _read_symop_loop(block, '_space_group_symop_spin_operation')

sites instance-attribute 

sites = [(label, symbol, np.array([float(fx), float(fy), float(fz)]), moments.get(label, np.zeros(3)), int(multiplicity)) for label, symbol, fx, fy, fz, multiplicity in zip(block.data['_atom_site_label'], block.data['_atom_site_type_symbol'], block.data['_atom_site_fract_x'], block.data['_atom_site_fract_y'], block.data['_atom_site_fract_z'], block.data['_atom_site_symmetry_multiplicity'])]

spin_basis instance-attribute 

spin_basis = _read_spin_basis(block, text, np.array(self.lattice.matrix))

spin_lattice instance-attribute 

spin_lattice = _read_symop_loop(block, '_space_group_symop_spin_lattice')

expanded_operations 

expanded_operations() -> list[SymmetryOperation]

Products of the spin-lattice and operation loops (the full listed group).

from_file classmethod 

from_file(filename: str | PathLike[str], *, symprec: float = 0.0001) -> SpinCifReader

get_structure 

get_structure() -> Structure

Expand the asymmetric unit into the full magnetic structure.

Moments are returned as Cartesian magmom site properties in the lattice's own Cartesian frame. Raises if an orbit disagrees with its _atom_site_symmetry_multiplicity or transforms inconsistently.

SpinCifWriter 

SpinCifWriter(sas: SpinSymmetryAdaptedStructure, nssg: NontrivialSpinSpaceGroup, magnetic_moments: NDArrayFloat, *, spin_only_group: SpinOnlyGroup, data_name: str = 'spinforge', parent_space_group_type: SpaceGroupType | None = None, site_occupancies: Sequence[float] | NDArrayFloat | None = None, atol: float = 1e-05)

A pymatgen-style writer for spinCIF (draft COMCIFS core_spin.dic).

Mirrors :class:spinforge.mcif.MCifWriter: str(writer) returns the spinCIF text and writer.write_file(path) writes it.

Parameters:

Name Type Description Default
sas SpinSymmetryAdaptedStructure

Spin-symmetry-adapted structure providing the supercell and the moment basis (used for the symmform_uvw restrictions).

 required
nssg NontrivialSpinSpaceGroup

The nontrivial spin space group the structure was generated from, in the primitive input-cell setting.

 required
spin_only_group SpinOnlyGroup

The trivial spin-only group the structure was enumerated with; its type and axis fill _space_group_spin.collinear_direction_xyz / coplanar_perp_uvw.

 required
magnetic_moments NDArrayFloat

Cartesian magnetic moments per supercell site, shape (num_supercell_sites, 3), exactly as passed to :meth:SpinSymmetryAdaptedStructure.generate_with_magnetic_moments. For structures from generate_oriented use :meth:from_oriented, which also conjugates the spin operations by the MSG rotation.

 required
site_occupancies Sequence[float] | NDArrayFloat | None

Fractional occupancy per supercell site (None = fully occupied). Written as _atom_site_occupancy; must be invariant under the SSG operations, since one asymmetric-unit row represents each orbit.

 None
data_name str

CIF data block name.

 'spinforge'
parent_space_group_type SpaceGroupType | None

Parent (nonmagnetic) space-group type; written as _parent_space_group tags when given.

 None
atol float

Tolerance for spin-space and translation checks (coefficient snapping, orthogonality). Site matching uses the supercell's own symprec via :meth:Supercell.site_permutations.

 1e-05

from_oriented classmethod 

from_oriented(sas: SpinSymmetryAdaptedStructure, nssg: NontrivialSpinSpaceGroup, structure: Structure, msg: MagneticSpaceSubgroup, *, spin_only_group: SpinOnlyGroup, data_name: str = 'spinforge', parent_space_group_type: SpaceGroupType | None = None, site_occupancies: Sequence[float] | NDArrayFloat | None = None, atol: float = 1e-05) -> SpinCifWriter

Writer for one (structure, msg) pair from generate_oriented.

Takes the moments from the structure's magmom site property and conjugates the spin parts of the SSG operations by the MSG rotation msg.Q that generate_oriented applied to them.

write_file 

write_file(filename: str, mode: str = 'wt') -> None

Write the spinCIF to filename.