Changeset 9687d58 in sasview for src/sas/sasgui/perspectives/fitting/media

Timestamp:

Apr 10, 2017 4:01:46 AM (8 years ago)

Author:

Piotr Rozyczko <rozyczko@…>

Branches:

ESS_GUI, ESS_GUI_Docs, ESS_GUI_batch_fitting, ESS_GUI_bumps_abstraction, ESS_GUI_iss1116, ESS_GUI_iss879, ESS_GUI_iss959, ESS_GUI_opencl, ESS_GUI_ordering, ESS_GUI_sync_sascalc

Children:

6c8fb2c

Parents:

9208346 (diff), c6f3aec (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' into ESS_GUI

Location:

src/sas/sasgui/perspectives/fitting/media

Files:

• edit_model_menu.bmp (deleted)
• edit_model_menu.png (added)
• fitting.rst (modified) (2 diffs)
• fitting_help.rst (modified) (12 diffs)
• plugin.rst (modified) (31 diffs)
• sm_help.rst (modified) (1 diff)

src/sas/sasgui/perspectives/fitting/media/fitting.rst

@@ -3 +3 @@
 Fitting Documentation
 =====================
+
+.. note:: In Windows use [Alt]-[Cursor left] to return to the previous page
 
 .. toctree::
@@ -18 +20 @@
 
    Information on the SasView Optimisers <optimizer.rst>
-
-   Writing a Plugin <plugin.rst>
+      
+   Converting SANS to SESANS for Fitting <../../../sans_to_sesans>
+   
+   Fitting SESANS Data <../../../sesans_fitting.rst>
+   
+   Writing a Plugin Model <plugin.rst>
+      
+   Computations with a GPU <../../../gpu_computations>
+   

src/sas/sasgui/perspectives/fitting/media/fitting_help.rst

@@ -18 +18 @@
 =======
 
+.. note:: If some code blocks are not readable, expand the documentation window
+
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
@@ -32 +34 @@
 *  in *Single* fit mode - individual data sets are fitted independently one-by-one
 
-*  in *Simultaneous* fit mode - multiple data sets are fitted simultaneously to the *same* model with/without constrained parameters (this might be useful, for example, if you have measured the same sample at different contrasts)
+*  in *Simultaneous* fit mode - multiple data sets are fitted simultaneously to
+   the *same* model with/without constrained parameters (this might be useful,
+   for example, if you have measured the same sample at different contrasts)
 
 *  in *Batch* fit mode - multiple data sets are fitted sequentially to the *same* model (this might be useful, for example, if you have performed a kinetic or time-resolved experiment and have *lots* of data sets!)
@@ -41 +45 @@
 -----------------
 
-By default, the models in SasView are grouped into five categories
-
-*  *Shapes* - models describing 'objects' (spheres, cylinders, etc)
+The models in SasView are grouped into categories. By default these consist of:
+
+*  *Cylinder* - cylindrical shapes (disc, right cylinder, cylinder with endcaps
+   etc)
+*  *Ellipsoid* - ellipsoidal shapes (oblate,prolate, core shell, etc)
+*  *Parellelepiped* - as the name implies
+*  *Sphere* - sheroidal shapes (sphere, core multishell, vesicle, etc)
+*  *Lamellae* - lamellar shapes (lamellar, core shell lamellar, stacked
+   lamellar, etc)
 *  *Shape-Independent* - models describing structure in terms of density correlation functions, fractals, peaks, power laws, etc
-*  *Customized Models* - SasView- or User-created (non-library) Python models
-*  *Uncategorised* - other models (for reflectivity, etc)
+*  *Paracrystal* - semi ordered structures (bcc, fcc, etc)
 *  *Structure Factor* - S(Q) models
+*  *Plugin Models* - User-created (custom/non-library) Python models
 
 Use the *Category* drop-down menu to chose a category of model, then select
@@ -82 +92 @@
 .. image:: cat_fig0.bmp
 
-The categorization of all models except the customized models can be reassigned,
-added to, and removed using *Category Manager*. Models can also be hidden from view
-in the drop-down menus.
+The categorization of all models except the user supplied Plugin Models can be
+reassigned, added to, and removed using *Category Manager*. Models can also be
+hidden from view in the drop-down menus.
 
 .. image:: cat_fig1.bmp
@@ -91 +101 @@
 ^^^^^^^^^^^^^^^^^
 
-To change category, highlight a model in the list by left-clicking on its entry and
-then click the *Modify* button. Use the *Change Category* panel that appears to make
-the required changes.
+To change category, highlight a model in the list by left-clicking on its entry
+and then click the *Modify* button. Use the *Change Category* panel that appears
+to make the required changes.
 
 .. image:: cat_fig2.bmp
@@ -104 +114 @@
 ^^^^^^^^^^^^^^^^^^^^^
 
-Use the *Enable All / Disable All* buttons and the check boxes beside each model to
-select the models to show/hide. To apply the selection, click *Ok*. Otherwise click
-*Cancel*.
+Use the *Enable All / Disable All* buttons and the check boxes beside each model
+to select the models to show/hide. To apply the selection, click *Ok*. Otherwise
+click *Cancel*.
 
 *NB: It may be necessary to change to a different category and then back again*
@@ -116 +126 @@
 ---------------
 
-For a complete list of all the library models available in SasView, see the Model Documentation.
+For a complete list of all the library models available in SasView, see
+the `Model Documentation <../../../index.html>`_ .
 
 It is also possible to add your own models.
@@ -124 +135 @@
 .. _Adding_your_own_models:
 
-Adding your own models
+Adding your own Models
 ----------------------
 
-There are currently two ways to add your own models to SasView:
-
-* Using the :ref:`Custom_Model_Editor`
-* By :ref:`Writing_a_Plugin`
-
-.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
-
-.. _Custom_Model_Editor:
-
-Custom Model Editor
--------------------
-
-From the *Fitting* option in the menu bar, select *Edit Custom Model*.
-
-.. image:: edit_model_menu.bmp
-
-and then one of the options
-
-*  *New* - to create a new custom model template
-*  *Sum|Multi(p1,p2)* - to create a new model by summing/multiplying existing models in the model library
-*  *Advanced* - to edit a new custom model
-*  *Delete* - to delete a custom model
-
-New
-^^^^
+There are essentially three ways to generate new fitting models for SasView:
+
+*  Using the SasView :ref:`New_Plugin_Model` helper dialog (best for beginners
+   and/or relatively simple models)
+*  By copying/editing an existing model (this can include models generated by
+   the New Plugin Model* dialog) in the :ref:`Python_shell` or 
+   :ref:`Advanced_Plugin_Editor` (suitable for all use cases)
+*  By writing a model from scratch outside of SasView (only recommended for code
+   monkeys!)
+
+Please read the guidance on :ref:`Writing_a_Plugin` before proceeding.
+
+**To be found by SasView your model must reside in the *~\\.sasview\\plugin_models* folder.**
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. _Plugin_Model_Operations:
+
+Plugin Model Operations
+-----------------------
+
+From the *Fitting* option in the menu bar, select *Plugin Model Operations*
+
+.. image:: edit_model_menu.png
+
+and then one of the sub-options
+
+*  *New Plugin Model* - to create a plugin model template with a helper dialog
+*  *Sum|Multi(p1,p2)* - to create a plugin model by summing/multiplying *existing models* in the model library
+*  *Advanced Plugin Editor* - to create/edit a plugin model in a Python shell
+*  *Delete Plugin Models* - to delete a plugin model
+*  *Load Plugin Models* - to (re-)load plugin models
+
+.. _New_Plugin_Model:
+
+New Plugin Model
+^^^^^^^^^^^^^^^^
+
+Relatively straightforward models can be programmed directly from the SasView
+GUI using the *New Plugin Model Function*.
 
 .. image:: new_model.bmp
 
-A model template generated by this option can be viewed and further modified using
-the :ref:`Advanced` option.
-
-*NB: "Fit Parameters" has been split into two sections, those which can be
-polydisperse (shape and orientation parameters) and those which are not
-(scattering length densities, for example).*
+When using this feature, be aware that even if your code has errors, including 
+syntax errors, a model file is still generated. When you then correct the errors 
+and click 'Apply' again to re-compile you will get an error informing you that 
+the model already exists if the 'Overwrite' box is not checked. In this case you 
+will need to supply a new model function name. By default the 'Overwrite' box is 
+*checked*\ .
+
+Also note that the 'Fit Parameters' have been split into two sections: those
+which can be polydisperse (shape and orientation parameters) and those which are
+not (eg, scattering length densities).
+
+A model file generated by this option can be viewed and further modified using
+the :ref:`Advanced_Plugin_Editor` .
 
 Sum|Multi(p1,p2)
@@ -167 +200 @@
 .. image:: sum_model.bmp
 
-This option creates a custom model of the form
-
-Custom Model = scale_factor \* (model1 +/\* model2)
-
-In the *Easy Sum/Multi Editor* give the new custom model a function name and brief
-description (to appear under the *Details* button on the *Fit Page*). Then select
+This option creates a custom Plugin Model of the form::
+
+     Plugin Model = scale_factor * {(scale_1 * model_1) +/- (scale_2 * model_2)} + background
+
+or::
+
+     Plugin Model = scale_factor * model_1 /* model_2 + background
+
+In the *Easy Sum/Multi Editor* give the new model a function name and brief
+description (to appear under the *Details* button on the *FitPage*). Then select
 two existing models, as p1 and p2, and the required operator, '+' or '*' between
 them. Finally, click the *Apply* button to generate the model and then click *Close*.
 
-*NB: Any changes to a custom model generated in this way only become effective after*
-*it is re-selected from the model drop-down menu on the Fit Page.*
-
-.. _Advanced:
-
-Advanced
-^^^^^^^^
-
-Selecting this option shows all the custom models in the plugin model folder
-
-  *C:\\Users\\[username]\\.sasview\\plugin_models* - (on Windows)
+Any changes to a plugin model generated in this way only become effective *after* it is re-selected from the model drop-down menu on the FitPage.
+
+.. _Advanced_Plugin_Editor:
+
+Advanced Plugin Editor
+^^^^^^^^^^^^^^^^^^^^^^
+
+Selecting this option shows all the plugin models in the plugin model folder, on Windows this is
+
+  *C:\\Users\\{username}\\.sasview\\plugin_models*
 
 You can edit, modify, and save the Python code in any of these models using the
-*Advanced Custom Model Editor*.
-
-See :ref:`Writing_a_Plugin` for details on the plugin format.
-
-*NB: Sum/Product models are still using the SasView 3.x model format.  Unless
-you are confident about what you are doing, it is recommended that you
-only modify lines denoted with the ## <----- comments!*
-
-When editing is complete, select *Run -> Compile* from the *Model Editor* menu bar. An
-*Info* box will appear with the results of the compilation and model unit tests. The
-model will only be usable if the tests 'pass'.
-
-To use the model, go to the relevant *Fit Page*, select the *Customized Models*
+*Advanced Plugin Model Editor*. Note that this is actually the same tool as the :ref:`Python_shell` .
+
+For details of the SasView plugin model format see :ref:`Writing_a_Plugin` .
+
+.. note:: Model files generated with the Sum/Multi option are still using the SasView 3.x model format. Unless you are confident about what you are doing, it is recommended that you only modify lines denoted with the ## <----- comments!
+
+When editing is complete, select *Run* > *Check Model* from the *Advanced Plugin Model Editor* menu bar. An *Info* box will appear with the results of the compilation and model unit tests. The model will only be usable if the tests 'pass'.
+
+.. image:: ../calculator/new_pycrust_example_2.png
+
+To use the model, go to the relevant *Fit Page*, select the *Plugin Models*
 category and then select the model from the drop-down menu.
 
-*NB: Any changes to a custom model generated in this way only become effective after*
-*it is re-selected from the model drop-down menu on the Fit Page.*
-
-Delete
-^^^^^^
-
-Simply highlight the custom model to be removed. This operation is final!
-
-*NB: Custom models shipped with SasView cannot be removed in this way.*
-
-.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
-
-  .. _Writing_a_Plugin:
-
-  Writing a Plugin
-  ----------------
-
-  Advanced users can write their own model in Python and save it to the the SasView
-  *plugin_models* folder
-
-    *C:\\Users\\[username]\\.sasview\\plugin_models* - (on Windows)
-
-  in .py format. The next time SasView is started it will compile the plugin and add
-  it to the list of *Customized Models*.
-
-  It is recommended that existing plugin models be used as templates.
+Any changes to a plugin model generated in this way only become effective *after* it is re-selected from the model drop-down menu on the FitPage.
+
+Delete Plugin Models
+^^^^^^^^^^^^^^^^^^^^
+
+Simply highlight the plugin model to be removed. The operation is final!!!
+
+*NB: Models shipped with SasView cannot be removed in this way.*
+
+Load Plugin Models
+^^^^^^^^^^^^^^^^^^
+
+This option loads (or re-loads) all models present in the
+*~\\.sasview\\plugin_models* folder.
 
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
@@ -392 +414 @@
 :ref:`Assessing_Fit_Quality`.
 
-*NB: If you need to use a customized model, you must ensure that model is available*
-*first (see* :ref:`Adding_your_own_models` *).*
+*NB: If you need to use a custom Plugin Model, you must ensure that model is
+available first (see* :ref:`Adding_your_own_models` *).*
 
 Method
@@ -476 +498 @@
 If multiple data sets are in one file, load just that file. *Unselect All Data*, then
 select a single initial data set to be fitted. Fit that selected data set as described
-above under :ref:`Single_Fit_Mode` .
-
-*NB: If you need to use a customized model, you must ensure that model is available*
-*first (see* :ref:`Adding_your_own_models` *).*
+above under :ref:`Single_Fit_Mode`.
+
+*NB: If you need to use a custom Plugin Model, you must ensure that model is
+available first (see* :ref:`Adding_your_own_models` *).*
 
 Method
@@ -617 +639 @@
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
-.. note::  This help document was last changed by Steve King, 04Jun2015
+.. note::  This help document was last changed by Steve King, 10Oct2016

src/sas/sasgui/perspectives/fitting/media/plugin.rst

@@ -1 +1 @@
 .. _Writing_a_Plugin:
 
-Writing a Plugin
-================
-
-Users can write their own models and save it to the the SasView
-*plugin_models* folder
-
-  *C:\\Users\\[username]\\.sasview\\plugin_models* - (on Windows)
-
-The next time SasView is started it will compile the plugin and add
-it to the list of *Customized Models*.  It is recommended that an
-existing model be used as a template.
-
-This page was originally written by our MOST experienced developers,
-but has subsequently been edited by our LEAST experienced developer who felt
-some instructions could have been clearer, and learnt one or two things that
-were missing altogether! But they succeeded in converting a model that passed
-testing, so there is no reason why you should not be able to do the same.
-
-SasView has three ways of writing models:
-
-- As a pure python model : Example -
+Writing a Plugin Model
+======================
+
+.. note:: If some code blocks are not readable, expand the documentation window
+
+Introduction
+^^^^^^^^^^^^
+
+There are essentially three ways to generate new fitting models for SasView:
+
+* Using the SasView :ref:`New_Plugin_Model` helper dialog (best for beginners
+  and/or relatively simple models)
+* By copying/editing an existing model (this can include models generated by
+  the *New Plugin Model* dialog) in the :ref:`Python_shell` or
+  :ref:`Advanced_Plugin_Editor` as described below (suitable for all use cases)
+* By writing a model from scratch outside of SasView (only recommended for
+  code monkeys!)
+
+Overview
+^^^^^^^^
+
+If you write your own model and save it to the the SasView *plugin_models* folder
+
+  *C:\\Users\\{username}\\.sasview\\plugin_models* (on Windows)
+
+the next time SasView is started it will compile the plugin and add
+it to the list of *Plugin Models* in a FitPage.
+
+SasView models can be of three types:
+
+- A pure python model : Example -
   `broadpeak.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/broad_peak.py>`_
-- As a python model with embedded C : Example -
+- A python model with embedded C : Example -
   `sphere.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/sphere.py>`_
-- As a python wrapper with separate C code : Example -
+- A python wrapper with separate C code : Example -
   `cylinder.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.py>`_,
   `cylinder.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.c>`_
 
-Many models are available for download from the
-`model marketplace <http://marketplace.sasview.org/>`_.
-
-The builtin modules are available in the *sasmodels-data/models* subdirectory
-of the sasview distribution.  On Windows, this will be something like
-*C:\Program Files (x86)\SasView\models*.  On MacOSX, these will be within
+The built-in modules are available in the *sasmodels-data\\models* subdirectory
+of your SasView installation folder.  On Windows, this will be something like
+*C:\\Program Files (x86)\\SasView\\sasmodels-data\\models*.  On Mac OSX, these will be within
 the application bundle as
 */Applications/SasView 4.0.app/Contents/Resources/sasmodels-data/models*.
 
+Other models are available for download from our
+`Model Marketplace <http://marketplace.sasview.org/>`_. You can contribute your own models to the 
+Marketplace aswell.
+
 Create New Model Files
 ^^^^^^^^^^^^^^^^^^^^^^
 
-In the *~/.sasview/plugin_models* directory, copy the appropriate files
-(using the examples above as templates) to mymodel.py (and mymodel.c, etc)
+In the *~\\.sasview\\plugin_models* directory, copy the appropriate files
+(we recommend using the examples above as templates) to mymodel.py (and mymodel.c, etc)
 as required, where "mymodel" is the name for the model you are creating.
 
 *Please follow these naming rules:*
 
-- No capitalization and thus no CamelCase.
-- If necessary use underscore to separate (i.e. barbell not BarBell or
+- No capitalization and thus no CamelCase
+- If necessary use underscore to separate words (i.e. barbell not BarBell or
   broad_peak not BroadPeak)
-- Don't include “model” in the name (i.e. barbell not BarBellModel)
+- Do not include "model" in the name (i.e. barbell not BarBellModel)
 
 
 Edit New Model Files
 ^^^^^^^^^^^^^^^^^^^^
+
+Model Contents
+..............
 
 The model interface definition is in the .py file.  This file contains:
@@ -65 +79 @@
     - without spaces (use underscores to separate words instead)
     - without any capitalization or CamelCase
-    - without incorporating the word 'model'
+    - without incorporating the word "model"
     - examples: *barbell* **not** *BarBell*; *broad_peak* **not** *BroadPeak*; 
       *barbell* **not** *BarBellModel*
@@ -72 +86 @@
    - this is the **title** string in the *.py* file
    - this is a one or two line description of the model, which will appear
-     at the start of the model documentation and as a tooltip in the GUI
+     at the start of the model documentation and as a tooltip in the SasView GUI
 
 - a **short discription**:
    - this is the **description** string in the *.py* file
    - this is a medium length description which appears when you click
-     *Description* on the model fit page
+     *Description* on the model FitPage
 
 - a **parameter table**:
@@ -85 +99 @@
    - this is ReStructuredText enclosed between the r""" and """ delimiters
      at the top of the *.py* file
+   - what you write here is abstracted into the SasView help documentation
+   - this is what other users will refer to when they want to know what your model does; 
+     so please be helpful!
 
 - a **definition** of the model:
@@ -97 +114 @@
 
 - a **plot** of the function, with a **figure caption**:
-   - this is automatically generated from the default parameters
+   - this is automatically generated from your default parameters
 
 - at least one **reference**:
@@ -107 +124 @@
    - the *.py* file should also contain a comment identifying *who*
      converted/created the model file
+
+Models that do not conform to these requirements will *never* be incorporated 
+into the built-in library.
 
 More complete documentation for the sasmodels package can be found at
@@ -170 +190 @@
 
 The model should include a **formula** written using LaTeX markup.
-The above example uses the *math* command to make a displayed equation.  You
+The example above uses the *math* command to make a displayed equation.  You
 can also use *\$formula\$* for an inline formula. This is handy for defining
 the relationship between the model parameters and formula variables, such
 as the phrase "\$r\$ is the radius" used above.  The live demo MathJax
 page `<http://www.mathjax.org/>`_ is handy for checking that the equations
-will look like you expect.
+will look like you intend.
 
 Math layout uses the `amsmath <http://www.ams.org/publications/authors/tex/amslatex>`_
@@ -207 +227 @@
 
     name = "sphere"  # optional: defaults to the filename without .py
+
     title = "Spheres with uniform scattering length density"
+
     description = """\
     P(q)=(scale/V)*[3V(sld-sld_solvent)*(sin(qr)-qr cos(qr))
@@ -216 +238 @@
         sld_solvent: the SLD of the solvent
     """
+
     category = "shape:sphere"
+
     single = True   # optional: defaults to True
+
     opencl = False  # optional: defaults to False
+
     structure_factor = False  # optional: defaults to False
 
@@ -229 +255 @@
 **title = "short description"** is short description of the model which
 is included after the model name in the automatically generated documentation.
-The title can also be used for a tooltip, for example.
+The title can also be used for a tooltip.
 
 **description = """doc string"""** is a longer description of the model. It
-shows up when you press the "Description" button of the SasView fit page.
+shows up when you press the "Description" button of the SasView FitPage.
 It should give a brief description of the equation and the parameters
 without the need to read the entire model documentation. The triple quotes
 allow you to write the description over multiple lines. Keep the lines
 short since the GUI will wrap each one separately if they are too long.
-**Make sure the parameter names in the description match the model definition.**
+**Make sure the parameter names in the description match the model definition!**
 
 **category = "shape:sphere"** defines where the model will appear in the
 model documentation.  In this example, the model will appear alphabetically
-in the list of spheroid models.
+in the list of spheroid models in the *Shape* category.
 
 **single = True** indicates that the model can be run using single
@@ -275 +301 @@
         ["radius",      "Ang",        50, [0, inf],    "volume", "Sphere radius"],
     ]
-    # pylint: disable=bad-whitespace, line-too-long
+    # pylint: enable=bad-whitespace, line-too-long
 
 **parameters = [["name", "units", default, [min,max], "type", "tooltip"],...]**
-defines the parameters form the model.
-
-- **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 Iq(), Iqxy() and form_volume().**
-
-- **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 fit screen
+defines the parameters that form the model.
+
+**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 Iq(), 
+Iqxy() 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.
 
   - parameter names should follow the mathematical convention; e.g.,
-    *radius_core* not *core_radius*, or *sld_solvent* not *solvent_sld*
+    *radius_core* not *core_radius*, or *sld_solvent* not *solvent_sld*.
+
   - model parameter names should be consistent between different models,
     so *sld_solvent*, for example, should have exactly the same name
-    in every model
+    in every model.
+
   - to see all the parameter names currently in use, type the following in the
     python shell/editor under the Tools menu::
@@ -301 +327 @@
 
     *re-use* as many as possible!!!
+
   - use "name[n]" for multiplicity parameters, where *n* is the name of
     the parameter defining the number of shells/layers/segments, etc.
@@ -306 +333 @@
 - **"units"** are displayed along with the parameter name
 
-  - every parameter should have units; use "None" if there are no units
+  - every parameter should have units; use "None" if there are no units.
+
   - **sld's should be given in units of 1e-6/Ang^2, and not simply
     1/Ang^2 to be consistent with the builtin models.  Adjust your formulas
     appropriately.**
+
   - fancy units markup is available for some units, including::
 
@@ -322 +351 @@
       and using negative exponents instead of the / operator, though
       the unit name should use the / operator for consistency.
-    - post a message to the sasview developers list with the changes
-
-- **default** is the initial value for the parameter
+    - please post a message to the SasView developers mailing list with your changes.
+
+- **default** is the initial value for the parameter.
 
   - **the parameter default values are used to auto-generate a plot of
     the model function in the documentation.**
 
-- **[min, max]** are the lower and upper limits on the parameter
-
-  - lower and upper limits can be any number, or -inf or inf.
+- **[min, max]** are the lower and upper limits on the parameter.
+
+  - lower and upper limits can be any number, or *-inf* or *inf*.
+
   - the limits will show up as the default limits for the fit making it easy,
     for example, to force the radius to always be greater than zero.
 
-- **"type"** can be one of: "", "sld", "volume", or "orientation"
+  - these are hard limits defining the valid range of parameter values;
+    polydisperity distributions will be truncated at the limits.
+
+- **"type"** can be one of: "", "sld", "volume", or "orientation".
 
   - "sld" parameters can have magnetic moments when fitting magnetic models;
     depending on the spin polarization of the beam and the $q$ value being
     examined, the effective sld for that material will be used to compute the
-    scattered intensity
+    scattered intensity.
+
   - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and
     have polydispersity loops generated automatically.
+
   - "orientation" parameters are only passed to Iqxy(), and have angular
     dispersion.
@@ -380 +415 @@
 .............
 
-For pure python models, define the Iq funtion::
+For pure python models, define the *Iq* function::
 
       import numpy as np
@@ -391 +426 @@
 The parameters *par1, par2, ...* are the list of non-orientation parameters
 to the model in the order that they appear in the parameter table.
-**Note that the autogenerated model file uses *x* rather than *q*.**
+**Note that the autogenerated model file uses** *x* **rather than** *q*.
 
 The *.py* file should import trigonometric and exponential functions from
-numpy rather that from math.  This lets us evaluate the model for the whole
+numpy rather than from math.  This lets us evaluate the model for the whole
 range of $q$ values at once rather than looping over each $q$ separately in
 python.  With $q$ as a vector, you cannot use if statements, but must instead
@@ -430 +465 @@
 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 definded, then the default *form_volume = 1.0* will be
+*form_volume* is not defined, then the default *form_volume = 1.0* will be
 used.
 
@@ -436 +471 @@
 .................
 
-Like pure python models, inline C models need define an *Iq* function::
+Like pure python models, inline C models need to define an *Iq* function::
 
     Iq = """
@@ -451 +486 @@
     }
 
-The C model operates on a single $q$ value at a time.  The code will be
-run in parallel across different $q$ values, either on the graphics card
-or the processor.
-
-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::
-
-    #define INVALID(v) (v.bell_radius < v.radius)
-
 *Iqxy* is similar to *Iq*, except it uses parameters *qx, qy* instead of *q*,
-and it includes orientation parameters. As in python models, *form_volume*
-includes only the volume parameters.  *Iqxy* will default to
-*Iq(sqrt(qx**2 + qy**2), par1, ...)* and *form_volume* will default to 1.0.
-
-The C code follows the C99 standard, including the usual math functions,
-as defined in
-`OpenCL <https://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/mathFunctions.html>`_.
-
-The standard constants and functions include the following::
-
-    M_PI = pi
-    M_PI_2 = pi/2
-    M_PI_4 = pi/4
-    M_E = e
-    M_SQRT1_2 = 1/sqrt(2)
-    NAN = NaN
-    INFINITY = 1/0
-    erf(x) = error function
-    erfc(x) = 1-erf(x)
-    expm1(x) = exp(x) - 1
-    tgamma(x) = gamma function
-
-Some non-standard constants and functions are also provided::
-
-    M_PI_180 = pi/180
-    M_4PI_3 = 4pi/3
-    square(x) = x*x
-    cube(x) = x*x*x
-    sinc(x) = sin(x)/x, with sin(0)/0 -> 1
-    SINCOS(x, s, c) sets s=sin(angle) and c=cos(angle)
-    powr(x, y) = x^y for x >= 0
-    pown(x, n) = x^n for n integer
-
-**source=['lib/fn.c', ...]** includes the listed C source files in the
+and it includes orientation parameters.
+
+*form_volume* defines the volume of the shape. As in python models, it 
+includes only the volume parameters.
+
+*Iqxy* will default to *Iq(sqrt(qx**2 + qy**2), par1, ...)* and
+*form_volume* will default to 1.0.
+
+**source=['fn.c', ...]** includes the listed C source files in the
 program before *Iq* and *Iqxy* are defined. This allows you to extend the
-library of available C functions. Additional special functions and
-scattering calculations are defined in
-`sasmodels/models/lib <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib>`_,
-including::
-
-    sph_j1c(x) = 3 j1(x)/x = 3 (sin(x) - x cos(x))/x^3  [spherical bessel function]
-    sas_J1c(x) = 2 J1(x)/x  [bessel function of the first kind]
-    sas_gamma(x) = gamma function  [tgamma is unstable below 1]
-    sas_erf(x) = error function [erf is broken on some Intel OpenCL drivers]
-    sas_erfc(x) = 1-erf(x)
-    sas_J0(x) = J0(x)
-    sas_J1(x) = J1(x)
-    sas_JN(x) = JN(x)
-    Si(x) = integral sin(z)/z from 0 to x
-    Gauss76Wt = gaussian quadrature weights for 76 point integral
-    Gauss76Z = gaussian quadrature values for 76 point integral
-
-These functions have been tuned to be fast and numerically stable down
-to $q=0$ even in single precision.  In some cases they work around bugs
-which appear on some platforms but not others.
+library of C functions available to your model.
 
 Models are defined using double precision declarations for the
-parameters and return values.  Declarations and constants will be converted
-to float or long double depending on the precision requested.
+parameters and return values.  When a model is run using single
+precision or long double precision, each variable is converted
+to the target type, depending on the precision requested.
+
 **Floating point constants must include the decimal point.**  This allows us
 to convert values such as 1.0 (double precision) to 1.0f (single precision)
@@ -529 +512 @@
 use the builtin constant M_PI rather than 4*atan(1); it is faster and smaller!
 
-FLOAT_SIZE is the number of bytes in the converted variables. If your
-algorithm depends on precision (which is not uncommon for numerical
-algorithms), use the following::
-
-    #if FLOAT_SIZE>4
-    ... code for double precision ...
-    #else
-    ... code for single precision ...
-    #endif
-
-A value defined as SAS_DOUBLE will stay double precision; this should
-not be used since some graphics card don't support double precision.
-
+The C model operates on a single $q$ value at a time.  The code will be
+run in parallel across different $q$ values, either on the graphics card
+or the processor.
+
+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::
+
+    #define INVALID(v) (v.bell_radius < v.radius)
+
+Special Functions
+.................
+
+The C code follows the C99 standard, with the usual math functions,
+as defined in
+`OpenCL <https://www.khronos.org/registry/cl/sdk/1.1/docs/man/xhtml/mathFunctions.html>`_.
+This includes the following:
+
+    M_PI, M_PI_2, M_PI_4, M_SQRT1_2, M_E:
+        $\pi$, $\pi/2$, $\pi/4$, $1/\sqrt{2}$ and Euler's constant $e$
+    exp, log, pow(x,y), expm1, sqrt:
+        Power functions $e^x$, $\ln x$, $x^y$, $e^x - 1$, $\sqrt{x}$.
+        The function expm1(x) is accurate across all $x$, including $x$
+        very close to zero.
+    sin, cos, tan, asin, acos, atan:
+        Trigonometry functions and inverses, operating on radians.
+    sinh, cos, tanh, asinh, acosh, atanh:
+        Hyperbolic trigonometry functions.
+    atan2(y,x):
+        Angle from the $x$\ -axis to the point $(x,y)$, which is equal to
+        $\tan^{-1}(y/x)$ corrected for quadrant.  That is, if $x$ and $y$ are
+        both negative, then atan2(y,x) returns a value in quadrant III where
+        atan(y/x) would return a value in quadrant I. Similarly for
+        quadrants II and IV when $x$ and $y$ have opposite sign.
+    fmin(x,y), fmax(x,y), trunc, rint:
+        Floating point functions.  rint(x) returns the nearest integer.
+    NAN:
+        NaN, Not a Number, $0/0$.  Use isnan(x) to test for NaN.  Note that
+        you cannot use :code:`x == NAN` to test for NaN values since that
+        will always return false.  NAN does not equal NAN!
+    INFINITY:
+        $\infty, 1/0$.  Use isinf(x) to test for infinity, or isfinite(x)
+        to test for finite and not NaN.
+    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.
+
+Some non-standard constants and functions are also provided:
+
+    M_PI_180, M_4PI_3:
+        $\frac{\pi}{180}$, $\frac{4\pi}{3}$
+    SINCOS(x, s, c):
+        Macro which sets s=sin(x) and c=cos(x). The variables *c* and *s*
+        must be declared first.
+    square(x):
+        $x^2$
+    cube(x):
+        $x^3$
+    sas_sinx_x(x):
+        $\sin(x)/x$, with limit $\sin(0)/0 = 1$.
+    powr(x, y):
+        $x^y$ for $x \ge 0$; this is faster than general $x^y$ on some GPUs.
+    pown(x, n):
+        $x^n$ for $n$ integer; this is faster than general $x^n$ on some GPUs.
+    FLOAT_SIZE:
+        The number of bytes in a floating point value.  Even though all
+        variables are declared double, they may be converted to single
+        precision float before running. If your algorithm depends on
+        precision (which is not uncommon for numerical algorithms), use
+        the following::
+
+            #if FLOAT_SIZE>4
+            ... code for double precision ...
+            #else
+            ... code for single precision ...
+            #endif
+    SAS_DOUBLE:
+        A replacement for :code:`double` so that the declared variable will
+        stay double precision; this should generally not be used since some
+        graphics cards do not support double precision.  There is no provision
+        for forcing a constant to stay double precision.
+
+The following special functions and scattering calculations are defined in
+`sasmodels/models/lib <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib>`_.
+These functions have been tuned to be fast and numerically stable down
+to $q=0$ even in single precision.  In some cases they work around bugs
+which appear on some platforms but not others, so use them where needed.
+Add the files listed in :code:`source = ["lib/file.c", ...]` to your *model.py*
+file in the order given, otherwise these functions will not be available.
+
+    polevl(x, c, n):
+        Polynomial evaluation $p(x) = \sum_{i=0}^n c_i x^i$ using Horner's
+        method so it is faster and more accurate.
+
+        $c = \{c_n, c_{n-1}, \ldots, c_0 \}$ is the table of coefficients,
+        sorted from highest to lowest.
+
+        :code:`source = ["lib/polevl.c", ...]` (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/polevl.c>`_)
+
+    p1evl(x, c, n):
+        Evaluation of normalized polynomial $p(x) = x^n + \sum_{i=0}^{n-1} c_i x^i$
+        using Horner's method so it is faster and more accurate.
+
+        $c = \{c_{n-1}, c_{n-2} \ldots, c_0 \}$ is the table of coefficients,
+        sorted from highest to lowest.
+
+        :code:`source = ["lib/polevl.c", ...]`
+        (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/polevl.c>`_)
+
+    sas_gamma(x):
+        Gamma function $\text{sas_gamma}(x) = \Gamma(x)$.
+
+        The standard math function, tgamma(x) is unstable for $x < 1$
+        on some platforms.
+
+        :code:`source = ["lib/sasgamma.c", ...]`
+        (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_gamma.c>`_)
+
+    sas_erf(x), sas_erfc(x):
+        Error function
+        $\text{sas_erf}(x) = \frac{2}{\sqrt\pi}\int_0^x e^{-t^2}\,dt$
+        and complementary error function
+        $\text{sas_erfc}(x) = \frac{2}{\sqrt\pi}\int_x^{\infty} e^{-t^2}\,dt$.
+
+        The standard math functions erf(x) and erfc(x) are slower and broken
+        on some platforms.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_erf.c", ...]`
+        (`link to error functions' code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_erf.c>`_)
+
+    sas_J0(x):
+        Bessel function of the first kind $\text{sas_J0}(x)=J_0(x)$ where
+        $J_0(x) = \frac{1}{\pi}\int_0^\pi \cos(x\sin(\tau))\,d\tau$.
+
+        The standard math function j0(x) is not available on all platforms.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J0.c", ...]`
+        (`link to Bessel function's code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_J0.c>`_)
+
+    sas_J1(x):
+        Bessel function of the first kind  $\text{sas_J1}(x)=J_1(x)$ where
+        $J_1(x) = \frac{1}{\pi}\int_0^\pi \cos(\tau - x\sin(\tau))\,d\tau$.
+
+        The standard math function j1(x) is not available on all platforms.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J1.c", ...]`
+        (`link to Bessel function's code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_J1.c>`_)
+
+    sas_JN(n, x):
+        Bessel function of the first kind and integer order $n$:
+        $\text{sas_JN}(n, x)=J_n(x)$ where
+        $J_n(x) = \frac{1}{\pi}\int_0^\pi \cos(n\tau - x\sin(\tau))\,d\tau$.
+        If $n$ = 0 or 1, it uses sas_J0(x) or sas_J1(x), respectively.
+
+        The standard math function jn(n, x) is not available on all platforms.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J0.c", "lib/sas_J1.c", "lib/sas_JN.c", ...]`
+        (`link to Bessel function's code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_JN.c>`_)
+
+    sas_Si(x):
+        Sine integral $\text{Si}(x) = \int_0^x \tfrac{\sin t}{t}\,dt$.
+
+        This function uses Taylor series for small and large arguments:
+
+        For large arguments,
+
+        .. math::
+
+             \text{Si}(x) \sim \frac{\pi}{2}
+             - \frac{\cos(x)}{x}\left(1 - \frac{2!}{x^2} + \frac{4!}{x^4} - \frac{6!}{x^6} \right)
+             - \frac{\sin(x)}{x}\left(\frac{1}{x} - \frac{3!}{x^3} + \frac{5!}{x^5} - \frac{7!}{x^7}\right)
+
+        For small arguments,
+
+        .. math::
+
+           \text{Si}(x) \sim x
+           - \frac{x^3}{3\times 3!} + \frac{x^5}{5 \times 5!} - \frac{x^7}{7 \times 7!}
+           + \frac{x^9}{9\times 9!} - \frac{x^{11}}{11\times 11!}
+
+        :code:`source = ["lib/Si.c", ...]`
+        (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/Si.c>`_)
+
+    sas_3j1x_x(x):
+        Spherical Bessel form
+        $\text{sph_j1c}(x) = 3 j_1(x)/x = 3 (\sin(x) - x \cos(x))/x^3$,
+        with a limiting value of 1 at $x=0$, where $j_1(x)$ is the spherical
+        Bessel function of the first kind and first order.
+
+        This function uses a Taylor series for small $x$ for numerical accuracy.
+
+        :code:`source = ["lib/sas_3j1x_x.c", ...]`
+        (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_3j1x_x.c>`_)
+
+
+    sas_2J1x_x(x):
+        Bessel form $\text{sas_J1c}(x) = 2 J_1(x)/x$, with a limiting value
+        of 1 at $x=0$, where $J_1(x)$ is the Bessel function of first kind
+        and first order.
+
+        :code:`source = ["lib/polevl.c", "lib/sas_J1.c", ...]`
+        (`link to Bessel form's code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/sas_J1.c>`_)
+
+
+    Gauss76Z[i], Gauss76Wt[i]:
+        Points $z_i$ and weights $w_i$ for 76-point Gaussian quadrature, respectively,
+        computing $\int_{-1}^1 f(z)\,dz \approx \sum_{i=1}^{76} w_i\,f(z_i)$.
+
+        Similar arrays are available in :code:`gauss20.c` for 20-point
+        quadrature and in :code:`gauss150.c` for 150-point quadrature.
+
+        :code:`source = ["lib/gauss76.c", ...]`
+        (`link to code <https://github.com/SasView/sasmodels/tree/master/sasmodels/models/lib/gauss76.c>`_)
+
+
+
+Problems with C models
+......................
+
+The graphics processor (GPU) in your computer is a specialized computer tuned
+for certain kinds of problems.  This leads to strange restrictions that you
+need to be aware of.  Your code may work fine on some platforms or for some
+models, but then return bad values on other platforms.  Some examples of
+particular problems:
+
+  **(1) Code is too complex, or uses too much memory.**  GPU devices only have a
+  limited amount of memory available for each processor.  If you run programs
+  which take too much memory, then rather than running multiple values in parallel
+  as it usually does, the GPU may only run a single version of the code at a
+  time, making it slower than running on the CPU.  It may fail to run on
+  some platforms, or worse, cause the screen to go blank or the system to reboot.
+
+  **(2) Code takes too long.**  Because GPU devices are used for the computer
+  display, the OpenCL drivers are very careful about the amount of time they
+  will allow any code to run.  For example, on OS X, the model will stop running
+  after 5 seconds regardless of whether the computation is complete.  You may end up
+  with only some of your 2D array defined, with the rest containing random
+  data. Or it may cause the screen to go blank or the system to reboot.
+
+  **(3) Memory is not aligned**.  The GPU hardware is specialized to operate on
+  multiple values simultaneously.  To keep the GPU simple the values in memory
+  must be aligned with the different GPU compute engines.  Not following these
+  rules can lead to unexpected values being loaded into 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::
+
+      double Iq(q, p1, p2, ...)
+      {
+          double vector[8];  // Only going to use seven slots, but declare 8
+          ...
+      }
+
+The first step when your model is behaving strangely is to set **single=False**.
+This automatically restricts the model to only run on the CPU, or on high-end
+GPU cards.  There can still be problems even on high-end cards, so you can force
+the model off the GPU by setting **opencl=False**.  This runs the model
+as a normal C program without any GPU restrictions so you know that
+strange results are probably from your code rather than the environment.  Once
+the code is debugged, you can compare your output to the output on the GPU.
+
+Although it can be difficult to get your model to work on the GPU, the reward
+can be a model that runs 1000x faster on a good card.  Even your laptop may
+show a 50x improvement or more over the equivalent pure python model.
 
 External C Models
@@ -548 +783 @@
 External C models are very much like embedded C models, except that
 *Iq*, *Iqxy* and *form_volume* are defined in an external source file
-loaded using the *source=[...]*  method. You need to supply the function
+loaded using the *source=[...]* statement. You need to supply the function
 declarations for each of these that you need instead of building them
 automatically from the parameter table.
@@ -557 +792 @@
 Form Factors
 ............
-
-::
-
-    def ER(radius, thickness):
-        """Effective radius of a core-shell sphere."""
-        return radius + thickness
 
 Away from the dilute limit you can estimate scattering including
@@ -572 +801 @@
 form averaged over all the polydispersity values.
 
-Consider the *core_shell_sphere*, which has a simple effective radius
+::
+
+    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
@@ -597 +832 @@
 one return value for each point in the mesh grid.
 
-*NOTE: we may be removing or modifying this feature soon.*  As of this
-writing, core-shell sphere returns (1., 1.) for *VR*, giving a volume
-ratio of 1.0.
+*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.*
 
 Unit Tests
@@ -624 +859 @@
 - a dictionary of parameter values. This can be {} using the default
   parameters, or filled with some parameters that will be different
-  from the default, such as {‘radius’:10.0, ‘sld’:4}. Unlisted parameters
+  from the default, such as {‘radius’:10.0, ‘sld’:4}. Unlisted parameters
   will be given the default values.
 - the input $q$ value or tuple of $(q_x, q_y)$ values.
@@ -640 +875 @@
 ^^^^^^^^^^^^^^^^^^^
 
-If you are editing your model from the SasView GUI, you can test it
-by selecting *Run -> Compile* from the *Model Editor* menu bar. An
-*Info* box will appear with the results of the compilation and a
-check that the model runs.
+Minimal Testing
+...............
+
+Either open the :ref:`Python_shell` (*Tools* > *Python Shell/Editor*) or the :ref:`Advanced_Plugin_Editor` (*Fitting* > *Plugin Model Operations* > *Advanced 
+Plugin Editor*), load your model, and then select *Run > Check Model* from the 
+menu bar.
+
+An *Info* box will appear with the results of the compilation and a check that 
+the model runs.
+
+Recommended Testing
+...................
 
 If the model compiles and runs, you can next run the unit tests that
-you have added using the **test=** values. Switch to the *Shell* tab
+you have added using the **test =** values. Switch to the *Shell* tab
 and type the following::
 
@@ -686 +929 @@
 For the random models,
 
-- sld will be in(-0.5,10.5),
-- angles (theta, phi, psi) will be in (-180,180),
-- angular dispersion will be in (0,45),
-- polydispersity will be in (0,1)
-- other values will be in (0, 2*v) where v is the value of the parameter in demo.
-
-Dispersion parameters n, sigma and type will be unchanged from demo so that
+- *sld* will be in the range (-0.5,10.5),
+- angles (*theta, phi, psi*) will be in the range (-180,180),
+- angular dispersion will be in the range (0,45),
+- polydispersity will be in the range (0,1)
+- other values will be in the range (0, 2\ *v*), where *v* is the value of the parameter in demo.
+
+Dispersion parameters *n*\, *sigma* and *type* will be unchanged from demo so that
 run times are predictable.
 
@@ -701 +944 @@
 
 
-Clean Lint
-^^^^^^^^^^
-
-**NB: For now we are not providing pylint with SasView; unless you have a
-SasView development environment available, you can ignore this section.**
+Clean Lint - (Developer Version Only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**NB: For now we are not providing pylint with the installer version of SasView; 
+so unless you have a SasView build environment available, you can ignore this section!**
 
 Run the lint check with::
@@ -717 +960 @@
 for standard model functions *Iq*, *Iqxy*, etc.
 
-We will have delinting sessions at the SasView code camps, where we can
+We will have delinting sessions at the SasView Code Camps, where we can
 decide on standards for model files, parameter names, etc.
 
-For now, you can tell pylint to ignore things.  For example, to align you
+For now, you can tell pylint to ignore things.  For example, to align your
 parameters in blocks::
 
@@ -738 +981 @@
 Don't put in too many pylint statements, though, since they make the code ugly.
 
-Check The Docs
-^^^^^^^^^^^^^^
+Check The Docs - (Developer Version Only)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can get a rough idea of how the documentation will look using the
@@ -756 +999 @@
 - `amsmath <http://www.ams.org/publications/authors/tex/amslatex>`_
 
-Finally
-^^^^^^^
+There is also a neat online WYSIWYG ReStructuredText editor at http://rst.ninjs.org\ .
+
+Share Your Model!
+^^^^^^^^^^^^^^^^^
 
 Once compare and the unit test(s) pass properly and everything is done,
 consider adding your model to the
-`model marketplace <http://marketplace.sasview.org/>`_.
-
+`Model Marketplace <http://marketplace.sasview.org/>`_ so that others may use it!
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. note::  This help document was last changed by Steve King, 25Oct2016

src/sas/sasgui/perspectives/fitting/media/sm_help.rst

@@ -20 +20 @@
 ==================
 
-Sometimes it will be necessary to correct reduced experimental data for the
-physical effects of the instrumental geometry in use. This process is called
-*desmearing*. However, calculated/simulated data - which by definition will be
-perfect/exact - can be *smeared* to make it more representative of what might
-actually be measured experimentally.
-
-SasView provides the following three smearing algorithms:
+Sometimes the instrumental geometry used to acquire the experimental data has 
+an impact on the clarity of features in the reduced scattering curve. For 
+example, peaks or fringes might be slightly broadened. This is known as 
+*Q resolution smearing*. To compensate for this effect one can either try and 
+remove the resolution contribution - a process called *desmearing* - or add the 
+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*. SasView will do the latter.
+
+Both smearing and desmearing rely on functions to describe the resolution 
+effect. SasView provides three smearing algorithms:
 
 *  *Slit Smearing*
 *  *Pinhole Smearing*
 *  *2D Smearing*
+
+SasView also has an option to use Q resolution data (estimated at the time of 
+data reduction) supplied in a reduced data file: the *Use dQ data* radio button.
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+dQ Smearing
+-----------
+ 
+If this option is checked, SasView will assume that the supplied dQ values 
+represent the standard deviations of Gaussian functions.
 
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