%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%   BornAgain Developers Reference
%%
%%   homepage:   http://www.bornagainproject.org
%%
%%   copyright:  Forschungszentrum Jülich GmbH 2015-2020
%%
%%   license:    Creative Commons CC-BY-SA
%%
%%   authors:    Scientific Computing Group at MLZ Garching
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\chapter{Particle assemblies}\label{sec:Assemblies}%
\index{Particle!assemblies|(}%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Generic scattering cross section}\label{SAssX}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\def\sp{\text{p}} \def\sm{\text{m}} \def\mz{\overline{z}}

\index{Nanoparticle|see{Particle}}%
\index{Mesoparticle|see{Particle}}%
In many important GISAS applications, fluctuations of the refractive
index are due to \E{droplets}, \E{islands}, \E{inclusions} or
\E{holes} \index{Droplet}%
\index{Island}%
\index{Inclusion}%
\index{Hole}%
of a mesoscopic size (nanometer to micrometer).  In the
following, all such inhomogeneities will be described as \E{particles}
that are embedded in a material layer.  In BornAgain, a sample can be
decorated with an arbitrary number of different particles species.
For readability, in the following only \E{one} kind of embedded
particles will be considered; the generalization to several species is
straightforward.

The matrix material has a SLD~$v_\sm(z)$ that may or may not vary
with~$z$.  The SLD of the entire sample, consisting of the matrix and
an assembly of particles of type~$\sp$, shall be written
\begin{equation}\label{Evmpr}
  v(\r) = v_\sm(z) + \Delta v_\sp(\r).
\end{equation}
If the particles are homogeneous, then
\begin{equation}\label{EDvpHomo}
  \Delta v_\sp(\r) = \left(v_\sp-v_\sm(z)\right)\chi_\sp(\r)
\end{equation}
with the indicator function
\begin{equation}\label{EdefChiP}
  \chi_\sp(\r)\coloneqq\left\{\begin{array}{ll} 1&\text{~if $\r$ in
    p,}\\[.2ex] 0&\text{~otherwise.} \end{array}\right.
\end{equation}
\nomenclature[1χ032 2p000]{$\chi_\sp(\r)$}{Indicates whether $\r$ is in particle of type~$\sp$}%
\index{Indicator function}%
The following formalism, however, shall not rely on \cref{EDvpHomo}, but
also allow for soft particles for which $\Delta v_\sp(\r)$ is a
continuous function of~$\r$.

The sum~\cref{Evmpr} has the same form as the
decomposition~\cref{Edecompose_vz}.  Nonetheless, implementations are
free to choose a convenient mean SLD~$\mv(z)$.  Currently, BornAgain
uses $\mv(z)\coloneqq v_\sm(z)$, though we suspect that for non-dilute
particles $\mv(z)\coloneqq v_\sm(z) + \overline{\Delta v_\sp(\r)}$
would yield a more accurate scattering simulation.  With
$\mv(z)\coloneqq v_\sm(z)$, we have $\delta v_l(\r) = \Delta
v_\sp(\r)$.  Outside the layer that contains the embedded particles,
$\delta v_l(\r)=0$.

With the factorization~\cref{Ekpar}, the scattering matrix
element~\cref{Etrama} becomes
\begin{equation}\label{Escamatrix2}
  \braket{\psi_\si|\delta v|\psi_\sf} = \int\!\d^2 r_\plll\,
  \e^{i\q_\plll \r_\plll} \int\!\d z\, \phi^*_\si(z) \delta v(\r)
  \phi_\sf(z).
\end{equation}
The SLD distribution of a set of identical particles, located at
positions~$\R_j$, can be written as a sum
\begin{equation}\label{Echihomo}
  v_\sp(\r) = \sum_j F(\r-\R_j).
\end{equation}
In many applications, particles are not all identical.  They may vary
in shape, size, orientation, or refractive index profile.  These
degrees of freedom shall be denoted by a parameter vector~$\v{T}_j$.
Specifically for a $2+1$~dimensional sample, it is convenient to
restrict the coordinate vectors~$\R_j$ to the $xy$~plane, and to
redefine~$\v{T}_j$ to include the vertical particle component
of~$\R_j$.  In consequence, \cref{Echihomo}~is replaced by
\begin{equation}\label{Echihetero}
  v_\sp(\r) = \sum_j F(\r-\R_{j\plll},\v{T}_j).
\end{equation}
With the \E{DWBA form factor}
\begin{equation}\label{EcFdef}
  \FD_{\si\sf}(\q_\plll,\v{T}) \coloneqq \int\!\d^2 r_\plll\,
  \e^{i\q_\plll \r_\plll} \int\!\d z\, \phi^*_\si(z) F(\r,\v{T})
  \phi_\sf(z),
\end{equation}
the scattering matrix element~\cref{Escamatrix2} becomes
\begin{equation}\label{EsumRF}
  \braket{\psi_\si|\delta v|\psi_\sf} = \sum_j \e^{i\q_\plll
    \R_{j\plll}} \FD_{\si\sf}(\q_\plll,\v{T}_j).
\end{equation}
The elastic scattering cross section~\cref{Exsection} can be written
as
\begin{equation}\label{Exsection2}
  \xElas = \sum_{jk} \e^{i\q_\plll(\R_{j\plll}-\R_{k\plll})}
  \FD_{\si\sf}(\q_\plll,\v{T}_j) \FD_{\si\sf}^*(\q_\plll,\v{T}_k).
\end{equation}

In the following \Cref{SFormFactor} we discuss the form
factor~$\FD_{\si\sf}$.  The remainder of this chapter is devoted to
the positional term and to the coupling between particle form and
position; various approximations are used to make~\cref{EsumRF}
manageable.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Particle form factor}\label{SFormFactor}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\index{Particle!form factor|see{Form factor}} \index{Form factor|(}

To compute the DWBA form factor for a generic vertical
wavefunction~$\phi(z)$, it is advantageous to exchange the order of
integration in~\cref{EcFdef}:
\begin{equation}\label{EcFx}
  \FD_{\si\sf}(\q_\plll,\v{T}) = \int\!\d z\, \phi^*_\si(z)
  F(q_\plll,z,\v{T}) \phi_\sf(z).
\end{equation}
The function
\begin{equation}\label{EFqpadef}
  F(\q_\plll,z,\v{T}) \coloneqq \int\!\d^2 r_\plll\, \e^{i\q_\plll
    \r_\plll} F(\r,\v{T})
\end{equation}
is an \E{intermediate Fourier transform}, since it is a transform in
some, but not all the coordinates; more specifically, it may be called
the \E{horizontal Fourier transform}.  For homogeneous particles, it
is the \E{shape transform} of horizontal cuts.

For samples that only consist of homogeneous layers the wavefunction
is the sum of two plane waves~\cref{Ephizwj}.  With the
notations~\cref{Eudef}, the DWBA form factor~\cref{EcFx} becomes
\begin{equation}\label{EcFres1}
  \FD_{\si\sf}(\q_\plll,\v{T}) = \sum_l \sum_u C^u_l F_l(\q^u_l,\v{T})
\end{equation}
with
\begin{equation}\label{EFqTdef}
  F_l(\q,\v{T}) \coloneqq \int\!\d z\, \e^{iq_\perp z}
  F(\q_\plll,z,\v{T}) \chi_l(z).
\end{equation}
Inserting~\cref{EFqpadef}, we find that this is a plain
three-dimensional Fourier transform:
\begin{equation}\label{EFqT3d}
  F_l(\q,\v{T}) = \int\!\d^3 r\, \e^{i\q \r} F(\r,\v{T})\chi_l(z).
\end{equation}
Except for the restriction to layer~$l$, it is the standard form
factor that appears in the regular (plane-wave) Born approximation.
Therefore, it is occasionally called the \E{Born form factor}, and so
we will call it.  \Cref{EcFres1,EFqTdef} remain applicable if the
plane waves~$\phi^\pm(z)$ are \E{damped} due to an imaginary part of
the refractive index.

\Work{Currently, the summation over~$l$ in~\cref{EcFres1} is not
  implemented in BornAgain.  Therefore particles must not extend
  beyond layer interfaces.  This restriction will be lifted in one of
  the next releases.}

To describe how~\cref{EFqT3d} is evaluated in BornAgain, we need to
specify some of the parameters contained in the generic parameter
vector $\v{T} \coloneqq (\Delta v_\sp,Z,\v{\Omega},\v{U})$: $\Delta
v_\sp$ is the SLD difference between the particle and the embedding
matrix, as discussed in~\cref{SAssX}; for an inhomogeneous particle,
it is some reference value obtained e.~g.\ from the maximum SLD.  $Z$
is the vertical location of the particle; in our formalism, it is the
vertical component of the position vector~$\R$.  $\v{\Omega}$ is a
tuple of rotation angles; they determine a rotation
matrix~$D_{\v{\Omega}}$ that shall be defined by its action
\begin{equation}\label{ErOm}
  F(\r,\Delta v_\sp,Z,\v{\Omega},\v{U}) =
  F(D_{\v{\Omega}}^{-1}\r,\Delta v_\sp,Z,\v{0},\v{U}).
\end{equation}
Finally, $\v{U}$ collects all remaining parameters, among them size
and shape parameters that determine the geometry and thereby the
refractive index profile of the particle.  With this, we can express
the generic Born form factor as
\begin{equation}\label{EqOm}
  F(\q,\Delta v_\sp,Z,\v{\Omega},\v{U}) = \Delta v_\sp \e^{iq_\plll Z}
  F(D_{\v{\Omega}}\q,\v{U}),
\end{equation}
introducing the standard form factor
\begin{equation}\label{EFqPdef}
  F(\q,\v{U}) \coloneqq F(\q,1,0,\v{0},\v{U}).
\end{equation}

BornAgain comes with a comprehensive library of form factors,
described in a dedicated
\href{http://apps.jcns.fz-juelich.de/src/BornAgain/FFCatalog.pdf}{Form
  Factor Catalog}.  \index{Form factor|)}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Decoupling approximations}\label{Spartidis}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

In the DWBA matrix element~\cref{EsumRF}, particle positions,
orientations, shapes, and sizes can be coupled in arbitrary ways.  To
proceed any further, we need to specify this coupling at least in
statistical terms.  This can in principle be done in two different
ways: Either through physical models, implemented within BornAgain, or
by loading a representative set $\{\R_i,\v{T}_i\}$ from an external
\E{morphology} file that could be generated from simulations, or from
electron microscopy images.

\addtocounter{footnote}{1}
% see http://tex.stackexchange.com/questions/35298 how to repair hyperref
\Note{\indent Import of \E{morphology data}, pioneered by \IsGISAXS\ \cite[Sec.~3.3]{Laz06},
\index{IsGISAXS@\string\IsGISAXS!morphology data}%
\index{Morphology!as input data}%
is not yet implemented in \BornAgain, and not on our agenda.
Please contact us if you have a use case.}

