Index: doc/developer/calculator.rst
===================================================================
--- doc/developer/calculator.rst	(revision e822c97dbba0cc80549b06c762412cd27ba38358)
+++ doc/developer/calculator.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -7,7 +7,7 @@
 model calculator which implements the polydispersity and magnetic SLD
 calculations.  There are three separate implementations of this layer,
-*kernelcl.py* for OpenCL, which operates on a single Q value at a time,
-*kerneldll.c* for the DLL, which loops over a vector of Q values, and
-*kernelpy.py* for python models which operates on vector Q values.
+:mod:`kernelcl` for OpenCL, which operates on a single Q value at a time,
+:mod:`kerneldll` for the DLL, which loops over a vector of Q values, and
+:mod:`kernelpy` for python models which operates on vector Q values.
 
 Each implementation provides three different calls *Iq*, *Iqxy* and *Imagnetic*
Index: doc/developer/index.rst
===================================================================
--- doc/developer/index.rst	(revision b85be2da3b04a7ce8ef87e2a85a44572b2b1480c)
+++ doc/developer/index.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -7,3 +7,4 @@
    :maxdepth: 4
 
+   overview.rst
    calculator.rst
Index: doc/developer/overview.rst
===================================================================
--- doc/developer/overview.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
+++ doc/developer/overview.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -0,0 +1,81 @@
+.. py:currentmodule:: sasmodels
+
+***************************
+Code Overview
+***************************
+
+Computational kernels
+---------------------
+
+At the heart of *sasmodels* are the individual computational kernels.  These
+functions take a particular $q$ value and a set of parameter values and
+return the expected scattering for that $q$. The instructions for writing
+a kernel are documented in :ref:`Writing_a_Plugin`.  The source code for
+the kernels is stored in :mod:`sasmodels.models`.
+
+The primary interface to the models is through :mod:`sasmodels.core`, which
+provides functions for listing available models, loading the model definition
+and compiling the model.  Use :func:`sasmodels.core.load_model` to load in
+a model definition and compile it.
+
+The computational kernels are difficult to call directly, but an example
+was provided in :ref:`Scripting_Interface`.
+
+The code for loading the kernel is in
+:mod:`sasmodels.generate`, but a big part of it, which is interpreting the
+definition, lives in :mod:`sasmodels.modelinfo`.  This defines the properties
+of the model in :class:`sasmodels.modelinfo.ModelInfo`, the available
+model parameters in :class:`sasmodels.modelinfo.ParameterTable` and the
+individual parameter attributes such as units and hard limits in
+:class:`sasmodels.modelinfo.Parameter`.
+
+The kernel functions for the most part do not define polydispersity,
+resolution functions or magnetism.  Instead, code for these is generated in
+:mod:`sasmodels.generate`
+
+
+
+Sasview kernels:
+
+* :mod:`
+    ('kernel', 'Evaluator type definitions'),
+    ('kernelcl', 'OpenCL model evaluator'),
+    ('kerneldll', 'Ctypes model evaluator'),
+    ('kernelpy', 'Python model evaluator'),
+
+Bumps fitting routines:
+
+* :mod:`sasmodels.bumps_model` is a wrapper around
+    ('bumps_model', 'Bumps interface'),
+    ('direct_model', 'Simple interface'),
+
+
+Utility functions:
+
+* :mod:`sasmodels` provides :func:`sasmodels.__init__.data_files` for the installer.
+* :mod:`sasmodels.rst2html` provides tools for converting model docs to html and viewing
+  the html.  When run as a main program, it can display arbitrary rst files.
+* :mod:`sasmodels.exception` annotates the current exception with a context string,
+  such as "while opening myfile.dat" without adjusting the traceback.
+
+
+And so on::
+
+
+    ('compare_many', 'Batch compare models on different compute engines'),
+    ('compare', 'Compare models on different compute engines'),
+    ('convert', 'Sasview to sasmodel converter'),
+    ('core', 'Model access'),
+    ('data', 'Data layout and plotting routines'),
+    ('details', 'Parameter packing for kernel calls'),
+    ('generate', 'Model parser'),
+    ('list_pars', 'Identify all parameters in all models'),
+    ('mixture', 'Mixture model evaluator'),
+    ('model_test', 'Unit test support'),
+    ('modelinfo', 'Parameter and model definitions'),
+    ('product', 'Product model evaluator'),
+    ('resolution', '1-D resolution functions'),
+    ('resolution2d', '2-D resolution functions'),
+    ('sasview_model', 'Sasview interface'),
+    ('sesans', 'SESANS calculation routines'),
+    ('weights', 'Distribution functions'),
Index: doc/genapi.py
===================================================================
--- doc/genapi.py	(revision 8ae853293022b5081a1e1a8c26f74eaa2b3f8a13)
+++ doc/genapi.py	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -56,5 +56,5 @@
 
 modules = [
-    ('__init__', 'Top level namespace'),
+    ('__init__', 'Sasmodels package'),
     #('alignment', 'GPU data alignment [unused]'),
     ('bumps_model', 'Bumps interface'),
Index: doc/guide/index.rst
===================================================================
--- doc/guide/index.rst	(revision 990d8dfe5ac399564bc0bb3b873c5a1b56d4e573)
+++ doc/guide/index.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -15,3 +15,4 @@
    sesans/sesans_fitting.rst
    plugin.rst
+   scripting.rst
    refs.rst
Index: doc/guide/scripting.rst
===================================================================
--- doc/guide/scripting.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
+++ doc/guide/scripting.rst	(revision 2e66ef55022b7fe939fdb5874c2c919d97e01b2c)
@@ -0,0 +1,106 @@
+.. _Scripting_Interface:
+
+*******************
+Scripting Interface
+*******************
+
+Need some basic details here of how to load models and data via script, evaluate
+them at given parameter values and run bumps fits.
+
+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
+class:`sasmodels.bumps_model.Model` and create an
+class:`sasmodels.bump_model.Experiment` that you can fit with the *bumps*
+interface. Here is an example from the *example* directory such as
+*example/model.py*::
+
+    import sys
+    from bumps.names import *
+    from sasmodels.core import load_model
+    from sasmodels.bumps_model import Model, Experiment
+    from sasmodels.data import load_data, set_beam_stop, set_top
+
+    """ IMPORT THE DATA USED """
+    radial_data = load_data('DEC07267.DAT')
+    set_beam_stop(radial_data, 0.00669, outer=0.025)
+    set_top(radial_data, -.0185)
+
+    kernel = load_model("ellipsoid")
+
+    model = Model(kernel,
+        scale=0.08,
+        radius_polar=15, radius_equatorial=800,
+        sld=.291, sld_solvent=7.105,
+        background=0,
+        theta=90, phi=0,
+        theta_pd=15, theta_pd_n=40, theta_pd_nsigma=3,
+        radius_polar_pd=0.222296, radius_polar_pd_n=1, radius_polar_pd_nsigma=0,
+        radius_equatorial_pd=.000128, radius_equatorial_pd_n=1, radius_equatorial_pd_nsigma=0,
+        phi_pd=0, phi_pd_n=20, phi_pd_nsigma=3,
+        )
+
+    # SET THE FITTING PARAMETERS
+    model.radius_polar.range(15, 1000)
+    model.radius_equatorial.range(15, 1000)
+    model.theta_pd.range(0, 360)
+    model.background.range(0,1000)
+    model.scale.range(0, 10)
+
+    #cutoff = 0     # no cutoff on polydisperisity loops
+    #cutoff = 1e-5  # default cutoff
+    cutoff = 1e-3  # low precision cutoff
+    M = Experiment(data=radial_data, model=model, cutoff=cutoff)
+    problem = FitProblem(M)
+
+Assume that bumps has been installed and the bumps command is available.
+Maybe need to set the path to sasmodels/sasview
+using *PYTHONPATH=path/to/sasmodels:path/to/sasview/src*.
+To run the model use the *bumps* program::
+
+    $ bumps 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.
+
+Getting a simple function that you can call on a set of q values and return
+a result is not so simple.  Since the time critical use case (fitting) involves
+calling the function over and over with identical $q$ values, we chose to
+optimize the call by only transfering the $q$ values to the GPU once at the
+start of the fit.  We do this by creating a :class:`sasmodels.kernel.Kernel`
+object from the :class:`sasmodels.kernel.KernelModel` returned from
+:func:`sasmodels.core.load_model` using the
+:meth:`sasmodels.kernel.KernelModel.make_kernel` method.  What it actual
+does depends on whether it is running as a DLL, as OpenCL or as a pure
+python kernel.  Once the kernel is in hand, we can then marshal a set of
+parameters into a :class:`sasmodels.details.CallDetails` object and ship it to
+the kernel using the :func:`sansmodels.direct_model.call_kernel` function.  An
+example should help, *example/cylinder_eval.py*::
+
+    from numpy import logspace
+    from matplotlib import pyplot as plt
+    from sasmodels.core import load_model
+    from sasmodels.direct_model import call_kernel
+
+    model = load_model('cylinder')
+    q = logspace(-3, -1, 200)
+    kernel = model.make_kernel([q])
+    Iq = call_kernel(kernel, dict(radius=200.))
+    plt.loglog(q, Iq)
+    plt.show()
