Skip to content

Documentation Checks

Jump to bottom
Ricardo Ferraz Leal edited this page Mar 31, 2019 · 10 revisions

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:

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_parallelepipedYYYYYYYYYRKH 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 YYYYYYYYYRKH Lorentz lorentz YYYYYYYYYRKH MassFractalModel mass_fractal YYYYYYYY.RKH MassSurfaceFractal mass_surface_fractalYYYYYYYY.RKH MicelleSphCore polymer_micelleYYYxxxYYxRKH - needs investigation MultiShellModel multi_shell .......... ParallelepipedModel parallelepiped YYYYYYYY.RKH PeakLorentzModel peak_lorentz YYYYYYYY.RKH PearlNecklaceModel pearl_necklace YYYYYYYY.RKH PolyExclVolume polymer_excl_volumeYYYYYYYY.RKH 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 YYYYYYYYYRKH StarPolymer star_polymer YYYYYYYY.RKH issues at extreme low Q StickyHSStructure stickyhardsphere YYYYn/aY.Yn/aRKH SurfaceFractalModel surface_fractal YYYYYYYY.RKH TeubnerStrey teubner_strey .......... TriaxialEllipsoidModel triaxial_ellipsoid YYYYYYYY.RKH check linked fig TwoLorentzian two_lorentzian YYYYYYYYYPDB TwoPowerLaw two_power_law YYYYYYYYYPDB VesicleModel vesicle YYYYYYYYYPDB BinaryHSModel binary_hard_sphere YYYY*YYYYPDB Core2ndMomentModel adsorbed_layer YYYYYYYYYSMK CoreMultiShellModel core_multi_shell YYYY...... Debye mono_gauss_coil YYYYYYYYYSMK FractalModel fractal YYYYYYYYYPDB MultiplicationModel ..... .... OnionExpShellModel .......... Poly_GaussCoil poly_gauss_coil YYYYYYYYYSMK PringleModel pringle YYYYYYYYYPDB RaspBerryModel raspberry YYYYYYYYYAJJ ReflectivityModel .......... ReflectivityIIModel .......... RPA10Model rpa [unfinished] .......... 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.

Clone this wiki locally