document CoordGroupHandle and CoordFrame classes

modules/index.rst

@@ -41,7 +41,9 @@ For Starters
 Molecules
 --------------------------------------------------------------------------------
 
-**Overview**: :doc:`molecules intro <intro-01>` | :doc:`mol overview <mol/base/mol>` | :doc:`graphical entity<gfx/entity>` | :doc:`entity <mol/base/entity>` | :doc:`queries <mol/base/query>`
+**Overview**: :doc:`molecules intro <intro-01>` | :doc:`mol overview <mol/base/mol>` | :doc:`graphical entity<gfx/entity>` | :doc:`entity <mol/base/entity>` | :doc:`queries <mol/base/query>` | :doc:`algorithms <mol/alg/molalg>`
+
+**Trajectories**: :doc:`basics <mol/base/traj>` | :ref:`analysis <traj-analysis>`
 
 **Input/Output**: :ref:`loading and saving molecules <mol-io>`
 

modules/mol/alg/doc/molalg.rst

@@ -82,6 +82,8 @@ The following function detects steric clashes in atomic structures. Two atoms ar
   :returns: The filtered :class:`~ost.mol.EntityView`
 
 
+.. _traj-analysis:
+
 Trajectory Analysis
 --------------------------------------------------------------------------------
 

modules/mol/base/doc/entity.rst

@@ -583,7 +583,18 @@ The Handle Classes
     
   .. attribute:: pos
   
-    The atom's position in global coordinates. Also available as :meth:`GetPos`.
+    The atom's position in global coordinates, transformed by the entity 
+    transformation. Also available as :meth:`GetPos`.
+    
+    Read-only.
+    
+    :type: :class:`~ost.geom.Vec3`
+    
+  .. attribute:: original_pos
+  
+    The atom's untransformed position in global coordinates. Also available as 
+    :meth:`GetOriginalPos`.
+    
     Read-only.
     
     :type: :class:`~ost.geom.Vec3`

modules/mol/base/doc/mol.rst

@@ -12,4 +12,5 @@ The mol module implements data structures to work with molecular datasets. At it
   entity
   editors
   query
-  surface
\ No newline at end of file
+  surface
+  traj
\ No newline at end of file

modules/mol/base/doc/traj.rst

+Trajectories
+================================================================================
+
+.. currentmodule:: ost.mol
+
+
+.. function:: CreateCoordGroup(atoms)
+
+  :param atoms: List of atoms. All atoms must be from the same entity.
+  :type atoms: :class:`AtomHandleList`
+  
+  :rtype: :class:`CoordGroupHandle`
+  :returns: A coord group with zero frames
+  
+.. class:: CoordGroupHandle
+
+  A collection of coordinate frames, e.g. an MD trajectory. Create with 
+  :func:`CreateCoordGroup`.
+  
+  
+  .. attribute:: entity
+  
+    The attached entity.
+    
+    :type: :class:`EntityHandle`
+    
+  .. attribute:: atoms
+  
+    The atoms of this coord group. The order of atoms is the same as the 
+    positions in the coord frames. All atoms are from the same entity.
+    
+    :type: :class:`AtomHandleList`
+  .. method:: AddFrames(frames)
+
+    Combine two trajectories by appending the frames of the second to the first
+    :param frames: a valid coord group
+    :type  frames: :class:`CoordGroupHandle`
+
+  .. method:: Capture()
+
+    Record the atom positions of the entity attached to this coord group in a 
+    new coordinate frame. Note that the atom positions transformed by the entity 
+    transform will be stored. Only available for mutable coord groups.
+    
+    :see: :attr:`AtomHandle.pos`
+
+  .. method:: CaptureInto(frame_index)
+
+    Same as :meth:`Capture`, but doesn't create a new frame and stores the 
+    coordinates directly into frame with index *frame_index*. Only available for 
+    mutable coord groups.
+    
+    :param frame_index: index of the frame
+    :type  frame_index: int
+
+  .. method:: CopyFrame(frame_index)
+
+    Copies the coordinates of frame with index *frame_index* to the attached 
+    entity.
+    
+    :param frame_index: index of the frame
+    :type  frame_index: int
+
+  .. method:: Filter(view)
+
+    Returns a new trajectory containing only coordinates of the atoms in view. 
+    Useful to remove water and other solvent molecules from a trajectory to 
+    save memory.
+    
+    :param view: a valid entity view
+    :type  view: :class:`EntityView`
+    :rtype: :class:`CoordGroupHandle`
+
+  .. method:: GetAtomCount()
+
+    Returns the number of atoms in the coord group
+    
+    :rtype: int
+
+
+  .. method:: GetAtomList()
+
+    Returns the atoms of the coord group in the same order they appear in the 
+    coordinate frames.
+    
+    :rtype: :class:`AtomHandleList`
+
+  .. method:: GetAtomPos(frame_index, atom)
+
+    Get position of *atom* in frame with index *frame_index*.
+    
+
+    :param frame_index: frame index
+    :type  frame_index: int
+    :param atom: A valid atom
+    :type  atom: :class:`AtomHandle`
+    :rtype: :class:`Vec3`
+
+  .. method:: GetEntity()
+
+    Returns the attached entity
+    
+    :rtype: :class:`EntityHandle`
+
+  .. method:: GetFrameCount()
+
+    Returns the number of frames of this coord group
+    
+    :rtype: int
+
+  .. method:: IsValid()
+
+    Whether this coord group is valid
+    
+    :rtype: bool
+
+  .. method:: SetAtomPos(frame_index, atom, pos)
+
+    Set position of *atom* in frame with index *frame_index* to *pos*
+    
+    :param frame_index: index of the frame
+    :type  frame_index: int
+    :param atom: a valid atom
+    :type  atom: :class:`AtomHandle`
+    :param pos: new position of the atom
+    :type  pos: :class:`Vec3`
+
+  .. method:: SetFramePositions(frame_index, positions)
+
+    Set the frame positions of frame with index *frame_index*. Order and count 
+    of positions must match :attr:`atoms`.
+    
+    :param frame_index: index of frame
+    :type  frame_index: int
+    :param positions: list of positions
+    :type  positions: :class:`~ost.geom.Vec3List`
+
+
+.. class:: CoordFrame
+
+  A single frame of coordinates in a :class:`CoordGroupHandle`.
+  
+  .. method:: GetAngle(atom1, atom2, atom3)
+
+    :param atom1: first atom
+    :type  atom1: :class:`AtomHandle`
+    :param atom2: second (central) atom
+    :type  atom2: :class:`AtomHandle`
+    :param atom3: third atom
+    :type  atom3: :class:`AtomHandle`
+    
+    :returns: the angle in radians between the 3 atoms
+    :rtype: float
+
+  .. method:: GetAtomPos(atom)
+
+    Returns the position of the atom in the coord frame
+    
+    :param atom: A valid atom handle
+    :type  atom: :class:`AtomHandle`
+    
+
+    
+    :rtype: :class:`Vec3`
+
+  .. method:: GetCenterOfMassPos(view)
+
+    
+    :param view: A valid entity view
+    :type  view: :class:`EntityView`
+    :rtype: :class:`Vec3`
+
+  .. method:: GetDihedralAngle(atom1, atom2, atom3, atom4)
+
+    Get dihedral angle of the four atoms.
+    
+    :param atom1: First atom. Must be valid
+    :type  atom1: :class:`AtomHandle`
+    :param atom2: Second atom. Must be valid
+    :type  atom2: :class:`AtomHandle`
+    :param atom3: Third atom. Must be valid
+    :type  atom3: :class:`AtomHandle`
+    :param atom3: Fourth atom. Must be valid
+    :type  atom3: :class:`AtomHandle`
+    
+    :rtype: float
+
+  .. method:: GetDistanceBetwAtoms(atom1, atom2)
+
+    Get distance in (Angstroem) between *atom1* and *atom2* in coord frame.
+    
+    :param atom1: First atom. Must be valid
+    :type  atom1: :class:`AtomHandle`
+    :param atom2: Second atom. Must be valid
+    :type  atom2: :class:`AtomHandle`
+    :rtype: float
+
+  .. method:: GetDistanceBetwCenterOfMass(view1, view2)
+
+    Get distance between center of mass of the first selection and the second.
+    
+    :param view1: First view. Must be valid
+    :type  view1: :class:`EntityView`
+    :param view2: Second view. Must be valid
+    :type  view2: :class:`EntityView`
+    :rtype: float
+
+  .. method:: GetRMSD(view1, view2)
+
+    Get RMSD between two views in the coord frame. The coordinates of the views 
+    are taken as is without superposition. The two views must have the same 
+    number of atoms. Atoms are matches as they appear in 
+    :attr:`EntityView.atoms`.
+    
+    :param view1: First view. Must be valid
+    :type  view1: :class:`EntityView`
+    :param view2: Second view. Must be valid
+    :type  view2: :class:`EntityView`
+    :rtype: float
+

modules/mol/base/pymod/export_atom.cc

@@ -53,6 +53,9 @@ void export_Atom()
     .add_property("pos",
                   make_function(&AtomBase::GetPos,
                                 return_value_policy<copy_const_reference>()))
+    .add_property("original_pos",
+                  make_function(&AtomBase::GetOriginalPos,
+                                return_value_policy<copy_const_reference>()))
     .add_property("name",
                   make_function(&AtomBase::GetName,
                                 return_value_policy<copy_const_reference>()),

modules/mol/base/pymod/export_coord_group.cc

@@ -53,6 +53,7 @@ void export_CoordGroup()
     .def("GetAtomPos",&CoordGroupHandle::GetAtomPos)
     .def("CopyFrame",&CoordGroupHandle::CopyFrame)
     .add_property("atoms", &CoordGroupHandle::GetAtomList)
+    .add_property("entity", &CoordGroupHandle::GetEntity)
     .def("IsValid", &CoordGroupHandle::IsValid)
     .def("Capture", capture1)
     .def("Capture", capture2)