Documentation: Doxygen page about interference functions (text and figures),...

Documentation: Doxygen page about interference functions (text and figures), UserManual (modifications of ff.tex and interferences.tex)

Core/Algorithms/inc/SimulationParameters.h

@@ -21,6 +21,7 @@
 //! @class Simulation
 //! @ingroup simulation
 //! @brief Collect the different options for simulation
+//! @ref SimulationParameters
 
 class BA_CORE_API_ SimulationParameters
 {

Doc/Doxygen/defgroups.doc

@@ -16,6 +16,107 @@
 \defgroup interference Interference functions
 @brief Available interference functions.
 
+Position of the problem
+----------------------------------------------------------
+\note For collections of particles, the scattered intensity contains contributions from neighboring particles. This additional pattern can be called the structure factor, the interference function or even in crystallography, the lattice factor. In this manual, we use the term "interference function" or interferences.
+
+Interferences are closely related to the way the sample is described. For example, how are the particles distributed? Are they clustered by shapes and / or sizes? Or is the layout completely disordered? What is the distance between the particles?
+Taking this kind of questions into account requires several features implemented in BornAgain.
+
+First we need some hypotheses in order to estimate the scattered intensity from the contributions of the form factors, the interferences and some possible correlations. Several options are available to determine the level of "coupling" between these terms: Decoupling approximation (DA), Local monodisperse approximation (LMA) or Size spacing correlation approximation (SSCA). \see SimulationParameters for a description.
+
+Let's now focus on the interference functions.
+
+
+Interferences
+----------------------------------------------------------
+\warning In BornAgain the particles are positioned in the same vertical layer.
+
+
+The interference function is specified when building the sample. It is linked with the particles (shapes, materials). 
+
+\b Syntax:
+
+\b particle\_layout.addInterferenceFunction(interference\_function),
+
+ where \b particle\_layout holds the information about the different shapes and their proportions for a given layer of particles and \b interference\_function is one of the following expressions:
+
+
+
+
+InterferenceFunctionNone()
+
+For very diluted distributions of particles, the particles are too far apart from each other to lead to any interference between the waves scattered by each of them. In this case the interference function is equal to 1. The scattered intensity is then entirely determined by the form factors of the particles distributed in the sample.
+
+
+
+
+InterferenceFunction1DLattice (lattice\_length, \f$\xi\f$) 
+
+where lattice\_length is the lattice constant and \f$\xi\f$ the angle between the lattice unit vector and the \b x axis of the GISAS setup.
+
+\warning InterferenceFunction1DLattice can only be used for particles which are infinitely long in one of sample surface's directions like, for example, a rectangular grating as illustrated in the figure below.
+
+@image html Figures/grating3D.png "Schematic 3D representation of a 1D lattice."
+
+\warning By default the long axis of the particles in this 1D lattice is along the beam axis: \f$\xi = 90^{\circ}\f$.
+
+A probability distribution function (pdf) is required in order to apply some  modifications to the scattering peaks. This function is implemented using \b setProbabilityDistributions(pdf) (see end of this page for a short description).
+
+
+
+
+InterferenceFunction1DParaCrystal (peak\_distance, width, corr\_length)
+
+where peak\_distance, width, corr\_length are the parameters characterizing the probability distribution function.
+
+\warning For this particular interference function, the implemented probability distribution function is Gaussian.
+
+\note A paracrystal 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.
+
+
+
+
+
+InterferenceFunction2DLattice (L\_1, L\_2, \f$\alpha\f$, \f$\xi\f$) 
+
+where
+- L\_1, L\_2 the lengths of the lattice cell, 
+- \f$\alpha\f$ the angle between the lattice basis vectors \b a, \b b in direct space,
+- \f$\xi\f$ is the angle defining the lattice orientation (set to 0 by default); it is taken as the angle between the \b a vector of the lattice basis and the \b x axis of the GISAS setup referential.  (see an illustration in the figure below)
+
+@image html Figures/2Dlattice.png "Schematic representation of a 2D lattice (top view)."
+
+A probability distribution function (pdf) has to be defined. This function is implemented using \b setProbabilityDistributions(pdf).
+
+
+
+
+
+InterferenceFunction2DParaCrystal(L\_1, L\_2, lattice\_angle, \f$\xi\f$, correlation\_length)
+where 
+- L\_1, L\_2 are the lengths of the lattice cell,
+- lattice\_angle the angle between the lattice basis vectors \b a, \b b  in direct space,
+- \f$\xi\f$ is the angle defining the lattice orientation (set to 0 by default).
+
+
+Two predefined interference functions for specific layouts of particles can be used:
+- \b createSquare (peak\_distance, correlation\_length, domain\_size\_1, domain\_size\_2)
+where the angle between the base vectors of the lattice is set to \f$\pi\f$/2. It creates a squared lattice
+- \b createHexagonal (peak\_distance, correlation_length, domain\_size\_1, domain\_size\_2) 
+where the angle between the base vectors of the lattice is set to 2\f$\pi\f$/3, domain\_size1 and domain\_size2  are the dimensions of the paracrystal along the main axes, peak\_distance and correlation\_length are related to the probability distribution functions and are the same in both directions and \b a \f$\equiv\f$ \b x .
+
+Probability distribution functions have to be defined. As the two-dimensional paracrystal is defined from two independent 1D paracrystals, we need two of these functions, using \b setProbabilityDistributions(pdf\_1, pdf\_2)
+
+
+
+\note \b Probability \b distribution \b functions
+\note 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 
+\note - in direct space using correlation functions or by truncating the lattice or,
+\note - in reciprocal space with structure factors or interference functions by convoluting the scattered pics with a function which could reproduce the experimental shapes.
+\note The last option has been chosen in BornAgain. These functions can be used with all interference functions except the case without any interference and the one dimensional paracrystal, for which only the Gaussian case has already been implemented.
+
+
 \defgroup algorithms Algorithms
 @brief Additional routines.