Documentation of Costzones

Examples/CostZones.hpp

 #ifndef _COSTZONES_HPP_
 #define _COSTZONES_HPP_
 
-//#include <utility>
-#include <stdexcept>
-
+/**
+ * \brief The costzones algorithm implementation.
+ * \author Quentin Khan <quentin.khan@inria.fr>
+ *
+ * This class is an implementation of the costzones algorithm described in 'A
+ * Parallel Adaptive Fast Multipole Method' (1993). The algorithm consists in an
+ * in-order traversal of the octree where cell costs are accumulated. When an
+ * accumulation is too big, a new zone is created.
+ *
+ * \tparam OctreeClass The type of the octree to work on.
+ * \tparam CellClass   The type of the cells we work with.
+ */
 template<typename OctreeClass, typename CellClass>
 class CostZones {
+    /// The current cumulative cost of visited cells.
     unsigned long long _currentCost = 0;
+    /// The total tree cost.
     unsigned long long _totalCost = 0;
-    std::vector< std::pair< int, CellClass*> > _emptyzone;
+    /// The vector containing the costzones.
     std::vector< std::vector< std::pair<int, CellClass*> > > _zones;
 
+    /// The iterator to move through the tree.
     typename OctreeClass::Iterator _it;
+    /// The number of zones to create.
     int _nbZones;
 
+    /// Enumeration to specify the children to move to during the in-order traversal.
     enum ChildrenSide {LEFT, RIGHT};
 
 public:
 
+    /**
+     * \brief Constructor
+     * \param tree    The tree to work on.
+     * \param nbZones The number of zones to create.
+     */
     CostZones(OctreeClass* tree, int nbZones) : 
-        _zones(1, _emptyzone),
+        _zones(1, std::vector< std::pair< int, CellClass*> >( ) ),
         _it(tree),
         _nbZones(nbZones)
         {}
 
-    std::vector< std::vector< std::pair<int, CellClass*> > >& getZones() {return _zones;}
+    /**
+     * \return The computed zones.
+     */
+    std::vector< std::vector< std::pair<int, CellClass*> > >& getZones() {
+        return _zones;
+    }
 
+    /**
+     * \brief Run the algorithm.
+     */
     void run() {
         _totalCost = 0;
         int nbRootChildren = 0;
@@ -52,9 +79,11 @@ public:
 private:
 
     /**
-     * Counts the children to the left and to the right of the cell currently
-     * pointed to by the iterator _it. You must check by yourself whether the
-     * cell is a leaf or not.
+     * \brief Counts left and right children of the current cell.
+     *
+     * The current cell is the one currently pointed at by the iterator _it.
+     *
+     * \warning You must check by yourself whether the cell is a leaf or not.
      *
      * \return A pair of int containing the count of left (first) and right
      *         (second) children.
@@ -80,12 +109,15 @@ private:
 
 
     /**
-     * Calls the costzones function on the left or right children of the current
-     * cell.
+     * \brief Applies costzones to the left or right children of the current cell.
+     *
+     * The current cell is the one currently pointed at by the iterator _it.
+     *
+     * \warning You must check by yourself whether the cell is a leaf or not.
      *
      * \param side The children side we want to visit.
      * \param childrenCount The children count as returned by
-     *                      countLeftRightChildren
+     *                      countLeftRightChildren.
      */
     void callCostZonesOnChildren(const ChildrenSide side, const std::pair<int, int>& childrenCount) {
         
@@ -119,18 +151,27 @@ private:
     }
 
 
-    void costzones() {
 
-        CellClass* cell = _it.getCurrentCell();    
+
+    /**
+     * \brief Main costzone algorithm.
+     *
+     * Moves through the tree in-order and assigns each cell to a zone. When a
+     * zone's cumulative cost is too high, the new cells are insterted in the
+     * next one.
+     */
+    void costzones() {
 
 // DEBUG SECTION
 #if 0
+        CellClass* cell = _it.getCurrentCell();    
         std::cout << "in  lvl " << std::setw(2) << _it.level() << " |"
                   << "cellidx " << std::setw(4)
                   << cell->getMortonIndex() << " : "
                   << cell->getCoordinate() << " "
                   << ( _it.canProgressToDown() ? "internal" : "leaf") << " "
                   << std::endl;
+//
         if (cell->_visited) {
             std::cerr << "Error : cell revisited..." << _it.level()
                       << ": " << cell->getCoordinate() << std::endl;
@@ -142,7 +183,6 @@ private:
 #endif
 // END DEBUG SECTION
 
-        int cellCost = cell->getCost();
         std::pair<int,int> childrenCount;
 
         // When not on a leaf, apply to left children first