Flexible rank assignments — Phase 1: infrastructure

[DLWoodruff]

First implementation phase of the flexible-rank-assignments design
(doc/designs/flexible_rank_assignments.md, merged in #724). Lands the
static, unit-testable building blocks without changing any runtime
behavior at equal rank counts — the live unequal-rank path is gated
off pending the Phase 2 communicator rework.

What's here

• mpisppy/utils/rank_apportionment.py — apportion_ranks(ratios, n_proc): largest-remainder (Hare) apportionment of a rank pool across
  cylinders by target ratio, with a floor of one rank per cylinder.

• mpisppy/cylinders/overlap_map.py — OverlapSegment +
  compute_overlap_segments(): given a local rank's scenarios, a peer
  cylinder's contiguous scenario partition (the slices from
  scen_names_to_ranks), and a per-scenario item count, produce the
  segments that back a local field buffer from the peer's buffers.
  Contiguous same-rank runs coalesce; equal rank counts degenerate to a
  single identity segment. Pure — no MPI/Pyomo.

• SPWindow.get() — optional item_offset/item_count for
  sub-range reads via MPI_Get displacement. Defaults reproduce the
  original whole-padded-field transfer exactly, so existing callers are
  untouched. This is the primitive multi-source assembly will use.

• WheelSpinner.run() — reads a per-cylinder rank_ratio dict key
  (default 1.0). All-1.0 is handled exactly as before. A non-uniform
  request is apportioned and reported (global_toc on rank 0), then
  raises NotImplementedError — building communicators for unequal
  per-cylinder counts is not yet wired into the comm/window layer.

• Fixes two errors in the design doc's overlap worked-example (verified
  against compute_overlap_segments).

Testing

• 33 new unit tests across test_rank_apportionment.py,
  test_overlap_map.py, test_spwindow_partial_get.py (real
  COMM_SELF RMA window), and test_flexible_rank_gate.py (stub comm).
  All wired into run_coverage.bash and test_pr_and_main.yml.
• Default (equal-rank) path confirmed unchanged by running
  test_with_cylinders (PH hub + xhatshuffle spoke) end to end.

Not in this phase

Building the actual unequal-rank communicators/window (drop
strata_comm, multi-source get_receive_buffer consuming the overlap
maps) is the next phase; that's why non-uniform ratios raise for now.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.69%. Comparing base (6662635) to head (109e571).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #725      +/-   ##
==========================================
+ Coverage   72.57%   72.69%   +0.11%     
==========================================
  Files         162      164       +2     
  Lines       20643    20715      +72     
==========================================
+ Hits        14982    15059      +77     
+ Misses       5661     5656       -5     

☔ View full report in Codecov by Sentry.
📢 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.