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.
SpinCifWriter.from_structure preserves constituent chemistry and accepts the explicit spin_rotation used for sampled moments, independently of an MSG object. The Structure's magnetic flag distinguishes an absent magnetic declaration from an explicitly zero magmom.
The reader preserves separate constituent rows, including coincident rows with different moments. Occupancies and occupied-atom moments remain separate; a mean-site moment requires weighting constituent moments by occupancy once.

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, mag_symprec: float | None = None, atol: float | None = None)

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).
`site_occupancies`		Occupancy keyed by atom-site label, defaulting to one when absent.
`site_moment_subspaces`		Coefficient matrices from `symmform_uvw`, keyed by magnetic atom-site label. Each matrix's columns span the permitted moment subspace in the declared spin basis. Missing or unknown forms have no entry.
`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`	Absolute fractional-position tolerance for expanding each constituent's orbit. This also supplies the default for `mag_symprec` and `atol`.	`0.0001`
`mag_symprec`	`float \| None`	Absolute occupied-atom moment tolerance for consistency within an orbit. Defaults to `symprec`.	`None`
`atol`	`float \| None`	Absolute tolerance for orthogonality of the normalized spin frame. Defaults to `symprec`. All comparisons use zero relative tolerance.	`None`

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')

site_moment_subspaces `instance-attribute` ¶

site_moment_subspaces = {}

site_occupancies `instance-attribute` ¶

site_occupancies = {label: float(occupancy) for label, occupancy in zip(labels, block.data.get('_atom_site_occupancy', ['1'] * len(labels)), strict=True)}

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(*site_columns, strict=True)]

spin_basis `instance-attribute` ¶

spin_basis = _read_spin_basis(block, text, np.array(self.lattice.matrix), atol=symprec if atol is None else atol)

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, mag_symprec: float | None = None, atol: float | None = None) -> SpinCifReader

get_structure ¶

get_structure() -> Structure

Expand the asymmetric unit into the full magnetic structure.

Each expanded constituent remains a separate row with its original species and occupancy, including coincident rows with different moments. magmom is the Cartesian occupied-atom vector in the read lattice's frame. magnetic records the presence of a moment row, including an explicit zero. No occupancy averaging or normalization is applied.

Raises if an orbit disagrees with its declared multiplicity, transforms inconsistently, or pymatgen cannot preserve a constituent's species and occupancy exactly.

SpinCifWriter ¶

SpinCifWriter(sas: SpinSymmetryAdaptedStructure, nssg: NontrivialSpinSpaceGroup, magnetic_moments: NDArrayFloat, *, spin_only_group: SpinOnlyGroup, spin_rotation: NDArrayFloat | None = None, 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 moments per occupied selected magnetic atom, 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
`spin_rotation`	`NDArrayFloat \| None`	Orthogonal 3 by 3 matrix taking intrinsic spins to spatial Cartesian spins. Moments must already include this rotation, as `intrinsic @ spin_rotation.T`. Both proper and improper frames are supported; `None` uses the identity. The operations and SSA restrictions are rotated with the same matrix.	`None`
`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) and absolute legacy occupancy comparisons. 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, symprec: float = 0.0001, mag_symprec: float | 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.

from_structure `classmethod` ¶

from_structure(sas: SpinSymmetryAdaptedStructure, nssg: NontrivialSpinSpaceGroup, structure: Structure, *, spin_only_group: SpinOnlyGroup, symprec: float, spin_rotation: NDArrayFloat | None = None, mag_symprec: float | None = None, data_name: str = 'spinforge', parent_space_group_type: SpaceGroupType | None = None, atol: float = 1e-05) -> SpinCifWriter

Write full chemistry from constituent rows matched to the SSA sites.

symprec bounds Cartesian position and lattice matching. Coincident constituent rows share a physical site, and their selected moments must agree within mag_symprec (defaulting to atol). The optional boolean magnetic property defaults to true; false requires zero. A mixed row applies its moment and flag to all constituents. Chemistry and magnetic flags must agree exactly across each SSG orbit.

An explicit mag_symprec is an absolute moment tolerance for both the SSA residual and spin-only-group checks. When omitted, these checks retain the array constructor's moment-scale-relative atol policy.

write_file ¶

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

Write the spinCIF to filename.

spinCIF¶

scif ¶

SPINCIF_REVISION module-attribute ¶

SpinCifReader ¶

collinear_direction_xyz instance-attribute ¶

coplanar_perp_uvw instance-attribute ¶

lattice instance-attribute ¶

operations instance-attribute ¶

site_moment_subspaces instance-attribute ¶

site_occupancies instance-attribute ¶

sites instance-attribute ¶

spin_basis instance-attribute ¶

spin_lattice instance-attribute ¶