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

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

doc: remove extra indentation on dispersion distribution descriptions

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