BornAgain provides various physical models for the distribution of
$\R_i$ and $\v{T}_i$.  Except if uniform particles form a perfect
two-dimensional crystal, some degrees of freedom will be more or less
disordered.  Therefore the models need to be formulated in a
statistical language.  That formalism is then versatile enough to also
cover any degree of order.

To prepare a statistical formulation, we encode the particle
coordinates in a distribution function
\index{Distribution function!embedded particles}%
\index{Particle!distribution function}%
\index{Statistics!particle distribution}%
\begin{equation}\label{EPDdeltas}
  \PD(\r,\v\tau,\v\tau') \coloneqq \sum_{jk}
  \delta^{2}(\r-(\R_{j\plll}-\R_{k\plll}))
  \delta^{n}(\v\tau-\v{T}_j)\delta^{n}(\v\tau'-\v{T}_k).
\end{equation}
The exponents denote the dimensionalities of the delta-functions;
$n$~is the dimensionality of~$\v\tau$.  Its total integral is
\begin{equation}\label{EPint}
  \int\!\d^2r\, \int\! \d\v{\tau}\, \d\v{\tau}' \PD(\r,\v\tau,\v\tau')
  = N_p^2,
\end{equation}
where~$N_p$ is the number \nomenclature[2n122 2p010]{$N_p$}{Number of
  scattering centers}% of particles, the integration over $\r$ is
restricted to the horizontal plane, and the differential $\d\v{\tau}$
is to be understood as $\d^n\tau$.  In later approximations,
\cref{EPint} will be a normalization requirement.  The differential
cross section~\cref{Exsection2} can now be written as
\begin{equation}\label{Epdm1}
  \xElas =\int\!\d^2r\, \e^{i\q_{\plll}\r}\!  \int\! \d\v{\tau}\,
  \d\v{\tau}' \PD(\r,\v\tau,\v\tau') \FD(\v\tau) \FD^*(\v\tau'),
\end{equation}
In the following, we will present different physical models that
provide computable approximations for the formally exact
distribution~\cref{EPDdeltas}.

For the time being, we only support models that make the following
assumption about the particle \E{properties} like shape, size, and
orientation (but \E{not} position) that are encoded in the vector~$\v
T_j$: \Note{\textbf{T-T decoupling approximation:} Properties of
  different particles are not correlated.}
\index{T-T decoupling approximation}%
In other words, the $\v T_j$ are independent and
identically distributed (\E{i.i.d.}) random variables.  They all have
the same distribution~$p(\v\tau)$.  Averages under this distribution
shall be denoted as
\begin{equation}\label{Epavg}
  \braket{f} \coloneqq \int\!\d\v\tau\,p(\v\tau)f(\tau).
\end{equation}
Pairs of particles have the distribution~$p(\v\tau)p(\v\tau')$, except
if the two particles are identical.  In consequence, the distribution
$\PD$ must have the form
\begin{equation}\label{EPbyG}
  \PD(\r,\v\tau,\v\tau') = N_p \{
  \delta(\r)p(\v\tau)\delta(\v\tau-\v\tau') +
  \left[\GD(\r|\v\tau,\v\tau') - \delta(\r)\right]
  p(\v\tau)p(\v\tau')\}
\end{equation}
with the conditional position correlation function~$\GD$.  Inserting
this in \cref{Epdm1} we obtain
\begin{equation}\label{EIdIc}
    \frac{1}{N_p}\xElas = I_\text{d}+I_\text{c}
\end{equation}
with the \E{diffuse} and \E{coherent} scattering intensities
\index{Diffuse scattering}% \index{Scattering!diffuse}%
\index{Coherent scattering}% \index{Scattering!coherent}%
\begin{eqnarray} I_\text{d}\label{EIddef} &\coloneqq&
          \braket{\left|\FD\right|^2}-\left|\braket{\FD}\right|^2,
          \\[2ex] I_\text{c}\label{EIcdef} &\coloneqq& \int\!\d^2r\,
          \e^{i\q_{\plll}\r}\!  \int\! \d\v{\tau}\, \d\v{\tau}'
          \GD(\r|\v\tau,\v\tau')p(\v\tau)p(\v\tau') \FD(\v\tau)
          \FD^*(\v\tau').
\end{eqnarray}
The diffuse intensity can be rewritten as
\begin{equation}\label{EIdDiff}
  I_\text{d} = \braket{\left|\FD-\braket{\FD}\right|^2},
\end{equation}
which shows that it is due to fluctuations of the single-particle form
factor.

To proceed further, we need to make approximations for the
distribution~$\GD$.  Only a few paracrystal models actually specify a
conditioning of~$\GD$ on the particle properties~$\v\tau,\v\tau'$.
For all other models, we assume the \Note{\textbf{R-T decoupling approximation:}
\index{R-T decoupling approximation}%
Particle positions do not depend on properties.}  Hence simply
$\GD(\r|\v\tau,\v\tau')=\GD(\r)$.  To distinguish $\GD(\r)$ from the
standard \E{pair correlation function}
\index{Pair correlation function}%
at atomic level, we will call it the \E{particle position correlation function}.
\index{Particle!position correlation function}%
The Fourier transform
\begin{equation}\label{ESqdef}
  \SD(\q) \coloneqq \int\!\d^2r\, \e^{i\q_{\plll}\r}\! \GD(\r)
\end{equation}
shall be called the \E{interference function}.
\index{Interference function}%.
It is the two-dimensional, mesoscale equivalent of the atomic \E{static structure factor}
\index{Static structure factor}%
(in crystallography also called \E{lattice factor}).
\index{Lattice factor}%
The coherent scattering intensity then takes the simple form
\begin{equation}\label{EIcFac}
  I_\text{c} = \SD(\q)
    \left|\braket{\FD}\right|^2.
\end{equation}
Together, the T-T and R-T decoupling make up the \E{decoupling
  approximation}
\index{IsGISAXS@\IsGISAXS!decoupling approximation}
of \IsGISAXS.\footnote {In the \IsGISAXS\ manual
\cite[Sec.~2.2]{Laz06}, the \E{decoupling approximation} (DA)
\index{Decoupling approximation}%
\index{DA|see{Decoupling approximation}}%
is opposed to the \E{local monodisperse approximation} (LMA)
\index{Local monodisperse approximation}%
\index{LMA|see{Local monodisperse approximation}}%
and the \E{size-spacing correlation approximation} (SSCA).
\index{Size-spacing correlation approximation}%
\index{SSCA|see{Size-spacing correlation approximation}}%
We can now disentangle this skew trichotomy: The LMA is opposite to
coherent superposition; it describes the incoherent sum
\index{Incoherent sum}%
of scattering from different coherence domains.
In \BornAgain, it can be emulated by averaging over
different simulated GISAS images (as described in \cref{Scoherlen}),
or by attaching different \texttt{ParticleLayout}s to a
\texttt{Layer}.  The SSCA is an alternative to the R-T decoupling
approximation.  In \IsGISAXS, and similarly in \BornAgain, it is only
available for paracrystals (\cref{SPara}).}  In BornAgain, R-T
decoupling is the default.  Only a few models explicitly introduce
some size-position coupling.  The following sections are therefore
mostly concerned with models for~$\SD(\q)$.

If a user-defined sample model leaves the interference function
unspecified, then the default (\texttt{InterferenceFunctionNone})
\index{InterferenceFunctionNone@\Code{InterferenceFunctionNone}}%
is simply $\SD(\q)=1$, which is a valid model for \E{dilute} particles.
\index{Dilute particles}%
\index{Particle!dilute assembly}%
$I_\text{c}$ then cancels the second term in~\cref{EIddef}, so that
the cross section~\cref{EIdIc} reduces to the incoherent sum
\begin{equation}\label{EIdInc}
  \frac{1}{N_p}\xElas = \braket{\left|\FD\right|^2}
\end{equation}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Lateral order of nanoparticles}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\iffalse By a \E{mesocrystal},
\index{Mesocrystal}%
\index{Crystal!mesoscopic|see{Mesocrystal}}%
we understand an assembly of \E{mesoscopic} particles
on a one- or two-dimensional lattice.
In BornAgain, we are nowhere concerned with the usual three-dimensional,
microscopic, atomistic crystals
\index{Crystal!microscopic (unsupported)}%
of conventional solid-state physics.\footnote {This
statement holds true regardless of the not so clear terminology in the
BornAgain class hierarchy.  The class \texttt{Crystal}
\index{Crystal@\Code{Crystal} (class)}%
stands for a mesocrystal of infinite extension.  The class \texttt{Mesocrystal}
\index{Mesocrystal@\Code{Mesocrystal} (class)}%
adds a outer geometric shape.}
It is quite possible that mesoparticles are made of microscopic
crystals, and cause wide-angle scattering, but this is ignored in
BornAgain; BornAgain does not support any wide-angle scattering
simulation.
\index{Wide-angle scattering (unsupported)}%
\fi

%===============================================================================
\subsection{One-dimensional lattice} \label{sec:sect:1dlattice}
%===============================================================================

For a perfect one-dimensional lattice along the x-axis with period
$a$, the position correlation function is given by:
\begin{equation}
  \rho_S\GD(\r) = \sum_{n\neq 0} \delta(x-na)\delta(y).
\end{equation}
Using standard relations for the Dirac comb, one obtains the
interference function
\begin{equation}\label{EScomb}
 \SD(\q) = \frac{2\pi}{a}\sum_k \delta\left(q_x - \frac{2\pi
   k}{a}\right),
\end{equation}
which has the reciprocal lattice period $2\pi/a$.  In \BornAgain, to
circumvent computational problems with the delta functions,
\cref{EScomb} is replaced by
\begin{equation}
  \SD(q_x) = \frac{1}{a}\sum_k H\left(q_x - \frac{2\pi k}{a}\right)
\end{equation}
with the finite distribution
\begin{equation}
   H(q_x) \equiv \int\!\d x\,\e^{i q_x x} h(x)
\end{equation}
that can be understood as Fourier transform of a
\index{Decay function}%
\E{decay function} $h(x)$.

\BornAgain\ currently supports the following one-dimensional decay
functions, parameterized by a decay length $\lambda$ and all starting
from $h(0)=1$:
\begin{equation}
  \begin{array}{|l|c|c|}
    \hline \text{Name} & h(x) & H(q_x) \\ \hline \text{Cauchy} &
    \e^{-|x|/\lambda} & \frac{2\lambda}{1+q_x^2\lambda^2} \\ \hline
    \text{Gauss} & \e^{-x^2/2\lambda^2} & \sqrt{2\pi}\lambda
    \e^{-q_x^2\lambda^2/2} \\ \hline \text{Triangle} & 1-|x|/\lambda
    \quad \text{for} \quad |x|<\lambda & \lambda \sinc^2(q_x\lambda/2)
    \\ \hline
  \end{array}
\end{equation}

In addition, a pseudo-Voigt decay function is available, which is a
convex combination of the Cauchy and Gauss decay functions.

If the one-dimensional lattice is rotated with respect to the
  x-axis by an angle $\xi$, the corresponding interference function is
  calculated by using the correct projection of the in-plane
  reciprocal vector instead of $q_x$:
\begin{equation}
  q_\xi = q_x \cos\xi + q_y \sin\xi.
\end{equation}

%===============================================================================
\subsection{Two-dimensional lattice} \label{sec:sect:2dlattice}
%===============================================================================

For a perfect two-dimensional lattice with lattice basis $(\v a,\v
b)$, the position correlation function is given by:
\begin{equation}
  \rho_S\GD(\r) = \sum_{m,n} \delta(\r-m\v a - n\v b) - \delta(\r).
\end{equation}
The corresponding interference function then becomes
\begin{equation}
  \SD(\q) = 4\pi^2 \rho_S \sum_{\q_i\in\Lambda^*} \delta(\q - \q_i),
\end{equation}
where $\Lambda^*$ denotes the reciprocal lattice of $(\v a,\v b)$.

In \BornAgain, the two-dimensional delta functions need to be replaced
again with distributions of finite width $H(\q - \q_i)$. Currently,
\BornAgain\ only allows for two-dimensional decay functions that are
defined in the radial variable
\begin{equation}
  \phi \coloneqq \sqrt{X^2/\lambda_X^2 + Y^2/\lambda_Y^2},
\end{equation}
where $(X,Y)$ are the coordinates in an orthonormal coordinate system,
where the $X$-axis is rotated by an angle $\gamma$ with respect to the
first lattice vector $\v a$.  This amounts to convoluting the
previously given interference function with $H(\q)$ or, equivalently,
multiplying the position correlation function by the inverse Fourier
image of $H(\q)$, called the
\index{Decay function}%
\E{decay function} $h(\phi)$.

The interference function can then be written as:
\begin{equation}
  \SD(\q) = \rho_S \sum_{\q_i\in\Lambda^*} H(\q - \q_i).
\end{equation}

\BornAgain\ currently supports the following types of two-dimensional
decay functions (parameterized by two decay lengths $\lambda_X,
\lambda_Y$):
\begin{equation}
  \begin{array}{|l|c|c|}
    \hline \text{Name} & h(\phi) & H(Q) \\ \hline \text{Cauchy} &
    \e^{-\phi} & \frac{2\pi\lambda_X\lambda_Y}{(1+Q^2)^{3/2}}
    \\ \hline \text{Gauss} & \e^{-\phi^2/2} & 2\pi\lambda_X\lambda_Y
    \e^{-Q^2/2} \\ \hline
  \end{array}
\end{equation}
with $Q \coloneqq \sqrt{q_X^2\lambda_X^2 + q_Y^2\lambda_Y^2}$.

In addition, a pseudo-Voigt decay function is available, which is a
convex combination of the Cauchy and Gauss decay functions.

The decay functions are all normalized such that $\int\!\d^2q_\plll
H(\q)= 4\pi^2$, which is equivalent to $h(0)=1$.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Paracrystals}\label{SPara}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%===============================================================================
\subsection{The one-dimensional paracrystal} \label{SPara1}
%===============================================================================

A paracrystal, originally developed by Hosemann \cite{Hos51}, models
the cumulative disorder of the interparticle distances.  Although the
paracrystal in one dimension is not directly implemented in
\BornAgain, it forms the basis for the paracrystal models in
\BornAgain\ and will thus be discussed first.

In one dimension, the paracrystal is determined by the distribution
$p(x)$ of the nearest neighbour position, relative to the mean
distance $D$.  Accordingly, the probability distribution of the
position of the nearest neighbour to the right of the particle at the
origin is
\begin{equation}
  p_1(x) = p(x-D).
\end{equation}
The position distribution function for the next to nearest neighbour
is the convolution of this distribution with itself:
\begin{equation}
  p_2(x) = p(x-D) \otimes p(x-D).
\end{equation}
The probability distribution of finding a particle to the right of the
particle at the origin then becomes:
\begin{equation}
  \rho_S \GD^+(x) = \sum_{n>0} \otimes^n p(x-D).
\end{equation}
The probability at the left side is just the mirror image: $\GD^-(x) =
\GD^+(-x)$.
We define the Fourier transform
\begin{equation}\label{EPqdef}
  P(q_x) \coloneqq \int\!\d x\, \e^{iq_x x}\, p(x-D),
\end{equation}
apply the convolution theorem, and sum the geometric series
to obtain the interference function
\begin{equation}
  \SD(q_x) = 1 + 2\Re\left(\frac{P(q_x)}{1-P(q_x)}\right) =
  \Re\left(\frac{1+P(q_x)}{1-P(q_x)}\right).
\end{equation}
Since $P(0)=1$, there is a singularity at the origin of $\SD(q_x)$.  This
singularity is caused by the forward scattering contribution of an
infinitely long lattice and can be removed in two ways in \BornAgain.
The simplest way is to multiply $P(q_x)$ by a fixed factor that is
very close, but not equal to, one:
\begin{equation}
  P'(q_x) \coloneqq P(q_x) \e^{-D/\Lambda},
\end{equation}
where $\Lambda$ has dimension of length and is called the damping
length.

A second possibility for removing the singularity at $q_x=0$ consists
of considering only a finite portion of the one-dimensional
paracrystal. Caution has to be taken here, since the probability
distributions at either side of the particle will depend on which
particle of the finite lattice is considered. The calculations can
still be carried out exactly and lead to the following expression for
the interference function:
\begin{equation}
   \SD(q_x) = 1 + 2\Re\left( \frac{P(q_x)}{1-P(q_x)} -
   \frac{P(q_x)\left[1-P^{N_p}(q_x)\right]}{N_p\left( 1 - P(q_x)
     \right)^2} \right),
\end{equation}
with $N_p$ the number of particles making up the finite lattice.

Before embarking on the paracrystal models, implemented in
  \BornAgain, it has to be stressed that there is no such thing as a
  paracrystal in more than one dimension. The following models are
  consequently only to be seen as ad hoc approximations of lattices
  with cumulative disorder.

%===============================================================================
\subsection{The radial paracrystal} \label{SParaR}
%===============================================================================

In the radial paracrystal model, the interference function of the
one-dimensional paracrystal is used directly, but applied to the
radial component of $\q_\plll$. The resulting interference function,
which is radially symmetric, is then given by
\begin{equation}
  \SD(\q_\plll) = \Re\left(\frac{1+P(q_\plll)}{1-P(q_\plll)}\right),
\end{equation}
or one of the versions with the singularity removed.

In \BornAgain, the following one-dimensional distribution functions
for $p(x)$ are implemented:
\begin{equation}
  \begin{array}{|l|c|c|}
    \hline \text{Name} & p(x) & P(q_x) \\ \hline \text{Cauchy} &
    \frac{1}{2\omega} \exp(-|x|/\omega) & \frac{1}{1+q_x^2\omega^2}
    \\ \hline \text{Gauss} & \frac{1}{\omega\sqrt{2\pi}}
    \exp(-x^2/2\omega^2) & \exp(-q_x^2\omega^2/2) \\ \hline
    \text{Gate} & \frac{1}{2\omega} \quad \text{for} \quad |x|<\omega
    & \sinc(q_x\omega) \\ \hline \text{Triangle} &
    \frac{1}{\omega}\left(1 - |x|/\omega\right) \quad \text{for} \quad
    |x|<\omega & \sinc^2(q_x \omega/2) \\ \hline \text{Cosine} &
    \frac{1}{2\omega}\left(1 + \cos(\pi x/\omega) \right) \quad
    \text{for} \quad |x|<\omega & \frac{\sinc(q_x
      \omega)}{1-(q_x\omega/\pi)^2} \\ \hline
  \end{array}
\end{equation}
In addition, a pseudo-Voigt distribution function is available, which
is a convex combination of the Cauchy and Gauss distribution
functions.

For the radial paracrystal, there is also an extension available in
\BornAgain\ that takes into account a coupling between the size of the
particles and the inter-particle distance. This approximation is
discussed in more detail in \ref{sec:sect:sscaparacrystal}.

%===============================================================================
\subsection{The two-dimensional paracrystal} \label{SPara2}
%===============================================================================

The two-dimensional paracrystal model in \BornAgain\ is implemented as
a simple convolution of the two one-dimensional paracrystals along the
lattice basis vectors. The calculation of the interference function
results in a simple product of two one-dimensional interference
functions:
\begin{equation}
  \SD(\q) = \Re\left(\frac{1+P_1(\q)}{1-P_1(\q)}\right)
  \Re\left(\frac{1+P_2(\q)}{1-P_2(\q)}\right),
\end{equation}
where $P_1(\q)$ and $P_2(\q)$ denote the Fourier transforms of the two
independent particle distributions (which are now both two-dimensional
distribution functions).

Again, \BornAgain\ provides for removing the singularity by either
using a damping length or by indicating finite domain sizes.

The two-dimensional distributions supported in \BornAgain\ are
parameterized by
\begin{equation}
  \phi \coloneqq \sqrt{X^2/\omega_X^2 + Y^2/\omega_Y^2},
\end{equation}
where $(X,Y)$ are the coordinates in an orthonormal coordinate system,
where the $X$-axis is rotated by an angle $\gamma$ with respect to the
first lattice vector $\v a$.

The following distributions are currently supported:
\begin{equation}
  \begin{array}{|l|c|c|}
    \hline \text{Name} & p(\phi) & P(Q) \\ \hline \text{Cauchy} &
    \frac{1}{2\pi\omega_X\omega_Y} \exp(-\phi) &
    \frac{1}{(1+Q^2)^{3/2}} \\ \hline \text{Gauss} &
    \frac{1}{2\pi\omega_X\omega_Y} \exp(-\phi^2/2) & \exp(-Q^2/2)
    \\ \hline \text{Gate} & \frac{1}{\pi\omega_X\omega_Y} \quad
    \text{for} \quad \phi < 1 & \frac{2J_1(Q)}{Q} \\ \hline
    \text{Cone} & \frac{3}{\pi\omega_X\omega_Y}\left(1 - \phi \right)
    \quad \text{for} \quad \phi < 1 & 6\left[ \frac{J_1(Q)}{Q} -
      \frac{1}{Q^3}\int_0^Q\!\d u u^2 J_0(u) \right] \\ \hline
  \end{array}
\end{equation}
with $Q \coloneqq \sqrt{q_X^2\omega_X^2 + q_Y^2\omega_Y^2}$.

Again, a convex combination of the Cauchy and Gauss distributions in
two dimensions is available (pseudo-Voigt).

%===============================================================================
\subsection{The radial paracrystal with size-position coupling} \label{sec:sect:sscaparacrystal}
%===============================================================================

Restricting the calculation to one layer, the differential cross
section for a specific arrangement of particles of different type is:
\begin{equation}
  \xElas = \sum_{ij} \e^{i\q_{\plll}(\R_{j\plll}-\R_{i\plll})}\!
  \FD(\v{T}_i) \FD^*(\v{T}_j).
\end{equation}

In a statistical ensemble, this cross section has to be averaged by
the joint probability density function for all postions and types of
each individual particle:
\begin{equation}
  \PD\left(\lbrace \R_{i\plll} \rbrace, \lbrace \v{T}_i
  \rbrace\right).
\end{equation}
Its normalization is chosen such that the total integral over its
phase space equals $N!$, with $N$ the number of particles. This
reflects the arbitrary nature of the indices $i$ for each particle and
will be removed when we consider a specific choice for the indices.

The expectation value of the differential cross section then becomes
\begin{equation}\label{Ecsc}
  \left\langle\xElas\right\rangle = \frac{1}{N!}\,
  \int\!\prod_i\!d^2\R_{i\plll}\!d\v{T}_i \,\PD\left(\lbrace
  \R_{i\plll} \rbrace, \lbrace \v{T}_i \rbrace\right) \sum_{jk}
  \e^{i\q_{\plll}(\R_{k\plll}-\R_{j\plll})}\!  \FD(\v{T}_j)
  \FD^*(\v{T}_k).
\end{equation}

As for the case of the radial paracrystal, a one-dimensional approach
is developed, which is then applied to the radial component of the
wavevector transfer. In this approach, we can replace the radial
postion $\R_{i\plll}$ with $x_i$.

For a one-dimensional arrangement of particles, we can choose the
indices of the particles such that they increase with their position
$x_i$. If the joint probability density function is adapted to only
have support for particles ordered in this way, we can drop the factor
$1/N!$ in the expectation value.

For each term appearing in the sum of the integrand of the expectation
value of the cross section, we only need to know the density function
of the positions and types of two particles, denoted by their indices
$j$ and $k$. All other dependencies should be integrated out. In
\cite{LeLa04}, this approach is used to calculate the effects of
different types of correlations between sizes and/or positions on the
diffuse scattering intensity. In \BornAgain\ only a specific case is
implemented, namely the one also appearing in the IsGisaxs software
package as the \emph{size-spacing correlation approximation}
\cite{Laz06}.

In this case, the distribution of the inter-neighbor distance between
two particles depends only on the sizes of these two
particles. Furthermore, the dependence is fixed to be a linear
relationship of the mean distance $d_n$ between particle $n-1$ and $n$
and the particles' sizes ($X(\v{T}_{n-1})$ and $X(\v{T}_n)$):
\begin{equation}\label{Edm}
  \langle d_n \rangle = D + \kappa \left[ \Delta X(\v{T}_{n-1}) +
    \Delta X(\v{T}_{n}) \right],
\end{equation}
where $D$ is the average interparticle distance, $\kappa$ is the
coupling parameter determining how much this interparticle distance is
influenced by the particles' sizes, and
\[ \Delta X(\v{T}_{n}) \coloneqq  X(\v{T}_{n}) - \langle X \rangle \]
is the deviation from the mean of the size of a particle of type
$\v{T}_n$.

The differential cross section (\ref{Ecsc}) in this case can then be
expressed as:
\begin{equation}\label{Ecsssca}
  \frac{1}{N}\left\langle\xElas\right\rangle = \int\!d\v{T}\,\PD
  (\v{T}) \left| \FD(\q,\v{T}) \right|^2 + 2\Re \left\lbrace
  \FD_\kappa(\q)\tilde{\FD}_\kappa(\q) \cdot \frac{P(q_\plll)}{1 -
    \tilde{p}_{2\kappa}(q_{\plll})P(q_\plll))} \right\rbrace ,
\end{equation}
with
\begin{align*}
  \tilde{p}_{\kappa}(q_\plll) & \coloneqq \int\!d\v{T}\,\PD (\v{T})
  e^{i\kappa q_\plll\Delta X(\v{T})}, \\ \FD_\kappa(\q) & \coloneqq
  \int\!d\v{T}\,\PD (\v{T}) e^{i\kappa q_\plll\Delta X(\v{T})} \FD(\q,
  \v{T}), \\ \tilde{\FD}_\kappa(\q) & \coloneqq \int\!d\v{T}\,\PD
  (\v{T}) e^{i\kappa q_\plll\Delta X(\v{T})} \FD^*(\q, \v{T})
\end{align*}
and $P(q_\plll)$ is the Fourier transform of the average next neighbor
distance (as was also the case for the radial paracrystal).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Disordered assemblies}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\MissingSection \iffalse The starting point for describing the
interference of the scattering from different particles is the
coherent scattering intensity of~\cref{EICoherent}.

The conditional interference function is defined as
\begin{equation}
  \SD(\q |\v\tau,\v\tau') \coloneqq 1 + \rho_S \int\!\d^2r\,
  \e^{i\q_\plll\r}\! \GD(\r|\v\tau,\v\tau').
\end{equation}
With the chosen normalization, $\rho_S \GD(\r|\v\tau,\v\tau') d^2r$
gives the probability of finding a particle of type $\v\tau'$ in the
infinitesimal area~$d^2r$ at the relative position~$\r$ from a given
(different) particle of type $\v\tau$.  \fi

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\iffalse
\section{OLD STUFF [TO REVISE]}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\Note{\indent The vertical positions of particles in a layer are given
  in relative coordinates. For the top layer, the bottom corresponds
  to \texttt{depth}=0. But for all the other layers, it is the top of
  the layer which corresponds to \texttt{depth}=0.}

%===============================================================================
\subsection{Collection of particles} \label{sec:sect:interf}
%===============================================================================

Since in most experimental conditions only the statistical properties
of the particles are known, one can consider the probabilistic value
of this cross-section \idest its expectation value. Assuming that the
particles' shapes are determined by their class $\alpha$, with the
abundance ratio $p_\alpha \equiv N_\alpha / N$, and defining the
particle density as $\rho_V \equiv N/V$, the expectation value
becomes:
\begin{align*}
  \braket{\xElas(\q)} & = \sum_\alpha p_\alpha \left\lvert
  F_\alpha(\q)\right\rvert ^2 + \frac{\rho_V}{V}\sum_{\alpha,\beta}
  p_\alpha p_\beta F_\alpha (\q)F_\beta^*(\q) \\ & \times \iint_V
  d^3\v{R}_\alpha d^3\v{R}_\beta \ppcf{\alpha}{\beta}{R} \exp \left[
    i\q\cdot (\v{R}_\alpha - \v{R}_\beta ) \right],
\end{align*}


where $\ppcf{\alpha}{\beta}{R}$ is called the \emph{partial pair
correlation function}. It represents the normalized probability of
finding particles of type $\alpha$ and $\beta$ in positions
$\v{R}_\alpha$ and $\v{R}_\beta$ respectively.

TO MERGE IN:

\begin{align*}
  & \braket{\xElas(\k_\si,\k_\sf)}_{\text{Off-specular}} \\ & =
  \sum_\alpha p_\alpha \left\lvert \curlf_\alpha(\k_{j,i},\k_{j,f},
  R_{\alpha,z})\right\rvert ^2 + \frac{\rho_S}{S}\sum_{\alpha,\beta}
  p_\alpha p_\beta \curlf_\alpha (\k_{j,i},\k_{j,f},
  R_{\alpha,z})\curlf_\beta^*(\k_{j,i},\k_{j,f}, R_{\beta,z}) \\ &
  \times \iint_S d^2r_\alpha^\plll d^2r_\beta^\plll
  \ppcf{\alpha}{\beta}{R^\plll} \exp \left[ i\v{q}_{j\plll}\cdot
    (\r_\alpha^\plll - \r_\beta^\plll ) \right].
\end{align*}


TO MERGE IN: This expression can be split into a diffuse part, which
by definition should be zero for the case of only one particle type,
and a coherent part, resulting from the coherent superposition of
scattering amplitudes for particles at different positions:
\begin{equation*}
  \braket{\xElas(\q)} = I_d(\q) + \braket{F_\alpha (\q )
    S_{\alpha\beta} (\q) F_\beta^* (\q)}_{\alpha\beta},
\end{equation*}
where
\begin{align*}
  I_d(\q) & \equiv \braket\left\rvert F_\alpha (\q)
  \right\rvert^2}_{\alpha} - \left\lvert \braket{F_\alpha
      (\q)}_{\alpha} \right\rvert^2, \\ S_{\alpha\beta} (\q) &\equiv 1
    + \rho_V \int_V \d^3\r\mathcal{G}_{\alpha\beta}(\r) \exp \left[
      i\q\cdot \r \right].
\end{align*}
$S_{\alpha\beta} (\q)$ is called the \emph{interference function}, and
$\braket{\dotso}_\alpha$ is the expectation value over the classes
$\lbrace \alpha\rbrace$.


TO MERGE IN: More precisely, the probability density for finding a
particle~$\alpha$ at position $\v{R}_\alpha$ and another one of type
$\beta$ at $\v{R}_\beta$ is given by:
\begin{equation*}
  \mathcal{P}(\alpha, \v{R}_\alpha ; \beta , \v{R}_\beta ) \equiv
  \rho_V^2 p_\alpha p_\beta \ppcf{\alpha}{\beta}{R}.
\end{equation*}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Layout of particles}\label{sec:partlayout}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%===============================================================================
\subsection{The regular lattice and the ideal paracrystal}
%===============================================================================

The particles are positioned at regular intervals generating a layout
characterized by its base vectors $\v{a}$ and $\v{b}$ (in direct
space) and the angle between these two vectors.  This lattice can be
two or one-dimensional depending on the characteristics of the
particles. For example when they are infinitely long, the
implementation can be simplified and reduced to a "pseudo" 1D system.

\index{Paracrystal}%
A paracrystal, whose notion was developed by
Hosemann \cite{Hos51}, allows fluctuations of the lengths and
orientations of lattice vectors.  Paracrystals can be defined as
distorted crystals in which the crystalline order has not disappeared
and for which the behavior of the interference functions at small
angles is coherent.  It is a transition between the regular lattice
and the disordered state.\\

For example, in one dimension, a paracrystal is generated using the
following method. First we place a particle at the origin. The second
particle is put at a distance $x$ with a density probability $p(x)$
that is peaked at a mean value $D$: $\int_{-\infty} ^{\infty}p(x)\d
x=1$ and $\int_{-\infty}^{\infty}xp(x)\d x=D$.  The third one is added
at a distance $y$ from the second site using the same rule with a
density probability $p_2(y)=
\int_{-\infty}^{\infty}p(x)p(y-x)dx=p\otimes p(y)$.

With such a method, the pair correlation function $g(x)$ is built step
by step.  Its expression and the one of its Fourier transform, which
is the interference function are
\begin{equation*}
g(x)=\delta(x)+ p(x)+ p(x)\otimes p(x)+\ldots + p(-x)+\ldots \:
\mathrm{and}\:\, S(q)=\Re\left(\dfrac{1+P(q)}{1-P(q)}\right),
\end{equation*}
 where $P(q)$ is the Fourier transform of the density probability
 $p(x)$.\\

\paragraph{Example} For a probability distribution function is Gaussian:
\begin{equation*}
p(x)=\frac{1}{\omega \sqrt{2\pi}}
\exp\left(-\dfrac{(x-D)^2}{\omega^2}\right),\qquad
P(q)=\exp\left(-\frac{q^2 \omega^2}{2}\right)\exp(iqD).
\end{equation*}
 The interference function of a one-dimensional paracrystal is given
 by

\begin{align*}
S(q) =\Re \left(\frac{1+\Phi(q) }{1 - \Phi(q)} \right), \quad
\mathrm{where}\quad \Phi(q) = P(q)\exp\left(-\frac{D}{\Lambda}\right),
\end{align*}
where $\Lambda$ is a damping length used in order to introduce some
finite-size effects.

\Cref{fig:1dparas_q} shows the evolution of $S(q)$ for different
values of $\omega /D$.

\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.6\textwidth]{fig/funcplot/S_q_1Dparacrystal.eps}
\end{center}
\caption{Interference function of a 1D Gaussian paracrystal plotted
  for different values of $\omega /D$. The peaks broaden with a
  decreasing amplitude as $\omega/D$ increases. This shows the
  transition between an ordered and a disordered states. }
\label{fig:1dparas_q}
\end{figure}

In two dimensions, the paracrystal is constructed on a pseudo-regular
lattice with base vectors $\v{a}$ and $\v{b}$ using the following
conditions for the densities of probabilities:\\ $\int
p_{\v{a}}(\r)\d^2r=\int p_{\v{b}}(\r)\d^2r=1$, $\int \r
p_{\v{a}}(\r)\d^2r=\v{a}$, $\int \r p_{\v{b}}(\r)\d^2r=\v{b}$.

In the ideal case the deformations along the two axes are decoupled
and each unit cell should retain a parallelogram shape.  The
interference function is given by
$S(q_{\plll})=\prod_{k=a,b}\Re\left(\dfrac{1+P_k(q_{\plll})}{1-P_k(q_{\plll})}
\right)$ with $P_k$ the Fourier transform of $p_k$, $k=a, b$.

\paragraph{Probability distributions} \mbox{}\\
The scattering by an ordered lattice gives rise to a series of Bragg
peaks situated at the nodes of the reciprocal lattice. Any divergence
from the ideal crystalline case modifies the output spectrum by, for
example, widening or attenuating the Bragg peaks. The influence of
these "defects" can be accounted for in direct space by using
correlation functions or by truncating the lattice or, in reciprocal
space with structure factors or interference functions by convoluting
the scattered peaks with a function which could reproduce the
experimental shapes.

%===============================================================================
\subsection{Size-Spacing Correlation Approximation}
%===============================================================================
\index{Size-spacing correlation approximation}%

TO MERGE IN: introduces correlations between polydisperse particles,
more precisely between the size of the particles and their mutual
spacing. A classical example would consist in particles whose
closest-neighbor spacing depends linearly on the sum of their
respective sizes \cite{LaLR07}, as illustrated in \cref{fig:ssca}.

%For a sample where only the statistical properties of particle positions and size are known, the scattered intensity per scattering particle is expressed as the average over an ensemble of the Fourier transform of the Patterson function, which is the autocorrelation of the SLD $\curlp (\r ) \equiv \sum_{ij} S_i(-\r )\otimes S_j(\r )\otimes \delta (\r + \r_i - \r_j )$:
%\begin{equation*}
%  I(\q ) = \frac{1}{N}\ensavg{}{\curlf (\curlp (\r ))},
%\end{equation*}
%where $\curlf$ denotes the Fourier transform and $\curlp$ the Patterson function

\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.9\textwidth]{fig/drawing/drawingSSCA.pdf}
\end{center}
\caption{Sketch of a 1D distributed collection of particles, whose
  scattering could be described by the size-spacing correlation
  approximation: the distance between two particles depends on their
  sizes.}
\label{fig:ssca}
\end{figure}

In the Size-Spacing Correlation Approximation, a correlation is
assumed between the shape/size of the particles and their mutual
spacing. A classical example would consist of particles whose
closest-neighbor spacing depends linearly on the sum of their
respective sizes. The following discussion of this type of correlation
is inspired by \cite{LaLR07}

The scattered intensity can also be calculated as the Fourier
transform of the Patterson function, which is the autocorrelation of
the SLD:
\begin{equation*}
  \curlp (\r ) \equiv \sum_{ij} S_i(-\r )\otimes S_j(\r )\otimes
  \delta (\r + \r_i - \r_j ).
\end{equation*}
For a sample where only the statistical properties of particle
positions and shape/size are known, the scattered intensity per
scattering particle becomes average over an ensemble of the Fourier
transform of the Patterson function:
\begin{equation*}
  I(\q ) = \frac{1}{N}\braket{\curlf (\curlp (\r ))},
\end{equation*}
where $\curlf$ denotes the Fourier transform.

The ensemble averaged Patterson function will be denoted as:
\begin{equation*}
  Z(r) \equiv \frac{1}{N}\braket{\curlp (\r )}.
\end{equation*}
In the case of systems where the particles are aligned in one
dimension, this autocorrelation function can be further split into
nearest neighbor probabilities. First, it is split into terms for
negative, zero or positive distance:
\begin{equation*}
  Z(\r ) \equiv z_0(\r ) + z_+(\r ) + z_-(\r ).
\end{equation*}
Taking $x$ as the coordinate in the direction in which the particles
are arranged and $s$ as an orthogonal coordinate ($\r \equiv (x,s)$),
one obtains:
\begin{align*}
  z_0(\r ) &= \sum_{\alpha_0} p(\alpha_0) S_{\alpha_0}(-x,-s) \otimes
  S_{\alpha_0}(x,s) \\ z_+(\r ) &= \sum_{\alpha_0\alpha_1}
  p(\alpha_0,\alpha_1) S_{\alpha_0}(-x,-s) \otimes S_{\alpha_1}(x,s)
  \otimes P_1(x|\alpha_0\alpha_1) \\ &+
  \sum_{\alpha_0\alpha_1\alpha_2} p(\alpha_0,\alpha_1,\alpha_2)
  S_{\alpha_0}(-x,-s) \otimes S_{\alpha_2}(x,s) \otimes
  P_1(x|\alpha_0\alpha_1) \otimes P_2(x|\alpha_0\alpha_1\alpha_2)
  \\ &+ \dotsb \\ z_-(\r ) &= z_+(-\r ),
\end{align*}
where $p(\alpha_0,\dotsc ,\alpha_n)$ denotes the probability of having
a sequence of particles of the indicated sizes/shapes and
$P_n(x|\alpha_0\dotsc\alpha_n)$ is the probability density of having a
particle of type $\alpha_n$ at a (positive) distance $x$ of its
nearest neighbor of type $\alpha_{n-1}$ in a sequence of the given
order.

In the Size-Spacing Correlation Approximation, one assumes that the
particle sequence probabilities are just a product of their individual
fractions:
\begin{equation*}
  p(\alpha_0,\dotsc ,\alpha_n) = \prod_i p(\alpha_i),
\end{equation*}
and the nearest neighbor distance distribution is dependent only on
the two particles involved:
\begin{equation*}
  P_n(x|\alpha_0\dotsc\alpha_n) = P_1(x|\alpha_{n-1}\alpha_n).
\end{equation*}
Furthermore, the distance distribution $P_1(x|\alpha_0\alpha_1)$
depends on the particle sizes/shapes only through its mean value $D$:
\begin{equation*}
  P_1(x|\alpha_0\alpha_1) = P_0(x - D(\alpha_0,\alpha_1) ),
\end{equation*}
where $D(\alpha_0,\alpha_1) = D_0 + \kappa \left[ \Delta R(\alpha_0) +
  \Delta R(\alpha_1) \right]$, with $\Delta R(\alpha_i)$ the deviation
of a size parameter of particle $i$ with respect to the mean over all
particles sizes/shapes and $\kappa$ the coupling parameter.

In momentum space, the sum of convolutions can be written as a
geometric series, which can be exactly calculated to be:
\begin{equation}
\label{Esscainf}
I(\q ) = \braket{\left| F_\alpha(\q ) \right| ^2}_{\alpha} + 2 \Re
\left\lbrace \widetilde{\curlf_\kappa}(\q )
\widetilde{\curlf_\kappa^*}(\q ) \cdot \frac{\Omega_\kappa(\q
  )}{\tilde{p}_{2\kappa}(\q )\left [ 1 - \Omega_\kappa(\q )\right] }
\right\rbrace,
\end{equation}
with
\begin{align*}
  \tilde{p}_\kappa(\q ) &= \int \d\alpha\; p(\alpha) \e^{i\kappa q_x
    \Delta R(\alpha)} \\ \Omega_\kappa(\q ) &= \tilde{p}_{2\kappa}(\q
  ) \phi(\q) \e^{i q_x D_0} \\ \widetilde{\curlf_\kappa}(\q ) &= \int
  \d\alpha\; p(\alpha)F_\alpha (\q ) \e^{i\kappa q_x \Delta
    R(\alpha)},
\end{align*}
and the Fourier transform of $P_1(x|\alpha_0\alpha_1)$ is
\begin{equation*}
  \curlp (\q ) = \phi (\q )\e^{i q_x D_0} \e^{i \kappa q_x \left[
      \Delta R(\alpha_0) + \Delta R(\alpha_1) \right] }.
\end{equation*}

Using the result from the one-dimensional analysis, one can apply this
formula ad hoc for distributions of particles in a plane, where the
coordinate $x$ will now be replaced with $(x,y)$, while the $s$
coordinate encodes a position in the remaining orthogonal
direction. One must be aware however that this constitutes a further
approximation, since this type of correlation does not have a general
solution in more than one dimension.

The intensity in \cref{Esscainf} will contain a Dirac delta function
contribution, caused by taking an infinite sum of terms that are
perfectly correlated at $\q = 0$. One can leverage this behaviour by
multiplying the nearest neighbor distribution by a constant factor
$\e^{-D/\Lambda}$, which removes the division by zero in
\cref{Esscainf}.  Another way of dealing with this infinity at $\q =0$
consists of taking only a finite number of terms, in which case the
geometric series still has an analytic solution, but becomes a bit
more cumbersome:
\begin{equation*}
\begin{split}
  I(\q ) &= \bra{\left| F_\alpha(\q ) \right| ^2}_\alpha + 2 \Re
  \Biggl\lbrace \frac{1}{\tilde{p}_{2\kappa}(\q
    )}\widetilde{\curlf_\kappa}(\q )\widetilde{\curlf_\kappa^*}(\q )
  \\ & \times \left[ \left( 1 - \frac{1}{N}\right)
    \frac{\Omega_\kappa(\q )}{1 - \Omega_\kappa(\q ) } -
    \frac{1}{N}\frac{\Omega_\kappa^2(\q )\left( 1-
      \Omega_\kappa^{N-1}(\q )\right) }{\left( 1 - \Omega_\kappa(\q )
      \right) ^2 } \right] \Biggr\rbrace.
\end{split}
\end{equation*}
This expression has a well-defined limit for $\Omega_\kappa(\q )
\rightarrow 1$ (when $\q \rightarrow 0$), namely:
\begin{equation*}
  \lim_{\q \rightarrow 0} I(\q ) = \bra{\left| F_\alpha(0)\right|
    ^2}_{\alpha} + \left( N-1 \right) \left|
  \bra{F_\alpha(0)}_{\alpha} \right|^2.
\end{equation*}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Vertical location of particles}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

 \Note{The particles cannot sit in between layers. At most they can be
   sitting on any inner interfaces.}

%===============================================================================
\subsection{Particles deposited on a substrate}
%===============================================================================
%Substrate modified Born approximation
In this configuration, the particles are sitting on top of a substrate
layer in air or vacuum.  In the DWBA the expression of a form factor
becomes
\begin{align}
F_{\rm{DWBA}}(q_{\plll}, k_{i,z}, k_{f,z}) &= F_{\rm{BA}}(q_{\plll},
k_{i,z}-k_{f,z})+ R_i F_{\rm{BA}}(q_{\plll}, -k_{i,z}-k_{f,z})
\nonumber \\ &+ R_f F_{\rm{BA}}(q_{\plll}, k_{i,z}+k_{f,z}) + R_i R_f
F_{\rm{BA}}(q_{\plll},-k_{i,z}+k_{f,z}), \label{Edwbaair}
\end{align}
where $q_{\plll}$ is the component of the scattering beam in the plane
of the interface ($\q=\k_i-\k_\sf$), $k_{i,z}$ and $k_{f,z}$ are the
z-component of the incident and scattered beam, respectively. $R_i$,
$R_f$ are the reflection coefficients in incidence and
reflection. They are defined
as\\ $R=\dfrac{k_z+\sqrt{n_s^2k_0^2-|k_{\plll}|^2}}{k_z-\sqrt{n_s^2
    k_0^2-|k_{\plll}|^2}}$, where $n_s=1-\delta_s +i \beta_s$ is the
refractive index of the substrate, $k_0$ is the wavelength in vacuum
($2\pi /\lambda$), $k_z$ and $k_{\plll}$ are the $z$-component and the
in-plane component of $\k_\si$ or $\k_\sf$. \\

\Note{If the particles are sitting on a multilayered system, the
  expression of the form factor in the DWBA is obtained by replacing
  the Fresnel coefficient by the corresponding coefficients of the
  underlying layers \cite{Par54,BoWo99}.}

Script~\ref{lst:badwba} illustrates the difference between BA and DWBA
in \BornAgain\ when generating the sample.  We consider the simple
case of:
\begin{itemize}
\item one kind of particles' shape,
\item no interference between the particles,
\item in the DWBA, a sample made of a layer of substrate on which are
  deposited the particles,
\item in the BA, a sample composed of the particles in air.
\end{itemize}

\Cref{fig:spheroidbadwba} shows the intensity contour plot generated
using this script with truncated spheroids as particles.

\newpage

\setPy
\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to generate a sample using Born (BA) or distorted-wave Born approximation (DWBA). The difference between BA and DWBA in this simple case is the absence or presence of a substrate layer in the sample.},label={lst:badwba}]
def get_sample(): """ Build and return the sample to calculate form
factor of truncated spheroid in Born or distorted-wave Born
Approximation.  """ # defining materials m_ambience =
HomogeneousMaterial("Air", 0.0, 0.0) m_substrate =
HomogeneousMaterial("Substrate", 6e-6, 2e-8) m_particle =
HomogeneousMaterial("Particle", 6e-4, 2e-8)

    # collection of particles ff=
FormFactorTruncatedSpheroid(7.5*nanometer, 9.0*nanometer, 1.2)
particleshape = Particle(m_particle, ff) particle_layout =
ParticleLayout() particle_layout.addParticle(particleshape, 1.0)

    # interferences interference = InterferenceFunctionNone()
particle_layout.setInterferenceFunction(interference)

    # assembling the sample air_layer = Layer(m_ambience)
air_layer.addLayout(particle_layout) substrate_layer =
Layer(m_substrate, 0)

    multi_layer = MultiLayer() multi_layer.addLayer(air_layer) #
    Comment the following line out for Born Approximation
    multi_layer.addLayer(substrate_layer) return multi_layer
\end{lstlisting}


\begin{figure}[tb]
\hfill \subfigure[Born
  Approximation]{\includegraphics[angle=-90,width=6cm]{fig/gisasmap/ffspheroidBA.pdf}}
\hfill \subfigure[DWB
  Approximation]{\includegraphics[angle=-90,width=6cm]{fig/gisasmap/ffspheroidDWBA.pdf}}
\hfill
\caption{Intensity map of TruncatedSpheroid form factor in BA and DWBA
  computing using script~\ref{lst:badwba} for the sample.}
\label{fig:spheroidbadwba}
\end{figure}

\FloatBarrier

\Note{In \BornAgain, the DWBA is implemented automatically when
  assembling the sample with more layers than only the air layer (for
  example, for particles are sitting on a substrate).}

%===============================================================================
\subsection{Buried particles}
%===============================================================================

The system considered in this section consists of particles
encapsulated in a layer, which is sitting on a substrate. In this case
the form factor in the DWBA is given by

\begin{align}
  F_{\rm{DWBA}}(q_{\plll}, k_{i,z}, k_{f,z}) &= T_\si T_\sf
  F_{\rm{BA}}(q_{\plll},
  k_{i,z}-k_{f,z})\e^{i(k_{i,z}-k_{f,z})d}\nonumber \\ &+ R_\si T_\sf
  F_{\rm{BA}}(q_{\plll}, -k_{i,z}-k_{f,z})\e^{i(-k_{i,z}-k_{f,z})d}
  \nonumber \\ &+ R_\sf T_\si F_{\rm{BA}}(q_{\plll}, k_{i,z}+k_{f,z})
  \e^{i(k_{i,z}+k_{f,z})d}\nonumber \\ &+ R_\sf R_\si
  F_{\rm{BA}}(q_{\plll},-k_{i,z}+k_{f,z})\e^{i(-k_{i,z}+k_{f,z})d}, \label{Edwbaburied}
\end{align}

\begin{equation*}
R_j
=\frac{t^{j}_{0,1}r^{j}_{1,2}\exp(2ik_{j,z}t)}{1+r^{j}_{0,1}r^{j}_{1,2}\exp(2ik_{j,z}t)},
\quad
T_j=\frac{t^{j}_{0,1}}{1+r^{j}_{0,1}r^{j}_{1,2}\exp(2ik_{j,z}t)},
j=i,f
\end{equation*}
where $q_{\plll}$ is the component of the scattering beam in the plane
of the interface, $k_{i,z}$ and $k_{f,z}$ are the z-component of the
incident and scattered beams, respectively.  $d$ is the depth at which
the particles are sitting in the layer. Note that this value is given
relative to the top of this layer and it is not the coordinate in the
absolute referential (linked with the full sample) and it is measured
up to the bottom of the particle. $t$ is the thickness of the
intermediate layer containing the particles. $R_{i,f}$ and $T_{i,f}$
are the reflection and transmission coefficients in incidence and
reflection (they can be calculated using Parratt or matrix
formalism). $r^j_{0,1}$, $r^j_{1,2}$ $t^j_{0,1}$ are the reflection
and transmission coefficients between layers; the indices are related
to different boundaries with 0: air, 1: intermediate layer and 2:
substrate layer and the superscript $j$ is associated with the
incident or scattered beams:
\begin{equation*}
r^j_{n,n+1}=\frac{k_{j,z,n}-k_{j,z,n+1}}{k_{j,z,n}-k_{j,z,n+1}},
\qquad t^j_{n,n+1}= \frac{2k_{j,z,n}}{k_{j,z,n}-k_{j,z,n+1}}, \quad
n=0,1, \quad j=i,f,
\end{equation*}
where index $n$ is related to the layers, $z$ to the vertical
component, and $j$ to the beams (incident and outgoing).

\Cref{fig:dwbaburied} shows a typical example of the output intensity
scattered from a sample made of 3 layers: air, substrate, and in
between, spherical particles embedded in the middle of a 30~nm-thick
layer. This figure had been generated using
listing~\ref{lst:dwbaburied}.

\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to generate a sample where spherical particles are embedded in the middle of a layer on a substrate.},label={lst:dwbaburied}]
def get_sample(): """ Build and return the sample with buried spheres
in DWBA.  """ # defining materials m_ambience =
HomogeneousMaterial("Air", 0.0, 0.0) m_interm_layer =
HomogeneousMaterial("IntermLayer",3.45e-6, 5.24e-9) m_substrate =
HomogeneousMaterial("Substrate", 7.43e-6, 1.72e-7) m_particle =
HomogeneousMaterial("Particle", 0.0, 0.0)

    # collection of particles ff =
