pref_voting 1.16.31__py3-none-any.whl

pref_voting/swf_axioms.py

@@ -0,0 +1,173 @@
+"""
+    File: swf_axioms.py
+    Author: Wesley H. Holliday (wesholliday@berkeley.edu) and Eric Pacuit (epacuit@umd.edu)
+    Date: April 29, 2024
+    
+    SWF axioms 
+"""
+
+from pref_voting.axiom import Axiom
+from pref_voting.axiom_helpers import *
+from itertools import permutations
+from pref_voting.helper import weak_orders
+
+def has_pareto_ranking_violation(prof,swf,verbose=False, strong_Pareto=False):
+
+    """Returns True if all voters rank x above y in prof, but the SWF does not rank x above y. 
+    
+    If verbose is True, prints the profile and the violation.
+
+    If strong_Pareto is True, then a violation occurs when all voters weakly prefer x to y, some voter strictly prefers x to y, but the SWF does not rank x above y.
+    
+    Args:
+        prof: a Profile or ProfileWithTies
+        swf (SocialWelfareFunction): An SWF to test.
+        verbose (bool, default=False): If a violation is found, display the violation.
+
+    Returns:
+        Result of the test (bool): Returns True if there is a violation and False otherwise.
+    
+    """
+    social_ranking = swf(prof)
+
+    for x in prof.candidates: 
+        for y in prof.candidates: 
+            if not social_ranking.extended_strict_pref(x,y): 
+                if (strong_Pareto == False and prof.support(x,y)==prof.num_voters) or (strong_Pareto == True and prof.support(x,y)> 0 and prof.support(y,x)==0):
+                    if verbose:  
+                        print(f"Pareto ranking violation by {swf}:")
+                        prof.display()
+                        print(prof.description())
+                        swf.display(prof)
+                        print(f"Candidate {x} Pareto dominates {y} but is not ranked above {y} by {swf}.")
+                        print()
+                    return True
+    return False
+
+def find_all_pareto_ranking_violations(prof,swf,verbose=False, strong_Pareto=False):
+
+    """Returns a list of all pairs of candidates for which the SWF violates the Pareto ranking axiom. 
+    
+    If verbose is True, prints the profile and the violation.
+
+    If strong_Pareto is True, then a violation occurs when all voters weakly prefer x to y, some voter strictly prefers x to y, but the SWF does not rank x above y.
+    
+    Args:
+        prof: a Profile or ProfileWithTies
+        swf (SocialWelfareFunction): An SWF to test.
+        verbose (bool, default=False): If a violation is found, display the violation.
+
+    Returns:
+        List of violations (list): List of all pairs of candidates for which there is a violation.
+    
+    """
+    social_ranking = swf(prof)
+
+    violations = []
+
+    for x in prof.candidates: 
+        for y in prof.candidates: 
+            if not social_ranking.extended_strict_pref(x,y): 
+                if (strong_Pareto == False and prof.support(x,y)==prof.num_voters) or (strong_Pareto == True and prof.support(x,y)> 0 and prof.support(y,x)==0):
+                    if verbose:  
+                        print(f"Pareto ranking violation by {swf}:")
+                        prof.display()
+                        print(prof.description())
+                        swf.display(prof)
+                        print(f"Candidate {x} Pareto dominates {y} but is not ranked above {y} by {swf}.")
+                        print()
+                    violations.append((x,y))
+                    
+    return violations
+
+pareto_ranking = Axiom(
+    "Pareto Ranking",
+    has_violation = has_pareto_ranking_violation,
+    find_all_violations = find_all_pareto_ranking_violations, 
+)
+
+def has_core_support_violation(prof,swf,verbose=False):
+    """Returns True if the swf violates the "core support criterion" of https://arxiv.org/abs/2308.08430 for the given profile, False otherwise. If verbose is True, prints the profile and the core support violation.
+
+    Args:
+        prof: a Profile.
+        swf (SocialWelfareFunction): An SWF to test.
+        verbose (bool, default=False): If a violation is found, display the violation.
+
+    Returns:
+        Result of the test (bool): Returns True if there is a violation and False otherwise.
+    """
+
+    social_ranking = swf(prof)
+
+    for x in prof.candidates:
+        for y in prof.candidates:
+            if social_ranking.extended_strict_pref(x,y):
+
+                maj_cand_for_y = [c for c in prof.candidates if social_ranking.extended_weak_pref(c,y)]
+
+                if isinstance(prof,Profile):
+                    core_support_for_x_vs_y = [r for r in prof.rankings if r.index(x) == 0 or r.index(x) < min([r.index(c) for c in maj_cand_for_y if c != x])]     
+                    core_support_for_y_vs_y = [r for r in prof.rankings if r.index(y) == 0 or r.index(y) < min([r.index(c) for c in maj_cand_for_y if c != y])]
+                    core_support = core_support_for_x_vs_y + core_support_for_y_vs_y
+                    restricted_prof = Profile(core_support)
+
+                if not restricted_prof.majority_prefers(x,y):
+                    if verbose:
+                        print(f"Core support violation by {swf} for {x} relative to {y}:")
+                        print(prof.anonymize())
+                        prof.display_margin_graph()
+                        print("Social ranking:",social_ranking)
+                        print(f"Major candidates relative to {y}:",maj_cand_for_y)
+                        print(f"Profile restricted to voters in core support for {x} relative to {y} and for {y} relative to {y}:")
+                        print(restricted_prof.anonymize())
+                        restricted_prof.display_margin_graph()
+                    return True
+    return False
+
+def find_all_core_support_violations(prof,swf,verbose=False):
+    """Returns a list of all pairs of candidates for which the swf violates the "core support criterion" of https://arxiv.org/abs/2308.08430 for the given profile. If verbose is True, prints the profile and the core support violation.
+
+    Args:
+        prof: a Profile.
+        swf (SocialWelfareFunction): An SWF to test.
+        verbose (bool, default=False): If a violation is found, display the violation.
+
+    Returns:
+        List of violations (list): List of all pairs of candidates for which there is a violation.
+    """
+
+    social_ranking = swf(prof)
+
+    violations = []
+
+    for x in prof.candidates:
+        for y in prof.candidates:
+            if social_ranking.extended_strict_pref(x,y):
+
+                maj_cand_for_y = [c for c in prof.candidates if social_ranking.extended_weak_pref(c,y)]
+
+                if isinstance(prof,Profile):
+                    core_support_for_x_vs_y = [r for r in prof.rankings if r.index(x) == 0 or r.index(x) < min([r.index(c) for c in maj_cand_for_y if c != x])]     
+                    core_support_for_y_vs_y = [r for r in prof.rankings if r.index(y) == 0 or r.index(y) < min([r.index(c) for c in maj_cand_for_y if c != y])]
+                    core_support = core_support_for_x_vs_y + core_support_for_y_vs_y
+                    restricted_prof = Profile(core_support)
+
+                if not restricted_prof.majority_prefers(x,y):
+                    if verbose:
+                        print(f"Core support violation by {swf} for {x} relative to {y}:")
+                        print(prof.anonymize())
+                        prof.display_margin_graph()
+                        print("Social ranking:",social_ranking)
+                        print(f"Major candidates relative to {y}:",maj_cand_for_y)
+                        print(f"Profile restricted to voters in core support for {x} relative to {y} and for {y} relative to {y}:")
+                        print(restricted_prof.anonymize())
+                        restricted_prof.display_margin_graph()
+                    violations.append((x,y))
+    return violations
+
+core_support = Axiom(
+    "Core Support",
+    has_violation = has_core_support_violation,
+    find_all_violations = find_all_core_support_violations, 
+)

pref_voting/utility_functions.py

@@ -0,0 +1,102 @@
+
+import numpy as np
+from scipy.spatial import distance
+from numba import jit, float32 
+
+@jit(nopython=True, fastmath=True)
+def mixed_rm_utility(v_pos: float32[:], c_pos: float32[:], beta = 0.5):
+    """Based on the Rabinowitz and Macdonald (1989) mixed model described on pages 43-44 of "A Unified Theory of Voting" by S. Merrill III and B. Grofman.
+
+    beta = 1 is the proximity quadratic utility function
+    beta = 0 is the RM directional utility function
+
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.
+        beta (float): The beta parameter of the mixed model.
+    
+    Returns:
+        float: The utility of the candidate to the voter.
+    """
+    return 2 * (1-beta) * np.dot(v_pos, c_pos) - beta * np.linalg.norm(v_pos - c_pos) ** 2 
+
+def rm_utility(v_pos: float32[:], c_pos: float32[:]): 
+    """Based on the Rabinowitz and Macdonald (1989) pure directional model. See "A Unified Theory of Voting" by S. Merrill III and B. Grofman, pg. 31.  
+
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.
+
+    Returns:
+        float: The utility of the candidate to the voter.
+    """
+
+    return np.dot(v_pos, c_pos)
+
+def linear_utility(v_pos: float32[:], c_pos: float32[:]):
+    """
+    The utility of the candidate for the voter is negative of the Euclidean distance between the positions. 
+
+    Args:   
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.  
+    Returns:
+        float: The utility of the candidate to the voter.
+    """
+    return -np.linalg.norm(v_pos - c_pos)
+
+def quadratic_utility(v_pos: float32[:], c_pos: float32[:]):
+    """ 
+    The utility of the candidate for the voter is negative of the squared Euclidean distance between the positions. 
+
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.
+    Returns:
+        float: The utility of the candidate to the voter.
+    """
+    return -np.linalg.norm(v_pos - c_pos)**2
+
+
+def city_block_utility(v_pos: float32[:], c_pos: float32[:]):
+    """
+    The utility of the candidate for the voter is the negative of the city-block distance between the positions (also known as the Manhattan distance). 
+
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.
+    Returns:
+        float: The utility of the candidate to the voter.
+    """
+    return -distance.cityblock(v_pos, c_pos)
+
+@jit(nopython=True, fastmath=True)
+def shepsle_utility(v_pos: float32[:], c_pos: float32[:], kappa: float32 = 1):
+    """
+    The Shepsle utility function from "The Strategy of Ambiguity: Uncertainty and Electoral Competition" by Kenneth A. Shepsle, American Political Science Review, 1972, vol. 66, issue 2, pp. 555-568.   For a justification of this utility function, see Appendix B from *Making Multicandidate Elections More Democratic* (https://doi.org/10.1515/9781400859504.114) by S. Merrill III. 
+
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate. 
+        kappa (float): A parameter that determines the steepness of the utility function. 
+    Returns:    
+        float: The utility of the candidate to the voter.      
+    """
+    d = np.linalg.norm(v_pos - c_pos)
+    return np.exp((kappa**2 * -d**2) / 2)
+
+
+@jit(nopython=True, fastmath=True)
+def matthews_utility(v_pos: float32[:], c_pos: float32[:]):
+    """
+    Based on the Matthews directional model.  See "A Unified Theory of Voting" by S. Merrill III and B. Grofman, pg. 26.
+    
+    Args:
+        v_pos (numpy array): The position(s) of the voter.
+        c_pos (numpy array): The position(s) of the candidate.  
+    Returns:    
+        float: The utility of the candidate to the voter.
+        
+    """
+    return np.dot(v_pos, c_pos) / (np.linalg.norm(v_pos) * np.linalg.norm(c_pos))
+

pref_voting/utility_methods.py

@@ -0,0 +1,178 @@
+'''
+    File: utility_methods.py
+    Author: Wes Holliday (wesholliday@berkeley.edu) and Eric Pacuit (epacuit@umd.edu)
+    Date: May 26, 2023
+    
+    Implementations of utility methods. 
+'''
+from pref_voting.voting_method import vm
+from pref_voting.social_welfare_function import swf
+from pref_voting.rankings import  Ranking
+import numpy as np  
+
+@swf(name="Sum Utilitarian")
+def sum_utilitarian_ranking(uprof, curr_cands = None): 
+    """Rank the alternatives according to the sum of the utilities. 
+    Args:
+        uprof (Profile): A Profile object.
+        curr_cands (list): A list of candidates to restrict the ranking to. If ``None``, then the ranking is over the entire domain of the profile.
+    Returns:
+        Ranking: A ranking of the candidates in ``curr_cands`` according to sum of the utilities.
+    """
+
+    curr_cands = curr_cands if curr_cands is not None else uprof.domain
+
+    sums = {c:uprof.util_sum(c) for c in curr_cands}
+    sorted_sums = sorted(list(set(sums.values())), reverse=True)
+    return Ranking({x: uidx+1 for uidx, u in enumerate(sorted_sums) 
+                    for x in curr_cands if sums[x] == u})
+
+@vm(name="Sum Utilitarian")
+def sum_utilitarian(uprof, curr_cands=None): 
+    """
+    Return the winning set of candidates according to sum of the utilities.
+    """
+    return sorted(sum_utilitarian_ranking(uprof, curr_cands=curr_cands).first())
+
+
+@swf(name="Relative Utilitarian")
+def relative_utilitarian_ranking(uprof, curr_cands=None): 
+    """
+    Rank the alternatives according to sum of the normalized utilities. 
+
+    Args:
+        uprof (Profile): A Profile object.
+        curr_cands (list): A list of candidates to restrict the ranking to. If ``None``, then the ranking is over the entire domain of the profile.
+    Returns:
+        Ranking: A ranking of the candidates in ``curr_cands`` according to sum of the normalized utilities.
+
+    .. note::
+        Before restricting to curr_cands, we normalize with respect to *all* alternatives in the domain. 
+    """
+
+    curr_cands = curr_cands if curr_cands is not None else uprof.domain
+
+    rel_utils = [u.normalize_by_range() for u in uprof.utilities]
+    sums = {c:np.sum([u(c) for u in rel_utils if u(c) is not None]) for c in curr_cands}
+    sorted_sums = sorted(list(set(sums.values())), reverse=True)
+    return Ranking({x: uidx+1 for uidx, u in enumerate(sorted_sums) 
+                    for x in curr_cands if sums[x] == u})
+
+@vm(name="Relative Utilitarian")
+def relative_utilitarian(uprof, curr_cands=None): 
+    """
+    Return the winning set of candidates according to sum of the normalized utilities.
+    """
+    return sorted(relative_utilitarian_ranking(uprof, curr_cands=curr_cands).first())
+
+
+@swf(name="Maximin")
+def maximin_ranking(uprof, curr_cands=None): 
+    """
+    Rank the alternatives according to the minimum utility.
+
+    Args:
+        uprof (Profile): A Profile object.
+        curr_cands (list): A list of candidates to restrict the ranking to. If ``None``, then the ranking is over the entire domain of the profile.
+    Returns:    
+        Ranking: A ranking of the candidates in ``curr_cands`` according to minimum utility.
+    """
+    
+    curr_cands = curr_cands if curr_cands is not None else uprof.domain
+
+    min_utils = {x:uprof.util_min(x) for x in curr_cands}
+    sorted_min_utils = sorted(list(set(min_utils.values())), reverse=True)
+    return Ranking({x: midx+1 
+                    for midx, m in enumerate(sorted_min_utils) 
+                    for x in min_utils.keys() if min_utils[x] == m})
+
+@vm(name="Maximin")
+def maximin(uprof, curr_cands=None):
+    """
+    Return the winning set of candidates according to minimum utility.
+    """
+    return sorted(maximin_ranking(uprof, curr_cands=curr_cands).first())
+
+
+@swf(name="Lexicographic Maximin")
+def lexicographic_maximin_ranking(uprof, curr_cands=None): 
+    """
+    Rank the alternatives according to the lexicographic maximin ranking. The lexicographic maximin ranking is the ranking that ranks alternatives according to the minimum utility, and then breaks ties by ranking alternatives according to the second minimum utility, and so on.
+
+    Args:
+        uprof (Profile): A Profile object.
+        curr_cands (list): A list of candidates to restrict the ranking to. If ``None``, then the ranking is over the entire domain of the profile.
+    Returns:
+        Ranking: A ranking of the candidates in ``curr_cands`` according to lexicographic maximin ranking.
+    """
+
+    curr_cands = curr_cands if curr_cands is not None else uprof.domain
+
+    utils = {x: tuple(sorted([u(x) for u in uprof.utilities if u(x) is not None])) for x in curr_cands}
+    assert len(list(set([len(us) for us in utils.values()]))) == 1, "Not all the items have the same number of utilities."
+    sorted_utils = sorted(list(set(utils.values())), reverse=True)
+    return Ranking({x: idx+1 
+                    for idx, us in enumerate(sorted_utils) 
+                    for x in utils.keys() if utils[x] == us})
+
+@vm(name="Lexicographic Maximin")
+def lexicographic_maximin(uprof, curr_cands=None):
+    """
+    Return the winning set of candidates according to lexicographic maximin ranking.
+    """
+    return sorted(lexicographic_maximin_ranking(uprof, curr_cands=curr_cands).first())
+
+
+@swf(name="Nash")
+def nash_ranking(uprof, sq=None, curr_cands=None): 
+    """
+    Rank the alternatives according to the Nash product ranking. Given the status quo ``sq``, the Nash product ranking ranks alternatives according to the product of the utilities of the alternatives minus the utility of the status quo.
+    
+    Args:
+        uprof (Profile): A Profile object.
+        sq (Candidate): The status quo. If ``None``, then the status quo is the first candidate in the domain of the profile.
+        curr_cands (list): A list of candidates to restrict the ranking to. If ``None``, then the ranking is over the entire domain of the profile.
+    Returns:
+        Ranking: A ranking of the candidates in ``curr_cands`` according to Nash product ranking.
+    
+    """
+    
+    assert sq is None or sq in uprof.domain, f"The status quo {sq} must be in the domain of the profile."
+    
+    curr_cands = curr_cands if curr_cands is not None else uprof.domain
+
+    sq = curr_cands[0] if sq is None else sq
+
+    items_to_rank = list(set([x for x in curr_cands if all([u(x) > u(sq) 
+                                                            for u in uprof.utilities])] + [sq]))
+    
+    nash_utils = {x: np.prod([u(x) - u(sq) for u in uprof.utilities]) 
+                  for x in items_to_rank}
+    sorted_nash_utils = sorted(list(set(nash_utils.values())), reverse=True)
+    
+    return Ranking({x: nidx+1 
+                    for nidx, n in enumerate(sorted_nash_utils) 
+                    for x in nash_utils.keys() if nash_utils[x] == n})
+
+@vm(name="Nash")
+def nash(uprof, sq=None, curr_cands=None):
+    """
+    Return the winning set of candidates according to Nash product ranking.
+    """
+    return sorted(nash_ranking(uprof, sq=sq, curr_cands=curr_cands).first())
+
+utilitarian_vms = [
+    sum_utilitarian,
+    relative_utilitarian,
+    maximin,
+    lexicographic_maximin,
+    nash
+]
+
+utilitarian_swfs = [
+    sum_utilitarian_ranking,
+    relative_utilitarian_ranking,
+    maximin_ranking,
+    lexicographic_maximin_ranking,
+   # nash_ranking
+]