sasmodels package

Subpackages

• sasmodels.custom package
  • Module contents
    • Custom Models

Submodules

sasmodels.alignment module

GPU data alignment.

Some web sites say that maximizing performance for OpenCL code requires aligning data on certain memory boundaries. The following functions provide this service:

align_data() aligns an existing array, returning a new array of the correct alignment.

align_empty() to create an empty array of the correct alignment.

Set alignment to gpu environment attribute boundary.

Note: This code is unused. So far, tests have not demonstrated any improvement from forcing correct alignment. The tests should be repeated with arrays forced away from the target boundaries to decide whether it is really required.

sasmodels.alignment.align_data(x, dtype, alignment=128)

Return a copy of an array on the alignment boundary.

sasmodels.alignment.align_empty(shape, dtype, alignment=128)

Return an empty array aligned on the alignment boundary.

sasmodels.bumps_model module

Wrap sasmodels for direct use by bumps.

Model is a wrapper for the sasmodels kernel which defines a bumps Parameter box for each kernel parameter. Model accepts keyword arguments to set the initial value for each parameter.

Experiment combines the Model function with a data file loaded by the sasview data loader. Experiment takes a cutoff parameter controlling how far the polydispersity integral extends.

class sasmodels.bumps_model.Model(model, **kwargs)

Bases: object

Bumps wrapper for a SAS model.

model is a runnable module as returned from core.load_model().

cutoff is the polydispersity weight cutoff.

Any additional key=value pairs are model dependent parameters.

parameters()

Return a dictionary of parameters objects for the parameters, excluding polydispersity distribution type.

state()

Return a dictionary of current values for all the parameters, including polydispersity distribution type.

class sasmodels.bumps_model.Experiment(data, model, cutoff=1e-05, name=None, extra_pars=None)

Bases: sasmodels.direct_model.DataMixin

Bumps wrapper for a SAS experiment.

data is a data.Data1D, data.Data2D or data.SesansData object. Use data.empty_data1D() or data.empty_data2D() to define \(q, \Delta q\) calculation points for displaying the SANS curve when there is no measured data.

model is a Model object.

cutoff is the integration cutoff, which avoids computing the the SAS model where the polydispersity weight is low.

The resulting model can be used directly in a Bumps FitProblem call.

nllf()

Return the negative log likelihood of seeing data given the model parameters, up to a normalizing constant which depends on the data uncertainty.

numpoints()

Return the number of data points

parameters()

Return a dictionary of parameters

plot(view=None)

Plot the data and residuals.

residuals()

Return theory minus data normalized by uncertainty.

resolution

resolution.Resolution applied to the data, if any.

save(basename)

Save the model parameters and data into a file.

Not Implemented except for sesans fits.

simulate_data(noise=None)

Generate simulated data.

theory()

Return the theory corresponding to the model parameters.

This method uses lazy evaluation, and requires model.update() to be called when the parameters have changed.

update()

Call when model parameters have changed and theory needs to be recalculated.

sasmodels.compare module

Program to compare models using different compute engines.

This program lets you compare results between OpenCL and DLL versions of the code and between precision (half, fast, single, double, quad), where fast precision is single precision using native functions for trig, etc., and may not be completely IEEE 754 compliant. This lets make sure that the model calculations are stable, or if you need to tag the model as double precision only.

Run using “./sascomp -h” in the sasmodels root to see the command line options. To run from from an installed version of sasmodels, use “python -m sasmodels.compare -h”.

Note that there is no way within sasmodels to select between an OpenCL CPU device and a GPU device, but you can do so by setting the SAS_OPENCL environment variable. Start a python interpreter and enter:

import pyopencl as cl
cl.create_some_context()

This will prompt you to select from the available OpenCL devices and tell you which string to use for the SAS_OPENCL variable. On Windows you will need to remove the quotes.

class sasmodels.compare.Explore(opts)

Bases: object

Bumps wrapper for a SAS model comparison.

The resulting object can be used as a Bumps fit problem so that parameters can be adjusted in the GUI, with plots updated on the fly.

model_update()

Respond to signal that model parameters have been changed.

nllf()

Return cost.

numpoints()

Return the number of points.

parameters()

Return a dictionary of parameters.

plot(view='log')

Plot the data and residuals.

revert_values()

Restore starting values of the parameters.

sasmodels.compare.MATH = {'acos': <built-in function acos>, 'acosh': <built-in function acosh>, 'asin': <built-in function asin>, 'asinh': <built-in function asinh>, 'atan': <built-in function atan>, 'atan2': <built-in function atan2>, 'atanh': <built-in function atanh>, 'ceil': <built-in function ceil>, 'copysign': <built-in function copysign>, 'cos': <built-in function cos>, 'cosh': <built-in function cosh>, 'degrees': <built-in function degrees>, 'e': 2.718281828459045, 'erf': <built-in function erf>, 'erfc': <built-in function erfc>, 'exp': <built-in function exp>, 'expm1': <built-in function expm1>, 'fabs': <built-in function fabs>, 'factorial': <built-in function factorial>, 'floor': <built-in function floor>, 'fmod': <built-in function fmod>, 'frexp': <built-in function frexp>, 'fsum': <built-in function fsum>, 'gamma': <built-in function gamma>, 'gcd': <built-in function gcd>, 'hypot': <built-in function hypot>, 'inf': inf, 'isclose': <built-in function isclose>, 'isfinite': <built-in function isfinite>, 'isinf': <built-in function isinf>, 'isnan': <built-in function isnan>, 'ldexp': <built-in function ldexp>, 'lgamma': <built-in function lgamma>, 'log': <built-in function log>, 'log10': <built-in function log10>, 'log1p': <built-in function log1p>, 'log2': <built-in function log2>, 'modf': <built-in function modf>, 'nan': nan, 'pi': 3.141592653589793, 'pow': <built-in function pow>, 'radians': <built-in function radians>, 'sin': <built-in function sin>, 'sinh': <built-in function sinh>, 'sqrt': <built-in function sqrt>, 'tan': <built-in function tan>, 'tanh': <built-in function tanh>, 'tau': 6.283185307179586, 'trunc': <built-in function trunc>}

list of math functions for use in evaluating parameters

sasmodels.compare.build_math_context()

build dictionary of functions from math module

sasmodels.compare.columnize(items, indent='', width=None)

Format a list of strings into columns.

Returns a string with carriage returns ready for printing.

sasmodels.compare.compare(opts, limits=None, maxdim=None)

Preform a comparison using options from the command line.

limits are the display limits on the graph, either to set the y-axis for 1D or to set the colormap scale for 2D. If None, then they are inferred from the data and returned. When exploring using Bumps, the limits are set when the model is initially called, and maintained as the values are adjusted, making it easier to see the effects of the parameters.

maxdim DEPRECATED Use opts[‘maxdim’] instead.

sasmodels.compare.constrain_pars(model_info, pars)

Restrict parameters to valid values.

This includes model specific code for models such as capped_cylinder which need to support within model constraints (cap radius more than cylinder radius in this case).

Warning: this updates the pars dictionary in place.

sasmodels.compare.delay(dt)

Return number date-time delta as number seconds

sasmodels.compare.eval_ctypes(model_info, data, dtype='double', cutoff=0.0)

Return a model calculator using the DLL calculation engine.

sasmodels.compare.eval_opencl(model_info, data, dtype='single', cutoff=0.0)

Return a model calculator using the OpenCL calculation engine.

sasmodels.compare.explore(opts)

explore the model using the bumps gui.

sasmodels.compare.get_pars(model_info)

Extract default parameters from the model definition.

sasmodels.compare.isnumber(s)

Return True if string contains an int or float

sasmodels.compare.limit_dimensions(model_info, pars, maxdim)

Limit parameters of units of Ang to maxdim.

sasmodels.compare.main(*argv)

Main program.

sasmodels.compare.make_data(opts)

Generate an empty dataset, used with the model to set Q points and resolution.

opts contains the options, with ‘qmax’, ‘nq’, ‘res’, ‘accuracy’, ‘is2d’ and ‘view’ parsed from the command line.

sasmodels.compare.make_engine(model_info, data, dtype, cutoff, ngauss=0)

Generate the appropriate calculation engine for the given datatype.

Datatypes with ‘!’ appended are evaluated using external C DLLs rather than OpenCL.

sasmodels.compare.parameter_range(p, v)

Choose a parameter range based on parameter name and initial value.

sasmodels.compare.parlist(model_info, pars, is2d)

Format the parameter list for printing.

sasmodels.compare.parse_opts(argv)

Parse command line options.

sasmodels.compare.parse_pars(opts, maxdim=None)

Generate parameter sets for base and comparison models.

Returns a pair of parameter dictionaries.

The default parameter values come from the model, or a randomized model if a seed value is given. Next, evaluate any parameter expressions, constraining the value of the parameter within and between models.

Note: When generating random parameters, the seed must already be set with a call to np.random.seed(opts[‘seed’]).

opts controls the parameter generation:

opts = {
    'info': (model_info 1, model_info 2),
    'seed': -1,         # if seed>=0 then randomize parameters
    'mono': False,      # force monodisperse random parameters
    'magnetic': False,  # force nonmagetic random parameters
    'maxdim': np.inf,   # limit particle size to maxdim for random pars
    'values': ['par=expr', ...],  # override parameter values in model
    'show_pars': False, # Show parameter values
    'is2d': False,      # Show values for orientation parameters
}

The values of par=expr are evaluated approximately as:

import numpy as np
from math import *
from parameter_set import *

parameter_set.par = eval(expr)

That is, you can use arbitrary python math expressions including the functions defined in the math library and the numpy library. You can also use the existing parameter values, which will either be the model defaults or the randomly generated values if seed is non-negative.

To compare different values of the same parameter, use par=expr,expr. The first parameter set will have the values from the first expression and the second parameter set will have the values from the second expression. Note that the second expression is evaluated using the values from the first expression, which allows things like:

length=2*radius,length+3

which will compare length to length+3 when length is set to 2*radius.

maxdim DEPRECATED Use opts[‘maxdim’] instead.

sasmodels.compare.plot_models(opts, result, limits=None, setnum=0)

Plot the results from run_models().

sasmodels.compare.plot_profile(model_info, label='base', **args)

Plot the profile returned by the model profile method.

model_info defines model parameters, etc.

label is the legend label for the plotted line.

args are parameter=value pairs for the model profile function.

sasmodels.compare.print_models(kind=None)

Print the list of available models in columns.

class sasmodels.compare.push_seed(seed=None)

Bases: object

Set the seed value for the random number generator.

When used in a with statement, the random number generator state is restored after the with statement is complete.

Parameters:

seed : int or array_like, optional

Seed for RandomState

Example:

Seed can be used directly to set the seed:

>>> from numpy.random import randint
>>> push_seed(24)
<...push_seed object at...>
>>> print(randint(0,1000000,3))
[242082    899 211136]

Seed can also be used in a with statement, which sets the random number generator state for the enclosed computations and restores it to the previous state on completion:

>>> with push_seed(24):
...    print(randint(0,1000000,3))
[242082    899 211136]

Using nested contexts, we can demonstrate that state is indeed restored after the block completes:

>>> with push_seed(24):
...    print(randint(0,1000000))
...    with push_seed(24):
...        print(randint(0,1000000,3))
...    print(randint(0,1000000))
242082
[242082    899 211136]
899

The restore step is protected against exceptions in the block:

>>> with push_seed(24):
...    print(randint(0,1000000))
...    try:
...        with push_seed(24):
...            print(randint(0,1000000,3))
...            raise Exception()
...    except Exception:
...        print("Exception raised")
...    print(randint(0,1000000))
242082
[242082    899 211136]
Exception raised
899

sasmodels.compare.randomize_pars(model_info, pars, maxdim=inf, is2d=False)

Generate random values for all of the parameters.

Valid ranges for the random number generator are guessed from the name of the parameter; this will not account for constraints such as cap radius greater than cylinder radius in the capped_cylinder model, so constrain_pars() needs to be called afterward..

sasmodels.compare.run_models(opts, verbose=False)

Process a parameter set, return calculation results and times.

sasmodels.compare.set_beam_stop(data, radius, outer=None)

Add a beam stop of the given radius. If outer, make an annulus.

sasmodels.compare.set_spherical_integration_parameters(opts, steps)

Set integration parameters for spherical integration over the entire surface in theta-phi coordinates.

sasmodels.compare.show_docs(opts)

show html docs for the model

sasmodels.compare.suppress_magnetism(pars)

Complete eliminate magnetism of the model to test models more quickly.

sasmodels.compare.suppress_pd(pars)

Complete eliminate polydispersity of the model to test models more quickly.

sasmodels.compare.tic()

Timer function.

Use “toc=tic()” to start the clock and “toc()” to measure a time interval.

sasmodels.compare.time_calculation(calculator, pars, evals=1)

Compute the average calculation time over N evaluations.

An additional call is generated without polydispersity in order to initialize the calculation engine, and make the average more stable.

sasmodels.compare_many module

Program to compare results from many random parameter sets for a given model.

The result is a comma separated value (CSV) table that can be redirected from standard output into a file and loaded into a spreadsheet.

The models are compared for each parameter set and if the difference is greater than expected for that precision, the parameter set is labeled as bad and written to the output, along with the random seed used to generate that parameter value. This seed can be used with compare to reload and display the details of the model.

sasmodels.compare_many.calc_stats(target, value, index)

Calculate statistics between the target value and the computed value.

target and value are the vectors being compared, with the difference normalized by target to get relative error. Only the elements listed in index are used, though index may be and empty slice defined by slice(None, None).

Returns:

maxrel the maximum relative difference

rel95 the relative difference with the 5% biggest differences ignored

maxabs the maximum absolute difference for the 5% biggest differences

maxval the maximum value for the 5% biggest differences

sasmodels.compare_many.compare_instance(name, data, index, N=1, mono=True, cutoff=1e-05, base='single', comp='double')

Compare the model under different calculation engines.

name is the name of the model.

data is the data object giving \(q, \Delta q\) calculation points.

index is the active set of points.

N is the number of comparisons to make.

cutoff is the polydispersity weight cutoff to make the calculation a little bit faster.

base and comp are the names of the calculation engines to compare.

sasmodels.compare_many.main(argv)

Main program.

sasmodels.compare_many.print_column_headers(pars, parts)

Generate column headers for the differences and for the parameters, and print them to standard output.

sasmodels.compare_many.print_help()

Print usage string, the option description and the list of available models.

sasmodels.compare_many.print_usage()

Print the command usage string.

sasmodels.conversion_table module

Parameter conversion table

CONVERSION_TABLE gives the old model name and a dictionary of old parameter names for each parameter in sasmodels. This is used by convert to determine the equivalent parameter set when comparing a sasmodels model to the models defined in previous versions of SasView and sasmodels. This is now versioned based on the version number of SasView.

When any sasmodels parameter or model name is changed, this must be modified to account for that.

Usage:

<old_Sasview_version> : {
    <new_model_name> : [
        <old_model_name> ,
        {
            <new_param_name_1> : <old_param_name_1>,
            ...
            <new_param_name_n> : <old_param_name_n>
        }
    ]
}

Any future parameter and model name changes can and should be given in this table for future compatibility.

sasmodels.convert module

Convert models to and from sasview.

sasmodels.convert.constrain_new_to_old(model_info, pars)

Restrict parameter values to those that will match sasview.

sasmodels.convert.convert_model(name, pars, use_underscore=False, model_version=(3, 1, 2))

Convert model from old style parameter names to new style.

sasmodels.convert.revert_name(model_info)

Translate model name back to the name used in SasView 3.x

sasmodels.convert.revert_pars(model_info, pars)

Convert model from new style parameter names to old style.

sasmodels.convert.test_backward_forward()

Test conversion of model parameters from 4.x to 3.x and back.

sasmodels.core module

Core model handling routines.

sasmodels.core.list_models(kind=None)

Return the list of available models on the model path.

kind can be one of the following:

• all: all models
• py: python models only
• c: c models only
• single: c models which support single precision
• double: c models which require double precision
• opencl: c models which run in opencl
• dll: c models which do not run in opencl
• 1d: models without orientation
• 2d: models with orientation
• magnetic: models supporting magnetic sld
• nommagnetic: models without magnetic parameter

For multiple conditions, combine with plus. For example, c+single+2d would return all oriented models implemented in C which can be computed accurately with single precision arithmetic.

sasmodels.core.load_model(model_name, dtype=None, platform='ocl')

Load model info and build model.

model_name is the name of the model, or perhaps a model expression such as sphere*hardsphere or sphere+cylinder.

dtype and platform are given by build_model().

sasmodels.core.load_model_info(model_string)

Load a model definition given the model name.

model_string is the name of the model, or perhaps a model expression such as sphere*cylinder or sphere+cylinder. Use ‘@’ for a structure factor product, e.g. sphere@hardsphere. Custom models can be specified by prefixing the model name with ‘custom.’, e.g. ‘custom.MyModel+sphere’.

This returns a handle to the module defining the model. This can be used with functions in generate to build the docs or extract model info.

sasmodels.core.build_model(model_info, dtype=None, platform='ocl')

Prepare the model for the default execution platform.

This will return an OpenCL model, a DLL model or a python model depending on the model and the computing platform.

model_info is the model definition structure returned from load_model_info().

dtype indicates whether the model should use single or double precision for the calculation. Choices are ‘single’, ‘double’, ‘quad’, ‘half’, or ‘fast’. If dtype ends with ‘!’, then force the use of the DLL rather than OpenCL for the calculation.

platform should be “dll” to force the dll to be used for C models, otherwise it uses the default “ocl”.

sasmodels.core.precompile_dlls(path, dtype='double')

Precompile the dlls for all builtin models, returning a list of dll paths.

