Merge pull request #10 from msa-em/dev

Pre-launch fixes

02_code.md

@@ -4,7 +4,10 @@ numbering:
   enumerator: 1.%s
 ---
 
-Python has inarguably become the leading programming language in the scientific community, continually gaining popularity for the past two decades. This is due to Python being friendly for beginners, owing to its less strict language structure (dynamic typing, automatic memory management, non-compiled language) and the plethora of tutorials and examples. It also benefits from being free (this text would be less accessible if it required a licence), with numerous high quality libraries covering a broad range of applications (numeric calculations, image analysis, machine learning, ...), including a number of packages dedicated to S/TEM. The diverse and broad scope of the python ecosystem allows for interoperability between different domains, and file formats as well as easily re-purposing existing implementations algorithms to new domains.
+Python has inarguably become the leading programming language in the scientific community, continually gaining popularity for the past two decades. 
+This is due to Python being friendly for beginners, owing to its less strict language structure (dynamic typing, automatic memory management, non-compiled language) and the plethora of tutorials and examples. 
+It also benefits from being open-source, with numerous high quality libraries covering a broad range of applications (numeric calculations, image analysis, machine learning, etc.), including a number of packages dedicated to S/TEM. 
+The diverse and broad scope of the python ecosystem allows for interoperability between different domains, and file formats as well as easily re-purposing existing implementations algorithms to new domains.
 
 There are a number of codes dedicated to S/TEM:
 - *ab*TEM - all-Python S/TEM image simulation
@@ -20,9 +23,11 @@ The main libraries used in the code examples of this text are:
 - NumPy (np) - fast numerical calculations
 - CuPy (cp) - drop-in replacement for NumPy to run on GPUs
 - Numba - just-in-time Python compiler for scientific and array-oriented computing
-- matplotlib - all things plotting 
+- matplotlib - plotting and visualization
 - ipywidgets - making interactive figures
-- ASE (Atomic Simulation Environment) - creating and visualizing atomic structures   
+- Atomic Simulation Environment (ASE) - creating and visualizing atomic structures   
 - ...
 
-Dynamically interpreted languages including Python are particularly attractive for domain experts and scientists trying out new ideas, but the performance of the interpreter can be a barrier to high performance. However, by making appropriate use of Python open-source numerical libraries including NumPy, CuPy, and Numba, it is possible to write a purely Python-based code that performs as well or even better than prior codes based on traditional languages such C++ or Fortran. That is indeed what *ab*TEM has been able to achieve, which has made it one of the fastest-growing and popular tools for S/TEM simulations, and our choice for this text.
+Dynamically interpreted languages including Python are particularly attractive for domain experts and scientists trying out new ideas, but the performance of the interpreter can be a barrier to high performance. 
+However, by making appropriate use of Python open-source numerical libraries including NumPy, CuPy, and Numba, it is possible to write a purely Python-based code that performs as well or even better than prior codes based on traditional languages such C++ or Fortran. 
+That is indeed what *ab*TEM has been able to achieve, which has made it one of the fastest-growing and popular tools for S/TEM simulations, and our choice for this text.

03_math.md