FormFactorFullSphere(10.2*nanometer) particleshape =
Particle(m_particle, ff) particleshape.setPosition(0.0, 0.0, -25.2)
particle_layout = ParticleLayout()
particle_layout.addParticle(particleshape, 1.0)

    # interferences interference = InterferenceFunctionNone()
particle_layout.setInterferenceFunction(interference)

    # assembling the sample air_layer = Layer(m_ambience)
intermediate_layer = Layer(m_interm_layer, 30.*nanometer)
intermediate_layer.addLayout(particle_layout) substrate_layer =
Layer(m_substrate, 0)

    multi_layer = MultiLayer() multi_layer.addLayer(air_layer)
    multi_layer.addLayer(intermediate_layer)
    multi_layer.addLayer(substrate_layer) return multi_layer
\end{lstlisting}


\begin{figure}[tb]
\centering
\includegraphics[angle=-90,width=0.6\textwidth]{fig/gisasmap/figIntBuriedPart.pdf}
\caption{Map of intensity scattered from a sample made of spherical
  particles embedded in the middle of a 30~nm-thick layer on a
  substrate (see Script~\ref{lst:dwbaburied} for details about the
  sample).}
\label{fig:dwbaburied}
\end{figure}

\newpage

\Note{For layers different from the air layer, the top interface is
  considered as the reference level to position the encapsulated
  particles. For example, spheres positioned at depth $d$ (positive)
  are located at a distance $d$ from the top of the layer up to the
  bottom of these particles. This convention is different for the top
  air layer, where particles sitting at the interface with an
  underlying layer (\idest the bottom of the air layer) are located at
  depth 0 (see \cref{fig:depthpartBA}).}


