lib.dispersion.ns

1 ############################################################################### 2 # # 3 # Copyright (C) 2000-2001 Nikolai Skrynnikov # 4 # Copyright (C) 2000-2001 Martin Tollinger # 5 # Copyright (C) 2013 Mathilde Lescanne # 6 # Copyright (C) 2013 Dominique Marion # 7 # Copyright (C) 2013 Edward d'Auvergne # 8 # Copyright (C) 2014 Troels E. Linnet # 9 # # 10 # This file is part of the program relax (http://www.nmr-relax.com). # 11 # # 12 # This program is free software: you can redistribute it and/or modify # 13 # it under the terms of the GNU General Public License as published by # 14 # the Free Software Foundation, either version 3 of the License, or # 15 # (at your option) any later version. # 16 # # 17 # This program is distributed in the hope that it will be useful, # 18 # but WITHOUT ANY WARRANTY; without even the implied warranty of # 19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # 20 # GNU General Public License for more details. # 21 # # 22 # You should have received a copy of the GNU General Public License # 23 # along with this program. If not, see <http://www.gnu.org/licenses/>. # 24 # # 25 ############################################################################### 26 27 # Module docstring. 28 """A collection of functions for generating the relaxation matrices for the numerical solutions. 29 30 These are for the numerical solutions to the Bloch-McConnell equations for relaxation dispersion. 31 """ 32 33 # Python module imports. 34 from math import cos, sin, pi 35 from numpy import array, float64, matrix 36 37

38 -def r180x_2d(flip=pi):

39 """The 2D rotation matrix for an imperfect X-axis pi-pulse. 40 41 @keyword flip: The X-axis pi-pulse flip angle (in rad). This is currently unused, hence perfect pi-pulses are assumed. 42 @type flip: float 43 @return: The 2D rotational matrix. 44 @rtype: numpy rank-2, 4D array 45 """ 46 47 # Build the matrix. 48 R = array([ 49 [ 1.0, 0.0, 0.0, 0.0], 50 [ 0.0, -1.0, 0.0, 0.0], 51 [ 0.0, 0.0, 1.0, 0.0], 52 [ 0.0, 0.0, 0.0, -1.0] 53 ], float64) 54 55 # Return the matrix. 56 return R

57 58

59 -def r180x_3d(flip=pi):

60 """The 3D rotation matrix for an imperfect X-axis pi-pulse. 61 62 @keyword flip: The X-axis pi-pulse flip angle (in rad). 63 @type flip: float 64 @return: The 3D rotational matrix. 65 @rtype: numpy rank-2, 7D array 66 """ 67 68 # Replicated calculations. 69 ct = cos(flip) 70 st = sin(flip) 71 72 # Build the matrix. 73 R = array([ 74 [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], 75 [0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0], 76 [0.0, 0.0, ct, -st, 0.0, 0.0, 0.0], 77 [0.0, 0.0, st, ct, 0.0, 0.0, 0.0], 78 [0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0], 79 [0.0, 0.0, 0.0, 0.0, 0.0, ct, -st], 80 [0.0, 0.0, 0.0, 0.0, 0.0, st, ct] 81 ], float64) 82 83 # Return the matrix. 84 return R

85 86

87 -def rcpmg_2d(R2A=None, R2B=None, dw=None, k_AB=None, k_BA=None):

88 """Definition of the 2D exchange matrix. 89 90 @keyword R2A: The transverse, spin-spin relaxation rate for state A. 91 @type R2A: float 92 @keyword R2B: The transverse, spin-spin relaxation rate for state B. 93 @type R2B: float 94 @keyword dw: The chemical exchange difference between states A and B in rad/s. 95 @type dw: float 96 @keyword k_AB: The forward exchange rate from state A to state B. 97 @type k_AB: float 98 @keyword k_BA: The reverse exchange rate from state B to state A. 99 @type k_BA: float 100 @return: The relaxation matrix. 101 @rtype: numpy rank-2, 4D array 102 """ 103 104 # The omega frequencies for states A and B (state A is assumed to be at zero frequency). 105 wA = 0.0 106 wB = wA + dw 107 108 # Create the matrix. 109 temp = matrix([ 110 [ -R2A-k_AB, -wA, k_BA, 0.0], 111 [ wA, -R2A-k_AB, 0.0, k_BA], 112 [ k_AB, 0.0, -R2B-k_BA, -wB], 113 [ 0.0, k_AB, wB, -R2B-k_BA] 114 ]) 115 116 # Return the matrix. 117 return temp

