kingmaker 0.1.0

A modular, performant, social choice framework for the simulation, computation, and analysis of strategic voting.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

use std::sync::Arc;

use rand::distr::weighted::WeightedIndex;
use rand::prelude::*;

use crate::core::{Ballot, Candidate, Preference, Tactic};
use crate::tactics::Identity;

use crate::core::Profile;

/// A bloc of voters, e.g. democrats / republicans or rural / suburban / urban.
///
/// A bloc of voters is considered to have a single aggregate preference and set of tactics. They represent the sum total distribution across all the voters in the bloc. When a voter draws from this distribution, that is the expression of their preferences / individuality.
#[derive(Debug)]
pub struct VotingBloc<B: Ballot> {
    /// The preference of the voting bloc
    preference: Arc<dyn Preference<B>>,
    /// The strategy of the voting bloc
    strategy: Vec<(Arc<dyn Tactic<B>>, f32)>,
    /// The number of members in the voting bloc
    members: usize,
}

impl<B: Ballot> VotingBloc<B> {
    /// Build a new voting bloc with the builder
    pub fn builder(
        preference: impl Preference<B> + 'static,
        members: usize,
    ) -> VotingBlocBuilder<B> {
        VotingBlocBuilder::new(preference, members)
    }
    /// Create a new voting bloc
    fn new(
        preference: Arc<dyn Preference<B>>,
        strategy: Vec<(Arc<dyn Tactic<B>>, f32)>,
        members: usize,
    ) -> Self {
        Self {
            preference,
            strategy,
            members,
        }
    }
    /// Get the preferences of the voting bloc
    #[must_use]
    pub fn preferences(&self) -> Arc<dyn Preference<B>> {
        self.preference.clone()
    }
    /// Get the preferences of the voting bloc
    #[must_use]
    pub fn strategy(&self) -> &[(Arc<dyn Tactic<B>>, f32)] {
        &self.strategy
    }
    /// Get the # of members in the voting bloc
    #[must_use]
    pub const fn members(&self) -> usize {
        self.members
    }
    /// Realize preferences to a profile
    pub fn realize(&self, candidates: &[Candidate], rng: &mut StdRng) -> Profile<B> {
        (0..self.members())
            .map(|_| self.preferences().draw(candidates, rng))
            .collect()
    }
    /// Realize preferences to a profile and apply strategy to them.
    ///
    /// In other words, make the voting bloc vote.
    ///
    /// # Panics
    ///
    /// Panics if the weights are not valid.
    pub fn vote(&self, candidates: &[Candidate], rng: &mut StdRng) -> Profile<B> {
        let weights: Vec<f32> = self.strategy.iter().map(|(_, weight)| *weight).collect();
        let dist = WeightedIndex::new(&weights).expect("Weights should be valid");
        (0..self.members())
            .map(|_| {
                let honest_ballot = self.preferences().draw(candidates, rng);
                let tactic = &self.strategy[dist.sample(rng)].0;
                tactic.apply(honest_ballot)
            })
            .collect()
    }
}

pub struct VotingBlocBuilder<B: Ballot> {
    preference: Arc<dyn Preference<B>>,
    strategy: Vec<(Arc<dyn Tactic<B>>, f32)>,
    members: usize,
}

impl<B: Ballot> VotingBlocBuilder<B> {
    /// Create a new voting bloc builder
    pub fn new(preference: impl Preference<B> + 'static, members: usize) -> Self {
        Self {
            preference: Arc::new(preference),
            strategy: Vec::new(),
            members,
        }
    }
    /// Add a tactic to the voting bloc
    pub fn add_tactic(mut self, tactic: impl Tactic<B> + 'static, weight: f32) -> Self {
        self.strategy.push((Arc::new(tactic), weight));
        self
    }
    /// Build the voting bloc
    pub fn build(mut self) -> VotingBloc<B> {
        if self.strategy.is_empty() {
            self.strategy.push((Arc::new(Identity), 1.0f32));
        }
        VotingBloc::new(self.preference, self.strategy, self.members)
    }
}