Julia Posts by Yi-Xin Liu, A Polymer Physicist

Tutorial on CubicHermiteSpline.jl

2024-02-17T00:00:00-00:00

This is a tutorial on how to use the Julia package CubicHermiteSpline.jl, which performs a cubic Hermite spline interpolation on an array of data points, $(x_i, y_i)$, given that their associated gradients, $k_i=(dy/dx)_i$, are known in advance.

New

v0.3.0 can now perform bivariate cubic Hermite spline interpolation for 2D data points (regular and irregular grids are both supported).
v0.2.2 can now compute the 1st order derivative of the interpolated function.

Getting started
Example 1: interpolating cubic polynomial
Example 2: interpolating smooth functions
Available methods
Contribute
Acknowledgements

Getting started

First, the package can be easily installed from the Julia REPL:

julia> using Pkg
julia> Pkg.add("CubicHermiteSpline")

Or in the package mode (typing ] in REPL):

(v1.5) pkg> add CubicHermiteSpline

Then you can load the package:

using CubicHermiteSpline
import Plots
using Plots: plot, plot!
using LaTeXStrings

Plotting related packages are also loaded. Let’s tweak the appearance of our plots:

Plots.default(size=(600, 370))
fntf = :Helvetica
titlefont = Plots.font(fntf, pointsize=12)
guidefont = Plots.font(fntf, pointsize=12)
tickfont = Plots.font(fntf, pointsize=9)
legendfont = Plots.font(fntf, pointsize=8)
Plots.default(fontfamily=fntf)
Plots.default(titlefont=titlefont, guidefont=guidefont, tickfont=tickfont, legendfont=legendfont)
Plots.default(minorticks=true)
Plots.default(linewidth=1.2)
Plots.default(foreground_color_legend=nothing)
Plots.default(legend=false)

Now we are ready to go.

Example 1: interpolating cubic polynomial

The cubic polynomial of the form

\[f(x) = ax^3 + bx^2 + cx + d\]

should be exactly interpolated by the cubic Hermite spline interpolation.

Below we use CubicHermiteSpline.jl to demonstrate this fact. First we define a typical cubic polynomial:

f(x) = x^3 - 3x^2 + 2x - 5;

Its gradient are available in an analytical form as

df(x) = 3x^2 - 6x + 2;

The exact cubic polynomial is evaluated at evenly spaced points.

a = 0.0
b = 2.5
x_exact = range(a, b, step=0.01);
y_exact = f.(x_exact);
k_exact = df.(x_exact);

The exact cubic polynomial is plotted.

xlabel = L"x"
ylabel = L"f(x)"
plot(x_exact, y_exact, xlabel=xlabel, ylabel=ylabel)

Generate a set of data points to be interpolated in the cubic polynomial curve on a evenly spaced grid:

x_input = range(a, b, step=0.5);
y_input = f.(x_input);
k_input = df.(x_input);

Create an interpolation instance:

spl = CubicHermiteSplineInterpolation(x_input, y_input, k_input);

Perform the actual cubic Hermite spline interpolation:

x_interp = range(a, b, step=0.01);
y_interp = spl(x_interp);

Plotting input data points, exact solution, and the interpolated result in a single plot shows that the interpolation is exact for cubic polynomials.

Plots.scatter(x_input, y_input, label="input data", legend=:topleft)
plot!(x_exact, y_exact, label="exact")
plot!(x_interp, y_interp, label="interpolated")

Interpolate the gradients of the cubic polynomial

k_interp = spl(x_interp; grad=true);

The results are plotted.

Plots.scatter(x_input, k_input, xlabel=xlabel, ylabel=L"f'(x)", label="input data", legend=:topleft)
plot!(x_exact, k_exact, label="exact")
plot!(x_interp, k_interp, label="interpolated")

Do the interpolation again for data points on an irregular grid:

x_input = [a, 0.1, 0.6, 1.75, b];
y_input = f.(x_input);
k_input = df.(x_input);

spl = CubicHermiteSplineInterpolation(x_input, y_input, k_input);

x_interp = range(a, b, step=0.01);
y_interp = spl(x_interp);

Plots.scatter(x_input, y_input, label="input data", legend=:topleft)
plot!(x_exact, y_exact, label="exact")
plot!(x_interp, y_interp, label="interpolated")

Also compute the 1st order derivative of the interpolated function.

k_interp = spl(x_interp; grad=true);

Plots.scatter(x_input, k_input, xlabel=xlabel, ylabel=L"f'(x)", label="input data", legend=:topleft)
plot!(x_exact, k_exact, label="exact")
plot!(x_interp, k_interp, label="interpolated")

Example 2: interpolating smooth functions

Here we use the spherical bessel function of the first kind:

\[j_1(x) = \frac{\sin x - x\cos x}{x^2}.\]

Below we show that the cubic Hermite spline performs impressively well for interpolating such smooth functions.

g(x) = (sin(x) - x*cos(x)) / x^2;

# dg(x) = ((x^2 - 2) * sin(x) + 2x*cos(x)) / x^3;
dg(x) = (sin(x) - 2*g(x)) / x;

a = 0.01
b = 8.01
x_exact = range(a, b, step=0.01);
y_exact = g.(x_exact);

ylabel = L"g(x)"
plot(x_exact, y_exact, xlabel=xlabel, ylabel=ylabel)

Perform cubic Hermite interpolation on an even grid:

x_input = range(a, b, step=0.5);
y_input = g.(x_input);
k_input = dg.(x_input);

spl = CubicHermiteSplineInterpolation(x_input, y_input, k_input);

x_interp = range(a, b, step=0.01);
y_interp = spl(x_interp);

Plots.scatter(x_input, y_input, xlabel=xlabel, ylabel=ylabel, label="input data", legend=:topright)
plot!(x_exact, y_exact, label="exact")
plot!(x_interp, y_interp, label="interpolated")

Compute the interpolated gradients of the target function.

k_interp = spl(x_interp; grad=true);

Plots.scatter(x_input, k_input, xlabel=xlabel, ylabel=L"g'(x)", label="input data", legend=:topright)
plot!(x_exact, k_exact, label="exact")
plot!(x_interp, k_interp, label="interpolated")

It can be seen from above plot that interpolation on data points and gradients works perfectly for known data points on a dense even grid.

Interpolate the function on an unevenly spaced grid:

x_input = [a, 0.6, 1.5, 3.4, 4.5, 5.0, 6.2, 7.5, b];
y_input = g.(x_input);
k_input = dg.(x_input);

spl = CubicHermiteSplineInterpolation(x_input, y_input, k_input);

x_interp = range(a, b, step=0.01);
y_interp = spl(x_interp);

Plots.scatter(x_input, y_input, xlabel=xlabel, ylabel=ylabel, label="input data", legend=:topright)
plot!(x_exact, y_exact, label="exact")
plot!(x_interp, y_interp, label="interpolated")

The gradients of the target function can be also interpolated.

k_interp = spl(x_interp; grad=true);

Plots.scatter(x_input, k_input, xlabel=xlabel, ylabel=L"g'(x)", label="input data", legend=:topright)
plot!(x_exact, k_exact, label="exact")
plot!(x_interp, k_interp, label="interpolated")

Note that the accuracy of the interpolation degrades near the extrema of the function if there is no input data point near that region.

Available methods

Interpolation

# `spl` is an instance of `CubicHermiteSplineInterpolation`.
# `x` can be a real number of an 1D array of real numbers.
# Following two methods are equivalent.
spl(x; grad=false)
interp(spl, x)

Interpolated gradients

spl(x; grad=true)
grad(spl, x)

Contribute

Star the package on github.com.
File an issue or make a pull request on github.com.
Contact me via email lyx@fudan.edu.cn.

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021) and Shanghai Pujiang Program (No. 18PJ1401200).

Tutorial on CubicHermiteSpline.jl was originally published by Yi-Xin Liu at Polyorder on June 19, 2020.

Julia in Practice: Building Scattering.jl from Scratch (6)

2020-04-29T00:00:00-00:00

In this post we will first coin the term form factor for arbitrary particles by generalizing the idea of the atomic form factor. We then derive an analytical expression for the form factor of a homogeneous sphere. The functionality is implemented in two submodules: scatterer.jl and formfactor.jl. These two modules will be gradually extended by adding more types of particles as the project goes on.

Form Factor
- General formula
- Form factor of a homogeneous sphere
Implementation
- scatterer.jl
- formfactor.jl
Usage
Acknowledgements
Reference

Form Factor

In this section will generalize the strategy described in the previous post to arbitrary particles consisting of any type of building blocks, such as electrons, atoms, molecules, complexes, polymers, nanoparticles, etc., as long as they themselves can be viewed as basic building blocks of the sample. We will see that such generalization eventually lead to the concept of form factor. Just as we call the amplitude of the x-ray scattering from an atom as atomic form factor, we will term the amplitude of the x-ray scattering from any particle as the form factor of the particle and denoted as $F(\vq)$. Note that, however, this quantity is usually termed as form factor amplitude in the literature. And the quantity $F(\vq)F^*(\vq)$ is instead termed as the form factor. Throughout this project, we will stick to the convention that $F(\vq)$ is called form factor.

General formula

The strategy presented in the previous post demonstrates that the amplitude of the x-ray scattering from multiple atoms can be derived from the amplitude of the scattering from its building blocks, i.e. a single atom, which in turn can be derived from the amplitde of the scattering from its building blocks, i.e. a single electron. It seems that there is a recursive relation between these amplitudes. To see it clearly, we shall rewrite the normalized amplitude of the x-ray scattering from a single electron as

\[\begin{equation} F_e(\vq) = \frac{A_e}{A_0} = b_e = \int d\vr\; \rho_e(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:Fe}\]

where $b_e$ is the scattering length of an electron. And $\rho_e(\vr)$ is the scattering length density distribution of an electron which is

\[\begin{equation} \rho_e(\vr) = F_0 \delta(\vr). \end{equation}\label{eq:rhoe}\]

where $F_0=b_e$ and $\delta(x)$ is a delta function. The normalized amplitude of the x-ray scattering from a single atom can also be rewritten as

\[\begin{equation} F_a(\vq) = \frac{A_a}{A_0} = \int d\vr\; \rho_a(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:Fa}\]

where $\rho_a(\vr)$ is the scattering length density distribution of the atom, which is defined as

\[\begin{equation} \rho_a(\vr) = F_e n_e(\vr). \end{equation}\label{eq:rhoa}\]

where $n_e(\vr)$ is the number density of the electrons within an atom. The normalized amplitude of the x-ray scattering from a particle (multiple atoms in a certain volume) consisting of $M$ types of atoms can be rewritten as

\[\begin{equation} F_p(\vq) = \frac{A_p}{A_0} = \int d\vr\; \rho_p(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:Fp}\]

where $\rho_p(\vr)$ is the scattering length density distribution of the particle, which is defined as

\[\begin{equation} \rho_p(\vr) = \sum_{\alpha=1}^{M} F_{a\alpha} n_{a\alpha}(\vr) \end{equation}\label{eq:rhop}\]

where $F_{a\alpha}$ is the normalized amplitude contributed by the atom of type $\alpha$, each is given by eq.\eqref{eq:Fa}, and $n_{a\alpha}(\vr)$ is the number density of the atom of type $\alpha$ within the particle. When the particle consists of only one type of atom, eq.\eqref{eq:rhop} is simply

\[\begin{equation} \rho_p(\vr) = F_a n_a(\vr) \end{equation}\label{eq:rhop2}\]

It is now ready for us to explore the structure of the normalized amplitude of a particle. The building block of a particle is atoms. The building block of an atom is electrons. We can find the normalized amplitude of a particle using a top-down approach, by following the chain $F_p \to \rho_p \to F_a \to \rho_a \to F_e$, i.e. by using the above equations in a reverse order. Therefore, the normalized amplitude is a universal quantity that is associated to the scatterer we are looking at. In the literature, it is termed as the form factor of the scatterer, just as the atomic form factor for an atom.

Suppose a sample we are interested in consists of $M$ types of building blocks. Each building block can be any chemical or physical objects, such as electrons, atoms, molecules, complexes, polymers, nanoparticles etc.. Then the form factor of the sample can be written in a general form

\[\begin{equation} F(\vq) = \frac{A}{A_0} = \int d\vr\; \rho(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:F}\]

where $\rho(\vr)$ is the scattering length density distribution of the sample which is given by

\[\begin{equation} \rho(\vr) = \sum_{\alpha=1}^{M} F_{b\alpha} n_{b\alpha}(\vr) \end{equation}\label{eq:rho}\]

Here $n_{b\alpha}(\vr)$ is the number density of the $\alpha$th building block of the sample with its center located at position $\vr$. $F_{b\alpha}$ is the form factor of the $\alpha$th building block of the sample. Note that, in general, $F_{b\alpha}$ is a function of $\vq$. To find $F_{b\alpha}$ for each building block, we will use eq.\eqref{eq:F} and eq.\eqref{eq:rho} in a recursive manner.

The scattering intensity which is directly measured in experiments is the differential scattering cross section:

\[\begin{equation} I(\vq) = \frac{J_\Omega}{J_0} = \frac{\abs{A}^2}{\abs{A_0}^2} = FF^* \end{equation}\label{eq:I}\]

By viewing eq.\eqref{eq:I}, we conclude that the form factor is the most fundamental quantity in scattering experiments, while the structure factor is a derived quantity from the form factor.

Note that, in some cases, such as polymers, the building blocks are highly correlated. Time average or ensemble average should be performed to obtain the scattering intensity. In these cases, the scattering intensity is proportional to the Fourier transform of the correlation function $\ensemble{n(\vr)n(\vr’)}$, just as in the case of polymeric systems. Therefore, eq.\eqref{eq:I} is not applicable in these situations.

Also note that, in the polymer community, due to the fact mentioned above, the term form factor is commonly referred to the square of the normalized amplitude, which is proportional to the scattering intensity.

Form factor of a homogeneous sphere

The simplest scatterer (except that of an electron which is just the scattering length $b_e$) is a homogeneous sphere. Here, the word homogeneous has a specific meaning that the scattering length density distribution $\rho(\vr)$ is a constant function across the whole volume of the sphere, $\rho(\vr)=\rho_0$. Note that it is only possible that the scattering angle should be quite small because $b_e \sim (1+\cos^22\theta)^{1/2}$ becomes a constant only in the limit of $\theta \to 0$. This is also the reason why the form factor of a homogeneous sphere is mostly interested and studied in the small-angle scattering (SAS) community. For small-angle x-ray scattering (SAXS) experiments, the radius of the sphere should be at least in nanoscale.

To compute the form factor of the homogeneous sphere, it is most convenient to use a spherical coordinate system $(r, \theta, \phi)$. We put the center of the sphere at the origin. The homogeneous sphere is spherical symmetric, which enables us choose its polar axis freely. The simplest choice is to let the direction of $\vq$ and the polar axis coincide. In such setup, we have

\[\vq \cdot \vr = qr\cos\theta\]

And the form factor written in eq.\eqref{eq:F} is evaluated as

\[\begin{split} F(q) &= 4\pi\int_0^R dr\; \rho_0r^2\frac{\sin(qr)}{qr} \\ &= \frac{4\pi\rho_0}{q}\int_0^R dr\; r\sin(qr) \\ &= -\frac{4\pi\rho_0}{q^2} \int_0^R dr\; rd\cos(qr) \\ &= -\frac{4\pi\rho_0}{q^2} \left[ r\cos(qr)\rvert_0^R - \int_0^R dr\; \cos(qr) \right] \\ &= -\frac{4\pi\rho_0}{q^2} \left[ R\cos(qR) - 0 - \frac{1}{q}\sin(qr)\rvert_0^R \right] \\ &= -\frac{4\pi\rho_0}{q^2} \left[ R\cos(qR) - \frac{1}{q}\sin(qR) \right] \\ &= 4\pi\rho_0 \frac{\sin(qR) - qR\cos(qR)}{q^3} \end{split}\]

\[\begin{equation} F(q) = 3\rho_0V \frac{\sin(qR) - qR\cos(qR)}{(qR)^3} \end{equation}\label{eq:Fsphere}\]

where $V=4\pi R^3/3$ is the volume of the sphere. Note that the first line of the above equation directly adopts the result of eq.(35) derived in the previous post. Noticing that the spherical bessel function of the first kind at order 1 is

\[j_1(z) = \frac{\sin z - z\cos z}{z^2}\]

Inserting it into eq.\eqref{eq:Fsphere}, we have

\[\begin{equation} F(q) = \rho_0V \frac{3j_1(qR)}{qR} \end{equation}\label{eq:Fspherej1}\]

And the intensity scattered by a single sphere is just

\[\begin{equation} I(q) = \rho_0^2V^2 \left(\frac{3j_1(qR)}{qR}\right)^2 \end{equation}\label{eq:Isphere}\]

Implementation

We can compute the form factor of a particle using eq.\eqref{eq:F} and eq.\eqref{eq:rho}, given that the form factor and the number density distribution are known explicitly for its building blocks and all sub building blocks. We will call such particles simple particles. When at least one of these two quantities are unknown in explicit form, we will call it complex particles. Complex particles have internal structures and their building blocks correlate with each other. Special techniques have to be introduced to obtain the scattering of complex particles.

Examples of simple particles are atoms, basic geometric shapes with uniform scattering length density distribution (such as homogeneous spheres, cylinders, polyhedra, etc.), composite of non-interacting basic geometric shapes with uniform scattering length density distribution. Non-ineracting building blocks means their position and orientation are fixed. Composite particles consisting of simple particles are also simple particles if the number density distributions of each building block are known. Atoms are simple particles because the number density distribution of its building block which is the electron is available. We will see in the later posts that by using eq.\eqref{eq:F} and eq.\eqref{eq:rho}, we can easily compute the composite simple particles consisting of basic simple particles as their building blocks. It is a powerful insight. For example, the article by Senesi and Lee¹ becomes a special case of this approach.

