Typos and wordings

0_Getting_started.ipynb

@@ -26,7 +26,7 @@
     "    * Solid-state problems (crystals, lattices, ...)\n",
     "    * Plane-wave discretisations\n",
     "    * Density functional theory (DFT)\n",
-    "    * Highly successful, but still many open mathematical problems\n",
+    "    * Highly successful, but still open mathematical questions\n",
     "\n",
     "\n",
     "- Topics:\n",
@@ -40,8 +40,8 @@
     "- Goals:\n",
     "    * Allow applied mathematicians to gain access to the topic\n",
     "    * Allow practitioners to deepen mathematical insight\n",
-    "    * Introduce the [density-functional toolkit](https://dftk.org)\n",
-    "      and its interplay with the Julia package ecosystom."
+    "    * Introduce the [density-functional toolkit](https://dftk.org) (DFTK)\n",
+    "      and its interplay with the Julia package ecosystem."
    ]
   },
   {
@@ -53,12 +53,14 @@
     "\n",
     "* Michael F. Herbst\n",
     "    - Postdoc at Applied and Computational Mathematics departmant at RWTH Aachen University\n",
-    "    - Chemistry background, but worked in maths departments for the past few years\n",
+    "    - Chemistry degree, but switched in between departments in the past years\n",
     "    - Active Julia user since about Julia 0.6\n",
+    "    - Switched to Julia as main language about 3 years ago\n",
+    "    - Contacts:\n",
     "    \n",
-    "    \n",
-    "    - Email: [email protected]\n",
-    "    - Web:   https://michael-herbst.com\n",
+    "\n",
+    "         Email: [email protected]\n",
+    "         Web:   https://michael-herbst.com\n",
     "    \n",
     "    \n",
     "* So who are you?\n",

1_Installation.ipynb

@@ -15,7 +15,8 @@
    "source": [
     "## Requirements\n",
     "\n",
-    "- **Julia $\\geq$ 1.6**\n",
+    "- **Julia 1.6** recommeded\n",
+    "  * Note: Our test suite segfaults in 1.7 (see this PR: https://github.com/JuliaLang/julia/pull/41516)\n",
     "- Some working python setup\n",
     "\n",
     "These notes have been made targeting DFTK 0.3.9."

2_Periodic_problems_and_plane_waves.ipynb

@@ -61,7 +61,7 @@
     "  \n",
     "- With this in mind it is natural to define a family\n",
     "  $$ H_k = \\frac12 (-i \\nabla + k)^2 $$\n",
-    "  as $k$-specific blocks of $H$."
+    "  of $k$-specific blocks of $H$."
    ]
   },
   {
@@ -111,9 +111,11 @@
     "\n",
     "- To solve the problem, we just need to find the eigenspectrum of all $H_k$ with $k \\in B$\n",
     "\n",
-    "**Problem 1:** $B$ is an overcountable set $\\Rightarrow$ **$k$-point sampling**: Instead of considering the full Brillouin zone we just consider a regular grid of values for $k$, the so-called **$k$-points**\n",
     "\n",
-    "**Problem 2:** Each $H_k$ is an operator over an infinite-dimensional domain $\\Rightarrow$ Project the problem into a finite basis diagonalise the resulting matrix (Ritz-Galerkin ansatz)."
+    "- **Problem 1:** $B$ is an overcountable set $\\Rightarrow$ **$k$-point sampling**: Instead of considering the full Brillouin zone we just consider a regular grid of values for $k$, the so-called **$k$-points**\n",
+    "\n",
+    "\n",
+    "- **Problem 2:** Each $H_k$ is an operator over an infinite-dimensional domain $\\Rightarrow$ Project the problem into a finite basis diagonalise the resulting matrix (Ritz-Galerkin ansatz)."
    ]
   },
   {
@@ -145,12 +147,12 @@
    "source": [
     "## Let's crunch some numbers!\n",
     "\n",
-    "One typical approach to get physical insight into a Hamiltonian $H$ is to plot a so-called band structure, that is the eigenvalues of $H_k$ versus $k$. The rough steps to plot a band structure are:\n",
+    "One typical approach to get physical insight into a Hamiltonian $H$ is to plot a so-called **band structure**, that is the eigenvalues of $H_k$ versus $k$. The rough steps to plot a band structure are:\n",
     "\n",
-    "1. Select $k$-Points at which $H_k$ should be diagonalised ($k$-point sampling)\n",
-    "2. Select plane-wave cutoff, thus the basis for discretising $H_k$\n",
-    "3. Find the eigenvalues of $H_k$ for each $k$\n",
-    "4. Plot eigenvalues versus $k$"
+    "1. Select a set of $k$-points ($k$-point sampling)\n",
+    "1. Select plane-wave cutoff, thus the basis for discretising $H_k$\n",
+    "1. Build and diagonalise $H_k$ for each $k$.\n",
+    "1. Plot eigenvalues versus $k$"
    ]
   },
   {
@@ -219,10 +221,13 @@
     "using Plots\n",
     "using LinearAlgebra\n",
     "\n",
-    "# Build the 1D lattice. The convention in DFTK is that trailling empty columns\n",
-    "# in the 3x3 lattice matrix are ignored and reduce the effective dimension.\n",
-    "lattice = diagm([100., 0, 0])\n",
-    "@show lattice\n",
+    "# Build the 1D lattice. DFTK is mostly tailored for 3D problems.\n",
+    "# Therefore quantities related to the problem space are have a fixed\n",
+    "# dimension 3. The convention is that for 1D / 2D problems the\n",
+    "# tailling entries are always zero and ignored in the computation.\n",
+    "# For the lattice we therefore construct a 3x3 matrix with only one entry.\n",
+    "lattice = zeros(3, 3)\n",
+    "lattice[1, 1] = 100.\n",
     "\n",
     "# Select a model. In this case we choose a free-electron model,\n",
     "# which is the same as saying that there is only a Kinetic term\n",
@@ -231,12 +236,13 @@
     "@show model.n_dim\n",
     "\n",
     "# Step 2: Define a plane-wave basis using this model and the same cutoff\n",
-    "#         as before. The kpoint grid is given as a regular (in some sense)\n",
-    "#         grid in the BZ, here we select only one k-Point (1x1x1).\n",
-    "#         The kpoints to plot the bands over are selected below.\n",
+    "# as before. The kpoint grid is given as a regular grid in the BZ.\n",
+    "# Here we select only one k-Point (1x1x1). The kpoints for calculating and plotting\n",
+    "# the bands are selected below. (This distinction between k-Points for the basis\n",
+    "# and the plotting is needed for more complicated models like DFT)\n",
     "basis = PlaneWaveBasis(model; Ecut=300, kgrid=(1, 1, 1));\n",
     "\n",
-    "# Steps 1, 3 & 4: K-Points for the band calculation, discretisation, diagonalisation\n",
+    "# Steps 1, 3 & 4: K-Point selection, discretisation, diagonalisation\n",
     "n_bands = 6\n",
     "ρ0 = guess_density(basis)  # Just dummy, has no meaning in this model\n",
     "p  = plot_bandstructure(basis, ρ0, n_bands, kline_density=15, unit=u\"hartree\")"
@@ -256,18 +262,20 @@
     "\n",
     "$$ H_k = \\frac12 (-i \\nabla + k)^2 + V $$\n",
     "\n",
-    "for all $k \\in \\text{BZ}$ with the potential $V$ interacting with the electrons.\n",
+    "for all $k \\in \\text{BZ}$ with a periodic potential $V$ interacting with the electrons.\n",
     "\n",
-    "- A number of \"standard\" potentials from the point of view of\n",
-    "  and plane-wave discretisations are readily implemented in DFTK.\n",
-    "  This allows to seamlessly construct density-functial theory models\n",
-    "  for a state-of-the-art treatment of electronic structures\n",
-    "  as well as models for bosonic systems (e.g. the Gross-Pitaevskii equation)\n",
-    "  or even anyonic systems just by assempling the right `terms`.\n",
-    "  See also the discussion in the next notebook.\n",
+    "- A number of \"standard\" potentials are readily implemented in DFTK and\n",
+    "  can be assembled using the `terms` kwarg of the model.\n",
+    "  This allows to seamlessly construct\n",
+    "  \n",
+    "    * density-functial theory models for treating electronic structures\n",
+    "      (see the next notebook)\n",
+    "    * Gross-Pitaevskii models for bosonic systems\n",
+    "    * even some more unusual cases like anyonic models.  \n",
+    "  \n",
     "  \n",
-    "- In this workbook we will go a little more low-level and directly provide\n",
-    "  an analytic potential describing the interaction with the electrons to DFTK.\n",
+    "In this workbook we will go a little more low-level and directly provide\n",
+    "an analytic potential describing the interaction with the electrons to DFTK.\n",
     "\n",
     "First we define a custom Gaussian potential as a new \"element\" inside DFTK:"
    ]
