Source Code for Module lib.dispersion.tsmfk01

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2009 Sebastien Morin                                          # 
  4  # Copyright (C) 2013-2014 Edward d'Auvergne                                   # 
  5  # Copyright (C) 2013 Troels E. Linnet                                         # 
  6  #                                                                             # 
  7  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  8  #                                                                             # 
  9  # This program is free software: you can redistribute it and/or modify        # 
 10  # it under the terms of the GNU General Public License as published by        # 
 11  # the Free Software Foundation, either version 3 of the License, or           # 
 12  # (at your option) any later version.                                         # 
 13  #                                                                             # 
 14  # This program is distributed in the hope that it will be useful,             # 
 15  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 16  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 17  # GNU General Public License for more details.                                # 
 18  #                                                                             # 
 19  # You should have received a copy of the GNU General Public License           # 
 20  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 21  #                                                                             # 
 22  ############################################################################### 
 23   
 24  # Module docstring. 
 25  """The Tollinger et al (2001) 2-site very-slow exchange U{TSMFK01<http://wiki.nmr-relax.com/TSMFK01>} model. 
 26   
 27  Description 
 28  =========== 
 29   
 30  Applicable in the limit of slow exchange, range of microsecond to second time scale, when |R2A-R2B| << k_AB, kB << 1/tau_CP.  R20A is the transverse relaxation rate of site A in the absence of exchange.  2*tau_CP is is the time between successive 180 degree pulses. 
 31   
 32  This module is for the function, gradient and Hessian of the U{TSMFK01<http://wiki.nmr-relax.com/TSMFK01>} model 
 33   
 34   
 35  References 
 36  ========== 
 37   
 38  The model is named after the reference: 
 39   
 40      - Tollinger, M., Skrynnikov, N. R., Mulder, F. A. A., Forman-Kay, J. D. and Kay, L. E. (2001).  Slow Dynamics in Folded and Unfolded States of an SH3 Domain, I{J. Am. Chem. Soc.}, B{123} (46) (U{DOI: 10.1021/ja011300z<http://dx.doi.org/10.1021/ja011300z>}). 
 41   
 42   
 43  Equations 
 44  ========= 
 45   
 46  The equation used is:: 
 47   
 48                                     sin(delta_omega * tau_CP) 
 49      R2Aeff = R20A + k_AB - k_AB * -------------------------  , 
 50                                     delta_omega * tau_CP 
 51   
 52  where:: 
 53   
 54      tau_CP = 1.0/(4*nu_cpmg) , 
 55   
 56  R20A is the transverse relaxation rate of site A in the absence of exchange, 2*tau_CP is is the time between successive 180 deg. pulses, k_AB is the forward chemical exchange rate constant, delta_omega is the chemical shift difference between the two states. 
 57   
 58   
 59  Links 
 60  ===== 
 61   
 62  More information on the TSMFK01 model can be found in the: 
 63   
 64      - U{relax wiki<http://wiki.nmr-relax.com/TSMFK01>}, 
 65      - U{relax manual<http://www.nmr-relax.com/manual/TSMFK01_2_site_CPMG_model.html>}, 
 66      - U{relaxation dispersion page of the relax website<http://www.nmr-relax.com/analyses/relaxation_dispersion.html#TSMFK01>}. 
 67  """ 
 68   
 69  # Python module imports. 
 70  from numpy import array, min, sin, isfinite, sum 
 71   
 72   
 73 -def r2eff_TSMFK01(r20a=None, dw=None, k_AB=None, tcp=None, back_calc=None, num_points=None): 
 74      """Calculate the R2eff values for the TSMFK01 model. 
 75   
 76      See the module docstring for details. 
 77   
 78   
 79      @keyword r20a:          The R20 parameter value of state A (R2 with no exchange). 
 80      @type r20a:             float 
 81      @keyword dw:            The chemical exchange difference between states A and B in rad/s. 
 82      @type dw:               float 
 83      @keyword k_AB:          The k_AB parameter value (the forward exchange rate in rad/s). 
 84      @type k_AB:             float 
 85      @keyword tcp:           The tau_CPMG times (1 / 4.nu1). 
 86      @type tcp:              numpy rank-1 float array. 
 87      @keyword back_calc:     The array for holding the back calculated R2eff values.  Each element corresponds to one of the CPMG nu1 frequencies. 
 88      @type back_calc:        numpy rank-1 float array 
 89      @keyword num_points:    The number of points on the dispersion curve, equal to the length of the cpmg_frqs and back_calc arguments. 
 90      @type num_points:       int 
 91      """ 
 92   
 93      # Catch parameter values that will result in no exchange, returning flat R2eff = R20 lines (when kex = 0.0, k_AB = 0.0). 
 94      if dw == 0.0 or k_AB == 0.0: 
 95          back_calc[:] = array([r20a]*num_points) 
 96          return 
 97   
 98      # Denominator. 
 99      denom = dw * tcp 
100   
101      # The numerator. 
102      numer = sin(denom) 
103   
104      # Catch zeros (to avoid pointless mathematical operations). 
105      # This will result in no exchange, returning flat lines. 
106      if min(numer) == 0.0: 
107          back_calc[:] = array([r20a + k_AB]*num_points) 
108          return 
109   
110      # Calculate R2eff. 
111      R2eff = r20a + k_AB - k_AB * numer / denom 
112   
113      # Catch errors, taking a sum over array is the fastest way to check for 
114      # +/- inf (infinity) and nan (not a number). 
115      if not isfinite(sum(R2eff)): 
116          R2eff = array([1e100]*num_points) 
117   
118      back_calc[:] = R2eff 
119