# Spin-DFT tutorial

## Requirements

### Software components

- nanotools
- RESCU+

### Pseudopotentials

I will need the following pseudopotential.

- Fe_AtomicData.mat

Let's copy it from the pseudo database to the current working directory and `export RESCUPLUS_PSEUDO=$PWD`.

### References

- Kohn, W., & Sham, L. J. (1965). Self-Consistent Equations Including Exchange and Correlation Effects. [Physical Review, 140(4A), A1133.](https://doi.org/10.1103/PhysRev.140.A1133)
- Jiang, D. E., & Carter, E. A. (2003). Carbon dissolution and diffusion in ferrite and austenite from first principles. [Physical Review B, 67(21), 214103.](https://doi.org/10.1103/PhysRevB.67.214103)

## Briefing

In this tutorial, I show how to calculate the magnetic moment of the Fe crystal in the collinear spin framework.

## Code

Create the script `etot.py` as follows

```python
from nanotools import Atoms, Cell, System, TotalEnergy
cell = Cell(avec=[[-1.435, 1.435, 1.435], [1.435, -1.435, 1.435], [1.435, 1.435, -1.435]], resolution=0.10)
with open("fe.xyz", "w") as f:
   f.write(\
"""1
s x y z sz
Fe 0. 0. 0. 2.
""")
atoms = Atoms(fractional_positions="fe.xyz")
sys = System(cell=cell, atoms=atoms)
sys.hamiltonian.ispin = 2
sys.atoms.set_initial_magnetic_moments("fe.xyz")
calc = TotalEnergy(sys)
calc.solve()
```

## Explanations

Here is a high level view of the calculation workflow:

1. [Create a `TotalEnergy` calculator](#total-energy-calculator) ([see the tutorial on TotalEnergy](../etot/tutorial_etot.md)).
2. [Solve the Kohn-Sham equation](#solve-the-kohn-sham-equation) self-consistently calling `solve`.
3. [Analyze the data](#analyze-the-data) and look at the results.

### Total energy calculator

I first create a `System` object.
I define a body centred cubic (BCC) cell with lattice parameter 2.87 Ang.
I specify the atom position and species via an xyz-file `fe.xyz`.
The system is created with degenerate spin by default.
I change to collinear spin setting `sys.hamiltonian.ispin = 2`.
The spin frameworks relate to the value of `ispin` as follows:

- 1: degenerate
- 2: collinear
- 4: non-collinear

I then set the initial magnetic moment calling `sys.atoms.set_initial_magnetic_moments("fe.xyz")`.
The function `set_initial_magnetic_moments` will read `fe.xyz` and look for the position of the column `sz`.
The magnetic moment of each atom will be initialized to the value of the column `sz`, in units of Bohr magnetons (i.e. each electron has spin 1/2).

### Solve the Kohn-Sham equation

RESCU+'s solvers are invoked calling the `solve` method

```python
calc.solve()
```

The method writes all parameters to a JSON file, then calls the relevant (Fortran) program, then loads the data back into the calculator.
The output of `rescuplus` goes to `nano_scf_out.h5` and `nano_scf_out.json`.

### Analyze the data

I can now read the data using the `read` method of `TotalEnergy`.

```python
from nanotools import TotalEnergy
calc = TotalEnergy.read("nano_scf_out.json")
```

and get the magnetic moment with the `get_total_magnetic_moment` method.
For example,

```python
print(calc.get_total_magnetic_moment())
```

gives `2.224`.
This is indeed quite close to the theoretical and experimental values reported in Jiang _et al._ which are 2.17 and 2.22 respectively.