Changes

src="[[https://mail.gna.org/public/relax-devel/2013-06/msg00016.html"See mail archive]] The following is a tutorial for adding new relaxation dispersionmodels for either CPMG-type or R1rho-type experiments to relax. Thisincludes both the models based on the analytical, closed-formexpressions as well as the models involving numerical integration ofthe Bloch-McConnell equations. The tutorial will follow the example of the addition of the 'M61'model already present within relax, pointing to the relevant commitsfor reference. To see the commit message and the code changes incolour, click on the links found within these commit messages. Thisspecific case is the Meiboom 1961 analytic model for 2-site fastexchange equation for R1rho-type experiments.  1) Adding the model to the list. Reference commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17611 Firstly the model should be added to the lists of thespecific_analyses.relax_disp.variables module. The model name isstored in a special variable which will be used throughout relax.  2) The relax_disp.select_model user function front end. Reference commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17612 The next step is to add the model, its description, the equations forthe analytic models, and all references to the relax_disp.select_modeluser function front end. When the relaxation dispersion chapter ofthe relax manual is created (this will be thedocs/latex/relax_disp.tex file), then the same description should beadded there as well.  3) The relax library. Reference commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17615 Now the dispersion function needs to be added to the relax library (inthe lib.relax_disp package). This should be designed as a simplePython function which takes the dispersion parameters and experimentalvariables, and calculates the R2eff/R1rho values. The module cancontain auxiliary functions for the calculation. Some auxiliaryfunctions, if not specific to relaxation dispersion, may be betterplaced in other locations within the relax library. The relaxation dispersion functions in the library currently take asan argument a data structure for the back-calculated R2eff/R1rhovalues and populate this structure. This design is not essential ifthe target function, described in the next point, handles the libraryfunction appropriately. Just look at the files in lib/dispersion toget an idea of the design used. The dispersion code in the relax library must be robust. Thisinvolves identifying parameter values or combinations which wouldcause failures in the mathematical operations (numerical issues notpresent in the mathematics must be considered). Note that parametervalues of 0 are common within a grid search. It should be decided ifthe R2eff/R1rho value should be set to zero, to another value, or tosomething large (e.g. 1e100). For example: Divisions - always catch zeros in the denominator with if statements,even if you believe that this will never be encountered.Square roots - make sure that the value inside is always > 0.Trigonometric functions - these should be tested for where they arenot defined or where the software implementation can no longer handlecertain values. For example try cosh(1000) in Python. In the reference example, the M61 model code was copied from the LM63module and modified appropriately.  4) The target function. Reference commits: http://article.gmane.org/gmane.science.nmr.relax.scm/17616http://article.gmane.org/gmane.science.nmr.relax.scm/17660http://article.gmane.org/gmane.science.nmr.relax.scm/17661 The target function is used in optimisation and is a class methodwhich takes as a single argument the parameter vector. This list ischanged by the minimisation algorithm during optimisation. The targetfunction should then return a single floating point number - thechi-squared value. Again in this example, the code for the M61 is copied from the LM63model and then modified.  5) Adding support for the parameters. Reference commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17573 This is needed to enable the model. This example is for the CR72model implementation as the parameters required for the M61 modelmatch those of the preexisting LM63 model.  6) The relax_disp.select_model back end. Reference commit: http://article.gmane.org/gmane.science.nmr.relax.scm/17622 Now the back end of the relax_disp.select_model user function for themodel can be added. This involved identifying the model andconstructing the parameter list.  7) The test suite. Reference commits: http://article.gmane.org/gmane.science.nmr.relax.scm/17647http://article.gmane.org/gmane.science.nmr.relax.scm/17648http://article.gmane.org/gmane.science.nmr.relax.scm/17649http://article.gmane.org/gmane.science.nmr.relax.scm/17662http://article.gmane.org/gmane.science.nmr.relax.scm/17663 This step is normally performed as step number 1. This is the mostimportant part that makes sure that the code not only works now, butwill continue working for the entire lifetime of the relax project. The idea is that synthetic data (here for example as Sparky peaklists) is created for the model and added to the test suite directorytest_suite/shared_data/dispersion/. This is then used in a systemtest to check that the code in relax can reproduce the data. It isvery important that the code added to the relax library is not used tocreate the synthetic data!  8) Comparing to other software. It can happen that a bug present in the lib.dispersion package code isalso replicated in the synthetic data. This is not uncommon.Therefore it is very useful to use other software with the test datafrom step 7 to see if the original parameters can be found. A goodexample can be seen in the test_suite/shared_data/dispersion/Hansenwhich contains Dr. Flemming Hansen's CPMG data (see the README file)and the results from different programs including NESSY, relax,CPMGFit, and ShereKhan. The comparison is in the file'software_comparison'. Once the relax code is able to find identical or better results thanthe dispersion softwares, then the values found in the test suiteoptimisation can be locked in. The assertEqual() andassertAlmostEqual() methods can be used to only allow the test to passwhen the correct values are found.  9) Debugging. This step should not require an explanation. It goes hand-in-handwith steps 7) and 8).