[WIP] support xhat mip gapper options in generic cylinders

doc/src/generic_cylinders.rst

@@ -118,3 +118,38 @@ warmstart-subproblems
 Loosely speaking, this option causes subproblem solves to be given the
 previous iteration solution as a warm-start. This is particularly important
 when using an option to lineraize proximal terms.
+
+
+mipgap extensions
+-----------------
+
+Extensions can be seen using the ``--help`` argument (the ``--module``
+argement is still required for ``--help``).  We provide a little
+background here. If the mipgap command does not have a prefix, then
+it refers to the hub algorithm, otherwise the prefix refers
+to the cylinder named in the prefix (if the cylinder is not
+present, no error message is given). So ``--mapgap-json`` gives
+the name of the mpigap json file for the PH hub algorithm, while
+``--lagrangian-mipgap-json`` gives it for the ``lagrangian`` spoke
+(if present).  See the ``mipgapper`` section of :ref:`Extensions`
+for a little more information.
+
+Here is an example json file:
+
+.. code-block:: json
+
+  {
+    "0": 0.02,
+    "1": 0.02,
+    "2": 0.01,
+    "10": 0.001,
+    "20": 0.0001
+  }
+
+The ``starting-mipgap`` (e.g., ``lagrangian-starting-mipgap``)
+and ``mipgap-ratio`` options taken together operate based on the overall
+gap (the so-called `cylinder` gap) to set the mipgap.
+As the cylinders close the relative optimality gap the extension will set the subproblem
+mipgaps as the ``min(starting_mipgap, mipgap_ratio * problem_ratio)``, where
+the ``problem_ratio`` is the relative optimality gap on the overall problem
+as computed by the cylinders.

mpisppy/generic_cylinders.py

@@ -82,6 +82,8 @@ def _parse_args(m):
     cfg.integer_relax_then_enforce_args()
     cfg.gapper_args()    
     cfg.gapper_args(name="lagrangian")
+    cfg.gapper_args(name="xhatshuffle")
+    cfg.gapper_args(name="xhatxbar")
     cfg.ph_nonant_args()
     cfg.relaxed_ph_args()
     cfg.fwph_args()
@@ -379,11 +381,15 @@ def _do_decomp(module, cfg, scenario_creator, scenario_creator_kwargs, scenario_
         if cfg.get("stage2EFsolvern") is not None:
             xhatshuffle_spoke["opt_kwargs"]["options"]["stage2EFsolvern"] = cfg["stage2EFsolvern"]
             xhatshuffle_spoke["opt_kwargs"]["options"]["branching_factors"] = cfg["branching_factors"]
+        if cfg.lagrangian_starting_mipgap is not None:
+            vanilla.add_gapper(lagrangian_spoke, cfg, "xhatshuffle")            
 
     if cfg.xhatxbar:
         xhatxbar_spoke = vanilla.xhatxbar_spoke(*beans,
                                                    scenario_creator_kwargs=scenario_creator_kwargs,
                                                    all_nodenames=all_nodenames)
+        if cfg.lagrangian_starting_mipgap is not None:
+            vanilla.add_gapper(xhatxbar_spoke, cfg, "xhatshuffle")
 
     # reduced cost fixer options setup
     if cfg.reduced_costs:

mpisppy/utils/config.py

@@ -560,7 +560,7 @@ def gapper_args(self, name=None):
             name = name+"_"
 
         if name == "":
-            self.add_to_config('mipgaps_json',
+            self.add_to_config(f'{name}mipgaps_json',
                                description="path to json file with a mipgap schedule for PH iterations",
                                domain=str,
                                default=None)