8. Model access

sasmodels.core

Core model handling routines.

sasmodels.core.build_model(model_info: sasmodels.modelinfo.ModelInfo, dtype: Optional[str] = None, platform: str = 'ocl') sasmodels.kernel.KernelModel

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.list_models(kind: Optional[str] = None) List[str]

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: str, dtype: Optional[str] = None, platform: str = 'ocl') sasmodels.kernel.KernelModel

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: str) sasmodels.modelinfo.ModelInfo

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.precompile_dlls(path: str, dtype: str = 'double') List[str]

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”.