- Synopsis
- Defaults
- Keyword arguments
- The sphere (isotropic diffusion)
- The spheroid (axially symmetric diffusion)
- The ellipsoid (rhombic diffusion)
- Units
- Prompt examples

diffusion_tensor.init

Initialise the diffusion tensor.

diffusion_tensor.init(params=None, time_scale=1.0, d_scale=1.0, angle_units=`deg', param_types=0, spheroid_type=None, fixed=True)

params: The diffusion tensor data.

time_scale: The correlation time scaling value.

d_scale: The diffusion tensor eigenvalue scaling value.

angle_units: The units for the angle parameters.

param_types: A flag to select different parameter combinations.

spheroid_type: A string which, if supplied together with spheroid parameters, will restrict the tensor to either being ``oblate`' or ``prolate`'.

fixed: A flag specifying whether the diffusion tensor is fixed or can be optimised.

When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal,
=
=
. In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are undefined. Therefore solely a single geometric parameter, either *τ*_{m} or
, can fully and sufficiently parameterise the diffusion tensor. The correlation function for the global rotational diffusion is

1 - tau / tm C(tau) = - e , 5

To select isotropic diffusion, the parameter should be a single floating point number. The number is the value of the isotropic global correlation time, *τ*_{m}, in seconds. To specify the time in nanoseconds, set the time scale to 1e-9. Alternative parameters can be used by changing the ``param_types`' flag to the following integers

**0 -**- {tm} (Default),
**1 -**- {Diso},

where

- 1 /
*τ*_{m}= 6 .

When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses as a spheroid. Four pieces of information are required to specify this tensor, the two geometric parameters,
and
, and the two orientational parameters, the polar angle *θ* and the azimuthal angle *φ* describing the orientation of the axis of symmetry. The correlation function of the global diffusion is

_1_ 1 \ - tau / tau_i C(tau) = - > ci . e , 5 /__ i=-1

where

- c-1 = 1/4 (3
*δ*_{z}ˆ2 - 1)ˆ2, - c0 = 3
*δ*_{z}ˆ2 (1 -*δ*_{z}ˆ2), - c1 = 3/4 (
*δ*_{z}ˆ2 - 1)ˆ2,

and

- 1 /
*τ*-1 = 6 - 2 , - 1 /
*τ*0 = 6 - , - 1 /
*τ*1 = 6 + 2 .

The direction cosine *δ*_{z} is defined as the cosine of the angle *α* between the XH bond vector and the unique axis of the diffusion tensor.

To select axially symmetric anisotropic diffusion, the parameters should be a tuple of floating point numbers of length four. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, ``param_types`', are

**0 -**- {
*τ*_{m}, ,*θ*,*φ*} (Default), **1 -**- {
,
,
*θ*,*φ*}, **2 -**- {
*τ*_{m}, ,*θ*,*φ*}, **3 -**- {
,
,
*θ*,*φ*}, **4 -**- {
,
,
*θ*,*φ*},

where

*τ*_{m}= 1 / 6 ,- = 1/3 ( + 2 ),
- = - ,
- = / .

The spherical angles {*θ*, *φ*} orienting the unique axis of the diffusion tensor within the PDB frame are defined between

- 0 ≤
*θ*≤*π*, - 0 ≤
*φ*≤ 2*π*,

while the angle *α* which is the angle between this axis and the given XH bond vector is defined between

- 0 ≤
*α*≤ 2*π*.

The spheroid type should be ``oblate`', ``prolate`', or None. This will be ignored if the diffusion tensor is not axially symmetric. If ``oblate`' is given, then the constraint
≤ 0 is used while if ``prolate`' is given, then the constraint
≥ 0 is used. If nothing is supplied, then
will be allowed to have any values. To prevent minimisation of diffusion tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised, thereby partitioning the two minima into the two subspaces along the boundary
= 0.

When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters
,
, and
representing the isotropic, anisotropic, and rhombic components of the tensor, and the three Euler angles *α*, *β*, and *γ* orienting the tensor within the PDB frame. The correlation function is

_2_ 1 \ - tau / tau_i C(tau) = - > ci . e , 5 /__ i=-2

where the weights on the exponentials are

- c-2 = 1/4 (d + e),
- c-1 = 3
*δ*_{y}ˆ2*δ*_{z}ˆ2, - c0 = 3
*δ*_{x}ˆ2*δ*_{z}ˆ2, - c1 = 3
*δ*_{x}ˆ2*δ*_{y}ˆ2, - c2 = 1/4 (d + e).

Let

- = sqrt(1 + 3 ),

then

- d = 3 (
*δ*_{x}ˆ4 +*δ*_{y}ˆ4 +*δ*_{z}ˆ4) - 1, - e = - 1 /
((1 + 3
)(
*δ*_{x}ˆ4 + 2*δ*_{y}ˆ2*δ*_{z}ˆ2) + (1 - 3 )(*δ*_{y}ˆ4 + 2*δ*_{x}ˆ2*δ*_{z}ˆ2) - 2(*δ*_{z}ˆ4 + 2*δ*_{x}ˆ2*δ*_{y}ˆ2)).

- 1 /
*τ*-2 = 6 - 2 . , - 1 /
*τ*-1 = 6 - (1 + 3 ), - 1 /
*τ*0 = 6 - (1 - 3 ), - 1 /
*τ*1 = 6 + 2 , - 1 /
*τ*1 = 6 + 2 . .

The three direction cosines *δ*_{x}, *δ*_{y}, and *δ*_{z} are the coordinates of a unit vector parallel to the XH bond vector. Hence the unit vector is [*δ*_{x}, *δ*_{y}, *δ*_{z}].

To select fully anisotropic diffusion, the parameters should be a tuple of length six. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, ``param_types`', are

**0 -**- {
*τ*_{m}, , ,*α*,*β*,*γ*} (Default), **1 -**- {
,
,
,
*α*,*β*,*γ*}, **2 -**- {
,
,
,
*α*,*β*,*γ*}, **3 -**- {Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},

where

*τ*_{m}= 1 / 6 ,- = 1/3 ( + + ),
- = - ( + )/2,
- = ( - )/2 .

The angles *α*, *β*, and *γ* are the Euler angles describing the diffusion tensor within the PDB frame. These angles are defined using the z-y-z axis rotation notation where *α* is the initial rotation angle around the z-axis, *β* is the rotation angle around the y-axis, and *γ* is the final rotation around the z-axis again. The angles are defined between

- 0 ≤
*α*≤ 2*π*, - 0 ≤
*β*≤*π*, - 0 ≤
*γ*≤ 2*π*.

Within the PDB frame, the XH bond vector is described using the spherical angles *θ* and *φ* where *θ* is the polar angle and *φ* is the azimuthal angle defined between

- 0 ≤
*θ*≤*π*, - 0 ≤
*φ*≤ 2*π*.

When param_types is set to 3, then the elements of the diffusion tensor matrix defined within the PDB frame can be supplied.

The correlation time scaling value should be a floating point number. The only parameter affected by this value is *τ*_{m}.

The diffusion tensor eigenvalue scaling value should also be a floating point number. Parameters affected by this value are , , , , , , and . Significantly, is not affected.

The units for the angle parameters should be either ``deg`' or ``rad`'. Parameters affected are *θ*, *φ*, *α*, *β*, and *γ*.

To set an isotropic diffusion tensor with a correlation time of 10 ns, type:

[numbers=none] relax> diffusion_tensor.init(10e-9)

[numbers=none] relax> diffusion_tensor.init(params=10e-9)

[numbers=none] relax> diffusion_tensor.init(10.0, 1e-9)

[numbers=none] relax> diffusion_tensor.init(params=10.0, time_scale=1e-9, fixed=True)

To select axially symmetric diffusion with a *τ*_{m} value of 8.5 ns,
of 1.1, *θ* value of 20 degrees, and *φ* value of 20 degrees, type:

[numbers=none] relax> diffusion_tensor.init((8.5e-9, 1.1, 20.0, 20.0), param_types=2)

To select a spheroid diffusion tensor with a
value of 1.698e7,
value of 1.417e7, *θ* value of 67.174 degrees, and *φ* value of -83.718 degrees, type one of:

[numbers=none] relax> diffusion_tensor.init((1.698e7, 1.417e7, 67.174, -83.718), param_types=3)

[numbers=none] relax> diffusion_tensor.init(params=(1.698e7, 1.417e7, 67.174, -83.718), param_types=3)

[numbers=none] relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)

[numbers=none] relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 67.174, -83.718), param_types=3, d_scale=1e8)

[numbers=none] relax> diffusion_tensor.init((1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad')

[numbers=none] relax> diffusion_tensor.init(params=(1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=3, d_scale=1e8, angle_units='rad', fixed=True)

To select ellipsoidal diffusion, type:

[numbers=none] relax> diffusion_tensor.init((1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=2)