boot-sp PR-4: K>1 batch executor (groups of K ranks; wheel per group)

[DLWoodruff]

Stacked PR — fork-only for now. Base is bootsp-pr-c (PR-3), so this diff is
PR-4 alone. The branch itself carries the whole boot-sp stack (PR-1→4), so
git checkout bootsp-pr-d is self-contained and runnable. Opens upstream only
after PR-2 (now upstream Pyomo/mpi-sppy#818)
and PR-3 land.

⚠️ Migration note (for anyone already tracking this branch)

This branch was force-pushed again (2026-07-26). A review against the
Chen & Woodruff papers found seven issues; the fixes were placed on the lowest
branch whose code they correct, so bootsp-pr-b (PR-2) and bootsp-pr-c (PR-3)
were both rewritten and this branch was rebased onto the new pr-c.

Re-sync, don't merge. Every commit SHA is new (previous published tip
15bedb80 → c3946212; the tip before that was 5b4e48b6). Reset your
checkout onto the new tip:

git fetch origin
git checkout bootsp-pr-d && git reset --hard origin/bootsp-pr-d
# for work branched off it (substitute the tip you branched from):
git rebase --onto origin/bootsp-pr-d 15bedb80 <your-branch>

A plain git pull will try to merge the old and new histories.

Smoothed bootstrap results change substantially. Two deviations from
CW2024 Algorithm 3 were corrected in PR-2, which this branch inherits: the
batches were overlapping sliding windows rather than independent resamples, and
the center was the empirical gap rather than the smoothed one. On the cvar
example at N=20, nB=10 the interval widens about fivefold — the previous
smoothed intervals were far too narrow. Smoothed_bagging is unaffected except
for a ddof=1 correction to its variance. The empirical methods are unchanged.

Bootstrap CI bounds change; point estimates do not. No CLI/flag changes —
the same commands run. But the interval endpoints move, from two fixes the
branch now inherits from main (they postdated this branch's old base):

• Sample splitting — the CI resampling pool now excludes the records used
  to compute xhat. The interval is estimated out-of-sample (on data that did
  not choose xhat) rather than optimistically in-sample, so it is honest and
  generally a touch wider.
• Independent, pair-seeded RNG streams — every resample draws differently,
  so the bounds shift. (The K > 1 batch executor's per-group seeding changed
  too, so those runs move as well.)

The gap point estimates (the centers) are unchanged — they are deterministic.
Only recorded/expected CI bounds need updating.

New requirement. Sample splitting needs
sample_size + candidate_sample_size ≤ max_count. A config that previously
over-subscribed the dataset now fails fast with a clear error instead of
silently overlapping the candidate and CI records.

The generic_cylinders bootstrap now honors sample splitting end to end —
do_boot holds the M candidate records out of the N-record pool
positionally, so the integrated --boot-* path is consistent with the
standalone estimators.

You also inherit current upstream main (CVaR η-bound, CI ruff pin, etc.),
since the branch was rebased onto it.

What this adds

The K > 1 batch executor for the data-based bootstrap in generic_cylinders
(design doc/designs/bootsp_merge_design.md §9.4). A resampled batch is no
longer only a per-rank extensive form: it can be solved by a group of K
ranks running a wheel. The R ranks partition into G = R // K groups that
run concurrently, each solving its share of the batches in sequence, with the
results gathered to rank 0.

The two endpoints are the same mechanism, so this is one executor with
--boot-ranks-per-batch as its only new rank knob:

• K = 1 → G = R: each rank its own group, a direct EF per batch (what PR-3
  shipped). Reproduced bit-for-bit as the degenerate case, so the standalone
  user_boot / simulate_boot are unaffected.
• K = R → G = 1: one group of all ranks, a wheel per batch in sequence (the
  development checkpoint).

The pieces

• BatchExecutor (confidence_intervals/bootsp/batch_executor.py) — owns
  the rank arithmetic and the collectives: each group's communicator (wheel /
  xhat-evaluation), a leaders-only communicator (the cross-group Gatherv),
  per-group batch share and rng seed, and gather().
