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

37 -def r180x_2d(flip=pi):

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

56 57

58 -def r180x_3d(flip=pi):

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

84 85

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

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

117 118

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

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

161 162

163 -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):

164 """Definition of the 3D exchange matrix. 165 166 @keyword matrix: The matrix to fill. 167 @type matrix: numpy rank-2 9D array 168 @keyword R1: The longitudinal, spin-lattice relaxation rate. 169 @type R1: float 170 @keyword r1rho_prime: The R1rho transverse, spin-spin relaxation rate in the absence of exchange. 171 @type r1rho_prime: float 172 @keyword pA: The population of state A. 173 @type pA: float 174 @keyword pB: The population of state B. 175 @type pB: float 176 @keyword pC: The population of state C. 177 @type pC: float 178 @keyword wA: The chemical shift offset of state A from the spin-lock. 179 @type wA: float 180 @keyword wB: The chemical shift offset of state B from the spin-lock. 181 @type wB: float 182 @keyword wC: The chemical shift offset of state C from the spin-lock. 183 @type wC: float 184 @keyword w1: The spin-lock field strength in rad/s. 185 @type w1: float 186 @keyword k_AB: The forward exchange rate from state A to state B. 187 @type k_AB: float 188 @keyword k_BA: The reverse exchange rate from state B to state A. 189 @type k_BA: float 190 @keyword k_BC: The forward exchange rate from state B to state C. 191 @type k_BC: float 192 @keyword k_CB: The reverse exchange rate from state C to state B. 193 @type k_CB: float 194 @keyword k_AC: The forward exchange rate from state A to state C. 195 @type k_AC: float 196 @keyword k_CA: The reverse exchange rate from state C to state A. 197 @type k_CA: float 198 """ 199 200 # The AB auto-block. 201 matrix[0, 0] = -r1rho_prime - k_AB - k_AC 202 matrix[0, 1] = -wA 203 matrix[1, 0] = wA 204 matrix[1, 1] = -r1rho_prime - k_AB - k_AC 205 matrix[1, 2] = -w1 206 matrix[2, 1] = w1 207 matrix[2, 2] = -R1 - k_AB - k_AC 208 209 # The AC auto-block. 210 matrix[3, 3] = -r1rho_prime - k_BA - k_BC 211 matrix[3, 4] = -wB 212 matrix[4, 3] = wB 213 matrix[4, 4] = -r1rho_prime - k_BA - k_BC 214 matrix[4, 5] = -w1 215 matrix[5, 4] = w1 216 matrix[5, 5] = -R1 - k_BA - k_BC 217 218 # The BC auto-block. 219 matrix[6, 6] = -r1rho_prime - k_CA - k_CB 220 matrix[6, 7] = -wC 221 matrix[7, 6] = wC 222 matrix[7, 7] = -r1rho_prime - k_CA - k_CB 223 matrix[7, 8] = -w1 224 matrix[8, 7] = w1 225 matrix[8, 8] = -R1 - k_CA - k_CB 226 227 # The AB cross-block. 228 matrix[0, 3] = k_BA 229 matrix[1, 4] = k_BA 230 matrix[2, 5] = k_BA 231 matrix[3, 0] = k_AB 232 matrix[4, 1] = k_AB 233 matrix[5, 2] = k_AB 234 235 # The AC cross-block. 236 matrix[0, 6] = k_CA 237 matrix[1, 7] = k_CA 238 matrix[2, 8] = k_CA 239 matrix[6, 0] = k_AC 240 matrix[7, 1] = k_AC 241 matrix[8, 2] = k_AC 242 243 # The BC cross-block. 244 matrix[3, 6] = k_CB 245 matrix[4, 7] = k_CB 246 matrix[5, 8] = k_CB 247 matrix[6, 3] = k_BC 248 matrix[7, 4] = k_BC 249 matrix[8, 5] = k_BC

250 251

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

253 """Definition of the 3D exchange matrix. 254 255 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). 256 257 258 @keyword matrix: The matrix to fill. 259 @type matrix: numpy rank-2 6D array 260 @keyword R1: The longitudinal, spin-lattice relaxation rate. 261 @type R1: float 262 @keyword r1rho_prime: The R1rho transverse, spin-spin relaxation rate in the absence of exchange. 263 @type r1rho_prime: float 264 @keyword pA: The population of state A. 265 @type pA: float 266 @keyword pB: The population of state B. 267 @type pB: float 268 @keyword wA: The chemical shift offset of state A from the spin-lock. 269 @type wA: float 270 @keyword wB: The chemical shift offset of state A from the spin-lock. 271 @type wB: float 272 @keyword w1: The spin-lock field strength in rad/s. 273 @type w1: float 274 @keyword k_AB: The forward exchange rate from state A to state B. 275 @type k_AB: float 276 @keyword k_BA: The reverse exchange rate from state B to state A. 277 @type k_BA: float 278 """ 279 280 # The AB auto-block. 281 matrix[0, 0] = -r1rho_prime - k_AB 282 matrix[0, 1] = -wA 283 matrix[1, 0] = wA 284 matrix[1, 1] = -r1rho_prime - k_AB 285 matrix[1, 2] = -w1 286 matrix[2, 1] = w1 287 matrix[2, 2] = -R1 - k_AB 288 289 # The BA auto-block. 290 matrix[3, 3] = -r1rho_prime - k_BA 291 matrix[3, 4] = -wB 292 matrix[4, 3] = wB 293 matrix[4, 4] = -r1rho_prime - k_BA 294 matrix[4, 5] = -w1 295 matrix[5, 4] = w1 296 matrix[5, 5] = -R1 - k_BA 297 298 # The AB cross-block. 299 matrix[0, 3] = k_BA 300 matrix[1, 4] = k_BA 301 matrix[2, 5] = k_BA 302 matrix[3, 0] = k_AB 303 matrix[4, 1] = k_AB 304 matrix[5, 2] = k_AB

305

Source Code for Module lib.dispersion.ns_matrices