Changeset 9624545 in sasmodels


Ignore:
Timestamp:
Mar 31, 2019 8:08:06 AM (5 months ago)
Author:
smk78
Branches:
master
Children:
4d00de6
Parents:
1dd78a2b
Message:

Overhaul of fitting_sq.rst for readability & clarification

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/guide/fitting_sq.rst

    r1423ddb r9624545  
    1414   This help document is under development 
    1515 
    16 .. figure:: p_and_s_buttons.png 
    17  
    1816**Product models**, or $P@S$ models for short, multiply the form factor 
    1917$P(Q)$ by the structure factor $S(Q)$, modulated by the **effective radius** 
    20 of the form factor. 
    21  
     18of the form factor. For the theory behind this, see :ref:`PStheory` later. 
     19 
     20**If writing your own** $P@S$ **models, DO NOT give your model parameters** 
     21**these names!** 
     22 
     23Parameters 
     24^^^^^^^^^^ 
     25 
     26Many parameters are common amongst $P@S$ models, but take on specific meanings: 
     27 
     28* *scale*: 
     29 
     30    Overall model scale factor. 
     31 
     32    To compute number density $n$ the volume fraction $V_f$ (parameterised as 
     33    **volfraction**) is needed.  In most $P(Q)$ models $V_f$ is not defined and 
     34    **scale** is used instead. Some $P(Q)$ models, such as the *vesicle*, do 
     35    define **volfraction** and so can leave **scale** at 1.0. 
     36 
     37    Structure factor models $S(Q)$ contain **volfraction**. In $P@S$ models 
     38    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. 
     41 
     42    If the volume fraction required for $S(Q)$ is *not* the volume fraction 
     43    needed to compute the $n$ for $P(Q)$, then leave **volfraction** as the 
     44    $V_f$ for $S(Q)$ and use **scale** to define the $V_f$ for $P(Q)$ as 
     45    $V_f$ = **scale**  $\cdot$  **volfraction**.  This situation may occur in 
     46    a mixed phase system where the effective volume fraction needed to compute 
     47    the structure is much higher than the true volume fraction. 
     48 
     49* *volfraction*: 
     50 
     51    The volume fraction of material, $V_f$. 
     52 
     53    For hollow shapes, **volfraction** still represents the volume fraction of 
     54    material but the $S(Q)$ calculation needs the volume fraction *enclosed by* 
     55    *the shape.*  To remedy this the user-specified **volfraction** is scaled 
     56    by the ratio form:shell computed from the average form volume and average 
     57    shell volume returned from the $P(Q)$ calculation when calculating $S(Q)$. 
     58    The original **volfraction** is divided by the shell volume to compute the 
     59    number density $n$ used in the $P@S$ model to get the absolute scaling on 
     60    the final $I(Q)$. 
     61 
     62* *radius_effective*: 
     63 
     64    The radial distance determining the range of the $S(Q)$ interaction. 
     65 
     66    This may be estimated from the "size" parameters $\mathbf \xi$ describing 
     67    the form of the shape.  For example, in a system containing freely-rotating 
     68    cylinders, the volume of space each cylinder requires to tumble will be 
     69    much larger than the volume of the cylinder itself. Thus the *effective* 
     70    radius of a cylinder will be larger than either its actual radius or half- 
     71    length. 
     72 
     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)$. 
     78 
     79    If **radius_effective** is calculated by $P(Q)$, it will be the 
     80    weighted average of the effective radii computed for the polydisperse 
     81    shape parameters, and that average is used to compute $S(Q)$. When 
     82    specified directly, the value of **radius_effective** may be 
     83    polydisperse, and $S(Q)$ will be averaged over a range of effective 
     84    radii. Whether this makes any physical sense will depend on the system. 
     85 
     86.. note:: 
     87 
     88   The following additional parameters are only available in SasView 5.0 and 
     89   later. 
     90 
     91* *radius_effective_mode*: 
     92 
     93    Defines how the effective radius (parameter **radius_effective**) should 
     94    be computed from the parameters of the shape. 
     95 
     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.x 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. 
     101 
     102    For example, the *ellipsoid* model defines the following 
     103    **radius_effective_modes**:: 
     104 
     105        1 => average curvature 
     106        2 => equivalent volume sphere 
     107        3 => min radius 
     108        4 => max radius 
     109 
     110    Note: **radius_effective_mode** will only appear in the parameter table if 
     111    the model defines the list of modes, otherwise it will be set permanently 
     112    to 0 for the user-defined effective radius. 
     113     
     114    **WARNING! If** $P(Q)$ **is multiplied by** $S(Q)$ **in the FitPage,** 
     115    **instead of being generated in the Sum|Multi dialog, the** 
     116    **radius_effective used is constrained (equivalent to** 
     117    **radius_effective_mode = 1)**. 
     118 
     119* *structure_factor_mode*: 
     120 
     121    The type of structure factor calculation to use. 
     122 
     123    If the $P@S$ model supports the $\beta(Q)$ *decoupling correction* [1] 
     124    then **structure_factor_mode** will appear in the parameter table after 
     125    the $S(Q)$ parameters. 
     126 
     127    If **structure_factor_mode = 0** then the 
     128    *local monodisperse approximation* will be used, i.e.: 
     129 
     130    .. math:: 
     131        I(Q) = \text{scale} \frac{V_f}{V} P(Q) S(Q) + \text{background} 
     132 
     133    where $P(Q) = \langle F(Q)^2 \rangle$. *This is the default in SasView* 
     134    *versions 4.x and earlier*. 
     135 
     136    If **structure_factor_mode = 1** then the $\beta(Q)$ correction will be 
     137    used, i.e.: 
     138 
     139    .. math:: 
     140        I(Q) = \text{scale} \frac{V_f}{V} P(Q) [ 1 + \beta(Q) (S(Q) - 1) ] 
     141        + \text{background} 
     142 
     143    The $\beta(Q)$ decoupling approximation has the effect of damping the 
     144    oscillations in the normal (local monodisperse) $S(Q)$. When $\beta(Q) = 1$ 
     145    the local monodisperse approximation is recovered. *This mode is only* 
     146    *available in SasView 5.x and later*. 
     147 
     148    More mode options may appear in future as more complicated operations are 
     149    added. 
     150 
     151.. _PStheory: 
     152 
     153Theory 
     154^^^^^^ 
    22155 
    23156Scattering at vector $\mathbf Q$ for an individual particle with 
     
    29162        \big/ V(\mathbf\xi) 
    30163 
    31 with particle volume $V(\mathbf \xi)$ and 
     164with the particle volume $V(\mathbf \xi)$ and 
    32165 
    33166.. math:: 
    34167    F(\mathbf Q, \mathbf\xi) = \int_{\mathbb R^3} \rho_c(\mathbf r, \mathbf\xi) 
    35         e^{i \mathbf Q \cdot \mathbf r} \,\mathrm d \mathbf r 
     168        e^{i \mathbf Q \cdot \mathbf r} \,\mathrm d \mathbf r = F 
    36169 
    37170The 1-D scattering pattern for monodisperse particles uses the orientation 
     
    52185.. math:: n = V_f/V(\mathbf\xi) 
    53186 
    54 is the number density of scatterers estimated from the volume fraction 
     187is the number density of scatterers estimated from the volume fraction $V_f$ 
    55188of particles in solution. In this formalism, each incoming 
    56189wave interacts with exactly one particle before being scattered into the 
     
    77210.. math:: I(Q) = n \langle F F^* \rangle S(Q) 
    78211 
    79 For particles without spherical symmetry, the decoupling approximation (DA) 
     212For particles without spherical symmetry, the decoupling approximation 
    80213is more accurate, with 
    81214 
     
    89222.. math:: I(Q) = P(Q)[1 + \beta\,(S(Q) - 1)] 
    90223 
    91 with form factor $P(Q) = n \langle F F^* \rangle$ and 
     224with the form factor $P(Q) = n \langle F F^* \rangle$ and 
    92225$\beta = \langle F \rangle \langle F \rangle^* \big/ \langle F F^* \rangle$. 
    93226These approximations can be extended to heterogeneous systems using averages 
    94227over size, $\langle \cdot \rangle_\mathbf\xi = \int_\Xi P_\mathbf\xi \langle\cdot\rangle\,\mathrm d\mathbf\xi \big/ \int_\Xi P_\mathbf\xi \,\mathrm d\mathbf\xi$ and setting 
    95228$n = V_f\big/\langle V \rangle_\mathbf\xi$. 
     229 
    96230Further improvements can be made using the local monodisperse 
    97 approximation (LMA) or using partial structure factors, as described 
    98 in \cite{bresler_sasfit:_2015}. 
    99  
    100 Many parameters are common amongst $P@S$ models, and take on specific meanings: 
    101  
    102 * *scale*: 
    103  
    104     Overall model scale factor. 
    105  
    106     To compute number density $n$ the volume fraction $V_f$ is needed.  In 
    107     most $P(Q)$ models $V_f$ is not defined and **scale** is used instead. 
    108     Some $P(Q)$ models, such as *vesicle*, do define **volfraction** and so 
    109     can leave **scale** at 1.0. 
    110  
    111     The structure factor model $S(Q)$ has **volfraction**.  This is also used 
    112     as the volume fraction for the form factor model $P(Q)$, replacing the 
    113     **volfraction** parameter if it exists in $P$. This means that 
    114     $P@S$ models can leave **scale** at 1.0. 
    115  
    116     If the volume fraction required for $S(Q)$ is *not* the volume fraction 
    117     needed to compute the number density for $P(Q)$, then leave 
    118     **volfraction** as the volume fraction for $S(Q)$ and use 
    119     **scale** to define the volume fraction for $P(Q)$ as 
    120     $V_f$ = **scale**  $\cdot$  **volfraction**.  This situation may 
    121     occur in a mixed phase system where the effective volume 
    122     fraction needed to compute the structure is much higher than the 
    123     true volume fraction. 
    124  
    125 * *volfraction*: 
    126  
    127     The volume fraction of material. 
    128  
    129     For hollow shapes, **volfraction** still represents the volume fraction of 
    130     material but the $S(Q)$ calculation needs the volume fraction *enclosed by* 
    131     *the shape.*  Thus the user-specified **volfraction** is scaled by the ratio 
    132     form:shell computed from the average form volume and average shell volume 
    133     returned from the $P(Q)$ calculation when calculating $S(Q)$.  The original 
    134     **volfraction** is divided by the shell volume to compute the number 
    135     density $n$ used in $P@S$ to get the absolute scaling on the final $I(Q)$. 
    136  
    137 * *radius_effective*: 
    138  
    139     The radial distance determining the range of the $S(Q)$ interaction. 
    140  
    141     This may be estimated from the "size" parameters $\mathbf \xi$ describing 
    142     the form of the shape.  For example, in a system containing freely-rotating 
    143     cylinders, the volume of space each cylinder requires to tumble will be 
    144     much larger than the volume of the cylinder itself.  Thus the effective 
    145     radius will be larger than either the radius or the half-length of the 
    146     cylinder.  It may be sensible to tie or constrain **radius_effective** 
    147     to one or other of these "size" parameters. **radius_effective** may 
    148     also be specified directly, independent of the estimate from $P(Q)$. 
    149  
    150     If it is calculated by $P(Q)$, **radius_effective** will be the 
    151     weighted average of the effective radii computed for the polydisperse 
    152     shape parameters, and that average used to compute $S(Q)$.  When 
    153     specified directly, the value of **radius_effective** may be 
    154     polydisperse, and $S(Q)$ will be averaged over a range of effective 
    155     radii.  Whether this makes any physical sense will depend on the system. 
    156  
    157 * *radius_effective_mode*: 
    158  
    159     Selects the **radius_effective** value to use. 
    160  
    161     When **radius_effective_mode = 0** then the **radius_effective** 
    162     parameter in the $P@S$ model is used.  Otherwise 
    163     **radius_effective_mode = k** is the index into the list of 
    164     **radius_effective_modes** defined by the model indicating how the 
    165     effective radius should be computed from the parameters of the shape. 
    166     For example, the *ellipsoid* model defines the following:: 
    167  
    168         1 => average curvature 
    169         2 => equivalent volume sphere 
    170         3 => min radius 
    171         4 => max radius 
    172  
    173     **radius_effective_mode** will only appear in the parameter table if 
    174     the model defines the list of modes, otherwise it will be set permanently 
    175     to 0 for user defined effective radius. 
    176  
    177 * *structure_factor_mode*: 
    178  
    179     The type of structure factor calculation to use. 
    180  
    181     If the $P@S$ model supports the $\beta(Q)$ *decoupling correction* [1] 
    182     then **structure_factor_mode** will appear in the parameter table after 
    183     the $S(Q)$ parameters. 
    184  
    185     If **structure_factor_mode = 0** then the 
    186     *local monodisperse approximation* will be used, i.e.: 
    187  
    188     .. math:: 
    189         I(Q) = \text{scale} \frac{V_f}{V} P(Q) S(Q) + \text{background} 
    190  
    191     where $P(Q) = \langle F(Q)^2 \rangle$. 
    192  
    193     If **structure_factor_mode = 1** then the $\beta(Q)$ correction will be 
    194     used, i.e.: 
    195  
    196     .. math:: 
    197         I(Q) = \text{scale} \frac{V_f}{V} P(Q) [ 1 + \beta(Q) (S(Q) - 1) ] 
    198         + \text{background} 
    199  
    200     The $\beta(Q)$ decoupling approximation has the effect of damping the 
    201     oscillations in the normal (local monodisperse) $S(Q)$. When $\beta(Q) = 1$ 
    202     the local monodisperse approximation is recovered. 
    203  
    204     More mode options may appear in future as more complicated operations are 
    205     added. 
     231approximation (LMA) or using partial structure factors [2]. 
    206232 
    207233References 
     
    210236.. [#] Kotlarchyk, M.; Chen, S.-H. *J. Chem. Phys.*, 1983, 79, 2461 
    211237 
     238.. [#] Bressler I., Kohlbrecher J., Thunemann A.F. *J. Appl. Crystallogr.* 
     239   48 (2015) 1587-1598 
     240 
    212241.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    213242 
    214243*Document History* 
    215244 
    216 | 2019-03-30 Paul Kienzle & Steve King 
     245| 2019-03-31 Paul Kienzle, Steve King & Richard Heenan 
Note: See TracChangeset for help on using the changeset viewer.