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.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