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

mlpack/include/mlpack/methods/neighbor_search/neighbor_search_impl.hpp

@@ -32,14 +32,16 @@ template<typename SortPolicy,
 NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
     DualTreeTraversalType, SingleTreeTraversalType>::
 NeighborSearch(MatType referenceSetIn,
-               const NeighborSearchMode mode,
+               const NeighborSearchStrategy strategy,
                const double epsilon,
                const DistanceType distance) :
-    referenceTree(mode == NAIVE_MODE ? NULL :
+    referenceTree(strategy == NAIVE ? NULL :
         BuildTree<Tree>(std::move(referenceSetIn), oldFromNewReferences)),
-    referenceSet(mode == NAIVE_MODE ?  new MatType(std::move(referenceSetIn)) :
-        &referenceTree->Dataset()),
-    searchMode(mode),
+    referenceSet(strategy == NAIVE ?
+        new MatType(std::move(referenceSetIn)) : &referenceTree->Dataset()),
+    searchMode(StrategyToMode(strategy)),
+    searchModeMod(false),
+    searchStrategy(strategy),
     epsilon(epsilon),
     distance(distance),
     baseCases(0),
@@ -51,6 +53,34 @@ NeighborSearch(MatType referenceSetIn,
 }
 
 // Construct the object.
+template<typename SortPolicy,
+         typename DistanceType,
+         typename MatType,
+         template<typename TreeDistanceType,
+                  typename TreeStatType,
+                  typename TreeMatType> class TreeType,
+         template<typename> class DualTreeTraversalType,
+         template<typename> class SingleTreeTraversalType>
+NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
+    DualTreeTraversalType, SingleTreeTraversalType>::
+NeighborSearch(Tree referenceTree,
+               const NeighborSearchStrategy strategy,
+               const double epsilon) :
+    referenceTree(new Tree(std::move(referenceTree))),
+    referenceSet(&this->referenceTree->Dataset()),
+    searchMode(StrategyToMode(strategy)),
+    searchModeMod(false),
+    searchStrategy(strategy),
+    epsilon(epsilon),
+    distance(this->referenceTree->Distance()),
+    baseCases(0),
+    scores(0),
+    treeNeedsReset(false)
+{
+  if (epsilon < 0)
+    throw std::invalid_argument("epsilon must be non-negative");
+}
+
 template<typename SortPolicy,
          typename DistanceType,
          typename MatType,
@@ -68,6 +98,8 @@ NeighborSearch(Tree referenceTree,
     referenceTree(new Tree(std::move(referenceTree))),
     referenceSet(&this->referenceTree->Dataset()),
     searchMode(mode),
+    searchModeMod(false),
+    searchStrategy(ModeToStrategy(mode)),
     epsilon(epsilon),
     distance(distance),
     baseCases(0),
@@ -89,12 +121,14 @@ template<typename SortPolicy,
          template<typename> class SingleTreeTraversalType>
 NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
     DualTreeTraversalType, SingleTreeTraversalType>::
-NeighborSearch(const NeighborSearchMode mode,
+NeighborSearch(const NeighborSearchStrategy strategy,
                const double epsilon,
                const DistanceType distance) :
     referenceTree(NULL),
-    referenceSet(mode == NAIVE_MODE ? new MatType() : NULL), // Empty matrix.
-    searchMode(mode),
+    referenceSet(strategy == NAIVE ? new MatType() : NULL),
+    searchMode(StrategyToMode(strategy)),
+    searchModeMod(false),
+    searchStrategy(strategy),
     epsilon(epsilon),
     distance(distance),
     baseCases(0),
@@ -105,7 +139,7 @@ NeighborSearch(const NeighborSearchMode mode,
     throw std::invalid_argument("epsilon must be non-negative");
 
   // Build the tree on the empty dataset, if necessary.
-  if (mode != NAIVE_MODE)
+  if (strategy != NAIVE)
   {
     referenceTree = BuildTree<Tree>(std::move(MatType()),
         oldFromNewReferences);
@@ -130,6 +164,8 @@ NeighborSearch(const NeighborSearch& other) :
     referenceSet(other.referenceTree ? &referenceTree->Dataset() :
         new MatType(*other.referenceSet)),
     searchMode(other.searchMode),
+    searchModeMod(other.searchModeMod),
+    searchStrategy(other.searchStrategy),
     epsilon(other.epsilon),
     distance(other.distance),
     baseCases(other.baseCases),
@@ -155,6 +191,8 @@ NeighborSearch(NeighborSearch&& other) :
     referenceTree(other.referenceTree),
     referenceSet(other.referenceSet),
     searchMode(other.searchMode),
+    searchModeMod(other.searchModeMod),
+    searchStrategy(other.searchStrategy),
     epsilon(other.epsilon),
     distance(std::move(other.distance)),
     baseCases(other.baseCases),
@@ -165,7 +203,9 @@ NeighborSearch(NeighborSearch&& other) :
   other.referenceTree = BuildTree<Tree>(std::move(MatType()),
       other.oldFromNewReferences);
   other.referenceSet = &other.referenceTree->Dataset();
-  other.searchMode = DUAL_TREE_MODE,
+  other.searchMode = DUAL_TREE_MODE;
+  other.searchModeMod = false;
+  other.searchStrategy = DUAL_TREE;
   other.epsilon = 0.0;
   other.baseCases = 0;
   other.scores = 0;
@@ -208,6 +248,8 @@ NeighborSearch<SortPolicy,
   referenceSet = other.referenceTree ? &referenceTree->Dataset() :
       new MatType(*other.referenceSet);
   searchMode = other.searchMode;
+  searchModeMod = other.searchModeMod;
+  searchStrategy = other.searchStrategy;
   epsilon = other.epsilon;
   distance = other.distance;
   baseCases = other.baseCases;
@@ -250,6 +292,8 @@ NeighborSearch<SortPolicy,
   referenceTree = other.referenceTree;
   referenceSet = other.referenceSet;
   searchMode = other.searchMode;
+  searchModeMod = other.searchModeMod;
+  searchStrategy = other.searchStrategy;
   epsilon = other.epsilon;
   distance = other.distance;
   baseCases = other.baseCases;
@@ -263,7 +307,9 @@ NeighborSearch<SortPolicy,
   other.referenceTree = BuildTree<Tree>(std::move(MatType()),
       other.oldFromNewReferences);
   other.referenceSet = &other.referenceTree->Dataset();
-  other.searchMode = DUAL_TREE_MODE,
+  other.searchMode = DUAL_TREE_MODE;
+  other.searchModeMod = false;
+  other.searchStrategy = DUAL_TREE;
   other.epsilon = 0.0;
   other.baseCases = 0;
   other.scores = 0;
@@ -300,6 +346,17 @@ void NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
     DualTreeTraversalType, SingleTreeTraversalType>::
 Train(MatType referenceSetIn)
 {
+  // For reverse compatibility; can be removed in mlpack 5.0.0.
+  if (searchModeMod)
+  {
+    searchStrategy = ModeToStrategy(searchMode);
+    searchModeMod = false;
+  }
+  else
+  {
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
   // Clean up the old tree, if we built one.
   if (referenceTree)
   {
@@ -313,7 +370,7 @@ Train(MatType referenceSetIn)
   }
 
   // We may need to rebuild the tree.
-  if (searchMode != NAIVE_MODE)
+  if (searchStrategy != NAIVE)
   {
     referenceTree = BuildTree<Tree>(std::move(referenceSetIn),
         oldFromNewReferences);
@@ -336,7 +393,18 @@ template<typename SortPolicy,
 void NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
 DualTreeTraversalType, SingleTreeTraversalType>::Train(Tree referenceTree)
 {
-  if (searchMode == NAIVE_MODE)
+  // For reverse compatibility; can be removed in mlpack 5.0.0.
+  if (searchModeMod)
+  {
+    searchStrategy = ModeToStrategy(searchMode);
+    searchModeMod = false;
+  }
+  else
+  {
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
+  if (searchStrategy == NAIVE)
     throw std::invalid_argument("cannot train on given reference tree when "
         "naive search (without trees) is desired");
 
@@ -374,6 +442,17 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
     arma::Mat<IndexType>& neighbors,
     arma::Mat<ElemType>& distances)
 {
+  // For reverse compatibility; can be removed in mlpack 5.0.0.
+  if (searchModeMod)
+  {
+    searchStrategy = ModeToStrategy(searchMode);
+    searchModeMod = false;
+  }
+  else
+  {
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
   if (k > referenceSet->n_cols)
   {
     std::stringstream ss;
@@ -398,7 +477,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
   // Mapping is only necessary if the tree rearranges points.
   if (TreeTraits<Tree>::RearrangesDataset)
   {
-    if (searchMode == DUAL_TREE_MODE)
+    if (searchStrategy == DUAL_TREE)
     {
       distancePtr = new arma::Mat<ElemType>; // Query indices need to be mapped.
       neighborPtr = new arma::Mat<IndexType>;
@@ -413,9 +492,9 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
 
   using RuleType = NeighborSearchRules<SortPolicy, DistanceType, Tree>;
 
-  switch (searchMode)
+  switch (searchStrategy)
   {
-    case NAIVE_MODE:
+    case NAIVE:
     {
       // Create the helper object for the tree traversal.
       RuleType rules(*referenceSet, querySet, k, distance, epsilon);
@@ -430,7 +509,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       rules.GetResults(*neighborPtr, *distancePtr);
       break;
     }
-    case SINGLE_TREE_MODE:
+    case SINGLE_TREE:
     {
       // Create the helper object for the tree traversal.
       RuleType rules(*referenceSet, querySet, k, distance, epsilon);
@@ -453,7 +532,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       rules.GetResults(*neighborPtr, *distancePtr);
       break;
     }
-    case DUAL_TREE_MODE:
+    case DUAL_TREE:
     {
       // Build the query tree.
       Tree* queryTree = BuildTree<Tree>(querySet, oldFromNewQueries);
@@ -479,7 +558,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       delete queryTree;
       break;
     }
-    case GREEDY_SINGLE_TREE_MODE:
+    case GREEDY_SINGLE_TREE:
     {
       // Create the helper object for the tree traversal.
       RuleType rules(*referenceSet, querySet, k, distance);
@@ -507,7 +586,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
   // Map points back to original indices, if necessary.
   if (TreeTraits<Tree>::RearrangesDataset)
   {
-    if (searchMode == DUAL_TREE_MODE && !oldFromNewReferences.empty())
+    if (searchStrategy == DUAL_TREE && !oldFromNewReferences.empty())
     {
       // We must map both query and reference indices.
       neighbors.set_size(k, querySet.n_cols);
@@ -530,7 +609,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       delete neighborPtr;
       delete distancePtr;
     }
-    else if (searchMode == DUAL_TREE_MODE)
+    else if (searchStrategy == DUAL_TREE)
     {
       // We must map query indices only.
       neighbors.set_size(k, querySet.n_cols);
@@ -581,6 +660,17 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
     arma::Mat<ElemType>& distances,
     bool sameSet)
 {
+  // For reverse compatibility; can be removed in mlpack 5.0.0.
+  if (searchModeMod)
+  {
+    searchStrategy = ModeToStrategy(searchMode);
+    searchModeMod = false;
+  }
+  else
+  {
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
   if (k > referenceSet->n_cols)
   {
     std::stringstream ss;
@@ -590,9 +680,9 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
   }
 
   // Make sure we are in dual-tree mode.
-  if (searchMode != DUAL_TREE_MODE)
-    throw std::invalid_argument("cannot call NeighborSearch::Search() with a "
-        "query tree when naive or singleMode are set to true");
+  if (searchStrategy != DUAL_TREE)
+    throw std::invalid_argument("Cannot call NeighborSearch::Search() with a "
+        "query tree when search strategy is not DUAL_TREE!");
 
   baseCases = 0;
   scores = 0;
@@ -659,6 +749,17 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
     arma::Mat<IndexType>& neighbors,
     arma::Mat<ElemType>& distances)
 {
+  // For reverse compatibility; can be removed in mlpack 5.0.0.
+  if (searchModeMod)
+  {
+    searchStrategy = ModeToStrategy(searchMode);
+    searchModeMod = false;
+  }
+  else
+  {
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
   if (k > referenceSet->n_cols)
   {
     std::stringstream ss;
@@ -697,9 +798,9 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
   RuleType rules(*referenceSet, *referenceSet, k, distance, epsilon,
       true /* don't return the same point as nearest neighbor */);
 
-  switch (searchMode)
+  switch (searchStrategy)
   {
-    case NAIVE_MODE:
+    case NAIVE:
     {
       // The naive brute-force solution.
       for (size_t i = 0; i < referenceSet->n_cols; ++i)
@@ -709,7 +810,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       baseCases += referenceSet->n_cols * referenceSet->n_cols;
       break;
     }
-    case SINGLE_TREE_MODE:
+    case SINGLE_TREE:
     {
       // Create the traverser.
       SingleTreeTraversalType<RuleType> traverser(rules);
@@ -727,27 +828,12 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
           << std::endl;
       break;
     }
-    case DUAL_TREE_MODE:
+    case DUAL_TREE:
     {
       // The dual-tree monochromatic search case may require resetting the
       // bounds in the tree.
       if (treeNeedsReset)
-      {
-        std::stack<Tree*> nodes;
-        nodes.push(referenceTree);
-        while (!nodes.empty())
-        {
-          Tree* node = nodes.top();
-          nodes.pop();
-
-          // Reset bounds of this node.
-          node->Stat().Reset();
-
-          // Then add the children.
-          for (size_t i = 0; i < node->NumChildren(); ++i)
-            nodes.push(&node->Child(i));
-        }
-      }
+        ResetTree(*referenceTree);
 
       // Create the traverser.
       DualTreeTraversalType<RuleType> traverser(rules);
@@ -762,8 +848,6 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       else
       {
         traverser.Traverse(*referenceTree, *referenceTree);
-        // Next time we perform this search, we'll need to reset the tree.
-        treeNeedsReset = true;
       }
 
       scores += rules.Scores();
@@ -778,7 +862,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::Search(
       treeNeedsReset = true;
       break;
     }
-    case GREEDY_SINGLE_TREE_MODE:
+    case GREEDY_SINGLE_TREE:
     {
       // Create the traverser.
       GreedySingleTreeTraverser<Tree, RuleType> traverser(rules);
@@ -855,7 +939,7 @@ DualTreeTraversalType, SingleTreeTraversalType>::EffectiveError(
     }
   }
 
-  if (numCases)
+  if (numCases > 0)
     effectiveError /= numCases;
 
   return effectiveError;
@@ -893,6 +977,35 @@ DualTreeTraversalType, SingleTreeTraversalType>::Recall(
   return ((double) found) / realNeighbors.n_elem;
 }
 
+template<typename SortPolicy,
+         typename DistanceType,
+         typename MatType,
+         template<typename TreeDistanceType,
+                  typename TreeStatType,
+                  typename TreeMatType> class TreeType,
+         template<typename> class DualTreeTraversalType,
+         template<typename> class SingleTreeTraversalType>
+void NeighborSearch<
+    SortPolicy, DistanceType, MatType, TreeType,
+    DualTreeTraversalType, SingleTreeTraversalType
+>::ResetTree(Tree& tree)
+{
+  std::stack<Tree*> nodes;
+  nodes.push(&tree);
+  while (!nodes.empty())
+  {
+    Tree* node = nodes.top();
+    nodes.pop();
+
+    // Reset bounds of this node.
+    node->Stat().Reset();
+
+    // Then add the children.
+    for (size_t i = 0; i < node->NumChildren(); ++i)
+      nodes.push(&node->Child(i));
+  }
+}
+
 //! Serialize the NeighborSearch model.
 template<typename SortPolicy,
          typename DistanceType,
@@ -905,15 +1018,41 @@ template<typename SortPolicy,
 template<typename Archive>
 void NeighborSearch<SortPolicy, DistanceType, MatType, TreeType,
 DualTreeTraversalType, SingleTreeTraversalType>::serialize(
-    Archive& ar, const uint32_t /* version */)
+    Archive& ar, const uint32_t version)
 {
+  if (cereal::is_saving<Archive>())
+  {
+    // For reverse compatibility; can be removed in mlpack 5.0.0.
+    if (searchModeMod)
+    {
+      searchStrategy = ModeToStrategy(searchMode);
+      searchModeMod = false;
+    }
+    else
+    {
+      searchMode = StrategyToMode(searchStrategy);
+    }
+  }
+
   // Serialize preferences for search.
-  ar(CEREAL_NVP(searchMode));
+  if (version == 0)
+  {
+    ar(CEREAL_NVP(searchMode));
+    searchModeMod = false;
+    searchStrategy = ModeToStrategy(searchMode);
+  }
+  else
+  {
+    ar(CEREAL_NVP(searchStrategy));
+    searchModeMod = false;
+    searchMode = StrategyToMode(searchStrategy);
+  }
+
   ar(CEREAL_NVP(treeNeedsReset));
 
   // If we are doing naive search, we serialize the dataset.  Otherwise we
   // serialize the tree.
-  if (searchMode == NAIVE_MODE)
+  if (searchStrategy == NAIVE)
   {
     // Delete the current reference set, if necessary and if we are loading.
     if (cereal::is_loading<Archive>() && referenceSet)

mlpack/include/mlpack/methods/neighbor_search/neighbor_search_stat.hpp

@@ -14,6 +14,8 @@
 #define MLPACK_METHODS_NEIGHBOR_SEARCH_NEIGHBOR_SEARCH_STAT_HPP
 
 #include <mlpack/prereqs.hpp>
+#include "sort_policies/nearest_neighbor_sort.hpp"
+#include "sort_policies/furthest_neighbor_sort.hpp"
 
 namespace mlpack {
 
@@ -100,6 +102,14 @@ class NeighborSearchStat
   }
 };
 
+// This is the type that must be used as the StatisticType for
+// k-nearest-neighbor search (e.g. the KNN or KNNType<> class).
+using NearestNeighborStat = NeighborSearchStat<NearestNeighborSort>;
+
+// This is the type that must be used as the StatisticType for
+// k-furthest-neighbor search (e.g. the KFN or KFNType<> class).
+using FurthestNeighborStat = NeighborSearchStat<FurthestNeighborSort>;
+
 } // namespace mlpack
 
 #endif

mlpack/include/mlpack/methods/neighbor_search/ns_model.hpp

@@ -49,9 +49,9 @@ class NSWrapperBase
   virtual const arma::mat& Dataset() const = 0;
 
   //! Get the search mode.
-  virtual NeighborSearchMode SearchMode() const = 0;
+  virtual NeighborSearchStrategy SearchStrategy() const = 0;
   //! Modify the search modem
-  virtual NeighborSearchMode& SearchMode() = 0;
+  virtual NeighborSearchStrategy& SearchStrategy() = 0;
 
   //! Get the approximation parameter epsilon.
   virtual double Epsilon() const = 0;
@@ -103,9 +103,9 @@ class NSWrapper : public NSWrapperBase
  public:
   //! Construct the NSWrapper object, initializing the internally-held
   //! NeighborSearch object.
-  NSWrapper(const NeighborSearchMode searchMode,
+  NSWrapper(const NeighborSearchStrategy searchStrategy,
             const double epsilon) :
-      ns(searchMode, epsilon)
+      ns(searchStrategy, epsilon)
   {
     // Nothing else to do.
   }
@@ -121,9 +121,9 @@ class NSWrapper : public NSWrapperBase
   const arma::mat& Dataset() const { return ns.ReferenceSet(); }
 
   //! Get the search mode.
-  NeighborSearchMode SearchMode() const { return ns.SearchMode(); }
+  NeighborSearchStrategy SearchStrategy() const { return ns.SearchStrategy(); }
   //! Modify the search mode.
-  NeighborSearchMode& SearchMode() { return ns.SearchMode(); }
+  NeighborSearchStrategy& SearchStrategy() { return ns.SearchStrategy(); }
 
   //! Get epsilon, the approximation parameter.
   double Epsilon() const { return ns.Epsilon(); }
@@ -201,12 +201,12 @@ class LeafSizeNSWrapper :
  public:
   //! Construct the LeafSizeNSWrapper by delegating to the NSWrapper
   //! constructor.
-  LeafSizeNSWrapper(const NeighborSearchMode searchMode,
+  LeafSizeNSWrapper(const NeighborSearchStrategy searchStrategy,
                     const double epsilon) :
       NSWrapper<SortPolicy,
                 TreeType,
                 DualTreeTraversalType,
-                SingleTreeTraversalType>(searchMode, epsilon)
+                SingleTreeTraversalType>(searchStrategy, epsilon)
   {
     // Nothing to do.
   }
@@ -270,7 +270,7 @@ class SpillNSWrapper :
 {
  public:
   //! Construct the SpillNSWrapper.
-  SpillNSWrapper(const NeighborSearchMode searchMode,
+  SpillNSWrapper(const NeighborSearchStrategy searchStrategy,
                  const double epsilon) :
       NSWrapper<
           SortPolicy,
@@ -281,7 +281,7 @@ class SpillNSWrapper :
           SPTree<EuclideanDistance,
                  NeighborSearchStat<SortPolicy>,
                  arma::mat>::template DefeatistSingleTreeTraverser>(
-          searchMode, epsilon)
+          searchStrategy, epsilon)
   {
     // Nothing to do.
   }
@@ -430,9 +430,9 @@ class NSModel
   //! Expose the dataset.
   const arma::mat& Dataset() const;
 
-  //! Expose SearchMode.
-  NeighborSearchMode SearchMode() const;
-  NeighborSearchMode& SearchMode();
+  //! Expose search strategy..
+  NeighborSearchStrategy SearchStrategy() const;
+  NeighborSearchStrategy& SearchStrategy();
 
   //! Expose LeafSize.
   size_t LeafSize() const { return leafSize; }
@@ -459,13 +459,13 @@ class NSModel
   bool& RandomBasis() { return randomBasis; }
 
   //! Initialize the model type.  (This does not perform any training.)
-  void InitializeModel(const NeighborSearchMode searchMode,
+  void InitializeModel(const NeighborSearchStrategy searchStrategy,
                        const double epsilon);
 
   //! Build the reference tree.
   void BuildModel(util::Timers& timers,
                   arma::mat&& referenceSet,
-                  const NeighborSearchMode searchMode,
+                  const NeighborSearchStrategy searchStrategy,
                   const double epsilon = 0);
 
   //! Perform neighbor search.  The query set will be reordered.