abcvoting.misc

Miscellaneous functions for committees (i.e., subsets of candidates).

class abcvoting.misc.CandidateSet(candidates=(), num_cand=None)

A set of candidates, that is, a set of positive integers.

Parameters:
candidatesiterable

An iterable of candidates (positive integers).

num_candint, optional

The maximum number of candidates. Used only for checks.

If this num_cand is provided, it is verified that approved does not contain numbers >= num_cand.

Expand for references to abcvoting.misc.CandidateSet

abcvoting.misc

str_with_names(cand_names=None)

Format a CandidateSet, using the names of candidates (instead of indices) if provided.

Parameters:
cand_nameslist of str or str, optional

List of symbolic names for every candidate.

Returns:
str
abcvoting.misc.FLOAT_ISCLOSE_ABS_TOL = 1e-12

The absolute tolerance when comparing floats.

See also: math.isclose().

abcvoting.misc.FLOAT_ISCLOSE_REL_TOL = 1e-12

The relative tolerance when comparing floats.

See also: math.isclose().

abcvoting.misc.binom(n, k)

Compute a binomial coefficient (n choose k).

Parameters:
n, kint

Positive integers.

Returns:
int
abcvoting.misc.compare_list_of_committees(committees1, committees2)

Check whether two lists of committees are equal.

The order of candidates and their multiplicities in these lists are ignored. To be precise, two lists are equal if every committee in list1 is contained in list2 and vice versa. Committees are, as usual, of type CandidateSet (i.e., sets of positive integers).

>>> comm1 = CandidateSet({0, 1, 3})
>>> comm2 = CandidateSet({0, 3, 1})  # the same set as `comm1`
>>> comm3 = CandidateSet({0, 1, 4})
>>> compare_list_of_committees([comm1, comm2, comm3], [comm1, comm3])
True
>>> compare_list_of_committees([comm1, comm3], [comm1])
False
Parameters:
committees1, committees2list of CandidateSet

Two lists of committees.

Returns:
bool

Expand for references to abcvoting.misc.compare_list_of_committees

abcvoting.misc

abcvoting.misc.dominate(profile, committee1, committee2)

Test whether committee committee1 dominates committee committee2.

That is, test whether each voter in the profile has at least as many approved candidates in committee1 as in committee2, and there is at least one voter with strictly more approved candidates in committee1.

Parameters:
profileabcvoting.preferences.Profile

A profile.

committee1, committee2iterable of int

Two committees.

Returns:
bool
abcvoting.misc.hamming(set1, set2)

Hamming distance between sets set1 and set2.

The Hamming distance for sets is the size of their symmetric difference, or, equivalently, the usual Hamming distance when sets are viewed as 0-1-strings.

Parameters:
set1, set2set of int

The two sets for which the Hamming distance is computed.

Returns:
int

The Hamming distance.

abcvoting.misc.header(text, symbol='-')

Format a header for text.

Parameters:
textstr

Header text.

symbolstr

Symbol to be used for the box around the header text; should be exactly 1 character.

Returns:
str
abcvoting.misc.isclose(x, y)

Compare two floats using the abcvoting default values for absolute and relative tolerance.

Parameters:
x, yfloat

Two floats.

Returns:
bool
abcvoting.misc.powerset(iterable, max_size=None)

Yield all possible subsets of the iterable (or all subsets with at most max-size elements).

From: https://docs.python.org/3/library/itertools.html#itertools-recipes

Parameters:
iterableiterable

An iterable.

max_sizeint, optional

Maximum size of the subsets.

Returns:
iterable
abcvoting.misc.sorted_committees(committees)

Sort a list of committees and ensure that committees are sets.

Parameters:
committeesiterable of iterable

An iterable of committees; committees can be sets, tuples, lists, etc.

Returns:
list of CandidateSet

A sorted list of committees.

abcvoting.misc.str_committees_with_header(committees, cand_names=None, winning=False)

Nicely format a list of committees including a header (stating the number of committees).

>>> comm1 = CandidateSet({0, 1, 3})
>>> comm2 = CandidateSet({0, 1, 4})
>>> print(str_committees_with_header([comm1, comm2], winning=True))
2 winning committees:
 {0, 1, 3}
 {0, 1, 4}

>>> print(str_committees_with_header([comm1, comm2], cand_names="abcde"))
2 committees:
 {a, b, d}
 {a, b, e}
Parameters:
committeeslist of iterable of int

A list of committees (set of positive integers).

cand_nameslist of str or str, optional

List of symbolic names for every candidate.

winningbool, optional

Write “winning committee” instead of “committee”.

Returns:
str

Expand for references to abcvoting.misc.str_committees_with_header

abcvoting.misc

abcvoting.misc.str_set_of_candidates(candset, cand_names=None)

Nicely format a set of candidates.

>>> print(str_set_of_candidates({0, 1, 3, 2}))
{0, 1, 2, 3}
>>> print(str_set_of_candidates({0, 3, 1}, cand_names="abcde"))
{a, b, d}
Parameters:
candsetiterable of int

An iteratble of candidates.

cand_nameslist of str or str, optional

List of symbolic names for every candidate.

Returns:
str

Expand for references to abcvoting.misc.str_set_of_candidates

abcvoting.misc

abcvoting.misc.str_sets_of_candidates(sets_of_candidates, cand_names=None)

Nicely format a list of sets of candidates.

>>> comm1 = CandidateSet({0, 1, 3})
>>> comm2 = CandidateSet({0, 1, 4})
>>> print(str_sets_of_candidates([comm1, comm2]))
 {0, 1, 3}
 {0, 1, 4}

>>> print(str_sets_of_candidates([comm1, comm2], cand_names="abcde"))
 {a, b, d}
 {a, b, e}
Parameters:
sets_of_candidateslist of iterable of int

A list of iterables that contain candidates (i.e., non-negative integers).

cand_nameslist of str or str, optional

List of symbolic names for every candidate.

Returns:
str

Expand for references to abcvoting.misc.str_sets_of_candidates

abcvoting.misc

abcvoting.misc.time_it(func)
abcvoting.misc.verify_expected_committees_equals_actual_committees(actual_committees, expected_committees, resolute=False, shortname='Rule')

Verify whether a voting rule returned the correct output. Raises exceptions if not.

Check whether two lists of committees (actual_committees and expected_committees) are equivalent. Raise RuntimeError if not.

Parameters:
actual_committeeslist of CandidateSet

Output of an ABC voting rule.

expected_committeeslist of CandidateSet

Expected output of this voting rule.

resolutebool, default=False

If True, raise RuntimeError if more actual_committees does not have length 1.

shortnamestr, optional

Name of rule used for Exception messages.

Returns:
None