Module align_tensor

Module containing functions for the handling of alignment tensors.

Functions

bool align_data_exists(tensor=None, pipe=None)
Function for determining if alignment data exists in the current data pipe.

bool all_tensors_fixed()
Determine if all alignment tensors are fixed.

copy(tensor_from=None, pipe_from=None, tensor_to=None, pipe_to=None)
Function for copying alignment tensor data from one data pipe to another.

delete(tensor=None)
Function for deleting alignment tensor data.

display(tensor=None)
Function for displaying the alignment tensor.

fix(id=None, fixed=True)
Fix the alignment tensor during optimisation.

fold_angles(sim_index=None)
Wrap the Euler angles and remove the glide reflection and translational symmetries.

float gdo(A)
Calculate the generalized degree of order (GDO) for the given alignment tensor.

list of str get_align_ids()
Return the list of all alignment IDs.

list of str get_tensor_ids()
Return the list of all tensor IDs.

int get_tensor_index(tensor=None, align_id=None, pipe=None)
Function for returning the index corresponding to the 'tensor' argument.

AlignTensorData instance get_tensor_object(tensor, pipe=None)
Return the AlignTensorData instance corresponding to the tensor ID.

AlignTensorData instance get_tensor_object_from_align(align_id, pipe=None)
Return the unique AlignTensorData instance corresponding to the alignment ID.

init(tensor=None, align_id=None, params=None, scale=1.0, angle_units='deg', param_types=0, domain=None, errors=False)
Function for initialising the alignment tensor.

matrix_angles(basis_set='matrix', tensors=None, angle_units='deg', precision=1)
Function for calculating the inter-matrix angles between the alignment tensors.

int num_tensors(skip_fixed=True)
Count the number of tensors.

bool opt_uses_align_data(align_id=None)
Determine if the PCS or RDC data for the given alignment ID is needed for optimisation.

bool opt_uses_tensor(tensor)
Determine if the given tensor is to be optimised.

reduction(full_tensor=None, red_tensor=None)
Specify which tensor is a reduction of which other tensor.

data.align_tensor.AlignTensorData instance return_tensor(index, skip_fixed=True)
Return the tensor container for the given index, skipping fixed tensors if required.

set(tensor=None, value=None, param=None, errors=False)
Set the tensor.

set_align_id(tensor=None, align_id=None)
Set the align ID string for the given tensor.

set_domain(tensor=None, domain=None)
Set the domain label for the given tensor.

svd(basis_set='irreducible 5D', tensors=None, precision=1)
Calculate the singular values of all the loaded tensors.

Variables

__package__ = 'pipe_control'

Imports: deepcopy, acos, pi, sqrt, arccos, complex128, dot, float64, inner, linalg, zeros, norm, sys, warn, AlignTensorList, calc_chi_tensor, kappa, RelaxError, RelaxNoTensorError, RelaxTensorError, RelaxUnknownParamCombError, RelaxUnknownParamError, wrap_angles, vector_angle_complex_conjugate, write_data, section, subsection, RelaxWarning, pipe_control, pipes, check_pipe

Function Details

align_data_exists(tensor=None, pipe=None)

Function for determining if alignment data exists in the current data pipe.

Parameters:

• tensor (str or None) - The alignment tensor ID string. If not supplied, then any alignment data will result in the function returning True.
• pipe (str or None) - The data pipe to search for data in. This defaults to the current data pipe if not supplied.

Returns: bool

The answer to the question.

all_tensors_fixed()

Determine if all alignment tensors are fixed.

Returns: bool

True if all tensors are fixed, False otherwise.

copy(tensor_from=None, pipe_from=None, tensor_to=None, pipe_to=None)

Function for copying alignment tensor data from one data pipe to another.

Parameters:

• tensor_from (str) - The identification string of the alignment tensor to copy the data from.
• pipe_from (str) - The data pipe to copy the alignment tensor data from. This defaults to the current data pipe.
• tensor_to (str or None) - The identification string of the alignment tensor to copy the data to. If set to None, then the ID string will be set to the value of tensor_from.
• pipe_to (str) - The data pipe to copy the alignment tensor data to. This defaults to the current data pipe.

delete(tensor=None)

Function for deleting alignment tensor data.

Parameters:

• tensor (str or None) - The alignment tensor identification string.

display(tensor=None)

Function for displaying the alignment tensor.

Parameters:

• tensor (str or None) - The alignment tensor identification string.

fix(id=None, fixed=True)

Fix the alignment tensor during optimisation.

Parameters:

• id (str or None) - The alignment tensor ID string. If set to None, then all alignment tensors will be fixed.
• fixed (bool) - If True, the alignment tensor will be fixed during optimisation. If False, the alignment tensors will be optimised.

fold_angles(sim_index=None)

Wrap the Euler angles and remove the glide reflection and translational symmetries.

Wrap the angles such that:

   0 <= alpha <= 2pi,
   0 <= beta <= pi,
   0 <= gamma <= 2pi.

For the simulated values, the angles are wrapped as:

   alpha - pi <= alpha_sim <= alpha + pi
   beta - pi/2 <= beta_sim <= beta + pi/2
   gamma - pi <= gamma_sim <= gamma + pi

Parameters:

• sim_index (int or None) - The simulation index. If set to None then the actual values will be folded rather than the simulation values.

gdo(A)

Calculate the generalized degree of order (GDO) for the given alignment tensor.

Parameters:

• A (rank-2, 3D numpy array) - The alignment tensor.

Returns: float

The GDO value.

get_align_ids()

Return the list of all alignment IDs.

Returns: list of str

The list of all alignment IDs.

get_tensor_ids()

Return the list of all tensor IDs.

Returns: list of str

The list of all tensor IDs.

get_tensor_index(tensor=None, align_id=None, pipe=None)

Function for returning the index corresponding to the 'tensor' argument.

Parameters:

• tensor (str or None) - The alignment tensor identification string.
• align_id (str or None) - Alternative to the tensor argument, used to return the tensor index for the tensors corresponding to the alignment ID string. If more than one tensor exists, then this will fail.
• pipe (str) - The data pipe to search for data in.

Returns: int

The index corresponding to the 'tensor' arg.

get_tensor_object(tensor, pipe=None)

Return the AlignTensorData instance corresponding to the tensor ID.

Parameters:

• tensor (str) - The alignment tensor identification string.
• pipe (str) - The data pipe to search for data in.

Returns: AlignTensorData instance

The alignment tensor object corresponding to the 'tensor' arg.

get_tensor_object_from_align(align_id, pipe=None)

Return the unique AlignTensorData instance corresponding to the alignment ID.

Parameters:

• align_id (str) - The alignment ID for the unique tensor.

Returns: AlignTensorData instance

The alignment tensor object corresponding to the 'tensor' arg.

init(tensor=None, align_id=None, params=None, scale=1.0, angle_units='deg', param_types=0, domain=None, errors=False)

Function for initialising the alignment tensor.

Parameters:

• tensor (str) - The alignment tensor identification string.
• align_id (str or None) - The alignment ID string that the tensor corresponds to.
• params (list of float or None) - The alignment tensor parameters.
• scale (float) - The alignment tensor eigenvalue scaling value.
• angle_units (str) - The units for the angle parameters (either 'deg' or 'rad').
• param_types (int) - The type of parameters supplied. The flag values correspond to, 0: {Axx, Ayy, Axy, Axz, Ayz}, and 1: {Azz, Axx-yy, Axy, Axz, Ayz}.
• domain (str or None) - The domain label.
• errors (bool) - A flag which determines if the alignment tensor data or its errors are being input.

matrix_angles(basis_set='matrix', tensors=None, angle_units='deg', precision=1)

Function for calculating the inter-matrix angles between the alignment tensors.

The basis set defines how the angles are calculated:

• "matrix", the standard inter-matrix angle. The angle is calculated via the Euclidean inner product of the alignment matrices in rank-2, 3D form divided by the Frobenius norm ||A||_F of the matrices.
• "irreducible 5D", the irreducible 5D basis set {A-2, A-1, A0, A1, A2}.
• "unitary 5D", the unitary 5D basis set {Sxx, Syy, Sxy, Sxz, Syz}.
• "geometric 5D", the geometric 5D basis set {Szz, Sxxyy, Sxy, Sxz, Syz}. This is also the Pales standard notation.

Parameters:

• basis_set (str) - The basis set to use for calculating the inter-matrix angles. It can be one of "matrix", "irreducible 5D", "unitary 5D", or "geometric 5D".
• tensors (None or list of str) - The list of alignment tensor IDs to calculate inter-matrix angles between. If None, all tensors will be used.
• angle_units (str) - The units for the angle parameters, either 'deg' or 'rad'.
• precision (int) - The precision of the printed out angles. The number corresponds to the number of figures to print after the decimal point.

num_tensors(skip_fixed=True)

Count the number of tensors.

Parameters:

• skip_fixed (bool) - If set to True, then only the tensors without the fixed flag will be counted. If set to False, then all tensors will be counted.

Returns: int

The number of tensors (excluding fixed tensors by default).

opt_uses_align_data(align_id=None)

Determine if the PCS or RDC data for the given alignment ID is needed for optimisation.

Parameters:

• align_id (str) - The optional alignment ID string.

Returns: bool

True if alignment data is to be used for optimisation, False otherwise.

opt_uses_tensor(tensor)

Determine if the given tensor is to be optimised.

Parameters:

• tensor (AlignmentTensor object.) - The alignment tensor to check.

Returns: bool

True if the tensor is to be optimised, False otherwise.

reduction(full_tensor=None, red_tensor=None)

Specify which tensor is a reduction of which other tensor.

Parameters:

• full_tensor (str) - The full alignment tensor.
• red_tensor (str) - The reduced alignment tensor.

return_tensor(index, skip_fixed=True)

Return the tensor container for the given index, skipping fixed tensors if required.

Parameters:

• index (int) - The index of the tensor (if skip_fixed is True, then fixed tensors are not included in the index count).
• skip_fixed (bool) - A flag which if True will exclude fixed tensors from the indexation.

Returns: data.align_tensor.AlignTensorData instance

The tensor corresponding to the index.

set(tensor=None, value=None, param=None, errors=False)

Set the tensor.

Parameters:

• tensor (AlignTensorData instance) - The alignment tensor object.
• value (list of float) - The list of values to set the parameters to.
• param (list of str) - The list of parameter names.
• errors (bool) - A flag which determines if the alignment tensor data or its errors are being input.

set_align_id(tensor=None, align_id=None)

Set the align ID string for the given tensor.

Parameters:

• tensor (str) - The alignment tensor label.
• align_id (str) - The alignment ID string.

set_domain(tensor=None, domain=None)

Set the domain label for the given tensor.

Parameters:

• tensor (str) - The alignment tensor label.
• domain (str) - The domain label.

svd(basis_set='irreducible 5D', tensors=None, precision=1)

Calculate the singular values of all the loaded tensors.

The basis set can be set to one of:

• 'irreducible 5D', the irreducible 5D basis set {A-2, A-1, A0, A1, A2}. This is a linear map, hence angles are preserved.
• 'unitary 9D', the unitary 9D basis set {Sxx, Sxy, Sxz, Syx, Syy, Syz, Szx, Szy, Szz}. This is a linear map, hence angles are preserved.
• 'unitary 5D', the unitary 5D basis set {Sxx, Syy, Sxy, Sxz, Syz}. This is a non-linear map, hence angles are not preserved.
• 'geometric 5D', the geometric 5D basis set {Szz, Sxxyy, Sxy, Sxz, Syz}. This is a non-linear map, hence angles are not preserved. This is also the Pales standard notation.

If the selected basis set is the default of 'irreducible 5D', the matrix on which SVD will be performed will be:

   | A-2(1) A-1(1) A0(1)  A1(1)  A2(1) |
   | A-2(2) A-1(2) A0(2)  A1(2)  A2(2) |
   | A-2(3) A-1(3) A0(3)  A1(3)  A2(3) |
   |   .      .     .      .      .    |
   |   .      .     .      .      .    |
   |   .      .     .      .      .    |
   | A-2(N) A-1(N) A0(N)  A1(N)  A2(N) |

If the selected basis set is 'unitary 9D', the matrix on which SVD will be performed will be:

   | Sxx1 Sxy1 Sxz1 Syx1 Syy1 Syz1 Szx1 Szy1 Szz1 |
   | Sxx2 Sxy2 Sxz2 Syx2 Syy2 Syz2 Szx2 Szy2 Szz2 |
   | Sxx3 Sxy3 Sxz3 Syx3 Syy3 Syz3 Szx3 Szy3 Szz3 |
   |  .    .    .    .    .    .    .    .    .   |
   |  .    .    .    .    .    .    .    .    .   |
   |  .    .    .    .    .    .    .    .    .   |
   | SxxN SxyN SxzN SyxN SyyN SyzN SzxN SzyN SzzN |

Otherwise if the selected basis set is 'unitary 5D', the matrix for SVD is:

   | Sxx1 Syy1 Sxy1 Sxz1 Syz1 |
   | Sxx2 Syy2 Sxy2 Sxz2 Syz2 |
   | Sxx3 Syy3 Sxy3 Sxz3 Syz3 |
   |  .    .    .    .    .   |
   |  .    .    .    .    .   |
   |  .    .    .    .    .   |
   | SxxN SyyN SxyN SxzN SyzN |

Or if the selected basis set is 'geometric 5D', the stretching and skewing parameters Szz and Sxx-yy will be used instead and the matrix is:

   | Szz1 Sxxyy1 Sxy1 Sxz1 Syz1 |
   | Szz2 Sxxyy2 Sxy2 Sxz2 Syz2 |
   | Szz3 Sxxyy3 Sxy3 Sxz3 Syz3 |
   |  .     .     .    .    .   |
   |  .     .     .    .    .   |
   |  .     .     .    .    .   |
   | SzzN SxxyyN SxyN SxzN SyzN |

For the irreducible basis set, the Am components are defined as:

           / 4pi \ 1/2
      A0 = | --- |     Szz ,
           \  5  /

               / 8pi \ 1/2
   A+/-1 = +/- | --- |     (Sxz +/- iSyz) ,
               \ 15  /

           / 2pi \ 1/2
   A+/-2 = | --- |     (Sxx - Syy +/- 2iSxy) .
           \ 15  /

The relationships between the geometric and unitary basis sets are:

   Szz = - Sxx - Syy,
   Sxxyy = Sxx - Syy,

The SVD values and condition number are dependant upon the basis set chosen.

Parameters:

• basis_set (str) - The basis set to use for the SVD. This can be one of "irreducible 5D", "unitary 9D", "unitary 5D" or "geometric 5D".
• tensors (None or list of str) - The list of alignment tensor IDs to calculate inter-matrix angles between. If None, all tensors will be used.
• precision (int) - The precision of the printed out angles. The number corresponds to the number of figures to print after the decimal point.