Difference between revisions of "Relax 3.3.0"

From relax wiki
Jump to navigation Jump to search
(Links to the API documentation.)
(More API documentation links.)
Line 708: Line 708:
 
* Added the "dtype" argument to function matrix_exponential_rankN.  This is to force the conversion of dtype, if they are of other type.  This can be conversion from complex128 to complex64.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added the "dtype" argument to function matrix_exponential_rankN.  This is to force the conversion of dtype, if they are of other type.  This can be conversion from complex128 to complex64.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Fix the bug: "M2_i = M1_mat", which was causing the problems getting system tests to pass.  Removed the specifications of which dtype, the initial matrices are created.  They can be converted later, with the specification of dtype to matrix_exponential_rankN().  All system tests now pass.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Fix the bug: "M2_i = M1_mat", which was causing the problems getting system tests to pass.  Removed the specifications of which dtype, the initial matrices are created.  They can be converted later, with the specification of dtype to matrix_exponential_rankN().  All system tests now pass.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
* Moved the Bloch-McConnell matrix for 2-site exchange into lib/dispersion/ns_matrices.py.  This is for consistency with the other code.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
+
* Moved the Bloch-McConnell matrix for 2-site exchange into [http://www.nmr-relax.com/api/3.3/lib.dispersion.ns_matrices-module.html lib/dispersion/ns_matrices.py].  This is for consistency with the other code.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
* Moved the matrices for Bloch-McConnell from lib ns_mmq_2site, since they are now defined in ns_matrices.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
+
* Moved the matrices for Bloch-McConnell from lib ns_mmq_2site, since they are now defined in [http://www.nmr-relax.com/api/3.3/lib.dispersion.ns_matrices-module.html ns_matrices.py].  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
* Moved the Bloch-McConnell matrix for 3-site exchange, into the lib/dispersion/ns_matrices.py.  This is to standardize the code.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
+
* Moved the Bloch-McConnell matrix for 3-site exchange, into the [http://www.nmr-relax.com/api/3.3/lib.dispersion.ns_matrices-module.html lib/dispersion/ns_matrices.py].  This is to standardize the code.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Removed m1 and m2 to be sent to lib function of [[NS MMQ 2-site]], since they are now populated inside the lib function.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Removed m1 and m2 to be sent to lib function of [[NS MMQ 2-site]], since they are now populated inside the lib function.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Implemented the Bloch-McConnell matrix for 3-site exchange, for multidimensional data.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Implemented the Bloch-McConnell matrix for 3-site exchange, for multidimensional data.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
Line 739: Line 739:
 
* Precision lowering of system test, test_korzhnev_2005_15n_sq_data and test_korzhnev_2005_1h_sq_data.  The system tests does not fail on Linux 64-bit system, but only on Mac 32-bit system.  This is due to floating error deviations.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Precision lowering of system test, test_korzhnev_2005_15n_sq_data and test_korzhnev_2005_1h_sq_data.  The system tests does not fail on Linux 64-bit system, but only on Mac 32-bit system.  This is due to floating error deviations.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added log files for super profiling against tags [[relax 3.2.1|3.2.1]] and [[relax 3.2.2|3.2.2]].  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added log files for super profiling against tags [[relax 3.2.1|3.2.1]] and [[relax 3.2.2|3.2.2]].  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
* Copied lib.linear_algebra.matrix_exponential to lib.dispersion.matrix_exponential.  The matrix exponential of higher dimensional data is only used in the dispersion part of relax.
+
* Copied lib.linear_algebra.matrix_exponential to [http://www.nmr-relax.com/api/3.3/lib.dispersion.matrix_exponential-module.html lib.dispersion.matrix_exponential].  The matrix exponential of higher dimensional data is only used in the dispersion part of relax.
* Added to __init__, the new lib.dispersion.matrix_exponential module.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
+
* Added to __init__, the new [http://www.nmr-relax.com/api/3.3/lib.dispersion.matrix_exponential-module.html lib.dispersion.matrix_exponential module].  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added to unit_tests/_lib/_dispersion/__init__.py, the new unit test file: test_matrix_exponential.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added to unit_tests/_lib/_dispersion/__init__.py, the new unit test file: test_matrix_exponential.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added numpy array save files.  They are the numpy array structures, which are send in from system test: Relax_disp.test_hansen_cpmg_data_to_ns_cpmg_2site_3D.  These numpy array structures, are used in unit tests.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added numpy array save files.  They are the numpy array structures, which are send in from system test: Relax_disp.test_hansen_cpmg_data_to_ns_cpmg_2site_3D.  These numpy array structures, are used in unit tests.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added unit test unit_tests/_lib/_dispersion/test_matrix_exponential.py to test the matrix exponential from higher dimensional data.  lib.dispersion.matrix_exponential.matrix_exponential_rankN will match against lib.linear_algebra.matrix_exponential.  Data which is used for comparison, comes from system test: Relax_disp.test_hansen_cpmg_data_to_ns_cpmg_2site_3D.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added unit test unit_tests/_lib/_dispersion/test_matrix_exponential.py to test the matrix exponential from higher dimensional data.  lib.dispersion.matrix_exponential.matrix_exponential_rankN will match against lib.linear_algebra.matrix_exponential.  Data which is used for comparison, comes from system test: Relax_disp.test_hansen_cpmg_data_to_ns_cpmg_2site_3D.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Renamed function to return data in unit test _lib/_dispersion/test_matrix_exponential.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Renamed function to return data in unit test _lib/_dispersion/test_matrix_exponential.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
* Fix to lib/dispersion/matrix_exponential.py, since the svn copy command was used on non-updated version of the file.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
+
* Fix to [http://www.nmr-relax.com/api/3.3/lib.dispersion.matrix_exponential-module.html lib/dispersion/matrix_exponential.py], since the svn copy command was used on non-updated version of the file.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added unit test for doing the matrix exponential for complex data.  This test shows, that the dtype=complex64, should be removed from lib/dispersion/ns_mmq_2site.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added unit test for doing the matrix exponential for complex data.  This test shows, that the dtype=complex64, should be removed from lib/dispersion/ns_mmq_2site.py.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added data for unit test for the testing of the matrix_exponential_rankN.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].
 
* Added data for unit test for the testing of the matrix_exponential_rankN.  [https://gna.org/task/?7807 Task #7807: Speed-up of dispersion models for clustered analysis].

Revision as of 14:55, 22 September 2014


Description

This is a major feature release which includes a huge number of changes, as can be seen below. The most important change is an incredible speed up of all relaxation dispersion models. See the table below for a comparison to the previous relax 3.2.3 release. The maximum possible advantage of linear algebra operations are used to eliminate all of the slow Python looping and to obtain the ultimate algorithms for speed. As this is using NumPy, conversion to C or FORTRAN will not result in any significant speed advantage. With these huge speed ups, relax should now be one of the fastest software packages for analysing relaxation dispersion phenomena.

Other important features include the implementation of a zooming grid search algorithm for use in all analysis types, expanded plotting capabilities for R values in the relaxation dispersion analysis, the ability to optimise the R1 parameter in all off-resonance dispersion models, proper minimisation statistics resetting by the minimisation user functions, and a large expansion of the periodic table information for all elements in the relax library for correctly estimating molecular masses. Additional features are that there is better tab completion support in the prompt UI for Mac OS X, the addition of the time user function for printing the current date and time, the value.copy user function accepting a force argument for overwriting values, model nesting in the dispersion auto-analysis has been extended, the spin-lock offset is now shown in the dispersion analysis in the GUI, the relax_disp.r2eff_estimate user function has been added for fast R2eff and I0 parameter value and error estimation, and gradient and Hessian functions have been added to the exponential curve-fitting C module allowing for more advanced optimisation in the relaxation curve-fitting and dispersion analyses.

Note that this new 3.3 relax series breaks compatibility with old relax scripts. The important change, which is the main reason for starting the relax 3.3.x line, is the renaming of the calc, grid_search and minimise user functions to minimise.calculate, minimise.grid_search and minimise.execute respectively. Please update your scripts appropriately. A new relax feature is that old user function calls are detected in the prompt and script UIs and a RelaxError raised explaining what to rename the user function to.

Important bugfixes in this release include that relax can run on MS Windows systems again, numerous Python 3 fixes, the ability to load Bruker DC files when the file format has corrupted whitespace, the GUI "close all analyses" feature works and no longer raises an error, structure.create_diff_tensor_pdb user function now works when no structural data is present, the geometric prolate diffusion 3D PDB representation in a model-free analysis now aligns with the axis in the PDB as it was previously rotated by 90 degrees, and the Monte Carlo simulations in the relaxation dispersion analysis for exponential curve-fitting for R2eff/R parameter errors is now correct and no longer underestimating the errors by half. For more details about the new features and the bug fixes, please see below. For fully formatted and easy to navigate release notes, please see http://wiki.nmr-relax.com/Relax_3.3.0.

To demonstrate the huge speeds ups in the relaxation dispersion analysis, the following table compares the speed of dispersion models in relax 3.2.3 compared to the new 3.3.0 version:

100 single spins analysis (times in seconds):
Dispersion model relax 3.2.3 timings relax 3.3.0 timings Speed change
No Rex 0.824±0.017 0.269±0.016 3.068x faster.
LM63 1.616±0.017 0.749±0.008 2.157x faster.
LM63 3-site 3.218±0.039 0.996±0.013 3.230x faster.
CR72 2.639±0.042 1.536±0.019 1.718x faster.
CR72 full 2.808±0.027 1.689±0.075 1.663x faster.
IT99 1.838±0.032 0.868±0.011 2.118x faster.
TSMFK01 1.643±0.033 0.718±0.011 2.289x faster.
B14 5.841±0.050 3.747±0.044 1.559x faster.
B14 full 5.942±0.053 3.841±0.044 1.547x faster.
NS CPMG 2-site expanded 8.309±0.066 4.070±0.073 2.041x faster.
NS CPMG 2-site 3D 245.180±2.162 45.410±0.399 5.399x faster.
NS CPMG 2-site 3D full 237.217±2.582 45.177±0.415 5.251x faster.
NS CPMG 2-site star 183.423±1.966 36.542±0.451 5.020x faster.
NS CPMG 2-site star full 183.622±1.326 36.788±0.343 4.991x faster.
MMQ CR72 5.920±0.105 4.078±0.105 1.452x faster.
NS MMQ 2-site 363.659±2.610 82.588±1.197 4.403x faster.
NS MMQ 3-site linear 386.798±4.480 92.060±0.754 4.202x faster.
NS MMQ 3-site 391.195±3.442 93.025±0.829 4.205x faster.
M61 1.576±0.022 0.862±0.009 1.828x faster.
DPL94 22.794±0.517 1.101±0.008 20.705x faster.
TP02 19.892±0.363 1.232±0.007 16.152x faster.
TAP03 31.701±0.378 1.936±0.017 16.377x faster.
MP05 24.918±0.572 1.428±0.015 17.454x faster.
NS R1rho 2-site 244.604±2.493 35.125±0.202 6.964x faster.
NS R1rho 3-site linear 287.181±2.939 68.245±0.536 4.208x faster.
NS R1rho 3-site 290.486±3.614 70.449±0.686 4.123x faster.
Cluster of 100 spins analysis (times in seconds):
Dispersion model relax 3.2.3 timings relax 3.3.0 timings Speed change
No Rex 0.818±0.016 0.008±0.001 97.333x faster.
LM63 1.593±0.018 0.037±0.000 43.401x faster.
LM63 3-site 3.134±0.039 0.067±0.001 47.128x faster.
CR72 2.610±0.047 0.115±0.001 22.732x faster.
CR72 full 2.679±0.034 0.122±0.005 22.017x faster.
IT99 1.807±0.025 0.063±0.001 28.687x faster.
TSMFK01 1.636±0.036 0.039±0.001 42.170x faster.
B14 5.799±0.054 0.488±0.010 11.879x faster.
B14 full 5.803±0.043 0.484±0.006 11.990x faster.
NS CPMG 2-site expanded 8.326±0.081 0.685±0.012 12.160x faster.
NS CPMG 2-site 3D 244.869±2.382 41.217±0.467 5.941x faster.
NS CPMG 2-site 3D full 236.760±2.575 41.001±0.466 5.775x faster.
NS CPMG 2-site star 183.786±2.089 30.896±0.417 5.948x faster.
NS CPMG 2-site star full 183.243±1.615 30.898±0.343 5.931x faster.
MMQ CR72 5.978±0.094 0.847±0.007 7.061x faster.
NS MMQ 2-site 363.138±3.041 75.906±0.845 4.784x faster.
NS MMQ 3-site linear 384.978±5.402 83.703±0.773 4.599x faster.
NS MMQ 3-site 388.557±3.261 84.702±0.762 4.587x faster.
M61 1.555±0.021 0.034±0.001 45.335x faster.
DPL94 22.837±0.494 0.140±0.002 163.004x faster.
TP02 19.958±0.407 0.167±0.002 119.222x faster.
TAP03 31.698±0.424 0.287±0.003 110.484x faster.
MP05 25.009±0.683 0.187±0.007 133.953x faster.
NS R1rho 2-site 242.096±1.483 32.043±0.157 7.555x faster.
NS R1rho 3-site linear 280.778±2.589 62.866±0.616 4.466x faster.
NS R1rho 3-site 282.192±5.195 63.174±0.816 4.467x faster.

Full details of this comparison can be seen in the test_suite/shared_data/dispersion/profiling directory. For information about each of these models, please see the links: http://wiki.nmr-relax.com/No_Rex, http://wiki.nmr-relax.com/LM63, http://wiki.nmr-relax.com/LM63_3-site, http://wiki.nmr-relax.com/CR72, http://wiki.nmr-relax.com/CR72_full, http://wiki.nmr-relax.com/IT99, http://wiki.nmr-relax.com/TSMFK01, http://wiki.nmr-relax.com/B14, http://wiki.nmr-relax.com/B14_full, http://wiki.nmr-relax.com/NS_CPMG_2-site_expanded, http://wiki.nmr-relax.com/NS_CPMG_2-site_3D, http://wiki.nmr-relax.com/NS_CPMG_2-site_3D_full, http://wiki.nmr-relax.com/NS_CPMG_2-site_star, http://wiki.nmr-relax.com/NS_CPMG_2-site_star_full, http://wiki.nmr-relax.com/MMQ_CR72, http://wiki.nmr-relax.com/NS_MMQ_2-site, http://wiki.nmr-relax.com/NS_MMQ_3-site_linear, http://wiki.nmr-relax.com/NS_MMQ_3-site, http://wiki.nmr-relax.com/M61, http://wiki.nmr-relax.com/DPL94, http://wiki.nmr-relax.com/TP02, http://wiki.nmr-relax.com/TAP03, http://wiki.nmr-relax.com/MP05, http://wiki.nmr-relax.com/NS_R1rho_2-site, http://wiki.nmr-relax.com/NS_R1rho_3-site_linear, http://wiki.nmr-relax.com/NS_R1rho_3-site.

For CPMG statistics: 3 fields, each with 20 CPMG points. Total number of dispersion points per spin is 60.

For R experiments: 3 fields, each with 10 spin lock offsets, and each offset has been measured at 5 different spin lock fields. Per field there is 50 dispersion points. Total number of dispersion points per spin is 150.


Download

The new relax versions can be downloaded from http://www.nmr-relax.com/download.html. If binary distributions are not yet available for your platform and you manage to compile the binary modules, please consider contributing these to the relax project (described in section 3.6 of the relax manual, http://www.nmr-relax.com/manual/relax_distribution_archives.html).


CHANGES file

Version 3.3.0
(3 September 2014, from /trunk)
http://svn.gna.org/svn/relax/tags/3.3.0


Features

  • Huge speed ups for all of the relaxation dispersion models ranging from 1.452x to 163.004x times faster. The speed ups for the clustered spin analysis are far greater than for the single spin analysis.
  • Implementation of a zooming grid search algorithm for optimisation in all analyses. This includes the addition of the minimise.grid_zoom user function to set the zoom level. The grid width will be divided by 2zoom_level and centred at the current parameter values. If the new grid is outside of the bounds of the original grid, the entire grid will be translated so that it lies entirely within the original.
  • Increased the amount of user feedback for the minimise.grid_search user function. Now a comment for each parameter is included in the printed grid search setup table. This includes if the lower or upper bounds, or both, have been supplied and if a preset value has been used instead.
  • Expanded support for R 2D graph plotting in the relax_disp.plot_disp_curves user function as the X-axis can now be the ν1 value, the effective field ωeff, or the rotating frame title angle θ. And the plots are interpolation over the spin-lock offset.
  • Ability to optimise the R1 relaxation rate parameter in the off-resonance relaxation dispersion models.
  • Creation of the relax_disp.r1_fit user function for activating and deactivating R1 fitting in the dispersion analysis.
  • Better tab completion support in the prompt UI for Mac OS X users. For some Python versions, the Mac supplied libedit library is used rather than GNU readline. But this library uses a completely different language and hence tab completion was non-functional on these systems. The library difference is now detected and the correct language sent into libedit to activate tab completion.
  • Created the time user function. This is just a shortcut for printing out the output of the time.asctime() function.
  • The value.copy user function now accepts the force flag to allow destination values to be overwritten.
  • Expanded model nesting capabilities in the relaxation dispersion auto-analysis to speed up the protocol.
  • The spin-lock offset is now included in the spectra list GUI element for the relaxation dispersion analysis.
  • Creation of the relax_disp.r2eff_estimate user function for the fast estimation of R2eff/R values and errors when full exponential curves have been collected. This experimental feature uses linearisation to estimate the R2eff and I0 parameters and the covariance matrix to estimate parameter errors.
  • Gradients and Hessians are implemented for the exponential curve-fitting, hence all optimisation algorithms and constraint algorithms are now available for this analysis type. Using Newton optimisation instead of Nelder-Mead Simplex can save over an order of magnitude in computation time. This is also available in the relaxation dispersion analysis.
  • The minimisation statistics are now being reset for all analysis types. The minimise.calculate, minimise.grid_search, and minimise.execute user functions now all reset the minimisation statistics for either the model or the Monte Carlo simulations prior to performing any optimisation. This is required for both parallelised grid searches and repetitive optimisation schemes to allow the result to overwrite an old result in all situations, as sometimes the original chi-squared value is lower and the new result hence is rejected.
  • Large expansion of the periodic table information in the relax library to include all elements, the IUPAC 2011 standard atomic weights for all elements, mass numbers and atomic masses for all stable isotopes, and gyromagnetic ratios.
  • Significant improvements to the structure centre of mass calculations by using the new periodic table information - all elements are now supported and exact masses are now used.
  • Added a button to the spectra list GUI element for the spectrum.error_analysis user function. This is placed after the 'Add' and 'Delete' buttons and is used in the NOE, R1 and R2 curve-fitting and relaxation dispersion analyses.
  • RelaxErrors are now raised in the prompt or script UI if an old user function is called, printing out the names of the old and new user functions. This is for help in upgrading old scripts and is currently for the calc(), grid_search(), and minimise() user function calls.


Changes


Bugfixes


Links

For reference, the following links are also part of the announcement for this release:


Announcements

If you would like to receive announcements about new relax versions, please subscribe to the relax announcement mailing list. This list only receives ~10 emails per year. It is archived at the SourceForge archives and in The Mail Archive.


See also