pref_voting 1.16.31__py3-none-any.whl

pref_voting/num_evaluation_method.py

@@ -0,0 +1,77 @@
+'''
+    File: num_evaluation_method.py
+    Author: Wes Holliday (wesholliday@berkeley.edu) and Eric Pacuit (epacuit@umd.edu)
+    Date: June 2, 2024
+    
+    The NumEvaluationMethod class and helper functions for numerical evaluation methods.
+'''
+
+import functools
+import numpy as np
+from pref_voting.mappings import Utility
+from pref_voting.rankings import Ranking
+
+class NumEvaluationMethod(object): 
+    """
+    A class to add functionality to numerical evaluation methods 
+
+    Args:
+        nem (function): An implementation of a numerical evaluation method. The function should accept any type of profile, and a keyword parameter ``curr_cands`` to find the numerical evaluation after restricting to ``curr_cands``. 
+        name (string): The human-readable name of the numerical evaluation function.
+    
+    Returns: 
+        A utility function (Utility) that represents the numerical evaluation of each candidate.
+
+    """
+    def __init__(self, nem, name = None): 
+        
+        self.nem = nem
+        self.name = name
+        functools.update_wrapper(self, nem)   
+
+    def __call__(self, edata, curr_cands = None, **kwargs):
+
+        if (curr_cands is not None and len(curr_cands) == 0) or len(edata.candidates) == 0: 
+            return Utility({})
+        return self.nem(edata, curr_cands = curr_cands, **kwargs)
+        
+    def ranking(self, edata, curr_cands = None, **kwargs): 
+        """
+        Return the ranking generated by the numerical evaluation. 
+        """
+
+        if (curr_cands is not None and len(curr_cands) == 0) or len(edata.candidates) == 0: 
+            return Ranking({})
+        ev =  self.nem(edata, curr_cands = curr_cands, **kwargs)
+        return ev.ranking()
+        
+    def display(self, edata, curr_cands = None, cmap = None, **kwargs): 
+        """
+        Display the winning set of candidates.
+        """
+ 
+        cmap = cmap if cmap is not None else edata.cmap
+
+        ev = self.__call__(edata, curr_cands = curr_cands, **kwargs)
+
+        if ev is None:  # some voting methods may return None if, for instance, it is taking long to compute the winner.
+            print(f"{self.name} numerical evaluation is not available")
+        else: 
+            w_str = f"{self.name} evaluation is " 
+            print(w_str + str(ev))
+        
+    def set_name(self, new_name):
+        """Set the name of the social welfare function."""
+
+        self.name = new_name
+
+    def __str__(self): 
+        return f"{self.name}"
+
+def nem(name = None):
+    """
+    A decorator used when creating a numerical evaluation method. 
+    """
+    def wrapper(f):
+        return NumEvaluationMethod(f, name=name)
+    return wrapper

pref_voting/other_axioms.py