\begin{figure}[tb]
\centering
\includegraphics[width=0.5\textwidth]{fig/drawing/drawingDepthParticle.pdf}
\caption{Illustration of the convention about \Code{depth} used in
  \BornAgain\ to encapsulate particles in layers.}
\label{fig:depthpartBA}
\end{figure}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Implementation in \BornAgain}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

This section describes the implementation of the interference
functions in \BornAgain.  For an implementation of all the components
of a simulation, the use is referred, for example, to
\cref{sec:Example1Python}.\\


\Note{In \BornAgain\ the particles are positioned in the same vertical
  layer.}

\subsection{Size-distribution models}
\index{Size-distribution models}%
The decoupling approximation (DA), local monodisperse approximation (LMA)
and size spacing correlation approximation (SSCA) can be used in \BornAgain.
The selection between DA and SSCA is made using\\
\Code{ILayout.setApproximation(EInterferenceFunction
  approximation)} when defining the characteristics of the way
particles and interference functions are embedded in a layer.  For
example,
\begin{lstlisting}
    particle_layout = ParticleLayout() ....  # interference approx
    chosen between: DA (default) and SSCA
    particle_layout.setApproximation(ILayout.DA)
\end{lstlisting}

Note that with the SSCA, the users have to specify the coupling
parameter $\kappa$ (with the function \Code{setKappa}), which should
be a positive dimensionless value. $\kappa$ characterizes the
influence of the neighboring particles' sizes on their distance. If
$\kappa=0$, the SSCA reduces to the DA with a radial paracrystal for
the interference function.\\

