mag4.spinconfig

Generate, group and merge the four spin configurations of the four-state method.

Functions

build_reference_bath(n_atoms[, user_ref])

Build the reference magnetic bath.

build_reference_from_couplings(atoms, ...)

Build a reference bath that respects the requested coupling signs.

build_reference_from_kvector(atoms, kfrac, ...)

Build a collinear reference bath s_i = sign(cos(2π k·R_i)).

build_reference_from_magmom(magmom, crystal)

±1 reference bath from a MAGMOM-style string of the WORKING SUPERCELL.

find_unique_configs(all_configs, sym_ops, *)

Group configurations equivalent under the magnetic (grey) group.

generate_four_states(ref_bath, dimer, ...)

Generate the four spin configurations uu, dd, ud, du for one dimer.

parse_kvector(spec)

Parse "1/2 1/2 0" or "0.5,0.5,0" → [Fraction(1,2), …].

parse_magmom_tokens(s)

Expand a VASP MAGMOM-style string into a flat list of floats.

parse_ref_couplings(spec, coupling_names)

Parse "J1:AFM,J2:FM" → {"J1": -1, "J2": +1}.

time_reversal_pairs(unitary_groups, sym_ops)

Pairs of unitary-only classes that time reversal proves degenerate.
mag4.spinconfig.build_reference_bath(n_atoms, user_ref=None)[source]

Build the reference magnetic bath.

Default behaviour is fully ferromagnetic (all +1). Pass user_ref as a list of ±1 of length n_atoms to override.

Raises:

ValueError – If the length is wrong or values other than ±1 are present.

Return type:

list

Parameters:
mag4.spinconfig.parse_magmom_tokens(s)[source]

Expand a VASP MAGMOM-style string into a flat list of floats.

Accepts plain values and n*v repetitions, whitespace- or comma-separated: "32*0 1 -1 2*1.5" → [0.0]*32 + [1.0, -1.0, 1.5, 1.5].

Return type:

List[float]

Parameters:

s (str)

mag4.spinconfig.build_reference_from_magmom(magmom, crystal)[source]

±1 reference bath from a MAGMOM-style string of the WORKING SUPERCELL.

The string is written exactly as one would set VASP’s MAGMOM for the supercell — POSCAR atom order (crystal.all_species species blocks), n*v repetitions allowed — e.g. for a 2×2×1 La₂CuO₄ √2 cell:

32*0  1 1 1 -1 -1 -1 -1 1  -1 -1 -1 1 1 1 1 -1  64*0

Only the SIGNS of the magnetic entries are used (any magnitude, e.g. ±1 or ±0.6); non-magnetic entries must be 0 and are validated against the species layout so an atom-order mismatch fails loudly. As a shorthand the string may instead carry just the N_mag magnetic values (in the magnetic-sublattice order). Returns the ±1 bath in crystal.target_species order.

Return type:

list

Parameters:

magmom (str)

mag4.spinconfig.parse_ref_couplings(spec, coupling_names)[source]

Parse "J1:AFM,J2:FM" → {"J1": -1, "J2": +1}.

Raises ValueError on unknown coupling names or unrecognised signs.

Return type:

Dict[str, int]

Parameters:
mag4.spinconfig.build_reference_from_couplings(atoms, lat_mat, couplings, spec, tol)[source]

Build a reference bath that respects the requested coupling signs.

Parameters:

  • atoms (magnetic atoms in legacy [label, x, y, z, …] format.)

  • lat_mat (3×3 lattice matrix (columns are lattice vectors).)

  • couplings ([[name, distance], …].)

  • spec (e.g. "J1:AFM,J2:FM".)

  • tol (distance tolerance for the bond search.)

  • ``(ref_bath (Returns) –

  • used (report)``. report carries the method)

  • any

  • conflict (frustration)

  • ``(satisfied (and per-coupling) –

  • counts. (total)`` bond)

Return type:

Tuple[list, dict]

mag4.spinconfig.parse_kvector(spec)[source]

Parse "1/2 1/2 0" or "0.5,0.5,0" → [Fraction(1,2), …].

Return type:

List[Fraction]

Parameters:

spec (str)

mag4.spinconfig.build_reference_from_kvector(atoms, kfrac, supercell, node_tol=1e-06)[source]

Build a collinear reference bath s_i = sign(cos(2π k·R_i)).

Parameters:

  • atoms (magnetic atoms in legacy [label, x, y, z, …] format, with) – fractional coordinates in the working (super)cell.

  • kfrac (propagation vector (3 Fraction) in parent reciprocal-lattice units.)

  • supercell ((na, nb, nc) multipliers used to build the working cell.)

  • ``(ref_bath (Returns) –

  • report)``.

  • node_tol (float)

Return type:

Tuple[list, dict]

mag4.spinconfig.generate_four_states(ref_bath, dimer, coupling_name)[source]

Generate the four spin configurations uu, dd, ud, du for one dimer.

Only the two atoms of the dimer differ between configurations; the rest of the magnetic bath is frozen to ref_bath.

Return type:

List[FourStateConfig]

Parameters:
mag4.spinconfig.find_unique_configs(all_configs, sym_ops, *, time_reversal=True)[source]

Group configurations equivalent under the magnetic (grey) group.

The group is the unitary crystal operations sym_ops plus, when time_reversal is True (the default), each of them composed with time reversal T (global spin flip) — exact in a collinear calculation without spin-orbit coupling. Returns a list of groups; the energy of any member of a group can be used interchangeably in the J extraction formulas.

time_reversal=False restricts to the unitary subgroup — used by --check-degeneracy to keep the T-redundant configurations as separate DFT runs whose energy agreement then tests the antiunitary symmetry (and the completeness of the spin model).

Return type:

List[List[FourStateConfig]]

Parameters:
mag4.spinconfig.time_reversal_pairs(unitary_groups, sym_ops)[source]

Pairs of unitary-only classes that time reversal proves degenerate.

unitary_groups must come from find_unique_configs() with time_reversal=False. Two classes pair up when an ANTIUNITARY operation P×T (unitary op composed with global spin flip) maps one representative onto the other — their DFT energies must then coincide even though no unitary operation relates them (they typically differ in total Sz). Returns 1-based (uid_a, uid_b) index pairs; since the unitary subgroup has index 2 in the grey group, each class belongs to at most one pair.

Return type:

List[Tuple[int, int]]

Parameters: