Changes between Version 15 and Version 16 of ModelConvInst


Ignore:
Timestamp:
Nov 20, 2015 12:22:43 PM (9 years ago)
Author:
smk78
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • ModelConvInst

    v15 v16  
    1 '''Introduction''' 
     1'''INTRODUCTION''' 
    22 
    3 In the new sasmodels package [https://github.com/SasView/sasmodels] there are three ways of writing models: 
     3''This wiki page was originally written by our MOST experienced developers, but has subsequently been edited by our LEAST experienced developer who felt some instructions could have been clearer, and learnt one or two things that were missing altogether! But they succeeded in converting a model that passed testing, so there is no reason why should not be able to do the same.''  
     4 
     5In the new sasmodels package there are three ways of writing models: 
    46- As a pure python model : Example - [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/broad_peak.py broadpeak.py] 
    57- As a python model with embedded C : Example - [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/sphere.py sphere.py] 
    68- As a python wrapper with separate C code : Example - [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.py cylinder.py], [https://github.com/SasView/sasmodels/blob/master/sasmodels/models/cylinder.c cylinder.c] 
    79 
    8 The documentation for the sasmodels package can be found at http://www.sasview.org/sasmodels/ 
     10The documentation for the sasmodels package can be found at [http://www.sasview.org/sasmodels/] 
    911 
    10 Before following the conversion instructions below, it is worth reading the documentation at http://www.sasview.org/sasmodels/api/generate.html#module-sasmodels.generate which describes the structure of a model. 
     12Before following the conversion instructions below, it is worth reading the documentation at [http://www.sasview.org/sasmodels/api/generate.html#module-sasmodels.generate] which describes the structure of a model. 
    1113 
    1214'''CREATE NEW MODEL FILES'''. 
    1315 
    14 If you have not already done so, download the sasmodels package from [https://github.com/sasview/sasmodels]. 
     16If you have not already done so, download the sasmodels package from the repo at [https://github.com/SasView/sasmodels]. 
    1517 
    16 In the sasmodels/models directory, copy the appropriate files using the examples above to mymodel.py and mymodel.c as required where “mymodel’ is the NEW name for the model to be moved. Please follow new naming rules:  
     18In the sasmodels/models directory, copy the appropriate files (using the examples above as templates) to mymodel.py (and mymodel.c, etc) as required, where "mymodel" is the NEW name for the model you are converting/creating. ''Please follow these new naming rules:'' 
    1719- No capitalization and thus no !CamelCase.  If necessary use underscore to separate (i.e. barbell not !BarBell or broad_peak not !BroadPeak) 
    1820- Remove “model” from the name (i.e. barbell not !BarBellModel) 
     
    2224 
    2325The model interface definition is in the .py file.  This file contains: 
    24 - 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: 
    25  - 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 
    26  - replace *2.x.x.x. Definition!** with Definition followed by a line of 10 dashes. 
    27  - 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.  
    28  - remove the table of parameters which will get autogenerated  
    29  - copy the figures from the sasview/src/sas/models/media/img subdirectory to the sasmodels/sasmodels/models/img subdirectory 
    30  - figure captions should be indented relative to the ..image:: tag.  This allows us to for example change the font of the caption through CSS.  
    31  - remove the figure number since this will be generated automatically for the caption. 
     26- **MODEL DOCUMENTATION** 
     27- **doc string**. 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. DO NOT use the old html documentation. For example, for the !BarBellModel, search for !BarBellModel in the rst file then copy everything after the *2.x.x. !ModelNameModel!**. Then edit the result as follows: 
     28 - 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. 
     29 - replace *2.x.x.x. Definition!** with just Definition followed by 10 dashes on the line below. 
     30 - wherever possible, try to replace images of math functions with Latex equivalents. 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].  
     31 - remove the table of parameters which will get autogenerated. 
     32 - copy non-math figures from the sasview/src/sas/models/media/img subdirectory to the sasmodels/sasmodels/models/img subdirectory and rename them to something sensible. For example, image183.jpg became power_law_1d.jpg. 
     33 - figure captions should be indented relative to the ..image:: tag. This allows us to, for example, change the font of the caption through CSS.  
     34 - remove the figure number since this will be generated automatically. 
    3235 - make sure all references to model parameters are appropriately renamed, and that the relationship between equation variables and model parameters are obvious. 
    33 - 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. 
    34 - 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. 
    35 - 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 src/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. 
    36 - 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 src/sas/models/include] 
    37  - 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: 
    38   - radius = radius 
    39   - sld = scattering length density of particle 
    40   - solvent_sld = scattering length density of matrix 
    41   - cor_length = correlation length 
    42   - exp = exponent (example: porod_exp) 
    43   - peak_pos = q_peak or q0 etc 
    44   - theta = axis_theta, phi = axis_phi 
    45   - add more as you see them 
    46   - NOTE:  There is no need to specify 'scale' or 'background', these are implicit to all models. 
    47  - lower and upper limits can be any number or -inf or inf 
    48   - add limits where required; the sasview models don't usually define them 
    49   - 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. 
    50  - type can take 3 values at this time: “”, “volume”, or “orientation” 
    51   - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and have polydispersity loops generated automatically 
     36- **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. 
     37- **title = "short description".**  This is a new string to be used for a tooltip, for example. It can probably be pulled directly from the model_functions.rst file. 
     38- **description = """doc string""".** Cut and paste the self.description string from the (old) !SasView model header in [https://github.com/SasView/sasview/tree/master/src/sas/models/include src/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.'' 
     39- **PARAMETERS** 
     40 - **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 src/sas/models/include]. 
     41 - ''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().'' 
     42 - VERY IMPORTANT: We are trying to make the model parameters more consistent between models. So solvent_sld, for example, should have exactly the same name in every model. ''The current list of new parameters is:'' 
     43  - ''radius''      = radius 
     44  - ''sld''         = scattering length density of particle 
     45  - ''solvent_sld'' = scattering length density of matrix 
     46  - ''cor_length''  = correlation length 
     47  - ''exp''         = exponent (example: porod_exp) 
     48  - ''peak_pos''    = q_peak or q0 etc 
     49  - ''theta''       = axis_theta, phi = axis_phi 
     50  - add more as you generate them! 
     51  - **''NOTE: There is no need to specify 'scale' or 'background', these are implicit to all models.''** 
     52 - lower and upper limits can be any number, or -inf or inf. 
     53  - add limits where required the (old) sasview models don't usually define them. 
     54  - 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. 
     55 - "type" can take 3 values at this time: “”, “volume”, or “orientation”. 
     56  - "volume" parameters are passed to Iq(), Iqxy(), and form_volume(), and have polydispersity loops generated automatically. 
    5257  - "orientation" parameters are only passed to Iqxy(). 
    53  - 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(). 
    54 - COMPUTATION 
     58- **THE COMPUTATION** 
    5559 - Pure Python 
    5660  - def Iq (this section does not exist for c models.  It is replaced by the list of c files to call) 
     
    6973      source = ["lib/J1.c", "lib/gauss76.c", "my_model.c"] 
    7074  }}} 
    71   - 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. 
    72 - 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). 
    73 - For certain models, namely core shell type models, the VR attribute returns the volume ratio for the core-shell. 
    74 - 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. 
    75  - 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. 
    76 - 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. 
    77 - 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. 
    78 - tests section (for unit test purposes) VERY IMPORTANT.  Syntax: test is a list of lists. each list is one test and contains, in order,  
    79  - a dictionary of parameter values. This can be {} using the default parameters, or filled with some parameters that will be different from the default ({‘radius’:10.0, ‘sld’:4}) unlisted parameters will be given the default values. 
    80  - the input q value or tuple of qx, qy values  
    81  - the output Iq or Iqxy expected of the model for the parameters and q value given 
    82  - inputs and outputs can also be lists if you have several values to test for the same model parameters 
    83  - for ER and VR, give the inputs as 'ER' and 'VR' respectively 
    84  - include at least one test for each model.  Please make sure that the answer value is correct (i.e. not a random number please) 
     75  - 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. 
     76 - ''NOTE: 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).'' 
     77 - ''NOTE: for certain models, namely core-shell type models, the VR attribute returns the volume ratio for the core-shell.'' 
     78- **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. 
     79- 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. 
     80- **TRANSITION CHECKS** 
     81 - **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. 
     82 - **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. 
     83- **UNIT TEST(S)** 
     84 - THESE ARE VERY IMPORTANT. Include at least one test for each model and PLEASE make sure that the answer value is correct (i.e. not a random number). 
     85 - **test** is a list of lists. Each list is one test and contains, in order:  
     86  - a dictionary of parameter values. This can be {} using the default parameters, or filled with some parameters that will be different from the default ({‘radius’:10.0, ‘sld’:4}). Unlisted parameters will be given the default values. 
     87  - the input q value or tuple of qx, qy values. 
     88  - the output Iq or Iqxy expected of the model for the parameters and q value given. 
     89  - inputs and outputs can also be lists if you have several values to test for the same model parameters. 
     90 - for ER and VR, give the inputs as 'ER' and 'VR' respectively. 
    8591 - to summarize: 
    8692{{{#!python 
     
    101107}}} 
    102108 
    103 '''TEST YOUR NEWLY CONVERTED MODEL''' 
     109'''TEST YOUR NEW/NEWLY-CONVERTED MODEL''' 
    104110 
    105 Test your new model by runing compare.py to verify that the converted model is giving the same results as it did in SasView prior to conversion. In order to do this, you need either a version of sasview installed in your python path, or a built sasview in a checked out directory at the same level as the checked out sasmodels repository. 
     111Test your new model by runing compare.py to verify that the converted model is giving the same results as it did in SasView prior to conversion. In order to do this, you need either a version of SasView installed in your python path, or a locally-built SasView in a checked-out directory ''at the same level'' as the checked-out sasmodels repository; i.e. you have the file structure: 
    106112 
    107 If the latter, you need to add the sasview build directory to your PYTHONPATH or use compare.sh which will do so for you. 
     113{{{ 
     114  drive:\some_folder 
     115}}} 
     116contains 
     117{{{ 
     118  \bumps 
     119  \periodictable 
     120  \sasview 
     121  \sasmodels 
     122}}} 
     123 
     124If using a locally-built SasView, you need to add ''drive:\some_folder\sasview'' to your PYTHONPATH environment variable, or use \sasmodels\compare.sh which will do so for you. If you don't have PYTHONPATH, use the ''User'' PATH variable instead.  
    108125 
    109126The first thing to test is that you are getting the same answer as !SasView for the 1D version of the model. This is done with: 
    110127 
    111128{{{ 
    112 ./compare.sh -1d modelname  
     129./compare.sh modelname -1d 
    113130}}} 
    114131 
     
    118135 
    119136{{{ 
    120 ./compare.sh -2d modelname 
     137./compare.sh modelname -2d 
    121138}}} 
    122139 
    123 Brief help for the comparison script can be obtained by just running '''./compare.sh''' 
     140**Brief help for the comparison script can be obtained by just running ./compare.sh** 
    124141 
    125  
    126 Run the unit tests that you have added: 
     142Now run the unit tests that you have added: 
    127143 
    128144{{{ 
     
    130146}}} 
    131147 
    132 '''FINISHING''' 
     148'''FINALLY''' 
    133149 
    134 Once compare passes properly and everything is done edit the models table to indicate that the conversion is complete 
     150Once compare and the unit test(s) pass properly and everything is done, commit your new model to the repo and then edit the models table at [http://trac.sasview.org/wiki/ListofModels] to indicate that the conversion is complete.