Changes in doc/guide/plugin.rst [81751c2:94bfa42] in sasmodels

File:

• doc/guide/plugin.rst (modified) (13 diffs)

doc/guide/plugin.rst

@@ -273 +273 @@
 `Form_Factors`_ for more details.
 
+**model_info = ...** lets you define a model directly, for example, by
+loading and modifying existing models.  This is done implicitly by
+:func:`sasmodels.core.load_model_info`, which can create a mixture model
+from a pair of existing models.  For example::
+
+    from sasmodels.core import load_model_info
+    model_info = load_model_info('sphere+cylinder')
+
+See :class:`sasmodels.modelinfo.ModelInfo` for details about the model
+attributes that are defined.
+
 Model Parameters
 ................
@@ -291 +302 @@
 
 **Note: The order of the parameters in the definition will be the order of the
-parameters in the user interface and the order of the parameters in Fq(), Iq(),
-Iqac(), Iqabc(), form_volume() and shell_volume().
-And** *scale* **and** *background* **parameters are implicit to all models,
-so they do not need to be included in the parameter table.**
+parameters in the user interface and the order of the parameters in Iq(),
+Iqac(), Iqabc() and form_volume(). And** *scale* **and** *background*
+**parameters are implicit to all models, so they do not need to be included
+in the parameter table.**
 
 - **"name"** is the name of the parameter shown on the FitPage.
@@ -363 +374 @@
     scattered intensity.
 
-  - "volume" parameters are passed to Fq(), Iq(), Iqac(), Iqabc(), form_volume()
-    and shell_volume(), and have polydispersity loops generated automatically.
+  - "volume" parameters are passed to Iq(), Iqac(), Iqabc() and form_volume(),
+    and have polydispersity loops generated automatically.
 
   - "orientation" parameters are not passed, but instead are combined with
@@ -492 +503 @@
 used.
 
-Hollow shapes, where the volume fraction of particle corresponds to the
-material in the shell rather than the volume enclosed by the shape, must
-also define a *shell_volume(par1, par2, ...)* function.  The parameters
-are the same as for *form_volume*.  The *I(q)* calculation should use
-*shell_volume* squared as its scale factor for the volume normalization.
-The structure factor calculation needs *form_volume* in order to properly
-scale the volume fraction parameter, so both functions are required for
-hollow shapes.
-
-Note: Pure python models do not yet support direct computation of the
-average of $F(q)$ and $F^2(q)$.
-
 Embedded C Models
 .................
@@ -515 +514 @@
 This expands into the equivalent C code::
 
+    #include <math.h>
     double Iq(double q, double par1, double par2, ...);
     double Iq(double q, double par1, double par2, ...)
@@ -523 +523 @@
 *form_volume* defines the volume of the shape. As in python models, it
 includes only the volume parameters.
-
-*form_volume* defines the volume of the shell for hollow shapes. As in
-python models, it includes only the volume parameters.
 
 **source=['fn.c', ...]** includes the listed C source files in the
@@ -562 +559 @@
 The INVALID define can go into *Iq*, or *c_code*, or an external C file
 listed in *source*.
-
-Structure Factors
-.................
-
-Structure factor calculations may need the underlying $<F(q)>$ and $<F^2(q)>$
-rather than $I(q)$.  This is used to compute $\beta = <F(q)>^2/<F^2(q)>$ in
-the decoupling approximation to the structure factor.
-
-Instead of defining the *Iq* function, models can define *Fq* as
-something like::
-
-    double Fq(double q, double *F1, double *F2, double par1, double par2, ...);
-    double Fq(double q, double *F1, double *F2, double par1, double par2, ...)
-    {
-        // Polar integration loop over all orientations.
-        ...
-        *F1 = 1e-2 * total_F1 * contrast * volume;
-        *F2 = 1e-4 * total_F2 * square(contrast * volume);
-        return I(q, par1, par2, ...);
-    }
-
-If the volume fraction scale factor is built into the model (as occurs for
-the vesicle model, for example), then scale *F1* by $\surd V_f$ so that
-$\beta$ is computed correctly.
-
-Structure factor calculations are not yet supported for oriented shapes.
-
-Note: only available as a separate C file listed in *source*, or within
-a *c_code* block within the python model definition file.
 
 Oriented Shapes
