Module align_tensor

Module containing functions for the handling of alignment tensors.

Functions

bool align_data_exists(tensor, 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.

numpy array or float calc_chi_tensor(A, B0, T)
Convert the alignment tensor into the magnetic susceptibility (chi) tensor.

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.

data_names()
Function for returning a list of names of data structures associated with the sequence.

float default_value(param)
Return the default values for the alignment tensor parameters.

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

display(tensor)
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.

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

AlignTensorData instance get_tensor_object(tensor, pipe=None)
Function for returning the AlignTensorData instance corresponding to the 'tensor' argument.

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

map_bounds(param)
The function for creating bounds for the mapping function.

float kappa(nuc1='15N', nuc2='1H')
Function for calculating the kappa constant.

map_labels(index, params, bounds, swap, inc)
Function for creating labels, tick locations, and tick values for an OpenDX map.

matrix_angles(basis_set=0, tensors=None)
Function for calculating the 5D angles between the alignment tensors.

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

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

float return_conversion_factor(param)
Function for returning the factor of conversion between different parameter units.

str return_data_name(name)
Return the parameter name.

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

str return_units(param)
Function for returning a string representing the parameters units.

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

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

svd(basis_set=0, tensors=None)
Function for calculating the singular values of all the loaded tensors.

Variables

__default_value_prompt_doc__ = '\n Alignment tensor paramet...

__return_data_name_prompt_doc__ = '\n Alignment tensor para...

__set_prompt_doc__ = '\n Alignment tensor set details\n ...

__package__ = 'generic_fns'

Imports: deepcopy, pi, sqrt, arccos, dot, float64, linalg, zeros, norm, search, sys, wrap_angles, AlignTensorList, pipes, g1H, h_bar, kB, mu0, return_gyromagnetic_ratio, RelaxError, RelaxNoTensorError, RelaxStrError, RelaxTensorError, RelaxUnknownParamCombError, RelaxUnknownParamError

Function Details

align_data_exists(tensor, pipe=None)

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

Parameters:

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

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.

calc_chi_tensor(A, B0, T)

Convert the alignment tensor into the magnetic susceptibility (chi) tensor.

A can be either the full tensor (3D or 5D), a component Aij of the tensor, Aa, or Ar, anything that can be multiplied by the constants to convert from one to the other.

Parameters:

• A (numpy array or float) - The alignment tensor or alignment tensor component.
• B0 (float) - The magnetic field strength in Hz.
• T (float) - The temperature in Kalvin.

Returns: numpy array or float

A multiplied by the PCS constant.

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) - The identification string of the alignment tensor to copy the data to.
• pipe_to (str) - The data pipe to copy the alignment tensor data to. This defaults to the current data pipe.

default_value(param)

Return the default values for the alignment tensor parameters.

Parameters:

• param (str) - The name of the parameter.

Returns: float

The default value, which for all parameters is set to zero.

delete(tensor=None)

Function for deleting alignment tensor data.

Parameters:

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

display(tensor)

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_tensor_index(tensor, pipe=None)

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

Parameters:

• tensor (str) - The alignment tensor identification string.
• 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)

Function for returning the AlignTensorData instance corresponding to the 'tensor' argument.

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.

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

Function for initialising the alignment tensor.

Parameters:

• tensor (str) - The alignment tensor identification string.
• params (float) - 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}.
• errors (bool) - A flag which determines if the alignment tensor data or its errors are being input.

kappa(nuc1='15N', nuc2='1H')

Function for calculating the kappa constant.

The kappa constant is:

   kappa = -3/(8pi^2).gI.gS.mu0.h_bar,

where gI and gS are the gyromagnetic ratios of the I and S spins, mu0 is the permeability of free space, and h_bar is Planck's constant divided by 2pi.

Parameters:

• nuc1 (str) - The first nucleus type.
• nuc2 (str) - The first nucleus type.

Returns: float

The kappa constant value.

map_labels(index, params, bounds, swap, inc)

Function for creating labels, tick locations, and tick values for an OpenDX map.

Parameters:

• index (int) - The index (which isn't used here?!?).
• params (list of str) - The list of parameter names.
• bounds (list of lists (of a float and bin)) - The bounds of the map.
• swap (list of int) - An array for switching axes around.
• inc (list of int) - The number of increments of one dimension in the map.

matrix_angles(basis_set=0, tensors=None)

Function for calculating the 5D angles between the alignment tensors.

The basis set used for the 5D vector construction changes the angles calculated.

Parameters:

• basis_set (int) - The basis set to use for constructing the 5D vectors. If set to 0, the basis set is {Sxx, Syy, Sxy, Sxz, Syz}. If 1, then the basis set is {Szz, Sxxyy, Sxy, Sxz, Syz}.
• tensors (None or array of str) - An array of tensors to apply SVD to. If None, all tensors will be used.

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).

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_conversion_factor(param)

Function for returning the factor of conversion between different parameter units.

Parameters:

• param (str) - The parameter name.

Returns: float

The conversion factor.

return_data_name(name)

Return the parameter name.

Parameters:

• name (str) - The name of the parameter to return the name of.

Returns: str

The parameter name.

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.

return_units(param)

Function for returning a string representing the parameters units.

Parameters:

• param (str) - The parameter name.

Returns: str

The string representation of the units.

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_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=0, tensors=None)

Function for calculating the singular values of all the loaded tensors.

The matrix on which SVD will be performed is:

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

This is the default unitary basis set (selected when basis_set is 0). Alternatively a geometric basis set consisting of the stretching and skewing parameters Szz and Sxx-yy respectively replacing Sxx and Syy can be chosen by setting basis_set to 1. The matrix in this case is:

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

The relationships between the geometric and unitary basis sets are:

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

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

Parameters:

• basis_set (int) - The basis set to create the 5 by n matrix on which to perform SVD.
• tensors (None or array of str) - An array of tensors to apply SVD to. If None, all tensors will be used.

Variables Details

__default_value_prompt_doc__

Value:

'''
    Alignment tensor parameter default values
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    __________________________________________________________________
______
    |                        |                    |                   
     |
...

__return_data_name_prompt_doc__

Value:

'''
    Alignment tensor parameter string matching patterns
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    __________________________________________________________________
__________________________
    |                                                        |        
      |                  |
...

__set_prompt_doc__

Value:

'''
    Alignment tensor set details
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If the alignment tensor has not been setup, use the more powerful 
function
    \'alignment_tensor.init\' to initialise the tensor parameters.

...