/* OpenTally: Open-source election vote counting * Copyright © 2021 Lee Yingtong Li (RunasSudo) * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Affero General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Affero General Public License for more details. * * You should have received a copy of the GNU Affero General Public License * along with this program. If not, see . */ use super::{NextPreferencesEntry, NextPreferencesResult, STVError, STVOptions, SumSurplusTransfersMode, SurplusMethod, SurplusOrder}; use crate::election::{Candidate, CountCard, CountState, Parcel, Vote}; use crate::numbers::Number; use itertools::Itertools; use std::cmp::max; use std::ops; /// Distribute the largest surplus according to the Gregory method, based on [STVOptions::surplus] pub fn distribute_surpluses(state: &mut CountState, opts: &STVOptions) -> Result where for<'r> &'r N: ops::Sub<&'r N, Output=N>, for<'r> &'r N: ops::Div<&'r N, Output=N>, for<'r> &'r N: ops::Neg { let quota = state.quota.as_ref().unwrap(); let mut has_surplus: Vec<(&Candidate, &CountCard)> = state.election.candidates.iter() // Present in order in case of tie .map(|c| (c, state.candidates.get(c).unwrap())) .filter(|(_, cc)| &cc.votes > quota) .collect(); let total_surpluses = has_surplus.iter() .fold(N::new(), |acc, (_, cc)| acc + &cc.votes - quota); if !has_surplus.is_empty() { // Determine if surplues can be deferred if opts.defer_surpluses { if super::can_defer_surpluses(state, opts, &total_surpluses) { state.logger.log_literal(format!("Distribution of surpluses totalling {:.dps$} votes will be deferred.", total_surpluses, dps=opts.pp_decimals)); return Ok(false); } } match opts.surplus_order { SurplusOrder::BySize => { // Compare b with a to sort high-low has_surplus.sort_by(|a, b| b.1.votes.cmp(&a.1.votes)); } SurplusOrder::ByOrder => { has_surplus.sort_by(|a, b| a.1.order_elected.cmp(&b.1.order_elected)); } } // Distribute top candidate's surplus let elected_candidate; // Handle ties if has_surplus.len() > 1 && has_surplus[0].1.votes == has_surplus[1].1.votes { let max_votes = &has_surplus[0].1.votes; let has_surplus = has_surplus.into_iter().filter_map(|(c, cc)| if &cc.votes == max_votes { Some(c) } else { None }).collect(); elected_candidate = super::choose_highest(state, opts, has_surplus)?; } else { elected_candidate = has_surplus[0].0; } distribute_surplus(state, &opts, elected_candidate); return Ok(true); } return Ok(false); } /// Return the denominator of the transfer value fn calculate_surplus_denom(surplus: &N, result: &NextPreferencesResult, transferable_votes: &N, weighted: bool, transferable_only: bool) -> Option where for<'r> &'r N: ops::Sub<&'r N, Output=N> { if transferable_only { let total_units = if weighted { &result.total_votes } else { &result.total_ballots }; let exhausted_units = if weighted { &result.exhausted.num_votes } else { &result.exhausted.num_ballots }; let transferable_units = total_units - exhausted_units; if transferable_votes > surplus { return Some(transferable_units); } else { return None; } } else { if weighted { return Some(result.total_votes.clone()); } else { return Some(result.total_ballots.clone()); } } } /// Return the reweighted value of the vote after being transferred fn reweight_vote( num_votes: &N, num_ballots: &N, surplus: &N, weighted: bool, surplus_fraction: &Option, surplus_denom: &Option, round_tvs: Option, rounding: Option) -> N { let mut result; match surplus_denom { Some(v) => { if let Some(_) = round_tvs { // Rounding requested: use the rounded transfer value if weighted { result = num_votes.clone() * surplus_fraction.as_ref().unwrap(); } else { result = num_ballots.clone() * surplus_fraction.as_ref().unwrap(); } } else { // Avoid unnecessary rounding error by first multiplying by the surplus if weighted { result = num_votes.clone() * surplus / v; } else { result = num_ballots.clone() * surplus / v; } } } None => { result = num_votes.clone(); } } // Round down if requested if let Some(dps) = rounding { result.floor_mut(dps); } return result; } /// Compute the number of votes to credit to a continuing candidate during a surplus transfer, based on [STVOptions::sum_surplus_transfers] fn sum_surplus_transfers(entry: &NextPreferencesEntry, surplus: &N, is_weighted: bool, surplus_fraction: &Option, surplus_denom: &Option, _state: &mut CountState, opts: &STVOptions) -> N where for<'r> &'r N: ops::Div<&'r N, Output=N>, { match opts.sum_surplus_transfers { SumSurplusTransfersMode::SingleStep => { // Calculate transfer across all votes //state.logger.log_literal(format!("Transferring {:.0} ballot papers, totalling {:.dps$} votes.", entry.num_ballots, entry.num_votes, dps=opts.pp_decimals)); return reweight_vote(&entry.num_votes, &entry.num_ballots, surplus, is_weighted, surplus_fraction, surplus_denom, opts.round_tvs, opts.round_votes); } SumSurplusTransfersMode::ByValue => { // Sum transfers by value let mut result = N::new(); // Sort into parcels by value let mut votes: Vec<&Vote> = entry.votes.iter().collect(); votes.sort_unstable_by(|a, b| (&a.value / &a.ballot.orig_value).cmp(&(&b.value / &b.ballot.orig_value))); for (_value, parcel) in &votes.into_iter().group_by(|v| &v.value / &v.ballot.orig_value) { let mut num_votes = N::new(); let mut num_ballots = N::new(); for vote in parcel { num_votes += &vote.value; num_ballots += &vote.ballot.orig_value; } //state.logger.log_literal(format!("Transferring {:.0} ballot papers, totalling {:.dps$} votes, received at value {:.dps2$}.", num_ballots, num_votes, value, dps=opts.pp_decimals, dps2=max(opts.pp_decimals, 2))); result += reweight_vote(&num_votes, &num_ballots, surplus, is_weighted, surplus_fraction, surplus_denom, opts.round_tvs, opts.round_votes); } return result; } SumSurplusTransfersMode::PerBallot => { // Sum transfer per each individual ballot // TODO: This could be moved to distribute_surplus to avoid looping over the votes and calculating transfer values twice let mut result = N::new(); for vote in entry.votes.iter() { result += reweight_vote(&vote.value, &vote.ballot.orig_value, surplus, is_weighted, surplus_fraction, surplus_denom, opts.round_tvs, opts.round_votes); } //state.logger.log_literal(format!("Transferring {:.0} ballot papers, totalling {:.dps$} votes.", entry.num_ballots, entry.num_votes, dps=opts.pp_decimals)); return result; } } } /// Distribute the surplus of a given candidate according to the Gregory method, based on [STVOptions::surplus] fn distribute_surplus(state: &mut CountState, opts: &STVOptions, elected_candidate: &Candidate) where for<'r> &'r N: ops::Sub<&'r N, Output=N>, for<'r> &'r N: ops::Div<&'r N, Output=N>, for<'r> &'r N: ops::Neg { state.logger.log_literal(format!("Surplus of {} distributed.", elected_candidate.name)); let count_card = state.candidates.get(elected_candidate).unwrap(); let surplus = &count_card.votes - state.quota.as_ref().unwrap(); let votes; match opts.surplus { SurplusMethod::WIG | SurplusMethod::UIG => { // Inclusive Gregory votes = state.candidates.get(elected_candidate).unwrap().parcels.concat(); } SurplusMethod::EG => { // Exclusive Gregory // Should be safe to unwrap() - or else how did we get a quota! votes = state.candidates.get_mut(elected_candidate).unwrap().parcels.pop().unwrap(); } _ => { panic!("Invalid --surplus for Gregory method"); } } // Count next preferences let result = super::next_preferences(state, votes); state.kind = Some("Surplus of"); state.title = String::from(&elected_candidate.name); // Transfer candidate votes // TODO: Refactor?? let is_weighted = match opts.surplus { SurplusMethod::WIG => { true } SurplusMethod::UIG | SurplusMethod::EG => { false } SurplusMethod::Meek => { todo!() } }; let transferable_votes = &result.total_votes - &result.exhausted.num_votes; let surplus_denom = calculate_surplus_denom(&surplus, &result, &transferable_votes, is_weighted, opts.transferable_only); let mut surplus_fraction; match surplus_denom { Some(ref v) => { surplus_fraction = Some(surplus.clone() / v); // Round down if requested if let Some(dps) = opts.round_tvs { surplus_fraction.as_mut().unwrap().floor_mut(dps); } if opts.transferable_only { state.logger.log_literal(format!("Transferring {:.0} transferable ballots, totalling {:.dps$} transferable votes, with surplus fraction {:.dps2$}.", &result.total_ballots - &result.exhausted.num_ballots, transferable_votes, surplus_fraction.as_ref().unwrap(), dps=opts.pp_decimals, dps2=max(opts.pp_decimals, 2))); } else { state.logger.log_literal(format!("Transferring {:.0} ballots, totalling {:.dps$} votes, with surplus fraction {:.dps2$}.", result.total_ballots, result.total_votes, surplus_fraction.as_ref().unwrap(), dps=opts.pp_decimals, dps2=max(opts.pp_decimals, 2))); } } None => { surplus_fraction = None; if opts.transferable_only { state.logger.log_literal(format!("Transferring {:.0} transferable ballots, totalling {:.dps$} transferable votes, at values received.", &result.total_ballots - &result.exhausted.num_ballots, transferable_votes, dps=opts.pp_decimals)); } else { state.logger.log_literal(format!("Transferring {:.0} ballots, totalling {:.dps$} votes, at values received.", result.total_ballots, result.total_votes, dps=opts.pp_decimals)); } } } let mut checksum = N::new(); for (candidate, entry) in result.candidates.into_iter() { // Credit transferred votes let candidate_transfers = sum_surplus_transfers(&entry, &surplus, is_weighted, &surplus_fraction, &surplus_denom, state, opts); let count_card = state.candidates.get_mut(candidate).unwrap(); count_card.transfer(&candidate_transfers); checksum += candidate_transfers; let mut parcel = entry.votes as Parcel; // Reweight votes for vote in parcel.iter_mut() { vote.value = reweight_vote(&vote.value, &vote.ballot.orig_value, &surplus, is_weighted, &surplus_fraction, &surplus_denom, opts.round_tvs, opts.round_weights); } count_card.parcels.push(parcel); } // Credit exhausted votes let mut exhausted_transfers; if opts.transferable_only { if transferable_votes > surplus { // No ballots exhaust exhausted_transfers = N::new(); } else { exhausted_transfers = &surplus - &transferable_votes; if let Some(dps) = opts.round_votes { exhausted_transfers.floor_mut(dps); } } } else { exhausted_transfers = sum_surplus_transfers(&result.exhausted, &surplus, is_weighted, &surplus_fraction, &surplus_denom, state, opts); } state.exhausted.transfer(&exhausted_transfers); checksum += exhausted_transfers; // Transfer exhausted votes let parcel = result.exhausted.votes as Parcel; state.exhausted.parcels.push(parcel); // Finalise candidate votes let count_card = state.candidates.get_mut(elected_candidate).unwrap(); count_card.transfers = -&surplus; count_card.votes.assign(state.quota.as_ref().unwrap()); checksum -= surplus; // Update loss by fraction state.loss_fraction.transfer(&-checksum); }