introduce an upper bound in el enumerador and change the interface

check the updated docu for the exact behaviour

modelling/doc/algorithms.rst

@@ -30,29 +30,42 @@ have a CA distances closer than 10A). This graph gets then decomposed into
 a minimal width tree and solved in a similar manner as in the sidechain
 modelling problem. This typically massively reduces the problem size by solving
 small subproblems and allows to tackle larger problems in a feasible amount
-of computing time.
-
-.. method:: ElEnumerador(mhandle, loop_candidates, start_resnums, \
-                         chain_indices, weights, [fill_solution = true])
-
-  Searches the the loops in **loop_candidates** that optimize the
-  score using the scorer that is set in **mhandle** and the given **weights**.
-  If **fill_solution** is true, they get directly set in the model and in the 
-  scoring environment attached to the **mhandle**.
+of computing time. Despite massively reducing the amount of loop scoring
+and set environment calls, we still need to define an upper bound of computation 
+time. After building the minimal width tree, one can already determine the
+exact number of loop scoring calls required to solve that tree. This measure
+turnes out to be an accurate measure of overall runtime, since the scoring
+clearly is the dominant operation. ElEnumerador checks, whether this number
+is above a user defined threshold. If yes, the 20% worst scoring loop candidates
+from the location with the largest amount of loop candidates gets removed and
+a new tree gets generated. Please note, that this scoring step only 
+considers the already set environment and no pairwise interactions to other
+loops. A global optimum is therefore not guaranteed, but still very likely.
+
+.. method:: ElEnumerador(mhandle, gaps, loop_candidates, weights, \
+                         [max_pruning_iterations=100, max_complexity=1000000])
+
+  Searches the loops in **loop_candidates** with their exact locations defined
+  in **gaps** that optimize the score using the scorer that is set in 
+  **mhandle** and the given **weights**. The algorithm performs a maximum of
+  **max_pruning_iterations** of the previously described pruning iterations
+  until every connected component in the interaction graph can be solved with
+  the number of required loop scoring calls being lower than **max_complexity**.
+  There is no guarantee that this is achieved (but it's super likely). 
+  In case of success, the algorithm updates **mhandle** with its attached model, 
+  gap list and scoring environment.
+  
 
   :param mhandle:       A handle with valid scorer attached, that contains
                         all scores for which you defined a weight in 
                         **weights**
+  :param gaps:          A list of gaps specifying the loop locations
   :param loop_candidates: A list of :class:`LoopCandidates` objects defining
-                          loops at different locations. They must not overlap!
-  :param start_resnums: A list defining the start resnum for every
-                        :class:`LoopCandidates` object.
-  :param chain_indices: A list of chain indices defining to which chain the
-                        :class:`LoopCandidates` belong.
+                          loops at different locations.
   :param weights:       The weights used for a linear combinations of scores
 
-  :param fill_solution: Whether to fill the solution in the model and
-                        backbone_scorer_env of **mhandle**
+  :param max_pruning_iterations: Maximum number of pruning iterations before
+                                 giving up
 
 
   :type mhandle:        :class:`ModellingHandle`

modelling/pymod/export_el_enumerador.cc

@@ -8,34 +8,21 @@ using namespace promod3::modelling;
 
 namespace{
 
-boost::python::list WrapEnumerador(ModellingHandle& mhandle,
-                                   const boost::python::list& loop_candidates,
-                                   const boost::python::list& start_resnums,
-                                   const boost::python::list& chain_indices,
-                                   const boost::python::dict& weights,
-                                   bool fill_solutions){
-
-  std::vector<promod3::modelling::LoopCandidates> v_loop_candidates;
-  std::vector<uint> v_start_resnums;
-  std::vector<uint> v_chain_indices;
+void WrapEnumerador(ModellingHandle& mhandle,
+                    const StructuralGapList& gaps,
+                    const boost::python::list& loop_candidates,
+                    const boost::python::dict& weights,
+                    uint max_pruning_iterations,
+                    uint max_complexity){
+
+  std::vector<promod3::modelling::LoopCandidatesPtr> v_loop_candidates;
   std::map<String,Real> m_weights;
 
   promod3::core::ConvertListToVector(loop_candidates, v_loop_candidates);
-  promod3::core::ConvertListToVector(start_resnums, v_start_resnums);
-  promod3::core::ConvertListToVector(chain_indices, v_chain_indices);
   promod3::core::ConvertDictToMap(weights, m_weights);
-
-  std::vector<int> solution = promod3::modelling::ElEnumerador(mhandle, 
-                                                               v_loop_candidates, 
-                                                               v_start_resnums, 
-                                                               v_chain_indices, 
-                                                               m_weights,
-                                                               fill_solutions);
-
-  boost::python::list return_list;
-  promod3::core::AppendVectorToList(solution,return_list);
-
-  return return_list;
+  promod3::modelling::ElEnumerador(mhandle, gaps, v_loop_candidates, 
+                                   m_weights, max_pruning_iterations,
+                                   max_complexity);
 }
 
 }
@@ -46,8 +33,11 @@ boost::python::list WrapEnumerador(ModellingHandle& mhandle,
 
 void export_el_enumerador(){
 
-  def("ElEnumerador", &WrapEnumerador, (arg("mhandle"),arg("loop_candidates"),
-                                        arg("start_resnums"),arg("chain_indices"),
-                                        arg("weights"),arg("fill_solutions")=true));
+  def("ElEnumerador", &WrapEnumerador, (arg("mhandle"),
+                                        arg("gaps"), 
+                                        arg("loop_candidates"),
+                                        arg("weights"),
+                                        arg("max_pruning_iterations") = 100,
+                                        arg("max_complexity")=1000000));
 
 }
\ No newline at end of file

modelling/src/el_enumerador.hh

@@ -8,12 +8,12 @@
 
 namespace promod3 { namespace modelling {
 
-std::vector<int> ElEnumerador(ModellingHandle& mhandle, 
-                               const std::vector<LoopCandidates>& loop_candidates,
-                               const std::vector<uint>& start_resnums,
-                               const std::vector<uint>& chain_indices,
-                               const std::map<String,Real>& weights,
-                               bool fill_solution = true);
+void ElEnumerador(ModellingHandle& mhandle,                  
+                  const StructuralGapList& gaps,
+                  std::vector<LoopCandidatesPtr>& loop_candidates,
+                  const std::map<String,Real>& weights,
+                  uint max_pruning_iterations = 100,
+                  uint max_complexity = 10000000);
 
 }} //ns