<no title>

class svvamp.Rule(with_two_candidates_reduces_to_plurality=False, is_based_on_rk=False, is_based_on_ut_minus1_1=False, meets_iia=False, precheck_um=True, precheck_tm=True, precheck_icm=True, log_identity='RULE', **kwargs)[source]

A voting rule.

Parameters:

with_two_candidates_reduces_to_plurality (bool) – True iff, when using this voting system with only two candidates, it amounts to Plurality (with voter and candidate tie-breaking).
is_based_on_rk (bool) – True iff this voting system is based only on strict rankings (no cardinal information, indifference not allowed).
is_based_on_ut_minus1_1 (bool) –
True iff:
- This voting system is based only on utilities (not rankings, i.e. does not depend on how voters break ties in their own preferences),
- And for a c-manipulator (IM or CM), it is optimal to pretend that c has utility 1 and other candidates have utility -1.
meets_iia (bool) – True iff this voting system meets Independence of Irrelevant Alternatives.
precheck_um (bool) – If True, then before computing CM, we check whether there is UM.
precheck_tm (bool) – If True, then before computing CM, we check whether there is TM.
precheck_icm (bool) – If True, then before computing CM, we check whether there is ICM. Remark: when the voting system meets InfMC_c_ctb, then precheck on ICM will not do better than other basic prechecks.
log_identity (str) – Cf. MyLog.
kwargs – Additional keyword parameters. See options_parameters for allowed and default options.

Notes

This is an ‘abstract’ class. As an end-user, you should always use its subclasses RuleApproval, RulePlurality, etc.

This class and its subclasses are suitable for voting rules that are deterministic and anonymous (treating all voters equally). As a consequence, they are not neutral (because they need to break ties in totally symmetric situations). As of now, SVVAMP does not support other kinds of voting systems.

Ties in a voter’s utilities

When a sincere voter v must provide a strict order in a specific voting system, she uses preferences_rk[v, :] (which breaks possible ties in her utilities).

In contrast, to know if a voter v wants to manipulate for a candidate c against w, we always use her utilities preferences_ut[v, :]. If she attributes the same utility to w and c, she is not interested in this manipulation.

Some ordinal voting systems in SVVAMP may be adapted to accept weak orders of preferences as ballots. This is future work.

Ties in the result of an election

The voting system itself may need to break ties, for example if candidates c and d have the same score in a score-based system. The standard tie-breaking in SVVAMP, referred to as Candidate Tie-Breaking (CTB), consists of breaking ties by lowest index: c is favored over d if c < d. This tie-breaking rule is used for example in ‘A note on manipulability of large voting schemes’ (Peleg, 1979). Future voting rules implemented as a subclass of Rule may use another tie-breaking rule.

Options for manipulation

Attributes allow to choose the algorithm used to compute different kinds of manipulation: cm_option, icm_option, im_option, tm_option and um_option.

To know what options are accepted for a given voting system, use options_parameters. Here is a non-exhaustive list of typical values for these options.

'exact': Exact algorithm. Can always decide manipulation: it answers True or False. Other algorithms may also answer numpy.nan, which is the SVVAMP convention meaning that the algorithm was not able to decide. For a given voting system, if the exact algorithm runs in polynomial time, then it is the only accepted option.

'slow': Non-polynomial algorithm, but not exact. For voting systems accepting this option, it is however faster than ‘exact’ (in a little-o sense) and more precise than ‘fast’.

'fast': Polynomial algorithm, not exact. If the exact algorithm runs in polynomial time, this option is not available.

'lazy': Perform only some preliminary checks. Run in polynomial time (unless deciding the winner of the election is not polynomial, like for Kemeny). Like other non-exact algorithms, it can decide manipulation to True, False or return numpy.nan (undecided).

For a given voting system, the default option is the most precise algorithm running in polynomial time.

Option for Independence of Irrelevant Alternatives (IIA)

The default algorithm for not_iia first performs some preliminary checks based on the known properties of the voting system under study. For example, if it meets the Condorcet criterion, then the algorithm exploits if. If it meets the majority favorite criterion (see below) and if w_ is a majority favorite, then it decides IIA immediately.

If the preliminary checks do not allow to decide, the default algorithm then uses brute force to test subsets of candidates including the sincere winner w_. This can be non-polynomial or non-exact, depending on the attribute iia_subset_maximum_size.

Implication diagram between criteria

Cf. corresponding attributes below for the definition of these criteria. See Durand et al., ‘Condorcet Criterion and Reduction in Coalitional Manipulability’.

Condorcet_c_ut_rel_ctb            ==>            Condorcet_c_ut_rel
||             Condorcet_c_rk_ctb ==>      Condorcet_c_rk       ||
||           ||        ||                   ||         ||       ||
V            V         ||                   ||         V        V
Condorcet_c_ut_abs_ctb            ==>            Condorcet_c_ut_abs
||                     ||                   ||                  ||
||                     V                    V                   ||
||     majority_favorite_c_rk_ctb ==> majority_favorite_c_rk    ||
||            ||                                  ||            ||
V             V                                   V             V
majority_favorite_c_ut_ctb        ==>        majority_favorite_ut_c
||                                                              ||
V                                                               V
IgnMC_c_ctb                       ==>                       IgnMC_c
||                                                              ||
V                                                               V
InfMC_c_ctb                       ==>                       InfMC_c

property ballots_

Ballots cast by the voters.

Default type: 2d array of integers. Default behavior: ballots[v, k] = preferences_rk[v, k].

property c_has_supporters_: 1d array of booleans. c_has_supporters_[c] is True iff at least one voter prefers candidate c to the sincere winner w_.

property candidates_by_scores_best_to_worst_

1d array of integers. All candidates, sorted from the winner to the last candidate in the election’s result.

Default behavior: candidates_by_scores_best_to_worst[k] is the candidate with k-th highest value in scores_. By definition, candidates_by_scores_best_to_worst[0] = w_.

property candidates_cm_: 1d array of booleans (or numpy.nan). candidates_cm_[c] is True if CM for candidate c is possible, False otherwise. If the algorithm cannot decide, then numpy.nan. For the sincere winner w_, we have by convention candidates_cm_[w_] = False.

property candidates_icm_: 1d array of booleans (or numpy.nan). candidates_icm_[c] is True if ICM for candidate c is possible, False otherwise. If the algorithm cannot decide, then numpy.nan. For the sincere winner w_, we have by convention candidates_icm[w_] = False.

property candidates_im_: 1d array of booleans (or numpy.nan). candidates_im[c] is True if there exists a voter who can manipulate for candidate c, False otherwise. If the algorithm cannot decide, then numpy.nan. For the sincere winner w_, we have by convention candidates_im_[w_] = False.

property candidates_tm_: 1d array of booleans (or numpy.nan). candidates_tm[c] is True if a TM for candidate c is possible, False otherwise. If the algorithm cannot decide, then numpy.nan (but as of now, this value is not never for TM). For the sincere winner w_, we have by convention candidates_tm[w] = False.

property candidates_um_: 1d array of booleans (or numpy.nan). candidates_um_[c] is True if UM for candidate c is possible, False otherwise. If the algorithm cannot decide, then numpy.nan. For the sincere winner w_, we have by convention candidates_um_[w_] = False.

classmethod check_option_allowed(option, value)[source]

Check whether a pair (option, value) is allowed.

Parameters:

option (str) –
value (object) –

Examples

Raise an error if the option is not in options_parameters:

>>> Rule.check_option_allowed('not_existing_option', 42)
Traceback (most recent call last):
ValueError: Option 'not_existing_option' is unknown for Rule.

Raise an error if the value is not authorized for this option:

>>> Rule.check_option_allowed('cm_option', 'unexpected_value')
Traceback (most recent call last):
ValueError: 'cm_option' = 'unexpected_value' is not allowed in Rule.

property cm_option

String. Option used to compute is_cm_() and related methods.

To know what options are accepted for a given voting system, use options_parameters.

property cm_power_index_: CM power index. For each candidate c != w, it is n_s / x_c (where n_s is the number of sincere voters and x_c the minimal number of manipulators that can make c win (cf necessary_coalition_size_cm_). Globally, it is the max over the candidates c != w.

demo_manipulation_(log_depth=1)[source]

Demonstrate the manipulation methods of Rule class.

Parameters:: log_depth (int) – Integer from 0 (basic info) to 3 (verbose).

demo_profile_(log_depth=1)[source]

Demonstrate the attributes of the loaded profile.

Parameters:: log_depth (int) – Integer from 0 (basic info) to 3 (verbose).

demo_results_(log_depth=1)[source]

Demonstrate the methods related to the result of the election (without manipulation).

Parameters:: log_depth (int) – Integer from 0 (basic info) to 3 (verbose).

property elects_condorcet_winner_rk_even_with_cm_

True iff there is a Condorcet winner, she is elected by sincere voting and it is not CM.

Type:: bool

property example_subset_iia_: 1d array of booleans. If the election is not IIA, example_subset_iia provides a subset of candidates breaking IIA. example_subset_iia[c] is True iff candidate c belongs to the subset. If the election is IIA (or if the algorithm cannot decide), then example_subset_iia = numpy.nan.

property example_winner_iia_: Integer (candidate). If the election is not IIA, example_winner_iia is the winner corresponding to the counter-example example_subset_iia. If the election is IIA (or if the algorithm cannot decide), then example_winner_iia = numpy.nan.

property icm_option

String. Option used to compute is_icm_() and related methods.

To know what options are accepted for a given voting system, use options_parameters.

property iia_subset_maximum_size: Float or numpy.inf. Maximum size of any subset of candidates that is used to compute not_iia() (and related methods). For a given voting system, this attribute has no effect if there is an exact algorithm running in polynomial time implemented in SVVAMP.

property im_option

String. Option used to compute is_im_() and related methods.

To know what options are accepted for a given voting system, use options_parameters.

property is_cm_

Boolean (or numpy.nan). True if a CM is possible, False otherwise. If the algorithm cannot decide, then numpy.nan.

We say that a situation is Coalitionally Manipulable (CM) for c != w_ iff voters who prefer c to w_ can cast ballots so that c is elected (while other voters still vote sincerely).

is_cm_c_(c)[source]

Coalition Manipulation, focus on one candidate.

Parameters:: c (int) – Candidate.
Returns:: candidates_cm[c].
Return type:: bool or nan

is_cm_c_with_bounds_(c)[source]

Coalition Manipulation, focus on one candidate, with bounds.

Parameters:: c (int) – Candidate.
Returns:: (candidates_cm[c], necessary_coalition_size_cm[c], sufficient_coalition_size_cm[c]).
Return type:: tuple

property is_icm_

Boolean (or numpy.nan). True if an ICM is possible, False otherwise. If the algorithm cannot decide, then numpy.nan.

We say that a situation is Ignorant-Coalition Manipulable (ICM) for c != w_ iff the voters who prefer c to w_ can cast ballots so that, whatever the other voters do, c is elected.

is_icm_c_(c)[source]

Ignorant-Coalition Manipulation, focus on one candidate.

Parameters:: c (int) – Candidate.
Returns:: candidates_icm[c]_.
Return type:: bool or nan

is_icm_c_with_bounds_(c)[source]

Ignorant-Coalition Manipulation, focus on one candidate, with bounds.

Parameters:: c (int) – Candidate.
Returns:: (candidates_icm_[c], necessary_coalition_size_icm_[c], sufficient_coalition_size_icm_[c]).
Return type:: tuple

property is_iia_: Boolean. Cf. is_not_iia.

property is_im_

Boolean. True if there exists a voter who can and wants to manipulate, False otherwise. If the algorithm cannot decide, then numpy.nan.

Voter v can and wants to manipulate for candidate c iff:

v strictly prefers c to w_ (in the sense of preferences_ut).

And by changing her vote, she can make c win instead of w_.

is_im_c_(c)[source]

Individual manipulation, focus on one candidate.

Parameters:: c (int) – Candidate.
Returns:: candidates_im[c].
Return type:: bool or nan

is_im_c_with_voters_(c)[source]

Individual manipulation, focus on one candidate, with details.

Parameters:: c (int) – Candidate.
Returns:: (candidates_im[c], v_im_for_c[:, c]).
Return type:: tuple

is_im_v_(v)[source]

Individual manipulation, focus on one voter.

Parameters:: v (int) – Voter.
Returns:: voters_im[v].
Return type:: bool or nan

is_im_v_with_candidates_(v)[source]

Individual manipulation, focus on one voter, with details.

Parameters:: v (int) – Voter.
Returns:: (voters_im[v], v_im_for_c[v, :]).
Return type:: tuple

property is_not_iia_: Boolean. True if there exists a subset of candidates including the sincere winner w_, such that if the election is held with this subset of candidates, then w_ is not the winner anymore. If the algorithm cannot decide, then the result is numpy.nan.

property is_tm_

Boolean (or numpy.nan). True if TM is possible, False otherwise. If the algorithm cannot decide, then numpy.nan (but as of now, this value is never used for TM).

For ordinal voting systems, we call trivial manipulation for candidate c against w_ the fact of putting c on top (compromising), w_ at the bottom (burying), while keeping a sincere order on the other candidates.

For cardinal voting systems, we call trivial manipulation for c (against w_) the fact of putting the maximum grade for c and the minimum grade for the other candidates.

In both cases, the intuitive idea is the following: if I want to make c win and I only know that candidate w_ is ‘dangerous’ (but I know nothing else), then trivial manipulation is my ‘best’ strategy.

We say that a situation is trivially manipulable for c (implicitly: coalitionally) iff, when all voters preferring c to the sincere winner w_ use trivial manipulation, candidate c wins.

is_tm_c_(c)[source]

Trivial manipulation, focus on one candidate.

Parameters:: c (int) – Candidate.
Returns:: candidates_tm[c].
Return type:: bool or nan

property is_um_

Boolean (or numpy.nan). True if UM is possible, False otherwise. If the algorithm cannot decide, then numpy.nan.

We say that a situation is unison-manipulable for a candidate c != w_ iff all voters who prefer c to the sincere winner w_ can cast the same ballot so that c is elected (while other voters still vote sincerely).

is_um_c_(c)[source]

Unison manipulation, focus on one candidate.

Parameters:: c (int) – Candidate.
Returns:: candidates_um[c]
Return type:: bool or nan

log_(method_name)[source]

Log corresponding to a particular manipulation method.

Examples

>>> rule = Rule()
>>> rule.log_('whatever_iia_whatever')
'iia_subset_maximum_size = 2.0'
>>> rule.log_('whatever_im_whatever')
'im_option = lazy'
>>> rule.log_('whatever_icm_whatever')
'icm_option = lazy'
>>> rule.log_('whatever_tm_whatever')
'tm_option = exact'
>>> rule.log_('whatever_um_whatever')
'um_option = lazy'
>>> rule.log_('whatever_cm_whatever')
'cm_option = lazy, um_option = lazy, icm_option = lazy, tm_option = exact'

property log_cm_: String. Parameters used to compute is_cm_() and related methods.

property log_icm_: String. Parameters used to compute is_icm_() and related methods.

property log_iia_: String. Parameters used to compute is_not_iia_() and related methods.

property log_im_: String. Parameters used to compute is_im_() and related methods.

property log_tm_: String. Parameters used to compute is_tm_() and related methods.

property log_um_: String. Parameters used to compute is_um_() and related methods.

property losing_candidates_

1d of Integers. List of losing candidates, in a decreasing order of (heuristic) dangerousness

This attribute is mostly intended for SVVAMP developers. It is used in most manipulation algorithms. The idea is to try first the candidates for whom we think manipulation is more likely to succeed, in order to gain time.

Losing candidates are sorted from the ‘most dangerous’ to the ‘least dangerous’ (for the sincere winner w_). By default, they are sorted by their score against w_ in the matrix_duels_ut (which is the number of potential manipulators for a given candidate). This behavior can be redefined in the subclass implementing a specific voting system.

property mean_utility_w_: Float. The mean utility for the sincere winner w_.

property meets_condorcet_c_rk

Boolean. True iff the voting system meets the Condorcet criterion (rk). I.e. if a candidate is a condorcet_winner_rk, then she wins.

Is implied by: meets_condorcet_c_rk_ctb.

Implies: meets_condorcet_c_ut_abs, meets_majority_favorite_c_rk.

property meets_condorcet_c_rk_ctb

if a candidate is a condorcet_winner_rk_ctb, she wins.

Implies: meets_condorcet_c_rk, meets_condorcet_c_ut_abs_ctb, meets_majority_favorite_c_rk_ctb.

Type:: Boolean. True iff the voting system meets the ‘Condorcet criterion (rk) with ctb’. I.e.

property meets_condorcet_c_ut_abs

Boolean. True iff the voting system meets the absolute Condorcet criterion. I.e. if a candidate is a condorcet_winner_ut_abs, then she wins.

Is implied by: meets_condorcet_c_rk, meets_condorcet_c_ut_rel, meets_condorcet_c_ut_abs_ctb.

Implies: meets_majority_favorite_c_ut.

property meets_condorcet_c_ut_abs_ctb

if a candidate is a condorcet_winner_ut_abs_ctb, she wins.

Is implied by: meets_condorcet_c_rk_ctb, meets_condorcet_c_ut_rel_ctb.

Implies: meets_condorcet_c_ut_abs, meets_majority_favorite_c_ut_ctb.

Type:: Boolean. True iff the voting system meets the ‘absolute Condorcet criterion with ctb’. I.e.

property meets_condorcet_c_ut_rel

Boolean. True iff the voting system meets the relative Condorcet criterion. I.e. if a candidate is a condorcet_winner_ut_rel, then she wins.

Is implied by: meets_condorcet_c_ut_rel_ctb.

Implies: meets_condorcet_c_ut_abs.

property meets_condorcet_c_ut_rel_ctb

if a candidate is a condorcet_winner_ut_rel_ctb, she wins.

Implies: meets_condorcet_c_ut_rel, meets_condorcet_c_ut_abs_ctb.

Type:: Boolean. True iff the voting system meets the ‘relative Condorcet criterion with ctb’. I.e.

property meets_ignmc_c

Boolean. True iff the voting system meets the ignorant majority coalition criterion. I.e. any ignorant coalition of size strictly more than n_v/2 can make any candidate win. See Durand et al.: ‘Condorcet Criterion and Reduction in Coalitional Manipulability’.

Ignorant means that they can choose their ballot without knowing what other voters will do.

Is implied by: meets_majority_favorite_c_ut, meets_IgnMC_c_ctb.

Implies: meets_InfMC_c.

property meets_ignmc_c_ctb

Boolean. True iff the voting system meets the ‘ignorant majority coalition criterion with ctb’. I.e.:

It meets_IgnMC_c,

And any ignorant coalition of size n_v/2 can make candidate 0 win.

Is implied by: meets_majority_favorite_c_ut_ctb.

Implies: meets_InfMC_c_ctb, meets_IgnMC_c.

property meets_infmc_c

Boolean. True iff the voting system meets the informed majority coalition criterion. I.e. any informed coalition of size strictly more than n_v/2 can make any candidate win. See Durand et al.: ‘Condorcet Criterion and Reduction in Coalitional Manipulability’.

Informed means that they know other voters’ ballots before choosing their own.

Is implied by: meets_IgnMC_c, meets_InfMC_c_ctb.

property meets_infmc_c_ctb

Boolean. True iff the voting system meets the ‘informed majority coalition criterion with ctb’. I.e.:

It meets_InfMC_c,

And any informed coalition of size n_v/2 can make candidate 0 win.

Is implied by: meets_IgnMC_c_ctb.

Implies: meets_InfMC_c.

property meets_majority_favorite_c_rk

Boolean. True iff the voting system meets the majority favorite criterion (rk). I.e. if strictly more than n_v/2 voters rank a candidate first (rk), then she wins.

Is implied by: meets_condorcet_c_rk, meets_majority_favorite_c_rk_ctb.

Implies: _meets_majority_favorite_c_ut.

property meets_majority_favorite_c_rk_ctb

Boolean. True iff the voting system meets the ‘majority favorite criterion (rk) with ctb’. I.e.:

It meets_majority_favorite_c_rk,

And if n_v/2 voters rank candidate 0 first (rk), she wins.

Is implied by: meets_condorcet_c_rk_ctb.

Implies: meets_majority_favorite_c_ut_ctb, meets_majority_favorite_c_rk.

property meets_majority_favorite_c_ut

Boolean. True iff the voting system meets the majority favorite criterion (ut). I.e. if strictly more than n_v/2 voters strictly prefer a candidate to all others (ut), she wins.

Is implied by: meets_condorcet_c_ut_abs, meets_majority_favorite_c_ut_ctb, meets_majority_favorite_c_rk.

Implies: meets_IgnMC_c.

property meets_majority_favorite_c_ut_ctb

Boolean. True iff the voting system meets the ‘majority favorite criterion (ut) with ctb’. I.e.:

It meets_majority_favorite_c_ut,

And if n_v/2 voters strictly prefer candidate 0 to all other candidates, she wins.

Is implied by: meets_condorcet_c_ut_abs_ctb, meets_majority_favorite_c_rk_ctb.

Implies: meets_IgnMC_c_ctb, meets_majority_favorite_c_ut.

property nb_candidates_cm_: Number of candidates who can benefit from CM.

property necessary_coalition_size_cm_

1d array of integers. necessary_coalition_size_cm_[c] is the lower bound found by the algorithm for \(x_c\) (cf. below). For the sincere winner w_, we have by convention necessary_coalition_size_cm_[w_] = 0.

Internally, to decide the problem of CM, SVVAMP studies the following question. When considering the sub-population of voters who do not prefer c to w_ (sincere voters), what is the minimal number \(x_c\) of c-manipulators needed to perform CM? For all voting system currently implemented in SVVAMP, it means that CM is possible iff there are \(x_c\) voters or more who prefer c to w_. (A sufficient condition on the voting system is that, if a population elects c, then an additional voter may always cast a ballot so that c stays elected)

For information only, the result of SVVAMP’s computations about \(x_c\) is given in outputs necessary_coalition_size_cm_ and sufficient_coalition_size_cm_. By definition, we have necessary_coalition_size_cm_[c] \(\leq x_c \leq\) sufficient_coalition_size_cm_[c].

When cm_option = 'exact', the exactness concerns the CM decision problems (Boolean results), not the numerical evaluation of \(x_c\). It means that for all Boolean answers, SVVAMP will not answer numpy.nan ( undecided). But it is possible that necessary_coalition_size_cm_[c] < sufficient_coalition_size_cm_[c].

property necessary_coalition_size_icm_

1d array of integers. necessary_coalition_size_icm[c] is the lower bound found by the algorithm for \(x_c\) (see below). For the sincere winner w_, we have by convention necessary_coalition_size_icm_[w_] = 0.

Internally, to decide the problem of ICM, SVVAMP studies the following question. When considering the sub-population of voters who do not prefer c to w_ (sincere voters), what is the minimal number \(x_c\) of c-manipulators needed to perform ICM? For all voting system currently implemented in SVVAMP, it means that ICM is possible iff there are \(x_c\) voters or more who prefer c to w_.

For information only, the result of SVVAMP’s computations about \(x_c\) is given in outputs necessary_coalition_size_icm_ and sufficient_coalition_size_icm_. By definition, we have necessary_coalition_size_icm_[c] \(\leq x_c \leq\) sufficient_coalition_size_icm_[c].

When icm_option = 'exact', the exactness concerns the ICM decision problems (boolean results below), but not the numerical evaluation of \(x_c\). It means that for all boolean answers, SVVAMP will not answer numpy.nan ( undecided). But it is possible that necessary_coalition_size_icm_[c] < sufficient_coalition_size_icm_[c].

property options

name of the option. Value: value of the option.

Type:: dict
Type:: The options. Key

options_parameters = {'cm_option': {'allowed': ['lazy', 'exact'], 'default': 'lazy'}, 'icm_option': {'allowed': ['lazy'], 'default': 'lazy'}, 'iia_subset_maximum_size': {'allowed': <function is_number>, 'default': 2}, 'im_option': {'allowed': ['lazy', 'exact'], 'default': 'lazy'}, 'tm_option': {'allowed': ['lazy', 'exact'], 'default': 'exact'}, 'um_option': {'allowed': ['lazy', 'exact'], 'default': 'lazy'}}

Options parameters. It is a dictionary of allowed and default options. Allowed is a minimal check that will be performed before launching big simulations, but other checks might be performed when setting the option. Allowed is either a list of values, like [‘lazy’, ‘fast’, ‘exact’], or a function checking if the parameter is correct. Example: {'max_grade': dict(allowed=np.isfinite, default=1), 'option_example': dict(allowed=[42, 51], default=42)}.

Type:: dict

property relative_social_welfare_w_: Float. The relative social welfare for the sincere winner w_.

property score_w_

Score of the sincere winner.

Default type: number or 1d array.

Default behavior:

If scores_ is a 1d array, then score_w_ is w_’s numerical score.
If scores_ is a 2d array, then score_w_ is w_’s score vector: score_w_ = scores_[:, w_].

property scores_

Scores of the candidates in the election.

See specific documentation for each voting rule. Typical type in most subclasses: 1d or 2d array. Typical behavior in most subclasses:

If scores_ is a 1d array, then scores_[c] is the numerical score for candidate c.
If scores_ is a 2d array, then scores_[:, c] is the score vector for candidate c.

It is not mandatory to follow this behavior.

property scores_best_to_worst_

Scores of the candidates, from the winner to the last candidate of the election.

Default type: 1d or 2d array.

Default behavior: scores_best_to_worst_ is derived from scores_ and candidates_by_scores_best_to_worst_.

If scores_ is a 1d array, then so is scores_best_to_worst_. It is defined by scores_best_to_worst_ = scores_[candidates_by_scores_best_to_worst_]. Then by definition, scores_best_to_worst_[0] = score_w_.

If scores_ is a 2d array, then so is scores_best_to_worst_. It is defined by scores_best_to_worst_ = scores_[:, candidates_by_scores_best_to_worst_]. Then by definition, scores_best_to_worst_[:, 0] = score_w_.

property sufficient_coalition_size_cm_: 1d array of integers or numpy.inf. sufficient_coalition_size_cm_[c] is the upper bound found by the algorithm for \(x_c\) (cf. necessary_coalition_size_cm_). For the sincere winner w_, we have by convention sufficient_coalition_size_cm_[w_] = 0.

property sufficient_coalition_size_icm_: 1d of integers or numpy.inf. sufficient_coalition_size_icm[c] is the upper bound found by the algorithm for \(x_c\) (see necessary_coalition_size_icm_()). For the sincere winner w_, we have by convention sufficient_coalition_size_icm_[w_] = 0.

property tm_option

String. Option used to compute is_tm_() and related methods.

To know what options are accepted for a given voting system, use options_parameters.

property total_utility_w_: Float. The total utility for the sincere winner w_.

property um_option

String. Option used to compute is_um_() and related methods.

To know what options are accepted for a given voting system, use options_parameters.

update_options(options)[source]

Update options.

For example, instead of rule.cm_option='exact', you can write rule.update_options{'cm_option': 'exact'}.

Parameters:: options (dict) – Key: option name. Value: option value.

property v_im_for_c_: 2d array of booleans. v_im_for_c_[v, c] is True if voter v can manipulate for candidate c, False otherwise. If the algorithm cannot decide, then numpy.nan. For the sincere winner :attr:w_`, we have by convention v_im_for_c_[v, w_] = False.

property v_might_im_for_c_

2d array of booleans. `

v_might_im_for_c_[v, c]` is True unless it is clearly and easily excluded that v has an individual manipulation in favor of c. Typically, if v is not pivotal (at all), then it is False. Specific implementations of this function in subclasses can also test if v is interested in manipulating for c, but it is not mandatory.

A non-trivial redefinition of this function is useful for voting systems where computing IM is costly. For voting systems where it is cheap, it it not worth the effort.

property v_wants_to_help_c_: 2d array of booleans. v_wants_to_help_c[v, c] is True iff voter v strictly prefers candidate c to the sincere winner w_. If v attributes the same utility to c and w_, then v is not interested.

property voters_im_: 1d array of booleans (or numpy.nan). voters_im_[v] is True if voter v can and wants to manipulate for at least one candidate, False otherwise. If the algorithm cannot decide, then numpy.nan.

property w_

Integer (winning candidate).

Default behavior: the candidate with highest value in vector scores_ is declared the winner. In case of a tie, the tied candidate with lowest index wins.

property w_is_condorcet_admissible_: Boolean. True iff the sincere winner w_ is Condorcet-admissible. Cf. condorcet_admissible_candidates.

property w_is_condorcet_winner_rk_: Boolean. True iff the sincere winner w_ is a condorcet_winner_rk.

property w_is_condorcet_winner_rk_ctb_: Boolean. True iff the sincere winner w_ is a condorcet_winner_rk_ctb.

property w_is_condorcet_winner_ut_abs_: Boolean. True iff the sincere winner w_ is a condorcet_winner_ut_abs.

property w_is_condorcet_winner_ut_abs_ctb_: Boolean. True iff the sincere winner w_ is a condorcet_winner_ut_abs_ctb.

property w_is_condorcet_winner_ut_rel_: Boolean. True iff the sincere winner w_ is a condorcet_winner_ut_rel.

property w_is_condorcet_winner_ut_rel_ctb_: Boolean. True iff the sincere winner w_ is a condorcet_winner_ut_abs_ctb.

property w_is_not_condorcet_admissible_: Boolean. True iff the sincere winner w_ is not a Condorcet-admissible candidate (whether some exist or not). Cf. condorcet_admissible_candidates.

property w_is_not_condorcet_winner_rk_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_rk (whether one exists or not).

property w_is_not_condorcet_winner_rk_ctb_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_rk_ctb (whether one exists or not).

property w_is_not_condorcet_winner_ut_abs_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_ut_abs (whether one exists or not).

property w_is_not_condorcet_winner_ut_abs_ctb_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_ut_abs_ctb (whether one exists or not).

property w_is_not_condorcet_winner_ut_rel_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_ut_rel (whether one exists or not).

property w_is_not_condorcet_winner_ut_rel_ctb_: Boolean. True iff the sincere winner w_ is not a condorcet_winner_ut_abs_ctb (whether one exists or not).

property w_is_not_resistant_condorcet_winner_: Boolean. True iff the sincere winner w_ is not a resistant_condorcet_winner (whether one exists or not).

property w_is_not_weak_condorcet_winner_: Boolean. True iff the sincere winner w_ is not a Weak Condorcet winner (whether some exist or not). Cf. weak_condorcet_winners.

property w_is_resistant_condorcet_winner_: Boolean. True iff the sincere winner w_ is a resistant_condorcet_winner.

property w_is_weak_condorcet_winner_: Boolean. True iff the sincere winner w_ is a Weak Condorcet winner. Cf. weak_condorcet_winners.

property w_missed_condorcet_admissible_: Boolean. True iff the sincere winner w_ is not a Condorcet-admissible candidate, despite the fact that at least one exists. Cf. condorcet_admissible_candidates.

property w_missed_condorcet_winner_rk_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_rk, despite the fact that she exists.

property w_missed_condorcet_winner_rk_ctb_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_rk_ctb, despite the fact that she exists.

property w_missed_condorcet_winner_ut_abs_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_ut_abs, despite the fact that she exists.

property w_missed_condorcet_winner_ut_abs_ctb_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_ut_abs_ctb, despite the fact that she exists.

property w_missed_condorcet_winner_ut_rel_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_ut_rel, despite the fact that she exists.

property w_missed_condorcet_winner_ut_rel_ctb_: Boolean. True iff the sincere winner w_ is not the condorcet_winner_ut_abs_ctb, despite the fact that she exists.

property w_missed_resistant_condorcet_winner_: Boolean. True iff the sincere winner w_ is not the resistant_condorcet_winner, despite the fact that she exists.

property w_missed_weak_condorcet_winner_: Boolean. True iff the sincere winner w_ is not a Weak Condorcet winner, despite the fact that at least one exists. Cf. weak_condorcet_winners.

property worst_relative_welfare_with_cm_: Worst relative social welfare (sincere winner or candidate who can benefit from CM).