# Changeset 5026e05 in sasmodels for doc/guide/pd/polydispersity.rst

Ignore:
Timestamp:
Mar 20, 2018 11:19:43 AM (4 years ago)
Branches:
master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests
Children:
ed5b109
Parents:
e2f1a41
Message:

Overhaul of polydispersity help for content, readability and accuracy.

File:
1 edited

### Legend:

Unmodified
 r92d330fd average over the size distribution. Each distribution is characterized by its center $\bar x$, its width $\sigma$, the number of sigmas $N_\sigma$ to include from the tails, and the number of points used to compute the average. The center of the distribution is set by the value of the model parameter.  Volume parameters have polydispersity *PD* (not to be confused with a molecular weight distributions in polymer science) leading to a size distribution of width $\text{PD} = \sigma / \bar x$, but orientation parameters use an angular distributions of width $\sigma$. Each distribution is characterized by a center value $\bar x$ or $x_\text{med}$, a width parameter $\sigma$ (note this is *not necessarily* the standard deviation, so read the description carefully), the number of sigmas $N_\sigma$ to include from the tails of the distribution, and the number of points used to compute the average. The center of the distribution is set by the value of the model parameter. Volume parameters have polydispersity *PD* (not to be confused with a molecular weight distributions in polymer science), but orientation parameters use angular distributions of width $\sigma$. $N_\sigma$ determines how far into the tails to evaluate the distribution, with larger values of $N_\sigma$ required for heavier tailed distributions. The following distribution functions are provided: *  *Uniform Distribution* *  *Rectangular Distribution* *  *Uniform Distribution* *  *Gaussian Distribution* *  *Boltzmann Distribution* *  *Lognormal Distribution* *  *Schulz Distribution* *  *Array Distribution* *  *Boltzmann Distribution* These are all implemented as *number-average* distributions. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Rectangular Distribution ^^^^^^^^^^^^^^^^^^^^^^^^ The Rectangular Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \begin{cases} 1 & \text{for } |x - \bar x| \leq w \\ 0 & \text{for } |x - \bar x| > w \end{cases} where $\bar x$ is the mean of the distribution, $w$ is the half-width, and *Norm* is a normalization factor which is determined during the numerical calculation. Note that the standard deviation and the half width $w$ are different! The standard deviation is .. math:: \sigma = w / \sqrt{3} whilst the polydispersity is .. math:: \text{PD} = \sigma / \bar x .. figure:: pd_rectangular.jpg Rectangular distribution. Additional distributions are under consideration. Suggested Applications ^^^^^^^^^^^^^^^^^^^^^^ If applying polydispersion to parameters describing particle sizes, use the Lognormal or Schulz distributions. If applying polydispersion to parameters describing interfacial thicknesses or angular orientations, use the Gaussian or Boltzmann distributions. The array distribution allows a user-defined distribution to be applied. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Uniform Distribution ^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^ The Uniform Distribution is defined as \end{cases} where $\bar x$ is the mean of the distribution, $\sigma$ is the half-width, and *Norm* is a normalization factor which is determined during the numerical calculation. Note that the polydispersity is given by where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution, $\sigma$ is the half-width, and *Norm* is a normalization factor which is determined during the numerical calculation. The polydispersity in sasmodels is given by .. math:: \text{PD} = \sigma / \bar x The value $N_\sigma$ is ignored for this distribution. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Rectangular Distribution ^^^^^^^^^^^^^^^^^^^^^^^^ The Rectangular Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \begin{cases} 1 & \text{for } |x - \bar x| \leq w \\ 0 & \text{for } |x - \bar x| > w \end{cases} where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution, $w$ is the half-width, and *Norm* is a normalization factor which is determined during the numerical calculation. Note that the standard deviation and the half width $w$ are different! The standard deviation is .. math:: \sigma = w / \sqrt{3} whilst the polydispersity in sasmodels is given by .. math:: \text{PD} = \sigma / \bar x .. figure:: pd_rectangular.jpg Rectangular distribution. .. note:: The Rectangular Distribution is deprecated in favour of the Uniform Distribution above and is described here for backwards compatibility with earlier versions of SasView only. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ The Gaussian Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) where $\bar x$ is the mean of the distribution and *Norm* is a normalization factor which is determined during the numerical calculation. The polydispersity is .. math:: \text{PD} = \sigma / \bar x .. figure:: pd_gaussian.jpg Normal distribution. .. math:: f(x) = \frac{1}{\text{Norm}} \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution and *Norm* is a normalization factor which is determined during the numerical calculation. The polydispersity in sasmodels is given by .. math:: \text{PD} = \sigma / \bar x .. figure:: pd_gaussian.jpg Normal distribution. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Boltzmann Distribution ^^^^^^^^^^^^^^^^^^^^^^ The Boltzmann Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution and *Norm* is a normalization factor which is determined during the numerical calculation. The width is defined as .. math:: \sigma=\frac{k T}{E} which is the inverse Boltzmann factor, where $k$ is the Boltzmann constant, $T$ the temperature in Kelvin and $E$ a characteristic energy per particle. .. figure:: pd_boltzmann.jpg Boltzmann distribution. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ ^^^^^^^^^^^^^^^^^^^^^^ The Lognormal Distribution describes a function of $x$ where $\ln (x)$ has a normal distribution. The result is a distribution that is skewed towards larger values of $x$. The Lognormal Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \frac{1}{xp}\exp\left(-\frac{(\ln(x) - \mu)^2}{2p^2}\right) where $\mu=\ln(x_\text{med})$ when $x_\text{med}$ is the median value of the distribution, and *Norm* is a normalization factor which will be determined during the numerical calculation. The median value for the distribution will be the value given for the respective size parameter, for example, *radius=60*. The polydispersity is given by $\sigma$ .. math:: \text{PD} = p For the angular distribution .. math:: p = \sigma / x_\text{med} The mean value is given by $\bar x = \exp(\mu+ p^2/2)$. The peak value is given by $\max x = \exp(\mu - p^2)$. .. figure:: pd_lognormal.jpg Lognormal distribution. This distribution function spreads more, and the peak shifts to the left, as $p$ increases, so it requires higher values of $N_\sigma$ and more points in the distribution. .. math:: f(x) = \frac{1}{\text{Norm}} \frac{1}{x\sigma}\exp\left(-\frac{1}{2}\bigg(\frac{\ln(x) - \mu}{\sigma}\bigg)^2\right) where *Norm* is a normalization factor which will be determined during the numerical calculation, $\mu=\ln(x_\text{med})$ and $x_\text{med}$ is the *median* value of the *lognormal* distribution, but $\sigma$ is a parameter describing the width of the underlying *normal* distribution. $x_\text{med}$ will be the value given for the respective size parameter in sasmodels, for example, *radius=60*. The polydispersity in sasmodels is given by .. math:: \text{PD} = p = \sigma / x_\text{med} The mean value of the distribution is given by $\bar x = \exp(\mu+ p^2/2)$ and the peak value by $\max x = \exp(\mu - p^2)$. The variance (the square of the standard deviation) of the *lognormal* distribution is given by .. math:: \nu = [\exp({\sigma}^2) - 1] \exp({2\mu + \sigma^2}) Note that larger values of PD might need a larger number of points and $N_\sigma$. .. figure:: pd_lognormal.jpg Lognormal distribution. For further information on the Lognormal distribution see: http://en.wikipedia.org/wiki/Log-normal_distribution and http://mathworld.wolfram.com/LogNormalDistribution.html .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ ^^^^^^^^^^^^^^^^^^^ The Schulz (sometimes written Schultz) distribution is similar to the Lognormal distribution, in that it is also skewed towards larger values of $x$, but which has computational advantages over the Lognormal distribution. The Schulz distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)} where $\bar x$ is the mean of the distribution and *Norm* is a normalization factor which is determined during the numerical calculation, and $z$ is a measure of the width of the distribution such that .. math:: z = (1-p^2) / p^2 The polydispersity is .. math:: p = \sigma / \bar x Note that larger values of PD might need larger number of points and $N_\sigma$. For example, at PD=0.7 and radius=60 |Ang|, Npts>=160 and Nsigmas>=15 at least. .. figure:: pd_schulz.jpg Schulz distribution. .. math:: f(x) = \frac{1}{\text{Norm}} (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)} where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the distribution, *Norm* is a normalization factor which is determined during the numerical calculation, and $z$ is a measure of the width of the distribution such that .. math:: z = (1-p^2) / p^2 where $p$ is the polydispersity in sasmodels given by .. math:: PD = p = \sigma / \bar x and $\sigma$ is the RMS deviation from $\bar x$. Note that larger values of PD might need a larger number of points and $N_\sigma$. For example, for PD=0.7 with radius=60 |Ang|, at least Npts>=160 and Nsigmas>=15 are required. .. figure:: pd_schulz.jpg Schulz distribution. For further information on the Schulz distribution see: M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461. M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461 and M Kotlarchyk, RB Stephens, and JS Huang, *J Phys Chem*, (1988), 92, 1533 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Boltzmann Distribution ^^^^^^^^^^^^^^^^^^^^^^ The Boltzmann Distribution is defined as .. math:: f(x) = \frac{1}{\text{Norm}} \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) where $\bar x$ is the mean of the distribution and *Norm* is a normalization factor which is determined during the numerical calculation. The width is defined as .. math:: \sigma=\frac{k T}{E} which is the inverse Boltzmann factor, where $k$ is the Boltzmann constant, $T$ the temperature in Kelvin and $E$ a characteristic energy per particle. .. figure:: pd_boltzmann.jpg Boltzmann distribution. .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ Note about DLS polydispersity ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ related) except when the DLS polydispersity parameter is <0.13. .. math:: p_{DLS} = \sqrt(\nu / \bar x^2) where $\nu$ is the variance of the distribution and $\bar x$ is the mean value of x. For more information see: S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143 | 2015-05-01 Steve King | 2017-05-08 Paul Kienzle | 2018-03-20 Steve King