For the LMA, its implementation is automatically done when using more
than one layout of particles:
\begin{lstlisting}
    particle_layout0 = ParticleLayout() particle_layout1 =
    ParticleLayout() ....  # association of each particles' layout
    with materials, form factors #... and with a material layer
    layer_a = Layer(m_material_a) layer_a.addLayout(particle_layout0)
    layer_a.addLayout(particle_layout1)
\end{lstlisting}

%%ADD EXPLANATION ABOUT LMA

%-------------------------------------------------------------------------------
\subsection{Probability distribution functions}\label{baftd}
%-------------------------------------------------------------------------------

The probability distribution functions have been implemented in the
reciprocal space in \BornAgain. Their expressions are given in
Table~\ref{table:pdf}.

\begin{table}[H]
\centering
\begin{tabular}{ccc}
\hline Function & One dimension & Two dimensions\\ \hline Cauchy &
$(1+q^2\omega^2)^{-3/2}$ & $(1 + q_x^2 cl_x^2 + q_y^2 cl_y^2)^{-3/2}$
\\ Gauss & $\dfrac{1}{2}\exp(-\dfrac{q^2\omega^2}{4})$ &
$\frac{1}{2}\exp\left(-\dfrac{q_x^2 cl_x^2+ q_y^2cl_y^2}{4}\right)$
\\ Voigt & $\dfrac{\eta}{2} \exp\left(-\dfrac{q^2\omega^2}{4}\right) +
\dfrac{1 - \eta}{(1 + q^2\omega^2)^{3/2}}$ & $\dfrac{\eta}{2}
\exp\left(-\dfrac{q_x^2 cl_x^2+ q_y^2cl_y^2}{4}\right)+ \dfrac{1 -
  \eta}{(1 + q_x^2 cl_x^2+ q_y^2cl_y^2)^{3/2}}$ \\ \hline
