Support dimension-ranked destination exploration in ScopeItemList

Summary:
`MoveToScopeItemsSpec` restricts an object's destinations to a set of scope items, but always explores every scope item in that set.

In this diff we add an optional `priorityOrdering` to `ScopeItemList`, a `ScopeItemPriorityOrdering` union whose only arm today is `DimensionBasedOrdering`.

`DimensionBasedOrdering` let us specify an dynamic object dimension name. Given this, when evaluating a move w.r.t .an object, we only explore scope items that are ranked better than the object's current scope item as per the dimension. This is useful in scenarios like the following: an object which represents traffic from region `R` is currently in `S` and we have a goal to reduce the latency w.r.t. to this object. IN such scenario we only want to explore destinations that are strictly better than `S` for that object.

The dimension must be dynamic (scope-dependent) on the list's scope; a static one is rejected, since its value doesn't vary by scope item. `ProblemChecker` catches a bad dimension early. `SwapMoveType` rejects `priorityOrdering`, since a swap has no single moving object to rank against. If the object isn't in the scope, all candidates are explored.

**The field is optional; leaving it unset preserves today's behavior exactly---no behavior change unless a client opts in. We plan to use this for GSP latency optimization stage**

Reviewed By: polmauri

Differential Revision: D113100882

fbshipit-source-id: 104f835b16888480370e2c14913358a94ca3a25e

Author: vj-menon

algopt/rebalancer/interface/ProblemChecker.cpp

@@ -1979,6 +1979,29 @@ void ProblemChecker::check(
       checkScopeItemExists(*scopeItemList.scopeName(), scopeItem);
     }
   }
+  if (scopeItemList.filter().has_value()) {
+    const auto& filter = *scopeItemList.filter();
+    switch (filter.getType()) {
+      case interface::ScopeItemFilter::Type::objectDimensionBased: {
+        const auto& dimensionName =
+            *filter.get_objectDimensionBased().dimensionName();
+        checkDimensionExists(dimensionName);
+        const auto& scopeName = *scopeItemList.scopeName();
+        const auto* dimensionScope =
+            folly::get_ptr(dynamicObjectDimensionToScope_, dimensionName);
+        if (dimensionScope == nullptr || *dimensionScope != scopeName) {
+          throw std::runtime_error(
+              fmt::format(
+                  "ObjectDimensionBasedFilter dimension '{}' is expected to be dynamic on scope '{}'",
+                  dimensionName,
+                  scopeName));
+        }
+        break;
+      }
+      case interface::ScopeItemFilter::Type::__EMPTY__:
+        throw std::runtime_error("ScopeItemFilter is not set");
+    }
+  }
 }
 
 void ProblemChecker::check(

algopt/rebalancer/interface/ProblemChecker.h

@@ -375,6 +375,7 @@ class ProblemChecker {
   algopt::SetImpl<std::string> constraintNames_;
   algopt::MapImpl<std::string, algopt::SetImpl<std::string>>
       dimensionToEntityTypes;
+  algopt::MapImpl<std::string, std::string> dynamicObjectDimensionToScope_;
   algopt::MapImpl<std::string, EntityType> globalNameToType;
   algopt::SetImpl<std::string> routingConfigNames_;
   algopt::SetImpl<std::string> destinationsToExploreOptionNames_;
@@ -400,6 +401,7 @@ void ProblemChecker::addDynamicObjectDimension(
     }
   }
   addObjectDimension(dimensionName, ScopeItemToObjectToValue());
+  dynamicObjectDimensionToScope_.emplace(dimensionName, scope);
 }
 
 template <typename ScopeItemToGroupToValue>
@@ -419,6 +421,7 @@ void ProblemChecker::addDynamicObjectDimension(
     }
   }
   addObjectDimension(dimensionName, ScopeItemToGroupToValue());
+  dynamicObjectDimensionToScope_.emplace(dimensionName, scope);
 }
 
 template <typename ObjectToGroup>

