Add elsim.studies API and migrate Monte Carlo examples (closes #10)

[endolith]

Summary

Adds elsim.studies, a small orchestration layer for Monte Carlo election studies (issue #10). The elections / strategies / methods modules remain the core simulation model; studies only handles parameter expansion, batched trial execution, result merging, and shared tallies used across paper-reproduction scripts.

Rebased onto master (2025-06-12). One conflict in elsim/__init__.py resolved in favor of this PR's design: relative imports and studies exported alongside the existing submodules.

Scope — elsim.studies API

Module	Purpose
parameters	expand_product, expand_zip, expand_rows — Cartesian product, zipped columns, and explicit scenario rows
backends	SerialBackend, JoblibBackend — swappable execution for run_batched
runner	run_batched, merge_counters — batched trials and Counter aggregation
condorcet_metrics	merrill_1984_comparison_methods, tally_condorcet_agreement — shared Condorcet-paradox tallies
social_utility	spatial_random_reference_utility_updates, random_society_utility_updates, ranked_rated_utility_updates — per-election utility increments for Merrill/Weber-style tables

Sphinx docs: docs/elsim.studies.rst. Tests: tests/test_studies.py.

Migrated examples (21 scripts)

All Monte Carlo / batch-reproduction scripts now use elsim.studies helpers instead of ad-hoc joblib loops:

• Distributions: distributions_by_dispersion.py, distributions_by_method.py, distributions_by_method_2D.py, distributions_by_n_cands.py
• Merrill 1984: merrill_1984_table_1_fig_1.py, merrill_1984_table_2.py, merrill_1984_table_3_fig_3.py, merrill_1984_table_4.py, merrill_1984_fig_2a_2b.py, merrill_1984_fig_2c_2d.py, merrill_1984_fig_2c_2d_updated.py, merrill_1984_fig_4a_4b.py, merrill_1984_fig_4a_4b_updated.py
• Niemi 1968: niemi_1968_table_1.py, niemi_1968_table_2.py
• Weber 1977: weber_1977_table_4.py, weber_1977_effectiveness_table.py, weber_1977_verify_vote_for_k.py
• Tomlinson 2023: tomlinson_2023_figure_3.py, tomlinson_2023_figure_3_updated.py
• Wikipedia: wikipedia_condorcet_paradox_likelihood.py

Not migrated (intentional)

Script	Reason
hypothesis_election_finder.py	Property-based search with Hypothesis, not a Monte Carlo batch study
weber_1977_expressions.py	Closed-form analytic expressions only (imported by other Weber scripts)

Out of scope — PR #56

PR #56 (cursor/declarative-spatial-studies-44e5) explores a separate, declarative spatial-study API. This PR does not include or depend on that approach. The two designs can be evaluated independently; merging this PR does not preclude a future declarative layer.

CI

• Rebased cleanly onto current master
• ruff check . --select=E9,F63,F7,F82 — pass
• pytest — 251 tests pass locally (Python 3.12)
• Full matrix (Python 3.8–3.14 × test / test+fast) expected green on push

Closes #10.

  

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.27%. Comparing base (14b8d55) to head (05e3b98).

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #52      +/-   ##
==========================================
+ Coverage   96.37%   97.27%   +0.90%     
==========================================
  Files          17       23       +6     
  Lines         496      661     +165     
==========================================
+ Hits          478      643     +165     
  Misses         18       18              

Flag	Coverage Δ
no-numba	96.82% <100.00%> (+1.05%)	⬆️
numba	91.07% <100.00%> (+2.96%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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