• Estimator refactor (boot_sp.py) — the empirical estimators route their
  parallelism through the executor; the five repeated Gatherv blocks collapse
  into executor.gather, and a single _batch_optimal_value is the one entry
  for the batch optimal L_b (EF best bound at K = 1, wheel outer bound at
  K > 1). The smoothed methods and the simulation prep keep the K = 1-only
  path via an optional mpicomm.
• Batch wheel builder (generic/boot_batch.py) — --boot-batch-config-file
  is parsed as a file of generic_cylinders flags and turned into a per-batch
  wheel (reusing the hub/spoke/decomp builders with injected sample-scenario
  names); its outer decomposition bound is read back as L_b.
• Wiring — do_boot/config drop the K != 1 restriction, require the
  batch config file, and retire the interim --boot-solver-name /
  --boot-solver-options (the batch solver now comes from the file).
• register_generic_args factored out of parse_args (pure refactor) so the
  batch config file and the main CLI share one registration point.

Why the outer bound (design §9.4.1)

A batch's reported gap is its value at xhat (an inner bound, solver-exact) minus
its optimal. For the optimal the executor uses the wheel's outer
(decomposition) bound, not an incumbent — a MIP batch carries a bound slack even
at K = 1, so inner−outer keeps the reported point estimate conservative — it
never understates the gap an exact solve would report.

The interval endpoints carry no such guarantee, and an earlier version of
this description claimed they did. Each endpoint combines the point estimate
with a width built from the spread of the batch gaps, and a bound slack
perturbs that spread without a sign; the pivotal methods (Classical_quantile,
Subsampling, Extended) reflect the bootstrap quantiles about the point
estimate, so a batch slack can move both of their endpoints down. All the
methods do converge to the exact-solve CI as the batch gap tightens, so
--rel-gap in the batch config file is the lever when the interval matters.

Validation

End to end on the schultz_data MIP, both endpoints reproduce the design's math
exactly: the G = 1 checkpoint (np=2, K=2) and G > 1 (np=4, K=2) both give the
same value at xhat as the K = 1 EF path (the xhat-evaluation is
K-invariant), while their Lagrangian/subgradient outer bound sits at or below the
EF optimum — so the reported gap is conservative.

• mpisppy/tests/test_boot_generic.py::test_do_boot_g1_wheel_matches_ef encodes
  this self-validatingly (no magic numbers), gated on n_proc >= 2 so it runs
  under the existing mpiexec -np 2 test_boot_generic invocation — no coverage
  harness change.
• All boot tests green: serial 48 passed / 3 skipped; mpiexec -np 2 33 passed
  / 2 skipped across the three MPI-run suites (incl. the G=1 wheel test).
  ruff clean, headers OK, docs build with no warnings.

Review fixes carried by this branch

A review of the whole stack against Chen & Woodruff (2023, 2024) and the
certified-bounds notes produced seven findings. Each fix sits on the lowest
branch whose code it corrects, so most arrive here by inheritance:

• PR-2 (Bootstrap/bagging confidence intervals (boot-sp merge PR-2: statdist + smoothed methods) Pyomo/mpi-sppy#818) — the two CW2024 Algorithm 3 deviations in the smoothed
  bootstrap, sample variances (ddof=1) in smoothed bagging, and a
  maximization guard in solve_routine.
• PR-3 — the conservatism wording above, the reference z* kept as the
  incumbent (with a convergence check), and a consistent fallback when the
  solver proves no outer bound.
• PR-4 (this branch) — the pieces that only exist once cylinders solve the
  batches: do_boot probes one scenario for its objective sense (a K > 1
  batch is a wheel, so solve_routine's check never sees it), _best_bound's
  docstring names its boot_batch sibling and why that one raises where this
  one falls back, and the relocated rst section regains the corrected wording.

Runnable demo

examples/bootsp/schultz_data/schultz_data_boot_cylinders.bash — 6 ranks find
xhat together, then re-form into two groups of three that solve the bootstrap
batches concurrently, each batch by a subgradient wheel (config in the committed
schultz_wheel_batch.txt). Runs in ~4 s with any MIP/MIQP solver; the log shows
the two concurrent 3-rank groups.

🤖 Generated with Claude Code