Merge pull request #8 from mlpack/master

Syncing

src/mlpack/core/tree/ballbound.hpp

@@ -108,6 +108,8 @@ class BallBound
 
   /**
    * Determines if a point is within this bound.
+   *
+   * @param point Point to check the condition.
    */
   bool Contains(const VecType& point) const;
 
@@ -120,6 +122,8 @@ class BallBound
 
   /**
    * Calculates minimum bound-to-point squared distance.
+   *
+   * @param point Point to which the minimum distance is requested.
    */
   template<typename OtherVecType>
   ElemType MinDistance(
@@ -128,11 +132,15 @@ class BallBound
 
   /**
    * Calculates minimum bound-to-bound squared distance.
+   *
+   * @param other Bound to which the minimum distance is requested.
    */
   ElemType MinDistance(const BallBound& other) const;
 
   /**
    * Computes maximum distance.
+   *
+   * @param point Point to which the maximum distance is requested.
    */
   template<typename OtherVecType>
   ElemType MaxDistance(
@@ -141,11 +149,16 @@ class BallBound
 
   /**
    * Computes maximum distance.
+   *
+   * @param other Bound to which the maximum distance is requested.
    */
   ElemType MaxDistance(const BallBound& other) const;
 
   /**
    * Calculates minimum and maximum bound-to-point distance.
+   *
+   * @param point Point to which the minimum and maximum distances are
+   *     requested.
    */
   template<typename OtherVecType>
   math::RangeType<ElemType> RangeDistance(
@@ -156,6 +169,9 @@ class BallBound
    * Calculates minimum and maximum bound-to-bound distance.
    *
    * Example: bound1.MinDistanceSq(other) for minimum distance.
+   *
+   * @param other Bound to which the minimum and maximum distances are
+   *     requested.
    */
   math::RangeType<ElemType> RangeDistance(const BallBound& other) const;
 

src/mlpack/core/tree/cellbound.hpp

@@ -89,6 +89,8 @@ class CellBound
   /**
    * Initializes to specified dimensionality with each dimension the empty
    * set.
+   *
+   * @param dimension Dimensionality of bound.
    */
   CellBound(const size_t dimension);
 
@@ -219,11 +221,15 @@ class CellBound
 
   /**
    * Expands this region to encompass another bound.
+   *
+   * @param other Bound which needs to be encompassed.
    */
   CellBound& operator|=(const CellBound& other);
 
   /**
    * Determines if a point is within this bound.
+   *
+   * @param point Point to check the condition.
    */
   template<typename VecType>
   bool Contains(const VecType& point) const;

src/mlpack/core/tree/hollow_ball_bound.hpp

@@ -123,12 +123,16 @@ class HollowBallBound
 
   /**
    * Determines if a point is within this bound.
+   *
+   * @param point Point to check the condition.   
    */
   template<typename VecType>
   bool Contains(const VecType& point) const;
 
   /**
    * Determines if another bound is within this bound.
+   *
+   * @param other Bound to check the condition.
    */
   bool Contains(const HollowBallBound& other) const;
 
@@ -141,7 +145,9 @@ class HollowBallBound
   void Center(VecType& center) const { center = this->center; }
 
   /**
-   * Calculates minimum bound-to-point squared distance.
+   * Calculates minimum bound-to-point squared distance
+   *.
+   * @param point Point to which the minimum distance is requested.
    */
   template<typename VecType>
   ElemType MinDistance(const VecType& point,
@@ -150,11 +156,15 @@ class HollowBallBound
 
   /**
    * Calculates minimum bound-to-bound squared distance.
+   *
+   * @param other Bound to which the minimum distance is requested.
    */
   ElemType MinDistance(const HollowBallBound& other) const;
 
   /**
    * Computes maximum distance.
+   *
+   * @param point Point to which the maximum distance is requested.
    */
   template<typename VecType>
   ElemType MaxDistance(const VecType& point,
@@ -163,11 +173,16 @@ class HollowBallBound
 
   /**
    * Computes maximum distance.
+   *
+   * @param other Bound to which the maximum distance is requested.
    */
   ElemType MaxDistance(const HollowBallBound& other) const;
 
   /**
    * Calculates minimum and maximum bound-to-point distance.
+   *
+   * @param point Point to which the minimum and maximum distances are
+   *     requested.
    */
   template<typename VecType>
   math::RangeType<ElemType> RangeDistance(
@@ -178,6 +193,9 @@ class HollowBallBound
    * Calculates minimum and maximum bound-to-bound distance.
    *
    * Example: bound1.MinDistanceSq(other) for minimum distance.
+   *
+   * @param other Bound to which the minimum and maximum distances are
+   *     requested.
    */
   math::RangeType<ElemType> RangeDistance(const HollowBallBound& other) const;
 

src/mlpack/core/tree/hrectbound.hpp

@@ -66,6 +66,8 @@ class HRectBound
   /**
    * Initializes to specified dimensionality with each dimension the empty
    * set.
+   *
+   * @param dimension Dimensionality of bound.
    */
   HRectBound(const size_t dimension);
 
@@ -190,12 +192,16 @@ class HRectBound
 
   /**
    * Determines if a point is within this bound.
+   *
+   * @param point Point to check the condition.   
    */
   template<typename VecType>
   bool Contains(const VecType& point) const;
 
   /**
    * Determines if this bound partially contains a bound.
+   *
+   * @param other Bound to check the condition.
    */
   bool Contains(const HRectBound& bound) const;
 

src/mlpack/methods/ann/layer/lstm.hpp

@@ -19,12 +19,7 @@ namespace mlpack {
 namespace ann /** Artificial Neural Network. */ {
 
 /**
- * An implementation of a lstm network layer.
- *
- * This class allows specification of the type of the activation functions used
- * for the gates and cells and also of the type of the function used to
- * initialize and update the peephole weights.
-
+ * Implementation of the LSTM module class.
  * The implementation corresponds to the following algorithm:
  *
  * @f{eqnarray}{
@@ -78,7 +73,7 @@ class LSTM
        const size_t rho = std::numeric_limits<size_t>::max());
 
   /**
-   * Ordinary feed forward pass of a neural network, evaluating the function
+   * Ordinary feed-forward pass of a neural network, evaluating the function
    * f(x) by propagating the activity forward through f.
    *
    * @param input Input data used for evaluating the specified function.
@@ -87,6 +82,21 @@ class LSTM
   template<typename InputType, typename OutputType>
   void Forward(InputType&& input, OutputType&& output);
 
+  /**
+   * Ordinary feed-forward pass of a neural network, evaluating the function
+   * f(x) by propagating the activity forward through f.
+   *
+   * @param input Input data used for evaluating the specified function.
+   * @param output Resulting output activation.
+   * @param cellState Cell state of the LSTM.
+   * @param useCellState Use the cellState passed in the LSTM cell.
+   */
+  template<typename InputType, typename OutputType>
+  void Forward(InputType&& input,
+               OutputType&& output,
+               OutputType&& cellState,
+               bool useCellState = false);
+
   /**
    * Ordinary feed backward pass of a neural network, calculating the function
    * f(x) by propagating x backwards trough f. Using the results from the feed

src/mlpack/methods/ann/layer/lstm_impl.hpp

@@ -159,10 +159,24 @@ void LSTM<InputDataType, OutputDataType>::Reset()
       offset, outSize, 1, false, false);
 }
 
+// Forward when cellState is not needed.
 template<typename InputDataType, typename OutputDataType>
 template<typename InputType, typename OutputType>
 void LSTM<InputDataType, OutputDataType>::Forward(
     InputType&& input, OutputType&& output)
+{
+  //! Locally-stored cellState.
+  OutputType cellState;
+  Forward(std::move(input), std::move(output), std::move(cellState), false);
+}
+
+// Forward when cellState is needed overloaded LSTM::Forward().
+template<typename InputDataType, typename OutputDataType>
+template<typename InputType, typename OutputType>
+void LSTM<InputDataType, OutputDataType>::Forward(InputType&& input,
+                                                  OutputType&& output,
+                                                  OutputType&& cellState,
+                                                  bool useCellState)
 {
   // Check if the batch size changed, the number of cols is defines the input
   // batch size.
@@ -187,6 +201,18 @@ void LSTM<InputDataType, OutputDataType>::Forward(
 
   if (forwardStep > 0)
   {
+    if (useCellState)
+    {
+      if (!cellState.is_empty())
+      {
+        cell.cols(forwardStep - batchSize,
+            forwardStep - batchSize + batchStep) = cellState;
+      }
+      else
+      {
+        throw std::runtime_error("Cell parameter is empty.");
+      }
+    }
     inputGate.cols(forwardStep, forwardStep + batchStep) +=
         arma::repmat(cell2GateInputWeight, 1, batchSize) %
         cell.cols(forwardStep - batchSize, forwardStep - batchSize + batchStep);
@@ -249,6 +275,9 @@ void LSTM<InputDataType, OutputDataType>::Forward(
   output = OutputType(outParameter.memptr() +
       (forwardStep + batchSize) * outSize, outSize, batchSize, false, false);
 
+  cellState = OutputType(cell.memptr() +
+      forwardStep * outSize, outSize, batchSize, false, false);
+
   forwardStep += batchSize;
   if ((forwardStep / batchSize) == bpttSteps)
   {

src/mlpack/methods/logistic_regression/logistic_regression_function.hpp

@@ -28,10 +28,25 @@ template<typename MatType = arma::mat>
 class LogisticRegressionFunction
 {
  public:
+  /**
+   * Creates the LogisticRegressionFunction.
+   *
+   * @param predictors The matrix of data points.
+   * @param responses The measured data for each point in predictors.
+   * @param lambda Regularization constant for ridge regression.
+   */
   LogisticRegressionFunction(const MatType& predictors,
                              const arma::Row<size_t>& responses,
                              const double lambda = 0);
 
+  /**
+   * Creates the LogisticRegressionFunction with initialPoint.
+   *
+   * @param predictors The matrix of data points.
+   * @param responses The measured data for each point in predictors.
+   * @param initialPoint Point from which to start the optimization.
+   * @param lambda Regularization constant for ridge regression.
+   */
   LogisticRegressionFunction(const MatType& predictors,
                              const arma::Row<size_t>& responses,
                              const arma::vec& initialPoint,
@@ -59,7 +74,7 @@ class LogisticRegressionFunction
 
   /**
    * Evaluate the logistic regression log-likelihood function with the given
-   * parameters.  Note that if a point has 0 probability of being classified
+   * parameters. Note that if a point has 0 probability of being classified
    * directly with the given parameters, then Evaluate() will return nan (this
    * is kind of a corner case and should not happen for reasonable models).
    *
@@ -72,9 +87,9 @@ class LogisticRegressionFunction
 
   /**
    * Evaluate the logistic regression log-likelihood function with the given
-   * parameters using the given batch size from the given point index.  This is
+   * parameters using the given batch size from the given point index. This is
    * useful for optimizers such as SGD, which require a separable objective
-   * function.  Note that if the points have 0 probability of being classified
+   * function. Note that if the points have 0 probability of being classified
    * correctly with the given parameters, then Evaluate() will return nan (this
    * is kind of a corner case and should not happen for reasonable models).
    *
@@ -102,8 +117,8 @@ class LogisticRegressionFunction
 
   /**
    * Evaluate the gradient of the logistic regression log-likelihood function
-   * with the given parameters, for the given batch size from a given point the
-   * in dataset. This is useful for optimizers such as SGD, which require a
+   * with the given parameters, for the given batch size from a given point in
+   * the dataset. This is useful for optimizers such as SGD, which require a
    * separable objective function.
    *
    * @param parameters Vector of logistic regression parameters.
@@ -122,7 +137,7 @@ class LogisticRegressionFunction
   /**
    * Evaluate the gradient of the logistic regression log-likelihood function
    * with the given parameters, and with respect to only one feature in the
-   * dataset.  This is useful for optimizers such as SCD, which require
+   * dataset. This is useful for optimizers such as SCD, which require
    * partial gradients.
    *
    * @param parameters Vector of logistic regression parameters.
@@ -142,6 +157,11 @@ class LogisticRegressionFunction
   double EvaluateWithGradient(const arma::mat& parameters,
                               GradType& gradient) const;
 
+  /**
+   * Evaluate the objective function and gradient of the logistic regression
+   * log-likelihood function simultaneously with the given parameters, for
+   * the given batch size from a given point in the dataset.
+   */
   template<typename GradType>
   double EvaluateWithGradient(const arma::mat& parameters,
                               const size_t begin,

src/mlpack/methods/reinforcement_learning/q_learning_impl.hpp

@@ -45,6 +45,7 @@ QLearning<
     totalSteps(0),
     deterministic(false)
 {
+  // Set up q-learning network.
   if (learningNetwork.Parameters().is_empty())
     learningNetwork.ResetParameters();
   this->updater.Initialize(learningNetwork.Parameters().n_rows,
@@ -67,6 +68,7 @@ arma::Col<size_t> QLearning<
   ReplayType
 >::BestAction(const arma::mat& actionValues)
 {
+  // Take best possible action at a particular instance.
   arma::Col<size_t> bestActions(actionValues.n_cols);
   arma::rowvec maxActionValues = arma::max(actionValues, 0);
   for (size_t i = 0; i < actionValues.n_cols; ++i)