@@ -26,9 +26,9 @@ i^2 = -1.
 Examples of complex numbers include $3+5i$, $4/5-(9/7)i$, $-0.23+4.33i$, and $1+\sqrt{5}i$. [](#fig_complex) shows examples of complex numbers. Complex numbers are enormously powerful, and essential when performing calclations using [quantum mechanics](wiki:Quantum_mechanics). 
 
 
-```{figure} 
+```{figure} #app:complex_numbers
 :name: fig_complex
-:placeholder: ./static/complex_numbers.png
+:placeholder: ./figures/complex_numbers.png
 **Complex numbers.** Every complex value consists of a real and an imaginary component, which can be used to compute the magnitude and phase of each value.
 ```
 

04_physics.md

@@ -41,7 +41,7 @@ where $\bm{r}^{\prime}$ now denotes the location of a scattering center, and the
 To describe the propagation of these waves in free space, the imaginary term in the exponential describes periodic variation. Thus for any fixed sum of the spatial and temporal terms in the exponent, the wavefunction has the same value; these represent the planes (or shells) of constant amplitude. To calculate the wave in an arbitrary position, we can simply substitute the new spatial location and time arguments to calculate the resulting amplitude.
 
 (bound-systems-ts)=
-## Bound Systems: The Schrödinger Equation (TS)
+## Bound Systems: The Schrödinger Equation
 
 To derive the wavefunction of a bound system, we need to solve the quantum "equation of motion" for the electron(s) in the corresponding confining potential: this is the Schrödinger equation. The Schrödinger equation gives the fundamental mathematical description of quantum systems, describing the time-evolution of their wavefunction. The equation for a single non-relativistic particle can in the position representation be written as
 
@@ -62,7 +62,7 @@ The equation can only be solved analytically for a handful of simple cases, of w
 where wavefunctions $\psi(\bm{r})$ are the eigenvectors and energies $E$ the eigenvalues of the system.
 
 (electrostatic-potentials-ts)=
-## Electrostatic Potentials (TS)
+## Electrostatic Potentials
 
 The electrostatic potential of a specimen determines not only how the electrons of the system are bound, but also how transmitting electrons scatter via the Lorentz force. It therefore connects the properties of the material to the resulting images or diffraction patterns. The electrostatic potential is fundamentally speaking derived from the electron density of the atoms in a specimen, which is described by their quantum mechanical many-body wavefunction. However, this is only rarely analytically solvable, and various approximations may be needed.
 
@@ -145,10 +145,10 @@ By further assuming that the detector is far from the scatterer, which allows us
 By substituting this to [](#eq:scattering_schrodinger) we get
 
 ```{math}
-\begin{align}
+\begin{aligned}
 \psi(\bm{r}) &\simeq \mathrm{e}^{\mathrm{i} k_{0} \cdot \bm{r}}-\frac{m}{2 \pi \hbar^{2}} \int V\left(\bm{r}^{\prime}\right) \mathrm{e}^{\mathrm{i} k_{0} \cdot \bm{r}^{\prime}} \frac{\mathrm{e}^{\mathrm{i} k \cdot\left(\bm{r}-\bm{r}^{\prime}\right)}}{|\bm{r}|} \mathrm{d}^{3} \bm{r}^{\prime}\\
 &=\mathrm{e}^{\mathrm{i} k_{0} \cdot \bm{r}}-\frac{m}{2 \pi \hbar^{2}} \frac{\mathrm{e}^{\mathrm{i} \bm{k} \cdot \bm{r}}}{|\bm{r}|} \int V\left(\bm{r}^{\prime}\right) \mathrm{e}^{\mathrm{i}\left(\bm{k}_{0}-\bm{k}\right) \cdot \bm{r}^{\prime}} \mathrm{d}^{3} \bm{r}^{\prime}.
-\end{align}
+\end{aligned}
 ```
 
 By further defining $\Delta \bm{k} \equiv \bm{k}-\bm{k}_{0}$, we can write the scattered part of the wave as
@@ -167,7 +167,7 @@ f(\Delta \bm{k}) \equiv-\frac{m}{2 \pi \hbar^{2}} \int V\left(\bm{r}^{\prime}\ri
 is called the atomic form factor (or electron scattering factor {cite:p}`kirkland_advanced_2010` and it describes the angular distribution of scattered intensity. In the first Born approximation it corresponds to the Fourier transform of the scattering potential ($f(\Delta \bm{k})=\mathcal{F}_k[V(r)]$).
 
 (atomic-form-factors-ts)=
-### Atomic form factors (TS)
+### Atomic form factors
 
 The atomic form factors thus describe the angular amplitude for scattering of a single electron of by a single atom. While the first Born approximation is inadequate for describing real specimens (as electrons typically scatter multiple times when passing through a crystal), this description is quite useful since it relates the three-dimensional Fourier transform of the atomic potential to the scattering amplitude.
 
@@ -180,7 +180,10 @@ V(\bm{r})=-\frac{Z e^{2}}{|\bm{r}|}+\int_{-\infty}^{+\infty} \frac{e^{2} \rho\le
 By substituting this into [](#eq:formfactor) and defining a new variable $\bm{R} \equiv \bm{r} - \bm{r}^{\prime}$, so that $\bm{r} = \bm{R} - \bm{r}^{\prime}$ and rearranging, we get
 
 ```{math}
-f(\Delta \bm{k})=\frac{m Z e^{2}}{2 \pi \hbar^{2}} \int_{-\infty}^{+\infty} \frac{1}{|\bm{r}|} \mathrm{e}^{-\mathrm{i} \Delta k \cdot \bm{r}} \mathrm{d}^{3} \bm{r} -\frac{m e^{2}}{2 \pi \hbar^{2}} \int_{-\infty}^{+\infty} \frac{1}{|\bm{R}|} \mathrm{e}^{-\mathrm{i} \Delta \bm{k} \cdot \bm{R}} \mathrm{d}^{3} \bm{R} \int_{-\infty}^{+\infty} \rho\left(\bm{r}^{\prime}\right) \mathrm{e}^{-\mathrm{i} \Delta \bm{k} \cdot \bm{r}^{\prime}} \mathrm{d}^{3} \bm{r}^{\prime}.
+\begin{aligned}
+f(\Delta \bm{k})=&\frac{m Z e^{2}}{2 \pi \hbar^{2}} \int_{-\infty}^{+\infty} \frac{1}{|\bm{r}|} \mathrm{e}^{-\mathrm{i} \Delta k \cdot \bm{r}} \mathrm{d}^{3} \bm{r} \\
+-&\frac{m e^{2}}{2 \pi \hbar^{2}} \int_{-\infty}^{+\infty} \frac{1}{|\bm{R}|} \mathrm{e}^{-\mathrm{i} \Delta \bm{k} \cdot \bm{R}} \mathrm{d}^{3} \bm{R} \int_{-\infty}^{+\infty} \rho\left(\bm{r}^{\prime}\right) \mathrm{e}^{-\mathrm{i} \Delta \bm{k} \cdot \bm{r}^{\prime}} \mathrm{d}^{3} \bm{r}^{\prime}.
+\end{aligned}
 ```
 
 The two first integrals are simply Fourier transforms of $1/r$ that each yield $4 \pi / \Delta k^2$, giving the general expression for the electron scattering factor of an atom as
@@ -267,5 +270,6 @@ Although IAM potentials are useful for many purposes, they do neglect chemical b
 
 ```{figure} #H2_potential
 :name: fig:H2_potential
+:placeholder: ./figures/dft_iam_diff.png
 The difference between the indepdendent atom model potential to the DFT potential for the hydrogen molecule as a function of the distance between the H atoms.
 ```

05_algorithms.md

@@ -267,32 +267,3 @@ I(\bm{R},n)
 ```
 where $\theta$ is the annular coordinate and $k'$ is the radial coordinate for $\bm{k}$-space.
 
-
-
-(bloch-wave-method)=
-### The Bloch Wave Method
-
-text
-
-
-(prism-method)=
-### PRISM
-
-text
-
-
-(other-method)=
-### Other Methods
-
-text
-
-
-
-<!-- ```{figure} #app:fft_1d
-
-```
-
-```{figure} #app:probe_size
-
-```
- -->

07_CTF.md

@@ -16,7 +16,7 @@ This deviation is typically expressed as a phase error or the aberration functio
 
 Another, possibly more intuitive way of framing the phase error is the point spread function 
 ```{math}
-    \mathrm{PSF}(\bm{r}) = F \mathrm{e} ^ {-i \chi(\bm{k})} ,
+    \mathrm{PSF}(\bm{r}) = \mathscr{F}^{-1}_{\bm{k} \rightarrow \bm{r}}\left\{ \mathrm{e} ^ {-i \chi(\bm{k})} \right\} ,
 ```
 the point spread function describes how an imaging system responds to a point source. In STEM, the PSF would be the image of the probe, given an infinite objective aperture, in HRTEM the PSF would be how a perfect point source is imaged by an objective lens with an infinite collection angle.  
 
@@ -30,4 +30,10 @@ For an uncorrected microscope the dominant aberration is ther third order spheri
 ```{math}
     \chi(k) \approx \frac{2\pi}{\lambda}\left( \frac{\lambda^2 k^2}{2} \Delta f + \frac{\lambda^4 k^4}{4} C_s \right) \quad .
 ```
-Here we used the common aliases of the aberration coefficients, so $C10 = -\Delta f$ is the negative defocus and $C_{30} = C_s$ is the third order spherical aberration. 
+Here we used the common aliases of the aberration coefficients, so $C10 = -\Delta f$ is the negative defocus and $C_{30} = C_s$ is the third order spherical aberration. 
+
+```{figure} #app:ctf_psf
+:name: fig_ctf_psf
+:placeholder: ./figures/ctf_psf.png
+**Interactive widget showing the influence of common aberrations on the point spread function (PSF) and contact transfer function (CTF) **: 
+```

08_TEM.md

@@ -18,14 +18,14 @@ After building an atomic potential as described in the [](#algorithms_page), the
 ```{figure} #app:tem_imaging
 :name: fig_tem_phase
 :placeholder: ./static/tem_imaging.png
-**TEM imaging of SrTiO$_$ grains**: 
+**TEM imaging of SrTiO$_3$ grains**: 
 ```
 
 
 
 ### Diffraction 
 
-```{figure}
+```{figure} #app:tem_diffraction
 :name: fig_tem_diffraction
 :placeholder: ./static/tem_diffraction.png
 **TEM diffraction of STO as a function of thickness**: 
@@ -41,17 +41,15 @@ In TEM, aberrations modify the exit wave ({math}`\Psi_{exit}`) after the multisl
 ```{math}
 :label: eq:TEM_aberrations
 
-\begin{align} 
-    \Psi_{image}(\bm{k}) = \Psi_{exit}(\bm{k}) \mathrm{e}^{-i\chi(\bm{k})},
-\end{align}
+\Psi_{image}(\bm{k}) = \Psi_{exit}(\bm{k}) \mathrm{e}^{-i\chi(\bm{k})},
 ```
 
 One example of the importance of aberrations and wavfunction modification is shown in [](#tem_contrast). Although the wavfunction at the imaging plane ({math}`\Psi_{image}(\bm{k}`)) may be complex, only the intensity of the exit wave is measured by detectors. Weakly scattering samples, impart very little ampltidue contrast on the incident beam, so most of the structural information is encoded in the phase of the exit wave. This is especially well known in the case of imaging of biological materials, as these structures are beam-sensitive and composed of low atomic number (weakly scattering elements). This effect is evident in the left pannel of [](#tem_contrast), where as the dose decreases, it is very challenging to observe the simulated covid spike protein.
 
 ```{figure} #app:tem_contrast
 :name: fig_tem_phase
 :placeholder: ./static/tem_contrast.png
-**TEM imaging of covid spike protein **: (left) In focus, (middle) defocued, and (right) Zernike phase plate TEM images. [Covid structure](https://www.rcsb.org/structure/3jcl) from {cite}`walls2016cryo`
+**TEM imaging of covid spike protein**: (left) In focus, (middle) defocued, and (right) Zernike phase plate TEM images. [Covid structure](https://www.rcsb.org/structure/3jcl) from {cite}`walls2016cryo`
 ```
 
 For the same, dose the image contrast can be increased by modfying the wavefunctions through the introduction of aberrations. This is most often done with defocus, which is illustrated in the middle pannel. The resulting image has improved contrast, making it easier to visualize the covid spike protein. The middle pannel shows the defocused image, but the aberrations can often be corrected for later in post-processing. 

09_STEM.md

@@ -17,21 +17,19 @@ The incident probe wavefunction is easiest to define in Fourier space
 ```{math}
 :label: eq:fourier_probe
 
-\begin{align} 
-    \Psi_0(\bm{k}) = A(\bm{k}) \mathrm{e}^{-i\chi(\bm{k})},
-\end{align}
+\Psi_0(\bm{k}) = A(\bm{k}) \mathrm{e}^{-i\chi(\bm{k})},
 ```
 
 where the amplitude, {math}`A(\bm{k})`, is the aperture function and the phase, {math}`\chi(\bm{k})`, is the aberration function introduced in section [%s](). The aperture is usually a disk with a radius given by the cutoff semiangle
 
 ```{math}
-\begin{align}
+\begin{aligned}
     A(\bm{k}) = 
     \begin{cases}
     1, &  \lambda k = \alpha < \alpha_{cutoff} \\
     0,              & \text{otherwise} .
     \end{cases}
-\end{align}
+\end{aligned}
 ```
 
 While the above definition is typical for most STEM experiments, the initial wavefunction can be defined using any other complex function and other initial conditions may be required for simulating more exotic experiments such phase plate STEM.
@@ -41,37 +39,20 @@ The probe is transferred to the specimen using an inverse Fourier transform and,
 ```{math}
 :label: eq:realspace_probe
 
-\begin{align} 
     \psi_0(\bm{r}, \bm{r}_p) = \mathcal{F}_{\bm{q}}^{-1} \left[\mathrm{e^{-i\chi(\bm{k}) - 2 \pi i \bm{k}\cdot \bm{r}_p }} A(\bm{k}) \right] ,
-\end{align}
 ```
 
 where, {math}`\bm{r}_p`, is a specified probe position in relative to the atomic coordinates.
 
-In [](#fig_probe) , we present an interactive visualization for exploring the relationship between size and shape of the incident probe and some parameters of the aperture and aberration functions.
-
-
-
-```{figure} #app:probe_size
-:name: fig_probe
-:placeholder: ./static/probe_size.png
-**Left** The Fourier space initial wavefunction in equation [](#eq:fourier_probe). **Middle** The real space probe at the specimen in equation [](#eq:realspace_probe). **Right**  The real space intensity. Start by considering the effect of changing just the aperture and energy. In real space, the probe forms the diffraction-limited Airy disk pattern; increasing the aperture or energy decreases the radius of the pattern. Consider the differences between the STEM and SEM probes.  Next, add defocus. In Fourier space, the phase starts oscillating radially with a linearly decreasing period, the resulting probe grows and its radial intensity profile may have multiple peaks and valleys. Now try to decrease the aperture to include only the inner slowly varying part of the phase; the result is a smaller, more well-behaved probe. Add some spherical aberration and try to compensate by adding some defocus to flatten the phase inside the aperture resulting in a better probe (uncorrected STEM at Scherzer). Lastly, make a large probe and observe the diffraction fringes from self-interaction(boundary artifacts). This is the issue that should be avoided by increasing the size of the unit cell, as described in section. 
-```
-
-
 Because STEM simulations can require long computation times, we often try to reduce the size of the simulation cell as much as possible. However, we must be careful to use a simulation cell large enough to hold the STEM probe. In particular, we need to consider the size of the probe throughout the full simulation cell volume. For an empty cell, the probe will have a maximum size at either the entrance or exit surface, depending on the probe defocus.
 
-Use the drop down menu in [](#fig_probe), to see what the probe looks like when it has wrap-around artifacts. Try modifying the aberrations and notice as the probe gets bigger the error gets worse. Note that this example only considers an empty cell volume. Atoms inside the simulation volume will scatter the electron beam, with heavier elements scattering electrons to higher angles. We recommend positioning individual STEM probes at the positions where the highest scattering is expected (for example directly on or adjacent to the thickest atomic columns), and carefully checking the dimensions of the probe at the exit surface. This is especially important for PRISM simulations, as the cropping box around the STEM probe can be significantly smaller than the full cell dimensions for high PRISM interpolation factors {cite:t}`ophus_fast_2017`.
-
 (imaging)=
 ### Imaging
 
 The initial wavefunction is passed through the specimen potential according to the multislice algorithm. The exit wavefunction, {math}`\psi_t(\bm{r}, \bm{r}_p)`, is then diffracted to the detector plane using another Fourier transform
 
 ```{math}
-\begin{align*}
-    \Psi_t(\bm{k}, \bm{r}_p) = \mathcal{F}_{\bm{r}} [\psi_t(\bm{r}, \bm{r}_p)] .
-\end{align*}
+\Psi_t(\bm{k}, \bm{r}_p) = \mathcal{F}_{\bm{r}} [\psi_t(\bm{r}, \bm{r}_p)] .
 ```
 
 The square modulus, {math}`|\Psi_t(\bm{k}, \bm{r}_p)|^2` is the diffraction pattern for the probe position {math}`\bm{r}_p`.
@@ -81,22 +62,20 @@ Every STEM mode requires calculating a diffraction pattern for each shifted init
 In bright-field (BF) and annular-dark-field (ADF) STEM the detector integrates the CBED pattern on a region in the diffraction plane. This is equivalent to multiplying with a detector function
 
 ```{math}
-\begin{align*}
-    g(\bm{r}_p) = \int\int D(\bm{k})|\Psi_t(\bm{k}, \bm{r}_p)|^2 ~d^2 \bm{k}
-\end{align*}
+g(\bm{r}_p) = \int\int D(\bm{k})|\Psi_t(\bm{k}, \bm{r}_p)|^2 ~d^2 \bm{k}
 ```
 
 
 where
 
 ```{math}
-\begin{align*}
+\begin{aligned}
     D(\bm{k}) = 
     \begin{cases}
     1, &  \alpha_a < \lambda k < \alpha_b \\
     0,              & \text{otherwise}
     \end{cases}
-\end{align*}
+\end{aligned}
 ```
 
 

environment.yml

@@ -2,10 +2,12 @@ name: guide-tem-simulation
 channels:
   - conda-forge
 dependencies:
+  - 'python<3.12'
   - 'numpy<2'
   - scipy
   - h5py
   - matplotlib
+  - colorspacious
   - abtem
   - ipywidgets
   - jupyterlab