The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Vote-Count-2.03
River stage zero No dependents
1 ++
/ Vote::Count::Charge

CountAbandoned

NAME

Vote::Count::Charge

VERSION 2.02

SYNOPSIS

  my $E = Vote::Count::Charge->new(
    Seats => 3,
    VoteValue => 1000,
    BallotSet => read_ballots('t/data/data1.txt', ) );

  $E->Elect('SOMECHOICE');
  $E->Charge('SOMECHOICE', $quota, $perCharge );
  say E->GetChoiceStatus( 'CARAMEL'),
   >  { state => 'withdrawn', votes => 0 }

Vote Charge implementation of Surplus Transfer

Vote Charge is how Vote::Count implements Surplus Transfer. The wording is chosen to make the concept more accessible to a general audience. It also uses integer math and imposes truncation as the rounding rule.

Vote Charge describes the process of Single Transferable Vote as:

The Votes are assigned a value, based on the number of seats and the total value of all of the votes, a cost is determined for electing a choice. The votes supporting that choice are then charged to pay that cost. The remainder of the value for the vote, if any, is available for the next highest choice of the vote.

When value is transferred back to the vote, Vote Charge refers to it as a Rebate.

Vote Charge uses integer math and truncates all remainders. Setting the Vote Value is equivalent to setting a number of decimal places, a Vote Value of 100,000 is the same as a 5 decimal place precision.

Description

This module provides methods that can be shared between Charge implementations and does not present a complete tool for conducting STV elections. Look at the Methods that have been implemented as part of Vote::Count.

Candidate / Choices States

Single Transferable Vote rules have more states than Active, Eliminated and Elected. Not all methods need all of the possible states. The SetChoiceStatus method is not linked to the underlying Vote::Count objects Active Set, the action methods: Elect, Defeat, Suspend, Defer, Reinstate, Withdraw do update the Active Set.

Active choices are referred to as Hopeful. The normal methods for accessing the Active list are available. Although not prevented from doing so, STV Methods should not directly set the active list, but rely on methods that manipulate candidate state. The VCUpdateActive method will sync the Active set with the STV choice states corresponding to active.

  • hopeful: The default active state of a choice.

  • withdrawn: A choice that will be treated as not present.

  • defeated: A choice that will no longer be considered for election.

  • deferred and suspended:

    A choice that is temporarily removed from consideration. Suspended is treated the same as Defeated, but is eligible for reinstatement. Deferred is removed from the ActiveSet, but treated as present when calculating Quota and Non-Continuing Votes.

  • elected and pending:

    Elected and Pending choices are removed from the Active Set, but Pending choices are not yet considered elected. The Pending state is available to hold newly elected choices for a method that will not immediately complete processing their election.

GetChoiceStatus

When called with the argument of a Choice, returns a hashref with the keys 'state' and 'votes'. When called without argument returns a hashref with the Choices as keys, and the values a hashref with the 'state' and 'votes' keys.

SetChoiceStatus

Takes the arguments of a Choice and a hashref with the keys 'state' and 'votes'. This method does not keep the underlying active list in Sync. Use either the targeted methods such as Suspend and Defeat or use VCUpdateActive to force the update.

VCUpdateActive

Update the ActiveSet of the underlying Vote::Count object to match the set of Choices that are currently 'hopeful'.

Elected and Pending

In addition to Elected, there is a Pending State. Pending means a Choice has reached the Quota, but not completed its Charges and Rebates. The distinction is for the benefit of methods that need choices held in pending, both Pending and Elected choices are removed from the active set.

Elect, Elected

Set Choice as Elected. Elected returns the list of currently elected choices.

Pending

Takes an Choice to set as Pending. Returns the list of Pending Choices.

Eliminated: Withdrawn, Defeated, or Suspended

In methods that set the Quota only once, choices eliminated before setting Quota are Withdrawn and may result in null ballots that can be exluded. Choices eliminated after setting Quota are Defeated. Some rules bring eliminated Choices back in later Rounds, Suspended distinguishes those eligible to return.

Defeat, Defer, Withdraw, Suspend

Perform the corresponding action for a Choice.

  $Election->Defeat('MARMALADE');

Defeated, Deferred, Withdrawn, Suspended

Returns a list of choices in that state.

Reinstate

Will reinstate all currently suspended choices or may be given a list of suspended choices that will be reinstated.

STVRound, NextSTVRound

STVRound returns the current Round, NextSTVRound advances the Round Counter and returns the new Round number.

STVEvent

Takes a reference as argument to add that reference to an Event History. This needs to be done seperately from logx because STVEvent holds a list of data references instead of readably formatted events.

WriteSTVEvent

Writes JSON and YAML logs (path based on LogTo) of the STVEvents.

SetQuota

Calculate the Hare or Droop Quota. After the Division the result is rounded down and 1 is added to the result. The default is the Droop Quota, but either 'hare' or 'droop' may be requested as an optional parameter.

  my $droopquota = $Election->SetQuota();
  my $harequota = $Election->SetQuota('hare');

The Hare formula is Active Votes divided by number of Seats. Droop adds 1 to the number of seats, and to the result after rounding, resulting in a lower quota. The Droop Quota is the smallest for which it is impossible for more choices than the number of seats to reach the quota.

Charge

Charges Ballots for election of choice, parameters are $choice, $quota and $charge (defaults to VoteValue ).

ResetVoteValue

Resets all Ballots to their initial Vote Value.

SeatsOpen

Calculate and return the number of seats remaining to fill.

BUG TRACKER

https://github.com/brainbuz/Vote-Count/issues

AUTHOR

John Karr (BRAINBUZ) brainbuz@cpan.org

CONTRIBUTORS

Copyright 2019-2021 by John Karr (BRAINBUZ) brainbuz@cpan.org.

LICENSE

This module is released under the GNU Public License Version 3. See license file for details. For more information on this license visit http://fsf.org.

SUPPORT

This software is provided as is, per the terms of the GNU Public License. Professional support and customisation services are available from the author.