| | 1 | '''CREATE NEW MODEL FILES'''. |
| | 2 | |
| | 3 | In sasmodels/models/ copy barbell.py and barbell.c to mymodel.py and mymodel.c for models with c code or broadpeak.py to mymodel.py where “mymodel’ is the NEW name for the model to be moved. Please follow new naming rules: |
| | 4 | - No capitalization and thus no !CamelCase. If necessary use underscore to separate (i.e. barbell not !BarBell or broad_peak not !BroadPeak) |
| | 5 | - Remove “model” from the name (i.e. barbell not !BarBellModel) |
| | 6 | |
| | 7 | |
| | 8 | '''EDIT NEW MODEL FILES''' |
| | 9 | |
| | 10 | 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. |
| | 11 | - 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 sasview/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: |
| | 12 | - replace *2.x.x.x. Definition !** with Definition followed by a line of 10 dashes. |
| | 13 | - 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. |
| | 14 | - remove the table of parameters which will get autogenerated |
| | 15 | - name = mymodel. Use the name of the file as described above in 1. |
| | 16 | - 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). |
| | 17 | - description doc string. Cut and paste the self.description string from the !SasView model. This gives a brief description of the equation and the parameters without the need to read the entire model documentation. |
| | 18 | - category is a GUI item that should be a default category that the model will be assigned to in the GUI if it is not overwritten by the user. This can be a comma separated list if the model should default to several categories |
| | 19 | - parameters. This is where the parameters get defined. The syntax should be obvious from the default. 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: |
| | 20 | - radius = radius |
| | 21 | - sld = scattering length density of particle |
| | 22 | - solvent_sld = scattering length density of matrix |
| | 23 | - cor_length = correlation length |
| | 24 | - exp = exponent (example: porod_exp) |
| | 25 | - peak_pos = q_peak or q0 etc |
| | 26 | - lower and upper limits can be any number or -inf or inf |
| | 27 | - type can take 3 values at this time: “”, “volume”, or “orientation” |
| | 28 | - COMPUTATION |
| | 29 | - Python |
| | 30 | - def Iq (this section does not exist for c models. It is replaced by the list of c files to call) |
| | 31 | - 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. |
| | 32 | - Python + C |
| | 33 | - in place of the above methods point to the C source files needed. There should be 3: two libraries and the model.c where model is the same name as given to the python model.py it should read source = ["lib/J1.c", "lib/gauss76.c", "my_model.c"] |
| | 34 | - 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. |
| | 35 | - 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). |
| | 36 | - 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. |
| | 37 | - 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. |
| | 38 | - 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. |
| | 39 | - tests section (for unit test purposes) VERY IMPORTANT. Syntax: test is a list of lists. each list is one test and contains, in order, |
| | 40 | - 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. |
| | 41 | - the q value or a tuple of qx, qy values |
| | 42 | - the Iq or Iqxy expected of the model for the parameters and q value given. There should be at least one test in the list. Please make sure that the answer value is correct (i.e. not a random number please) |
| | 43 | |
| | 44 | '''TEST YOUR NEWLY CONVERTED MODEL''' |
| | 45 | |
| | 46 | 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 |
| | 47 | |
| | 48 | '''FINISHING''' |
| | 49 | |
| | 50 | Once compare passes properly and everything is done edit the models table to indicate that the conversion is complete |