\end{tabular}
\caption{List of probability distribution functions in reciprocal
  space. $\omega$, $cl$ stand for coherence lengths (the index refers
  to the axis) and $\eta$ is a weighting coefficient.}
\label{table:pdf}
\end{table}

The Cauchy distribution corresponds to $\exp(-r)$ in real space and
the Voigt one is a linear combination of the Gaussian and Cauchy
probability distribution functions.\\

\noindent \underline{One dimension}
\begin{itemize}
\item \Code{FTDistribution1DCauchy($\omega$)},
\item \Code{FTDistribution1DGauss($\omega$)},
\item \Code{FTDistribution1DVoigt($\omega, \eta$)}.
\end{itemize}
where $\omega$ is the coherence length and $\eta$ is a weighting
factor.\\

\noindent \underline{Two dimensions}
\begin{itemize}
\item \Code{FTDistribution2DCauchy($cl_x$, $cl_y$)},
\item \Code{FTDistribution2DGauss($cl_x$, $cl_y$)},
\item \Code{FTDistribution2DVoigt($cl_x$, $cl_y$)}
\end{itemize}
where $cl_{x,y}$ are the coherence lengths in the $x$ or $y$
direction, respectively.

These functions can be used with all interference functions, except
the case without any interference.

%-------------------------------------------------------------------------------
\subsection{Interferences}
%-------------------------------------------------------------------------------
\index{Interference function}%

