#1359: LB: write docs for args to LBs

src/vt/vrt/collection/balance/greedylb/greedylb.cc

@@ -72,8 +72,59 @@ void GreedyLB::init(objgroup::proxy::Proxy<GreedyLB> in_proxy) {
   proxy = scatter_proxy = in_proxy;
 }
 
+/*static*/ std::unordered_map<std::string, std::string>
+GreedyLB::getInputKeysWithHelp() {
+  std::unordered_map<std::string, std::string> const keys_help = {
+    {
+      "min",
+      R"(
+Values: <double>
+Default: 0.8
+Description:
+  The load threshold for objects to consider on each node. The default value of
+  0.8 will consider 80% of the average load for re-balancing on each node. The
+  order these will be selected is based on the value passed to "strategy". If
+  the parameter "auto" is set to "true", this will be the minimum threshold;
+  otherwise, it sets the threshold directly.
+)"
+    },
+    {
+      "max",
+      R"(
+Values: <double>
+Default: 1.004
+Description:
+  The maximum load threshold for objects to consider on each node which is only
+  used if "auto" is "true".
+)"
+    },
+    {
+      "auto",
+      R"(
+Values: {true, false}
+Default: true
+Description:
+  Automatically determine the threshold between "min" and "max" using
+  calculated I (imbalance metric) with the formula
+  min(max(1-I, min), max).
+)"
+    },
+    {
+      "strategy",
+      R"(
+)"
+    }
+  };
+  return keys_help;
+}
+
 void GreedyLB::inputParams(balance::SpecEntry* spec) {
-  std::vector<std::string> allowed{"min", "max", "auto", "strategy"};
+  auto keys_help = getInputKeysWithHelp();
+
+  std::vector<std::string> allowed;
+  for (auto&& elm : keys_help) {
+    allowed.push_back(elm.first);
+  }
   spec->checkAllowedKeys(allowed);
   min_threshold = spec->getOrDefault<double>("min", greedy_threshold_p);
   max_threshold = spec->getOrDefault<double>("max", greedy_max_threshold_p);

src/vt/vrt/collection/balance/greedylb/greedylb.h

@@ -84,6 +84,8 @@ struct GreedyLB : BaseLB {
   void runLB() override;
   void inputParams(balance::SpecEntry* spec) override;
 
+  static std::unordered_map<std::string, std::string> getInputKeysWithHelp();
+
 private:
   double getAvgLoad() const;
   double getMaxLoad() const;

src/vt/vrt/collection/balance/hierarchicallb/hierlb.cc

@@ -71,8 +71,68 @@ void HierarchicalLB::init(objgroup::proxy::Proxy<HierarchicalLB> in_proxy) {
   proxy = in_proxy;
 }
 
+/*static*/ std::unordered_map<std::string, std::string>
+HierarchicalLB::getInputKeysWithHelp() {
+  std::unordered_map<std::string, std::string> const keys_help = {
+    {
+      "min",
+      R"(
+Values: <double>
+Default: 0.8
+Description:
+  The load threshold for objects to consider on each node. The default value of
+  0.8 will consider 80% of the average load for re-balancing on each node. The
+  order these will be selected is based on the value passed to "strategy". If
+  the parameter "auto" is set to "true", this will be the minimum threshold;
+  otherwise, it sets the threshold directly.
+)"
+    },
+    {
+      "max",
+      R"(
+Values: <double>
+Default: 1.004
+Description:
+  The maximum load threshold for objects to consider on each node which is only
+  used if "auto" is "true".
+)"
+    },
+    {
+      "auto",
+      R"(
+Values: {true, false}
+Default: true
+Description:
+  Automatically determine the threshold between "min" and "max" using
+  calculated I (imbalance metric) with the formula
+  min(max(1-I, min), max).
+)"
+    },
+    {
+      "strategy",
+      R"(
+Values: {LoadOverLessThan, LoadOverGreaterThan, LoadOverOneEach}
+Default: LoadOverLessThan
+Description:
+  Select the strategy for which objects to select for rebalancing that are over
+  the selected threshold:
+   -  LoadOverLessThan    -- pick the smallest objects on the node
+   -  LoadOverGreaterThan -- pick the largest objects on the node
+   -  LoadOverOneEach     -- pick objects from all the sample bins across the
+                             range of sizes
+)"
+    }
+  };
+  return keys_help;
+}
+
 void HierarchicalLB::inputParams(balance::SpecEntry* spec) {
-  std::vector<std::string> allowed{"min", "max", "auto", "strategy"};
+  auto keys_help = getInputKeysWithHelp();
+
+  std::vector<std::string> allowed;
+  for (auto&& elm : keys_help) {
+    allowed.push_back(elm.first);
+  }
   spec->checkAllowedKeys(allowed);
   min_threshold = spec->getOrDefault<double>("min", hierlb_threshold_p);
   max_threshold = spec->getOrDefault<double>("max", hierlb_max_threshold_p);

src/vt/vrt/collection/balance/hierarchicallb/hierlb.h

@@ -76,6 +76,8 @@ struct HierarchicalLB : BaseLB {
   void runLB() override;
   void inputParams(balance::SpecEntry* spec) override;
 
+  static std::unordered_map<std::string, std::string> getInputKeysWithHelp();
+
   void setupTree(double const threshold);
   void calcLoadOver(HeapExtractEnum const extract);
   void loadOverBin(ObjBinType bin, ObjBinListType& bin_list);

src/vt/vrt/collection/balance/randomlb/randomlb.cc

@@ -52,8 +52,43 @@ void RandomLB::init(objgroup::proxy::Proxy<RandomLB> in_proxy) {
   proxy = in_proxy;
 }
 
+/*static*/ std::unordered_map<std::string, std::string>
+RandomLB::getInputKeysWithHelp() {
+  std::unordered_map<std::string, std::string> const keys_help = {
+    {
+      "randomize_seed",
+      R"(
+Values: {true, false}
+Default: false
+Description:
+  Whether the seed which determines placement of objects should be randomized.
+  The parameter "seed" is only read if this is set to false. When it is true,
+  the load balancer will create a std::random_device to generate the values.
+)"
+    },
+    {
+      "seed",
+      R"(
+Values: <int>
+Default: 123456789
+Description:
+  An integer value that is used to seed the value that generates random
+  locations for migrations. The seed is deterministically combined with the
+  phase number and the node (rank) to provide a unique seed for each rank for
+  each phase.
+)"
+    }
+  };
+  return keys_help;
+}
+
 void RandomLB::inputParams(balance::SpecEntry* spec) {
-  std::vector<std::string> allowed{"seed", "randomize_seed"};
+  auto keys_help = getInputKeysWithHelp();
+
+  std::vector<std::string> allowed;
+  for (auto&& elm : keys_help) {
+    allowed.push_back(elm.first);
+  }
   spec->checkAllowedKeys(allowed);
   seed_ = spec->getOrDefault<int32_t>("seed", seed_);
   randomize_seed_ = spec->getOrDefault<bool>("randomize_seed", randomize_seed_);

src/vt/vrt/collection/balance/randomlb/randomlb.h

@@ -58,6 +58,8 @@ struct RandomLB : BaseLB {
   void runLB() override;
   void inputParams(balance::SpecEntry* spec) override;
 
+  static std::unordered_map<std::string, std::string> getInputKeysWithHelp();
+
 private:
   int seed_ = 123456789;
   bool randomize_seed_ = false;

src/vt/vrt/collection/balance/rotatelb/rotatelb.cc

@@ -53,6 +53,11 @@ void RotateLB::init(objgroup::proxy::Proxy<RotateLB> in_proxy) {
   proxy = in_proxy;
 }
 
+/*static*/ std::unordered_map<std::string, std::string>
+RotateLB::getInputKeysWithHelp() {
+  return std::unordered_map<std::string, std::string>{};
+}
+
 void RotateLB::inputParams(balance::SpecEntry* spec) { }
 
 void RotateLB::runLB() {

src/vt/vrt/collection/balance/rotatelb/rotatelb.h

@@ -69,6 +69,8 @@ struct RotateLB : BaseLB {
   void runLB() override;
   void inputParams(balance::SpecEntry* spec) override;
 
+  static std::unordered_map<std::string, std::string> getInputKeysWithHelp();
+
 private:
   objgroup::proxy::Proxy<RotateLB> proxy = {};
 };