Changeset bd7630d in sasmodels for doc/guide

Timestamp:

Aug 20, 2018 4:15:02 PM (6 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests

Children:

c11d09f

Parents:

0168844

Message:

update scripting docs. Refs #1141

File:

• doc/guide/scripting.rst (modified) (2 diffs)

doc/guide/scripting.rst

@@ -10 +10 @@
 The key functions are :func:`sasmodels.core.load_model` for loading the
 model definition and compiling the kernel and
-:func:`sasmodels.data.load_data` for calling sasview to load the data. Need
-the data because that defines the resolution function and the q values to
-evaluate. If there is no data, then use :func:`sasmodels.data.empty_data1D`
-or :func:`sasmodels.data.empty_data2D` to create some data with a given $q$.
-
-Using sasmodels through bumps
-=============================
-
-With the data and the model, you can wrap it in a *bumps* model with
+:func:`sasmodels.data.load_data` for calling sasview to load the data.
+
+Preparing data
+==============
+
+Usually you will load data via the sasview loader, with the
+:func:`sasmodels.data.load_data` function.  For example::
+
+    from sasmodels.data import load_data
+    data = load_data("sasmodels/example/093191_201.dat")
+
+You may want to apply a data mask, such a beam stop, and trim high $q$::
+
+    from sasmodels.data import set_beam_stop
+    set_beam_stop(data, qmin, qmax)
+
+The :func:`sasmodels.data.set_beam_stop` method simply sets the *mask*
+attribute for the data.
+
+The data defines the resolution function and the q values to evaluate, so
+even if you simulating experiments prior to making measurements, you still
+need a data object for reference. Use :func:`sasmodels.data.empty_data1D`
+or :func:`sasmodels.data.empty_data2D` to create a container with a
+given $q$ and $\Delta q/q$.  For example::
+
+    import numpy as np
+    from sasmodels.data import empty_data1D
+
+    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5%
+    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120)
+    data = empty_data1D(q, resolution=0.05)
+
+To use a more realistic model of resolution, or to load data from a file
+format not understood by SasView, you can use :class:`sasmodels.data.Data1D`
+or :class:`sasmodels.data.Data2D` directly.  The 1D data uses
+*x*, *y*, *dx* and *dy* for $x = q$ and $y = I(q)$, and 2D data uses
+*x*, *y*, *z*, *dx*, *dy*, *dz* for $x, y = qx, qy$ and $z = I(qx, qy)$.
+[Note: internally, the Data2D object uses SasView conventions,
+*qx_data*, *qy_data*, *data*, *dqx_data*, *dqy_data*, and *err_data*.]
+
+For USANS data, use 1D data, but set *dxl* and *dxw* attributes to
+indicate slit resolution::
+
+    data.dxl = 0.117
+
+See :func:`sasmodels.resolution.slit_resolution` for details.
+
+SESANS data is more complicated; if your SESANS format is not supported by
+SasView you need to define a number of attributes beyond *x*, *y*.  For
+example::
+
+    SElength = np.linspace(0, 2400, 61) # [A]
+    data = np.ones_like(SElength)
+    err_data = np.ones_like(SElength)*0.03
+
+    class Source:
+        wavelength = 6 # [A]
+        wavelength_unit = "A"
+    class Sample:
+        zacceptance = 0.1 # [A^-1]
+        thickness = 0.2 # [cm]
+
+    class SESANSData1D:
+        #q_zmax = 0.23 # [A^-1]
+        lam = 0.2 # [nm]
+        x = SElength
+        y = data
+        dy = err_data
+        sample = Sample()
+    data = SESANSData1D()
+
+    x, y = ... # create or load sesans
+    data = smd.Data
+
+The *data* module defines various data plotters as well.
+
+Using sasmodels directly
+========================
+
+Once you have a computational kernel and a data object, you can evaluate
+the model for various parameters using
+:class:`sasmodels.direct_model.DirectModel`.  The resulting object *f*
+will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$
+values in the data.  For example::
+
+    import numpy as np
+    from sasmodels.data import empty_data1D
+    from sasmodels.core import load_model
+    from sasmodels.direct_model import DirectModel
+
+    # 120 points logarithmically spaced from 0.005 to 0.2, with dq/q = 5%
+    q = np.logspace(np.log10(5e-3), np.log10(2e-1), 120)
+    data = empty_data1D(q, resolution=0.05)
+    kernel = load_model("ellipsoid)
+    f = DirectModel(data, kernel)
+    Iq = f(radius_polar=100)
+
+Polydispersity information is set with special parameter names:
+
+    * *par_pd* for polydispersity width, $\Delta p/p$,
+    * *par_pd_n* for the number of points in the distribution,
+    * *par_pd_type* for the distribution type (as a string), and
+    * *par_pd_nsigmas* for the limits of the distribution.
+
+Using sasmodels through the bumps optimizer
+===========================================
+
+Like DirectModel, you can wrap data and a kernel in a *bumps* model with
 class:`sasmodels.bumps_model.Model` and create an
-class:`sasmodels.bump_model.Experiment` that you can fit with the *bumps*
+class:`sasmodels.bumps_model.Experiment` that you can fit with the *bumps*
 interface. Here is an example from the *example* directory such as
 *example/model.py*::
@@ -75 +174 @@
     SasViewCom bumps.cli example/model.py --preview
 
-Using sasmodels directly
-========================
-
-Bumps has a notion of parameter boxes in which you can set and retrieve
-values.  Instead of using bumps, you can create a directly callable function
-with :class:`sasmodels.direct_model.DirectModel`.  The resulting object *f*
-will be callable as *f(par=value, ...)*, returning the $I(q)$ for the $q$
-values in the data.  Polydisperse parameters use the same naming conventions
-as in the bumps model, with e.g., radius_pd being the polydispersity associated
-with radius.
+Calling the computation kernel
+==============================
 
 Getting a simple function that you can call on a set of q values and return