prompt.diffusion

35 """Class for manipulating the diffusion tensor.""" 36

37 - def copy(self, pipe_from=None, pipe_to=None):

38 """Function for copying diffusion tensor data from one data pipe to another. 39 40 Keyword Arguments 41 ~~~~~~~~~~~~~~~~~ 42 43 pipe_from: The name of the data pipe to copy the diffusion tensor data from. 44 45 pipe_to: The name of the data pipe to copy the diffusion tensor data to. 46 47 48 Description 49 ~~~~~~~~~~~ 50 51 This function will copy the diffusion tensor data between data pipes. The destination data 52 pipe must not contain any diffusion tensor data. If the pipe_from or pipe_to arguments are 53 not supplied, then both will default to the current data pipe (hence giving one argument is 54 essential). 55 56 57 Examples 58 ~~~~~~~~ 59 60 To copy the diffusion tensor from the data pipe 'm1' to the current data pipe, type: 61 62 relax> diffusion_tensor.copy('m1') 63 relax> diffusion_tensor.copy(pipe_from='m1') 64 65 66 To copy the diffusion tensor from the current data pipe to the data pipe 'm9', type: 67 68 relax> diffusion_tensor.copy(pipe_to='m9') 69 70 71 To copy the diffusion tensor from the data pipe 'm1' to 'm2', type: 72 73 relax> diffusion_tensor.copy('m1', 'm2') 74 relax> diffusion_tensor.copy(pipe_from='m1', pipe_to='m2') 75 """ 76 77 # Function intro text. 78 if self._exec_info.intro: 79 text = self._exec_info.ps3 + "diffusion_tensor.copy(" 80 text = text + "pipe_from=" + repr(pipe_from) 81 text = text + ", pipe_to=" + repr(pipe_to) + ")" 82 print(text) 83 84 # The argument checks. 85 arg_check.is_str(pipe_from, 'pipe from', can_be_none=True) 86 arg_check.is_str(pipe_to, 'pipe to', can_be_none=True) 87 88 # Both pipe arguments cannot be None. 89 if pipe_from == None and pipe_to == None: 90 raise RelaxError("The pipe_from and pipe_to arguments cannot both be set to None.") 91 92 # Execute the functional code. 93 diffusion_tensor.copy(pipe_from=pipe_from, pipe_to=pipe_to)

94 95

96 - def delete(self):

97 """Function for deleting diffusion tensor data. 98 99 Description 100 ~~~~~~~~~~~ 101 102 This function will delete all diffusion tensor data from the current data pipe. 103 """ 104 105 # Function intro text. 106 if self._exec_info.intro: 107 text = self._exec_info.ps3 + "diffusion_tensor.delete()" 108 print(text) 109 110 # Execute the functional code. 111 diffusion_tensor.delete()

112 113

114 - def display(self):

115 """Function for displaying the diffusion tensor information.""" 116 117 # Function intro text. 118 if self._exec_info.intro: 119 text = self._exec_info.ps3 + "diffusion_tensor.display()" 120 print(text) 121 122 # Execute the functional code. 123 diffusion_tensor.display()

124 125

126 - def init(self, params=None, time_scale=1.0, d_scale=1.0, angle_units='deg', param_types=0, spheroid_type=None, fixed=True):

127 """Function for initialising the diffusion tensor. 128 129 Keyword Arguments 130 ~~~~~~~~~~~~~~~~~ 131 132 params: The diffusion tensor data. 133 134 time_scale: The correlation time scaling value. 135 136 d_scale: The diffusion tensor eigenvalue scaling value. 137 138 angle_units: The units for the angle parameters. 139 140 param_types: A flag to select different parameter combinations. 141 142 spheroid_type: A string which, if supplied together with spheroid parameters, will restrict 143 the tensor to either being 'oblate' or 'prolate'. 144 145 fixed: A flag specifying whether the diffusion tensor is fixed or can be optimised. 146 147 148 The sphere (isotropic diffusion) 149 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 151 When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are 152 equal, Dx = Dy = Dz. In this case, the orientation of the XH bond vector within the 153 diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are 154 undefined. Therefore solely a single geometric parameter, either tm or Diso, can fully and 155 sufficiently parameterise the diffusion tensor. The correlation function for the global 156 rotational diffusion is 157 158 ----- 159 1 - tau / tm 160 C(tau) = - e , 161 5 162 ----- 163 164 To select isotropic diffusion, the parameters argument should be a single floating point 165 number. The number is the value of the isotropic global correlation time, tm, in seconds. 166 To specify the time in nanoseconds, set the 'time_scale' argument to 1e-9. Alternative 167 parameters can be used by changing the 'param_types' flag to the following integers 168 169 0: {tm} (Default), 170 1: {Diso}, 171 172 where 173 174 1 / tm = 6Diso. 175 176 177 The spheroid (axially symmetric diffusion) 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 179 180 When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses 181 as a spheroid. Four pieces of information are required to specify this tensor, the two 182 geometric parameters, Diso and Da, and the two orientational parameters, the polar angle 183 theta and the azimuthal angle phi describing the orientation of the axis of symmetry. The 184 correlation function of the global diffusion is 185 186 ----- 187 _1_ 188 1 \ - tau / tau_i 189 C(tau) = - > ci . e , 190 5 /__ 191 i=-1 192 ----- 193 194 where 195 196 c-1 = 1/4 (3 dz^2 - 1)^2, 197 c0 = 3 dz^2 (1 - dz^2), 198 c1 = 3/4 (dz^2 - 1)^2, 199 200 and 201 202 1 / tau -1 = 6Diso - 2Da, 203 1 / tau 0 = 6Diso - Da, 204 1 / tau 1 = 6Diso + 2Da. 205 206 The direction cosine dz is defined as the cosine of the angle alpha between the XH bond 207 vector and the unique axis of the diffusion tensor. 208 209 To select axially symmetric anisotropic diffusion, the parameters argument should be a tuple 210 of floating point numbers of length four. A tuple is a type of data structure enclosed in 211 round brackets, the elements of which are separated by commas. Alternative sets of 212 parameters, 'param_types', are 213 214 0: {tm, Da, theta, phi} (Default), 215 1: {Diso, Da, theta, phi}, 216 2: {tm, Dratio, theta, phi}, 217 3: {Dpar, Dper, theta, phi}, 218 4: {Diso, Dratio, theta, phi}, 219 220 where 221 222 tm = 1 / 6Diso, 223 Diso = 1/3 (Dpar + 2Dper), 224 Da = Dpar - Dper, 225 Dratio = Dpar / Dper. 226 227 The spherical angles {theta, phi} orienting the unique axis of the diffusion tensor within 228 the PDB frame are defined between 229 230 0 <= theta <= pi, 231 0 <= phi <= 2pi, 232 233 while the angle alpha which is the angle between this axis and the given XH bond vector is 234 defined between 235 236 0 <= alpha <= 2pi. 237 238 The 'spheroid_type' argument should be 'oblate', 'prolate', or None. The argument will be 239 ignored if the diffusion tensor is not axially symmetric. If 'oblate' is given, then the 240 constraint Da <= 0 is used while if 'prolate' is given, then the constraint Da >= 0 is 241 used. If nothing is supplied, then Da will be allowed to have any values. To prevent 242 minimisation of diffusion tensor parameters in a space with two minima, it is recommended 243 to specify which tensor is to be minimised, thereby partitioning the two minima into the two 244 subspaces along the boundry Da = 0. 245 246 247 The ellipsoid (rhombic diffusion) 248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 249 250 When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as 251 an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. 252 The full tensor is specified by six pieces of information, the three geometric parameters 253 Diso, Da, and Dr representing the isotropic, anisotropic, and rhombic components of the 254 tensor, and the three Euler angles alpha, beta, and gamma orienting the tensor within the 255 PDB frame. The correlation function is 256 257 258 ----- 259 _2_ 260 1 \ - tau / tau_i 261 C(tau) = - > ci . e , 262 5 /__ 263 i=-2 264 ----- 265 266 where the weights on the exponentials are 267 268 c-2 = 1/4 (d + e), 269 c-1 = 3 dy^2 dz^2, 270 c0 = 3 dx^2 dz^2, 271 c1 = 3 dx^2 dy^2, 272 c2 = 1/4 (d + e). 273 274 Let 275 276 R = sqrt(1 + 3Dr), 277 278 then 279 280 d = 3 (dx^4 + dy^4 + dz^4) - 1, 281 e = - 1 / R ((1 + 3Dr)(dx^4 + 2dy^2 dz^2) + (1 - 3Dr)(dy^4 + 2dx^2 dz^2) - 2(dz^4 + 2dx^2 dy^2)). 282 283 The correlation times are 284 285 1 / tau -2 = 6Diso - 2Da . R, 286 1 / tau -1 = 6Diso - Da (1 + 3Dr), 287 1 / tau 0 = 6Diso - Da (1 - 3Dr), 288 1 / tau 1 = 6Diso + 2Da, 289 1 / tau 1 = 6Diso + 2Da . R. 290 291 The three direction cosines dx, dy, and dz are the coordinates of a unit vector parallel to 292 the XH bond vector. Hence the unit vector is [dx, dy, dz]. 293 294 To select fully anisotropic diffusion, the parameters argument should be a tuple of length 295 six. A tuple is a type of data structure enclosed in round brackets, the elements of which 296 are separated by commas. Alternative sets of parameters, 'param_types', are 297 298 0: {tm, Da, Dr, alpha, beta, gamma} (Default), 299 1: {Diso, Da, Dr, alpha, beta, gamma}, 300 2: {Dx, Dy, Dz, alpha, beta, gamma}, 301 3: {Dxx, Dyy, Dzz, Dxy, Dxz, Dyz}, 302 303 where 304 305 tm = 1 / 6Diso, 306 Diso = 1/3 (Dx + Dy + Dz), 307 Da = Dz - (Dx + Dy)/2, 308 Dr = (Dy - Dx)/2Da. 309 310 The angles alpha, beta, and gamma are the Euler angles describing the diffusion tensor 311 within the PDB frame. These angles are defined using the z-y-z axis rotation notation where 312 alpha is the initial rotation angle around the z-axis, beta is the rotation angle around the 313 y-axis, and gamma is the final rotation around the z-axis again. The angles are defined 314 between 315 316 0 <= alpha <= 2pi, 317 0 <= beta <= pi, 318 0 <= gamma <= 2pi. 319 320 Within the PDB frame, the XH bond vector is described using the spherical angles theta and 321 phi where theta is the polar angle and phi is the azimuthal angle defined between 322 323 0 <= theta <= pi, 324 0 <= phi <= 2pi. 325 326 When param_types is set to 3, then the elements of the diffusion tensor matrix defined 327 within the PDB frame can be supplied. 328 329 330 Units 331 ~~~~~ 332 333 The 'time_scale' argument should be a floating point number. The only parameter affected by 334 this value is tm. 335 336 The 'd_scale' argument should also be a floating point number. Parameters affected by this 337 value are Diso, Dpar, Dper, Da, Dx, Dy, and Dz. Significantly, Dr is not affected. 338 339 The 'angle_units' argument should either be the string 'deg' or 'rad'. Parameters affected 340 are theta, phi, alpha, beta, and gamma. 341 342 343 344 Examples 345 ~~~~~~~~ 346 347 To set an isotropic diffusion tensor with a correlation time of 10 ns, type: 348 349 relax> diffusion_tensor.init(10e-9) 350 relax> diffusion_tensor.init(params=10e-9) 351 relax> diffusion_tensor.init(10.0, 1e-9) 352 relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True) 353 354 355 To select axially symmetric diffusion with a tm value of 8.5 ns, Dratio of 1.1, theta value 356 of 20 degrees, and phi value of 20 degrees, type: 357 358 relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2) 359 360 361 To select a spheroid diffusion tensor with a Dpar value of 1.698e7, Dper value of 1.417e7, 362 theta value of 67.174 degrees, and phi value of -83.718 degrees, type one of: 363 364 relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3) 365 relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3) 366 relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, 367 d_scale=1e8) 368 relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, 369 d_scale=1e8) 370 relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, 371 d_scale=1e8, angle_units='rad') 372 relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, 373 d_scale=1e8, angle_units='rad', fixed=True) 374 375 376 To select ellipsoidal diffusion, type: 377 378 relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), 379 param_types=2) 380 """ 381 382 # Function intro text. 383 if self._exec_info.intro: 384 text = self._exec_info.ps3 + "diffusion_tensor.init(" 385 text = text + "params=" + repr(params) 386 text = text + ", time_scale=" + repr(time_scale) 387 text = text + ", d_scale=" + repr(d_scale) 388 text = text + ", angle_units=" + repr(angle_units) 389 text = text + ", param_types=" + repr(param_types) 390 text = text + ", spheroid_type=" + repr(spheroid_type) 391 text = text + ", fixed=" + repr(fixed) + ")" 392 print(text) 393 394 # The argument checks. 395 arg_check.is_num_or_num_tuple(params, 'diffusion parameters', size=[4, 6]) 396 arg_check.is_num(time_scale, 'time scale') 397 arg_check.is_num(d_scale, 'D scale') 398 arg_check.is_str(angle_units, 'angle units') 399 arg_check.is_int(param_types, 'parameter types') 400 arg_check.is_str(spheroid_type, 'spheroid type', can_be_none=True) 401 arg_check.is_bool(fixed, 'fixed flag') 402 403 # Execute the functional code. 404 diffusion_tensor.init(params=params, time_scale=time_scale, d_scale=d_scale, angle_units=angle_units, param_types=param_types, spheroid_type=spheroid_type, fixed=fixed)

Source Code for Module prompt.diffusion_tensor