[mlpack-git] master: Better commenting of the SDP class. Make the dangers of invalid SDPs documented, among other things. (ff889c9)

[gitdub at big.cc.gt.atl.ga.us]

Repository : https://github.com/mlpack/mlpack

On branch  : master
Link       : https://github.com/mlpack/mlpack/compare/bb6e5c56aab07e6449d86021246b52a9e323f3a0...bd6cb33f8d8270b02a84e81e38727679bb6c319a

>---------------------------------------------------------------

commit ff889c9d629ec7ef4518bfa95b54eebfe4ac48b4
Author: Ryan Curtin <ryan at ratml.org>
Date:   Mon Feb 2 15:05:55 2015 -0500

    Better commenting of the SDP class.
    Make the dangers of invalid SDPs documented, among other things.


>---------------------------------------------------------------

ff889c9d629ec7ef4518bfa95b54eebfe4ac48b4
 src/mlpack/core/optimizers/sdp/sdp.hpp | 50 ++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/src/mlpack/core/optimizers/sdp/sdp.hpp b/src/mlpack/core/optimizers/sdp/sdp.hpp
index c276ca6..923fa3b 100644
--- a/src/mlpack/core/optimizers/sdp/sdp.hpp
+++ b/src/mlpack/core/optimizers/sdp/sdp.hpp
@@ -17,7 +17,17 @@ namespace optimization {
  *     min    dot(C, X)
  *     s.t.   dot(Ai, X) = bi, i=1,...,m, X >= 0
  *
- * @tparam ObjectiveMatrixType Should be either arma::mat or arma::sp_mat
+ * This representation allows the constraint matrices Ai to be specified as
+ * either dense matrices (arma::mat) or sparse matrices (arma::sp_mat).  After
+ * initializing the SDP object, you will need to set the constraints yourself,
+ * via the SparseA(), SparseB(), DenseA(), DenseB(), and C() functions.  Note
+ * that for each matrix you add to either SparseA() or DenseA(), you must add
+ * the corresponding b value to the corresponding vector SparseB() or DenseB().
+ *
+ * The objective matrix (C) may be stored as either dense or sparse depending on
+ * the ObjectiveMatrixType parameter.
+ *
+ * @tparam ObjectiveMatrixType Should be either arma::mat or arma::sp_mat.
  */
 template <typename ObjectiveMatrixType>
 class SDP
@@ -27,51 +37,64 @@ class SDP
   typedef ObjectiveMatrixType objective_matrix_type;
 
   /**
-   * Initialize this SDP to an empty state.
+   * Initialize this SDP to an empty state.  To add constraints, you will have
+   * to modify the constraints via the SparseA(), DenseA(), SparseB(), DenseB(),
+   * and C() functions.  For the sake of speed, there is no error checking, so
+   * if you specify an invalid SDP, whatever solver you use will gladly try to
+   * solve it!  (And it will probably crash horribly.)
    */
   SDP();
 
   /**
-   * Initialize this SDP to one which structurally has size n.
+   * Initialize this SDP to one which structurally has size n.  To set the
+   * constraints you will still need to access through SparseA(), DenseA(),
+   * SparseB(), DenseB(), and C().  Consider using move semantics to keep things
+   * fast.  As with the previous constructor, there is no error checking for the
+   * sake of speed, so if you build an invalid SDP, whatever solver you use will
+   * gladly try to solve it!  (And it will probably crash horribly.)
    *
-   * @param n
-   * @param numSparseConstraints
-   * @param numDenseConstraints
+   * @param n Number of rows (and columns) in the objective matrix C.
+   * @param numSparseConstraints Number of sparse constraints.
+   * @param numDenseConstraints Number of dense constraints.
    */
   SDP(const size_t n,
       const size_t numSparseConstraints,
       const size_t numDenseConstraints);
 
+  //! Return number of rows and columns in the objective matrix C.
   size_t N() const { return c.n_rows; }
 
   size_t N2bar() const { return N() * (N() + 1) / 2; }
 
+  //! Return the number of sparse constraints (constraints with sparse Ai) in
+  //! the SDP.
   size_t NumSparseConstraints() const { return sparseB.n_elem; }
-
+  //! Return the number of dense constraints (constraints with dense Ai) in the
+  //! SDP.
   size_t NumDenseConstraints() const { return denseB.n_elem; }
 
+  //! Return the total number of constraints in the SDP.
   size_t NumConstraints() const { return sparseB.n_elem + denseB.n_elem; }
 
   //! Modify the sparse objective function matrix (sparseC).
   ObjectiveMatrixType& C() { return c; }
-
   //! Return the sparse objective function matrix (sparseC).
   const ObjectiveMatrixType& C() const { return c; }
 
   //! Return the vector of sparse A matrices (which correspond to the sparse
-  // constraints).
+  //! constraints).
   const std::vector<arma::sp_mat>& SparseA() const { return sparseA; }
 
   //! Modify the veector of sparse A matrices (which correspond to the sparse
-  // constraints).
+  //! constraints).
   std::vector<arma::sp_mat>& SparseA() { return sparseA; }
 
   //! Return the vector of dense A matrices (which correspond to the dense
-  // constraints).
+  //! constraints).
   const std::vector<arma::mat>& DenseA() const { return denseA; }
 
   //! Modify the veector of dense A matrices (which correspond to the dense
-  // constraints).
+  //! constraints).
   std::vector<arma::mat>& DenseA() { return denseA; }
 
   //! Return the vector of sparse B values.
@@ -87,12 +110,11 @@ class SDP
   /**
    * Check whether or not the constraint matrices are linearly independent.
    *
-   * Warning: possibly very expensive check
+   * Warning: possibly very expensive check.
    */
   bool HasLinearlyIndependentConstraints() const;
 
  private:
-
   //! Objective function matrix c.
   ObjectiveMatrixType c;