Changeset 47fb816 in sasmodels for doc


Ignore:
Timestamp:
Oct 12, 2018 5:44:26 PM (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:
b0de252
Parents:
0db7dbd (diff), 353e899 (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 cuda-test

Location:
doc
Files:
6 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/magnetism/magnetism.rst

    r4f5afc9 rbefe905  
    3939 
    4040.. math:: 
    41     -- &= ((1-u_i)(1-u_f))^{1/4} \\ 
    42     -+ &= ((1-u_i)(u_f))^{1/4} \\ 
    43     +- &= ((u_i)(1-u_f))^{1/4} \\ 
    44     ++ &= ((u_i)(u_f))^{1/4} 
     41    -- &= (1-u_i)(1-u_f) \\ 
     42    -+ &= (1-u_i)(u_f) \\ 
     43    +- &= (u_i)(1-u_f) \\ 
     44    ++ &= (u_i)(u_f) 
    4545 
    4646Ideally the experiment would measure the pure spin states independently and 
    … …  
    104104| 2015-05-02 Steve King 
    105105| 2017-11-15 Paul Kienzle 
     106| 2018-06-02 Adam Washington 

  • doc/guide/pd/polydispersity.rst

    r92d330fd rd089a00  
    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:: 
    … …  
    2024  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background} 
    2125 
    22 where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 
    23 average over the size distribution. 
    24  
    25 Each distribution is characterized by its center $\bar x$, its width $\sigma$, 
    26 the number of sigmas $N_\sigma$ to include from the tails, and the number of 
    27 points used to compute the average. The center of the distribution is set by the 
    28 value of the model parameter.  Volume parameters have polydispersity *PD* 
    29 (not to be confused with a molecular weight distributions in polymer science) 
    30 leading to a size distribution of width $\text{PD} = \sigma / \bar x$, but 
    31 orientation parameters use an angular distributions of width $\sigma$. 
    32 $N_\sigma$ determines how far into the tails to evaluate the distribution, with 
    33 larger values of $N_\sigma$ required for heavier tailed distributions. 
     26where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an  
     27average over the distribution $f(x; \bar x, \sigma)$, giving 
     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} 
     33 
     34Each distribution is characterized by a center value $\bar x$ or 
     35$x_\text{med}$, a width parameter $\sigma$ (note this is *not necessarily* 
     36the standard deviation, so read the description of the distribution carefully),  
     37the number of sigmas $N_\sigma$ to include from the tails of the distribution,  
     38and the number of points used to compute the average. The center of the  
     39distribution is set by the value of the model parameter. 
     40 
     41The distribution width applied to *volume* (ie, shape-describing) parameters  
     42is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$.  
     43However, the distribution width applied to *orientation* parameters is just  
     44$\sigma = \mathrm{PD}$. 
     45 
     46$N_\sigma$ determines how far into the tails to evaluate the distribution, 
     47with larger values of $N_\sigma$ required for heavier tailed distributions. 
    3448The scattering in general falls rapidly with $qr$ so the usual assumption 
    35 that $G(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)G(r - 3\sigma_r)$ 
     49that $f(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)f(r - 3\sigma_r)$ 
    3650will not contribute much to the average may not hold when particles are large. 
    3751This, too, will require increasing $N_\sigma$. 
    3852 
    3953Users should note that the averaging computation is very intensive. Applying 
    40 polydispersion to multiple parameters at the same time or increasing the 
    41 number of points in the distribution will require patience! However, the 
    42 calculations are generally more robust with more data points or more angles. 
     54polydispersion and/or orientational distributions to multiple parameters at  
     55the same time, or increasing the number of points in the distribution, will  
     56require patience! However, the calculations are generally more robust with  
     57more data points or more angles. 
    4358 
    4459The following distribution functions are provided: 
    4560 
     61*  *Uniform Distribution* 
    4662*  *Rectangular Distribution* 
    47 *  *Uniform Distribution* 
    4863*  *Gaussian Distribution* 
     64*  *Boltzmann Distribution* 
    4965*  *Lognormal Distribution* 
    5066*  *Schulz Distribution* 
    5167*  *Array Distribution* 
    52 *  *Boltzmann Distribution* 
    5368 
    5469These are all implemented as *number-average* distributions. 
     70 
     71Additional distributions are under consideration. 
     72 
     73**Beware: when the Polydispersity & Orientational Distribution panel in SasView is** 
     74**first opened, the default distribution for all parameters is the Gaussian Distribution.** 
     75**This may not be suitable. See Suggested Applications below.** 
     76 
     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  
     83           SasView models. 
     84 
     85Suggested Applications 
     86^^^^^^^^^^^^^^^^^^^^^^ 
     87 
     88If applying polydispersion to parameters describing particle sizes, consider using 
     89the Lognormal or Schulz distributions. 
     90 
     91If applying polydispersion to parameters describing interfacial thicknesses 
     92or angular orientations, consider using the Gaussian or Boltzmann distributions. 
     93 
     94If applying polydispersion to parameters describing angles, use the Uniform  
     95distribution. Beware of using distributions that are always positive (eg, the  
     96Lognormal) because angles can be negative! 
     97 
     98The array distribution allows a user-defined distribution to be applied. 
     99 
     100.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     101 
     102Uniform Distribution 
     103^^^^^^^^^^^^^^^^^^^^ 
     104 
     105The Uniform Distribution is defined as 
     106 
     107.. math:: 
     108 
     109    f(x) = \frac{1}{\text{Norm}} 
     110    \begin{cases} 
     111        1 & \text{for } |x - \bar x| \leq \sigma \\ 
     112        0 & \text{for } |x - \bar x| > \sigma 
     113    \end{cases} 
     114 
     115where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the 
     116distribution, $\sigma$ is the half-width, and *Norm* is a normalization 
     117factor which is determined during the numerical calculation. 
     118 
     119The polydispersity in sasmodels is given by 
     120 
     121.. math:: \text{PD} = \sigma / \bar x 
     122 
     123.. figure:: pd_uniform.jpg 
     124 
     125    Uniform distribution. 
     126 
     127The value $N_\sigma$ is ignored for this distribution. 
    55128 
    56129.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    65138    f(x) = \frac{1}{\text{Norm}} 
    66139    \begin{cases} 
    67       1 & \text{for } |x - \bar x| \leq w \\ 
    68       0 & \text{for } |x - \bar x| > w 
     140        1 & \text{for } |x - \bar x| \leq w \\ 
     141        0 & \text{for } |x - \bar x| > w 
    69142    \end{cases} 
    70143 
    71 where $\bar x$ is the mean of the distribution, $w$ is the half-width, and 
    72 *Norm* is a normalization factor which is determined during the numerical 
    73 calculation. 
     144where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the 
     145distribution, $w$ is the half-width, and *Norm* is a normalization 
     146factor which is determined during the numerical calculation. 
    74147 
    75148Note that the standard deviation and the half width $w$ are different! 
    … …  
    79152.. math:: \sigma = w / \sqrt{3} 
    80153 
    81 whilst the polydispersity is 
     154whilst the polydispersity in sasmodels is given by 
    82155 
    83156.. math:: \text{PD} = \sigma / \bar x 
    … …  
    87160    Rectangular distribution. 
    88161 
    89  
    90  
    91 Uniform Distribution 
    92 ^^^^^^^^^^^^^^^^^^^^^^^^ 
    93  
    94 The Uniform Distribution is defined as 
    95  
    96     .. math:: 
    97  
    98         f(x) = \frac{1}{\text{Norm}} 
    99         \begin{cases} 
    100           1 & \text{for } |x - \bar x| \leq \sigma \\ 
    101           0 & \text{for } |x - \bar x| > \sigma 
    102         \end{cases} 
    103  
    104     where $\bar x$ is the mean of the distribution, $\sigma$ is the half-width, and 
    105     *Norm* is a normalization factor which is determined during the numerical 
    106     calculation. 
    107  
    108     Note that the polydispersity is given by 
    109  
    110     .. math:: \text{PD} = \sigma / \bar x 
    111  
    112     .. figure:: pd_uniform.jpg 
    113  
    114         Uniform distribution. 
    115  
    116 The value $N_\sigma$ is ignored for this distribution. 
     162.. note:: The Rectangular Distribution is deprecated in favour of the 
     163            Uniform Distribution above and is described here for backwards 
     164            compatibility with earlier versions of SasView only. 
    117165 
    118166.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    126174 
    127175    f(x) = \frac{1}{\text{Norm}} 
    128            \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) 
    129  
    130 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    131 factor which is determined during the numerical calculation. 
    132  
    133 The polydispersity is 
     176            \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right) 
     177 
     178where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the 
     179distribution and *Norm* is a normalization factor which is determined 
     180during the numerical calculation. 
     181 
     182The polydispersity in sasmodels is given by 
    134183 
    135184.. math:: \text{PD} = \sigma / \bar x 
    … …  
    138187 
    139188    Normal distribution. 
     189 
     190.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     191 
     192Boltzmann Distribution 
     193^^^^^^^^^^^^^^^^^^^^^^ 
     194 
     195The Boltzmann Distribution is defined as 
     196 
     197.. math:: 
     198 
     199    f(x) = \frac{1}{\text{Norm}} 
     200            \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) 
     201 
     202where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the 
     203distribution and *Norm* is a normalization factor which is determined 
     204during the numerical calculation. 
     205 
     206The width is defined as 
     207 
     208.. math:: \sigma=\frac{k T}{E} 
     209 
     210which is the inverse Boltzmann factor, where $k$ is the Boltzmann constant, 
     211$T$ the temperature in Kelvin and $E$ a characteristic energy per particle. 
     212 
     213.. figure:: pd_boltzmann.jpg 
     214 
     215    Boltzmann distribution. 
    140216 
    141217.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    144220^^^^^^^^^^^^^^^^^^^^^^ 
    145221 
     222The Lognormal Distribution describes a function of $x$ where $\ln (x)$ has 
     223a normal distribution. The result is a distribution that is skewed towards 
     224larger values of $x$. 
     225 
    146226The Lognormal Distribution is defined as 
    147227 
    148228.. math:: 
    149229 
    150     f(x) = \frac{1}{\text{Norm}} 
    151            \frac{1}{xp}\exp\left(-\frac{(\ln(x) - \mu)^2}{2p^2}\right) 
    152  
    153 where $\mu=\ln(x_\text{med})$ when $x_\text{med}$ is the median value of the 
    154 distribution, and *Norm* is a normalization factor which will be determined 
    155 during the numerical calculation. 
    156  
    157 The median value for the distribution will be the value given for the 
    158 respective size parameter, for example, *radius=60*. 
    159  
    160 The polydispersity is given by $\sigma$ 
    161  
    162 .. math:: \text{PD} = p 
    163  
    164 For the angular distribution 
    165  
    166 .. math:: p = \sigma / x_\text{med} 
    167  
    168 The mean value is given by $\bar x = \exp(\mu+ p^2/2)$. The peak value 
    169 is given by $\max x = \exp(\mu - p^2)$. 
     230    f(x) = \frac{1}{\text{Norm}}\frac{1}{x\sigma} 
     231            \exp\left(-\frac{1}{2} 
     232                        \bigg(\frac{\ln(x) - \mu}{\sigma}\bigg)^2\right) 
     233 
     234where *Norm* is a normalization factor which will be determined during 
     235the numerical calculation, $\mu=\ln(x_\text{med})$ and $x_\text{med}$ 
     236is the *median* value of the *lognormal* distribution, but $\sigma$ is 
     237a parameter describing the width of the underlying *normal* distribution. 
     238 
     239$x_\text{med}$ will be the value given for the respective size parameter 
     240in sasmodels, for example, *radius=60*. 
     241 
     242The polydispersity in sasmodels is given by 
     243 
     244.. math:: \text{PD} = \sigma = p / x_\text{med} 
     245 
     246The mean value of the distribution is given by $\bar x = \exp(\mu+ \sigma^2/2)$ 
     247and the peak value by $\max x = \exp(\mu - \sigma^2)$. 
     248 
     249The variance (the square of the standard deviation) of the *lognormal* 
     250distribution is given by 
     251 
     252.. math:: 
     253 
     254    \nu = [\exp({\sigma}^2) - 1] \exp({2\mu + \sigma^2}) 
     255 
     256Note that larger values of PD might need a larger number of points 
     257and $N_\sigma$. 
    170258 
    171259.. figure:: pd_lognormal.jpg 
    172260 
    173     Lognormal distribution. 
    174  
    175 This distribution function spreads more, and the peak shifts to the left, as 
    176 $p$ increases, so it requires higher values of $N_\sigma$ and more points 
    177 in the distribution. 
     261    Lognormal distribution for PD=0.1. 
     262 
     263For further information on the Lognormal distribution see: 
     264http://en.wikipedia.org/wiki/Log-normal_distribution and 
     265http://mathworld.wolfram.com/LogNormalDistribution.html 
    178266 
    179267.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    182270^^^^^^^^^^^^^^^^^^^ 
    183271 
     272The Schulz (sometimes written Schultz) distribution is similar to the 
     273Lognormal distribution, in that it is also skewed towards larger values of 
     274$x$, but which has computational advantages over the Lognormal distribution. 
     275 
    184276The Schulz distribution is defined as 
    185277 
    186278.. math:: 
    187279 
    188     f(x) = \frac{1}{\text{Norm}} 
    189            (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)} 
    190  
    191 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    192 factor which is determined during the numerical calculation, and $z$ is a 
    193 measure of the width of the distribution such that 
     280    f(x) = \frac{1}{\text{Norm}} (z+1)^{z+1}(x/\bar x)^z 
     281            \frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)} 
     282 
     283where $\bar x$ ($x_\text{mean}$ in the figure) is the mean of the 
     284distribution, *Norm* is a normalization factor which is determined 
     285during the numerical calculation, and $z$ is a measure of the width 
     286of the distribution such that 
    194287 
    195288.. math:: z = (1-p^2) / p^2 
    196289 
    197 The polydispersity is 
    198  
    199 .. math:: p = \sigma / \bar x 
    200  
    201 Note that larger values of PD might need larger number of points and $N_\sigma$. 
    202 For example, at PD=0.7 and radius=60 |Ang|, Npts>=160 and Nsigmas>=15 at least. 
     290where $p$ is the polydispersity in sasmodels given by 
     291 
     292.. math:: PD = p = \sigma / \bar x 
     293 
     294and $\sigma$ is the RMS deviation from $\bar x$. 
     295 
     296Note that larger values of PD might need a larger number of points 
     297and $N_\sigma$. For example, for PD=0.7 with radius=60 |Ang|, at least 
     298Npts>=160 and Nsigmas>=15 are required. 
    203299 
    204300.. figure:: pd_schulz.jpg 
    … …  
    207303 
    208304For further information on the Schulz distribution see: 
    209 M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461. 
     305M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461 and 
     306M Kotlarchyk, RB Stephens, and JS Huang, *J Phys Chem*, (1988), 92, 1533 
    210307 
    211308.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    237334.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    238335 
    239 Boltzmann Distribution 
    240 ^^^^^^^^^^^^^^^^^^^^^^ 
    241  
    242 The Boltzmann Distribution is defined as 
    243  
    244 .. math:: 
    245  
    246     f(x) = \frac{1}{\text{Norm}} 
    247            \exp\left(-\frac{ | x - \bar x | }{\sigma}\right) 
    248  
    249 where $\bar x$ is the mean of the distribution and *Norm* is a normalization 
    250 factor which is determined during the numerical calculation. 
    251 The width is defined as 
    252  
    253 .. math:: \sigma=\frac{k T}{E} 
    254  
    255 which is the inverse Boltzmann factor, 
    256 where $k$ is the Boltzmann constant, $T$ the temperature in Kelvin and $E$ a 
    257 characteristic energy per particle. 
    258  
    259 .. figure:: pd_boltzmann.jpg 
    260  
    261     Boltzmann distribution. 
    262  
    263 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    264  
    265336Note about DLS polydispersity 
    266337^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    267338 
    268 Many commercial Dynamic Light Scattering (DLS) instruments produce a size 
    269 polydispersity parameter, sometimes even given the symbol $p$\ ! This 
    270 parameter is defined as the relative standard deviation coefficient of 
    271 variation of the size distribution and is NOT the same as the polydispersity 
    272 parameters in the Lognormal and Schulz distributions above (though they all 
    273 related) except when the DLS polydispersity parameter is <0.13. 
     339Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and  
     340it should not be assumed that any of the following can be simply equated with  
     341the polydispersity *PD* parameter used in SasView. 
     342 
     343The dimensionless **Polydispersity Index (PI)** is a measure of the width of the  
     344distribution of autocorrelation function decay rates (*not* the distribution of  
     345particle sizes itself, though the two are inversely related) and is defined by  
     346ISO 22412:2017 as 
     347 
     348.. math:: 
     349 
     350    PI = \mu_{2} / \bar \Gamma^2 
     351 
     352where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the  
     353intensity-weighted average value, of the distribution of decay rates. 
     354 
     355*If the distribution of decay rates is Gaussian* then 
     356 
     357.. math:: 
     358 
     359    PI = \sigma^2 / 2\bar \Gamma^2 
     360 
     361where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)**  
     362to be defined as 
     363 
     364.. math:: 
     365 
     366    RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI} 
     367 
     368PI values smaller than 0.05 indicate a highly monodisperse system. Values  
     369greater than 0.7 indicate significant polydispersity. 
     370 
     371The **size polydispersity P-parameter** is defined as the relative standard  
     372deviation coefficient of variation   
     373 
     374.. math:: 
     375 
     376    P = \sqrt\nu / \bar R 
     377 
     378where $\nu$ is the variance of the distribution and $\bar R$ is the mean 
     379value of $R$. Here, the product $P \bar R$ is *equal* to the standard  
     380deviation of the Lognormal distribution. 
     381 
     382P values smaller than 0.13 indicate a monodisperse system. 
    274383 
    275384For more information see: 
    276 S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143 
     385 
     386`ISO 22412:2017, International Standards Organisation (2017) <https://www.iso.org/standard/65410.html>`_. 
     387 
     388`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/>`_. 
     389 
     390`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>`_. 
     391 
     392S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143. 
     393 
     394T Allen, in *Particle Size Measurement*, 4th Edition, Chapman & Hall, London (1990). 
    277395 
    278396.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    282400| 2015-05-01 Steve King 
    283401| 2017-05-08 Paul Kienzle 
     402| 2018-03-20 Steve King 
     403| 2018-04-04 Steve King 
     404| 2018-08-09 Steve King 

  • doc/guide/plugin.rst

    r7e6bc45e r2015f02  
    423423calculations, but instead rely on numerical integration to compute the 
    424424appropriately smeared pattern. 
     425 
     426Each .py file also contains a function:: 
     427 
     428        def random(): 
     429        ... 
     430         
     431This function provides a model-specific random parameter set which shows model  
     432features in the USANS to SANS range.  For example, core-shell sphere sets the  
     433outer radius of the sphere logarithmically in `[20, 20,000]`, which sets the Q  
     434value for the transition from flat to falling.  It then uses a beta distribution  
     435to set the percentage of the shape which is shell, giving a preference for very  
     436thin or very thick shells (but never 0% or 100%).  Using `-sets=10` in sascomp  
     437should show a reasonable variety of curves over the default sascomp q range.   
     438The parameter set is returned as a dictionary of `{parameter: value, ...}`.   
     439Any model parameters not included in the dictionary will default according to  
     440the code in the `_randomize_one()` function from sasmodels/compare.py. 
    425441 
    426442Python Models 
    … …  
    822838 
    823839        :code:`source = ["lib/Si.c", ...]` 
    824         (`Si.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/Si.c>`_) 
     840        (`Si.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_Si.c>`_) 
    825841 
    826842    sas_3j1x_x(x): 

  • 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 

  • doc/rst_prolog

    r30b60d2 r2c12061  
    99.. |Ang^-3| replace:: |Ang|\ :sup:`-3` 
    1010.. |Ang^-4| replace:: |Ang|\ :sup:`-4` 
     11.. |nm^-1| replace:: nm\ :sup:`-1` 
    1112.. |cm^-1| replace:: cm\ :sup:`-1` 
    1213.. |cm^2| replace:: cm\ :sup:`2` 
Note: See TracChangeset for help on using the changeset viewer.