mlpack 4.6.2__cp313-cp313-win_amd64.whl → 4.7.0__cp313-cp313-win_amd64.whl

mlpack/include/mlpack/methods/ann/rnn.hpp

@@ -37,7 +37,11 @@ template<
 class RNN
 {
  public:
+  // Convenience typedefs.
+  using ElemType = typename MatType::elem_type;
   using CubeType = typename GetCubeType<MatType>::type;
+  using URowType = typename GetURowType<MatType>::type;
+
   /**
    * Create the RNN object.
    *
@@ -76,18 +80,52 @@ class RNN
   /**
    * Add a new module to the model.
    *
-   * @param args The layer parameter.
+   * @param args The parameters to pass to the constructor of the layer.
+   */
+  template<typename LayerType, typename... Args>
+  void Add(Args&&... args)
+  {
+    network.template Add<LayerType>(std::forward<Args>(args)...);
+  }
+
+  /**
+   * Add a new layer to the model, without specifying the matrix type of the
+   * layer as a template parameter.
+   *
+   * @param args The parameters to pass to the constructor of the layer.
    */
-  template <typename LayerType, typename... Args>
-  void Add(Args... args) { network.template Add<LayerType>(args...); }
+  template<template<typename...> typename LayerType,
+           typename... Args>
+  void Add(Args&&... args)
+  {
+    network.template Add<LayerType<MatType>>(std::forward<Args>(args)...);
+  }
 
   /**
    * Add a new module to the model.
    *
    * @param layer The Layer to be added to the model.
    */
+  [[deprecated("Will be removed in mlpack 5.0.0.  Use Add(std::move(layer)).")]]
   void Add(Layer<MatType>* layer) { network.Add(layer); }
 
+  /**
+   * Add a new layer to the model by copying/moving the parameters of the given
+   * layer.  Note that any trainable weights of this layer will be reset!
+   * (Constant parameters are kept.)  Preferably, pass the layer with
+   * std::move().
+   *
+   * @param layer The layer to be added to the model.
+   */
+  template<typename LayerType>
+  void Add(LayerType&& layer,
+           // This SFINAE can be removed in mlpack 5.0.0.
+           typename std::enable_if<!std::is_pointer_v<
+                std::remove_reference_t<LayerType>>>::type* = 0)
+  {
+    network.Add(std::forward<LayerType>(layer));
+  }
+
   //! Get the network model.
   const std::vector<Layer<MatType>*>& Network() const
   {
@@ -128,11 +166,10 @@ class RNN
    * @return The final objective of the trained model (NaN or Inf on error).
    */
   template<typename OptimizerType, typename... CallbackTypes>
-  typename MatType::elem_type Train(
-      CubeType predictors,
-      CubeType responses,
-      OptimizerType& optimizer,
-      CallbackTypes&&... callbacks);
+  ElemType Train(CubeType predictors,
+                 CubeType responses,
+                 OptimizerType& optimizer,
+                 CallbackTypes&&... callbacks);
 
   /**
    * Train the recurrent network on the given input data. By default, the
@@ -156,10 +193,9 @@ class RNN
    * @return The final objective of the trained model (NaN or Inf on error).
    */
   template<typename OptimizerType = ens::RMSProp, typename... CallbackTypes>
-  typename MatType::elem_type Train(
-      CubeType predictors,
-      CubeType responses,
-      CallbackTypes&&... callbacks);
+  ElemType Train(CubeType predictors,
+                 CubeType responses,
+                 CallbackTypes&&... callbacks);
 
   /**
    * Train the recurrent network on the given input data using the given
@@ -186,12 +222,11 @@ class RNN
    * @return The final objective of the trained model (NaN or Inf on error).
    */
   template<typename OptimizerType, typename... CallbackTypes>
-  typename MatType::elem_type Train(
-      CubeType predictors,
-      CubeType responses,
-      arma::urowvec sequenceLengths,
-      OptimizerType& optimizer,
-      CallbackTypes&&... callbacks);
+  ElemType Train(CubeType predictors,
+                 CubeType responses,
+                 URowType sequenceLengths,
+                 OptimizerType& optimizer,
+                 CallbackTypes&&... callbacks);
 
   /**
    * Train the recurrent network on the given input data, given that each input
@@ -222,11 +257,10 @@ class RNN
    * @return The final objective of the trained model (NaN or Inf on error).
    */
   template<typename OptimizerType = ens::RMSProp, typename... CallbackTypes>
-  typename MatType::elem_type Train(
-      CubeType predictors,
-      CubeType responses,
-      arma::urowvec sequenceLengths,
-      CallbackTypes&&... callbacks);
+  ElemType Train(CubeType predictors,
+                 CubeType responses,
+                 URowType sequenceLengths,
+                 CallbackTypes&&... callbacks);
 
   /**
    * Predict the responses to a given set of predictors. The responses will
@@ -257,7 +291,7 @@ class RNN
    */
   void Predict(const CubeType& predictors,
                CubeType& results,
-               const arma::urowvec& sequenceLengths);
+               const URowType& sequenceLengths);
 
   // Return the nujmber of weights in the model.
   size_t WeightSize() { return network.WeightSize(); }
@@ -318,11 +352,26 @@ class RNN
    * @param predictors Input variables.
    * @param responses Target outputs for input variables.
    */
-  typename MatType::elem_type Evaluate(
-      const CubeType& predictors,
-      const CubeType& responses);
+  ElemType Evaluate(const CubeType& predictors, const CubeType& responses);
 
-  //! Serialize the model.
+  /**
+   * Evaluate the recurrent network with the given predictors and responses.
+   * This functions is usually used to monitor progress while training.
+   *
+   * @param predictors Input variables.
+   * @param responses Target outputs for input variables.
+   * @param sequenceLengths Length of each input sequences.  Should have size
+   *     `predictors.n_cols`, and all values should be less than or equal to
+   *     `predictors.n_slices`.
+   * @param batchSize Number of points to be passed at a time to use for
+   *        objective function evaluation.
+   */
+  ElemType Evaluate(const CubeType& predictors,
+                    const CubeType& responses,
+                    const URowType& sequenceLengths,
+                    const size_t batchSize);
+
+  // Serialize the model.
   template<typename Archive>
   void serialize(Archive& ar, const uint32_t /* version */);
 
@@ -337,7 +386,7 @@ class RNN
    *
    * @param parameters Matrix model parameters.
    */
-  typename MatType::elem_type Evaluate(const MatType& parameters);
+  ElemType Evaluate(const MatType& parameters);
 
    /**
    * Evaluate the recurrent network with the given parameters, but using only
@@ -353,9 +402,9 @@ class RNN
    * @param batchSize Number of points to be passed at a time to use for
    *        objective function evaluation.
    */
-  typename MatType::elem_type Evaluate(const MatType& parameters,
-                                       const size_t begin,
-                                       const size_t batchSize);
+  ElemType Evaluate(const MatType& parameters,
+                    const size_t begin,
+                    const size_t batchSize);
 
   /**
    * Evaluate the recurrent network with the given parameters.
@@ -366,8 +415,8 @@ class RNN
    * @param gradient Matrix to output gradient into.
    */
   template<typename GradType>
-  typename MatType::elem_type EvaluateWithGradient(const MatType& parameters,
-                                                   GradType& gradient);
+  ElemType EvaluateWithGradient(const MatType& parameters,
+                                GradType& gradient);
 
    /**
    * Evaluate the recurrent network with the given parameters, but using only
@@ -382,10 +431,10 @@ class RNN
    *        objective function evaluation.
    */
   template<typename GradType>
-  typename MatType::elem_type EvaluateWithGradient(const MatType& parameters,
-                                                   const size_t begin,
-                                                   GradType& gradient,
-                                                   const size_t batchSize);
+  ElemType EvaluateWithGradient(const MatType& parameters,
+                                const size_t begin,
+                                GradType& gradient,
+                                const size_t batchSize);
 
   /**
    * Evaluate the gradient of the recurrent network with the given parameters,
@@ -428,7 +477,7 @@ class RNN
    */
   void ResetData(CubeType predictors,
                  CubeType responses,
-                 arma::urowvec sequenceLengths = arma::urowvec());
+                 URowType sequenceLengths = URowType());
 
  private:
   // Helper functions.
@@ -441,7 +490,52 @@ class RNN
   void ResetMemoryState(const size_t memorySize, const size_t batchSize);
 
   //! Set the current step index of all recurrent layers to `step`.
-  void SetCurrentStep(const size_t step, const bool end);
+  void SetCurrentStep(const size_t step,
+                      const bool end,
+                      size_t batchSize,
+                      size_t activeBatchSize,
+                      bool backwards = false);
+
+  // Reorders the data in a batch to have sequence lengths in descending order.
+  void ReorderBatch(const size_t begin,
+                    const size_t batchSize,
+                    CubeType& predictors,
+                    CubeType& responses,
+                    URowType& sequenceLengths);
+
+  // Calculates the number of active points in the batch.
+  void CalculateActivePoints(size_t& activeBatchSize,
+                             const size_t begin,
+                             URowType& sequenceLengths,
+                             const size_t step,
+                             const std::enable_if_t<
+                                 IsArma<URowType>::value>* = 0)
+  {
+    // Since we know that `sequenceLengths` is sorted in order of descending
+    // lengths and `activeBatchSize` only decreases as `step` increases, we
+    // can just decrease `activeBatchSize` until we find the sequence length
+    // that is greater than the current step.
+    while (activeBatchSize > 0 &&
+        sequenceLengths[begin + activeBatchSize - 1] <= step)
+      activeBatchSize--;
+  }
+
+  #if defined(MLPACK_HAS_COOT)
+
+  void CalculateActivePoints(size_t& activeBatchSize,
+                             const size_t begin,
+                             const URowType& sequenceLengths,
+                             const size_t step,
+                             const std::enable_if_t<
+                                 IsCoot<URowType>::value>* = 0)
+  {
+    // Individual element access is probably slower if `URowType` is a
+    // Bandicoot type so we don't use the optimized version.
+    activeBatchSize = accu(sequenceLengths
+        .subvec(begin, begin + activeBatchSize - 1) > step);
+  }
+
+  #endif // defined(MLPACK_HAS_COOT)
 
   //! Number of timesteps to consider for backpropagation through time (BPTT).
   size_t bpttSteps;
@@ -464,8 +558,8 @@ class RNN
   CubeType responses;
 
   // The length of each input sequence.  If this is empty, then every sequence
-  // is assuemd to have the same length (`predictors.n_slices`).
-  arma::urowvec sequenceLengths;
+  // is assumed to have the same length (`predictors.n_slices`).
+  URowType sequenceLengths;
 }; // class RNNType
 
 } // namespace mlpack