# source:sasmodels/doc/guide/pd/polydispersity.rst@5026e05

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 5026e05 was 5026e05, checked in by smk78, 5 years ago

Overhaul of polydispersity help for content, readability and accuracy.

• Property mode set to 100644
File size: 10.7 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
[eda8b30]8.. _polydispersityhelp:
9
[990d8df]10Polydispersity Distributions
11----------------------------
12
[eda8b30]13With some models in sasmodels we can calculate the average intensity for a
[990d8df]14population of particles that exhibit size and/or orientational
[eda8b30]15polydispersity. The resultant intensity is normalized by the average
[990d8df]16particle volume such that
17
18.. math::
19
20  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background}
21
22where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an
23average over the size distribution.
24
[5026e05]25Each distribution is characterized by a center value $\bar x$ or $x_\text{med}$,
26a width parameter $\sigma$ (note this is *not necessarily* the standard deviation, so read
27the description carefully), the number of sigmas $N_\sigma$ to include from the
28tails of the distribution, and the number of points used to compute the average.
29The center of the distribution is set by the value of the model parameter.
30
31Volume parameters have polydispersity *PD* (not to be confused with a molecular
32weight distributions in polymer science), but orientation parameters use angular
33distributions of width $\sigma$.
34
[990d8df]35$N_\sigma$ determines how far into the tails to evaluate the distribution, with
36larger values of $N_\sigma$ required for heavier tailed distributions.
37The scattering in general falls rapidly with $qr$ so the usual assumption
38that $G(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)G(r - 3\sigma_r)$
39will not contribute much to the average may not hold when particles are large.
40This, too, will require increasing $N_\sigma$.
41
42Users should note that the averaging computation is very intensive. Applying
43polydispersion to multiple parameters at the same time or increasing the
44number of points in the distribution will require patience! However, the
45calculations are generally more robust with more data points or more angles.
46
[22279a4]47The following distribution functions are provided:
[990d8df]48
[75e4319]49*  *Uniform Distribution*
[5026e05]50*  *Rectangular Distribution*
[990d8df]51*  *Gaussian Distribution*
[5026e05]52*  *Boltzmann Distribution*
[990d8df]53*  *Lognormal Distribution*
54*  *Schulz Distribution*
55*  *Array Distribution*
56
57These are all implemented as *number-average* distributions.
58
[990d8df]60
[5026e05]61Suggested Applications
62^^^^^^^^^^^^^^^^^^^^^^
[990d8df]63
[5026e05]64If applying polydispersion to parameters describing particle sizes, use
65the Lognormal or Schulz distributions.
[990d8df]66
[5026e05]67If applying polydispersion to parameters describing interfacial thicknesses
68or angular orientations, use the Gaussian or Boltzmann distributions.
[990d8df]69
[5026e05]70The array distribution allows a user-defined distribution to be applied.
[990d8df]71
[5026e05]72.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[990d8df]73
[5026e05]74Uniform Distribution
75^^^^^^^^^^^^^^^^^^^^
[990d8df]76
[5026e05]77The Uniform Distribution is defined as
[990d8df]78
[5026e05]79    .. math::
[990d8df]80
[5026e05]81        f(x) = \frac{1}{\text{Norm}}
82        \begin{cases}
83          1 & \text{for } |x - \bar x| \leq \sigma \\
84          0 & \text{for } |x - \bar x| > \sigma
85        \end{cases}
[990d8df]86
[5026e05]87    where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution,
88    $\sigma$ is the half-width, and *Norm* is a normalization factor which is
89    determined during the numerical calculation.
[990d8df]90
[5026e05]91    The polydispersity in sasmodels is given by
[990d8df]92
[5026e05]93    .. math:: \text{PD} = \sigma / \bar x
[92d330fd]94
[5026e05]95    .. figure:: pd_uniform.jpg
[3d58247]96
[5026e05]97        Uniform distribution.
[990d8df]98
[5026e05]99The value $N_\sigma$ is ignored for this distribution.
100
101.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
102
103Rectangular Distribution
[75e4319]104^^^^^^^^^^^^^^^^^^^^^^^^
105
[5026e05]106The Rectangular Distribution is defined as
[75e4319]107
108    .. math::
109
110        f(x) = \frac{1}{\text{Norm}}
111        \begin{cases}
[5026e05]112          1 & \text{for } |x - \bar x| \leq w \\
113          0 & \text{for } |x - \bar x| > w
[75e4319]114        \end{cases}
115
[5026e05]116    where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution,
117    $w$ is the half-width, and *Norm* is a normalization factor which is determined
118    during the numerical calculation.
[75e4319]119
[5026e05]120    Note that the standard deviation and the half width $w$ are different!
[75e4319]121
[5026e05]122    The standard deviation is
[75e4319]123
[5026e05]124    .. math:: \sigma = w / \sqrt{3}
[75e4319]125
[5026e05]126    whilst the polydispersity in sasmodels is given by
[92d330fd]127
[5026e05]128    .. math:: \text{PD} = \sigma / \bar x
129
130    .. figure:: pd_rectangular.jpg
131
132        Rectangular distribution.
133
134    .. note:: The Rectangular Distribution is deprecated in favour of the Uniform Distribution
135              above and is described here for backwards compatibility with earlier versions of SasView only.
[75e4319]136
[990d8df]137.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
138
139Gaussian Distribution
140^^^^^^^^^^^^^^^^^^^^^
141
142The Gaussian Distribution is defined as
143
[5026e05]144    .. math::
145
146        f(x) = \frac{1}{\text{Norm}}
147               \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right)
[990d8df]148
[5026e05]149    where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution
150    and *Norm* is a normalization factor which is determined during the numerical calculation.
[990d8df]151
[5026e05]152    The polydispersity in sasmodels is given by
[990d8df]153
[5026e05]154    .. math:: \text{PD} = \sigma / \bar x
155
156    .. figure:: pd_gaussian.jpg
157
158        Normal distribution.
159
160.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
161
162Boltzmann Distribution
163^^^^^^^^^^^^^^^^^^^^^^
164
165The Boltzmann Distribution is defined as
[990d8df]166
[5026e05]167    .. math::
[990d8df]168
[5026e05]169        f(x) = \frac{1}{\text{Norm}}
170               \exp\left(-\frac{ | x - \bar x | }{\sigma}\right)
[990d8df]171
[5026e05]172    where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution
173    and *Norm* is a normalization factor which is determined during the numerical calculation.
174
175    The width is defined as
176
177    .. math:: \sigma=\frac{k T}{E}
178
179    which is the inverse Boltzmann factor, where $k$ is the Boltzmann constant,
180    $T$ the temperature in Kelvin and $E$ a characteristic energy per particle.
181
182    .. figure:: pd_boltzmann.jpg
183
184        Boltzmann distribution.
[990d8df]185
186.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
187
188Lognormal Distribution
189^^^^^^^^^^^^^^^^^^^^^^
190
[5026e05]191The Lognormal Distribution describes a function of $x$ where $\ln (x)$ has a normal distribution.
192The result is a distribution that is skewed towards larger values of $x$.
193
[990d8df]194The Lognormal Distribution is defined as
195
[5026e05]196    .. math::
[990d8df]197
[5026e05]198        f(x) = \frac{1}{\text{Norm}}
199               \frac{1}{x\sigma}\exp\left(-\frac{1}{2}\bigg(\frac{\ln(x) - \mu}{\sigma}\bigg)^2\right)
200
201    where *Norm* is a normalization factor which will be determined during the numerical calculation,
202    $\mu=\ln(x_\text{med})$ and $x_\text{med}$ is the *median* value of the *lognormal* distribution,
203    but $\sigma$ is a parameter describing the width of the underlying *normal* distribution.
[990d8df]204
[5026e05]205    $x_\text{med}$ will be the value given for the respective size parameter in sasmodels, for
[990d8df]207
[5026e05]208    The polydispersity in sasmodels is given by
[990d8df]209
[5026e05]210    .. math:: \text{PD} = p = \sigma / x_\text{med}
[990d8df]211
[5026e05]212    The mean value of the distribution is given by $\bar x = \exp(\mu+ p^2/2)$ and the peak value
213    by $\max x = \exp(\mu - p^2)$.
[990d8df]214
[5026e05]215    The variance (the square of the standard deviation) of the *lognormal* distribution is given by
[990d8df]216
[5026e05]217    .. math::
[990d8df]218
[5026e05]219        \nu = [\exp({\sigma}^2) - 1] \exp({2\mu + \sigma^2})
[990d8df]220
[5026e05]221    Note that larger values of PD might need a larger number of points and $N_\sigma$.
222
223    .. figure:: pd_lognormal.jpg
[990d8df]224
[5026e05]225        Lognormal distribution.
[990d8df]226
[5026e05]227For further information on the Lognormal distribution see:
228http://en.wikipedia.org/wiki/Log-normal_distribution and
229http://mathworld.wolfram.com/LogNormalDistribution.html
[990d8df]230
231.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
232
233Schulz Distribution
234^^^^^^^^^^^^^^^^^^^
235
[5026e05]236The Schulz (sometimes written Schultz) distribution is similar to the Lognormal distribution,
237in that it is also skewed towards larger values of $x$, but which has computational advantages
238over the Lognormal distribution.
239
[990d8df]240The Schulz distribution is defined as
241
[5026e05]242    .. math::
[990d8df]243
[5026e05]244        f(x) = \frac{1}{\text{Norm}}
245               (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)}
[990d8df]246
[5026e05]247    where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution,
248    *Norm* is a normalization factor which is determined during the numerical calculation,
249    and $z$ is a measure of the width of the distribution such that
[990d8df]250
[5026e05]251    .. math:: z = (1-p^2) / p^2
[990d8df]252
[5026e05]253    where $p$ is the polydispersity in sasmodels given by
[990d8df]254
[5026e05]255    .. math:: PD = p = \sigma / \bar x
[990d8df]256
[5026e05]257    and $\sigma$ is the RMS deviation from $\bar x$.
258
259    Note that larger values of PD might need a larger number of points and $N_\sigma$.
260    For example, for PD=0.7 with radius=60 |Ang|, at least Npts>=160 and Nsigmas>=15 are required.
[990d8df]261
[5026e05]262    .. figure:: pd_schulz.jpg
[990d8df]263
[5026e05]264        Schulz distribution.
[990d8df]265
266For further information on the Schulz distribution see:
[5026e05]267M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461 and
268M Kotlarchyk, RB Stephens, and JS Huang, *J Phys Chem*, (1988), 92, 1533
[990d8df]269
270.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
271
272Array Distribution
273^^^^^^^^^^^^^^^^^^
274
[a5a12ca]275This user-definable distribution should be given as a simple ASCII text
[990d8df]276file where the array is defined by two columns of numbers: $x$ and $f(x)$.
277The $f(x)$ will be normalized to 1 during the computation.
278
279Example of what an array distribution file should look like:
280
281====  =====
282 30    0.1
283 32    0.3
284 35    0.4
285 36    0.5
286 37    0.6
287 39    0.7
288 41    0.9
289====  =====
290
291Only these array values are used computation, therefore the parameter value
292given for the model will have no affect, and will be ignored when computing
293the average.  This means that any parameter with an array distribution will
[a5a12ca]294not be fitable.
295
296.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
297
299^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
300
301Many commercial Dynamic Light Scattering (DLS) instruments produce a size
[1f058ea]302polydispersity parameter, sometimes even given the symbol $p$\ ! This
[990d8df]303parameter is defined as the relative standard deviation coefficient of
304variation of the size distribution and is NOT the same as the polydispersity
305parameters in the Lognormal and Schulz distributions above (though they all
306related) except when the DLS polydispersity parameter is <0.13.
307
[5026e05]308.. math::
309
310    p_{DLS} = \sqrt(\nu / \bar x^2)
311
312where $\nu$ is the variance of the distribution and $\bar x$ is the mean value of x.
313