source: sasmodels/doc/guide/resolution.rst @ db1d9d5

ticket-1257-vesicle-productticket_1156ticket_822_more_unit_tests
Last change on this file since db1d9d5 was db1d9d5, checked in by Paul Kienzle <pkienzle@…>, 5 years ago

merge with master

  • Property mode set to 100644
File size: 9.9 KB
RevLine 
[db1d9d5]1.. resolution.rst
[990d8df]2
[db1d9d5]3.. This is a port of the original SasView html help file sm_help to ReSTructured
4.. text by S King, ISIS, during SasView CodeCamp-III in Feb 2015.
[990d8df]5
6
7.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
8
9Resolution Functions
10====================
11
12Sometimes the instrumental geometry used to acquire the experimental data has
13an impact on the clarity of features in the reduced scattering curve. For
14example, peaks or fringes might be slightly broadened. This is known as
15*Q resolution smearing*. To compensate for this effect one can either try and
16remove the resolution contribution - a process called *desmearing* - or add the
17resolution contribution into a model calculation/simulation (which by definition
18will be exact) to make it more representative of what has been measured
[db1d9d5]19experimentally - a process called *smearing*. The Sasmodels component of SasView
20does the latter.
[990d8df]21
22Both smearing and desmearing rely on functions to describe the resolution
[1f058ea]23effect. Sasmodels provides three smearing algorithms:
[990d8df]24
25*  *Slit Smearing*
26*  *Pinhole Smearing*
27*  *2D Smearing*
28
29The $Q$ resolution values should be determined by the data reduction software
30for the instrument and stored with the data file.  If not, they will need to
31be set manually before fitting.
32
[db1d9d5]33.. note::
34    Problems may be encountered if the data set loaded by SasView is a
35    concatenation of SANS data from several detector distances where, of
36    course, the worst Q resolution is next to the beam stop at each detector
37    distance. (This will also be noticeable in the residuals plot where
38    there will be poor overlap). SasView sensibly orders all the input
39    data points by increasing Q for nicer-looking plots, however, the dQ
40    data can then vary considerably from point to point. If 'Use dQ data'
41    smearing is selected then spikes may appear in the model fits, whereas
42    if 'None' or 'Custom Pinhole Smear' are selected the fits look normal.
43
44    In such instances, possible solutions are to simply remove the data
45    with poor Q resolution from the shorter detector distances, or to fit
46    the data from different detector distances simultaneously.
47
[990d8df]48
49.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
50
51Slit Smearing
52-------------
53
54**This type of smearing is normally only encountered with data from X-ray Kratky**
55**cameras or X-ray/neutron Bonse-Hart USAXS/USANS instruments.**
56
57The slit-smeared scattering intensity is defined by
58
59.. math::
60    I_s = \frac{1}{\text{Norm}}
61          \int_{-\infty}^{\infty} dv\, W_v(v)
62          \int_{-\infty}^{\infty} du\, W_u(u)\,
63          I\left(\sqrt{(q+v)^2 + |u|^2}\right)
64
65where *Norm* is given by
66
67.. math:: \int_{-\infty}^{\infty} dv\, W_v(v) \int_{-\infty}^{\infty} du\, W_u(u)
68
69**[Equation 1]**
70
71The functions $W_v(v)$ and $W_u(u)$ refer to the slit width weighting
72function and the slit height weighting determined at the given $q$ point,
73respectively. It is assumed that the weighting function is described by a
74rectangular function, such that
75
76.. math:: W_v(v) = \delta(|v| \leq \Delta q_v)
77
78**[Equation 2]**
79
80and
81
82.. math:: W_u(u) = \delta(|u| \leq \Delta q_u)
83
84**[Equation 3]**
85
86so that $\Delta q_\alpha = \int_0^\infty d\alpha\, W_\alpha(\alpha)$
87for $\alpha$ as $v$ and $u$.
88
89Here $\Delta q_u$ and $\Delta q_v$ stand for the the slit height (FWHM/2)
90and the slit width (FWHM/2) in $q$ space.
91
92This simplifies the integral in Equation 1 to
93
94.. math::
95
96    I_s(q) = \frac{2}{\text{Norm}}
97             \int_{-\Delta q_v}^{\Delta q_v} dv
98             \int_{0}^{\Delta q_u}
99             du\, I\left(\sqrt{(q+v)^2 + u^2}\right)
100
101**[Equation 4]**
102
103which may be solved numerically, depending on the nature of
104$\Delta q_u$ and $\Delta q_v$.
105
106Solution 1
107^^^^^^^^^^
108
109**For** $\Delta q_v = 0$ **and** $\Delta q_u = \text{constant}$
110
111.. math::
112
113    I_s(q) \approx \int_0^{\Delta q_u} du\, I\left(\sqrt{q^2+u^2}\right)
114           = \int_0^{\Delta q_u} d\left(\sqrt{q'^2-q^2}\right)\, I(q')
115
116For discrete $q$ values, at the $q$ values of the data points and at the $q$
[1f058ea]117values extended up to $q_N = q_i + \Delta q_u$ the smeared
[990d8df]118intensity can be approximately calculated as
119
120.. math::
121
122    I_s(q_i)
123    \approx \sum_{j=i}^{N-1} \left[\sqrt{q_{j+1}^2 - q_i^2} - \sqrt{q_j^2 - q_i^2}\right]\, I(q_j)
124            \sum_{j=1}^{N-1} W_{ij}\, I(q_j)
125
126**[Equation 5]**
127
128where $W_{ij} = 0$ for $I_s$ when $j < i$ or $j > N-1$.
129
130Solution 2
131^^^^^^^^^^
132
133**For** $\Delta q_v = \text{constant}$ **and** $\Delta q_u = 0$
134
135Similar to Case 1
136
137.. math::
138
139    I_s(q_i)
140    \approx \sum_{j=p}^{N-1} [q_{j+1} - q_i]\, I(q_j)
141    \approx \sum_{j=p}^{N-1} W_{ij}\, I(q_j)
142
143for $q_p = q_i - \Delta q_v$ and $q_N = q_i + \Delta q_v$
144
145**[Equation 6]**
146
147where $W_{ij} = 0$ for $I_s$ when $j < p$ or $j > N-1$.
148
149Solution 3
150^^^^^^^^^^
151
152**For** $\Delta q_v = \text{constant}$ **and** $\Delta q_u = \text{constant}$
153
154In this case, the best way is to perform the integration of Equation 1
155numerically for both slit height and slit width. However, the numerical
156integration is imperfect unless a large number of iterations, say, at
157least 10000 by 10000 for each element of the matrix $W$, is performed.
158This is usually too slow for routine use.
159
160An alternative approach is used in sasmodels which assumes
161slit width << slit height. This method combines Solution 1 with the
162numerical integration for the slit width. Then
163
164.. math::
165
166    I_s(q_i)
167    &\approx \sum_{j=p}^{N-1} \sum_{k=-L}^L
168            \left[\sqrt{q_{j+1}^2 - (q_i + (k\Delta q_v/L))^2}
169                  - \sqrt{q_j^2 - (q_i + (k\Delta q_v/L))^2}\right]
170            (\Delta q_v/L)\, I(q_j) \\
171    &\approx \sum_{j=p}^{N-1} W_{ij}\,I(q_j)
172
173**[Equation 7]**
174
175for $q_p = q_i - \Delta q_v$ and $q_N = q_i + \Delta q_v$
176
177where $W_{ij} = 0$ for $I_s$ when $j < p$ or $j > N-1$.
178
179.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
180
181Pinhole Smearing
182----------------
183
184**This is the type of smearing normally encountered with data from synchrotron**
185**SAXS cameras and SANS instruments.**
186
[f8a2baa]187The pinhole smearing computation is performed in a similar fashion to the
188slit-smeared case above except that the weight function used is a Gaussian. Thus
[990d8df]189Equation 6 becomes
190
191.. math::
192
193    I_s(q_i)
194    &\approx \sum_{j=0}^{N-1}[\operatorname{erf}(q_{j+1})
195                - \operatorname{erf}(q_j)]\, I(q_j) \\
196    &\approx \sum_{j=0}^{N-1} W_{ij}\, I(q_j)
197
198**[Equation 8]**
199
200.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
201
2022D Smearing
203-----------
204
205The 2D smearing computation is performed in a similar fashion to the 1D pinhole
206smearing above except that the weight function used is a 2D elliptical Gaussian.
207Thus
208
209.. math::
210
211  I_s(x_0,\, y_0)
212  &= A\iint dx'dy'\,
213     \exp \left[ -\left(\frac{(x'-x_0')^2}{2\sigma_{x_0'}^2}
214                      + \frac{(y'-y_0')^2}{2\sigma_{y_0'}}\right)\right] I(x',\, y') \\
215  &= A\sigma_{x_0'}\sigma_{y_0'}\iint dX dY\,
216     \exp\left[-\frac{(X^2+Y^2)}{2}\right] I(\sigma_{x_0'}X x_0',\, \sigma_{y_0'} Y + y_0') \\
217  &= A\sigma_{x_0'}\sigma_{y_0'}\iint dR d\Theta\,
218     R\exp\left(-\frac{R^2}{2}\right) I(\sigma_{x_0'}R\cos\Theta + x_0',\, \sigma_{y_0'}R\sin\Theta+y_0')
219
220**[Equation 9]**
221
222In Equation 9, $x_0 = q \cos(\theta)$, $y_0 = q \sin(\theta)$, and
223the primed axes are all in the coordinate rotated by an angle $\theta$ about
224the $z$\ -axis (see the figure below) so that
225$x'_0 = x_0 \cos(\theta) + y_0 \sin(\theta)$ and
226$y'_0 = -x_0 \sin(\theta) + y_0 \cos(\theta)$.
[0db85af]227Note that the rotation angle is zero for a $x$-$y$ symmetric
[990d8df]228elliptical Gaussian distribution. The $A$ is a normalization factor.
229
[30b60d2]230.. figure:: resolution_2d_rotation.png
[990d8df]231
232    Coordinate axis rotation for 2D resolution calculation.
233
234Now we consider a numerical integration where each of the bins in $\theta$
235and $R$ are *evenly* (this is to simplify the equation below) distributed
236by $\Delta \theta$ and $\Delta R$ respectively, and it is further assumed
237that $I(x',y')$ is constant within the bins. Then
238
239.. math::
240
241   I_s(x_0,\, y_0)
242    &\approx A \sigma_{x'_0}\sigma_{y'_0}\sum_i^n
243        \Delta\Theta\left[\exp\left(\frac{(R_i-\Delta R/2)^2}{2}\right)
244                    - \exp\left(\frac{(R_i + \Delta R/2)^2}{2}\right)\right]
245                    I(\sigma_{x'_0} R_i\cos\Theta_i+x'_0,\, \sigma_{y'_0}R_i\sin\Theta_i + y'_0) \\
246    &\approx \sum_i^n W_i\, I(\sigma_{x'_0} R_i \cos\Theta_i + x'_0,\, \sigma_{y'_0}R_i\sin\Theta_i + y'_0)
247
248**[Equation 10]**
249
250Since the weighting factor on each of the bins is known, it is convenient to
[0db85af]251transform $x'$-$y'$ back to $x$-$y$ coordinates (by rotating it
[990d8df]252by $-\theta$ around the $z$\ -axis).
253
254Then, for a polar symmetric smear
255
256.. math::
257
258    I_s(x_0,\, y_0) \approx \sum_i^n W_i\,
259        I(x'\cos\theta - y'\sin\theta,\, x'sin\theta + y'\cos\theta)
260
261**[Equation 11]**
262
263where
264
265.. math::
266
267    x' &= \sigma_{x'_0} R_i \cos\Theta_i + x'_0 \\
268    y' &= \sigma_{y'_0} R_i \sin\Theta_i + y'_0 \\
269    x'_0 &= q = \sqrt{x_0^2 + y_0^2} \\
270    y'_0 &= 0
271
[0db85af]272while for a $x$-$y$ symmetric smear
[990d8df]273
274.. math::
275
276    I_s(x_0,\, y_0) \approx \sum_i^n W_i\, I(x',\, y')
277
278**[Equation 12]**
279
280where
281
282.. math::
283
284    x' &= \sigma_{x'_0} R_i \cos\Theta_i + x'_0 \\
285    y' &= \sigma_{y'_0} R_i \sin\Theta_i + y'_0 \\
286    x'_0 &= x_0 = q_x \\
287    y'_0 &= y_0 = q_y
288
289
290The current version of sasmodels uses Equation 11 for 2D smearing, assuming
291that all the Gaussian weighting functions are aligned in the polar coordinate.
292
293.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
294
295Weighting & Normalization
296-------------------------
297
298In all the cases above, the weighting matrix $W$ is calculated on the first
299call to a smearing function, and includes ~60 $q$ values (finely and evenly
300binned) below (>0) and above the $q$ range of data in order to smear all
301data points for a given model and slit/pinhole size. The *Norm* factor is
302found numerically with the weighting matrix and applied on the computation
303of $I_s$.
304
305.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
306
307*Document History*
308
309| 2015-05-01 Steve King
310| 2017-05-08 Paul Kienzle
Note: See TracBrowser for help on using the repository browser.