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

  $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.


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.


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.


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.


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.


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.


Defeated, Deferred, Withdrawn, Suspended

Returns a list of choices in that state.


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.


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.


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


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.


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


Resets all Ballots to their initial Vote Value.


Calculate and return the number of seats remaining to fill.



John Karr (BRAINBUZ)


Copyright 2019-2021 by John Karr (BRAINBUZ)


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


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