Changeset a7684e5 in sasmodels


Ignore:
Timestamp:
Aug 26, 2014 9:07:44 AM (10 years ago)
Author:
Paul Kienzle <pkienzle@…>
Branches:
master, core_shell_microgels, costrafo411, magnetic_model, release_v0.94, release_v0.95, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests
Children:
ff7119b
Parents:
13d86bc
Message:

docu updates

Location:
sasmodels
Files:
2 added
5 edited

Legend:

Unmodified
Added
Removed

  • sasmodels/gen.py

    r32c160a ra7684e5  
    1 __all__ = ["make_opencl"] 
     1""" 
     2SAS model constructor. 
     3 
     4Small angle scattering models are defined by a set of kernel functions: 
     5 
     6    *Iq(q, p1, p2, ...)* returns the scattering at q for a form with 
     7    particular dimensions averaged over all orientations. 
     8 
     9    *Iqxy(qx, qy, p1, p2, ...)* returns the scattering at qx,qy for a form 
     10    with particular dimensions for a single orientation. 
     11 
     12    *Imagnetic(qx, qy, result[], p1, p2, ...)* returns the scattering for the 
     13    polarized neutron spin states (up-up, up-down, down-up, down-down) for 
     14    a form with particular dimensions for a single orientation. 
     15 
     16    *form_volume(p1, p2, ...)* returns the volume of the form with particular 
     17    dimension. 
     18 
     19    *ER(p1, p2, ...)* returns the effective radius of the form with 
     20    particular dimensions. 
     21 
     22    *VR(p1, p2, ...)* returns the volume ratio for core-shell style forms. 
     23 
     24These functions are defined in a kernel module .py script and an associated 
     25set of .c files.  The model constructor will use them to create models with 
     26polydispersity across volume and orientation parameters, and provide 
     27scale and background parameters for each model. 
     28 
     29*Iq*, *Iqxy*, *Imagnetic* and *form_volume* should be stylized C-99 
     30functions written for OpenCL.  Floating point values should be 
     31declared as *real*.  Depending on how the function is called, a macro 
     32will replace *real* with *float* or *double*.  Unfortunately, MacOSX 
     33is picky about floating point constants, which should be defined with 
     34value + 'f' if they are of type *float* or just a bare value if they 
     35are of type *double*.  The solution is a macro *REAL(value)* which 
     36adds the 'f' if compiling for single precision floating point.  This 
     37does make the code ugly, and may someday be replaced by a clever 
     38regular expression which does the same job.  OpenCL has a *sincos* 
     39function which can improve performance when both the *sin* and *cos* 
     40values are needed for a particular argument.  Since this function 
     41does not exist in C-99, all use of *sincos* should be replaced by the 
     42macro *SINCOS(value,sn,cn)* where *sn* and *cn* are previously declared 
     43*real* values.  *value* may be an expression.  When compiled for systems 
     44without OpenCL, *SINCOS* will be replaced by *sin* and *cos* calls.  All 
     45functions need prototype declarations even if the are defined before they 
     46are used -- another present from MacOSX.  OpenCL does not support 
     47*#include* preprocessor directives; instead the includes must be listed 
     48in the kernel metadata, with functions defined before they are used. 
     49The included files should be listed using relative path to the kernel 
     50source file, or if using one of the standard models, relative to the 
     51sasmodels source files. 
     52 
     53*ER* and *VR* are python functions which operate on parameter vectors. 
     54The constructor code will generate the necessary vectors for computing 
     55them with the desired polydispersity. 
     56 
     57The kernel module must set variables defining the kernel meta data: 
     58 
     59    *name* is the model name 
     60 
     61    *title* is a short description of the model, suitable for a tool tip, 
     62    or a one line model summary in a table of models. 
     63 
     64    *description* is an extended description of the model to be displayed 
     65    while the model parameters are being edited. 
     66 
     67    *parameters* is a list of parameters.  Each parameter is itself a 
     68    list containing *name*, *units*, *default value*, 
     69    [*lower bound*, *upper bound*], *type* and *description*. 
     70 
     71    *source* is the list of C-99 source files that must be joined to 
     72    create the OpenCL kernel functions.  The files defining the functions 
     73    need to be listed before the files which use the functions. 
     74 
     75    *ER* is a python function defining the effective radius.  If it is 
     76    not present, the effective radius is 0. 
     77 
     78    *VR* is a python function defining the volume ratio.  If it is not 
     79    present, the volume ratio is 1. 
     80 
     81The doc string at the start of the kernel module will be used to 
     82construct the model documentation web pages.  Embedded figures should 
     83appear in the subdirectory "img" beside the model definition, and tagged 
     84with the kernel module name to avoid collision with other models.  Some 
     85file systems are case-sensitive, so only use lower case characters for 
     86file names and extensions. 
     87 
     88Parameters are defined as follows: 
     89 
     90    *name* is the name that will be used in the call to the kernel 
     91    function and the name that will be displayed to the user.  Names 
     92    should be lower case, with words separated by underscore.  If 
     93    acronyms are used, the whole acronym should be upper case. 
     94 
     95    *units* should be one of *degrees* for angles, *Ang* for lengths, 
     96    *1e-6/Ang^2* for SLDs. 
     97 
     98    *default value* will be the initial value for  the model when it 
     99    is selected, or when an initial value is not otherwise specified. 
     100 
     101    *limits* are the valid bounds of the parameter, used to limit the 
     102    polydispersity density function.   In the fit, the parameter limits 
     103    given to the fit are the limits  on the central value of the parameter. 
     104    If there is polydispersity, it will evaluate parameter values outside 
     105    the fit limits, but not outside the hard limits specified in the model. 
     106    If there are no limits, use +/-inf imported from numpy. 
     107 
     108    *type* indicates how the parameter will be used.  "volume" parameters 
     109    will be used in all functions.  "orientation" parameters will be used 
     110    in *Iqxy* and *Imagnetic*.  "magnetic* parameters will be used in 
     111    *Imagnetic* only.  If *type* is none, the parameter will be used in 
     112    all of *Iq*, *Iqxy* and *Imagnetic*.  This will probably be a 
     113    is the empty string if the parameter is used in all model calculations, 
     114    it is "volu 
     115 
     116    *description* is a short description of the parameter.  This will 
     117    be displayed in the parameter table and used as a tool tip for the 
     118    parameter value in the user interface. 
     119 
     120The function :func:`make` loads the metadata from the module and returns 
     121the kernel source.  The function :func:`doc` extracts 
     122""" 
     123 
     124# TODO: identify model files which have changed since loading and reload them. 
     125 
     126__all__ = ["make, doc"] 
    2127 
    3128import os.path 
    4129 
    5130import numpy as np 
    6  
    7 from .jsonutil import relaxed_loads 
    8131 
    9132F64 = np.dtype('float64') 
    … …  
    183306  norm_vol += vol_weight;""" 
    184307 
     308# Documentation header for the module, giving the model name, its short 
     309# description and its parameter table.  The remainder of the doc comes 
     310# from the module docstring. 
     311DOC_HEADER=""".. _%(name)s: 
     312 
     313%(name)s 
     314======================================================= 
     315 
     316%(title)s 
     317 
     318%(parameters)s 
     319 
     320The returned value is scaled to units of |cm^-1|. 
     321 
     322%(docs)s 
     323""" 
    185324 
    186325def indent(s, depth): 
    … …  
    389528def make(kernel_module): 
    390529    """ 
    391     Build an OpenCL function from the source in *kernelfile*. 
    392  
    393     The kernel file needs to define metadata about the parameters.  This 
    394     will be a JSON definition containing 
     530    Build an OpenCL/ctypes function from the definition in *kernel_module*. 
     531 
     532    The module can be loaded with a normal python import statement if you 
     533    know which module you need, or with __import__('sasmodels.model.'+name) 
     534    if the name is in a string. 
    395535    """ 
    396536    # TODO: allow Iq and Iqxy to be defined in python 
    … …  
    416556    return source, info 
    417557 
     558def doc(kernel_module): 
     559    """ 
     560    Return the documentation for the model. 
     561    """ 
     562    subst = dict(name=kernel_module.name, 
     563                 title=kernel_module.title, 
     564                 parameters=make_partable(kernel_module.parameters), 
     565                 doc=kernel_module.__doc__) 
     566    return DOC_HEADER%subst 
     567 
    418568 
    419569def demo_time(): 

  • sasmodels/models/cylinder.c

    r1f21edf ra7684e5  
    1 /* PARAMETERS 
    2 { 
    3 name: "cylinder", 
    4 title: "Cylinder with uniform scattering length density", 
    5 include: [ "lib/J1.c", "lib/gauss76.c", "lib/cylkernel.c" ], 
    6 parameters: [ 
    7    // [ "name", "units", default, [lower, upper], "type", "description" ], 
    8    [ "sld", "1e-6/Ang^2", 4, [-Infinity,Infinity], "", 
    9      "Cylinder scattering length density" ], 
    10    [ "solvent_sld", "1e-6/Ang^2", 1, [-Infinity,Infinity], "", 
    11      "Solvent scattering length density" ], 
    12    [ "radius", "Ang",  20, [0, Infinity], "volume", 
    13      "Cylinder radius" ], 
    14    [ "length", "Ang",  400, [0, Infinity], "volume", 
    15      "Cylinder length" ], 
    16    [ "theta", "degrees", 60, [-Infinity, Infinity], "orientation", 
    17      "In plane angle" ], 
    18    [ "phi", "degrees", 60, [-Infinity, Infinity], "orientation", 
    19      "Out of plane angle" ], 
    20 ], 
    21 } 
    22 PARAMETERS END 
    23  
    24 DOCUMENTATION 
    25 .. _CylinderModel: 
    26  
    27 CylinderModel 
    28 ============= 
    29  
    30 This model provides the form factor for a right circular cylinder with uniform 
    31 scattering length density. The form factor is normalized by the particle volume. 
    32  
    33 For information about polarised and magnetic scattering, click here_. 
    34  
    35 Definition 
    36 ---------- 
    37  
    38 The output of the 2D scattering intensity function for oriented cylinders is 
    39 given by (Guinier, 1955) 
    40  
    41 .. math:: 
    42  
    43     P(q,\alpha) = \frac{\text{scale}}{V}f^2(q) + \text{bkg} 
    44  
    45 where 
    46  
    47 .. math:: 
    48  
    49     f(q) = 2 (\Delta \rho) V 
    50            \frac{\sin (q L/2 \cos \alpha)}{q L/2 \cos \alpha} 
    51            \frac{J_1 (q r \sin \alpha)}{q r \sin \alpha} 
    52  
    53 and $\alpha$ is the angle between the axis of the cylinder and $\vec q$, $V$ 
    54 is the volume of the cylinder, $L$ is the length of the cylinder, $r$ is the 
    55 radius of the cylinder, and $d\rho$ (contrast) is the scattering length density 
    56 difference between the scatterer and the solvent. $J_1$ is the first order 
    57 Bessel function. 
    58  
    59 To provide easy access to the orientation of the cylinder, we define the 
    60 axis of the cylinder using two angles $\theta$ and $\phi$. Those angles 
    61 are defined in Figure :num:`figure #CylinderModel-orientation`. 
    62  
    63 .. _CylinderModel-orientation: 
    64  
    65 .. figure:: img/image061.JPG 
    66  
    67     Definition of the angles for oriented cylinders. 
    68  
    69 .. figure:: img/image062.JPG 
    70  
    71     Examples of the angles for oriented pp against the detector plane. 
    72  
    73 NB: The 2nd virial coefficient of the cylinder is calculated based on the 
    74 radius and length values, and used as the effective radius for $S(Q)$ 
    75 when $P(Q) \cdot S(Q)$ is applied. 
    76  
    77 The returned value is scaled to units of |cm^-1| and the parameters of 
    78 the CylinderModel are the following: 
    79  
    80 %(parameters)s 
    81  
    82 The output of the 1D scattering intensity function for randomly oriented 
    83 cylinders is then given by 
    84  
    85 .. math:: 
    86  
    87     P(q) = \frac{\text{scale}}{V} 
    88         \int_0^{\pi/2} f^2(q,\alpha) \sin \alpha d\alpha + \text{background} 
    89  
    90 The *theta* and *phi* parameters are not used for the 1D output. Our 
    91 implementation of the scattering kernel and the 1D scattering intensity 
    92 use the c-library from NIST. 
    93  
    94 Validation of the CylinderModel 
    95 ------------------------------- 
    96  
    97 Validation of our code was done by comparing the output of the 1D model 
    98 to the output of the software provided by the NIST (Kline, 2006). 
    99 Figure :num:`figure #CylinderModel-compare` shows a comparison of 
    100 the 1D output of our model and the output of the NIST software. 
    101  
    102 .. _CylinderModel-compare: 
    103  
    104 .. figure:: img/image065.JPG 
    105  
    106     Comparison of the SasView scattering intensity for a cylinder with the 
    107     output of the NIST SANS analysis software. 
    108     The parameters were set to: *Scale* = 1.0, *Radius* = 20 |Ang|, 
    109     *Length* = 400 |Ang|, *Contrast* = 3e-6 |Ang^-2|, and 
    110     *Background* = 0.01 |cm^-1|. 
    111  
    112 In general, averaging over a distribution of orientations is done by 
    113 evaluating the following 
    114  
    115 .. math:: 
    116  
    117     P(q) = \int_0^{\pi/2} d\phi 
    118         \int_0^\pi p(\theta, \phi) P_0(q,\alpha) \sin \theta d\theta 
    119  
    120  
    121 where $p(\theta,\phi)$ is the probability distribution for the orientation 
    122 and $P_0(q,\alpha)$ is the scattering intensity for the fully oriented 
    123 system. Since we have no other software to compare the implementation of 
    124 the intensity for fully oriented cylinders, we can compare the result of 
    125 averaging our 2D output using a uniform distribution $p(\theta, \phi) = 1.0$. 
    126 Figure :num:`figure #CylinderModel-crosscheck` shows the result of 
    127 such a cross-check. 
    128  
    129 .. _CylinderModel-crosscheck: 
    130  
    131 .. figure:: img/image066.JPG 
    132  
    133     Comparison of the intensity for uniformly distributed cylinders 
    134     calculated from our 2D model and the intensity from the NIST SANS 
    135     analysis software. 
    136     The parameters used were: *Scale* = 1.0, *Radius* = 20 |Ang|, 
    137     *Length* = 400 |Ang|, *Contrast* = 3e-6 |Ang^-2|, and 
    138     *Background* = 0.0 |cm^-1|. 
    139  
    140 DOCUMENTATION END 
    141 */ 
    1421real form_volume(real radius, real length); 
    1432real Iq(real q, real sld, real solvent_sld, real radius, real length); 
    1443real Iqxy(real qx, real qy, real sld, real solvent_sld, real radius, real length, real theta, real phi); 
    145  
    1464 
    1475real form_volume(real radius, real length) 

  • sasmodels/models/cylinder.py

    r32c160a ra7684e5  
     1# Note: model title and parameter table are inserted automatically 
    12r""" 
    2 CylinderModel 
    3 ============= 
    4  
    5 This model provides the form factor for a right circular cylinder with uniform 
    6 scattering length density. The form factor is normalized by the particle volume. 
     3The form factor is normalized by the particle volume. 
    74 
    85For information about polarised and magnetic scattering, click here_. 
    … …  
    3835.. _CylinderModel-orientation: 
    3936 
    40 .. figure:: img/image061.JPG 
     37.. figure:: img/image061.JPG   (should be img/cylinder-1.jpg, or img/cylinder-orientation.jpg) 
    4138 
    4239    Definition of the angles for oriented cylinders. 
    … …  
    4946radius and length values, and used as the effective radius for $S(Q)$ 
    5047when $P(Q) \cdot S(Q)$ is applied. 
    51  
    52 The returned value is scaled to units of |cm^-1| and the parameters of 
    53 the CylinderModel are the following: 
    54  
    55 %(parameters)s 
    5648 
    5749The output of the 1D scattering intensity function for randomly oriented 
    … …  
    6759use the c-library from NIST. 
    6860 
    69 Validation of the CylinderModel 
    70 ------------------------------- 
     61Validation 
     62---------- 
    7163 
    7264Validation of our code was done by comparing the output of the 1D model 
    … …  
    116108from numpy import pi, inf 
    117109 
     110name = "cylinder" 
     111title = "Right circular cylinder with uniform scattering length density." 
     112description = """ 
     113     f(q)= 2*(sldCyl - sldSolv)*V*sin(qLcos(alpha/2)) 
     114            /[qLcos(alpha/2)]*J1(qRsin(alpha/2))/[qRsin(alpha)] 
     115 
     116            P(q,alpha)= scale/V*f(q)^(2)+background 
     117            V: Volume of the cylinder 
     118            R: Radius of the cylinder 
     119            L: Length of the cylinder 
     120            J1: The bessel function 
     121            alpha: angle betweenthe axis of the 
     122            cylinder and the q-vector for 1D 
     123            :the ouput is P(q)=scale/V*integral 
     124            from pi/2 to zero of... 
     125            f(q)^(2)*sin(alpha)*dalpha+ bkg 
     126    """ 
     127 
     128parameters = [ 
     129#   [ "name", "units", default, [lower, upper], "type", 
     130#     "description" ], 
     131    [ "sld", "1e-6/Ang^2", 4, [-inf,inf], "", 
     132      "Cylinder scattering length density" ], 
     133    [ "solvent_sld", "1e-6/Ang^2", 1, [-inf,inf], "", 
     134      "Solvent scattering length density" ], 
     135    [ "radius", "Ang",  20, [0, inf], "volume", 
     136      "Cylinder radius" ], 
     137    [ "length", "Ang",  400, [0, inf], "volume", 
     138      "Cylinder length" ], 
     139    [ "theta", "degrees", 60, [-inf, inf], "orientation", 
     140      "In plane angle" ], 
     141    [ "phi", "degrees", 60, [-inf, inf], "orientation", 
     142      "Out of plane angle" ], 
     143    ] 
     144 
     145source = [ "lib/J1.c", "lib/gauss76.c", "lib/cylkernel.c", "cylinder.c"] 
     146 
    118147def ER(radius, length): 
    119148    ddd = 0.75*radius*(2*radius*length + (length+radius)*(length+pi*radius)) 
    120149    return 0.5 * (ddd)**(1./3.) 
    121150 
    122 INFO = { 
    123     "name": "cylinder", 
    124     "title": "Cylinder with uniform scattering length density", 
    125     "source": [ "lib/J1.c", "lib/gauss76.c", "lib/cylkernel.c", "cylinder.c"], 
    126     "parameters": [ 
    127     #   [ "name", "units", default, [lower, upper], "type", 
    128     #     "description" ], 
    129         [ "sld", "1e-6/Ang^2", 4, [-inf,inf], "", 
    130           "Cylinder scattering length density" ], 
    131         [ "solvent_sld", "1e-6/Ang^2", 1, [-inf,inf], "", 
    132           "Solvent scattering length density" ], 
    133         [ "radius", "Ang",  20, [0, inf], "volume", 
    134           "Cylinder radius" ], 
    135         [ "length", "Ang",  400, [0, inf], "volume", 
    136           "Cylinder length" ], 
    137         [ "theta", "degrees", 60, [-inf, inf], "orientation", 
    138           "In plane angle" ], 
    139         [ "phi", "degrees", 60, [-inf, inf], "orientation", 
    140           "Out of plane angle" ], 
    141         ], 
    142     "description": """ 
    143          f(q)= 2*(sldCyl - sldSolv)*V*sin(qLcos(alpha/2)) 
    144                 /[qLcos(alpha/2)]*J1(qRsin(alpha/2))/[qRsin(alpha)] 
    145  
    146                 P(q,alpha)= scale/V*f(q)^(2)+background 
    147                 V: Volume of the cylinder 
    148                 R: Radius of the cylinder 
    149                 L: Length of the cylinder 
    150                 J1: The bessel function 
    151                 alpha: angle betweenthe axis of the 
    152                 cylinder and the q-vector for 1D 
    153                 :the ouput is P(q)=scale/V*integral 
    154                 from pi/2 to zero of... 
    155                 f(q)^(2)*sin(alpha)*dalpha+ bkg 
    156         """, 
    157     "ER": ER, 
    158     } 
    159  

  • sasmodels/models/cylinder_clone.py

    r32c160a ra7684e5  
    118118name = "CylinderModel" 
    119119title = "Cylinder with uniform scattering length density" 
    120 source = [ "lib/J1.c", "lib/gauss76.c", "lib/cylkernel.c", "cylinder_clone.c"] 
     120description = """\ 
     121         f(q)= 2*(sldCyl - sldSolv)*V*sin(qLcos(alpha/2)) 
     122                /[qLcos(alpha/2)]*J1(qRsin(alpha/2))/[qRsin(alpha)] 
     123 
     124                P(q,alpha)= scale/V*f(q)^(2)+background 
     125                V: Volume of the cylinder 
     126                R: Radius of the cylinder 
     127                L: Length of the cylinder 
     128                J1: The bessel function 
     129                alpha: angle betweenthe axis of the 
     130                cylinder and the q-vector for 1D 
     131                :the ouput is P(q)=scale/V*integral 
     132                from pi/2 to zero of... 
     133                f(q)^(2)*sin(alpha)*dalpha+ bkg 
     134""" 
     135 
    121136parameters = [ 
    122137    #   [ "name", "units", default, [lower, upper], "type", 
    … …  
    135150      "Out of plane angle" ], 
    136151    ] 
    137 description = """\ 
    138          f(q)= 2*(sldCyl - sldSolv)*V*sin(qLcos(alpha/2)) 
    139                 /[qLcos(alpha/2)]*J1(qRsin(alpha/2))/[qRsin(alpha)] 
    140  
    141                 P(q,alpha)= scale/V*f(q)^(2)+background 
    142                 V: Volume of the cylinder 
    143                 R: Radius of the cylinder 
    144                 L: Length of the cylinder 
    145                 J1: The bessel function 
    146                 alpha: angle betweenthe axis of the 
    147                 cylinder and the q-vector for 1D 
    148                 :the ouput is P(q)=scale/V*integral 
    149                 from pi/2 to zero of... 
    150                 f(q)^(2)*sin(alpha)*dalpha+ bkg 
    151 """ 
     152source = [ "lib/J1.c", "lib/gauss76.c", "lib/cylkernel.c", "cylinder_clone.c"] 
    152153 
    153154def ER(radius, length): 

  • sasmodels/sasview_model.py

    r32c160a ra7684e5  
    88    model =  opencl_model(kernel_module, dtype=dtype) 
    99    def __init__(self, multfactor=1): 
    10         SasviewModel.__init__(self, self.kernel) 
    11     attrs = dict(__init__=__init__, kernel=model) 
     10        SasviewModel.__init__(self, model) 
     11    attrs = dict(__init__=__init__) 
    1212    ConstructedModel = type(model.info['name'],  (SasviewModel,), attrs) 
    13     #class ConstructedModel(SasviewModel): 
    14     #    kernel = model 
    15     #    def __init__(self, multfactor=1): 
    16     #        SasviewModel.__init__(self, self.kernel) 
    17     #ConstructedModel.__name__ = model.info['name'] 
    1813    return ConstructedModel 
    1914 
Note: See TracChangeset for help on using the changeset viewer.