Merge pull request #1974 from SasView/scattering-calculator-docs

Scattering calculator docs

Author: Wojciech Potrzebowski

src/sas/qtgui/Calculators/media/gen_coords.png

@@ -0,0 +1,82 @@
+.. gsc_ex_default_data.rst
+
+.. _gsc_ex_default_data:
+
+Example 1: Default Calculator Data
+==================================
+
+In this example we will use the default data in the generic scattering calculator to find 
+the scattering intensity of a 60x60x60\ |Ang| cube with constant
+scattering length density of 6.97x10\ :sup:`-6`\ |Ang|:sup:`-2`. We begin by 
+selecting Tool>Generic Scattering Calculator from the top menu.
+
+Upon loading the calculator we are shown the following interface:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_1.png
+
+The default data within the generic scattering calculator (highlighted in red) describes a rectangular grid of 10x10x10 pixels, with 
+each pixel being 6x6x6\ |Ang|. Each pixel has a constant nuclear SLD of 6.97x10\ :sup:`-6`\ |Ang|:sup:`-2`
+and no magnetic SLD.
+
+To calculate the scattering pattern we press the `compute` button, and the following image appears in the main window:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_2.png
+
+This shows the scattering intensity on a 30x30 grid of pixels, up to a maximum value of 0.3\ |Ang|:sup:`-1` in each axis, as
+specified in the Q Range settings in the calculator. In order to see a higher resolution image we can adjust the number of Qx (Qy) bins. For a smooth image here we will set
+this value to 100.
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_3.png
+
+The orange highlight of the textbox informs us that this value is potentially too high. More precisely it is informing us that with the given spacing of
+pixels in the realspace data the fourier transform cannot resolve peaks at such fine resolution in Q space. While using more Q bins can produce
+nicer images - which more clearly show the overall pattern - we should be aware of this limitation. Pressing compute again gives us a new output:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_4.png
+
+Given that for purely nuclear data the scattering pattern corresponds to a fourier transform, it should not be a suprise that for a cube oriented with
+the axes, a sinc pattern appears.
+
+It is often far more useful to know the orientational average at each magnitude $\|\mathbf{Q}\|$ than the result for a single oriented cube. Because the default data
+is positioned on a regular grid, and contains only nuclear scattering length densities, we can use the Debye full average option, which uses the Debye formula to
+calculate the orientational average:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_5.png
+
+Pressing compute again gives:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_6.png
+
+For such a simple structure as a cube, the analytical result is well known, and we can compare the calculator's simulation to the fitting tool. In the main window we select the most
+recent dataset (the Debye full average) and select `Send data to` with `Fitting` mode selected in the adjacent drop down. We can now select the `Parallelepiped` model category and then
+the `Parallelepiped` model in the fitting window. We also adjust all the paramters in the window to match those of the default data in the scattering calculator. 
+
+ - scale: 1
+ - background: 0
+ - sld: 6.97 ($\times 10^{-6}$ in units)
+ - sld_solvent: 0
+ - length_a: 60
+ - length_b: 60
+ - length_c: 60
+
+If we now press `Compute/Plot` at the bottom of the fitting window we see a plot of our data and the analytical result.
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_7.png
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_7b.png
+
+As we would expect, at higher Q values the calculator result deviates from the analytical result, due to the discretisation of the data in the calculator. With a 10x10x10 cube of pixels
+we obtain $\chi^2 = 1.96$.
+
+If we adjust the calculator settings to use a 20x20x20 grid of pixels to describe the same sample, we expect to see a much better match. We adjust the settings as follows:
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_8.png
+
+Recomputing the data and comparing it to the fitting calculator as before gives a substantially better fit of $\chi^2 = 0.12$. It is visibly obvious from the graph as well
+that this fit is much closer to the analytical result.
+
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_9.png
+.. figure:: gsc_ex_default_data_assets/gsc_ex_default_data_9b.png
+
+*Document History*
+
+| 2021-09-14 Robert Bourne

src/sas/qtgui/Calculators/media/gen_debye_eq.png