Examples of complex particles are polymers and particles whose building blocks contain polymers. It is required to compute the correlation of the number density distribution of polymers’ building blocks which are segments. Sometimes, analytical expression for the correlation of the number density distribution is available. Furthemore, for a correlated system, the correlation of the number density distribution is generally not equal to the square of the ensemble average of the number density distribution:

\[\begin{equation} \ensemble{n(\vr)n(\vr')} \neq \ensemble{n(\vr)}^2 \end{equation}\label{eq:correlation}\]

scatterer.jl

Any matter that can scatter x-rays will have a form factor. We will first define an abstract type to represent all such matter.

abstract type AbstractScatterer end

Inheriting from it, two abstract types representing the sample and the particle are defined. The AbstractSample stands for the actual sample the experiment want to measure, while the AbstractParticle models the scattering components in the sample.

abstract type AbstractSample <: AbstractScatterer end
abstract type AbstractParticle <: AbstractScatterer end

According to our previous discussion, the particle is further categorized into following two types. The way of computing the form factors of these two types of particles are quite different.

abstract type SimpleParticle <: AbstractParticle end
abstract type ComplexParticle <: AbstractParticle end

The homogeneous sphere is a simple particle. We can define it as follows

struct Sphere{T <: Real} <: SimpleParticle
    R::Float64 # radius
    V::Float64 # volume
    ρ::Float64 # scattering length density
    Δρ::Float64 # = ρ - ρ_ambient
    origin::RVector{T}
    function Sphere(R::Real, ρ::Real, Δρ::Real, origin::RVector{T}) where {T<:Real}
        @argcheck R > 0 DomainError
        @argcheck ρ > 0 DomainError
        new{T}(R, 4π*R^3/3, ρ, Δρ, RVector(origin))
    end
end

Since the homogeneous sphere is isotropic, it is not necessary to have a field for its orientation.

formfactor.jl

It is straightforward to implement a method to compute the form factor of a homogeneous sphere using eq.\eqref{eq:Fsphere}.

function formfactor_basic(s::Sphere, q::Real)
    qR = q * s.R
    return s.Δρ * s.V * 3 * sphericalbesselj(1, qR) / qR
end

Here the suffix basic denotes that the homogeneous sphere is a basic simple particle which means that it has no building block. The sphericalbesselj function has been implemented in the SpecialFunctions.jl package.

Usage

The usage of above submodules is straightforward. First, we create a homogeneous sphere with radius $1.0$ and uniform scattering length density $\rho=15.0$, locating at the origin. Assume that the scattering length density of the ambient is $0$.

julia> s0 = Sphere(1.0, 15.0, 15.0, [0.0, 0.0, 0.0])
Sphere{Float64}(1.0, 4.1887902047863905, 15.0, 15.0, [0.0, 0.0, 0.0])

The form factor of this sphere at a single $q$ is computed as

julia> formfactor_basic(s0, 1.0)
56.76895855490903

The form factor of this sphere in a range of $q$ values are obtained using

julia> F = [formfactor_basic(s0, q) for q in 0.01:0.01:10];

And the scattering intensity is readily computed

julia> I = abs2.(F);

Then the form factor and scattering intensity are plotted and shown below.

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

Reference

Senesi, A.; Lee, B. Scattering Functions of Polyhedra. J. Appl. Crystallogr. 2015, 48, 565–577. ↩

Julia in Practice: Building Scattering.jl from Scratch (6) was originally published by Yi-Xin Liu at Polyorder on April 29, 2020.

Julia in Practice: Building Scattering.jl from Scratch (5)

2022-02-12T00:00:00-00:00

In this post we will present a concise review of the fundamental theory of X-ray scattering, including electromagnetic waves, flux and intensity, scattering cross section and scattering length, scattering by an electron, interference, and atomic form factor. Although the specific properties of X-rays are used, the derivation is applicable to other incident beams, such as neutrons. The derivation presented here is different from most of literature with an emphasis on a consistent treatment on the wave nature of the incident beam. The notations used in this post mostly follow the book by Roe¹.

Electromagnetic Wave
Flux
- Flux of a plane wave
- Flux of a spherical wave
Scattering by an electron
Interference
- Derivation based on formula \eqref{eq:amplitude}
- Classical derivation
Scattering by Atoms
- Atomic form factor
- Multiple atoms
Generalization to Arbitrary Particles
Acknowledgements
References

Electromagnetic Wave

An electromagnetic wave, including X-rays, which is monochromatic, sinusoidal, and planar travelling, has the following form:

\[\begin{equation} \vE(\vr,t) = \vE_0\cos(\omega t - \vk\cdot\vr) \end{equation}\label{eq:waveE}\]

where $\vE_0$ is a constant vectors, $\vk$ is called the wave vector, and $\omega$ is the angular frequency. The frequency in hertz, $\nu$, is related to the angular frequency via

\[\omega = 2\pi\nu\]

Actually, it is more convenient to write

\[\begin{equation} \vE(\vr,t) = \vE_0 e^{i(\omega t - \vk\cdot\vr)} \end{equation}\label{eq:wave}\]

where, by convention, the electromagnetic wave is the real part of the above equation.

The direction of the wave vector $\vk$ is the direction of the wave travels and its length is $2\pi/\lambda$. Thus the wave vector is sometimes written as

\[\begin{equation} \vk = \frac{2\pi}{\lambda}\vS \end{equation}\label{eq:vk}\]

where $\vS$ is a unit vector and $\lambda$ is the wave length which is related to the frequency as

\[\lambda = \frac{c}{\nu}\]

Here $c$ is the speed of light.

The amplitude of an electromagnetic wave is

\[\begin{equation} E(\vr, t) = E_0 \cos(\omega t - \vk\cdot\vr) \end{equation}\label{eq:ampE}\]

where $E_0=\abs{\vE_0}$. It is also more convenient to write it in a complex form

\[\begin{equation} A(\vr, t) = E_0 e^{i(\omega t - \vk\cdot\vr)} \end{equation}\label{eq:ampA}\]

where it is understood that the actual amplitude is the real part of $A$: $E(\vr,t)=\mathrm{Real}[A(\vr,t)]$. Note that, however, the amplitude is not equal to $\abs{A}$ which is just $E_0$.

Flux

Flux of a plane wave

The energy density of an electromagnetic plane wave is given by

\[u(\vr, t) = \epsilon_0\abs{\vE}^2.\]

where $\epsilon_0$ is the permittivity in vacuum. This energy density moves with the electric and magnetic fields in a similar manner to the wave itself. We can find the rate of transport of energy, i.e., the flux, by considering a small time interval $\Delta t$. A wave passes through a cylinder of length $c\Delta t$ and cross-sectional area $S$ in the interval $\Delta t$. The energy passing through area $S$ in time $\Delta t$ is

\[u \times (\mathrm{volume\;of\;the\;cylinder}) = uSc\Delta t\]

The energy per unit area per unit time passing through an area perpendicular to the wave, called the energy flux and denoted by $j$, can be calculated by dividing the energy by the area $S$ and the time interval $\Delta t$:

\[j = \frac{uSc\Delta t}{S\Delta t} = cu\]

\[\begin{equation} j = c\epsilon_0\abs{\vE}^2 \end{equation}\]

By substituting eq.\eqref{eq:ampE} into above equation, we have

\[j(\vr, t) = c\epsilon_0 E_0^2 \cos^2(\omega t - \vk\cdot\vr)\]

$j$ is an extremely rapidly varying quantity since the frequency is of the order of $10^{19}$ Hz with the fact that the typical wave length of an X-ray radiated by a copper target tube is 0.154 angstrom. In X-ray scattering experiments, we are most interested in the time averaged flux $J$. Since the wave is a periodic function of time with a period of $T=2\pi/\omega$, the time arerage can be simply carried out in a full cycle starting at $\vr=0$:

\[\begin{equation} \begin{split} J &= \ensemble{j} \\ &= \frac{1}{T}\int_0^Tdt\;j(t) \\ &= c\epsilon_0 E_0^2 \frac{1}{T}\int_0^Tdt\; \cos^2(\frac{2\pi} {T}t) \\ &= \frac{1}{2}c\epsilon_0 E_0^2 \end{split} \end{equation}\label{eq:JE02}\]

It can be seen that the time averaged flux is proportional to the square of the maximum amplitude of the electromagnetic wave. Therefore, by utilizing eq.\eqref{eq:ampA}, we can rewrite above equation into

\[J = \frac{1}{2}c\epsilon_0 AA^*\]

where $A^*$ is the complex conjugate of $A$. However, it is more common to absorb the constants $c\epsilon_0/2$ into $A$. Thus, later on throughout this project, we will define the amplitude of an electromagnetic wave as

\[\begin{equation} A(\vr, t) = A_0 e^{i(\omega t - \vk\cdot\vr)} \end{equation}\label{eq:finalA}\]

where

\[\begin{equation} A_0 = \left( \frac{1}{2}c\epsilon_0 \right)^{1/2} E_0 \end{equation}\label{eq:A0}\]

And the (time averaged) flux can now be simply written as

\[\begin{equation} J = \abs{A}^2 = AA^* \end{equation}\label{eq:JAA}\]

Flux of a spherical wave

In a typical experimental setup for X-ray scattering as shown in Figure 1, the incident beam is always a plane wave. Such plane wave irradiates a sample, from which the scattered beam emanates in all directions.

Figure 1. Basic setup of an X-ray scattering experiment involving incident plane wave, sample, the scattered spherical wave, and the detector.

Experimentally we measure the flux of the scattered beam as a function of the scattering angle denoted as $2\theta$. The scattered beam is a spherical wave. Before we discuss the flux of a spherical wave. Let’s first get familiar with the concept of the solid angle.

Just like a planar angle in radians is the ratio of the length of a circular arc to its radius, the solid angle is defined as

\[\begin{equation} \Omega = \frac{S}{R^2} \end{equation}\label{eq:Omega}\]

Here, $S$ is the spherical surface area and $R$ is the radius of the considered sphere. In particular, for a full spherical surface, its solid angle is $\Omega=4\pi R^2 / R^2 = 4\pi$. The solid angle for a cone with its apex at the apex of the solid angle, and with apex angle $2\theta$ is given by

\[\Omega = 2\pi(1-\cos\theta).\]

The flux of a spherical wave is invariant only when it passing through a solid angle. It can be easily seen by considering the beam as a steam of photons. Obviously, the number of photons emanating from a point source is a constant passing through a solid angle. Thus the flux in the unit of solid angle is

\[\begin{equation} J_{\Omega} = \frac{nE_p}{\Omega} \end{equation}\label{eq:JOmega}\]

while the flux in the unit of area is

\[J = \frac{nE_p}{S}\]

where $E_p$ is the energy of a photon. Inserting it into eq.\eqref{eq:JOmega} and using eq.\eqref{eq:Omega}, we then have

\[\begin{equation} J_{\Omega} = JR^2 \end{equation}\label{eq:JOmegaJ}\]

Note that, for a spherical wave, the relation between flux and the maximum magnitude of a plane wave in eq.\eqref{eq:JAA} should be rewritten as

\[\begin{equation} J_\Omega = \abs{A}^2 = AA^*. \end{equation}\label{eq:JOmegaAA}\]

Scattering by an electron

Suppose a free electron is placed at position O, as shown in Figure 2. The incident X-ray beam propagates in the direction of the $x$ axis. Its flux is $J_0$ in the unit of per area since it is a plane wave. The incident beam is scattered by the electron and the scattering wave is observed at position P by a detector. As compared to the wavelength of the X-ray, the distance $R = OP$ is large. The scattering angle $2\theta$ is the angle between line OP and the $x$ axis. In all following derivations, the scattering event is considered to be both coherent and no phase change occurs.

Figure 2. Scattering of an X-ray by a free electron at the origin.

The full wave representation of the incident beam is given by eq.\eqref{eq:wave}. The electric field vector $\vE_0$ should be in the $yz$ plane perpendicular to the propagating direction of the incident beam because the electromagnetic wave is a transverse wave. To identify the scattering wave at angle $2\theta$, the task is to determine its maximum amplitude and its phase.

Maximum magnitude of the scattered wave

The vector $\vE_0$ in arbitrary direction can be decomposed into two vectors parallel to the $y$ and $z$ axes, respectively. Let’s first consider the case in which the incident beam is polarized in the $z$ direction, with the maximum magnitude being $E_{0z}$. The electromagnetic field of the beam sets the free electron oscillating in the $z$ direction. The alternating acceleration of the oscillating electron in turn induces emission of an electromagnetic wave of the same frequency propagating in all directions. According to the classic electromagnetic theory, the maximum magnitude of the scattering wave at position P obeys

\[\begin{equation} E_z = E_{0z}\frac{e^2}{mc^2}\frac{1}{R} \end{equation}\label{eq:Ez}\]

where $e$ and $m$ are the charge and mass of an electron, respectively.

Next, Let’s consider a incident beam with its electric field vector pointing to the $y$ direction. In this case, the oscillation of the electron is no longer perpendicular to the line OP. Thus the electric field vector $\vE_y$ is the projection of the vector $\vE_{0y}$ on to the line perpendicular to both $z$ axis and the line OP. From Figure 2, it is easily seen that the angle between the vector $\vE_{0y}$ and $\vE_y$ is $2\theta$, thus the magnitude of $\vE_y$ is

\[\begin{equation} E_y = E_{0y}\frac{e^2}{mc^2}\frac{1}{R}\cos2\theta. \end{equation}\label{eq:Ey}\]

For an arbitrarily polarized incident beam, it can be expressed as

\[\begin{equation} \vE_0 = \vE_{0y} + \vE_{0z}. \end{equation}\label{eq:E0}\]

The $y$ and $z$ components of $\vE_0$ contributes in the scattering wave in the way given by eq.\eqref{eq:Ez} and eq.\eqref{eq:Ey}. Then the electric field vector of the scattering wave is $\vE = \vE_y + \vE_z$, and its magnitude is

\[\begin{equation} E^2 = E_y^2 + E_z^2 = \frac{e^2}{mc^2}\frac{1}{R}\left( E_{0z}^2 + E_{0y}^2\cos^22\theta \right) \end{equation}\]

For an unpolarized beam, the direction of its electric field varies randomly with time. We are most interested in the time average value of the scattering wave:

\[\begin{equation} \ensemble{E^2} = \ensemble{E_y^2} + \ensemble{E_z^2} = \left(\frac{e^2}{mc^2}\right)^2 \frac{1}{R^2}\left( \ensemble{E_{0z}^2} + \ensemble{E_{0y}^2}\cos^22\theta \right) \end{equation}\label{eq:E2}\]

To find $\ensemble{E_{0y}^2}$ and $\ensemble{E_{0z}^2}$, we invoke the following relation using eq.\eqref{eq:E0}:

\[E_0^2 = E_{0y}^2 + E_{0z}^2\]

and taking time average of both sides of the above equation

\[E_0^2 = \ensemble{E_0^2} = \ensemble{E_{0z}^2} + \ensemble{E_{0y}^2}\]

However, since the beam is randomly polarized, the time average of $y$ and $z$ components should be equal. Thus we have

\[\ensemble{E_{0z}^2} = \ensemble{E_{0y}^2} = \frac{1}{2}E_0^2\]

Inserting above equation into eq.\eqref{eq:E2}, we arrive at

\[\begin{equation} \ensemble{E^2} = E_0^2\left(\frac{e^2}{mc^2}\right)^2\frac{1+\cos^22\theta}{R^2} \end{equation}\label{eq:E2_avg}\]

Scattering cross section and scattering length

According to eq.\eqref{eq:JE02}, with $\ensemble{E^2}$ given by eq.\eqref{eq:E2_avg}, the flux in the unit of per area is

\[J = \frac{1}{2}c\epsilon_0\ensemble{E^2}=\frac{1}{2}c\epsilon_0E_0^2\left(\frac{e^2}{mc^2}\right)^2\frac{1+\cos^22\theta}{2R^2}\]

Using eq.\eqref{eq:JOmegaJ}, the flux in the unit of per solid angle is then

\[\begin{equation} J_\Omega = JR^2 = \frac{1}{2}c\epsilon_0E_0^2\left(\frac{e^2}{mc^2}\right)^2\frac{1+\cos^22\theta}{2} \end{equation}\label{eq:JOmega_electron}\]

This is called the Thomson formula for the scattering of X-rays by a single free electron. The flux of the incident plane wave is given by eq.\eqref{eq:JE02} and we repeat it here

\[J_0 = \frac{1}{2}c\epsilon_0E_0^2\]

We now define a quantity, the differential scattering cross section of an electron for unpolarized x-rays, as

\[\begin{equation} \left(\frac{d\sigma}{d\Omega}\right)_e = \frac{J_\Omega}{J_0} = \left(\frac{e^2}{mc^2}\right)^2\frac{1+\cos^22\theta}{2} \end{equation}\label{eq:crosssection}\]

Since $J_\Omega$ has the unit of reciprocal of solid angle and $J$ has the unit of reciprocal of area, the differential scattering cross section has a unit of area. Taking the square root of it, the result is in unit of length which is called the scattering length

\[\begin{equation} b_e = \frac{J_\Omega}{J_0} = \frac{e^2}{mc^2} \left(\frac{1+\cos^22\theta}{2}\right)^{1/2} \end{equation}\label{eq:be}\]

In fact, the above derivation is applicable to any charged particles, such as nucleus. However, as the scattering length $b_e$ is proportional to $1/m^2$, the scattering by nucleus is negligible because the mass of a nucleon is much higher than the electron. Thus the scattering of x-rays from matter results entirely from the presence of electrons around atomic centers.

By comparing eq.\eqref{eq:JOmega_electron} to eq.\eqref{eq:JOmegaAA}, we find the maximum magnitude of a scattering wave is given by

\[\begin{equation} A_0b_e \end{equation}\label{eq:magnitude}\]

where $A_0$ is defined in eq.\eqref{eq:A0}.

Phase of the scattering wave

Figure 3 shows the paths travelled by the incident beam and the scattering wave at scattering angle $2\theta$. The phase difference between the wave at position Q and at the position of the beam source P is given by

\[\Delta\phi_1 = \vk_0\cdot(\vr - \vr_0),\]

while the phase difference between the wave at the detector D and at position Q is given by

\[\Delta\phi_2 = \vk\cdot(\vr_d - \vr).\]

Figure 3. Phase difference of the scattering of an X-ray by a free electron at the origin.

The total phase difference between the scattering wave reaching the detector and the incident wave leaving the beam source is

\[\begin{equation} \begin{split} \Delta\phi &= \Delta\phi_1 + \Delta\phi_2 \\ &= \vk_0\cdot(\vr - \vr_0) + \vk\cdot(\vr_d - \vr) \\ &= (\vk\cdot\vr_d-\vk_0\cdot\vr_0) - (\vk - \vk_0)\cdot\vr \\ &= f(2\theta) - (\vk - \vk_0)\cdot\vr \end{split} \end{equation}\label{eq:Deltaphi}\]

The last line of the above equation tells us that the total phase difference consists of two parts: the first part is independent of the position of the electron (scatterer) and the second part is a function of $\vr$. It is common to define a scattering vector

\[\begin{equation} \vq = \vk - \vk_0 = \frac{2\pi}{\lambda}(\vS - \vS_0) \end{equation}\]

Its relation with the incident beam and the scattering wave is illustrated in Figure 4. Figure 4b shows that the scattering vector is perpendicular to the angular bisector of the angle of the other two wave vectors.

Figure 4. Relationship among the scattering vector and wave vectors of the incident beam and the scattering wave.

We then write the incident beam at the beam source

\[\vE_{P}(t) = \vE_0e^{i(\omega t - \vk_0\cdot\vr_0)}\]

Its phase is

\[\begin{equation} \phi_P = \omega t - \vk_0\cdot\vr_0 \end{equation}\label{eq:phiP}\]

Consequently, we can compute the phase of the scattering wave reaching the detector, using eq.\eqref{eq:Deltaphi}, as

\[\begin{equation} \begin{split} \phi_D &= \phi_P + \Delta\phi \\ &= (\omega t - \vk_0\cdot\vr_0) + (\vk\cdot\vr_d-\vk_0\cdot\vr_0) - \vq\cdot\vr \\ &= \omega t + g(2\theta) - \vq\cdot\vr \end{split} \end{equation}\label{eq:phiD}\]

With the maximum magnitude given by eq.\eqref{eq:magnitude} and the phase given by the above equation, the amplitude of the scattering wave reaching the detector is

\[\begin{equation} A = A_0b_e e^{i[\omega t + g(2\theta) - \vq\cdot\vr]} \end{equation}\label{eq:amplitude}\]

Interference

When a beam of x-rays irradiates a sample, it usually results in two different phenomena: (1) scattering of x-rays by a single electron which is described in the previous section, and (2) interference among the waves scattered by these primary events. This interference essentially leads to the variation of the fluxes of the waves scattered in different directions. In experiments, we measure the flux as a function of the scattering direction and the relative placement of electrons or atoms in the sample are readily deduced from the collected data.

Strictly speaking, the term scattering should refer only to phenomenon (1) above, whereas the term diffraction refers to the combination of phenomena (1) and (2). However, this distinction is seldom followed and these two terms are often used interchangeably. In practice, the term diffraction is used only for crystalline samples or when the structure of the sample is sufficiently regular to exhibit sharp peaks in the scattering curve. When the scattering pattern is diffuse, and especially when the pattern of interest is mainly in the small-angle region, the term scattering is almost exclusively used although the phenomenon (2) inevitably presented.

In this section, we shall develop a formalism for treatment of phenomenon (2). A derivation different from most of literature is presented first. The classical derivation is also discussed for the sake of completeness.

Derivation based on formula \eqref{eq:amplitude}

Once we have the formula eq.\eqref{eq:amplitude} for an electron at any position $\vr$, we can compute the total amplitude of all scattering waves at scattering angle $2\theta$, scattered by $N$ electrons positioned at $\vr_n$ for $n=1,2,\dots,N$, reaching the detector simply by adding all amplitudes together:

\[A = \sum_{n=1}^N A_n = \sum_{n=1}^N A_0b_e e^{i[\omega t + g(2\theta) - \vq\cdot\vr_n]}\]

We can moving all terms that are independent of $n$ outside of the summation, leading to

\[A = A_0b_e e^{i[\omega t + g(2\theta)]}\sum_{n=1}^N e^{-i\vq\cdot\vr_n}\]

It follows that the flux of the scattering wave at angle $2\theta$ is

\[\begin{split} J_\Omega &= AA^* \\ &= \left[ A_0b_e e^{i[\omega t + g(2\theta)]}\sum_{n=1}^N e^{-i\vq\cdot\vr_n]} \right]\left[ A_0b_e e^{i[\omega t + g(2\theta)]}\sum_{n=1}^N e^{-i\vq\cdot\vr_n]} \right]^* \\ &= A_0^2b_e^2 \sum_{n=1}^N e^{-i\vq\cdot\vr_n} \sum_{n=1}^N e^{i\vq\cdot\vr_n} \end{split}\]

From the second line to the third line, the factors $e^{i[\omega t + g(2\theta)]}$ and $e^{-i[\omega t + g(2\theta)]}$ cancels out. Since these factors make no contribution to the flux, without losing any information, we can write the amplitude in a simpler form

\[\begin{equation} A(\vq) = A_0b_e\sum_{n=1}^N e^{-i\vq\cdot\vr_n} \end{equation}\label{eq:ANelectrons}\]

where $\vr_i$ is the position vector of the $i$-th electron. When the number of electrons is large and they distributed more or less continuously in the space, we can convert the above equation into an integral by defining a number density operator (field) of electrons:

\[n_e(\vr) = \sum_{n=1}^N \delta(\vr-\vr_n)\]

where $\delta(x)$ is a delta function. To see that $n_e(\vr)$ is actually a number density, we integrate it and find that the result is the number of electrons $N$ as expected:

\[\begin{split} \int d\vr\; n_e(\vr) &= \int d\vr\; \sum_{n=1}^N \delta(\vr-\vr_n) \\ &= \sum_{n=1}^N \int d\vr\;\delta(\vr-\vr_n) \\ &= \sum_{n=1}^N 1 \\ &= N \end{split}\]

where from the second line to the third line, we have used the definition of a delta function $\int dx\;\delta(x)=1$. The particular property of the delta function we will use here is

\[f(x_0) = \int dx\; f(x)\delta(x-x_0)\]

Using above equation, we can rewrite $e^{-i\vq\cdot\vr}$ as

\[e^{-i\vq\cdot\vr_n} = \int d\vr\; e^{-i\vq\cdot\vr} \delta(\vr-\vr_n)\]

Inserting this equation into eq.\eqref{eq:ANelectrons}, we have

\[\begin{split} A &= A_0b_e\sum_{n=1}^N \int d\vr\; e^{-i\vq\cdot\vr} \delta(\vr-\vr_n) \\ &= A_0b_e \int d\vr\; e^{-i\vq\cdot\vr} \sum_{n=1}^N \delta(\vr-\vr_n) \\ &= A_0b_e \int d\vr\; n_e(\vr) e^{-i\vq\cdot\vr} \end{split}\]

\[\begin{equation} A(\vq) = A_0b_e \int_V d\vr\; n_e(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:Aintegral}\]

where $V$ denotes that the integration to be performed over the scattering volume. This equation shows that the wave amplitude $A(\vq)$ is proportional to the 3D Fourier transform of the number density $n_e(\vr)$ of the electrons. The Fourier transform plays a central role in the interpretation of scattering and diffraction phenomena.

Classical derivation

The classical derivation of the total amplitude of the scattering waves at angle $2\theta$ reaching the detector considers the setup shown in Figure 5, where two electrons are placed at two positions O and P. The scattering waves emitted by electron $O$ and electron $P$ are both in the direction of the wave vector $\vk$. The angle between the wave vector of the incident beam $\vk_0$ and $\vk$ is $2\theta$.

Figure 5. Most general construction of the interference of two electrons.

From the discussion presented in the previous section, we know that the maximum magnitudes of both scattering waves arriving at the detector are identical. But their phase difference $\Delta\phi$ will depend on the path length difference $\delta$ between the two waves:

\[\Delta\phi = \phi_P - \phi_O = \frac{2\pi}{\lambda}\delta\]

From Figure 5, we find the path length difference is

\[\delta = QP - OR\]

Note that in the above equation we write the length $QP$ first because in the definition of $\Delta\phi$ we put P at first. To compute the length $QP$, we designate a vector pointing from O to P as $\vr$ which is the difference of the position vectors of position O and P: $\vr = \vr_P - \vr_O$. Then we have $QP = \vS_0\cdot\vr$ and $OR=\vS\cdot\vr$. Therefore, the phase difference can be expressed in terms of $\vS, \vS_0$ and $\vr$ as

\[\begin{split} \Delta\phi &= \frac{2\pi}{\lambda}(\vS_0\cdot\vr - \vS\cdot\vr) \\ &= -(\frac{2\pi}{\lambda}\vS - \frac{2\pi}{\lambda}\vS_0)\cdot\vr \\ &= -\vq\cdot\vr \end{split}\]

where the scattering vector $\vq$ is naturally obtained. Assume that the amplitude of the spherical wave $A_O(x,t)$ scattered at point O is

\[\begin{equation} A_O(x,t) = A_0b_e e^{i(\omega t - 2\pi x/\lambda)} \end{equation}\label{eq:AO}\]

where $x$ is understood as the path travelled along the direction $\vS$. Because of the phase difference, the amplitude of the spherical wave $A_P(x,t)$ scattered at point P is then

\[\begin{split} A_P(x,t) &= A_O(x,t)e^{i\Delta\phi} \\ &= A_0b_e e^{i(\omega t - 2\pi x/\lambda)}e^{i\Delta\phi} \end{split}\]

The combined wave $A(x,t)$ that reaches the detector is the sum of $A_O(x,t)$ and $A_P(x,t)$:

\[\begin{split} A(x,t) &= A_O(x,t) + A_P(x,t) \\ &= A_0b_e e^{i(\omega t - 2\pi x/\lambda)}(1 + e^{-i\vq\cdot\vr}) \end{split}\]

Then the flux is evaluated as

\[\begin{split} J_\Omega(\vq) &= A(x,t)A_P^*(x,t) \\ &= A_0^2b_e^2 (1 + e^{i\vq\cdot\vr})(1 + e^{-i\vq\cdot\vr}) \end{split}\]

where the phase factors $e^{i(\omega t - 2\pi x/\lambda)}$ and $e^{-i(\omega t - 2\pi x/\lambda)}$ cancels out. It is thus suffice to write the amplitude of the scattering wave as

\[\begin{equation} A(\vq) = A_0b_e(1 + e^{-i\vq\cdot\vr}) \end{equation}\label{eq:Aclassical}\]

When there are $N$ electrons, eq.\eqref{eq:Aclassical} can easily be generalized to

\[A(\vq) = A_0b_e \sum_{n=1}^N e^{-i\vq\cdot\vr_n}\]

which is exactly the same as eq.\eqref{eq:ANelectrons}. In the above equation, $\vr_n$ denotes the position of electron $n$ relative to an arbitrary origin. When eq.\eqref{eq:Aclassical} was derived, the origin was placed at one of the electrons, but that was not necessary. What really matters is only the relative difference in the path length between the rays scattered at different electrons. Any effect of the change in the origin would have simply canceled out when the flux was evaluated by taking the absolute square of the amplitude.

It can be seen that the classical derivation is not as clear as our single electron scattering based derivation. For example, the amplitude expressions presented in eq.\eqref{eq:AO} and related are implicitly assumed without any proof. By comparing to eq.\eqref{eq:amplitude}, we know that $x$ in eq.\eqref{eq:AO} has a much deeper meaning than it seems.

In the previous derivation, it is assumed that the incident beam and the vector $\vr$ forms an arbitrary angle $\alpha$, shown in Figure 5. In the derivation of the Bragg’s law in the crystallographic community, a specific $\alpha=\pi/2 + \theta$ is assumed as shown in Figure 6, which simplifies the calculation of the path difference. It should be bared in mind, however, that such setup is not general. Another popular setup to develop the scattering theory is shown in Figure 7, where $\alpha$ is chosen to be $\pi/2$ which is another special case of the setup shown in Figure 5.

Figure 6. Specialized construction of the interference of two electrons with $\alpha=\pi/2$.

Figure 7. Specialized construction of the interference of two electrons with $\alpha=\pi/2+\theta$.

Scattering by Atoms

The amplitude of x-ray scattering from an atom can be directly obtained by viewing the atom as a cluster of electrons and using eq.\eqref{eq:ANelectrons} or eq.\eqref{eq:Aintegral}. Note that the x-ray scattering from the atomic nucleus can be ignored as discussed in the previous section.

Atomic form factor

The atomic form factor is defined as the amplitude of x-ray scattering from an atom measured in the unit of $A_0b_e$:

\[\begin{equation} f(\vq) = \frac{A(\vq)}{A_0b_e} = \int d\vr\; n_e(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:atom}\]

where $n_e(\vr)$ is the time-averaged electron density distribution of the atom, and $\vr$ is defined by putting the origin of the reference coordinate system on the center of the atom. For a free atom, $n_e(\vr)$ bares spherical symmetry. Consequently, the atomic form factor only depends on the magnitude of the scattering vector. By expressing eq.\eqref{eq:atom} in a spherical coordinate system and performing integration over inclination and azimuth, we find

\[\begin{split} f(q) &= \int_0^{2\pi}d\phi\int_0^{\pi}d\theta\;\sin\theta \int_0^{\infty}dr\; n_e(r)r^2 e^{-iqr\cos\theta} \\ &= 2\pi\int_0^{\infty}dr\; n_e(r)r^2 \int_0^{\pi}d\theta\;\sin\theta e^{-iqr\cos\theta} \\ &= 2\pi\int_0^{\infty}dr\; n_e(r)r^2 \int_0^{\pi}d(-\cos\theta)\; e^{-iqr\cos\theta} \\ &= 2\pi\int_0^{\infty}dr\; n_e(r)r^2 \left[ \frac{e^{-iqr\cos\theta}}{iqr} \right]_0^{\pi} \\ &= 2\pi\int_0^{\infty}dr\; n_e(r)r^2\frac{e^{iqr}-e^{-iqr}}{iqr} \\ &= 2\pi\int_0^{\infty}dr\; n_e(r)r^2\frac{2i\sin(qr)}{iqr} \\ &= 4\pi\int_0^{\infty}dr\; n_e(r)r^2\frac{\sin(qr)}{qr} \end{split}\]

\[\begin{equation} f(q) = 4\pi\int_0^{\infty}dr\; n_e(r)r^2\frac{\sin(qr)}{qr} \end{equation}\]

where we have chosen the polar axis of the spherical coordinate system to coincide with the direction of $\vq$, and the origin at the atom center.

Multiple atoms

For x-ray scattering by multiple atoms, it is convenient to regroup electrons according to atoms to which they belong to. As shown in Figure 8, the position vector $\vr_{jn}$ of any electron can be decomposed into two parts:

\[\vr_{jn} = \vr_j + \vr_n\]

where $\vr_j$ is the position vector of the center of $j$th atom ($j=1, 2, \dots, N_a$), and $\vr_n$ denotes the relative position of $jn$th electron ($n=1, 2, \dots, Z_j$) with respect to the center of $j$th atom.

Figure 8. X-ray scattering by multiple atoms.

With this setup, eq.\eqref{eq:ANelectrons} can be rewritten as

\[\begin{split} A(\vq) &= A_0b_e \sum_{j=1}^{N_a} \sum_{n=1}^{Z_j} e^{-i\vq\cdot\vr_{jn}} \\ &= A_0b_e \sum_{j=1}^{N_a} \sum_{n=1}^{Z_j} e^{-i\vq\cdot(\vr_j+\vr_n)} \\ &= A_0b_e \sum_{j=1}^{N_a} \left(\sum_{n=1}^{Z_j} e^{-i\vq\cdot\vr_n}\right) e^{-i\vq\cdot\vr_j} \end{split}\]

The quantity in the parentheses in the third line of above equation, when averaged over time, is in effect the same as the integral presented in eq.\eqref{eq:atom}. Therefore, we can write the above equation as

\[\begin{equation} A(\vq) = A_0b_e \sum_{j=1}^{N_a} f_j(\vq) e^{-i\vq\cdot\vr_j} \end{equation}\label{eq:atoms}\]

where $f_j(\vq)$ denotes the atomic form factor of $j$th atom. If the sample has only one type of atom, we can factor out the $f_j$ term because $f(\vq)=f_j(\vq)$ is independent of $j$:

\[\begin{equation} A(\vq) = A_0b_ef(\vq) \sum_{j=1}^{N_a} e^{-i\vq\cdot\vr_j} \end{equation}\label{eq:sameatoms}\]

Similar to the number density operator for electrons, we introduce a number density operator defined for the center of atoms:

\[n_a(\vr) = \sum_{j} \delta(\vr-\vr_j)\]

which enable us to write eq.\eqref{eq:sameatoms} in the form

\[\begin{equation} A(\vq) = A_0b_e f(\vq) \int_Vd\vr\; n_a(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:sameatomsintegral}\]

Now it is reasonable to define a scattering length of an atom:

\[\begin{equation} b_a = b_e f(\vq) \end{equation}\label{eq:ba}\]

which transforms eq.\eqref{eq:sameatomsintegral} to

\[\begin{equation} A(\vq) = A_0b_a \int_Vd\vr\; n_a(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:generalsameatoms}\]

Eq.\eqref{eq:generalsameatoms} has an exactly same form as eq.\eqref{eq:Aintegral} by the mapping $b_a \to b_e$ and $n_a(\vr) \to n_e(\vr)$. Note that $b_a$ is in general a function of $\vq$.

Furthermore, we can define a scattering length density distribution of an atom as

\[\begin{equation} \rho_a(\vr) = b_a n_a(\vr) \end{equation}\label{eq:rhoa}\]

which further reduce eq.\eqref{eq:generalsameatoms} to

\[\begin{equation} A(\vq) = A_0 \int_Vd\vr\; \rho_a(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:finalsameatoms}\]

If there are $M$ types of atoms, each has $N_{a\alpha}$ atoms with $\alpha=1, 2, \dots, M$. Each atom of type $\alpha$ has $Z_\alpha$ electrons. Thus the total number of electrons in the sample is

\[N = Z_\alpha \sum_{\alpha=1}^{M} N_{a\alpha}\]

Eq.\eqref{eq:atoms} is linear with respect to the index of atom $j$, which means that the amplitude of each type of atom can be simply added to obtain the total amplitude. Therefore, the most general form of the amplitude of x-ray scattering from a collection of atoms is

\[\begin{equation} A(\vq) = A_0b_e \sum_{\alpha=1}^{M} f_\alpha(\vq) \int_Vd\vr\; n_{a\alpha}(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:generalatoms}\]

where $n_{a\alpha}(\vr)$ is the number density distribution of the atom of type $\alpha$. With the definition of scattering length density distribution of the atom $\rho_{a\alpha}$ for the atom of type $\alpha$, we can write eq.\eqref{eq:generalatoms} in a more compact form:

\[\begin{equation} A(\vq) = A_0 \int_Vd\vr\; \rho(\vr) e^{-i\vq\cdot\vr} \end{equation}\label{eq:finalatoms}\]

with the scattering length distribution of the sample $\rho(\vr)$ defined by

\[\begin{split} \rho(\vr) &= \sum_{\alpha=1}^{M} \rho_{a\alpha}(\vr) \\ &= \sum_{\alpha=1}^{M} b_{a\alpha} n_{a\alpha}(\vr) \\ &= \sum_{\alpha=1}^{M} b_e f_\alpha(\vq) n_{a\alpha}(\vr) \end{split}\]

Clearly the scattering length distribution of the sample $\rho(\vr)$ is a sum of the products of the scattering length of an electron $b_e$, the atomic form factor $f_\alpha(\vq)$, and the number density of the atom $n_{a\alpha}(\vr)$, for each type of atom.

Generalization to Arbitrary Particles

The strategy described in the Multiple atoms section can be generalized to arbitrary particles consisting of any type of building blocks, such as electrons, atoms, molecules, complexes, polymers, nanoparticles, etc., as long as they can be viewed as basic building blocks of the sample. Such generalization will eventually lead to the concept of form factor, which we will pursue further in the next post.

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

References

Roe, R. J. Methods of X-Ray and Neutron Scattering in Polymer Science; Oxford University Press, 2000. ↩

Julia in Practice: Building Scattering.jl from Scratch (5) was originally published by Yi-Xin Liu at Polyorder on April 23, 2020.

Usage and Testing of rotation.jl

2020-04-19T00:00:00-00:00

Numerical experiments are carried out to demonstrate the usage as well as serving as a test for the rotation.jl submodule. This is an appendix to the previous post. The format of this post mimics the Jupyter notebook. The output of a code block after run is captured by Literate.jl and rendered here as a markdown code block in the format of the text language.

Some Experiments on Rotation Operations
Testing and Usage of Scattering/rotation.jl
Acknowledgements

First, we load some necessary packages

using Revise
using Scattering
using LinearAlgebra
using Test

Some Experiments on Rotation Operations

$\vu, \vv, \vw$ are the basis vectors of the UVW internal coordinate system with their components expressed in the reference XYZ coordinate system. Let $\vw$ point to the principle direction of a scatterer.

w = [1.0, 2.0, 3.0]
normalize!(w)
# pick a vector that is not parallel to w
a = [0, 1, 2]
# find u by cross product
u = cross(w, a)
normalize!(u)
# find v perpendicular to both w and u
v = cross(w, u)
normalize!(v)
w

3-element Array{Float64,1}:
2672612419124244
5345224838248488
8017837257372732

$\mP$ is the rotation matrix which rotates XYZ coordinate system (basis vectors) to UVW coordinate system: $[\vu\;\vv\;\vw] = [\ve_x\;\ve_y\;\ve_z]\mP$.

P = hcat(u, v, w)

3×3 Array{Float64,2}:
  0.408248   0.872872  0.267261
 -0.816497   0.218218  0.534522
  0.408248  -0.436436  0.801784

$\mR$ is the rotation matrix which rotates a vector in XYZ system to UVW coordinate system: $\mR = \mP^{-1} = \mP^T$ and $\mR\vu = [1\;0\;0]^T, \mR\vv = [0\;1\;0]^T, \mR\vw = [0\;0\;1]^T$

@test transpose(P) ≈ inv(P)
R = transpose(P)

3×3 LinearAlgebra.Transpose{Float64,Array{Float64,2}}:
408248  -0.816497   0.408248
872872   0.218218  -0.436436
267261   0.534522   0.801784

@test det(R) ≈ 1

Test Passed

Verify that $\mR$ indeed transforms basis vectors of the XYZ coordinate system to $\vu, \vv, \vw$, whose components are expressed in the XYZ coordinate system.

@test R * u ≈ [1, 0, 0]
@test R * v ≈ [0, 1, 0]
@test R * w ≈ [0, 0, 1]

Test Passed

tr(R)

1.4282499064371286

Compute the rotation angle:

θ = acos((tr(R)-1)/2)
rad2deg(θ)

77.63580469304388

Compute the rotation axis expressed in the XYZ system:

uu = [R[3,2]-R[2,3], R[1,3]-R[3,1], R[2,1]-R[1,2]] / (2sin(θ))

3-element Array{Float64,1}:
49700656431759865
07216735383016143
8647406247345901

Alternative way to compute the rotation axis. Note that the result may be different from the one computed above with only a sign.

vals, vecs = eigen(R)
idx = findfirst(x -> x ≈ one(x), vals)
uu2 = real(vecs[:, idx])
@test uu2 ≈ uu || uu2 ≈ -uu

Test Passed

Alternative way to compute the rotation angle

vv = [R[3,2]-R[2,3], R[1,3]-R[3,1], R[2,1]-R[1,2]]
@test asin(norm(vv)/2) ≈ θ

Test Passed

A proper rotation matrix should have $\det(\mR) = +1$

det(R)

1.0000000000000002

transpose(R)

3×3 Array{Float64,2}:
  0.408248   0.872872  0.267261
 -0.816497   0.218218  0.534522
  0.408248  -0.436436  0.801784

inv(R)

3×3 LinearAlgebra.Transpose{Float64,Array{Float64,2}}:
  0.408248   0.872872  0.267261
 -0.816497   0.218218  0.534522
  0.408248  -0.436436  0.801784

A proper rotation matrix should be an orthogonal matrix

@test transpose(R) ≈ inv(R)

Test Passed

Convert current rotation matrix representation to Euler angles representation. Convention used: Z1Y2Z3

Procedure:

Rotate about +z by eta (counter-clockwise in x-y plane),
Rotate about the former y-axis (which is y’), counter clockwise in x’-z plane. Then,
Rotate about the former z-axis (which is z’), counter-clockwise in x’-y’ plane.

See wiki page:

https://en.wikipedia.org/wiki/Rotation_matrix
https://en.wikipedia.org/wiki/Euler_angles#Intrinsic_rotations

α = atan(R[2,3], R[1,3])
β = acos(R[3,3])
γ = atan(R[3,2], -R[3,1])
rad2deg.([α, β, γ])
c1 = cos(α)
c2 = cos(β)
c3 = cos(γ)
s1 = sin(α)
s2 = sin(β)
s3 = sin(γ)

Ra = zero(R)
Ra[1, 1] = c1*c2*c3 - s1*s3
Ra[1, 2] = -c3*s1 - c1*c2*s3
Ra[1, 3] = c1 * s2
Ra[2, 1] = c1*s3 + c2*c3*s1
Ra[2, 2] = c1*c3 - c2*s1*s3
Ra[2, 3] = s1*s2
Ra[3, 1] = -c3*s2
Ra[3, 2] = s2*s3
Ra[3, 3] = c2
@test Ra ≈ R

Test Passed

rad2deg.([α, β, γ])

3-element Array{Float64,1}:
 -46.91127686463718
  36.69922520048988
 116.56505117707799

Convention: Z1X2Z3

α = atan(R[1,3], -R[2,3])
β = acos(R[3,3])
γ = atan(R[3,1], R[3,2])
rad2deg.([α, β, γ])
c1 = cos(α)
c2 = cos(β)
c3 = cos(γ)
s1 = sin(α)
s2 = sin(β)
s3 = sin(γ)

Rb = zero(R)
Rb[1, 1] = c1*c3 - c2*s1*s3
Rb[1, 2] = -c1*s3 - c2*c3*s1
Rb[1, 3] = s1 * s2
Rb[2, 1] = c3*s1 + c1*c2*s3
Rb[2, 2] = c1*c2*c3 - s1*s3
Rb[2, 3] = -c1*s2
Rb[3, 1] = s2*s3
Rb[3, 2] = c3*s2
Rb[3, 3] = c2
@test Rb ≈ R

Test Passed

Convention Z1Y2X3

α = atan(R[2,1],R[1,1])
β = asin(-R[3,1])
γ = atan(R[3,2], R[3,3])
rad2deg.([α, β, γ])
c1 = cos(α)
c2 = cos(β)
c3 = cos(γ)
s1 = sin(α)
s2 = sin(β)
s3 = sin(γ)

Z1Y2X3 = zero(R)
Z1Y2X3[1, 1] = c1*c2
Z1Y2X3[1, 2] = c1*s2*s3 - c3*s1
Z1Y2X3[1, 3] = s1*s3 + c1*c3*s2
Z1Y2X3[2, 1] = c2*s1
Z1Y2X3[2, 2] = c1*c3 + s1*s2*s3
Z1Y2X3[2, 3] = c3*s1*s2 - c1*s3
Z1Y2X3[3, 1] = -s2
Z1Y2X3[3, 2] = c2*s3
Z1Y2X3[3, 3] = c2*c3
@test Z1Y2X3 ≈ R

Test Passed

Convention: Z1Y2Z3

Rp = hcat([-1, 0, 0], [0, 0, 1], [0, 1, 0])
α = atan(Rp[2,3], Rp[1,3])
β = acos(Rp[3,3])
γ = atan(Rp[3,2], -Rp[3,1])
rad2deg.([α, β, γ])

θp = acos((tr(Rp)-1)/2)
up =[Rp[3,2]-Rp[2,3], Rp[1,3]-Rp[3,1], Rp[2,1]-Rp[1,2]]
θpp = asin(norm(up)/2)

0.0

rad2deg(θp), rad2deg(θpp), up

(180.0, 0.0, [0, 0, 0])

Find rotation axis by diagonalization

vals, vecs = eigen(Rp)
idx = findfirst(x -> x ≈ one(x), vals)
uu = real(vecs[:, idx])

3-element Array{Float64,1}:
0
7071067811865475
7071067811865477

Testing and Usage of Scattering/rotation.jl

Testing EulerAngle constructors

using StaticArrays: SVector, FieldVector
α, β, γ = π/4, π/3, π/2

(0.7853981633974483, 1.0471975511965976, 1.5707963267948966)

Constructors of EulerAngle. Initialize by a vector

EulerAngle([α, β, γ])

Scattering.Rotation.EulerAngle{Float64}(0.7853981633974483, 1.0471975511965976, 1.5707963267948966)

EulerAngle(1.3, 0, 0)

Scattering.Rotation.EulerAngle{Float64}(1.3, 0.0, 0.0)

Initialize by three angles

euler = EulerAngle(α, β, γ)

Scattering.Rotation.EulerAngle{Float64}(0.7853981633974483, 1.0471975511965976, 1.5707963267948966)

Copy constructor

EulerAngle(euler)

Scattering.Rotation.EulerAngle{Float64}(0.7853981633974483, 1.0471975511965976, 1.5707963267948966)

Initialize by a static vector

sv = SVector(1.0, 2.0, 3.0)
EulerAngle(sv)

Scattering.Rotation.EulerAngle{Float64}(1.0, 2.0, 3.0)

Follow the Z1Y2Z3 convention

α = atan(v[3], u[3])
β = acos(w[3])
γ = atan(w[2], -w[1])
rad2deg.([α, β, γ])

3-element Array{Float64,1}:
 -46.91127686463718
  36.69922520048988
 116.56505117707799

Testing RotationMatrix constructors

Constructor of RotationMatrix initialized with a matrix

rotmat = RotationMatrix(Vector3D(u), Vector3D(v), Vector3D(w))
@test transpose(RotMatrix(hcat(u,v,w))) ≈ rotmat.R

Test Passed

Convert an EulerAngle instance to a RotationMatrix instance

rotmat_euler = RotationMatrix(EulerAngle(α, β, γ))
@test rotmat_euler.R ≈ rotmat.R

Test Passed

Convert a RotationMatrix instance to an EulerAngle instance

euler = EulerAngle(rotmat_euler)
@test [euler.α, euler.β, euler.γ] ≈ [α, β, γ]

Test Passed

Testing EulerAxisAngle Constructors

Constructor of AxisAngleRepresentation initialized with a RotationMatrix instance: conversion from rotation matrix representation to axis-angle representation

axisangle = EulerAxisAngle(rotmat)

Scattering.Rotation.EulerAxisAngle{Float64}([0.49700656431759865, 0.07216735383016143, 0.8647406247345901], 1.3550004093288814, [0.0 -0.8647406247345901 0.07216735383016143; 0.8647406247345901 0.0 -0.49700656431759865; -0.07216735383016143 0.49700656431759865 0.0])

Convert Euler axis-angle representation to rotation matrix representation

rotmat_axisangle = RotationMatrix(axisangle)
@test rotmat_axisangle.R ≈ rotmat.R atol=1e-15

Test Passed

axisangle2 = EulerAxisAngle(axisangle.ω, axisangle.θ)
@test axisangle2.K ≈ axisangle.K

Test Passed

Testing conversion and promotion

euler

Scattering.Rotation.EulerAngle{Float64}(-0.8187562376025611, 0.6405223126794245, 2.0344439357957027)

axisangle

Scattering.Rotation.EulerAxisAngle{Float64}([0.49700656431759865, 0.07216735383016143, 0.8647406247345901], 1.3550004093288814, [0.0 -0.8647406247345901 0.07216735383016143; 0.8647406247345901 0.0 -0.49700656431759865; -0.07216735383016143 0.49700656431759865 0.0])

EulerAxisAngle(euler)

Scattering.Rotation.EulerAxisAngle{Float64}([0.4970065643175987, 0.07216735383016142, 0.86474062473459], 1.3550004093288814, [0.0 -0.86474062473459 0.07216735383016142; 0.86474062473459 0.0 -0.4970065643175987; -0.07216735383016142 0.4970065643175987 0.0])

RotationMatrix(euler) |> EulerAxisAngle

Scattering.Rotation.EulerAxisAngle{Float64}([0.4970065643175987, 0.07216735383016142, 0.86474062473459], 1.3550004093288814, [0.0 -0.86474062473459 0.07216735383016142; 0.86474062473459 0.0 -0.4970065643175987; -0.07216735383016142 0.4970065643175987 0.0])

EulerAngle(axisangle)

Scattering.Rotation.EulerAngle{Float64}(-0.8187562376025609, 0.6405223126794247, 2.0344439357957027)

convert(EulerAngle, axisangle)

Scattering.Rotation.EulerAngle{Float64}(-0.8187562376025609, 0.6405223126794247, 2.0344439357957027)

convert(EulerAngle, euler)

Scattering.Rotation.EulerAngle{Float64}(-0.8187562376025611, 0.6405223126794245, 2.0344439357957027)

Testing promotion, comparison, and unit rotation

@test euler == axisangle

Test Passed

@test euler == euler

Test Passed

@test promote(euler) == rotmat

Test Passed

@test promote(axisangle) == rotmat

Test Passed

one(rotmat)

Scattering.Rotation.RotationMatrix{Float64}([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0])

one(euler)

Scattering.Rotation.EulerAngle{Float64}(0.0, 0.0, 0.0)

promote(one(euler))

Scattering.Rotation.RotationMatrix{Float64}([1.0 -0.0 0.0; 0.0 1.0 0.0; -0.0 0.0 1.0])

one(axisangle)

Scattering.Rotation.EulerAxisAngle{Float64}([1.0, 0.0, 0.0], 0.0, [0.0 -0.0 0.0; 0.0 0.0 -1.0; -0.0 1.0 0.0])

promote(one(axisangle))

Scattering.Rotation.RotationMatrix{Float64}([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0])

Testing inv function

rot1 = rotmat

Scattering.Rotation.RotationMatrix{Float64}([0.408248290463863 -0.816496580927726 0.408248290463863; 0.8728715609439696 0.21821789023599242 -0.4364357804719848; 0.2672612419124244 0.5345224838248488 0.8017837257372732])

Test inv function for RotationMatrix

irot1 = inv(rot1)
@test transpose(rot1.R) ≈ irot1.R

Test Passed

rot2 = EulerAxisAngle(rot1)

Scattering.Rotation.EulerAxisAngle{Float64}([0.49700656431759865, 0.07216735383016143, 0.8647406247345901], 1.3550004093288814, [0.0 -0.8647406247345901 0.07216735383016143; 0.8647406247345901 0.0 -0.49700656431759865; -0.07216735383016143 0.49700656431759865 0.0])

Test inv function for EulerAxisAngle

irot2 = inv(rot2)
@test irot2 == irot1

Test Passed

rot3 = EulerAngle(rot1)

Scattering.Rotation.EulerAngle{Float64}(-0.818756237602561, 0.6405223126794245, 2.0344439357957027)

Test inv function for EulerAngle

irot3 = inv(rot3)
@test irot3 == irot1

Test Passed

Testing multiplication of two AbstractRotation instances

Test multiplication of two RotationMatrix instances.

R1 = rotmat
M = RotationMatrix(Rp)
R2 = R1 * M
@test R2.R ≈ R1.R*M.R

Test Passed

Test multiplication of a EulerAxisAngle instance and a RotationMatrix instance.

R1 = rotmat
R1a = EulerAxisAngle(R1)
M = RotationMatrix(Rp)
R2 = R1a * M
@test R2 == R1 * M

Test Passed

Test multiplication of a RotationMatrix instance and a EulerAxisAngle instance.

R1 = rotmat
M = RotationMatrix(Rp)
Ma = EulerAxisAngle(M)
R2 = R1 * Ma
@test R2 == R1 * M

Test Passed

Test multiplication of a EulerAxisAngle instance and a EulerAxisAngle instance.

R1 = rotmat
R1a = EulerAxisAngle(R1)
M = RotationMatrix(Rp)
Ma = EulerAxisAngle(M)
R2 = R1a * Ma
@test R2 == R1 * M

Test Passed

Testing computing power of a AbstractRotation instance

function pow1(rot::AbstractRotation, n::Integer)
    rot = promote(rot)
    result = rot
    for i in 1:(n-1)
        result *= rot
    end
    result
end

function pow(rot::RotationMatrix, n::Integer)
    if n == zero(n)
        return one(rot)
    elseif n == one(n)
        return rot
    else
        if isodd(n)
            return rot * pow(rot, n-1)
        else
            rothalf = pow(rot, n÷2)
            return rothalf * rothalf
        end
    end
end

pow(rot::AbstractRotation, n::Integer) = pow(promote(rot), n)

pow (generic function with 2 methods)

pow(euler, 0)

Scattering.Rotation.RotationMatrix{Float64}([1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0])

pow(euler, 1)

Scattering.Rotation.RotationMatrix{Float64}([0.40824829046386313 -0.8164965809277259 0.4082482904638629; 0.8728715609439694 0.21821789023599242 -0.4364357804719848; 0.26726124191242434 0.5345224838248487 0.8017837257372732])

pow(euler, 2)

Scattering.Rotation.RotationMatrix{Float64}([-0.4369210333151354 -0.2932896043722907 0.8503418245705543; 0.43018214432212887 -0.8983623348886722 -0.08881687880007882; 0.7899641342195538 0.32699590703939707 0.5186813505672173])

pow(euler, 3)

Scattering.Rotation.RotationMatrix{Float64}([-0.20711300761088602 0.7472703153125533 0.6314200487243415; -0.6322711178708509 -0.5947556020638506 0.4964866637886771; 0.7465503570320742 -0.29639981387703873 0.5956590591512387])

pow(euler, 4)

Scattering.Rotation.RotationMatrix{Float64}([0.7364715816744584 0.6696830270043788 0.09557328459445946; -0.644577211376976 0.651844177986726 0.3995239494677259; 0.2052555187063243 -0.35584239624735736 0.9117271308201462])

pow(euler, 5).R

3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9} with indices SOneTo(3)×SOneTo(3):
910754   -0.404104   0.0850187
412606    0.882094  -0.227304
0168598   0.242097   0.970106

