Changeset 3e1c9e5 in sasview

Timestamp:

Oct 10, 2016 5:52:25 PM (8 years ago)

Author:

smk78

Branches:

master, 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, costrafo411, magnetic_scatt, release-4.1.1, release-4.1.2, release-4.2.2, ticket-1009, ticket-1094-headless, ticket-1242-2d-resolution, ticket-1243, ticket-1249, ticket885, unittest-saveload

Children:

d472e86, 49e000b

Parents:

f2261c2

Message:

Disinfected menu_bar.rst, fitting_help.rst and plugin.rst of 'custom
model' in favour of 'plugin model' and re-wrote sections of the
documentation to match it to the functionality of the program with
particular emphasis on creating/testing plugin models.

Files:

• docs/sphinx-docs/source/user/menu_bar.rst (modified) (2 diffs)
• src/sas/sasgui/perspectives/fitting/media/edit_model_menu.png (modified) (previous)
• src/sas/sasgui/perspectives/fitting/media/fitting_help.rst (modified) (6 diffs)
• src/sas/sasgui/perspectives/fitting/media/plugin.rst (modified) (4 diffs)

docs/sphinx-docs/source/user/menu_bar.rst

@@ -62 +62 @@
 - change optimiser (under Fit Options);
 - view fit parameter correlations, distributions, and convergence traces (under Fit Results);
-- create/edit a Custom Model.
+- create/edit a Plugin Model.
 
 Additional functionality is available under this menu option during particular types of model fitting, including:
@@ -80 +80 @@
 - the :ref:`marketplace`\ ;
 - a check to see if there is a more recent version of *SasView*.
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. note::  This help document was last changed by Steve King, 10Oct2016

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

@@ -18 +18 @@
 =======
 
+.. note:: If some code blocks are not readable, expand the documentation window
+
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
@@ -116 +118 @@
 ---------------
 
-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 +126 @@
 .. _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*.
+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 options
-
-*  *New* - to create a custom model template with a help dialog
-*  *Sum|Multi(p1,p2)* - to create a custom model by summing/multiplying *existing models* in the model library
-*  *Advanced* - to create/edit a custom model in a Python shell
-*  *Delete* - to delete a custom model
-*  *Load* - to (re-)load custom models
-
-New
-^^^^
+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
+^^^^^^^^^^^^^^^^
 
 .. image:: new_model.bmp
 
 A model template generated by this option can be viewed and further modified using
-the :ref:`Advanced` option.
+the :ref:`Advanced_Plugin_Editor` .
 
 *NB: "Fit Parameters" has been split into two sections, those which can be
@@ -168 +177 @@
 .. 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 model of the form::
+
+     Custom Model = scale_factor \* {(scale_1 \* model_1) \+ (scale_2 \* model_2)} \+ background
+
+or::
+
+     Custom 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, on Windows this is
+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*. Note that this is actually the same tool as the :ref:`Python_shell` .
+*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` .
@@ -196 +208 @@
 .. 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 Custom 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*
+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.
 
-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 FitPage.
-
-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.*
-
-Load
-^^^^
-
-This option loads (or re-loads) all models present in the plugin model folder.
+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: Plugin 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
@@ -601 +615 @@
 .. 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

@@ -9 +9 @@
 ^^^^^^^^^^^^
 
-There are currently two ways to add your own models to SasView:
-
-* Using the :ref:`Custom_Model_Editor`
-* By Writing a Plugin Model
-
-The Custom Model Editor lets you combine *existing* SasView library models. For anything more 
-complex, or if you want to apply polydispersity to parameters, you will need to write a Plugin Model.  
+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
@@ -22 +20 @@
 If you write your own model and save it to the the SasView *plugin_models* folder
 
-  *C:\\Users\\[username]\\.sasview\\plugin_models* (on Windows)
+  *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* in a FitPage.
-
-SasView has three ways of writing models:
-
-- As a pure python model : Example -
+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>`_
@@ -671 +669 @@
 ^^^^^^^^^^^^^^^^^^^
 
-Installed SasView
-.................
-
-If you are editing your model from the SasView GUI, you can test it
-by selecting *Run > Check Model* from the *Model Editor* menu bar. An
-*Info* box will appear with the results of the compilation and a
-check that the model runs.
-
-
-Built SasView
-.............
+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
@@ -802 +801 @@
 consider adding your model to the
 `Model Marketplace <http://marketplace.sasview.org/>`_ so that others may use it!
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. note::  This help document was last changed by Steve King, 10Oct2016