- Timestamp:
- Sep 22, 2016 4:59:23 PM (8 years ago)
- 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
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
src/sas/sasgui/perspectives/fitting/media/plugin.rst
r3d164b9 r7f23423 1 1 .. _Writing_a_Plugin: 2 2 3 Writing a Plugin 4 ================ 5 6 Users can write their own models and save it to the the SasView 3 Writing a Plugin Model 4 ====================== 5 6 Overview 7 ^^^^^^^^ 8 9 You can write your own model and save it to the the SasView 7 10 *plugin_models* folder 8 11 9 *C:\\Users\\[username]\\.sasview\\plugin_models* -(on Windows)12 *C:\\Users\\[username]\\.sasview\\plugin_models* (on Windows) 10 13 11 14 The next time SasView is started it will compile the plugin and add 12 it to the list of *Customized Models* . It is recommended that an15 it to the list of *Customized Models* in a FitPage. It is recommended that an 13 16 existing 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 felt17 some instructions could have been clearer, and learnt one or two things that18 were missing altogether! But they succeeded in converting a model that passed19 testing, so there is no reason why you should not be able to do the same.20 17 21 18 SasView has three ways of writing models: … … 29 26 `cylinder.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.c>`_ 30 27 31 Many models are available for download from the32 `model marketplace <http://marketplace.sasview.org/>`_.33 34 28 The built-in modules are available in the *sasmodels-data\\models* subdirectory 35 of the sasview installation folder. On Windows, this will be something like36 *C:\\Program Files (x86)\\SasView\\sasmodels-data . On MacOSX, these will be within29 of 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 37 31 the application bundle as 38 32 */Applications/SasView 4.0.app/Contents/Resources/sasmodels-data/models*. 33 34 Other models are available for download from our 35 `Model Marketplace <http://marketplace.sasview.org/>`_. You can contribute your own models to the 36 Marketplace aswell. 39 37 40 38 Create New Model Files … … 47 45 *Please follow these naming rules:* 48 46 49 - No capitalization and thus no CamelCase .47 - No capitalization and thus no CamelCase 50 48 - If necessary use underscore to separate words (i.e. barbell not BarBell or 51 49 broad_peak not BroadPeak) … … 56 54 ^^^^^^^^^^^^^^^^^^^^ 57 55 56 Model Contents 57 .............. 58 58 59 The model interface definition is in the .py file. This file contains: 59 60 … … 65 66 - without spaces (use underscores to separate words instead) 66 67 - without any capitalization or CamelCase 67 - without incorporating the word 'model'68 - without incorporating the word "model" 68 69 - examples: *barbell* **not** *BarBell*; *broad_peak* **not** *BroadPeak*; 69 70 *barbell* **not** *BarBellModel* … … 72 73 - this is the **title** string in the *.py* file 73 74 - 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 GUI75 at the start of the model documentation and as a tooltip in the SasView GUI 75 76 76 77 - a **short discription**: 77 78 - this is the **description** string in the *.py* file 78 79 - this is a medium length description which appears when you click 79 *Description* on the model fit page80 *Description* on the model FitPage 80 81 81 82 - a **parameter table**: … … 85 86 - this is ReStructuredText enclosed between the r""" and """ delimiters 86 87 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! 88 91 89 92 - a **definition** of the model: … … 98 101 99 102 - a **plot** of the function, with a **figure caption**: 100 - this is automatically generated from thedefault parameters103 - this is automatically generated from your default parameters 101 104 102 105 - at least one **reference**: … … 174 177 175 178 The model should include a **formula** written using LaTeX markup. 176 The above example uses the *math* command to make a displayed equation. You179 The example above uses the *math* command to make a displayed equation. You 177 180 can also use *\$formula\$* for an inline formula. This is handy for defining 178 181 the relationship between the model parameters and formula variables, such 179 182 as the phrase "\$r\$ is the radius" used above. The live demo MathJax 180 183 page `<http://www.mathjax.org/>`_ is handy for checking that the equations 181 will look like you expect.184 will look like you intend. 182 185 183 186 Math layout uses the `amsmath <http://www.ams.org/publications/authors/tex/amslatex>`_ … … 211 214 212 215 name = "sphere" # optional: defaults to the filename without .py 216 213 217 title = "Spheres with uniform scattering length density" 218 214 219 description = """\ 215 220 P(q)=(scale/V)*[3V(sld-sld_solvent)*(sin(qr)-qr cos(qr)) … … 220 225 sld_solvent: the SLD of the solvent 221 226 """ 227 222 228 category = "shape:sphere" 229 223 230 single = True # optional: defaults to True 231 224 232 opencl = False # optional: defaults to False 233 225 234 structure_factor = False # optional: defaults to False 226 235 … … 233 242 **title = "short description"** is short description of the model which 234 243 is included after the model name in the automatically generated documentation. 235 The title can also be used for a tooltip , for example.244 The title can also be used for a tooltip. 236 245 237 246 **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.247 shows up when you press the "Description" button of the SasView FitPage. 239 248 It should give a brief description of the equation and the parameters 240 249 without the need to read the entire model documentation. The triple quotes 241 250 allow you to write the description over multiple lines. Keep the lines 242 251 short 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!** 244 253 245 254 **category = "shape:sphere"** defines where the model will appear in the 246 255 model documentation. In this example, the model will appear alphabetically 247 in the list of spheroid models .256 in the list of spheroid models in the *Shape* category. 248 257 249 258 **single = True** indicates that the model can be run using single … … 279 288 ["radius", "Ang", 50, [0, inf], "volume", "Sphere radius"], 280 289 ] 281 # pylint: disable=bad-whitespace, line-too-long282 290 283 291 **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 292 defines the parameters that form the model. 293 294 **Note: The order of the parameters in the definition will be the order of the 295 parameters in the user interface and the order of the parameters in Iq(), 296 Iqxy() and form_volume(). And** *scale* **and** *background* **parameters are 297 implicit 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. 294 300 295 301 - 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 297 304 - model parameter names should be consistent between different models, 298 305 so *sld_solvent*, for example, should have exactly the same name 299 in every model 306 in every model. 307 300 308 - to see all the parameter names currently in use, type the following in the 301 309 python shell/editor under the Tools menu:: … … 305 313 306 314 *re-use* as many as possible!!! 315 307 316 - use "name[n]" for multiplicity parameters, where *n* is the name of 308 317 the parameter defining the number of shells/layers/segments, etc. … … 310 319 - **"units"** are displayed along with the parameter name 311 320 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 313 323 - **sld's should be given in units of 1e-6/Ang^2, and not simply 314 324 1/Ang^2 to be consistent with the builtin models. Adjust your formulas 315 325 appropriately.** 326 316 327 - fancy units markup is available for some units, including:: 317 328 … … 326 337 and using negative exponents instead of the / operator, though 327 338 the unit name should use the / operator for consistency. 328 - p ost a message to the sasview developers list with the changes329 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. 331 342 332 343 - **the parameter default values are used to auto-generate a plot of 333 344 the model function in the documentation.** 334 345 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 338 350 - the limits will show up as the default limits for the fit making it easy, 339 351 for example, to force the radius to always be greater than zero. 340 352 341 - **"type"** can be one of: "", "sld", "volume", or "orientation" 353 - **"type"** can be one of: "", "sld", "volume", or "orientation". 342 354 343 355 - "sld" parameters can have magnetic moments when fitting magnetic models; 344 356 depending on the spin polarization of the beam and the $q$ value being 345 357 examined, the effective sld for that material will be used to compute the 346 scattered intensity 358 scattered intensity. 359 347 360 - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and 348 361 have polydispersity loops generated automatically. 362 349 363 - "orientation" parameters are only passed to Iqxy(), and have angular 350 364 dispersion. … … 384 398 ............. 385 399 386 For pure python models, define the Iq funtion::400 For pure python models, define the *Iq* function:: 387 401 388 402 import numpy as np … … 395 409 The parameters *par1, par2, ...* are the list of non-orientation parameters 396 410 to 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*. 398 412 399 413 The *.py* file should import trigonometric and exponential functions from 400 numpy rather tha tfrom math. This lets us evaluate the model for the whole414 numpy rather than from math. This lets us evaluate the model for the whole 401 415 range of $q$ values at once rather than looping over each $q$ separately in 402 416 python. With $q$ as a vector, you cannot use if statements, but must instead … … 434 448 list includes the *volume* parameters in order. This is used for a weighted 435 449 volume normalization so that scattering is on an absolute scale. If 436 *form_volume* is not defin ded, then the default *form_volume = 1.0* will be450 *form_volume* is not defined, then the default *form_volume = 1.0* will be 437 451 used. 438 452 … … 440 454 ................. 441 455 442 Like pure python models, inline C models need define an *Iq* function::456 Like pure python models, inline C models need to define an *Iq* function:: 443 457 444 458 Iq = """ … … 520 534 These functions have been tuned to be fast and numerically stable down 521 535 to $q=0$ even in single precision. In some cases they work around bugs 522 which appear on some platforms but not others. 536 which appear on some platforms but not others. So use them where needed!!! 523 537 524 538 Models are defined using double precision declarations for the 525 539 parameters and return values. Declarations and constants will be converted 526 540 to float or long double depending on the precision requested. 541 527 542 **Floating point constants must include the decimal point.** This allows us 528 543 to convert values such as 1.0 (double precision) to 1.0f (single precision) … … 544 559 545 560 A value defined as SAS_DOUBLE will stay double precision; this should 546 not be used since some graphics card don't support double precision.561 not be used since some graphics cards do not support double precision. 547 562 548 563 … … 766 781 consider adding your model to the 767 782 `model marketplace <http://marketplace.sasview.org/>`_. 768
Note: See TracChangeset
for help on using the changeset viewer.