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.

.. toctree::
   :maxdepth: 2
   :caption: Contents

   installation
   tutorial
   theory
   cli
   usage
   api
   contributing

Overview
--------

Sign convention used throughout:

.. math::

   \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]

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 →
   :math:`JS^2`, :math:`J`, :math:`J/k_B` (method auto-detected).
4. ``mag4-magnon`` — LSWT bands, Luttinger–Tisza ordering vector,
   :math:`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 :math:`G1'` groups).
- Four-spin **ring exchange**: fitted in energy-mapping (``--jring``),
  isolated exactly by the 16-state parity projection, folded into
  effective couplings for :math:`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 :math:`T_c`: Mermin–Wagner dimensionality guard and
  flat-axis-q₀ diagnostics.

Quickstart
----------

.. code-block:: bash

   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 :doc:`tutorial`.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`