-                      r870a2f4
+                      r9ee2756
 This document describes the layer between the form factor kernels and the
 model calculator which implements the polydispersity and magnetic SLD
+model calculator which implements the dispersity and magnetic SLD
 calculations.  There are three separate implementations of this layer,
 :mod:`kernelcl` for OpenCL, which operates on a single Q value at a time,
 …
 Each implementation provides three different calls *Iq*, *Iqxy* and *Imagnetic*
+for 1-D, 2-D and 2-D magnetic kernels respectively.
+The C code is defined in *kernel_iq.c* and *kernel_iq.cl* for DLL and OpenCL
+respectively.  The kernel call looks as follows::
+for 1-D, 2-D and 2-D magnetic kernels respectively. The C code is defined
+in *kernel_iq.c*, with the minor differences between OpenCL and DLL handled
+by #ifdef statements.
+The kernel call looks as follows::
   kernel void KERNEL_NAME(
       int nq,                  // Number of q values in the q vector
       int pd_start,            // Starting position in the polydispersity loop
       int pd_stop,             // Ending position in the polydispersity loop
       ProblemDetails *details, // Polydispersity info
+      int pd_start,            // Starting position in the dispersity loop
+      int pd_stop,             // Ending position in the dispersity loop
+      ProblemDetails *details, // dispersity info
       double *values,          // Value and weights vector
       double *q,               // q or (qx,qy) vector
       double *result,          // returned I(q), with result[nq] = pd_weight
       double cutoff)           // polydispersity weight cutoff
+      double cutoff)           // dispersity weight cutoff
 The details for OpenCL and the python loop are slightly different, but these
 …
 *nq* indicates the number of q values that will be calculated.
 The *pd_start* and *pd_stop* parameters set the range of the polydispersity
 loop to compute for the current kernel call.   Give a polydispersity
+The *pd_start* and *pd_stop* parameters set the range of the dispersity
+loop to compute for the current kernel call.   Give a dispersity
 calculation with 30 weights for length and 30 weights for radius for example,
 there are a total of 900 calls to the form factor required to compute the
 …
 the length index to 3 and the radius index to 10 for a position of 3*30+10=100,
 and could then proceed to position 200.  This allows us to interrupt the
 calculation in the middle of a long polydispersity loop without having to
+calculation in the middle of a long dispersity loop without having to
 do special tricks with the C code.  More importantly, it stops the OpenCL
 kernel in a reasonable time; because the GPU is used by the operating
 …
 The *ProblemDetails* structure is a direct map of the
 :class:`details.CallDetails` buffer.  This indicates which parameters are
 polydisperse, and where in the values vector the values and weights can be
 found.  For each polydisperse parameter there is a parameter id, the length
 of the polydispersity loop for that parameter, the offset of the parameter
+:class:`details.CallDetails` buffer.  This indicates which parameters have
+dispersity, and where in the values vector the values and weights can be
+found.  For each parameter with dispersity there is a parameter id, the length
+of the dispersity loop for that parameter, the offset of the parameter
 values in the pd value and pd weight vectors and the 'stride' from one index
 to the next, which is used to translate between the position in the
 polydispersity loop and the particular parameter indices.  The *num_eval*
 field is the total size of the polydispersity loop.  *num_weights* is the
+dispersity loop and the particular parameter indices.  The *num_eval*
+field is the total size of the dispersity loop.  *num_weights* is the
 number of elements in the pd value and pd weight vectors.  *num_active* is
 the number of non-trivial pd loops (polydisperse parameters should be ordered
 by decreasing pd vector length, with a length of 1 meaning no polydispersity).
+the number of non-trivial pd loops (parameters with dispersity should be ordered
+by decreasing pd vector length, with a length of 1 meaning no dispersity).
 Oriented objects in 2-D need a cos(theta) spherical correction on the angular
 variation in order to preserve the 'surface area' of the weight distribution.
 …
 *(Mx, My, Mz)*.  Sample magnetization is translated from *(M, theta, phi)*
 to *(Mx, My, Mz)* before the kernel is called.   After the fixed values comes
 the pd value vector, with the polydispersity values for each parameter