pow(euler, 100).R

3×3 StaticArrays.SArray{Tuple{3,3},Float64,2,9} with indices SOneTo(3)×SOneTo(3):
 -0.443094   0.414668   0.794807
 -0.277188  -0.906518   0.318422
  0.852546  -0.0792197  0.516614

euler^1

Scattering.Rotation.RotationMatrix{Float64}([0.40824829046386313 -0.8164965809277259 0.4082482904638629; 0.8728715609439694 0.21821789023599242 -0.4364357804719848; 0.26726124191242434 0.5345224838248487 0.8017837257372732])

euler^2

Scattering.Rotation.RotationMatrix{Float64}([-0.4369210333151354 -0.2932896043722907 0.8503418245705543; 0.43018214432212887 -0.8983623348886722 -0.08881687880007882; 0.7899641342195538 0.32699590703939707 0.5186813505672173])

euler^3

Scattering.Rotation.RotationMatrix{Float64}([-0.20711300761088602 0.7472703153125533 0.6314200487243415; -0.6322711178708509 -0.5947556020638506 0.4964866637886771; 0.7465503570320742 -0.29639981387703873 0.5956590591512387])

euler^4

Scattering.Rotation.RotationMatrix{Float64}([0.7364715816744584 0.6696830270043788 0.09557328459445946; -0.644577211376976 0.651844177986726 0.3995239494677259; 0.2052555187063243 -0.35584239624735736 0.9117271308201462])

