Changeset 7f23423 in sasview


Ignore:
Timestamp:
Sep 22, 2016 2:59:23 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, release_4.0.1, ticket-1009, ticket-1094-headless, ticket-1242-2d-resolution, ticket-1243, ticket-1249, ticket885, unittest-saveload
Children:
7b15990, 31d7803
Parents:
20a3c55
Message:

Under review. More minor changes.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • src/sas/sasgui/perspectives/fitting/media/plugin.rst

    r3d164b9 r7f23423  
    11.. _Writing_a_Plugin: 
    22 
    3 Writing a Plugin 
    4 ================ 
    5  
    6 Users can write their own models and save it to the the SasView 
     3Writing a Plugin Model 
     4====================== 
     5 
     6Overview 
     7^^^^^^^^ 
     8 
     9You can write your own model and save it to the the SasView 
    710*plugin_models* folder 
    811 
    9   *C:\\Users\\[username]\\.sasview\\plugin_models* - (on Windows) 
     12  *C:\\Users\\[username]\\.sasview\\plugin_models* (on Windows) 
    1013 
    1114The next time SasView is started it will compile the plugin and add 
    12 it to the list of *Customized Models*.  It is recommended that an 
     15it to the list of *Customized Models* in a FitPage.  It is recommended that an 
    1316existing model be used as a template. 
    14  
    15 This page was originally written by our MOST experienced developers, 
    16 but has subsequently been edited by our LEAST experienced developer who felt 
    17 some instructions could have been clearer, and learnt one or two things that 
    18 were missing altogether! But they succeeded in converting a model that passed 
    19 testing, so there is no reason why you should not be able to do the same. 
    2017 
    2118SasView has three ways of writing models: 
     
    2926  `cylinder.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.c>`_ 
    3027 
    31 Many models are available for download from the 
    32 `model marketplace <http://marketplace.sasview.org/>`_. 
    33  
    3428The built-in modules are available in the *sasmodels-data\\models* subdirectory 
    35 of the sasview installation folder.  On Windows, this will be something like 
    36 *C:\\Program Files (x86)\\SasView\\sasmodels-data.  On MacOSX, these will be within 
     29of your SasView installation folder.  On Windows, this will be something like 
     30*C:\\Program Files (x86)\\SasView\\sasmodels-data\\models*.  On Mac OSX, these will be within 
    3731the application bundle as 
    3832*/Applications/SasView 4.0.app/Contents/Resources/sasmodels-data/models*. 
     33 
     34Other models are available for download from our 
     35`Model Marketplace <http://marketplace.sasview.org/>`_. You can contribute your own models to the  
     36Marketplace aswell. 
    3937 
    4038Create New Model Files 
     
    4745*Please follow these naming rules:* 
    4846 
    49 - No capitalization and thus no CamelCase. 
     47- No capitalization and thus no CamelCase 
    5048- If necessary use underscore to separate words (i.e. barbell not BarBell or 
    5149  broad_peak not BroadPeak) 
     
    5654^^^^^^^^^^^^^^^^^^^^ 
    5755 
     56Model Contents 
     57.............. 
     58 
    5859The model interface definition is in the .py file.  This file contains: 
    5960 
     
    6566    - without spaces (use underscores to separate words instead) 
    6667    - without any capitalization or CamelCase 
    67     - without incorporating the word 'model' 
     68    - without incorporating the word "model" 
    6869    - examples: *barbell* **not** *BarBell*; *broad_peak* **not** *BroadPeak*;  
    6970      *barbell* **not** *BarBellModel* 
     
    7273   - this is the **title** string in the *.py* file 
    7374   - this is a one or two line description of the model, which will appear 
    74      at the start of the model documentation and as a tooltip in the GUI 
     75     at the start of the model documentation and as a tooltip in the SasView GUI 
    7576 
    7677- a **short discription**: 
    7778   - this is the **description** string in the *.py* file 
    7879   - this is a medium length description which appears when you click 
    79      *Description* on the model fit page 
     80     *Description* on the model FitPage 
    8081 
    8182- a **parameter table**: 
     
    8586   - this is ReStructuredText enclosed between the r""" and """ delimiters 
    8687     at the top of the *.py* file 
    87    - what you write here is abstracted into the help documentation 
     88   - what you write here is abstracted into the SasView help documentation 
     89   - this is what other users will refer to when they want to know what your model does;  
     90     so please be helpful! 
    8891 
    8992- a **definition** of the model: 
     
    98101 
    99102- a **plot** of the function, with a **figure caption**: 
    100    - this is automatically generated from the default parameters 
     103   - this is automatically generated from your default parameters 
    101104 
    102105- at least one **reference**: 
     
    174177 
    175178The model should include a **formula** written using LaTeX markup. 
    176 The above example uses the *math* command to make a displayed equation.  You 
     179The example above uses the *math* command to make a displayed equation.  You 
    177180can also use *\$formula\$* for an inline formula. This is handy for defining 
    178181the relationship between the model parameters and formula variables, such 
    179182as the phrase "\$r\$ is the radius" used above.  The live demo MathJax 
    180183page `<http://www.mathjax.org/>`_ is handy for checking that the equations 
    181 will look like you expect. 
     184will look like you intend. 
    182185 
    183186Math layout uses the `amsmath <http://www.ams.org/publications/authors/tex/amslatex>`_ 
     
    211214 
    212215    name = "sphere"  # optional: defaults to the filename without .py 
     216 
    213217    title = "Spheres with uniform scattering length density" 
     218 
    214219    description = """\ 
    215220    P(q)=(scale/V)*[3V(sld-sld_solvent)*(sin(qr)-qr cos(qr)) 
     
    220225        sld_solvent: the SLD of the solvent 
    221226    """ 
     227 
    222228    category = "shape:sphere" 
     229 
    223230    single = True   # optional: defaults to True 
     231 
    224232    opencl = False  # optional: defaults to False 
     233 
    225234    structure_factor = False  # optional: defaults to False 
    226235 
     
    233242**title = "short description"** is short description of the model which 
    234243is included after the model name in the automatically generated documentation. 
    235 The title can also be used for a tooltip, for example. 
     244The title can also be used for a tooltip. 
    236245 
    237246**description = """doc string"""** is a longer description of the model. It 
    238 shows up when you press the "Description" button of the SasView fit page. 
     247shows up when you press the "Description" button of the SasView FitPage. 
    239248It should give a brief description of the equation and the parameters 
    240249without the need to read the entire model documentation. The triple quotes 
    241250allow you to write the description over multiple lines. Keep the lines 
    242251short since the GUI will wrap each one separately if they are too long. 
    243 **Make sure the parameter names in the description match the model definition.** 
     252**Make sure the parameter names in the description match the model definition!** 
    244253 
    245254**category = "shape:sphere"** defines where the model will appear in the 
    246255model documentation.  In this example, the model will appear alphabetically 
    247 in the list of spheroid models. 
     256in the list of spheroid models in the *Shape* category. 
    248257 
    249258**single = True** indicates that the model can be run using single 
     
    279288        ["radius",      "Ang",        50, [0, inf],    "volume", "Sphere radius"], 
    280289    ] 
    281     # pylint: disable=bad-whitespace, line-too-long 
    282290 
    283291**parameters = [["name", "units", default, [min,max], "type", "tooltip"],...]** 
    284 defines the parameters form the model. 
    285  
    286 - **the order of the parameters in the definition will be the order of 
    287   the parameters in the user interface and the order of the parameters 
    288   in Iq(), Iqxy() and form_volume().** 
    289  
    290 - **scale and background parameters are implicit to all models, so 
    291   they do not need to be included in the parameter table** 
    292  
    293 - **"name"** is the name of the parameter shown on the fit screen 
     292defines the parameters that form the model. 
     293 
     294**Note: The order of the parameters in the definition will be the order of the  
     295parameters in the user interface and the order of the parameters in Iq(),  
     296Iqxy() and form_volume(). And** *scale* **and** *background* **parameters are  
     297implicit to all models, so they do not need to be included in the parameter table.** 
     298 
     299- **"name"** is the name of the parameter shown on the FitPage. 
    294300 
    295301  - parameter names should follow the mathematical convention; e.g., 
    296     *radius_core* not *core_radius*, or *sld_solvent* not *solvent_sld* 
     302    *radius_core* not *core_radius*, or *sld_solvent* not *solvent_sld*. 
     303 
    297304  - model parameter names should be consistent between different models, 
    298305    so *sld_solvent*, for example, should have exactly the same name 
    299     in every model 
     306    in every model. 
     307 
    300308  - to see all the parameter names currently in use, type the following in the 
    301309    python shell/editor under the Tools menu:: 
     
    305313 
    306314    *re-use* as many as possible!!! 
     315 
    307316  - use "name[n]" for multiplicity parameters, where *n* is the name of 
    308317    the parameter defining the number of shells/layers/segments, etc. 
     
    310319- **"units"** are displayed along with the parameter name 
    311320 
    312   - every parameter should have units; use "None" if there are no units 
     321  - every parameter should have units; use "None" if there are no units. 
     322 
    313323  - **sld's should be given in units of 1e-6/Ang^2, and not simply 
    314324    1/Ang^2 to be consistent with the builtin models.  Adjust your formulas 
    315325    appropriately.** 
     326 
    316327  - fancy units markup is available for some units, including:: 
    317328 
     
    326337      and using negative exponents instead of the / operator, though 
    327338      the unit name should use the / operator for consistency. 
    328     - post a message to the sasview developers list with the changes 
    329  
    330 - **default** is the initial value for the parameter 
     339    - please post a message to the SasView developers mailing list with your changes. 
     340 
     341- **default** is the initial value for the parameter. 
    331342 
    332343  - **the parameter default values are used to auto-generate a plot of 
    333344    the model function in the documentation.** 
    334345 
    335 - **[min, max]** are the lower and upper limits on the parameter 
    336  
    337   - lower and upper limits can be any number, or -inf or inf. 
     346- **[min, max]** are the lower and upper limits on the parameter. 
     347 
     348  - lower and upper limits can be any number, or *-inf* or *inf*. 
     349 
    338350  - the limits will show up as the default limits for the fit making it easy, 
    339351    for example, to force the radius to always be greater than zero. 
    340352 
    341 - **"type"** can be one of: "", "sld", "volume", or "orientation" 
     353- **"type"** can be one of: "", "sld", "volume", or "orientation". 
    342354 
    343355  - "sld" parameters can have magnetic moments when fitting magnetic models; 
    344356    depending on the spin polarization of the beam and the $q$ value being 
    345357    examined, the effective sld for that material will be used to compute the 
    346     scattered intensity 
     358    scattered intensity. 
     359 
    347360  - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and 
    348361    have polydispersity loops generated automatically. 
     362 
    349363  - "orientation" parameters are only passed to Iqxy(), and have angular 
    350364    dispersion. 
     
    384398............. 
    385399 
    386 For pure python models, define the Iq funtion:: 
     400For pure python models, define the *Iq* function:: 
    387401 
    388402      import numpy as np 
     
    395409The parameters *par1, par2, ...* are the list of non-orientation parameters 
    396410to the model in the order that they appear in the parameter table. 
    397 **Note that the autogenerated model file uses *x* rather than *q*.** 
     411**Note that the autogenerated model file uses** *x* **rather than** *q*. 
    398412 
    399413The *.py* file should import trigonometric and exponential functions from 
    400 numpy rather that from math.  This lets us evaluate the model for the whole 
     414numpy rather than from math.  This lets us evaluate the model for the whole 
    401415range of $q$ values at once rather than looping over each $q$ separately in 
    402416python.  With $q$ as a vector, you cannot use if statements, but must instead 
     
    434448list includes the *volume* parameters in order.  This is used for a weighted 
    435449volume normalization so that scattering is on an absolute scale.  If 
    436 *form_volume* is not definded, then the default *form_volume = 1.0* will be 
     450*form_volume* is not defined, then the default *form_volume = 1.0* will be 
    437451used. 
    438452 
     
    440454................. 
    441455 
    442 Like pure python models, inline C models need define an *Iq* function:: 
     456Like pure python models, inline C models need to define an *Iq* function:: 
    443457 
    444458    Iq = """ 
     
    520534These functions have been tuned to be fast and numerically stable down 
    521535to $q=0$ even in single precision.  In some cases they work around bugs 
    522 which appear on some platforms but not others. 
     536which appear on some platforms but not others. So use them where needed!!! 
    523537 
    524538Models are defined using double precision declarations for the 
    525539parameters and return values.  Declarations and constants will be converted 
    526540to float or long double depending on the precision requested. 
     541 
    527542**Floating point constants must include the decimal point.**  This allows us 
    528543to convert values such as 1.0 (double precision) to 1.0f (single precision) 
     
    544559 
    545560A value defined as SAS_DOUBLE will stay double precision; this should 
    546 not be used since some graphics card don't support double precision. 
     561not be used since some graphics cards do not support double precision. 
    547562 
    548563 
     
    766781consider adding your model to the 
    767782`model marketplace <http://marketplace.sasview.org/>`_. 
    768  
Note: See TracChangeset for help on using the changeset viewer.