docu update and fixed python export

actions/doc/index_dev.rst

@@ -202,7 +202,7 @@ happens if a user throws dirty input data in.
 
 Making the Script Executable
 --------------------------------------------------------------------------------
-In |project|, unit tests are run via |ost_s|_ and |python|'s
+In |project|, unit tests are run via |ost_s|_'s :mod:`ost.testutils` and |python|'s
 :class:`unittest.TestCase`. Those are called when the test module is executed
 as a script:
 

doc/buildsystem.rst

@@ -5,20 +5,21 @@ Building |project|
 Dependencies
 --------------------------------------------------------------------------------
 |project| is build on top of |ost_l|_ (|ost_s|), requiring at least version
-1.4, and |qmean|_. To create the build system, |cmake|_ is required in version
+1.4. To create the build system, |cmake|_ is required in version
 2.8.7 or higher. |python|_ works well from version 2.7. For |ost_s| and the
 |C++| bit of |project|, |boost|_ is required in version 1.47.0 (the same as
 used for |ost_s|). Also |eigen3|_ and |lapack|_ are needed. To build
 documentation, |sphinx|_ 1.2b1 is used.
 
+The currently (Nov. 2015) preferred versions are:
+
 * |ost_s|_ 1.4
-* |qmean|_
-* |cmake|_ 2.8.7
-* |python|_ 2.7
-* |boost|_ 1.47.0
-* |sphinx|_ 1.3.1
+* |cmake|_ 2.8.12
+* |python|_ 2.7.5
+* |boost|_ 1.53.0
 * |eigen3|_ 3.2.1
-* |lapack|_ 3.0
+* |lapack|_ 3.4.2
+* |sphinx|_ 1.3.1
 
 --------------------------------------------------------------------------------
  Using |cmake|
@@ -26,20 +27,25 @@ documentation, |sphinx|_ 1.2b1 is used.
 |cmake| is used to configure the build system and in the end produces makefiles
 and certain directories needed for building |project|. Basically it is called
 right from a shell with the directory containing the top-level
-:file:`CMakeLists.txt` as an argument:
+:file:`CMakeLists.txt` as an argument. The preferred approach is to generate a
+build folder and configure and compile in there:
 
 .. code-block:: console
 
-   $ cmake . -DOST_ROOT=<PATH TO OST> -DQMEAN_ROOT=<PATH TO QMEAN>
+   # execute this in the ProMod3 root folder
+   $ mkdir build
+   $ cd build
+   $ cmake .. -DOST_ROOT=<PATH TO OST> 
 
-For us, at least pointers to the |ost_s| and |qmean| installation directories
-are needed, handed over to |cmake| by ``-D`` into the variables ``OST_ROOT``
-and ``QMEAN_ROOT``. Other important variables would be ``BOOST_ROOT``, set to
-the same path as for |ost_s| and probably ``PYTHON_ROOT`` if you want to use a
-certain |python|. Also |eigen3| can be pulled in like this, e.g. if you have to
-download it by yourself because its not installed on your system. Just point
-``EIGEN3_INCLUDE_DIR`` to the path which provides the :file:`Eigen` header
-directory. Don't forget to put a ``-D`` in front of options.
+For us, at least pointer to the |ost_s| installation directory is needed, 
+handed over to |cmake| by ``-D`` into the variable ``OST_ROOT`` (e.g. |ost_s|
+headers would be located in ``OST_ROOT/include/ost``).
+
+Similarly, one can specify folders for |boost|, |python|, |eigen3| and |lapack|
+if multiple versions exist and/or they are not installed in a default location.
+These are set with the ``BOOST_ROOT`` (make sure that's the same as for |ost_s|), 
+``PYTHON_ROOT``, ``EIGEN3_INCLUDE_DIR``, ``BLAS_blas_LIBRARY`` (BLAS library used
+by |lapack|) and ``LAPACK_lapack_LIBRARY``.
 
 Here is a list of more options used within |project|:
 
@@ -58,17 +64,23 @@ in the :file:`CMakeCache.txt` of |ost_s|:
 * ``OPTIMIZE``
 * ``OST_DOUBLE_PRECISION``
 
+.. doesn't work (yet?)
+  Instead of providing all those options at the command line, you can also use
+  ``ccmake`` instead of ``cmake``, which allows you to set the |cmake| variables
+  interactively. Press 'c' to try to configure the build. If it fails, enter the
+  requested paths and configure again. Advanced settings can be edited by 
+  pressing 't'.
+
 Instead of calling |cmake| by yourself, there is the :file:`conf-scripts`
 directory, providing smallish scripts to invoke |cmake| the right way for
-various systems. Usually those scripts just need the |ost_s| and |qmean| paths
+various systems. Usually those scripts just need the |ost_s| path
 and the location of the top-level :file:`CMakeLists.txt`.
 
-What we highly recommend is going for out-of-source builds. This means creating
-a dedicated directory for building |project| and calling |cmake| or a
-configuration script from there. This way, you can have several builds with
-different configurations. Also if anything goes wrong, just remove the build
-directory to get to a clean state again. No searching for |cmake| cache files or
-checking if certain files really got rebuild and similar things required.
+As mentioned earlier, we highly recommend to use out-of-source builds. 
+This way, you can have several builds with different configurations. Also if 
+anything goes wrong, just remove the build directory to get to a clean state
+again. No searching for |cmake| cache files or checking if certain files
+really got rebuild and similar things required.
 
 
 Running Make

doc/contributing.rst

 Contributing
 ================================================================================
 The following should explain, in a coarse grain manner, how to add new
-features/ your project to |project|. Important topics are |git| branches, the
+features or your project to |project|. Important topics are |git| branches, the
 directory structure and tightly linked with this also |cmake|. The most general
 advice would be to use existing bits and pieces as examples and to be
 consistent with what you already find here. As an example, documentation

loop/doc/loop_candidate.rst

@@ -94,7 +94,7 @@ Loop Candidates
 
 .. class:: LoopCandidates(n_stem,c_stem,seq)
 
-  The *LoopCandidates* is the basic object used for loop modelling. It contains the positions of the two anchor residues, the *n_stem* and *c_stem* residues, and thes sequence of the residues to be modelled in between these anchor residues.
+  The *LoopCandidates* is the basic object used for loop modelling. It contains the positions of the two anchor residues, the *n_stem* and *c_stem* residues, and the sequence of the residues to be modelled in between these anchor residues.
   It also contains a list of :class:`LoopCandidate`, which are possible conformations of the backbone between the stem residues.
 
 
@@ -137,11 +137,11 @@ Loop Candidates
     :param initial_bb:     Initial configuration used for the sampling
     :param seq:            The sequence of residues to be added between the *n_stem* and *c_stem*
     :param num_loops:      Number of loop candidates to return
-    :param steps:          Number of MC steps to perform for each loop candidate generated.
+    :param steps:          Number of MC steps to perform for each loop candidate generated
+    :param sampler:        Used to generate a new configuration at each MC step
+    :param closer:         Used to close the loop (make it match the *n_stem* and *c_stem* geometry) after each MC step
+    :param scorer:         Used to score the generated configurations at each MC step
     :param cooler:         Controls the temperature profile of the simulated annealing
-    :param scorer:         Used to score the generated configurations at each MC step.
-    :param sampler:        Used to generate a new configuration at each MC step.
-    :param closer:         Used to close the loop (make it match the *n_stem* and *c_stem* geometry) after each MC step. 
 
     :type n_stem:           :class:`ost.mol.ResidueHandle`
     :type c_stem:           :class:`ost.mol.ResidueHandle`
@@ -149,10 +149,10 @@ Loop Candidates
     :type initial_bb:       :class:`BackboneList`
     :type num_loops:        :class:`int`
     :type steps:            :class:`int`
-    :type sampler:          :class:`MonteCarloSampler`
-    :type closer:           :class:`MonteCarloCloser`
-    :type scorer:           :class:`MonteCarloScorer`
-    :type cooler:           :class:`MonteCarloCooler`
+    :type sampler:          :ref:`mc-sampler-object`
+    :type closer:           :ref:`mc-closer-object`
+    :type scorer:           :ref:`mc-scorer-object`
+    :type cooler:           :ref:`mc-cooler-object`
 
     :returns:              A list of loop candidates
     :rtype:                :class:`LoopCandidates`
@@ -165,21 +165,21 @@ Loop Candidates
     :param c_stem:         The residue at the C-terminal end of the loop 
     :param seq:            The sequence of residues to be added between the *n_stem* and *c_stem*
     :param num_loops:      Number of loop candidates to return
-    :param steps:          Number of MC steps to perform for each loop candidate generated.
+    :param steps:          Number of MC steps to perform for each loop candidate generated
+    :param sampler:        Used to generate a new configuration at each MC step
+    :param closer:         Used to close the loop (make it match the *n_stem* and *c_stem* geometry) after each MC step
+    :param scorer:         Used to score the generated configurations at each MC step
     :param cooler:         Controls the temperature profile of the simulated annealing
-    :param scorer:         Used to score the generated configurations at each MC step.
-    :param sampler:        Used to generate a new configuration at each MC step.
-    :param closer:         Used to close the loop (make it match the *n_stem* and *c_stem* geometry) after each MC step. 
 
     :type n_stem:           :class:`ost.mol.ResidueHandle`
     :type c_stem:           :class:`ost.mol.ResidueHandle`
     :type seq:              :class:`str`
     :type num_loops:        :class:`int`
     :type steps:            :class:`int`
-    :type sampler:          :class:`MonteCarloSampler`
-    :type closer:           :class:`MonteCarloCloser`
-    :type scorer:           :class:`MonteCarloScorer`
-    :type cooler:           :class:`MonteCarloCooler`
+    :type sampler:          :ref:`mc-sampler-object`
+    :type closer:           :ref:`mc-closer-object`
+    :type scorer:           :ref:`mc-scorer-object`
+    :type cooler:           :ref:`mc-cooler-object`
 
     :returns:              A list of loop candidates
     :rtype:                :class:`LoopCandidates`

loop/doc/monte_carlo.rst

@@ -43,10 +43,10 @@ provided by |project|.
                         The input **bb_list** gets used otherwise.
   :param seed:          Seed for internal random number generator.
 
-  :type cooler:         :class:`CoolerObject`
-  :type scorer:         :class:`ScorerObject`
-  :type sampler:        :class:`SamplerObject`
-  :type closer:         :class:`CloserObject`
+  :type sampler:        :ref:`mc-sampler-object`
+  :type closer:         :ref:`mc-closer-object`
+  :type scorer:         :ref:`mc-scorer-object`
+  :type cooler:         :ref:`mc-cooler-object`
   :type steps:          :class:`int`
   :type bb_list:        :class:`BackboneList`
   :type initialize:     :class:`bool`
@@ -107,8 +107,9 @@ provided by |project|.
 
 
 
+.. _mc-sampler-object:
 
-Sampler Objects
+Sampler Object
 --------------------------------------------------------------------------------
 
 The sampler objects can be used to generate initial conformations and
@@ -298,8 +299,9 @@ for any monte carlo sampling pipeline.
 
 
 
+.. _mc-closer-object:
 
-Closer Objects
+Closer Object
 --------------------------------------------------------------------------------
 
 After the proposal of new conformations by the sampler objects, the
@@ -428,8 +430,9 @@ or simple stem superposition in case of terminal sampling.
   :returns:             Whether closing was successful
 
         
+.. _mc-scorer-object:
 
-Scorer Objects
+Scorer Object
 --------------------------------------------------------------------------------
 
 The scorer asses a proposed conformation and are intended to return a pseudo
@@ -468,7 +471,9 @@ energy, the lower the better.
     :returns:           A linear combination of the scores
 
 
-Cooler Objects
+.. _mc-cooler-object:
+
+Cooler Object
 --------------------------------------------------------------------------------
 
 The cooler objects control the temperature of the monte carlo trajectory.

sidechain/doc/frame.rst

@@ -44,17 +44,16 @@ The Frame Objects
  
 .. class:: Frame(frame_residues)
 
-  :param frame_residues:  
-
-  :type frame_residues: 
-
   The :class:`Frame` object allows to calculate frame energies for rotamers.
   Due to technical reasons, this is only possible if the rotamers are
   part of rotamer groups.
 
+  :param frame_residues:  :class:`list` of :class:`FrameResidue` objects building
+                          the frame.
+
   .. method:: SetFrameEnergy(rotamer_group)
 
-    Calculates and sets frame energies
+    Calculates and sets frame energies for all rotamers in the rotamer group.
 
     :param rotamer_group: group of rotamers for energy calculation
 
@@ -63,8 +62,8 @@ The Frame Objects
   .. method:: AddFrameEnergy(rotamer_group)
 
     Calculates and adds frame energies to the already existing frame
-    energy values. This might be useful if you have several :class:`Frame`
-    objects.
+    energy values for all rotamers in the rotamer group.
+    This is useful if you have several :class:`Frame` objects.
 
     :param rotamer_group: group of rotamers for energy calculation
 
@@ -165,6 +164,8 @@ and sidechain frame residues.
   :raises:              :class:`RuntimeError` when not all required atoms
                         atoms are present in **residue** 
 
+  :returns:             :class:`FrameResidue`
+
 .. method:: ConstructFrameResidue(residue,residue_index)
 
   Constructs a :class:`FrameResidue` from a :class:`ost.mol.ResidueHandle`.
@@ -173,9 +174,11 @@ and sidechain frame residues.
   Atoms of the residue will be represented as carbons.
   
 
-  :param residue:       Reside from which all atoms will be taken to
+  :param residue:       Residue from which all atoms will be taken to
                         construct a :class:`FrameResidue`.
   :param residue_index: Index this :class:`FrameResidue` belongs to.
 
   :type residue:        :class:`ost.mol.ResidueHandle`
   :type residue_index:  :class:`int`
+
+  :returns:             :class:`FrameResidue`

sidechain/doc/graph.rst

@@ -20,7 +20,7 @@ The Interaction Graph
   The Graph object has no constructor exported to python. It is meant to be
   constructed using the static create functions.
 
-  .. method:: CreateFromRRMList(rotamer_groups)
+  .. staticmethod:: CreateFromRRMList(rotamer_groups)
 
     :param rotamer_groups: :class:`RRMRotamerGroup` objects representing the
                            possible sidechain conformations for every amino
@@ -29,7 +29,7 @@ The Interaction Graph
     :type rotamer_groups: :class:`list`
 
 
-  .. method:: CreateFromFRMList(rotamer_groups)
+  .. staticmethod:: CreateFromFRMList(rotamer_groups)
 
     :param rotamer_groups: :class:`FRMRotamerGroup` objects representing the
                            possible sidechain conformations for every amino
@@ -106,8 +106,3 @@ The Interaction Graph
 
 
 
-
-
-
-
-

sidechain/doc/index.rst

@@ -17,10 +17,27 @@ The paper describes the modelling of sidechains using two different rotamer
 models. A rigid model, as well as a flexible model. Both models are implemented
 in PROMOD3 and can be applied in flexible ways.
 
-The most simple way though is the usage of following function:
+Reconstruct Function
+--------------------------------------------------------------------------------
 
 .. currentmodule:: promod3.sidechain.reconstruct_sidechains
 
+The simplest usage of the module is provided by the :func:`Reconstruct` function:
+
+.. code-block:: python
+
+  from ost import io,mol
+  from promod3.sidechain import reconstruct_sidechains
+  
+  #load a protein 
+  prot = io.LoadPDB('1eye',remote=True)
+  #get only amino acids
+  prot = mol.CreateEntityFromView(prot.Select("peptide=true"),True)
+  io.SavePDB(prot,"sidechain_test_orig.pdb")
+  #reconstruct sidechains
+  reconstruct_sidechains.Reconstruct(prot)
+  io.SavePDB(prot,"sidechain_test_rec.pdb")
+
 .. method:: Reconstruct(prot,[,keep_sidechains=False,build_disulfids,rotamer_model="frm",consider_hbonds=True,rotamer_library=None,add_polar_hydrogens=False])
 
   .. currentmodule:: promod3.sidechain
@@ -66,14 +83,19 @@ The most simple way though is the usage of following function:
   :type add_polar_hydrogens: :class:`bool`
 
 
-Following code fragment shows an example of a basic sidechain reconstruction
+Sidechain Module Functionality
+--------------------------------------------------------------------------------
+
+.. currentmodule:: promod3.sidechain
+
+The following code fragment shows an example of a basic sidechain reconstruction
 algorithm using the functionality in the module. Note, that this code will
 crash as soon as you have structures containing all the weirdness the PDB throws
-at us. In this case you should use the Reconstruct function above. An overview
-of the full provided functionality can be found at the bottom of this page.
+at us. In this case, you should use the :func:`~promod3.sidechain.reconstruct_sidechains.Reconstruct` function above. An overview of the full provided functionality can be found at the bottom of this page.
 
 .. code-block:: python
   
+  from ost import io,mol
   from promod3 import sidechain
 
   #load a protein, the rotamer library and the settings with default values
@@ -82,7 +104,7 @@ of the full provided functionality can be found at the bottom of this page.
   library = sidechain.LoadDunbrackLib()
 
   #let's create a new entity from the protein only containing the amino acids
-  prot = ost.mol.CreateEntityFromView(prot.Select("peptide=true"),True)
+  prot = mol.CreateEntityFromView(prot.Select("peptide=true"),True)
 
   #gather some data, the rotamer ids and backbone torsion angles
   torsion_angles = list()
@@ -112,10 +134,8 @@ of the full provided functionality can be found at the bottom of this page.
                                                               torsion_angles[i][0],
                                                               i == 1, 
                                                               i == (len(rotamer_ids)-1))
-
       frame_residues.append(frame_residue)
 
-
   frame = sidechain.Frame(frame_residues)
 
 
@@ -135,7 +155,7 @@ of the full provided functionality can be found at the bottom of this page.
       #internal and frame energy have to be calculated directly
       rot_group.CalculateInternalEnergies()
       frame.SetFrameEnergy(rot_group)
-      #remove supper unlikely rotamer in rotamer group 
+      #remove super unlikely rotamer in rotamer group 
       #e.g. those who clash with the frame
       rot_group.ApplySelfEnergyThresh()
       #finally add it and keep track of the indices

sidechain/doc/rotamer.rst

@@ -23,6 +23,9 @@ like term and an approximation of an hbond energy term.
 The Lennard-Jones term gets mainly controlled by the type of the particle, that
 has to be defined at initialization.
 
+.. class:: SidechainParticle
+
+  Enumerates the types of particle. Possible values:
 
   * HParticle   - represents hydrogen
   * CParticle   - default representation of a carbon
@@ -34,19 +37,17 @@ has to be defined at initialization.
   * OCParticle  - represents carbonyl-oxygen for ASP/GLU
   * SParticle   - represents sulfur
 
-
 .. class:: Particle(type, pos, charge, name)
 
-  :param type:          Type of particle, must be one of the ParticleTypes 
-                        described above
+  :param type:          Type of particle
   :param pos:           Positions of particle
   :param charge:        Charge of particle, will be used in case H-Bonds
   :param name:          Name of particle. This name will be given to an actual
                         :class:`ost.mol.AtomHandle` if a rotamer gets applied
                         to a :class:`ost.mol.ResidueHandle`
 
