modify or analyze an AtomSel

Member classes perform actions on atom objects associated with an
<m atomSel>.AtomSel object. These are invoked using the apply() method 
of an AtomSel object. A user-defined AtomSelAction can be defined by
creating a class which derives from the PyAtomSelAction class.

Constituent classes:

SetProperty(name,value)
    set named property of all <m atom>.Atoms in a selection

    The arguments are the name is a property of an Atom (e.g. pos) and 
    new value to use.

  Example:

    sel = AtomSel("name HN")
    sel.apply( SetProperty("atomName","H") )
    from vec3 import Vec3
    sel.apply( SetProperty("pos",Vec3(0,0,0)) )


SetVelAction(velVal)

  will set velocities of all atoms in the atom selection to the 
value velVal, of type <m vec3>.Vec3.

Translate(transVal)

  will translate coordinates of all atoms in the selection to the 
value transVal, of type <m vec3>.Vec3.

Rotate(rotMat,centerVec)

  will apply the rotation operation q = rotMat * (q-centerVec)
to the positions of all atoms in the selection, where q is the atom
position. If centerVec is omitted, it is taken to be the origin.
rotMat is of type <m mat3>.Mat3, and centerVec is of type <m
vec3>.Vec3. 

Fit(fitTo,fitBy,altCoords)

  will perform an rmsd fitting to the list of atomic coordinates
specified in fitTo. fitBy is an <m atomSel>.AtomSel which specifies
which coordinates are used in the rmsd calculation (all known atoms by
default). If altCoords is specified, use these instead of those in the
selection to calculate the fit (but still perform the fit
transformation on the coordinates of the AtomSel). Once constructed a
Fit object contains the methods rotation() and translation() which
return R and T, the rotation matrix and translation vector which
transform the initial coordinates into the fit coordinates by the
expression:
  
   qFit = R q + T

The actual transformation is applied using an AtomSel's apply()
method. Alternately, fitTo can be an AtomSel (with the same number of
atoms as fitBy). Using an AtomSel allows one to fit different
coordinates within a Simulation, or within different Simulations.


RMSD(compare)

  compute the rmsd of the atoms of the AtomSel with the contents of
compare.  Compare can be a list of atomic coordinates (of length
sel.simulation().numAtoms()) or an <m atomSel>.AtomSel with the correct
number of atoms.  Using an AtomSel allows one to compare different
coordinates within a Simulation, or within different Simulations.  No
property of the AtomSel is modified. Rather, after calling the
AtomSel's apply() method, one can access two methods of the RSMD
object:
    rmsd() 
      the overall rmsd 
    byResidue()
      returns a dictionary, which contains per-residue RMSD values
      indexed by residue number.


examples:

#translate all atoms 3 angstroms in the x direction
#
from atomSelAction import Translate
AtomSel("all").apply( Translate(Vec3(3,0,0)) )

#use the alpha carbons to compute a rigid-body fit to the
#corresponding coordinates stored in fitTo. 
#All known atoms are then moved according to the fit transformation.
#
AtomSel("known").apply( Fit(fitTo,"name CA") )

#compute the backbone rmsd with the coordinates stored in otherCoords
#the 
#
comparer=RMSD(otherCoords)
AtomSel("name C or name CA or name N").apply(comparer)
for resid in comparer.byResidue().keys():
	print resid, comparer.byResidue()[resid]