OpenTally/docs/options.md

Options and advanced options

Preset

The preset dropdown allows you to choose from a hardcoded list of preloaded STV counting rules. These are:

Method	Description	Exceptions	Validated against
OpenTally WIGM	Recommended set of simple STV rules designed for computer counting, using the weighted inclusive Gregory method and rational arithmetic.
Scottish STV	Rules from the Scottish Local Government Elections Order 2011, using the weighted inclusive Gregory method.		2007 Linn ward local election (eSTV 2.0.16)
Meek STV	Advanced STV rules designed for computer counting, recognised by the Proportional Representation Society of Australia (Victoria–Tasmania) as the superior STV system.
• OpenTally Meek	Recommended rules for Meek STV. Operates according to the original 1987 Hill–Wichmann–Woodall ‘Algorithm 123’ specification (The Computer Journal 1987;30(3):277–81), except that (a) ties are broken backwards then at random, (b) fixed-point arithmetic with 5 decimal places is used, and (c) candidates are elected on strictly exceeding the quota.		Ballot papers derived from the ERS97 model election (Algorithm 123)
• Meek STV (2006)	Operates according to Hill's 2006 revisions (Voting Matters 2006;(22):7–10). This is the algorithm referred to in OpenSTV/OpaVote as ‘Meek STV’, and forms the basis of New Zealand's Meek STV rules.	[E1]	Ballot papers derived from the ERS97 model election (OpenSTV 1.7)
• Meek STV (New Zealand)	Operates according to Schedule 1A of the Local Electoral Regulations 2001.	[E1]	Ballot papers derived from the ERS97 model election (OpenSTV 1.7, Hill's nzmeek 6.7.7)
Australian Senate STV	Rules from the Commonwealth Electoral Act 1918, using the unweighted inclusive Gregory method.	[E2] [E3]	2019 Tasmanian Senate election (AEC EasyCount)
Western Australia STV	Rules from the Electoral Act 1907 (WA), using the weighted inclusive Gregory method.	[E2] [E3]
Australian Capital Territory STV	Rules from the Electoral Act 1992 (ACT), using the exclusive Gregory method.		2020 Kurrajong territory election (eVACS 2016)
Wright STV	Rules proposed by Anthony van der Craats designed for computer counting, involving reset and re-iteration of the count after each candidate exclusion.		EVE Online CSM 15 election (EVE reference implementation)
PRSA 1977	Simple rules designed for hand counting, using the exclusive Gregory method, with counting performed in thousandths of a vote.		Example 1 of the PRSA's Proportional Representation Manual
ERS97	More complex rules designed for hand counting, using the exclusive Gregory method.		Ballot papers derived from the ERS97 model election
• ERS76	Former rules from the 1976 2nd edition.	[E4]
• ERS73	Former rules from the 1973 1st edition.	[E4]
Church of England	Rules from the Church of England Single Transferable Vote Rules 2020, similar to ERS73.

Exceptions:

• [E1] When generating random numbers, OpenTally uses a deterministic random number generator based on SHA-256, rather than the Wichmann–Hill(-based) algorithm.
• [E2] When breaking ties forwards/backwards, OpenTally selects the candidate who had more/fewer votes at the first/last stage when any tied candidate had more/fewer votes than the others, rather than the method described in the legislation (when each all had unequal votes). The OpenTally developers regard the method described in the legislation as a defect. For an independent discussion, see Conway et al.
• [E3] A tie between 2 candidates for the final vacancy will be broken backwards then at random, rather than the method described in the legislation.
• [E4] The quota is always calculated to 2 decimal places. For full ERS76 (ERS73) compliance, set Round quota to 0 d.p. when the quota is more than 100 (100 or more).

This functionality is not available on the command line.

Quota-related options

Quota (-q/--quota)

The quota dropdowns allow you to define the quota used in the election, and the quota criterion used to elect candidates. The quota may be set to:

• Droop and Droop (exact): V/(S+1)
• Hare and Hare (exact): V/S

where V is the number of votes and S is the number of seats.

The ‘(exact)’ version of each quota has effect only if Round quota to [n] d.p. is enabled. When that setting is enabled, Droop and Hare will increment the quota up to the next available rounded unit (even if the quotient is exact already), while the ‘(exact)’ versions will round the quota up if and only if the quotient is not already exact.

When Round quota to [n] d.p. is not enabled, Droop (or Droop (exact)) is also known as the Newland–Britton or Hagenbach-Bischoff quota.

Quota criterion (-c/--quota-criterion)

The quota criterion may be set to >= (candidates are elected if they meet or exceed the quota) or > (candidates are elected only if they strictly exceed the quota).

Note that the combination ‘>= Droop (exact)’ (with Round quota to [n] d.p. enabled) can result in more candidates meeting the quota than there are available vacancies, hence this particular combination is not recommended.

Quota mode (--quota-mode)

This option allows you to specify whether the votes required for election can change during the count. The options are:

• Static quota: The quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count.
• Static with ERS97 rules: The quota is static, but candidates may be elected if their vote exceeds (or equals, according to the Quota criterion) the total active vote, divided by (S + 1) (or S, according to the Quota option).

When Surplus method is set to Meek method, this setting is ignored, and the progressively reducing quota of the Meek method is instead applied.

STV variants

Surplus order (--surplus-order)

This dropdown allows you to select in what order surpluses are distributed:

• By size (default): When multiple candidates exceed the quota, the largest surplus is transferred (even if it arose at a later stage of the count).
• By order: When multiple candidates exceed the quota, the surplus of the candidate elected first is transferred (even if it is smaller than another). Candidates are always declared elected in descending order of number of votes.

Some STV counting rules provide, for example, that ‘no surplus shall be transferred before a surplus that arose earlier in the counting whether larger or not’ (PRSA 1977). In this case, the option ‘By order’ should be selected.

Surplus method (-s/--surplus)

This dropdown allows you to select how ballots are transferred during surplus transfers. The recommended methods are:

• Weighted inclusive Gregory (default): During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are weighted according to the weights of the ballot papers.
• Meek method: Transfers are computed as described at http://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf.

Other methods are supported, but not recommended:

• Unweighted inclusive Gregory: During surplus transfers, all applicable ballot papers of the transferring candidate are examined. Transfers are not weighted, and each ballot paper has equal value in the calculation.
• Exclusive Gregory (last bundle): During surplus transfers, only the ballot papers received in the last transfer are examined. Transfers are not weighted.

Other surplus transfer methods, such as non-fractional transfers (e.g. random sample) are not supported at this time.

Papers to examine in surplus transfer (--transferable-only)

• Include non-transferable papers (default): When this option is selected, all ballot papers of the transferring candidate are examined. Non-transferable papers are always exhausted at the relevant surplus fractions.
• Use transferable papers only (CLI: --transferable-only): When this option is selected, only transferable papers of the transferring candidate are examined. Non-transferable papers are exhausted only if the value of the transferable papers is less than the surplus.

Exclusion method (--exclusion)

• Single stage (default): When excluding candidate(s), transfer all their ballot papers in one stage.
• By value: When excluding candidate(s), transfer their ballot papers in descending order of accumulated transfer value. Each transfer of all ballots of a certain transfer value forms a separate stage, i.e. if a transfer allows another candidate to meet the quota criterion, no further papers are transferred to that candidate.
• By source: When excluding candidate(s), transfer their ballot papers according to the candidate from which those papers were received, in the order received, i.e. in the order the transferring candidates were elected or excluded. Each transfer of all ballots received from a certain candidate forms a separate stage.
• By parcel (by order): When excluding a candidate, transfer their ballot papers one parcel at a time, in the order each was received. Each parcel forms a separate stage. This option cannot be combined with bulk exclusion.
• Wright method (re-iterate): When excluding candidate(s), reset the count from the distribution of first preferences, disregarding the excluded candidates.

When Surplus method is set to Meek method, this setting is ignored, and the Meek method is instead applied.

(Meek) NZ-style exclusion (--meek-nz-exclusion)

When Surplus method is set to Meek method, this option controls how candidate keep values are updated when candidates are excluded:

• When NZ-style exclusion is disabled (default), the excluded candidate's keep value is immediately reduced to 0. This is the method specified in the 1987 and 2006 Meek rules.
• When NZ-style exclusion is enabled, all elected candidates' keep values are first updated by one further iteration; only then is the excluded candidate's keep value reduced to 0. This is the method specified in the New Zealand Local Electoral Regulations 2001.

Ties (-t/--ties)

This dropdown allows you to select how ties (in surplus transfer or exclusion) are broken. The options are:

• Backwards: Ties are broken according to which tied candidate had the most/fewest votes at the end of the most recent stage where one tied candidate had more/fewer votes than the others, if such a stage exists.
• Fowards: Ties are broken according to which tied candidate had the most/fewest votes at the end of the earliest stage where one tied candidate had more/fewer votes than the others, if such a stage exists. This is also known as the ‘ahead at first difference’ method.
• Random: Ties are broken at random (see Random seed).
• Prompt: The user is prompted to break the tie.

Multiple tie breaking methods can be specified. If the first method cannot resolve the tie, the next is tried, and so on. In the web application, 4 options are available (‘Backwards then random’, ‘Forwards then random’, ‘Random’ and ‘Prompt’). On the command line, the --ties option can take multiple arguments (e.g. --ties backwards random).

Random seed (--random-seed)

This option allows you to input an arbitrary value to seed the deterministic random number generator used to break ties when Ties is set to Random. When the same seed value is used, ties will always be broken in the same way, allowing the breaking of ties to be independently verified.

The default value is the current date, formatted YYYYMMDD.

The algorithm used by the random number generator is specified at rng.md.

Constraints (--constraints)

This file selector allows you to load a CON file specifying constraints on the election. For example, if a certain minimum or maximum number of candidates can be elected from a particular category.

OpenTally applies constraints using the Grey–Fitzgerald method. Whenever a candidate is declared elected or excluded, any candidate who must be elected to secure a conformant result is deemed guarded, and any candidate who must not be elected to secure a conformant result is deemed doomed. Any candidate who is doomed is excluded at the next opportunity. Any candidate who is guarded is prevented from being excluded.

Multiple constraints are supported using the method described by Hill (Voting Matters 1998;(9):2–4) and Otten (Voting Matters 2001;(13):4–7).

Numeric representation

Numbers (-n/--numbers), Decimal places (--decimals)

This dropdown allows you to select how numbers (vote totals, etc.) are represented internally in memory. The options are:

• Fixed: Numbers are represented as fixed-precision decimals, up to a certain number of decimal places (default: 5).
• Fixed (guarded): Numbers are represented as fixed-precision decimals with ‘guard digits’ – also known as ‘quasi-exact’ arithmetic. If n decimal places are requested, numbers are represented up to 2n decimal places, and two values are considered equal if the absolute difference is less than (10⁻ⁿ)/2.
• Rational: Numbers are represented exactly as fractions, resulting in the elimination of rounding error, but increasing computational complexity when the number of surplus transfers is very large.
• Float (64-bit): Numbers are represented as native 64-bit floating-point numbers. This is fast, but not recommended as unexpectedly large rounding errors may be introduced in some circumstances.

Display up to [n] d.p. (--pp-decimals)

This option allows you to specify to how many decimal places votes will be reported in the results report. It does not affect the internal precision of calculations.

Normalise ballots (--normalise-ballots)

In the BLT file format, each set of preferences can have a specified weight – this is typically used to indicate multiple voters who had the same preferences.

When ballots are not normalised (default), a set of preferences with weight n > 1 is represented as a single ballot with value n. This is known as list-packed ballots.

When ballots are normalised, a set of preferences with weight n > 1 is instead converted to n ballots each with value 1. This is generally required only when the rules directly deal with individual ballot weights, such as when Sum surplus transfers is set to Per ballot.

Count optimisations

Early bulk election (--no-early-bulk-elect)

When early bulk election is enabled (default), the count terminates as soon as the set of winning candidates is known. Specifically:

• At the beginning of each stage, if the number of not-excluded candidates exactly equals the number of vacancies to fill, all remaining candidates are declared elected in a single stage. This is typical of most STV rules.
• If a proposed exclusion would cause the number of not-excluded candidates to exactly equal the number of vacancies, all remaining candidates are declared elected without transfers arising from the proposed exclusion being performed.
• At the end of any stage, if n vacancies remain and the n-th top continuing candidate has more votes than all lower continuing candidates (plus votes awaiting transfer), the n top continuing candidate are immediately declared elected.

If an early bulk election is performed, further surplus distributions are not performed, and outstanding exclusions, if any, are not completed, even if they could change the order of election.

When early bulk election is disabled, surpluses continue to be distributed, and outstanding exclusions continue to be completed, even once the number of not-excluded candidates exactly equals the number of vacancies to fill. Bulk election is performed only as a final measure once there are no more surpluses to distribute, and no exclusions to complete.

In either case, candidates are declared elected in descending order of votes. This ensures that only one candidate is ever elected at a time and the order of election is well-defined, which is required e.g. for some affirmative action rules.

Note that the OpenTally rules for early bulk election are aggressive, and many STV rules do not implement all 3 (if any at all). It is not possible at this time to selectively apply only some of the rules. In order to reproduce the result of a count performed by others, where not all rules were implemented, consider disabling early bulk election and comparing the results at the time a bulk election would have been made.

Note also that early bulk election can conflict with constraints. If an election is to be run with constraints, it is recommend that early bulk election be disabled.

Bulk exclusion (--bulk-exclude)

When bulk exclusion is disabled (default), only one candidate is ever excluded per stage.

When bulk exclusion is enabled, as many candidates are excluded as possible at once per stage, provided that sufficient candidates remain to fill the vacancies, and the bulk exclusion could not change the order of exclusion. If 2 or more candidates are tied, either all are bulk excluded or none are. The ballot papers of all excluded candidates are considered together, and transferred according to the Exclusion method.

Defer surpluses (--defer-surpluses)

When deferred surpluses is disabled (default), all surpluses must be transferred before candidates can be excluded.

When deferred surpluses is enabled, the transfer of all surpluses is deferred if doing so could not change the order of exclusion (including of a bulk exclusion, if that is enabled).

(Meek) Immediate election (--meek-immediate-elect)

When Surplus method is set to Meek method, this option controls when candidates are elected:

• When immediate election is disabled (default), all current surpluses are distributed and keep values finalised, before any candidates exceeding the quota are then declared elected. This is the method specified in the 1987 Meek rules.
• When immediate election is enabled, a candidate meeting the quota interrupts a surplus distribution. The candidate is immediately declared elected, before the distribution of all surpluses of all now-elected candidates continues. This is the method specified in the 2006 Meek rules.

Rounding

Round quota/votes/surplus fractions/ballot weights to [n] d.p. (--round-quota, --round-votes, --round-tvs, --round-weights)

When rounding is enabled, the specified values are rounded to the specified number of decimal places. This enables, for example, votes to be counted only in integers, while ballot weights and surplus fractions are calculated to higher precision (according to the Numbers option).

When enabled, the quota is incremented or rounded up (according to the Quota option), whereas votes, surplus fractions and weights are always rounded down.

In relation to Round surplus fractions to [n] d.p. (--round-tvs) – note that surplus fractions are used in STV in calculations of the form A × (B/C), where (B/C) is the surplus fraction. The order of operations depends on this setting:

• When this option is disabled (default), (A × B) is calculated first, then divided by C. This minimises rounding errors.
• When this option is enabled, (B/C) is calculated separately first and rounded to the specified precision, before being multiplied by A. Many STV rules designed for hand counting prescribe this method of manipulating surplus fractions.

In Australia, surplus fractions are often known as ‘transfer values’; however, the term ‘value’ is reserved in OpenTally for referring to the values of votes.

When Surplus method is set to Meek method:

• --round-weights instead controls the rounding of candidate keep values
• --round-tvs instead controls the rounding of each intermediate product when computing candidates' votes
• --round-votes controls the rounding of the final number of votes credited to each candidate

(Gregory) Sum surplus transfers (--sum-surplus-transfers)

This option allows you to specify how the numbers of votes credited to candidates in a surplus transfer is calculated. In each case, votes are grouped according to the next available preference for a continuing candidate. Subsequently:

• Single step: The total value of all votes expressing a next available preference for that candidate is multiplied by the surplus fraction. The product is credited to that candidate.
• By value: The votes expressing a next available preference for that candidate are further divided according to value. For each group of votes at a particular value, the total value of all such votes is multiplied by the surplus fraction. The product is credited to that candidate. This is distinct to Single step only for weighted inclusive Gregory.
• Per ballot: For each individual vote expressing a next available preference for that candidate, the value of the vote is multiplied by the surplus fraction. The product is credited to that candidate.

This option affects the result only insofar as rounding (due to use of fixed-precision arithmetic, or due to an explicit rounding option) is concerned.

(Meek) Surplus tolerance (--meek-surplus-tolerance)

When Surplus method is set to Meek method, this option allows you to specify when the distribution of surpluses will be considered complete. The tolerance may be specified either as a percentage (ends with a %) or absolute number of votes (no %):

• Percentage: Surplus distributions will be considered complete when every elected candidate's surplus exceeds the quota by no more than the specified percentage. This is the method specified in the 1987 Meek rules.
• Absolute number of votes: Surplus distributions will be considered complete when the total surpluses of all elected candidates is no greater than the specified number of votes. This is the simpler method specified in the 2006 Meek rules.