path is the directory in which to save the dlls. It will be created if it does not already exist.

This can be used when build the windows distribution of sasmodels which may be missing the OpenCL driver and the dll compiler.

sasmodels.core.reparameterize(base, parameters, translation, filename=None, title=None, insert_after=None, docs=None, name=None, source=None)

Reparameterize an existing model.

base is the original modelinfo. This cannot be a reparameterized model; only one level of reparameterization is supported.

parameters are the new parameter definitions that will be included in the model info.

translation is a string each line containing var = expr. The variable var can be a new intermediate value, or it can be a parameter from the base model that will be replace by the expression. The expression expr can be any C99 expression, including C-style if-expressions condition ? value1 : value2. Expressions can use any new or existing parameter that is not being replaced including intermediate values that are previously defined. Parameters can only be assigned once, never updated. C99 math functions are available, as well as any functions defined in the base model or included in source (see below).

filename is the filename for the replacement model. This is usually __file__, giving the path to the model file, but it could also be a nominal filename for translations defined on-the-fly.

title is the model title, which defaults to base.title plus ” (reparameterized)”.

insert_after controls parameter placement. By default, the new parameters replace the old parameters in their original position. Instead, you can provide a dictionary {‘par’: ‘newpar1,newpar2’} indicating that new parameters named newpar1 and newpar2 should be included in the table after the existing parameter par, or at the beginning if par is the empty string.

docs constains the doc string for the translated model, which by default references the base model and gives the translation text.

name is the model name (default = "constrained_" + base.name).

source is a list any additional C source files that should be included to define functions and constants used in the translation expressions. This will be included after all sources for the base model. Sources will only be included once, even if they are listed in both places, so feel free to list all dependencies for the helper function, such as “lib/polevl.c”.

sasmodels.data module

SAS data representations.

Plotting functions for data sets:

plot_data() plots the data file.

plot_theory() plots a calculated result from the model.

Wrappers for the sasview data loader and data manipulations:

load_data() loads a sasview data file.

set_beam_stop() masks the beam stop from the data.

set_half() selects the right or left half of the data, which can be useful for shear measurements which have not been properly corrected for path length and reflections.

set_top() cuts the top part off the data.

Empty data sets for evaluating models without data:

empty_data1D() creates an empty dataset, which is useful for plotting a theory function before the data is measured.

empty_data2D() creates an empty 2D dataset.

Note that the empty datasets use a minimal representation of the SasView objects so that models can be run without SasView on the path. You could also use these for your own data loader.

class sasmodels.data.Data1D(x=None, y=None, dx=None, dy=None)

Bases: object

1D data object.

Note that this definition matches the attributes from sasview, with some generic 1D data vectors and some SAS specific definitions. Some refactoring to allow consistent naming conventions between 1D, 2D and SESANS data would be helpful.

Attributes

x, dx: \(q\) vector and gaussian resolution

y, dy: \(I(q)\) vector and measurement uncertainty

mask: values to include in plotting/analysis

dxl: slit widths for slit smeared data, with dx ignored

qmin, qmax: range of \(q\) values in x

filename: label for the data line

_xaxis, _xunit: label and units for the x axis

_yaxis, _yunit: label and units for the y axis

xaxis(label, unit)

set the x axis label and unit

yaxis(label, unit)

set the y axis label and unit

class sasmodels.data.Data2D(x=None, y=None, z=None, dx=None, dy=None, dz=None)

Bases: object

2D data object.

Note that this definition matches the attributes from sasview. Some refactoring to allow consistent naming conventions between 1D, 2D and SESANS data would be helpful.

Attributes

qx_data, dqx_data: \(q_x\) matrix and gaussian resolution

qy_data, dqy_data: \(q_y\) matrix and gaussian resolution

data, err_data: \(I(q)\) matrix and measurement uncertainty

mask: values to exclude from plotting/analysis

qmin, qmax: range of \(q\) values in x

filename: label for the data line

_xaxis, _xunit: label and units for the x axis

_yaxis, _yunit: label and units for the y axis

_zaxis, _zunit: label and units for the y axis

Q_unit, I_unit: units for Q and intensity

x_bins, y_bins: grid steps in x and y directions

xaxis(label, unit)

set the x axis label and unit

yaxis(label, unit)

set the y axis label and unit

zaxis(label, unit)

set the y axis label and unit

class sasmodels.data.Detector(pixel_size=(None, None), distance=None)

Bases: object

Detector attributes.

class sasmodels.data.Sample

Bases: object

Sample attributes.

class sasmodels.data.SesansData(**kw)

Bases: sasmodels.data.Data1D

SESANS data object.

This is just Data1D with a wavelength parameter.

x is spin echo length and y is polarization (P/P0).

isSesans = True

class sasmodels.data.Source

Bases: object

Beam attributes.

class sasmodels.data.Vector(x=None, y=None, z=None)

Bases: object

3-space vector of x, y, z

sasmodels.data.demo()

Load and plot a SAS dataset.

sasmodels.data.empty_data1D(q, resolution=0.0, L=0.0, dL=0.0)

Create empty 1D data using the given q as the x value.

rms resolution \(\Delta q/q\) defaults to 0%. If wavelength L and rms wavelength divergence dL are defined, then resolution defines rms \(\Delta \theta/\theta\) for the lowest q, with \(\theta\) derived from \(q = 4\pi/\lambda \sin(\theta)\).

sasmodels.data.empty_data2D(qx, qy=None, resolution=0.0)

Create empty 2D data using the given mesh.

If qy is missing, create a square mesh with qy=qx.

resolution dq/q defaults to 5%.

sasmodels.data.load_data(filename, index=0)

Load data using a sasview loader.

sasmodels.data.plot_data(data, view=None, limits=None)

Plot data loaded by the sasview loader.

data is a sasview data object, either 1D, 2D or SESANS.

view is log or linear.

limits sets the intensity limits on the plot; if None then the limits are inferred from the data.

sasmodels.data.plot_theory(data, theory, resid=None, view=None, use_data=True, limits=None, Iq_calc=None)

Plot theory calculation.

data is needed to define the graph properties such as labels and units, and to define the data mask.

theory is a matrix of the same shape as the data.

view is log or linear

use_data is True if the data should be plotted as well as the theory.

limits sets the intensity limits on the plot; if None then the limits are inferred from the data.

Iq_calc is the raw theory values without resolution smearing

sasmodels.data.protect(func)

Decorator to wrap calls in an exception trapper which prints the exception and continues. Keyboard interrupts are ignored.

sasmodels.data.set_beam_stop(data, radius, outer=None)

Add a beam stop of the given radius. If outer, make an annulus.

sasmodels.data.set_half(data, half)

Select half of the data, either “right” or “left”.

sasmodels.data.set_top(data, cutoff)

Chop the top off the data, above cutoff.

sasmodels.details module

Kernel Call Details

When calling sas computational kernels with polydispersity there are a number of details that need to be sent to the caller. This includes the list of polydisperse parameters, the number of points in the polydispersity weight distribution, and which parameter is the “theta” parameter for polar coordinate integration. The CallDetails object maintains this data. Use make_details() to build a details object which can be passed to one of the computational kernels.

class sasmodels.details.CallDetails(model_info)

Bases: object

Manage the polydispersity information for the kernel call.

Conceptually, a polydispersity calculation is an integral over a mesh in n-D space where n is the number of polydisperse parameters. In order to keep the program responsive, and not crash the GPU, only a portion of the mesh is computed at a time. Meshes with a large number of points will therefore require many calls to the polydispersity loop. Restarting a nested loop in the middle requires that the indices of the individual mesh dimensions can be computed for the current loop location. This is handled by the pd_stride vector, with n//stride giving the loop index and n%stride giving the position in the sub loops.

One of the parameters may be the latitude. When integrating in polar coordinates, the total circumference decreases as latitude varies from pi r^2 at the equator to 0 at the pole, and the weight associated with a range of latitude values needs to be scaled by this circumference. This scale factor needs to be updated each time the theta value changes. theta_par indicates which of the values in the parameter vector is the latitude parameter, or -1 if there is no latitude parameter in the model. In practice, the normalization term cancels if the latitude is not a polydisperse parameter.

num_active

Number of active polydispersity loops

num_eval

Total size of the pd mesh

num_weights

Total length of all the weight vectors

parts = None

pd_length

Number of weights for each polydisperse parameter

pd_offset

Offsets for the individual weight vectors in the set of weights

pd_par

List of polydisperse parameters

pd_stride

Stride in the pd mesh for each pd dimension

show(values=None)

Print the polydispersity call details to the console

theta_par

Location of the theta parameter in the parameter vector

sasmodels.details.convert_magnetism(parameters, values)

Convert magnetism values from polar to rectangular coordinates.

Returns True if any magnetism is present.

sasmodels.details.correct_theta_weights(parameters, dispersity, weights)

Deprecated Theta weights will be computed in the kernel wrapper if they are needed.

If there is a theta parameter, update the weights of that parameter so that the cosine weighting required for polar integration is preserved.

Avoid evaluation strictly at the pole, which would otherwise send the weight to zero. This is probably not a problem in practice (if dispersity is +/- 90, then you probably should be using a 1-D model of the circular average).

Note: scale and background parameters are not include in the tuples for dispersity and weights, so index is parameters.theta_offset, not parameters.theta_offset+2

Returns updated weights vectors

sasmodels.details.dispersion_mesh(model_info, mesh)

Create a mesh grid of dispersion parameters and weights.

mesh is a list of (value, dispersity, weights), where the values are the individual parameter values, and (dispersity, weights) is the distribution of parameter values.

Only the volume parameters should be included in this list. Orientation parameters do not affect the calculation of effective radius or volume ratio. This is convenient since it avoids the distinction between value and dispersity that is present in orientation parameters but not shape parameters.

Returns [p1,p2,…],w where pj is a vector of values for parameter j and w is a vector containing the products for weights for each parameter set in the vector.

sasmodels.details.make_details(model_info, length, offset, num_weights)

Return a CallDetails object for a polydisperse calculation of the model defined by model_info. Polydispersity is defined by the length of the polydispersity distribution for each parameter and the offset of the distribution in the polydispersity array. Monodisperse parameters should use a polydispersity length of one with weight 1.0. num_weights is the total length of the polydispersity array.

sasmodels.details.make_kernel_args(kernel, mesh)

Converts (value, dispersity, weight) for each parameter into kernel pars.

Returns a CallDetails object indicating the polydispersity, a data object containing the different values, and the magnetic flag indicating whether any magnetic magnitudes are non-zero. Magnetic vectors (M0, phi, theta) are converted to rectangular coordinates (mx, my, mz).

sasmodels.direct_model module

Class interface to the model calculator.

Calling a model is somewhat non-trivial since the functions called depend on the data type. For 1D data the Iq kernel needs to be called, for 2D data the Iqxy kernel needs to be called, and for SESANS data the Iq kernel needs to be called followed by a Hankel transform. Before the kernel is called an appropriate q calculation vector needs to be constructed. This is not the simple q vector where you have measured the data since the resolution calculation will require values beyond the range of the measured data. After the calculation the resolution calculator must be called to return the predicted value for each measured data point.

DirectModel is a callable object that takes parameter=value keyword arguments and returns the appropriate theory values for the data.

DataMixin does the real work of interpreting the data and calling the model calculator. This is used by DirectModel, which uses direct parameter values and by bumps_model.Experiment which wraps the parameter values in boxes so that the user can set fitting ranges, etc. on the individual parameters and send the model to the Bumps optimizers.

class sasmodels.direct_model.DataMixin

Bases: object

DataMixin captures the common aspects of evaluating a SAS model for a particular data set, including calculating Iq and evaluating the resolution function. It is used in particular by DirectModel, which evaluates a SAS model parameters as key word arguments to the calculator method, and by bumps_model.Experiment, which wraps the model and data for use with the Bumps fitting engine. It is not currently used by sasview_model.SasviewModel since this will require a number of changes to SasView before we can do it.

_interpret_data initializes the data structures necessary to manage the calculations. This sets attributes in the child class such as data_type and resolution.

_calc_theory evaluates the model at the given control values.

_set_data sets the intensity data in the data object, possibly with random noise added. This is useful for simulating a dataset with the results from _calc_theory.

class sasmodels.direct_model.DirectModel(data, model, cutoff=1e-05)

Bases: sasmodels.direct_model.DataMixin

Create a calculator object for a model.

data is 1D SAS, 2D SAS or SESANS data

model is a model calculator return from core.load_model()

cutoff is the polydispersity weight cutoff.

profile(**pars)

Generate a plottable profile.

simulate_data(noise=None, **pars)

Generate simulated data for the model.

sasmodels.direct_model.call_Fq(calculator, pars, cutoff=0.0, mono=False)

Like call_kernel(), but returning F, F^2, R_eff, V_shell, V_form/V_shell.

For solid objects V_shell is equal to V_form and the volume ratio is 1.

Use parameter radius_effective_mode to select the effective radius calculation to use amongst the radius_effective_modes list given in the model.

sasmodels.direct_model.call_kernel(calculator, pars, cutoff=0.0, mono=False)

Call kernel returned from model.make_kernel with parameters pars.

cutoff is the limiting value for the product of dispersion weights used to perform the multidimensional dispersion calculation more quickly at a slight cost to accuracy. The default value of cutoff=0 integrates over the entire dispersion cube. Using cutoff=1e-5 can be 50% faster, but with an error of about 1%, which is usually less than the measurement uncertainty.

mono is True if polydispersity should be set to none on all parameters.

sasmodels.direct_model.call_profile(model_info, pars=None)

Returns the profile x, y, (xlabel, ylabel) representing the model.

sasmodels.direct_model.get_mesh(model_info, values, dim='1d', mono=False)

Retrieve the dispersity mesh described by the parameter set.

Returns a list of (value, dispersity, weights) with one tuple for each parameter in the model call parameters. Inactive parameters return the default value with a weight of 1.0.

sasmodels.direct_model.main()

Program to evaluate a particular model at a set of q values.

sasmodels.direct_model.test_reparameterize()

Check simple reparameterized models will load and build

sasmodels.exception module

Utility to add annotations to python exceptions.

exception sasmodels.exception.WindowsError

Bases: Exception

Fake WindowsException when not on Windows.

sasmodels.exception.annotate_exception(msg, exc=None)

Add an annotation to the current exception, which can then be forwarded to the caller using a bare “raise” statement to raise the annotated exception. If the exception exc is provided, then that exception is the one that is annotated, otherwise sys.exc_info is used.

Example:

>>> D = {}
>>> try:
...    print(D['hello'])
... except:
...    annotate_exception("while accessing 'D'")
...    raise
Traceback (most recent call last):
    ...
KeyError: "hello while accessing 'D'"

sasmodels.generate module

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.

Iqac(qab, qc, p1, p2, …) returns the scattering at qab, qc for a rotationally symmetric form with particular dimensions. qab, qc are determined from shape orientation and scattering angles. This call is used if the shape has orientation parameters theta and phi.

Iqabc(qa, qb, qc, p1, p2, …) returns the scattering at qa, qb, qc for a form with particular dimensions. qa, qb, qc are determined from shape orientation and scattering angles. This call is used if the shape has orientation parameters theta, phi and psi.

Iqxy(qx, qy, p1, p2, …) returns the scattering at qx, qy. Use this to create an arbitrary 2D theory function, needed for q-dependent background functions and for models with non-uniform magnetism.

form_volume(p1, p2, …) returns the volume of the form with particular dimension, or 1.0 if no volume normalization is required.

shell_volume(p1, p2, …) returns the volume of the shell for forms which are hollow.

radius_effective(mode, p1, p2, …) returns the effective radius of the form with particular dimensions. Mode determines the type of effective radius returned, with mode=1 for equivalent volume.

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.

C code should be stylized C-99 functions written for OpenCL. All functions need prototype declarations even if the are defined before they are used. Although OpenCL supports #include preprocessor directives, the list of includes should 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.

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

id is an implicit variable formed from the filename. It will be a valid python identifier, and will be used as the reference into the html documentation, with ‘_’ replaced by ‘-‘.

name is the model name as displayed to the user. If it is missing, it will be constructed from the id.

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. Note that effect_radius and volfraction must occur first in structure factor calculations.

category is the default category for the model. The category is two level structure, with the form “group:section”, indicating where in the manual the model will be located. Models are alphabetical within their section.

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.

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

Iq, Iqac, Iqabc 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.

valid expression that evaluates to True if the input parameters are valid (e.g., “bell_radius >= radius” for the barbell or capped cylinder models). The expression can call C functions, including those defined in your model file.

A modelinfo.ModelInfo structure is constructed from the kernel meta data and returned to the caller.

Valid inputs should be identified by the valid expression. 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, even for models with no polydispersity. If the valid expression misses some parameter combinations and they reach the kernel, the kernel should probably return NaN rather than zero. Even if the volume also evaluates to zero for these parameters, the distribution weights are still accumulated and the average volume calculation will be slightly off.

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.

Code follows the C99 standard with the following extensions and conditions:

M_PI_180 = pi/180
M_4PI_3 = 4pi/3
square(x) = x*x
cube(x) = x*x*x
sas_sinx_x(x) = sin(x)/x, with sin(0)/0 -> 1
all double precision constants must include the decimal point
all double declarations may be converted to half, float, or long double
FLOAT_SIZE is the number of bytes in the converted variables

load_kernel_module() loads the model definition file and modelinfo.make_model_info() parses it. make_source() converts C-based model definitions to C source code, including the polydispersity integral. model_sources() returns the list of source files the model depends on, and ocl_timestamp() returns the latest time stamp amongst the source files (so you can check if the model needs to be rebuilt).