The interference function is specified when building the sample. It is
linked with the particles (shape, material). Examples of
implementation are given at the end of each description.

\paragraph{Syntax:}
 \Code{particle\_layout.setInterferenceFunction(interference\_function)},\\ where
 \Code{particle\_layout} holds the information about the different
 shapes and their proportions for a given layer of particles, and
 \Code{interference\_function} is one of the following expressions:
\begin{itemize}
\item \Code{InterferenceFunctionNone()}
\item \Code{InterferenceFunction1DLattice(lattice\_parameters)}
\item \Code{InterferenceFunctionRadialParaCrystal(peak\_distance,
  damping\_length)}
\item \Code{InterferenceFunction2DLattice(lattice\_parameters)}
\item \Code{InterferenceFunction2DParaCrystal(length\_1, length\_2,
  $\alpha$\_lattice, $\xi$, \\ damping\_length)}
\end{itemize}

\Note{\Code{InterferenceFunction1DLattice} can only be used for
  particles which are infinitely long in one direction of the sample's
  surface like for example a rectangular grating.}

\newpage
%-------------------------------------------------------------------------------
\subsection{InterferenceFunctionNone}
%-------------------------------------------------------------------------------

The particles are placed randomly in the dilute limit and are
considered as individual, non-interacting scatterers. The scattered
intensity is function of the form factors only.

\paragraph{Example} The sample is made of a substrate on which are deposited half-spheres. Script~\ref{lst:nointerf} details the commands necessary to generate such a sample. \Cref{fig:nointerf} shows an example of output intensity: Script~\ref{lst:nointerf}  + detector's + input beam's characterizations.


\begin{figure}[tb]
\begin{center}
\includegraphics[angle=-90,width=0.5\textwidth]{fig/gisasmap/HSphere_NoInterf.pdf}
\end{center}
\caption{Output intensity scattered from a sample made of half-spheres
  with no interference between them.}
\label{fig:nointerf}
\end{figure}

\FloatBarrier
\newpage

\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to simulate a sample made of half-spheres deposited on a substrate layer without any interference. The part specific to the interferences is marked in a red italic font.},label={lst:nointerf}]
def get_sample(): """ Build and return the sample representing
particles with no interference """ # defining materials m_ambience =
HomogeneousMaterial("Air", 0.0, 0.0) m_substrate =
HomogeneousMaterial("Substrate", 6e-6, 2e-8) m_particle =
HomogeneousMaterial("Particle", 6e-4, 2e-8) # collection of particles
sphere_ff = FormFactorTruncatedSphere(5*nanometer, 5*nanometer) sphere
= Particle(m_particle, sphere_ff) particle_layout = ParticleLayout()
particle_layout.addParticle(sphere, 1.0) |interference =
InterferenceFunctionNone()|
|particle_layout.setInterferenceFunction(interference)| # assembling
the sample air_layer = Layer(m_ambience)
air_layer.addLayout(particle_layout) substrate_layer =
Layer(m_substrate, 0)

    multi_layer = MultiLayer() multi_layer.addLayer(air_layer)
    multi_layer.addLayer(substrate_layer) return multi_layer
\end{lstlisting}

\newpage
%-------------------------------------------------------------------------------
\subsection{\Code{InterferenceFunction1DLattice(lattice\_length, xi)}}
%-------------------------------------------------------------------------------
where lattice\_length is the lattice constant and $\xi$ the angle in
radian between the lattice unit vector and the $\v{x}$-axis of the
reference Cartesian frame as shown in \cref{fig:1dgrating}.

\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.75\textwidth]{fig/drawing/1DGrating.pdf}
\end{center}
\caption{Schematic representation of a 1D lattice (side and top
  views). Such a lattice is characterized by a lattice length and the
  angle $\xi$.}
\label{fig:1dgrating}
\end{figure}

\Note{By default the long axis of the particles in this 1D lattice is
  along the beam axis. That is the reason why in the example below the
  particles are rotated by $90^{\circ}$ in the $(x,y)$ plane: the main
  axis of the lattice is therefore parallel to the y-axis,
  perpendicular to the long axis of the particles.}

\vspace{12pt} A probability distribution function \Code{pdf} has to be
chosen from the list in \cref{baftd} in order to apply some
modifications to the scattering peaks. This function is implemented
using \Code{setProbabilityDistribution(pdf)}.

\paragraph{Example:} Script~\ref{lst:1dlattinterf} details how to build in  \BornAgain\ a sample using\\ \Code{InterferenceFunction1DLattice} as the interference function. As mentioned previously, this interference function can only be used with infinitely wide or long particles.\\ Here the sample is made of infinitely long boxes deposited on a substrate (these particles are characterized by their widths and heights). They are also rotated by $90^{\circ}$  in the sample surface in order to have their long axis perpendicular to the input beam, which is along the $x$-axis.\\
 The lattice parameters (the lattice length and angle between the
 lattice main axis and the $x$-axis) are passed into the constructor
 of the interference function.

\newpage
\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to generate a sample made of infinitely long boxes deposited on a substrate layer with the 1DLatticeInterference function. The part specific to the interferences is marked in a red italic font.},label={lst:1dlattinterf}]
def get_sample(): """ Build and return the sample with
1DLatticeInterference function """ # defining materials m_air =
HomogeneousMaterial("Air", 0.0, 0.0) m_substrate =
HomogeneousMaterial("Substrate", 6e-6, 2e-8) m_particle =
HomogeneousMaterial("Particle", 6e-4, 2e-8)

    # collection of particles ff = FormFactorInfLongBox(10.*nanometer,
15.0*nanometer) box = Particle(m_particle, ff) particle_layout =
ParticleLayout() transform = Transform3D.createRotateZ(90.0*degree)
particle_layout.addParticle(box, transform)

    # interference function |interference =
InterferenceFunction1DLattice(30.0*nanometer, 0.0*degree)| |pdf =
FTDistribution1DCauchy(200./2./M_PI*nanometer)|
|interference.setProbabilityDistribution(pdf)|
|particle_layout.setInterferenceFunction(interference)|

    # air layer with particles and substrate form multi layer
air_layer = Layer(m_air) air_layer.addLayout(particle_layout)
substrate_layer = Layer(m_substrate, 0)

    multi_layer = MultiLayer() multi_layer.addLayer(air_layer)
    multi_layer.addLayer(substrate_layer) return multi_layer
\end{lstlisting}

\newpage
%-------------------------------------------------------------------------------
\subsection{\Code{InterferenceFunctionRadialParaCrystal(peak\_distance, damping\_length)}}
%-------------------------------------------------------------------------------
\begin{itemize}
\item[where] \Code{peak\_distance} is the average distance to the
  first neighbor peak,
\item[]\Code{width} is the width parameter of the probability
  distribution,
\item[] \Code{damping\_length} is used to introduce finite size
  effects by applying a multiplicative coefficient equal to
  $\exp$(-\Code{peak\_distance/damping\_length}) to the Fourier
  transform of the probability densities. \Code{damping\_length} is
  equal to 0 by default and, in this case, no correction is applied.
