Skip to content

feat(examples): rebuild 2D center-squeeze collapse animations on the round-trace API #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devin-ai-integration wants to merge 8 commits into
base: devin/1783868545-collapse-methods
Choose a base branch
from
Open

feat(examples): rebuild 2D center-squeeze collapse animations on the round-trace API #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
da978dc
feat(examples): add 2D collapse geometry helpers
devin-ai-integration[bot] Jul 12, 2026
af9260d
feat(examples): add palette and theme helpers for 2D collapse plots
devin-ai-integration[bot] Jul 12, 2026
e45bf66
feat(examples): add shared four-panel collapse frame scaffold
devin-ai-integration[bot] Jul 12, 2026
38d5aac
feat(examples): add 2D IRV center-squeeze collapse animation
devin-ai-integration[bot] Jul 12, 2026
ecd1245
feat(examples): add 2D Baldwin/Total Vote Runoff collapse animation
devin-ai-integration[bot] Jul 12, 2026
809a0f6
feat(examples): add combined IRV and TVR collapse driver
devin-ai-integration[bot] Jul 12, 2026
2a40b8c
chore(examples): ignore generated collapse results
devin-ai-integration[bot] Jul 12, 2026
f17a9f5
docs(examples): document 2D center-squeeze collapse animations
devin-ai-integration[bot] Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,3 +231,4 @@ _autosummary/
# Build-time copy of examples into docs (see conf.py prepare_examples_doc)
docs/examples/README.md
docs/examples/results/
examples/results/
32 changes: 32 additions & 0 deletions examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,6 +306,38 @@ Source: [distributions_by_dispersion.py](distributions_by_dispersion.py)

Source: [distributions_by_method_2D.py](distributions_by_method_2D.py)

## Center-squeeze collapse animations (2D)

Animated demonstrations of the center-squeeze effect in a two-dimensional
spatial model. Voters and candidates are both normally distributed (candidate
spread half the voter spread), and the scripts sample random elections until
they find a "core collapse" example, then animate the elimination rounds:
each round shows ballots transferring between candidates, first-choice tallies,
average favorability (mean normalized utility), and head-to-head wins.

- **IRV** (`collapse_finder_2d_irv.py`): keeps elections where vote-splitting
makes IRV eliminate the verified Condorcet winner nearest the electorate's
center first and work outward, so only the two farthest candidates survive
to the final round.
- **Total Vote Runoff / Baldwin** (`collapse_finder_2d_tvr.py`): eliminates the
lowest Borda-count candidate each round, so the least-representative
candidates drop first and support converges inward. Baldwin and Total Vote
Runoff satisfy the Condorcet criterion, so the script keeps elections where
the geometric-center candidate is verified as the Condorcet winner from the
pairwise matrix and is elected by Baldwin.
- **Both** (`collapse_finder_2d_both.py`): finds a single election satisfying
both verified criteria above: IRV squeezes out the Condorcet winner while
Baldwin correctly elects it. It renders both animations side by side from
the same voters and candidates.
Comment on lines +328 to +331

@coderabbitai coderabbitai Bot Jul 31, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the "side by side" description.

examples/collapse_finder_2d_both.py writes two separate GIFs into the irv/ and tvr/ subdirectories. It does not compose one frame with both animations. Describe the actual output so readers do not expect a combined layout.

📝 Proposed wording fix 
 - **Both** (`collapse_finder_2d_both.py`): finds a single election satisfying
   both verified criteria above: IRV squeezes out the Condorcet winner while
-  Baldwin correctly elects it. It renders both animations side by side from
-  the same voters and candidates.
+  Baldwin correctly elects it. It renders both animations from the same voters
+  and candidates into separate `irv/` and `tvr/` subdirectories.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- **Both** (`collapse_finder_2d_both.py`): finds a single election satisfying
both verified criteria above: IRV squeezes out the Condorcet winner while
Baldwin correctly elects it. It renders both animations side by side from
the same voters and candidates.
- **Both** (`collapse_finder_2d_both.py`): finds a single election satisfying
both verified criteria above: IRV squeezes out the Condorcet winner while
Baldwin correctly elects it. It renders both animations from the same voters
and candidates into separate `irv/` and `tvr/` subdirectories.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@examples/README.md` around lines 328 - 331, Update the
`collapse_finder_2d_both.py` description in `examples/README.md` to remove the
claim that it renders animations side by side, and instead state that it writes
separate GIFs to the `irv/` and `tvr/` subdirectories while using the same
voters and candidates.


Running a script searches for a qualifying election and writes its frames and
GIF under `examples/results/` (generated output is git-ignored). Run from the
repository root, e.g. `python -m examples.collapse_finder_2d_irv`.

Sources: [collapse_finder_2d_irv.py](collapse_finder_2d_irv.py),
[collapse_finder_2d_tvr.py](collapse_finder_2d_tvr.py),
[collapse_finder_2d_both.py](collapse_finder_2d_both.py)

## Tomlinson 2023

Kiran Tomlinson, Johan Ugander, Jon Kleinberg (2023) [Moderation in instant runoff voting](https://arxiv.org/abs/2303.09734)
Expand Down
Loading