@@ -0,0 +1,161 @@
+"""
+File: other_axioms.py
+Date: April 29 2025
+Authors: Wes Holliday (wesholliday@berkeley.edu) and Eric Pacuit (epacuit@umd.edu)
+
+Other axioms
+---------------------
+"""
+
+from itertools import repeat
+import numpy as np
+
+from pref_voting.axiom import Axiom
+from pref_voting.profiles import Profile
+from pref_voting.profiles_with_ties import ProfileWithTies
+from pref_voting.rankings import Ranking
+
+
+def _reverse_ranking(ballot, all_cands):
+    """
+    Reverse a single ballot, treating *unranked* candidates as
+    tied for last before the reversal.
+
+    Parameters
+    ----------
+    ballot : tuple | Ranking
+        • tuple  – a strict linear order
+        • Ranking – weak order, possibly incomplete
+    all_cands : list | set
+        The full candidate set of the profile.
+    """
+    if isinstance(ballot, tuple):                 
+        return tuple(reversed(ballot))              
+
+    if isinstance(ballot, Ranking):
+        full_rmap = ballot.rmap.copy()
+        if full_rmap:
+            last_rank = max(full_rmap.values()) + 1
+        else:                                        
+            last_rank = 1
+        for c in all_cands:
+            if c not in full_rmap:
+                full_rmap[c] = last_rank
+
+        max_rank = max(full_rmap.values())
+        rev_rmap = {c: max_rank + 1 - k for c, k in full_rmap.items()}
+        return Ranking(rev_rmap)
+
+def _reverse_profile(P):
+    """
+    Build the reversed profile ``Pᵣ``.
+    """
+    all_cands = P.candidates
+    rev_ballots = [_reverse_ranking(b, all_cands) for b in P.rankings]
+
+    if isinstance(P, Profile):
+        return Profile(rev_ballots)
+
+    if isinstance(P, ProfileWithTies):
+        P_r = ProfileWithTies(rev_ballots, candidates=all_cands)
+        if P.using_extended_strict_preference:
+            P_r.use_extended_strict_preference()
+        return P_r
+    
+def _reverse_margin_graph(mg):
+    """
+    Return the *edge-reversed* margin graph.
+
+    All positive-margin edges (u, v, w) become (v, u, w); weights are preserved.
+    """
+    rev_edges = [(v, u, w) for (u, v, w) in mg.edges]
+    return MarginGraph(mg.candidates[:], rev_edges, cmap=mg.cmap)
+
+def has_reversal_symmetry_violation(edata, vm, verbose=False):
+    """
+    Returns True iff ``vm`` violates reversal symmetry on *edata*.
+
+    Reversal Symmetry states that if x is a **unique** winner in ``edata``, 
+    then x should not be among the winners in the reversal of ``edata``.
+    """
+
+    if len(edata.candidates) <= 1:
+        return False
+
+    if isinstance(edata, MarginGraph):
+        mg = edata
+        winners = vm(mg)
+        if len(winners) != 1:
+            return False
+
+        x = winners[0]
+        mg_r = _reverse_margin_graph(mg)
+        rev_winners = vm(mg_r)
+
+        if x in rev_winners:
+            if verbose:
+                print(f"Reversal-symmetry violation for {vm.name} on a MarginGraph")
+                print(f"Unique winner {x} also wins after edge reversal.")
+                print("\nOriginal margin graph:")
+                mg.display()
+                print(mg.description())
+                vm.display(mg)
+                print('\nReversed margin graph:')
+                mg_r.display()
+                print(mg_r.description())
+                vm.display(mg_r)
+
+            return True
+        return False
+
+    winners = vm(edata)
+    if isinstance(winners, np.ndarray):
+        winners = winners.tolist()
+    if len(winners) != 1:
+        return False
+
+    x = winners[0]
+    P_r = _reverse_profile(edata)
+    rev_winners = vm(P_r)
+    if isinstance(rev_winners, np.ndarray):
+        rev_winners = rev_winners.tolist()
+
+    if x in rev_winners:
+        if verbose:
+            print(f"Reversal-symmetry violation for {vm.name}")
+            print(f"Unique winner {x} also wins after reversal.")
+            print("\nOriginal profile:")
+            edata.display()
+            print(edata.description())
+            vm.display(edata)
+            print("\nReversed profile:")
+            P_r.display()
+            print(P_r.description())
+            vm.display(P_r)
+        return True
+    return False
+
+
+def find_all_reversal_symmetry_violations(edata, vm, verbose=False):
+    """
+    Returns a one-item list [(unique_winner, winners_after_reversal)] describing the violation on *edata*, or [].
+    """
+    if not has_reversal_symmetry_violation(edata, vm, verbose):
+        return []
+
+    winners = vm(edata)
+    winners = winners.tolist() if isinstance(winners, np.ndarray) else winners
+    if isinstance(edata, MarginGraph):
+        rev_winners = vm(_reverse_margin_graph(edata))
+    else:
+        rev_winners = vm(_reverse_profile(edata))
+
+    rev_winners = rev_winners.tolist() if isinstance(rev_winners, np.ndarray) else rev_winners
+    return [(winners, rev_winners)]
+
+
+reversal_symmetry = Axiom(
+    "Reversal Symmetry",
+    has_violation=has_reversal_symmetry_violation,
+    find_all_violations=find_all_reversal_symmetry_violations,
+)