3. Compare models on different compute engines¶
sasmodels.compare
¶
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 ./compare.sh (Linux, Mac) or compare.bat (Windows) in the sasmodels root to see the command line options.
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 PYOPENCL_CTX environment variable ahead of time. 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 PYOPENCL_CTX variable. On Windows you will need to remove the quotes.
Program description¶
usage: sascomp model [options…] [key=val]
Generate and compare SAS models. If a single model is specified it shows a plot of that model. Different models can be compared, or the same model with different parameters. The same model with the same parameters can be compared with different calculation engines to see the effects of precision on the resultant values.
model or model1,model2 are the names of the models to compare (see below).
Options (* for default):
=== data generation === -data=”path” uses q, dq from the data file -noise=0 sets the measurement error dI/I -res=0 sets the resolution width dQ/Q if calculating with resolution -lowq*/-midq/-highq/-exq use q values up to 0.05, 0.2, 1.0, 10.0 -q=min:max alternative specification of qrange -nq=128 sets the number of Q points in the data set -1d*/-2d computes 1d or 2d data -zero indicates that q=0 should be included
=== model parameters === -preset*/-random[=seed] preset or random parameters -sets=n generates n random datasets with the seed given by -random=seed -pars/-nopars* prints the parameter set or not -default/-demo* use demo vs default parameters -sphere[=150] set up spherical integration over theta/phi using n points
=== calculation options === -mono*/-poly force monodisperse or allow polydisperse random parameters -cutoff=1e-5* cutoff value for including a point in polydispersity -magnetic/-nonmagnetic* suppress magnetism -accuracy=Low accuracy of the resolution calculation Low, Mid, High, Xhigh -neval=1 sets the number of evals for more accurate timing -ngauss=0 overrides the number of points in the 1-D gaussian quadrature
=== precision options === -engine=default uses the default calcution precision -single/-double/-half/-fast sets an OpenCL calculation engine -single!/-double!/-quad! sets an OpenMP calculation engine
=== plotting === -plot*/-noplot plots or suppress the plot of the model -linear/-log*/-q4 intensity scaling on plots -hist/-nohist* plot histogram of relative error -abs/-rel* plot relative or absolute error -title=”note” adds note to the plot title, after the model name -weights shows weights plots for the polydisperse parameters -profile shows the sld profile if the model has a plottable sld profile
=== output options === -edit starts the parameter explorer -help/-html shows the model docs instead of running the model
=== environment variables === -DSAS_MODELPATH=~/.sasmodels/custom_models sets path to custom models -DSAS_WEIGHTS_PATH=~/.sasview/weights sets path to custom distributions -DSAS_OPENCL=vendor:device|cuda:device|none sets the target GPU device -DXDG_CACHE_HOME=~/.cache sets the pyopencl cache root (linux only) -DSAS_COMPILER=tinycc|msvc|mingw|unix sets the DLL compiler -DSAS_OPENMP=0 set to 1 to turn on OpenMP for the DLLs -DSAS_DLL_PATH=~/.sasmodels/compiled_models sets the DLL cache
The interpretation of quad precision depends on architecture, and may vary from 64-bit to 128-bit, with 80-bit floats being common (1e-19 precision). On unix and mac you may need single quotes around the DLL computation engines, such as -engine=’single!,double!’ since !, is treated as a history expansion request in the shell.
Key=value pairs allow you to set specific values for the model parameters. Key=value1,value2 to compare different values of the same parameter. The value can be an expression including other parameters.
Items later on the command line override those that appear earlier.
Examples:
# compare single and double precision calculation for a barbell sascomp barbell -engine=single,double
# generate 10 random lorentz models, with seed=27 sascomp lorentz -sets=10 -seed=27
# compare ellipsoid with R = R_polar = R_equatorial to sphere of radius R sascomp sphere,ellipsoid radius_polar=radius radius_equatorial=radius
# model timing test requires multiple evals to perform the estimate sascomp pringle -engine=single,double -timing=100,100 -noplot
-
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.
-
-
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.
build_math_context
()¶ build dictionary of functions from math module
-
sasmodels.compare.
columnize
(items, indent='', width=79)¶ Format a list of strings into columns.
Returns a string with carriage returns ready for printing.
-
sasmodels.compare.
compare
(opts, limits=None, maxdim=inf)¶ Preform a comparison using options from the command line.
limits are the limits on the values to use, 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 is the maximum value for any parameter with units of Angstrom.
-
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, use_demo=False)¶ Extract demo 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=inf)¶ Generate a parameter set.
The default 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. If maxdim is given, limit parameters with units of Angstrom to this value.
Returns a pair of parameter dictionaries for base and comparison models.
-
sasmodels.compare.
plot_models
(opts, result, limits=None, setnum=0)¶ Plot the results from
run_model()
.
-
sasmodels.compare.
plot_profile
(model_info, label='base', **args)¶ Plot the profile returned by the model profile method.
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.
-
sasmodels.compare.
randomize_pars
(model_info, pars)¶ 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, suppress=True)¶ If suppress is True complete eliminate magnetism of the model to test models more quickly. If suppress is False, make sure at least one sld parameter is magnetic, setting the first parameter to have a strong magnetic sld (8/A^2) at 60 degrees (with no explicit demo parameters given in the model, there will be no default magnetism).
-
sasmodels.compare.
suppress_pd
(pars, suppress=True)¶ If suppress is True complete eliminate polydispersity of the model to test models more quickly. If suppress is False, make sure at least one parameter is polydisperse, setting the first polydispersity parameter to 15% if no polydispersity is given (with no explicit demo parameters given in the model, there will be no default polydispersity).
-
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.
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>, 'comb': <built-in function comb>, 'copysign': <built-in function copysign>, 'cos': <built-in function cos>, 'cosh': <built-in function cosh>, 'degrees': <built-in function degrees>, 'dist': <built-in function dist>, '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>, 'isqrt': <built-in function isqrt>, '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, 'perm': <built-in function perm>, 'pi': 3.141592653589793, 'pow': <built-in function pow>, 'prod': <built-in function prod>, 'radians': <built-in function radians>, 'remainder': <built-in function remainder>, '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