finalize and document new atom property interface

This finishes changes started in the mem-optimize branch to
remove the AtomProp class from the public interface.

examples/demos/the_hammer.py

@@ -12,7 +12,7 @@ class Anim(QtCore.QTimer):
         self.b=b
         self.angle=0.0
         self.dir=0.01
-        self.edi=self.a.view.handle.RequestXCSEditor(mol.EditMode.UNBUFFERED_EDIT)
+        self.edi=self.a.view.handle.EditXCS(mol.UNBUFFERED_EDIT)
         QtCore.QObject.connect(self, QtCore.SIGNAL("timeout()"), self.OnTimer)
 
         
@@ -34,17 +34,15 @@ class Anim(QtCore.QTimer):
 
 def Hammer(off=geom.Vec3()):
   ent=mol.CreateEntity()
-  edi=ent.RequestXCSEditor(mol.EditMode.BUFFERED_EDIT)
+  edi=ent.EditXCS(mol.BUFFERED_EDIT)
   chain=edi.InsertChain("A")
   res=edi.AppendResidue(chain, "QUAD")
-  prop=mol.AtomProp()
-  prop.radius=1.0
-  a=edi.InsertAtom(res, "A", off+geom.Vec3(0.0, 0.0, 0.0), prop)
-  b=edi.InsertAtom(res, "B", off+geom.Vec3(0.0, 4.0, 0.0), prop)  
-  c=edi.InsertAtom(res, "C", off+geom.Vec3(2.0, 4.0, 0.0), prop)  
-  d=edi.InsertAtom(res, "D", off+geom.Vec3(2.0, 5.0, 0.0), prop)    
-  e=edi.InsertAtom(res, "E", off+geom.Vec3(-2.0, 5.0, 0.0), prop)      
-  f=edi.InsertAtom(res, "F", off+geom.Vec3(-2.0, 4.0, 0.0), prop)        
+  a=edi.InsertAtom(res, "A", off+geom.Vec3(0.0, 0.0, 0.0), "H")
+  b=edi.InsertAtom(res, "B", off+geom.Vec3(0.0, 4.0, 0.0), "H")
+  c=edi.InsertAtom(res, "C", off+geom.Vec3(2.0, 4.0, 0.0), "H")
+  d=edi.InsertAtom(res, "D", off+geom.Vec3(2.0, 5.0, 0.0), "H")
+  e=edi.InsertAtom(res, "E", off+geom.Vec3(-2.0, 5.0, 0.0), "H")
+  f=edi.InsertAtom(res, "F", off+geom.Vec3(-2.0, 4.0, 0.0), "H")
   edi.Connect(a, b)
   edi.Connect(b, c)
   edi.Connect(c, d)
@@ -55,17 +53,17 @@ def Hammer(off=geom.Vec3()):
 
 def TheWall():
   ent=mol.CreateEntity()
-  edi=ent.RequestXCSEditor(mol.EditMode.BUFFERED_EDIT)
+  edi=ent.EditXCS(mol.BUFFERED_EDIT)
   chain=edi.InsertChain("A")
   res=edi.AppendResidue(chain, "QUAD")
-  prop=mol.AtomProp()
-  prop.radius=0.25
   index=0
   for i in range(-10, 10):
     for j in range(-10, 10):
       index+=1
-      edi.InsertAtom(res, "A%d" % index, geom.Vec3(4.0, -2.0, 0.0)+
-                     geom.Vec3(i, 0, j)*0.25, prop)
+      atom=edi.InsertAtom(res, "A%d" % index, geom.Vec3(4.0, -2.0, 0.0)+
+                          geom.Vec3(i, 0, j)*0.25)
+      atom.radius=0.25
+                     
   return ent
 
 a=Hammer()

modules/mol/base/doc/editors.rst

@@ -64,10 +64,14 @@ The basic functionality of editors is implemented in the EditorBase class.
      :type  residue_name: string
      :returns:     :class:`ResidueHandle`
   
-  .. method:: InsertAtom(residue, atom_name, pos, [prop=mol.AtomProp()])
+  .. method:: InsertAtom(residue, atom_name, pos, element="", occupancy=1.0, b_factor=0.0, is_hetatm=False)
   
     Insert new atom and add it to residue. For atoms with alternative atom
-    locations use :meth:`InsertAltAtom`.
+    locations use :meth:`InsertAltAtom`. If the element parameter is a valid 
+    element, the atom properties mass, charge, and radius are set to default 
+    values for that element. If element is an empty string (or an invalid 
+    element), the properties are set to rather meaningless default values. You 
+    may later set any of the properties manually.
     
     :param residue:   is the parent residue and must be valid
     :type residue:    :class:`ResidueHandle`
@@ -79,10 +83,18 @@ The basic functionality of editors is implemented in the EditorBase class.
     :type atom_name:  string
     :param pos:       is the position of the atom in global coordinates
     :type pos:        :class:`geom.Vec3`
-    :param prop:      are the atom's properties such as element, van der Waals 
-                      radius charge and so on. The default set of atom
-                      properties is rather meaningless.
-    :type prop:       class:`AtomProp`
+    :param element:   is the atom's element. If set to a a valid element,
+                      atom properties such as mass, charge, radius are set 
+                      based on default values for that element. If the element 
+                      string is empty, or unknown, the properties are filled 
+                      with rather meaningless default values.
+    :type element:    class:`string`
+    :param occupancy: The occupancy of the atom. between 0 and 1
+    :type occupancy:  float
+    :param b_factor:  temperature factor.
+    :type  b_factor:  float
+    :param is_hetatm: whether the atom is an atom coming from a HETATM record.
+    :type is_hetatm:  bool
     :returns:         :class:`AtomHandle`
 
 Editor for the External Coordinate System

modules/mol/base/doc/entity.rst

@@ -591,25 +591,32 @@ The Handle Classes
   .. attribute:: radius
   
     The van-der-Waals radius of the atom. Also available as :meth:`GetRadius`. 
-    Read-only.
+    Read/write.
     
     :type: float
   
   .. attribute:: occupancy
   
-    The atom's occupancy in the range 0 to 1. Also available as 
-    :meth:`GetOccupancy`. Read-only.
-    
+    The atom's occupancy in the range 0 to 1. Read/write. Also available as 
+    meth:`GetOccupancy`, :meth:`SetOccupancy`.
     :type: float
+    
+  .. attribute:: b_factor
+  
+    The atom's temperature factor. Read/write. Also available as 
+    :meth:`GetBFactor`, :meth:`SetBFactor`.
+    
+    :type: float    
+
   .. attribute:: charge
     
-    The atom's charge
+    The atom's charge. Also available as :meth:`GetCharge`, :meth:`SetCharge`.
     
     :type: float
 
   .. attribute:: residue
   
-    The residue this atom belongs to.
+    The residue this atom belongs to. Read-only.
     
     :type: :class:`ResidueHandle`
   
@@ -634,11 +641,7 @@ The Handle Classes
     :type  other_atom: :class:`AtomHandle`
     :rtype: :class:`BondHandle`
 
-  .. method:: GetAtomProps()
-    
-    Get atom properties such as mass, charge, element and occupancy.
-    
-    :rtype: :class:`AtomProp`
+
 
   .. method:: GetBondCount()
     

modules/mol/base/pymod/export_atom.cc

@@ -50,18 +50,25 @@ void export_Atom()
                   make_function(&AtomBase::GetName,
                                 return_value_policy<copy_const_reference>()),
                   &AtomBase::SetName)
-    .add_property("index",&AtomBase::GetIndex)
+    .add_property("index", &AtomBase::GetIndex)
     
     .def("GetRadius", &AtomBase::GetRadius)
     .def("GetElement", &AtomBase::GetElement, 
          return_value_policy<copy_const_reference>())
     .def("SetElement", &AtomBase::SetElement)
     .def("GetCharge", &AtomBase::GetCharge)
