source: sasmodels/doc/guide/pd/polydispersity.rst @ 2e66ef5

core_shell_microgelscostrafo411magnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 2e66ef5 was 990d8df, checked in by Paul Kienzle <pkienzle@…>, 8 years ago

move polydispersity and resolution docs into sasmodels; write installation instructions

  • Property mode set to 100644
File size: 6.9 KB
RevLine 
[990d8df]1.. pd_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.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
7
8Polydispersity Distributions
9----------------------------
10
11With some models in sasmodels we can calculate the average form factor for a
12population of particles that exhibit size and/or orientational
13polydispersity. The resultant form factor is normalized by the average
14particle volume such that
15
16.. math::
17
18  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background}
19
20where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an
21average over the size distribution.
22
23Each distribution is characterized by its center $\bar x$, its width $\sigma$,
24the number of sigmas $N_\sigma$ to include from the tails, and the number of
25points used to compute the average. The center of the distribution is set by the
26value of the model parameter.  Volume parameters have polydispersity *PD*
27(not to be confused with a molecular weight distributions in polymer science)
28leading to a size distribution of width $\text{PD} = \sigma / \bar x$, but
29orientation parameters use an angular distributions of width $\sigma$.
30$N_\sigma$ determines how far into the tails to evaluate the distribution, with
31larger values of $N_\sigma$ required for heavier tailed distributions.
32The scattering in general falls rapidly with $qr$ so the usual assumption
33that $G(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)G(r - 3\sigma_r)$
34will not contribute much to the average may not hold when particles are large.
35This, too, will require increasing $N_\sigma$.
36
37Users should note that the averaging computation is very intensive. Applying
38polydispersion to multiple parameters at the same time or increasing the
39number of points in the distribution will require patience! However, the
40calculations are generally more robust with more data points or more angles.
41
42The following five distribution functions are provided:
43
44*  *Rectangular Distribution*
45*  *Gaussian Distribution*
46*  *Lognormal Distribution*
47*  *Schulz Distribution*
48*  *Array Distribution*
49
50These are all implemented as *number-average* distributions.
51
52.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
53
54Rectangular Distribution
55^^^^^^^^^^^^^^^^^^^^^^^^
56
57The Rectangular Distribution is defined as
58
59.. math::
60
61    f(x) = \frac{1}{\text{Norm}}
62    \begin{cases}
63      1 & \text{for } |x - \bar x| \leq w \\
64      0 & \text{for } |x - \bar x| > w
65    \end{cases}
66
67where $\bar x$ is the mean of the distribution, $w$ is the half-width, and
68*Norm* is a normalization factor which is determined during the numerical
69calculation.
70
71Note that the standard deviation and the half width $w$ are different!
72
73The standard deviation is
74
75.. math:: \sigma = w / \sqrt{3}
76
77whilst the polydispersity is
78
79.. math:: \text{PD} = \sigma / \bar x
80
81.. figure:: pd_rectangular.jpg
82
83    Rectangular distribution.
84
85.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
86
87Gaussian Distribution
88^^^^^^^^^^^^^^^^^^^^^
89
90The Gaussian Distribution is defined as
91
92.. math::
93
94    f(x) = \frac{1}{\text{Norm}}
95           \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right)
96
97where $\bar x$ is the mean of the distribution and *Norm* is a normalization factor
98which is determined during the numerical calculation.
99
100The polydispersity is
101
102.. math:: \text{PD} = \sigma / \bar x
103
104.. figure:: pd_gaussian.jpg
105
106    Normal distribution.
107
108.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
109
110Lognormal Distribution
111^^^^^^^^^^^^^^^^^^^^^^
112
113The Lognormal Distribution is defined as
114
115.. math::
116
117    f(x) = \frac{1}{\text{Norm}}
118           \frac{1}{xp}\exp\left(-\frac{(\ln(x) - \mu)^2}{2p^2}\right)
119
120where $\mu=\ln(x_\text{med})$ when $x_\text{med}$ is the median value of the
121distribution, and *Norm* is a normalization factor which will be determined
122during the numerical calculation.
123
124The median value for the distribution will be the value given for the respective
125size parameter, for example, *radius=60*.
126
127The polydispersity is given by $\sigma$
128
129.. math:: \text{PD} = p
130
131For the angular distribution
132
133.. math:: p = \sigma / x_\text{med}
134
135The mean value is given by $\bar x = \exp(\mu+ p^2/2)$. The peak value
136is given by $\max x = \exp(\mu - p^2)$.
137
138.. figure:: pd_lognormal.jpg
139
140    Lognormal distribution.
141
142This distribution function spreads more, and the peak shifts to the left, as
143$p$ increases, so it requires higher values of $N_\sigma$ and more points
144in the distribution.
145
146.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
147
148Schulz Distribution
149^^^^^^^^^^^^^^^^^^^
150
151The Schulz distribution is defined as
152
153.. math::
154
155    f(x) = \frac{1}{\text{Norm}}
156           (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)}
157
158where $\bar x$ is the mean of the distribution and *Norm* is a normalization
159factor which is determined during the numerical calculation, and $z$ is a
160measure of the width of the distribution such that
161
162.. math:: z = (1-p^2) / p^2
163
164The polydispersity is
165
166.. math:: p = \sigma / \bar x
167
168Note that larger values of PD might need larger number of points and $N_\sigma$.
169For example, at PD=0.7 and radius=60 |Ang|, Npts>=160 and Nsigmas>=15 at least.
170
171.. figure:: pd_schulz.jpg
172
173    Schulz distribution.
174
175For further information on the Schulz distribution see:
176M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461.
177
178.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
179
180Array Distribution
181^^^^^^^^^^^^^^^^^^
182
183This user-definable distribution should be given as as a simple ASCII text
184file where the array is defined by two columns of numbers: $x$ and $f(x)$.
185The $f(x)$ will be normalized to 1 during the computation.
186
187Example of what an array distribution file should look like:
188
189====  =====
190 30    0.1
191 32    0.3
192 35    0.4
193 36    0.5
194 37    0.6
195 39    0.7
196 41    0.9
197====  =====
198
199Only these array values are used computation, therefore the parameter value
200given for the model will have no affect, and will be ignored when computing
201the average.  This means that any parameter with an array distribution will
202not be fittable.
203
204.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
205
206Note about DLS polydispersity
207^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
208
209Many commercial Dynamic Light Scattering (DLS) instruments produce a size
210polydispersity parameter, sometimes even given the symbol $p$! This
211parameter is defined as the relative standard deviation coefficient of
212variation of the size distribution and is NOT the same as the polydispersity
213parameters in the Lognormal and Schulz distributions above (though they all
214related) except when the DLS polydispersity parameter is <0.13.
215
216For more information see:
217S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143
218
219.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
220
221*Document History*
222
223| 2015-05-01 Steve King
224| 2017-05-08 Paul Kienzle
Note: See TracBrowser for help on using the repository browser.