Changes in / [b955dd5:f64b154] in sasmodels


Ignore:
Files:
5 added
6 edited

Legend:

Unmodified
Added
Removed

  • doc/guide/fitting_sq.rst

    r694c6d0 r3448301  
    1818of the form factor. For the theory behind this, see :ref:`PStheory` later. 
    1919 
    20 **If writing your own** $P@S$ **models, DO NOT give your model parameters** 
    21 **these names!** 
    22  
    2320Parameters 
    2421^^^^^^^^^^ 
     22 
     23**Except for volfraction, when writing your own** $P@S$ **models, DO NOT give** 
     24**your model parameters these names!** 
    2525 
    2626Many parameters are common amongst $P@S$ models, but take on specific meanings: 
    … …  
    3737    Structure factor models $S(Q)$ contain **volfraction**. In $P@S$ models 
    3838    this is *also* used as the volume fraction for the form factor model 
    39     $P(Q)$, *replacing* any **volfraction** parameter in $P(Q)$. This means 
    40     that $P@S$ models can also leave **scale** at 1.0. 
     39    $P(Q)$, so these models can also leave **scale** at 1.0.  If $P(Q)$ already 
     40    has a **volfraction** parameter, it is tied to the **volfraction** for 
     41    $S(Q)$. 
    4142 
    4243    If the volume fraction required for $S(Q)$ is *not* the volume fraction 
    … …  
    7172    length. 
    7273 
    73     In use, it may be sensible to tie or constrain **radius_effective** 
    74     to one or other of the "size" parameters describing the form of the shape. 
    75  
    76     **radius_effective** may also be specified directly, independent of the 
    77     estimate from $P(Q)$. 
     74    If **radius_effective_mode = 0** (see below) it may be sensible to tie or 
     75    constrain **radius_effective** to one or other of the "size" parameters 
     76    describing the form of the shape (although the parameter cannot then be 
     77    polydisperse). But **radius_effective** may also be specified directly, 
     78    independent of the estimate from $P(Q)$. 
    7879 
    7980    If **radius_effective** is calculated by $P(Q)$, it will be the 
    … …  
    8687.. note:: 
    8788 
    88    The following additional parameters are only available in SasView 5.0 and 
     89   The following additional parameters are only available in SasView 4.3 and 
    8990   later. 
    9091 
    … …  
    9495    be computed from the parameters of the shape. 
    9596 
    96     When **radius_effective_mode = 0** then unconstrained **radius_effective** 
    97     parameter in the $S(Q)$ model is used. *This is the default in SasView* 
    98     *versions 4.x and earlier*. Otherwise, in SasView 5.0 and later, 
    99     **radius_effective_mode = k** represents an index in a list of alternative 
    100     **radius_effective** calculations which will appear in a drop-down box. 
     97    When **radius_effective_mode = 0** then the unconstrained 
     98    **radius_effective** parameter in the $S(Q)$ model is used. *This is the* 
     99    *default in SasView versions 4.x and earlier*. Otherwise, in SasView 4.3 
     100    and later, **radius_effective_mode = k** represents an index in a list of 
     101    alternative **radius_effective** calculations. 
     102 
     103    In SasView 4.3 and later **k** must be entered as an integer (and it will 
     104    be necessary to read the source code file to discover what calculations the 
     105    modes represent), but in SasView 5.0 and later the options appear in a 
     106    drop-down box. 
    101107 
    102108    For example, the *ellipsoid* model defines the following 
    … …  
    144150    oscillations in the normal (local monodisperse) $S(Q)$. When $\beta(Q) = 1$ 
    145151    the local monodisperse approximation is recovered. *This mode is only* 
    146     *available in SasView 5.0 and later*. 
     152    *available in SasView 4.3 and later*. 
    147153 
    148154    More mode options may appear in future as more complicated operations are 

  • doc/guide/pd/polydispersity.rst

    rd089a00 ra5cb9bc  
    1111-------------------------------------------- 
    1212 
    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  
     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 
    1717the actual parameter it is being applied too. 
    1818 
    19 The resultant intensity is then normalized by the average particle volume such  
     19The resultant intensity is then normalized by the average particle volume such 
    2020that 
    2121 
    … …  
    2424  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background} 
    2525 
    26 where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an  
     26where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an 
    2727average over the distribution $f(x; \bar x, \sigma)$, giving 
    2828 
    2929.. math:: 
    3030 
    31   P(q) = \frac{\text{scale}}{V} \int_\mathbb{R}  
     31  P(q) = \frac{\text{scale}}{V} \int_\mathbb{R} 
    3232  f(x; \bar x, \sigma) F^2(q, x)\, dx + \text{background} 
    3333 
    3434Each distribution is characterized by a center value $\bar x$ or 
    3535$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}$. 
     36the standard deviation, so read the description carefully), the number of 
     37sigmas $N_\sigma$ to include from the tails of the distribution, and the 
     38number of points used to compute the average. The center of the distribution 
     39is set by the value of the model parameter. The meaning of a polydispersity 
     40parameter *PD* (not to be confused with a molecular weight distributions 
     41in polymer science) in a model depends on the type of parameter it is being 
     42applied too. 
     43 
     44The distribution width applied to *volume* (ie, shape-describing) parameters 
     45is relative to the center value such that $\sigma = \mathrm{PD} \cdot \bar x$. 
     46However, the distribution width applied to *orientation* (ie, angle-describing) 
     47parameters is just $\sigma = \mathrm{PD}$. 
    4548 
    4649$N_\sigma$ determines how far into the tails to evaluate the distribution, 
    … …  
    5255 
    5356Users 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  
     57polydispersion and/or orientational distributions to multiple parameters at 
     58the same time, or increasing the number of points in the distribution, will 
     59require patience! However, the calculations are generally more robust with 
    5760more data points or more angles. 
    5861 
    … …  
    6669*  *Schulz Distribution* 
    6770*  *Array Distribution* 
     71*  *User-defined Distributions* 
    6872 
    6973These are all implemented as *number-average* distributions. 
    7074 
    71 Additional distributions are under consideration. 
    7275 
    7376**Beware: when the Polydispersity & Orientational Distribution panel in SasView is** 
    … …  
    7578**This may not be suitable. See Suggested Applications below.** 
    7679 
    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 
    8386           SasView models. 
    8487 
    … …  
    9295or angular orientations, consider using the Gaussian or Boltzmann distributions. 
    9396 
    94 If applying polydispersion to parameters describing angles, use the Uniform  
    95 distribution. Beware of using distributions that are always positive (eg, the  
     97If applying polydispersion to parameters describing angles, use the Uniform 
     98distribution. Beware of using distributions that are always positive (eg, the 
    9699Lognormal) because angles can be negative! 
    97100 
    98 The array distribution allows a user-defined distribution to be applied. 
     101The array distribution provides a very simple means of implementing a user- 
     102defined distribution, but without any fittable parameters. Greater flexibility 
     103is conferred by the user-defined distribution. 
    99104 
    100105.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    … …  
    334339.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    335340 
     341User-defined Distributions 
     342^^^^^^^^^^^^^^^^^^^^^^^^^^ 
     343 
     344You 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* 
     347and *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 
     370As 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 
     392You 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 
     407The *self.nsigmas* and *self.npts* parameters are normally used to control 
     408the accuracy of the distribution integral. The *self._linspace* function 
     409uses 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 
     411nsigmas you will need to generate your own *x*.  Be sure to honour the 
     412limits *lb* and *ub*, for example to disallow a negative radius or constrain 
     413the volume fraction to lie between zero and one. 
     414 
     415To activate a user-defined distribution, put it in a file such as *distname.py* 
     416in the *SAS_WEIGHTS_PATH* folder.  This is defined with an environment 
     417variable, defaulting to:: 
     418 
     419    SAS_WEIGHTS_PATH=~/.sasview/weights 
     420 
     421The weights path is loaded on startup.  To update the distribution definition 
     422in 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 
    336429Note about DLS polydispersity 
    337430^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    338431 
    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  
     432Several measures of polydispersity abound in Dynamic Light Scattering (DLS) and 
     433it should not be assumed that any of the following can be simply equated with 
    341434the polydispersity *PD* parameter used in SasView. 
    342435 
    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  
     436The dimensionless **Polydispersity Index (PI)** is a measure of the width of the 
     437distribution of autocorrelation function decay rates (*not* the distribution of 
     438particle sizes itself, though the two are inversely related) and is defined by 
    346439ISO 22412:2017 as 
    347440 
    … …  
    350443    PI = \mu_{2} / \bar \Gamma^2 
    351444 
    352 where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the  
     445where $\mu_\text{2}$ is the second cumulant, and $\bar \Gamma^2$ is the 
    353446intensity-weighted average value, of the distribution of decay rates. 
    354447 
    … …  
    359452    PI = \sigma^2 / 2\bar \Gamma^2 
    360453 
    361 where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)**  
     454where $\sigma$ is the standard deviation, allowing a **Relative Polydispersity (RP)** 
    362455to be defined as 
    363456 
    … …  
    366459    RP = \sigma / \bar \Gamma = \sqrt{2 \cdot PI} 
    367460 
    368 PI values smaller than 0.05 indicate a highly monodisperse system. Values  
     461PI values smaller than 0.05 indicate a highly monodisperse system. Values 
    369462greater than 0.7 indicate significant polydispersity. 
    370463 
    371 The **size polydispersity P-parameter** is defined as the relative standard  
    372 deviation coefficient of variation   
     464The **size polydispersity P-parameter** is defined as the relative standard 
     465deviation coefficient of variation 
    373466 
    374467.. math:: 
    … …  
    377470 
    378471where $\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  
     472value of $R$. Here, the product $P \bar R$ is *equal* to the standard 
    380473deviation of the Lognormal distribution. 
    381474 

  • sasmodels/compare.py

    rb297ba9 rb297ba9  
    3939 
    4040from . import core 
     41from . import weights 
    4142from . import kerneldll 
    4243from . import kernelcl 
    … …  
    4546from .direct_model import DirectModel, get_mesh 
    4647from .generate import FLOAT_RE, set_integration_size 
    47 from .weights import plot_weights 
    4848 
    4949# pylint: disable=unused-import 
    … …  
    115115 
    116116    === environment variables === 
    117     -DSAS_MODELPATH=path sets directory containing custom models 
     117    -DSAS_MODELPATH=~/.sasmodels/custom_models sets path to custom models 
     118    -DSAS_WEIGHTS_PATH=~/.sasview/weights sets path to custom distributions 
    118119    -DSAS_OPENCL=vendor:device|cuda:device|none sets the target GPU device 
    119120    -DXDG_CACHE_HOME=~/.cache sets the pyopencl cache root (linux only) 
    120121    -DSAS_COMPILER=tinycc|msvc|mingw|unix sets the DLL compiler 
    121     -DSAS_OPENMP=1 turns on OpenMP for the DLLs 
    122     -DSAS_DLL_PATH=path sets the path to the compiled modules 
     122    -DSAS_OPENMP=0 set to 1 to turn on OpenMP for the DLLs 
     123    -DSAS_DLL_PATH=~/.sasmodels/compiled_models sets the DLL cache 
    123124 
    124125The interpretation of quad precision depends on architecture, and may 
    … …  
    784785            model_info = base._kernel.info 
    785786            dim = base._kernel.dim 
    786             plot_weights(model_info, get_mesh(model_info, base_pars, dim=dim)) 
     787            weights.plot_weights(model_info, get_mesh(model_info, base_pars, dim=dim)) 
    787788        if opts['show_profile']: 
    788789            import pylab 
    … …  
    14411442    #import pprint; pprint.pprint(model_info) 
    14421443 
     1444    # Hack to load user-defined distributions; run through all parameters 
     1445    # and make sure any pd_type parameter is a defined distribution. 
     1446    if (any(p.endswith('pd_type') and v not in weights.MODELS 
     1447            for p, v in pars.items()) or 
     1448        any(p.endswith('pd_type') and v not in weights.MODELS 
     1449            for p, v in pars2.items())): 
     1450       weights.load_weights() 
     1451 
    14431452    if opts['show_pars']: 
    14441453        if model_info.name != model_info2.name or pars != pars2: 

  • sasmodels/models/__init__.py

    r2d81cfe rd827c5e  
    11""" 
    2 1D Modeling for SAS 
     2Model definition files 
     3---------------------- 
     4 
     5The models below are grouped by type.  The list is a snapshot at a particular 
     6time and may be out of date. 
     7 
     8Models with pure form factor (all of which define *F(Q)*): 
     9 
     10    :mod:`barbell` 
     11    :mod:`capped_cylinder` 
     12    :mod:`core_multi_shell` 
     13    :mod:`core_shell_bicelle` 
     14    :mod:`core_shell_bicelle_elliptical` 
     15    :mod:`core_shell_bicelle_elliptical_belt_rough` 
     16    :mod:`core_shell_cylinder` 
     17    :mod:`core_shell_ellipsoid` 
     18    :mod:`core_shell_parallelepipied` 
     19    :mod:`core_shell_sphere` 
     20    :mod:`cylinder` [limiting conditions (long rods, thin disks) not implemented] 
     21    :mod:`ellipsoid` 
     22    :mod:`elliptical_cylinder` 
     23    :mod:`fuzzy_sphere` 
     24    :mod:`hollow_cylinder` 
     25    :mod:`hollow_rectangular_prism` 
     26    :mod:`hollow_rectangular_prism_thin_walls` 
     27    :mod:`multilayer_vesicle` 
     28    :mod:`onion` 
     29    :mod:`parallelepiped` 
     30    :mod:`rectangular_prism` 
     31    :mod:`sphere` 
     32    :mod:`spherical_sld` 
     33    :mod:`triaxial_ellipsoid` 
     34    :mod:`vesicle` 
     35 
     36Models with local structure factor: 
     37 
     38    :mod:`flexible_cylinder` 
     39    :mod:`flexible_cylinder_elliptical` 
     40    :mod:`linear_pearls` 
     41    :mod:`mono_gauss_coil` 
     42    :mod:`pearl_necklace` 
     43    :mod:`poly_gauss_coil` 
     44    :mod:`polymer_micelle` 
     45    :mod:`pringle` 
     46    :mod:`raspberry` 
     47    :mod:`stacked_disks` 
     48    :mod:`star_polymer` 
     49 
     50Models with long range structure factor: 
     51 
     52    :mod:`binary_hard_sphere` 
     53    :mod:`bcc_paracrystal` 
     54    :mod:`fcc_paracrystal` 
     55    :mod:`fractal` 
     56    :mod:`fractal_core_shell` 
     57    :mod:`lamellar` 
     58    :mod:`lamellar_hg` 
     59    :mod:`lamellar_hg_stack_caille` 
     60    :mod:`lamellar_stack_caille` 
     61    :mod:`lamellar_stack_paracrystal` 
     62    :mod:`mass_fractal` 
     63    :mod:`mass_surface_fractal` 
     64    :mod:`rpa` 
     65    :mod:`sc_paracrystal` 
     66    :mod:`surface_fractal` 
     67 
     68Models which are pure structure factors:: 
     69 
     70    :mod:`hardsphere` 
     71    :mod:`hayter_msa` 
     72    :mod:`squarewell` 
     73    :mod:`stickyhardsphere` 
     74 
     75Other models: 
     76 
     77    :mod:`adsorbed_layer` 
     78    :mod:`be_polyelectrolyte` 
     79    :mod:`broad_peak` 
     80    :mod:`correlation_length` 
     81    :mod:`dab` 
     82    :mod:`gauss_lorentz_gel` 
     83    :mod:`gaussian_peak` 
     84    :mod:`gel_fit` 
     85    :mod:`guinier_porod` 
     86    :mod:`guinier` 
     87    :mod:`line` 
     88    :mod:`lorentz` 
     89    :mod:`peak_lorentz` 
     90    :mod:`polymer_excl_volume` 
     91    :mod:`porod` 
     92    :mod:`power_law` 
     93    :mod:`spinodal` 
     94    :mod:`teubner_strey` 
     95    :mod:`two_lorentzian` 
     96    :mod:`unified_power_Rg` 
     97 
    398""" 

  • sasmodels/sasview_model.py

    ra34b811 ra34b811  
    3131from . import modelinfo 
    3232from .details import make_kernel_args, dispersion_mesh 
     33 
     34# Hack: load in any custom distributions 
     35# Uses ~/.sasview/weights/*.py unless SASMODELS_WEIGHTS is set in the environ. 
     36# Override with weights.load_weights(pattern="<weights_path>/*.py") 
     37weights.load_weights() 
    3338 
    3439# pylint: disable=unused-import 

  • sasmodels/weights.py

    rb297ba9 rb297ba9  
    230230)) 
    231231 
     232SAS_WEIGHTS_PATH = "~/.sasview/weights" 
     233def load_weights(pattern=None): 
     234    # type: (str) -> None 
     235    """ 
     236    Load dispersion distributions matching the given glob pattern 
     237    """ 
     238    import logging 
     239    import os 
     240    import os.path 
     241    import glob 
     242    import traceback 
     243    from .custom import load_custom_kernel_module 
     244    if pattern is None: 
     245        path = os.environ.get("SAS_WEIGHTS_PATH", SAS_WEIGHTS_PATH) 
     246        pattern = os.path.join(path, "*.py") 
     247    for filename in sorted(glob.glob(os.path.expanduser(pattern))): 
     248        try: 
     249            #print("loading weights from", filename) 
     250            module = load_custom_kernel_module(filename) 
     251            MODELS[module.Dispersion.type] = module.Dispersion 
     252        except Exception as exc: 
     253            logging.error(traceback.format_exc(exc)) 
    232254 
    233255def get_weights(disperser, n, width, nsigmas, value, limits, relative): 
Note: See TracChangeset for help on using the changeset viewer.