Per-spoke solver for xhat spokes + close solver-options-redesign §4

[DLWoodruff]

Bundles two related pieces of "solver work" on the solver-options surface.

1. Per-spoke solver for the xhat inner-bound spokes (code)

The outer-bound spokes already accept --<spoke>-solver-name, -solver-options, and -solver-options-file (lagrangian, reduced_costs, subgradient, relaxed_ph, ph_dual — all via Config.add_solver_specs(prefix)), and FWPH has its own --fwph-mip-solver-name / --fwph-qp-solver-name. The xhat inner-bound spokes did not: their *_args helpers never called add_solver_specs, and their factories never called apply_solver_specs.

This adds the full trio to the xhat spokes:

• Register — add_solver_specs("<prefix>") in xhatlooper_args, xhatshuffle_args, xhatspecific_args, xhatxbar_args, xhatlshaped_args.
• Consume — apply_solver_specs("<prefix>", spoke, cfg) in the five matching spoke factories in cfg_vanilla.py.

apply_solver_specs updates iter0/iterk_solver_options in place (never reassigns), so each xhat factory's nested xhat_solver_options reference to iterk stays valid. Because the three flags register independently, "different options but the inherited solver" also works (supply only --<xhat>-solver-options).

So, e.g.:

generic_cylinders ... --solver-name gurobi --xhatshuffle --xhatshuffle-solver-name xpress

now runs the PH hub on gurobi and the xhatshuffle inner-bound spoke on xpress.

Regression tests added to mpisppy/tests/test_solver_options_layers.py (already wired into the coverage harness):

• all five xhat *_args register the solver trio;
• xhatshuffle_spoke routes per-spoke solver name + options (and the nested xhat_solver_options) into the spoke;
• xhatlshaped_spoke routes them too — it is the one xhat factory with no nested xhat_solver_options dict, and it previously had no unit coverage at all (only end-to-end via examples/run_all.py and generic_tester.py).

Corrects and will close #805 (whose original problem statement overstated the gap — the outer-bound spokes already had these flags).

2. Doc reconciliation (docs, no behavior change)

The solver-options redesign shipped a while ago (PRs #696–#703), and parts of the design doc still read as forward-looking.

• solver_options_redesign.md §4 open questions Make SPOKE_SLEEP_TIME automatic #1–Bundles to spokes #4 marked Resolved, matching the shipped implementation (4 stage test #5 was already marked).
• Status header and §1 refreshed: the redesign is shipped, not "in progress".
• §1.4 no longer claims apply_solver_specs overwrites the iter0/iterk dicts wholesale — phase 4 changed that to an overlay, which §1.5 already said. Stale line-number anchors dropped.
• §6.4 put in past tense (it was still "should land" / "Suggested order"), and the lone **Shipped.** marker on phase 8 dropped now that the preamble covers all eight.
• doc/src/generic_cylinders.rst documented --<spoke>-solver-options but never --<spoke>-solver-name. Added, with the hub-on-one-solver / spoke-on-another example, the three xhat spokes generic_cylinders exposes, and a note that FWPH's two-solver flags are the exception to the pattern.

Notes

• xhatlooper / xhatspecific register the flags too, but those spokes aren't wired into generic_cylinders (they're used by other drivers) — intentional, and they're deliberately not named in the generic_cylinders docs.
• Third-party drivers that call an xhat spoke factory without having called the matching *_args helper are unaffected: cfg.get() returns None for the unregistered key and apply_solver_specs no-ops.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR extends mpi-sppy’s solver-options “per-spoke” configuration surface to the xhat inner-bound spokes (bringing them in line with existing outer-bound spokes), and updates the solver-options redesign design doc to mark several previously-open questions as resolved.

Changes:

• Register per-spoke solver specification flags for xhat spokes by adding add_solver_specs("<xhat>") in the relevant Config *_args helpers.
• Apply per-spoke solver specifications inside the corresponding xhat spoke factories via apply_solver_specs("<xhat>", spoke_dict, cfg).
• Add regression tests verifying (a) xhat args register the solver trio and (b) xhatshuffle_spoke routes per-spoke solver name/options into the spoke options; plus doc updates resolving solver-options redesign §4 questions.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
mpisppy/utils/config.py	Registers per-xhat-spoke solver flags via add_solver_specs() in the xhat *_args helpers.
mpisppy/utils/cfg_vanilla.py	Ensures xhat spoke factories consume per-spoke solver specs by calling apply_solver_specs() before building xhat-specific option sub-dicts.
mpisppy/tests/test_solver_options_layers.py	Adds regression tests for xhat per-spoke solver flag registration and routing (via xhatshuffle_spoke).
doc/designs/solver_options_redesign.md	Marks solver-options redesign §4 questions as resolved and references the shipped implementation behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 76.67%. Comparing base (d65c85b) to head (a4b6eb9).

Files with missing lines	Patch %	Lines
mpisppy/utils/cfg_vanilla.py	80.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #806   +/-   ##
=======================================
  Coverage   76.67%   76.67%           
=======================================
  Files         176      176           
  Lines       23253    23263   +10     
=======================================
+ Hits        17829    17838    +9     
- Misses       5424     5425    +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.