# Dipole moment tutorial

## Requirements

### Software components

- nanotools
- RESCU+

### Pseudopotentials

I will need the following pseudopotentials.

- H_AtomicData.mat
- O_AtomicData.mat

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

### References

- Wikipedia contributors. "Electric dipole moment." Wikipedia, The Free Encyclopedia. Wikipedia, The Free Encyclopedia, 14 Aug. 2021. Web. 20 Aug. 2021.

## Briefing

In this tutorial, I show how to calculate the dipole moment of a water molecule.

The dipole moment is defined as

$$
\mathbf{p}(\mathbf{r}) = \int\limits_{V} \rho(\mathbf{r}')\, \left(\mathbf{r}' - \mathbf{r}\right) \ d^3 \mathbf{r}'
$$

where $\rho$ is the total charge in the system, i.e. the electronic charge plus the ionic charge from the pseudo-ion cores.
Note that the calculation of the dipole requires a reference point $\mathbf{r}$ and the dipole may depend on the position of that center.

## Setup

Create the Python script `etot.py` with the following content ([see the tutorial on TotalEnergy](../etot/tutorial_etot.md))

```python
from nanotools import Atoms, Cell, System, TotalEnergy
import numpy as np

xyz = """3
Water molecule
O          8.00000           8.0000    8.1178
H          8.00000           8.7554    7.5288
H          8.00000           7.2446    7.5288
"""
with open("h2o.xyz", "w") as f:
   f.write(xyz)
atoms = Atoms(positions="h2o.xyz")
cell = Cell(avec = np.diag([16,16,16]), resolution=0.1)
sys = System(atoms=atoms, cell=cell)
calc = TotalEnergy(sys)
calc.solve()
```

and `dip.py`

```python
from nanotools import Dipole
calc = Dipole.from_totalenergy("nano_scf_out.json")
print(calc.get_dipole_moment())           # e * Ang
print(calc.get_dipole_moment()/0.2081943) # debye
```

## Explanations

Here is a high level view of the calculation workflow:

1. Perform a [total energy calculation](#total-energy-calculation).
1. Perform a [dipole calculation](#dipole-calculation).

### Total energy calculation

This step is performed to obtain the ground state density.
Simply execute `etot.py`.
For additional details on total energy calculations, refer the to [tutorial on TotalEnergy](../etot/tutorial_etot.md).

### Dipole calculation

In this step, a `Dipole` object is create passing the path to the total energy results to `from_totalenergy`.
The dipole moment is obtained simply invoking `get_dipole_moment`.
It is returned in units of e$\cdot$Ang.
The value in debye is obtained dividing by `0.2081943`.

```python
[-7.15008622e-16  8.51566954e-16  3.38609613e-01]
[-5.05106647e-12 -4.81216468e-12  1.62641154e+00]
```

The value of `1.63` is comparable with the classical electrostatic value of `1.84` given by

$$
p = 2\cdot 1.5 \cos\left(\frac{104.5^\circ}{2}\right)
$$