Changeset 12f77e9 in sasmodels for doc/guide

Timestamp:

Oct 30, 2018 10:56:38 AM (6 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

master

Children:

4e96703

Parents:

1657e21 (diff), c6084f1 (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.

Message:

Merge branch 'master' into ticket-608-user-defined-weights

Location:

doc/guide

Files:

• magnetism/magnetism.rst (modified) (1 diff)
• plugin.rst (modified) (6 diffs)
• pd/polydispersity.rst (modified) (11 diffs)

doc/guide/magnetism/magnetism.rst

@@ -89 +89 @@
 
 ===========   ================================================================
- M0:sld       $D_M M_0$
- mtheta:sld   $\theta_M$
- mphi:sld     $\phi_M$
- up:angle     $\theta_\mathrm{up}$
- up:frac_i    $u_i$ = (spin up)/(spin up + spin down) *before* the sample
- up:frac_f    $u_f$ = (spin up)/(spin up + spin down) *after* the sample
+ sld_M0       $D_M M_0$
+ sld_mtheta   $\theta_M$
+ sld_mphi     $\phi_M$
+ up_frac_i    $u_i$ = (spin up)/(spin up + spin down) *before* the sample
+ up_frac_f    $u_f$ = (spin up)/(spin up + spin down) *after* the sample
+ up_angle     $\theta_\mathrm{up}$
 ===========   ================================================================
 
 .. note::
-    The values of the 'up:frac_i' and 'up:frac_f' must be in the range 0 to 1.
+    The values of the 'up_frac_i' and 'up_frac_f' must be in the range 0 to 1.
 
 *Document History*

doc/guide/plugin.rst

@@ -428 +428 @@
         def random():
         ...
-        
-This function provides a model-specific random parameter set which shows model 
-features in the USANS to SANS range.  For example, core-shell sphere sets the 
-outer radius of the sphere logarithmically in `[20, 20,000]`, which sets the Q 
-value for the transition from flat to falling.  It then uses a beta distribution 
-to set the percentage of the shape which is shell, giving a preference for very 
-thin or very thick shells (but never 0% or 100%).  Using `-sets=10` in sascomp 
-should show a reasonable variety of curves over the default sascomp q range.  
-The parameter set is returned as a dictionary of `{parameter: value, ...}`.  
-Any model parameters not included in the dictionary will default according to 
+
+This function provides a model-specific random parameter set which shows model
+features in the USANS to SANS range.  For example, core-shell sphere sets the
+outer radius of the sphere logarithmically in `[20, 20,000]`, which sets the Q
+value for the transition from flat to falling.  It then uses a beta distribution
+to set the percentage of the shape which is shell, giving a preference for very
+thin or very thick shells (but never 0% or 100%).  Using `-sets=10` in sascomp
+should show a reasonable variety of curves over the default sascomp q range.
+The parameter set is returned as a dictionary of `{parameter: value, ...}`.
+Any model parameters not included in the dictionary will default according to
 the code in the `_randomize_one()` function from sasmodels/compare.py.
 
@@ -701 +701 @@
     erf, erfc, tgamma, lgamma:  **do not use**
         Special functions that should be part of the standard, but are missing
-        or inaccurate on some platforms. Use sas_erf, sas_erfc and sas_gamma
-        instead (see below). Note: lgamma(x) has not yet been tested.
+        or inaccurate on some platforms. Use sas_erf, sas_erfc, sas_gamma
+        and sas_lgamma instead (see below).
 
 Some non-standard constants and functions are also provided:
@@ -769 +769 @@
         Gamma function sas_gamma\ $(x) = \Gamma(x)$.
 
-        The standard math function, tgamma(x) is unstable for $x < 1$
+        The standard math function, tgamma(x), is unstable for $x < 1$
         on some platforms.
 
         :code:`source = ["lib/sas_gamma.c", ...]`
         (`sas_gamma.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gamma.c>`_)
+
+    sas_gammaln(x):
+        log gamma function sas_gammaln\ $(x) = \log \Gamma(|x|)$.
+
+        The standard math function, lgamma(x), is incorrect for single
+        precision on some platforms.
+
+        :code:`source = ["lib/sas_gammainc.c", ...]`
+        (`sas_gammainc.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gammainc.c>`_)
+
+    sas_gammainc(a, x), sas_gammaincc(a, x):
+        Incomplete gamma function
+        sas_gammainc\ $(a, x) = \int_0^x t^{a-1}e^{-t}\,dt / \Gamma(a)$
+        and complementary incomplete gamma function
+        sas_gammaincc\ $(a, x) = \int_x^\infty t^{a-1}e^{-t}\,dt / \Gamma(a)$
+
+        :code:`source = ["lib/sas_gammainc.c", ...]`
+        (`sas_gammainc.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gammainc.c>`_)
 
     sas_erf(x), sas_erfc(x):
@@ -811 +829 @@
         If $n$ = 0 or 1, it uses sas_J0($x$) or sas_J1($x$), respectively.
 
+        Warning: JN(n,x) can be very inaccurate (0.1%) for x not in [0.1, 100].
+
         The standard math function jn(n, x) is not available on all platforms.
 
@@ -819 +839 @@
         Sine integral Si\ $(x) = \int_0^x \tfrac{\sin t}{t}\,dt$.
 
+        Warning: Si(x) can be very inaccurate (0.1%) for x in [0.1, 100].
+
         This function uses Taylor series for small and large arguments:
 
-        For large arguments,
+        For large arguments use the following Taylor series,
 
         .. math::
@@ -829 +851 @@
              - \frac{\sin(x)}{x}\left(\frac{1}{x} - \frac{3!}{x^3} + \frac{5!}{x^5} - \frac{7!}{x^7}\right)
 
-        For small arguments,
+        For small arguments ,
 
         .. math::

doc/guide/pd/polydispersity.rst

@@ -11 +11 @@
 --------------------------------------------
 
-For some models we can calculate the average intensity for a population of 
-particles that possess size and/or orientational (ie, angular) distributions. 
-In SasView we call the former *polydispersity* but use the parameter *PD* to 
-parameterise both. In other words, the meaning of *PD* in a model depends on 
+For some models we can calculate the average intensity for a population of
+particles that possess size and/or orientational (ie, angular) distributions.
+In SasView we call the former *polydispersity* but use the parameter *PD* to
+parameterise both. In other words, the meaning of *PD* in a model depends on
 the actual parameter it is being applied too.
 
-The resultant intensity is then normalized by the average particle volume such 
+The resultant intensity is then normalized by the average particle volume such
 that
 
@@ -24 +24 @@
   P(q) = \text{scale} \langle F^* F \rangle / V + \text{background}
 
-where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 
+where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an
 average over the distribution $f(x; \bar x, \sigma)$, giving
 
 .. math::
 
-  P(q) = \frac{\text{scale}}{V} \int_\mathbb{R} 
+  P(q) = \frac{\text{scale}}{V} \int_\mathbb{R}
   f(x; \bar x, \sigma) F^2(q, x)\, dx + \text{background}
 
 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 of the distribution 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.
-
-The distribution width applied to *volume* (ie, shape-describing) parameters 
-is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$. 
-However, the distribution width applied to *orientation* parameters is just 
-$\sigma = \mathrm{PD}$.
+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. The meaning of a polydispersity
+parameter *PD* (not to be confused with a molecular weight distributions
+in polymer science) in a model depends on the type of parameter it is being
+applied too.
+
+The distribution width applied to *volume* (ie, shape-describing) parameters
+is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$.
+However, the distribution width applied to *orientation* (ie, angle-describing)
+parameters is just $\sigma = \mathrm{PD}$.
 
 $N_\sigma$ determines how far into the tails to evaluate the distribution,
@@ -52 +55 @@
 
 Users should note that the averaging computation is very intensive. Applying
-polydispersion and/or orientational distributions to multiple parameters at 
-the same time, or increasing the number of points in the distribution, will 
-require patience! However, the calculations are generally more robust with 
+polydispersion and/or orientational distributions to multiple parameters at
+the same time, or increasing the number of points in the distribution, will
+require patience! However, the calculations are generally more robust with
 more data points or more angles.
 
@@ -66 +69 @@
 *  *Schulz Distribution*
 *  *Array Distribution*
+*  *User-defined Distributions*
 
 These are all implemented as *number-average* distributions.
 
-Additional distributions are under consideration.
 
 **Beware: when the Polydispersity & Orientational Distribution panel in SasView is**
@@ -75 +78 @@
 **This may not be suitable. See Suggested Applications below.**
 
-.. note:: In 2009 IUPAC decided to introduce the new term 'dispersity' to replace 
-           the term 'polydispersity' (see `Pure Appl. Chem., (2009), 81(2), 
-           351-353 <http://media.iupac.org/publications/pac/2009/pdf/8102x0351.pdf>`_ 
-           in order to make the terminology describing distributions of chemical 
-           properties unambiguous. However, these terms are unrelated to the 
-           proportional size distributions and orientational distributions used in 
+.. note:: In 2009 IUPAC decided to introduce the new term 'dispersity' to replace
+           the term 'polydispersity' (see `Pure Appl. Chem., (2009), 81(2),
+           351-353 <http://media.iupac.org/publications/pac/2009/pdf/8102x0351.pdf>`_
+           in order to make the terminology describing distributions of chemical
+           properties unambiguous. However, these terms are unrelated to the
+           proportional size distributions and orientational distributions used in
            SasView models.
 
@@ -92 +95 @@
 or angular orientations, consider using the Gaussian or Boltzmann distributions.
 
-If applying polydispersion to parameters describing angles, use the Uniform 
-distribution. Beware of using distributions that are always positive (eg, the 
+If applying polydispersion to parameters describing angles, use the Uniform
+distribution. Beware of using distributions that are always positive (eg, the
 Lognormal) because angles can be negative!
 
-The array distribution allows a user-defined distribution to be applied.
+The array distribution provides a very simple means of implementing a user-
+defined distribution, but without any fittable parameters. Greater flexibility
+is conferred by the user-defined distribution.
 
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
@@ -334 +339 @@
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
+User-defined Distributions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also define your own distribution by creating a python file defining a
+*Distribution* object with a *_weights* method.  The *_weights* method takes
+*center*, *sigma*, *lb* and *ub* as arguments, and can access *self.npts*
+and *self.nsigmas* from the distribution.  They are interpreted as follows:
+
+* *center* the value of the shape parameter (for size dispersity) or zero
+  if it is an angular dispersity.  This parameter may be fitted.
+
+* *sigma* the width of the distribution, which is the polydispersity parameter
+  times the center for size dispersity, or the polydispersity parameter alone
+  for angular dispersity.  This parameter may be fitted.
+
+* *lb*, *ub* are the parameter limits (lower & upper bounds) given in the model
+  definition file.  For example, a radius parameter has *lb* equal to zero.  A
+  volume fraction parameter would have *lb* equal to zero and *ub* equal to one.
+
+* *self.nsigmas* the distance to go into the tails when evaluating the
+  distribution.  For a two parameter distribution, this value could be
+  co-opted to use for the second parameter, though it will not be available
+  for fitting.
+
+* *self.npts* the number of points to use when evaluating the distribution.
+  The user will adjust this to trade calculation time for accuracy, but the
+  distribution code is free to return more or fewer, or use it for the third
+  parameter in a three parameter distribution.
+
+As an example, the code following wraps the Laplace distribution from scipy stats::
+
+    import numpy as np
+    from scipy.stats import laplace
+
+    from sasmodels import weights
+
+    class Dispersion(weights.Dispersion):
+        r"""
+        Laplace distribution
+
+        .. math::
+
+            w(x) = e^{-\sigma |x - \mu|}
+        """
+        type = "laplace"
+        default = dict(npts=35, width=0, nsigmas=3)  # default values
+        def _weights(self, center, sigma, lb, ub):
+            x = self._linspace(center, sigma, lb, ub)
+            wx = laplace.pdf(x, center, sigma)
+            return x, wx
+
+You can plot the weights for a given value and width using the following::
+
+    from numpy import inf
+    from matplotlib import pyplot as plt
+    from sasmodels import weights
+
+    # reload the user-defined weights
+    weights.load_weights()
+    x, wx = weights.get_weights('laplace', n=35, width=0.1, nsigmas=3, value=50,
+                                limits=[0, inf], relative=True)
+
+    # plot the weights
+    plt.interactive(True)
+    plt.plot(x, wx, 'x')
+
+The *self.nsigmas* and *self.npts* parameters are normally used to control
+the accuracy of the distribution integral. The *self._linspace* function
+uses them to define the *x* values (along with the *center*, *sigma*,
+*lb*, and *ub* which are passed as parameters).  If you repurpose npts or
+nsigmas you will need to generate your own *x*.  Be sure to honour the
+limits *lb* and *ub*, for example to disallow a negative radius or constrain
+the volume fraction to lie between zero and one.
+
+To activate a user-defined distribution, put it in a file such as *distname.py*
+in the *SAS_WEIGHTS_PATH* folder.  This is defined with an environment
+variable, defaulting to::
+
+    SAS_WEIGHTS_PATH=~/.sasview/weights
+
+The weights path is loaded on startup.  To update the distribution definition
+in a running application you will need to enter the following python commands::
+
+    import sasmodels.weights
+    sasmodels.weights.load_weights('path/to/distname.py')
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
 Note about DLS polydispersity
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and 
-it should not be assumed that any of the following can be simply equated with 
+Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and
+it should not be assumed that any of the following can be simply equated with
 the polydispersity *PD* parameter used in SasView.
 
-The dimensionless **Polydispersity Index (PI)** is a measure of the width of the 
-distribution of autocorrelation function decay rates (*not* the distribution of 
-particle sizes itself, though the two are inversely related) and is defined by 
+The dimensionless **Polydispersity Index (PI)** is a measure of the width of the
+distribution of autocorrelation function decay rates (*not* the distribution of
+particle sizes itself, though the two are inversely related) and is defined by
 ISO 22412:2017 as
 
@@ -350 +443 @@
     PI = \mu_{2} / \bar \Gamma^2
 
-where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the 
+where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the
 intensity-weighted average value, of the distribution of decay rates.
 
@@ -359 +452 @@
     PI = \sigma^2 / 2\bar \Gamma^2
 
-where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)** 
+where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)**
 to be defined as
 
@@ -366 +459 @@
     RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI}
 
-PI values smaller than 0.05 indicate a highly monodisperse system. Values 
+PI values smaller than 0.05 indicate a highly monodisperse system. Values
 greater than 0.7 indicate significant polydispersity.
 
-The **size polydispersity P-parameter** is defined as the relative standard 
-deviation coefficient of variation  
+The **size polydispersity P-parameter** is defined as the relative standard
+deviation coefficient of variation
 
 .. math::
@@ -377 +470 @@
 
 where $\nu$ is the variance of the distribution and $\bar R$ is the mean
-value of $R$. Here, the product $P \bar R$ is *equal* to the standard 
+value of $R$. Here, the product $P \bar R$ is *equal* to the standard
 deviation of the Lognormal distribution.