@test pow(euler, 100).R ≈ (euler^100).R

Test Passed

Benchmarks

using BenchmarkTools

@btime pow1($euler, 1000)

142.561 μs (3004 allocations: 172.31 KiB)
Scattering.Rotation.RotationMatrix{Float64}([-0.17617351956438138 0.7712758102440354 0.6116342988556001; -0.6592241548072412 -0.553880454852226 0.50856656934094; 0.7310173764848875 -0.31360814126062625 0.606022713280731])

The implementation of pow (or Scattering.^ which is the same as pow here) is significantly faster than the naive implementation.

@btime $euler^1000

2.327 μs (49 allocations: 3.02 KiB)
Scattering.Rotation.RotationMatrix{Float64}([-0.1761735195643819 0.7712758102440348 0.6116342988555798; -0.6592241548072477 -0.5538804548522176 0.5085665693409378; 0.7310173764848691 -0.3136081412606315 0.6060227132807026])

Testing applying AbstractRotation instance to a vector

Test multiplication of a RotationMatrix instance and a Vector

M = RotationMatrix(Rp)
v = [1.0, 2.0, 3.0]
@test M*v ≈ M.R * v

Test Passed

Test multiplication of a RotationMatrix instance and a RVector (SVector, QVector)

M = RotationMatrix(Rp)
r = RVector([1.0, 2.0, 3.0])
@test M*r ≈ M.R * r

