1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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
34 from math import cos, sin, pi
35 from numpy import array, float64, matrix
36
37
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
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
56 return R
57
58
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
69 ct = cos(flip)
70 st = sin(flip)
71
72
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
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
105 wA = 0.0
106 wB = wA + dw
107
108
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
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
146 wA = 0.0
147 wB = dw
148
149
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
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
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
218 matrix[0, 0] = -k_AB - k_AC - R20A
219 matrix[0, 1] = k_BA
220 matrix[0, 2] = k_CA
221
222
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
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
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
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
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
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
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
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
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
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
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