\end{itemize}

A probability distribution function \Code{pdf} has to be chosen from
the list in \cref{baftd} in order to apply some modifications to the
scattering peaks. This function is implemented using
\Code{setProbabilityDistribution(pdf)}.


\Note{ This interference function is not one-dimensional.  It takes
  into account the radial component of the scattering vector.  }

\paragraph{Example}
To illustrate the radial paracrystal interference function, we use the
same sample as in the case without interference: half-spheres
deposited on a substrate.

\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to define the radial paracrystal interference function between half-spheres, where \Code{trsphere} is of type \Code{Particle}.},label={lst:1dpara}]
    particle_layout = ParticleLayout()
    particle_layout.addParticle(trsphere, 1.0) interference =
    InterferenceFunctionRadialParaCrystal(25.0*nanometer,
    1e3*nanometer) pdf = FTDistribution1DGauss(7 * nanometer)
    interference.setProbabilityDistribution(pdf)
    particle_layout.setInterferenceFunction(interference)
\end{lstlisting}



\begin{figure}[tb]
\begin{center}
\includegraphics[angle=-90,width=0.5\textwidth]{fig/gisasmap/HSphere_1DDL.pdf}
\end{center}
\caption{Output intensity scattered from a sample made of half-spheres
  with the radial paracrystal interference between them. This figure
  has been generated using Script~\ref{lst:1dpara} for the
  interference function.}
\label{fig:1ddl}
\end{figure}

\FloatBarrier

\newpage
%-------------------------------------------------------------------------------
\subsection{\Code{InterferenceFunction2DLattice(L\_1, L\_2, alpha, xi)}}
%-------------------------------------------------------------------------------
where ($L_1$, $L_2$, $\alpha$, $\xi$) are shown in
\cref{fig:2dlattice} with
\begin{itemize}
\item[]$L_1$, $L_2$ the lengths of the lattice cell,
\item[]$\alpha$ the angle between the lattice basis vectors $\v{a},
  \v{b}$ in direct space,
\item[] $\xi$ is the angle defining the lattice orientation (set to
  $0$ by default); it is taken as the angle between the $\v{a}$ vector
  of the lattice basis and the $\v{x}$ axis of the reference Cartesian
  frame (as shown in \cref{fig:2dlattice}).
\end{itemize}

\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.5\textwidth]{fig/drawing/2Dlattice.pdf}
\end{center}
\caption{Schematic representation of a 2D lattice (top view). Such a
  lattice is characterized by lattice lengths $L_1$, $L_2$ and angles
  $\alpha$ and $\xi$.}
\label{fig:2dlattice}
\end{figure}

Like for the one-dimensional case, a probability distribution function
\Code{pdf} has to be defined. One can choose between those listed in
\cref{baftd} and implements it using
\Code{setProbabilityDistribution(pdf)}.

\paragraph{Example} The sample used to run the simulation is made of half-spheres deposited on a substrate. The interference function is "2Dlattice" and the particles are located at the nodes of a square lattice with $L_1=L_2=20$~nm, $\v{a}\equiv \v{b}$ and the probability distribution function is Gaussian. We also use the Decoupling Approximation.

\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to define a 2DLattice interference function between hemi-spherical particles as well as the Decoupling Approximation in \Code{getSimulation()}.  The part specific to the interferences is marked in a red italic font.},label={lst:2dlatticeinterf}]
    #collection of particles sphere_ff =
  FormFactorTruncatedSphere(5*nanometer, 5*nanometer) sphere =
  Particle(m_particle, sphere_ff) |interference =
  InterferenceFunction2DLattice(20.0*nanometer, 20.0*nanometer,
  90.0*degree, 0.0*degree)| |pdf =
  FTDistribution2DGauss(200.0*nanometer/2.0/M_PI,
  75.0*nanometer/2.0/M_PI)|
  |interference.setProbabilityDistribution(pdf)| particle_layout =
  ParticleLayout() particle_layout.addParticle(sphere, 1.0)
  |particle_layout.setInterferenceFunction(interference)|

    # interference approx chosen between: DA (default) and SSCA
  |particle_layout.setApproximation(ILayout.DA)|
\end{lstlisting}

%\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol]
%def get_simulation():
%    """
%    Create and return GISAXS simulation with beam and detector
%    """
%    simulation = Simulation()
%    simulation.setDetectorParameters(100, 0.0*degree, 2.0*degree, 100, 0.0*degree, 2.0*degree, True)
%    simulation.setBeamParameters(1.0*angstrom, 0.2*degree, 0.0*degree)
%    return simulation
%\end{lstlisting}


\begin{figure}[tb]
\begin{center}
\includegraphics[angle=-90,width=0.5\textwidth]{fig/gisasmap/HSphere_2Dlattice.pdf}
\end{center}
\caption{Output intensity scattered from a sample made of half-spheres
  with 2DLattice interference function in the Decoupling
  Approximation.}
\label{fig:2dlatticeintensity}
\end{figure}

\FloatBarrier

\newpage%{\cleardoublepage}
%-------------------------------------------------------------------------------
\subsection{InterferenceFunction2DParaCrystal($L_1$, $L_2$, lattice\_angle, $xi$, damping\_length)} % TODO RESTORE \Code{}, \xi
%-------------------------------------------------------------------------------
\begin{itemize}
\item[where] $L_1$, $L_2$ are the lengths of the lattice cell,
\item[] lattice\_angle the angle between the lattice basis vectors
  $\v{a}, \v{b}$ in direct space,
\item[] $\xi$ is the angle defining the lattice orientation (set to
  $0$ by default).
\item[] \Code{damping\_length} is used to introduce finite size
  effects by applying a multiplicative coefficient equal to
  $\exp$(-\Code{peak\_distance/damping\_length}) to the Fourier
  transform of the probability densities. \Code{damping\_length} is
  equal to 0 by default and, in this case, no correction is applied.
\end{itemize}
Two predefined interference functions can also be used:
\begin{itemize}
\item \Code{createSquare(peak\_distance, damping\_length,
  domain\_size\_1, domain\_size\_2)}\\ where the angle between the
  base vectors of the lattice is set to $\pi/2$, it creates a squared
  lattice,
\item \Code{createHexagonal(peak\_distance, damping\_length,
  domain\_size\_1, domain\_size\_2)}\\ where the angle between the
  base vectors of the lattice is set to $2\pi/3$ ,
\end{itemize}
where \Code{domain\_size1, 2} are the dimensions of coherent domains
of the paracrystal along the main axes,\\ \Code{peak\_distance} is the
same in both directions and $\v{a}\equiv \v{x}$.\\

Probability distribution functions have to be defined. As the
two-dimensional paracrystal is defined from two independent
one-dimensional paracrystals, we need two of these functions,
using\\ \Code{setProbabilityDistributions(pdf\_1, pdf\_2)}, with
\Code{pdf\_{1,2}} related to each main axis of the paracrystal (see
\cref{fig:2dparaschematic}).


\begin{figure}[tb]
\begin{center}
\includegraphics[width=0.75\textwidth]{fig/drawing/drawing2Dparacrystal.pdf}
\end{center}
\caption{Schematics of the ideal 2D paracrystal. The gray-shaded areas
  mark the regions where the probability to find a node is larger that
  the width at half-maximum of the distribution. $L$ and $W$ are the
  mean inter-node distances along the two crystallographic
  axes. cl$_{(L,W),(x,y)}$ are the widths of the distribution of
  distance. The disorder is propagated as we add more nodes. Such a
  structure would be generated using
  \Code{InterferenceFunction2DParacrystal(L,W,90.*degrees,0,damp\_length)},
  with \Code{pdf$_1$ = FTDistribution2DGauss(cl$_{L,x}$,cl$_{L,y}$)}
  and \Code{pdf$_2$ = FTDistribution2DGauss(cl$_{W,x}$,cl$_{W,y}$)}.}
\label{fig:2dparaschematic}
\end{figure}


\paragraph{Example} The particles deposited on a substrate are half-spheres. The scattered beams interference via the 2DParacrystal distribution function. The paracrystal is based on a 2D hexagonal lattice with a Gaussian probability distribution function in reciprocal space.  Script~\ref{lst:2dparainterf} shows the implementation of the interference function and \cref{fig:2ddl} an example of output intensity using hemi-spherical particles.

\begin{lstlisting}[language=python, style=eclipseboxed,numbers=none,nolol,caption={\Code{Python} script to define a "2DParacrystal" interference function between particles forming an hexagonal monolayer. },label={lst:2dparainterf}]
    interference =
    InterferenceFunction2DParaCrystal.createHexagonal(30.0*nanometer,0.0,
    40.0*micrometer, 40.0*micrometer)| pdf =
    FTDistribution2DCauchy(1.0*nanometer, 1.0*nanometer)
    interference.setProbabilityDistributions(pdf, pdf)
    particle_layout.setInterferenceFunction(interference)
\end{lstlisting}

\begin{figure}[tb]
\begin{center}
\includegraphics[angle=-90,width=0.5\textwidth]{fig/gisasmap/HSphere_2DDL.pdf}
\end{center}
\caption{Output intensity scattered from a sample made of half-spheres
  with 2DParacrystal interference function.}
\label{fig:2ddl}
\end{figure}

\FloatBarrier


%===============================================================================
\subsection{Summary}
%===============================================================================

\begin{table}[h]
  \footnotesize
\begin{tabular}{lll}
\hline Function & Parameters & Comments\\ \hline
\Code{InterferenceFunctionNone} & None & disordered distribution
\\ \hline \Code{InterferenceFunction1DLattice} &
\Code{lattice\_length} & use only with infinitely long/wide particles
\\ & $\xi=\widehat{(\v{x},\v{a})}$ & pdf=(Cauchy, Gauss or Voigt) to
be defined\\ \hline \Code{InterferenceFunctionRadialParaCrystal} &
peak\_distance of pdf & pdf=(Cauchy, Gauss or Voigt) to be defined
\\ & damping\_length (optional) & \\ \hline
\Code{InterferenceFunction2DLattice} & L\_1, L\_2: lattice lengths &
pdf=(Cauchy, Gauss or Voigt) to be defined\\ &
lattice\_angle=$\widehat{(\v{a},\v{b})}$ & \\ & $\xi
=\widehat{(\v{x},\v{a})}$ & \\ \hline
\Code{InterferenceFunction2DParaCrystal} & L\_1, L\_2: lattice lengths
& 2D pdf=(Cauchy, Gauss or Voigt) to be defined \\ &
lattice\_angle=$\widehat{(\v{a},\v{b})}$ & (1 pdf per axis) \\ &
$\xi=\widehat{(\v{x},\v{a})}$ & \\ & damping\_length (optional) & same
for both axes\\ \hline \hline
\end{tabular}
\caption{List of interference functions implemented in \BornAgain. pdf
  : probability distribution function, $\v{a}, \v{b}$ are the lattice
  base vectors, and $\v{x}$ is the axis vector perpendicular to the
  detector plane.}
\end{table}

\fi

\index{Particle assemblies|)}%
