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