+    .def("GetBFactor", &AtomBase::GetBFactor)
+    .def("SetBFactor", &AtomBase::SetBFactor)
+    .def("SetOccupancy", &AtomBase::SetOccupancy)
+    .def("GetOccupancy", &AtomBase::GetOccupancy)
     .def("GetMass", &AtomBase::GetMass)
     .def("IsHetAtom", &AtomBase::IsHetAtom)
     .def("SetMass", &AtomBase::SetMass)
+    .add_property("b_factor", &AtomBase::GetBFactor, &AtomBase::SetBFactor)
+    .add_property("occupancy", &AtomBase::GetOccupancy, 
+                  &AtomBase::SetOccupancy)
     .def("SetCharge", &AtomBase::SetCharge)
-    .add_property("radius", &AtomBase::GetRadius)
+    .add_property("radius", &AtomBase::GetRadius, &AtomBase::SetRadius)
     .add_property("element", make_function(&AtomBase::GetElement, 
                   return_value_policy<copy_const_reference>()),
                   &AtomBase::SetElement)

modules/mol/base/pymod/export_editors.cc

@@ -54,8 +54,6 @@ void (ICSEditor::*rotate_torsion_b)(const AtomHandle&, const AtomHandle&,
                                     const AtomHandle&, const AtomHandle&,
                                     Real)=&ICSEditor::RotateTorsionAngle;
                                  
-BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_insert_atom_overloads, 
-                                       EditorBase::InsertAtom, 3, 4)
 }
 
 void export_Editors()
@@ -63,7 +61,8 @@ void export_Editors()
   class_<EditorBase>("EditorBase", no_init)
     .def("InsertChain", &EditorBase::InsertChain)
     .def("InsertAtom", &EditorBase::InsertAtom,
-         X_insert_atom_overloads())
+         (arg("residue"), arg("name"), arg("pos"), arg("element")="", 
+          arg("occupancy")=1.0, arg("b_factor")=0.0, arg("is_hetatm")=false))
     .def("InsertAltAtom", &EditorBase::InsertAltAtom)
     .def("DeleteResidue", &EditorBase::DeleteResidue)
     .def("DeleteChain", &EditorBase::DeleteChain)

modules/mol/base/pymod/wrap_mol.cc

@@ -48,6 +48,7 @@ BOOST_PYTHON_MODULE(_mol)
   enum_<EditMode>("EditMode")
     .value("BUFFERED_EDIT", BUFFERED_EDIT)
     .value("UNBUFFERED_EDIT", UNBUFFERED_EDIT)
+    .export_values()
   ;
   export_Entity();
   export_Surface();

modules/mol/base/src/editor_base.cc

@@ -78,11 +78,17 @@ void EditorBase::RenameChain(ChainHandle chain, const String& new_name)
 
 
 AtomHandle EditorBase::InsertAtom(ResidueHandle res, const String& name,
-                                  const geom::Vec3& pos, const String& ele)
+                                  const geom::Vec3& pos, const String& ele,
+                                  Real occupancy, Real b_factor, 
+                                  bool is_hetatm)
 {
   CheckHandleValidity(res);
   ent_.Impl()->MarkTraceDirty();  
-  return AtomHandle(res.Impl()->InsertAtom(name, pos, ele));
+  AtomHandle atom(res.Impl()->InsertAtom(name, pos, ele));
+  atom.SetBFactor(b_factor);
+  atom.SetHetAtom(is_hetatm);
+  atom.SetOccupancy(occupancy);
+  return atom;
 }
 
 AtomHandle EditorBase::InsertAltAtom(ResidueHandle res, const String& name,

modules/mol/base/src/editor_base.hh

@@ -116,7 +116,9 @@ public:
   ///     naming.
   /// \param pos is the position of the atom in global coordinates
   AtomHandle InsertAtom(ResidueHandle residue, const String& name, 
-                        const geom::Vec3& pos, const String& ele="");
+                        const geom::Vec3& pos, const String& ele="",
+                        Real occupancy=1.0, Real b_factor=0.0, 
+                        bool is_hetatm=false);
 
   /// \brief Insert new atom with alternative position indicator
   /// \sa EditorBase::AddAltAtomPos(), ResidueHandle