next up previous contents index pdf_icon_nav.pngrelax_logo_nav.png
Next: domain Up: The list of functions Previous: diffusion_tensor.display   Contents   Index

Subsections


diffusion_tensor.init

Image diff_tensor Image diff_tensor

Synopsis

Initialise the diffusion tensor.

Defaults

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

Keyword arguments

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.

The sphere (isotropic diffusion)

When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal, $\mathfrak{D}_x$ = $\mathfrak{D}_y$ = $\mathfrak{D}_z$. 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 $\mathfrak{D}_{iso}$, 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 $\mathfrak{D}_{iso}$.

The spheroid (axially symmetric diffusion)

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, $\mathfrak{D}_{iso}$ and $\mathfrak{D}_a$, 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 $\mathfrak{D}_{iso}$ - 2 $\mathfrak{D}_a$,
 1 / τ 0 = 6 $\mathfrak{D}_{iso}$ - $\mathfrak{D}_a$,
 1 / τ 1 = 6 $\mathfrak{D}_{iso}$ + 2 $\mathfrak{D}_a$.

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, $\mathfrak{D}_a$, θ, φ} (Default),
1 -
{ $\mathfrak{D}_{iso}$, $\mathfrak{D}_a$, θ, φ},
2 -
{τm, $\mathfrak{D}_{ratio}$, θ, φ},
3 -
{ $\mathfrak{D}_{\scriptscriptstyle \parallel }$, $\mathfrak{D}_{\scriptscriptstyle \perp}$, θ, φ},
4 -
{ $\mathfrak{D}_{iso}$, $\mathfrak{D}_{ratio}$, θ, φ},

where

 τm = 1 / 6 $\mathfrak{D}_{iso}$,
  $\mathfrak{D}_{iso}$ = 1/3 ( $\mathfrak{D}_{\scriptscriptstyle \parallel }$ + 2 $\mathfrak{D}_{\scriptscriptstyle \perp}$),
  $\mathfrak{D}_a$ = $\mathfrak{D}_{\scriptscriptstyle \parallel }$ - $\mathfrak{D}_{\scriptscriptstyle \perp}$,
  $\mathfrak{D}_{ratio}$ = $\mathfrak{D}_{\scriptscriptstyle \parallel }$ / $\mathfrak{D}_{\scriptscriptstyle \perp}$.

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 $\mathfrak{D}_a$ ≤ 0 is used while if `prolate' is given, then the constraint $\mathfrak{D}_a$ ≥ 0 is used. If nothing is supplied, then $\mathfrak{D}_a$ 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 $\mathfrak{D}_a$ = 0.

The ellipsoid (rhombic diffusion)

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 $\mathfrak{D}_{iso}$, $\mathfrak{D}_a$, and $\mathfrak{D}_r$ 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

  $\mathfrak{R}$ = sqrt(1 + 3 $\mathfrak{D}_r$),

then

 d = 3 (δx^4 + δy^4 + δz^4) - 1,
 e = - 1 / $\mathfrak{R}$ ((1 + 3 $\mathfrak{D}_r$)(δx^4 + 2δy^2 δz^2) + (1 - 3 $\mathfrak{D}_r$)(δy^4 + 2δx^2 δz^2) - 2(δz^4 + 2δx^2 δy^2)).

The correlation times are

 1 / τ -2 = 6 $\mathfrak{D}_{iso}$ - 2 $\mathfrak{D}_a$ . $\mathfrak{R}$,
 1 / τ -1 = 6 $\mathfrak{D}_{iso}$ - $\mathfrak{D}_a$ (1 + 3 $\mathfrak{D}_r$),
 1 / τ 0 = 6 $\mathfrak{D}_{iso}$ - $\mathfrak{D}_a$ (1 - 3 $\mathfrak{D}_r$),
 1 / τ 1 = 6 $\mathfrak{D}_{iso}$ + 2 $\mathfrak{D}_a$,
 1 / τ 1 = 6 $\mathfrak{D}_{iso}$ + 2 $\mathfrak{D}_a$ . $\mathfrak{R}$.

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, $\mathfrak{D}_a$, $\mathfrak{D}_r$, α, β, γ} (Default),
1 -
{ $\mathfrak{D}_{iso}$, $\mathfrak{D}_a$, $\mathfrak{D}_r$, α, β, γ},
2 -
{ $\mathfrak{D}_x$, $\mathfrak{D}_y$, $\mathfrak{D}_z$, α, β, γ},
3 -
{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},

where

 τm = 1 / 6 $\mathfrak{D}_{iso}$,
  $\mathfrak{D}_{iso}$ = 1/3 ( $\mathfrak{D}_x$ + $\mathfrak{D}_y$ + $\mathfrak{D}_z$),
  $\mathfrak{D}_a$ = $\mathfrak{D}_z$ - ( $\mathfrak{D}_x$ + $\mathfrak{D}_y$)/2,
  $\mathfrak{D}_r$ = ( $\mathfrak{D}_y$ - $\mathfrak{D}_x$)/2 $\mathfrak{D}_a$.

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.

Units

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 $\mathfrak{D}_{iso}$, $\mathfrak{D}_{\scriptscriptstyle \parallel }$, $\mathfrak{D}_{\scriptscriptstyle \perp}$, $\mathfrak{D}_a$, $\mathfrak{D}_x$, $\mathfrak{D}_y$, and $\mathfrak{D}_z$. Significantly, $\mathfrak{D}_r$ is not affected.

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

Prompt examples

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, $\mathfrak{D}_{ratio}$ 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 $\mathfrak{D}_{\scriptscriptstyle \parallel }$ value of 1.698e7, $\mathfrak{D}_{\scriptscriptstyle \perp}$ 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)


next up previous contents index pdf_icon_nav.pngrelax_logo_nav.png
Next: domain Up: The list of functions Previous: diffusion_tensor.display   Contents   Index
The relax user manual (PDF), created 2020-08-26.