Changeset b31b7e2 in sasview


Ignore:
Timestamp:
May 14, 2018 9:30:36 AM (3 years ago)
Author:
Piotr Rozyczko <rozyczko@…>
Branches:
ESS_GUI, 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:
f9214aa
Parents:
d1fa2b8
Message:

Fitting perspective documentation - part 1. SASVIEW-917

Location:
src/sas/qtgui/Perspectives/Fitting/media
Files:
5 added
6 edited

Legend:

Unmodified
Added
Removed
  • src/sas/qtgui/Perspectives/Fitting/media/fitting_help.rst

    r417c03f rb31b7e2  
    5252 
    5353Use the *Category* drop-down menu to chose a category of model, then select 
    54 a model from the drop-down menu beneath. A graph of the chosen model, calculated 
    55 using default parameter values, will appear. The graph will update dynamically 
    56 as the parameter values are changed. 
     54a model from the drop-down menu to the right. The "Show Plot" button on the 
     55bottom of the dialog will become active. If you click on it,  
     56a graph of the chosen model, calculated using default parameter values, will appear. 
     57The graph will update dynamically as the parameter values are changed. 
    5758 
    5859You can decide your own model categorizations using the :ref:`Category_Manager`. 
    5960 
    60 Once you have selected a model you can read its help documentation by clicking 
    61 on the *Description* button to the right. 
     61Once you have selected a model you can read its help documentation by right clicking 
     62on the empty space in the parameter table. 
     63 
     64.. image:: descr_fig.png 
    6265 
    6366Show 1D/2D 
     
    6972*NB: Magnetic scattering can only be fitted in SasView in 2D.* 
    7073 
    71 To activate 2D fitting mode, click the *Show 2D* button on the *Fit Page*. To 
    72 return to 1D fitting model, click the same button (which will now say *Show 1D*). 
     74To activate 2D fitting mode, select the *2D view* checkbox on the *Fit Page*. To 
     75return to 1D fitting model, de-select the same checkbox. 
    7376 
    7477.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    136139*  By copying/editing an existing model (this can include models generated by 
    137140   the New Plugin Model* dialog) in the :ref:`Python_shell` or 
    138    :ref:`Advanced_Plugin_Editor` (suitable for all use cases) 
     141   :ref:`Plugin_Editor` (suitable for all use cases) 
    139142*  By writing a model from scratch outside of SasView (only recommended for code 
    140143   monkeys!) 
     
    151154----------------------- 
    152155 
    153 From the *Fitting* option in the menu bar, select *Plugin Model Operations* 
     156From the *Fitting* option in the menu bar, select one of the options: 
    154157 
    155158.. image:: edit_model_menu.png 
    156159 
    157 and then one of the sub-options 
    158  
    159 *  *New Plugin Model* - to create a plugin model template with a helper dialog 
    160 *  *Sum|Multi(p1,p2)* - to create a plugin model by summing/multiplying *existing models* in the model library 
    161 *  *Advanced Plugin Editor* - to create/edit a plugin model in a Python shell 
    162 *  *Delete Plugin Models* - to delete a plugin model 
    163 *  *Load Plugin Models* - to (re-)load plugin models 
     160*  *Add Custom Model* - to create a plugin model template with a helper dialog 
     161*  *Edit Custom Model* - to edit a plugin model in an editor window 
     162*  *Manage Custom Models* - to open a custom model manager allowing for a number of actions to be taken on custom models: listing, adding, deleteing, duplicating, editing 
     163*  *Add/Multiply Models* - to create a plugin model by summing/multiplying *existing models* in the model library 
    164164 
    165165.. _New_Plugin_Model: 
    166166 
    167 New Plugin Model 
     167Add Custom Model 
    168168^^^^^^^^^^^^^^^^ 
    169169 
    170170Relatively straightforward models can be programmed directly from the SasView 
    171 GUI using the *New Plugin Model Function*. 
     171GUI using the *Plugin Definition* Function. 
    172172 
    173173.. image:: new_model.png 
     
    185185 
    186186A model file generated by this option can be viewed and further modified using 
    187 the :ref:`Advanced_Plugin_Editor` . 
     187the :ref:`Model_Editor`. 
    188188 
    189189**SasView version 4.2** made it possible to specify whether a plugin created with 
     
    217217a P(Q) model has been selected). 
    218218 
    219 Sum|Multi(p1,p2) 
    220 ^^^^^^^^^^^^^^^^ 
     219 
     220.. Model_Editor: 
     221 
     222Model Editor 
     223^^^^^^^^^^^^ 
     224 
     225Selecting "Edit Custom Model" option opens the editor window. 
     226 
     227.. image :: model_editor_empty.png 
     228 
     229Initially, the editor is empty. A custom model can be loaded by clicking on the *Load plugin...* button and choosing one of the existing custom plugins. 
     230 
     231Once the model is loaded, it can be edited and saved with *Save* button. 
     232Saving the model will perform the validation and only when the model is correct it will be saved to a file. 
     233Successful model check is indicated by a SasView status bar message. 
     234 
     235When *Cancel* is clicked, any changes to the model are discarded and the window is closed. 
     236 
     237 
     238For details of the SasView plugin model format see :ref:`Writing_a_Plugin` . 
     239 
     240To use the model, go to the relevant *Fit Page*, select the *Plugin Models* 
     241category and then select the model from the drop-down menu. 
     242 
     243 
     244.. Plugin_Manager: 
     245 
     246Plugin Manager 
     247^^^^^^^^^^^^^^ 
     248 
     249Selecting the *Manage Custom Models* option shows a list of all the plugin models in the plugin model folder, on Windows this is 
     250 
     251  *C:\\Users\\{username}\\.sasview\\plugin_models* 
     252 
     253You can add, edit, duplicate and delete these models using buttons on the right side of the list. 
     254 
     255.. image:: plugin_manager.png 
     256 
     257 
     258Add a model 
     259^^^^^^^^^^^ 
     260 
     261Clicking the "Add" button opens the Model Editor window, allowing you to create a new plugin as described above. 
     262 
     263Duplicate a model 
     264^^^^^^^^^^^^^^^^^ 
     265 
     266Clicking the "Duplicate" button will create a copy of the selected model(s). Naming of the duplicate follows the standard, with added * (n)* to the plugin model name, with *n* being the first unused yet integer. 
     267 
     268Edit a model 
     269^^^^^^^^^^^^ 
     270 
     271When a single model is selected, clicking this button will open the Advanced *Model Editor* allowing you to edit the 
     272Python code of the model. 
     273If no models or multiple models are selected, the *Edit* button is disabled. 
     274 
     275Delete Plugin Models 
     276^^^^^^^^^^^^^^^^^^^^ 
     277 
     278Simply highlight the plugin model(s) to be removed and click on the "Delete" button. The operation is final. 
     279 
     280*NB: Models shipped with SasView cannot be removed in this way.* 
     281 
     282 
     283Add/Multiply Models 
     284^^^^^^^^^^^^^^^^^^^ 
    221285 
    222286.. image:: sum_model.png 
     
    230294     Plugin Model = scale_factor * (model1 * model2) + background 
    231295 
    232 In the *Easy Sum/Multi Editor* give the new model a function name and brief 
     296In the *Add/Multiply Models* give the new model a function name and brief 
    233297description (to appear under the *Details* button on the *FitPage*). Then select 
    234 two existing models, as p1 and p2, and the required operator, '+' or '*' between 
     298two existing models, as model_1 and model_2, and the required operator, '+' or '*' between 
    235299them. Finally, click the *Apply* button to generate and test the model and then click *Close*. 
    236300 
    237 Any changes to a plugin model generated in this way only become effective *after* it is re-selected 
    238 from the plugin models drop-down menu on the FitPage. If the model is not listed you can force a 
    239 recompilation of the plugins by selecting *Fitting* > *Plugin Model Operations* > *Load Plugin Models*. 
    240301 
    241302**SasView version 4.2** introduced a much simplified and more extensible structure for plugin models 
    242 generated through the Easy Sum/Multi Editor. For example, the code for a combination of a sphere model 
     303generated through the Add/Multiply Models editor. For example, the code for a combination of a sphere model 
    243304with a power law model now looks like this:: 
    244305 
     
    275336that was not possible in earlier versions of SasView. 
    276337 
    277 .. _Advanced_Plugin_Editor: 
    278  
    279 Advanced Plugin Editor 
    280 ^^^^^^^^^^^^^^^^^^^^^^ 
    281  
    282 Selecting this option shows all the plugin models in the plugin model folder, on Windows this is 
    283  
    284   *C:\\Users\\{username}\\.sasview\\plugin_models* 
    285  
    286 You can edit, modify, and save the Python code in any of these models using the 
    287 *Advanced Plugin Model Editor*. Note that this is actually the same tool as the :ref:`Python_shell` . 
    288  
    289 For details of the SasView plugin model format see :ref:`Writing_a_Plugin` . 
    290  
    291 .. 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! 
    292  
    293 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'. 
    294  
    295 .. image:: ../calculator/new_pycrust_example_2.png 
    296  
    297 To use the model, go to the relevant *Fit Page*, select the *Plugin Models* 
    298 category and then select the model from the drop-down menu. 
    299  
    300 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. 
    301  
    302 Delete Plugin Models 
    303 ^^^^^^^^^^^^^^^^^^^^ 
    304  
    305 Simply highlight the plugin model to be removed. The operation is final!!! 
    306  
    307 *NB: Models shipped with SasView cannot be removed in this way.* 
    308  
    309 Load Plugin Models 
    310 ^^^^^^^^^^^^^^^^^^ 
    311  
    312 This option loads (or re-loads) all models present in the 
    313 *~\\.sasview\\plugin_models* folder. 
     338 
    314339 
    315340.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    317342.. _Fitting_Options: 
    318343 
    319 Fitting Options 
     344Fit Algorithms 
    320345--------------- 
    321346 
     
    323348to modify some of the configurational parameters for each optimiser. 
    324349 
    325 From *Fitting* in the menu bar select *Fit Options*, then select one of the following 
     350From *Fitting* in the menu bar select *Fit Algorithms*, then select one of the following 
    326351optimisers: 
    327352 
     
    332357*  Nelder-Mead Simplex 
    333358 
     359.. image:: fit_algorithms.png 
     360 
    334361The DREAM optimiser is the most sophisticated, but may not necessarily be the best 
    335362option for fitting simple models. If uncertain, try the Levenberg-Marquardt optimiser 
     
    348375sub-region of the data for fitting. 
    349376 
    350 In a *FitPage* or *BatchPage* change the *Q* values in the *Min* and/or *Max* 
    351 text boxes. Vertical coloured bars will appear on the graph with the data and 
    352 'theory' indicating the current *Q* limits (red = *Qmin*, purple = *Qmax*). 
     377In a *FitPage* or *BatchPage* change the tab to *Fit Options* and then change  
     378the *Q* values in the *Min* and/or *Max* 
     379text boxes.  
     380 
     381.. 
     382  Vertical coloured bars will appear on the graph with the data and 
     383  'theory' indicating the current *Q* limits (red = *Qmin*, purple = *Qmax*). 
    353384 
    354385To return to including all data in the fit, click the *Reset* button. 
     
    356387.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    357388 
    358  
    359 Shortcuts 
    360 --------- 
    361  
    362 Copy/Paste Parameters 
    363 ^^^^^^^^^^^^^^^^^^^^^ 
    364  
    365 It is possible to copy the parameters from one *Fit Page* and to paste them into 
    366 another *Fit Page* using the same model. 
    367  
    368 To *copy* parameters, either: 
    369  
    370 *  Select *Edit -> Copy Params* from the menu bar, or 
    371 *  Use Ctrl(Cmd on Mac) + Left Mouse Click on the *Fit Page*. 
    372  
    373 To *paste* parameters, either: 
    374  
    375 *  Select *Edit -> Paste Params* from the menu bar, or 
    376 *  Use Ctrl(Cmd on Mac) + Shift + Left-click on the *Fit Page*. 
    377  
    378 If either operation is successful a message will appear in the info line at the 
    379 bottom of the SasView window. 
    380  
    381 Bookmark 
    382 ^^^^^^^^ 
    383  
    384 To *Bookmark* a *Fit Page* either: 
    385  
    386 *  Select a *Fit Page* and then click on *Bookmark* in the tool bar, or 
    387 *  Right-click and select the *Bookmark* in the popup menu. 
     389.. 
     390 
     391  Shortcuts 
     392  --------- 
     393 
     394  Copy/Paste Parameters 
     395  ^^^^^^^^^^^^^^^^^^^^^ 
     396 
     397  It is possible to copy the parameters from one *Fit Page* and to paste them into 
     398  another *Fit Page* using the same model. 
     399 
     400  To *copy* parameters, either: 
     401 
     402  *  Select *Edit -> Copy Params* from the menu bar, or 
     403  *  Use Ctrl(Cmd on Mac) + Left Mouse Click on the *Fit Page*. 
     404 
     405  To *paste* parameters, either: 
     406 
     407  *  Select *Edit -> Paste Params* from the menu bar, or 
     408  *  Use Ctrl(Cmd on Mac) + Shift + Left-click on the *Fit Page*. 
     409 
     410  If either operation is successful a message will appear in the info line at the 
     411  bottom of the SasView window. 
     412 
     413  Bookmark 
     414  ^^^^^^^^ 
     415 
     416  To *Bookmark* a *Fit Page* either: 
     417 
     418  *  Select a *Fit Page* and then click on *Bookmark* in the tool bar, or 
     419  *  Right-click and select the *Bookmark* in the popup menu. 
    388420 
    389421.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    391423.. _Status_bar: 
    392424 
    393 Status Bar & Console 
    394 -------------------- 
     425Status Bar & Log Explorer 
     426------------------------- 
    395427 
    396428The status bar is located at the bottom of the SasView window and displays 
    397 messages, hints, warnings and errors. 
    398  
    399 At the right-hand side of the status bar is a button marked *Console*. The *Console* 
    400 displays available message history and some run-time traceback information. 
    401  
    402 During a long task the *Console* can also be used to monitor the progress. 
     429messages, warnings and errors. 
     430 
     431.. image:: log_explorer.png 
     432 
     433The bottom part of the SasView application window contains the *Log Explorer*. 
     434The *Log Explorer* displays available message history and run-time traceback information. 
    403435 
    404436.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
     
    409441--------------- 
    410442 
    411 *NB: Before proceeding, ensure that the Single Mode radio button at the bottom of* 
    412 *the Data Explorer is checked (see the section* :ref:`Loading_data` *).* 
     443*NB: Before proceeding, ensure that the Batch mode checkbox at the bottom of* 
     444*the Data Explorer is unchecked (see the section* :ref:`Loading_data` *).* 
    413445 
    414446This mode fits one data set. 
    415447 
    416 When data is sent to the fitting it is plotted in a graph window as markers. 
     448.. When data is sent to the fitting it is plotted in a graph window as markers. 
     449When data is sent to the fitting, the Fit Page will show the dataset name. 
     450 
     451.. image:: dataset_name.png 
     452 
     453Clicking on the *Show Plot* will cause the data can be plotted in a graph window as markers. 
    417454 
    418455If a graph does not appear, or a graph window appears but is empty, then the data 
     
    420457or in the *Console* window. 
    421458 
    422 Assuming the data has loaded correctly, when a model is selected a green model 
     459Assuming the data has loaded correctly, when a model is selected a blue model 
    423460calculation (or what SasView calls a 'Theory') line will appear in the earlier graph 
    424461window, and a second graph window will appear displaying the residuals (the 
     
    440477*'correlated').* 
    441478 
    442 In the bottom left corner of the *Fit Page* is a box displaying the normalised value 
     479In the bottom right corner of the *Fit Page* is a box displaying the normalised value 
    443480of the statistical $\chi^2$ parameter returned by the optimiser. 
    444481 
Note: See TracChangeset for help on using the changeset viewer.