# Notation and conventions

## Usage of unicode characters

DFTK liberally uses unicode characters to represent Greek characters (e.g. ψ, ρ, ε...). Make sure you use the proper Julia plugins to simplify typing them.

## Symbol conventions

• Reciprocal-space vectors: $k$ for vectors in the Brillouin zone, $G$ for vectors of the reciprocal lattice, $q$ for general vectors
• Real-space vectors: $R$ for lattice vectors, $r$ and $x$ are usually used for unit for vectors in the unit cell or general real-space vectors, respectively. This convention is, however, less consistently applied.
• $\Omega$ is the unit cell, and $|\Omega|$ (or sometimes just $\Omega$) is its volume.
• $A$ are the real-space lattice vectors (model.lattice) and $B$ the Brillouin zone lattice vectors (model.recip_lattice).
• The Bloch waves are$$$\psi_{nk}(x) = e^{ik\cdot x} u_{nk}(x),$$$where $n$ is the band index and $k$ the $k$-point. In the code we sometimes use $\psi$ and $u$ interchangeably.
• $\varepsilon$ are the eigenvalues, $\varepsilon_F$ is the Fermi level.
• $\rho$ is the density.
• In the code we use normalized plane waves:$$$e_G(r) = \frac 1 {\sqrt{\Omega}} e^{i G \cdot r}.$$$
• $Y^l_m$ are the complex spherical harmonics, and $Y_{lm}$ the real ones.
• $j_l$ are the Bessel functions. In particular, $j_{0}(x) = \frac{\sin x}{x}$.

## Units

In DFTK, atomic units are used throughout, most importantly lengths are in Bohr and energies in Hartree. See wikipedia for a list of conversion factors. Appropriate unit conversion can can be performed using the Unitful and UnitfulAtomic packages:

using Unitful
using UnitfulAtomic
austrip(10u"eV")      # 10eV in Hartree
0.36749322175518595
using Unitful: Å
using UnitfulAtomic
auconvert(Å, 1.2)  # 1.2 Bohr in Ångström
0.6350126530835999 Å
Differing unit conventions

Different electronic-structure codes use different unit conventions. For example for lattice vectors the common length units are Bohr (used by DFTK) and Ångström (used e.g. by ASE, 1Å ≈ 1.80 Bohr). When setting up a calculation for DFTK one needs to ensure to convert to Bohr and atomic units. When structures are provided as AtomsBase.jl-compatible objects, this unit conversion is automatically performed behind the scenes. See AtomsBase integration for details.

## Lattices and lattice vectors

Both the real-space lattice (i.e. model.lattice) and reciprocal-space lattice (model.recip_lattice) contain the lattice vectors in columns. For example, model.lattice[:, 1] is the first real-space lattice vector. If 1D or 2D problems are to be treated these arrays are still $3 \times 3$ matrices, but contain two or one zero-columns, respectively. The real-space lattice vectors are sometimes referred to by $A$ and the reciprocal-space lattice vectors by $B = 2\pi A^{-T}$.

Row-major versus column-major storage order

Julia stores matrices as column-major, but other languages (notably Python and C) use row-major ordering. Care therefore needs to be taken to properly transpose the unit cell matrices $A$ before using it with DFTK. For the supported third-party packages load_lattice, load_positions and load_atoms again handle such conversion automatically.

We use the convention that the unit cell in real space is $[0, 1)^3$ in reduced coordinates and the unit cell in reciprocal space (the reducible Brillouin zone) is $[-1/2, 1/2)^3$.

## Reduced and cartesian coordinates

Unless denoted otherwise the code uses reduced coordinates for reciprocal-space vectors such as $k$, $G$, $q$ or real-space vectors like $r$ and $R$ (see Symbol conventions). One switches to Cartesian coordinates by

$$$x_\text{cart} = M x_\text{red}$$$

where $M$ is either $A$ / model.lattice (for real-space vectors) or $B$ / model.recip_lattice (for reciprocal-space vectors). A useful relationship is

$$$b_\text{cart} \cdot a_\text{cart}=2\pi b_\text{red} \cdot a_\text{red}$$$

if $a$ and $b$ are real-space and reciprocal-space vectors respectively. Other names for reduced coordinates are integer coordinates (usually for $G$-vectors) or fractional coordinates (usually for $k$-points).

## Normalization conventions

The normalization conventions used in the code is that quantities stored in reciprocal space are coefficients in the $e_{G}$ basis, and quantities stored in real space use real physical values. This means for instance that wavefunctions in the real space grid are normalized as $\frac{|\Omega|}{N} \sum_{r} |\psi(r)|^{2} = 1$ where $N$ is the number of grid points and in reciprocal space its coefficients are $\ell^{2}$-normalized, see the discussion in section PlaneWaveBasis and plane-wave discretisations where this is demonstrated.