- Timestamp:
- Mar 6, 2019 6:10:02 PM (6 years ago)
- Branches:
- master
- Children:
- f64b154
- Parents:
- 4e96703 (diff), 9150036 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent. - Location:
- doc/guide
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/guide/plugin.rst
raa8c6e0 r9150036 272 272 structure factor to account for interactions between particles. See 273 273 `Form_Factors`_ for more details. 274 275 **model_info = ...** lets you define a model directly, for example, by 276 loading and modifying existing models. This is done implicitly by 277 :func:`sasmodels.core.load_model_info`, which can create a mixture model 278 from a pair of existing models. For example:: 279 280 from sasmodels.core import load_model_info 281 model_info = load_model_info('sphere+cylinder') 282 283 See :class:`sasmodels.modelinfo.ModelInfo` for details about the model 284 attributes that are defined. 274 285 275 286 Model Parameters … … 894 905 - \frac{\sin(x)}{x}\left(\frac{1}{x} - \frac{3!}{x^3} + \frac{5!}{x^5} - \frac{7!}{x^7}\right) 895 906 896 For small arguments 907 For small arguments, 897 908 898 909 .. math:: -
doc/guide/pd/polydispersity.rst
rd089a00 ra5cb9bc 11 11 -------------------------------------------- 12 12 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 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 17 the actual parameter it is being applied too. 18 18 19 The resultant intensity is then normalized by the average particle volume such 19 The resultant intensity is then normalized by the average particle volume such 20 20 that 21 21 … … 24 24 P(q) = \text{scale} \langle F^* F \rangle / V + \text{background} 25 25 26 where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 26 where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 27 27 average over the distribution $f(x; \bar x, \sigma)$, giving 28 28 29 29 .. math:: 30 30 31 P(q) = \frac{\text{scale}}{V} \int_\mathbb{R} 31 P(q) = \frac{\text{scale}}{V} \int_\mathbb{R} 32 32 f(x; \bar x, \sigma) F^2(q, x)\, dx + \text{background} 33 33 34 34 Each distribution is characterized by a center value $\bar x$ or 35 35 $x_\text{med}$, a width parameter $\sigma$ (note this is *not necessarily* 36 the standard deviation, so read the description of the distribution carefully), 37 the number of sigmas $N_\sigma$ to include from the tails of the distribution, 38 and the number of points used to compute the average. The center of the 39 distribution is set by the value of the model parameter. 40 41 The distribution width applied to *volume* (ie, shape-describing) parameters 42 is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$. 43 However, the distribution width applied to *orientation* parameters is just 44 $\sigma = \mathrm{PD}$. 36 the standard deviation, so read the description carefully), the number of 37 sigmas $N_\sigma$ to include from the tails of the distribution, and the 38 number of points used to compute the average. The center of the distribution 39 is set by the value of the model parameter. The meaning of a polydispersity 40 parameter *PD* (not to be confused with a molecular weight distributions 41 in polymer science) in a model depends on the type of parameter it is being 42 applied too. 43 44 The distribution width applied to *volume* (ie, shape-describing) parameters 45 is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$. 46 However, the distribution width applied to *orientation* (ie, angle-describing) 47 parameters is just $\sigma = \mathrm{PD}$. 45 48 46 49 $N_\sigma$ determines how far into the tails to evaluate the distribution, … … 52 55 53 56 Users should note that the averaging computation is very intensive. Applying 54 polydispersion and/or orientational distributions to multiple parameters at 55 the same time, or increasing the number of points in the distribution, will 56 require patience! However, the calculations are generally more robust with 57 polydispersion and/or orientational distributions to multiple parameters at 58 the same time, or increasing the number of points in the distribution, will 59 require patience! However, the calculations are generally more robust with 57 60 more data points or more angles. 58 61 … … 66 69 * *Schulz Distribution* 67 70 * *Array Distribution* 71 * *User-defined Distributions* 68 72 69 73 These are all implemented as *number-average* distributions. 70 74 71 Additional distributions are under consideration.72 75 73 76 **Beware: when the Polydispersity & Orientational Distribution panel in SasView is** … … 75 78 **This may not be suitable. See Suggested Applications below.** 76 79 77 .. note:: In 2009 IUPAC decided to introduce the new term 'dispersity' to replace 78 the term 'polydispersity' (see `Pure Appl. Chem., (2009), 81(2), 79 351-353 <http://media.iupac.org/publications/pac/2009/pdf/8102x0351.pdf>`_ 80 in order to make the terminology describing distributions of chemical 81 properties unambiguous. However, these terms are unrelated to the 82 proportional size distributions and orientational distributions used in 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 83 86 SasView models. 84 87 … … 92 95 or angular orientations, consider using the Gaussian or Boltzmann distributions. 93 96 94 If applying polydispersion to parameters describing angles, use the Uniform 95 distribution. Beware of using distributions that are always positive (eg, the 97 If applying polydispersion to parameters describing angles, use the Uniform 98 distribution. Beware of using distributions that are always positive (eg, the 96 99 Lognormal) because angles can be negative! 97 100 98 The array distribution allows a user-defined distribution to be applied. 101 The array distribution provides a very simple means of implementing a user- 102 defined distribution, but without any fittable parameters. Greater flexibility 103 is conferred by the user-defined distribution. 99 104 100 105 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ … … 334 339 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 335 340 341 User-defined Distributions 342 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 343 344 You can also define your own distribution by creating a python file defining a 345 *Distribution* object with a *_weights* method. The *_weights* method takes 346 *center*, *sigma*, *lb* and *ub* as arguments, and can access *self.npts* 347 and *self.nsigmas* from the distribution. They are interpreted as follows: 348 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 352 * *sigma* the width of the distribution, which is the polydispersity parameter 353 times the center for size dispersity, or the polydispersity parameter alone 354 for angular dispersity. This parameter may be fitted. 355 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. 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 370 As an example, the code following wraps the Laplace distribution from scipy stats:: 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 392 You can plot the weights for a given value and width using the following:: 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 407 The *self.nsigmas* and *self.npts* parameters are normally used to control 408 the accuracy of the distribution integral. The *self._linspace* function 409 uses 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 411 nsigmas you will need to generate your own *x*. Be sure to honour the 412 limits *lb* and *ub*, for example to disallow a negative radius or constrain 413 the volume fraction to lie between zero and one. 414 415 To activate a user-defined distribution, put it in a file such as *distname.py* 416 in the *SAS_WEIGHTS_PATH* folder. This is defined with an environment 417 variable, defaulting to:: 418 419 SAS_WEIGHTS_PATH=~/.sasview/weights 420 421 The weights path is loaded on startup. To update the distribution definition 422 in 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') 426 427 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 428 336 429 Note about DLS polydispersity 337 430 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 338 431 339 Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and 340 it should not be assumed that any of the following can be simply equated with 432 Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and 433 it should not be assumed that any of the following can be simply equated with 341 434 the polydispersity *PD* parameter used in SasView. 342 435 343 The dimensionless **Polydispersity Index (PI)** is a measure of the width of the 344 distribution of autocorrelation function decay rates (*not* the distribution of 345 particle sizes itself, though the two are inversely related) and is defined by 436 The dimensionless **Polydispersity Index (PI)** is a measure of the width of the 437 distribution of autocorrelation function decay rates (*not* the distribution of 438 particle sizes itself, though the two are inversely related) and is defined by 346 439 ISO 22412:2017 as 347 440 … … 350 443 PI = \mu_{2} / \bar \Gamma^2 351 444 352 where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the 445 where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the 353 446 intensity-weighted average value, of the distribution of decay rates. 354 447 … … 359 452 PI = \sigma^2 / 2\bar \Gamma^2 360 453 361 where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)** 454 where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)** 362 455 to be defined as 363 456 … … 366 459 RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI} 367 460 368 PI values smaller than 0.05 indicate a highly monodisperse system. Values 461 PI values smaller than 0.05 indicate a highly monodisperse system. Values 369 462 greater than 0.7 indicate significant polydispersity. 370 463 371 The **size polydispersity P-parameter** is defined as the relative standard 372 deviation coefficient of variation 464 The **size polydispersity P-parameter** is defined as the relative standard 465 deviation coefficient of variation 373 466 374 467 .. math:: … … 377 470 378 471 where $\nu$ is the variance of the distribution and $\bar R$ is the mean 379 value of $R$. Here, the product $P \bar R$ is *equal* to the standard 472 value of $R$. Here, the product $P \bar R$ is *equal* to the standard 380 473 deviation of the Lognormal distribution. 381 474
Note: See TracChangeset
for help on using the changeset viewer.