mag4 — documentation

mag4 extracts Heisenberg magnetic exchange couplings from DFT by three interchangeable methods — four-state difference formulas, energy-mapping least squares (with an optional four-spin ring-exchange term), and the 16-state ring projection — and analyses them with multi-sublattice linear spin-wave theory (LSWT) and Tyablikov-RPA critical temperatures. It reads CIF/POSCAR and writes ready-to-run VASP and/or WIEN2k inputs, one directory per symmetry-inequivalent magnetic configuration.

Contents

• Installation
  • Requirements
  • Install from source
  • Verification
• Tutorial
  • Step 0 — Install
  • Step 1 — Inspect the structure and choose the J shells
  • Step 2 — Generate the DFT inputs
  • Step 3 — Run the DFT calculations
  • Step 4 — Extract the couplings
  • Step 5 — Magnons and the critical temperature
  • Advanced 1 — Energy mapping (all orders, least squares)
  • Advanced 2 — The 16-state ring method
  • Advanced 3 — T_c including the ring exchange
  • Advanced 4 — Diagnostics you should know about
  • Where to go next
• Theoretical background
  • Heisenberg Hamiltonian
  • Four-state method
  • Energy-mapping method
  • 16-state ring method
  • Symmetry reduction — the magnetic grey group
  • Ring renormalisation of the couplings
  • Linear spin-wave theory
• Command-line reference
  • mag4-magnetic
  • mag4-extract
  • mag4-magnon
  • mag4-angles
  • mag4-moments
• Programmatic usage
  • Four-state pipeline (from a CIF)
  • Multi-sublattice LSWT and T_c
  • M – L – M angles
  • WIEN2k moment extraction
• API reference
  • mag4
  • Constants and data structures
  • Geometry
  • Reading / writing
  • Supercell
  • Four-state method
  • VASP input generation
  • WIEN2k input generation
  • Energy parsing
  • J-value extraction
  • Reports and pipeline
  • Sub-package mag4.magnon
  • Sub-package mag4.analysis
  • Sub-package mag4.cli
• Contributing
  • Setting up the environment
  • Recommended workflow
  • Conventions

Overview

Sign convention used throughout:

\[ \begin{align}\begin{aligned}\mathcal{H} = +\sum_{i \neq j} J_{ij}\, \mathbf{S}_i \cdot \mathbf{S}_j \qquad (\mathrm{AFM:}\ J > 0,\quad \mathrm{FM:}\ J < 0)\\J S^2 = \frac{E_{\uparrow\uparrow} + E_{\downarrow\downarrow} - E_{\uparrow\downarrow} - E_{\downarrow\uparrow}}{4} \quad [\mathrm{meV}\cdot S^2]\end{aligned}\end{align} \]

The pipeline

1. mag4-magnetic — CIF/POSCAR → J-shell detection, isolation-aware supercell, per-config DFT inputs (--method four-state · energy-mapping · 16-state).

2. Run your DFT code in every configN/ (VASP or WIEN2k).

3. mag4-extract — convergence / band-gap / magnetic-state checks → \(JS^2\), \(J\), \(J/k_B\) (method auto-detected).

4. mag4-magnon — LSWT bands, Luttinger–Tisza ordering vector, \(T_c\) (MF + Tyablikov RPA), straight from the extraction with --from-extract (ring exchange folded in with --jring).

Auxiliary tools: mag4-angles (M–L–M bridging angles per shell, Goodenough–Kanamori reasoning) and mag4-moments (per-site converged moments, magnetic-state verification).

Main features

• Automatic J-shell extraction with distance clustering and optional geometry-aware splitting by bridging-ligand fingerprint (--ligand).

• Isolation-aware supercell search (algebraic multiplicity criterion + no-self-folding rule); --full-isolation for textbook divisor-4 cells.

• Symmetry deduplication under the magnetic grey group (crystal operations + time reversal), with --check-degeneracy to verify the antiunitary degeneracies explicitly.

• Magnetic (Shubnikov) space group and magnetic point group of every configuration (BNS number, type, grey \(G1'\) groups).

• Four-spin ring exchange: fitted in energy-mapping (--jring), isolated exactly by the 16-state parity projection, folded into effective couplings for \(T_c\) (mag4-magnon --jring).

• Contamination diagnostics: ring and beyond-cutoff leakage into each four-state J, with corrected-J formulas.

• Reference baths: FM (default), --ref-couplings "J1:AFM", --ref-kvector, or the supercell MAGMOM string (--ref-magmom).

• VASP (INCAR/KPOINTS incl. PBE+U, PBE0, meta-GGA) and WIEN2k (symmetric .struct, .inst, job scripts) back-ends.

• Honest \(T_c\): Mermin–Wagner dimensionality guard and flat-axis-q₀ diagnostics.

Quickstart

pip install -e .

mag4-magnetic --cif NiO.cif --element Ni --spin 1 --dry-run   # inspect
mag4-magnetic --cif NiO.cif --element Ni --spin 1             # generate
# … run DFT in every NiO/configN/ …
cd NiO && mag4-extract --code vasp --spin 1                   # extract J
mag4-magnon --cif ../NiO.cif --element Ni --from-extract .    # T_c

Start with the Tutorial.

Indices and tables

• Index

• Module Index

• Search Page