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

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since ba51e00 was 0db85af, checked in by Paul Kienzle <pkienzle@…>, 7 years ago

Now allowed '-' before and after '$', such as 1-$\sigma$ or $x$-$y$-$z$

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