Changeset afe206d in sasmodels for doc

Timestamp:

Sep 25, 2018 9:41:04 AM (6 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests

Children:

ce1eed5

Parents:

12eec1e (diff), 2015f02 (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-1142-plugin-reload

Location:

doc

Files:

• guide/pd/polydispersity.rst (modified) (7 diffs)
• guide/plugin.rst (modified) (1 diff)
• guide/scripting.rst (modified) (2 diffs)
• rst_prolog (modified) (1 diff)

doc/guide/pd/polydispersity.rst

@@ -8 +8 @@
 .. _polydispersityhelp:
 
-Polydispersity Distributions
-----------------------------
-
-With some models in sasmodels we can calculate the average intensity for a
-population of particles that exhibit size and/or orientational
-polydispersity. The resultant intensity is normalized by the average
-particle volume such that
+Polydispersity & Orientational Distributions
+--------------------------------------------
+
+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 
+that
 
 .. math::
@@ -21 +25 @@
 
 where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 
-average over the size distribution $f(x; \bar x, \sigma)$, giving
+average over the distribution $f(x; \bar x, \sigma)$, giving
 
 .. math::
@@ -30 +34 @@
 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 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 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* (ie, angle-describing) 
-parameters is just $\sigma = \mathrm{PD}$.
+However, the distribution width applied to *orientation* parameters is just 
+$\sigma = \mathrm{PD}$.
 
 $N_\sigma$ determines how far into the tails to evaluate the distribution,
@@ -51 +52 @@
 
 Users should note that the averaging computation is very intensive. Applying
-polydispersion 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.
+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.
 
 The following distribution functions are provided:
@@ -69 +71 @@
 Additional distributions are under consideration.
 
+**Beware: when the Polydispersity & Orientational Distribution panel in SasView is**
+**first opened, the default distribution for all parameters is the Gaussian Distribution.**
+**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 properties 
-           unambiguous. Throughout the SasView documentation we continue to use the 
-           term polydispersity because one of the consequences of the IUPAC change is 
-           that orientational polydispersity would not meet their new criteria (which 
-           requires dispersity to be dimensionless).
+           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.
 
 Suggested Applications
 ^^^^^^^^^^^^^^^^^^^^^^
 
-If applying polydispersion to parameters describing particle sizes, use
+If applying polydispersion to parameters describing particle sizes, consider using
 the Lognormal or Schulz distributions.
 
 If applying polydispersion to parameters describing interfacial thicknesses
-or angular orientations, use the Gaussian or Boltzmann distributions.
+or angular orientations, consider using the Gaussian or Boltzmann distributions.
 
 If applying polydispersion to parameters describing angles, use the Uniform 
@@ -332 +337 @@
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Many commercial Dynamic Light Scattering (DLS) instruments produce a size
-polydispersity parameter, sometimes even given the symbol $p$\ ! This
-parameter is defined as the relative standard deviation coefficient of
-variation of the size distribution and is NOT the same as the polydispersity
-parameters in the Lognormal and Schulz distributions above (though they all
-related) except when the DLS polydispersity parameter is <0.13.
-
-.. math::
-
-    p_{DLS} = \sqrt(\nu / \bar x^2)
-
-where $\nu$ is the variance of the distribution and $\bar x$ is the mean
-value of $x$.
+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 
+ISO 22412:2017 as
+
+.. math::
+
+    PI = \mu_{2} / \bar \Gamma^2
+
+where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the 
+intensity-weighted average value, of the distribution of decay rates.
+
+*If the distribution of decay rates is Gaussian* then
+
+.. math::
+
+    PI = \sigma^2 / 2\bar \Gamma^2
+
+where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)** 
+to be defined as
+
+.. math::
+
+    RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI}
+
+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  
+
+.. math::
+
+    P = \sqrt\nu / \bar R
+
+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 
+deviation of the Lognormal distribution.
+
+P values smaller than 0.13 indicate a monodisperse system.
 
 For more information see:
-S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143
+
+`ISO 22412:2017, International Standards Organisation (2017) <https://www.iso.org/standard/65410.html>`_.
+
+`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/>`_.
+
+`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>`_.
+
+S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143.
+
+T Allen, in *Particle Size Measurement*, 4th Edition, Chapman & Hall, London (1990).
 
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
@@ -357 +402 @@
 | 2018-03-20 Steve King
 | 2018-04-04 Steve King
+| 2018-08-09 Steve King

doc/guide/plugin.rst

@@ -423 +423 @@
 calculations, but instead rely on numerical integration to compute the
 appropriately smeared pattern.
+
+Each .py file also contains a function::
+
+        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 
+the code in the `_randomize_one()` function from sasmodels/compare.py.
 
 Python Models

doc/guide/scripting.rst

@@ -10 +10 @@
 The key functions are :func:`sasmodels.core.load_model` for loading the
 model definition and compiling the kernel and
