Official government website icon

bit	Xplor-NIH	VMD-XPLOR

Pydoc: module varTensorTools

varTensorTools

index

Tools for manipulation of tensors represented with 7 pseudo-atoms. This module presents functions to simplify the creation, manipulation and analysis of varTensor.VarTensor objects, which are used to represent orientation tensors.

Functions

VarTensor_analyze(potList): perform analysis of VarTensor terms and return nicely formatted summary

addAxisAtoms(resid=-1, segid='', sim=None): add atoms to the current structure. If the resid argument
is omitted, a new number is automatically generated. If the
segment name is omitted, the default is used. Initial coords
for the various atoms are also generated.

Returns a tuple of the segid and residue number.

alignTensorToZ(oTensor, tensorTrans=0): First compute the best-fit alignment tensor orientation, and then
rotate the entire system such that the z-axis of the alignment tensor
actually lies in the Cartesian z direction. The tensorTrans
argument specifies the x and y components of an optional translation to be
applied to all pseudoatoms used to describe the alignment tensors. The z
component is always zero.

calcTensor(vTensor, expts=0, coords=None, weights=None, useErr=False, svdTolerance=0.1, svdNum=None, selection='all', suppressExceptions=False, verbose=True): Given a known structure, and a varTensor.VarTensor object with
associated experimental RDC and/or CSA terms, determine the orientation
tensor, Da, and rhombicity.  The Saupe matrix is returned (in the axis
system of the input coordinates).  If there is an ensemble of
structures, a single orientation tensor is calculated.  Note that when the
varTensor instance (vTensor argument) has multiple associated experiments,
each term in the solution matrix is premultiplied by 1/sqrt( term.scale() ),
so that the appropriate scaling is maintained.

The optional expts argument specifies which RDC and/or CSA experiments to
use in the calculation of the tensor; if omitted, all experiments associated
with the tensor will be used in the tensor calculation.

If the coords argument is specified, it should be a sequence of sets of
atomic coordinates (e.g., as obtained from simulation.atomPosArr) to be
used in determination of the tensor.  If the sequence has more than one
coordinate set, the weights argument specifies the relative importance of
each set (uniform weight if weights is not specified).

Set the useErr argument to True to appropriately weight the SVD calculation
to take account of observed RDC and CSA errors.  This defaults to False.

The selection argument can be used to select a subset of restraints to use
for the SVD calculation.  The restraints used are those whose atom
selections lie within the selection argument.

svdTolerance specifies the size of the smallest singular value used in
solving the linear equation.  The equation for the unique elements of the
Saupe tensor is

    t = v * diag * uT * b

where v, diag and uT are results of SVD and b is a vector of observed
measurements.  diag is a diagonal matrix, the nonzero elements of which are
reciprocals of singular values of a matrix composed of geometrical bond
vector information.  If the absolute value of a singular value is less than
svdTolerance times the absolute value of the next largest singular value,
the corresponding value of diag and those for all smaller singular values
are set to zero.

Alternatively, svdNum specifies the number of singular values to include
(of a maximum of 5).

The suppressExceptions argument can be set to True to avoid an exception
being thrown if there are fewer than 5 observed RDCs. In that case, the
alignment tensor is underdetermined, and the SVD solution will not be
unique.

Reference: Losonczi, J.A., et al. J. Magn. Reson. (1999) 138: 334-342.

calcTensorOrientation(oTensor, verbose=True, algo='lsq'): given a known structure, and experimental RDCs, and
Da and rhombicity, determine the tensor orientation.

All rdcs in oTensor.expts are used in determining the tensor.

The Saupe matrix is returned.

calcTensor_ensemble(vTensor, expts=0, svdTolerance=0.01, useErr=False, selection='known'): given a known structure, and a VarTensor object with associated
experimental RDC or CSA terms, determine the orientation tensor, Da, and
rhombicity. The Saupe matrix is returned. If there is an ensemble of
structures, multiple alignment tensors are calculated. Note when vTensor
has multiple associated experiments: each term in the solution matrix is
premultiplied by 1/sqrt( term.scale() ), so that the appropriate scaling
is maintained.

The optional expts argument specifies which RDC or CSA experiments to use
in calculation of the tensor. If it is omitted, all expts associated with
the tensor will be used in the tensor calculation.

The selection argument can be used to select a subset of restraints to
use for the SVD calculation. The restraints used are those whose atom
selections lie within the selection argument.

Set the useErr argument to True to appropriately weight the
SVD calculation to take account of observed RDC and CSA errors. This
defaults to False.

svdTolerance specifies the size of the smallest singular value used in
solving the linear equation. The equation for the unique elements of the
Saupe tensor is
t = v * diag * uT * b
where v, diag and uT are results of SVD and b is a vector of observed
measurements. diag is a diagonal matrix, the nonzero elements of which
are reciprocals of singular values of a matrix composed of geometrical
bond vector information. The elements of diag are set to zero if the
absolute value of the corresponding singular value is less than
svdTolerance times the average of the absoulte value of singular values.

composite_RDCRfactor(term): For the RDC terms associated with the argument VarTensor object,
return composite R-factor by calling
rdcPotTools.composite_Rfactor_infinite.

composite_RDCchi2(term): For the RDC terms associated with the argument VarTensor object,
return composite chi^2 by calling
rdcPotTools.composite_chi62.

configIVM(p, ivm): first argument is an potential term containing a varTensor and the
second is an IVM. This routine does the required initial topology setup.

configIVM_fix(p, ivm): first argument is an RDCPot1 and the second is an IVM.
this routine fixes all atoms such that the tensor does not vary.

