varTensorTools index/home/schwitrs/xplor/python/varTensorTools.py

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=5, 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)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 requires 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     fixRhTo     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'