File Coverage

blib/lib/Vote/Count/Method/CondorcetIRV.pm
Criterion Covered Total %
statement 41 41 100.0
branch 4 4 100.0
condition n/a
subroutine 9 9 100.0
pod 1 1 100.0
total 55 55 100.0


line stmt bran cond sub pod time code
1 3     3   544 use strict;
  3         6  
  3         92  
2 3     3   17 use warnings;
  3         7  
  3         114  
3 3     3   51 use 5.024;
  3         12  
4 3     3   17 use feature qw /postderef signatures/;
  3         7  
  3         263  
5              
6             use namespace::autoclean;
7 3     3   20 use Moose;
  3         7  
  3         20  
8 3     3   266 extends 'Vote::Count';
  3         6  
  3         19  
9             with 'Vote::Count::BottomRunOff';
10              
11             our $VERSION='2.02';
12              
13             =head1 NAME
14              
15             Vote::Count::Method::CondorcetIRV
16              
17             =head1 VERSION 2.02
18              
19             =cut
20              
21             # ABSTRACT: Simple Condorcet IRV Methods.
22              
23             =pod
24              
25             =head1 SYNOPSIS
26              
27             use Vote::Count::Method::CondorcetIRV ;
28              
29             my $Election = Vote::Count::Method::CondorcetIRV->new(
30             'BallotSet' => $someballotset,
31             'TieBreakMethod' => 'precedence', # defaults to all
32             );
33             my $result = $Election->SmithSetIRV() ;
34             say "Winner is: " . $result->{'winner'};
35             say $Election->logv();
36              
37             =head1 Description
38              
39             Provides Common Basic Condorcet-IRV Methods. These methods are simple and beat other Condorcet Methods on Later Harm.
40              
41             =head1 Method Common Names: Smith Set IRV, Smith-IRV
42              
43             Identifies the Smith Set and runs IRV on it.
44              
45             =head2 Function Name: SmithSetIRV
46              
47             SmithSetIRV is exported and requires a Vote::Count object, an optional second argument is an IRV tiebreaker rule name (see IRV module). It will return a hashref similar to RunIRV, in the event of a tie the Vote::Count Object's Active Set will also be the tied choices (available for any later tie breakers you would implement). Events will be logged to the Vote::Count Object.
48              
49             =head2 Criteria
50              
51             =head3 Simplicity
52              
53             SmithSet IRV is easy to understand but requires a full matrix and thus is harder to handcount than Benham or BTR IRV. If it desired to handcount, an aggressive Floor Rule like TCA (see Floor module) is recommended, or an Approval or Top Count Floor of up to 15%. 15% Top Count permits at most 6 choices, but 6 choices still require 15 pairings to complete the Matrix.
54              
55             =head3 Later Harm
56              
57             When there is no Condorcet Winner this method is Later Harm Sufficient. There might be edge cases where IRV's sensitivity to dropping order creates a Later Harm effect, but they should be pretty rare. When there is a Condorcet Winner the effect is the normal one for a Condorcet Method.
58              
59             The easiest way to imagine a case where a choice not in the Smith Set changed the outcome is by cloning the winner, such that there is a choice defeating them in early Top Count but not defeating them. The negative impact of the clone is an established weakness of IRV. It would appear that any possible Later Harm issue in addition to being very much at the edge is more than offset by consistency improvement.
60              
61             Smith Set IRV still inherits the Later Harm failure of requiring a Condorcet Winner, but it has the lowest possible Later Harm effect for a Smith compliant Method. Woodhull and restricting Pairwise Opposition to the Smith Set have equal Later Harm effect to Smith Set IRV.
62              
63             =head3 Condorcet Criteria
64              
65             Meets Condorcer Winner, Condorcet Loser, and Smith.
66              
67             =head3 Consistency
68              
69             By meeting the three Condorcet Criteria a level of consistency is guaranteed. When there is no Condorcet Winner the resolution has all of the weaknesses of IRV, as discussed in the Later Harm topic above restricting IRV to the Smith Set would appear to provide a consistency gain over basic IRV.
70              
71             Smith Set IRV is therefore substantially more consistent than basic IRV, but less consistent than Condorcet methods like SSD that focus on Consistency.
72              
73             =head1 Smith Set Restricted MinMax (Currently Unimplemented, See Vote::Count::Method::MinMax)
74              
75             MinMax methods do not meet the Smith Criteria nor the Condorcet Loser Criteria, two do meet the Condorcet Winner Criteria, and one meets Later Harm. Restricting MinMax to the Smith Set will make all of the sub-methods meet all three Condorcet Criteria; "Opposition" will match the Later Harm protection of Smith Set IRV.
76              
77             =head1 Method Common Name: Woodhull Method (Currently Unimplemented)
78              
79             The Woodhull method is similar to Smith Set IRV. The difference is: instead of eliminating the choices outside the Smith Set, Woodhull does not permit them to win. Since, it has to deal with the situation where an ineligible choice wins via IRV, it becomes slightly more complex. In addition, group elimination of unwinnable choices improves consistency, which is another advantage to Smith Set IRV. As for possible differences in Later Harm effect, the Later Harm comes from the restriction of the victor to the Smith Set, which is the same effect for both methods.
80              
81             The argument in favor of Woodhull over Smith would be that: Anything which alters the dropping order can alter the outcome of IRV, and Woodhull preserves the IRV dropping order. Since, a dropping order change has an equal possiblity of helping or hurting one's preferred choice, this side-effect is a random flaw. Removing the least consequential choices is preventing them from impacting the election (in a random manner), thus this author sees it as an advantage for Smith Set IRV.
82              
83             =head1 Method Common Name: Bottom Two Runoff IRV, BTR IRV
84              
85             This is the simplest modification to IRV which meets the Condorcet Winner Criteria. Instead of eliminating the low choice, the lowest two choices enter a virtual runoff, eliminating the loser. This is the easiest Hand Count Condorcet method, there will always be fewer pairings than choices. This method fails LNH, when there is no Condorcet Winner the LNH impact may substantial since it can come into play for each runoff. BTR IRV will only eliminate a member of the Smith Set when both members of the runoff are in it, it can never eliminate the final member of the Smith Set. BTR IRV meets both Condorcet Criteria and the Smith Criteria.
86              
87             This method is implemented in the Main IRV Role L<Vote::Count::IRV|Vote::Count::IRV/RunBTRIRV>.
88              
89             =head1 Method Common Names: Benham, Benham IRV
90              
91             This method modifies IRV by checking for a Condorcet Winner each round, and then drops the low choice as regular IRV. It is probably the most widely used Condorcet Method for Hand Counting because it does not require a full matrix. For each choice it is only required to determine if they lose to any of the other active choices.
92              
93             This method is implemented by L<Vote::Count::Method::CondorcetDropping|Vote::Count::Method::CondorcetDropping/Benham>.
94              
95             =cut
96              
97             no warnings 'experimental';
98 3     3   21793  
  3         9  
  3         126  
99             use Carp;
100 3     3   18  
  3         10  
  3         1092  
101             my $matrix = $E->PairMatrix();
102 6     6 1 729 $E->logt('SmithSetIRV');
  6         12  
  6         19  
  6         11  
103 6         216 my $winner = $matrix->CondorcetWinner();
104 6         46 if ($winner) {
105 6         36 $E->logv("Condorcet Winner: $winner");
106 6 100       33 return {
107 2         16 'winner' => $winner,
108             'tied' => 0
109 2         24 };
110             }
111             else {
112             my $Smith = $matrix->SmithSet();
113             $E->logv( "Smith Set: " . join( ',', sort( keys $Smith->%* ) ) );
114 4         25 my $IRV = $E->RunIRV( $Smith, $tiebreaker );
115 4         56 unless ( $IRV->{'winner'} ) {
116 4         44 $winner = '';
117 4 100       23 $E->SetActive( { map { $_ => 1 } ( $IRV->{'tied'}->@* ) } );
118 1         3 }
119 1         4 return $IRV;
  2         14  
120             }
121 4         24 }
122              
123             1;
124              
125             #FOOTER
126              
127             =pod
128              
129             BUG TRACKER
130              
131             L<https://github.com/brainbuz/Vote-Count/issues>
132              
133             AUTHOR
134              
135             John Karr (BRAINBUZ) brainbuz@cpan.org
136              
137             CONTRIBUTORS
138              
139             Copyright 2019-2021 by John Karr (BRAINBUZ) brainbuz@cpan.org.
140              
141             LICENSE
142              
143             This module is released under the GNU Public License Version 3. See license file for details. For more information on this license visit L<http://fsf.org>.
144              
145             SUPPORT
146              
147             This software is provided as is, per the terms of the GNU Public License. Professional support and customisation services are available from the author.
148              
149             =cut
150