3.6. Model parser

«  3.5. Annotate exceptions   ::   Contents   ::   3.7. OpenCL model evaluator  »

3.6. Model parser

3.6.1. sasmodels.generate

SAS model constructor.

Small angle scattering models are defined by a set of kernel functions:

Iq(q, p1, p2, ...) returns the scattering at q for a form with particular dimensions averaged over all orientations.

Iqxy(qx, qy, p1, p2, ...) returns the scattering at qx,qy for a form with particular dimensions for a single orientation.

Imagnetic(qx, qy, result[], p1, p2, ...) returns the scattering for the polarized neutron spin states (up-up, up-down, down-up, down-down) for a form with particular dimensions for a single orientation.

form_volume(p1, p2, ...) returns the volume of the form with particular dimension.

ER(p1, p2, ...) returns the effective radius of the form with particular dimensions.

VR(p1, p2, ...) returns the volume ratio for core-shell style forms.

These functions are defined in a kernel module .py script and an associated set of .c files. The model constructor will use them to create models with polydispersity across volume and orientation parameters, and provide scale and background parameters for each model.

Iq, Iqxy, Imagnetic and form_volume should be stylized C-99 functions written for OpenCL. All functions need prototype declarations even if the are defined before they are used. OpenCL does not support #include preprocessor directives, so instead the list of includes needs to be given as part of the metadata in the kernel module definition. The included files should be listed using a path relative to the kernel module, or if using “lib/file.c” if it is one of the standard includes provided with the sasmodels source. The includes need to be listed in order so that functions are defined before they are used.

Floating point values should be declared as double. For single precision calculations, double will be replaced by float. The single precision conversion will also tag floating point constants with “f” to make them single precision constants. When using integral values in floating point expressions, they should be expressed as floating point values by including a decimal point. This includes 0., 1. and 2.

OpenCL has a sincos function which can improve performance when both the sin and cos values are needed for a particular argument. Since this function does not exist in C99, all use of sincos should be replaced by the macro SINCOS(value,sn,cn) where sn and cn are previously declared double variables. When compiled for systems without OpenCL, SINCOS will be replaced by sin and cos calls. If value is an expression, it will appear twice in this case; whether or not it will be evaluated twice depends on the quality of the compiler.

If the input parameters are invalid, the scattering calculator should return a negative number. Particularly with polydispersity, there are some sets of shape parameters which lead to nonsensical forms, such as a capped cylinder where the cap radius is smaller than the cylinder radius. The polydispersity calculation will ignore these points, effectively chopping the parameter weight distributions at the boundary of the infeasible region. The resulting scattering will be set to background. This will work correctly even when polydispersity is off.

ER and VR are python functions which operate on parameter vectors. The constructor code will generate the necessary vectors for computing them with the desired polydispersity.

The available kernel parameters are defined as a list, with each parameter defined as a sublist with the following elements:

name is the name that will be used in the call to the kernel function and the name that will be displayed to the user. Names should be lower case, with words separated by underscore. If acronyms are used, the whole acronym should be upper case.

units should be one of degrees for angles, Ang for lengths, 1e-6/Ang^2 for SLDs.

default value will be the initial value for the model when it is selected, or when an initial value is not otherwise specified.

[lb, ub] are the hard limits on the parameter value, used to limit the polydispersity density function. In the fit, the parameter limits given to the fit are the limits on the central value of the parameter. If there is polydispersity, it will evaluate parameter values outside the fit limits, but not outside the hard limits specified in the model. If there are no limits, use +/-inf imported from numpy.

type indicates how the parameter will be used. “volume” parameters will be used in all functions. “orientation” parameters will be used in Iqxy and Imagnetic. “magnetic* parameters will be used in Imagnetic only. If type is the empty string, the parameter will be used in all of Iq, Iqxy and Imagnetic.

description is a short description of the parameter. This will be displayed in the parameter table and used as a tool tip for the parameter value in the user interface.

The kernel module must set variables defining the kernel meta data:

name is the model name

title is a short description of the model, suitable for a tool tip, or a one line model summary in a table of models.

description is an extended description of the model to be displayed while the model parameters are being edited.

parameters is the list of parameters. Parameters in the kernel functions must appear in the same order as they appear in the parameters list. Two additional parameters, scale and background are added to the beginning of the parameter list. They will show up in the documentation as model parameters, but they are never sent to the kernel functions.

source is the list of C-99 source files that must be joined to create the OpenCL kernel functions. The files defining the functions need to be listed before the files which use the functions.

ER is a python function defining the effective radius. If it is not present, the effective radius is 0.

VR is a python function defining the volume ratio. If it is not present, the volume ratio is 1.

form_volume, Iq, Iqxy, Imagnetic are strings containing the C source code for the body of the volume, Iq, and Iqxy functions respectively. These can also be defined in the last source file.

Iq and Iqxy also be instead be python functions defining the kernel. If they are marked as Iq.vectorized = True then the kernel is passed the entire q vector at once, otherwise it is passed values one q at a time. The performance improvement of this step is significant.

An info dictionary is constructed from the kernel meta data and returned to the caller.

Additional fields can be defined in the kernel definition file that are not needed for sas modelling.

demo is a dictionary of parameter=value defining a set of parameters to use by default when compare is called.

oldname is the name of the model in sasview before sasmodels was split into its own package, and oldpars is a dictionary of parameter: old_parameter pairs defining the new names for the parameters. This is used by compare to check the values of the new model against the values of the old model before you are ready to add the new model to sasmodels.

The model evaluator, function call sequence consists of q inputs and the return vector, followed by the loop value/weight vector, followed by the values for the non-polydisperse parameters, followed by the lengths of the polydispersity loops. To construct the call for 1D models, the categories fixed-1d and pd-1d list the names of the parameters of the non-polydisperse and the polydisperse parameters respectively. Similarly, fixed-2d and pd-2d provide parameter names for 2D models. The pd-rel category is a set of those parameters which give polydispersitiy as a portion of the value (so a 10% length dispersity would use a polydispersity value of 0.1) rather than absolute dispersity such as an angle plus or minus 15 degrees.

The volume category lists the volume parameters in order for calls to volume within the kernel (used for volume normalization) and for calls to ER and VR for effective radius and volume ratio respectively.

The orientation and magnetic categories list the orientation and magnetic parameters. These are used by the sasview interface. The blank category is for parameters such as scale which don’t have any other marking.

The doc string at the start of the kernel module will be used to construct the model documentation web pages. Embedded figures should appear in the subdirectory “img” beside the model definition, and tagged with the kernel module name to avoid collision with other models. Some file systems are case-sensitive, so only use lower case characters for file names and extensions.

The function make() loads the metadata from the module and returns the kernel source. The function doc() extracts the doc string and adds the parameter table to the top. The function sources() returns a list of files required by the model.


Build an OpenCL/ctypes function from the definition in kernel_module.

The module can be loaded with a normal python import statement if you know which module you need, or with __import__(‘sasmodels.model.’+name) if the name is in a string.


Return the documentation for the model.


Return a list of the sources file paths for the module.


Convert code from double precision to single precision.

«  3.5. Annotate exceptions   ::   Contents   ::   3.7. OpenCL model evaluator  »