+  :type type:           :class:`SidechainParticle`
   :type pos:            :class:`ost.geom.Vec3`
-
   :type charge:         :class:`float`
   :type name:           :class:`str`
 

sidechain/doc/rotamer_id.rst

@@ -12,6 +12,10 @@ that affect the hbond term or different versions of proline/cysteine.
 The RotamerID
 --------------------------------------------------------------------------------
 
+.. class:: RotamerID
+
+  Enumerates the amino acids. Possible values:
+  
   * ARG - Arginine
   * ASN - Asparagine
   * ASP - Aspartate
@@ -40,11 +44,14 @@ The RotamerID
   * ALA - Alanine
   * XXX - Invalid
   
+  The RotamerID enum can be accessed either directly as ``promod3.sidechain.ARG``
+  or as ``promod3.sidechain.RotamerID.ARG``.
+
   
 How can I get an ID?
 --------------------------------------------------------------------------------
 The RotamerID enum can directly be accessed from Python. Two convenient
-functions exist to get RotamerIDs from the ost.conop.AminoAcid enum
+functions exist to get RotamerIDs from the :class:`ost.conop.AminoAcid` enum
 or from amino acid three letter codes.
 
 .. method:: TLCToRotID(tlc)

sidechain/pymod/export_rotamer_ids.cc

@@ -39,4 +39,6 @@ void export_RotamerIDs()
   ;
 
   def("TLCToRotID",&TLCToRotID,(arg("tlc")));
+
+  def("AAToRotID",&AAToRotID,(arg("aa")));
 }