Rules module

Rules module#

Proportional Approval Voting#

Compute the selections of the Proportional Approval Voting (PAV) rule via Integer Linear Programming (ILP). The ILP is solved with the pulp package.

The definition of the PAV rule for the trichotomous context is taken from Section 3.3 of Proportionality in Thumbs Up and Down Voting (Kraiczy, Papasotiropoulos, Pierczyński and Skowron, 2025).

param profile:

The trichotomous profile.

type profile:

AbstractTrichotomousProfile

param max_size_selection:

Maximum number of alternatives to select.

type max_size_selection:

int

param initial_selection:

An initial partial selection fixing some alternatives as selected or rejected. If implicit_reject is True in the initial selection, no alternatives are fixed to be rejected. Defaults to None.

type initial_selection:

Selection, optional

param resoluteness:

If True, returns a single optimal selection (resolute). If False, returns all tied optimal selections (irresolute). Defaults to True.

type resoluteness:

bool, optional

param verbose:

If True, enables ILP solver output. Defaults to False.

type verbose:

bool, optional

param max_seconds:

Time limit in seconds for the ILP solver. Defaults to 600.

type max_seconds:

int, optional

returns:

The selection if resolute (resoluteness == True), or a list of selections if irresolute (resoluteness == False).

rtype:

Selection | list[Selection]

proportional_approval_voting(profile: AbstractTrichotomousProfile, max_size_selection: int, initial_selection: Selection | None = None, resoluteness: bool = True, verbose: bool = False, max_seconds: int = 600) → Selection | list[Selection][source]#

Compute the selections of the Proportional Approval Voting (PAV) rule via Integer Linear Programming (ILP). The ILP is solved with the pulp package.

The definition of the PAV rule for the trichotomous context is taken from Section 3.3 of Proportionality in Thumbs Up and Down Voting (Kraiczy, Papasotiropoulos, Pierczyński and Skowron, 2025).

Parameters:

  • profile (AbstractTrichotomousProfile) – The trichotomous profile.

  • max_size_selection (int) – Maximum number of alternatives to select.

  • initial_selection (Selection, optional) – An initial partial selection fixing some alternatives as selected or rejected. If implicit_reject is True in the initial selection, no alternatives are fixed to be rejected. Defaults to None.

  • resoluteness (bool, optional) – If True, returns a single optimal selection (resolute). If False, returns all tied optimal selections (irresolute). Defaults to True.

  • verbose (bool, optional) – If True, enables ILP solver output. Defaults to False.

  • max_seconds (int, optional) – Time limit in seconds for the ILP solver. Defaults to 600.

Returns:

The selection if resolute (resoluteness == True), or a list of selections if irresolute (resoluteness == False).

Return type:

Selection | list[Selection]

Sequential Phragmén’s Rule#

sequential_phragmen(profile: AbstractTrichotomousProfile, max_size_selection: int, initial_loads: list[int | float | mpq] | None = None, initial_selection: Selection | None = None, tie_breaking: TieBreakingRule | None = None, resoluteness: bool = True) → Selection | list[Selection][source]#

Compute the selections of the sequential Phragmén’s rule.

The definition of the sequential Phragmén’s rule for the trichotomous context is taken from Section 3.2 of Proportionality in Thumbs Up and Down Voting (Kraiczy, Papasotiropoulos, Pierczyński and Skowron, 2025).

Parameters:

  • profile (AbstractTrichotomousProfile) – The trichotomous profile.

  • max_size_selection (int) – Maximum number of alternatives to select.

  • initial_loads (list of Numeric, optional) – Initial loads for each ballot in the profile. Defaults to zero for all ballots.

  • initial_selection (Selection, optional) – An initial selection that fixes some alternatives as selected or rejected. If implicit_reject is True, no alternatives are fixed to be rejected.

  • tie_breaking (TieBreakingRule, optional) – Tie-breaking rule used when multiple alternatives tie. Defaults to lexicographic tie-breaking.

  • resoluteness (bool, optional) – If True, returns a single selection (resolute). If False, returns all tied optimal selections (irresolute). Defaults to True.

Returns:

The selection if resolute (resoluteness == True), or a list of selections if irresolute (resoluteness == False).

Return type:

Selection | list[Selection]

Tax-Based Rules#

tax_pb_instance(profile: AbstractTrichotomousProfile, max_size_selection: int, initial_selection: Selection | None = None) → tuple[Instance, ApprovalMultiProfile, dict[Project, Alternative]][source]#

Construct a Participatory Budgeting (PB) instance and PB profile from a trichotomous profile.

This function translates the trichotomous voting profile into a PB instance, setting project costs inversely proportional to net support.

Parameters:

  • profile (AbstractTrichotomousProfile) – The trichotomous profile.

  • max_size_selection (int) – The budget limit or maximum number of alternatives to be selected.

  • initial_selection (Selection or None, optional) – An initial selection fixing some alternatives as selected or rejected.

Returns:

  • pb_election.Instance – The generated PB instance containing projects.

  • pb_election.ApprovalMultiProfile – The PB profile created from approval ballots derived from the trichotomous profile.

  • dict – A mapping from PB projects back to the original alternatives.

tax_pb_rule_scheme(profile: AbstractTrichotomousProfile, max_size_selection: int, pb_rule: Callable, initial_selection: Selection | None = None, tie_breaking: TieBreakingRule | None = None, resoluteness: bool = True, pb_rule_kwargs: dict = None) → Selection | list[Selection][source]#

Apply a participatory budgeting rule to a trichotomous profile by translating it into a suitable PB instance with opposition tax.

This function converts the given profile into a PB instance and profile, applies the specified PB rule using pabutools, and converts the results back.

The taxed PB rule scheme has been defined in Section 4.2 of Proportionality in Thumbs Up and Down Voting (Kraiczy, Papasotiropoulos, Pierczyński and Skowron, 2025).

Parameters:

  • profile (AbstractTrichotomousProfile) – The trichotomous profile.

  • max_size_selection (int) – The maximum number of alternatives allowed in the selection.

  • pb_rule (callable) – The participatory budgeting rule function to apply.

  • initial_selection (Selection or None, optional) – An initial selection fixing some alternatives as selected or rejected.

  • tie_breaking (TieBreakingRule or None, optional) – Tie-breaking rule used for resolving ties. Defaults to lexicographic tie-breaking if None.

  • resoluteness (bool, optional) – Whether to return a single resolute selection (True) or all tied selections (False). Defaults to True.

  • pb_rule_kwargs (dict, optional) – Additional keyword arguments passed to the PB rule.

Returns:

The resulting selection(s) after applying the PB rule.

Return type:

Selection or list of Selection

tax_method_of_equal_shares(profile: AbstractTrichotomousProfile, max_size_selection: int, initial_selection: Selection | None = None, tie_breaking: TieBreakingRule | None = None, resoluteness: bool = True) → Selection | list[Selection][source]#

Apply the Tax method of equal shares to a trichotomous profile.

This method uses participatory budgeting rules to compute proportional selections with the method of equal shares adapted for approval-disapproval profiles.

Parameters:

  • profile (AbstractTrichotomousProfile) – The input profile.

  • max_size_selection (int) – The maximum number of alternatives to select.

  • initial_selection (Selection or None, optional) – Initial fixed selection state.

  • tie_breaking (TieBreakingRule or None, optional) – Tie-breaking rule. Defaults to lexicographic.

  • resoluteness (bool, optional) – Whether to return a single or multiple tied selections.

Returns:

The selection if resolute (resoluteness == True), or a list of selections if irresolute (resoluteness == False).

Return type:

Selection | list[Selection]

tax_sequential_phragmen(profile: AbstractTrichotomousProfile, max_size_selection: int, initial_selection: Selection | None = None, tie_breaking: TieBreakingRule | None = None, resoluteness: bool = True) → Selection | list[Selection][source]#

Apply Tax sequential Phragmén method on a trichotomous profile.

This rule transforms the profile into a participatory budgeting instance and applies sequential Phragmén via pabutools.

Parameters:

  • profile (AbstractTrichotomousProfile) – The input voting profile.

  • max_size_selection (int) – The maximum size of the selection.

  • initial_selection (Selection or None, optional) – Initial fixed selections.

  • tie_breaking (TieBreakingRule or None, optional) – Tie-breaking rule, defaulting to lexicographic.

  • resoluteness (bool, optional) – Whether to return one selection or all tied selections.

Returns:

The selection if resolute (resoluteness == True), or a list of selections if irresolute (resoluteness == False).

Return type:

Selection | list[Selection]

Contents