118 119

120 -def rcpmg_3d(R1A=None, R1B=None, R2A=None, R2B=None, pA=None, pB=None, dw=None, k_AB=None, k_BA=None):

121 """Definition of the 3D exchange matrix. 122 123 @keyword R1A: The longitudinal, spin-lattice relaxation rate for state A. 124 @type R1A: float 125 @keyword R1B: The longitudinal, spin-lattice relaxation rate for state B. 126 @type R1B: float 127 @keyword R2A: The transverse, spin-spin relaxation rate for state A. 128 @type R2A: float 129 @keyword R2B: The transverse, spin-spin relaxation rate for state B. 130 @type R2B: float 131 @keyword pA: The population of state A. 132 @type pA: float 133 @keyword pB: The population of state B. 134 @type pB: float 135 @keyword dw: The chemical exchange difference between states A and B in rad/s. 136 @type dw: float 137 @keyword k_AB: The forward exchange rate from state A to state B. 138 @type k_AB: float 139 @keyword k_BA: The reverse exchange rate from state B to state A. 140 @type k_BA: float 141 @return: The relaxation matrix. 142 @rtype: numpy rank-2, 7D array 143 """ 144 145 # The omega frequencies for states A and B (state A is assumed to be at zero frequency). 146 wA = 0.0 147 wB = dw 148 149 # Create the matrix. 150 temp = matrix([ 151 [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], 152 [ 0.0, -R2A-k_AB, -wA, 0.0, k_BA, 0.0, 0.0], 153 [ 0.0, wA, -R2A-k_AB, 0.0, 0.0, k_BA, 0.0], 154 [ 2.0*R1A*pA, 0.0, 0.0, -R1A-k_AB, 0.0, 0.0, k_BA], 155 [ 0.0, k_AB, 0.0, 0.0, -R2B-k_BA, -wB, 0.0], 156 [ 0.0, 0.0, k_AB, 0.0, wB, -R2B-k_BA, 0.0], 157 [ 2.0*R1B*pB, 0.0, 0.0, k_AB, 0.0, 0.0, -R1B-k_BA] 158 ]) 159 160 # Return the matrix. 161 return temp

162 163

164 -def rmmq_2site(matrix=None, R20A=None, R20B=None, dw=None, k_AB=None, k_BA=None):

165 """The Bloch-McConnell matrix for 2-site exchange. 166 167 @keyword matrix: The matrix to populate. 168 @type matrix: numpy rank-2, 2D complex128 array 169 @keyword R20A: The transverse, spin-spin relaxation rate for state A. 170 @type R20A: float 171 @keyword R20B: The transverse, spin-spin relaxation rate for state B. 172 @type R20B: float 173 @keyword dw: The combined chemical exchange difference parameters between states A and B in rad/s. This can be any combination of dw and dwH. 174 @type dw: float 175 @keyword k_AB: The rate of exchange from site A to B (rad/s). 176 @type k_AB: float 177 @keyword k_BA: The rate of exchange from site B to A (rad/s). 178 @type k_BA: float 179 """ 180 181 # Fill in the elements. 182 matrix[0, 0] = -k_AB - R20A 183 matrix[0, 1] = k_BA 184 matrix[1, 0] = k_AB 185 matrix[1, 1] = -k_BA + 1.j*dw - R20B

186 187

188 -def rmmq_3site(matrix=None, R20A=None, R20B=None, R20C=None, dw_AB=None, dw_AC=None, k_AB=None, k_BA=None, k_BC=None, k_CB=None, k_AC=None, k_CA=None):

