Changeset 5026e05 in sasmodels for doc/guide


Ignore:
Timestamp:
Mar 20, 2018 11:19:43 AM (7 years ago)
Author:
smk78
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
Added
Removed
  • doc/guide/pd/polydispersity.rst

    r92d330fd r5026e05  
    2323average over the size distribution. 
    2424 
    25 Each distribution is characterized by its center $\bar x$, its width $\sigma$, 
    26 the number of sigmas $N_\sigma$ to include from the tails, and the number of 
    27 points used to compute the average. The center of the distribution is set by the 
    28 value of the model parameter.  Volume parameters have polydispersity *PD* 
    29 (not to be confused with a molecular weight distributions in polymer science) 
    30 leading to a size distribution of width $\text{PD} = \sigma / \bar x$, but 
    31 orientation parameters use an angular distributions of width $\sigma$. 
     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 
    3235$N_\sigma$ determines how far into the tails to evaluate the distribution, with 
    3336larger values of $N_\sigma$ required for heavier tailed distributions. 
     
    4447The following distribution functions are provided: 
    4548 
     49*  *Uniform Distribution* 
    4650*  *Rectangular Distribution* 
    47 *  *Uniform Distribution* 
    4851*  *Gaussian Distribution* 
     52*  *Boltzmann Distribution* 
    4953*  *Lognormal Distribution* 
    5054*  *Schulz Distribution* 
    5155*  *Array Distribution* 
    52 *  *Boltzmann Distribution* 
    5356 
    5457These are all implemented as *number-average* distributions. 
    5558 
    56 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    57  
    58 Rectangular Distribution 
    59 ^^^^^^^^^^^^^^^^^^^^^^^^ 
    60  
    61 The Rectangular Distribution is defined as 
    62  
    63 .. math:: 
    64  
    65     f(x) = \frac{1}{\text{Norm}} 
    66     \begin{cases} 
    67       1 & \text{for } |x - \bar x| \leq w \\ 
    68       0 & \text{for } |x - \bar x| > w 
    69     \end{cases} 
    70  
    71 where $\bar x$ is the mean of the distribution, $w$ is the half-width, and 
    72 *Norm* is a normalization factor which is determined during the numerical 
    73 calculation. 
    74  
    75 Note that the standard deviation and the half width $w$ are different! 
    76  
    77 The standard deviation is 
    78  
    79 .. math:: \sigma = w / \sqrt{3} 
    80  
    81 whilst the polydispersity is 
    82  
    83 .. math:: \text{PD} = \sigma / \bar x 
    84  
    85 .. figure:: pd_rectangular.jpg 
    86  
    87     Rectangular distribution. 
    88  
    89  
     59Additional distributions are under consideration. 
     60 
     61Suggested Applications 
     62^^^^^^^^^^^^^^^^^^^^^^ 
     63 
     64If applying polydispersion to parameters describing particle sizes, use  
     65the Lognormal or Schulz distributions. 
     66 
     67If applying polydispersion to parameters describing interfacial thicknesses  
     68or angular orientations, use the Gaussian or Boltzmann distributions. 
     69 
     70The array distribution allows a user-defined distribution to be applied. 
     71 
     72.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    9073 
    9174Uniform Distribution 
    92 ^^^^^^^^^^^^^^^^^^^^^^^^ 
     75^^^^^^^^^^^^^^^^^^^^ 
    9376 
    9477The Uniform Distribution is defined as 
     
    10285        \end{cases} 
    10386 
    104     where $\bar x$ is the mean of the distribution, $\sigma$ is the half-width, and 
    105     *Norm* is a normalization factor which is determined during the numerical 
    106     calculation. 
    107  
    108     Note that the polydispersity is given by 
     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. 
     90 
     91    The polydispersity in sasmodels is given by 
    10992 
    11093    .. math:: \text{PD} = \sigma / \bar x 
     
    11598 
    11699The value $N_\sigma$ is ignored for this distribution. 
     100 
     101.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     102 
     103Rectangular Distribution 
     104^^^^^^^^^^^^^^^^^^^^^^^^ 
     105 
     106The Rectangular Distribution is defined as 
     107 
     108    .. math:: 
     109 
     110        f(x) = \frac{1}{\text{Norm}} 
     111        \begin{cases} 
     112          1 & \text{for } |x - \bar x| \leq w \\ 
     113          0 & \text{for } |x - \bar x| > w 
     114        \end{cases} 
     115 
     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. 
     119 
     120    Note that the standard deviation and the half width $w$ are different! 
     121 
     122    The standard deviation is 
     123 
     124    .. math:: \sigma = w / \sqrt{3} 
     125 
     126    whilst the polydispersity in sasmodels is given by 
     127 
     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. 
    117136 
    118137.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    123142The Gaussian Distribution is defined as 
    124143 
    125 .. math:: 
    126  
    127     f(x) = \frac{1}{\text{Norm}} 
    128            \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) 
    129  
    130 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    131 factor which is determined during the numerical calculation. 
    132  
    133 The polydispersity is 
    134  
    135 .. math:: \text{PD} = \sigma / \bar x 
    136  
    137 .. figure:: pd_gaussian.jpg 
    138  
    139     Normal distribution. 
     144    .. math:: 
     145 
     146        f(x) = \frac{1}{\text{Norm}} 
     147               \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) 
     148 
     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. 
     151 
     152    The polydispersity in sasmodels is given by 
     153 
     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 
     166 
     167    .. math:: 
     168 
     169        f(x) = \frac{1}{\text{Norm}} 
     170               \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) 
     171 
     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. 
    140185 
    141186.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    144189^^^^^^^^^^^^^^^^^^^^^^ 
    145190 
     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 
    146194The Lognormal Distribution is defined as 
    147195 
    148 .. math:: 
    149  
    150     f(x) = \frac{1}{\text{Norm}} 
    151            \frac{1}{xp}\exp\left(-\frac{(\ln(x) - \mu)^2}{2p^2}\right) 
    152  
    153 where $\mu=\ln(x_\text{med})$ when $x_\text{med}$ is the median value of the 
    154 distribution, and *Norm* is a normalization factor which will be determined 
    155 during the numerical calculation. 
    156  
    157 The median value for the distribution will be the value given for the 
    158 respective size parameter, for example, *radius=60*. 
    159  
    160 The polydispersity is given by $\sigma$ 
    161  
    162 .. math:: \text{PD} = p 
    163  
    164 For the angular distribution 
    165  
    166 .. math:: p = \sigma / x_\text{med} 
    167  
    168 The mean value is given by $\bar x = \exp(\mu+ p^2/2)$. The peak value 
    169 is given by $\max x = \exp(\mu - p^2)$. 
    170  
    171 .. figure:: pd_lognormal.jpg 
    172  
    173     Lognormal distribution. 
    174  
    175 This distribution function spreads more, and the peak shifts to the left, as 
    176 $p$ increases, so it requires higher values of $N_\sigma$ and more points 
    177 in the distribution. 
     196    .. math:: 
     197 
     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. 
     204 
     205    $x_\text{med}$ will be the value given for the respective size parameter in sasmodels, for  
     206    example, *radius=60*. 
     207 
     208    The polydispersity in sasmodels is given by 
     209 
     210    .. math:: \text{PD} = p = \sigma / x_\text{med} 
     211 
     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)$. 
     214 
     215    The variance (the square of the standard deviation) of the *lognormal* distribution is given by 
     216 
     217    .. math:: 
     218 
     219        \nu = [\exp({\sigma}^2) - 1] \exp({2\mu + \sigma^2}) 
     220 
     221    Note that larger values of PD might need a larger number of points and $N_\sigma$. 
     222     
     223    .. figure:: pd_lognormal.jpg 
     224 
     225        Lognormal distribution. 
     226 
     227For further information on the Lognormal distribution see: 
     228http://en.wikipedia.org/wiki/Log-normal_distribution and  
     229http://mathworld.wolfram.com/LogNormalDistribution.html 
    178230 
    179231.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    182234^^^^^^^^^^^^^^^^^^^ 
    183235 
     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 
    184240The Schulz distribution is defined as 
    185241 
    186 .. math:: 
    187  
    188     f(x) = \frac{1}{\text{Norm}} 
    189            (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)} 
    190  
    191 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    192 factor which is determined during the numerical calculation, and $z$ is a 
    193 measure of the width of the distribution such that 
    194  
    195 .. math:: z = (1-p^2) / p^2 
    196  
    197 The polydispersity is 
    198  
    199 .. math:: p = \sigma / \bar x 
    200  
    201 Note that larger values of PD might need larger number of points and $N_\sigma$. 
    202 For example, at PD=0.7 and radius=60 |Ang|, Npts>=160 and Nsigmas>=15 at least. 
    203  
    204 .. figure:: pd_schulz.jpg 
    205  
    206     Schulz distribution. 
     242    .. math:: 
     243 
     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)} 
     246 
     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 
     250 
     251    .. math:: z = (1-p^2) / p^2 
     252 
     253    where $p$ is the polydispersity in sasmodels given by 
     254 
     255    .. math:: PD = p = \sigma / \bar x 
     256 
     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. 
     261 
     262    .. figure:: pd_schulz.jpg 
     263 
     264        Schulz distribution. 
    207265 
    208266For further information on the Schulz distribution see: 
    209 M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461. 
     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  
    210269 
    211270.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    237296.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    238297 
    239 Boltzmann Distribution 
    240 ^^^^^^^^^^^^^^^^^^^^^^ 
    241  
    242 The Boltzmann Distribution is defined as 
    243  
    244 .. math:: 
    245  
    246     f(x) = \frac{1}{\text{Norm}} 
    247            \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) 
    248  
    249 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    250 factor which is determined during the numerical calculation. 
    251 The width is defined as 
    252  
    253 .. math:: \sigma=\frac{k T}{E} 
    254  
    255 which is the inverse Boltzmann factor, 
    256 where $k$ is the Boltzmann constant, $T$ the temperature in Kelvin and $E$ a 
    257 characteristic energy per particle. 
    258  
    259 .. figure:: pd_boltzmann.jpg 
    260  
    261     Boltzmann distribution. 
    262  
    263 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    264  
    265298Note about DLS polydispersity 
    266299^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
     
    273306related) except when the DLS polydispersity parameter is <0.13. 
    274307 
     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 
    275314For more information see: 
    276315S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143 
     
    282321| 2015-05-01 Steve King 
    283322| 2017-05-08 Paul Kienzle 
     323| 2018-03-20 Steve King 
Note: See TracChangeset for help on using the changeset viewer.