source: sasmodels/doc/guide/pd/polydispersity.rst @ a5cb9bc

Last change on this file since a5cb9bc was a5cb9bc, checked in by Paul Kienzle <pkienzle@…>, 6 years ago

save before committing

  • Property mode set to 100644
File size: 17.0 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
[97d172c]10Polydispersity & Orientational Distributions
11--------------------------------------------
[990d8df]12
[a5cb9bc]13For some models we can calculate the average intensity for a population of
14particles that possess size and/or orientational (ie, angular) distributions.
15In SasView we call the former *polydispersity* but use the parameter *PD* to
16parameterise both. In other words, the meaning of *PD* in a model depends on
[97d172c]17the actual parameter it is being applied too.
18
[a5cb9bc]19The resultant intensity is then normalized by the average particle volume such
[97d172c]20that
[990d8df]21
22.. math::
23
24  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background}
25
[a5cb9bc]26where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an
[97d172c]27average over the distribution $f(x; \bar x, \sigma)$, giving
[d712a0f]28
29.. math::
30
[a5cb9bc]31  P(q) = \frac{\text{scale}}{V} \int_\mathbb{R}
[d712a0f]32  f(x; \bar x, \sigma) F^2(q, x)\, dx + \text{background}
[990d8df]33
[ed5b109]34Each distribution is characterized by a center value $\bar x$ or
35$x_\text{med}$, a width parameter $\sigma$ (note this is *not necessarily*
36the standard deviation, so read the description carefully), the number of
37sigmas $N_\sigma$ to include from the tails of the distribution, and the
38number of points used to compute the average. The center of the distribution
[aa25fc7]39is set by the value of the model parameter. The meaning of a polydispersity
40parameter *PD* (not to be confused with a molecular weight distributions
41in polymer science) in a model depends on the type of parameter it is being
[29afc50]42applied too.
[ed5b109]43
[aa25fc7]44The distribution width applied to *volume* (ie, shape-describing) parameters
45is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$.
46However, the distribution width applied to *orientation* (ie, angle-describing)
[29afc50]47parameters is just $\sigma = \mathrm{PD}$.
[ed5b109]48
49$N_\sigma$ determines how far into the tails to evaluate the distribution,
50with larger values of $N_\sigma$ required for heavier tailed distributions.
[990d8df]51The scattering in general falls rapidly with $qr$ so the usual assumption
[d712a0f]52that $f(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)f(r - 3\sigma_r)$
[990d8df]53will not contribute much to the average may not hold when particles are large.
54This, too, will require increasing $N_\sigma$.
55
56Users should note that the averaging computation is very intensive. Applying
[a5cb9bc]57polydispersion and/or orientational distributions to multiple parameters at
58the same time, or increasing the number of points in the distribution, will
59require patience! However, the calculations are generally more robust with
[97d172c]60more data points or more angles.
[990d8df]61
[22279a4]62The following distribution functions are provided:
[990d8df]63
[75e4319]64*  *Uniform Distribution*
[5026e05]65*  *Rectangular Distribution*
[990d8df]66*  *Gaussian Distribution*
[5026e05]67*  *Boltzmann Distribution*
[990d8df]68*  *Lognormal Distribution*
69*  *Schulz Distribution*
70*  *Array Distribution*
[0e04dd7]71*  *User-defined Distributions*
[990d8df]72
73These are all implemented as *number-average* distributions.
74
75
[86bb5df]76**Beware: when the Polydispersity & Orientational Distribution panel in SasView is**
77**first opened, the default distribution for all parameters is the Gaussian Distribution.**
78**This may not be suitable. See Suggested Applications below.**
79
[a5cb9bc]80.. note:: In 2009 IUPAC decided to introduce the new term 'dispersity' to replace
81           the term 'polydispersity' (see `Pure Appl. Chem., (2009), 81(2),
82           351-353 <http://media.iupac.org/publications/pac/2009/pdf/8102x0351.pdf>`_
83           in order to make the terminology describing distributions of chemical
84           properties unambiguous. However, these terms are unrelated to the
85           proportional size distributions and orientational distributions used in
[97d172c]86           SasView models.
[d712a0f]87
[5026e05]88Suggested Applications
89^^^^^^^^^^^^^^^^^^^^^^
[990d8df]90
[97d172c]91If applying polydispersion to parameters describing particle sizes, consider using
[5026e05]92the Lognormal or Schulz distributions.
[990d8df]93
[ed5b109]94If applying polydispersion to parameters describing interfacial thicknesses
[97d172c]95or angular orientations, consider using the Gaussian or Boltzmann distributions.
[990d8df]96
[aa25fc7]97If applying polydispersion to parameters describing angles, use the Uniform
98distribution. Beware of using distributions that are always positive (eg, the
[29afc50]99Lognormal) because angles can be negative!
100
[0e04dd7]101The array distribution provides a very simple means of implementing a user-
102defined distribution, but without any fittable parameters. Greater flexibility
[a5cb9bc]103is conferred by the user-defined distribution.
[990d8df]104
[5026e05]105.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
[990d8df]106
[5026e05]107Uniform Distribution
108^^^^^^^^^^^^^^^^^^^^
[990d8df]109
[5026e05]110The Uniform Distribution is defined as
[990d8df]111
[f4ae8c4]112.. math::
[990d8df]113
[f4ae8c4]114    f(x) = \frac{1}{\text{Norm}}
115    \begin{cases}
116        1 & \text{for } |x - \bar x| \leq \sigma \\
117        0 & \text{for } |x - \bar x| > \sigma
118    \end{cases}
[990d8df]119
[f4ae8c4]120where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the
121distribution, $\sigma$ is the half-width, and *Norm* is a normalization
122factor which is determined during the numerical calculation.
[990d8df]123
[f4ae8c4]124The polydispersity in sasmodels is given by
[990d8df]125
[f4ae8c4]126.. math:: \text{PD} = \sigma / \bar x
[92d330fd]127
[f4ae8c4]128.. figure:: pd_uniform.jpg
[3d58247]129
[f4ae8c4]130    Uniform distribution.
[990d8df]131
[5026e05]132The value $N_\sigma$ is ignored for this distribution.
133
134.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
135
136Rectangular Distribution
[75e4319]137^^^^^^^^^^^^^^^^^^^^^^^^
138
[5026e05]139The Rectangular Distribution is defined as
[75e4319]140
[f4ae8c4]141.. math::
[75e4319]142
[f4ae8c4]143    f(x) = \frac{1}{\text{Norm}}
144    \begin{cases}
145        1 & \text{for } |x - \bar x| \leq w \\
146        0 & \text{for } |x - \bar x| > w
147    \end{cases}
[75e4319]148
[f4ae8c4]149where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the
150distribution, $w$ is the half-width, and *Norm* is a normalization
151factor which is determined during the numerical calculation.
[75e4319]152
[f4ae8c4]153Note that the standard deviation and the half width $w$ are different!
[75e4319]154
[f4ae8c4]155The standard deviation is
[75e4319]156
[f4ae8c4]157.. math:: \sigma = w / \sqrt{3}
[75e4319]158
[f4ae8c4]159whilst the polydispersity in sasmodels is given by
[92d330fd]160
[f4ae8c4]161.. math:: \text{PD} = \sigma / \bar x
[5026e05]162
[f4ae8c4]163.. figure:: pd_rectangular.jpg
[5026e05]164
[f4ae8c4]165    Rectangular distribution.
[ed5b109]166
[f4ae8c4]167.. note:: The Rectangular Distribution is deprecated in favour of the
168            Uniform Distribution above and is described here for backwards
169            compatibility with earlier versions of SasView only.
[75e4319]170
[990d8df]171.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
172
173Gaussian Distribution
174^^^^^^^^^^^^^^^^^^^^^
175
176The Gaussian Distribution is defined as
177
[f4ae8c4]178.. math::
[5026e05]179
[f4ae8c4]180    f(x) = \frac{1}{\text{Norm}}
181            \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right)
[990d8df]182
[f4ae8c4]183where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the
184distribution and *Norm* is a normalization factor which is determined
185during the numerical calculation.
[990d8df]186
[f4ae8c4]187The polydispersity in sasmodels is given by
[990d8df]188
[f4ae8c4]189.. math:: \text{PD} = \sigma / \bar x
[5026e05]190
[f4ae8c4]191.. figure:: pd_gaussian.jpg
[5026e05]192
[f4ae8c4]193    Normal distribution.
[5026e05]194
195.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
196
197Boltzmann Distribution
198^^^^^^^^^^^^^^^^^^^^^^
199
200The Boltzmann Distribution is defined as
[990d8df]201
[f4ae8c4]202.. math::
[990d8df]203
[f4ae8c4]204    f(x) = \frac{1}{\text{Norm}}
205            \exp\left(-\frac{ | x - \bar x | }{\sigma}\right)
[990d8df]206
[f4ae8c4]207where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the
208distribution and *Norm* is a normalization factor which is determined
209during the numerical calculation.
[5026e05]210
[f4ae8c4]211The width is defined as
[5026e05]212
[f4ae8c4]213.. math:: \sigma=\frac{k T}{E}
[5026e05]214
[f4ae8c4]215which is the inverse Boltzmann factor, where $k$ is the Boltzmann constant,
216$T$ the temperature in Kelvin and $E$ a characteristic energy per particle.
[5026e05]217
[f4ae8c4]218.. figure:: pd_boltzmann.jpg
[5026e05]219
[f4ae8c4]220    Boltzmann distribution.
[990d8df]221
222.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
223
224Lognormal Distribution
225^^^^^^^^^^^^^^^^^^^^^^
226
[ed5b109]227The Lognormal Distribution describes a function of $x$ where $\ln (x)$ has
228a normal distribution. The result is a distribution that is skewed towards
229larger values of $x$.
[5026e05]230
[990d8df]231The Lognormal Distribution is defined as
232
[f4ae8c4]233.. math::
[990d8df]234
[f4ae8c4]235    f(x) = \frac{1}{\text{Norm}}\frac{1}{x\sigma}
236            \exp\left(-\frac{1}{2}
237                        \bigg(\frac{\ln(x) - \mu}{\sigma}\bigg)^2\right)
[990d8df]238
[f4ae8c4]239where *Norm* is a normalization factor which will be determined during
240the numerical calculation, $\mu=\ln(x_\text{med})$ and $x_\text{med}$
241is the *median* value of the *lognormal* distribution, but $\sigma$ is
242a parameter describing the width of the underlying *normal* distribution.
[ed5b109]243
[f4ae8c4]244$x_\text{med}$ will be the value given for the respective size parameter
245in sasmodels, for example, *radius=60*.
[990d8df]246
[f4ae8c4]247The polydispersity in sasmodels is given by
[990d8df]248
[29afc50]249.. math:: \text{PD} = \sigma = p / x_\text{med}
[990d8df]250
[29afc50]251The mean value of the distribution is given by $\bar x = \exp(\mu+ \sigma^2/2)$
252and the peak value by $\max x = \exp(\mu - \sigma^2)$.
[990d8df]253
[f4ae8c4]254The variance (the square of the standard deviation) of the *lognormal*
255distribution is given by
[990d8df]256
[f4ae8c4]257.. math::
[990d8df]258
[f4ae8c4]259    \nu = [\exp({\sigma}^2) - 1] \exp({2\mu + \sigma^2})
[990d8df]260
[f4ae8c4]261Note that larger values of PD might need a larger number of points
262and $N_\sigma$.
[ed5b109]263
[f4ae8c4]264.. figure:: pd_lognormal.jpg
[990d8df]265
[29afc50]266    Lognormal distribution for PD=0.1.
[990d8df]267
[5026e05]268For further information on the Lognormal distribution see:
[ed5b109]269http://en.wikipedia.org/wiki/Log-normal_distribution and
[5026e05]270http://mathworld.wolfram.com/LogNormalDistribution.html
[990d8df]271
272.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
273
274Schulz Distribution
275^^^^^^^^^^^^^^^^^^^
276
[ed5b109]277The Schulz (sometimes written Schultz) distribution is similar to the
278Lognormal distribution, in that it is also skewed towards larger values of
279$x$, but which has computational advantages over the Lognormal distribution.
[5026e05]280
[990d8df]281The Schulz distribution is defined as
282
[f4ae8c4]283.. math::
[990d8df]284
[f4ae8c4]285    f(x) = \frac{1}{\text{Norm}} (z+1)^{z+1}(x/\bar x)^z
286            \frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)}
[990d8df]287
[f4ae8c4]288where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the
289distribution, *Norm* is a normalization factor which is determined
290during the numerical calculation, and $z$ is a measure of the width
291of the distribution such that
[990d8df]292
[f4ae8c4]293.. math:: z = (1-p^2) / p^2
[990d8df]294
[f4ae8c4]295where $p$ is the polydispersity in sasmodels given by
[990d8df]296
[f4ae8c4]297.. math:: PD = p = \sigma / \bar x
[990d8df]298
[f4ae8c4]299and $\sigma$ is the RMS deviation from $\bar x$.
[ed5b109]300
[f4ae8c4]301Note that larger values of PD might need a larger number of points
302and $N_\sigma$. For example, for PD=0.7 with radius=60 |Ang|, at least
303Npts>=160 and Nsigmas>=15 are required.
[990d8df]304
[f4ae8c4]305.. figure:: pd_schulz.jpg
[990d8df]306
[f4ae8c4]307    Schulz distribution.
[990d8df]308
309For further information on the Schulz distribution see:
[5026e05]310M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461 and
[ed5b109]311M Kotlarchyk, RB Stephens, and JS Huang, *J Phys Chem*, (1988), 92, 1533
[990d8df]312
313.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
314
315Array Distribution
316^^^^^^^^^^^^^^^^^^
317
[a5a12ca]318This user-definable distribution should be given as a simple ASCII text
[990d8df]319file where the array is defined by two columns of numbers: $x$ and $f(x)$.
320The $f(x)$ will be normalized to 1 during the computation.
321
322Example of what an array distribution file should look like:
323
324====  =====
325 30    0.1
326 32    0.3
327 35    0.4
328 36    0.5
329 37    0.6
330 39    0.7
331 41    0.9
332====  =====
333
334Only these array values are used computation, therefore the parameter value
335given for the model will have no affect, and will be ignored when computing
336the average.  This means that any parameter with an array distribution will
[a5a12ca]337not be fitable.
338
339.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
340
[aa25fc7]341User-defined Distributions
342^^^^^^^^^^^^^^^^^^^^^^^^^^
343
[0e04dd7]344You can also define your own distribution by creating a python file defining a
[36873d1]345*Distribution* object with a *_weights* method.  The *_weights* method takes
346*center*, *sigma*, *lb* and *ub* as arguments, and can access *self.npts*
347and *self.nsigmas* from the distribution.  They are interpreted as follows:
[aa25fc7]348
[36873d1]349* *center* the value of the shape parameter (for size dispersity) or zero
350  if it is an angular dispersity.  This parameter may be fitted.
351
[0e04dd7]352* *sigma* the width of the distribution, which is the polydispersity parameter
[36873d1]353  times the center for size dispersity, or the polydispersity parameter alone
354  for angular dispersity.  This parameter may be fitted.
355
[0e04dd7]356* *lb*, *ub* are the parameter limits (lower & upper bounds) given in the model
357  definition file.  For example, a radius parameter has *lb* equal to zero.  A
358  volume fraction parameter would have *lb* equal to zero and *ub* equal to one.
[36873d1]359
360* *self.nsigmas* the distance to go into the tails when evaluating the
361  distribution.  For a two parameter distribution, this value could be
362  co-opted to use for the second parameter, though it will not be available
363  for fitting.
364
365* *self.npts* the number of points to use when evaluating the distribution.
366  The user will adjust this to trade calculation time for accuracy, but the
367  distribution code is free to return more or fewer, or use it for the third
368  parameter in a three parameter distribution.
369
[0e04dd7]370As an example, the code following wraps the Laplace distribution from scipy stats::
[aa25fc7]371
372    import numpy as np
373    from scipy.stats import laplace
374
375    from sasmodels import weights
376
377    class Dispersion(weights.Dispersion):
378        r"""
379        Laplace distribution
380
381        .. math::
382
383            w(x) = e^{-\sigma |x - \mu|}
384        """
385        type = "laplace"
386        default = dict(npts=35, width=0, nsigmas=3)  # default values
387        def _weights(self, center, sigma, lb, ub):
388            x = self._linspace(center, sigma, lb, ub)
389            wx = laplace.pdf(x, center, sigma)
390            return x, wx
391
[36873d1]392You can plot the weights for a given value and width using the following::
[aa25fc7]393
394    from numpy import inf
395    from matplotlib import pyplot as plt
396    from sasmodels import weights
397
398    # reload the user-defined weights
399    weights.load_weights()
400    x, wx = weights.get_weights('laplace', n=35, width=0.1, nsigmas=3, value=50,
401                                limits=[0, inf], relative=True)
402
403    # plot the weights
404    plt.interactive(True)
405    plt.plot(x, wx, 'x')
406
[36873d1]407The *self.nsigmas* and *self.npts* parameters are normally used to control
408the accuracy of the distribution integral. The *self._linspace* function
409uses them to define the *x* values (along with the *center*, *sigma*,
410*lb*, and *ub* which are passed as parameters).  If you repurpose npts or
411nsigmas you will need to generate your own *x*.  Be sure to honour the
412limits *lb* and *ub*, for example to disallow a negative radius or constrain
413the volume fraction to lie between zero and one.
[aa25fc7]414
[f41027b]415To activate a user-defined distribution, put it in a file such as *distname.py*
416in the *SAS_WEIGHTS_PATH* folder.  This is defined with an environment
417variable, defaulting to::
[9ce5bcb]418
[f41027b]419    SAS_WEIGHTS_PATH=~/.sasview/weights
420
421The weights path is loaded on startup.  To update the distribution definition
422in a running application you will need to enter the following python commands::
423
424    import sasmodels.weights
425    sasmodels.weights.load_weights('path/to/distname.py')
[9ce5bcb]426
[aa25fc7]427.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
428
[990d8df]429Note about DLS polydispersity
430^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
431
[a5cb9bc]432Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and
433it should not be assumed that any of the following can be simply equated with
[97d172c]434the polydispersity *PD* parameter used in SasView.
435
[a5cb9bc]436The dimensionless **Polydispersity Index (PI)** is a measure of the width of the
437distribution of autocorrelation function decay rates (*not* the distribution of
438particle sizes itself, though the two are inversely related) and is defined by
[97d172c]439ISO 22412:2017 as
[990d8df]440
[5026e05]441.. math::
442
[97d172c]443    PI = \mu_{2} / \bar \Gamma^2
444
[a5cb9bc]445where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the
[97d172c]446intensity-weighted average value, of the distribution of decay rates.
447
448*If the distribution of decay rates is Gaussian* then
449
450.. math::
451
452    PI = \sigma^2 / 2\bar \Gamma^2
453
[a5cb9bc]454where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)**
[97d172c]455to be defined as
[990d8df]456
[5026e05]457.. math::
458
[86bb5df]459    RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI}
[5026e05]460
[a5cb9bc]461PI values smaller than 0.05 indicate a highly monodisperse system. Values
[97d172c]462greater than 0.7 indicate significant polydispersity.
463
[a5cb9bc]464The **size polydispersity P-parameter** is defined as the relative standard
465deviation coefficient of variation
[97d172c]466
467.. math::
468
469    P = \sqrt\nu / \bar R
470
471where $\nu$ is the variance of the distribution and $\bar R$ is the mean
[a5cb9bc]472value of $R$. Here, the product $P \bar R$ is *equal* to the standard
[97d172c]473deviation of the Lognormal distribution.
[5026e05]474
[97d172c]475P values smaller than 0.13 indicate a monodisperse system.
[5026e05]476
[990d8df]477For more information see:
[d089a00]478
479`ISO 22412:2017, International Standards Organisation (2017) <https://www.iso.org/standard/65410.html>`_.
480
481`Polydispersity: What does it mean for DLS and Chromatography <http://www.materials-talks.com/blog/2014/10/23/polydispersity-what-does-it-mean-for-dls-and-chromatography/>`_.
482
483`Dynamic Light Scattering: Common Terms Defined, Whitepaper WP111214. Malvern Instruments (2011) <http://www.biophysics.bioc.cam.ac.uk/wp-content/uploads/2011/02/DLS_Terms_defined_Malvern.pdf>`_.
484
485S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143.
486
[97d172c]487T Allen, in *Particle Size Measurement*, 4th Edition, Chapman & Hall, London (1990).
[990d8df]488
489.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
490
491*Document History*
492
493| 2015-05-01 Steve King
494| 2017-05-08 Paul Kienzle
[5026e05]495| 2018-03-20 Steve King
[29afc50]496| 2018-04-04 Steve King
[97d172c]497| 2018-08-09 Steve King
Note: See TracBrowser for help on using the repository browser.