189 """The Bloch-McConnell matrix for 3-site exchange. 190 191 @keyword matrix: The matrix to populate. 192 @type matrix: numpy rank-2, 3D complex128 array 193 @keyword R20A: The transverse, spin-spin relaxation rate for state A. 194 @type R20A: float 195 @keyword R20B: The transverse, spin-spin relaxation rate for state B. 196 @type R20B: float 197 @keyword R20C: The transverse, spin-spin relaxation rate for state C. 198 @type R20C: float 199 @keyword dw_AB: The combined chemical exchange difference parameters between states A and B in rad/s. This can be any combination of dw and dwH. 200 @type dw_AB: float 201 @keyword dw_AC: The combined chemical exchange difference parameters between states A and C in rad/s. This can be any combination of dw and dwH. 202 @type dw_AC: float 203 @keyword k_AB: The rate of exchange from site A to B (rad/s). 204 @type k_AB: float 205 @keyword k_BA: The rate of exchange from site B to A (rad/s). 206 @type k_BA: float 207 @keyword k_BC: The rate of exchange from site B to C (rad/s). 208 @type k_BC: float 209 @keyword k_CB: The rate of exchange from site C to B (rad/s). 210 @type k_CB: float 211 @keyword k_AC: The rate of exchange from site A to C (rad/s). 212 @type k_AC: float 213 @keyword k_CA: The rate of exchange from site C to A (rad/s). 214 @type k_CA: float 215 """ 216 217 # The first row. 218 matrix[0, 0] = -k_AB - k_AC - R20A 219 matrix[0, 1] = k_BA 220 matrix[0, 2] = k_CA 221 222 # The second row. 223 matrix[1, 0] = k_AB 224 matrix[1, 1] = -k_BA - k_BC + 1.j*dw_AB - R20B 225 matrix[1, 2] = k_CB 226 227 # The third row. 228 matrix[2, 0] = k_AC 229 matrix[2, 1] = k_BC 230 matrix[2, 2] = -k_CB - k_CA + 1.j*dw_AC - R20C

231 232

233 -def rr1rho_3d_2site(matrix=None, R1=None, r1rho_prime=None, pA=None, pB=None, wA=None, wB=None, w1=None, k_AB=None, k_BA=None):

234 """Definition of the 3D exchange matrix. 235 236 This code originates from the funNumrho.m file from the Skrynikov & Tollinger code (the sim_all.tar file https://web.archive.org/web/https://gna.org/support/download.php?file_id=18404 attached to https://web.archive.org/web/https://gna.org/task/?7712#comment5). 237 238 239 @keyword matrix: The matrix to fill. 240 @type matrix: numpy rank-2 6D array 241 @keyword R1: The longitudinal, spin-lattice relaxation rate. 242 @type R1: float 243 @keyword r1rho_prime: The R1rho transverse, spin-spin relaxation rate in the absence of exchange. 244 @type r1rho_prime: float 245 @keyword pA: The population of state A. 246 @type pA: float 247 @keyword pB: The population of state B. 248 @type pB: float 249 @keyword wA: The chemical shift offset of state A from the spin-lock. 250 @type wA: float 251 @keyword wB: The chemical shift offset of state A from the spin-lock. 252 @type wB: float 253 @keyword w1: The spin-lock field strength in rad/s. 254 @type w1: float 255 @keyword k_AB: The forward exchange rate from state A to state B. 256 @type k_AB: float 257 @keyword k_BA: The reverse exchange rate from state B to state A. 258 @type k_BA: float 259 """ 260 261 # The AB auto-block. 262 matrix[0, 0] = -r1rho_prime - k_AB 263 matrix[0, 1] = -wA 264 matrix[1, 0] = wA 265 matrix[1, 1] = -r1rho_prime - k_AB 266 matrix[1, 2] = -w1 267 matrix[2, 1] = w1 268 matrix[2, 2] = -R1 - k_AB 269 270 # The BA auto-block. 271 matrix[3, 3] = -r1rho_prime - k_BA 272 matrix[3, 4] = -wB 273 matrix[4, 3] = wB 274 matrix[4, 4] = -r1rho_prime - k_BA 275 matrix[4, 5] = -w1 276 matrix[5, 4] = w1 277 matrix[5, 5] = -R1 - k_BA 278 279 # The AB cross-block. 280 matrix[0, 3] = k_BA 281 matrix[1, 4] = k_BA 282 matrix[2, 5] = k_BA 283 matrix[3, 0] = k_AB 284 matrix[4, 1] = k_AB 285 matrix[5, 2] = k_AB

