Tutorial

This document provides an overview of the structure of the code and how to access basic information about calculations. Basic familiarity with the concepts of plane-wave density functional theory is assumed throughout. Feel free to take a look at the Periodic problems or the density-functional theory chapters for some introductory material on the topic.

For our discussion we will use the classic example of computing the LDA ground state of the silicon crystal. Performing such a calculation roughly proceeds in three steps.

using DFTK
using Plots
using Unitful
using UnitfulAtomic

# 1. Define lattice and atomic positions
a = 5.431u"angstrom"          # Silicon lattice constant
lattice = a / 2 * [[0 1 1.];  # Silicon lattice vectors
                   [1 0 1.];  # specified column by column
                   [1 1 0.]]

3×3 Matrix{Unitful.Quantity{Float64, 𝐋, Unitful.FreeUnits{(Å,), 𝐋, nothing}}}:
    0.0 Å  2.7155 Å  2.7155 Å
 2.7155 Å     0.0 Å  2.7155 Å
 2.7155 Å  2.7155 Å     0.0 Å

By default, all numbers passed as arguments are assumed to be in atomic units. Quantities such as temperature, energy cutoffs, lattice vectors, and the k-point grid spacing can optionally be annotated with Unitful units, which are automatically converted to the atomic units used internally. For more details, see the Unitful package documentation and the UnitfulAtomic.jl package.

# Load HGH pseudopotential for Silicon
Si = ElementPsp(:Si, psp=load_psp("hgh/lda/Si-q4"))

# Specify type and positions of atoms
atoms = [Si => [ones(3)/8, -ones(3)/8]]

# 2. Select model and basis
model = model_LDA(lattice, atoms)
kgrid = [4, 4, 4]     # k-point grid (Regular Monkhorst-Pack grid)
Ecut = 7              # kinetic energy cutoff
# Ecut = 190.5u"eV"  # Could also use eV or other energy-compatible units
basis = PlaneWaveBasis(model; Ecut, kgrid)
# Note the implicit passing of keyword arguments here:
# this is equivalent to PlaneWaveBasis(model; Ecut=Ecut, kgrid=kgrid)

# 3. Run the SCF procedure to obtain the ground state
scfres = self_consistent_field(basis, tol=1e-8);

n     Energy            Eₙ-Eₙ₋₁     ρout-ρin   α      Diag
---   ---------------   ---------   --------   ----   ----
  1   -7.905196599858         NaN   1.95e-01   0.80    4.0
  2   -7.909809162003   -4.61e-03   2.98e-02   0.80    1.0
  3   -7.910051922517   -2.43e-04   3.07e-03   0.80    3.1
  4   -7.910052829550   -9.07e-07   4.74e-04   0.80    2.4
  5   -7.910052851496   -2.19e-08   4.80e-05   0.80    2.0
  6   -7.910052854036   -2.54e-09   4.10e-06   0.80    3.0

That's it! Now you can get various quantities from the result of the SCF. For instance, the different components of the energy:

scfres.energies

Energy breakdown (in Ha):
    Kinetic             3.0795157 
    AtomicLocal         -2.1806385
    AtomicNonlocal      1.7339398 
    Ewald               -8.3979253
    PspCorrection       -0.2946254
    Hartree             0.5417573 
    Xc                  -2.3920765

    total               -7.910052854036

Eigenvalues:

hcat(scfres.eigenvalues...)

7×10 Matrix{Float64}:
 -0.170182  -0.131801   -0.0883283  …  -0.0562608  -0.11494    -0.0700171
  0.201343   0.0909035   0.0122922      0.0111142   0.0420616   0.0176498
  0.249295   0.174773    0.176137       0.132964    0.220114    0.11233
  0.249295   0.231427    0.20237        0.161043    0.220114    0.190455
  0.350986   0.360027    0.340134       0.291807    0.320726    0.327376
  0.36997    0.395898    0.389483   …   0.331814    0.38819     0.460222
  0.36997    0.401676    0.412474       0.565534    0.38819     0.462716

eigenvalues is an array (indexed by k-points) of arrays (indexed by eigenvalue number). The "splatting" operation ... calls hcat with all the inner arrays as arguments, which collects them into a matrix.

The resulting matrix is 7 (number of computed eigenvalues) by 8 (number of k-points). There are 7 eigenvalues per k-point because there are 4 occupied states in the system (4 valence electrons per silicon atom, two atoms per unit cell, and paired spins), and the eigensolver gives itself some breathing room by computing some extra states (see n_ep_extra argument to self_consistent_field).

We can check the occupations ...

hcat(scfres.occupation...)

7×10 Matrix{Float64}:
 2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0
 2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0
 2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0
 2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0  2.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0
 0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0  0.0

... and density, where we use that the density objects in DFTK are indexed as ρ[iσ, ix, iy, iz], i.e. first in the spin component and then in the 3-dimensional real-space grid.

rvecs = collect(r_vectors(basis))[:, 1, 1]  # slice along the x axis
x = [r[1] for r in rvecs]                   # only keep the x coordinate
plot(x, scfres.ρ[1, :, 1, 1], label="", xlabel="x", ylabel="ρ", marker=2)

We can also perform various postprocessing steps: for instance compute a band structure

plot_bandstructure(scfres; kline_density=10)

or get the cartesian forces (in Hartree / Bohr)

compute_forces_cart(scfres)[1]  # Select silicon forces

2-element Vector{StaticArrays.SVector{3, Float64}}:
 [0.0004493485917160235, 0.0004493885437063034, 0.00044936988245190417]
 [-0.00044938854370653596, -0.0004493485917156503, -0.0004493698824513133]

The [1] extracts the forces for the first kind of atoms, i.e. Si (silicon) in the setup of the atoms list of step 1 above. As expected, they are almost zero in this highly symmetric configuration.

Where to go from here

Take a look at the example index to continue exploring DFTK.