# crystod-mag

Symmetry-adapted spin bases (cluster multipoles / SAMM): every
symmetry-distinct magnetic order allowed on the sites of one element, printed
with its irrep, its per-atom spin directions, a ready-to-paste VASP or Quantum
ESPRESSO magnetization input, and a VESTA file with spin arrows.

| I want to ... | command |
|---|---|
| enumerate the magnetic orders at q = 0 | `crystod-mag -c POSCAR --element Ni --qpoint 0 0 0` |
| survey every special k point | `crystod-mag -c POSCAR --element Ni` |
| get a Quantum ESPRESSO input instead | `... --format qe` |
| build a magnetic supercell at q ≠ 0 | `crystod-mag -c POSCAR --element Ni --qpoint R` |

## 28. Symmetry-adapted spin bases

*Example directory: `example/28_spin_basis` (testsuite section 28)*

Treat the spins on the sites of a magnetic element as axial-vector degrees of
freedom and decompose them into space-group irreps at a q point by projection —
a complete, symmetry-exhaustive enumeration of the ferromagnetic and
antiferromagnetic arrangements, following the cluster-multipole /
symmetry-adapted multipole moment (SAMM) framework of M.-T. Suzuki *et al.*
[PRB **95**, 094406 (2017); PRB **99**, 174407 (2019)]:

```bash
crystod-mag -c example/test_POSCARs/221_PPOSCAR_AlNi3 --element Ni --qpoint 0 0 0
crystod-mag -c example/test_POSCARs/221_PPOSCAR_AlNi3 --element Ni --qpoint 0 0 0 --format qe

# survey mode: spin-multipole irreps at ALL special k points
crystod-mag -c example/test_POSCARs/221_PPOSCAR_AlNi3 --element Ni
```

The output opens with the magnetic sites and the complete irrep enumeration —
for the Ni 3c cluster of AlNi3 (the Mn3Ir geometry), 9 spin degrees of freedom
decompose into exactly three symmetry-adapted families:

```
Space group: Pm-3m (#221)
Magnetic sites: Ni x 3
  Ni1: [0.5, 0.5, 0.0]
  Ni2: [0.5, 0.0, 0.5]
  Ni3: [0.0, 0.5, 0.5]

Selected q-point: GAMMA = [0.0, 0.0, 0.0]

Spin (axial-vector) representation on Ni sites: 9 dimensions
Decomposition: 2 x GM4+(3) + GM5+(3)

Symmetry-adapted spin bases:
  GM4+(3): dim 3 [FM, dipole]
  GM4+(3): dim 3 [AFM, octupole]
  GM5+(3): dim 3 [AFM, octupole]
```

Every basis vector is then printed with its per-atom spin directions, net
moment, and the magnetization input. The [111] component of the GM4+ cluster
octupole is the experimentally realized 120-degree structure of Mn3Ir — note
the exactly vanishing net moment:

```
=== GM4+(3) [AFM, octupole] ===
  component 111:
    Ni1: S = [ 0.4082,  0.4082,  0.8165]
    Ni2: S = [ 0.4082, -0.8165, -0.4082]
    Ni3: S = [-0.8165,  0.4082, -0.4082]
    net moment: [0.0, 0.0, -0.0]
    spin directions (all atoms, POSCAR order):
      Al1: [0, 0, 0]
      Ni2: [0.4082, 0.4082, 0.8165]
      Ni3: [0.4082, -0.8165, -0.4082]
      Ni4: [-0.8165, 0.4082, -0.4082]
    MAGMOM = 0 0 0   0.4082 0.4082 0.8165   0.4082 -0.8165 -0.4082   -0.8165 0.4082 -0.4082
    written to: POSCAR_AlNi3_spin_GM4+_octupole_111.vesta
```

Per-atom spin directions and a ready-to-paste noncollinear magnetization input
are printed by default for every basis vector. `--format` selects the input
format:

- `vasp` (default) prints a noncollinear `MAGMOM` line;
- `qe` prints the Quantum ESPRESSO counterpart — `noncolin = .true.` with
  per-type `starting_magnetization(i)` / `angle1(i)` (polar angle from z) /
  `angle2(i)` (azimuth from x) for the `&SYSTEM` namelist, where the magnetic
  element is split into one atom type per distinct spin direction (the atom
  membership of each type is printed as comments for
  `ATOMIC_SPECIES`/`ATOMIC_POSITIONS`).

With `--format qe`, the same 120-degree octupole becomes (Ni split into three
types because the three spins point in three different directions):

```
    Quantum ESPRESSO noncollinear magnetization (&SYSTEM):
      noncolin = .true.
      ! type 1 (Al): Al1 -- non-magnetic
      ! type 2 (Ni1): Ni2  S = [0.4082, 0.4082, 0.8165]
      starting_magnetization(2) = 1.0000
      angle1(2) = 35.2611
      angle2(2) = 45.0000
      ! type 3 (Ni2): Ni3  S = [0.4082, -0.8165, -0.4082]
      starting_magnetization(3) = 1.0000
      angle1(3) = 114.0928
      angle2(3) = -63.4378
      ! type 4 (Ni3): Ni4  S = [-0.8165, 0.4082, -0.4082]
      starting_magnetization(4) = 1.0000
      angle1(4) = 114.0928
      angle2(4) = 153.4378
      ! angle1 = polar angle from the z axis (deg); angle2 = azimuth from the x axis in the xy plane (deg).
      ! Split Ni into the types above in ATOMIC_SPECIES / ATOMIC_POSITIONS to realize this spin arrangement.
```

When `--qpoint` is omitted, the spin (axial-vector) irrep decomposition is
listed for every special k point of the space group — the magnetic counterpart
of the `crystod` SALC survey (e.g. for AlNi3: GM: `2.0 [GM4+(3)] + 1.0 [GM5+(3)]`,
R: `R2+ + R3+ + R4+ + R5+`, ...).

For the Mn3Ir-type Ni 3c cluster of AlNi3 this yields
`9 dims = 2 x GM4+(3) + GM5+(3)`: the GM4+ (T1g) cluster dipole (FM), the GM4+
(T1g) cluster octupole (AFM: the experimentally realized 120-degree structure of
Mn3Ir, which shares the irrep with the dipole and hence allows the anomalous
Hall effect), and the GM5+ (T2g) cluster octupole (AFM). Every AFM basis
satisfies `sum_i S_i = 0` exactly.

Each basis vector is exported as
`POSCAR_<formula>_spin_<irrep>_<dipole|octupole|...>_<direction>.vesta`
(e.g. `POSCAR_AlNi3_spin_GM4+_octupole_111.vesta` for the 120-degree Mn3Ir-type
state), with spin arrows on the magnetic atoms scaled so that the largest spin
gets `--amplitude` Angstroms (default 1.5). For q != 0 (e.g. `--qpoint R`) the
commensurate magnetic supercell is built automatically, with the Bloch phase
applied to the spins and the MAGMOM/VESTA output referring to the supercell.
`--conventional` exports the spin structures in the conventional cell instead of
the primitive cell (VESTA files get a `_conv` suffix, and for q != 0 the
conventional cell is multiplied until the Bloch phase is commensurate);
`--tolerance` sets the symmetry tolerance (default 1e-5).

```{seealso}
**Theory:** the construction is the SALC projection used elsewhere in CrystOD
([1. Theoretical background](theory-representations.md)) with the Cartesian
part replaced by `det(R) R`, since spins are axial vectors; irrep labels come
from spgrep + the bundled ISO-IR (ISOTROPY, Miller-Love) tables as usual.
Within a multiply-occurring irrep the unique net-moment (dipole) combination is
split off from the net-zero (higher-multipole) ones, and multipole ranks
(dipole, octupole, ...) are assigned representation-theoretically from the
parity-resolved angular-momentum characters (Suzuki's Table III logic).
```