Trusted, Bureaucrats
4,223
edits
Changes
Jump to navigation
Jump to search
m
Fix for the mail archive link.
{{tip|See the [httpshttp://www.nmr-relax.com/mail.gna.org/public/relax-devel/2013-06/msg00016.html mail archive] for the original post.}}
The following is a tutorial for adding new relaxation dispersion models for either CPMG-type or {{:R1rho}}-type experiments to the software relax. This includes both the models based on the analytic, closed-form expressions as well as the models involving numeric solutions of the Bloch-McConnell equations.
The tutorial will follow the example of the addition of the models already present within relax, pointing to the relevant commits for reference. To see the commit message and the code changes in colour, click on the links found within these commit messages. The models in the reference commits sections are in reverse chronological order and therefore the top links will be the most recent and relevant.
This step is normally performed first. This is the most important part that makes sure that the code not only works now, but will continue working for the entire lifetime of the relax project.
The idea is that real or synthetic data, for example as Sparky peak lists, is obtained or created for the model and added to the test suite directory <code>test_suite/shared_data/dispersion/</code>. This is then used in a system test to check that the code in relax can consistently reproduce the results.
=== Synthetic data ===
=== Measured data ===
An alternative is to use real measured relaxation dispersion data. This data should be added as peak lists containing peak intensities to <code>test_suite/shared_data/dispersion/</code>. As the real solution cannot be known a priori, the results from relax must be compared to results obtained from another software program (possibly directly from a publication). The steps required for using such data are:
* Create a new directory name for the test data.
* Add the original full peak lists to the directory.
* Make truncated versions of these files (ending in <code>_trunc.*</code>) and add these as well. These will be used for the system test instead of the full data to allow the test to finish in a reasonable amount of time.
* Add a script which performs the full analysis in relax for the model. Also a script which performs the analysis using only the [[R2eff ]] model. See the '''<code>test_suite/shared_data/dispersion/Hansen/*.py''' </code> scripts for reference - these scripts should be copied to your data directory and modified (using the '''<code>svn cp''' </code> command). Once the scripts are functional, they can be copied and modified for the truncated data (again using the '''<code>svn cp''' </code> command).
* Copy the full analysis script to '''<code>test_suite/system_tests/scripts/relax_disp/''' </code> with an appropriate name (always using the '''<code>svn cp''' </code> command). This can then be used in a new system test. Better still, the final save file from the '''<code>r2eff_calc.py''' </code> script for the truncated data can be used to start the script. This is again to save a lot of computation time in the test. See the '''<code>test_tp02_data_to_ns_r1rho_2site()''' </code> system test in the '''<code>test_suite/system_tests/relax_disp.py''' </code> file for a template.
If you are not a relax developer, a [https://gna.org/projects/relax support request] can be [https://gna.org/support/?func=additem&group=relax submitted]. You can attach files and add comments to that request for a relax developer to make the changes for you.
* The [[TP02]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18256 r20500] [http://article.gmane.org/gmane.science.nmr.relax.scm/18293 r20538] [http://article.gmane.org/gmane.science.nmr.relax.scm/18295 r20541] [http://article.gmane.org/gmane.science.nmr.relax.scm/18297 r20537]
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17647 r19891] [http://article.gmane.org/gmane.science.nmr.relax.scm/17648 r19892] [http://article.gmane.org/gmane.science.nmr.relax.scm/17649 r19893] [http://article.gmane.org/gmane.science.nmr.relax.scm/17662 r19906] [http://article.gmane.org/gmane.science.nmr.relax.scm/17663 r19907]
== Creating a new experiment type ==
== Adding the model to the list ==
Firstly the model should be added to the lists of the <code>specific_analyses.relax_disp.variables </code> module. The model name is stored in a special variable which will be used throughout relax.
=== Reference commits ===
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17611 r19855]
* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]
== The relax_disp.select_model user function front end ==
The next step is to add the model, its description, the equations for the analytic models, and all references to the {{uf|relax_disp.select_model }} user function front end.
== The relax_disp.select_model user function back end ==
Now the back end of the {{uf|relax_disp.select_model }} user function for the model can be added. This involved identifying the model and constructing the parameter list.
=== Reference commits ===
* The [[M61]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17622 r19866]
* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]
== Adding support for the parameters ==
This is needed to enable the model. It involves modifying many of the modules in the <code>specific_analyses.relax_disp </code> package.
=== Reference commits ===
* The [[MQ NS CPMG 2-site]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/18812 r21056]
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17573 r19817]
== The target function ==
The target function is used in optimisation and is a class method which takes as a single argument the parameter vector. This list is changed by the minimisation algorithm during optimisation. The target function should then return a single floating point number - the chi-squared value.
Again in this example, the code for the [[M61 ]] is copied from the [[LM63 ]] model and then modified.
=== Reference commits ===
* The [[No Rex]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17592 r19836]
* The [[CR72]] model at [http://article.gmane.org/gmane.science.nmr.relax.scm/17571 r19815]
== The relax library ==
