Changeset 01dba26 in sasmodels for doc/guide


Ignore:
Timestamp:
Sep 12, 2018 5:17:58 PM (6 years ago)
Author:
Paul Kienzle <pkienzle@…>
Branches:
master
Children:
a5cb9bc
Parents:
55e82f0 (diff), 2c12061 (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:
3 edited

Legend:

Unmodified
Added
Removed

  • doc/guide/gpu_setup.rst

    r59485a4 r63602b1  
    139139the compiler. 
    140140 
    141 On Windows, set *SASCOMPILER=tinycc* for the tinycc compiler, 
    142 *SASCOMPILER=msvc* for the Microsoft Visual C compiler, 
    143 or *SASCOMPILER=mingw* for the MinGW compiler. If TinyCC is available 
     141On Windows, set *SAS_COMPILER=tinycc* for the tinycc compiler, 
     142*SAS_COMPILER=msvc* for the Microsoft Visual C compiler, 
     143or *SAS_COMPILER=mingw* for the MinGW compiler. If TinyCC is available 
    144144on the python path (it is provided with SasView), that will be the 
    145145default. If you want one of the other compilers, be sure to have it 

  • doc/guide/pd/polydispersity.rst

    rf41027b r01dba26  
    88.. _polydispersityhelp: 
    99 
    10 Polydispersity Distributions 
    11 ---------------------------- 
    12  
    13 With some models in sasmodels we can calculate the average intensity for a 
    14 population of particles that exhibit size and/or orientational 
    15 polydispersity. The resultant intensity is normalized by the average 
    16 particle volume such that 
     10Polydispersity & Orientational Distributions 
     11-------------------------------------------- 
     12 
     13For some models we can calculate the average intensity for a population of  
     14particles that possess size and/or orientational (ie, angular) distributions.  
     15In SasView we call the former *polydispersity* but use the parameter *PD* to  
     16parameterise both. In other words, the meaning of *PD* in a model depends on  
     17the actual parameter it is being applied too. 
     18 
     19The resultant intensity is then normalized by the average particle volume such  
     20that 
    1721 
    1822.. math:: 
    … …  
    2125 
    2226where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an  
    23 average over the size distribution $f(x; \bar x, \sigma)$, giving 
     27average over the distribution $f(x; \bar x, \sigma)$, giving 
    2428 
    2529.. math:: 
    … …  
    3034Each distribution is characterized by a center value $\bar x$ or 
    3135$x_\text{med}$, a width parameter $\sigma$ (note this is *not necessarily* 
     36<<<<<<< HEAD 
    3237the standard deviation, so read the description carefully), the number of 
    3338sigmas $N_\sigma$ to include from the tails of the distribution, and the 
    … …  
    4247However, the distribution width applied to *orientation* (ie, angle-describing) 
    4348parameters is just $\sigma = \mathrm{PD}$. 
     49======= 
     50the standard deviation, so read the description of the distribution carefully),  
     51the number of sigmas $N_\sigma$ to include from the tails of the distribution,  
     52and the number of points used to compute the average. The center of the  
     53distribution is set by the value of the model parameter. 
     54 
     55The distribution width applied to *volume* (ie, shape-describing) parameters  
     56is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$.  
     57However, the distribution width applied to *orientation* parameters is just  
     58$\sigma = \mathrm{PD}$. 
     59>>>>>>> master 
    4460 
    4561$N_\sigma$ determines how far into the tails to evaluate the distribution, 
    … …  
    5167 
    5268Users should note that the averaging computation is very intensive. Applying 
    53 polydispersion to multiple parameters at the same time or increasing the 
    54 number of points in the distribution will require patience! However, the 
    55 calculations are generally more robust with more data points or more angles. 
     69polydispersion and/or orientational distributions to multiple parameters at  
     70the same time, or increasing the number of points in the distribution, will  
     71require patience! However, the calculations are generally more robust with  
     72more data points or more angles. 
    5673 
    5774The following distribution functions are provided: 
    … …  
    6986 
    7087 
     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 
    7192.. note:: In 2009 IUPAC decided to introduce the new term 'dispersity' to replace  
    7293           the term 'polydispersity' (see `Pure Appl. Chem., (2009), 81(2),  
    7394           351-353 <http://media.iupac.org/publications/pac/2009/pdf/8102x0351.pdf>`_  
    74            in order to make the terminology describing distributions of properties  
    75            unambiguous. Throughout the SasView documentation we continue to use the  
    76            term polydispersity because one of the consequences of the IUPAC change is  
    77            that orientational polydispersity would not meet their new criteria (which  
    78            requires dispersity to be dimensionless). 
     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. 
    7999 
    80100Suggested Applications 
    81101^^^^^^^^^^^^^^^^^^^^^^ 
    82102 
    83 If applying polydispersion to parameters describing particle sizes, use 
     103If applying polydispersion to parameters describing particle sizes, consider using 
    84104the Lognormal or Schulz distributions. 
    85105 
    86106If applying polydispersion to parameters describing interfacial thicknesses 
    87 or angular orientations, use the Gaussian or Boltzmann distributions. 
     107or angular orientations, consider using the Gaussian or Boltzmann distributions. 
    88108 
    89109If applying polydispersion to parameters describing angles, use the Uniform 
    … …  
    422442^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    423443 
    424 Many commercial Dynamic Light Scattering (DLS) instruments produce a size 
    425 polydispersity parameter, sometimes even given the symbol $p$\ ! This 
    426 parameter is defined as the relative standard deviation coefficient of 
    427 variation of the size distribution and is NOT the same as the polydispersity 
    428 parameters in the Lognormal and Schulz distributions above (though they all 
    429 related) except when the DLS polydispersity parameter is <0.13. 
    430  
    431 .. math:: 
    432  
    433     p_{DLS} = \sqrt(\nu / \bar x^2) 
    434  
    435 where $\nu$ is the variance of the distribution and $\bar x$ is the mean 
    436 value of $x$. 
     444Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and  
     445it should not be assumed that any of the following can be simply equated with  
     446the polydispersity *PD* parameter used in SasView. 
     447 
     448The dimensionless **Polydispersity Index (PI)** is a measure of the width of the  
     449distribution of autocorrelation function decay rates (*not* the distribution of  
     450particle sizes itself, though the two are inversely related) and is defined by  
     451ISO 22412:2017 as 
     452 
     453.. math:: 
     454 
     455    PI = \mu_{2} / \bar \Gamma^2 
     456 
     457where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the  
     458intensity-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 
     466where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)**  
     467to be defined as 
     468 
     469.. math:: 
     470 
     471    RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI} 
     472 
     473PI values smaller than 0.05 indicate a highly monodisperse system. Values  
     474greater than 0.7 indicate significant polydispersity. 
     475 
     476The **size polydispersity P-parameter** is defined as the relative standard  
     477deviation coefficient of variation   
     478 
     479.. math:: 
     480 
     481    P = \sqrt\nu / \bar R 
     482 
     483where $\nu$ is the variance of the distribution and $\bar R$ is the mean 
     484value of $R$. Here, the product $P \bar R$ is *equal* to the standard  
     485deviation of the Lognormal distribution. 
     486 
     487P values smaller than 0.13 indicate a monodisperse system. 
    437488 
    438489For more information see: 
    439 S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143 
     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 
     497S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143. 
     498 
     499T Allen, in *Particle Size Measurement*, 4th Edition, Chapman & Hall, London (1990). 
    440500 
    441501.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    447507| 2018-03-20 Steve King 
    448508| 2018-04-04 Steve King 
     509| 2018-08-09 Steve King 

  • doc/guide/scripting.rst

    r4aa5dce rbd7630d  
    1010The key functions are :func:`sasmodels.core.load_model` for loading the 
    1111model definition and compiling the kernel and 
    12 :func:`sasmodels.data.load_data` for calling sasview to load the data. Need 
    13 the data because that defines the resolution function and the q values to 
    14 evaluate. If there is no data, then use :func:`sasmodels.data.empty_data1D` 
    15 or :func:`sasmodels.data.empty_data2D` to create some data with a given $q$. 
    16  
    17 Using sasmodels through bumps 
    18 ============================= 
    19  
    20 With the data and the model, you can wrap it in a *bumps* model with 
     12:func:`sasmodels.data.load_data` for calling sasview to load the data. 
     13 
     14Preparing data 
     15============== 
     16 
     17Usually you will load data via the sasview loader, with the 
     18:func:`sasmodels.data.load_data` function.  For example:: 
     19 
     20    from sasmodels.data import load_data 
     21    data = load_data("sasmodels/example/093191_201.dat") 
     22 
     23You may want to apply a data mask, such a beam stop, and trim high $q$:: 
     24 
     25    from sasmodels.data import set_beam_stop 
     26    set_beam_stop(data, qmin, qmax) 
     27 
     28The :func:`sasmodels.data.set_beam_stop` method simply sets the *mask* 
     29attribute for the data. 
     30 
     31The data defines the resolution function and the q values to evaluate, so 
     32even if you simulating experiments prior to making measurements, you still 
     33need a data object for reference. Use :func:`sasmodels.data.empty_data1D` 
     34or :func:`sasmodels.data.empty_data2D` to create a container with a 
     35given $q$ and $\Delta q/q$.  For example:: 
     36 
     37    import numpy as np 
     38    from sasmodels.data import empty_data1D 
     39 
     40    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5% 
     41    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120) 
     42    data = empty_data1D(q, resolution=0.05) 
     43 
     44To use a more realistic model of resolution, or to load data from a file 
     45format not understood by SasView, you can use :class:`sasmodels.data.Data1D` 
     46or :class:`sasmodels.data.Data2D` directly.  The 1D data uses 
     47*x*, *y*, *dx* and *dy* for $x = q$ and $y = I(q)$, and 2D data uses 
     48*x*, *y*, *z*, *dx*, *dy*, *dz* for $x, y = qx, qy$ and $z = I(qx, qy)$. 
     49[Note: internally, the Data2D object uses SasView conventions, 
     50*qx_data*, *qy_data*, *data*, *dqx_data*, *dqy_data*, and *err_data*.] 
     51 
     52For USANS data, use 1D data, but set *dxl* and *dxw* attributes to 
     53indicate slit resolution:: 
     54 
     55    data.dxl = 0.117 
     56 
     57See :func:`sasmodels.resolution.slit_resolution` for details. 
     58 
     59SESANS data is more complicated; if your SESANS format is not supported by 
     60SasView you need to define a number of attributes beyond *x*, *y*.  For 
     61example:: 
     62 
     63    SElength = np.linspace(0, 2400, 61) # [A] 
     64    data = np.ones_like(SElength) 
     65    err_data = np.ones_like(SElength)*0.03 
     66 
     67    class Source: 
     68        wavelength = 6 # [A] 
     69        wavelength_unit = "A" 
     70    class Sample: 
     71        zacceptance = 0.1 # [A^-1] 
     72        thickness = 0.2 # [cm] 
     73 
     74    class SESANSData1D: 
     75        #q_zmax = 0.23 # [A^-1] 
     76        lam = 0.2 # [nm] 
     77        x = SElength 
     78        y = data 
     79        dy = err_data 
     80        sample = Sample() 
     81    data = SESANSData1D() 
     82 
     83    x, y = ... # create or load sesans 
     84    data = smd.Data 
     85 
     86The *data* module defines various data plotters as well. 
     87 
     88Using sasmodels directly 
     89======================== 
     90 
     91Once you have a computational kernel and a data object, you can evaluate 
     92the model for various parameters using 
     93:class:`sasmodels.direct_model.DirectModel`.  The resulting object *f* 
     94will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$ 
     95values in the data.  For example:: 
     96 
     97    import numpy as np 
     98    from sasmodels.data import empty_data1D 
     99    from sasmodels.core import load_model 
     100    from sasmodels.direct_model import DirectModel 
     101 
     102    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5% 
     103    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120) 
     104    data = empty_data1D(q, resolution=0.05) 
     105    kernel = load_model("ellipsoid) 
     106    f = DirectModel(data, kernel) 
     107    Iq = f(radius_polar=100) 
     108 
     109Polydispersity information is set with special parameter names: 
     110 
     111    * *par_pd* for polydispersity width, $\Delta p/p$, 
     112    * *par_pd_n* for the number of points in the distribution, 
     113    * *par_pd_type* for the distribution type (as a string), and 
     114    * *par_pd_nsigmas* for the limits of the distribution. 
     115 
     116Using sasmodels through the bumps optimizer 
     117=========================================== 
     118 
     119Like DirectModel, you can wrap data and a kernel in a *bumps* model with 
    21120class:`sasmodels.bumps_model.Model` and create an 
    22 class:`sasmodels.bump_model.Experiment` that you can fit with the *bumps* 
     121class:`sasmodels.bumps_model.Experiment` that you can fit with the *bumps* 
    23122interface. Here is an example from the *example* directory such as 
    24123*example/model.py*:: 
    … …  
    75174    SasViewCom bumps.cli example/model.py --preview 
    76175 
    77 Using sasmodels directly 
    78 ======================== 
    79  
    80 Bumps has a notion of parameter boxes in which you can set and retrieve 
    81 values.  Instead of using bumps, you can create a directly callable function 
    82 with :class:`sasmodels.direct_model.DirectModel`.  The resulting object *f* 
    83 will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$ 
    84 values in the data.  Polydisperse parameters use the same naming conventions 
    85 as in the bumps model, with e.g., radius_pd being the polydispersity associated 
    86 with radius. 
     176Calling the computation kernel 
     177============================== 
    87178 
    88179Getting a simple function that you can call on a set of q values and return 
Note: See TracChangeset for help on using the changeset viewer.