@@ -0,0 +1,179 @@
+.. gsc_ex_magnetic_cylinder.rst
+
+.. _gsc_ex_magnetic_cylinder:
+
+Example 2: A Magnetic Cylinder
+==================================
+
+In this example we will generate an SLD file describing a single solid
+cylinder, with both nuclear and magnetic scattering length densities (SLDs).
+We will then use the calculator to create scattering intensity patterns for
+both a non-magnetised and magnetised cylinder.
+
+Our cylinder will have a radius of 20\ |Ang| and a
+length of 40\ |Ang|, with its axis
+at a 60° polar angle to the $z$-axis. The cylinder will have equal nuclear and
+magnetic SLDs, with the magnetic SLD along the cylinder's axis. 
+We will write first an SLD file for an cylinder aligned along the $z$ axis -
+and perform the rotation within the calculator.
+
+The file should describe a cylinder as below, with a constant nuclear
+scattering length density of
+1x10\ :sup:`-6`\ |Ang|:sup:`-2` and
+a constant magnetic scattering length density of 
+(0, 0, 1x10\ :sup:`-6`)\ |Ang|:sup:`-2`:
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/cylinder_graphic.png
+
+The following code generates a SLD file describing such a sample, using the SLD
+file format as given in the documentation for the generic scattering
+calculator::
+
+        import numpy as np
+
+        size = np.linspace(-35.0, 35.0, 50) # describe each axis of the grid
+        # create a full 3D grid
+        xs, ys, zs = np.meshgrid(size, size, size)
+        xs = xs.flatten()
+        ys = ys.flatten()
+        zs = zs.flatten()
+        # create arrays to hold the SLDs
+        N = np.zeros_like(xs)
+        Mx = np.zeros_like(xs)
+        My = np.zeros_like(xs)
+        Mz = np.zeros_like(xs)
+        # fill in the values of the non-zero SLDs within the cylinder
+        inside_cylinder = np.bitwise_and(np.float_power(xs, 2) + np.float_power(ys, 2) <= 20**2, np.abs(zs) <= 20)
+        N[inside_cylinder] = 1e-6
+        Mz[inside_cylinder] = 1e-6
+        # save the output to an sld file
+        output = np.column_stack((xs, ys, zs, N, Mx, My, Mz))
+        np.savetxt("mag_cylinder.sld", output, header="x y z N mx my mz")
+
+We do not need to worry that the large number of pixels with zero valued SLD
+around the cylinder slows down the computation, as such pixels are
+stripped before the calculation begins.
+
+Structural Scattering
+^^^^^^^^^^^^^^^^^^^^^
+
+First we consider the scattering pattern of a non-magnetic cylinder. We open
+the scattering calculator and use the nuclear datafile `load` button to load
+the nuclear SLD for this sample into the calculator.
+
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/gsc_tool_1.png
+
+By pressing the `draw` button we can see a view of the pixels describing the
+sample. Pixels with 0 SLD are coloured in yellow, all others are given a colour
+related
+to their SLD, which in this case is a constant.
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/cylinder_draw_output.png
+
+In order to set the cylinder at an angle of 60° to the $z$ axis we use the
+sample coordinates highlighted in red below. We also want a 100x100 pixel
+binning in $Q$.
+Unlike the default data in example 1, this value is not given a warning orange
+background, due to the higher discretisation of the real space data for the
+cylinder.
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/gsc_tool_2.png
+
+Pressing compute gives us the following output in the main window:
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/nuclear_output.png
+
+This relatively simple system can be compared with the analytical model in the
+fitting calculator to test the correctness of our results.
+We send the output of the scattering calculator to the fitting panel as in
+example 1 :ref:`gsc_ex_default_data` and choose the `cylinder` category and `cylinder` model.
+We then set the following settings to match the fitting calculator to the
+scattering calculator settings:
+
+ - *scale*: 1.0
+ - *background*: 0.0
+ - *sld*: 1 ($\times 10^{-6}$ in units)
+ - *sld_solvent*: 0
+ - *radius*: 20
+ - *length*: 40
+ - *theta*: 60
+ - *phi*: 0
+
+Computing this gives us the model and residual plots:
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/main_window_3.png
+
+The value of $\chi^2 = 5.65\times 10^{-6}$ demonstrates that the calculator has
+produced very accurate results.
+
+For a better comparison of the results, we can adjust the colour scales by
+right-clicking on each of the scattering intensity plots and selecting `2D
+Color Map` to set the maximum and minimum ranges of the plots: 
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/color_map_4.png
+
+We also need to adjust the scale for the residuals plot. Since the residuals
+for this fit include negative values we need to change from a log to a linear
+scale
+by right clicking the plot and selecting `Toggle Linear/Log Scale`. We can then
+adjust the range of the color map as before - in this case to the range from
+-0.01 to 0.01.
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/main_window_5.png
+
+Magnetic Scattering
+^^^^^^^^^^^^^^^^^^^^^
+
+We will now add the magnetic SLD to the cylinder. We load our magnetic cylinder
+SLD file into the magnetic datafile slot, and alter the magnetic beamline
+settings
+to put the polarisation direction along the $U$ axis (the horizontal direction)
+and to record the ++ cross-section ("+" state as defined in Moon, Riste, and
+Koehler, 1969 [#MRK1969]_ corresponds to 0 in the textbox for up_frac).
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/gsc_tool_5b.png
+
+Running the calculation gives us the following output in the main window:
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/magnetic_output.png
+
+Additional to the structural scattering pattern now an angular anisotropy due
+to the magnetisation occurs.
+
+Again we can compare our result to the analytic result of the fitting
+calculator. We set the same settings as before for the cylinder model but also
+check the
+`Magnetism` checkbox in the fitting window. We then navigate to the `Magnetism`
+tab and set the following settings to match with the scattering calculator:
+
+ - *up_frac_i*: 0
+ - *up_frac_f*: 0
+ - *up_angle*: 90 (corresponds to up_theta in the calculator)
+ - *up_phi*: 0
+ - *sld_M0*: 1 (corresponds to sample magnetic SLD)
+ - *sld_mtheta*: 60 (gives the direction of the magnetic SLD in polar angles)
+ - *sld_mphi*: 0
+ - *sld_solvent_M0*: 0 (the magnetic SLD of the solvent)
+ - *sld_solvent_mtheta*: 0
+ - *sld_solvent_mphi*: 0
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/magnetism_fitting.png
+  
+Carrying out the fitting gives the following results (after adjusting scales to
+match):
+
+.. figure:: gsc_ex_magnetic_cylinder_assets/main_window_6.png
+
+Again the value of $\chi^2 = 1.92\times 10^{-7}$ shows an excellent fit.
+
+References
+----------
+
+    .. [#MRK1969] Polarization Analysis of Thermal-Neutron Scattering
+         (1969) R. M. Moon, T. Riste, and W. C. Koehler Phys. Rev. 181, 920 
+         `DOI <https://doi.org/10.1103/PhysRev.181.920>`__
+
+*Document History*
+
+| 2021-09-14 Robert Bourne