+the pd value vector, with the dispersity values for each parameter
 stacked one after the other.  The order isn't important since the location
 for each parameter is stored in the *pd_offset* field of the *ProblemDetails*
 …
 values, the pd weight vector is stored, with the same configuration as the
 pd value vector.  Note that the pd vectors can contain values that are not
 in the polydispersity loop; this is used by :class:`mixture.MixtureKernel`
+in the dispersity loop; this is used by :class:`mixture.MixtureKernel`
 to make it easier to call the various component kernels.
 …
 The *results* vector contains one slot for each of the *nq* values, plus
 one extra slot at the end for the current polydisperse normalization.  This
+is required when the polydispersity loop is broken across several kernel
 calls.
+one extra slot at the end for the weight normalization accumulated across
+all points in the dispersity mesh.  This is required when the dispersity
+loop is broken across several kernel calls.
 *cutoff* is a importance cutoff so that points which contribute negligibly
 …
 - USE_OPENCL is defined if running in opencl
 - MAX_PD is the maximum depth of the polydispersity loop [model specific]
+- MAX_PD is the maximum depth of the dispersity loop [model specific]
 - NUM_PARS is the number of parameter values in the kernel.  This may be
   more than the number of parameters if some of the parameters are vector
   values.
 - NUM_VALUES is the number of fixed values, which defines the offset in the
   value list to the polydisperse value and weight vectors.
+  value list to the dispersity value and weight vectors.
 - NUM_MAGNETIC is the number of magnetic SLDs
 - MAGNETIC_PARS is a comma separated list of the magnetic SLDs, indicating
   their locations in the values vector.
+- MAGNETIC_PAR0 to MAGNETIC_PAR2 are the first three magnetic parameter ids
+  so we can hard code the setting of magnetic values if there are only a
+  few of them.
+- MAGNETIC_PAR1, ... are the first three magnetic parameter ids so we can
+  hard code the setting of magnetic values if there are only a few of them.
 - KERNEL_NAME is the name of the function being declared
 - PARAMETER_TABLE is the declaration of the parameters to the kernel:
 …
     Cylinder2D::
         #define CALL_IQ(q, i, var) Iqxy(q[2*i], q[2*i+1], \
+        #define CALL_IQ(q, i, var) Iqxy(qa, qc, \
         var.length, \
         var.radius, \
         var.sld, \
+        var.sld_solvent, \
+        var.theta, \
+        var.phi)
+        var.sld_solvent)
 - CALL_VOLUME(var) is similar, but for calling the form volume::
 …
         #define INVALID(var) constrained(var.p1, var.p2, var.p3)
 Our design supports a limited number of polydispersity loops, wherein
 we need to cycle through the values of the polydispersity, calculate
+Our design supports a limited number of dispersity loops, wherein
+we need to cycle through the values of the dispersity, calculate
 the I(q, p) for each combination of parameters, and perform a normalized
 weighted sum across all the weights.  Parameters may be passed to the
 underlying calculation engine as scalars or vectors, but the polydispersity
+underlying calculation engine as scalars or vectors, but the dispersity
 calculator treats the parameter set as one long vector.
 Let's assume we have 8 parameters in the model, with two polydisperse.  Since
 this is a 1-D model the orientation parameters won't be used::
+Let's assume we have 8 parameters in the model, two of which allow dispersity.
+Since this is a 1-D model the orientation parameters won't be used::
 : scale        {scl = constant}
 …
 : radius       {r = vector of 10pts}
 : length       {l = vector of 30pts}
 : sld          {s = constant/(radius**2*length)}
+: sld          {s1 = constant/(radius**2*length)}
 : sld_solvent  {s2 = constant}
 : theta        {not used}
 …
 This generates the following call to the kernel.  Note that parameters 4 and
 are treated as polydisperse even though they are not --- this is because
+are treated as having dispersity even though they don't --- this is because
 it is harmless to do so and simplifies the looping code::
 …
         pd_offset = {10, 0, 31, 32}   // *length* starts at index 10 in weights
         pd_stride = {1, 30, 300, 300} // cumulative product of pd length
         num_eval = 300   // 300 values in the polydispersity loop
