Model Documentation Checks

All models added to SasView need to be properly documented. This means there should be (in order):

a model name:

• this is the name string in the .py file

• titles should be:
  • all in lower case
  • without spaces (use underscores to separate words instead)
  • without any capitalization or CamelCase
  • without incorporating the word 'model'
  • examples: barbell not BarBell; broad_peak not BroadPeak; barbell not BarBellModel

a short description:

• this is the title string in the .py file

• the .py file also contains a description string: this becomes a tooltip in the GUI

a model parameter table:

• this will be auto-generated from the parameters in the .py file

• model parameter names should be consistent between different models, so solvent_sld, for example, should have exactly the same name in every model
• scale and background are implicit to all models, they do not need to be added separately

• new parameter names:
  • radius = radius
  • sld = scattering length density of particle
  • solvent_sld = scattering length density of matrix
  • regiona_sld = scattering length density of region a for a multi component model with several slds
  • cor_length = correlation length
  • exp = an exponent
  • peak_pos = q_peak or q0, etc
  • theta = axis_theta
  • phi = axis_phi
  • vol_frac = volume fraction of particle
  • etc

• every parameter should have units (or the word None)
• units should be properly formatted; ie, using sub-/super-scripts and using negative exponents rather than / operators
• fancy units markup are contained in the variable RST_UNITS in sasmodels/generate.py
• if necessary, add new units to RST_UNITS, use the macros defined in doc/rst_prolog, or add your own

• every parameter must have a default value

a long description:

• this is the RST text enclosed between the r""" and """ delimiters in the .py file

a definition of the model:

• as part of the long description

a formula defining the function the model calculates:

• as part of the long description

• images of math functions should be replaced with Latex equivalents:
  • use the live demo Mathjax page ( ​http://www.mathjax.org/) to make sure the equation looks as expected
  • or copy the Latex code from Paul Kienzle's document ( ​http://sasview.org/attachment/wiki/SasModels%20Work%20Package/Equations.docx.pdf)

an explanation of the parameters:

• as part of the long description
• explaining how the symbols in the formula map to the model parameters

a plot of the function

• using the default parameters

a figure caption:

• as part of the long description
• the figure number is auto-generated

at least one reference:

• as part of the long description
• specifying where the reader can obtain more information about the model

the name of the author

• as part of the long description

• the .py file should also contain a comment identifying who converted/created the model file