Changeset 31fc4ad in sasmodels


Ignore:
Timestamp:
Oct 22, 2018 10:54:14 AM (3 weeks ago)
Author:
Paul Kienzle <pkienzle@…>
Branches:
beta_approx, py3, ticket-1015-gpu-mem-error, ticket-1157, ticket-608-user-defined-weights, ticket_1156
Children:
07646b6
Parents:
be43e39
Message:

and notes about shell_volume and Fq to the user guide

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/guide/plugin.rst

    r2015f02 r31fc4ad  
    291291 
    292292**Note: The order of the parameters in the definition will be the order of the 
    293 parameters in the user interface and the order of the parameters in Iq(), 
    294 Iqac(), Iqabc() and form_volume(). And** *scale* **and** *background* 
    295 **parameters are implicit to all models, so they do not need to be included 
    296 in the parameter table.** 
     293parameters in the user interface and the order of the parameters in Fq(), Iq(), 
     294Iqac(), Iqabc(), form_volume() and shell_volume(). 
     295And** *scale* **and** *background* **parameters are implicit to all models, 
     296so they do not need to be included in the parameter table.** 
    297297 
    298298- **"name"** is the name of the parameter shown on the FitPage. 
     
    363363    scattered intensity. 
    364364 
    365   - "volume" parameters are passed to Iq(), Iqac(), Iqabc() and form_volume(), 
    366     and have polydispersity loops generated automatically. 
     365  - "volume" parameters are passed to Fq(), Iq(), Iqac(), Iqabc(), form_volume() 
     366    and shell_volume(), and have polydispersity loops generated automatically. 
    367367 
    368368  - "orientation" parameters are not passed, but instead are combined with 
     
    428428        def random(): 
    429429        ... 
    430          
    431 This function provides a model-specific random parameter set which shows model  
    432 features in the USANS to SANS range.  For example, core-shell sphere sets the  
    433 outer radius of the sphere logarithmically in `[20, 20,000]`, which sets the Q  
    434 value for the transition from flat to falling.  It then uses a beta distribution  
    435 to set the percentage of the shape which is shell, giving a preference for very  
    436 thin or very thick shells (but never 0% or 100%).  Using `-sets=10` in sascomp  
    437 should show a reasonable variety of curves over the default sascomp q range.   
    438 The parameter set is returned as a dictionary of `{parameter: value, ...}`.   
    439 Any model parameters not included in the dictionary will default according to  
     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 
    440440the code in the `_randomize_one()` function from sasmodels/compare.py. 
    441441 
     
    492492used. 
    493493 
     494Hollow shapes, where the volume fraction of particle corresponds to the 
     495material in the shell rather than the volume enclosed by the shape, must 
     496also define a *shell_volume(par1, par2, ...)* function.  The parameters 
     497are the same as for *form_volume*.  The *I(q)* calculation should use 
     498*shell_volume* squared as its scale factor for the volume normalization. 
     499The structure factor calculation needs *form_volume* in order to properly 
     500scale the volume fraction parameter, so both functions are required for 
     501hollow shapes. 
     502 
     503Note: Pure python models do not yet support direct computation of the 
     504average of $F(q)$ and $F^2(q)$. 
     505 
    494506Embedded C Models 
    495507................. 
     
    503515This expands into the equivalent C code:: 
    504516 
    505     #include <math.h> 
    506517    double Iq(double q, double par1, double par2, ...); 
    507518    double Iq(double q, double par1, double par2, ...) 
     
    512523*form_volume* defines the volume of the shape. As in python models, it 
    513524includes only the volume parameters. 
     525 
     526*form_volume* defines the volume of the shell for hollow shapes. As in 
     527python models, it includes only the volume parameters. 
    514528 
    515529**source=['fn.c', ...]** includes the listed C source files in the 
     
    548562The INVALID define can go into *Iq*, or *c_code*, or an external C file 
    549563listed in *source*. 
     564 
     565Structure Factors 
     566................. 
     567 
     568Structure factor calculations may need the underlying $<F(q)>$ and $<F^2(q)>$ 
     569rather than $I(q)$.  This is used to compute $\beta = <F(q)>^2/<F^2(q)>$ in 
     570the decoupling approximation to the structure factor. 
     571 
     572Instead of defining the *Iq* function, models can define *Fq* as 
     573something like:: 
     574 
     575    double Fq(double q, double *F1, double *F2, double par1, double par2, ...); 
     576    double Fq(double q, double *F1, double *F2, double par1, double par2, ...) 
     577    { 
     578        // Polar integration loop over all orientations. 
     579        ... 
     580        *F1 = 1e-2 * total_F1 * contrast * volume; 
     581        *F2 = 1e-4 * total_F2 * square(contrast * volume); 
     582        return I(q, par1, par2, ...); 
     583    } 
     584 
     585If the volume fraction scale factor is built into the model (as occurs for 
     586the vesicle model, for example), then scale *F1* by $\surd V_f$ so that 
     587$\beta$ is computed correctly. 
     588 
     589Structure factor calculations are not yet supported for oriented shapes. 
     590 
     591Note: only available as a separate C file listed in *source*, or within 
     592a *c_code* block within the python model definition file. 
    550593 
    551594Oriented Shapes 
Note: See TracChangeset for help on using the changeset viewer.