| | 3 | All models added to !SasView need to be properly documented. This means there should be (in order): |
| | 4 | |
| | 5 | a '''model name''': |
| | 6 | - this is the ''name'' string in the ''.py'' file |
| | 7 | |
| | 8 | - titles should be: |
| | 9 | - all in ''lower'' case |
| | 10 | - without spaces (use underscores to separate words instead) |
| | 11 | - without any capitalization or !CamelCase |
| | 12 | - without incorporating the word 'model' |
| | 13 | - examples: ''barbell'' '''not''' ''!BarBell''; ''broad_peak'' '''not''' ''!BroadPeak''; ''barbell'' '''not''' ''!BarBellModel'' |
| | 14 | |
| | 15 | a '''short description''': |
| | 16 | - this is the ''title'' string in the ''.py'' file |
| | 17 | |
| | 18 | - the ''.py'' file also contains a ''description'' string: this becomes a tooltip in the GUI |
| | 19 | |
| | 20 | a model '''parameter table''': |
| | 21 | - this will be auto-generated from the ''parameters'' in the ''.py'' file |
| | 22 | |
| | 23 | - model parameter names should be consistent between different models, so ''solvent_sld'', for example, should have exactly the same name in every model |
| | 24 | - ''scale'' and ''background'' are implicit to all models, they do not need to be added separately |
| | 25 | |
| | 26 | - new parameter names: |
| | 27 | - radius = radius |
| | 28 | - sld = scattering length density of particle |
| | 29 | - solvent_sld = scattering length density of matrix |
| | 30 | - regiona_sld = scattering length density of region a for a multi component model with several slds |
| | 31 | - cor_length = correlation length |
| | 32 | - exp = an exponent |
| | 33 | - peak_pos = q_peak or q0, etc |
| | 34 | - theta = axis_theta |
| | 35 | - phi = axis_phi |
| | 36 | - vol_frac = volume fraction of particle |
| | 37 | - etc |
| | 38 | |
| | 39 | - every parameter should have units (or the word ''None'') |
| | 40 | - units should be properly formatted; ie, using sub-/super-scripts and using negative exponents rather than / operators |
| | 41 | - fancy units markup are contained in the variable RST_UNITS in sasmodels/generate.py |
| | 42 | - if necessary, add new units to RST_UNITS, use the macros defined in doc/rst_prolog, or add your own |
| | 43 | |
| | 44 | - every parameter must have a default value |
| | 45 | |
| | 46 | a '''long description''': |
| | 47 | - this is the RST text enclosed between the r""" and """ delimiters in the ''.py'' file |
| | 48 | |
| | 49 | a '''definition''' of the model: |
| | 50 | - as part of the '''long description''' |
| | 51 | |
| | 52 | a '''formula''' defining the function the model calculates: |
| | 53 | - as part of the '''long description''' |
| | 54 | |
| | 55 | - images of math functions should be replaced with Latex equivalents: |
| | 56 | - use the live demo Mathjax page ( http://www.mathjax.org/) to make sure the equation looks as expected |
| | 57 | - or copy the Latex code from Paul Kienzle's document ( http://sasview.org/attachment/wiki/SasModels%20Work%20Package/Equations.docx.pdf) |
| | 58 | |
| | 59 | an '''explanation of the parameters''': |
| | 60 | - as part of the '''long description''' |
| | 61 | - explaining how the symbols in the formula map to the model parameters |
| | 62 | |
| | 63 | a '''plot''' of the function |
| | 64 | - using the default parameters |
| | 65 | |
| | 66 | a '''figure caption''': |
| | 67 | - as part of the '''long description''' |
| | 68 | - the figure number is auto-generated |
| | 69 | |
| | 70 | at least one '''reference''': |
| | 71 | - as part of the '''long description''' |
| | 72 | - specifying where the reader can obtain more information about the model |
| | 73 | |
| | 74 | the '''name of the author'' |
| | 75 | - as part of the '''long description''' |
| | 76 | |
| | 77 | - the ''.py'' file should also contain a comment identifying ''who'' converted/created the model file |
