Version 38 (modified by richardh, 8 years ago) (diff)

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: this becomes a tooltip in the GUI
  • the .py file also contains a description string: this becomes the short description of the model in the GUI

a model parameter table:

  • this will be auto-generated from the parameters in the .py file
  • scale and background are implicit to all models, they do not need to be added separately
  • parameter names should follow the mathematical convention; eg, radius_core not core_radius, or sld_solvent not solvent_sld
  • use python -m sasmodels.list_pars to see all the parameter names currently in use: re-use as many as possible!!!
  • model parameter names should be consistent between different models, so sld_solvent, for example, should have exactly the same name in every model
  • 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

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

This table indicates the status of documentation compliance with the above rules (Y = compliant / . = status pending):

SasView namesasmodels name short_desc param_table long_desc definition formula param_desc plot ref attribution Assigned
HayterMSAStructure hayter_msa YYYYn/aY.Yn/aRKH
BarBellModel barbell YYYYYYYYYRKH
BCCrystalModel bcc_paracrystal YYYYYYYYYRKH
BEPolyelectrolyte be_polyelectrolyte YxYYYYYY.RKHinvestigate contrast factor
BroadPeakModel broad_peak YYYYYYYn/an/aRKH
CappedCylinderModel capped_cylinder YYYYYYYYYRKH
CoreShellBicelleModel core_shell_bicelle YYYYYYYYYRKH
CoreShellCylinderModel core_shell_cylinderYYYYn/aY.Yn/aRKH
CoreShellEllipsoidModelcore_shell_ellipsoidYYYYYY.Yn/aRKH
CoreShellEllipsoidXTModelcore_shell_ellipsoid_xtYYYYYY.Yn/aRKH
CoreShellModel core_shell_sphere YYYYYYYYYRKH
CorrLength correlation_length YYYYYYYY.RKH
CSParallelepipedModel core_shell_parallelepiped.........RKH
CylinderModel cylinder YYYYn/aY.n/an/aRKH
DABModel dab YYYYYYYYYRKH
EllipsoidModel ellipsoid YYYYYYYYYRKH
EllipticalCylinderModel elliptical_cylinderYYYYYYYYYRKH
FCCrystalModel fcc_paracrystal YYYYYYYYYRKH
FlexibleCylinderModel flexible_cylinder YYYYYYYYYRKH
FlexCylEllipXModel flexible_cylinder_ellipticalYYYYYYYYYRKH
FractalCoreShell fractal_core_shell YYYYYYYYYRKH
FuzzySphereModel fuzzy_sphere YYYYYYYY.RKH
PeakGaussModel gaussian_peak YYYYYYn/aY.RKH
GaussLorentzGel gauss_lorentz_gel YYYYYYYY.RKH
GelFitModel gel_fit YYYYYYYY.RKH
Guinier guinier YYYYYYYY.RKH
GuinierPorod guinier_porod YYYYYYYY.RKH
HardsphereStructure hardsphere YYYYn/aY.Yn/aRKH
HollowCylinderModel hollow_cylinder YYYYn/aY.Yn/aRKH
LamellarModel lamellar YYYYYY.Yn/aRKH
LamellarPSModel lamellar_stack_caille YYYYYY.Yn/aRKH
LamellarPSHGModel lamellar_hg_stack_caille YYYYYY.Yn/aRKH
LamellarFFHGModel lamellar_hg YYYYYY.Yn/aRKH
LamellarPCrystallModel lamellar_stack_paracrystal YYYYYY.Yn/aRKH
LineModel line YYYYYYYn/an/aRKH
LinearPearlsModel linear_pearls ..........
Lorentz lorentz ..........
MassFractalModel mass_fractal .........RKH
MassSurfaceFractal mass_surface_fractal.........RKH
MicelleSphCore polymer_micelleYYYxxxYYxRKH - needs investigation
MultiShellModel multi_shell ..........
ParallelepipedModel parallelepiped YYYYYYYY.RKH
PeakLorentzModel peak_lorentz ..........
PearlNecklaceModel pearl_necklace ..........
PolyExclVolume polymer_excl_volume..........
PorodModel porod YYYYYYYn/aYRKH
!AbsolutePower_Law power_law YYYYYYYxYRKH
RectangularPrismModel rectangular_prism YYYYYYYY.RKH
RectangularHollowPrismModelhollow_rectangular_prismYYYYYYYY.RKH
RectangularHollowPrismInfThinWallsModelhollow_rectangular_prism_thin_walls YYYYYYYY.RKH
SCCrystalModel sc_paracrystal YYYYYYYYYRKH
SphereModel sphere YYYYYYYY.RKH
StackedDisksModel stacked_disk ..........
StarPolymer star_polymer ..........
StickyHSStructure stickyhardsphere YYYYn/aY.Yn/aRKH
SurfaceFractalModel surface_fractal .........RKH
TeubnerStrey teubner_strey ..........
TriaxialEllipsoidModel triaxial_ellipsoid YYYYYYYY.RKH check linked fig
TwoLorentzian two_lorentzian ..........
TwoPowerLaw two_power_law ..........
VesicleModel vesicle YYYYYYYYYPDB
BinaryHSModel binary_hard_sphere YYYY*YYYYPDB
Core2ndMomentModel adsorbed_layer YYYYYYYYYSMK
CoreMultiShellModel ..........
Debye mono_gauss_coil YYYYYYYYYSMK
FractalModel fractal YYYYYYYYYPDB
MultiplicationModel ..... ....
OnionExpShellModel ..........
Poly_GaussCoil poly_gauss_coil YYYYYYYYYSMK
PringleModel ..........
RaspBerryModel raspberry YYYYYYYYYAJJ
ReflectivityModel ..........
ReflectivityIIModel ..........
RPA10Model rpa [unfinished] .........RKH
SphericalSLDModel ..........
SquareWellStructure squarewell YYYYn/aY.Yn/aRKH
UnifiedPowerRg ..........
sum_p1_p2 ..........
sum_Ap1_1_Ap2 ..........
polynomial5 ..........
sph_bessel_jn ..........
testmodel ..........
testmodel_2 ..........
  • = code not completely verified against equations in paper. Doc equations verified.