Changeset cddfef6 in sasmodels for doc

Timestamp:

Mar 30, 2019 8:35:15 AM (6 years ago)

Author:

smk78

Branches:

master, ticket_1156, ticket_822_more_unit_tests

Children:

affc548

Parents:

bc69321 (diff), 9d3a0e5 (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'master' of ​https://github.com/SasView/sasmodels

Location:

doc/guide

Files:

• plugin.rst (modified) (13 diffs)
• resolution.rst (modified) (3 diffs)
• fitting_sq.rst (added)
• index.rst (modified) (1 diff)
• p_and_s_buttons.png (added)

doc/guide/plugin.rst

@@ -303 +303 @@
 **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().
+Iqac(), Iqabc(), radius_effective(), 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.**
@@ -387 +387 @@
 can take arbitrary values, even for integer parameters, so your model should
 round the incoming parameter value to the nearest integer inside your model
-you should round to the nearest integer.  In C code, you can do this using::
+you should round to the nearest integer.  In C code, you can do this using:
+
+.. code-block:: c
 
     static double
@@ -499 +501 @@
 Models should define *form_volume(par1, par2, ...)* where the parameter
 list includes the *volume* parameters in order.  This is used for a weighted
-volume normalization so that scattering is on an absolute scale.  If
-*form_volume* is not defined, then the default *form_volume = 1.0* will be
-used.
+volume normalization so that scattering is on an absolute scale.  For
+solid shapes, the *I(q)* function should use *form_volume* squared
+as its scale factor.  If *form_volume* is not defined, then the default
+*form_volume = 1.0* will be 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.
+are the same as for *form_volume*.  Here the *I(q)* function should use
+*shell_volume* squared instead of *form_volume* squared so that the scale
+parameter corresponds to the volume fraction of material in the sample.
+The structure factor calculation needs the volume fraction of the filled
+shapes for its calculation, so the volume fraction parameter in the model
+is automatically scaled by *form_volume/shell_volume* prior to calling the
+structure factor.
 
 **Note: Pure python models do not yet support direct computation of the**
@@ -525 +530 @@
     """
 
-This expands into the equivalent C code::
+This expands into the equivalent C code:
+
+.. code-block:: c
 
     double Iq(double q, double par1, double par2, ...);
@@ -536 +543 @@
 includes only the volume parameters.
 
-*form_volume* defines the volume of the shell for hollow shapes. As in
+*shell_volume* defines the volume of the shell for hollow shapes. As in
 python models, it includes only the volume parameters.
 
@@ -568 +575 @@
 Rather than returning NAN from Iq, you must define the *INVALID(v)*.  The
 *v* parameter lets you access all the parameters in the model using
-*v.par1*, *v.par2*, etc. For example::
+*v.par1*, *v.par2*, etc. For example:
+
+.. code-block:: c
 
     #define INVALID(v) (v.bell_radius < v.radius)
@@ -583 +592 @@
 
 Instead of defining the *Iq* function, models can define *Fq* as
-something like::
+something like:
+
+.. code-block:: c
 
     double Fq(double q, double *F1, double *F2, double par1, double par2, ...);
@@ -615 +626 @@
 laboratory frame and beam travelling along $-z$.
 
-The oriented C model (oriented pure Python models are not supported) 
+The oriented C model (oriented pure Python models are not supported)
 is called using *Iqabc(qa, qb, qc, par1, par2, ...)* where
 *par1*, etc. are the parameters to the model.  If the shape is rotationally
@@ -644 +655 @@
 
 Using the $z, w$ values for Gauss-Legendre integration in "lib/gauss76.c", the
-numerical integration is then::
+numerical integration is then:
+
+.. code-block:: c
 
     double outer_sum = 0.0;
@@ -987 +1000 @@
   memory, and wrong answers computed. The conclusion from a very long and
   strange debugging session was that any arrays that you declare in your
-  model should be a multiple of four. For example::
+  model should be a multiple of four. For example:
+
+  .. code-block:: c
 
       double Iq(q, p1, p2, ...)
@@ -1019 +1034 @@
 structure factor is the *hardsphere* interaction, which
 uses the effective radius of the form factor as an input to the structure
-factor model.  The effective radius is the average radius of the
-form averaged over all the polydispersity values.
-
-::
-
-    def ER(radius, thickness):
-        """Effective radius of a core-shell sphere."""
-        return radius + thickness
-
-Now consider the *core_shell_sphere*, which has a simple effective radius
-equal to the radius of the core plus the thickness of the shell, as
-shown above. Given polydispersity over *(r1, r2, ..., rm)* in radius and
-*(t1, t2, ..., tn)* in thickness, *ER* is called with a mesh
-grid covering all possible combinations of radius and thickness.
-That is, *radius* is *(r1, r2, ..., rm, r1, r2, ..., rm, ...)*
-and *thickness* is *(t1, t1, ... t1, t2, t2, ..., t2, ...)*.
-The *ER* function returns one effective radius for each combination.
-The effective radius calculator weights each of these according to
-the polydispersity distributions and calls the structure factor
-with the average *ER*.
-
-::
-
-    def VR(radius, thickness):
-        """Sphere and shell volumes for a core-shell sphere."""
-        whole = 4.0/3.0 * pi * (radius + thickness)**3
-        core = 4.0/3.0 * pi * radius**3
-        return whole, whole - core
-
-Core-shell type models have an additional volume ratio which scales
-the structure factor.  The *VR* function returns the volume of
-the whole sphere and the volume of the shell. Like *ER*, there is
-one return value for each point in the mesh grid.
-
-*NOTE: we may be removing or modifying this feature soon. As of the
-time of writing, core-shell sphere returns (1., 1.) for VR, giving a volume
-ratio of 1.0.*
+factor model.  The effective radius is the weighted average over all
+values of the shape in polydisperse systems.
+
+There can be many notions of effective radius, depending on the shape.  For
+a sphere it is clearly just the radius, but for an ellipsoid of revolution
+we provide average curvature, equivalent sphere radius, minimum radius and
+maximum radius.  These options are listed as *radius_effective_modes* in
+the python model defintion, and must be computed by the *radius_effective*
+function which takes the *radius_effective_mode* parameter as an integer,
+along with the various model parameters.  Unlike normal C/Python arrays,
+the first mode is 1, the second is 2, etc.  Mode 0 indicates that the
+effective radius from the shape is to be ignored in favour of the the
+effective radius parameter in the structure factor model.
+
+
+Consider the core-shell sphere, which defines the following effective radius
+modes in the python model::
+
+    radius_effective_modes = [
+        "outer radius",
+        "core radius",
+    ]
+
+and the following function in the C-file for the model:
+
+.. code-block:: c
+
+    static double
+    radius_effective(int mode, double radius, double thickness)
+    {
+        switch (mode) {
+            case 0: return radius + thickness;
+            case 1: return radius;
+            default: return 0.;
+        }
+    }
+
+    static double
+    form_volume(double radius, double thickness)
+    {
+        return M_4PI_3 * cube(radius + thickness);
+    }
+
+Given polydispersity over *(r1, r2, ..., rm)* in radius and *(t1, t2, ..., tn)*
+in thickness, *radius_effective* is called over a mesh grid covering all
+possible combinations of radius and thickness, with a single *(ri, tj)* pair
+in each call. The weights each of these results according to the
+polydispersity distributions and calls the structure factor with the average
+effective radius.  Similarly, for *form_volume*.
+
+Hollow models have an additional volume ratio which is needed to scale the
+structure factor.  The structure factor uses the volume fraction of the filled
+particles as part of its density estimate, but the scale factor for the
+scattering intensity (as non-solvent volume fraction / volume) is determined
+by the shell volume only.  Therefore the *shell_volume* function is
+needed to compute the form:shell volume ratio, which then scales the
+*volfraction* parameter prior to calling the structure factor calculator.
+In the case of a hollow sphere, this would be:
+
+.. code-block:: c
+
+    static double
+    shell_volume(double radius, double thickness)
+    {
+        double whole = M_4PI_3 * cube(radius + thickness);
+        double core = M_4PI_3 * cube(radius);
+        return whole - core;
+    }
+
+If *shell_volume* is not present, then *form_volume* and *shell_volume* are
+assumed to be equal, and the shape is considered solid.
 
 Unit Tests
@@ -1115 +1164 @@
 ...................
 
-**NB: For now, this more detailed testing is only possible if you have a 
+**NB: For now, this more detailed testing is only possible if you have a
 SasView build environment available!**
 
@@ -1253 +1302 @@
 | 2016-10-25 Steve King
 | 2017-05-07 Paul Kienzle - Moved from sasview to sasmodels docs
+| 2019-03-28 Paul Kienzle - Update docs for radius_effective and shell_volume

doc/guide/resolution.rst

@@ -1 +1 @@
 .. resolution.rst
 
-.. This is a port of the original SasView html help file sm_help to ReSTructured 
+.. This is a port of the original SasView html help file sm_help to ReSTructured
 .. text by S King, ISIS, during SasView CodeCamp-III in Feb 2015.
 
@@ -17 +17 @@
 resolution contribution into a model calculation/simulation (which by definition
 will be exact) to make it more representative of what has been measured
-experimentally - a process called *smearing*. The Sasmodels component of SasView 
+experimentally - a process called *smearing*. The Sasmodels component of SasView
 does the latter.
 
@@ -32 +32 @@
 
 .. note::
-    Problems may be encountered if the data set loaded by SasView is a 
-    concatenation of SANS data from several detector distances where, of 
-    course, the worst Q resolution is next to the beam stop at each detector 
-    distance. (This will also be noticeable in the residuals plot where 
-    there will be poor overlap). SasView sensibly orders all the input 
-    data points by increasing Q for nicer-looking plots, however, the dQ 
-    data can then vary considerably from point to point. If 'Use dQ data' 
-    smearing is selected then spikes may appear in the model fits, whereas 
+    Problems may be encountered if the data set loaded by SasView is a
+    concatenation of SANS data from several detector distances where, of
+    course, the worst Q resolution is next to the beam stop at each detector
+    distance. (This will also be noticeable in the residuals plot where
+    there will be poor overlap). SasView sensibly orders all the input
+    data points by increasing Q for nicer-looking plots, however, the dQ
+    data can then vary considerably from point to point. If 'Use dQ data'
+    smearing is selected then spikes may appear in the model fits, whereas
     if 'None' or 'Custom Pinhole Smear' are selected the fits look normal.
-    
-    In such instances, possible solutions are to simply remove the data 
-    with poor Q resolution from the shorter detector distances, or to fit 
+
+    In such instances, possible solutions are to simply remove the data
+    with poor Q resolution from the shorter detector distances, or to fit
     the data from different detector distances simultaneously.
 

doc/guide/index.rst

@@ -12 +12 @@
    pd/polydispersity.rst
    resolution.rst
+   plugin.rst
+   fitting_sq.rst
    magnetism/magnetism.rst
    orientation/orientation.rst
    sesans/sans_to_sesans.rst
    sesans/sesans_fitting.rst
-   plugin.rst
    scripting.rst
    refs.rst