From 4cf9053681528d9e3804dfeed38d9093455687f5 Mon Sep 17 00:00:00 2001
From: RunasSudo <runassudo@yingtongli.me>
Date: Sun, 11 Jun 2023 21:47:37 +1000
Subject: [PATCH] Implement --surplus-assume-total

This replaces and extends the former --subtract-nontransferable option

#4
---
 docs/FnSpecs.tex          |  2 ++
 docs/options.md           |  9 +++++----
 html/index.html           |  1 +
 html/presets.js           |  2 +-
 src/cli/stv.rs            |  6 +++---
 src/stv/gregory/mod.rs    | 15 ++++++++++-----
 src/stv/options.rs        | 14 +++++---------
 src/stv/wasm.rs           |  4 ++--
 tests/tests_impl/nswlg.rs |  6 +++---
 9 files changed, 32 insertions(+), 27 deletions(-)

diff --git a/docs/FnSpecs.tex b/docs/FnSpecs.tex
index 7c715cf..ac73c93 100644
--- a/docs/FnSpecs.tex
+++ b/docs/FnSpecs.tex
@@ -325,6 +325,8 @@
 	
 	\subsection\label{surplus-wig-sf}\paragraph If \textit{--papers} is \textit{both}, divide the elected candidate's surplus by their progress total.
 	
+	% FIXME: Update this for new --transferable-only, --surplus-assume-total flags
+	
 	\subsectionc\paragraph If \textit{--papers} is \textit{transferable}, for each parcel held by the elected candidate, multiply the number of transferable ballots in the parcel by the parcel's value, and sum the products. Divide the elected candidate's surplus by the sum.
 	
 	\subsectionc\paragraph If \textit{--papers} is \textit{subtract_nontransferable}, for each parcel held by the elected candidate, multiply the number of non-transferable ballots in the parcel by the parcel's value, and sum the products. Subtract the sum from the elected candidate's progress total. Divide the elected candidate's surplus by the difference.
diff --git a/docs/options.md b/docs/options.md
index a4ebbab..064d3ff 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -109,11 +109,12 @@ Random sample methods are also supported, but also not recommended:
 
 A random sample method will usually be used with a *Quota criterion* set to *>=*.
 
-### Ballots to examine in surplus transfer (--transferable-only/--subtract-nontransferable)
+### Ballots to examine in surplus transfer (--transferable-only/--surplus-assume-total)
 
-* *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.
+* *Include non-transferable ballots* (default): When this option is selected, all ballots of the transferring candidate are examined. The denominator of the surplus fraction is the total value of the ballots. 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.
+* *Assume progress total* (--surplus-assume-total): Same as *Include non-transferable ballots*, but the denominator of the surplus fraction is the candidate's recorded progress total. This has effect only as far as concerns rounding, and only in the weighted inclusive Gregory method.
+* *Use transferable ballots only* (--transferable-only): When this option is selected, only transferable ballots of the transferring candidate are examined. The denominator of the surplus fraction is the total value of the transferable ballots. 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 --surplus-assume-total): 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, and only in the weighted inclusive Gregory method.
 
 ### (Gregory) Exclusion method (--exclusion)
 
diff --git a/html/index.html b/html/index.html
index 8f93997..72fe54f 100644
--- a/html/index.html
+++ b/html/index.html
@@ -123,6 +123,7 @@
 						<label>
 							<select id="selPapers">
 								<option value="both" selected>Include non-transferable ballots</option>
+								<option value="assume_progress_total">Assume progress total</option>
 								<option value="transferable">Use transferable ballots only</option>
 								<option value="subtract_nontransferable">Subtract non-transferables</option>
 							</select>
diff --git a/html/presets.js b/html/presets.js
index b5c5d0b..b9b6244 100644
--- a/html/presets.js
+++ b/html/presets.js
@@ -207,7 +207,7 @@ function changePreset() {
 		document.getElementById('selSumTransfers').value = 'by_parcel';
 		document.getElementById('selSurplus').value = 'by_order';
 		document.getElementById('selMethod').value = 'wig';
-		document.getElementById('selPapers').value = 'both';
+		document.getElementById('selPapers').value = 'assume_progress_total';
 		document.getElementById('selExclusion').value = 'parcels_by_order';
 		document.getElementById('selTies').value = 'backwards,random';
 	} else if (document.getElementById('selPreset').value === 'act') {
diff --git a/src/cli/stv.rs b/src/cli/stv.rs
index d7dfada..99655da 100644
--- a/src/cli/stv.rs
+++ b/src/cli/stv.rs
@@ -121,9 +121,9 @@ pub struct SubcmdOptions {
 	#[clap(help_heading=Some("STV VARIANTS"), long)]
 	transferable_only: bool,
 	
-	/// (Gregory STV) If --transferable-only, calculate value of transferable papers by subtracting value of non-transferable papers
+	/// (Gregory STV) When calculating surplus fractions, assume the progress total is the total value of all the candidate's papers
 	#[clap(help_heading=Some("STV VARIANTS"), long)]
-	subtract_nontransferable: bool,
+	surplus_assume_total: bool,
 	
 	/// (Gregory STV) Method of exclusions [default: single_stage] [possible values: single_stage, by_value, by_source, parcels_by_order, reset_and_reiterate]
 	#[clap(help_heading=Some("STV VARIANTS"), long, possible_values=&["single_stage", "by_value", "first_prefs_then_by_value", "by_source", "parcels_by_order", "wright", "reset_and_reiterate"], default_value="single_stage", value_name="method", hide_possible_values=true, hide_default_value=true)]
@@ -302,7 +302,7 @@ where
 		cmd_opts.surplus.into(),
 		cmd_opts.surplus_order.into(),
 		cmd_opts.transferable_only,
-		cmd_opts.subtract_nontransferable,
+		cmd_opts.surplus_assume_total,
 		cmd_opts.exclusion.into(),
 		cmd_opts.meek_nz_exclusion,
 		cmd_opts.sample.into(),
diff --git a/src/stv/gregory/mod.rs b/src/stv/gregory/mod.rs
index 9528f80..d1bd8e0 100644
--- a/src/stv/gregory/mod.rs
+++ b/src/stv/gregory/mod.rs
@@ -233,7 +233,7 @@ where
 	
 	// Count votes
 	
-	let mut parcels_next_prefs= Vec::new();
+	let mut parcels_next_prefs = Vec::new();
 	
 	let mut transferable_ballots = N::new();
 	let mut transferable_votes = N::new();
@@ -266,14 +266,19 @@ where
 	// Calculate and print surplus fraction
 	
 	let total_ballots = &transferable_ballots + &exhausted_ballots;
-	let total_votes = &transferable_votes + &exhausted_votes;
+	let mut total_votes = &transferable_votes + &exhausted_votes;
 	
 	let count_card = state.candidates.get_mut(elected_candidate).unwrap();
 	count_card.ballot_transfers = -&total_ballots;
 	
-	if opts.transferable_only && opts.subtract_nontransferable {
-		// Override transferable_votes
-		transferable_votes = count_card.votes.clone() - exhausted_votes;
+	if opts.surplus_assume_total {
+		// Override total_votes
+		total_votes = count_card.votes.clone();
+		
+		if opts.transferable_only {
+			// Override transferable_votes
+			transferable_votes = count_card.votes.clone() - exhausted_votes;
+		}
 	}
 	
 	let mut surplus_denom = calculate_surplus_denom(&surplus, &transferable_ballots, &transferable_votes, &total_ballots, &total_votes, opts);
diff --git a/src/stv/options.rs b/src/stv/options.rs
index 0256eba..807dc28 100644
--- a/src/stv/options.rs
+++ b/src/stv/options.rs
@@ -81,9 +81,9 @@ pub struct STVOptions {
 	#[builder(default="false")]
 	pub transferable_only: bool,
 	
-	/// (Gregory STV) If --transferable-only, calculate value of transferable papers by subtracting value of non-transferable papers
+	/// (Gregory STV) When calculating surplus fractions, assume the progress total is the total value of all the candidate's papers
 	#[builder(default="false")]
-	pub subtract_nontransferable: bool,
+	pub surplus_assume_total: bool,
 	
 	/// (Gregory STV) Method of exclusions
 	#[builder(default="ExclusionMethod::SingleStage")]
@@ -169,7 +169,7 @@ impl STVOptions {
 		if self.surplus != SurplusMethod::Meek {
 			if self.surplus_order != SurplusOrder::BySize { flags.push(self.surplus_order.describe()); }
 			if self.transferable_only { flags.push("--transferable-only".to_string()); }
-			if self.subtract_nontransferable { flags.push("--subtract-nontransferable".to_string()); }
+			if self.surplus_assume_total { flags.push("--surplus-assume-total".to_string()); }
 			if self.exclusion != ExclusionMethod::SingleStage { flags.push(self.exclusion.describe()); }
 		}
 		if self.surplus == SurplusMethod::Meek && self.meek_nz_exclusion { flags.push("--meek-nz-exclusion".to_string()); }
@@ -238,14 +238,10 @@ impl STVOptions {
 				return Err(STVError::InvalidOptions("--constraint-mode repeat_count requires a Gregory method for --surplus"));
 			}
 		}
-		if self.subtract_nontransferable {
+		if self.surplus_assume_total {
 			if self.surplus != SurplusMethod::WIG {
 				// Invalid because other methods do not distinguish between ballots of different value during surplus transfer
-				return Err(STVError::InvalidOptions("--subtract-nontransferable requires --surplus wig"));
-			}
-			if !self.transferable_only {
-				// Invalid because nontransferables are only subtracted with --transferable-only
-				return Err(STVError::InvalidOptions("--subtract-nontransferable requires --transferable-only"));
+				return Err(STVError::InvalidOptions("--surplus-assume-total requires --surplus wig"));
 			}
 		}
 		if !self.immediate_elect {
diff --git a/src/stv/wasm.rs b/src/stv/wasm.rs
index 0de5285..3e14da8 100644
--- a/src/stv/wasm.rs
+++ b/src/stv/wasm.rs
@@ -1,5 +1,5 @@
 /*  OpenTally: Open-source election vote counting
- *  Copyright © 2021–2022 Lee Yingtong Li (RunasSudo)
+ *  Copyright © 2021–2023 Lee Yingtong Li (RunasSudo)
  *
  *  This program is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU Affero General Public License as published by
@@ -280,7 +280,7 @@ impl STVOptions {
 			surplus.into(),
 			surplus_order.into(),
 			if papers == "transferable" || papers == "subtract_nontransferable" { true } else { false },
-			if papers == "subtract_nontransferable" { true } else { false },
+			if papers == "assume_progress_total" || papers == "subtract_nontransferable" { true } else { false },
 			exclusion.into(),
 			meek_nz_exclusion,
 			sample.into(),
diff --git a/tests/tests_impl/nswlg.rs b/tests/tests_impl/nswlg.rs
index a3bd0a5..3efcdef 100644
--- a/tests/tests_impl/nswlg.rs
+++ b/tests/tests_impl/nswlg.rs
@@ -1,5 +1,5 @@
 /*  OpenTally: Open-source election vote counting
- *  Copyright © 2021–2022 Lee Yingtong Li (RunasSudo)
+ *  Copyright © 2021–2023 Lee Yingtong Li (RunasSudo)
  *
  *  This program is free software: you can redistribute it and/or modify
  *  it under the terms of the GNU Affero General Public License as published by
@@ -33,10 +33,10 @@ fn nswlg_albury21_rational() {
 		.ties(vec![TieStrategy::Backwards, TieStrategy::Random(String::from("20220322"))])
 		.surplus_order(stv::SurplusOrder::ByOrder)
 		.transferable_only(true)
-		.subtract_nontransferable(true)
+		.surplus_assume_total(true)
 		.build().unwrap();
 	
-	assert_eq!(stv_opts.describe::<Rational>(), "--round-votes 0 --round-quota 0 --round-subtransfers by_parcel --quota-criterion geq --ties backwards random --random-seed 20220322 --surplus-order by_order --transferable-only --subtract-nontransferable");
+	assert_eq!(stv_opts.describe::<Rational>(), "--round-votes 0 --round-quota 0 --round-subtransfers by_parcel --quota-criterion geq --ties backwards random --random-seed 20220322 --surplus-order by_order --transferable-only --surplus-assume-total");
 	
 	utils::read_validate_election::<Rational>("tests/data/City_of_Albury-finalpreferencedatafile.csv", "tests/data/City_of_Albury-finalpreferencedatafile.blt", stv_opts, None, &[]);
 }