286 287

288 -def rr1rho_3d_3site(matrix=None, R1=None, r1rho_prime=None, pA=None, pB=None, pC=None, wA=None, wB=None, wC=None, w1=None, k_AB=None, k_BA=None, k_BC=None, k_CB=None, k_AC=None, k_CA=None):

289 """Definition of the 3D exchange matrix. 290 291 @keyword matrix: The matrix to fill. 292 @type matrix: numpy rank-2 9D array 293 @keyword R1: The longitudinal, spin-lattice relaxation rate. 294 @type R1: float 295 @keyword r1rho_prime: The R1rho transverse, spin-spin relaxation rate in the absence of exchange. 296 @type r1rho_prime: float 297 @keyword pA: The population of state A. 298 @type pA: float 299 @keyword pB: The population of state B. 300 @type pB: float 301 @keyword pC: The population of state C. 302 @type pC: float 303 @keyword wA: The chemical shift offset of state A from the spin-lock. 304 @type wA: float 305 @keyword wB: The chemical shift offset of state B from the spin-lock. 306 @type wB: float 307 @keyword wC: The chemical shift offset of state C from the spin-lock. 308 @type wC: float 309 @keyword w1: The spin-lock field strength in rad/s. 310 @type w1: float 311 @keyword k_AB: The forward exchange rate from state A to state B. 312 @type k_AB: float 313 @keyword k_BA: The reverse exchange rate from state B to state A. 314 @type k_BA: float 315 @keyword k_BC: The forward exchange rate from state B to state C. 316 @type k_BC: float 317 @keyword k_CB: The reverse exchange rate from state C to state B. 318 @type k_CB: float 319 @keyword k_AC: The forward exchange rate from state A to state C. 320 @type k_AC: float 321 @keyword k_CA: The reverse exchange rate from state C to state A. 322 @type k_CA: float 323 """ 324 325 # The AB auto-block. 326 matrix[0, 0] = -r1rho_prime - k_AB - k_AC 327 matrix[0, 1] = -wA 328 matrix[1, 0] = wA 329 matrix[1, 1] = -r1rho_prime - k_AB - k_AC 330 matrix[1, 2] = -w1 331 matrix[2, 1] = w1 332 matrix[2, 2] = -R1 - k_AB - k_AC 333 334 # The AC auto-block. 335 matrix[3, 3] = -r1rho_prime - k_BA - k_BC 336 matrix[3, 4] = -wB 337 matrix[4, 3] = wB 338 matrix[4, 4] = -r1rho_prime - k_BA - k_BC 339 matrix[4, 5] = -w1 340 matrix[5, 4] = w1 341 matrix[5, 5] = -R1 - k_BA - k_BC 342 343 # The BC auto-block. 344 matrix[6, 6] = -r1rho_prime - k_CA - k_CB 345 matrix[6, 7] = -wC 346 matrix[7, 6] = wC 347 matrix[7, 7] = -r1rho_prime - k_CA - k_CB 348 matrix[7, 8] = -w1 349 matrix[8, 7] = w1 350 matrix[8, 8] = -R1 - k_CA - k_CB 351 352 # The AB cross-block. 353 matrix[0, 3] = k_BA 354 matrix[1, 4] = k_BA 355 matrix[2, 5] = k_BA 356 matrix[3, 0] = k_AB 357 matrix[4, 1] = k_AB 358 matrix[5, 2] = k_AB 359 360 # The AC cross-block. 361 matrix[0, 6] = k_CA 362 matrix[1, 7] = k_CA 363 matrix[2, 8] = k_CA 364 matrix[6, 0] = k_AC 365 matrix[7, 1] = k_AC 366 matrix[8, 2] = k_AC 367 368 # The BC cross-block. 369 matrix[3, 6] = k_CB 370 matrix[4, 7] = k_CB 371 matrix[5, 8] = k_CB 372 matrix[6, 3] = k_BC 373 matrix[7, 4] = k_BC 374 matrix[8, 5] = k_BC

375

Source Code for Module lib.dispersion.ns_matrices