configIVM_fixAxis(p, ivm): first argument is an RDCPot1 and the second is an IVM.
this routine fixes all atoms such that the tensor orientation does
not vary.

configIVM_fixAxisToOther(p, ivm, pot2): first argument is a VarTensor, the second an IVM, and the third another
VarTensor.
this routine does topology setup to fix the axis (tensor orientation)
to that of another potential term.

configIVM_fixDa(p, ivm): first argument is an RDCPot1 and the second is an IVM.
this routine does topology setup for fixed Da.

configIVM_fixRh(p, ivm): first argument is an RDCPot1 and the second is an IVM.
this routine does topology setup for fixed Da.

configIVM_fixRhToOther(p, ivm, pot2): first argument is a VarTensor, the second an IVM, and the third another
VarTensor.
this routine does topology setup for Rhombicity fixed to that of another
potential term.
NOTE: for this to work, the axes must also be fixed together.

configIVM_varyDa(p, ivm): first argument is an RDCPot1 and the second is an IVM.
this routine does topology setup for varying Da.

the o-p1 bond will rotate about an axis perpendicular to the
y-o-p1 atom plane. since only the projection on the x-o-y plane is
significant in the calculation of Da, o-p1 should always have
zero-projection along the o-z axis.

configIVM_varyRh(p, ivm): first argument is a VarTensor and the second is an IVM.
this routine does topology setup for varying Rhombicity.

the o-p2 bond will rotate about an axis perpendicular to the
z-o2-p2 atom plane. Note that only the azimuthal angle p2-o2-z is
considered in the calculation of Rh.

copyTensor(ten1, ten2): copy positions of tensor atoms from ten2 to ten1

create_VarTensor(name, axis=0, esim=0): Create a varTensor.VarTensor instance.

name (a string) is its assigned name. axis is a sequence with the segment
id (segid; a string) and residue number (resid; a number), in that order,
associated with the axis atoms. esim is an optional ensemble simulation
argument.

deletePseudoAtoms(obj): Delete the pseudoatoms associated with the specified VarTensor obj.

ensembleTensorInfo(t): get info for all tensors of the ensemble

eulerAngles(t, eIndex=-1): For the given varTensor.VarTensor object, return the four sets of
equivalent euler angles.

Euler angles computed using Goldstein's x-convention
p. 147

Euler Angles are for rotation matrix which converts the
  matrix R whose columns are composed of the vectors [ijk]
  into a matrix whose columns comprise the current [xyz]
  vectors:
           [xyz] = R [ijk]

in this def. R is simply [xyz]^T

generalizedDegreeOfOrder(t): Return the generalized degree of order of tensor t.

t is a varTensor.VarTensor instance. The generalized degree of order is
defined as sqrt((2/3)*sum(Sij**2)), where sqrt is the square root and the
sum extends over all ij elements of the associated Saupe order matrix (Sij).

Reference: Tolman et al. JACS (2001) 123:1416.

getVarTensors(potList): given a list of potential terms, return a list of unique VarTensor
objects either in the list or refered to by another potential type.

massSetup(list=[], axisMass=300, pAtomFactor=3): appropriately setup tensor atom masses.
tensor orientational atom's masses are set to axisMass, and
the parameter atom masses are set to axisMass * pAtomFactor.

if list is not specified, then all registered VarTensor objects are
configured.

normalizedScalarProduct(t1, t2): Return the normalized scalar product between tensors t1 and t2.

t1 and t2 are varTensor.VarTensor instances. The normalized scalar product
is defined by Sass et al. JACS (1999) 121:2047-2055.

orthogonalize(t): given a VarTensor t, check that the axis atoms are orthgonal. If not,
print a warning message and then orthonalize.

registerExptToVarTensor(varTensor, expt): add the term expt to the varTensor.VarTensor's expts list.

saupeMatrix(t, eIndex=0): given a VarTensor, calculate the associated Saupe matrix.
The eIndex argument is used for ensembles in which members are allowed
different alignment tensors.

saupeToVarTensor(mat, Dmax=1): given a Saupe matrix as a mat3.SymMat3, generate a
varTensor.VarTensor object with whose orientation axis, Da, and Rh
correspond to the input matrix. The Saupe matrix can be premultiplied by
Dmax or, optionally, it can be supplied as a separate argument.

If an ensembleSimulation.EnsembleSimulation is active, the input
tensors can be different for each ensemble member.

Note that the generated VarTensor object is accompanied by pseudoatoms,
and the term is registered within varTensorTools, so that full
cleanup of the VarTensor object reqires a call to
unregisterTerm and deletePseudoAtoms.

scalarProd(t1, t2): Calculate the (unnormalized) scalar product between tensors t1 and t2.

For internal use.

syncAxisAtoms(t): copy atoms representing orientation to member simulations>0

topologySetup(ivm, list=[]): configure the given IVM object's topology setup using the freedom string
for each VarTensor in list. This function should be called prior to
ivm.IVM.autoTorsion() or protocol.torsionTopology()

The freedom language contains the following keywords:
   fix
   fixAxis
   fixDa, varyDa
   fixRh, varyRh
   fixAxisTo <name>
   fixRhTo <name>
   ignore

More than one can be specified, using a comma as a seperator.

xyzFromEuler(tensor, phi, theta, psi): set the x, y, and z axes of tensor to correspond to the
given Euler phi, theta and psi rotations (in radians)

Data
		current_axisResid = 5000 current_axisSegid = 'AXIS' psfTemplate = '\nstructure\nPSF\n\n 3 !NTITLE\n REMARKS auto... 0 !NGRP\n 0 0 0\nend \n'