Changes between Version 10 and Version 11 of ModelConvInst


Ignore:
Timestamp:
Nov 19, 2015 8:49:18 AM (8 years ago)
Author:
pkienzle
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • ModelConvInst

    v10 v11  
    11'''Introduction''' 
    22 
    3 In the new sasmodels package there are three ways of writing models: 
     3In the new sasmodels package [https://gihub.com/SasView/sasmodels] there are three ways of writing models: 
    44- As a pure python model : Example - [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/broad_peak.py broadpeak.py] 
    55- As a python model with embedded C : Example - [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/sphere.py sphere.py] 
     
    1919'''EDIT NEW MODEL FILES''' 
    2020 
    21 Cut and paste appropriate sections from old model into new sasmodels in appropriate places.  Fill out all required sections. Most of the magic is done in the python file.  Only the computation section (mainly the Iq method etc) will be either in the python file or the c file as described in the computation section below. 
    22 - First lengthy docstring starts with an r (for raw) and three sets of quotes to start the doc string and ends with a second set of 3 quotes.  This is where the FULL documentation for the model goes (to be picked up by sphinx). Paste the model documentation from the appropriate section of model_functions.rst (found at [https://github.com/SasView/sasview/blob/master/src/sas/models/media/model_functions.rst src/sas/models/media/model_functions.rst]) here.  For example, for the !BarBellModel, search for !BarBellModel in the rst file then copy everything after the *2.x.x. !ModelNameModel. Edit the result as follows: 
    23  - replace *2.x.x.x. Definition !** with Definition followed by a line of 10 dashes. 
     21The model interface definition is in the .py file.  This file contains: 
     22- model documentation.  The .py starts with an r (for raw) and three sets of quotes to start the doc string and ends with a second set of 3 quotes.  This is where the FULL documentation for the model goes (to be picked up by sphinx). Paste the model documentation from the appropriate section of model_functions.rst (found at [https://github.com/SasView/sasview/blob/master/src/sas/models/media/model_functions.rst src/sas/models/media/model_functions.rst]) here.  For example, for the !BarBellModel, search for !BarBellModel in the rst file then copy everything after the *2.x.x. !ModelNameModel!**. Edit the result as follows: 
     23 - the *2.x.x.x Model!** section with its brief description of the model becomes the model title; it feels odd that the documentation string does not start with name and brief description but it is automatically added by the model loader 
     24 - replace *2.x.x.x. Definition!** with Definition followed by a line of 10 dashes. 
    2425 - wherever possible try to replace images of math functions with Latex. you can use the live demo Mathjax page (http://www.mathjax.org/) to make sure the equation looks as expected.  also a lot of the Latex code can be taken from (or edited) from the PDF document created by Paul Kienzle: http://sasview.org/attachment/wiki/SasModels%20Work%20Package/Equations.docx.pdf.  
    2526 - remove the table of parameters which will get autogenerated  
    26 - name = mymodel.  Use the name of the file as described above in 1. 
    27 - title is a short tool tip description of the model.  This is a new value to be used for tooltip for example. Make-up something appropriate but short (one line). 
    28 - description doc string.  Cut and paste the self.description string from the !SasView model header in [https://github.com/SasView/sasview/tree/master/src/sas/models/include srs/sas/models/include].  This gives a brief description of the equation and the parameters without the need to read the entire model documentation. 
    29 - parameters. This is where the parameters get defined.  The syntax should be obvious from the default.  Copy the parameters from the model header file [https://github.com/SasView/sasview/tree/master/src/sas/models/include srs/sas/models/include] 
    30 - PARAMETER NAMES:  VERY IMPORTANT.  We are trying to make the model parameter more consistent between models.  So solvent sld for example should have exactly the same name in every model.  Current list of new parameters is: 
    31  - radius = radius 
    32  - sld = scattering length density of particle 
    33  - solvent_sld = scattering length density of matrix 
    34  - cor_length = correlation length 
    35  - exp = exponent (example: porod_exp) 
    36  - peak_pos = q_peak or q0 etc 
    37 - lower and upper limits can be any number or -inf or inf 
     27 - copy the figures from the sasview/src/sas/models/media/img subdirectory to the sasmodels/sasmodels/models/img subdirectory 
     28 - figure captions should be indented relative to the ..image:: tag.  This allows us to for example change the font of the caption through CSS.  
     29 - remove the figure number since this will be generated automatically for the caption. 
     30 - make sure all references to model parameters are appropriately renamed, and that the relationship between equation variables and model parameters are obvious. 
     31- name = "mymodel".  This is the name of the model that is shown to the user.  Use the name of the file as described above in 1. There will be less confusion if the model name matches the file name, but they could be different. 
     32- title = "short description".  This is a new value to be used for tooltip for example.  It can probably be pulled directly from the model_functions.rst file. 
     33- description = """doc string""".  Cut and paste the self.description string from the !SasView model header in [https://github.com/SasView/sasview/tree/master/src/sas/models/include srs/sas/models/include].  This gives a brief description of the equation and the parameters without the need to read the entire model documentation.  Make sure the parameter names match the current model definition. 
     34- parameters = [["name", "units", default, [min,max], "type", "tooltip"],...]. This is where the parameters get defined.  The syntax should be obvious from the default.  Copy the parameters from the model header file [https://github.com/SasView/sasview/tree/master/src/sas/models/include srs/sas/models/include] 
     35 - PARAMETER NAMES:  VERY IMPORTANT.  We are trying to make the model parameter more consistent between models.  So solvent sld for example should have exactly the same name in every model.  Current list of new parameters is: 
     36  - radius = radius 
     37  - sld = scattering length density of particle 
     38  - solvent_sld = scattering length density of matrix 
     39  - cor_length = correlation length 
     40  - exp = exponent (example: porod_exp) 
     41  - peak_pos = q_peak or q0 etc 
     42  - theta = axis_theta, phi = axis_phi 
     43  - add more as you see them 
     44 - lower and upper limits can be any number or -inf or inf 
    3845  - add limits where required; the sasview models don't usually define them 
    3946  - the limits will show up as the default limits for the fit, making it easy for example to force the radius to always be greater than zero. 
    40 - type can take 3 values at this time: “”, “volume”, or “orientation” 
     47 - type can take 3 values at this time: “”, “volume”, or “orientation” 
     48  - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and have polydispersity loops generated automatically 
     49  - "orientation" parameters are only passed to Iqxy(). 
     50 - the order of the parameters in the definition will be the order of the parameters in the user interface and the order of the parameters in Iq(), Iqxy() and form_volume(). 
    4151- COMPUTATION 
    4252 - Pure Python 
    4353  - def Iq (this section does not exist for c models.  It is replaced by the list of c files to call) 
     54   - Iq.vectorized = True or False. This is used to tag the definition as accepting a Q vector, or having to compute each Q individually. 
     55    - use functions from numpy rather than math 
     56    - don't use if statements.  Instead do tricks like "a = x*(q>0) + y*(q<=0)" which sets a to x if q is positive or y if q is zero  
    4457  - def Iqxy.  If this model does not have an oriented form just set it equal to the square root of the sum of Iq(x) squared and Iq(y) squared. 
    4558  - [https://github.com/SasView/sasview/tree/master/src/sas/models src/sas/models] contains the pure python models, mixed together with the python + C models.  
     
    5366      source = ["lib/J1.c", "lib/gauss76.c", "my_model.c"] 
    5467  }}} 
    55   - the c file must contain the Iq and Iqxy methods.  These and any other functions defined (e.g. form_volume, radius, etc) must be defined as doubles in the first lines of the file. 
     68  - the c file must contain the form_volume, Iq, Iqxy methods.  These and any other functions defined (e.g. the _cyl() helper function) must be defined as doubles in the first lines of the file. 
    5669- For certain models, such as those that can be multiplied by a structure factor, the ER attribute should be set to the Equivalent Radius (of a sphere). 
    5770- For certain models, namely core shell type models, the VR attribute returns the volume ratio for the core-shell. 
    5871- demo is a dictionary containing the value of each parameter as given in the rst documentation.  Make sure to enter the appropriate values from that documentation.  This will then be used to generate the example curve in said documentation. 
     72 - include polydispersity parameters (e.g., radius_pd=0.2, radius_pd_n=9) so that you can compare the polydispersity calculations against those from sasview; use -mono on the compare.sh command line to see the direct calculation without polydispersity. 
    5973- oldname is the name for this model used in !SasView.  Make sure to put the correct original name.  This is required for the transition to allow compatibility and to test that the models are equivalent. 
    6074- oldpars is the name of the parameters as used in !SasView.  For each parameter give the name of the parameter as used in the original !SasView code version of this model.  Again this is required for the transition.