Source Code for Module lib.dispersion.lm63_3site

  1  ############################################################################### 
  2  #                                                                             # 
  3  # Copyright (C) 2009 Sebastien Morin                                          # 
  4  # Copyright (C) 2013-2014 Edward d'Auvergne                                   # 
  5  #                                                                             # 
  6  # This file is part of the program relax (http://www.nmr-relax.com).          # 
  7  #                                                                             # 
  8  # This program is free software: you can redistribute it and/or modify        # 
  9  # it under the terms of the GNU General Public License as published by        # 
 10  # the Free Software Foundation, either version 3 of the License, or           # 
 11  # (at your option) any later version.                                         # 
 12  #                                                                             # 
 13  # This program is distributed in the hope that it will be useful,             # 
 14  # but WITHOUT ANY WARRANTY; without even the implied warranty of              # 
 15  # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the               # 
 16  # GNU General Public License for more details.                                # 
 17  #                                                                             # 
 18  # You should have received a copy of the GNU General Public License           # 
 19  # along with this program.  If not, see <http://www.gnu.org/licenses/>.       # 
 20  #                                                                             # 
 21  ############################################################################### 
 22   
 23  # Module docstring. 
 24  """The Luz and Meiboom (1963) 3-site fast exchange U{LM63 3-site<http://wiki.nmr-relax.com/LM63_3-site>} model. 
 25   
 26  Description 
 27  =========== 
 28   
 29  This module is for the function, gradient and Hessian of the U{LM63 3-site<http://wiki.nmr-relax.com/LM63_3-site>} model. 
 30   
 31   
 32  References 
 33  ========== 
 34   
 35  The model is named after the reference: 
 36   
 37      - Luz, S. and Meiboom S., (1963)  Nuclear Magnetic Resonance study of protolysis of trimethylammonium ion in aqueous solution - order of reaction with respect to solvent, I{J. Chem. Phys}. B{39}, 366-370 (U{DOI: 10.1063/1.1734254<http://dx.doi.org/10.1063/1.1734254>}). 
 38   
 39   
 40  Equations 
 41  ========= 
 42   
 43  The equation used is:: 
 44   
 45                     _3_ 
 46                     \    phi_ex_i   /     4 * nu_cpmg         /     ki      \ \  
 47      R2eff = R20 +   >   -------- * | 1 - -----------  * tanh | ----------- | | . 
 48                     /__     ki      \         ki              \ 4 * nu_cpmg / / 
 49                     i=2 
 50   
 51  For deconvoluting the parameters, see the relax user manual or the reference: 
 52   
 53      - O'Connell, N. E., Grey, M. J., Tang, Y., Kosuri, P., Miloushev, V. Z., Raleigh, D. P., and Palmer, 3rd, A. G. (2009). Partially folded equilibrium intermediate of the villin headpiece HP67 defined by 13C relaxation dispersion. I{J. Biomol. NMR}, B{45}(1-2), 85-98. (U{DOI: 10.1007/s10858-009-9340-0<http://dx.doi.org/10.1007/s10858-009-9340-0>}). 
 54   
 55   
 56  Links 
 57  ===== 
 58   
 59  More information on the LM63 3-site model can be found in the: 
 60   
 61      - U{relax wiki<http://wiki.nmr-relax.com/LM63_3-site>}, 
 62      - U{relax manual<http://www.nmr-relax.com/manual/LM63_3_site_fast_exchange_CPMG_model.html>}, 
 63      - U{relaxation dispersion page of the relax website<http://www.nmr-relax.com/analyses/relaxation_dispersion.html#LM63_3-site>}. 
 64  """ 
 65   
 66  # Python module imports. 
 67  from math import tanh 
 68   
 69   
 70 -def r2eff_LM63_3site(r20=None, rex_B=None, rex_C=None, quart_kB=None, quart_kC=None, cpmg_frqs=None, back_calc=None, num_points=None): 
 71      """Calculate the R2eff values for the LM63 3-site model. 
 72   
 73      See the module docstring for details. 
 74   
 75   
 76      @keyword r20:           The R20 parameter value (R2 with no exchange). 
 77      @type r20:              float 
 78      @keyword rex_B:         The phi_ex_B / kB parameter value. 
 79      @type rex_B:            float 
 80      @keyword rex_C:         The phi_ex_C / kC parameter value. 
 81      @type rex_C:            float 
 82      @keyword quart_kB:      Approximate chemical exchange rate constant between sites A and B (the exchange rate in rad/s) divided by 4. 
 83      @type quart_kB:         float 
 84      @keyword quart_kC:      Approximate chemical exchange rate constant between sites A and C (the exchange rate in rad/s) divided by 4. 
 85      @type quart_kC:         float 
 86      @keyword cpmg_frqs:     The CPMG nu1 frequencies. 
 87      @type cpmg_frqs:        numpy rank-1 float array 
 88      @keyword back_calc:     The array for holding the back calculated R2eff values.  Each element corresponds to one of the CPMG nu1 frequencies. 
 89      @type back_calc:        numpy rank-1 float array 
 90      @keyword num_points:    The number of points on the dispersion curve, equal to the length of the cpmg_frqs and back_calc arguments. 
 91      @type num_points:       int 
 92      """ 
 93   
 94      # Loop over the time points, back calculating the R2eff values. 
 95      for i in range(num_points): 
 96          # Catch zeros. 
 97          if rex_B == 0.0 and rex_C == 0.0: 
 98              back_calc[i] = r20 
 99   
100          # Avoid divide by zero. 
101          elif quart_kB == 0.0 or quart_kC == 0.0: 
102              back_calc[i] = 1e100 
103   
104          # The full formula. 
105          else: 
106              back_calc[i] = r20 
107              back_calc[i] += rex_B * (1.0 - cpmg_frqs[i] * tanh(quart_kB / cpmg_frqs[i]) / quart_kB) 
108              back_calc[i] += rex_C * (1.0 - cpmg_frqs[i] * tanh(quart_kC / cpmg_frqs[i]) / quart_kC) 
109