diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_1994_3_25-29.pdf b/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_1994_3_25-29.pdf old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_2004_12_24.pdf b/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_2004_12_24.pdf old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_2005_13_19-22.pdf b/src/sas/qtgui/Perspectives/Corfunc/media/Fibre_Diffraction_Review_2005_13_19-22.pdf old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.png b/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.png new file mode 100644 index 0000000000..0e3c46bb77 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.svg b/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.svg new file mode 100644 index 0000000000..0bff18d8d0 --- /dev/null +++ b/src/sas/qtgui/Perspectives/Corfunc/media/commutivity.svg @@ -0,0 +1,316 @@ + + + + + + + + + + + + + + + + + + + γ(r)CorrelationFunction + + F(q)Form/StructureFactor + I(q)ScatteringAmplitude + ρ(r)ScatteringLength Density + + + + + + Autocorrelation + Square Magnitude + FourierTransform + FourierTransform + Loss of PhaseInformation + Loss of PhaseInformation + + diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-how-to.rst b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-how-to.rst new file mode 100644 index 0000000000..697fca63bc --- /dev/null +++ b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-how-to.rst @@ -0,0 +1,93 @@ +.. _corfunc-how-to: + +How To Use Corfunc +================== + +Running a Calculation +--------------------- + +Upon sending data for correlation function analysis, it will be plotted (minus +the background value), along with a bar indicating the upper end of the +low-Q range (used for Guinier back-extrapolation) and 2 bars indicating +the range to be used for Porod forward-extrapolation. + +This information is also shown on the orange and green interactive slider on the left. +You can drag bars on this slider (not the plot), or enter values manually. + +.. figure:: tutorial_data_loaded.png + :align: center + +Once the Q ranges have been set, click the "Go" button to run the analysis. +This will run through the process described in the technical documentation using the +default options shown above the button. + +The parameters used along the way can be overriden by changing them in the appropriate text boxes, +and whether or not they are recalculated is controlled by the check boxes. + +Options +------- + +In addition to the checkboxes that control whether parts of the calculation are executed, +there are options for choosing how the lamellar parameters are extracted. +These are intended to give flexibility to users and allow for manual control in certain edge +cases, or where there are small errors in the transformed data. + +Automatic selection is the most robust choice, this will choose the leftmost option +as long as it is feasible. + + +The extra options are as follows: + +1) There is an option to choose how the tangent slope used for calculating lamellar parameters +such as `hard block` are calculated. Usually this is done by finding the inflection point of the +curve. However, in some datasets it is more appropriate to use the point half way between the minimum +and maximum values of :math:`\Gamma_1`; + +2) The second option chooses whether to use the first minimum or subsequent maximum to infer the periodicity. +The standard option is to use the maximum, but in some cases, such as where the period is +long compared to experimental data, +it might be necessary to use twice the minimum as a proxy. + +The automatic selection should be appropriate for general use. + +Output +------ + +When the calculation is complete, the extrapolated curve will be shown on the Q-space plot. + + .. figure:: tutorial_after_go.png + :align: center + +The `Real Space` tab shows plots of :math:`\Gamma_1` and :math:`\Gamma_3` + + .. figure:: tutorial_real_space.png + :align: center + +To check the extrapolation parameters, a diagram shows the geometric construction used to +derive them in the `Extraction Diagram` tab. + + .. figure:: tutorial_extraction.png + :align: center + +Finally, you can see the interface distribution function in the `IDF` tab + + .. figure:: tutorial_idf.png + :align: center + +The export buttons allow you to produce CSV files containing either the extrapolated +Q-space data, or the transformed data. + +The structure of the transformed data file is shown below (note that as this is a 4 column .csv file, +SasView will interpret this as a :math:`I(q)` vs :math:`q` curve if you try to load it from the main +SasView window). + + .. figure:: tutorial_export_data.png + :align: center + +.. note:: If *Export Extrapolated* is selected a dialog box will appear in which the + bounds and binning of the extrapolated data can be selected. This is pre-populated + with the values for the experimental data; i.e. using these values would *not* + actually include any extrapolated data! + +.. figure:: tutorial_extrapolate.png + :align: center diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-technical.rst b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-technical.rst new file mode 100644 index 0000000000..a14143499a --- /dev/null +++ b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-technical.rst @@ -0,0 +1,189 @@ +.. _corfunc-technical: + +Corfunc Technical Documentation +=============================== + +In Brief +-------- + +.. figure:: tutorial_data_loaded.png + :align: center + +The correlation function analysis is performed in **3 steps**. + +First, the scattering curve is **extrapolated** to :math:`Q = 0` (Guinier) and toward +:math:`Q = \infty` (Porod), the details of the extrapolation is controlled by +the parameters `Guinier End`, `Porod Start` and `Porod End`, which +are settable by entering text, or by using the `Adjust` slider. +There is a smooth transition from the data to the extrapolation, start and end refer to +the region over which this occurs (see below). +Parameters for the extrapolation can manually entered in `Extrapolation Parameters` and +SasView can be told whether to recalcuate the parameters using the `Fit Background`, +`Fit Guinier` and `Fit Porod` checkboxes. + +Secondly, the data is **transformed** to obtain the projected correlation functions. + +Finally, the transformed data is **interpreted** in terms of an ideal lamellar morphology + + +Extrapolation +------------- + +Small Q +....... + +The scattering data is extrapolated to :math:`q = 0` by fitting a Guinier function, defined as + +.. math:: + I(q) = e^{A + Bq^2} + +to data up to :math:`q` value specified by `Guinier Start`. + +This a Gaussian centred at :math:`q=0` (we only ever see the positive half). +The natural logarithm of the parameter :math:`A` is a constant of proportionality +equal to the scattering intensity at :math:`q=0`. +The parameter :math:`B` describes the width of the function and is related to the +size of the scattering object. For example, in systems of dispersed spherical +particles it is related to the radius of gyration :math:`R_g` by :math:`B = R_g^2 / 3`. + +*Note:* The Guinier model makes assumptions that do not hold for all systems +and so this approximation might not always be accurate. +If errors from the Guinier model fit occur, they will manifest as a constant offset in the correlation function, +because low :math:`q` values correspond to a long periodicity in :math:`x`. +Empirically, however, inaccuracies in the Guinier region have a very low impact on the +final analysis, and only some of the lamellar parameters will be affected at all. + +Large Q +....... + +The data is extrapolated towards :math:`q = \infty` by fitting a Porod model, to the region +between `Porod Start` and `Porod End`. This model is defined by + +.. math:: + I(q) = K q^{-4} e^{-q^2\sigma^2} + I_{B} + +Where :math:`I_B` is the background intensity, :math:`K` is the Porod constant, and :math:`\sigma` is a +parameter which, in a two phase system, describes the sharpness of the scattering length density +profile at the interface between phases. + +This model comprises three components, a constant background intensity, the standard Porod law, so + +.. math:: + I(q) - I_B \propto q^{-4} + +and a contribution which is attibutable to the sharpness of the boundaries between regions. so + +.. math:: + I(q) - I_B \propto e^{-q^2\sigma^2} + +SasView will use this formula to extrapolate to very large :math:`q` (100 +times the maximum data value). This ensures that the transform used in the +next stage does not contain artefacts (i.e. from treating secular data as periodic) + + +Merging +....... + +In the final step before transformation, the experimental and model data are merged together. +For the Guinier model, this happens on the region between the start of the experimental data and +the value specified by `Guinier End`. +For the Porod model, the merging happens between `Porod Start` and `Porod End`. + ++----------------+-------------------+-------------------+ +| From | To | Data | ++================+===================+===================+ +|| 0 || Start of data || Guinier Model | +|| Start of data || *Guinier End* || Guinier/Data mix | +|| *Guinier End* || *Porod Start* || Data | +|| *Porod Start* || *Porod End* || Data/Porod mix | +|| *Porod End* || 100x end of data || Porod model | ++----------------+-------------------+-------------------+ + +A smooth transition is achieved with sigmoid weighting defined as follows. +We start with two input functions, :math:`f(x)` on the 'left' and :math:`g(x)` on the 'right', and these +are to be smoothed over the range :math:`[a, b]`. +We use :math:`y(x)` to represent the transition over :math:`[a,b]`. :math:`y(x)` is given by the following convex combination + +.. math:: + y(x) = h(x) g(x) + (1-h(x))f(x) + +where :math:`h(x)` is a weighting between the two, with a value of zero at :math:`a` and one at :math:`b`, defined as + +.. math:: + h(x) = \frac{1}{1 + \frac{(x-b)^2}{(x-a)^2}} + + +Transformation +-------------- + +Corfunc uses a discrete cosine transform on the extrapolated data in order to calculate the +1D correlation function as: + +.. math:: + \Gamma _{1}(x) = \frac{1}{Q^{*}} \int_{0}^{\infty }I(q) q^{2} cos(qx) dq + +where Q\ :sup:`*` is the Scattering (also called Porod) Invariant. + +The following algorithm is applied: + +.. math:: + \Gamma(x_k) = 2 \sum_{n=0}^{N-1} x_n \cos{\left[ \frac{\pi}{N} + \left(n + \frac{1}{2} \right) k \right] } \text{ for } k = 0, 1, \ldots, + N-1, N + +The 3D correlation function is calculated as: + +.. math:: + \Gamma _{3}(x) = \frac{1}{Q^{*}} \int_{0}^{\infty}I(q) q^{2} + \frac{sin(qx)}{qx} dq + +.. note:: It is always advisable to inspect Γ\ :sub:`1`\ (x) and Γ\ :sub:`3`\ (x) + for artefacts arising from the extrapolation and transformation processes: + + - do they tend to zero as x tends to :math:`\infty`? + - do they smoothly curve onto the ordinate at x = 0? (if not check the value + of :math:`\sigma` is sensible) + - are there ripples at x values corresponding to 2 :math:`\pi` over the two + q values at which the extrapolated and experimental data are merged? + - are there any artefacts at x values corresponding to 2 :math:`\pi` / q\ :sub:`max` in + the experimental data? + - and lastly, do the significant features/peaks in the correlation functions + actually correspond to anticpated spacings in the sample?!!! + +Finally, the program calculates the interface distribution function (IDF) g\ :sub:`1`\ (x) as +the discrete cosine transform of: + +.. math:: + q^{4} I(q) + +The IDF is proportional to the second derivative of Γ\ :sub:`1`\ (x). + + +Interpretation +-------------- + +Once the correlation functions have been calculated *SasView* will +try and interpret Γ\ :sub:`1`\ (x) in terms of an ideal lamellar morphology +as shown below. + +.. figure:: fig2.png + :align: center + +**It is for the user to decide if this interpretation has any relevance to their system!** + +The structural parameters extracted are: + +* Long Period :math:`= L_p` +* Average Hard Block Thickness :math:`= L_c` +* Average Core Thickness :math:`= D_0` +* Average Interface Thickness :math:`\text{} = D_{tr}` +* Eekhaut Polydispersity :math:`= \Gamma_{\text{min}}/\Gamma_{\text{max}}` +* Stribeck Polydispersity +* Local Crystallinity :math:`= L_c/L_p` + +which lead to: + +* Average Soft Block Thickness :math:`= L_p - L_c = L_a` +* Average Chord Length :math:`= ((1/L_c) + (1/L_a)) :sup:`-1`` +* Average Crystalline Chord Length :math:`= ((1/L_c) + (1/L_a)) :sup:`-1` / \Phi_{\text{c}}` +* Non-Ideality :math:`= (L_p – L_p*) :sup:`2` / L_p :sup:`2`` diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-theory.rst b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-theory.rst new file mode 100644 index 0000000000..8cecb2de94 --- /dev/null +++ b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc-theory.rst @@ -0,0 +1,372 @@ +.. _corfunc-theory: + + + +Correlation Function Theory +=========================== + +Overview +-------- + +In small angle scattering we measure the tendency for probe particles (neutrons, photons, etc) +to transfer various amounts of momentum to a sample. The momentum is generally inferred from the scattering angle +of probe particles, along with other information about the probe particles (e.g. kinetic energy). +Small angle scattering is assumed to be elastic, which allows the momentum transfer to be directly related to a wavelength, and thus +a spatial distance. The correlation function represents the scattering intensity in terms of this spatial distance, +rather than in terms of momentum transfer. + +We can interpret the correlation function in terms of the sample structure by thinking about +pairs of points separated by a given displacement. When, on average over the sample, the pairs of points +have a high scattering length density, then the correlation function has a large value. Similarly, +when the pairs have a low scattering length density, the correlation function is low. +More concretely: the correlation function :math:`\Gamma(\vec{r})` for vector :math:`\vec{r} = (x,y,z)` is proportional to +the pairwise product of scattering length densities for all points separated by the vector :math:`(x,y,z)` +summed over all orientations and locations. + +Another way of thinking about the correlation function is as the scattering length +density but with phase information removed. As scattering experiments contain +no phase information, calculating the correlation function +is as close as one can get to calculating the scattering length density from +scattering data without incorporating additional information. + +The nature of small angle scattering further limits what spatial information +can be recovered. Whilst in its most general form the correlation +function takes a three dimensional vector input, +small angle scattering measurements are limited to one or two dimensions, +which in turn limits the amount of information about the correlation +function that can be obtained. For this reason, in the correlation function +analysis tool we consider various one dimensional projections of the full +correlation function, labelled :math:`\Gamma_1` and :math:`\Gamma_3` . + +The :math:`\Gamma_1` projection looks at changes in a single +direction perpendicular to the beam, with the other directions being averaged. +The direction is typically selected by hand from a 2D measurement prior to analysis. +Theoretically, the correlation function will be fully recoved as long as the system +being looked at is truly one dimensional and properly aligned. +However, one must remember the constraints of a small angle scattering experiment, +we only measure a small range of momentum transfer, and extrapolate the rest, +as such the extrapolation steps must be appropriate for the system. +This is in addition to the usual considerations of resolution and systematic +measurement error. + +The :math:`\Gamma_3` projection is motivated by a system of +monodisperse, randomly oriented particles in dilute suspension, +such that there are no spatial correlations between particles. +It is the kind of system described by the Debye equation. +Just as is the case with :math:`\Gamma_1`, as long as one truly +has this kind of system, and with caveats about extrapolation +and experimental constraints, one should be able to fully recover +the correlation function. + +Lorentz Correction +------------------ + +Lorentz corrections are often used in correlation function analysis. +Corfunc uses a Lorentz correction of + +.. math:: + I(q) = q^2 I_\text{measured}(q) + +In what follows, we assume that appropriate corrections have been made. +:math:`I(q)` here is what would be called :math:`I_1(q)` in :ref:`Stribeck`. + +Formal Description +------------------ + +More formally, the correlation function is a quantity that arises naturally from calculating the square magnitude +of the three dimensional Fourier transform, which is proportional to the scattering amplitude. + +.. math:: + \frac{d\sigma}{d\Omega} \propto F(\vec{q}) F^*(\vec{q}) + +where + +.. math:: + F(\vec{q}) = \int \rho(r) e^{i \vec{r}\cdot\vec{q}} \; dr^3 + +where :math:`dr^3` is the volume element (:math:`dx\;dy\;dz`). + + +.. figure:: commutivity.png + :align: center + + + +A couple of algebraic steps will bring us to the correlation function: first, +as :math:`\rho` is real, and the conjugate of :math:`e^{ix}` is :math:`e^{-ix}` we +know that the conjugate of :math:`F` is given by + +.. math:: + F^*(\vec{q}) = \int \rho(r) e^{-i \vec{r}\cdot\vec{q}} + +meaning that, with some renaming of variables (from :math:`r` to :math:`s` and :math:`t`), we have + +.. math:: + F(\vec{q}) F^*(\vec{q}) = \left(\int \rho(\vec{t}) e^{i \vec{t}\cdot\vec{q}} \; dt^3\right)\left( \int \rho(\vec{s}) e^{-i \vec{s}\cdot\vec{q}} \; ds^3 \right) + +With some rearrangement this becomes + +.. math:: + \int\int \rho(\vec{s}) \rho(\vec{t}) e^{i (t-s)\cdot\vec{q}} \; dr^3 \; ds^3 + + +and now letting :math:`\vec{r} = \vec{t} - \vec{s}` +and applying the Fourier translation theorem, we can rewrite the above as +(note this is not the same :math:`\vec{r}` as before, but a new variable): + +.. math:: + \int\int \rho(\vec{s}) \rho(\vec{s} + \vec{r}) e^{i \vec{r}\cdot\vec{q}} \; ds^3 \; dr^3 + +Some final reordering of the integration gives + +.. math:: + \int \left[ \int \rho(\vec{s}) \rho(\vec{s} + \vec{r}) \; ds^3 \right] \; e^{i \vec{r}\cdot\vec{q}} \; dr^3 + +The quantity in square brackets is what is called the correlation function, :math:`\gamma(\vec{r})`, so: + +.. math:: + \gamma(\vec{r}) = \int \rho(\vec{s}) \rho(\vec{s} + \vec{r}) \; ds^3 + +and it is the quantity that is Fourier transformed (with some appropriate scaling) +to get the magnitude of the scattering. + +Some useful properties of the Correlation Function +.................................................. + +As we have mentioned before, the correlation function contains no phase information, +mathematically this is the same as saying (1) that its Fourier transform is purely real, +or (2) that the correlation function is an even function. The consequence of this is +that we can write the Fourier transform of the correlation function using a cosine instead +of a complex exponential. + +Demonstrating the evenness of the correlation function is easily done by a change of +the variable of integration from :math:`\vec{s}` +to :math:`\vec{u} = \vec{s} + \vec{r}`. + +.. math:: + \gamma(\vec{r}) = \int \rho(\vec{s}) \rho(\vec{s} + \vec{r}) \; ds^3 = \int \rho(\vec{u}-\vec{r}) \rho(\vec{u}) \; du^3 = \gamma(-\vec{r}) + +and from this we can show that its Fourier transform is real by applying the following +to each dimension in turn (shown here in the 1D case for even :math:`f(x)`). + +First, we split the integral into negative and positive :math:`x` parts: + +.. math:: + \int_{-\infty}^\infty f(x) e^{i x \xi} dx = \int_{-\infty}^0 f(x) e^{i x \xi} dx + \int_{0}^\infty f(x) e^{i x \xi} dx + +Let :math:`u = -x` for the negative part, use the fact that :math:`f(-x)=f(x)` and +recalculate the bounds of integration + +.. math:: + = \int_0^\infty f(u) e^{-i u \xi} du + \int_{0}^\inf f(x) e^{i x \xi} dx + +Note that :math:`u` only appears within the integral, so we can rename it to :math:`x` +and recombine it with the positive part. We can also multiply the integral by two and +the integrand by two, giving + +.. math:: + = 2 \int_0^\infty f(x) \frac{e^{i x \xi} + e^{-i x \xi}}{2} dx + +The fractional part of which is the complex definition of cosine. +Applying this definition and using the fact that :math:`f(x)` is even +to restore the original bounds of integration we get + +.. math:: + = \int_{-\infty}^{\infty} f(x) cos(x \xi) dx + +which shows that the Fourier transform is purely real, reflecting the +fact that there is no phase information (which would be encoded in the imaginary part). + + +The :math:`\Gamma_1` Projection +............................... + +Consider the Fourier transform of the three dimensional correlation function, + +.. math:: + \int\int\int \gamma(\vec{r}) e^{i \vec{r} \cdot \vec{q}} \; dx \; dy \; dz + + +Now let :math:`q_z = q_y = 0`. +The motivation for this is (1) that during small angle scattering :math:`q_z` +is small enough to be neglected, and (2) that we are choosing to measure +in one direction of the :math:`q_x q_y` plane. +We assume, without loss of generality, this to be where :math:`q_y=0`. + +This gives us :math:`q \cdot r = x q_x`, and so the transform becomes + +.. math:: + I(q) = \int \gamma(\vec{r}) e^{i x q_x} \; dx \; dy \; dz + +which we can rewrite as + +.. math:: + \int\left( \int\int \gamma(\vec{r}) \; dy\;dz\right) e^{i x q_x} \; dx + +the quantity in the brackets is :math:`\Gamma_1(x)`. That is to say + +.. math:: + \Gamma_1(x) = \int\int \gamma(\vec{r}) \;dy\;dz + +If we now use the fact that :math:`\gamma(\vec{r})` is an even function, +we can use the result above to get + +.. math:: + I(q) = \int \Gamma_1(x) \cos(qx) dx + +The job of Corfunc is now to invert this. The following operation does the job: + +.. math:: + \Gamma_1(x) = \int I(q) \cos(qx) dx + +We can check this by showing that + +.. math:: + f(y) = \int \left( \int f(x) \cos(qx) dx \right) \cos(qy) dq + +Doing this formally requires a fair bit of algebraic legwork, +but there is an informal argument that will get us there. +First note that we can write it as (hand-waving away the convergence issues) + +.. math:: + f(y) = \int f(x) \int cos(qx) cos(qy) dq dx + +Then the equation corresponds to the identity function if the integral + +.. math:: + \int cos(qx) cos(qy) dq + +is the delta function. This is the case, because cosine functions form an orthogonal basis. +When :math:`x=y` the integral is non-zero, being an +integral of the always positive :math:`cos^2(qx)`. +Conversely, when :math:`x \neq y` the integral is zero. + + + + +The :math:`\Gamma_3` Projection +............................... + +The :math:`\Gamma_3` projection is based on spherical symmetry. +It's derivation is essentially that of Debye's formula + +We begin with an expression for the scattered intensity as above + +.. math:: + I(\vec{q}) = \int_{\mathbb{R}^3} \gamma(\vec{r}) e^{i \vec{r} \cdot \vec{q}} dr^3 + +now, we want to average this over all angles, i.e. over all :math:`q`-vectors of a given length, and we do so in a coordinate +system relative to :math:`\vec{r}`. This is an unobvious choice of coordinate system, but it simplifies things greatly, +as in such a coordinate system, the dot product :math:`\vec{r}\cdot\vec{q}` becomes :math:`qr \cos\theta`. + +For our averaging there is a total of :math:`4\pi` steradians in a sphere, giving a leading factor of :math:`1/4\pi`. + +.. math:: + I(\vec{q}) = \frac{1}{4\pi}\int_{\phi=0}{\phi=2\pi}\int_{\theta=0}^{\theta=\pi}\int_{\vec{r}\in\mathbb{R}} \gamma(\vec{r}) e^{i qr \cos\theta} d\vec{r}^3 \sin(\theta) d\theta d\phi + +The integral is constant with with respect to :math:`\phi`, so drops out as a factor of :math:`2\pi`. + +.. math:: + = \frac{1}{2}\int_{\theta=0}^{\theta=\pi}\int_{\vec{r}\in\mathbb{R}^3} \gamma(\vec{r}) e^{i \vec{r} \cdot \vec{q}} d\vec{r}^3 \sin(\theta) d\theta + +and we can adjust the order of integration, noting that because of our choice of coordinate system, :math:`\gamma(\vec{r})` is +independent of :math:`\theta`. + +.. math:: + = \frac{1}{2}\int_{\vec{r}\in\mathbb{R}^3} \gamma(\vec{r}) \int_{\theta=0}^{\theta=\pi} e^{i \vec{r} \cdot \vec{q}} \sin(\theta) d\theta d\vec{r}^3 + +Now, we can consider the inner integral specifically, firstly by doing a substitution of :math:`u = -\cos\theta`. This +means that :math:`du = \sin\theta d\theta`, the interval :math:`\theta\in[0,\pi]` becomes :math:`u\in[1, -1]`. + +.. math:: + \int_{\theta=0}^{\theta=\pi} e^{i \vec{r} \cdot \vec{q}} \sin(\theta) d\theta = \int_{u=-1}^{u=1} e^{i q r u} du + +which is just an exponential and easily integrated + +.. math:: + = \left[ \frac{-i e^{i q r u}}{qr} \right]_{-1}^{1} = \frac{i \left(e^{-i q r} - e^{i q r} \right) }{qr} = 2 \frac{i \sinh(-iqr)}{qr} + +which by the relationship between complex trigonometric and hyperbolic functions becomes + +.. math:: + = 2 \frac{\sin qr}{qr} + +The leading :math:`2` will cancel the leading :math:`1/2` and the value of :math:`I(q)` can be seen to be + +.. math:: + I(q) = \int_{\vec{r}\in\mathbb{R}^3} \gamma(\vec{r}) \frac{\sin qr}{qr} d\vec{r}^3 + +Note that this object is not dependent on the angular components of :math:`\vec{r}`, so the integral +over :math:`\mathbb{R}^3` can be written as + +.. math:: + = \int_0^\infty \int_\Omega\gamma(\vec{r})d\Omega \frac{\sin qr}{qr} dr + +Where :math:`\Omega` is a solid angle element. Letting + +.. math:: + \Gamma_3(r) = \int_\Omega \gamma(\vec{r}) d\Omega + +we have, finally, + +.. math:: + I(q) = \int_0^\infty \Gamma_3(r) \frac{\sin qr}{qr} dr + +In corfunc we don't invert this directly, but do so via :math:`\Gamma_1` + +Relationship between :math:`\Gamma_1` and :math:`\Gamma_3` +.......................................................... + +Internally, Corfunc calculates :math:`\Gamma_3` from :math:`\Gamma_1`. +Let's now look at how we can get one from the other, starting with :math:`\Gamma_3`. + +.. math:: + \Gamma_3 = \int I(q) \frac{\sin(q x)}{q x} dq + +First, multiply by :math:`x` + +.. math:: + x \Gamma_3 = x \int I(q) \frac{\sin(q x)}{q x} dq = \int I(q) \frac{\sin(q x)}{q} dq + +Now take the derivative with respect to :math:`x` + +.. math:: + \frac{d}{dx} x \Gamma_3 = \frac{d}{dx} \int I(q) \frac{\sin(q x)}{q} dq = \int I(q) \cos (q x) dq = \Gamma_1 + +Which, after expressing in terms of :math:`\Gamma_1` gives us the relation we use in corfunc, for +calculating :math:`\Gamma_3` + +.. math:: + \Gamma_3(x) = \int_0^x \frac{\Gamma_1(r)}{r} dr + + + + +References +---------- + +.. [Rutland] + Ruland, W. *Coll. Polym. Sci.* (1977), 255, 417-427 + +.. [Strobl] + Strobl, G. R.; Schneider, M. *J. Polym. Sci.* (1980), 18, 1343-1359 + +.. [Koberstein] + Koberstein, J.; Stein R. *J. Polym. Sci. Phys. Ed.* (1983), 21, 2181-2200 + +.. [Calleja1] + Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 247-251 + +.. [Calleja2] + Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 257-261 + +.. [Calleja3] + Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 260-270 + +.. [Goschel] + Göschel, U.; Urban, G. *Polymer* (1995), 36, 3633-3639 + +.. [Stribeck] + Stribeck, N. *X-Ray Scattering of Soft Matter*, Springer. Berlin (2007), 138-161 + +:ref:`FDR` (PDF format) diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/corfunc_help.rst b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc_help.rst old mode 100755 new mode 100644 index e1f6fc8e44..812d106e5d --- a/src/sas/qtgui/Perspectives/Corfunc/media/corfunc_help.rst +++ b/src/sas/qtgui/Perspectives/Corfunc/media/corfunc_help.rst @@ -1,311 +1,21 @@ -.. corfunc_help.rst +.. _corfunc_help: -.. _Correlation_Function_Analysis: Correlation Function Analysis ============================= -Description ------------ +The Correlation Function Analysis documentation is split into three sections. +One on the general principles of correlation function analysis. +Another containing details on how the analysis is performed in SasView, and +another showing how to use the tool from a users perspective. -This currently performs correlation function analysis on SAXS/SANS data, -but in the the future is also planned to generate model-independent volume -fraction profiles from the SANS from adsorbed polymer/surfactant layers. -The two types of analyses differ in the mathematical transform that is -applied to the data (Fourier vs Hilbert). However, both functions are -returned in *real space*. +.. toctree:: + :maxdepth: 2 -A correlation function may be interpreted in terms of an imaginary rod moving -through the structure of the material. Γ(x) is the probability that a rod of -length x has equal electron/neutron scattering length density at either end. -Hence a frequently occurring spacing within a structure will manifest itself -as a peak in Γ(x). *SasView* will return both the one-dimensional ( Γ\ :sub:`1`\ (x) ) -and three-dimensional ( Γ\ :sub:`3`\ (x) ) correlation functions, the difference -being that the former is only averaged in the plane of the scattering vector. + Theoretical basis of correlation function analysis -A volume fraction profile :math:`\Phi`\ (z) describes how the density of polymer -segments/surfactant molecules varies with distance, z, normal to an (assumed -locally flat) interface. The form of :math:`\Phi`\ (z) can provide information -about the arrangement of polymer/surfactant molecules at the interface. The width -of the profile provides measures of the layer thickness, and the area under -the profile is related to the amount of material that is adsorbed. + Details of how the Corfunc module in SasView works -Both analyses are performed in 3 stages: + How-to/tutorial on using Corfunc -* Extrapolation of the scattering curve to :math:`Q = 0` and toward - :math:`Q = \infty` -* Smoothed merging of the two extrapolations into the original data -* Fourier / Hilbert Transform of the smoothed data to give the correlation - function or volume fraction profile, respectively -* (Optional) Interpretation of Γ\ :sub:`1`\ (x) assuming the sample conforms - to an ideal lamellar morphology -.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - - -Extrapolation -------------- - -To :math:`Q = 0` -................ - -The data are extrapolated to q = 0 by fitting a Guinier function to the data -points in the low-q range. - -The equation used is: - -.. math:: - I(q) = e^{A + Bq^2} - -Where the parameter :math:`B` is related to the effective radius-of-gyration of -a spherical object having the same small-angle scattering in this region. - -Note that as q tends to zero this function tends to a limiting value and is -therefore less appropriate for use in systems where the form factor does not -do likewise. However, because of the transform, the correlation functions are -most affected by the Guinier back-extrapolation at *large* values of x where -the impact on any extrapolated parameters will be least significant. - -To :math:`Q = \infty` -..................... - -The data are extrapolated towards q = :math:`\infty` by fitting a Porod model to -the data points in the high-q range and then computing the extrapolation to 100 -times the maximum q value in the experimental dataset. This should be more than -sufficient to ensure that on transformation any truncation artefacts introduced -are at such small values of x that they can be safely ignored. - -The equation used is: - -.. math:: - I(q) = K q^{-4}e^{-q^2\sigma^2} + Bg - -Where :math:`Bg` is the background, :math:`K` is the Porod constant, and :math:`\sigma` (which -must be > 0) describes the width of the electron/neutron scattering length density -profile at the interface between the crystalline and amorphous regions as shown below. - -.. figure:: fig1.png - :align: center - - -Smoothing ---------- - -The extrapolated data set consists of the Guinier back-extrapolation from q ~ 0 -up to the lowest q value in the original data, then the original scattering data, -and then the Porod tail-fit beyond this. The joins between the original data and -the Guinier/Porod extrapolations are smoothed using the algorithm below to try -and avoid the formation of truncation ripples in the transformed data: - -Functions :math:`f(x_i)` and :math:`g(x_i)` where :math:`x_i \in \left\{ -{x_1, x_2, ..., x_n} \right\}`, are smoothed over the range :math:`[a, b]` -to produce :math:`y(x_i)`, by the following equations: - -.. math:: - y(x_i) = h_ig(x_i) + (1-h_i)f(x_i) - -where: - -.. math:: - h_i = \frac{1}{1 + \frac{(x_i-b)^2}{(x_i-a)^2}} - - -Transformation --------------- - -Fourier -....... - -If "Fourier" is selected for the transform type, *SasView* will perform a -discrete cosine transform on the extrapolated data in order to calculate the -1D correlation function as: - -.. math:: - \Gamma _{1}(x) = \frac{1}{Q^{*}} \int_{0}^{\infty }I(q) q^{2} cos(qx) dq - -where Q\ :sup:`*` is the Scattering (also called Porod) Invariant. - -The following algorithm is applied: - -.. math:: - \Gamma(x_k) = 2 \sum_{n=0}^{N-1} x_n \cos{\left[ \frac{\pi}{N} - \left(n + \frac{1}{2} \right) k \right] } \text{ for } k = 0, 1, \ldots, - N-1, N - -The 3D correlation function is calculated as: - -.. math:: - \Gamma _{3}(x) = \frac{1}{Q^{*}} \int_{0}^{\infty}I(q) q^{2} - \frac{sin(qx)}{qx} dq - -.. note:: It is always advisable to inspect Γ\ :sub:`1`\ (x) and Γ\ :sub:`3`\ (x) - for artefacts arising from the extrapolation and transformation processes: - - - do they tend to zero as x tends to :math:`\infty`? - - do they smoothly curve onto the ordinate at x = 0? (if not check the value - of :math:`\sigma` is sensible) - - are there ripples at x values corresponding to (2 :math:`pi` over) the two - q values at which the extrapolated and experimental data are merged? - - are there any artefacts at x values corresponding to 2 :math:`pi` / q\ :sub:`max` in - the experimental data? - - and lastly, do the significant features/peaks in the correlation functions - actually correspond to anticpated spacings in the sample?!!! - -Finally, the program calculates the interface distribution function (IDF) g\ :sub:`1`\ (x) as -the discrete cosine transform of: - -.. math:: - -q^{4} I(q) - -The IDF is proportional to the second derivative of Γ\ :sub:`1`\ (x). - -Hilbert -....... - -If "Hilbert" is selected for the transform type, the analysis will perform a -Hilbert transform on the extrapolated data in order to calculate the Volume -Fraction Profile. - -.. note:: The Hilbert transform functionality is not yet implemented in SasView. - - -Interpretation --------------- - -Correlation Function -.................... - -Once the correlation functions have been calculated *SasView* can be asked to -try and interpret Γ\ :sub:`1`\ (x) in terms of an ideal lamellar morphology -as shown below. - -.. figure:: fig2.png - :align: center - -The structural parameters extracted are: - -* Long Period :math:`= L_p` -* Average Hard Block Thickness :math:`= L_c` -* Average Core Thickness :math:`= D_0` -* Average Interface Thickness :math:`\text{} = D_{tr}` -* Polydispersity :math:`= \Gamma_{\text{min}}/\Gamma_{\text{max}}` -* Local Crystallinity :math:`= L_c/L_p` - -Volume Fraction Profile -....................... - -SasView does not provide any automatic interpretation of volume fraction profiles -in the same way that it does for correlation functions. However, a number of -structural parameters are obtainable by other means: - -* Surface Coverage :math:`=\theta` -* Anchor Separation :math:`= D` -* Bound Fraction :math:`=

` -* Second Moment :math:`= \sigma` -* Maximum Extent :math:`= \delta_{\text{h}}` -* Adsorbed Amount :math:`= \Gamma` - -.. figure:: profile1.png - :align: center - -.. figure:: profile2.png - :align: center - -The reader is directed to the references for information on these parameters. - -References ----------- - -Correlation Function -.................... - -Ruland, W. *Coll. Polym. Sci.* (1977), 255, 417-427 - -Strobl, G. R.; Schneider, M. *J. Polym. Sci.* (1980), 18, 1343-1359 - -Koberstein, J.; Stein R. *J. Polym. Sci. Phys. Ed.* (1983), 21, 2181-2200 - -Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 247-251 - -Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 257-261 - -Baltá Calleja, F. J.; Vonk, C. G. *X-ray Scattering of Synthetic Poylmers*, Elsevier. Amsterdam (1989), 260-270 - -Göschel, U.; Urban, G. *Polymer* (1995), 36, 3633-3639 - -Stribeck, N. *X-Ray Scattering of Soft Matter*, Springer. Berlin (2007), 138-161 - -:ref:`FDR` (PDF format) - -Volume Fraction Profile -....................... - -Washington, C.; King, S. M. *J. Phys. Chem.*, (1996), 100, 7603-7609 - -Cosgrove, T.; King, S. M.; Griffiths, P. C. *Colloid-Polymer Interactions: From Fundamentals to Practice*, Wiley. New York (1999), 193-204 - -King, S. M.; Griffiths, P. C.; Cosgrove, T. *Applications of Neutron Scattering to Soft Condensed Matter*, Gordon & Breach. Amsterdam (2000), 77-105 - -King, S.; Griffiths, P.; Hone, J.; Cosgrove, T. *Macromol. Symp.* (2002), 190, 33-42 - -.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ - - -Usage ------ -Upon sending data for correlation function analysis, it will be plotted (minus -the background value), along with a bar indicating the *upper end of the -low-Q range* (used for Guinier back-extrapolation), and 2 bars indicating -the range to be used for Porod forward-extrapolation. These bars may be moved by -entering appropriate values in the Q range input boxes or by clicking on them and -dragging them to the desired location.. - -.. figure:: tutorial1.png - :align: center - -Once the Q ranges have been set, click the "Calculate" button in the *Background* section -of the dialog to determine the background level. -Alternatively, enter your own value into the box. If the box turns -yellow this indicates that background subtraction has created some negative intensities. - -Now click the "Extrapolate" button to extrapolate the data. The graph window will update -to show the extrapolated data, and the values of the parameters used for the Guinier and -Porod extrapolations will appear in the "Extrapolation Parameters" section of the Corfunc -GUI. - -.. figure:: tutorial2.png - :align: center - -Now click the "Transform" button to perform the Fourier transform and plot -the results. The lower graph will display the 1D and 3D-averaged correlation functions. -The Interface Distribution Function (or IDF) is also computed, but is not displayed -for clarity. How to access the IDF, and the correlation functions themselves, is -explained shortly. - - .. figure:: tutorial3.png - :align: center - -*If* the sample morphology can be adequately described as an ideal lamellar morphology -the Corfunc GUI can attempt to derive morphological characterization parameters from the -1D correlation function. To do this, click the "Extract Parameters" button. - - .. figure:: tutorial4.png - :align: center - -Finally, it is possible to save the values of the real-space distance axis, the 1D and 3D -correlation functions, and the IDF to a simple ASCII text file by clicking on the "Save" -button. The file is given the unique file descriptor *.crf*. - - .. figure:: tutorial5.png - :align: center - -The structure of the file is shown below. - - .. figure:: tutorial6.png - :align: center - -.. note:: At the time of writing SasView will not load these *.crf* files, but they can - be easily loaded and displayed in most spreadsheet applications. - -.. note:: - This help document was last changed by Steve King, 21May2020 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/fdr-pdfs.rst b/src/sas/qtgui/Perspectives/Corfunc/media/fdr-pdfs.rst old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/fig1.png b/src/sas/qtgui/Perspectives/Corfunc/media/fig1.png old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/fig2.png b/src/sas/qtgui/Perspectives/Corfunc/media/fig2.png old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/profile1.png b/src/sas/qtgui/Perspectives/Corfunc/media/profile1.png old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/profile2.png b/src/sas/qtgui/Perspectives/Corfunc/media/profile2.png old mode 100755 new mode 100644 diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial1.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial1.png deleted file mode 100755 index 17517d6200..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial1.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial2.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial2.png deleted file mode 100755 index 2d948f1aaf..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial2.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial3.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial3.png deleted file mode 100755 index 33b90b8e90..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial3.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial4.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial4.png deleted file mode 100755 index 0b3c779d4b..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial4.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial5.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial5.png deleted file mode 100644 index 2ada9d90c4..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial5.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial6.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial6.png deleted file mode 100644 index f500d24450..0000000000 Binary files a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial6.png and /dev/null differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_after_go.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_after_go.png new file mode 100644 index 0000000000..60177329c2 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_after_go.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_data_loaded.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_data_loaded.png new file mode 100644 index 0000000000..769be0bbe1 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_data_loaded.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_export_data.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_export_data.png new file mode 100644 index 0000000000..d362b40a28 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_export_data.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extraction.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extraction.png new file mode 100644 index 0000000000..7270870db9 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extraction.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extrapolate.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extrapolate.png new file mode 100644 index 0000000000..87641c27f7 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_extrapolate.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_idf.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_idf.png new file mode 100644 index 0000000000..7c3c3d829f Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_idf.png differ diff --git a/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_real_space.png b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_real_space.png new file mode 100644 index 0000000000..45cc776441 Binary files /dev/null and b/src/sas/qtgui/Perspectives/Corfunc/media/tutorial_real_space.png differ