Changes between Initial Version and Version 1 of DevNotes/Projects/sesans/SESANSCodeCampIIIStatusReport

Timestamp:

Mar 15, 2016 1:33:47 PM (9 years ago)

Author:

krzywon

Comment:

—

DevNotes/Projects/sesans/SESANSCodeCampIIIStatusReport

@@ +1 @@
+= Status report on inclusion of SESANS data analysis in SASVIEW during Sasview Code Camp III (February 2015) =
+  Jurrian Bakker (j.h.bakker@tudelft.nl), Wim Bouwman (w.g.bouwman@tudelft.nl)
+
+  April 10, 2015
+
+== 1. The aim of the code camp ==
+
+The aim of this work package is to add the ability to analyse SESANS data using
+!SasView. !SasView is a software package designed to analyze scattering data by
+graphical visualization and model fitting in reciprocal (Fourier) space. We will
+extend this ability by allowing fitting in real space using Hankel transformation
+of existing SANS models and direct programming of real space scattering
+models.
+
+The long-term goal is to enable co-analysis of SANS and SESANS data.
+SESANS can be used to increase the accuracy of low-Q data in a SANS experiment;
+conversely, SANS data can be used to decrease experimental error at
+low length scales in a SESANS experiment. If structural models could be fitted
+in both real space and Fourier space simultaneously, SANS and SESANS data
+would provide structural information at complementary length scales.
+The work was divided into several stages:
+
+1. Definition of data format (Section 2).
+2. Enable dataloader package to read SESANS data and represent it in a suitable structure.
+3. Wrap SANS models into a SESANS data analysis wrapper to calculate the projected correlation functions numerically from model parameters.
+4. Combine the dataloader and SESANS data analysis wrapper with BUMPS in fitting scripts.
+5. Enable fitting of SESANS data through !SasView GUI
+
+The first four tasks have been completed to some extent: a data format is
+proposed and a dataloader was created for this format (Section 2). Further
+scripts will need to be written to convert instrument output data into this data
+format. SESANS wrapper is able to combine with BUMPS to fit SESANS data
+read in by the dataloader with some tweaks (Section 6). It was decided that
+inclusion of SESANS analysis into the Sasview GUI would be too early at this
+stage, since the Sasview GUI will undergo heavy rewriting to clean up the code
+and create a more user-friendly interface.
+
+So in conclusion: we have now the possibility to use the models available in
+sasmodels to analyse SESANS-measurements in the command line in a developers
+environment. It is good for the experts, but not yet for users.
+
+== 2. Data format ==
+
+The current file extension is .ses or .sesans (not case sensitive).
+Our preliminary suggestion for the file format is to have a list of name-value
+pairs as a header at the top of the file, detailing general experimental parameters
+necessary for fitting and analyzing data. This list should contain all information
+necessary for the file to be ’portable’ between users.
+
+Following that is a 6 column list of instrument experimental variables:
+
+* Spin echo length (δ, in Angstroms)
+* Spin echo length error (∆δ, in Angstroms) (experimental resolution)
+* neutron wavelength (λ, in Angstroms) (essential for ToF instruments)
+* neutron wavelength error (∆λ, in Angstroms)
+* Normalized polarization (P/P0, unitless)
+* Normalized polarization error (∆(P/P0), unitless) (measurement error)
+
+The neutron wavelength appears in both scattering power (Σ) and spin echo
+length (δ), making data analysis more complicated for Time-of-Flight SESANS
+than for Monochromatic SESANS.
+
+  Σ = λ^2^t(∆ρ0)^2^φ(1 − φ)ξ  (1)
+
+  δ = cλ^2^BL/(2π tan (θ0))  (2)
+
+After discussion with partners (DUT/ISIS/ESS/ORNL, etc.), we might add
+more items to the header. Extending the header will not be a problem, since
+the dataloader has been written to allow for a 2-column header of arbitrary
+length.
+
+=== 2.1 Example Data File ===
+
+At the moment, the data file is a tab-separated text file. Using tab as a separator
+elegantly avoids problems with whitespaces and special characters when parsing
+the data (keeps the dataloader code short, simple and flexible).
+
+  DataFileTitle Polystyrene of Markus Strobl, Full Sine, ++ only
+
+  Sample Polystyrene 2 um in 53% H2O, 47% D2O
+
+  Settings D1=D2=20x8 mm,Ds = 16x10 mm (WxH), GF1 =scanning, GF2 = 2.5 A. 2 um polystyrene in 53% H2O, 47% D2O; 8.55% contrast
+
+  Operator CPD
+
+  Date ma 7 jul 2014 18:54:43
+
+  ScanType sine one element scan
+
+  Thickness [mm] 2
+
+  Q_zmax [\AA^-1] 0.05
+
+  Q_ymax [\AA^-1] 0.05
+
+  spin echo length [nm] error SEL wavelength [nm] error wavelength polarisation error pol
+
+  49.778 2.4889 0.211 0.01055 0.99782 0.0044367
+
+  63.041 3.152 0.211 0.01055 1.0026 0.0047862
+
+  76.487 3.8244 0.211 0.01055 0.99601 0.0060598
+
+  89.847 4.4924 0.211 0.01055 0.99175 0.0058257
+
+  103.41 5.1705 0.211 0.01055 0.99543 0.0060966
+
+  116.95 5.8475 0.211 0.01055 0.99512 0.0048106
+
+  etc....
+
+== 3. Dataloader ==
+
+The data loader uses the data file and parses it for use in Sasview (plotting
+only for now) and loading into BUMPS (for data fitting). Future changes to
+the Sasview source code should have minimal or no impact on the code of the
+dataloader.
+
+One new file was created in the Sasview source code to load in data:
+
+* [https://github.com/SasView/sasview/blob/master/src/sas/sascalc/dataloader/readers/sesans_reader.py sesans_reader.py]::
+  The code for this file has been added to this document in Appendix 7
+
+Three existing files of the source code were modified:
+
+* [https://github.com/SasView/sasview/blob/master/src/sas/sascalc/dataloader/data_info.py data_info.py]::
+  added the SESANSData1D class to handle SESANS data as opposed to Data1D or Data2D for SANS/SAXS data. Added the plottable sesans1D class to handle SESANS plots.
+
+* [https://github.com/SasView/sasview/blob/master/src/sas/sascalc/dataloader/readers/associations.py associations.py]::
+  added sesans reader to the registry to allow use in Sasview.
+
+* [https://github.com/SasView/sasview/blob/master/src/sas/sascalc/dataloader/readers/defaults.json defaults.json]::
+  added default file extension .ses to allow automatic detection of SESANS data files; this is not yet working as intended.
+
+== 4. Wrapper from SAS model to SESANS in absolute units ==
+
+The conversion from SANS into SESANS in absolute units is a simple Hankel
+transformation when all the small-angle scattered neutrons are detected. First
+we calculate the Hankel transform including the absolute intensities by
+{{{
+#!html
+<math>Ge(δ) = 2π &int;_0_&infinity; J0(Qδ)*dΣ/dΩ(Q)*QdQ</math>, (3)
+}}}
+
+in which J0 is the zeroth order Bessel function, δ the spin-echo length, Q the
+wave vector transfer and dΣ/dΩ(Q) the scattering cross section in absolute units.
+This is a 1-dimensional integral, which can be rather fast. In the numerical
+calculation we integrate from Qmin = 0.1 × 2π/Rmax in which Rmax will be
+model dependent. We determined the factor 0.1 by varying its value until the
+value of the integral was stable. This happened at a value of 0.3. The have a
+safety margin of a factor of three we have choosen the value 0.1. For the solid
+sphere we took 3 times the radius for Rmax. The real integration is performed to
+Qmax which is an instrumental parameter that is read in from the measurement
+file. From 3 we can calculate the polarisation that we measure in a SESANS
+experiment:
+
+  P(δ) = e^t(λπ )^2^(Ge(δ)−Ge(0)), (4)
+
+in which t is the thickness of the sample and λ is the wavelength of the neutrons.
+For collimation by a supermirror analyser the Qmax will be fixed.
+
+Two new files were created for fitting the SESANS data:
+
+[https://github.com/SasView/sasmodels/blob/master/example/sesansfit.py sesansfit.py]::
+  The file containing the fit model and parameter boundaries to be used in the fitting
+
+[https://github.com/SasView/sasmodels/blob/master/sasmodels/sesans.py sesans.py]::
+  The file containing the Hankel transform
+
+== 5. Combination of dataloader with wrapper to fit in command line with bumps ==
+
+Install the sasview and sasmodels source code (description in Section 6 Make
+sure you have a Git Bash prompt open and that your path is in the sasmodels
+folder.
+
+Now it’s time to use BUMPS for SESANS fitting: Place the .ses (or .sesans)
+file that you wish to fit into the ’sasmodels/example/’ folder and enter the
+following into the command-line:
+
+  ./bumps.sh example/sesansfit.py --preview (for a quick preview of the fit) (something should appear on your screen if the installation was successful)
+
+Figure 1: a window showing a plot of SESANS data in the current version of Sasview
+
+  ./bumps.sh example/sesansfit.py --edit (for interactive GUI mode).
+
+  ./bumps.sh example/sesansfit.py --fit=amoeba -edit (a very good fitting algorithm).
+
+Note that you can also call up a help menu using the -help option, we give
+no guarantees that any of the options given by help, other than those listed
+above, will work though: BUMPS is still a work in progress. Best of luck with
+your SESANS fitting!
+
+== Appendix 1: Installation Guide ==
+
+For the moment, Sasview, and with it, the SESANS fitting module can only be
+used on Windows operating systems. Firstly, follow the [AnacondaSetup]. Be sure
+to create a Github account if you have none. After completing the installation
+of sasview, perform the following steps:
+
+Clone the sasmodels package from github by entering the following into the
+command-line:
+
+  git clone !https://github.com/Sasview/sasmodels.git sasmodels
+
+Download Intel Opencl drivers from: [https://software.intel.com/en-us/articles/opencldrivers#win64]
+and install it (this is to make the BUMPS package work).
+
+From [http://www.lfd.uci.edu/~gohlke/pythonlibs/#pyopencl], Download pyopencl-
+2015.1-cp27-none-win32.whl Enter the following into the command-line: 
+
+  pip install pyopencl- 2015.1-cp27-none-win32.whl (make sure to be in the correct directrory, otherwise you need to enter the entire path to it).
+
+For the moment, you will need to perform a small hack of Anaconda. You
+need to modify [Anaconda directory]/Lib/site-packages/bumps/gui/fit_thread.py,
+line 153: Change line to If False to turn off multi-core support (There is no
+multi-core support in the current implementation)
+
+In Git Bash (Unix prompt from Git, comes with the Git installation) ,
+navigate to sasmodels folder.
+
+Create file bumps.sh in the sasmodels main directory (easiest method is to open
+compare.sh and adjust the appropriate lines, then save as bumps.sh)) to easily
+use BUMPS fitting system (this is simply a text file).
+
+Contents are:
+
+{{{
+#!/bin/sh
+
+SASVIEW=$PWD/../sasview-code/src
+PYTHONPATH=$PWD:$PWD/../bumps:$PWD/../periodictable:$SASVIEW
+export PYOPENCL_CTX PYTHONPATH
+
+echo PYTHONPATH=$PYTHONPATH
+set -x
+
+python -m bumps.cli $*
+}}}
+
+
+== Acknowledgements ==
+
+We would like to thank everybody of the SASVIEW team for their patient help
+with introducing us to this great project. This report is the product of a very
+intensive collaboration during the code camp 2015 in Copenhagen.