The function make_doc() extracts the doc string and adds the parameter table to the top. make_figure in sasmodels/doc/genmodel creates the default figure for the model. [These two sets of code should mignrate into docs.py so docs can be updated in one place].

sasmodels.generate.contains_Fq(source)

Return True if C source defines “void Fq(“.

sasmodels.generate.contains_shell_volume(source)

Return True if C source defines “double shell_volume(“.

sasmodels.generate.convert_section_titles_to_boldface(s)

Use explicit bold-face rather than section headings so that the table of contents is not polluted with section names from the model documentation.

Sections are identified as the title line followed by a line of punctuation at least as long as the title line.

sasmodels.generate.convert_type(source, dtype)

Convert code from double precision to the desired type.

Floating point constants are tagged with ‘f’ for single precision or ‘L’ for long double precision.

sasmodels.generate.demo_time()

Show how long it takes to process a model.

sasmodels.generate.dll_timestamp(model_info)

Return a timestamp for the model corresponding to the most recently changed file or dependency.

sasmodels.generate.find_xy_mode(source)

Return the xy mode as qa, qac, qabc or qxy.

Note this is not a C parser, and so can be easily confused by non-standard syntax. Also, it will incorrectly identify the following as having 2D models:

/*
double Iqac(qab, qc, ...) { ... fill this in later ... }
*/

If you want to comment out the function, use // on the front of the line:

/*
// double Iqac(qab, qc, ...) { ... fill this in later ... }
*/

sasmodels.generate.format_units(units)

Convert units into ReStructured Text format.

sasmodels.generate.get_data_path(external_dir, target_file)

Search for the target file relative in the installed application.

Search first in the location of the generate module in case we are running directly from the distribution. Search next to the python executable for windows installs. Search in the ../Resources directory next to the executable for Mac OS/X installs.

sasmodels.generate.indent(s, depth)

Indent a string of text with depth additional spaces on each line.

sasmodels.generate.kernel_name(model_info, variant)

Name of the exported kernel symbol.

variant is “Iq”, “Iqxy” or “Imagnetic”.

sasmodels.generate.load_kernel_module(model_name)

Return the kernel module named in model_name.

If the name ends in .py then load it as a custom model using custom.__init__.load_custom_kernel_module(), otherwise load it as a builtin from sasmodels.models.

sasmodels.generate.load_template(filename)

Load template file from sasmodels resource directory.

sasmodels.generate.main()

Program which prints the source produced by the model.

sasmodels.generate.make_doc(model_info)

Return the documentation for the model.

sasmodels.generate.make_html(model_info)

Convert model docs directly to html.

sasmodels.generate.make_partable(pars)

Generate the parameter table to include in the sphinx documentation.

sasmodels.generate.make_source(model_info)

Generate the OpenCL/ctypes kernel from the module info.

Uses source files found in the given search path. Returns None if this is a pure python model, with no C source components.

sasmodels.generate.model_sources(model_info)

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

sasmodels.generate.ocl_timestamp(model_info)

Return a timestamp for the model corresponding to the most recently changed file or dependency.

Note that this does not look at the time stamps for the OpenCL header information since that need not trigger a recompile of the DLL.

sasmodels.generate.read_text(f)

sasmodels.generate.set_integration_size(info, n)

Update the model definition, replacing the gaussian integration with a gaussian integration of a different size.

Note: this really ought to be a method in modelinfo, but that leads to import loops.

sasmodels.generate.tag_source(source)

Return a unique tag for the source code.

sasmodels.generate.test_tag_float()

Check that floating point constants are identified and tagged with ‘f’

sasmodels.generate.view_html(model_name)

Load the model definition and view its help.

sasmodels.generate.view_html_from_info(info)

View the help for a loaded model definition.

sasmodels.gengauss module

Generate the Gauss-Legendre integration points and save them as a C file.

sasmodels.gengauss.gengauss(n, path)

Save the Gauss-Legendre integration points for length n into file path.

sasmodels.guyou module

Convert between latitude-longitude and Guyou map coordinates.

sasmodels.guyou.ellipticFi(phi, psi, m)

Returns F(phi+ipsi|m). See Abramowitz and Stegun, 17.4.11.

sasmodels.guyou.ellipticJi(u, v, m)

Returns [sn, cn, dn](u + iv|m).

sasmodels.guyou.guyou(lam, phi)

Transform from (latitude, longitude) to point (x, y)

sasmodels.guyou.guyou_invert(x, y)

Transform from point (x, y) on plot to (latitude, longitude)

sasmodels.guyou.main()

Show the Guyou transformation

sasmodels.guyou.plot_grid()

Plot the latitude-longitude grid for Guyou transform

sasmodels.jitter module

Jitter Explorer

Application to explore orientation angle and angular dispersity.

From the command line:

# Show docs
python -m sasmodels.jitter --help

# Guyou projection jitter, uniform over 20 degree theta and 10 in phi
python -m sasmodels.jitter --projection=guyou --dist=uniform --jitter=20,10,0

From a jupyter cell:

import ipyvolume as ipv
from sasmodels import jitter
import importlib; importlib.reload(jitter)
jitter.set_plotter("ipv")

size = (10, 40, 100)
view = (20, 0, 0)

#size = (15, 15, 100)
#view = (60, 60, 0)

dview = (0, 0, 0)
#dview = (5, 5, 0)
#dview = (15, 180, 0)
#dview = (180, 15, 0)

projection = 'equirectangular'
#projection = 'azimuthal_equidistance'
#projection = 'guyou'
#projection = 'sinusoidal'
#projection = 'azimuthal_equal_area'

dist = 'uniform'
#dist = 'gaussian'

jitter.run(size=size, view=view, jitter=dview, dist=dist, projection=projection)
#filename = projection+('_theta' if dview[0] == 180 else '_phi' if dview[1] == 180 else '')
#ipv.savefig(filename+'.png')

sasmodels.jitter.PLOT_ENGINE(calculator, draw_shape, size, view, jitter, dist, mesh, projection)

class sasmodels.jitter.Quaternion(w, r)

Bases: object

Quaternion(w, r) = w + ir[0] + jr[1] + kr[2]

Quaternion.from_angle_axis(theta, r) for a rotation of angle theta about an axis oriented toward the direction r. This defines a unit quaternion, normalizing \(r\) to the unit vector \(\hat r\), and setting quaternion \(Q = \cos \theta + \sin \theta \hat r\)

Quaternion objects can be multiplied, which applies a rotation about the given axis, allowing composition of rotations without risk of gimbal lock. The resulting quaternion is applied to a set of points using Q.rot(v).

conj()

Conjugate quaternion

static from_angle_axis(theta, r)

Build quaternion as rotation theta about axis r

inv()

Inverse quaternion

norm()

Quaternion length

rot(v)

Transform point v by quaternion

sasmodels.jitter.R_to_xyz(R)

Return phi, theta, psi Tait-Bryan angles corresponding to the given rotation matrix.

Extracting Euler Angles from a Rotation Matrix Mike Day, Insomniac Games https://d3cw3dd2w32x2b.cloudfront.net/wp-content/uploads/2012/07/euler-angles1.pdf Based on: Shoemake’s “Euler Angle Conversion”, Graphics Gems IV, pp. 222-229

sasmodels.jitter.Rx(angle)

Construct a matrix to rotate points about x by angle degrees.

sasmodels.jitter.Ry(angle)

Construct a matrix to rotate points about y by angle degrees.

sasmodels.jitter.Rz(angle)

Construct a matrix to rotate points about z by angle degrees.

sasmodels.jitter.apply_jitter(jitter, points)

Apply the jitter transform to a set of points.

Points are stored in a 3 x n numpy matrix, not a numpy array or tuple.

sasmodels.jitter.build_model(model_name, n=150, qmax=0.5, **pars)

Build a calculator for the given shape.

model_name is any sasmodels model. n and qmax define an n x n mesh on which to evaluate the model. The remaining parameters are stored in the returned calculator as calculator.pars. They are used by draw_scattering() to set the non-orientation parameters in the calculation.

Returns a calculator function which takes a dictionary or parameters and produces Iqxy. The Iqxy value needs to be reshaped to an n x n matrix for plotting. See the direct_model.DirectModel class for details.

sasmodels.jitter.clipped_range(data, portion=1.0, mode='central')

Determine range from data.

If portion is 1, use full range, otherwise use the center of the range or the top of the range, depending on whether mode is ‘central’ or ‘top’.

sasmodels.jitter.draw_axes(axes, origin=(-1, -1, -1), length=(2, 2, 2))

Draw wireframe axes lines, with given origin and length

sasmodels.jitter.draw_bcc(axes, size, view, jitter, steps=None, alpha=1)

Draw points for body-centered cubic paracrystal

sasmodels.jitter.draw_beam(axes, view=(0, 0), alpha=0.5, steps=25)

Draw the beam going from source at (0, 0, 1) to detector at (0, 0, -1)

sasmodels.jitter.draw_box(axes, size, view)

Draw a wireframe box at a particular view.

sasmodels.jitter.draw_ellipsoid(axes, size, view, jitter, steps=25, alpha=1)

Draw an ellipsoid.

sasmodels.jitter.draw_fcc(axes, size, view, jitter, steps=None, alpha=1)

Draw points for face-centered cubic paracrystal

sasmodels.jitter.draw_jitter(axes, view, jitter, dist='gaussian', size=(0.1, 0.4, 1.0), draw_shape=<function draw_parallelepiped>, projection='equirectangular', alpha=0.8, views=None)

Represent jitter as a set of shapes at different orientations.

sasmodels.jitter.draw_labels(axes, view, jitter, text)

Draw text at a particular location.

sasmodels.jitter.draw_mesh(axes, view, jitter, radius=1.2, n=11, dist='gaussian', projection='equirectangular')

Draw the dispersion mesh showing the theta-phi orientations at which the model will be evaluated.

sasmodels.jitter.draw_parallelepiped(axes, size, view, jitter, steps=None, color=(0.6, 1.0, 0.6), alpha=1)

Draw a parallelepiped surface, with view and jitter.

sasmodels.jitter.draw_person_on_sphere(axes, view, height=0.5, radius=1.0)

Draw a person on the surface of a sphere.

view indicates (latitude, longitude, orientation)

sasmodels.jitter.draw_sc(axes, size, view, jitter, steps=None, alpha=1)

Draw points for simple cubic paracrystal

sasmodels.jitter.draw_scattering(calculator, axes, view, jitter, dist='gaussian')

Plot the scattering for the particular view.

calculator is returned from build_model(). axes are the 3D axes on which the data will be plotted. view and jitter are the current orientation and orientation dispersity. dist is one of the sasmodels weight distributions.

sasmodels.jitter.draw_sphere(axes, radius=1.0, steps=25, center=(0, 0, 0), color='w', alpha=1.0)

Draw a sphere

sasmodels.jitter.get_projection(projection)

jitter projections <https://en.wikipedia.org/wiki/List_of_map_projections>

equirectangular (standard latitude-longitude mesh)

<https://en.wikipedia.org/wiki/Equirectangular_projection> Allows free movement in phi (around the equator), but theta is limited to +/- 90, and points are cos-weighted. Jitter in phi is uniform in weight along a line of latitude. With small theta and phi ranging over +/- 180 this forms a wobbling disk. With small phi and theta ranging over +/- 90 this forms a wedge like a slice of an orange.

azimuthal_equidistance (Postel)

<https://en.wikipedia.org/wiki/Azimuthal_equidistant_projection> Preserves distance from center, and so is an excellent map for representing a bivariate gaussian on the surface. Theta and phi operate identically, cutting wegdes from the antipode of the viewing angle. This unfortunately does not allow free movement in either theta or phi since the orthogonal wobble decreases to 0 as the body rotates through 180 degrees.

sinusoidal (Sanson-Flamsteed, Mercator equal-area)

<https://en.wikipedia.org/wiki/Sinusoidal_projection> Preserves arc length with latitude, giving bad behaviour at theta near +/- 90. Theta and phi operate somewhat differently, so a system with a-b-c dtheta-dphi-dpsi will not give the same value as one with b-a-c dphi-dtheta-dpsi, as would be the case for azimuthal equidistance. Free movement using theta or phi uniform over +/- 180 will work, but not as well as equirectangular phi, with theta being slightly worse. Computationally it is much cheaper for wide theta-phi meshes since it excludes points which lie outside the sinusoid near theta +/- 90 rather than packing them close together as in equirectangle. Note that the poles will be slightly overweighted for theta > 90 with the circle from theta at 90+dt winding backwards around the pole, overlapping the circle from theta at 90-dt.

Guyou (hemisphere-in-a-square) not weighted

<https://en.wikipedia.org/wiki/Guyou_hemisphere-in-a-square_projection> With tiling, allows rotation in phi or theta through +/- 180, with uniform spacing. Both theta and phi allow free rotation, with wobble in the orthogonal direction reasonably well behaved (though not as good as equirectangular phi). The forward/reverse transformations relies on elliptic integrals that are somewhat expensive, so the behaviour has to be very good to justify the cost and complexity. The weighting function for each point has not yet been computed. Note: run the module guyou.py directly and it will show the forward and reverse mappings.

azimuthal_equal_area incomplete

<https://en.wikipedia.org/wiki/Lambert_azimuthal_equal-area_projection> Preserves the relative density of the surface patches. Not that useful and not completely implemented

Gauss-Kreuger not implemented

<https://en.wikipedia.org/wiki/Transverse_Mercator_projection#Ellipsoidal_transverse_Mercator> Should allow free movement in theta, but phi is distorted.

sasmodels.jitter.ipv_axes()

Build a matplotlib style Axes interface for ipyvolume

sasmodels.jitter.main()

Command line interface to the jitter viewer.

sasmodels.jitter.make_image(z, kw)

Convert numpy array z into a PIL RGB image.

sasmodels.jitter.make_vec(*args)

Turn all elements of args into numpy arrays

sasmodels.jitter.map_colors(z, kw)

Process matplotlib-style colour arguments.

Pulls ‘cmap’, ‘alpha’, ‘vmin’, and ‘vmax’ from th kw dictionary, setting the kw[‘color’] to an RGB array. These are ignored if ‘c’ or ‘color’ are set inside kw.

sasmodels.jitter.orient_relative_to_beam(view, points)

Apply the view transform to a set of points.

Points are stored in a 3 x n numpy matrix, not a numpy array or tuple.

sasmodels.jitter.orient_relative_to_beam_quaternion(view, points)

Apply the view transform to a set of points.

Points are stored in a 3 x n numpy matrix, not a numpy array or tuple.

This variant uses quaternions rather than rotation matrices for the computation. It works but it is not used because it doesn’t solve any problems. The challenge of mapping theta/phi/psi to SO(3) does not disappear by calculating the transform differently.

sasmodels.jitter.run(model_name='parallelepiped', size=(10, 40, 100), view=(0, 0, 0), jitter=(0, 0, 0), dist='gaussian', mesh=30, projection='equirectangular')

Show an interactive orientation and jitter demo.

model_name is one of: sphere, ellipsoid, triaxial_ellipsoid, parallelepiped, cylinder, or sc/fcc/bcc_paracrystal

size gives the dimensions (a, b, c) of the shape.

view gives the initial view (theta, phi, psi) of the shape.

view gives the initial jitter (dtheta, dphi, dpsi) of the shape.

dist is the type of dispersition: gaussian, rectangle, or uniform.

mesh is the number of points in the dispersion mesh.

projection is the map projection to use for the mesh: equirectangular, sinusoidal, guyou, azimuthal_equidistance, or azimuthal_equal_area.

sasmodels.jitter.select_calculator(model_name, n=150, size=(10, 40, 100))

Create a model calculator for the given shape.

model_name is one of sphere, cylinder, ellipsoid, triaxial_ellipsoid, parallelepiped or bcc_paracrystal. n is the number of points to use in the q range. qmax is chosen based on model parameters for the given model to show something intersting.

Returns calculator and tuple size (a,b,c) giving minor and major equitorial axes and polar axis respectively. See build_model() for details on the returned calculator.

sasmodels.jitter.set_plotter(name)

Setting the plotting engine to matplotlib/ipyvolume or equivalently mpl/ipv.

sasmodels.jitter.test_qrot()

Quaternion checks

sasmodels.jitter.transform_xyz(view, jitter, x, y, z)

Send a set of (x,y,z) points through the jitter and view transforms.

sasmodels.kernel module

Execution kernel interface

KernelModel defines the interface to all kernel models. In particular, each model should provide a KernelModel.make_kernel() call which returns an executable kernel, Kernel, that operates on the given set of q_vector inputs. On completion of the computation, the kernel should be released, which also releases the inputs.

class sasmodels.kernel.Kernel

Bases: object

Instantiated model for the compute engine, applied to a particular q.

Subclasses should define __init__() to set up the kernel inputs, and _call_kernel() to evaluate the kernel:

def __init__(self, ...):
    ...
    self.q_input = <q-value class with nq attribute>
    self.info = <ModelInfo object>
    self.dim = <'1d' or '2d'>
    self.dtype = <kernel.dtype>
    size = 2*self.q_input.nq+4 if self.info.have_Fq else self.q_input.nq+4
    size = size + <extra padding if needed for kernel>
    self.result = np.empty(size, dtype=self.dtype)

def _call_kernel(self, call_details, values, cutoff, magnetic,
                radius_effective_mode):
    # type: (CallDetails, np.ndarray, np.ndarray, float, bool, int) -> None
    ... # call <kernel>
    nq = self.q_input.nq
    if self.info.have_Fq:  # models that compute both F and F^2
        end = 2*nq if have_Fq else nq
        self.result[0:end:2] = F**2
        self.result[1:end:2] = F
    else:
        end = nq
        self.result[0:end] = Fsq
    self.result[end + 0] = total_weight
    self.result[end + 1] = form_volume
    self.result[end + 2] = shell_volume
    self.result[end + 3] = radius_effective

Fq(call_details, values, cutoff, magnetic, radius_effective_mode=0)

Returns <F(q)>, <F(q)^2>, effective radius, shell volume and form:shell volume ratio. The <F(q)> term may be None if the form factor does not support direct computation of \(F(q)\)

\(P(q) = <F^2(q)>/<V>\) is used for structure factor calculations,

\[I(q) = \text{scale} \cdot P(q) \cdot S(q) + \text{background}\]

For the beta approximation, this becomes

\[I(q) = \text{scale} P (1 + <F>^2/<F^2> (S - 1)) + \text{background} = \text{scale}/<V> (<F^2> + <F>^2 (S - 1)) + \text{background}\]

\(<F(q)>\) and \(<F^2(q)>\) are averaged by polydispersity in shape and orientation, with each configuration \(x_k\) having form factor \(F(q, x_k)\), weight \(w_k\) and volume \(V_k\). The result is:

\[P(q)=\frac{\sum w_k F^2(q, x_k) / \sum w_k}{\sum w_k V_k / \sum w_k}\]

The form factor itself is scaled by volume and contrast to compute the total scattering. This is then squared, and the volume weighted F^2 is then normalized by volume F. For a given density, the number of scattering centers is assumed to scale linearly with volume. Later scaling the resulting \(P(q)\) by the volume fraction of particles gives the total scattering on an absolute scale. Most models incorporate the volume fraction into the overall scale parameter. An exception is vesicle, which includes the volume fraction parameter in the model itself, scaling \(F\) by \(\surd V_f\) so that the math for the beta approximation works out.

By scaling \(P(q)\) by total weight \(\sum w_k\), there is no need to make sure that the polydisperisity distributions normalize to one. In particular, any distibution values \(x_k\) outside the valid domain of \(F\) will not be included, and the distribution will be implicitly truncated. This is controlled by the parameter limits defined in the model (which truncate the distribution before calling the kernel) as well as any region excluded using the INVALID macro defined within the model itself.

The volume used in the polydispersity calculation is the form volume for solid objects or the shell volume for hollow objects. Shell volume should be used within \(F\) so that the normalizing scale represents the volume fraction of the shell rather than the entire form. This corresponds to the volume fraction of shell-forming material added to the solvent.

The calculation of \(S\) requires the effective radius and the volume fraction of the particles. The model can have several different ways to compute effective radius, with the radius_effective_mode parameter used to select amongst them. The volume fraction of particles should be determined from the total volume fraction of the form, not just the shell volume fraction. This makes a difference for hollow shapes, which need to scale the volume fraction by the returned volume ratio when computing \(S\). For solid objects, the shell volume is set to the form volume so this scale factor evaluates to one and so can be used for both hollow and solid shapes.

Iq(call_details, values, cutoff, magnetic)

Returns I(q) from the polydisperse average scattering.

\[I(q) = \text{scale} \cdot P(q) + \text{background}\]

With the correct choice of model and contrast, setting scale to the volume fraction \(V_f\) of particles should match the measured absolute scattering. Some models (e.g., vesicle) have volume fraction built into the model, and do not need an additional scale.

dim = None

Kernel dimension, either “1d” or “2d”.

dtype = None

Numerical precision for the computation.

info = None

Model info.

q_input = None

Q values at which the kernel is to be evaluated.

release()

Free resources associated with the kernel instance.

result = None

Place to hold result of _call_kernel() for subclass.

class sasmodels.kernel.KernelModel

Bases: object

Model definition for the compute engine.

dtype = None

info = None

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

release()

Free resources associated with the kernel.

sasmodels.kernelcl module

GPU driver for C kernels

TODO: docs are out of date

There should be a single GPU environment running on the system. This environment is constructed on the first call to environment(), and the same environment is returned on each call.

After retrieving the environment, the next step is to create the kernel. This is done with a call to GpuEnvironment.compile_program(), which returns the type of data used by the kernel.

Next a GpuInput object should be created with the correct kind of data. This data object can be used by multiple kernels, for example, if the target model is a weighted sum of multiple kernels. The data should include any extra evaluation points required to compute the proper data smearing. This need not match the square grid for 2D data if there is an index saying which q points are active.

Together the GpuInput, the program, and a device form a GpuKernel. This kernel is used during fitting, receiving new sets of parameters and evaluating them. The output value is stored in an output buffer on the devices, where it can be combined with other structure factors and form factors and have instrumental resolution effects applied.

In order to use OpenCL for your models, you will need OpenCL drivers for your machine. These should be available from your graphics card vendor. Intel provides OpenCL drivers for CPUs as well as their integrated HD graphics chipsets. AMD also provides drivers for Intel CPUs, but as of this writing the performance is lacking compared to the Intel drivers. NVidia combines drivers for CUDA and OpenCL in one package. The result is a bit messy if you have multiple drivers installed. You can see which drivers are available by starting python and running:

import pyopencl as cl cl.create_some_context(interactive=True)

Once you have done that, it will show the available drivers which you can select. It will then tell you that you can use these drivers automatically by setting the SAS_OPENCL environment variable, which is PYOPENCL_CTX equivalent but not conflicting with other pyopnecl programs.

Some graphics cards have multiple devices on the same card. You cannot yet use both of them concurrently to evaluate models, but you can run the program twice using a different device for each session.

OpenCL kernels are compiled when needed by the device driver. Some drivers produce compiler output even when there is no error. You can see the output by setting PYOPENCL_COMPILER_OUTPUT=1. It should be harmless, albeit annoying.

class sasmodels.kernelcl.GpuEnvironment

Bases: object

GPU context for OpenCL, with possibly many devices and one queue per device.

compile_program(name, source, dtype, fast, timestamp)

Compile the program for the device in the given context.

has_type(dtype)

Return True if all devices support a given type.

class sasmodels.kernelcl.GpuInput(q_vectors, dtype=dtype('float32'))

Bases: object

Make q data available to the gpu.

q_vectors is a list of q vectors, which will be [q] for 1-D data, and [qx, qy] for 2-D data. Internally, the vectors will be reallocated to get the best performance on OpenCL, which may involve shifting and stretching the array to better match the memory architecture. Additional points will be evaluated with q=1e-3.

dtype is the data type for the q vectors. The data type should be set to match that of the kernel, which is an attribute of GpuModel. Note that not all kernels support double precision, so even if the program was created for double precision, the GpuModel.dtype may be single precision.

Call release() when complete. Even if not called directly, the buffer will be released when the data object is freed.

dtype = dtype('float32')

is_2d = False

nq = 0

q = None

q_b = None

release()

Free the buffer associated with the q value.

class sasmodels.kernelcl.GpuKernel(model, q_vectors)

Bases: sasmodels.kernel.Kernel

Callable SAS kernel.

model is the GpuModel object to call

The kernel is derived from kernel.Kernel, providing the _call_kernel() method to evaluate the kernel for a given set of parameters. Because of the need to move the q values to the GPU before evaluation, the kernel is instantiated for a particular set of q vectors, and can be called many times without transfering q each time.

Call release() when done with the kernel instance.

dim = ''

Kernel dimensions (1d or 2d).

dtype = None

Kernel precision.

info = None

SAS model information structure.

q_input = None

release()

Release resources associated with the kernel.

result = None

Calculation results, updated after each call to _call_kernel().

class sasmodels.kernelcl.GpuModel(source, model_info, dtype=dtype('float32'), fast=False)

Bases: sasmodels.kernel.KernelModel

GPU wrapper for a single model.

source and model_info are the model source and interface as returned from generate.make_source() and modelinfo.make_model_info().

dtype is the desired model precision. Any numpy dtype for single or double precision floats will do, such as ‘f’, ‘float32’ or ‘single’ for single and ‘d’, ‘float64’ or ‘double’ for double. Double precision is an optional extension which may not be available on all devices. Half precision (‘float16’,’half’) may be available on some devices. Fast precision (‘fast’) is a loose version of single precision, indicating that the compiler is allowed to take shortcuts.

dtype = None

fast = False

get_function(name)

Fetch the kernel from the environment by name, compiling it if it does not already exist.

info = None

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

source = ''

sasmodels.kernelcl.compile_model(context, source, dtype, fast=False)

Build a model to run on the gpu.

Returns the compiled program and its type.

Raises an error if the desired precision is not available.

sasmodels.kernelcl.environment()

Returns a singleton GpuEnvironment.

This provides an OpenCL context and one queue per device.

sasmodels.kernelcl.fix_pyopencl_include()

Monkey patch pyopencl to allow spaces in include file path.

sasmodels.kernelcl.get_warp(kernel, queue)

Return the size of an execution batch for kernel running on queue.

sasmodels.kernelcl.has_type(device, dtype)

Return true if device supports the requested precision.

sasmodels.kernelcl.quote_path(v)

Quote the path if it is not already quoted.

If v starts with ‘-‘, then assume that it is a -I option or similar and do not quote it. This is fragile: -Ipath with space needs to be quoted.

sasmodels.kernelcl.reset_environment()

Return a new OpenCL context, such as after a change to SAS_OPENCL.

sasmodels.kernelcl.use_opencl()

Return True if OpenCL is the default computational engine

sasmodels.kernelcuda module

GPU driver for C kernels (with CUDA)

To select cuda, use SAS_OPENCL=cuda, or SAS_OPENCL=cuda:n for a particular device number. If no device number is specified, then look for CUDA_DEVICE=n or a file ~/.cuda-device containing n for the device number. Otherwise, try all available device numbers.

TODO: docs are out of date

There should be a single GPU environment running on the system. This environment is constructed on the first call to environment(), and the same environment is returned on each call.

After retrieving the environment, the next step is to create the kernel. This is done with a call to GpuEnvironment.compile_program(), which returns the type of data used by the kernel.

Next a GpuInput object should be created with the correct kind of data. This data object can be used by multiple kernels, for example, if the target model is a weighted sum of multiple kernels. The data should include any extra evaluation points required to compute the proper data smearing. This need not match the square grid for 2D data if there is an index saying which q points are active.

Together the GpuInput, the program, and a device form a GpuKernel. This kernel is used during fitting, receiving new sets of parameters and evaluating them. The output value is stored in an output buffer on the devices, where it can be combined with other structure factors and form factors and have instrumental resolution effects applied.

In order to use OpenCL for your models, you will need OpenCL drivers for your machine. These should be available from your graphics card vendor. Intel provides OpenCL drivers for CPUs as well as their integrated HD graphics chipsets. AMD also provides drivers for Intel CPUs, but as of this writing the performance is lacking compared to the Intel drivers. NVidia combines drivers for CUDA and OpenCL in one package. The result is a bit messy if you have multiple drivers installed. You can see which drivers are available by starting python and running:

import pyopencl as cl cl.create_some_context(interactive=True)

Once you have done that, it will show the available drivers which you can select. It will then tell you that you can use these drivers automatically by setting the SAS_OPENCL environment variable, which is PYOPENCL_CTX equivalent but not conflicting with other pyopnecl programs.

Some graphics cards have multiple devices on the same card. You cannot yet use both of them concurrently to evaluate models, but you can run the program twice using a different device for each session.

OpenCL kernels are compiled when needed by the device driver. Some drivers produce compiler output even when there is no error. You can see the output by setting PYOPENCL_COMPILER_OUTPUT=1. It should be harmless, albeit annoying.

class sasmodels.kernelcuda.GpuEnvironment(devnum=None)

Bases: object

GPU context for CUDA.

compile_program(name, source, dtype, fast, timestamp)

Compile the program for the device in the given context.

context = None

has_type(dtype)

Return True if all devices support a given type.

release()

Free the CUDA device associated with this context.

class sasmodels.kernelcuda.GpuInput(q_vectors, dtype=dtype('float32'))

Bases: object

Make q data available to the gpu.

q_vectors is a list of q vectors, which will be [q] for 1-D data, and [qx, qy] for 2-D data. Internally, the vectors will be reallocated to get the best performance on OpenCL, which may involve shifting and stretching the array to better match the memory architecture. Additional points will be evaluated with q=1e-3.

dtype is the data type for the q vectors. The data type should be set to match that of the kernel, which is an attribute of GpuModel. Note that not all kernels support double precision, so even if the program was created for double precision, the GpuModel.dtype may be single precision.

Call release() when complete. Even if not called directly, the buffer will be released when the data object is freed.

release()

Free the buffer associated with the q value.

class sasmodels.kernelcuda.GpuKernel(model, q_vectors)

Bases: sasmodels.kernel.Kernel

Callable SAS kernel.

model is the GpuModel object to call

The kernel is derived from kernel.Kernel, providing the _call_kernel() method to evaluate the kernel for a given set of parameters. Because of the need to move the q values to the GPU before evaluation, the kernel is instantiated for a particular set of q vectors, and can be called many times without transfering q each time.

Call release() when done with the kernel instance.

dim = ''

Kernel dimensions (1d or 2d).

dtype = None

Kernel precision.

info = None

SAS model information structure.

release()

Release resources associated with the kernel.

result = None

Calculation results, updated after each call to _call_kernel().

class sasmodels.kernelcuda.GpuModel(source, model_info, dtype=dtype('float32'), fast=False)

Bases: sasmodels.kernel.KernelModel

GPU wrapper for a single model.

source and model_info are the model source and interface as returned from generate.make_source() and modelinfo.make_model_info().

dtype is the desired model precision. Any numpy dtype for single or double precision floats will do, such as ‘f’, ‘float32’ or ‘single’ for single and ‘d’, ‘float64’ or ‘double’ for double. Double precision is an optional extension which may not be available on all devices. Half precision (‘float16’,’half’) may be available on some devices. Fast precision (‘fast’) is a loose version of single precision, indicating that the compiler is allowed to take shortcuts.

dtype = None

fast = False

get_function(name)

Fetch the kernel from the environment by name, compiling it if it does not already exist.

info = None

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

source = ''

sasmodels.kernelcuda.compile_model(source, dtype, fast=False)

Build a model to run on the gpu.

Returns the compiled program and its type. The returned type will be float32 even if the desired type is float64 if any of the devices in the context do not support the cl_khr_fp64 extension.

sasmodels.kernelcuda.environment()

Returns a singleton GpuEnvironment.

This provides an OpenCL context and one queue per device.

sasmodels.kernelcuda.has_type(dtype)

Return true if device supports the requested precision.

sasmodels.kernelcuda.mark_device_functions(source)

Mark all function declarations as __device__ functions (except kernel).

sasmodels.kernelcuda.partition(n)

Constructs block and grid arguments for n elements.

sasmodels.kernelcuda.reset_environment()

Call to create a new OpenCL context, such as after a change to SAS_OPENCL.

sasmodels.kernelcuda.show_device_functions(source)

Show all discovered function declarations, but don’t change any.

sasmodels.kernelcuda.sync()

Overview:

Waits for operation in the current context to complete.

Note: Maybe context.synchronize() is sufficient.

sasmodels.kernelcuda.use_cuda()

Returns True if CUDA is the default compute engine.

sasmodels.kerneldll module

DLL driver for C kernels

If the environment variable SAS_OPENMP is set, then sasmodels will attempt to compile with OpenMP flags so that the model can use all available kernels. This may or may not be available on your compiler toolchain. Depending on operating system and environment.

Windows does not have provide a compiler with the operating system. Instead, we assume that TinyCC is installed and available. This can be done with a simple pip command if it is not already available:

pip install tinycc

If Microsoft Visual C++ is available (because VCINSTALLDIR is defined in the environment), then that will be used instead. Microsoft Visual C++ for Python is available from Microsoft:

http://www.microsoft.com/en-us/download/details.aspx?id=44266

If neither compiler is available, sasmodels will check for MinGW, the GNU compiler toolchain. This available in packages such as Anaconda and PythonXY, or available stand alone. This toolchain has had difficulties on some systems, and may or may not work for you.

You can control which compiler to use by setting SAS_COMPILER in the environment:

• tinycc (Windows): use the TinyCC compiler shipped with SasView
• msvc (Windows): use the Microsoft Visual C++ compiler
• mingw (Windows): use the MinGW GNU cc compiler
• unix (Linux): use the system cc compiler.
• unix (Mac): use the clang compiler. You will need XCode installed, and the XCode command line tools. Mac comes with OpenCL drivers, so generally this will not be needed.

Both msvc and mingw require that the compiler is available on your path. For msvc, this can done by running vcvarsall.bat in a windows terminal. Install locations are system dependent, such as:

C:Program Files (x86)Common FilesMicrosoftVisual C++ for Python9.0vcvarsall.bat

or maybe

C:UsersyournameAppDataLocalProgramsCommonMicrosoftVisual C++ for Python9.0vcvarsall.bat

OpenMP for msvc requires the Microsoft vcomp90.dll library, which doesn’t seem to be included with the compiler, nor does there appear to be a public download location. There may be one on your machine already in a location such as:

C:Windowswinsxsx86_microsoft.vc90.openmp*vcomp90.dll

If you copy this to somewhere on your path, such as the python directory or the install directory for this application, then OpenMP should be supported.

For full control of the compiler, define a function compile_command(source,output) which takes the name of the source file and the name of the output file and returns a compile command that can be evaluated in the shell. For even more control, replace the entire compile(source,output) function.

The global attribute ALLOW_SINGLE_PRECISION_DLLS should be set to False if you wish to prevent single precision floating point evaluation for the compiled models, otherwise set it defaults to True.

class sasmodels.kerneldll.DllKernel(kernel, model_info, q_input)

Bases: sasmodels.kernel.Kernel

Callable SAS kernel.

kernel is the c function to call.

model_info is the module information

q_input is the DllInput q vectors at which the kernel should be evaluated.

The resulting call method takes the pars, a list of values for the fixed parameters to the kernel, and pd_pars, a list of (value, weight) vectors for the polydisperse parameters. cutoff determines the integration limits: any points with combined weight less than cutoff will not be calculated.

Call release() when done with the kernel instance.

release()

Release resources associated with the kernel.

class sasmodels.kerneldll.DllModel(dllpath, model_info, dtype=dtype('float32'))

Bases: sasmodels.kernel.KernelModel

ctypes wrapper for a single model.

dllpath is the stored path to the dll.

model_info is the model definition returned from modelinfo.make_model_info().

dtype is the desired model precision. Any numpy dtype for single or double precision floats will do, such as ‘f’, ‘float32’ or ‘single’ for single and ‘d’, ‘float64’ or ‘double’ for double. Double precision is an optional extension which may not be available on all devices.

Call release() when done with the kernel.

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

release()

Release any resources associated with the model.

sasmodels.kerneldll.compile_command(source, output)

unix compiler command

sasmodels.kerneldll.compile_model(source, output)

Compile source producing output.

Raises RuntimeError if the compile failed or the output wasn’t produced.

sasmodels.kerneldll.decode(s)

sasmodels.kerneldll.dll_name(model_file, dtype)

Name of the dll containing the model. This is the base file name without any path or extension, with a form such as ‘sas_sphere32’.

sasmodels.kerneldll.dll_path(model_file, dtype)

Complete path to the dll for the model. Note that the dll may not exist yet if it hasn’t been compiled.

sasmodels.kerneldll.load_dll(source, model_info, dtype=dtype('float64'))

Create and load a dll corresponding to the source.

model_info is the info object returned from modelinfo.make_model_info().

source is returned from generate.make_source(), as make_source(model_info)[‘dll’].

See make_dll() for details on controlling the dll path and the allowed floating point precision.

sasmodels.kerneldll.make_dll(source, model_info, dtype=dtype('float64'))

Returns the path to the compiled model defined by kernel_module.

If the model has not been compiled, or if the source file(s) are newer than the dll, then make_dll will compile the model before returning. This routine does not load the resulting dll.

dtype is a numpy floating point precision specifier indicating whether the model should be single, double or long double precision. The default is double precision, np.dtype(‘d’).

Set sasmodels.ALLOW_SINGLE_PRECISION_DLLS to False if single precision models are not allowed as DLLs.

Set sasmodels.kerneldll.SAS_DLL_PATH to the compiled dll output path. Alternatively, set the environment variable SAS_DLL_PATH. The default is in ~/.sasmodels/compiled_models.

sasmodels.kernelpy module

Python driver for python kernels

Calls the kernel with a vector of \(q\) values for a single parameter set. Polydispersity is supported by looping over different parameter sets and summing the results. The interface to PyModel matches those for kernelcl.GpuModel and kerneldll.DllModel.

class sasmodels.kernelpy.PyInput(q_vectors, dtype)

Bases: object

Make q data available to the gpu.

q_vectors is a list of q vectors, which will be [q] for 1-D data, and [qx, qy] for 2-D data. Internally, the vectors will be reallocated to get the best performance on OpenCL, which may involve shifting and stretching the array to better match the memory architecture. Additional points will be evaluated with q=1e-3.

dtype is the data type for the q vectors. The data type should be set to match that of the kernel, which is an attribute of PyModel. Note that not all kernels support double precision, so even if the program was created for double precision, the GpuProgram.dtype may be single precision.

Call release() when complete. Even if not called directly, the buffer will be released when the data object is freed.

release()

Free resources associated with the model inputs.

class sasmodels.kernelpy.PyKernel(model_info, q_input)

Bases: sasmodels.kernel.Kernel

Callable SAS kernel.

kernel is the kernel object to call.

model_info is the module information

q_input is the DllInput q vectors at which the kernel should be evaluated.

The resulting call method takes the pars, a list of values for the fixed parameters to the kernel, and pd_pars, a list of (value,weight) vectors for the polydisperse parameters. cutoff determines the integration limits: any points with combined weight less than cutoff will not be calculated.

Call release() when done with the kernel instance.

release()

Free resources associated with the kernel.

class sasmodels.kernelpy.PyModel(model_info)

Bases: sasmodels.kernel.KernelModel

Wrapper for pure python models.

make_kernel(q_vectors)

Instantiate the python kernel with input q_vectors

release()

Free resources associated with the model.

sasmodels.list_pars module

List all parameters used along with the models which use them.

Usage:

python -m sasmodels.list_pars [-v]

If ‘-v’ is given, then list the models containing the parameter in addition to just the parameter name.

sasmodels.list_pars.find_pars(kind=None)

Find all parameters in all models.

Returns the reference table {parameter: [model, model, …]}

sasmodels.list_pars.list_pars(names_only=True, kind=None)

Print all parameters in all models.

If names_only then only print the parameter name, not the models it occurs in.

sasmodels.list_pars.main()

Program to list the parameters used across all models.

sasmodels.mixture module

Mixture model

The product model multiplies the structure factor by the form factor, modulated by the effective radius of the form. The resulting model has a attributes of both the model description (with parameters, etc.) and the module evaluator (with call, release, etc.).

To use it, first load form factor P and structure factor S, then create ProductModel(P, S).

class sasmodels.mixture.MixtureKernel(model_info, kernels, q)

Bases: sasmodels.kernel.Kernel

Instantiated kernel for mixture of models.

Iq(call_details, values, cutoff, magnetic)

Returns I(q) from the polydisperse average scattering.

\[I(q) = \text{scale} \cdot P(q) + \text{background}\]

With the correct choice of model and contrast, setting scale to the volume fraction \(V_f\) of particles should match the measured absolute scattering. Some models (e.g., vesicle) have volume fraction built into the model, and do not need an additional scale.

release()

Free resources associated with the kernel.

class sasmodels.mixture.MixtureModel(model_info, parts)

Bases: sasmodels.kernel.KernelModel

Model definition for mixture of models.

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

release()

Free resources associated with the kernel.

sasmodels.mixture.make_mixture_info(parts, operation='+')

Create info block for mixture model.

sasmodels.model_test module

Run model unit tests.

Usage:

python -m sasmodels.model_test [opencl|cuda|dll|all] model1 model2 ...

If model1 is ‘all’, then all except the remaining models will be tested. Subgroups are also possible, such as ‘py’, ‘single’ or ‘1d’. See core.list_models() for details.

Each model is tested using the default parameters at q=0.1, (qx, qy)=(0.1, 0.1), and Fq is called to make sure R_eff, volume and volume ratio are computed. The return values at these points are not considered. The test is only to verify that the models run to completion, and do not produce inf or NaN.

Tests are defined with the tests attribute in the model.py file. tests is a list of individual tests to run, where each test consists of the parameter values for the test, the q-values and the expected results. For the effective radius test and volume ratio tests, use the extended output form, which checks each output of kernel.Fq. For 1-D tests, either specify the q value or a list of q-values, and the corresponding I(q) value, or list of I(q) values.

That is:

tests = [
    [ {parameters}, q, I(q)],
    [ {parameters}, [q], [I(q)] ],
    [ {parameters}, [q1, q2, ...], [I(q1), I(q2), ...]],

    [ {parameters}, (qx, qy), I(qx, Iqy)],
    [ {parameters}, [(qx1, qy1), (qx2, qy2), ...],
                    [I(qx1, qy1), I(qx2, qy2), ...]],

    [ {parameters}, q, F(q), F^2(q), R_eff, V, V_r ],
    ...
]

Parameters are key:value pairs, where key is one of the parameters of the model and value is the value to use for the test. Any parameters not given in the parameter list will take on the default parameter value.

Precision defaults to 5 digits (relative).

sasmodels.model_test.check_model(model_info)

Run the tests for a single model, capturing the output.

Returns success status and the output string.

sasmodels.model_test.invalid_pars(partable, pars)

Return a list of parameter names that are not part of the model.

sasmodels.model_test.is_near(target, actual, digits=5)

Returns true if actual is within digits significant digits of target.

taget zero and inf should match actual zero and inf. If you want to accept eps for zero, choose a value such as 1e-10, which must match up to +/- 1e-15 when digits is the default value of 5.

If target is None, then just make sure that actual is not NaN.

If target is NaN, make sure actual is NaN.

sasmodels.model_test.main()

Run tests given is models.

Returns 0 if success or 1 if any tests fail.

sasmodels.model_test.make_suite(loaders, models)

Construct the pyunit test suite.

loaders is the list of kernel drivers to use (dll, opencl or cuda). For python model the python driver is always used.

models is the list of models to test, or [“all”] to test all models.

sasmodels.model_test.model_tests()

Test runner visible to nosetests.

Run “nosetests sasmodels” on the command line to invoke it.

sasmodels.model_test.run_one(model_name)

[Deprecated] Run the tests associated with model_name.

Use the following instead:

succss, output = check_model(load_model_info(model_name))

sasmodels.modelinfo module

Model Info and Parameter Tables

Defines ModelInfo and ParameterTable and the routines for manipulating them. In particular, make_model_info() converts a kernel module into the model info block as seen by the rest of the sasmodels library.

sasmodels.modelinfo.C_SYMBOLS = ['Imagnetic', 'Iq', 'Iqxy', 'Iqac', 'Iqabc', 'form_volume', 'shell_volume', 'c_code', 'valid']

Set of variables defined in the model that might contain C code

sasmodels.modelinfo.MAX_PD = 5

Maximum number of simultaneously polydisperse parameters

class sasmodels.modelinfo.ModelInfo

Bases: object

Interpret the model definition file, categorizing the parameters.

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.

The structure should be mostly static, other than the delayed definition of Iq, Iqac and Iqabc if they need to be defined.

Imagnetic = None

Returns I(qx, qy, a, b, …). The interface follows Iq.

Iq = None

Returns I(q, a, b, …) for parameters a, b, etc. defined by the parameter table. Iq can be defined as a python function, or as a C function. If it is defined in C, then set Iq to the body of the C function, including the return statement. This function takes values for q and each of the parameters as separate double values (which may be converted to float or long double by sasmodels). All source code files listed in source will be loaded before the Iq function is defined. If Iq is not present, then sources should define static double Iq(double q, double a, double b, …) which will return I(q, a, b, …). Multiplicity parameters are sent as pointers to doubles. Constants in floating point expressions should include the decimal point. See generate for more details. If have_Fq is True, then Iq should return an interleaved array of \([\sum F(q_1), \sum F^2(q_1), \ldots, \sum F(q_n), \sum F^2(q_n)]\).

Iqabc = None

Returns I(qa, qb, qc, a, b, …). The interface follows Iq.

Iqac = None

Returns I(qab, qc, a, b, …). The interface follows Iq.

Iqxy = None

Returns I(qx, qy, a, b, …). The interface follows Iq.

base = None

For reparameterized systems, base is the base parameter table. For normal systems it is simply a copy of parameters.

basefile = None

Base file is usually filename, but not when a model has been reparameterized, in which case it is the file containing the original model definition. This is needed to signal an additional dependency for the model time stamp, and so that the compiler reports correct file for syntax errors.

c_code = None

inline source code, added after all elements of source

category = None

Location of the model description in the documentation. This takes the form of “section” or “section:subsection”. So for example, porod uses category=”shape-independent” so it is in the Shape-Independent Functions section whereas capped_cylinder uses: category=”shape:cylinder”, which puts it in the Cylinder Functions section.

composition = None

Composition is None if this is an independent model, or it is a tuple with comoposition type (‘product’ or ‘misture’) and a list of ModelInfo blocks for the composed objects. This allows us to rebuild a complete mixture or product model from the info block. composition is not given in the model definition file, but instead arises when the model is constructed using names such as sphere*hardsphere or cylinder+sphere.

description = None

Long description of the model.

docs = None

Doc string from the top of the model file. This should be formatted using ReStructuredText format, with latex markup in “.. math” environments, or in dollar signs. This will be automatically extracted to a .rst file by generate.make_doc(), then converted to HTML or PDF by Sphinx.

filename = None

Full path to the file defining the kernel, if any.

form_volume = None

Returns the form volume for python-based models. Form volume is needed for volume normalization in the polydispersity integral. If no parameters are volume parameters, then form volume is not needed. For C-based models, (with source defined, or with Iq defined using a string containing C code), form_volume must also be C code, either defined as a string, or in the sources.

get_hidden_parameters(control)

Returns the set of hidden parameters for the model. control is the value of the control parameter. Note that multiplicity models have an implicit control parameter, which is the parameter that controls the multiplicity.

have_Fq = False

True if the model defines an Fq function with signature void Fq(double q, double *F1, double *F2, ...)

hidden = None

Different variants require different parameters. In order to show just the parameters needed for the variant selected, you should provide a function hidden(control) -> set([‘a’, ‘b’, …]) indicating which parameters need to be hidden. For multiplicity models, you need to use the complete name of the parameter, including its number. So for example, if variant “a” uses only sld1 and sld2, then sld3, sld4 and sld5 of multiplicity parameter sld[5] should be in the hidden set.

id = None

Id of the kernel used to load it from the filesystem.

lineno = None

Line numbers for symbols defining C code

name = None

Display name of the model, which defaults to the model id but with capitalization of the parts so for example core_shell defaults to “Core Shell”.

opencl = None

True if the model can be run as an opencl model. If for some reason the model cannot be run in opencl (e.g., because the model passes functions by reference), then set this to false.

parameters = None

Model parameter table. Parameters are defined using a list of parameter definitions, each of which is contains parameter name, units, default value, limits, type and description. See Parameter for details on the individual parameters. The parameters are gathered into a ParameterTable, which provides various views into the parameter list.

profile = None

Returns a model profile curve x, y. If profile is defined, this curve will appear in response to the Show button in SasView. Use profile_axes to set the axis labels. Note that y values will be scaled by 1e6 before plotting.

profile_axes = None

Axis labels for the profile plot. The default is [‘x’, ‘y’]. Only the x component is used for now.

radius_effective = None

Computes the effective radius of the shape given the volume parameters. Only needed for models defined in python that can be used for monodisperse approximation for non-dilute solutions, P@S. The first argument is the integer effective radius mode, with default 0.

radius_effective_modes = None

List of options for computing the effective radius of the shape, or None if the model is not usable as a form factor model.

random = None

Returns a random parameter set for the model

sesans = None

Returns sesans(z, a, b, …) for models which can directly compute the SESANS correlation function. Note: not currently implemented.

shell_volume = None

Returns the shell volume for python-based models. Form volume and shell volume are needed for volume normalization in the polydispersity integral and structure interactions for hollow shapes. If no parameters are volume parameters, then shell volume is not needed. For C-based models, (with source defined, or with Iq defined using a string containing C code), shell_volume must also be C code, either defined as a string, or in the sources.

single = None

True if the model can be computed accurately with single precision. This is True by default, but models such as bcc_paracrystal set it to False because they require double precision calculations.

source = None

List of C source files used to define the model. The source files should define the Iq function, and possibly Iqac or Iqabc if the model defines orientation parameters. Files containing the most basic functions must appear first in the list, followed by the files that use those functions.

structure_factor = None

True if the model is a structure factor used to model the interaction between form factor models. This will default to False if it is not provided in the file.

tests = None

The set of tests that must pass. The format of the tests is described in model_test.

title = None

Short description of the model.

translation = None

Parameter translation code to convert from parameters table from caller to the base table used to evaluate the model.

valid = None

Expression which evaluates to True if the input parameters are valid and the model can be computed, or False otherwise. Invalid parameter sets will not be included in the weighted \(I(Q)\) calculation or its volume normalization. Use C syntax for the expressions, with || for or && for and and ! for not. Any non-magnetic parameter can be used.

class sasmodels.modelinfo.Parameter(name, units='', default=nan, limits=(-inf, inf), ptype='', description='')

Bases: object

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 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. For vector parameters, the name will be followed by [len] where len is an integer length of the vector, or the name of the parameter which controls the length. The attribute id will be created from name without the length.

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

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

limits ([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 are not passed, but will be used to convert from qx, qy to qa, qb, qc in calls to Iqxy and Imagnetic. If type is the empty string, the parameter will be used in all of Iq, Iqxy and Imagnetic. “sld” parameters can automatically be promoted to magnetic parameters, each of which will have a magnitude and a direction, which may be different from other sld parameters. The volume parameters are used for calls to form_volume within the kernel (required for volume normalization), to shell_volume (for hollow shapes), and to radius_effective (for structure factor interactions) respectively.

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.

Additional values can be set after the parameter is created:

• length is the length of the field if it is a vector field
• length_control is the parameter which sets the vector length
• is_control is True if the parameter is a control parameter for a vector
• polydisperse is true if the parameter accepts a polydispersity
• relative_pd is true if that polydispersity is a portion of the value (so a 10% length dipsersity would use a polydispersity value of 0.1) rather than absolute dispersisity (such as an angle plus or minus 15 degrees).

choices is the option names for a drop down list of options, as for example, might be used to set the value of a shape parameter.

Control parameters are used for variant models such as rpa which have different cases with different parameters, as well as models like spherical_sld with its user defined number of shells. The control parameter should appear in the parameter table along with the parameters it is is controlling. For variant models, use [CASES] in place of the parameter limits Within the parameter definition table, with case names such as:

CASES = ["diblock copolymer", "triblock copolymer", ...]

This should give limits=[[case1, case2, …]], but the model loader translates it to limits=[0, len(CASES)-1], and adds choices=CASES to the Parameter definition. Note that models can use a list of cases as a parameter without it being a control parameter. Either way, the parameter is sent to the model evaluator as float(choice_num), where choices are numbered from 0. ModelInfo.get_hidden_parameters() will determine which parameers to display.

The class contructor should not be called directly, but instead the parameter table is built using make_parameter_table() and parse_parameter() therein.

as_definition()

Declare space for the variable in a parameter structure.

For example, the parameter thickness with length 3 will return “double thickness[3];”, with no spaces before and no new line character afterward.

as_function_argument()

Declare the variable as a function argument.

For example, the parameter thickness with length 3 will return “double *thickness”, with no spaces before and no comma afterward.

class sasmodels.modelinfo.ParameterTable(parameters)

Bases: object

ParameterTable manages the list of available parameters.

There are a couple of complications which mean that the list of parameters for the kernel differs from the list of parameters that the user sees.

(1) Common parameters. Scale and background are implicit to every model, but are not passed to the kernel.

(2) Vector parameters. Vector parameters are passed to the kernel as a pointer to an array, e.g., thick[], but they are seen by the user as n separate parameters thick1, thick2, …

Therefore, the parameter table is organized by how it is expected to be used. The following information is needed to set up the kernel functions:

• kernel_parameters is the list of parameters in the kernel parameter table, with vector parameter p declared as p[].
• iq_parameters is the list of parameters to the Iq(q, …) function, with vector parameter p sent as p[].
• form_volume_parameters is the list of parameters to the form_volume(…) function, with vector parameter p sent as p[].

Problem details, which sets up the polydispersity loops, requires the following:

• theta_offset is the offset of the theta parameter in the kernel parameter table, with vector parameters counted as n individual parameters p1, p2, …, or offset is -1 if there is no theta parameter.
• max_pd is the maximum number of polydisperse parameters, with vector parameters counted as n individual parameters p1, p2, … Note that this number is limited to sasmodels.modelinfo.MAX_PD.
• npars is the total number of parameters to the kernel, with vector parameters counted as n individual parameters p1, p2, …
• common_parameters is the list of common parameters, with a unique copy for each model so that structure factors can have a default background of 0.0.
• call_parameters is the complete list of parameters to the kernel, including scale and background, with vector parameters recorded as individual parameters p1, p2, …
• active_1d is the set of names that may be polydisperse for 1d data
• active_2d is the set of names that may be polydisperse for 2d data

User parameters are the set of parameters visible to the user, including the scale and background parameters that the kernel does not see. User parameters don’t use vector notation, and instead use p1, p2, …

check_angles(strict=False)

Check that orientation angles are theta, phi and possibly psi.

strict should be True when checking a parameter table defined in a model file, but False when checking from mixture models, etc., where the parameters aren’t being passed to a calculator directly.

check_duplicates()

Check for duplicate parameter names

set_zero_background()

Set the default background to zero for this model. This is done for structure factor models.

user_parameters(pars, is2d=True)

Return the list of parameters for the given data type.

Vector parameters are expanded in place. If multiple parameters share the same vector length, then the parameters will be interleaved in the result. The control parameters come first. For example, if the parameter table is ordered as:

sld_core
sld_shell[num_shells]
sld_solvent
thickness[num_shells]
num_shells

and pars[num_shells]=2 then the returned list will be:

num_shells
scale
background
sld_core
sld_shell1
thickness1
sld_shell2
thickness2
sld_solvent

Note that shell/thickness pairs are grouped together in the result even though they were not grouped in the incoming table. The control parameter is always returned first since the GUI will want to set it early, and rerender the table when it is changed.

Parameters marked as sld will automatically have a set of associated magnetic parameters (p_M0, p_mtheta, p_mphi), as well as polarization information (up_theta, up_frac_i, up_frac_f).

sasmodels.modelinfo.derive_table(table, insert, remove, insert_after=None)

Create a derived parameter table.

Parameters given in insert are added to the table and parameters named in remove are deleted from the table. If insert_after is provided, then it indicates where in the new parameter table the parameters are inserted.

sasmodels.modelinfo.expand_pars(partable, pars=None)

Create a parameter set from key-value pairs.

pars are the key-value pairs to use for the parameters. Any parameters not specified in pars are set from the partable defaults.

If pars references vector fields, such as thickness[n], then support different ways of assigning the parameter values, including assigning a specific value (e.g., thickness3=50.0), assigning a new value to all (e.g., thickness=50.0) or assigning values using list notation.

sasmodels.modelinfo.isstr(x)

Return True if the object is a string.

sasmodels.modelinfo.make_model_info(kernel_module)

Extract the model definition from the loaded kernel module.

Fill in default values for parts of the module that are not provided.

Note: vectorized Iq and Iqac/Iqabc functions will be created for python models when the model is first called, not when the model is loaded.

sasmodels.modelinfo.make_parameter_table(pars)

Construct a parameter table from a list of parameter definitions.

This is used by the module processor to convert the parameter block into the parameter table seen in the ModelInfo for the module.

sasmodels.modelinfo.parse_parameter(name, units='', default=nan, user_limits=None, ptype='', description='')

Parse an individual parameter from the parameter definition block.

This does type and value checking on the definition, leading to early failure in the model loading process and easier debugging.

sasmodels.modelinfo.prefix_parameter(par, prefix)

Return a copy of the parameter with its name prefixed.

sasmodels.modelinfo.suffix_parameter(par, suffix)

Return a copy of the parameter with its name prefixed.

sasmodels.multiscat module

Multiple scattering calculator

Calculate multiple scattering using 2D FFT convolution.

Usage:

python -m sasmodels.multiscat [options] model_name model_par=value ...

Options include:
-h, --help: show help and exit
-n, --nq: the number of mesh points (dq = qmax*window/nq)
-o, --outfile: save results to outfile.txt and outfile_powers.txt
-p, --probability: the scattering probability (0.1)
-q, --qmax: that max q that you care about (0.5)
-r, --random: generate a random parameter set
-s, --seed: generate a random parameter set with a given seed
-w, --window: the extension window (q is calculated for qmax*window)
-2, --2d: perform the calculation for an oriented pattern

Assume the probability of scattering is \(p\). After each scattering event, \(1-p\) neutrons will leave the system and go to the detector, and the remaining \(p\) will scatter again.

Let the scattering probability for \(n\) scattering event at \(q\) be \(f_n(q)\), with

\[f_1(q) = \frac{I_1(q)}{\int I_1(q) {\rm d}q}\]

for \(I_1(q)\), the single scattering from the system. After two scattering events, the scattering probability will be the convolution of the first scattering and itself, or \(f_2(q) = (f_1*f_1)(q)\). After \(n\) events it will be \(f_n(q) = (f_1 * \cdots * f_1)(q)\). The total scattering is calculated as the weighted sum of \(f_k\), with weights following the Poisson distribution

\[P(k; \lambda) = \frac{\lambda^k e^{-\lambda}}{k!}\]

for \(\lambda\) determined by the total thickness divided by the mean free path between scattering, giving

\[I(q) = \sum_{k=0}^\infty P(k; \lambda) f_k(q)\]

The \(k=0\) term is ignored since it involves no scattering. We cut the series when cumulative probability is less than cutoff \(C=99\%\), which is \(\max n\) such that

\[\sum_{k=1}^n \frac{P(k; \lambda)}{1 - P(0; \lambda)} < C\]

Using the convolution theorem, where \(F = \mathcal{F}(f)\) is the Fourier transform,

\[f * g = \mathcal{F}^{-1}\{\mathcal{F}\{f\} \cdot \mathcal{F}\{g\}\}\]

so

\[f * \ldots * f = \mathcal{F}^{-1}\{ F^n \}\]

Since the Fourier transform is a linear operator, we can move the polynomial expression for the convolution into the transform, giving

\[I(q) = \mathcal{F}^{-1}\left\{ \sum_{k=1}^{n} P(k; \lambda) F^k \right\}\]

In the dilute limit \(\lambda \rightarrow 0\) only the \(k=1\) term is active, and so

\[P(1; \lambda) = \lambda e^{-\lambda} = \int I_1(q) {\rm d}q\]

therefore we compute

\[I(q) = \mathcal{F}^{-1}\left\{ \sum_{l=1}^{n} \frac{P(k; \lambda)}{P(1; \lambda))} F^k \right\} \, \int I_1(q) {\rm d}q = \mathcal{F}^{-1}\left\{ \sum_{l=1}^{n} \frac{\lambda^{k-1}}{k!} F^k \right\} \, \int I_1(q) {\rm d}q\]

For speed we may use the fast fourier transform with a power of two. The resulting \(I(q)\) will be linearly spaced and likely heavily oversampled. The usual pinhole or slit resolution calculation can performed from these calculated values.

By default single precision OpenCL is used for the calculation. Set the environment variable SAS_OPENCL=none to use double precision numpy FFT instead. The OpenCL versions is about 10x faster on an elderly Mac with Intel HD 4000 graphics. The single precision numerical artifacts don’t seem to seriously impact overall accuracy, though they look pretty bad.

sasmodels.multiscat.Calculator

alias of sasmodels.multiscat.NumpyCalculator

class sasmodels.multiscat.ICalculator

Bases: object

Multiple scattering calculator

fft(Iq)

Compute the forward FFT for an image, real -> complex.

ifft(fourier_frame)

Compute the inverse FFT for an image, complex -> complex.

multiple_scattering(Iq, p, coverage=0.99)

Compute multiple scattering for I(q) given scattering probability p.

Given a probability p of scattering with the thickness, the expected number of scattering events, \(\lambda = -\log(1 - p)\), giving a Poisson weighted sum of single, double, triple, etc. scattering patterns. The number of patterns used is based on coverage (default 99%).

class sasmodels.multiscat.MultipleScattering(qmin=None, qmax=None, nq=None, window=2, probability=None, coverage=0.99, is2d=False, resolution=None, dtype=dtype('float64'))

Bases: sasmodels.resolution.Resolution

Compute multiple scattering using Fourier convolution.

The fourier steps are determined by qmax, the maximum \(q\) value desired, nq the number of \(q\) steps and window, the amount of padding around the circular convolution. The \(q\) spacing will be \(\Delta q = 2 q_\mathrm{max} w / n_q\). If nq is not given it will use \(n_q = 2^k\) such that \(\Delta q < q_\mathrm{min}\).

probability is related to the expected number of scattering events in the sample \(\lambda\) as \(p = 1 - e^{-\lambda}\).

coverage determines how many scattering steps to consider. The default is 0.99, which sets \(n\) such that \(1 \ldots n\) covers 99% of the Poisson probability mass function.

is2d is True then 2D scattering is used, otherwise it accepts and returns 1D scattering.

resolution is the resolution function to apply after multiple scattering. If present, then the resolution \(q\) vectors will provide default values for qmin, qmax and nq.

apply(theory)

Smear theory by the resolution function, returning Iq.

radial_profile(Iqxy)

Compute that radial profile for the given Iqxy grid. The grid should be defined as for

class sasmodels.multiscat.NumpyCalculator(dims=None, dtype=dtype('float64'))

Bases: sasmodels.multiscat.ICalculator

Multiple scattering calculator using numpy fft.

fft(Iq)

Compute the forward FFT for an image, real -> complex.

ifft(fourier_frame)

Compute the inverse FFT for an image, complex -> complex.

multiple_scattering(Iq, p, coverage=0.99)

Compute multiple scattering for I(q) given scattering probability p.

Given a probability p of scattering with the thickness, the expected number of scattering events, \(\lambda = -\log(1 - p)\), giving a Poisson weighted sum of single, double, triple, etc. scattering patterns. The number of patterns used is based on coverage (default 99%).

class sasmodels.multiscat.OpenclCalculator(dims, dtype=dtype('float64'))

Bases: sasmodels.multiscat.ICalculator

Multiple scattering calculator using OpenCL via pyfft.

fft(Iq)

Compute the forward FFT for an image, real -> complex.

ifft(fourier_frame)

Compute the inverse FFT for an image, complex -> complex.

multiple_scattering(Iq, p, coverage=0.99)

Compute multiple scattering for I(q) given scattering probability p.

Given a probability p of scattering with the thickness, the expected number of scattering events, \(\lambda = -\log(1 - p)\), giving a Poisson weighted sum of single, double, triple, etc. scattering patterns. The number of patterns used is based on coverage (default 99%).

polyval1d = None

polyval1f = None

sasmodels.multiscat.annular_average(qxy, Iqxy, qbins)

Compute annular average of points in Iqxy at qbins. The \(q_x\), \(q_y\) coordinates for Iqxy are given in qxy.

sasmodels.multiscat.main()

Command line interface to multiple scattering calculator.

sasmodels.multiscat.parse_pars(model, opts)

Parse par=val arguments from the command line.

sasmodels.multiscat.plotxy(q, Iq)

Plot q, Iq or (qx, qy), Iqxy.

sasmodels.multiscat.rebin(x, I, xo)

Rebin from edges x, bins I into edges xo.

x and xo should be monotonically increasing.

If x has duplicate values, then all corresponding values at I(x) will be effectively summed into the same bin. If xo has duplicate values, the first bin will contain the entire contents and subsequent bins will contain zeros.

sasmodels.multiscat.scattering_coeffs(p, coverage=0.99)

Return the coefficients of the scattering powers for transmission probability p. This is just the corresponding values for the Poisson distribution for \(\lambda = -\ln(1-p)\) such that \(\sum_{k = 0 \ldots n} P(k; \lambda)\) is larger than coverage.

sasmodels.multiscat.scattering_powers(Iq, n, dtype='f', transform=None)

Calculate the scattering powers up to n.

This includes k=1 even though it should just be Iq itself

The frames are unweighted; to weight scale by \(\lambda^k e^{-\lambda}/k!\).

sasmodels.multiscat.truncated_poisson_invcdf(coverage, L)

Return smallest k such that cdf(k; L) > coverage from the truncated Poisson probability excluding k=0

sasmodels.product module

Product model

The product model multiplies the structure factor by the form factor, modulated by the effective radius of the form. The resulting model has a attributes of both the model description (with parameters, etc.) and the module evaluator (with call, release, etc.).

To use it, first load form factor P and structure factor S, then create make_product_info(P, S).

The P@S models is somewhat complicated because there are many special parameters that need to be handled in particular ways. Much of the code is used to figure out what special parameters we have, where to find them in the P@S model inputs and how to distribute them to the underlying P and S model calculators.

The parameter packet received by the P@S is a details.CallDetails structure along with a data vector. The CallDetails structure indicates which parameters are polydisperse, the length of the distribution, and where to find it in the data vector. The distributions are ordered from longest to shortest, with length 1 distributions filling out the distribution set. That way the kernel calculator doesn’t have to check if it needs another nesting level since it is always there. The data vector consists of a list of target values for the parameters, followed by a concatenation of the distribution values, and then followed by a concatenation of the distribution weights. Given the combined details and data for P@S, we must decompose them in to details for P and details for S separately, which unfortunately requires intimate knowledge of the data structures and tricky code.

The special parameters are:

• scale and background:

  First two parameters of the value list in each of P, S and P@S. When decomposing P@S parameters, ignore scale and background, instead using 1 and 0 for the first two slots of both P and S. After calling P and S individually, the results are combined as volfraction*scale*P*S + background. The scale and background do not show up in the polydispersity structure so they are easy to handle.

• volfraction:

  Always the first parameter of S, but it may also be in P. If it is in P, then P.volfraction is used in the combined P@S list, and S.volfraction is elided, otherwise S.volfraction is used. If we are using volfraction from P we can treat it like all the other P parameters when calling P, but when calling S we need to insert the P.volfraction into data vector for S and assign a slot of length 1 in the distribution. Because we are using the original layout of the distribution vectors from P@S, but copying it into private data vectors for S and P, we are free to “borrow” a P slots to store the missing S.volfraction distribution. We use the P.volfraction slot itself but any slot will work.

  For hollow shapes, volfraction represents the volume fraction of material but S needs the volume fraction enclosed by the shape. The answer is to scale the user specified volume fraction by the form:shell ratio computed from the average form volume and average shell volume returned from P. Use the original volfraction divided by shell_volume to compute the number density, and scale P@S by that to get absolute scaling on the final I(q). The scale for P@S should therefore usually be one.

• radius_effective:

  Always the second parameter of S and always part of P@S, but never in P. The value may be calculated using P.radius_effective() or it may be set to the radius_effective value in P@S, depending on radius_effective_mode. If part of S, the value may be polydisperse. If calculated by P, then it will be the weighted average of effective radii computed for the polydisperse shape parameters.

• structure_factor_mode

  If P@S supports beta approximation (i.e., if it has the Fq function that returns <FF*> and <F><F*>), then structure_factor_mode will be added to the P@S parameters right after the S parameters. This mode may be 0 for the monodisperse approximation or 1 for the beta approximation. We will add more values here as we implemented more complicated operations, but for now P and S must be computed separately. If beta, then we return I = scale volfrac/volume ( <FF> + <F>^2 (S-1)) + background. If not beta then return I = scale/volume P S + background . In both cases, return the appropriate immediate values.

• radius_effective_mode

  If P defines the radius_effective function (and therefore P.info.radius_effective_modes is a list of effective radius modes), then radius_effective_mode will be the final parameter in P@S. Mode will be zero if radius_effective is defined by the user using the S parameter; any other value and the radius_effective parameter will be filled in from the value computed in P. In the latter case, the polydispersity information for S.radius_effective will need to be suppressed, with pd length set to 1, the first value set to the effective radius and the first weight set to 1. Do this after composing the S data vector so the inputs are left untouched.

• regular parameters

  The regular P parameters form a block of length P.info.npars at the start of the data vector (after scale and background). These will be followed by S.effective_radius, and S.volfraction (if P.volfraction is absent), and then the regular S parameters. The P and S blocks can be copied as a group into the respective P and S data vectors. We can copy the distribution value and weight vectors untouched to both the P and S data vectors since they are referenced by offset and length. We can update the radius_effective slots in the P data vector with P.radius_effective() if needed.

• magnetic parameters

  For each P parameter that is an SLD there will be a set of three magnetic parameters tacked on to P@S after the regular P and S and after the special structure_factor_mode and radius_effective_mode. These can be copied as a group after the regular P parameters. There won’t be any magnetic S parameters.

class sasmodels.product.ProductKernel(model_info, p_kernel, s_kernel, q)

Bases: sasmodels.kernel.Kernel

Instantiated kernel for product model.

Iq(call_details, values, cutoff, magnetic)

Returns I(q) from the polydisperse average scattering.

\[I(q) = \text{scale} \cdot P(q) + \text{background}\]

With the correct choice of model and contrast, setting scale to the volume fraction \(V_f\) of particles should match the measured absolute scattering. Some models (e.g., vesicle) have volume fraction built into the model, and do not need an additional scale.

release()

Free resources associated with the kernel.

class sasmodels.product.ProductModel(model_info, P, S)

Bases: sasmodels.kernel.KernelModel

Model definition for product model.

P = None

Form factor modelling individual particles.

S = None

Structure factor modelling interaction between particles.

dtype = None

Model precision. This is not really relevant, since it is the individual P and S models that control the effective dtype, converting the q-vectors to the correct type when the kernels for each are created. Ideally this should be set to the more precise type to avoid loss of precision, but precision in q is not critical (single is good enough for our purposes), so it just uses the precision of the form factor.

info = None

Combined info plock for the product model

make_kernel(q_vectors)

Instantiate a kernel for evaluating the model at q_vectors.

release()

Free resources associated with the model.

sasmodels.product.make_extra_pars(p_info)

Create parameters for structure factor and effective radius modes.

sasmodels.product.make_product_info(p_info, s_info)

Create info block for product model.

sasmodels.resolution module

Define the resolution functions for the data.

This defines classes for 1D and 2D resolution calculations.

class sasmodels.resolution.Resolution

Bases: object

Abstract base class defining a 1D resolution function.

q is the set of q values at which the data is measured.

q_calc is the set of q values at which the theory needs to be evaluated. This may extend and interpolate the q values.

apply is the method to call with I(q_calc) to compute the resolution smeared theory I(q).

apply(theory)

Smear theory by the resolution function, returning Iq.

q = None

q_calc = None

class sasmodels.resolution.Perfect1D(q)

Bases: sasmodels.resolution.Resolution

Resolution function to use when there is no actual resolution smearing to be applied. It has the same interface as the other resolution functions, but returns the identity function.

apply(theory)

Smear theory by the resolution function, returning Iq.

class sasmodels.resolution.Pinhole1D(q, q_width, q_calc=None, nsigma=(2.5, 3.0))

Bases: sasmodels.resolution.Resolution

Pinhole aperture with q-dependent gaussian resolution.

q points at which the data is measured.

q_width gaussian 1-sigma resolution at each data point.

q_calc is the list of points to calculate, or None if this should be estimated from the q and q_width.

nsigma is the width of the resolution function. Should be 2.5. See pinhole_resolution() for details.

apply(theory)

Smear theory by the resolution function, returning Iq.

class sasmodels.resolution.Slit1D(q, qx_width, qy_width=0.0, q_calc=None)

Bases: sasmodels.resolution.Resolution

Slit aperture with resolution function.

q points at which the data is measured.

qx_width slit width in qx

qy_width slit height in qy

q_calc is the list of points to calculate, or None if this should be estimated from the q and q_width.

The weight_matrix is computed by slit_resolution()

apply(theory)

Smear theory by the resolution function, returning Iq.

sasmodels.resolution.apply_resolution_matrix(weight_matrix, theory)

Apply the resolution weight matrix to the computed theory function.

sasmodels.resolution.pinhole_resolution(q_calc, q, q_width, nsigma=(2.5, 3.0))

Compute the convolution matrix W for pinhole resolution 1-D data.

Each row W[i] determines the normalized weight that the corresponding points q_calc contribute to the resolution smeared point q[i]. Given W, the resolution smearing can be computed using dot(W,q).

Note that resolution is limited to \(\pm 2.5 \sigma\).[1] The true resolution function is a broadened triangle, and does not extend over the entire range \((-\infty, +\infty)\). It is important to impose this limitation since some models fall so steeply that the weighted value in gaussian tails would otherwise dominate the integral.

q_calc must be increasing. q_width must be greater than zero.

[1] Barker, J. G., and J. S. Pedersen. 1995. Instrumental Smearing Effects in Radially Symmetric Small-Angle Neutron Scattering by Numerical and Analytical Methods. Journal of Applied Crystallography 28 (2): 105–14. https://doi.org/10.1107/S0021889894010095.

sasmodels.resolution.slit_resolution(q_calc, q, width, height, n_height=30)

Build a weight matrix to compute I_s(q) from I(q_calc), given \(q_\perp\) = width and \(q_\parallel\) = height. n_height is is the number of steps to use in the integration over \(q_\parallel\) when both \(q_\perp\) and \(q_\parallel\) are non-zero.

Each \(q\) can have an independent width and height value even though current instruments use the same slit setting for all measured points.

If slit height is large relative to width, use:

\[I_s(q_i) = \frac{1}{\Delta q_\perp} \int_0^{\Delta q_\perp} I\left(\sqrt{q_i^2 + q_\perp^2}\right) \,dq_\perp\]

If slit width is large relative to height, use:

\[I_s(q_i) = \frac{1}{2 \Delta q_\parallel} \int_{-\Delta q_\parallel}^{\Delta q_\parallel} I\left(|q_i + q_\parallel|\right) \,dq_\parallel\]

For a mixture of slit width and height use:

\[I_s(q_i) = \frac{1}{2 \Delta q_\parallel \Delta q_\perp} \int_{-\Delta q_\parallel}^{\Delta q_\parallel} \int_0^{\Delta q_\perp} I\left(\sqrt{(q_i + q_\parallel)^2 + q_\perp^2}\right) \,dq_\perp dq_\parallel\]

Definition

We are using the mid-point integration rule to assign weights to each element of a weight matrix \(W\) so that

\[I_s(q) = W\,I(q_\text{calc})\]

If q_calc is at the mid-point, we can infer the bin edges from the pairwise averages of q_calc, adding the missing edges before q_calc[0] and after q_calc[-1].

For \(q_\parallel = 0\), the smeared value can be computed numerically using the \(u\) substitution

\[u_j = \sqrt{q_j^2 - q^2}\]

This gives

\[I_s(q) \approx \sum_j I(u_j) \Delta u_j\]

where \(I(u_j)\) is the value at the mid-point, and \(\Delta u_j\) is the difference between consecutive edges which have been first converted to \(u\). Only \(u_j \in [0, \Delta q_\perp]\) are used, which corresponds to \(q_j \in \left[q, \sqrt{q^2 + \Delta q_\perp}\right]\), so

\[W_{ij} = \frac{1}{\Delta q_\perp} \Delta u_j = \frac{1}{\Delta q_\perp} \left( \sqrt{q_{j+1}^2 - q_i^2} - \sqrt{q_j^2 - q_i^2} \right) \ \text{if}\ q_j \in \left[q_i, \sqrt{q_i^2 + q_\perp^2}\right]\]

where \(I_s(q_i)\) is the theory function being computed and \(q_j\) are the mid-points between the calculated values in q_calc. We tweak the edges of the initial and final intervals so that they lie on integration limits.

(To be precise, the transformed midpoint \(u(q_j)\) is not necessarily the midpoint of the edges \(u((q_{j-1}+q_j)/2)\) and \(u((q_j + q_{j+1})/2)\), but it is at least in the interval, so the approximation is going to be a little better than the left or right Riemann sum, and should be good enough for our purposes.)

For \(q_\perp = 0\), the \(u\) substitution is simpler:

\[u_j = \left|q_j - q\right|\]

so

\[W_{ij} = \frac{1}{2 \Delta q_\parallel} \Delta u_j = \frac{1}{2 \Delta q_\parallel} (q_{j+1} - q_j) \ \text{if}\ q_j \in \left[q-\Delta q_\parallel, q+\Delta q_\parallel\right]\]

However, we need to support cases were \(u_j < 0\), which means using \(2 (q_{j+1} - q_j)\) when \(q_j \in \left[0, q_\parallel-q_i\right]\). This is not an issue for \(q_i > q_\parallel\).

For both \(q_\perp > 0\) and \(q_\parallel > 0\) we perform a 2 dimensional integration with

\[u_{jk} = \sqrt{q_j^2 - (q + (k\Delta q_\parallel/L))^2} \ \text{for}\ k = -L \ldots L\]

for \(L\) = n_height. This gives

\[W_{ij} = \frac{1}{2 \Delta q_\perp q_\parallel} \sum_{k=-L}^L \Delta u_{jk} \left(\frac{\Delta q_\parallel}{2 L + 1}\right)\]

sasmodels.resolution.pinhole_extend_q(q, q_width, nsigma=(2.5, 3.0))

Given q and q_width, find a set of sampling points q_calc so that each point \(I(q)\) has sufficient support from the underlying function.

sasmodels.resolution.slit_extend_q(q, width, height)

Given q, width and height, find a set of sampling points q_calc so that each point I(q) has sufficient support from the underlying function.

sasmodels.resolution.bin_edges(x)

Determine bin edges from bin centers, assuming that edges are centered between the bins.

Note: this uses the arithmetic mean, which may not be appropriate for log-scaled data.

sasmodels.resolution.interpolate(q, max_step)

Returns q_calc with points spaced at most max_step apart.

sasmodels.resolution.linear_extrapolation(q, q_min, q_max)

Extrapolate q out to [q_min, q_max] using the step size in q as a guide. Extrapolation below uses about the same size as the first interval. Extrapolation above uses about the same size as the final interval.

Note that extrapolated values may be negative.

sasmodels.resolution.geometric_extrapolation(q, q_min, q_max, points_per_decade=None)

Extrapolate q to [q_min, q_max] using geometric steps, with the average geometric step size in q as the step size.

if q_min is zero or less then q[0]/10 is used instead.

points_per_decade sets the ratio between consecutive steps such that there will be \(n\) points used for every factor of 10 increase in q.

If points_per_decade is not given, it will be estimated as follows. Starting at \(q_1\) and stepping geometrically by \(\Delta q\) to \(q_n\) in \(n\) points gives a geometric average of:

\[\log \Delta q = (\log q_n - \log q_1) / (n - 1)\]

From this we can compute the number of steps required to extend \(q\) from \(q_n\) to \(q_\text{max}\) by \(\Delta q\) as:

\[n_\text{extend} = (\log q_\text{max} - \log q_n) / \log \Delta q\]

Substituting:

\[n_\text{extend} = (n-1) (\log q_\text{max} - \log q_n) / (\log q_n - \log q_1)\]

sasmodels.resolution2d module

#This software was developed by the University of Tennessee as part of the #Distributed Data Analysis of Neutron Scattering Experiments (DANSE) #project funded by the US National Science Foundation. #See the license text in license.txt

class sasmodels.resolution2d.Pinhole2D(data=None, index=None, nsigma=3.0, accuracy='Low', coords='polar')

Bases: sasmodels.resolution.Resolution

Gaussian Q smearing class for SAS 2d data

apply(theory)

Smear theory by the resolution function, returning Iq.

class sasmodels.resolution2d.Slit2D(q, qx_width, qy_width=0.0, q_calc=None, accuracy='low')

Bases: sasmodels.resolution.Resolution

Slit aperture with resolution function on an oriented sample.

q points at which the data is measured.

qx_width slit width in qx

qy_width slit height in qy; current implementation requires a fixed qy_width for all q points.

q_calc is the list of q points to calculate, or None if this should be estimated from the q and qx_width.

accuracy determines the number of qy points to compute for each q. The values are stored in sasmodels.resolution2d.N_SLIT_PERP. The default values are: low=101, med=401, high=1001, xhigh=2001

apply(theory)

Smear theory by the resolution function, returning Iq.

sasmodels.rst2html module

Convert a restructured text document to html.

Inline math markup can uses the math directive, or it can use latex style $expression$. Math can be rendered using simple html and unicode, or with mathjax.

sasmodels.rst2html.can_use_qt()

Return True if QWebView exists.

Checks first in PyQt5 then in PyQt4

sasmodels.rst2html.load_rst_as_html(filename)

Load rst from file and convert to html

sasmodels.rst2html.main()

Command line interface to rst or html viewer.

sasmodels.rst2html.qtview(html, url='')

View HTML in a Qt dialog

sasmodels.rst2html.replace_compact_fraction(content)

Convert frac12 to frac{1}{2} for broken latex parsers

sasmodels.rst2html.replace_dollar(content)

Convert dollar signs to inline math markup in rst.

sasmodels.rst2html.rst2html(rst, part='whole', math_output='mathjax')

Convert restructured text into simple html.

Valid math_output formats for formulas include: - html - mathml - mathjax See http://docutils.sourceforge.net/docs/user/config.html#math-output for details.

The following part choices are available: - whole: the entire html document - html_body: document division with title and contents and footer - body: contents only

There are other parts, but they don’t make sense alone:

subtitle, version, encoding, html_prolog, header, meta, html_title, title, stylesheet, html_subtitle, html_body, body, head, body_suffix, fragment, docinfo, html_head, head_prefix, body_prefix, footer, body_pre_docinfo, whole

sasmodels.rst2html.suppress_html_errors()

Context manager for keeping error reports out of the generated HTML.

Within the context, system message nodes in the docutils parse tree will be ignored. After the context, the usual behaviour will be restored.

sasmodels.rst2html.test_dollar()

Test substitution of dollar signs with equivalent RST math markup

sasmodels.rst2html.view_help(filename, qt=False)

View rst or html file. If qt use q viewer, otherwise use wx.

sasmodels.rst2html.view_html(html, url='')

HTML viewer app in Qt

sasmodels.rst2html.view_html_qtapp(html, url='')

HTML viewer app in Qt

sasmodels.rst2html.view_html_wxapp(html, url='')

HTML viewer app in wx

sasmodels.rst2html.view_url_qtapp(url)

URL viewer app in Qt

sasmodels.rst2html.view_url_wxapp(url)

URL viewer app in wx

sasmodels.rst2html.wxview(html, url='', size=(850, 540))

View HTML in a wx dialog

sasmodels.sasview_model module

Sasview model constructor.

Given a module defining an OpenCL kernel such as sasmodels.models.cylinder, create a sasview model class to run that kernel as follows:

from sasmodels.sasview_model import load_custom_model
CylinderModel = load_custom_model('sasmodels/models/cylinder.py')

sasmodels.sasview_model.MODELS = {}

set of defined models (standard and custom)

sasmodels.sasview_model.MODEL_BY_PATH = {}

custom model {path: model} mapping so we can check timestamps

sasmodels.sasview_model.MultiplicationModel(form_factor, structure_factor)

Returns a constructed product model from form_factor and structure_factor.

class sasmodels.sasview_model.MultiplicityInfo(number, control, choices, x_axis_label)

Bases: tuple

choices

Alias for field number 2

control

Alias for field number 1

number

Alias for field number 0

x_axis_label

Alias for field number 3

sasmodels.sasview_model.MultiplicityInfoType

alias of sasmodels.sasview_model.MultiplicityInfo

sasmodels.sasview_model.SUPPORT_OLD_STYLE_PLUGINS = True

True if pre-existing plugins, with the old names and parameters, should continue to be supported.

class sasmodels.sasview_model.SasviewModel(multiplicity=None)

Bases: object

Sasview wrapper for opencl/ctypes model.

calc_composition_models(qx)

returns parts of the composition model or None if not a composition model.

calculate_ER(mode=1)

Calculate the effective radius for P(q)*S(q)

mode is the R_eff type, which defaults to 1 to match the ER calculation for sasview models from version 3.x.

Returns:the value of the effective radius

calculate_Iq(qx, qy=None)

Calculate Iq for one set of q with the current parameters.

If the model is 1D, use q. If 2D, use qx, qy.

This should NOT be used for fitting since it copies the q vectors to the card for each evaluation.

The returned tuple contains the scattering intensity followed by a callable which returns a dictionary of intermediate data from ProductKernel.

calculate_VR()

Calculate the volf ratio for P(q)*S(q)

Returns:the value of the form:shell volume ratio

category = None

default model category

clone()

Return a identical copy of self

cutoff = 1e-05

default cutoff for polydispersity

description = None

short model description

details = None

units and limits for each parameter

dispersion = None

values for dispersion width, npts, nsigmas and type

evalDistribution(qdist)

Evaluate a distribution of q-values.

Parameters:qdist – array of q or a list of arrays [qx,qy]

• For 1D, a numpy array is expected as input

  evalDistribution(q)

where *q* is a numpy array.

• For 2D, a list of [qx,qy] is expected with 1D arrays as input

qx = [ qx[0], qx[1], qx[2], ....]
qy = [ qy[0], qy[1], qy[2], ....]

If the model is 1D only, then

\[q = \sqrt{q_x^2+q_y^2}\]

fixed = None

names of the fittable parameters

getDispParamList()

Return a list of polydispersity parameters for the model

getParam(name)

Set the value of a model parameter

Parameters:name – name of the parameter

getParamList()

Return a list of all available parameters for the model

getProfile()

Get SLD profile

: return: (z, beta) where z is a list of depth of the transition points

beta is a list of the corresponding SLD values

id = None

load/save name for the model

input_name = 'Q'

input_unit = 'A^{-1}'

is_fittable(par_name)

Check if a given parameter is fittable or not

Parameters:par_name – the parameter name to check

is_form_factor = False

True if model should appear as a form factor

is_multiplicity_model = False

True if model has multiplicity

is_structure_factor = False

True if model should appear as a structure factor

magnetic_params = None

names of the magnetic parameters in the order they appear

multiplicity = None

multiplicity value, or None if no multiplicity on the model

multiplicity_info = None

Multiplicity information

name = None

display name for the model

non_fittable = ()

parameters that are not fitted

orientation_params = None

names of the orientation parameters in the order they appear

output_name = 'Intensity'

output_unit = 'cm^{-1}'

params = None

parameter {name: value} mapping

run(x=0.0)

Evaluate the model

Parameters:x – input q, or [q,phi] Returns:scattering function P(q)

DEPRECATED: use calculate_Iq instead

classmethod runTests()

Run any tests built into the model and captures the test output.

Returns success flag and output

runXY(x=0.0)

Evaluate the model in cartesian coordinates

Parameters:x – input q, or [qx, qy] Returns:scattering function P(q)

DEPRECATED: use calculate_Iq instead

setParam(name, value)

Set the value of a model parameter

Parameters:

• name – name of the parameter
• value – value of the parameter

set_dispersion(parameter, dispersion)

Set the dispersion object for a model parameter

Parameters:

• parameter – name of the parameter [string]
• dispersion – dispersion object of type Dispersion

sasmodels.sasview_model.find_model(modelname)

Find a model by name. If the model name ends in py, try loading it from custom models, otherwise look for it in the list of builtin models.

sasmodels.sasview_model.load_custom_model(path)

Load a custom model given the model path.

sasmodels.sasview_model.load_standard_models()

Load and return the list of predefined models.

If there is an error loading a model, then a traceback is logged and the model is not returned.

sasmodels.sasview_model.magnetic_demo()

Demostrate call to magnetic model.

sasmodels.sasview_model.make_model_from_info(model_info)

Convert model_info into a SasView model wrapper.

sasmodels.sasview_model.reset_environment()

Clear the compute engine context so that the GUI can change devices.

This removes all compiled kernels, even those that are active on fit pages, but they will be restored the next time they are needed.

sasmodels.sasview_model.test_cylinder()

Test that the cylinder model runs, returning the value at [0.1,0.1].

sasmodels.sasview_model.test_empty_distribution()

Make sure that sasmodels returns NaN when there are no polydispersity points

sasmodels.sasview_model.test_model_list()

Make sure that all models build as sasview models

sasmodels.sasview_model.test_old_name()

Load and run cylinder model as sas.models.CylinderModel

sasmodels.sasview_model.test_product()

Test that 2-D hardsphere model runs and doesn’t produce NaN.

sasmodels.sasview_model.test_rpa()

Test that the 2-D RPA model runs

sasmodels.sasview_model.test_structure_factor()

Test that 2-D hardsphere model runs and doesn’t produce NaN.

sasmodels.sasview_model.test_structure_factor_background()

Check that sasview model and direct model match, with background=0.

sasmodels.sesans module

Conversion of scattering cross section from SANS (I(q), or rather, ds/dO) in absolute units (cm-1)into SESANS correlation function G using a Hankel transformation, then converting the SESANS correlation function into polarisation from the SESANS experiment

Everything is in units of metres except specified otherwise (NOT TRUE!!!) Everything is in conventional units (nm for spin echo length)

Wim Bouwman (w.g.bouwman@tudelft.nl), June 2013

class sasmodels.sesans.SesansTransform(z, SElength, lam, zaccept, Rmax, log_spacing=1.0003)

Bases: object

Spin-Echo SANS transform calculator. Similar to a resolution function, the SesansTransform object takes I(q) for the set of q_calc values and produces a transformed dataset

SElength (A) is the set of spin-echo lengths in the measured data.

zaccept (1/A) is the maximum acceptance of scattering vector in the spin echo encoding dimension (for ToF: Q of min(R) and max(lam)).

Rmax (A) is the maximum size sensitivity; larger radius requires more computation time.

apply(Iq)

Apply the SESANS transform to the computed I(q).

q = None

SElength from the data in the original data units; not used by transform but the GUI uses it, so make sure that it is present.

q_calc = None

q values to calculate when computing transform

sasmodels.special module

Special Functions

This following standard C99 math functions are available:

M_PI, M_PI_2, M_PI_4, M_SQRT1_2, M_E:

\(\pi\), \(\pi/2\), \(\pi/4\), \(1/\sqrt{2}\) and Euler’s constant \(e\)

exp, log, pow(x,y), expm1, log1p, sqrt, cbrt:

Power functions \(e^x\), \(\ln x\), \(x^y\), \(e^x - 1\), \(\ln 1 + x\), \(\sqrt{x}\), \(\sqrt[3]{x}\). The functions expm1(x) and log1p(x) are accurate across all \(x\), including \(x\) very close to zero.

sin, cos, tan, asin, acos, atan:

Trigonometry functions and inverses, operating on radians.

sinh, cosh, tanh, asinh, acosh, atanh:

Hyperbolic trigonometry functions.

atan2(y,x):

Angle from the \(x\)-axis to the point \((x,y)\), which is equal to \(\tan^{-1}(y/x)\) corrected for quadrant. That is, if \(x\) and \(y\) are both negative, then atan2(y,x) returns a value in quadrant III where atan(y/x) would return a value in quadrant I. Similarly for quadrants II and IV when \(x\) and \(y\) have opposite sign.

fabs(x), fmin(x,y), fmax(x,y), trunc, rint:

Floating point functions. rint(x) returns the nearest integer.

NAN:

NaN, Not a Number, \(0/0\). Use isnan(x) to test for NaN. Note that you cannot use x == NAN to test for NaN values since that will always return false. NAN does not equal NAN! The alternative, x != x may fail if the compiler optimizes the test away.

INFINITY:

\(\infty, 1/0\). Use isinf(x) to test for infinity, or isfinite(x) to test for finite and not NaN.

erf, erfc, tgamma, lgamma: do not use

Special functions that should be part of the standard, but are missing or inaccurate on some platforms. Use sas_erf, sas_erfc and sas_gamma instead (see below). Note: lgamma(x) has not yet been tested.

Some non-standard constants and functions are also provided:

M_PI_180, M_4PI_3:

\(\frac{\pi}{180}\), \(\frac{4\pi}{3}\)

SINCOS(x, s, c):

Macro which sets s=sin(x) and c=cos(x). The variables c and s must be declared first.

square(x):

\(x^2\)

cube(x):

\(x^3\)

sas_sinx_x(x):

\(\sin(x)/x\), with limit \(\sin(0)/0 = 1\).

powr(x, y):

\(x^y\) for \(x \ge 0\); this is faster than general \(x^y\) on some GPUs.

pown(x, n):

\(x^n\) for \(n\) integer; this is faster than general \(x^n\) on some GPUs.

FLOAT_SIZE:

The number of bytes in a floating point value. Even though all variables are declared double, they may be converted to single precision float before running. If your algorithm depends on precision (which is not uncommon for numerical algorithms), use the following:

#if FLOAT_SIZE>4
... code for double precision ...
#else
... code for single precision ...
#endif

SAS_DOUBLE:

A replacement for double so that the declared variable will stay double precision; this should generally not be used since some graphics cards do not support double precision. There is no provision for forcing a constant to stay double precision.

The following special functions and scattering calculations are defined. These functions have been tuned to be fast and numerically stable down to \(q=0\) even in single precision. In some cases they work around bugs which appear on some platforms but not others, so use them where needed. Add the files listed in source = ["lib/file.c", ...] to your model.py file in the order given, otherwise these functions will not be available.

polevl(x, c, n):

Polynomial evaluation \(p(x) = \sum_{i=0}^n c_i x^i\) using Horner’s method so it is faster and more accurate.

\(c = \{c_n, c_{n-1}, \ldots, c_0 \}\) is the table of coefficients, sorted from highest to lowest.

p1evl(x, c, n):

Evaluate normalized polynomial \(p(x) = x^n + \sum_{i=0}^{n-1} c_i x^i\) using Horner’s method so it is faster and more accurate.

\(c = \{c_{n-1}, c_{n-2} \ldots, c_0 \}\) is the table of coefficients, sorted from highest to lowest.

sas_gamma(x):

Gamma function sas_gamma\((x) = \Gamma(x)\).

The standard math function, tgamma(x) is unstable for \(x < 1\) on some platforms.

sas_gammaln(x):

log gamma function sas_gammaln\((x) = \log \Gamma(|x|)\).

The standard math function, lgamma(x), is incorrect for single precision on some platforms.

sas_gammainc(a, x), sas_gammaincc(a, x):

Incomplete gamma function sas_gammainc\((a, x) = \int_0^x t^{a-1}e^{-t}\,dt / \Gamma(a)\) and complementary incomplete gamma function sas_gammaincc\((a, x) = \int_x^\infty t^{a-1}e^{-t}\,dt / \Gamma(a)\)

sas_erf(x), sas_erfc(x):

Error function sas_erf\((x) = \frac{2}{\sqrt\pi}\int_0^x e^{-t^2}\,dt\) and complementary error function sas_erfc\((x) = \frac{2}{\sqrt\pi}\int_x^{\infty} e^{-t^2}\,dt\).

The standard math functions erf(x) and erfc(x) are slower and broken on some platforms.

sas_J0(x):

Bessel function of the first kind sas_J0\((x)=J_0(x)\) where \(J_0(x) = \frac{1}{\pi}\int_0^\pi \cos(x\sin(\tau))\,d\tau\).

The standard math function j0(x) is not available on all platforms.

sas_J1(x):

Bessel function of the first kind sas_J1\((x)=J_1(x)\) where \(J_1(x) = \frac{1}{\pi}\int_0^\pi \cos(\tau - x\sin(\tau))\,d\tau\).

The standard math function j1(x) is not available on all platforms.

sas_JN(n, x):

Bessel function of the first kind and integer order \(n\): sas_JN\((n, x)=J_n(x)\) where \(J_n(x) = \frac{1}{\pi}\int_0^\pi \cos(n\tau - x\sin(\tau))\,d\tau\). If \(n\) = 0 or 1, it uses sas_J0(x) or sas_J1(x), respectively.

The standard math function jn(n, x) is not available on all platforms.

sas_Si(x):

Sine integral sas_Si\((x) = \int_0^x \tfrac{\sin t}{t}\,dt\).

This function uses Taylor series for small and large arguments:

For large arguments,

\[\text{Si}(x) \sim \frac{\pi}{2} - \frac{\cos(x)}{x} \left(1 - \frac{2!}{x^2} + \frac{4!}{x^4} - \frac{6!}{x^6} \right) - \frac{\sin(x)}{x} \left(\frac{1}{x} - \frac{3!}{x^3} + \frac{5!}{x^5} - \frac{7!}{x^7}\right)\]

For small arguments,

\[\text{Si}(x) \sim x - \frac{x^3}{3\times 3!} + \frac{x^5}{5 \times 5!} - \frac{x^7}{7 \times 7!} + \frac{x^9}{9\times 9!} - \frac{x^{11}}{11\times 11!}\]

sas_3j1x_x(x):

Spherical Bessel form sas_3j1x_x\((x) = 3 j_1(x)/x = 3 (\sin(x) - x \cos(x))/x^3\), with a limiting value of 1 at \(x=0\), where \(j_1(x)\) is the spherical Bessel function of the first kind and first order.

This function uses a Taylor series for small \(x\) for numerical accuracy.

sas_2J1x_x(x):

Bessel form sas_2J1x_x\((x) = 2 J_1(x)/x\), with a limiting value of 1 at \(x=0\), where \(J_1(x)\) is the Bessel function of first kind and first order.

gauss76.n, gauss76.z[i], gauss76.w[i]:

Points \(z_i\) and weights \(w_i\) for 76-point Gaussian quadrature, respectively, computing \(\int_{-1}^1 f(z)\,dz \approx \sum_{i=1}^{76} w_i\,f(z_i)\). When translating the model to C, include ‘lib/gauss76.c’ in the source and use GAUSS_N, GAUSS_Z, and GAUSS_W.

Similar arrays are available in gauss20 for 20-point quadrature and gauss150.c for 150-point quadrature. By using import gauss76 as gauss it is easy to change the number of points in the integration.

class sasmodels.special.Gauss(w, z)

Bases: object

Gauss-Legendre integration weights

sasmodels.special.SINCOS(x)

return sin(x), cos(x)

sasmodels.special.cube(x)

return x^3

sasmodels.special.p1evl(x, c, n)

return x^n + p(x) for polynomial p of degree n-1 with coefficients c

sasmodels.special.polevl(x, c, n)

return p(x) for polynomial p of degree n-1 with coefficients c

sasmodels.special.pown(x, n)

return x^n for n integer

sasmodels.special.powr(x, y)

return x^y for x>0

sasmodels.special.sas_2J1x_x(x)

return 2*J1(x)/x

sasmodels.special.sas_3j1x_x(x)

return 3*j1(x)/x

sasmodels.special.sas_Si(x)

return Si(x)

sasmodels.special.sas_j1(x)

return j1(x)

sasmodels.special.sas_sinx_x(x)

return sin(x)/x

sasmodels.special.sincos(x)

return sin(x), cos(x)

sasmodels.special.square(x)

return x^2

sasmodels.weights module

SAS distributions for polydispersity.

class sasmodels.weights.ArrayDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Empirical dispersion curve.

Use set_weights() to set \(w = f(x)\).

default = {'npts': 35, 'nsigmas': 1, 'width': 0}

set_weights(values, weights)

Set the weights for the given x values.

type = 'array'

class sasmodels.weights.BoltzmannDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Boltzmann dispersion, with \(\sigma=k T/E\).

\[w = \exp\left( -|x - c|/\sigma\right)\]

default = {'npts': 35, 'nsigmas': 3, 'width': 0}

type = 'boltzmann'

class sasmodels.weights.Dispersion(npts=None, width=None, nsigmas=None)

Bases: object

Base dispersion object.

Subclasses should define _weights(center, sigma, lb, ub) which returns the x points and their corresponding weights.

default = {'npts': 35, 'nsigmas': 3, 'width': 0}

get_pars()

Return the parameters to the disperser as a dictionary.

get_weights(center, lb, ub, relative)

Return the weights for the distribution.

center is the center of the distribution

lb, ub are the min and max allowed values

relative is True if the distribution width is proportional to the center value instead of absolute. For polydispersity use relative. For orientation parameters use absolute.

set_weights(values, weights)

Set the weights on the disperser if it is ArrayDispersion.

type = 'base disperser'

class sasmodels.weights.GaussianDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Gaussian dispersion, with 1-\(\sigma\) width.

\[w = \exp\left(-\tfrac12 (x - c)^2/\sigma^2\right)\]

default = {'npts': 35, 'nsigmas': 3, 'width': 0}

type = 'gaussian'

class sasmodels.weights.LogNormalDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

log Gaussian dispersion, with 1-\(\sigma\) width.

\[w = \frac{\exp\left(-\tfrac12 (\ln x - c)^2/\sigma^2\right)}{x\sigma}\]

default = {'npts': 80, 'nsigmas': 8, 'width': 0}

type = 'lognormal'

class sasmodels.weights.RectangleDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Uniform dispersion, with width \(\sqrt{3}\sigma\).

\[w = 1\]

default = {'npts': 35, 'nsigmas': 1.73205, 'width': 0}

type = 'rectangle'

class sasmodels.weights.SchulzDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Schultz dispersion, with 1-\(\sigma\) width.

\[w = \frac{z^z\,R^{z-1}}{e^{Rz}\,c \Gamma(z)}\]

where \(c\) is the center of the distribution, \(R = x/c\) and \(z=(c/\sigma)^2\).

This is evaluated using logarithms as

\[w = \exp\left(z \ln z + (z-1)\ln R - Rz - \ln c - \ln \Gamma(z) \right)\]

default = {'npts': 80, 'nsigmas': 8, 'width': 0}

type = 'schulz'

class sasmodels.weights.UniformDispersion(npts=None, width=None, nsigmas=None)

Bases: sasmodels.weights.Dispersion

Uniform dispersion, with width \(\sigma\).

\[w = 1\]

default = {'npts': 35, 'nsigmas': None, 'width': 0}

type = 'uniform'

sasmodels.weights.get_weights(disperser, n, width, nsigmas, value, limits, relative)

Return the set of values and weights for a polydisperse parameter.

disperser is the name of the disperser.

n is the number of points in the weight vector.

width is the width of the disperser distribution.

nsigmas is the number of sigmas to span for the dispersion convolution.

value is the value of the parameter in the model.

limits is [lb, ub], the lower and upper bound on the possible values.

relative is true if width is defined in proportion to the value of the parameter, and false if it is an absolute width.

Returns (value, weight), where value and weight are vectors.

sasmodels.weights.load_weights(pattern=None)

Load dispersion distributions matching the given glob pattern

sasmodels.weights.plot_weights(model_info, mesh)

Plot the weights returned by get_weights().

model_info defines model parameters, etc.

mesh is a list of tuples containing (value, dispersity, weights) for each parameter, where (dispersity, weights) pairs are the distributions to be plotted.

Module contents

sasmodels

sasmodels is a package containing models for small angle neutron and xray scattering. Models supported are the one dimensional circular average and two dimensional oriented patterns. As well as the form factor calculations for the individual shapes sasmodels also provides automatic shape polydispersity, angular dispersion and resolution convolution. SESANS patterns can be computed for any model.

Models can be written in python or in C. C models can run on the GPU if OpenCL drivers are available. See generate for details on defining new models.

sasmodels.data_files()

Return the data files to be installed with the package.

The format is a list of (directory, [files…]) pairs which can be used directly in setup(…,data_files=…) for setup.py.