@@ -351,7 +359,7 @@
     "nucleus = ElementGaussian()\n",
     "atoms = [nucleus => [[0.2, 0, 0], [0.8, 0, 0]]]\n",
     "\n",
-    "# Assembple the model, discretise and build the Hamiltonian\n",
+    "# Assemble the model, discretise and build the Hamiltonian\n",
     "model = Model(lattice; atoms=atoms, terms=[Kinetic(), AtomicLocal()])\n",
     "basis = PlaneWaveBasis(model; Ecut=300, kgrid=(1, 1, 1));\n",
     "ham   = Hamiltonian(basis)\n",

3_Density_functional_theory.ipynb

@@ -46,7 +46,7 @@
     "  \n",
     "**More details**\n",
     "- My [2020 Juliacon talk](https://www.youtube.com/watch?v=-RomkxjlIcQ) (motivation for electronic-structure theory and DFT)\n",
-    "- Chapter 2 of [my PhD thesis](https://michael-herbst.com/publications/2018.05_phd_corrected.pdf) (Mathematical formulation of quantum mechanics"
+    "- Chapter 2 of my [PhD thesis](https://michael-herbst.com/publications/2018.05_phd_corrected.pdf) (Mathematical formulation of quantum mechanics)"
    ]
   },
   {
@@ -85,7 +85,7 @@
     "  with\n",
     "     * the electron **density** $\\rho = \\sum_i^N |\\psi_i|^2$\n",
     "       being directly dependent on *all* orbitals.\n",
-    "     * $\\sum_i  \\int \\psi_i^\\ast \\left(-\\frac12 \\Delta\\right) \\psi_i$ describing\n",
+    "     * $\\sum_i 2 \\int \\psi_i^\\ast \\left(-\\frac12 \\Delta\\right) \\psi_i$ describing\n",
     "       the **kinetic** energy of the electrons\n",
     "       (i.e. the term we discussed in the previous notebook)\n",
     "     * $\\int V_\\text{ext} \\rho$ being the **external** potential energy,\n",
@@ -154,13 +154,13 @@
     "    &&\\rho &= \\sum_{i=1}^N 2 |\\psi_i|^2\n",
     "\\end{aligned}\\right.$$\n",
     "\n",
-    "in which $H[\\rho] = -\\frac12 \\Delta + V[\\rho]$ is the **DFT Hamiltonian**. These equations are called the **self-consistent field** (SCF) problem (for historic reasons).\n",
+    "in which $H[\\rho] = -\\frac12 \\Delta + V[\\rho]$ is the **DFT Hamiltonian**. These equations are called the **self-consistent field** (SCF) problem.\n",
     "\n",
     "- The first and second line are basically an eigenvalue problem\n",
     "  with the usual orthogonality between the resulting eigenfunctions.\n",
-    "- Since $V$ depends on $\\rho$ (3rd line), which itself depends on $\\psi_i$ (last line)\n",
+    "- Since $V$ depends on $\\rho$ (3rd line), which itself depends on $\\psi_i$ (last line),\n",
     "  solving the SCF equations implies solving a *non-linear* eigenvalue problem.\n",
-    "- In this sense the DFT Hamiltonian is a straight generalisation of the problems\n",
+    "- In this sense the DFT Hamiltonian is a generalisation of the diagonalisation problems\n",
     "  we discussed in the previous notebook."
    ]
   },