@@ -744 +712 @@
     erf, erfc, tgamma, lgamma:  **do not use**
         Special functions that should be part of the standard, but are missing
-        or inaccurate on some platforms. Use sas_erf, sas_erfc and sas_gamma
-        instead (see below). Note: lgamma(x) has not yet been tested.
+        or inaccurate on some platforms. Use sas_erf, sas_erfc, sas_gamma
+        and sas_lgamma instead (see below).
 
 Some non-standard constants and functions are also provided:
@@ -812 +780 @@
         Gamma function sas_gamma\ $(x) = \Gamma(x)$.
 
-        The standard math function, tgamma(x) is unstable for $x < 1$
+        The standard math function, tgamma(x), is unstable for $x < 1$
         on some platforms.
 
         :code:`source = ["lib/sas_gamma.c", ...]`
         (`sas_gamma.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gamma.c>`_)
+
+    sas_gammaln(x):
+        log gamma function sas_gammaln\ $(x) = \log \Gamma(|x|)$.
+
+        The standard math function, lgamma(x), is incorrect for single
+        precision on some platforms.
+
+        :code:`source = ["lib/sas_gammainc.c", ...]`
+        (`sas_gammainc.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gammainc.c>`_)
+
+    sas_gammainc(a, x), sas_gammaincc(a, x):
+        Incomplete gamma function
+        sas_gammainc\ $(a, x) = \int_0^x t^{a-1}e^{-t}\,dt / \Gamma(a)$
+        and complementary incomplete gamma function
+        sas_gammaincc\ $(a, x) = \int_x^\infty t^{a-1}e^{-t}\,dt / \Gamma(a)$
+
+        :code:`source = ["lib/sas_gammainc.c", ...]`
+        (`sas_gammainc.c <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gammainc.c>`_)
 
     sas_erf(x), sas_erfc(x):
@@ -854 +840 @@
         If $n$ = 0 or 1, it uses sas_J0($x$) or sas_J1($x$), respectively.
 
+        Warning: JN(n,x) can be very inaccurate (0.1%) for x not in [0.1, 100].
+
         The standard math function jn(n, x) is not available on all platforms.
 
@@ -862 +850 @@
         Sine integral Si\ $(x) = \int_0^x \tfrac{\sin t}{t}\,dt$.
 
+        Warning: Si(x) can be very inaccurate (0.1%) for x in [0.1, 100].
+
         This function uses Taylor series for small and large arguments:
 
-        For large arguments,
+        For large arguments use the following Taylor series,
 
         .. math::
@@ -1033 +1023 @@
           "radius": 120., "radius_pd": 0.2, "radius_pd_n":45},
          0.2, 0.228843],
-        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45},
-         0.1, None, None, 120., None, 1.],  # q, F, F^2, R_eff, V, form:shell
-        [{"@S": "hardsphere"}, 0.1, None],
+        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45}, "ER", 120.],
+        [{"radius": 120., "radius_pd": 0.2, "radius_pd_n":45}, "VR", 1.],
     ]
 
 
-**tests=[[{parameters}, q, Iq], ...]** is a list of lists.
+**tests=[[{parameters}, q, result], ...]** is a list of lists.
 Each list is one test and contains, in order:
 
@@ -1051 +1040 @@
 - input and output values can themselves be lists if you have several
   $q$ values to test for the same model parameters.
-- for testing effective radius, volume and form:shell volume ratio, use the
-  extended form of the tests results, with *None, None, R_eff, V, V_r*
-  instead of *Iq*.  This calls the kernel *Fq* function instead of *Iq*.
-- for testing F and F^2 (used for beta approximation) do the same as the
-  effective radius test, but include values for the first two elements,
-  $<F(q)>$ and $<F^2(q)>$.
-- for testing interaction between form factor and structure factor, specify
-  the structure factor name in the parameters as *{"@S": "name", ...}* with
-  the remaining list of parameters defined by the *P@S* product model.
+- for testing *ER* and *VR*, give the inputs as "ER" and "VR" respectively;
+  the output for *VR* should be the sphere/shell ratio, not the individual
+  sphere and shell values.
 
 .. _Test_Your_New_Model: