### Topological Defects

This module characterizes the topological defect for a vector field, of which the vibration mode, non-affine displacement field, and active matter dynamics are typical scenarios.

#### 1. Topological defect in 2D

For two-dimensional (2D) systems, the vector field (such as eigenvector fields, see hessian.md) $\vec{e}_{i}$ are 2D vectors spanning the $x$, $y$ coordinates. To identify the topological defect (TD) in this field $(e_i^x, e_i^y)$, eigenvectors $\vec{e}_{i}$ at each particle position $\vec{r_i}$ are mapped onto a $ngrid \times ngrid$ square lattice superimposed on the sample:

$$
e_r =\sum_iw(\vec{r}-\vec{r}_i)e_i
$$

Here, $\vec{r}_i$ is the position of particle $i$, and $w(\vec{r}-\vec{r}_i)$ is a Gaussian weight function defined as:

$$
w(\vec{r}-\vec{r}_i)=\frac{1}{\sqrt{2\pi \sigma^2}} \exp \left(-\frac{(\vec{r_j}-\vec{r}_i)^2}{2\sigma^2}\right)
$$

with $\sigma=1$. Therefore, phase angle $\theta(\vec{r})$ at each lattice site $\vec{r}$ is then given by:

$$
\tan\theta(\vec{r})=\frac{\sum_iw(\vec{r}-\vec{r}_i)e_i^y}{\sum_iw(\vec{r}-\vec{r}_i)e_i^x} = \frac{e_r^y}{e_r^x}
$$

Hence, this procedure allows to define a map from the eigenvector field, given at the positions of the particles, to a regular grid. The topological defects are then identified by calculating topological charge $q$ which is the line integral of $\nabla\theta$ over a closed path,

$$
q=\frac{1}{2 \pi} \oint_{\mathcal{C}} d \theta
$$

where $\mathcal{C}$ is a closed contour and $\theta$ is treated as a continuous phase angle. In practice, $\theta$ is discretized at each site $\vec{r}$. The topological $\operatorname*{charge}q$ is quantized and takes integer values $\pm n.$ Specifically , $q= + 1$ corresponds to a topological vortex (+1 TD), while $q=-1$ to a topological anti-vortex (-1 TD).



##### Input Argument
- kconfig (int): the target configuration to characterize the topological defect, default 0 for the first configuration.
- ngrid (int, optional): Number of neighbors. Default 100.
- gaussian_cut (float, optional): the longest distance to consider the gaussian probability or the contribution from the simulation particles. Default 5.0.
- outputfile (str, optional): output file. Default `None`.

**Return**
- grids_UV_grid (np.ndarray): The grid of the eigenvector field.

**Example**
```python
import numpy as np
from PyMatterSim.utils.logging import get_logger_handle
from PyMatterSim.reader.dump_reader import DumpReader
from PyMatterSim.reader.reader_utils import DumpFileType
from PyMatterSim.static.topodefect import TopoDefect


dumpfile = "center.mode.n1320.atom"
# get particle positions
readdump = DumpReader(dumpfile, ndim=2, filetype=DumpFileTypeLAMMPS)
readdump.read_onefile()
# get particle vectors
read_mode = DumpReader(
    dumpfile, ndim=2, filetype=DumpFileType.LAMMPSVECTOR, columnsids=[9,10]
)
read_mode.read_onefile()
# calculate topological defects
TopoDefect = TopoDefect(readdump.snapshots, read_mode)
grids_UV_grid = TopoDefect.topo_defect_2d(ngrid=100, gaussian_cut=5.0)
```