Changeset c5cfb20 in sasview for src/sas/sasgui/perspectives/fitting/media/fitting_help.rst

Timestamp:

Sep 18, 2017 12:19:13 PM (7 years ago)

Author:

Paul Kienzle <pkienzle@…>

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

Children:

1e6d9340

Parents:

1659f54 (diff), cfd27dd (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 ticket-639-katex

File:

• src/sas/sasgui/perspectives/fitting/media/fitting_help.rst (modified) (4 diffs)

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

@@ -195 +195 @@
 the :ref:`Advanced_Plugin_Editor` .
 
+**SasView version 4.2** made it possible to specify whether a plugin created with 
+the *New Plugin Model* dialog is actually a form factor P(Q) or a structure factor 
+S(Q). To do this, simply add one or other of the following lines under the *import* 
+statements.
+
+For a form factor::
+
+     form_factor = True
+         
+or for a structure factor::
+
+     structure_factor = True
+         
+If the plugin is a structure factor it is *also* necessary to add two variables to 
+the parameter list::
+
+     parameters = [ 
+                     ['radius_effective', '', 1, [0.0, numpy.inf], 'volume', ''],
+                     ['volfraction', '', 1, [0.0, 1.0], '', ''],
+                     [...],
+
+and to the declarations of the functions Iq and Iqxy:::
+
+     def Iq(x , radius_effective, volfraction, ...):
+
+     def Iqxy(x, y, radius_effective, volfraction, ...):
+
+Such a plugin should then be available in the S(Q) drop-down box on a FitPage (once 
+a P(Q) model has been selected).
+
 Sum|Multi(p1,p2)
 ^^^^^^^^^^^^^^^^
@@ -206 +236 @@
 or::
 
-     Plugin Model = scale_factor * model_1 /* model_2 + background
+     Plugin Model = scale_factor * (model1 * model2) + 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*.
-
-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.
+them. Finally, click the *Apply* button to generate and test the model and then click *Close*.
+
+Any changes to a plugin model generated in this way only become effective *after* it is re-selected 
+from the plugin models drop-down menu on the FitPage. If the model is not listed you can force a 
+recompilation of the plugins by selecting *Fitting* > *Plugin Model Operations* > *Load Plugin Models*.
+
+**SasView version 4.2** introduced a much simplified and more extensible structure for plugin models 
+generated through the Easy Sum/Multi Editor. For example, the code for a combination of a sphere model 
+with a power law model now looks like this::
+
+     from sasmodels.core import load_model_info
+     from sasmodels.sasview_model import make_model_from_info
+     
+     model_info = load_model_info('sphere+power_law')
+     model_info.name = 'MyPluginModel'
+     model_info.description = 'sphere + power_law'
+     Model = make_model_from_info(model_info)
+
+To change the models or operators contributing to this plugin it is only necessary to edit the string 
+in the brackets after *load_model_info*, though it would also be a good idea to update the model name 
+and description too!!!
+
+The model specification string can handle multiple models and combinations of operators (+ or *) which 
+are processed according to normal conventions. Thus 'model1+model2*model3' would be valid and would 
+multiply model2 by model3 before adding model1. In this example, parameters in the *FitPage* would be 
+prefixed A (for model2), B (for model3) and C (for model1). Whilst this might appear a little 
+confusing, unless you were creating a plugin model from multiple instances of the same model the parameter 
+assignments ought to be obvious when you load the plugin.
+
+If you need to include another plugin model in the model specification string, just prefix the name of 
+that model with *custom*. For instance::
+
+     sphere+custom.MyPluginModel
+
+To create a P(Q)*\S(Q) model use the @ symbol instead of * like this::
+
+     sphere@hardsphere
+     
+This streamlined approach to building complex plugin models from existing library models, or models 
+available on the *Model Marketplace*, also permits the creation of P(Q)*\S(Q) plugin models, something 
+that was not possible in earlier versions of SasView. 
 
 .. _Advanced_Plugin_Editor:
@@ -484 +552 @@
 .. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
 
+.. _Batch_Fit_Mode:
+
 Batch Fit Mode
 --------------
@@ -636 +706 @@
 
      Example: radius [2 : 5] , radius [10 : 25]
-
-.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
-
-.. note::  This help document was last changed by Steve King, 10Oct2016
+     
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+Combined Batch Fit Mode
+-----------------------
+
+The purpose of the Combined Batch Fit is to allow running two or more batch
+fits in sequence without overwriting the output table of results.  This may be
+of interest for example if one is fitting a series of data sets where there is
+a shape change occurring in the series that requires changing the model part
+way through the series; for example a sphere to rod transition.  Indeed the
+regular batch mode does not allow for multiple models and requires all the
+files in the series to be fit with single model and set of parameters.  While
+it is of course possible to just run part of the series as a batch fit using
+model one followed by running another batch fit on the rest of the series with
+model two (and/or model three etc), doing so will overwrite the table of
+outputs from the previous batch fit(s).  This may not be desirable if one is
+interested in comparing the parameters: for example the sphere radius of set
+one and the cylinder radius of set two.
+
+Method
+^^^^^^
+
+In order to use the *Combined Batch Fit*, first load all the data needed as
+described in :ref:`Loading_data`. Next start up two or more *BatchPage* fits
+following the instructions in :ref:`Batch_Fit_Mode` but **DO NOT PRESS FIT**.
+At this point the *Combine Batch Fit* menu item under the *Fitting menu* should
+be active (if there is one or no *BatchPage* the menu item will be greyed out
+and inactive).  Clicking on *Combine Batch Fit* will bring up a new panel,
+similar to the *Const & Simult Fit* panel. In this case there will be a
+checkbox for each *BatchPage* instead of each *FitPage* that should be included
+in the fit.  Once all are selected, click the Fit button on
+the *BatchPage* to run each batch fit in *sequence*
+
+.. image:: combine_batch_page.png
+
+The batch table will then pop up at the end as for the case of the simple Batch
+Fitting with the following caveats:
+
+.. note::
+   The order matters.  The parameters in the table will be taken from the model
+   used in the first *BatchPage* of the list.  Any parameters from the
+   second and later *BatchPage* s that have the same name as a parameter in the
+   first will show up allowing for plotting of that parameter across the
+   models. The other parameters will not be available in the grid.
+.. note::
+   a corralary of the above is that currently models created as a sum|multiply
+   model will not work as desired because the generated model parameters have a
+   p#_ appended to the beginning and thus radius and p1_radius will not be
+   recognized as the same parameter.
+   
+.. image:: combine_batch_grid.png
+
+In the example shown above the data is a time series with a shifting peak.
+The first part of the series was fitted using the *broad_peak* model, while
+the rest of the data were fit using the *gaussian_peak* model. Unfortunately the
+time is not listed in the file but the file name contains the information. As
+described in :ref:`Grid_Window`, a column can be added manually, in this case
+called time, and the peak position plotted against time. 
+
+.. image:: combine_batch_plot.png
+
+Note the discontinuity in the peak position.  This reflects the fact that the
+Gaussian fit is a rather poor model for the data and is not actually
+finding the peak.
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. note::  This help document was last changed by Paul Butler, 10 September
+   2017