Merge plan for overlapping PRs #52, #56, #65 (unified studies API, spatial sweeps, parallel examples)

[endolith]

Handoff note for any agent: three Cursor-authored PRs currently overlap because all three were branched off master rather than off each other.

• Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52: unified studies API (dirty against master)
• Studies API: declarative spatial sweeps, remove JoblibBackend and hardcoded Merrill methods #56: declarative spatial sweeps (still a draft; does several unrelated things)
• Parallelize examples with joblib (closes #5) #65: parallelize example scripts with joblib (examples only, no library changes; warns it overlaps with Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52)

Desired merge order:

1. Parallelize examples with joblib (closes #5) #65 first. It is mechanical and changes no behavior, so example outputs should stay identical. That makes it the verification baseline.
2. Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 second. The unified API abstracts away the parallel pattern, so the migration is a real simplification diffable against the baseline. The JoblibBackend removal from Studies API: declarative spatial sweeps, remove JoblibBackend and hardcoded Merrill methods #56 is a design decision that belongs here, so it should be settled during Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52's review rather than in a competing branch.
3. Studies API: declarative spatial sweeps, remove JoblibBackend and hardcoded Merrill methods #56 third, but split into separate stacked PRs on top of Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52:
   • new accumulator functions for the spatial normal electorate figures (2d and 2d+shared patterns)
   • approval voting helper
   • Merrill example cleanup
4. Rebase Studies API: declarative spatial sweeps, remove JoblibBackend and hardcoded Merrill methods #56's split branches onto Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 after it merges.

Related: #79 specifies the studies API extension to support all five efficiency metrics (SUE, Bayesian regret, utilitarian efficiency, ESUP, Condorcet efficiency), with the metric list driving which tallies the runner computes.

All three PRs were created by Cursor, and no agent is actively working on them anymore. Any agent may pick up this plan.

Status update (2026-08-01, Skales)

Split 1/3 landed as #81: spatial normal-electorate accumulators (elsim/studies/spatial_normal.py), stacked on #52's branch, mergeable state clean.

Remaining splits of #56:

• Split 2/3: approval voting helper (approval at optimal cutoff) in elsim/studies/condorcet_metrics.py + tests.
• Split 3/3 (shrunk): Merrill tables 1/2/4 updated to use the new approval helper.

Scope change: the earlier "Merrill example cleanup" also included restoring the broken table layout in the merrill_1984_fig_4a_4b.py docstring and simplifying merrill_1984_fig_2a_2b.py. Those are regressions introduced by #52's refactor (master is correct), so they belong squashed into #52, not in a split of #56. Skales's MCP tools can't amend/rebase, so another agent should fold those two fixes into #52 during its rebase. Note left on #52.

Branches are expected to be dirty; another agent handles rebase/conflict resolution later.

— Skales

[endolith]

Plan update from review with the maintainer (2026-08-01):

• The regression fixes caused by Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 (restore the figure 4a/4b docstring table layout; simplify the figure 2a/2b script) belong squashed INTO Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 itself, so the regression never appears in history. Skales cannot amend/rebase via GitHub MCP, so another agent with local git should squash those fixes into Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 (can be done at a later date).
• Part 3 of Studies API: declarative spatial sweeps, remove JoblibBackend and hardcoded Merrill methods #56 shrinks accordingly: it is now only the Merrill example cleanup that uses the new approval helper from part 2 — update Merrill tables 1, 2, 4 to use the helper instead of repeated lambdas (the unified API / rated-methods work). No docstring/table restoration work remains in the splits.
• Dirty branches are fine: Add elsim.studies API and migrate Monte Carlo examples (closes #10) #52 and Parallelize examples with joblib (closes #5) #65 have conflicts with master but CI is green; another agent will do the rebase/conflict resolution later.

— Skales

[endolith]

Update: split 2/3 has now landed as #82 ("feat: add approval_at_optimal helper"), stacked on #52's branch, one commit, tests included. Split 3/3 (Merrill tables 1/2/4 using the new helper) is handed off in #83. Both remaining items for another agent: squash the #52 regression fixes into #52 during its rebase (note left on #52), and implement split 3 from #83.

— Skales