Slamming: preference-driven in-hub variable fixing

[DLWoodruff]

What

Adds slamming to mpi-sppy: forcing (fixing) selected nonanticipative
variables according to pre-specified user preferences while a decomposition hub
is running, to drive toward a feasible/converged incumbent when ordinary
convergence is slow. It is an Extension (in the in-hub-fixing family with
fixer.py, reduced_costs_fixer.py, relaxed_ph_fixer.py) and runs under any
PHBase-derived hub (PH, APH, Subgradient, FWPH).

This is distinct from the existing SlamMin/SlamMax spokes, which are
non-destructive incumbent finders; the slammer alters the hub search per user
preference and is multistage-capable (the spokes are two-stage only).

Design: doc/designs/slamming_design.md.

How it's used

Activated only when a directives file is supplied, so a run with no slamming
options is byte-for-byte unchanged:

• --slamming-directives-file <file> — activates the extension
• --slam-start-iter K — first iteration at which slamming may occur (default 1)
• --iters-between-slams M — cadence once started (default 1)

Supplying the other options without the file is a hard error.

The directives file is a CSV keyed by nonant name with shell-style wildcards
(*/?; index brackets [ ] are matched literally — deliberately not
fnmatch, whose bracket semantics would make DoBuild[*] fail to match
DoBuild[Seattle]). Each row gives a name pattern, an optional can_slam
(1/0), an ordered |-separated list of directions from
{lb, ub, nearest, anywhere, min, max} (first applicable is used), and a
priority (largest is slammed first; ties by name). Matching is
last-match-wins; only variables matched by a can_slam rule are ever slammed;
a pattern that matches nothing is an error that names the file.

A worked example translated from PySP's wwph.suffixes ships at
examples/sizes/config/slamming_directives.csv.

Behavior

• One variable is slammed per event, by largest priority (name-tiebroken so the
  choice is identical on every rank). Eligibility: matched + can_slam, not
  already fixed, not a surrogate, has an applicable direction. There is no
  convergence gate (slamming an already-settled variable just pins it).
• lb/ub/nearest/anywhere use only rank-identical data (no
  communication); min/max do one small reduction over the per-node
  communicator, and only when such a slam actually fires.
• Slams are sticky.

Scope

This is the slamming mechanism. Deciding when to slam beyond the built-in
iteration-count trigger (genuine stall/cycle detection) is a separate future
project that would invoke this mechanism as a consumer; it is intentionally not
part of this PR.

Tests / docs

• mpisppy/tests/test_slammer.py — 43 solver-free unit tests (parser, matcher,
  every direction, selection / eligibility / stickiness, trigger,
  backward-compatibility, zero-match error). Wired into run_coverage.bash
  and test_pr_and_main.yml.
• Docs: doc/src/extensions.rst (slammer section + flag) and the design doc.
• Verified live on the sizes MIP (serial and mpiexec -np 2): slams fire on
  cadence, the cross-rank max reduction stays coherent, persistent-solver
  updates work, and a bad pattern errors naming the file.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 91.11111% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.93%. Comparing base (ca1984a) to head (fc344ba).

Files with missing lines	Patch %	Lines
mpisppy/extensions/slammer.py	95.14%	10 Missing ⚠️
mpisppy/utils/cfg_vanilla.py	10.00%	9 Missing ⚠️
mpisppy/generic/extensions.py	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #765      +/-   ##
==========================================
+ Coverage   73.73%   73.93%   +0.20%     
==========================================
  Files         165      166       +1     
  Lines       21121    21346     +225     
==========================================
+ Hits        15574    15783     +209     
- Misses       5547     5563      +16     

☔ 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.