lib.alignment.pcs

ave_pcs_tensor(dj, vect, N, A, weights=None)

Calculate the ensemble average PCS, using the 3D tensor.

This function calculates the average PCS for a set of XH bond vectors from a structural ensemble, using the 3D tensorial form of the alignment tensor. The formula for this ensemble average PCS value is:

                        _N_
                        \                   T
   <delta_ij(theta)>  =  >  pc . djc . mu_jc . Ai . mu_jc,
                        /__
                        c=1

where:

i is the alignment tensor index,
j is the index over spins,
c is the index over the states or multiple structures,
N is the total number of states or structures,
theta is the parameter vector,
djc is the PCS constant for spin j and state c,
pc is the population probability or weight associated with state c (equally weighted to 1/N if weights are not provided),
mu_jc is the unit vector corresponding to spin j and state c,
Ai is the alignment tensor.

The PCS constant is defined as:

        mu0 15kT   1
   dj = --- ----- ---- ,
        4pi Bo**2 r**3

where:

mu0 is the permeability of free space,
k is Boltzmann's constant,
T is the absolute temperature,
Bo is the magnetic field strength,
r is the distance between the paramagnetic centre (electron spin) and the nuclear spin.

Parameters:

dj (numpy rank-1 array) - The PCS constants for each structure c for spin j. This should be an array with indices corresponding to c.
vect (numpy matrix) - The electron-nuclear unit vector matrix. The first dimension corresponds to the structural index, the second dimension is the coordinates of the unit vector. The vectors should be parallel to the vector connecting the paramagnetic centre to the nuclear spin.
N (int) - The total number of structures.
A (numpy rank-2 3D tensor) - The alignment tensor.
weights (numpy rank-1 array) - The weights for each member of the ensemble (the last member need not be supplied).

Returns: float

The average PCS value.

ave_pcs_tensor_ddeltaij_dAmn(dj, vect, N, dAi_dAmn, weights=None)

source code

Calculate the ensemble average PCS gradient element for Amn, using the 3D tensor.

This function calculates the alignment tensor parameter part of the average PCS gradient for a set of electron-nuclear spin unit vectors (paramagnetic to the nuclear spin) from a structural ensemble, using the 3D tensorial form of the alignment tensor. The formula for this ensemble average PCS gradient element is:

                       _N_
   ddelta_ij(theta)    \                   T   dAi
   ----------------  =  >  pc . djc . mu_jc . ---- . mu_jc,
         dAmn          /__                    dAmn
                       c=1

where:

i is the alignment tensor index,
j is the index over spins,
m, the index over the first dimension of the alignment tensor m = {x, y, z}.
n, the index over the second dimension of the alignment tensor n = {x, y, z},
c is the index over the states or multiple structures,
theta is the parameter vector,
Amn is the matrix element of the alignment tensor,
djc is the PCS constant for spin j and state c,
N is the total number of states or structures,
pc is the population probability or weight associated with state c (equally weighted to 1/N if weights are not provided),
mu_jc is the unit vector corresponding to spin j and state c,
dAi/dAmn is the partial derivative of the alignment tensor with respect to element Amn.

Parameters:

dj (numpy rank-1 array) - The PCS constants for each structure c for spin j. This should be an array with indices corresponding to c.
vect (numpy matrix) - The electron-nuclear unit vector matrix. The first dimension corresponds to the structural index, the second dimension is the coordinates of the unit vector. The vectors should be parallel to the vector connecting the paramagnetic centre to the nuclear spin.
N (int) - The total number of structures.
dAi_dAmn (numpy rank-2 3D tensor) - The alignment tensor derivative with respect to parameter Amn.
weights (numpy rank-1 array) - The weights for each member of the ensemble (the last member need not be supplied).

Returns: float

The average PCS gradient element.

ave_pcs_tensor_ddeltaij_dc(ddj=None, dj=None, r=None, unit_vect=None, N=None, Ai=None, dr_dc=None, weights=None)

source code

Calculate the ensemble average PCS gradient element for the paramagnetic centre coordinate c, using the 3D tensor.

This function calculates the paramagnetic centre coordinate part of the average PCS gradient for a set of electron-nuclear spin unit vectors (paramagnetic to the nuclear spin) from a structural ensemble, using the 3D tensorial form of the alignment tensor. The formula for this ensemble average PCS gradient element is:

                       _N_
   ddelta_ij(theta)    \        / ddjc                       dr_jcT                          dr_jc \ 
   ----------------  =  >  pc . | ----.r_jcT.Ai.r_jc  +  djc.------.Ai.r_jc  +  djc.r_jcT.Ai.----- | ,
         dxi           /__      \ dxi                         dxi                             dxi  /
                       c=1

where the last two terms in the sum are equal due to the symmetry of the alignment tensor, and:

xi are the paramagnetic position coordinates {x0, x1, x2},
i is the alignment tensor index,
j is the index over spins,
c is the index over the states or multiple structures,
theta is the parameter vector,
djc is the PCS constant for spin j and state c,
N is the total number of states or structures,
pc is the population probability or weight associated with state c (equally weighted to 1/N if weights are not provided),
r_jc is the vector corresponding to spin j and state c,

and where:

   ddjc    mu0 15kT                 5 (si - xi)
   ----  = --- ----- ---------------------------------------------  ,
   dxi     4pi Bo**2 ((sx-x0)**2 + (sy-x1)**2 + (sz-x2)**2)**(7/2)

where {sx, sy, sz} are the spin atomic coordinates, and:

   dr       | 1 |   dr       | 0 |   dr       | 0 |
   ---  = - | 0 | , ---  = - | 1 | , ---  = - | 0 | .
   dx0      | 0 |   dx1      | 0 |   dx2      | 1 |

The pseudocontact shift constant is defined here as:

         mu0 15kT    1
   djc = --- ----- ------ ,
         4pi Bo**2 rjc**5

Parameters:

ddj (numpy rank-1 array) - The PCS constant gradient for each structure c for spin j. This should be an array with indices corresponding to c.
dj (numpy rank-1 array) - The PCS constants for each structure c for spin j. This should be an array with indices corresponding to c.
r (float) - The distance between the paramagnetic centre and the spin (in meters).
vect (numpy matrix) - The electron-nuclear unit vector matrix. The first dimension corresponds to the structural index, the second dimension is the coordinates of the unit vector. The vectors should be parallel to the vector connecting the paramagnetic centre to the nuclear spin.
N (int) - The total number of structures.
Ai (numpy rank-2, 3D tensor) - The alignment tensor i.
weights (numpy rank-1 array) - The weights for each member of the ensemble (the last member need not be supplied).

Returns: float

The average PCS gradient element.

pcs_constant_grad(T=None, Bo=None, r=None, unit_vect=None, grad=None)

source code

Calculate the PCS constant gradient with respect to the paramagnetic centre position.

The pseudocontact shift constant is defined here as:

         mu0 15kT    1
   djc = --- ----- ------ ,
         4pi Bo**2 rjc**5

where:

mu0 is the permeability of free space,
k is Boltzmann's constant,
T is the absolute temperature,
Bo is the magnetic field strength,
r is the distance between the paramagnetic centre (electron spin) and the nuclear spin.

The 5th power of the distance is used to simplify the PCS derivative. The pseudocontact shift constant derivative is:

   ddjc   mu0 15kT                 5 (si - xi)
   ---- = --- ----- ---------------------------------------------  ,
   dxi    4pi Bo**2 ((sx-x0)**2 + (sy-x1)**2 + (sz-x2)**2)**(7/2)

where:

{x0, x1, x2} are the paramagnetic centre coordinates,
{sx, sy, sz} are the spin atomic coordinates.

Parameters:

T (float) - The temperature in kelvin.
Bo (float) - The magnetic field strength.
r (float) - The distance between the paramagnetic centre and the spin (in meters).
unit_vect (numpy rank-1, 3D array) - The paramagnetic centre to spin unit vector.
grad (numpy rank-1, 3D array) - The gradient component to update. The indices {0, 1, 2} match the {dx, dy, dz} derivatives.

pcs_tensor(dj, mu, A)

source code

Calculate the PCS, using the 3D alignment tensor.

The PCS value is:

                               T
   delta_ij(theta)  = dj . mu_j . Ai . mu_j,

where:

i is the alignment tensor index,
j is the index over spins,
theta is the parameter vector,
dj is the PCS constant for spin j,
mu_j i the unit vector corresponding to spin j,
Ai is the alignment tensor.

The PCS constant is defined as:

        mu0 15kT   1
   dj = --- ----- ---- ,
        4pi Bo**2 r**3

where:

mu0 is the permeability of free space,
k is Boltzmann's constant,
T is the absolute temperature,
Bo is the magnetic field strength,
r is the distance between the paramagnetic centre (electron spin) and the nuclear spin.

Parameters:

dj (float) - The PCS constant for spin j.
mu (numpy rank-1 3D array) - The unit vector connecting the electron and nuclear spins.
A (numpy rank-2 3D tensor) - The alignment tensor.

Returns: float

The PCS value.

Module pcs

ave_pcs_tensor(dj, vect, N, A, weights=None)

ave_pcs_tensor_ddeltaij_dAmn(dj, vect, N, dAi_dAmn, weights=None)

ave_pcs_tensor_ddeltaij_dc(ddj=None, dj=None, r=None, unit_vect=None, N=None, Ai=None, dr_dc=None, weights=None)

pcs_constant_grad(T=None, Bo=None, r=None, unit_vect=None, grad=None)

pcs_tensor(dj, mu, A)