Changes in / [345cc8f:bd91e8f] in sasmodels


Ignore:
Files:
1 added
2 edited

Legend:

Unmodified
Added
Removed

  • doc/guide/fitting_sq.rst

    r1423ddb re62c019  
    1616.. figure:: p_and_s_buttons.png 
    1717 
    18 **Product models**, or $P@S$ models for short, multiply the form factor 
    19 $P(Q)$ by the structure factor $S(Q)$, modulated by the **effective radius** 
    20 of the form factor. 
     18**Product models**, or $P@S$ models for short, multiply the structure factor 
     19$S(Q)$ by the form factor $P(Q)$, modulated by the **effective radius** of the 
     20form factor. 
    2121 
    22  
    23 Scattering at vector $\mathbf Q$ for an individual particle with 
    24 shape parameters $\mathbf\xi$ and contrast $\rho_c(\mathbf r, \mathbf\xi)$ 
    25 is computed from the square of the amplitude, $F(\mathbf Q, \mathbf\xi)$, as 
    26  
    27 .. math:: 
    28     I(\mathbf Q) = F(\mathbf Q, \mathbf\xi) F^*(\mathbf Q, \mathbf\xi) 
    29         \big/ V(\mathbf\xi) 
    30  
    31 with particle volume $V(\mathbf \xi)$ and 
    32  
    33 .. math:: 
    34     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 
    36  
    37 The 1-D scattering pattern for monodisperse particles uses the orientation 
    38 average in spherical coordinates, 
    39  
    40 .. math:: 
    41     I(Q) = n \langle F F^*\rangle = \frac{n}{4\pi} 
    42     \int_{\theta=0}^{\pi} \int_{\phi=0}^{2\pi} 
    43     F F^* \sin(\theta) \,\mathrm d\phi \mathrm d\theta 
    44  
    45 where $F(\mathbf Q,\mathbf\xi)$ uses 
    46 $\mathbf Q = [Q \sin\theta\cos\phi, Q \sin\theta\sin\phi, Q \cos\theta]^T$. 
    47 A $u$-substitution may be used, with $\alpha = \cos \theta$, 
    48 $\surd(1 - \alpha^2) = \sin \theta$, and 
    49 $\mathrm d\alpha = -\sin\theta\,\mathrm d\theta$. 
    50 Here, 
    51  
    52 .. math:: n = V_f/V(\mathbf\xi) 
    53  
    54 is the number density of scatterers estimated from the volume fraction 
    55 of particles in solution. In this formalism, each incoming 
    56 wave interacts with exactly one particle before being scattered into the 
    57 detector. All interference effects are within the particle itself. 
    58 The detector accumulates counts in proportion to the relative probability 
    59 at each pixel. The extension to heterogeneous systems is simply a matter of 
    60 adding the scattering patterns in proportion to the number density of each 
    61 particle. That is, given shape parameters $\mathbf\xi$ with probability 
    62 $P_\mathbf{\xi}$, 
    63  
    64 .. math:: 
    65  
    66     I(Q) = \int_\Xi n(\mathbf\xi) \langle F F^* \rangle \,\mathrm d\xi 
    67          = V_f\frac{\int_\Xi P_\mathbf{\xi} \langle F F^* \rangle 
    68          \,\mathrm d\mathbf\xi}{\int_\Xi P_\mathbf\xi V(\mathbf\xi)\,\mathrm d\mathbf\xi} 
    69  
    70 This approximation is valid in the dilute limit, where particles are 
    71 sufficiently far apart that the interaction between them can be ignored. 
    72  
    73 As concentration increases, a structure factor term $S(Q)$ can be included, 
    74 giving the monodisperse approximation for the interaction between particles, 
    75 with 
    76  
    77 .. math:: I(Q) = n \langle F F^* \rangle S(Q) 
    78  
    79 For particles without spherical symmetry, the decoupling approximation (DA) 
    80 is more accurate, with 
    81  
    82 .. math:: 
    83  
    84     I(Q) = n [\langle F F^* \rangle 
    85         + \langle F \rangle \langle F \rangle^* (S(Q) - 1)] 
    86  
    87 Or equivalently, 
    88  
    89 .. math:: I(Q) = P(Q)[1 + \beta\,(S(Q) - 1)] 
    90  
    91 with form factor $P(Q) = n \langle F F^* \rangle$ and 
    92 $\beta = \langle F \rangle \langle F \rangle^* \big/ \langle F F^* \rangle$. 
    93 These approximations can be extended to heterogeneous systems using averages 
    94 over 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 
    95 $n = V_f\big/\langle V \rangle_\mathbf\xi$. 
    96 Further 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: 
     22Many of the parameters in $P@S$ models take on specific meanings so that they 
     23can be handled correctly inside SasView: 
    10124 
    10225* *scale*: 
    10326 
    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. 
     27  In simple $P(Q)$ models **scale** often represents the volume fraction of 
     28  material. 
     29   
     30  In $P@S$ models **scale** should be set to 1.0, as the $P@S$ model contains a 
     31  **volfraction** parameter. 
    12432 
    12533* *volfraction*: 
    12634 
    127     The volume fraction of material. 
     35  The volume fraction of material. 
    12836 
    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)$. 
     37  For hollow shapes, **volfraction** still represents the volume fraction of 
     38  material but the $S(Q)$ calculation needs the volume fraction *enclosed by* 
     39  *the shape.* SasView scales the user-specified volume fraction by the ratio 
     40  form:shell computed from the average form volume and average shell volume 
     41  returned from the $P(Q)$ calculation (the original volfraction is divided 
     42  by the shell volume to compute the number density, and then $P@S$ is scaled 
     43  by that to get the absolute scaling on the final $I(Q)$). 
    13644 
    13745* *radius_effective*: 
    13846 
    139     The radial distance determining the range of the $S(Q)$ interaction. 
     47  The radial distance determining the range of the $S(Q)$ interaction. 
     48   
     49  This may, or may not, be the same as any "size" parameters describing the 
     50  form of the shape. For example, in a system containing freely-rotating 
     51  cylinders, the volume of space each cylinder requires to tumble will be 
     52  much larger than the volume of the cylinder itself. Thus the effective 
     53  radius will be larger than either the radius or half-length of the 
     54  cylinder. It may be sensible to tie or constrain **radius_effective** to one 
     55  or other of these "size" parameters. 
    14056 
    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. 
     57  If just part of the $S(Q)$ calculation, the value of **radius_effective** may 
     58  be polydisperse. If it is calculated by $P(Q)$, then it will be the weighted 
     59  average of the effective radii computed for the polydisperse shape 
     60  parameters. 
    17661 
    17762* *structure_factor_mode*: 
    17863 
    179     The type of structure factor calculation to use. 
     64  If the $P@S$ model supports the $\beta(Q)$ *decoupling correction* [1] then 
     65  **structure_factor_mode** will appear in the parameter table after the $S(Q)$ 
     66  parameters. 
     67   
     68  If **structure_factor_mode = 0** then the *local monodisperse approximation* 
     69  will be used, i.e.: 
    18070 
    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. 
     71    $I(Q)$ = $(scale$ / $volume)$ x $P(Q)$ x $S(Q)$ + $background$ 
    18472 
    185     If **structure_factor_mode = 0** then the 
    186     *local monodisperse approximation* will be used, i.e.: 
     73  If **structure_factor_mode = 1** then the $\beta(q)$ correction will be 
     74  used, i.e.: 
    18775 
    188     .. math:: 
    189         I(Q) = \text{scale} \frac{V_f}{V} P(Q) S(Q) + \text{background} 
     76    $I(Q)$ = $(scale$ x $volfraction$ / $volume)$ x $( <F(Q)^2>$ + $<F(Q)>^2$ x $(S(Q)$ - $1) )$ + $background$ 
    19077 
    191     where $P(Q) = \langle F(Q)^2 \rangle$. 
     78    where $P(Q)$ = $<|F(Q)|^2>$. 
     79     
     80  This is equivalent to: 
     81   
     82    $I(Q)$ = $(scale$ / $volume)$ x $P(Q)$ x $( 1$ + $\beta(Q)$ x $(S(Q)$ - $1) )$ + $background$ 
    19283 
    193     If **structure_factor_mode = 1** then the $\beta(Q)$ correction will be 
    194     used, i.e.: 
     84  The $\beta(Q)$ decoupling approximation has the effect of damping the 
     85  oscillations in the normal (local monodisperse) $S(Q)$. When $\beta(Q)$ = 1 
     86  the local monodisperse approximation is recovered. 
    19587 
    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. 
     88  More mode options may appear in future as more complicated operations are 
     89  added. 
    20690 
    20791References 

  • sasmodels/kernelcl.py

    r9fac5f5 ra34b811  
    158158ENV = None 
    159159def reset_environment(): 
    160     # type: () -> "GpuEnvironment" 
    161     """ 
    162     Return a new OpenCL context, such as after a change to SAS_OPENCL. 
     160    # type: () -> None 
     161    """ 
     162    Call to create a new OpenCL context, such as after a change to SAS_OPENCL. 
    163163    """ 
    164164    global ENV 
    165165    ENV = GpuEnvironment() if use_opencl() else None 
    166     return ENV 
     166 
    167167 
    168168def environment(): 
Note: See TracChangeset for help on using the changeset viewer.