algopt/rebalancer/interface/tests/ProblemSolverChecksTest.cpp

@@ -73,6 +73,19 @@ getDefaultGroupCapacitySpec() {
   return spec;
 }
 
+static ScopeItemList makeDimensionFilteredScopeItemList(
+    const std::string& scopeName,
+    const std::string& dimensionName) {
+  ObjectDimensionBasedFilter dimensionFilter;
+  dimensionFilter.dimensionName() = dimensionName;
+  ScopeItemFilter scopeItemFilter;
+  scopeItemFilter.objectDimensionBased() = dimensionFilter;
+  ScopeItemList scopeItemList;
+  scopeItemList.scopeName() = scopeName;
+  scopeItemList.filter() = scopeItemFilter;
+  return scopeItemList;
+}
+
 TEST_P(ProblemSolverChecksTest, SetObjectNameTwice) {
   auto solver =
       initializeTestProblemSolver({.executorThreadCount = GetParam()});
@@ -2753,6 +2766,39 @@ TEST_P(ProblemSolverChecksTest, MoveToScopeItemSpecsTest) {
             "name2", destinationsToExploreOption),
         "unknown group j3 in partition job");
   }
+
+  {
+    // filter must reference an existing dimension
+    MoveToScopeItemsSpec moveToScopeItemsSpec;
+    moveToScopeItemsSpec.defaultScopeItems() =
+        makeDimensionFilteredScopeItemList("rack", "network");
+
+    DestinationsToExploreOptions destinationsToExploreOption;
+    destinationsToExploreOption.set_moveToScopeItems(moveToScopeItemsSpec);
+
+    REBALANCER_EXPECT_RUNTIME_ERROR(
+        solver->addDestinationsToExploreOptions(
+            "filterBadDimension", destinationsToExploreOption),
+        "unknown dimension network");
+  }
+
+  {
+    // filter requires a dynamic dimension; a static one is rejected.
+    solver->addObjectDimension(
+        "size", std::map<std::string, double>{{"s1", 1.0}, {"s2", 2.0}});
+
+    MoveToScopeItemsSpec moveToScopeItemsSpec;
+    moveToScopeItemsSpec.defaultScopeItems() =
+        makeDimensionFilteredScopeItemList("rack", "size");
+
+    DestinationsToExploreOptions destinationsToExploreOption;
+    destinationsToExploreOption.set_moveToScopeItems(moveToScopeItemsSpec);
+
+    REBALANCER_EXPECT_RUNTIME_ERROR(
+        solver->addDestinationsToExploreOptions(
+            "filterStaticDimension", destinationsToExploreOption),
+        "ObjectDimensionBasedFilter dimension 'size' is expected to be dynamic on scope 'rack'");
+  }
 }
 
 TEST_P(ProblemSolverChecksTest, SampleSizeTest) {
@@ -3233,7 +3279,7 @@ TEST_P(ProblemSolverChecksTest, GroupMoveWithHintStrategiesMoveType) {
   }
   {
     // no hint map
-    MoveStrategies groupToMoveStrategy2;
+    const MoveStrategies groupToMoveStrategy2;
     auto spec = makeGroupMoveWithStrategies(
         "primaryPartition", "secondaryPartition", groupToMoveStrategy2);
 

algopt/rebalancer/interface/thrift/SolverSpecs.thrift

@@ -414,11 +414,34 @@ struct MoveToCurrentScopeItemSpec {
   1: string scopeNameForExploringMovesToCurrentScopeItem;
 }
 
+// Filters candidate scope items by a dimension of the moving object, so a move
+// type explores only scope items that are better than the current one, plus
+// ties when includeEqual is set. See ScopeItemList.filter.
+struct ObjectDimensionBasedFilter {
+  // The object dimension whose value is used to compare candidate scope items. It
+  // must be a dynamic object dimension defined on the enclosing ScopeItemList's scope (scopeName)
+  1: string dimensionName;
+  // Whether a lower value should be considered better (e.g. latency). If false, higher is better.
+  2: bool preferLower = true;
+  // Also keep scope items that tie the current one, not just better ones.
+  3: bool includeEqual = false;
+}
+
+union ScopeItemFilter {
+  1: ObjectDimensionBasedFilter objectDimensionBased;
+}
+
 @thrift.ReserveIds{ids = [3]}
 struct ScopeItemList {
   1: string scopeName;
   // if scopeItems are not explicitly listed, all scopeItems in the specified scopeName are taken
   2: optional list<string> scopeItems;
+  // If set, restrict exploration to candidate scope items that the selected
+  // ScopeItemFilter considers better than the moving object's current scope
+  // item, plus ties when the filter includes equal values. If unset, or the
+  // object has no scope item in this scope, all candidates are explored. See
+  // ScopeItemFilter for the strategies.
+  4: optional ScopeItemFilter filter;
 }
 
 struct GroupToScopeItemList {

algopt/rebalancer/solver/moves/DestinationsToExploreGenerator.cpp

@@ -16,6 +16,55 @@
 
 namespace facebook::rebalancer {
 
+namespace {
+// Keeps only the scope items that compare better than the moving object's
+// current one on a chosen dimension. See ScopeItemList.filter.
+class ObjectDimensionBasedFilter {
+ public:
+  ObjectDimensionBasedFilter(
+      const interface::ObjectDimensionBasedFilter& filter,
+      const entities::ObjectScalarDimension& dimension,
+      entities::ScopeId scopeId,
+      entities::ObjectId object,
+      std::optional<entities::ScopeItemId> currentScopeItem)
+      : filter_{filter},
+        dimension_{dimension},
+        scopeId_{scopeId},
+        object_{object} {
+    if (currentScopeItem.has_value()) {
+      currentValue_ = valueAt(*currentScopeItem);
+    }
+  }
+
+  bool includes(entities::ScopeItemId scopeItemId) const {
+    // An object outside the scope has no current value to beat, so keep all.
+    if (!currentValue_.has_value()) {
+      return true;
+    }
+    const auto candidate = valueAt(scopeItemId);
+    if (candidate == *currentValue_) {
+      return *filter_.includeEqual();
+    }
+    return *filter_.preferLower() ? candidate < *currentValue_
+                                  : candidate > *currentValue_;
+  }
+
+ private:
+  double valueAt(entities::ScopeItemId scopeItemId) const {
+    return dimension_.getValueSafe(
+        object_,
+        entities::ScopeScopeItemPair{
+            .scopeId = scopeId_, .scopeItemId = scopeItemId});
+  }
+
+  const interface::ObjectDimensionBasedFilter& filter_;
+  const entities::ObjectScalarDimension& dimension_;
+  entities::ScopeId scopeId_;
+  entities::ObjectId object_;
+  std::optional<double> currentValue_;
+};
+} // namespace
+
 DestinationsToExploreGenerator::DestinationsToExploreGenerator(
     const PackerSet<entities::ContainerId>& nonAcceptingContainers,
     const entities::Universe& universe)
@@ -36,7 +85,8 @@ DestinationsToExploreGenerator::getAcceptingDestinations(
     // in the given scope
     interface::ScopeItemList scopeItemList;
     scopeItemList.scopeName() = scopeName;
-    return getAcceptingContainersList(scopeItemList);
+    return getAcceptingContainersList(
+        scopeItemList, hotContainerId, /*hotObject=*/std::nullopt);
   }
 
   return ReferenceList<const std::vector<entities::ContainerId>>{
@@ -46,14 +96,16 @@ DestinationsToExploreGenerator::getAcceptingDestinations(
 ReferenceList<const std::vector<entities::ContainerId>>
 DestinationsToExploreGenerator::getAcceptingDestinations(
     const interface::MoveToScopeItemsSpec& moveToScopeItems,
+    const entities::ContainerId hotContainer,
     const entities::ObjectId hotObject) {
   auto& objectToScopeItems = *moveToScopeItems.objectToScopeItems();
   auto& hotObjectName = universe_.getEntityName(hotObject);
 
   // if an object is specified in objectToScopeItems, use that.
   auto scopeItemListPtr = folly::get_ptr(objectToScopeItems, hotObjectName);
   if (scopeItemListPtr) {
-    return getAcceptingContainersList(*scopeItemListPtr);
+    return getAcceptingContainersList(
+        *scopeItemListPtr, hotContainer, hotObject);
   }
 
   // if a group is specified in groupToScopeItems and hotObject belongs to that
@@ -81,43 +133,88 @@ DestinationsToExploreGenerator::getAcceptingDestinations(
           groupToScopeItem,
           universe_.getEntityName(onlyGroupId),
           defaultScopeItems);
-      return getAcceptingContainersList(scopeItemList);
+      return getAcceptingContainersList(scopeItemList, hotContainer, hotObject);
     }
   }
 
   // use defaultScopeItems if there is no specialization for hotObject
-  return getAcceptingContainersList(defaultScopeItems);
+  return getAcceptingContainersList(defaultScopeItems, hotContainer, hotObject);
 }
 
 ReferenceList<const std::vector<entities::ContainerId>>
 DestinationsToExploreGenerator::getAcceptingDestinations(
-    const interface::MoveToScopeItemsSpec& moveToScopeItems) {
+    const interface::MoveToScopeItemsSpec& moveToScopeItems,
+    const entities::ContainerId hotContainer) {
   if (!moveToScopeItems.objectToScopeItems()->empty()) {
     throw std::runtime_error(
         "this function requires that objectToScopeItems is empty");
   }
-  return getAcceptingContainersList(*moveToScopeItems.defaultScopeItems());
+  return getAcceptingContainersList(
+      *moveToScopeItems.defaultScopeItems(),
+      hotContainer,
+      /*hotObject=*/std::nullopt);
 }
 
 ReferenceList<const std::vector<entities::ContainerId>>
 DestinationsToExploreGenerator::getAcceptingContainersList(
-    const interface::ScopeItemList& scopeItemList) {
-  ReferenceList<const std::vector<entities::ContainerId>> destinations;
+    const interface::ScopeItemList& scopeItemList,
+    const entities::ContainerId hotContainer,
+    std::optional<entities::ObjectId> hotObject) {
   auto& scopeName = *scopeItemList.scopeName();
   auto scopeId = universe_.getScopeId(scopeName);
   auto& scope = universe_.getScope(scopeId);
-  if (scopeItemList.scopeItems().has_value()) {
-    auto& scopeItemNames = scopeItemList.scopeItems().value();
-    for (auto& scopeItemName : scopeItemNames) {
-      auto scopeItemId = universe_.getScopeItemId(scopeId, scopeItemName);
+
+  std::optional<ObjectDimensionBasedFilter> objectDimensionFilter;
+  if (scopeItemList.filter().has_value()) {
+    if (!hotObject.has_value()) {
+      throw std::runtime_error(
+          "ScopeItemList.filter requires the moving object, but this move type does not provide one");
+    }
+    const auto& filter = *scopeItemList.filter();
+    switch (filter.getType()) {
+      case interface::ScopeItemFilter::Type::objectDimensionBased: {
+        const auto& filterSpec = filter.get_objectDimensionBased();
+        const auto& dimension = universe_.getObjects()
+                                    .getDimension(universe_.getDimensionId(
+                                        *filterSpec.dimensionName()))
+                                    .only();
+        if (!dimension.isDynamic() || dimension.getScopeId() != scopeId)
+            [[unlikely]] {
+          throw std::runtime_error(
+              fmt::format(
+                  "ObjectDimensionBasedFilter dimension '{}' is expected to be dynamic on scope '{}'",
+                  *filterSpec.dimensionName(),
+                  scopeName));
+        }
+        const auto hotContainerScopeItem = scope.getScopeItemId(hotContainer);
+        objectDimensionFilter.emplace(
+            filterSpec, dimension, scopeId, *hotObject, hotContainerScopeItem);
+        break;
+      }
+      case interface::ScopeItemFilter::Type::__EMPTY__:
+        throw std::runtime_error("ScopeItemFilter is not set");
+    }
+  }
+
+  ReferenceList<const std::vector<entities::ContainerId>> destinations;
+  const auto addToDestinations = [&](entities::ScopeItemId scopeItemId) {
+    if (!objectDimensionFilter.has_value() ||
+        objectDimensionFilter->includes(scopeItemId)) {
       destinations.emplace_back(getAcceptingContainers(scopeItemId, scope));
     }
+  };
+
+  if (scopeItemList.scopeItems().has_value()) {
+    const auto& scopeItemNames = scopeItemList.scopeItems().value();
+    for (const auto& scopeItemName : scopeItemNames) {
+      addToDestinations(universe_.getScopeItemId(scopeId, scopeItemName));
+    }
   } else {
     // if scopeItems are not explicitly listed, all scopeItems in the specified
     // scopeName are taken
     auto& scopeItemIds = scope.getScopeItemIds();
     for (auto scopeItemId : scopeItemIds) {
-      destinations.emplace_back(getAcceptingContainers(scopeItemId, scope));
+      addToDestinations(scopeItemId);
     }
   }
   return destinations;

algopt/rebalancer/solver/moves/DestinationsToExploreGenerator.h

@@ -40,15 +40,20 @@ class DestinationsToExploreGenerator {
   ReferenceList<const std::vector<entities::ContainerId>>
   getAcceptingDestinations(
       const interface::MoveToScopeItemsSpec& moveToScopeItems,
+      const entities::ContainerId hotContainer,
       const entities::ObjectId hotObject);
 
   ReferenceList<const std::vector<entities::ContainerId>>
   getAcceptingDestinations(
-      const interface::MoveToScopeItemsSpec& moveToScopeItems);
+      const interface::MoveToScopeItemsSpec& moveToScopeItems,
+      const entities::ContainerId hotContainer);
 
  private:
   ReferenceList<const std::vector<entities::ContainerId>>
-  getAcceptingContainersList(const interface::ScopeItemList& scopeItemList);
+  getAcceptingContainersList(
+      const interface::ScopeItemList& scopeItemList,
+      const entities::ContainerId hotContainer,
+      std::optional<entities::ObjectId> hotObject);
 
   const std::vector<entities::ContainerId>& getAcceptingContainers(
       entities::ScopeItemId scopeItemId,

algopt/rebalancer/solver/moves/GroupMoveWithHintStrategiesMoveType.cpp

@@ -472,7 +472,7 @@ std::vector<MoveSet> GroupMoveWithHintStrategiesMoveType::generateAllMoveSets(
 
     auto acceptingContainersPerScopeItem =
         problem.getDestinationsGenerator().getAcceptingDestinations(
-            *hintOptions.moveToScopeItems(), hotObjectId);
+            *hintOptions.moveToScopeItems(), hotContainer, hotObjectId);
 
     std::vector<MoveSet> newMoveSets;
     if (hintOptions.tertiaryPartition().has_value() &&

algopt/rebalancer/solver/moves/MoveType.cpp

@@ -118,7 +118,9 @@ MoveType::getDestinationsToExplore(
 
     case interface::DestinationsToExploreOptions::Type::moveToScopeItems: {
       return problem.getDestinationsGenerator().getAcceptingDestinations(
-          destinationsToExplore.get_moveToScopeItems(), hotObjectId);
+          destinationsToExplore.get_moveToScopeItems(),
+          hotContainerId,
+          hotObjectId);
     }
 
     case interface::DestinationsToExploreOptions::Type::