API Reference
Complete API documentation for ElectoralSim.
Core
| Class/Function | Description |
|---|---|
| ElectionModel | Main simulation model |
| Config | Configuration dataclass |
| PartyConfig | Party configuration |
Agents
| Class/Function | Description |
|---|---|
| VoterAgents | Vectorized voter agent storage |
| PartyAgents | Vectorized party agent storage |
| adaptive_strategy_step | Dynamic party position updates |
Behavior Models
| Class | Description |
|---|---|
| BehaviorEngine | Combines multiple behavior models |
| ProximityModel | Spatial/ideological voting |
| ValenceModel | Non-policy candidate appeal |
| RetrospectiveModel | Economic/incumbent voting |
| StrategicVotingModel | Duverger's Law effects |
| WastedVoteModel | Tactical voting |
| SociotropicPocketbookModel | Economic perception |
Campaign Models
| Class | Description |
|---|---|
| CampaignFinance | Finance-to-valence conversion |
| MediaEnvironment | Media exposure & sentiment |
| VoterRegistration | Eligibility & registration |
| CampaignTargeting | Constituency resource allocation |
| TurnoutMobilization | Canvassing & GOTV effects |
| PollingAccess | Distance & wait-time barriers |
Constituency & Counting
| Class/Function | Description |
|---|---|
| ConstituencyMetadata | District metadata dataclass |
| ConstituencyManager | Constituency collection management |
| is_candidate_eligible | Reserved-seat eligibility check |
| count_fptp | FPTP vote counting |
| count_pr | PR vote counting with allocation |
Electoral Systems
| Function | Description |
|---|---|
| dhondt_allocation | D'Hondt seat allocation |
| sainte_lague_allocation | Sainte-Laguë allocation |
| hare_quota_allocation | Hare quota (LR) |
| droop_quota_allocation | Droop quota |
| irv_election | Instant Runoff Voting |
| stv_election | Single Transferable Vote |
| approval_voting | Approval voting |
| condorcet_winner | Condorcet winner detection |
| borda_count | Borda count rank voting |
| score_voting | Score (range) voting |
| pav_committee | Proportional Approval Voting |
| generate_rankings | Utility-to-ranking conversion |
| allocate_seats | Universal seat allocation |
Primary Elections
| Function | Description |
|---|---|
| closed_primary | Party-members-only primary |
| open_primary | Open primary election |
| candidate_selection | Candidate field generation |
Events & Timeline
| Class/Function | Description |
|---|---|
| Event | Dynamic event dataclass |
| EventManager | Event generation & tracking |
| ElectionTimeline | Campaign/election scheduling |
| PollGenerator | Synthetic poll generation |
Metrics
| Function | Description |
|---|---|
| gallagher_index | Disproportionality measure |
| effective_number_of_parties | Laakso-Taagepera ENP |
| efficiency_gap | Gerrymandering metric |
| loosemore_hanby_index | Disproportionality measure |
| herfindahl_hirschman_index | Market concentration index |
| partisan_bias | Tilt toward one party |
| mean_median_gap | Vote distribution skew |
| partisan_gini | Inequality measure |
| polsby_popper | District compactness |
| convex_hull_compactness | Geometric compactness |
Coalition & Government
| Function/Class | Description |
|---|---|
| form_government | Coalition formation |
| minimum_winning_coalitions | Find MWCs |
| minimum_connected_winning | Find MCWs |
| coalition_strain | Calculate strain |
| GovernmentSimulator | Stability simulation |
Analysis
| Function | Description |
|---|---|
| one_at_a_time | OAT parameter sensitivity |
| grid_sensitivity | Grid-based sensitivity |
| swing_analysis | Swing parameter analysis |
| mse_loss | Calibration loss function |
| grid_search_calibration | Grid-search calibration |
| generate_calibration_report | Calibration report |
| run_duverger_experiment | FPTP vs PR convergence |
| calculate_vse | Voting System Efficiency |
| calculate_welfare | Social welfare |
Redistricting
| Class/Function | Description |
|---|---|
| PrecinctGraph | Precinct adjacency graph |
| recom_proposal | ReCom spanning-tree recombination |
| ensemble_analysis | Ensemble comparison |
GPU Acceleration
| Function | Description |
|---|---|
| is_gpu_available | GPU availability check |
| compute_utilities_gpu | GPU utility computation |
| mnl_sample_gpu | GPU MNL sampling |
Visualization
| Function | Description |
|---|---|
| plot_seat_distribution | Seat bar chart |
| plot_vote_shares | Vote share pie chart |
| plot_seats_vs_votes | Seats vs votes comparison |
| plot_election_summary | 2-panel summary |
| plot_ideological_space | Ideological space scatter |
Opinion Dynamics
| Class | Description |
|---|---|
| OpinionDynamics | Social network opinion evolution |