Polyorder

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.

Tutorial and A Template for Blogging with the LYX Jekyll Theme

2020-04-17T00:00:00-00:00

An abstract or a summary of the blog post should be put here. This paragraph, before the excerpt mark, also goes before the TOC. The excerpt mark we choose in the LYX theme is , which can be configured in _config.yml.

Heading
Front Matter
TOC
Math Equations
Codes
- Code blocks
- Inline codes
Links
Images
Citations
Quotes
Alert Boxes
Formatting
Acknowledgements
References

Heading

Headings starts from ## instead of common #, which is reserved for the title of the blog post. All headings can be linked via their short name (spaces replaced by hypens -): Math Equations.

Front Matter

The front matter of a post page source file is a collection of YAML options enclosed by --. The front matter controls how Jekyll builds this current post. Available options are:

layout: should always be post for publishing a blog post.
title: the title of the blog post.
subheadline: subtitle of the blog post, which will be displayed above the tile with smaller font and all capitalized characters.
description: a short summary of the blog post. It shows under the title on page /blog/.
teaser: shorter than description, which highlights the key point of the blog post. I shows under the title on this blog post.
author: the short name should be provided, which is defined in _data/authors.yml
date: the original publishing date of the blog post, which can be different than the date in the filename of this blog post.
modified: the date when the blog post was modified.
image.feature: whether to display a image header for the blog post. Absent or valued false when present of the feature keyword will disable the image header.
image.twitter: for Twitter card.
categories: a list of categories, can be one.
tags: a list of tags, can be one or none.
comments: show utterences comments by default. Absent of comments will show comments. To disable comments, set comments: false explicitly.
show_meta.info: if true, show information including author, date, categories, and tags.
math: include a list of user defined LaTeX commands/macros by default. To disable, set math: false.

Math Equations

Math equations is rendered by MathJax. Here is an example of inline math equation $\pi^2/6 = \sum_{n=1}^{\infty} 1/n^2$. And display math equation is written 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}\]

All display math equations are numbered automatically by enclosing the equation with \begin{equation} and \end{equation}. Otherwise, it will not be numbered:

\[V = \frac{4}{3}\pi R^3\]

Adding \label{a_label_describes_this_equation} to the end of the math block to be cited later, such as

\[\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}\]

Multiline display equation is also possible:

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

Now cite the Gaussian distribution equation using \eqref{eq:guass} eq.\eqref{eq:gauss}.

Above equations use some user defined LaTeX commands. To disable it, add math: false to the front matter. Check out the predefined macros at _include/latex_commands.html, and you can modify it freely as you like.

Codes

Code blocks

There are two kinds of code blocks:

Kramdown fencing code blocks enclosed by ```.
Liquid code blocks using {% highlight %}{% endhighlight %}.

Unfortunately, Jekyll processes these code blocks differently and outputs incompatible HTML contents, leading to serious issues. In general, one should use Jekyll code blocks for better syntax highlighting. However, there will be sometimes that it is more convenient to use fencing code blocks. The LYX Jekyll theme handles this situation carefully, see _sass/_syntax.scss. The rendered code blocks should have little visual differences.

Note that due to fencing blocks lack the data-lang attribute in their corresponding HTML codes, we use a dirty hack using CSS to display language name on the code block panel. Only a few languages are supported. Check out which language is supported in _sass/_syntax.scss, adding more as you wish.

Line numbers are displayed by default in fencing code blocks which cannot be disabled. If you don’t want to display line numbers, use Liquid code blocks instead.

Julia syntax highlighting using fencing code blocks:

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

Julia syntax highlighting using Liquid code blocks with line numbers:

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

Julia syntax highlighting using Liquid code blocks without line numbers:

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

The output by running previous code block is formatted as language text whose syntax highlighting using fencing blocks:

Translation{Float64}([1.0, 2.0, 3.0])

The output syntax highlighting using Liquid fencing blocks:

1
Translation{Float64}([1.0, 2.0, 3.0])

Note that the appearance is different from fencing blocks because <pre> is the parent of <code data-lang=text>. We can not select the <pre> to markup using CSS rules.

Console syntax highlighting using fencing code blocks:

julia> f(x, y) = x + y
julia> f(2, 3)
5
julia> f(3, 4)
7

Console syntax highlighting using Liquid code blocks:

1
2
3
4
5
julia> f(x, y) = x + y
julia> f(2, 3)
5
julia> f(3, 4)
7

Note that since we can not set the lang=julia as in fencing code blocks, the Liquid code blocks will not highlight the codes after julia> as Julia, but as general console codes.

Inline codes

File extensions with <code>: .css, .js, .html
Paths and file names with <samp>: lib/code/path/file.name
Liquid-like code may need some escaping: {{tag}}
Fencing code blocks’ ticks can be output like this: <code>```</code> → ```.
Don’t be lazy with alternative/code/formatting.

Images

Centered: use .center
Align left without text around: use nothing
Align left with text right: use .alignleft
Align right with text left: use .alignright

Citations

Here is an reference example.¹

Quotes

Here’s a short quotation which is in the middle of a sentence.

This is a long quotation by someone, normal markdown formatting rules apply: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~ TWiStErRob

Another block quotes:

Program output text output from file.name in library

Alert Boxes

All alerts support markdown and their names are all lowercase, because they’re used as CSS classes, for example TODO is alert todo=. The TODO: prefix is not automatically inserted, it’s for name calling only here.

Alert: This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Warning: call out a caveat that is easy to trigger This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Info: supplementary information, for example links to further reading or documentation. This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Tip: call out something non-trivial that could help. This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Success: This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Text: This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

TODO: reminder to myself that something needs to be done here This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Terminal:
This is like any normal markdown, even when used from non-markdown context: strong, em, em, strong em, html bold, code, kbd, samp, ins, ~~del~~.

Formatting

Belonging words should have   between to prevent wrapping: Yi-Xin Liu.
Long list of alternatives should have  between them to allow wrapping: this one/that one/other thing.
Use <del> to ~~strike text out~~.
Use <samp> for sample output: Exit code: 1.
Use <samp> for math: 4 people × 5 days = 20 man hours.
Use <var> for something representing a number: your age times.
Use  for callout Grammar Nazis.
Use  for UI elements: Press Next to proceed.
Use <abbr> to show an abbreviation: shot, but it’s not necessary if the abbr is defined in markdown.
Custom colors using colored content when referencing something highlighted on an image: Save button.

Acknowledgements

The LYX Jekyll theme adopts features from

The HPSTR Jekyll Theme by Michael Rose
The Clean Blog Theme by David Miller.
The TWiStErRob Blog Theme by Róbert Sándor Papp.

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. ↩

Tutorial and A Template for Blogging with the LYX Jekyll Theme was originally published by Yi-Xin Liu at Polyorder on April 13, 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.

Weak Inhomogeneity Expansion in Polymer Field Theory

2019-01-03T00:00:00-00:00

This report performs weak inhomogeneity expansion for the continuous Gaussian chain model of a homopolymer in an external field. The aim is to understand where does the Debye function come from. This technique constitutes the main parts of the random phase approximation (RPA). By extending this technique from single-chain formulation to many-chain formulation and regarding the potential field arising from interaction with other chains in the same system as an external field, RPA is equivalent to the weak inhomogeneity expansion.

Continuous Gaussian Chain
Weak Inhomogeneity Expansion
Appendix
Notice
Acknowledgements
References

Continuous Gaussian Chain

The normalized single partition function for a continuous Gaussian chain under an external field is given by¹

\[\begin{equation} Q[w] = \frac{1}{V}\int d\vx\; q(\vx, 1; [w]) \end{equation}\label{eq:Q}\]

where the physical length is scaled by the radius of gyration of a non-perturb Gaussian chain $R_g=\sqrt{Nb^2/6}$. The volume $V$ is also dimensionless scaled by $R_g^3$.

The propagator $q$ in the above equation satisfies the Fokker-Planck equation, also known as the modified diffusion equation (MDE)

\[\begin{equation} \der{q(\vx, s; [w])}{s} = \nabla^2 q(\vx, s; [w]) - w(\vx)q(\vx, s; [w]) \end{equation}\label{eq:MDE}\]

subject to the initial condition

\[\begin{equation} q(\vx, 0; [w]) = 1 \end{equation}\]

Note that to write the MDE in the form as in eq. \eqref{eq:MDE}, $w(\vx)$ is actually $N$ times the external potential field. Assuming the external field is $W(\vx)$, then $w(\vx)=NW(\vx)$

For a given external field $w(\vx)$, we can obtain the propagator by solving eq. \eqref{eq:MDE}.

Weak Inhomogeneity Expansion

In general, it is impossible to find an analytic solution to the MDE with a general $w(\vx)$. However, a particularly perturbation expansion can be derived when the applied potential field $w(\vx)$ has inhomogeneities that are weak in amplitude. To define such a situation, we introduce the volume average of the potential

\[\begin{equation} w_0 \equiv \frac{1}{V}\int d\vx\; w(\vx) \end{equation}\label{eq:w0-w}\]

and re-express $w(\vx)$ according to

\[\begin{equation} w(\vx) = w_0 + \epsilon\omega(\vx) \end{equation}\label{eq:w-omega}\]

which serves to define the inhomogeneous part of the field, $\epsilon\omega(\vx)$. For weak inhomogeneities, a small parameter $\epsilon$ ($\abs{\epsilon}\ll 1$) describes their characteristic amplitude. For the continuous Gaussian chain model of a homopolymer, the MDE and initial condition become

\[\begin{equation} \der{q(\vx, s)}{s} = \nabla^2 q(\vx, s) - w_0q(\vx, s) - \epsilon\omega(\vx)q(\vx, s) \end{equation}\label{eq:MDE-w0}\] \[\begin{equation} q(\vx, 0) = 1 \end{equation}\]

where the functional dependence of q on $w(\vx)$ has been suppressed in our notation. The term proportional to $w_0$ on the right-hand side of eq.\eqref{eq:MDE-w0} can be removed by the substitution

\[\begin{equation} q(\vx, s) = e^{-w_0s}p(\vx, s) \end{equation}\label{eq:q-p}\]

which leads to

\[\begin{equation} \der{p(\vx, s)}{s} = \nabla^2 p(\vx, s) - \epsilon\omega(\vx)p(\vx, s) \end{equation}\label{eq:MDE-omega}\] \[\begin{equation} p(\vx, 0) = 1 \end{equation}\]

A weak inhomogeneity expansion can be developed by assuming that $p(\vx, s)$ can be expressed as

\[\begin{equation} p(\vx, s) \sim \sum_{j=0}^{\infty} \epsilon^j p^{(j)}(\vx, s) \end{equation}\label{eq:p-expansion}\]

where the $p^{(j)}(\vx, s)$ are independent of $\epsilon$. In eq.\eqref{eq:p-expansion} we adopt the conventional notation $\sim$ to indicate an asymptotic expansion. As such, the infinite series on the right-hand side may be either convergent or divergent. Even when it does not converge, eq.\eqref{eq:p-expansion} can still be useful in truncated form for approximating $p(\vx, s)$ at sufficiently small $\epsilon$.

The $p^{(j)}$ are calculated by inserting eq.\eqref{eq:p-expansion} into eq.\eqref{eq:MDE-omega} and equating terms order by order in $\epsilon$.

Zero-th Order Solution

At leading order, $O(\epsilon^0)$, we have

\[\begin{equation} \der{p^{(0)}(\vx, s)}{s} = \nabla^2 p^{(0)}(\vx, s) \end{equation}\label{eq:MDE-p0}\] \[\begin{equation} p^{(0)}(\vx, 0) = 1 \end{equation}\]

which has the trivial solution

\[\begin{equation} p^{(0)}(\vx, s) = 1 \end{equation}\]

First Order Solution

At $O(\epsilon^1)$, the corresponding equations (see Appendix A for derivation) are

\[\begin{equation} \der{p^{(1)}(\vx, s)}{s} = \nabla^2 p^{(1)}(\vx, s) - \omega(\vx)p^{(0)}(\vx, s) \end{equation}\label{eq:MDE-p1}\] \[\begin{equation} p^{(1)}(\vx, 0) = 0 \end{equation}\]

Provided the system under consideration is unbounded or subject to periodic boundary conditions, this initial value problem is most easily solved by means of spatial Fourier transforms. Defining Fourier transforms in accordance with

\[\begin{equation} \hat{f}(\vk) \equiv \int d\vx\; e^{-i\vk\cdot\vx}f(\vx) \end{equation}\]

and assuming that the Fourier transform of $\omega(\vx)$ exists, denoted by $\hat{\omega}(\vk)$, one finds that (See Appendix B for derivation)

\[\begin{equation} \hat{p}^{(1)}(\vk, s) = -\hat{h}_2(\vk, s)\hat{\omega}(\vk) \end{equation}\label{eq:p1}\]

where the carets denote Fourier-transformed quantities and

\[\begin{equation} \hat{h}_2(\vk, s) \equiv \frac{1}{k^2}\left( 1 - e^{-k^2s} \right) \end{equation}\]

Second Order Solution

At $O(\epsilon^2)$, the corresponding equations (see Appendix C for derivation) are

\[\begin{equation} \der{p^{(2)}(\vx, s)}{s} = \lap p^{(2)}(\vx, s) - \omega(\vx)p^{(1)}(\vx, s) \end{equation}\label{eq:MDE-p2}\] \[\begin{equation} p^{(2)}(\vx, 0) = 0 \end{equation}\]

A similar procedure leads to (see Appendix D for derivation)

\[\begin{equation} \hat{p}^{(2)}(\vk, s) = \frac{1}{V}\sum_{\vk'} \hat{h}_3(\vk, \vk', s)\hat{\omega}(\vk-\vk')\hat{\omega}(\vk') \end{equation}\label{eq:p2}\]

with

\[\begin{equation} \hat{h}_3(\vk, \vk', s) = \frac{1}{k^2\abs{\vk-\vk'}^2}\left[ 1 - e^{-k^2s} -\frac{k^2}{k^2-\abs{\vk-\vk'}^2} \left( e^{-\abs{\vk-\vk'}^2s} - e^{-k^2s} \right) \right] \end{equation}\]

Expansion of $Q$

We can expand the normalized single partition function $Q$ based on above perturbation expansion of the propagator $q$. The propagator being expanded to $O(\epsilon^2)$ is

\[\begin{equation} \begin{split} q(\vx, s) &= e^{-w_0s}p(\vx, s) \\ &\sim \sum_{j=0}^{2} \epsilon^j p^{(j)}(\vx, s) \\ &= e^{-w_0s}\left[ p^{(0)}(\vx, s) + \epsilon p^{(1)}(\vx, s) + \epsilon^2 p^{(2)}(\vx, s) \right] \\ &= e^{-w_0s}\left[ 1 + \epsilon p^{(1)}(\vx, s) + \epsilon^2 p^{(2)}(\vx, s) \right] \end{split} \end{equation}\]

Therefore we can expand $Q$ as

\[\begin{equation} \begin{split} Q[w] &= \frac{1}{V}\int d\vx\; q(\vx, 1) \\ &\sim \frac{1}{V}\int d\vx\; e^{-w_0}\left[ 1 + \epsilon p^{(1)}(\vx, 1) + \epsilon^2 p^{(2)}(\vx, 1) \right] \\ &= e^{-w_0}\left[ \frac{1}{V}\int d\vx\; + \frac{1}{V}\int d\vx\;\epsilon p^{(1)}(\vx, 1) + \frac{1}{V}\int d\vx\;\epsilon^2 p^{(2)}(\vx, 1) \right] \\ &= e^{-w_0}\left[ 1 + \frac{\epsilon}{V}\int d\vx\; p^{(1)}(\vx, 1) + \frac{\epsilon^2}{V}\int d\vx\; p^{(2)}(\vx, 1) \right] \end{split} \end{equation}\label{eq:Q-expan-v1}\]

It is more convenient to write the integrals of $p^{(j)}$ in Fourier space, which can be expressed as

\[\begin{equation} \begin{split} \int d\vx\; p^{(1)}(\vx, 1) &= \int d\vx\; \frac{1}{(2\pi)^3}\int d\vk\; \hat{p}^{(1)}(\vk, 1) e^{i\vk\cdot\vx} \\ &= \int d\vk\; \hat{p}^{(1)}(\vk, 1) \left[\frac{1}{(2\pi)^3}\int d\vx\; e^{i\vk\cdot\vx} \right] \\ &= \int d\vk\; \hat{p}^{(1)}(\vk, 1) \delta(\vk) \\ &= \hat{p}^{(1)}(\vzero, 1) \end{split} \end{equation}\]

and

\[\begin{equation} \begin{split} \int d\vx\; p^{(2)}(\vx, 1) &= \int d\vx\; \frac{1}{(2\pi)^3}\int d\vk\; \hat{p}^{(2)}(\vk, 1) e^{i\vk\cdot\vx} \\ &= \int d\vk\; \hat{p}^{(2)}(\vk, 1) \left[\frac{1}{(2\pi)^3}\int d\vx\; e^{i\vk\cdot\vx} \right] \\ &= \int d\vk\; \hat{p}^{(2)}(\vk, 1) \delta(\vk) \\ &= \hat{p}^{(2)}(\vzero, 1) \end{split} \end{equation}\]

Now we can express $Q$ in the Fourier space as

\[\begin{equation} Q[w] \sim e^{-w_0}\left[ 1 + \frac{\epsilon}{V}\hat{p}^{(1)}(\vzero, 1) + \frac{\epsilon^2}{V}\hat{p}^{(2)}(\vzero, 1) \right] \end{equation}\label{eq:Q-expan-v2}\]

The expansion of $Q$ can be further simplified. Firstly, we know that the volume average of the fluctuation of the potential field is 0 because

\[\begin{equation} \begin{split} \frac{1}{V}\int d\vx\; \omega(\vx) &= \frac{1}{V}\int d\vx\; \left[ w(\vx) - w_0 \right] \\ &= \frac{1}{V}\int d\vx\; w(\vx) - \frac{1}{V}\int d\vx\; w_0 \\ &= w_0 - \frac{1}{V} w_0 V \\ &= 0 \end{split} \end{equation}\]

The value of the Fourier transform of the potential field at zero wave number is equal to this average because

\[\begin{equation} \begin{split} \int d\vx\; \omega(\vx) &= \int d\vx\; \frac{1}{(2\pi)^3}\int d\vk\; \hat{\omega}(\vk)e^{i\vk\cdot\vx} \\ &= \int d\vk\; \frac{1}{(2\pi)^3}\int d\vx\; \hat{\omega}(\vk)e^{i\vk\cdot\vx} \\ &= \int d\vk\; \hat{\omega}(\vk) \left[ \frac{1}{(2\pi)^3}\int d\vx\; e^{i\vk\cdot\vx}\right] \\ &= \int d\vk\; \hat{\omega}(\vk) \delta(\vk) \\ &= \hat{\omega}(\vzero) \end{split} \end{equation}\]

Therefore, one obtains

\[\begin{equation} \hat{\omega}(\vzero) = 0 \end{equation}\]

Substituting this into eq.\eqref{eq:p1} gives

\[\begin{equation} \hat{p}^{(1)}(\vzero, 1) = 0 \end{equation}\label{eq:p101-Fourier}\]

Secondly, from eq.\eqref{eq:p2} we know

\[\begin{equation} \begin{split} \hat{p}^{(2)}(\vzero, 1) &= \frac{1}{V}\sum_{\vk'} \hat{h}_3(\vzero, \vk', 1)\hat{\omega}(-\vk')\hat{\omega}(\vk') \\ &= \frac{1}{V}\sum_{\vk} \hat{h}_3(\vzero, \vk, 1)\hat{\omega}(-\vk)\hat{\omega}(\vk) \end{split} \end{equation}\label{eq:p201-h3}\]

In the second line, we only change the summation variable from $\vk’$ to $\vk$. Noting that

\[\begin{equation} \begin{split} \hat{h}_3(\vzero, \vk', 1) &= \lim_{\vk\to 0} \hat{h}_3(\vk, \vk', 1) \\ &= \lim_{\vk\to 0} \frac{1}{k^2\abs{\vk-\vk'}^2}\left[ 1 - e^{-k^2} -\frac{k^2}{k^2-\abs{\vk-\vk'}^2} \left( e^{-\abs{\vk-\vk'}^2} - e^{-k^2} \right) \right] \\ &= \lim_{\vk\to 0} \frac{1}{k^2\abs{\vk-\vk'}^2}\left( 1 - e^{-k^2} \right) - \lim_{\vk\to 0} \frac{1}{k^2\abs{\vk-\vk'}^2} \frac{k^2}{k^2-\abs{\vk-\vk'}^2} \left( e^{-\abs{\vk-\vk'}^2} - e^{-k^2} \right) \\ &= \lim_{\vk\to 0} \frac{1}{k^2\abs{\vk-\vk'}^2}\left[ 1 - (1 - k^2) \right] + \frac{1}{k'^4}\left( e^{-k'^2} - 1 \right) \\ &= \frac{1}{k'^2} + \frac{1}{k'^4}\left( e^{-k'^2} - 1 \right) \end{split} \end{equation}\]

Let

\[\begin{equation} x = k'^2 \end{equation}\]

Then it becomes

\[\begin{equation} \begin{split} \hat{h}_3(\vzero, \vk', 1) &= \frac{1}{x} + \frac{1}{x^2}\left( e^{-x} - 1 \right) \\ &= \frac{1}{x^2}\left( e^{-x} + x - 1 \right) \end{split} \end{equation}\]

This is where the well known Debye function comes from, which is defined as

\[\begin{equation} \hat{g}_D(x) = \frac{2}{x^2}\left( e^{-x} + x - 1 \right) \end{equation}\]

Therefore,

\[\begin{equation} \hat{h}_3(\vzero, \vk', 1) = \frac{1}{2}\hat{g}_D(x) \end{equation}\label{eq:h301-final}\]

Insert eq.\eqref{eq:p101-Fourier}, \eqref{eq:p201-h3}, and \eqref{eq:h301-final} into eq.\eqref{eq:Q-expan-v2}, we arrive the final expansion of $Q$ in the Fourier space

\[\begin{equation} Q[w] \sim e^{-w_0}\left[ 1 + \frac{\epsilon^2}{2V^2}\sum_{\vk}\hat{g}_D(k^2)\hat{\omega}(-\vk)\hat{\omega}(\vk) \right] \end{equation}\label{eq:Q-expan-v3}\]

or, by inverting the Fourier transforms,

\[\begin{equation} \begin{split} Q[w] &\sim e^{-w_0}\left[ 1 + \frac{\epsilon^2}{2V^2}\sum_{\vk}\hat{g}_D(k^2)\hat{\omega}(-\vk)\hat{\omega}(\vk) \right] \\ &\sim e^{-w_0}\left\lbrace 1 + \frac{\epsilon^2}{2V^2} \sum_{\vk}\hat{g}_D(k^2) \left[\int d\vx\;\omega(\vx)e^{i\vk\cdot\vx} \right] \left[\int d\vx'\;\omega(\vx')e^{-i\vk\cdot\vx'} \right] \right\rbrace \\ &\sim e^{-w_0}\left\lbrace 1 + \frac{\epsilon^2}{2V} \int d\vx\int d\vx'\;\left[\frac{1}{V}\sum_{\vk}\hat{g}_D(k^2) e^{i\vk\cdot(\vx-\vx')} \right]\omega(\vx)\omega(\vx') \right\rbrace \end{split} \end{equation}\]

If we define the inverse transform of the Debye function as

\[\begin{equation} \begin{split} g_D(\abs{\vx - \vx'}) &= \frac{1}{V}\sum_{\vk}\hat{g}_D(k^2)e^{i\vk\cdot(\vx-\vx')} \\ &= \frac{1}{(2\pi)^3}\int d\vk\; \hat{g}_D(k^2)e^{i\vk\cdot(\vx-\vx')} \end{split} \end{equation}\]

Then the expansion of $Q$ in real space can be written as

\[\begin{equation} Q[w] \sim e^{-w_0}\left[ 1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx') \right] \end{equation}\label{eq:Q-expan-final}\]

Expansion of the Density Operator

A weak inhomogeneity expansion for the segment density operator $\rho(\vx; [w])$ can be obtained in one of two equivalent ways. One way is expressing $\rho(\vx; [w])$ as an integral of the propagator, such as

\[\begin{equation} \rho(\vx; [w]) = \frac{1}{VQ[w]}\int_0^1 q(\vx, 1-s; [w])q(\vx, s; [w]) \end{equation}\]

and substituting the weak inhomogeneity expansion of the propagator eq.\eqref{eq:q-p} and \eqref{eq:p-expansion} into above equation and keeping to a certain order. The other way is performing a direct functional differentiation of eq.\eqref{eq:Q-expan-final} according to

\[\begin{equation} \begin{split} \rho(\vx; [w]) &= \rho(\vx; [W(\vx)]) \\ &= -\Der{\ln Q[W(\vx)]}{W(\vx)} \\ &= -N\Der{\ln Q[W(\vx)]}{NW(\vx)} \\ &= -N\Der{\ln Q[w]}{w} \end{split} \end{equation}\]

Here we Follow the latter approach. From eq.\eqref{eq:Q-expan-final} we have

\[\begin{equation} \ln Q[w] \sim -w_0 + \ln\left[ 1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx') \right] \end{equation}\]

From eq.\eqref{eq:w0-w} we have

\[\begin{equation} \Der{w_0}{w} = \frac{1}{V} \end{equation}\]

From eq.\eqref{eq:w-omega} we have

\[\begin{equation} \Der{\omega}{w} = \frac{1}{\epsilon} \end{equation}\]

Now we can perform the functional differentiation as

\[\begin{equation} \begin{split} \rho(\vx; [w]) &= -N\Der{\ln Q[w]}{w} \\ &= N\Der{w_0}{w} - \Der{}{w}\ln\left[ 1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx') \right] \\ &= \frac{N}{V} - N\Der{}{\omega}\ln\left[ 1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx') \right]\Der{\omega}{w} \\ &= \rho_0 - N\frac{1}{\epsilon}\Der{}{\omega}\ln\left[ 1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx') \right] \\ &= \rho_0 - N\frac{1}{\epsilon}\frac{1}{1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx')} \frac{\epsilon^2}{2V} 2\int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx') \\ &= \rho_0 - \rho_0 \epsilon \frac{1}{1 + \frac{\epsilon^2}{2V} \int d\vx \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx)\hat{\omega}(\vx')} \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx') \end{split} \end{equation}\]

where $\rho_0 \equiv N/V$ is the volume-average segment density of a single chain. If we only retain the first order contribution of $\epsilon$, above equation can be simplified to

\[\begin{equation} \rho(\vx; [w]) = \rho_0 - \rho_0 \epsilon \int d\vx'\; g_D(\abs{\vx - \vx'})\omega(\vx') \end{equation}\label{eq:rho-omega}\]

Or we can use eq.\eqref{eq:w-omega} to rewrite $\rho$ as a functional of $w$ instead of $\omega$

\[\begin{equation}\label{eq:rho-w} \rho(\vx; [w]) = \rho_0 \left[ 1 - \int d\vx'\; g_D(\abs{\vx - \vx'})(w-w_0) \right] \end{equation}\]

We can also inverse the above equation to predict what external field should be applied if we want to obtain a certain segment density. Such inversion can be done in the Fourier space

\[\begin{equation} \hat{\phi}(\vk) = - \hat{g}_D(k^2)\hat{\Delta w}(\vk) \end{equation}\label{eq:phik-wk}\]

where $\phi=\rho/\rho_0 - 1$ is the dimensionless fluctuation of segment density around its volume-average value and $\Delta w=w-w_0$ is the fluctuation of the external field. It is straightforward to inverse it

\[\begin{equation}\label{eq:wk-phik} -\hat{\Delta w}(\vk) = \hat{g}_D^{-1}(k^2) \hat{\phi}(\vk) \end{equation}\]

Appendix

A. Derivation of eq.\eqref{eq:MDE-p1}

At $O(\epsilon^1)$, the expansion for $p(\vx, s)$ is

\[\begin{equation} p \sim p^{(0)} + \epsilon p^{(1)} \end{equation}\]

Inserting it into eq.\eqref{eq:MDE-omega}, we have

\[\begin{equation} \der{}{s}\left[ p^{(0)} + \epsilon p^{(1)} \right] = \nabla^2 \left[ p^{(0)} + \epsilon p^{(1)} \right] - \epsilon\omega\left[ p^{(0)} + \epsilon p^{(1)} \right] \end{equation}\label{eq:MDE-full-A}\]

From the zeroth order expansion eq.\eqref{eq:MDE-p0}, we know

\[\begin{equation} \der{p^{(0)}}{s} - \nabla^2 p^{(0)} = 0 \end{equation}\]

It simplifies eq.\eqref{eq:MDE-full-A} to

\[\begin{equation} \der{p^{(1)}}{s} = \nabla^2 p^{(1)} - \omega p^{(0)} - \epsilon\omega p^{(1)} \end{equation}\]

As $\epsilon \to 0$, the last term in the right-hand side of the above equation vanishes, leading to eq.\eqref{eq:MDE-p1}.

B. Derivation of eq.\eqref{eq:p1}

We know

\[\begin{equation} p^{(0)}(\vx, s) = 1 \end{equation}\]

which is the trivial solution of zeroth order expansion. Therefore eq.\eqref{eq:MDE-p1} becomes

\[\begin{equation} \der{}{s}p^{(1)}(\vx, s) = \nabla^2 p^{(1)}(\vx, s) - \omega(\vx) \end{equation}\]

Perform Fourier transforms on both sides of above equation, we reaches

\[\begin{equation} \der{}{s}\hat{p}^{(1)}(\vk, s) = -k^2 \hat{p}^{(1)}(\vk, s) - \hat{\omega}(\vk) \end{equation}\]

Re-organize above equation into the form

\[\begin{equation} \frac{d\left[ k^2\hat{p}^{(1)} + \hat{\omega} \right]}{k^2\hat{p}^{(1)} + \hat{\omega}} = -k^2 ds \end{equation}\]

It can be easily solved and the solution is

\[\begin{equation} \ln\left[ k^2\hat{p}^{(1)} + \hat{\omega} \right] = -k^2 s + C \end{equation}\label{eq:p1-intermediate-A}\]

Let $s=0$, and with $\hat{p}^{(1)}(\vk, 0)=0$ (because $p^{(1)}(\vx, 0)=0$), we then have

\[\begin{equation} \ln \hat{\omega} = C \end{equation}\]

\[\begin{equation} \hat{\omega} = e^C \end{equation}\]

Write eq.\eqref{eq:p1-intermediate-A} with $\hat{p}^{(1)}$ in the left-hand side and substitute above equation into it, we arrives at

\[\begin{equation} \hat{p}^{(1)} = -\frac{1}{k^2}\left( 1 - e^{-k^2s} \right)\hat{\omega} \end{equation}\]

which is equivalent to eq.\eqref{eq:p1}.

C. Derivation of eq.\eqref{eq:MDE-p2}

At $O(\epsilon^2)$, the expansion for $p(\vx, s)$ is

\[\begin{equation} p \sim p^{(0)} + \epsilon p^{(1)} + \epsilon^2 p^{(2)} \end{equation}\]

Inserting it into eq.\eqref{eq:MDE-omega}, we have

\[\begin{equation} \der{}{s}\left[ p^{(0)} + \epsilon p^{(1)} + \epsilon^2 p^{(2)} \right] = \nabla^2 \left[ p^{(0)} + \epsilon p^{(1)} + \epsilon^2 p^{(2)} \right] - \epsilon\omega\left[ p^{(0)} + \epsilon p^{(1)} + \epsilon^2 p^{(2)} \right] \end{equation}\label{eq:MDE-full-p2-A}\]

Substitute eq.\eqref{eq:MDE-p0} and \eqref{eq:MDE-p1} into above equation and ignore terms with $\epsilon$, it simplifies to eq.\eqref{eq:MDE-p2}.

D. Derivation of eq.\eqref{eq:p2}

We copy eq.\eqref{eq:MDE-p2} here

\[\begin{equation} \der{p^{(2)}(\vx, s)}{s} = \lap p^{(2)}(\vx, s) - \omega(\vx)p^{(1)}(\vx, s) \end{equation}\]

Perform Fourier transforms on both sides of above equation, we arrives

\[\begin{equation} \der{\hat{p}^{(2)}(\vk, s)}{s} = -k^2\hat{p}^{(2)}(\vk, s) - \widehat{\omega p^{(1)}}(\vk, s) \end{equation}\]

This is a general first order linear partial differential equation with respect to $s$

\[\begin{equation} \der{\hat{p}^{(2)}}{s} + k^2\hat{p}^{(2)} = -\widehat{\omega p^{(1)}} \end{equation}\]

The solution is

\[\begin{equation}\label{eq:p2-raw-A} \hat{p}^{(2)} = \frac{\int ds\; u(s)[-\widehat{\omega p^{(1)}}] + C}{u(s)} \end{equation}\]

where $C$ is a constant which can be obtained by applying the initial condition, and

\[\begin{equation} u(s) = \exp\left( \int ds\;k^2 \right) = e^{k^2s} \end{equation}\label{eq:us-A}\]

From the first order solution, we can find

\[\begin{equation} \begin{split} \widehat{\omega p^{(1)}} &= \hat{w} * \hat{p}^{(1)} \\ &= \frac{1}{V}\sum_{\vk'} \hat{w}(\vk') \hat{p}^{(1)}(\vk-\vk') \end{split} \end{equation}\]

Substituting eq.\eqref{eq:p1} into above equation, we have

\[\begin{equation} \widehat{\omega p^{(1)}} = -\frac{1}{V}\sum_{\vk'} \hat{h}_2(\vk-\vk',s)\hat{w}(\vk-\vk')\hat{w}(\vk') \end{equation}\label{eq:wp1-A}\]

To simplify the notation, we define

\[\begin{equation} \alpha \equiv k^2 \end{equation}\] \[\begin{equation} \beta \equiv \abs{\vk-\vk'}^2 \end{equation}\]

Substitute eq.\eqref{eq:us-A} and \eqref{eq:wp1-A} into eq.\eqref{eq:p2-raw-A}

\[\begin{equation} \begin{split} \hat{p}^{(2)} &= e^{-\alpha s} \left\lbrace \int ds\; e^{\alpha s} \left[ \frac{1}{V}\sum_{\vk'}\frac{1}{\beta}(1-e^{-\beta s})\hat{w}(\vk-\vk')\hat{w}(\vk') \right] + C \right\rbrace \\ &= e^{-\alpha s} \left\lbrace \frac{1}{V\beta}\sum_{\vk'} \left[\int ds\; e^{\alpha s}(1-e^{-\beta s}) \right]\hat{w}(\vk-\vk')\hat{w}(\vk') + C \right\rbrace \\ &= e^{-\alpha s} \left\lbrace \frac{1}{V\beta} \sum_{\vk'} \left[ \frac{1}{\alpha}e^{\alpha s} - \frac{1}{\alpha-\beta}e^{(\alpha-\beta)s} \right]\hat{w}(\vk-\vk')\hat{w}(\vk') + C \right\rbrace \end{split} \end{equation}\]

Because $p^{(2)}(\vx, 0)=0$, thus $\hat{p}^{(2)}(\vk, 0)=0$, therefore

\[\begin{equation} 0 = e^{-\alpha 0} \left\lbrace \frac{1}{V\beta} \sum_{\vk'} \left[ \frac{1}{\alpha}e^{\alpha 0} - \frac{1}{\alpha-\beta}e^{(\alpha-\beta)0} \right]\hat{w}(\vk-\vk')\hat{w}(\vk') + C \right\rbrace \end{equation}\]

Thus

\[\begin{equation} C = -\frac{1}{V\beta} \sum_{\vk'} \left( \frac{1}{\alpha} - \frac{1}{\alpha-\beta} \right)\hat{w}(\vk-\vk')\hat{w}(\vk') \end{equation}\]

Substitute it back into previous equation,

\[\begin{equation} \begin{split} \hat{p}^{(2)} &= e^{-\alpha s} \left\lbrace \frac{1}{V\beta} \sum_{\vk'} \left[ \frac{1}{\alpha}e^{\alpha s} - \frac{1}{\alpha-\beta}e^{(\alpha-\beta)s} \right]\hat{w}(\vk-\vk')\hat{w}(\vk') -\frac{1}{V\beta} \sum_{\vk'} \left( \frac{1}{\alpha} - \frac{1}{\alpha-\beta} \right)\hat{w}(\vk-\vk')\hat{w}(\vk') \right\rbrace \\ &= \frac{1}{V} \sum_{\vk'} \left[ e^{-\alpha s}\left( \frac{1}{\alpha}e^{\alpha s} - \frac{1}{\alpha} - \frac{1}{\alpha-\beta}e^{(\alpha-\beta)s} + \frac{1}{\alpha-\beta} \right)\frac{1}{\beta} \right] \hat{w}(\vk-\vk')\hat{w}(\vk') \end{split} \end{equation}\]

We can define

\[\begin{equation} \begin{split} \hat{h}_3(\vk, \vk', s) &= e^{-\alpha s}\left( \frac{1}{\alpha}e^{\alpha s} - \frac{1}{\alpha} - \frac{1}{\alpha-\beta}e^{(\alpha-\beta)s} + \frac{1}{\alpha-\beta} \right)\frac{1}{\beta} \\ &= \frac{1}{\beta}\left( \frac{1}{\alpha} - \frac{1}{\alpha}e^{-\alpha s} - \frac{1}{\alpha-\beta}e^{-\beta s} + \frac{1}{\alpha-\beta}e^{-\alpha s} \right) \\ &= \frac{1}{\alpha\beta}\left[ 1 - e^{-\alpha s} - \frac{\alpha}{\alpha-\beta}\left( e^{-\beta s} - e^{-\alpha s} \right) \right] \end{split} \end{equation}\]

which completes the derivation.

Notice

This report is originally an internal document of Yi-Xin Liu’s group, which is generated at Jan. 25, 2016. The PDF version can be downloaded via the following link. Comments are welcome!

Download Fulltext in PDF

Acknowledgements

This note is supported by the by the China Scholarship Council (No. 201406105018).

References

Fredrickson, G. H. The Equilibrium Theory of Inhomogeneous Polymers; Clarendon Press: Oxford, 2006. ↩

Weak Inhomogeneity Expansion in Polymer Field Theory was originally published by Yi-Xin Liu at Polyorder on January 03, 2019.

Test PolyFTS with Polyorder

2015-04-17T00:00:00-00:00

We will verify the PolyFTS calculation by comparing to the Polyorder results. The SCFT model we will test is miktoarm star block copolymer and homopolymer blends (AB3 + A).

1. Settings

1.1 Common Settings

1
2
3
4
5
6
f:          0.4
phi_h:      0.3
xN:         18
Lx:         64
ds:         0.01
stop_tol:   1e-8

1.2 Polyorder Settings

1
2
3
4
MDE solver:             ETDRK4
SCFT updater:           Anderson mixing
seed:                   file
Cell size optimization: Brent

1.3 PolyFTS Settings

1
2
3
4
MDE solver:             ROS
SCFT updater:           SIS
seed:                   random numbers or file (for HEX)
Cell size optimization: variable cell

2. DIS

For disordered structure, it is not necessary to optimize the unit cell size. The unit cell size can be arbitrarily chosen to be 1.0. Also, we can use only one plane wave in 1D.

Software	a	H	t
Polyorder	1.0	4.3848	0.00083
PolyFTS	1.0	4.384794	0.02
PolyFTS+smear	1.0	4.3848	0.01

3. LAM

3.1 Single Unit Cell Size

We choose the unit cell size to be 3.552616, which is the optimum value obtained by Polyorder.

Free Energy

Software	a	H	t
Polyorder	3.552616	4.1076304682	0.04
PolyFTS	3.552616	4.1076351249	1.84
PolyFTS+smear	3.552616	4.3615373785	1.97

3.2 Cell Size Optimization

Brent optimization in Polyorder preforms 3 SCFT simulations to find the initial points and 4 additional SCFT simulations to search the minimum. Variable cell SCFT simulations by PolyFTS takes 25,000 SCFT cycles, which is about 6 times more than the bare SCFT simulations.

Software	a	H	t
Polyorder	3.552616	4.1076304682	0.38
PolyFTS	3.556888	4.1076334133	11.24
PolyFTS+smear	4.083726	4.3477787568	32.38

4. HEX

4.1 Single Unit Cell Size

In Polyorder, we choose a rectangular unit cell whose side lengths are $a$ and $b$. The ratio $b/a$ is equal to $\sqrt{3}$. In PolyFTS we choose a rhombic unit cell with angle between side lengths being $2\pi/3$.

Free Energy

Software	a	H	t
Polyorder	4.621005	4.1458955044	1.68
PolyFTS	4.621005	4.1458949638	48.26
PolyFTS + Symmetrizer	4.621005	4.1458949635	32.50
PolyFTS + smear	4.621005	4.3556394360	6.28

Density Field

Software	A	B
PolyFTS without symmetrizer
PolyFTS with symmetrizer
PolyFTS with smearing

4.2 Cell Size Optimization

In Polyorder we choose a rectangular unit cell, while in PolyFTS we choose a rhombic unit cell with angle between side lengths being $2\pi/3$.

Brent optimization in Polyorder preforms 3 SCFT simulations to find the initial points and 4 additional SCFT simulations to search the minimum. Variable cell SCFT simulations by PolyFTS with symmetrizer takes 63,000 SCFT cycles. Variable cell SCFT simulations by PolyFTS without symmetrizer takes 126,000 SCFT cycles.

Free Energy

Software	a	H	t
Polyorder	4.621005	4.1458955044	13.35
PolyFTS	4.621874	4.1458949237	1007.56
PolyFTS + Symmetrizer	4.622002	4.1458949227	496.81
PolyFTS + smear	4.949710	4.3534538770	1182.66

Density Field

Software	A	B
PolyFTS without symmetrizer
PolyFTS with symmetrizer
PolyFTS with smearing

4.3 Discussion

For HEX phase, there are two kinds of structures: cylinder formed by specie A (HEX-A phase) and cylinder formed by specie B (HEX-B phase). In this particular case, HEX-A phase is more stable, despite that specie A’s volume fraction is larger than that of specie B.

Using random initial fields, PolyFTS with symmetrizer can only produce HEX-B phase. To obtain HEX-A phase, one can switch the two columns corresponding to A and B fields in fields.dat and use the resulted file to initialize the PolyFTS + symmetrizer simulation.

5. Conclusion

Polyorder and PolyFTS agree very well within an error of about 1e-6.
Caution about the type A and type B phase of the HEX structure. Use corresponding field to initialize simulation.
Output and input field are all SpeciesField.

Reference

Test PolyFTS with Polyorder was originally published by Yi-Xin Liu at Polyorder on April 10, 2015.

Polyorder Configuration File

2015-04-06T00:00:00-00:00

The configuration file for Polyorder can be either in INI or in YAML format. Sample configuration files can be found in the example folder in the Polyorder project.

Format

Here we use the YAML format to demonstrate how to write a configuration file for Polyorder.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
# Configurations for PolyOrder
---  # begin of new document
Version:  # corresponds to [section] in INI format
    # Format: <major>.<minor>, mapping to a float number.
    # Requires:
    #       <minor> = [0, 1, 2, ..., 9]
    # Compare versions, larger one is the latest one.
    # For example:
    #       9.2 > 9.1 > 8.0 > 7.9
    # certain Model may require minimum version number
    version     : 11.0
    format      : YAML  # the format of this configuration file
IO:  # I/O settings
    base_dir        : ./  # path should end with "/"
    data_file       : scft_out  # prefix of an output data file
    param_file      : param_out  # prefix of an output parameter file
    q_file          : q_out  # prefix of an output propagator data
    is_display      : true  # whether to display information
    is_save_data    : true  # whether to save data files
    is_save_q       : false  # whether to save propagator data
    # interval in unit of SCFT cycle for display
    display_interval: 100
    # interval in unit of SCFT cycle for recording data
    record_interval : 10
    # interval in unit of SCFT cycle for saving files
    # Use small interval to monitor intermediate results
    # Use large interval to avoid saving any intermediate results
    save_interval   : 20000
Model:  # SCFT model description
    # SCFT models, currently implemented are
    #       [AB, AB3+A]
    model           : AB
    # number of chain types
    # Example:
    #       AB + BC + C + M
    #       n_chains = 4
    n_chain         : 1
    # A list contains number of blocks for each chain.
    # For homopolymer and small molecules, n_block = 1.
    # We refer blocks, homopolymers, and small molecules to components.
    # Then number of components, n_component, is the sum of this list.
    n_block         : [2]
    # A list of the physical segment length of each component.
    # Size of this list is n_component.
    # Taking AB + C + M as an example,
    # where AB is an A-B diblock copolymer),
    # C is a homopolymer,
    # M is a small molecules.
    # Then, the returning list is
    #       [bA, bB, bC, bM]
    a               : [1.0, 1.0]
    # A list of the relative length of each component.
    # Size of this list is n_component.
    # Note the meaning of f depends on the choice of base.
    # For example, for an AB + C system, the list of f is
    #       [0.2, 0.8, 0.6]
    # which may mean
    #       f_A = N_A / N_AB
    #       f_B = N_B / N_AB
    #       f_C = N_C / N_AB
    # where N_AB = N_A + N_B.
    # Or, equivalently, f may write as
    #      [0.125, 0.5, 0.375]
    # which means
    #      f_A = N_A / N_ABC
    #      f_B = N_B / N_ABC
    #      f_C = N_C / N_ABC
    # where N_ABC = N_A + N_B + N_C.
    # The list is optional when Algorithm_MDE.f_mode = fix-ds.
    f               : [0.5, 0.5]
    # A list of the volume fraction of each chain specie.
    # Size of this list is n_chain.
    # In canonical ensemble, it is the volume fraction $\phi$.
    # In grand canonical ensemble, it is the activity $z$.
    # For example, in canonical ensemble
    #       AB + C
    #       phi = [phi_AB, phi_C]
    # where phi_AB + phi_C = 1.0 for mass conservation.
    # In grand canonical ensemble
    #       phi = [z_{AB}, z_C]
    phi             : [1.0]
    # A list of (\chi N) of each pair of components.
    # For n components, there are at most
    #       n * (n-1) / 2
    # (\chi N)s, where n = n_component.
    # These (\chi N)s are listed in the following way,
    #       AB + C + M
    #       [chiN_AB, chiN_AC, chiN_AM, chiN_BC, chiN_BM, chiN_CM]
    # (\chi N) between same type of component can be denoted as 0.
    chiN            : [30]
    is_compressible : false  # compressibility, [true, false]
    # for polymer brush
    graft_density   :
    # for implicit solvent
    excluded_volume :
UnitCell:  # unit cell description
    # Crystal system type of the unit cell
    # Available choices are
    # 1D:
    #       [lam]
    # 2D:
    #       [square, rect, hex]
    # 3D:
    #       [oblique, hex, cubic, tegragonal, orthorhombic,
    #        trigonal, monoclinic, triclinic]
    # All inputs are case-insensitive.
    CrystalSystemType   : Lamellar
    # Length and angles of a unit cell.
    #       [a, b, c, alpha, beta, gamma]
    # b, c should not have value for 1D.
    # c should not have value for 2D.
    a                   : 4.0
    b                   :
    c                   :
    alpha               :
    beta                :
    gamma               :
    # For Python package gyroid use only.
    # Not implemented in PolyOrder::Config.
    SymmetryGroup       :
    N_list              : []
    c_list              : []
Grid:  # numerical grid description
    # Grid dimension. Choose one of
    #       [1, 2, 3]
    dimension               : 1
    # Discrete points along each dimension
    #       [Lx, Ly, Lz]
    # For dimension = 1, Ly and Lz must be 1
    # For dimension = 2, Lz must be 1
    Lx                      : 64
    Ly                      : 1
    Lz                      : 1
    # Confinement settings
    # Confinement geometry. Choose one of
    #       [None, line, slit, slab, cube, disk, cylinder, sphere]
    # Currently, only [None, line, slit, slab] are implemented.
    # All inputs are case-insensitive.
    confine_geometry        : None
    # Grid type along each dimension. Choose one of
    #       [regular, chebyshev]
    # All inputs are case-insensitive.
    # For dimension = 1, grid_type_y and grid_type_z is optional.
    # For dimension = 2, grid_type_z is optional.
    grid_type_x             : Regular
    grid_type_y             :
    grid_type_z             :
    # A three-element vector describes the boundary condition:
    #       alpha * du/dx + beta * u = gamma
    # the vector is
    #       [alpha, beta, gamma]
    # See the definition of DBC, NBC, RBC, and PBC in cheb++ package.
    BC_coefficients_left    : []
    BC_coefficients_right   : []
    # Grid initialization
    # Way to initialize SCFT. Choose one of
    #       [field, density, propagator]
    # All inputs are case-insensitive.
    scft_init_type          : field
    # Way to initialize the numerical grid. Choose one of
    #       [random, file, constant]
    # All inputs are case-insensitive.
    gridInitType            : file
    # If gridInitType is random, then this option gives the random seed.
    # If random_seed is 0 or empty, then random seed is automatically
    # generated from current machine state.
    random_seed             :
    # If gridInitType is file, then this option gives the name of the
    # data file.
    field_data              : field_in_64.mat
Algorithm_MDE:  # description of the algorithm for solving MDE.
    # Algorithms, currently implemented are
    #       [OS, RQM4, ETDRK4]
    # All inputs are case-insensitive.
    algorithm       : RQM4
    # Mode for specifying the volume fraction of each component.
    # Choose one of
    #       [fix-ds, fix-Ms]
    # All options are case-insensitive.
    # Mode: fix-ds
    #       f = ds * (Ms-1)
    # Both ds and Ms should be provided.
    # Mode: fix-Ms
    #       ds = f / (Ms-1)
    # Both f and Ms should be provided.
    f_mode          : fix-Ms
    # A list of the size of contour step for each component.
    # Size of this list is n_component.
    # For small molecules, ds = 1.0
    # Example:
    #       AB + C + M
    #       [ds_A, ds_B, ds_C, 1.0]
    # It is optional when f_mode = fix-Ms
    ds              : [0.01, 0.01]
    # A list of the number of discrete contour points for each component.
    # Size of this list is n_component.
    # For small molecules, Ms = 1.
    # Example:
    #       AB + C + M
    #       [Ms_A, Ms_B, Ms_C, 1]
    Ms              : [51, 51]
    # Schemes for the ETDRK4 method. Choose one of
    #       [Cox-Matthews, Krogstad]
    # All options are case-insensitive.
    etdrk4_scheme   : Cox-Matthews
    # Number of discrete points along contour
    # for ETDRK4 coefficients compuation.
    # Can be left as empty, then the default value will be used.
    etdrk4_M        :
Algorithm_SCFT:  # Description of the SCFT algorithm
    # Algorithms. Choose one of
    #       [EM, Anderson, SIS, ETD]
    # Consult specific Model builder for the availability
    # of these algorithms.
    algorithm           : Anderson
    # A list of relaxation parameters.
    # Size of this list is (n_component + 1).
    # For incompressible model, the last element is the relaxation
    # coefficeint for incompressible field.
    # For compressible model, the last element is the
    # compressibility parameter.
    #lam                 : [0.05, 0.05, 5.0]  # for EM/ETDRK4
    lam                 : [0.9, 0.9, 5.0]  # for Anderson
    # Minimum number of SCFT cycles.
    min_iter            : 10
    # Maximum number of SCFT cycles.
    max_iter            : 500
    # Stop criteria.
    # The difference of H between neighboring SCFT cycles.
    thresh_H            : 1.0e-6
    # The residual error.
    thresh_residual     : 1.0e-8
    # The actual incompressiblity.
    thresh_incomp       :
    # Number of history for Anderson mixing algorithm.
    n_Anderson_mixing   : 10
Algorithm_Cell_Optimization:  # Description of cell size optimization algo
    # Choose one of
    #       [single, Brent]
    # All options are case-insensitive.
    algorithm       : Brent
    # Tolerance of the cell size of diffrence for Bent optimizaiton algo.
    tol_cell        : 1.0e-3
    # Maximum number of iterations allowed for Brent optimization algo.
    max_iter_cell   : 30
    # Cell size vector
    #       [a, b, c]
    # For Brent optimization, this is the initial cell size.
    batch_cell_min  : [4.0, 0.0, 0.0]
    # For Brent optimization, this is the search step size.
    batch_cell_step : [1.0, 0.0, 0.0]
    # For Brent optimization, this is not used.
    batch_cell_max  : []
Algorithm_Contour_Integration:  # Description of contour integration algo.
    # Choose one of
    #       [trapz, simpson]
    # All options are case-insensitive.
    algorithm       : Simpson

Notes

All Format

No difference will be caused by changing the suquences of the parameters.
BC_coefficients_left and BC_coefficients_right vectors are $(a,b,c)$ where $au_x + bu = c$.
The minimum tol_cell is 3.0e-8.

INI Only

Comments can be added as a “#”-leading-line.
Key and value should be comparted by a equal sign, and all blank character between keys and values will be neglected automatically.
The trailing whitespaces may cause serious problem, they should be removed carefully.
Support section name. Section name is enclosed by square bracket.

YAML Only

For YAML format, block comments are lead by “#”, and inline comments are also lead by “#” but should have at least one space between “#” and main content.

Changelog

Version 11.0

Now configuration file is in YAML format.

Version 10.3

Add Model.phi to specify the volume fraction of each specie.

Version 10.2

Add Grid.scft_init_type to specify initialization densities or potential fields or propagators.

Version 10.1

Add Algorithm_MDE.f_mode to allow controlling how to determine volume fraction.

Version 10.0

Add Version, Algorithm_MDE, Algorithm_SCFT, Algorithm_Cell_Optimization, Algorithm_Contour_Integration sections.
Remove SCFT.is_batch_cell
Move some keys to new sections
Break SCFT section into IO and Algorithm_SCFT sections.
Use tests/test_config_v10 to test whether a configuration file is consistent internally.

Version 9.0 and before

2014.06.12 Compatible with current version of Polyorder.
2013.07.31 Compatible with scftpy/bulk.
2013.06.24 Add q_file.
2012.11.08 Add BC support.
2012.10.11 Currently, only supports one type of chain.
2012.10.10 Break compatability with previous version. Only for scftpy use. Move Ms from Model section to Grid section.
2012.4.24 Add dielectric_constant, charge_distribution to Algorithm section. Delete isAnnealed from Model section.
2012.4.22 Add Algorithm section
2012.4.20 Add fft2mg_mode and fft2mg_interp
2012.4.18 Add gensym.py support

ToDo List

Refractor Config.cc/Config.h to let Config be a format independent class. Support both INI and YAML format. And easy to support other formats, such as JSON, XML, etc.

Reference

Polyorder

Polyorder Configuration File was originally published by Yi-Xin Liu at Polyorder on April 06, 2015.

Simpson's Rule and Other Fourth-Order Quadrature Formulas

2020-04-11T00:00:00-00:00

In this post we will list some popular closed-, open-, and semi-open form of numerical integration formulas for Simpson’s rule and other 4th order algorithms.

1. Closed formulas

By dividing the closed interval $[a, b]$ into $N-1$ uniform subintervals with length of $h=(b-a)/(N-1)$, the extended Simpson’s rule is given by (1)

\[\begin{aligned} \label{simpson} \int_a^b f(x)dx = & \frac{h}{3} \left( f_0 + 4f_1 + 2f_2 + 4f_3 + \cdots + 2f_{N-3} + 4f_{N-2} + f_{N-1} \right) \\ & -\frac{b-a}{180}f^{(4)}(\xi)h^4 \end{aligned}\]

where $f_i = f(x_i)$ for $x_i = ih$, and $\xi$ is in $(a, b)$. The number of points, $N$, must be odd, meaning that there are even number of subintervals. This requirement is a consequence of the fact that the coefficients alternate in a specific pattern, namely there are $n$ pairs of $(4, 2)$ coefficient terms plus an extra $4$-coefficient term and two end-point terms. Therefore, there are $2n+3$ terms in total, while $2n+3$ is always odd.

To relax the constraint of odd number of points, which is important for situations when it is not convenient to freely choose the number of points such as in experiments or numerical simultaions, we can use

\[\begin{aligned} \label{three-term} \int_a^b f(x)dx = h \bigl( &\frac{9}{24}f_0 + \frac{28}{24}f_1 + \frac{23}{24}f_2 + \\ & f_3 + f_4 + \cdots + f_{N-5} + f_{N-4} + \\ & \frac{23}{24}f_{N-3} + \frac{28}{24}f_{N-2} + \frac{9}{24}f_{N-1} \bigr) \\ & +O(h^4) \end{aligned}\]

Note that the coefficients are no longer alternate except the first and last three terms. See Arif Zaman’s Note (2) for a derivation of the exact form of the error. Other non-alternate forms of fourth-order quadrature formulas are possible. An example from Wolfram Mathworld (3)

\[\begin{aligned} \label{four-term} \int_a^b f(x)dx = h \bigl( &\frac{17}{48}f_0 + \frac{59}{48}f_1 + \frac{43}{48}f_2 + \frac{49}{48}f_3 + \\ & f_4 + f_5 + \cdots + f_{N-6} + f_{N-5} + \\ & \frac{49}{48}f_{N-4} + \frac{43}{48}f_{N-3} + \frac{59}{48}f_{N-2} + \frac{17}{48}f_{N-1} \bigr) \\ & +O(h^4) \end{aligned}\]

2. Open and semi-open formulas

Sometimes open and semi-open formulas are required. Below is a fourth-order open formula for $(0, N-1)$

\[\begin{aligned} \label{open-three-term} \int_a^b f(x)dx = h \bigl( &\frac{55}{24}f_1 - \frac{4}{24}f_2 + \frac{33}{24}f_3 + \\ & f_4 + f_5 + \cdots + f_{N-6} + f_{N-5} + \\ & \frac{33}{24}f_{N-4} - \frac{4}{24}f_{N-3} + \frac{55}{24}f_{N-2} \bigr) \\ & +O(h^4) \end{aligned}\]

And here is a fourth-order semi-open formula for $(0, N-1]$

\[\begin{aligned} \label{semiopen-three-term} \int_a^b f(x)dx = h \bigl( &\frac{55}{24}f_1 - \frac{4}{24}f_2 + \frac{33}{24}f_3 + \\ & f_4 + f_5 + \cdots + f_{N-5} + f_{N-4} + \\ & \frac{23}{24}f_{N-3} + \frac{28}{24}f_{N-2} + \frac{9}{24}f_{N-1} \bigr) \\ & +O(h^4) \end{aligned}\]

Note that above formulas share the same discrete scheme as the closed formulas.

Reference

Press, W. H.; Teukolsky, S. A.; Vetterling, W. T.; Flannery, B. P. Numercial Recipes: The Art of Scientific Computing; 3rd ed.; Cambridge University Press: Cambridge, 2007.
Arif Zaman’s Note
An example from Wolfram Mathworld

Simpson's Rule and Other Fourth-Order Quadrature Formulas was originally published by Yi-Xin Liu at Polyorder on September 11, 2014.

mpltex: A Tool for Creating Publication Quality Plots

2020-04-11T00:00:00-00:00

This post serves as a tutorial to the mpltex Python package, a tool for producing publication quality plots using matplotlib. LaTeX formatting for axis titles, legends, and texts in the figure is supported. The internal matplotlib color cycle is replaced by Tableau classic 10 color scheme which looks less saturated and more pleasing to eyes. Other available color schemes for multi-line plots are ColorBrewer Set 1 and Tableau classic 20. mpltex also provide a way to generate highly configurable line styles with colors, line types, and line markers. Hollow markers are supported.

Creating a publication-quality plot is not an easy job. One needs to consider a dozen of factors:

The figure size should be set explicitly to match journal specific value. For exmaple, journals published by American Chemical Society (ACS) allows a maximum 3.25-inch width figure for single-column and a maximum 7-inch width figure for double-column.
The font family should be customized. Most of the time, “Times New Roman” is a safe choice. You should consult the journal author guide for more information.
The font size also needs to be set properly.
The linewdith of axis, axis ticks, line arts, the format of legend, the colors are all important factors affects the final looking of a plot.
The file format of a figure should be chosen carefully. For most publishers, EPS is a good choice for line arts and other simple 2D arts, such as histograms, power spectra, bar charts, errorcharts, scatterplots.

Matplotlib, a Python 2D plotting library, is an amazingly flexible tool to create scientific plots. You can create various 2D arts with just a few lines of Python code. A plot created by the default settings of matplotlib looks like

The code for producing the above plot is

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import numpy as np
import matplotlib.pyplot as plt

def my_plot(t):
    fig, ax = plt.subplots(1)
    ax.plot(t, t, label='$t$')
    ax.plot(t, t**2, label='$t^2$')
    ax.plot(t, t**3, label='$t^3$')
    ax.plot(t, t**4, label='$t^4$')
    ax.plot(t, np.log(1+t), label='$\ln(1+t)$')
    ax.plot(t, t**(1./2), label='$t^{1/2}$')
    ax.plot(t, t**(1./3), label='$t^{1/3}$')

    ax.set_xlabel('$t$')
    ax.set_ylabel('$f(t)$')
    ax.legend(loc='best', ncol=2)
    fig.tight_layout(pad=0.1)
    fig.savefig('matplotlib-raw')

t = np.arange(0, 1.0+0.01, 0.01)
my_plot(t)
plt.close('all')

This plot is obviouly not ready for journal publication. The font size is too small. The line width for axes, ticks, and profiles are too thin. I also don’t like the border around the figure legend. And the line colors are too saturated and are not pleasing to look at.

To fix all these problems, I developed a Python package, mpltex, to customize the behavior of matplotlib for creating publication-quality plots. With mpltex, one can easily generate the following plot perfectly fufilled the requirements of ACS journals

by just adding ONE LINE (besides the import package line import mpltex) before the definition of funciton my_plot in the above code block

@mpltex.acs_decorator

This line uses the decorator @acs_decorator from mpltex to decorate the function my_plot.

Currently, mpltex (v0.6.1) provides five decorators: @acs_decorator, @aps_decorator, @rsc_decorator, @presentation_decorator, and @web_decorator. @acs_decorator, @aps_decorator, and @rsc_decorator are designed for creating plots for journals published by American Chemical Society (ACS), American Physical Society (APS), and Royal Society of Chemistry (RSC), respectively. Journals from other publishers are yet to be supported. Hopefully, other decorators for this purpose will be available in the near future. @presentation_decorator creates plots in the PDF format and is suitable to be incorporated in presentation slides (especially convenient for Keynote and Beamer). @web_decorator produces plots in the PNG format to be used in webpages.

In addition to these decorators, mpltex also provides a convenient generator, linestyle_generator, to generate various line styles to help create line arts with markers. The following codes convert the above plot into line profiles with different line styles and line markers. (To use following codes, please update to mpltex v0.6.1 or later.)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import numpy as np
import matplotlib.pyplot as plt

import mpltex

@mpltex.acs_decorator
def my_plot(t):
    fig, ax = plt.subplots(1)
    linestyles = mpltex.linestyle_generator()
    ax.plot(t, t, label='$t$', **next(linestyles))
    ax.plot(t, t**2, label='$t^2$', **next(linestyles))
    ax.plot(t, t**3, label='$t^3$', **next(linestyles))
    ax.plot(t, t**4, label='$t^4$', **next(linestyles))
    ax.plot(t, np.log(1+t), label='$\ln(1+t)$', **next(linestyles))
    ax.plot(t, t**(1./2), label='$t^{1/2}$', **next(linestyles))
    ax.plot(t, t**(1./3), label='$t^{1/3}$', **next(linestyles))

    ax.set_xlabel('$t$')
    ax.set_ylabel('$f(t)$')
    ax.legend(loc='best', ncol=2)
    fig.tight_layout(pad=0.1)
    fig.savefig('mpltex-acs-line-markers')

t = np.arange(0, 1.0+0.05, 0.05)
my_plot(t)
plt.close('all')

The resulted plot should look like

This plot is created by the default linestyle_generator. linestyle_generator has four arguments: colors, lines, markers, and hollow_styles. All are Python iterables (list, tuple, or other iterable objects). If you don’t want to cycle one of these, just pass an empty list or None to that argument. Below are examples of some most useful line-art styles.

Plot created by mpltex, cycling colors and line markers using

linestyles = mpltex.linestyle_generator(lines=[])

Plot created by mpltex, cycling colors and line styles using

linestyles = mpltex.linestyle_generator(markers=[])

Plot created by mpltex, cycling colors and filled markers using

linestyles = mpltex.linestyle_generator(lines=[], hollow_styles=[])

Plot created by mpltex, cycling colors, line styles and filled markers using

linestyles = mpltex.linestyle_generator(hollow_styles=[])

Plot created by mpltex, cycling colors and filled markers connected by solid lines using

linestyles = mpltex.linestyle_generator(lines=['-'], hollow_styles=[])

Plot created by mpltex, cycling all markers connected by solid lines using

linestyles = mpltex.linestyle_generator(lines=['-'])

And you can do something really cool by passing some specially designed combo arguments, such as

linestyles = mpltex.linestyle_generator(colors=[],
                                        lines=['-',':'],
                                        markers=['o','s'],
                                        hollow_styles=[False, False, True, True],)

This will create a black-white line art containing selected line styles and markers.

Reference

mpltex: A Tool for Creating Publication Quality Plots was originally published by Yi-Xin Liu at Polyorder on September 09, 2014.

A Quick Guide to the Self-Consistent Field Theory in Polymer Physics

2020-04-11T00:00:00-00:00

In this post I will present an detailed (informal) derivation of the self-consistent field theory (SCFT) for many-chain polymer systems. I start from the continuous Gaussian chain model. Then the Gaussian chain in an external field is described. After that, a system of multiple two-bead chains as a simplified model for many-chain model is examined. Then this approach is extended to many-chain A-B block copolymer system. Finally, as an application of this derivation, we derive SCFT for many-chain A-B diblock copolyelectrolyte solutions.

1. Introduction

The self-consistent field theory (SCFT) for many-chain systems is obtained by imposing a mean-field approximation to simplify the statistical field theories. The statistical field theories can be constructed from the particle-based model by carrying out a particle-to-field transformation.

The general approach for a particle-to-field transformation is to invoke formal techniques related to Hubbard-Stratonovich transformations, which have the effect of decoupling interactions among particles (or polymer segments) and replacing them with interactions between the particles and one or more auxiliary fields.

2. Continuous Gaussian Chain Model

3. Single Continuous Gaussian Chain in External Field

4. Many Chain Model for Two-Bead Chains

5. Many Chain Model for A-B Block Copolymers

6. Many Chain for Solutions of A-B Diblock Copolyelectrolytes

Download Fulltext in PDF

A Quick Guide to the Self-Consistent Field Theory in Polymer Physics was originally published by Yi-Xin Liu at Polyorder on May 26, 2014.

Lecture notes in polymer physics

2015-04-15T00:00:00-00:00

This material is based on the lectures given by Prof. A. C. Shi from Jan. 12 to 14, 2009 at Fudan University, with some additional derivation details.

Download Fulltext in PDF

1. One Mode Approximation

Assume the function to be approximated can be expanded in a series

\[\phi (x) = \sum_n \phi_n (x) e^{ik_nx}\]

where $n = 0, \pm 1, \pm 2, \cdots$. For one mode approximation, only the first three terms are taken, that is

\[\phi (x) = \phi_0 (x) e^{ik_0x} + \phi_{-1} (x) e^{ik_{-1}x} + \phi_1 (x) e^{ik_1x}\]

In two and higher dimensional space, variables, $x$ and $k$, become vectors $\mathbf{x}$ and $\mathbf{k}$. To approximate high dimensional functions, one should consider the origin and its neighbors. Using two-dimensional hexagonal lattice as an example, one mode approximation retains only the origin term and the six nearest neighbors, depicted in Figure 1.

Figure 1

One mode approximation is not a good approximation for square wave. To expand square wave function according to eq. 1, $\phi_n$ decrease with $n$ in an order of $1/n$, which is very slow and a large number of terms are required to approximate it well enough. This also explains that spectral method is not suitable to deal with strong segregation systems where the density profile resembles a square wave function.

2. Spinodal Decomposition and Nucleation

3. Conserved and Non-conserved Order Parameter

4. Ginzburg Criteria

5. Scattering Theory

6. Excluded Volume and Incompressibility

7. Structure Factor for Single Ideal Gaussian Chain

8. Response Function and Fluctuation-Dissipation Theorem

9. Random Phase Approximation

10. Landau Theory and Phase Transition

11. Variational Mean-Field Theory

12. Perturbation Theory

13. Weak Segregation Theory and Strong Segregation Theory

14. Saddle Point Approximation

Lecture notes in polymer physics was originally published by Yi-Xin Liu at Polyorder on May 26, 2014.

Polyorder

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

Tutorial and A Template for Blogging with the LYX Jekyll Theme

Table of Contents

Heading

Front Matter