-:func:`sasmodels.data.load_data` for calling sasview to load the data. Need
-the data because that defines the resolution function and the q values to
-evaluate. If there is no data, then use :func:`sasmodels.data.empty_data1D`
-or :func:`sasmodels.data.empty_data2D` to create some data with a given $q$.
-
-Using sasmodels through bumps
-=============================
-
-With the data and the model, you can wrap it in a *bumps* model with
+:func:`sasmodels.data.load_data` for calling sasview to load the data.
+
+Preparing data
+==============
+
+Usually you will load data via the sasview loader, with the
+:func:`sasmodels.data.load_data` function.  For example::
+
+    from sasmodels.data import load_data
+    data = load_data("sasmodels/example/093191_201.dat")
+
+You may want to apply a data mask, such a beam stop, and trim high $q$::
+
+    from sasmodels.data import set_beam_stop
+    set_beam_stop(data, qmin, qmax)
+
+The :func:`sasmodels.data.set_beam_stop` method simply sets the *mask*
+attribute for the data.
+
+The data defines the resolution function and the q values to evaluate, so
+even if you simulating experiments prior to making measurements, you still
+need a data object for reference. Use :func:`sasmodels.data.empty_data1D`
+or :func:`sasmodels.data.empty_data2D` to create a container with a
+given $q$ and $\Delta q/q$.  For example::
+
+    import numpy as np
+    from sasmodels.data import empty_data1D
+
+    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5%
+    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120)
+    data = empty_data1D(q, resolution=0.05)
+
+To use a more realistic model of resolution, or to load data from a file
+format not understood by SasView, you can use :class:`sasmodels.data.Data1D`
+or :class:`sasmodels.data.Data2D` directly.  The 1D data uses
+*x*, *y*, *dx* and *dy* for $x = q$ and $y = I(q)$, and 2D data uses
+*x*, *y*, *z*, *dx*, *dy*, *dz* for $x, y = qx, qy$ and $z = I(qx, qy)$.
+[Note: internally, the Data2D object uses SasView conventions,
+*qx_data*, *qy_data*, *data*, *dqx_data*, *dqy_data*, and *err_data*.]
+
+For USANS data, use 1D data, but set *dxl* and *dxw* attributes to
+indicate slit resolution::
+
+    data.dxl = 0.117
+
+See :func:`sasmodels.resolution.slit_resolution` for details.
+
+SESANS data is more complicated; if your SESANS format is not supported by
+SasView you need to define a number of attributes beyond *x*, *y*.  For
+example::
+
+    SElength = np.linspace(0, 2400, 61) # [A]
+    data = np.ones_like(SElength)
+    err_data = np.ones_like(SElength)*0.03
+
+    class Source:
+        wavelength = 6 # [A]
+        wavelength_unit = "A"
+    class Sample:
+        zacceptance = 0.1 # [A^-1]
+        thickness = 0.2 # [cm]
+
+    class SESANSData1D:
+        #q_zmax = 0.23 # [A^-1]
+        lam = 0.2 # [nm]
+        x = SElength
+        y = data
+        dy = err_data
+        sample = Sample()
+    data = SESANSData1D()
+
+    x, y = ... # create or load sesans
+    data = smd.Data
+
+The *data* module defines various data plotters as well.
+
+Using sasmodels directly
+========================
+
+Once you have a computational kernel and a data object, you can evaluate
+the model for various parameters using
+:class:`sasmodels.direct_model.DirectModel`.  The resulting object *f*
+will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$
+values in the data.  For example::
+
+    import numpy as np
+    from sasmodels.data import empty_data1D
+    from sasmodels.core import load_model
+    from sasmodels.direct_model import DirectModel
+
+    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5%
+    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120)
+    data = empty_data1D(q, resolution=0.05)
+    kernel = load_model("ellipsoid)
+    f = DirectModel(data, kernel)
+    Iq = f(radius_polar=100)
+
+Polydispersity information is set with special parameter names:
+
+    * *par_pd* for polydispersity width, $\Delta p/p$,
+    * *par_pd_n* for the number of points in the distribution,
+    * *par_pd_type* for the distribution type (as a string), and
+    * *par_pd_nsigmas* for the limits of the distribution.
+
+Using sasmodels through the bumps optimizer
+===========================================
+
+Like DirectModel, you can wrap data and a kernel in a *bumps* model with
 class:`sasmodels.bumps_model.Model` and create an
-class:`sasmodels.bump_model.Experiment` that you can fit with the *bumps*
+class:`sasmodels.bumps_model.Experiment` that you can fit with the *bumps*
 interface. Here is an example from the *example* directory such as
 *example/model.py*::
@@ -75 +174 @@
     SasViewCom bumps.cli example/model.py --preview
 
-Using sasmodels directly
-========================
-
-Bumps has a notion of parameter boxes in which you can set and retrieve
-values.  Instead of using bumps, you can create a directly callable function
-with :class:`sasmodels.direct_model.DirectModel`.  The resulting object *f*
-will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$
-values in the data.  Polydisperse parameters use the same naming conventions
-as in the bumps model, with e.g., radius_pd being the polydispersity associated
-with radius.
+Calling the computation kernel
+==============================
 
 Getting a simple function that you can call on a set of q values and return

doc/rst_prolog

@@ -9 +9 @@
 .. |Ang^-3| replace:: |Ang|\ :sup:`-3`
 .. |Ang^-4| replace:: |Ang|\ :sup:`-4`
+.. |nm^-1| replace:: nm\ :sup:`-1`
 .. |cm^-1| replace:: cm\ :sup:`-1`
 .. |cm^2| replace:: cm\ :sup:`2`