10. 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 make_details() to build a details object which can be passed to one of the computational kernels.

class sasmodels.details.CallDetails(model_info: ModelInfo)

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.

__class__

alias of type

__delattr__(name, /)

Implement delattr(self, name).

__dict__ = mappingproxy({'__module__': 'sasmodels.details', '__doc__': '\n    Manage the polydispersity information for the kernel call.\n\n    Conceptually, a polydispersity calculation is an integral over a mesh\n    in n-D space where n is the number of polydisperse parameters.  In order\n    to keep the program responsive, and not crash the GPU, only a portion\n    of the mesh is computed at a time.  Meshes with a large number of points\n    will therefore require many calls to the polydispersity loop.  Restarting\n    a nested loop in the middle requires that the indices of the individual\n    mesh dimensions can be computed for the current loop location.  This\n    is handled by the *pd_stride* vector, with n//stride giving the loop\n    index and n%stride giving the position in the sub loops.\n\n    One of the parameters may be the latitude.  When integrating in polar\n    coordinates, the total circumference decreases as latitude varies from\n    pi r^2 at the equator to 0 at the pole, and the weight associated\n    with a range of latitude values needs to be scaled by this circumference.\n    This scale factor needs to be updated each time the theta value\n    changes.  *theta_par* indicates which of the values in the parameter\n    vector is the latitude parameter, or -1 if there is no latitude\n    parameter in the model.  In practice, the normalization term cancels\n    if the latitude is not a polydisperse parameter.\n    ', 'parts': None, '__init__': <function CallDetails.__init__>, 'pd_par': <property object>, 'pd_length': <property object>, 'pd_offset': <property object>, 'pd_stride': <property object>, 'num_eval': <property object>, 'num_weights': <property object>, 'num_active': <property object>, 'theta_par': <property object>, 'show': <function CallDetails.show>, '__dict__': <attribute '__dict__' of 'CallDetails' objects>, '__weakref__': <attribute '__weakref__' of 'CallDetails' objects>, '__annotations__': {'parts': 'list["CallDetails"]', 'offset': 'np.ndarray', 'length': 'np.ndarray'}})

__dir__()

Default dir() implementation.

__doc__ = '\n    Manage the polydispersity information for the kernel call.\n\n    Conceptually, a polydispersity calculation is an integral over a mesh\n    in n-D space where n is the number of polydisperse parameters.  In order\n    to keep the program responsive, and not crash the GPU, only a portion\n    of the mesh is computed at a time.  Meshes with a large number of points\n    will therefore require many calls to the polydispersity loop.  Restarting\n    a nested loop in the middle requires that the indices of the individual\n    mesh dimensions can be computed for the current loop location.  This\n    is handled by the *pd_stride* vector, with n//stride giving the loop\n    index and n%stride giving the position in the sub loops.\n\n    One of the parameters may be the latitude.  When integrating in polar\n    coordinates, the total circumference decreases as latitude varies from\n    pi r^2 at the equator to 0 at the pole, and the weight associated\n    with a range of latitude values needs to be scaled by this circumference.\n    This scale factor needs to be updated each time the theta value\n    changes.  *theta_par* indicates which of the values in the parameter\n    vector is the latitude parameter, or -1 if there is no latitude\n    parameter in the model.  In practice, the normalization term cancels\n    if the latitude is not a polydisperse parameter.\n    '

__eq__(value, /)

Return self==value.

__format__(format_spec, /)

Default object formatter.

__ge__(value, /)

Return self>=value.

__getattribute__(name, /)

Return getattr(self, name).

__getstate__()

Helper for pickle.

__gt__(value, /)

Return self>value.

__hash__()

Return hash(self).

__init__(model_info: ModelInfo) → None

classmethod __init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__(value, /)

Return self<=value.

__lt__(value, /)

Return self<value.

__module__ = 'sasmodels.details'

__ne__(value, /)

Return self!=value.

classmethod __new__(*args, **kwargs)

__reduce__()

Helper for pickle.

__reduce_ex__(protocol, /)

Helper for pickle.

__repr__()

Return repr(self).

__setattr__(name, value, /)

Implement setattr(self, name, value).

__sizeof__()

Size of object in memory, in bytes.

__str__()

Return str(self).

classmethod __subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.__subclasscheck__(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

__weakref__

list of weak references to the object

property num_active

Number of active polydispersity loops

property num_eval

Total size of the pd mesh

property num_weights

Total length of all the weight vectors

parts: list[CallDetails] = None

property pd_length

Number of weights for each polydisperse parameter

property pd_offset

Offsets for the individual weight vectors in the set of weights

property pd_par

List of polydisperse parameters

property pd_stride

Stride in the pd mesh for each pd dimension

show(values=None)

Print the polydispersity call details to the console

property theta_par

Location of the theta parameter in the parameter vector

sasmodels.details.convert_magnetism(parameters: ParameterTable, values: Sequence[ndarray]) → bool

Convert magnetism values from polar to rectangular coordinates.

Returns True if any magnetism is present.

sasmodels.details.correct_theta_weights(parameters: ParameterTable, dispersity: Sequence[ndarray], weights: Sequence[ndarray]) → Sequence[ndarray]

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: ModelInfo, mesh: list[tuple[float, ndarray, ndarray]]) → tuple[list[ndarray], list[ndarray]]

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: ModelInfo, length: ndarray, offset: ndarray, num_weights: int) → CallDetails

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: Kernel, mesh: tuple[list[ndarray], list[ndarray]]) → tuple[CallDetails, ndarray, bool]

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