Test Passed

Test multiplication of a EulerAxisAngle instance and a Vector

M = RotationMatrix(Rp)
Ma = EulerAxisAngle(M)
v = [1.0, 2.0, 3.0]
@test Ma*v ≈ M.R * v

Test Passed

Test multiplication of a EulerAxisAngle instance and a RVector (SVector, QVector)

M = RotationMatrix(Rp)
Ma = EulerAxisAngle(M)
v = RVector([1.0, 2.0, 3.0])
@test Ma*v ≈ M.R * v

Test Passed

Test multiplication of a EulerAngle instance and a Vector

M = RotationMatrix(Rp)
Ma = EulerAngle(M)
v = [1.0, 2.0, 3.0]
@test Ma*v ≈ M.R * v

Test Passed

Test multiplication of a EulerAngle instance and a RVector (SVector, QVector)

M = RotationMatrix(Rp)
Ma = EulerAngle(M)
v = RVector([1.0, 2.0, 3.0])
@test Ma*v ≈ M.R * v

Test Passed

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).
The captured output text blocks in this post is automatically generated by using Literate.jl.

Usage and Testing of rotation.jl was originally published by Yi-Xin Liu at Polyorder on April 19, 2020.

Julia in Practice: Building Scattering.jl from Scratch (4)

2020-04-19T00:00:00-00:00

In this post we implement submodules rotation.jl of Scattering.jl to rotate a vector in the reference coordinate system to the internal coordinate system of the scatterer. Three representations of a rotaion operation are discussed and implemented. The conversion among and math operations on these representations are also implemented.

Rotations
Implementation
Usage
Acknowledgements
References

Rotations

Rotations are another type of isometric transformation which preserve distances and angles. As stated in the previous post, we will adopt the convention of alias transformation. Therefore, a rotation operation is applied to the coordinates. It will rotate the reference coordinates to the internal coordinates of a scatterer. It thus natural to choose a rotation to represent the orientation of a scatterer, as shown in Figure 1. In the following, we will briefly review three popular represenations of a rotation. For a more comprehensive introduction, especially in the context of crystallography, please consult these references¹². A series of Wiki pages about rotations in a general sense are also good sources to learn:

Figure 1. Illustration for rotation of the reference coordinate system to the internal coordinate system of a scatterer.

Rotation matrices

The transformation of a position vector $\vr = [x\;y\;z]^T = [x_1\;x_2\;x_3]^T$ in the reference coordinate system $xyz$ to the internal coordinate system of a scatterer $x’y’z’$ can be written as a multiplication of the vector by a rotation matrix $\mR$. The resulted position vector $\vr’=[x’\;y’\;z’]^T$ with its coordinates expressed in the $x’y’z’$ system is then given by

