9. Parameter packing for kernel calls

sasmodels.details

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

show(values=None)

Print the polydispersity call details to the console

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

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