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