\[\vr' = \mR\vr\]

To determine the rotation matrix which has 9 components in 3D space, we have to identify at least 9 equations. It is most convenient to examine the transformation of three basis vectors of the $x’y’z’$ system, $\vu=[u_x\;u_y\;u_z]^T, \vv=[v_x\;v_y\;v_z]^T, \vw=[w_x\;w_y\;w_z]^T$ with their coordinates expressed in the $xyz$ system. When the coordinates of these basis vectors are expressed in the $x’y’z’$ system, they are just three unit vectors $[1\;0\;0]^T, [0\;1\;0]^T, [0\;0\;1]^T$. Thus we have

\[\begin{equation} \begin{split} \mR\vu &= [1\;0\;0]^T \\ \mR\vv &= [0\;1\;0]^T \\ \mR\vw &= [0\;0\;1]^T \end{split} \end{equation}\]

It is possible to rewrite above equation in a more compact form as

\[\begin{equation} \begin{split} \mR[\vu\;\vv\;\vw] &= \begin{bmatrix} 1& 0& 0 \\ 0& 1& 0 \\ 0& 0& 1 \end{bmatrix} \\ &= \mI \end{split} \end{equation}\]

The term in the right hand side of the above equation is just an identity matrix $\mI$. In convention, we will write the matrix $[\vu\;\vv\;\vw]$ as $\mP$. Obviously, $\mP$ is an orthonormal matrix because its three column vectors are just three basis vectors of a coordinate system which are unit vectors and orthogonal to each other. As long as we know all the components of the three basis vectors of the internal coordinate system in the reference coordinate system, we can easily construct $mP$ and the rotation matrix can be obtained by inverse the above equation:

\[\mR = \mP^{-1}\]

This equation can be futher simplified using a property of an orthornormal matrix:

\[\begin{equation} \begin{split} \mP^T\mP &= \begin{bmatrix} \vu^T \\ \vv^T \\ \vw^T \end{bmatrix} [\vu\;\vv\;\vw] \\ &= \mI \end{split} \end{equation}\]

which means

\[\mP^{-1} = \mP^T\]

Therefore, the rotation matrix is just the transposition of $\mP$:

\[\begin{equation} \mR = \mP^T = \begin{bmatrix} u_x& u_y& u_z \\ v_x& v_y& v_z \\ w_x& w_y& w_z \end{bmatrix} \end{equation}\]

It is now clear that $\mP$ is also a rotation matrix which transforms a vector in the internal coordinate system to the reference coordinate system. All rotation matrices should have following properties:

$\mR^{-1} = \mR^T$
$\det(\mR) = \pm 1$ since $1=\det(I)=\det(\mR^T\mR)=\det(\mR^T)\det(\mR)=\det(\mR)^2$

For the coordinate system transformation described above, the determinat should be the volume of the parallelopiped which is $+1$. such $\mR$ is called a proper rotation. Given a matrix, to determine whether it is a proper rotation matrix, we should first compute its determinant to see if it is $+1$. If so, we then compute its inverse, and check if it is identical to its transposition. If both crierions are met, then the matrix represents a proper rotation in the Cartesian coordinate system. However, it is not necessary true for other non-Cartesian coordinate systems.

Euler axis angle

The rotation matrix is convenient for numerical computations, however it is not an intuitive way to represent a rotation. The most popular way to describe a rotation is by Euler axis angle or polar angles: there exists a rotation axis given by a unit vector $\vomega$, about which the object rotates by angle $\theta$ according to the Euler’s rotation theorem.

Rotation axis

By definition, a vector $\vr$ parallel to the rotation axis is invariant under rotation:

\[\mR\vr = \vr\]

\[\begin{equation} (\mR - \mI)\vr = 0 \end{equation}\label{eq:rotaxis0}\]

Obviously, the vector $\vr$ is an eigenvector of $\mR$ corresponding to the eigenvalue $\lambda=+1$. To obtain $\vr$, we can simply diagonalize $\mR$ and find the eigenvector corresponding to the eigenvalue of $+1$. For non-symmetric $\mR$, however, there is a simpler way to determine $\vr$. We can show that

\[\begin{equation} \begin{split} (\mR - \mR^T)\vr &= [(\mI - \mR^T) + (\mR - \mI)]\vr \\ &= (\mI - \mR^T)\vr + (\mR - \mI)\vr \\ &= (\mR^T\mR - \mR^T)\vr + (\mR - \mI)\vr \\ &= \mR^T(\mR - \mI)\vr + (\mR - \mI)\vr \\ &= \mR^T 0 + 0 \\ &= 0 \end{split} \end{equation}\label{eq:skewsym}\]

From the second to the third line, we have invoked the property of a rotation matrix $\mR^T\mR = \mI$, while from the fourth to the fifth line eq.\eqref{eq:rotaxis0} is applied. It is also easy to show that $\mR - \mR^T$ is a skew-symmetric matrix because

\[(\mR - \mR^T)^T = \mR^T - \mR = -(\mR - \mR^T)\]

A skew-symmetric matrix can be used to represent cross products as matrix multiplications. Consider vectors $\va = [a_1\;a_2\;a_3]^T$ and $\vb = [b_1\;b_2\;b_3]^T$. Then, defining a skew-symmetric matrix with its components from $\va$

\[\begin{equation} [\va]_{\times} = \begin{bmatrix} 0& -a_3& a_2 \\ a_3& 0& -a_1 \\ -a_2& a_1& 0 \end{bmatrix} \end{equation}\label{eq:crossproduct}\]

the cross product can be written as

\[\va \times \vb = [\va]_{\times}\vb.\]

Since the cross product of any vector with itself is equal to 0, eq.\eqref{eq:skewsym} implies that $\mR - \mR^T$ is actually the cross product matrix of vector $\vr$,

\[\mR - \mR^T = [\vr]_{\times}.\]

By writing out $\mR - \mR^T$ explicitly as

\[\begin{equation} \mR - \mR^T = \begin{bmatrix} 0& u_y-v_x& u_z-w_x \\ v_x-u_y& 0& v_z-w_y \\ w_x-u_z& w_y-v_z& 0 \end{bmatrix} \end{equation}\label{eq:RRT}\]

Comparing eq.\eqref{eq:RRT} with eq.\eqref{eq:crossproduct}, we immediately arrives at

\[\begin{equation} \vr = \begin{bmatrix} r_x \\ r_y \\ r_z \end{bmatrix} = \begin{bmatrix} w_y-v_z \\ u_z-w_x \\ v_x-u_y \end{bmatrix} = \begin{bmatrix} R_{32}-R_{23} \\ R_{13}-R_{31} \\ R_{21}-R_{12} \end{bmatrix} \end{equation}\label{eq:vomega}\]

The last term is useful when we denote the rotation matrix as $\mR = [R_{ij}]$ where $i={1,2,3},j={1,2,3}$ are row and column indices, respectively. Finally, the unit vector parallel to the rotation axis is

\[\begin{equation} \vomega = \frac{\vr}{\norm{\vr}} \end{equation}\label{eq:vomega-norm}\]

Note that $\vomega$ computed by eq.\eqref{eq:vomega} becomes a zero vector when $\mR$ is symmetric. Therefore, this approach is inapplicable to symmetric matrices.

Rotation angle

Once the rotation axis is known, the angle of rotation $\theta$ is the angle between two vectors $\va$ and $\mR\va$, where $\va$ can be any vector that is perpendicular to $\vomega$.

However, a more straightforward way to find $\theta$ is to compute the trace of the rotation matrix and invoke the relation²

\[\begin{equation} \Tr(\mR) = 1 + 2\cos\theta \end{equation}\label{eq:trR}\]

It follows that the angle of rotation can be computed via

\[\begin{equation} \theta = \arccos\left[ \frac{\Tr(\mR)-1}{2} \right] \end{equation}\label{eq:theta}\]

where we should restrict the range of $\theta$ to $[0, \pi]$.

Conversion to the rotation matrix

Given by an Euler axis angle representation with known $\vomega=[\omega_x\;\omega_y\;\omega_z]^T$ and $\theta$, we can construct the corresponding rotation matrix directly:

\[\begin{equation} \mR = \begin{bmatrix} \cos\theta + \omega_x^2(1-\cos\theta)& \omega_x\omega_y(1-\cos\theta)-\omega_z\sin\theta& \omega_x\omega_z(1-\cos\theta)+\omega_y\sin\theta \\ \omega_y\omega_x(1-\cos\theta)+\omega_z\sin\theta& \cos\theta + \omega_y^2(1-\cos\theta)& \omega_y\omega_z(1-\cos\theta)-\omega_x\sin\theta \\ \omega_z\omega_x(1-\cos\theta)-\omega_y\sin\theta& \omega_z\omega_y(1-\cos\theta)+\omega_x\sin\theta& \cos\theta + \omega_z^2(1-\cos\theta) \end{bmatrix} \end{equation}\label{eq:aa2rm}\]

See ref² for how to derive above equation. Alternatively, we can utilize the cross product matrix of $\vomega$ by comparing to eq.\eqref{eq:crossproduct}:

\[\begin{equation} \mK = \begin{bmatrix} 0& -\omega_z& \omega_y \\ \omega_z& 0& -\omega_x \\ -\omega_y& \omega_x& 0 \end{bmatrix} \end{equation}\label{eq:Kmat}\]

The rotation matrix is then obtained as

\[\begin{equation} \mR = \mI + \mK\sin\theta + (1-\cos\theta)\mK^2 \end{equation}\label{eq:K2rm}\]

The above equation can be derived in a Lie-algebraic way or a geometric way using the Rodrigues’ rotation formula.

Euler angles

Another popular description of a rotation is using Euler angles. It is demonstrated by Leonhard Euler that it is sufficient to rotate a reference coordinate system by three angles around three axes of a coordinate system to reach any target frame. The rotation around an axis of a coordinate system is called an elemental/basic rotation. Albeit its popularity, the Euler angles representation of a rotation causes many confusions and it has a serious artifact known as the Gimbal lock. There exist twelve possible sequences of rotation axes, leading to twelve conventions. Different fields usually choose a particular convention. In this project, we will choose the Z1Y2Z3 convention according to the Wiki page Euler angles.

Convert Euler angles to the rotation matrix

Euler angles are denoted as $\alpha, \beta, \gamma$. The rotation matrix conforming to the Z1Y2Z3 convention has the form

\[\begin{equation} \mR = \begin{bmatrix} \cos\alpha\cos\beta\cos\gamma-\sin\alpha\sin\gamma& -\cos\gamma\sin\alpha-\cos\alpha\cos\beta\sin\gamma& \cos\alpha\sin\beta \\ \cos\alpha\sin\gamma+\cos\beta\cos\gamma\sin\alpha& \cos\alpha\cos\gamma-\cos\beta\sin\alpha\sin\gamma& \sin\alpha\sin\beta \\ -\cos\gamma\sin\beta& \sin\beta\sin\gamma& \cos\beta \end{bmatrix} \end{equation}\label{eq:euler2mat}\]

Convert the rotation matrix to Euler angles

From eq.\eqref{eq:euler2mat}, we have

\[\begin{split} \frac{R_{23}}{R_{13}} &= \tan\alpha \\ R_{33} &= \cos\beta \\ \frac{R_{32}}{-R_{31}} &= \tan\gamma \end{split}\]

Then Euler angles can be obtained acoordingly

\[\begin{equation} \begin{split} \alpha &= \arctan(R_{23}, R_{13}) \\ \beta &= \arccos(R_{33}) \\ \gamma &= \arctan(R_{32}, -R_{31}) \end{split} \end{equation}\label{eq:mat2euler}\]

where $\arctan(a, b)$ is a specialized version of the arctan function which takes into account the quadrant that the point $(b, a)$ is in. Note that eq.\eqref{eq:mat2euler} is valid for $\theta$ in the range $(0, \pi]$. When $\beta=0$ or $R_{33}=1$, $\alpha$ and $\gamma$ has infinite many solutions which satisfy

\[\tan(\alpha+\gamma) = \frac{R_{21}}{R_{11}}\]

\[\alpha + \gamma = \arctan(R_{21}, R_{11})\]

In this project, we fix $\gamma=0$ when $\beta=0$.

Implementation

It is now straightforward to implement a submodule rotation.jl of Scattering.jl which realize rotations and their associated operations.

Rotation types

First, we define an abstract type to describe any rotation operators:

1
abstract type AbstractRotation end

Inheriting from it, we define a concrete type for rotation matrices:

1
2
3
struct RotationMatrix{T<:Real} <: AbstractRotation
    R::RotMatrix{T} # 3x3 matrix
end

To ensure the user supplied matrix is actually a rotation matrix, we add an internal constructor to it

1
2
3
4
5
6
7
function RotationMatrix(R::RotMatrix{T}) where {T<:Real}
    # Verify that P is a valid rotation matrix
    detR = det(R)
    @assert(detR ≈ one(detR), "Not a valid rotation matrix: det=$detR.")
    @assert(transpose(R) ≈ inv(R), "Not a valid rotation matrix: RT != R^-1.")
    new{T}(R)
end

It is convenient to define a outer constructer which takes three arguments. They are unit basis vectors of the internal coordinate system of a scatterer $\vu, \vv, \vw$ whose components are expressed in the reference coordinate system.

1
RotationMatrix(u::Vector3D{T}, v::Vector3D{T}, w::Vector3D{T}) where {T <: Real} = RotationMatrix(transpose(RotMatrix(hcat(u,v,w))))

Note that we first construct $\mP$ using hcat function. Then we transpose it to obtain $\mR$ using transpose function.

Similarly, we define a concrete type for Euler axis angle:

1
2
3
4
5
struct EulerAxisAngle{T<:Real} <: AbstractRotation
    ω::RVector{T} # rotation axis
    θ::T # in radian unit
    K::SMatrix{3,3,T} # the cross product matrix such that Kv = ω×v for any vector v.
end

Note that the cross product matrix $\mK$ is also stored. We also need an internal constructor which ensures the rotation axis vector is a unit vector

1
2
3
4
5
function EulerAxisAngle(ω::RVector{T}, θ::T) where {T<:Real}
    ω /= norm(ω) # make sure ω is normalized
    K = hcat([0, ω[3], -ω[2]], [-ω[3], 0, ω[1]], [ω[2], -ω[1], 0])
    new{T}(ω, θ, K)
end

Finally, we define a concrete type for Euler angles:

1
2
3
4
5
struct EulerAngle{T<:Real} <: AbstractRotation
    α::T # in radian unit
    β::T # in radian unit
    γ::T # in radian unit
end

And an internal constructor is also necessary to ensure all three angles are in the same type:

1
2
3
function EulerAngle(α::T=0, β::T=0, γ::T=0) where {T<:Real}
    new{T}(α, β, γ)
end

Conversions

Conversions are implemented as outer constructors for each type. Converting Euler axis angle to a rotation matrix:

1
2
3
4
5
6
function RotationMatrix(axisangle::EulerAxisAngle)
    θ = axisangle.θ
    K = axisangle.K
    R = one(K) + sin(θ)*K + (1-cos(θ))*K*K
    RotationMatrix(R)
end

where eq.\eqref{eq:K2rm} is used. Converting Euler angles to a rotation matrix:

1
2
3
4
5
6
7
8
9
10
11
12
13
function RotationMatrix(euler::EulerAngle)
    c1 = cos(euler.α)
    c2 = cos(euler.β)
    c3 = cos(euler.γ)
    s1 = sin(euler.α)
    s2 = sin(euler.β)
    s3 = sin(euler.γ)
    v1 = [c1*c2*c3 - s1*s3 -c3*s1 - c1*c2*s3 c1*s2]
    v2 = [c1*s3 + c2*c3*s1 c1*c3 - c2*s1*s3 s1*s2]
    v3 = [-c3*s2 s2*s3 c2]
    R = RotMatrix(vcat(v1, v2, v3))
    RotationMatrix(R)
end

where eq.\eqref{eq:euler2mat} is used. Converting a rotation matrix to Euler axis angle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
function EulerAxisAngle(rotmatrix::RotationMatrix)
    R = rotmatrix.R
    θ = acos((tr(R)-1)/2)
    v = [R[3,2]-R[2,3], R[1,3]-R[3,1], R[2,1]-R[1,2]]
    if θ ≈ zero(θ)
        return EulerAxisAngle([1.0, 0.0, 0.0], 0.0)
    end
    if v ≈ zero(v)
        vals, vecs = eigen(R)
        idx = findfirst(x -> x ≈ one(x), vals)
        ω = real(vecs[:, idx])
    end
    EulerAxisAngle(ω, θ)
end

where eq.\eqref{eq:vomega} and eq.\eqref{eq:theta} are used. Converting a rotation matrix to Euler angles:

1
2
3
4
5
6
7
8
9
10
11
12
13
function EulerAngle(rotmatrix::RotationMatrix)
    R = rotmatrix.R
    if R[3,3] ≈ one(R[3,3])
        α = atan(R[2,1],R[1,1])
        β = zero(α)
        γ = zero(α)
    else
        α = atan(R[2,3], R[1,3])
        β = acos(R[3,3])
        γ = atan(R[3,2], -R[3,1])
    end
    EulerAngle(α, β, γ)
end

where eq.\eqref{eq:mat2euler} is used.

The conversions between Euler angles and Euler axis angle are implemented by converting them to rotation matrices first:

1
2
EulerAxisAngle(euler::EulerAngle) = RotationMatrix(euler) |> EulerAxisAngle
EulerAngle(axisangle::EulerAxisAngle) = RotationMatrix(axisangle) |> EulerAngle

Strictly follow our convention developed in this post, the conversions among these three representations are lostless. Thus it is reasonable to define a set of conversion rules following the Julia guidelines:

1
2
convert(::Type{T}, x::AbstractRotation) where {T<:AbstractRotation} = T(x)
convert(::Type{T}, x::T) where {T<:AbstractRotation} = x

The second line handles the situation when the object x is already of the target type.

Promotion

The rotation matrix is most convenient for numerical compuations. Therefore, its rank is considered higher than the other two representations. It means that we will convert any type of a rotation to the rotation matrix during computation. In Julia, it is realized by promotion rules. A promotion rule promote two or more types to a single common type. It will be used implicitly by Julia for methods promote_type and promote.

We define the following promotion rule:

1
promote_rule(::Type{T}, ::Type{S}) where {T<:AbstractRotation, S<:AbstractRotation} = RotationMatrix

which promotes two rotations of different types to the RotationMatrix type. However, when two rotations are of same type, Julia implicitly does nothing and this behavior can not be overridden at present. For example, if two rotations are of type EulerAngle, the return type will be EulerAngle instead of RotationMatrix. It is important to bare this in mind when implement == and * later.

It is also convenient to implement a promote method which takes a single argument and promotes all rotations to the RotationMatrix type. Note that one-argument promote is not supported by Julia Base.

1
2
promote(rot::RotationMatrix) = rot
promote(rot::AbstractRotation) = RotationMatrix(rot)

Inversion

The inversion of a rotation is computed via inverting the rotation matrix, then converting it back to the original type:

1
2
inv(rot::RotationMatrix) = collect(transpose(rot.R)) |> RotationMatrix
inv(rot::T) where {T<:AbstractRotation} = inv(promote(rot)) |> T.name.wrapper

In the above implementation, we utilized the relation $\mR^{-1} = \mR^T$.

Comparison

It is meaningful to check whether two rotations are identical. So we have extended the == operator defined in Julia Base:

1
2
3
4
==(rot1::RotationMatrix, rot2::RotationMatrix) = rot1.R ≈ rot2.R
==(rot1::EulerAngle, rot2::EulerAngle) = RotationMatrix(rot1) == RotationMatrix(rot2)
==(rot1::EulerAxisAngle, rot2::EulerAxisAngle) = RotationMatrix(rot1) == RotationMatrix(rot2)
==(rot1::AbstractRotation, rot2::AbstractRotation) = ==(promote(rot1,rot2)...)

Note how poromtion rules defined previously has been used.

Multiplication of two rotation operations

Since any rotation operation can be expressed as a matrix, it means that we can multiply them together to obtain another rotation. Mulitiplication of two rotations of any type is implemented by first promoting them to the RotationMatrix type:

1
2
3
4
*(rot1::RotationMatrix, rot2::RotationMatrix) = RotationMatrix(rot1.R * rot2.R)
*(rot1::EulerAngle, rot2::EulerAngle) = RotationMatrix(rot1) * RotationMatrix(rot2)
*(rot1::EulerAxisAngle, rot2::EulerAxisAngle) = RotationMatrix(rot1) * RotationMatrix(rot2)
*(rot1::AbstractRotation, rot2::AbstractRotation) = *(promote(rot1,rot2)...)

Note that the result of a multiplication is always of type RotationMatrix. As mentioned earlier, promotion of two rotations of an identical type returns this type other than RotationMatrix. Therefore, it is required to explicitly add the first three lines.

Power of a rotation operation

Raising a rotation to an integral power $n$ means multiplying a rotation for $n$ times. A naive implementation is

1
2
3
4
5
6
7
8
function pow1(rot::AbstractRotation, n::Integer)
    rot = promote(rot)
    result = rot
    for i in 1:(n-1)
        result *= rot
    end
    result
end

However, the complexity is only $O(N)$. The complexity can be optimized to $O(\log(N))$:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
function ^(rot::AbstractRotation, n::Integer)
    rot = promote(rot)
    if n == zero(n)
        return one(rot)
    elseif n == one(n)
        return rot
    else
        if isodd(n)
            return rot * rot^(n-1)
        else
            rothalf = rot^(n÷2)
            return rothalf * rothalf
        end
    end
end

where we have utilized a unit rotation which is simply a do-nothing rotation. It is implemented as follows:

1
2
one(rot::RotationMatrix{T}) where {T<:Real} = one(rot.R) |> RotationMatrix
one(rot::T) where {T<:AbstractRotation} = one(promote(rot)) |> T.name.wrapper

Using BechmarkTools, we can compare these two methods as

julia> using BenchmarkTools
julia> using Scattering
julia> # construct euler ...
julia> @btime pow1($euler, 1000)
142.561 μs (3004 allocations: 172.31 KiB)
julia> @btime $euler^1000
2.327 μs (49 allocations: 3.02 KiB)

We can see that the optimized version is nearly $70\times$ faster than the naive version when $n=1000$.

Transformation of a position vector

Transformation of a position vector with components expressed in the reference coordinate system to the internal coordinate system of a scatterer is implemented by applying a rotation operation on the vector:

1
*(rot::AbstractRotation, v::RVector{T}) where {T <: Real} = promote(rot).R * v

As can be seen, the actual computation is carried out by a matrix-vector product.

Usage

Due to the length of this blog post, the usage as well as the test of rotation.jl is presented in a separate blog post.

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

References

Wondratschek, H. Matrices, Mappings and Crystallographic Symmetry. In IUCr Commission on Crystallographic Teaching: Teaching pamphlets; 1997. ↩
Evans, P. R. Rotations and Rotation Matrices. Acta Cryst. D 2001, 57, 1355–1359. ↩ ↩² ↩³

Julia in Practice: Building Scattering.jl from Scratch (4) was originally published by Yi-Xin Liu at Polyorder on April 18, 2020.

Julia in Practice: Building Scattering.jl from Scratch (3)

2020-04-09T00:00:00-00:00

In this post we will implement a submodule translation.jl to perform transformation of a vector in the reference coordinate to the internal coordinate of a scatterer. Translation and coordinate transformation will be discussed in detail.

Translation and Coordinate Transformation
Implementation
- Conversion
- Math operations
Usage
Acknowledgements
References

Translation and Coordinate Transformation

The core functionality of Scattering.jl is to compute the form factor of an arbitrary scatter. It is convenient to model any scatter as a type which contains all the physical parameters necessary for the form factor computation. The most essential quantities are the position, shape (characteristic lengths for an object with known shape), and the orientation of the object if it is anisotropic. The shape depend on specific object we are actually looking at. Positions and orientations, however, are independent of the type of a scatterer. Therefore, it is possible to develop a general description for them.

A general way to describe the position of an object in space is using the position vector. And the orientation of an object can be conveniently described by a rotation operator. This blog post is devoted to the description of position. And the description of orientation will be deferred to the next post.

The description of positions and orientations strongly depends on which coordinate system they are in. Since all analytical expressions of form factors are assumed in the Cartesian coordinate, hereafter positions and orientations of scatterers are assumed to be expressed in the Cartesian coordinate system.

The most concise references to consult for these subjects are ref¹².

Points and Vectors

Although points and vectors can be both expressed in an array of numbers, called components, it is important to note the distinction between them. Points of a Euclidean space form a so-called affine space, and are themselves not vectors, because the “sum” of two points and the “multiplication” of a point by a scalar are not defined. Rather, an affine space has an auxiliary vector space “attached” to it, over which these operations are defined; “differences” between points are uniquely associated with vectors in this auxiliary space:

\[\begin{equation} \vv = p_2 - p_1 \end{equation}\label{eq:vector}\]

Once an origin point $o$ and a basis for the vector space are chosen, the coordinates of a point $p$ are the components of the difference vector $p − o$. This special difference vector is known as the position vector. If we let the origin of a Cartesian coordinate coincide with point $o$, then we can express $o$ as a column vector $[0\;0\;0]^T$ (here superscript $T$ denotes matrix transpose). $p$ then is $[p_x\;p_y\;p_z]^T$ expressed in the Cartesian coordinate. And the vector $\vv$ is expressed as $[p_x-0\;p_y-0\;p_z-0]^T = [p_x\;p_y\;p_z]^T$ as well. We say $p_x,\;p_y,\;p_z$ are components of the point $p$ or the vector $\vv$. Thus in this setup, $\vv$ and $p$ have an identical expression in the form of array of components.

One of the most important properties of a vector is that it is invariant under coordinate transformation which means its components are independent of which coordinate system they are in, while the components of a point are just labels in its associated coordinate system and they will change accordingly under coordinate transformation.

Alibi and alias translations

In this project, we are interested in isometric transformations which means distances and angles (thus the shape of an object to be transformed) is preserved after the transformation. For such isometric transformation, however, there are two possible (equivalent) interpretations: alibi (active) and alias (passive). An alibi transformation moves (or rotates) an object to another location while the underlying coordinate system is unchanged.

Figure 1 shows a typical alibi translation. The object at point $p$ with a position vector $\vr$ has been translated to point $p’$ with a position vector $\vr’$. The translation vector is thus

\[\begin{equation} \vt = p' - p \end{equation}\label{eq:alibi_translation_vector}\]

And the new position vector of the translated object is

\[\begin{equation} \vr' = \vr + \vt \end{equation}\label{eq:alibi_translation}\]

Figure 1. Illustration for an alibi translation. The reference coordinate is o.

Figure 2 shows a typical alias translation. The old coordinate with its origin at point $o$ (position vector $\vo=[0\;0\;0]^T$) is translated to the new coordinate with its origin at point $o’$ (position vector $\vo’$). It is important to note that the components of $\vo’$ should be expressed in the old coordinate in the following calculations.

Figure 2. Illustration for an alias translation from old coordinate o' to new coordinate o''. The reference coordinate is o.

The position of the object in the old coordinate is at point $p$, and it is at point $p’$ in the new coordinate. Note the components of $p$ and $p’$ are different in general. The object’s position vector in the old coordinates is

\[\begin{equation} \vr = p - o \end{equation}\]

and in the new coordinate is

\[\begin{equation} \begin{split} \vr' &= p - o' \\ &= p' - \begin{bmatrix} 0 \\ 0 \\ 0 \end{bmatrix} \\ &= p'. \end{split} \end{equation}\]

The first line is computed in the old coordinate and the second and third line is computed in the new coordinate, where have invoked the property of a vector that it is invariant under coordinate transformation. We can rewrite $\vr’$ as

\[\begin{equation} \begin{split} \vr' &= p - o' \\ &= p - o + o - o' \\ &= \vr - (o' - o). \end{split} \end{equation}\]

In the third line, we can then define a translation vector, $\vt$, for the coordinate transformation, which translates the old coordinate to the new coordinate:

\[\begin{equation} \vt = o' - o = \vo'. \end{equation}\label{eq:alias_translation_vector}\]

In the aid of the translation vector, we can now compute $\vr’$ as

\[\begin{equation} \vr' = \vr - \vt \end{equation}\label{eq:alias_translation}\]

The above formula, however, can be directly read off from Figure 2 using the geometric vector addition rule. Note that in the alias interpretation, the translation vector has an opposite direction to that of the alibi interpretation by comparing \eqref{eq:alibi_translation} and \eqref{eq:alias_translation}.

In the sense of coordinate transformation, we can define a translation operator, $T$, which transform a position vector $\vr$ in the old coordinate to a position vector $\vr’$ in the new coordinate:

\[\begin{equation} \vr' = T\vr = \vr - \vt \end{equation}\label{eq:translation_operator}\]

Application of a translation operator on a vector has the meaning that it transforms such vector from the old coordinate to the new coordinate.

Convention we used

In description of the position and orientation of a scatterer, we will adhere to the convention of alias or (passive) transformations. First we shall choose a reference Cartesian coordinate system with its origin at $o=[0\;0\;0]^T$. Then a scatterer with its origin locates at point $o’$ in the reference coordinate. The origin of a scatterer can be chosen as its center of mass or any other particular point that is characteristic to the scatterer. We will create a new Cartesian coordinate with its origin at $o’$. The resulted coordinate is called the internal coordinate system of this particular scatterer. The whole setup is illustrated in Figure 3. The scatterer in Figure 3 is an ellipse.

Figure 3. Illustration for transformation of a vector from reference coordinate to scatterer's internal coordinate.

Now any point in the body (and the boundary) of the scatterer can be described by two position vectors: a vector in the reference coordinate $\vr$ and a vector in the internal coordinate $\vr’$. We can then transform the position vector $\vr$ to the internal coordinate using the translation operator:

\[\begin{equation} \vr' = T\vr = \vr - \vr_0 \end{equation}\label{eq:translation}\]

or vice versa, we can transform the position vector in the internal coordinate $\vr’$ to the reference coordinate using an inverse translation operator:

\[\begin{equation} \vr = T^{-1}\vr' = \vr' + \vr_0 \end{equation}\label{eq:inverse_translation}\]

The inverse translation operator is denoted as $T^{-1}$. It is clear now the translation operator subtracts the translation vector from the vector it applies to, while the inverse translation operator does the opposite: it adds the translation vector to the vector it applies to. The translation vector will always mean that it transforms a vector from the reference coordinate to the internal coordinate of a scatterer. With these assumptions, we can informally express the translation operator explicitly:

\[\begin{equation} T = \vr_0 \end{equation}\label{eq:explicit_translation_operator}\]

and the inverse translation operator

\[\begin{equation} T^{-1} = -T = -\vr_0 \end{equation}\label{eq:inverse_translation_operator}\]

Following this formalism, we can rewrite eq.\eqref{eq:translation} and eq.\eqref{eq:inverse_translation} as

\[\begin{equation} \begin{split} \vr' &= T\vr = \vr - T \\ \vr &= T^{-1}\vr' = \vr' - T^{-1} \end{split} \end{equation}\label{eq:translation_rewritten}\]

It can be seen that in this formalism, we can treat translation and inverse translation consistently: applying a translation operator (either direct or inverse) to a vector results in a new vector which is the difference between the old vector and the operator itself.

Note that the translation vector here is denoted as $\vr_0 = o’ - o$ instead of $\vt$ because $\vr_0$ is commonly used to denote the position of an object in space, and it coincides with the translation vector in the present setup.

Figure 4. Illustration for transformation of a vector from old internal coordinate to new internal coordinate.

Sometimes, we will want to translate a scatterer from position $o’$ (described in the reference coordinate) to a new position $o’’$ (also described in the reference coordinate) as illustrated in Figure 4. Suppose we only know the translation operator of the old internal coordinate $T_1$ and the translation vector $\vt = o’’ - o’$ of between two internal coordinates. How can we express the new translation operator, $T_2$, for the translated scatterer locates at $o’’$ in terms of $T_1$ and $\vt$?

The translation operator for the old internal coordinate is

\[\begin{equation} T_1 = \vr_0' \end{equation}\]

From Figure 4 we see that the new position vector of the origin of the translated scatterer is

\[\begin{equation} \vr_0'' = \vr_0' + \vt = T_1 + \vt \end{equation}\]

Therefore the new translation operator is

\[\begin{equation} T_2 = \vr_0'' = T_1 + \vt \end{equation}\]

Or more simply, if we know the position vector or the point of the origin of the translated scatterer in the reference coordinate, $\vr_0’’ = o’’ - o = o’’$, we can write $T_2 = \vr_0’’$.

Implementation

With a clear understanding of the translation of a scatterer, we will now start to implement it in a submodule translation.jl for Scattering.jl. First it is convenient to define an abstract type to describe any translation operators which shall be useful for later extension:

1
abstract type AbstractTranslation end

Then we will define a concrete type for a translation operator:

1
2
3
struct Translation{T <: Real} <: AbstractTranslation
    t::Vector3D{T}
end

It only has one field which is a vector of three components. Vector3D is a constant defined as

1
2
using StaticArrays: SVector
const Vector3D{T} = SVector{3,T}

Here the sized array provided by the StaticArrays.jl package perfectly fits our use.

It is helpful to add a convenient constructor which accepts a Vector or three components separately

1
2
Translation(t::Vector{T}) where {T<:Real} = Vector3D(t) |> Translation
Translation(x::Real, y::Real, z::Real) = Translation([promote(x,y,z)...])

The promote method is provided by the Julia Base. It ensures the input x,y,z have same type which is required by the default constructor.

The chaining operator |> is extremely useful to increase the readability of the code. The output of the left operand of |> will be sent to the right operand as its input arguments. We can chain as many methods as possible together.

Conversion

A Translation instance is merely a three-component column vector. Thus it is sensible to convert any three-component column (or row) vector into a Translation instance. Julia provides a consistent way to deal with such situation. What we do is to provide additional convert method to the Julia Base:

1
2
import Base.convert
convert(::Type{T}, t::Vector3D) where {T<:AbstractTranslation} = Translation(t)

Note that it is necessary to import convert before addition. Otherwise, the new convert method will be invisible to users.

Math operations

As an operator, a Translation instance may support some math operations. The first one is applying it to a vector, which transform the vector into the coordinate system encoded in the Translation operator. Like matrix multiplication, we can use * to carry out the translation operation:

1
2
import Base.*
*(T::AbstractTranslation, v::Vector3D{S}) where {S<:Real} = v - T.t

It implements eq.\eqref{eq:translation_rewritten}.

There should be an unit operator for a translation operator such that it operates on a vector will return the vector itself. Thus the unit operator is actually a zero vector which we can implement it by extending Julia Base:

1
2
import Base.one
one(T::Translation{S}) where {S<:Real} = zero(T.t) |> Translation

Note that the translation operator has no zero operator. And as discussed earlier, the translation operator can be inversed as in eq.\eqref{eq:inverse_translation_operator}. It is also easy to implement:

1
2
import Base.inv
inv(T::S) where {S<:AbstractTranslation} = Translation(-T.t)

And we can also chain two translations together to produce a single equivalent translation since

\[\begin{equation} \begin{split} T_2T_1\vr &= T_2(\vr-T_1) \\ &= (\vr - T_1) - T_2 \\ &= \vr - (T_1 + T_2) \\ &= (T_1 + T_2)\vr \end{split} \end{equation}\label{eq:chain_translation}\]

Therefore, we have

\[\begin{equation} T_2T_1 = T_1 + T_2 \end{equation}\label{eq:chain_translation2}\]

This composition of translations shall be implemented as

1
*(T1::AbstractTranslation, T2::AbstractTranslation) = (T1.t + T2.t) |> Translation

Finally, it is convenient to extends Base.== to compare two translation operators whether they are identical:

1
==(T1::AbstractTranslation, T2::AbstractTranslation) = T1.t ≈ T2.t

The ≈ operator is an synonym for Base.isapprox method.

The implementation of the translation.jl module is done. And it is less than 20 lines of codes which is amazing!

Usage

Now we can perform translation operations using the Scattering.jl package in the Julia REPL as follows

julia> using Scattering
julia> using Test
julia> t = Vector3D(1.0, 2, 3);
julia> T1 = Translation(t) # create a translation operator from a vector
Translation{Float64}([1.0, 2.0, 3.0])
julia> inv(T1) # inversing an operator
Translation{Float64}([-1.0, -2.0, -3.0])
julia> v = Vector3D(1.0, 1, 1);
julia> @test one(T1) * v == v # unit operator do nothing
Test Passed
julia> T1 * v # transform v to T1's internal coordinate
[0.0, -1.0, -2.0]
julia> @test one(T1) * T1 == T1 # unit operator do nothing
Test Passed
julia> T2 = Translation(1.0, 1.0, 1.0) # create operator from three numbers
Translation{Float64}([1.0, 1.0, 1.0])
julia> T2 * T1 * v # apply composite operators on a vector
[-1.0, -2.0, -3.0]

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

References

Wondratschek, H. Matrices, Mappings and Crystallographic Symmetry. In IUCr Commission on Crystallographic Teaching: Teaching pamphlets; 1997. ↩
Radaelli, P. G. Symmetry in Crystallography: Understanding the International Tables; Oxford University Press, 2011. ↩

Julia in Practice: Building Scattering.jl from Scratch (3) was originally published by Yi-Xin Liu at Polyorder on April 04, 2020.

Julia in Practice: Building Scattering.jl from Scratch (2)

2020-04-09T00:00:00-00:00

In this post we will implement a submodule, peak.jl, to model the shape of scattering peaks. Essential Julia language features will be introduced along the development of the submodule. You shall learn types, constructors, functions, methods, functors, modules, testing, and benchmarking after reading this post.

Shape of the Scattering Peak
Implementation
Modules
Usage
Acknowledgements
References

Shape of the Scattering Peak

For a perfect periodic lattice, i.e. a single crystal, as will be derived in later posts, the shape of the scattering peak has the form

\[\begin{equation} L(x) = \frac{\sin^2(Nx/2)}{N^2\sin^2(x/2)} \end{equation}\label{eq:L-raw}\]

where $N$ is number of unit cells which also determines the grain size of a single crystal. As the number of unit cells increases, more cells interfere constructively and the scattering peak becomes sharper. The trend has been shown in Figure 1. Note that we have shifted the peak position to $x=2$ since in scattering the peak position is always positive.

Figure 1. The shape of the scattering peak described by Eq.\eqref{eq:L-raw}.

Note that $N$ in the denominator of $L(x)$ is introduced to normalize the function. Although the function oscillates strongly beyond the central lobe, these oscillations are usually insignificant and can be safely ignored for common crystal grain size ($N$ > 50). In practice, however, it is more convenient to choose other non-oscillating peak shapes to simulate the actual one. Gaussian and Lorentzian peaks are two popular choices. The Gaussian peak is defined as

\[\begin{equation} L(x) = \frac{2}{\pi\delta}\exp\left( -\frac{4x^2}{\pi\delta^2} \right) \end{equation}\label{eq:L-gauss}\]

where the peak width (full-width at half-maximum, $h$) depends on the parameter $\delta$ as $h = \sqrt{\pi\ln2}\delta$. Note that we use a specialized form for the Gaussian distribution to be compatible with the following introduced generalized peak. The Lorentzian peak is

\[\begin{equation} L(x) = \frac{\delta/2\pi}{x^2 + (\delta/2)^2} \end{equation}\label{eq:L-loren}\]

where the peak width is simply $h = \delta$. A more generalized peak shape function has been proposed in the literature¹, which can be seen as a mixture of the Gaussian and Lorentzian peaks. It has the form

\[\begin{equation} L(x) = \frac{2}{\pi\delta} \prod_{n=0}^{\infty} \left( 1 + \frac{\gamma_{\nu}^2}{(n+\nu/2)^2}\frac{4x^2}{\pi^2\delta^2} \right)^{-1} \end{equation}\label{eq:L-general}\]

where the parameter is a ratio of gamma functions

\[\begin{equation} \gamma_{\nu} = \sqrt{\pi}\frac{\Gamma[(\nu+1)/2]}{\Gamma(\nu/2)} \end{equation}\label{eq:gamma-nu}\]

Its peak width is also $h = \delta$. The general peak shape has the property that it reduces to the Gaussian peak in the form of Eq.\eqref{eq:L-gauss} in the limit of $\nu \to \infty$, while it approaches to the Lorentzian peak in the form of Eq.\eqref{eq:L-loren} as $\nu \to 0$. Therefore, the parameter $\nu$ controls the shape of the generalized peak. This versatile peak shape allows one to account for the various contributions to peak broadening (instrumental resolution, grain size, grain shape, microstrain).

Implementation

Now we will dive into the implementation details. We will use this opportunity to introduce some core language features about Julia. You will see that it is quite neat to use Julia to do the work.

Types

The shape of the scattering peak is fully specified by two parameters, $\nu$ and $\delta$. When $\nu$ is bigger than a threshold value $\nu_{max}$, we use the Gaussian peak to approximate the generalized peak. And when $\nu$ is smaller than a threshold value $\nu_{min}$, we use the Lorentzian peak instead of the generalized peak. Therefore, we have to implement three types of peaks, which is natural to define a Julia type for each one. And they shall all inherit from an abstract type that unifies the interface to produce a specific peak shape.

In Julia, we can define an abstract type as

1
abstract type ScatteringPeak end

Now we can define a concrete Gaussian peak type inherited from it as

1
2
3
4
struct GaussianPeak <: ScatteringPeak
    σ::Real # the variance
    μ::Real # the mean value, i.e. the position of the peak
end

The first line states that the GaussianPeak type is inherited from the ScatteringPeak denoted by the symbol <:. Note that a concrete type such as GaussianPeak should be defined using a keyword struct other than type. The type has two fields, σ and μ. Here we plan to use the standard expression of the Gaussian peak:

\[\begin{equation} L(x) = \frac{1}{\sqrt{2\pi}\sigma}\exp\left[ -\frac{(x-\mu)^2}{2\sigma^2} \right] \end{equation}\label{eq:gauss}\]

Thus, we have to do a conversion between eq.\eqref{eq:L-gauss} and eq.\eqref{eq:gauss} using $\delta = \sqrt{\frac{8}{\pi}}\sigma$ and $\mu=0$.

Similarly, we can define a Lorentzian type

1
2
3
4
struct LorentzianPeak <: ScatteringPeak
    δ::Real # the peak width
    μ::Real # the center of the peak
end

and a generalized peak type

1
2
3
4
5
6
struct GeneralizedPeak <: ScatteringPeak
    δ::Real # the variance
    ν::Real # the mean value, i.e. the position of the peak
    γν::Real # = √π * Γ[(ν+1)/2] / Γ(ν/2)
    γνhalf::Real # = Γ(ν/2)
end

Note that besides δ and ν, we have two more fields γν and γνhalf which store precomputed parameters in eq.\eqref{eq:gamma-nu} to save some time for later computations.

Constructors

Just as in C++, a constructor is a special function that use the type name as its name and create an instance of that type (instantiate an instance). Julia provides default constructors for all user-defined types, which accept the equal number of arguments as the number of its fields. Sometimes, however, it is convenient to custom our own constructors. Julia allows unlimited number of constructor for a type. For example, for the GaussianPeak type, the mean value parameter $\mu$ is commonly set to 0, so it is convenient to provide a constructor which takes only one arguments which provides the value of $\sigma$:

1
2
3
4
function GaussianPeak(σ::Real, μ::Real=0)
    @assert(σ > 0, "The variance must be positive.")
    new(σ, μ)
end

Now, we can initiate an instance as

1
p = GaussianPeak(0.1)

Using default constructor, we have to do the following

1
p = GaussianPeak(0.1, 0.0)

Our own constructor also checks the value of $\sigma$, ensuring its value is positive. We can write a similar constructor for the LorentzianPeak type.

Constructors like above are put outside of the definition of its corresponding type. They are outer constructors. When only outer constructors are presented for a type, the default constructor provided by Julia is still working. However, sometimes it is better to disable the default constructor when we don’t want user to provide values for some fields explicitly. For example, the fields γν and γνhalf both depend on another field ν. To ensure the consistency in the instance, we don’t want users of our package to initialize the GeneralizedPeak type using the default constructor. To this end, we can define an internal constructor which will override the default one:

1
2
3
4
5
6
7
8
9
10
11
12
13
struct GeneralizedPeak <: ScatteringPeak
    δ::Real # the variance
    ν::Real # the mean value, i.e. the position of the peak
    γν::Real # = √π * Γ[(ν+1)/2] / Γ(ν/2)
    γνhalf::Real # = Γ(ν/2)
    function GeneralizedPeak(δ::Real, ν::Real)
        @assert(δ > 0, "The peak width must be positive.")
        @assert(ν > 0, "The peak shape parameter must be positive.")
        γνhalf = gamma(ν/2)
        γν = √π * gamma((ν+1)/2) / γνhalf
        new(δ, ν, γν, γνhalf)
    end
end

With above definition, we can only initiate a GeneralizedPeak instance using

1
p = GeneralizedPeak(0.1, 1.0)

and following attempt will fail

1
p = GeneralizedPeak(0.1, 1.0, 0.0, 0.0)

Functions

It is useful to provide a unified interface to create a correct ScatteringPeak instance based on the values of $\delta$ and $\nu$. We can write a function for this purpose

1
2
3
4
5
6
7
8
9
10
function peak(δ::Real, ν::Real)
    if ν < 0.01
        LorentzianPeak(δ)
    elseif ν > 200
        σ = √(π/8) * δ
        GaussianPeak(σ)
    else
        GeneralizedPeak(δ, ν)
    end
end

It accepts two real numbers and returns a correct ScatteringPeak instance accordingly. Note that we have set $\nu_{min}=0.01$ and $\nu_{max}=200$. Also a conversion has been done for the GaussianPeak instance in line 5.

Tests

We can verify the peak in the Julia REPL

1
2
3
julia> p = peak(0.1, 1.0);
julia> typeof(p)
# GeneralizedPeak

There is also a very useful package, Test.jl, which provides functionalities to facilitate the testing work. We can perform a test as

1
2
3
4
julia> using Test
julia> p = peak(0.1, 1.0);
julia> @test typeof(p) isa GeneralizedPeak
# Test Passed

In the above, we first import the Test package use using keyword. Then @test macro is used to verify that the instance created by the peak function is a GeneralizedPeak peak as expected (since $\nu_{min} < \nu = 1.0 < \nu_{max}$).

Methods

Now it is time for us to add the essential part of each type: to actually create a peak. We shall use Julia methods. A method is a special function whose arguments are marked with explicit types. A function can have many methods. Therefore, a method can be viewed as a specific instance of a function.

1
2
3
peakshape(p::LorentzianPeak, x) = @. (p.δ/(2π)) / ((x-p.μ)^2 .+ (p.δ/2)^2)
peakshape(p::GaussianPeak, x) = @. exp(-(x-p.μ)^2/(2p.σ^2)) / (√(2π)*p.σ)
peakshape(p::GeneralizedPeak, x; tol::Real=1e-4, nmax::Integer=2000) = [compute_single_point(p, x[i], tol, nmax) for i in 1:length(x)]

Above codes define three methods all named peakshape for three types of scattering peak, respectively. Note that the keyword function can be omitted when the function body can be written in one line (one-liner). This greatly reduces the redundancy of the code and make the code looks extremely clean. The @. macro broadcast all operations to every elements of an array-like object. The implementation of compute_single_point will be presented in the following subsection.

Using these peakshape methods, we can now compute any type of scattering peaks, such as:

1
2
3
4
5
6
julia> p = peak(0.1, 1.0);
julia> q = collect(0.001:0.001:4.0);
julia> qhkl = 2.0;
julia> qs = q .- qhkl;
julia> peakshape(p, qs)
# produce a generalized peak with its peak locates at q = 2.0

The Julia compiler first deduces the type of instance p, which is GeneralizedPeak in the above example. Then it will dispatch it to the correct version of the peakshape method, which is the third one in the example.

We can compare these types of scattering peaks by plotting them together as shown in Figure 2.

Figure 2. A comparison of various scattering peaks.

It is obvious that the GeneralizedPeak is indeed a mixture of other two types.

Functors

Methods are associated with types, so it is possible to make any arbitrary Julia object “callable” by adding methods to its type. Such “callable” objects are sometimes called functors. Since the only functionality of the ScatteringPeak type is computing the peak shape, the functor fits this use case perfectly. For example, we can define functors as

1
(p::ScatteringPeak)(x) = peakshape(p, x)

The functor is a function without name and its only argument is a type instance. Now we can compute the peak simply using

1
julia> p(qs)

where p is a <:ScatteringPeak instance and qs is an array of $x$ values.

Benchmark and Performance

To compute a generalized peak, we have to evaluate an infinite product series in Eq.\eqref{eq:L-general}. By doing some numerical experiments, we learn that the series converges fast near and far away from the peak, but it converges much slower in between (around peak shoulder). So we have to allow the number of terms varying during computation. A tolerance is set to control the minimum number of terms for each $x$ value. The implementation is given below

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
function compute_single_point(p::GeneralizedPeak, q::Real; tol::Real=1e-4, nmax::Integer=2000)
    c = 2/(p.δ*π)
    s = c
    s_prev = 0.0
    ds = 1.0
    n = 0
    while ds > tol && n < nmax
        s_prev = s
        t1 = (p.γν/(n+p.ν/2))^2
        t2 = (c * q)^2
        s /= (1 + t1*t2)
        ds = abs(s - s_prev)
        n += 1
    end
    s
end

This is the only computation intensive method in this submodule. To ensure its performance, we can run some benchmarks. Julia core provides a @time macro which can estimate the computation time of a method. However, its results are known to be disturbed by environment settings. So it is not quite reliable. The BenchmarkTools.jl package, on the other hand, provide a reliable macro @btime that isolates the environment. We can check out the performance of our code by running

1
2
3
4
julia> using BenchmarkTools
julia> p = peak(0.1, 1.0);
julia> @btime compute_single_point($p, 0.2)
# 11.xx μs (xx allocations: xx bytes)

Julia also provides a macro @code_warntype which helps us to identify the type instability issue. Using @code_warntype, it shows that our current implementation of compute_single_point is not optimized.

1
2
julia> @code_warntype compute_single_point(p, 0.2)
# pseudo codes presented here.

From the output of above @code_warntype, we can observe that Julia compiler cannot infer the types of c, s, s_prev, and ds due to the lack of type information of p.δ. To solve this issue, we should re-define GaussianPeak, LorentzianPeak and GeneralizedPeak to accept a type parameter which defines the type of their internal fields. For example,

1
2
3
4
struct GaussianPeak{T<:Real} <: ScatteringPeak
    σ::T # the variance
    μ::T # the mean value, i.e. the position of the peak
end

We should also update its constructor

1
2
3
4
function GaussianPeak(σ::T, μ::T=zero(T)) where {T<:Real}
    @assert(σ > 0, "The variance must be positive.")
    new{T}(σ, μ)
end

After all refactoring work is done, we re-run @code_warntype and will notice that all types are inferred by the compiler successfully. Using @btime to benchmark again, we will notice that the running time is only 207 ns which is 50 times faster!

Modules

The above codes are organized into a submodule and put in a single file named peak.jl

1
2
3
4
5
6
7
module Peak

using SpecialFunctions # for gamma function

# all other codes ...

end

We use the gamma function in the SpecialFunctions.jl package to compute the $\Gamma$ function in Eq.\eqref{eq:gamma-nu}.

We will create a new file Scattering.jl to organize all its submodules and export Julia objects.

1
2
3
4
5
6
7
8
9
module ScatteringPeak

include("peak.jl")

using .Peak: ScatteringPeak, GaussianPeak, LorentzianPeak, GeneralizedPeak, peak
export ScatteringPeak, GaussianPeak, LorentzianPeak, GeneralizedPeak
export peak

end

Currently, only the Peak submodule is included and exported.

Usage

Now we can generate a peak using the Scattering.jl package as follows

julia> using Scattering
julia> p = peak(0.1, 1.0);
julia> qs = collect(0.001:0.001:4.0) .- 2.0
julia> p(qs) # peak is generated here

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

References

Yager, K. G.; Zhang, Y.; Lu, F.; Gang, O. Periodic Lattices of Arbitrary Nano-Objects: Modeling and Applications for Self-Assembled Systems. J. Appl. Crystallogr. 2013, 47, 118–129. ↩

Julia in Practice: Building Scattering.jl from Scratch (2) was originally published by Yi-Xin Liu at Polyorder on March 23, 2020.

Julia in Practice: Building Scattering.jl from Scratch (1)

2019-05-17T00:00:00-00:00

This is the first post of a series of blog posts published in Yi-Xin Liu’s research group website on an effort to demonstrate how to develop a software package for computing scattering and diffraction curves of individual or self-assembled nanoparticles, polymers as well as biological materials using Julia programming language. The purpose of this series of blog posts is in three folds: (1) to provide a source of concise understanding of the scattering theory especially for small angle X-ray scattering (SAXS); (2) to demonstrate the power of the Julia programming language in scientific computing; and (3) to serve as a detailed documentation for the Scattering.jl software package.

Scattering Theory
Why Julia
Acknowledgements
References

Scattering Theory

Characterization tools based on the scattering theory are one of the most important techniques that provide the structural information of materials in various length scales from angstrom to micrometer. Typical scattering techniques are light scattering (LS), wide angle and small angle X-ray scattering (WAXS, SAXS), electron diffraction (ED), and neutron scattering (NS), depending on which type of the source of the incident beam has been utilized. Unlike imaging (real space) techniques, such as transmission electron microscope (TEM) and atomic force microscope (AFM), scattering techniques collect data in reciprocal space. Here “Reciprocal” means the information of large length scale (either feature size or distance) will be encoded in the small angle (low $q$) end of the scattering data. Thus the wavelength of different source beams determines its ability to detect objects in different length scales.

Imaging techniques typically will focus on a small region of a sample and only selected images are reported. Thus the data are always biased. As compared to imaging techniques, an important advantage of the reciprocal tools is that they gather the structural information in a sense of ensemble average (both time and space) of the entire volume of the sample. Other advantages include non-destructive measurements, ease to conduct in-situ measurements and measuring samples in their native states.

The aim of this series of posts is in two fold. Firstly, we want to develop a useful software package, Scattering.jl, that provides a consistent API to compute various scattering functions of arbitrary scatterers and their ordered or disorder assemblies in arbitrary length scales. Using this package as a starting point, we can perform more advanced analysis and simulations. For example, one can infer the size, shape, and arrangement of scatterers from the experimental scattering curves using various fitting models and algorithms. In particular, machine learning technique should be especially powerful in dealing with such inverse problems. Secondly, we want to take this opportunity to demonstrate the power of Julia programming language which is believed to be the language of choice for scientific computing.

To achieve this, a clear overview of the scattering theory is a must. As a topic having such a long history and spreading across almost every scientific field, huge amount of resources are scattered around and their notations are a mess. It is challenging to give a consistent formalism of the scattering theory. Fortunately, we have noticed several excellent papers with great readability on this topic.¹²³ Here we give a briefly summary of their work. It should lay a solid foundation for our following development work. Details and derivations are deferred to later posts.

The general expression for scattering intensities is simply an ensemble average intensities contributed by every elementary scatterers (e.g. electrons):

\[\begin{equation} I(\vq) = \ensemble{\abs{\sum_{n=1}^N \rho_n\exp{\left(i\vq\cdot\vr_n\right)}}^2}. \end{equation}\label{eq:I-general}\]

The total number of elementary scatterers is $N$. $\rho_n$ is the scattering contribution of scatterer $n$, $\vr_n$ is the position vector of scatterer $n$ and $\vq$ is the scattering vector [$q=\abs{\vq}=(4\pi/\lambda)\sin\theta$, where $\theta$ is half the scattering angle and $\lambda$ is the wavelength of the incident beam].

The summation in the above equation can be split into multiple summation by decomposing the position vector into a sum of several relative vectors, each of which shall represent a conceptual or realistic objects. For example (see the following figure), a periodic lattice of particles can be first divided into unit cells. Each unit cell consists of several motifs. Lastly each motifs may consist of a bunch of elementary scatterers.

Figure is adopted from Ref[1].

For periodic lattices, after some derivations, and further considering the distribution of sizes and orientations and variation of scatterer positions due to thermal fluctuations, the final expression for the scattering intensities is

\[\begin{equation} I(q) = P(q)\left[ \frac{cZ_0(q)}{P(q)}G(q) + 1 - \beta(q)G(q) \right] \end{equation}\label{eq:I-periodic}\]

Clearly, we have four quantities in total to compute: $P(q)$, $Z_0(q)$, $\beta(q)$, and $G(q)$.

$P(q)$ is the form factor of the periodic lattice, which is simply a sum over the form factor of all motifs in the unit cell when the interparticle correlation is ignored.

\[\begin{equation} P(q) = \sum_{j}P_j(q) = \sum_j \ensemble{\abs{F_j(\vq)}^2}_{od} \end{equation}\label{eq:Pq}\]

where $F_j(\vq)$ is the form factor of motif $j$, the subscripts $o$ and $d$ stand for average over orientation and size distribution, respectively. Hence, it is essential we can develop a code to compute the form factor of each motif. Typical motifs are spheres, cylinders, core-shell particles, and polygons in nanoparticle system. For simple shapes, there may be an analytical expression for the form factor. For arbitrary shapes, however, we shall compute it numerically. The computation of $F(\vq)$ should be the core of our software package.

$Z_0(q)$ is the lattice for the periodic lattice, which can be computed as

\[\begin{equation} Z_0(q) = \frac{1}{q^2} \sum_{\lbrace hkl \rbrace} \abs{\sum_j\ensemble{F_j(\mM_j\cdot\vq_{hkl})}_d\exp[2\pi i(x_jh + y_jk + z_jl)]}^2 L(q - q_{hkl}) \end{equation}\label{eq:Z0}\]

The equation above seems scary. But don’t panic, we will dive into every details about it in later posts. At present, only you should know is that the form factor of a motif is still the most important object.

The function $L(x)$ is a function which mimics the shape of scattering peaks. Since this function is less involved in the whole theory, it serves as a good starting point of the development of our package. The best way to learn is PRACTICE, PRACTICE, PRACTICE! (Important things shall echo three times.) Thus the next post of this series will be dedicated to developing a submodule of the Scattering.jl that computes $L(x)$.

Other quantities, $\beta(q)$ and $G(q)$, account for the effect of size distribution of scatterers and encodes fluctuations of the scatterer positions, respectively. They will be our topics after the computation of $F(\vq)$, $P(q)$ and $Z_0(q)$ is implemented.

Why Julia

I ran into Julia about five years ago. Back to those days, I was in love with Python which greatly increased my coding productivity. However, I was suffering from its slowness. Before Python, I developed scientific software using C++ which is fast but it is too complicated and sometimes it made me crazy to implement a specific numerical algorithm. You can check out those software packages I have developed here. I was wondering then if there was a programming language which combines the performance of C++ and productivity of Python. I tried to search terms like “speed and scripting programming language” in Google and I found Julia, which was in its very early stage but showed its great potential. After that, I payed special attention on it. Now Julia is in version 1.3. After ten years intensive developing, it matures into a stable language. Therefore I decide to give it a try. Scattering.jl is my first package written in Julia.

Besides its speed (check out a comparison of performance of various popular programming languages here), what attracts me most are listed below:

The syntax is even more clean and concise than Python.
Julia’s mathematical syntax makes it an ideal way to express algorithms just as they are written in papers, owing to the support of Unicode characters and other syntax sugar added by the language. This drastically increase the readability and maintainability of the code.
Multiple dispatch mechanism (allowing multiple functions to have the same name) allows you to write reusable codes more easily. And the functionality is smooth to be extended by others.
High level support for GPU computing and parallel programming.
Production ready numerical and machine learning packages: the state-of-the-art differential equations ecosystem (DifferentialEquations.jl), optimization tools (JuMP.jl and Optim.jl), iterative linear solvers (IterativeSolvers.jl), a robust framework for Fourier transforms (AbstractFFTs.jl), and powerful tools for deep learning with automatic differentiation and GPU acceleration (Flux.jl).

Nature published an article to promote Julia: Julia: come for the syntax, stay for the speed.

Let’s get a little bit of taste of Julia:

1
2
P(x, μ, σ) = 1/(√(2π)*σ) * exp(-(x-μ)^2/(2σ^2)) # Gaussian distribution
C(r) = 2π*r # compute circumference of a circle

And the Python equivalence:

1
2
3
4
5
import numpy as np
def P(x, mu, sigma)
    return 1/(np.sqrt(2*np.pi)*sigma) * np.exp(-(x-mu)**2/(2*sigma**2))
def C(r)
    return 2*np.pi*r

Now it is time to get our hands dirty! See you in the next post.

Acknowledgements

This work is partially supported by the General Program of the National Natural Science Foundation of China (No. 21873021).

References

Li, T.; Senesi, A. J.; Lee, B. Small Angle X-Ray Scattering for Nanoparticle Research. Chem. Rev. 2016, 116, 11128–11180. ↩
Senesi, A. J.; Lee, B. Small-Angle Scattering of Particle Assemblies. J. Appl. Crystallogr. 2015, 48, 1172–1182. ↩
Yager, K. G.; Zhang, Y.; Lu, F.; Gang, O. Periodic Lattices of Arbitrary Nano-Objects: Modeling and Applications for Self-Assembled Systems. J. Appl. Crystallogr. 2013, 47, 118–129. ↩

Julia in Practice: Building Scattering.jl from Scratch (1) was originally published by Yi-Xin Liu at Polyorder on March 19, 2020.

Julia Posts by Yi-Xin Liu, A Polymer Physicist

Tutorial on CubicHermiteSpline.jl

Table of Contents

Getting started

Example 1: interpolating cubic polynomial

Example 2: interpolating smooth functions

Available methods

Contribute

Acknowledgements

Julia in Practice: Building Scattering.jl from Scratch (6)

Table of Contents

Form Factor

General formula

Form factor of a homogeneous sphere

Implementation

scatterer.jl

formfactor.jl

Usage

Acknowledgements

Reference

Julia in Practice: Building Scattering.jl from Scratch (5)

Table of Contents

Electromagnetic Wave

Flux

Flux of a plane wave

Flux of a spherical wave

Scattering by an electron

Maximum magnitude of the scattered wave

Scattering cross section and scattering length

Phase of the scattering wave

Interference

Derivation based on formula \eqref{eq:amplitude}

Classical derivation

Scattering by Atoms

Atomic form factor

Multiple atoms

Generalization to Arbitrary Particles

Acknowledgements

References

Usage and Testing of rotation.jl

Table of Contents

Some Experiments on Rotation Operations

Testing and Usage of Scattering/rotation.jl

Testing EulerAngle constructors

Testing RotationMatrix constructors

Testing EulerAxisAngle Constructors

Testing conversion and promotion

Testing promotion, comparison, and unit rotation

Testing inv function

Testing multiplication of two AbstractRotation instances

Testing computing power of a AbstractRotation instance

Testing applying AbstractRotation instance to a vector

Acknowledgements

Julia in Practice: Building Scattering.jl from Scratch (4)

Table of Contents

Rotations

Rotation matrices

Euler axis angle

Rotation axis

Rotation angle

Conversion to the rotation matrix

Euler angles

Convert Euler angles to the rotation matrix

Convert the rotation matrix to Euler angles

Implementation

Rotation types

Conversions

Promotion

Inversion

Comparison

Multiplication of two rotation operations

Power of a rotation operation

Transformation of a position vector

Usage

Acknowledgements

References

Julia in Practice: Building Scattering.jl from Scratch (3)

Table of Contents

Translation and Coordinate Transformation

Points and Vectors