@@ -184,10 +184,7 @@
    "id": "changing-maine",
    "metadata": {},
    "source": [
-    "**Note:** In the picture I sketch in this notebook I make a few assumptions for simplicity (e.g. no unpaired electrons, no spin, only integer occupation, existence of a gap, etc.). Adding in these extra complications does not change much of the bottom line, so I've decided to leave these aspects out for clarity. You can find more details in the references below.\n",
-    "\n",
-    "#### More details\n",
-    "- More references on DFT (at various levels) are given in the [DFTK documentation](https://juliamolsim.github.io/DFTK.jl/stable/guide/density_functional_theory/)"
+    "**Note:** In the picture I sketch in this notebook I make a few assumptions for simplicity (e.g. no unpaired electrons, no spin, only integer occupation, existence of a gap, etc.). Adding in these extra complications does not change much of the bottom line, so I've decided to leave these aspects out for clarity. You can find more details (at various levels) in the [references given in the DFTK documentation](https://juliamolsim.github.io/DFTK.jl/stable/guide/density_functional_theory/)."
    ]
   },
   {
@@ -250,7 +247,9 @@
     "- First DFTK inspects the molecule to guess an initial density $\\rho_0$.\n",
     "- Then we solve $ \\rho = D(V(\\rho)) $ by computing\n",
     "  $D(V(\\rho_n))$ for a sequence of iterates $\\rho_n$ until input and output\n",
-    "  are close enough, then we flag convergence.\n",
+    "  are close enough, i.e. the residual\n",
+    "  $$ R(\\rho_n) = D(V(\\rho_n)) - \\rho_n$$\n",
+    "  is small. Then DFTK flags convergence.\n",
     "- We will discuss these algorithms with more details in the next notebook.\n",
     "\n",
     "In the end we obtained the ground-state energy of silicon as"

4_Solving_the_SCF_problem.ipynb

@@ -108,7 +108,7 @@
     "callback = DFTK.ScfDefaultCallback() ∘ plot_callback\n",
     "    \n",
     "# Run the SCF and show the plot\n",
-    "scfres = self_consistent_field(aluminium_setup(); tol=1e-12, callback=callback);\n",
+    "scfres = self_consistent_field(aluminium_setup(5); tol=1e-12, callback=callback);\n",
     "p"
    ]
   },