+        num_eval = 300   // 300 values in the dispersity loop
         num_weights = 42 // 42 values in the pd vector
         num_active = 2   // only the first two pd are active
 …
     values = { scl, bkg,                                  // universal
                r, l, s, s2, theta, phi,                   // kernel pars
+               r, l, s1, s2, theta, phi,                  // kernel pars
                in spin, out spin, spin angle,             // applied magnetism
                mx s, my s, mz s, mx s2, my s2, mz s2,     // magnetic slds
+               mx s1, my s1, mz s1, mx s2, my s2, mz s2,  // magnetic slds
                r0, .., r9, l0, .., l29, s, s2,            // pd values
                r0, .., r9, l0, .., l29, s, s2}            // pd weights
 …
     result = {r1, ..., r130, pd_norm, x }
 The polydisperse parameters are stored in as an array of parameter
 indices, one for each polydisperse parameter, stored in pd_par[n].
+Non-polydisperse parameters do not appear in this array. Each polydisperse
+The dispersity parameters are stored in as an array of parameter
+indices, one for each parameter, stored in pd_par[n]. Parameters which do
+not support dispersity do not appear in this array. Each dispersity
 parameter has a weight vector whose length is stored in pd_length[n].
 The weights are stored in a contiguous vector of weights for all
 …
 in pd_offset[n].  The values corresponding to the weights are stored
 together in a separate weights[] vector, with offset stored in
 par_offset[pd_par[n]]. Polydisperse parameters should be stored in
+par_offset[pd_par[n]]. Dispersity parameters should be stored in
 decreasing order of length for highest efficiency.
 We limit the number of polydisperse dimensions to MAX_PD (currently 4),
 though some models may have fewer if they have fewer polydisperse
+We limit the number of dispersity dimensions to MAX_PD (currently 4),
+though some models may have fewer if they have fewer dispersity
 parameters.  The main reason for the limit is to reduce code size.
+Each additional polydisperse parameter requires a separate polydispersity
+loop.  If more than 4 levels of polydispersity are needed, then kernel_iq.c
+and kernel_iq.cl will need to be extended.
+Each additional dispersity parameter requires a separate dispersity
+loop.  If more than 4 levels of dispersity are needed, then we need to
+switch to a monte carlo importance sampling algorithm with better
+performance for high-dimensional integrals.
 Constraints between parameters are not supported.  Instead users will
 …
 theta since the polar coordinates normalization is tied to this parameter.
 If there is no polydispersity we pretend that it is polydisperisty with one
+parameter, pd_start=0 and pd_stop=1.  We may or may not short circuit the
 calculation in this case, depending on how much time it saves.
+If there is no dispersity we pretend that we have a disperisty mesh over
+a single parameter with a single point in the distribution, giving
+pd_start=0 and pd_stop=1.
 The problem details structure could be allocated and sent in as an integer
 array using the read-only flag.  This would allow us to copy it once per fit
 along with the weights vector, since features such as the number of
+polydisperity elements per pd parameter or the coordinated won't change
+between function evaluations.  A new parameter vector must be sent for
+each I(q) evaluation.  This is not currently implemented, and would require
 some resturcturing of the :class:`sasview_model.SasviewModel` interface.
 The results array will be initialized to zero for polydispersity loop
+disperity points per pd parameter won't change between function evaluations.
+A new parameter vector must be sent for each I(q) evaluation.  This is
+not currently implemented, and would require some resturcturing of
+the :class:`sasview_model.SasviewModel` interface.
+The results array will be initialized to zero for dispersity loop
 entry zero, and preserved between calls to [start, stop] so that the
 results accumulate by the time the loop has completed.  Background and
 …
 This will require accumulated error for each I(q) value to be preserved
 between kernel calls to implement this fully.  The kernel_iq.c code, which
 loops over q for each parameter set in the polydispersity loop, will need
 also need the accumalation vector.
+between kernel calls to implement this fully.  The *kernel_iq.c* code, which
+loops over q for each parameter set in the dispersity loop, will also need
+the accumulation vector.

Note: See TracChangeset for help on using the changeset viewer.

SasView

Changeset 9ee2756 in sasmodels for doc/developer/calculator.rst

Legend:

doc/developer/calculator.rst

Download in other formats: