diff --git a/docs/options.md b/docs/options.md index 8b9eda1..1fe9368 100644 --- a/docs/options.md +++ b/docs/options.md @@ -68,7 +68,7 @@ Note that the combination ‘*>= Droop (exact)*’ (or, when *Round quota to [n] This option allows you to specify whether the votes required for election can change during the count. The options are: * *Static quota* (default): The quota is calculated once after all first-preference votes are allocated, and remains constant throughout the count. -* *Static with ERS97/ERS76 rules*: The quota is static, but candidates may be elected if their vote exceeds (or equals, according to the *Quota criterion*) the active vote, divided by one more than the number of remaining vacancies (with minor variations in details between ERS97 and ERS76). Additionally, under ERS97 rules, the quota is reduced if ballot papers exhaust before any candidate is elected. +* *Static with ERS97/ERS76 rules*: The quota is static, but candidates may be elected if their vote exceeds (or equals, according to the *Quota criterion*) the active vote, divided by one more than the number of remaining vacancies (with minor variations in details between ERS97 and ERS76). Additionally, under ERS97 rules, the quota is reduced if ballots exhaust before any candidate is elected. * *Dynamic by total vote*: The quota is recalculated at the end of each stage, according to the *Quota* option. * *Dynamic by active vote*: The quota is recalculated at the end of each stage, according to the *Quota* option, but where *V* is the active vote and *S* is the number of remaining vacancies. @@ -89,35 +89,35 @@ Some STV counting rules provide, for example, that ‘no surplus shall be transf 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 elected candidate are examined. Transfers are weighted according to the values of the ballot papers. +* *Weighted inclusive Gregory* (default): During surplus transfers, all applicable ballots of the elected candidate are examined. Transfers are weighted according to the values of the ballots. * *Meek method*: Transfers are computed as described at . Other Gregory methods are supported, but not recommended: -* *Unweighted inclusive Gregory*: During surplus transfers, all applicable ballot papers of the elected 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 (all of one value) are examined. +* *Unweighted inclusive Gregory*: During surplus transfers, all applicable ballots of the elected candidate are examined. Transfers are not weighted, and each ballot has equal value in the calculation. +* *Exclusive Gregory (last bundle)*: During surplus transfers, only the ballots received in the last transfer (all of one value) are examined. Random sample methods are also supported, but also not recommended: -* *Hare (exclusive sample)*: During surplus transfers, a subset of the ballot papers received in the last transfer, equal in size to the surplus, is examined. -* *Inclusive Hare (sample)*: During surplus transfers, a subset of the elected candidate's ballot papers, equal in size to the surplus, is examined. +* *Hare (exclusive sample)*: During surplus transfers, a subset of the ballots received in the last transfer, equal in size to the surplus, is examined. +* *Inclusive Hare (sample)*: During surplus transfers, a subset of the elected candidate's ballots, equal in size to the surplus, is examined. A random sample method will usually be used with a *Quota criterion* set to *>=*. -### Papers to examine in surplus transfer (--transferable-only/--subtract-nontransferable) +### Ballots to examine in surplus transfer (--transferable-only/--subtract-nontransferable) -* *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. This is the method typically used with the weighted inclusive Gregory or Meek methods. -* *Use transferable papers only* (--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. This is the method typically used with other surplus distribution methods. -* *Subtract non-transferables* (--transferable-only --subtract-nontransferable): Same as *Use transferable papers only*, but the value of the transferable papers is calculated by subtracting the value of non-transferable papers from the progress total. This has effect only as far as concerns rounding. +* *Include non-transferable ballots* (default): When this option is selected, all ballots of the transferring candidate are examined. Non-transferable ballots are always exhausted at the relevant surplus fractions. This is the method typically used with the weighted inclusive Gregory or Meek methods. +* *Use transferable ballots only* (--transferable-only): When this option is selected, only transferable ballots of the transferring candidate are examined. Non-transferable ballots are exhausted only if the value of the transferable ballots is less than the surplus. This is the method typically used with other surplus distribution methods. +* *Subtract non-transferables* (--transferable-only --subtract-nontransferable): Same as *Use transferable ballots only*, but the value of the transferable ballots is calculated by subtracting the value of non-transferable ballots from the progress total. This has effect only as far as concerns rounding. ### (Gregory) Exclusion method (--exclusion) When *Surplus method* is set to a Gregory method, this option controls how candidates are excluded: -* *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, 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 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. +* *Single stage* (default): When excluding candidate(s), transfer all their ballots in one stage. +* *By value*: When excluding candidate(s), transfer their ballots 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, no further ballots are transferred to that candidate. +* *By source*: When excluding candidate(s), transfer their ballots according to the candidate from which those ballots were received, 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 ballots 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. ### (Meek) NZ-style exclusion (--meek-nz-exclusion) @@ -129,20 +129,20 @@ When *Surplus method* is set to *Meek method*, this option controls how candidat ### (Sample) Sample method (--sample) -When *Surplus method* is set to a random sample method, this option controls which subset of ballot papers is selected for transfer during surplus distributions: +When *Surplus method* is set to a random sample method, this option controls which subset of ballots is selected for transfer during surplus distributions: -* *Stratify* (default): The candidate's ballot papers are first stratified into subparcels according to next available preference, and an equal proportion of each subparcel is transferred, with the subset transferred comprising the ballot papers in each subparcel most recently received by the candidate. In the calculation of proportions, the largest remainders are rounded up so there is no loss by fraction. This is the method specified by the [*Electoral Act 1992* (Ireland)](http://www.irishstatutebook.ie/eli/1992/act/23/section/121/enacted/en/html#sec121). -* *By order*: The subset transferred comprises the ballot papers most recently received by the candidate. +* *Stratify* (default): The candidate's ballots are first stratified into subparcels according to next available preference, and an equal proportion of each subparcel is transferred, with the subset transferred comprising the ballots in each subparcel most recently received by the candidate. In the calculation of proportions, the largest remainders are rounded up so there is no loss by fraction. This is the method specified by the [*Electoral Act 1992* (Ireland)](http://www.irishstatutebook.ie/eli/1992/act/23/section/121/enacted/en/html#sec121). +* *By order*: The subset transferred comprises the ballots most recently received by the candidate. * *Cincinnati*: The subset is selected using the deterministic method used in [Cambridge, Massachusetts](https://web.archive.org/web/20081118104049/http://www.fairvote.org/media/1993countmanual.pdf) (derived from Article IX of the former 1938 Cincinnati *Code of Ordinances*). -In any case, the subset selected depends on the order of ballot papers in the BLT file, and is independent of the *Random seed* option. +In any case, the subset selected depends on the order of ballots in the BLT file, and is independent of the *Random seed* option. ### (Sample) Transfer ballot-by-ballot (--sample-per-ballot) When *Surplus method* is set to a random sample method, this option controls when candidates are declared elected: * When ballot-by-ballot transfer is disabled (default), candidates are declared elected only at the end of a stage, as usual. -* When ballot-by-ballot transfer is enabled, candidates are declared elected immediately on meeting the quota after the transfer of any single ballot paper. Consequential surpluses therefore do not arise, and surpluses only occur during the count of first preferences. +* When ballot-by-ballot transfer is enabled, candidates are declared elected immediately on meeting the quota after the transfer of any single ballot. Consequential surpluses therefore do not arise, and surpluses only occur during the count of first preferences. ### Ties (-t/--ties) @@ -183,14 +183,14 @@ When this option is selected, only constraints specifying a maximum number of ca The count proceeds as normal, until the point that a candidate would be elected who would violate the constraint. At this point, that candidate and all other candidates from the constrained group are excluded, and all previously excluded candidates from the non-constrained group are reintroduced. -All ballot papers are removed from the count, and redistributed among the candidates in the following order: +All ballots are removed from the count, and redistributed among the candidates in the following order: * Any undistributed surpluses, each surplus comprising one stage -* Any exhausted ballot papers, in one or more stages (according to *Exclusion method*) -* The ballot papers of each continuing candidate from the non-constrained group, in one or more stages (according to *Exclusion method*), candidate-by-candidate in random order or an order specified by the user (according to *Ties*, with options other than *Random* and *Prompt* ignored) -* The ballot papers of each continuing candidate from the constrained group, in like manner +* Any exhausted ballots, in one or more stages (according to *Exclusion method*) +* The ballots of each continuing candidate from the non-constrained group, in one or more stages (according to *Exclusion method*), candidate-by-candidate in random order or an order specified by the user (according to *Ties*, with options other than *Random* and *Prompt* ignored) +* The ballots of each continuing candidate from the constrained group, in like manner -Once all ballot papers have been so redistributed, the count resumes as usual. +Once all ballots have been so redistributed, the count resumes as usual. This method is specified, for example, in Schedule 1.1 of the [Monash Student Association *Election Regulations* (2021)](https://msa.monash.edu/app/uploads/2021/07/MSA-Election-Regulations-2021.pdf). @@ -200,7 +200,7 @@ This method is specified, for example, in Schedule 1.1 of the [Monash Student As * *Votes only*: The result sheet displays the number of votes held by each candidate at each stage of the count. * *Votes (transposed)*: Same as *Votes only*, but transfers are displayed to the left of, rather than above, progress totals. -* *Ballots and votes*: The result sheet displays the number of votes *and ballot papers* held by each candidate at each stage of the count. +* *Ballots and votes*: The result sheet displays the number of votes *and ballots* held by each candidate at each stage of the count. This functionality is not available on the command line. @@ -241,7 +241,7 @@ Note that the OpenTally rules for early bulk election are aggressive, and many S When bulk exclusion is disabled (default), only one candidate is ever excluded per stage. -When bulk exclusion is enabled, as many candidates as possible are excluded together in each single 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*. +When bulk exclusion is enabled, as many candidates as possible are excluded together in each single 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 ballots of all excluded candidates are considered together, and transferred according to the *Exclusion method*. Note that some rules (such as the Australian Senate rules) provide for more conservative ‘bulk exclusion’ which additionally requires that the bulk exclusion cannot cause a candidate to be elected. This form of bulk exclusion accordingly cannot change the result compared with no bulk exclusion (except as far as rounding or parcelling may be concerned), and is not currently supported. diff --git a/docs/validation.md b/docs/validation.md index 05d713f..48df01a 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -5,9 +5,9 @@ STV-counting software is frequently validated empirically by comparing the resul | Method | Election | Comparator | Included test case | |-|-|-|-| | Scottish STV | [2007 Glasgow council Linn ward election](https://web.archive.org/web/20121004213938/http://www.glasgow.gov.uk/en/YourCouncil/Elections_Voting/Election_Results/ElectionScotland2007/LGWardResults.htm?ward=1&wardname=1%20-%20Linn) | eSTV 2.0.16 (official) | ✓ | -| OpenTally Meek | [Reverse engineered ballot papers for the ERS97 model election](https://yingtongli.me/blog/2021/01/04/ers97.html) | [Algorithm 123](https://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf) | ✓ | -| Meek STV (2006) | Reverse engineered ballot papers for the ERS97 model election | [OpenSTV 1.7](https://github.com/Conservatory/openstv) | ✓ | -| Meek STV (New Zealand) | Reverse engineered ballot papers for the ERS97 model election | OpenSTV 1.7, [Hill's nzmeek 6.7.7](https://yingtongli.me/blog/2021/07/08/nzmeek.html) | ✓ | +| OpenTally Meek | [Reverse engineered ballots for the ERS97 model election](https://yingtongli.me/blog/2021/01/04/ers97.html) | [Algorithm 123](https://www.dia.govt.nz/diawebsite.NSF/Files/meekm/%24file/meekm.pdf) | ✓ | +| Meek STV (2006) | Reverse engineered ballots for the ERS97 model election | [OpenSTV 1.7](https://github.com/Conservatory/openstv) | ✓ | +| Meek STV (New Zealand) | Reverse engineered ballots for the ERS97 model election | OpenSTV 1.7, [Hill's nzmeek 6.7.7](https://yingtongli.me/blog/2021/07/08/nzmeek.html) | ✓ | | Australian Senate STV | [2019 Tasmanian Senate election](https://results.aec.gov.au/24310/Website/SenateDownloadsMenu-24310-Csv.htm) | EasyCount (official) | ✓ | | Australian Senate STV | [2019 NSW Senate election](https://results.aec.gov.au/24310/Website/SenateDownloadsMenu-24310-Csv.htm) | EasyCount (official) | | | Australian Capital Territory STV | [2020 Kurrajong Legislative Assembly election](https://www.elections.act.gov.au/elections_and_voting/2020_legislative_assembly_election/ballot-paper-preference-data-2020-election) | [eVACS 2020](https://www.elections.act.gov.au/elections_and_voting/electronic_voting_and_counting) (official) | ✓ | @@ -19,10 +19,10 @@ STV-counting software is frequently validated empirically by comparing the resul | Wright STV | [EVE Online CSM 15 election](https://www.eveonline.com/news/view/meet-the-new-council) | [ccp-wright-stv](https://github.com/ccpgames/ccp-wright-stv) (official) | ✓ | | PRSA 1977 | [*Proportional Representation Manual*](https://www.prsa.org.au/publicat.htm#p2) [example 1](https://www.prsa.org.au/utopiatc.pdf) | [Model result](https://www.prsa.org.au/example1.pdf) (official) | ✓ | | PRSA 1977 | 40 elections from [stvdb](https://gitlab.com/RunasSudo/stvdb) | [count.nl (RunasSudo version)](https://gitlab.com/RunasSudo/prsa_count) | ✓ | -| ERS97 | [Reverse engineered ballot papers for the ERS97 model election](https://yingtongli.me/blog/2021/01/04/ers97.html) | [Model result](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/#sub-section-24) (official) | ✓ | -| ERS97 | [Joe Otten/eSTV ballot papers for the ERS97 model election](https://web.archive.org/web/20020606014623/http://estv.otten.co.uk/) | [Model result](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/#sub-section-24) (official) | ✓ | -| ERS76 | Ballot papers adapted from Joe Otten/eSTV ERS97 papers | Model result (official) | ✓ | -| Church of England | Joe Otten/eSTV ballot papers for the ERS97 model election | [eSTV 1.47](https://web.archive.org/web/20040607021930/http://www.electoral-reform.org.uk/votingsystems/estv.htm) | ✓ | +| ERS97 | [Reverse engineered ballots for the ERS97 model election](https://yingtongli.me/blog/2021/01/04/ers97.html) | [Model result](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/#sub-section-24) (official) | ✓ | +| ERS97 | [Joe Otten/eSTV ballots for the ERS97 model election](https://web.archive.org/web/20020606014623/http://estv.otten.co.uk/) | [Model result](https://www.electoral-reform.org.uk/latest-news-and-research/publications/how-to-conduct-an-election-by-the-single-transferable-vote-3rd-edition/#sub-section-24) (official) | ✓ | +| ERS76 | Ballots adapted from Joe Otten/eSTV ERS97 | Model result (official) | ✓ | +| Church of England | Joe Otten/eSTV ballots for the ERS97 model election | [eSTV 1.47](https://web.archive.org/web/20040607021930/http://www.electoral-reform.org.uk/votingsystems/estv.htm) | ✓ | # References diff --git a/html/index.html b/html/index.html index 685cef3..8849c88 100644 --- a/html/index.html +++ b/html/index.html @@ -121,8 +121,8 @@ diff --git a/src/constraints.rs b/src/constraints.rs index ef87eaf..b893f20 100644 --- a/src/constraints.rs +++ b/src/constraints.rs @@ -929,8 +929,8 @@ where return Ok(true); } - // ------------------------------------------------ - // Distribute ballot papers of electable candidates + // ------------------------------------------ + // Distribute ballots of electable candidates let electable_candidates_old: Vec<&Candidate> = state.election.candidates.iter() // Present in order in case of multiple .filter(|c| { @@ -968,8 +968,8 @@ where state.title = StageKind::BallotsOf(candidate_distributing); state.logger.log_smart( - "Distributing ballot papers of {}.", - "Distributing ballot papers of {}.", + "Distributing ballots of {}.", + "Distributing ballots of {}.", vec![candidate_distributing.name.as_str()] ); stv::exclude_candidates(state, opts, vec![dummy_candidate])?; @@ -978,8 +978,8 @@ where return Ok(true); } - // -------------------------------------------------- - // Distribute ballot papers of unelectable candidates + // -------------------------------------------- + // Distribute ballots of unelectable candidates let unelectable_candidates_old: Vec<&Candidate> = state.election.candidates.iter() // Present in order in case of multiple .filter(|c| { @@ -1017,8 +1017,8 @@ where state.title = StageKind::BallotsOf(candidate_distributing); state.logger.log_smart( - "Distributing ballot papers of {}.", - "Distributing ballot papers of {}.", + "Distributing ballots of {}.", + "Distributing ballots of {}.", vec![candidate_distributing.name.as_str()] ); stv::exclude_candidates(state, opts, vec![dummy_candidate])?;