@@ -125,7 +125,7 @@
    "id": "administrative-manufacturer",
    "metadata": {},
    "source": [
-    "**Hint:** This callback allows to read or modify the full state of the SCF iteration,\n",
+    "**Remark:** This callback allows to read or modify the full state of the SCF iteration,\n",
     "which is a valuable tool when debugging an SCF algorithm.\n",
     "When working in the REPL or with scripts one of my favourite callbacks is\n",
     "```julia\n",
@@ -233,7 +233,7 @@
     "\n",
     "**Exercise:** Modify `fixed_point_iteration` such that it supports this *damped* fixed-point iteration. Try different values for $\\alpha$ between $0$ and $1$ and estimate roughly the $\\alpha$ which gives fastest convergence. For which $\\alpha$ do you observe no convergence at all?\n",
     "\n",
-    "**Note:** The observations you make here are general. We will argue in the next notebook why every SCF converges (locally) if a small enough $\\alpha > 0$ is chosen."
+    "**Remark:** The observations you make here are general. We will argue in the next notebook why every SCF converges (locally) if a small enough $\\alpha > 0$ is chosen."
    ]
   },
   {
@@ -298,7 +298,7 @@
    "id": "cultural-neighborhood",
    "metadata": {},
    "source": [
-    "To work with this algorithms we will use DFTK's intrinsic mechanism to choose a damping. The syntax for this is\n",
+    "To work with this algorithm we will use DFTK's intrinsic mechanism to choose a damping. The syntax for this is\n",
     "\n",
     "```julia\n",
     "repeat = 1\n",
@@ -375,7 +375,7 @@
     "where $P^{-1}$ is a preconditioner that hopefully improve convergence.\n",
     "To re-introduce Anderson around this iteration\n",
     "just replace the previous definition of $R$ by\n",
-    "$R(\\rho) = P^{-1} (F(\\rho_n) - \\rho_n)$, that's it.\n",
+    "$R(\\rho) = P^{-1} (F(\\rho_n) - \\rho_n)$. That's it.\n",
     "\n",
     "As we will discuss in the next notebook the ideal preconditioning $P$\n",
     "depends on the dielectric properties of the material (e.g. whether it is a\n",

5_Analysing_SCF_convergence.ipynb

@@ -277,13 +277,56 @@
     "reduce the damping (try it!)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "colored-processing",
+   "metadata": {},
+   "source": [
+    "Having computed the eigenvalues of the dielectric matrix\n",
+    "we can now also look at the eigenmodes, which are responsible for the bad convergence behaviour.\n",
+    "For example we plot the larges Aluminium mode:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "incident-disney",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "using Plots\n",
+    "using Statistics\n",
+    "\n",
+    "function plot_mode(mode)\n",
+    "    # Average along x axis\n",
+    "    mode_yz = mean(real.(mode), dims=1)[1, :, :, 1]\n",
+    "    heatmap(mode_yz, c=:RdBu_11, aspect_ratio=1, grid=false,\n",
+    "            legend=false, clim=(-0.006, 0.006))\n",
+    "end\n",
+    "\n",
+    "plot_mode(X_large[1])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "radio-contrary",
+   "metadata": {},
+   "source": [
+    "This mode essentially lumps electron density between the left end and the right hand of the cell.\n",
+    "\n",
+    "For this reason the usual term to refer to the origin of the degrading SCF convergence behaviour\n",
+    "in large metallic systems is **charge sloshing**."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "exclusive-exclusive",
    "metadata": {},
    "source": [
-    "**Exercise:** Find the largest eigenvalue in case the Kerker preconditioner is used.\n",
-    "*Hint:* You can construct the operator $P^{-1} \\varepsilon^\\dagger$ by simply chaining the functions (`Pinv_Kerker ∘ epsilon`). Assuming that the smallest eigenvalue is about $0.8$, what is the condition number now?\n",
+    "**Exercise:** Let's see what the Kerker preconditioner can do when it comes to charge sloshing.\n",
+    "\n",
+    "Find the largest eigenvalue for the Aluminium SCF in case the Kerker preconditioner is used.\n",
+    "*Hint:* You can construct the operator $P^{-1} \\varepsilon^\\dagger$ by simply chaining the functions (`Pinv_Kerker ∘ epsilon`). Assuming that the smallest eigenvalue is about $0.8$, what is the condition number now? Feel free to take a look at the shape of the largest eigenvalue. What do you notice?\n",
     "\n",
     "If you want, repeat the exercise for `repeat = 6`. You can assume the smallest eigenvalue is still about $0.95$ or $0.8$, respectively. How does the condition number change if you double the system size?\n",
     "\n",
@@ -423,7 +466,7 @@
    "source": [
     "#### Takeaways:\n",
     "- For insulating systems the best approach is to not use any mixing.\n",
-    "- **The ideal mixing** strongly depeends on the dielectric properties of system which is studied (metal versus insulator versus semiconductor).\n",
+    "- **The ideal mixing** strongly depends on the dielectric properties of system which is studied (metal versus insulator versus semiconductor).\n",
     "- A more detailed discussion as well as some ideas how to deal with inhomogeneous systems (where both metals and insulators coexist) is given in [a recently published paper](https://doi.org/10.1088/1361-648X/abcbdb)."
    ]
   }

6_Floating_point_error.ipynb

@@ -206,7 +206,7 @@
     "#### Takeaway\n",
     "- Trustworthy DFT calculations in pure `Float32` are tricky.\n",
     "- IntervalArithmetic allows to identify routines where much precision is lost.\n",
-    "- If in doubt DFTK allows you to check your DFT calculation in higher precision (e.g. `Double64`) ... but at least for now this is noticably slower."
+    "- If in doubt DFTK allows you to check your DFT calculation in higher precision (e.g. `Double64`) ... but of course that comes at a cost."
    ]
   }
  ],

7_Properties_automatic_differentation.ipynb

@@ -19,10 +19,11 @@
     "- What is of great interest, however, are **differences** or **changes** in the energy\n",
     "  in response to a perturbation.\n",
     "- In fact such responses often represent quantities, which are directly measurable\n",
-    "  in experiment (or are at least closely linked to an experimental quantity).\n",
+    "  in experiment (or are at least they are closely linked to measurements).\n",
     "- A few examples:\n",
     "  * *dipole moment* (response of the energy to a change in electric field)\n",
     "  * *forces* (response to a change in atomic positions)\n",
+    "  * ...\n",
     "\n",
     "Notice that \"response\" is just a different term for \"taking an energy derivative\". So that's a good opportunity to try some automatic differentation tools in combination with DFTK."
    ]
@@ -180,7 +181,7 @@
    "id": "organic-sender",
    "metadata": {},
    "source": [
-    "where again we made use of the Hellman-Feynman. "
+    "where again we made use of the Hellman-Feynman theorem."
    ]
   },
   {