diff --git a/.gitignore b/.gitignore index 2f43d2c..cef99fd 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,10 @@ /homepage/_news.html +# Functional specifications build products +/docs/FnSpecs.* +!/docs/FnSpecs.tex + # Jekyll /homepage/_site /homepage/.sass-cache diff --git a/docs/FnSpecs.tex b/docs/FnSpecs.tex new file mode 100644 index 0000000..204d6f1 --- /dev/null +++ b/docs/FnSpecs.tex @@ -0,0 +1,1016 @@ +\documentclass[a4paper,11pt]{article} + +% Configuration +\usepackage[top=1.25cm,bottom=1.13cm,inner=2cm,outer=2cm,headheight=8pt,headsep=0.5cm,footskip=1cm,includehead,includefoot]{geometry} +\frenchspacing +\usepackage[hidelinks,bookmarksnumbered=true,unicode,pdftitle={OpenTally Functional Specifications},pdfauthor={Lee Yingtong Li (RunasSudo)}]{hyperref} +\usepackage{parskip} +\setlength{\parskip}{0.35cm plus 0.1cm minus 0.1cm} +\usepackage{fancyhdr} +\setlength{\emergencystretch}{3em} +\usepackage{microtype} + +\newlength\lmarg\lmarg=1.2cm +\newlength\qindent\qindent=1cm + +% Packages +\usepackage{underscore} +\usepackage{bookmark} % Non-sequential bookmarks + +% Fonts +\usepackage[math-style=ISO, bold-style=ISO]{unicode-math} +\setmainfont[RawFeature=-tlig]{TeX Gyre Termes} +\setsansfont[RawFeature=-tlig]{TeX Gyre Heros} +%\setmonofont[RawFeature=-tlig]{TeX Gyre Cursor} +\setmonofont[RawFeature=-tlig]{Source Code Pro} +\setmathfont[RawFeature=-tlig]{TeX Gyre Termes Math} +\setmathfont[RawFeature=-tlig,range={"0025}]{TeX Gyre Heros} +\setmathfont[RawFeature=-tlig,range=up/{greek,Greek,latin,Latin,num}]{TeX Gyre Heros} +\setmathfont[RawFeature=-tlig,range=it/{greek,Greek,latin,Latin,num}]{TeX Gyre Heros Italic} +\setmathfont[RawFeature=-tlig,range=bfup/{greek,Greek,latin,Latin,num}]{TeX Gyre Heros Bold} +\setmathfont[RawFeature=-tlig,range=bfit/{greek,Greek,latin,Latin,num}]{TeX Gyre Heros Bold Italic} +\newfontfamily{\freeserif}{FreeSerif}[RawFeature=-tlig] +\renewcommand{\familydefault}{\sfdefault} +%\usepackage[italic,greek,unicodeminus]{mathastext} + +% TOC format +\usepackage{titletoc} +\makeatletter +\newcounter{toc@section} +\titlecontents{part}[0pt]{\vspace{0.21cm}\setcounter{toc@section}{0}\bfseries}{}{\uppercase}{\titlerule*[1pc]{.}\contentspage}[] +\titlecontents{subpart}[0pt]{\vspace{0.21cm}\bfseries\scshape}{}{\setcounter{toc@section}{0}}{\titlerule*[1pc]{.}\contentspage}[] +\dottedcontents{section}[1.5cm]{\ifnum\value{toc@section}=0\vspace{0.21cm}\fi\setcounter{toc@section}{1}}{1cm}{1pc}[] +\makeatother + +% Headings, etc. +\renewcommand{\thepart}{\arabic{part}} +\renewcommand{\part}[1]{\vspace{0.5cm}\refstepcounter{part}\ifnum\value{part}>1\pagebreak[0]\fi{\centering\bfseries PART \thepart—\MakeUppercase{#1}\phantomsection\addcontentsline{toc}{part}{Part \thepart—#1}\nopagebreak\par}\vspace{-0.5cm}} + +\newcounter{subpart}[part] +\newcommand{\subpart}[1]{\vspace{0.5cm}\refstepcounter{subpart}\ifnum\value{subpart}>1\pagebreak[0]\fi{\centering\bfseries Division \thesubpart—#1\phantomsection\addcontentsline{toc}{subpart}{Division \thesubpart—#1}\nopagebreak\par}\vspace{-0.5cm}} +\makeatletter\newcommand{\toclevel@subpart}{1}\makeatother + +\newcounter{secinsubpart}[subpart] +\renewcommand{\section}[1]{\vspace{0.5cm}\stepcounter{secinsubpart}\refstepcounter{section}\ifnum\value{secinsubpart}>1\pagebreak[0]\fi{\bfseries\parbox[t]{\lmarg}{\thesection.}#1\phantomsection\addcontentsline{toc}{section}{\protect\numberline{\thesection} #1}\nopagebreak\par}} +\makeatletter\renewcommand{\toclevel@section}{2}\makeatother + +\newcommand{\subheading}[1]{\vspace{0.5cm}{\hangindent=\lmarg\hangafter=0\itshape#1\nopagebreak\par}} + +\renewcommand{\thesubsection}{\thesection.\arabic{subsection}} +\renewcommand{\subsection}{\refstepcounter{subsection}\hangindent=\lmarg\parbox[t]{\lmarg}{\thesubsection.}} +\newcommand{\subsectionc}{\hangindent=\lmarg\hspace{\lmarg}} + +\renewcommand{\theparagraph}{(\alph{paragraph})} +\renewcommand{\paragraph}{\refstepcounter{paragraph}\hangindent=\dimexpr\lmarg+\qindent\relax\parbox[t]{\qindent}{\theparagraph}} +\newcommand{\paragraphc}{\hspace{\dimexpr\lmarg+\qindent\relax}} + +\renewcommand{\thesubparagraph}{(\roman{subparagraph})} +\renewcommand{\subparagraph}{\refstepcounter{subparagraph}\hangindent=\dimexpr\lmarg+2\qindent\relax\parbox[t]{\qindent}{\thesubparagraph}} +\newcommand{\subparagraphc}{\hspace{\dimexpr\lmarg+2\qindent\relax}\hangindent=\dimexpr\lmarg+2\qindent\relax} + +\newcounter{subsubparagraph}[subparagraph] +\renewcommand{\thesubsubparagraph}{(\Alph{subsubparagraph})} +\newcommand{\subsubparagraph}{\refstepcounter{subsubparagraph}\hangindent=\dimexpr\lmarg+3\qindent\relax\parbox[t]{\qindent}{\thesubsubparagraph}} +\newcommand{\subsubparagraphc}{\hspace{\dimexpr\lmarg+3\qindent\relax}} + +\newcounter{subsubsubparagraph}[subsubparagraph] +\renewcommand{\thesubsubsubparagraph}{(\Roman{subsubsubparagraph})} +\newcommand{\subsubsubparagraph}{\refstepcounter{subsubsubparagraph}\hangindent=\dimexpr\lmarg+4\qindent\relax\parbox[t]{\qindent}{\thesubsubsubparagraph}} + +\newlength{\notetaglength} +\newcommand{\note}[2]{{\nopagebreak\par\footnotesize\selectfont\settowidth{\notetaglength}{\bfseries #1:}\addtolength{\notetaglength}{1em}\leftskip=\lmarg\hangindent=\notetaglength\makebox[\notetaglength][l]{\bfseries #1:}#2\par}} + +\newcommand{\defn}[1]{\textit{\textbf{#1}}} +\newcommand{\nobreakpar}{\nopagebreak[4]\par} + +\begin{document} + \fancypagestyle{plain}{\fancyhf{}} + \pagestyle{fancy}\fancyhf{}\renewcommand{\headrulewidth}{0pt} + \lhead{\textsf{\scriptsize OpenTally Functional Specifications}} + \lfoot{\textsf{\scriptsize Draft 2022-11-06}} + \rfoot{\textsf{\scriptsize\thepage}} + + \pagenumbering{roman} + {\bfseries\centering\fontsize{13pt}{15pt}\selectfont OPENTALLY FUNCTIONAL SPECIFICATIONS\par INDEX\par} + \makeatletter\@starttoc{toc}\makeatother + + \newpage\pagenumbering{arabic} + % End front matter + + \part{Preliminary} + + \section{Introduction} + + \subsection These are the \textit{OpenTally Functional Specifications}, which specify how an election is to be counted in a conforming implementation. + + \section{Scope} + + \subsection These specifications set out how the result of an election, namely the winning candidates and their order of election, are to be determined. + + \subsection These specifications do not cover the input or validation of ballots. In particular, the following matters are outside the scope of these specifications and are implementation-defined: + + \subsectionc\paragraph the format of ballots in input files, + + \subsectionc\paragraph the checking of ballots for formality. + + \subsection These specifications do not cover presentational matters or other matters which cannot impact the result of the election. In particular, the following matters are outside the scope of these specifications and are implementation-defined: + + \subsectionc\paragraph the values of exhausted ballots, + + \subsectionc\paragraph the votes lost by fraction, + + \subsectionc\paragraph the votes credited to elected candidates after their surpluses are distributed, + + \subsectionc\paragraph the presentation of results. + + \section{Method of counting} + + \subsection If \textit{--method} is \textit{wig}, \textit{uig}, \textit{eg}, \textit{hare} or \textit{ihare}, the ballots are to be counted according to section~\ref{trad-stage1}. + + \subsection If \textit{--method} is \textit{meek}, the ballots are to be counted according to section~\ref{meek-stage1}. + + \part{Methods other than Meek} + + \subpart{General} + + \section{First stage}\label{trad-stage1} + + \subsection Take the transferable ballots in the input file, in the order each appears. Sort them into parcels, each of value 1, according to next available preference. %Set any non-transferable ballots aside as exhausted. + + \subsection Transfer each parcel to the corresponding candidate, and credit the candidate with votes equal to the number of ballots in the parcel. + + \subsection\label{quota-xref1}Calculate the \textit{quota} according to section~\ref{quota}. + + \subsection\label{trad-elect-xref1}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-1}This is the \textit{end of a stage}. Proceed to section~\ref{trad-stage2}. + + \section{Election of continuing candidates}\label{trad-elect} + + \subsection This section applies in + subsections~\ref{trad-elect-xref1}, + \ref{trad-surplus-after-do}, + \ref{trad-exclusion-after-do}, + \ref{hare-by-order-elect-s}\ref{hare-by-order-elect-p}\ref{hare-by-order-elect-sp}\ref{hare-by-order-elect}, + \ref{hare-cincinnati-elect-s}\ref{cincinnati-do}\ref{hare-cincinnati-elect} + and \ref{exclusion-hare-elect-s}\ref{exclusion-hare-elect-p}\ref{exclusion-hare-elect}, + to elect any continuing candidates who must be elected. + + \subsection\label{quota-xref7}If \textit{--quota-mode} is \textit{ers97} and no candidates have been declared elected, recalculate the quota according to section~\ref{quota}. + + \subsection\label{ers-vre-xref1-s}If \textit{--no-immediate-elect} is disabled: + + \subsectionc\paragraph\label{ers-vre-xref2-p}If \textit{--quota-mode} is \textit{ers97} or \textit{ers76}: + + %\paragraphc\subparagraph\label{ers-vre-xref2}Calculate the vote required for election according to section~\ref{ers-vre}. + + \paragraphc\subparagraph Add: + + \subparagraphc\subsubparagraph the sum of all continuing candidates' progress totals, plus + + \subparagraphc\subsubparagraph the sum of all excluded candidates' progress totals, plus + + \subparagraphc\subsubparagraph the total of any undistributed surpluses. + + \subparagraphc Divide the sum by 1 more than the number of remaining vacancies. The quotient is the \defn{vote required for election}. + + \paragraphc\subparagraph\label{trad-elect-ers}Declare elected any continuing candidate who meets the quota or the vote required for election, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. + + \paragraphc\subparagraph If \textit{--quota-mode} is \textit{ers97} and any candidates were declared elected in subparagraph~\ref{trad-elect-ers}, repeat this paragraph. + + \paragraphc\subparagraph If \textit{--quota-mode} is \textit{ers76} and any candidates were declared elected in subparagraph~\ref{trad-elect-ers} due to meeting the quota, repeat this paragraph. + + %\paragraphc\subparagraph Consider each continuing candidate in descending order of progress total, breaking any tie according to section~\ref{ties}. + %\paragraphc\subparagraph\label{ers-vre-xref1-sp}For each continuing candidate: + %\subparagraphc\subsubparagraph\label{ers-vre-xref1}Calculate the vote required for election according to section~\ref{ers-vre}. + %\subparagraphc\subsubparagraph Declare the candidate elected if they meet the quota or the vote required for election. + %\subsectionc\paragraph\label{ers-vre-xref2-p}If \textit{--quota-mode} is \textit{ers76}: + + \subsectionc\paragraph\label{quota-xref6-p}If \textit{--quota-mode} is \textit{dynamic_by_total} or \textit{dynamic_by_active}: + + \paragraphc\subparagraph\label{quota-xref6}Recalculate the quota according to section~\ref{quota}. + + \paragraphc\subparagraph\label{trad-elect-dynamic}Declare elected any continuing candidate who meets the quota, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. + + \paragraphc\subparagraph If any candidates were declared elected in subparagraph~\ref{trad-elect-dynamic}, repeat this paragraph. + + \subsectionc\paragraph If \textit{--quota-mode} is \textit{static}, declare elected any continuing candidate who meets the quota, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. + + \subheading{Early bulk election of sure winners} + + \subsection\label{trad-ebe-criteria}This subsection applies if \textit{--early-bulk-elect} is enabled, and the continuing candidates with the highest progress totals, up to the number of remaining vacancies (the \defn{leading candidates}), each have a higher progress total than: + + \subsectionc\paragraph the sum of all other continuing candidates' progress totals, plus + + \subsectionc\paragraph the sum of all excluded candidates' progress totals, plus + + \subsectionc\paragraph the total of any undistributed surpluses. + + \subsection If subsection~\ref{trad-ebe-criteria} applies, immediately declare elected each of the leading candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \section{Second or subsequent stages}\label{trad-stage2} + + \subsection If no more vacancies remain to be filled, the count is complete. + + \subsection\label{trad-defer-xref}Otherwise, if 1 or more candidates have undistributed surpluses, and \textit{--defer-surpluses} is disabled or the distribution of surpluses cannot be deferred under section~\ref{trad-defer}, perform a surplus distribution according to section~\ref{trad-surplus}. + + \subsection Otherwise, if the number of continuing candidates equals the number of remaining vacancies, declare elected all continuing candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \subsection\label{trad-exclusion-xref}Otherwise, perform an exclusion according to section~\ref{trad-exclusion}. + + \subsection Repeat this section until the count is complete. + + \section{Deferring surplus distributions}\label{trad-defer} + + \subsection This section applies in subsection~\ref{trad-defer-xref}, if \textit{--defer-surpluses} is enabled, to determine when the distribution of surpluses must be deferred. + + \subsection If there are fewer than 2 continuing candidates, the distribution of surpluses must be deferred. + + \subsection\label{bulk-exclude-xref1-s}Otherwise, if: + + \subsectionc\paragraph the total of all undistributed surpluses is less than the difference between the progress totals of the 2 continuing candidates with the lowest progress totals, and + + \subsectionc\paragraph\label{bulk-exclude-xref1}if \textit{--bulk-exclude} is enabled and a bulk exclusion could be performed under section~\ref{bulk-exclude}, the total of all undistributed surpluses is less than the difference between the sum of the progress totals of the continuing candidates who could be bulk excluded, and the progress total of the continuing candidate with the next lowest progress total, + + \subsectionc the distribution of surpluses must be deferred. + + \subsection Otherwise, the distribution of surpluses must not be deferred. + + \section{Surplus distribution}\label{trad-surplus} + + \subsection This section applies in subsection~\ref{trad-defer-xref} to distribute a candidate's surplus. + + \subsection When this section applies, apply the following procedure to the candidate with an undistributed surplus, and if there are multiple such candidates: + + \subsectionc\paragraph if \textit{--surplus-order} is \textit{by_size}, the one with the highest progress total (the \defn{elected candidate}), breaking any tie according to section~\ref{ties}. + + \subsectionc\paragraph if \textit{--surplus-order} is \textit{by_order}, the one who was elected the earliest (the \defn{elected candidate}). + + \subsection If \textit{--no-immediate-elect} is enabled, declare that candidate elected. + + \subsection\label{trad-surplus-do}\paragraph\label{surplus-wig-xref}If \textit{--method} is \textit{wig}, apply section~\ref{surplus-wig} to the elected candidate. + + \subsectionc\paragraph\label{surplus-uig-xref}If \textit{--method} is \textit{uig}, apply section~\ref{surplus-uig} to the elected candidate. + + \subsectionc\paragraph\label{surplus-eg-xref}If \textit{--method} is \textit{eg}, apply section~\ref{surplus-eg} to the elected candidate. + + \subsectionc\paragraph\label{surplus-hare-xref}If \textit{--method} is \textit{hare} or \textit{ihare}, apply section~\ref{surplus-hare} to the elected candidate. + + \subsection\label{trad-surplus-after-do}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-2}This is the \textit{end of a stage}. Return to section~\ref{trad-stage2}. + + \section{Exclusion—generally}\label{trad-exclusion} + + \subsection This section applies in subsection~\ref{trad-exclusion-xref} to exclude 1 or more continuing candidates. + + \subsection\label{bulk-exclude-xref2-s}When this section applies:\nobreakpar + + \subsectionc\paragraph If it is the first time this section is applied, and 1 or more continuing candidates have a progress total equal to or lower than the value of \textit{--min-threshold}, apply the following procedure to all those candidates. + + \subsectionc\paragraph\label{bulk-exclude-xref2}Otherwise, if \textit{--bulk-exclude} is enabled and a bulk exclusion can be performed under section~\ref{bulk-exclude}, apply the following procedure to the candidates to be bulk excluded. + + \subsectionc\paragraph Otherwise, apply the following procedure to the continuing candidate with the lowest progress total, breaking any tie according to section~\ref{ties}. + + \subsection Declare that candidate, or those candidates (the \defn{excluded candidates}), excluded. + + \subsection If \textit{--early-bulk-elect} is enabled, and the number of continuing candidates equals the number of remaining vacancies, declare elected all continuing candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \subsection\label{exclusion-reset-and-reiterate-xref}If \textit{--exclusion} is \textit{reset_and_reiterate}, then apply section~\ref{exclusion-reset-and-reiterate}. + + \subsection\label{exclusion-single-stage-xref}Otherwise: + + \subsectionc\paragraph If \textit{--exclusion} is \textit{single_stage}, apply section~\ref{exclusion-each-stage} to all of the excluded candidates' parcels at once. + + \subsectionc\paragraph If \textit{--exclusion} is \textit{by_value}: + + \paragraphc\subparagraph Aggregate the excluded candidates' parcels, in the order each was received, into 1 combined parcel for each value. + + \paragraphc\subparagraph Apply section~\ref{exclusion-each-stage} to each combined parcel in turn, in descending order of value. + + \subsectionc\paragraph If \textit{--exclusion} is \textit{parcels_by_order}, apply section~\ref{exclusion-each-stage} to each of the excluded candidates' parcels in turn, in the order each parcel was received by the excluded candidate. + + \subsection\label{exclusion-single-stage-after}Once all of the excluded candidates' parcels have been transferred under subsection~\ref{exclusion-single-stage-xref}, return to section~\ref{trad-stage2}. + + \section{Exclusion—each stage}\label{exclusion-each-stage} + + \subsection This section applies in subsection~\ref{exclusion-single-stage-xref} to transfer 1 or more parcels from excluded candidates (the \defn{parcels to transfer}). + + \subsection\label{trad-exclusion-do}\paragraph\label{exclusion-gregory-xref}If \textit{--method} is \textit{wig}, \textit{uig} or \textit{eg}, apply section~\ref{exclusion-gregory} to the parcels to transfer. + + \subsectionc\paragraph\label{exclusion-hare-xref}If \textit{--method} is \textit{hare} or \textit{ihare}, apply section~\ref{exclusion-hare} to the parcels to transfer. + + \subsection\label{quota-xref2}If \textit{--quota-mode} is \textit{ers97}, and there are no elected candidates, recalculate the quota according to section~\ref{quota}. + + \subsection\label{trad-exclusion-after-do}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-3}This is the \textit{end of a stage}. Return to subsection~\ref{exclusion-single-stage-after}. + + %\section{ERS97/ERS76 vote required for election}\label{ers-vre} + %\subsection\label{ers-vre-apply}This section applies in + %subsection~\ref{ers-vre-xref1-s}\ref{ers-vre-xref1-p}\ref{ers-vre-xref1-sp}\ref{ers-vre-xref1} + %subsection \ref{ers-vre-xref1-s}\ref{ers-vre-xref2-p}\ref{ers-vre-xref2}, + %if \textit{--quota-mode} is \textit{ers97} or \textit{ers76}, to calculate the \textit{vote required for election}. + %\subsection To calculate the vote required for election, add: + %\subsectionc\paragraph the sum of all continuing candidates' progress totals, plus + %\subsectionc\paragraph the sum of all excluded candidates' progress totals, plus + %\subsectionc\paragraph the total of any undistributed surpluses. + %\subsectionc Divide the sum by 1 more than the number of remaining vacancies. The quotient is the \defn{vote required for election}. + + \subpart{Surplus distribution—Gregory method} + + \section{Weighted inclusive Gregory method}\label{surplus-wig} + + \subsection This section applies in subsection~\ref{trad-surplus-do}\ref{surplus-wig-xref}, when \textit{--method} is \textit{wig}, to distribute the surplus of an elected candidate. + + \subsection\label{surplus-wig-sf}\paragraph If \textit{--papers} is \textit{both}, divide the elected candidate's surplus by their progress total. + + \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. + + \subsection\paragraph If \textit{--round-surplus-fractions} is disabled, the quotient is the \defn{surplus fraction}. + + \subsectionc\paragraph If \textit{--round-surplus-fractions} is enabled and $n$ decimal places are requested, truncate the quotient to $n$ decimal places. The result is the \defn{surplus fraction}. + + \subsection However, if the surplus fraction would be greater than 1, it is instead 1. + + \subsection\label{surplus-wig-parcel-xref}\paragraph If \textit{--round-subtransfers} is \textit{single_step} or \textit{per_ballot}, apply subsection~\ref{surplus-wig-parcel} to all of the elected candidate's parcels at once. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_value}: + + \paragraphc\subparagraph Aggregate the elected candidate's parcels, in the order each was received, into 1 combined parcel for each value. + + \paragraphc\subparagraph Apply subsection~\ref{surplus-wig-parcel} to each combined parcel in turn, in descending order of value. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_parcel}, apply subsection~\ref{surplus-wig-parcel} to each of the elected candidate's parcels in turn, in the order each parcel was received by the excluded candidate. + + \subheading{Subtransfer of 1 or more parcels} + + \subsection\label{surplus-wig-parcel}This subsection applies to transfer 1 or more parcels as described in subsection~\ref{surplus-wig-parcel-xref}. + + \subsectionc\paragraph For each of those parcels: + + \paragraphc\subparagraph Multiply the parcel's value (the \defn{original value}) by the surplus fraction. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-values} is disabled, the product is the \defn{continued value}. + + \subparagraphc\subsubparagraph If \textit{--round-values} is enabled and $n$ decimal places are requested, truncate the product to $n$ decimal places. The result is the \defn{continued value}. + + \paragraphc\subparagraph Take the transferable ballots in the parcel, in the order each was added to the parcel. Sort them into further parcels, of value equal to the continued value, according to next available preference. + + \paragraphc\subparagraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph For each continuing candidate:\nobreakpar + + \paragraphc\subparagraph\label{surplus-wig-votes}\subsubparagraph If \textit{--round-subtransfers} is \textit{per_ballot}, for each further parcel transferred to the continuing candidate, multiply the number of ballots in the further parcel by the continued value, and sum the products. + + \subparagraphc\subsubparagraph If \textit{--round-subtransfers} is not \textit{per_ballot}: + + \subsubparagraphc\subsubsubparagraph For each further parcel transferred to the continuing candidate, multiply the number of ballots in the further parcel by the original value, and sum the products. + + \subsubparagraphc\subsubsubparagraph Multiply the sum by the surplus fraction. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-votes} is disabled, credit the continuing candidate with votes equal to the result in subparagraph~\ref{surplus-wig-votes}. + + \subparagraphc\subsubparagraph If \textit{--round-votes} is enabled and $n$ decimal places are requested, truncate the result in subparagraph~\ref{surplus-wig-votes} to $n$ decimal places. Credit the continuing candidate with votes equal to the result. + + \subheading{Completing the surplus distribution} + + \subsection Once all of the elected candidate's parcels have been transferred under subsection~\ref{surplus-wig-parcel-xref}, proceed to subsection~\ref{trad-surplus-after-do}. + + \section{Unweighted inclusive Gregory method}\label{surplus-uig} + + \subsection This section applies in subsection~\ref{trad-surplus-do}\ref{surplus-uig-xref}, when \textit{--method} is \textit{uig}, to distribute the surplus of an elected candidate. + + \subsection\label{uig-value-received-s}\paragraph\label{uig-value-received}If \textit{--papers} is \textit{transferable}, for each of the elected candidate's parcels, multiply the number of transferable ballots in the parcel by the parcel's value, and sum the products. If the sum is less than the elected candidate's surplus, this paragraph applies. + + \subsectionc\paragraph\label{surplus-uig-tv-p}If paragraph~\ref{uig-value-received} does not apply: + + \paragraphc\subparagraph\label{surplus-uig-tv}\subsubparagraph If \textit{--papers} is \textit{both}, divide the elected candidate's surplus by the total number of ballots in all of their parcels. + + \subparagraphc\subsubparagraph If \textit{--papers} is \textit{transferable}, divide the elected candidate's surplus by the total number of transferable ballots in all of their parcels. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-surplus-fractions} and \textit{--round-values} are disabled, the quotient is the \defn{transfer value}. + + \subparagraphc\subsubparagraph If \textit{--round-surplus-fractions} and/or \textit{--round-values} is enabled and $n$ decimal places are requested (and if both are enabled, however many decimal places is fewer), truncate the quotient to $n$ decimal places. The result is the \defn{transfer value}. + + \subsection\label{surplus-uig-parcel-xref}\paragraph If \textit{--round-subtransfers} is \textit{single_step} or \textit{per_ballot}, apply subsection~\ref{surplus-uig-parcel} to all of the elected candidate's parcels at once. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_value}: + + \paragraphc\subparagraph Aggregate the elected candidate's parcels, in the order each was received, into 1 combined parcel for each value. + + \paragraphc\subparagraph Apply subsection~\ref{surplus-uig-parcel} to each combined parcel in turn. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_parcel}, apply subsection~\ref{surplus-uig-parcel} to each of the elected candidate's parcels in turn. + + \subheading{Subtransfer of 1 or more parcels} + + \subsection\label{surplus-uig-parcel}This subsection applies to transfer 1 or more parcels as described in subsection~\ref{surplus-uig-parcel-xref}. + + \subsectionc\paragraph For each of those parcels: + + \paragraphc\subparagraph\subsubparagraph If subsection~\ref{uig-value-received-s}\ref{uig-value-received} applies, take the transferable ballots in the parcel, in the order each was added to the parcel. Sort them into further parcels of the same value, according to next available preference. + + \subparagraphc\subsubparagraph If subsection~\ref{uig-value-received-s}\ref{uig-value-received} does not apply, take the transferable ballots in the parcel, in the order each was added to the parcel. Sort them into further parcels, of value equal to the transfer value, according to next available preference. + + \paragraphc\subparagraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph For each continuing candidate: + + \paragraphc\subparagraph For each further parcel transferred to the continuing candidate, multiply the number of ballots in the further parcel by the further parcel's value, and sum the products. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-votes} is disabled, credit the continuing candidate with votes equal to the sum. + + \subparagraphc\subsubparagraph If \textit{--round-votes} is enabled and $n$ decimal places are requested, truncate the sum to $n$ decimal places. Credit the continuing candidate with votes equal to the result. + + \subheading{Completing the surplus distribution} + + \subsection Once all of the elected candidate's parcels have been transferred under subsection~\ref{surplus-uig-parcel-xref}, proceed to subsection~\ref{trad-surplus-after-do}. + + \section{Exclusive Gregory method}\label{surplus-eg} + + \subsection This section applies in subsection~\ref{trad-surplus-do}, when \textit{--method} is \textit{eg}, to distribute the surplus of an elected candidate. + + \subsection In this section, \defn{last parcel} means the the parcel most recently received by the elected candidate. + + \subsection\label{eg-value-received-s}\paragraph\label{eg-value-received}If \textit{--papers} is \textit{transferable}, multiply the number of transferable ballots in the last parcel by the last parcel's value. If the product is less than the elected candidate's surplus, this paragraph applies. + + \subsectionc\paragraph\label{surplus-eg-tv-p}If paragraph~\ref{eg-value-received} does not apply: + + \paragraphc\subparagraph\label{surplus-eg-tv}\subsubparagraph If \textit{--papers} is \textit{both}, divide the elected candidate's surplus by the number of ballots in the last parcel. + + \subparagraphc\subsubparagraph If \textit{--papers} is \textit{transferable}, divide the elected candidate's surplus by the number of transferable ballots in the last parcel. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-surplus-fractions} and \textit{--round-values} are disabled, the quotient is the \defn{transfer value}. + + \subparagraphc\subsubparagraph If \textit{--round-surplus-fractions} and/or \textit{--round-values} is enabled and $n$ decimal places are requested (and if both are enabled, however many decimal places is fewer), truncate the quotient to $n$ decimal places. The result is the \defn{transfer value}. + + \subsection\paragraph If subsection~\ref{eg-value-received-s}\ref{eg-value-received} applies, take the transferable ballots in the last parcel, in the order each was added to the parcel. Sort them into further parcels of the same value, according to next available preference. + + \subsectionc\paragraph If subsection~\ref{eg-value-received-s}\ref{eg-value-received} does not apply, take the transferable ballots in the last parcel, in the order each was added to the parcel. Sort them into further parcels, of value equal to the transfer value, according to next available preference. + + \subsection Transfer each further parcel to the corresponding continuing candidate. + + \subsection For each continuing candidate: + + \subsectionc\paragraph Multiply the number of ballots in the further parcel transferred to the continuing candidate by the further parcel's value. + + \subsectionc\paragraph\subparagraph If \textit{--round-votes} is disabled, credit the continuing candidate with votes equal to the product. + + \paragraphc\subparagraph If \textit{--round-votes} is enabled and $n$ decimal places are requested, truncate the product to $n$ decimal places. Credit the continuing candidate with votes equal to the result. + + \subsection Proceed to subsection~\ref{trad-surplus-after-do}. + + \subpart{Surplus distribution—Hare method} + + \section{Hare method generally}\label{surplus-hare} + + \subsection This section applies in subsection~\ref{trad-surplus-do}\ref{surplus-hare-xref}, when \textit{--method} is \textit{hare} or \textit{ihare}, to distribute the surplus of an elected candidate. + + \subsection\paragraph If \textit{--method} is \textit{hare}, the parcel most recently received by the elected candidate is the \defn{surplus parcel}. + + \subsectionc\paragraph If \textit{--method} is \textit{ihare}, aggregate all of the elected candidate's parcels, in the order each was received, into 1 combined parcel of value 1. The combined parcel is the \defn{surplus parcel}. + + \subsection\label{hare-surplus-do}\paragraph\label{hare-stratify-xref}If \textit{--sample} is \textit{stratify}, apply section~\ref{hare-stratify} to the surplus parcel. + + \subsectionc\paragraph\label{hare-by-order-xref}If \textit{--sample} is \textit{by_order}, apply section~\ref{hare-by-order} to the surplus parcel. + + \subsectionc\paragraph\label{hare-cincinnati-xref}If \textit{--sample} is \textit{cincinnati}, apply section~\ref{hare-cincinnati} to the surplus parcel. + + \section{Stratified sample}\label{hare-stratify} + + \subsection This section applies in subsection~\ref{hare-surplus-do}\ref{hare-stratify-xref}, when \textit{--sample} is \textit{stratify}, to transfer the surplus parcel of an elected candidate. + + \subsection If \textit{--papers} is \textit{transferable} and the number of transferable ballots in the surplus parcel is less than the surplus:\nobreakpar + + \subsectionc\paragraph Take the transferable ballots in the surplus parcel, in the order each was added to the parcel. Sort them into further parcels, each of value 1, according to next available preference. + + \subsectionc\paragraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsection\label{hare-stratify-sf-s}Otherwise: + + \subsectionc\paragraph\label{hare-stratify-sf}\subparagraph If \textit{--papers} is \textit{both}, divide the elected candidate's surplus by the number of ballots in the surplus parcel. The quotient is the \defn{surplus fraction}. + + \paragraphc\subparagraph If \textit{--papers} is \textit{transferable}, divide the elected candidate's surplus by the number of transferable ballots in the surplus parcel. The quotient is the \defn{surplus fraction}. + + \subsectionc\paragraph For each continuing candidate, multiply the number of transferable ballots in the surplus parcel with a next available preference for that continuing candidate by the surplus fraction. + + \subsectionc\paragraph Round up to the next integer so many of the quotients as necessary, and round the rest down, such that the quotients sum to the surplus fraction. + + \subsectionc\paragraph The quotients to round up are those with the greatest fractional parts. If 2 or more quotients have the same fractional part, round up the quotient of the continuing candidate(s) with the higher progress total, breaking any tie according to section~\ref{ties}. + + \subsectionc\paragraph For each continuing candidate, where $n$ is the candidate's quotient, select the $n$ last ballots in the surplus parcel with a next available preference for that continuing candidate. Make a further parcel, of value 1, of those selected ballots. + + \subsectionc\paragraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsection Proceed to subsection~\ref{trad-surplus-after-do}. + + \section{By order}\label{hare-by-order} + + \subsection This section applies in subsection~\ref{hare-surplus-do}\ref{hare-by-order-xref}, when \textit{--sample} is \textit{by_order}, to transfer the surplus parcel of an elected candidate. + + \subsection If \textit{--papers} is \textit{transferable} and the number of transferable ballots in the surplus parcel is less than the surplus: + + \subsectionc\paragraph Take the transferable ballots in the surplus parcel, in the order each was added to the parcel. Sort them into further parcels, each of value 1, according to next available preference. + + \subsectionc\paragraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsection\label{hare-by-order-elect-s} Otherwise: + + \subsectionc\paragraph If \textit{--sample-per-ballot} is disabled: + + \paragraphc\subparagraph\subsubparagraph If \textit{--papers} is \textit{both}, select the $n$ last ballots in the surplus parcel, where $n$ is the elected candidate's surplus. + + \subparagraphc\subsubparagraph If \textit{--papers} is \textit{transferable}, select the $n$ last transferable ballots in the surplus parcel, where $n$ is the elected candidate's surplus. + + \paragraphc\subparagraph Take the selected ballots, in the order each was added to the surplus parcel. Sort those that are transferable into further parcels, of value 1, according to next available preference. + + \paragraphc\subparagraph Transfer each further parcel to the corresponding continuing candidate. + + \paragraphc\subparagraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsectionc\paragraph\label{hare-by-order-elect-p}If \textit{--sample-per-ballot} is enabled: + + \paragraphc\subparagraph For each continuing candidate, prepare a further parcel of value 1. + + \paragraphc\subparagraph\label{hare-by-order-elect-sp}Repeat the following procedure until the number of ballots transferred from the surplus parcel equals the elected candidate's surplus, or until no more vacancies remain to be filled: + + \subparagraphc\subsubparagraph\subsubsubparagraph If \textit{--papers} is \textit{both}, take the ballot in the surplus parcel which was added the last. + + \subsubparagraphc\subsubsubparagraph If \textit{--papers} is \textit{transferable}, take the transferable ballot in the surplus parcel which was added the last. + + \subparagraphc\subsubparagraph If the ballot is transferable: + + \subsubparagraphc\subsubsubparagraph Sort it to the further parcel corresponding to the continuing candidate who is its next available preference. + + \subsubparagraphc\subsubsubparagraph Credit that continuing candidate with 1 vote. + + \subparagraphc\subsubparagraph\label{hare-by-order-elect}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \paragraphc\subparagraph Transfer each further parcel that is not empty to the corresponding candidate. + + \subsection Proceed to subsection~\ref{trad-surplus-after-do}. + + \section{Cincinnati method}\label{hare-cincinnati} + + \subsection This section applies in subsection~\ref{hare-surplus-do}\ref{hare-cincinnati-xref}, when \textit{--sample} is \textit{cincinnati}, to transfer the surplus parcel of an elected candidate. + + \subsection Divide the number of ballots in the surplus parcel by the elected candidate's surplus. Disregard any fraction in the quotient. The result is the \defn{skip value}. + + \subsection If \textit{--sample-per-ballot} is disabled: + + \subsectionc\paragraph\label{cincinnati1}Take the ballots in the surplus parcel, in the order each was added to the parcel. Examine every $n$-th ballot starting from the 1st, where $n$ is the skip value. Select those which are transferable, until the number of selected ballots equals the elected candidate's surplus. + + \subsectionc\paragraph If subparagraph~\ref{cincinnati1} does not select enough transferable ballots to equal the elected candidate's surplus, next examine every $n$-th ballot starting from the 2nd, then every $n$-th ballot starting from the 3rd, and so on. Continue until enough transferable ballots are selected to equal the elected candidate's surplus, or until all ballots in the surplus parcel are examined. + + \subsectionc\paragraph Take the selected ballots, in the order each was selected. Sort them into further parcels, of value 1, according to next available preference. + + \subsectionc\paragraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsection\label{hare-cincinnati-elect-s}If \textit{--sample-per-ballot} is enabled: + + \subsectionc\paragraph For each continuing candidate, prepare a further parcel of value 1. + + \subsectionc\paragraph\label{cincinnati-order}For the purpose of paragraph~\ref{cincinnati-do}, examine the ballots in the surplus parcel in the following order: + + \paragraphc\subparagraph Take the ballots in the surplus parcel, in the order each was added to the parcel. Examine every $n$-th ballot starting from the 1st, where $n$ is the skip value. + + \paragraphc\subparagraph If subparagraph~\ref{cincinnati1} does not select enough ballots to examine, next examine every $n$-th ballot starting from the 2nd, then every $n$-th ballot starting from the 3rd, and so on. + + \subsectionc\paragraph\label{cincinnati-do}Repeat the following procedure until the number of ballots transferred from the surplus parcel equals the elected candidate's surplus, until all ballots in the surplus parcel are examined, or until no more vacancies remain to be filled: + + \paragraphc\subparagraph\subsubparagraph If \textit{--papers} is \textit{both}, take the next ballot in the order given by paragraph~\ref{cincinnati-order}. + + \subparagraphc\subsubparagraph If \textit{--papers} is \textit{transferable}, take the next transferable ballot in the order given by paragraph~\ref{cincinnati-order}. + + \paragraphc\subparagraph If the ballot is transferable: + + \subparagraphc\subsubparagraph Sort it to the further parcel corresponding to the continuing candidate who is its next available preference. + + \subparagraphc\subsubparagraph Credit that continuing candidate with 1 vote. + + \paragraphc\subparagraph\label{hare-cincinnati-elect}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \subsectionc\paragraph Transfer each further parcel that is not empty to the corresponding candidate. + + \subsection Proceed to subsection~\ref{trad-surplus-after-do}. + + \subpart{Exclusion} + + \section{Gregory method}\label{exclusion-gregory} + + \subsection This section applies in subsection~\ref{trad-exclusion-do}\ref{exclusion-gregory-xref}, when \textit{--method} is \textit{wig}, \textit{uig} or \textit{eg}, to transfer 1 or more parcels from excluded candidates (the \defn{parcels to transfer}). + + \subsection\label{exclusion-gregory-parcel-xref}\paragraph If \textit{--round-subtransfers} is \textit{single_step} or \textit{per_ballot}, apply subsection~\ref{exclusion-gregory-parcel} to all of the parcels to transfer at once. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_value}: + + \paragraphc\subparagraph Aggregate the parcels to transfer, in the order each was received, into 1 combined parcel for each value. + + \paragraphc\subparagraph Apply subsection~\ref{exclusion-gregory-parcel} to each combined parcel in turn. + + \subsectionc\paragraph If \textit{--round-subtransfers} is \textit{by_parcel}, apply subsection~\ref{exclusion-gregory-parcel} to each of the parcels to transfer in turn. + + \subheading{Subtransfer of 1 or more parcels} + + \subsection\label{exclusion-gregory-parcel}This subsection applies to transfer 1 or more parcels (out of the whole set of parcels to transfer) as described in subsection~\ref{exclusion-gregory-parcel-xref}. + + \subsectionc\paragraph For each of those parcels: + + \paragraphc\subparagraph Take the transferable ballots in the parcel, in the order each was added to the parcel. Sort them into further parcels of the same value, according to next available preference. + + \paragraphc\subparagraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph For each continuing candidate: + + \paragraphc\subparagraph\label{exclusion-gregory-votes}\subsubparagraph If \textit{--round-subtransfers} is \textit{per_ballot}, for each further parcel transferred to the continuing candidate, multiply the number of ballots in the further parcel by the the further parcel's value, and sum the products. + + \subparagraphc\subsubparagraph If \textit{--round-subtransfers} is not \textit{per_ballot}: + + \subsubparagraphc\subsubsubparagraph For each further parcel transferred to the continuing candidate, multiply the number of ballots in the further parcel by the further parcel's value, and sum the products. + + \paragraphc\subparagraph\subsubparagraph If \textit{--round-votes} is disabled, credit the continuing candidate with votes equal to the result in subparagraph~\ref{exclusion-gregory-votes}. + + \subparagraphc\subsubparagraph If \textit{--round-votes} is enabled and $n$ decimal places are requested, truncate the result in subparagraph~\ref{exclusion-gregory-votes} to $n$ decimal places. Credit the continuing candidate with votes equal to the result. + + \subheading{Completing the transfer} + + \subsection Once all of the parcels to transfer have been transferred under subsection~\ref{exclusion-gregory-parcel-xref}, proceed to subsection~\ref{trad-exclusion-after-do}. + + \section{Hare method}\label{exclusion-hare} + + \subsection This section applies in subsection~\ref{trad-exclusion-do}\ref{exclusion-hare-xref}, when \textit{--method} is \textit{hare} or \textit{ihare}, to transfer 1 or more parcels from excluded candidates (the \defn{parcels to transfer}). + + \subsection If \textit{--sample-per-ballot} is disabled: + + \subsectionc\paragraph Aggregate the transferable ballots from the parcels to transfer, in the order each parcel was received. Sort them into further parcels, of value 1, according to next available preference. + + \subsectionc\paragraph Transfer each further parcel to the corresponding continuing candidate. + + \subsectionc\paragraph Credit each continuing candidate with votes equal to the number of ballots in the further parcel transferred to them. + + \subsection\label{exclusion-hare-elect-s}If \textit{--sample-per-ballot} is enabled: + + \subsectionc\paragraph For each continuing candidate, prepare a further parcel of value 1. + + \subsectionc\paragraph\label{exclusion-hare-elect-p}Aggregate the transferable ballots from the parcels to transfer, in the order each parcel was received. Sequentially for each transferable ballot: + + \paragraphc\subparagraph Sort it to the further parcel corresponding to the continuing candidate who is its next available preference. + + \paragraphc\subparagraph Credit that continuing candidate with 1 vote. + + \paragraphc\subparagraph\label{exclusion-hare-elect}Apply section~\ref{trad-elect} to elect any continuing candidates who must be elected. + + \subsectionc\paragraph Transfer each further parcel that is not empty to the corresponding candidate. + + \subsection Proceed to subsection~\ref{trad-exclusion-after-do}. + + \section{Reset and re-iterate}\label{exclusion-reset-and-reiterate} + + \subsection This section applies in subsection~\ref{exclusion-reset-and-reiterate-xref}, when \textit{--exclusion} is \textit{reset_and_reiterate}, at the exclusion of 1 or more candidates. + + \subsection Remove all parcels from all candidates, and set each candidate's progress total to 0. + + \subsection Un-elect each elected candidate, so that all previously elected candidates become continuing candidates again (but all excluded candidates remain excluded). + + \subsection Count the ballots again according to section~\ref{trad-stage1}. + + \part{Meek method} + + \section{First stage}\label{meek-stage1} + + \subsection Set the keep value of each continuing candidate to 1. + + \subsection\label{meek-distribute-xref1}Distribute the ballots in the input file to the candidates according to section~\ref{meek-distribute}. + + \subsection\label{quota-xref3}Calculate the quota according to section~\ref{quota}. + + \subsection\label{meek-elect-xref1}Apply section~\ref{meek-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-4}This is the \textit{end of a stage}. Proceed to section~\ref{meek-stage2}. + + \section{Distribution of ballots}\label{meek-distribute} + + \subsection This section applies in subsections~\ref{meek-distribute-xref1}, \ref{meek-recalc-do}\ref{meek-distribute-xref2} and \ref{meek-distribute-xref3}, to distribute the ballots in the input file to the candidates. + + \subsection Set each candidate's progress total to 0. + + \subsection For each ballot in the input file, in the order each appears: + + \subsectionc\paragraph Set the ballot's \defn{value} to 1. + + \subsectionc\paragraph For each preference listed on the ballot, from first to last: + + \paragraphc\subparagraph\label{meek-distribute-votes}\subsubparagraph Multiply the ballot's value by the corresponding candidate's keep value. + + \subparagraphc\subsubparagraph If \textit{--round-votes} is enabled, and $n$ decimal places are requested, truncate the quotient to $n$ decimal places, and if the result is inexact, add $10^{-n}$. + + \paragraphc\subparagraph Credit the candidate with votes equal to the result of subparagraph~\ref{meek-distribute-votes}. + + \paragraphc\subparagraph\label{meek-distribute-intermediate}\subsubparagraph Subtract the candidate's keep value from 1. Multiply the ballot's value by the difference. + + \subparagraphc\subsubparagraph If \textit{--round-surplus-fractions} is enabled, and $n$ decimal places are requested, truncate the quotient to $n$ decimal places, and if the result is inexact, add $10^{-n}$. + + \paragraphc\subparagraph Set the ballot's \textit{value} to the result of subparagraph~\ref{meek-distribute-intermediate}. + + \section{Election of continuing candidates}\label{meek-elect} + + \subsection This section applies in subsections~\ref{meek-elect-xref1}, \ref{meek-recalc-after} and \ref{meek-elect-xref2}, to elect any continuing candidates who must be elected. + + \subsection Declare elected any continuing candidate who meets the quota, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. + + \subheading{Early bulk election of sure winners} + + \subsection\label{meek-ebe-criteria}This subsection applies if \textit{--early-bulk-elect} is enabled, and the continuing candidates with the highest progress totals, up to the number of remaining vacancies (the \defn{leading candidates}), each have a higher progress total than: + + \subsectionc\paragraph the sum of all other continuing candidates' progress totals, plus + + \subsectionc\paragraph the sum of all excluded candidates' progress totals, plus + + \subsectionc\paragraph the total of any undistributed surpluses. + + \subsection If subsection~\ref{meek-ebe-criteria} applies, immediately declare elected each of the leading candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \section{Second or subsequent stages}\label{meek-stage2} + + \subsection If no more vacancies remain to be filled, the count is complete. + + \subsection\label{meek-defer-xref}\label{meek-recalc-xref1}Otherwise, if 1 or more candidates have surpluses which exceed the surplus tolerance under section~\ref{meek-tolerance}, and \textit{--defer-surpluses} is disabled or the distribution of surpluses cannot be deferred under section~\ref{meek-defer}, apply section~\ref{meek-recalc} to recalculate the elected candidates' keep values. + + \subsection Otherwise, if the number of continuing candidates equals the number of remaining vacancies, declare elected all continuing candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \subsection\label{meek-exclude-xref}Otherwise, perform an exclusion according to section~\ref{meek-exclude}. + + \subsection Repeat this section until the count is complete. + + \section{Surplus tolerance}\label{meek-tolerance} + + \subsection This section applies in subsections~\ref{meek-defer-xref} and \ref{meek-recalc-do}, if 1 or more candidates have surpluses, to determine if those surpluses exceed the surplus tolerance. + + \subsection If \textit{--meek-surplus-tolerance} is a percentage, $n\%$, the surpluses exceed the surplus tolerance if and only if any of the surpluses is greater than $n\%$ of the quota. + + \subsection If \textit{--meek-surplus-tolerance}, $n$, is not a percentage, the surpluses exceed the surplus tolerance if and only if the total of all surpluses is greater than $n$. + + \section{Deferring surplus distributions}\label{meek-defer} + + \subsection This section applies in subsections~\ref{meek-defer-xref} and \ref{meek-recalc-do}, if \textit{--defer-surpluses} is enabled, to determine when the distribution of surpluses must be deferred. + + \subsection If there are fewer than 2 continuing candidates, the distribution of surpluses must be deferred. + + \subsection\label{bulk-exclude-xref4-s}Otherwise, if: + + \subsectionc\paragraph the total of all undistributed surpluses is less than the difference between the progress totals of the 2 continuing candidates with the lowest progress totals, and + + \subsectionc\paragraph\label{bulk-exclude-xref4}if \textit{--bulk-exclude} is enabled and a bulk exclusion could be performed under section~\ref{bulk-exclude}, the total of all undistributed surpluses is less than the difference between the sum of the progress totals of the continuing candidates who could be bulk excluded, and the progress total of the continuing candidate with the next lowest progress total, + + \subsectionc the distribution of surpluses must be deferred. + + \subsection Otherwise, the distribution of surpluses must not be deferred. + + \section{Recalculation of keep values}\label{meek-recalc} + + \subsection This section applies in subsections~\ref{meek-recalc-xref1} to recalculate the elected candidates' keep values. + + \subsection\label{meek-recalc-do}If 1 or more candidates have surpluses which exceed the surplus tolerance under section~\ref{meek-tolerance}, and \textit{--defer-surpluses} is disabled or the distribution of surpluses cannot be deferred under section~\ref{meek-defer}: + + \subsectionc\paragraph\label{meek-recalc-formula}For each elected candidate: + + \paragraphc\subparagraph\label{meek-recalc-cand}\subsubparagraph Multiply the candidate's keep value by the quota. Divide the quotient by the candidate's progress total. + + \subparagraphc\subsubparagraph If \textit{--round-values} is enabled and $n$ decimal places are requested, truncate the quotient to $n$ decimal places, and if the result is inexact, add $10^{-n}$. + + \paragraphc\subparagraph Set the candidate's keep value to the result of subparagraph~\ref{meek-recalc-cand}. + + \subsectionc\paragraph\label{meek-distribute-xref2}Distribute the ballots in the input file to the candidates according to section~\ref{meek-distribute}. + + \subsectionc\paragraph\label{quota-xref4}Recalculate the quota according to section~\ref{quota}. + + \subsectionc\paragraph If \textit{--no-immediate-elect} is disabled, and 1 or more continuing candidates meet the quota or subsection~\ref{meek-ebe-criteria} applies, proceed immediately to subsection~\ref{meek-recalc-after}. + + \subsectionc\paragraph Otherwise, repeat this subsection until there are no surpluses exceeding the surplus tolerance under section~\ref{meek-tolerance}, or if \textit{--defer-surpluses} is enabled, the distribution of surpluses can be deferred under section~\ref{meek-defer}. + + \subsection\label{meek-recalc-after}Apply section~\ref{meek-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-5}This is the \textit{end of a stage}. Return to section~\ref{meek-stage2}. + + \section{Exclusion}\label{meek-exclude} + + \subsection This section applies in subsection~\ref{meek-exclude-xref} to exclude 1 or more continuing candidates. + + \subsection If \textit{--meek-nz-exclusion} is enabled, apply subsection~\ref{meek-recalc-do}\ref{meek-recalc-formula}. + + \subsection\label{bulk-exclude-xref3-s}When this section applies:\nobreakpar + + \subsectionc\paragraph If it is the first time this section is applied, and 1 or more continuing candidates have a progress total equal to or lower than the value of \textit{--min-threshold}, apply the following procedure to all those candidates. + + \subsectionc\paragraph\label{bulk-exclude-xref3}Otherwise, if \textit{--bulk-exclude} is enabled and a bulk exclusion can be performed under section~\ref{bulk-exclude}, apply the following procedure to the candidates to be bulk excluded. + + \subsectionc\paragraph Otherwise, apply the following procedure to the continuing candidate with the lowest progress total, breaking any tie according to section~\ref{ties}. + + \subsection Declare that candidate, or those candidates, excluded, and set their keep values to 0. + + \subsection If \textit{--early-bulk-elect} is enabled, and the number of continuing candidates equals the number of remaining vacancies, declare elected all continuing candidates, one by one in descending order of progress total, breaking any tie according to section~\ref{ties}. The count is then complete. + + \subsection\label{meek-distribute-xref3}Distribute the ballots in the input file to the candidates according to section~\ref{meek-distribute}. + + \subsection\label{quota-xref5}Recalculate the quota according to section~\ref{quota}. + + \subsection\label{meek-elect-xref2}Apply section~\ref{meek-elect} to elect any continuing candidates who must be elected. + + \subsection\label{end-stage-6}This is the \textit{end of a stage}. Return to section~\ref{meek-stage2}. + + \part{Provisions applying to all methods} + + \subpart{General provisions} + + \section{Calculation of quota}\label{quota} + + \subsection This section applies in subsections~\ref{quota-xref1}, \ref{quota-xref7}, \ref{ers-vre-xref1-s}\ref{quota-xref6-p}\ref{quota-xref6}, \ref{quota-xref2}, \ref{quota-xref3}, \ref{meek-recalc-do}\ref{quota-xref4} and \ref{quota-xref5}, to calculate the quota. + + \subsection\paragraph If \textit{--quota-mode} is \textit{static}, \textit{ers97}, \textit{ers76} or \textit{dynamic_by_total}: + + \paragraphc\subparagraph If \textit{--quota} is \textit{droop} or \textit{droop_exact}, divide the sum of all candidates' progress totals by 1 more than the number of vacancies. + + \paragraphc\subparagraph If \textit{--quota} is \textit{hare} or \textit{hare_exact}, divide the sum of all candidates' progress totals by the number of vacancies. + + \subsectionc\paragraph If \textit{--quota-mode} is \textit{dynamic_by_active}: + + \paragraphc\subparagraph\label{quota-active-vote}Add: + + \subparagraphc\subsubparagraph the sum of all continuing candidates' progress totals, plus + + \subparagraphc\subsubparagraph the sum of all excluded candidates' progress totals, plus + + \subparagraphc\subsubparagraph the total of any undistributed surpluses. + + \paragraphc\subparagraph If \textit{--quota} is \textit{droop} or \textit{droop_exact}, divide the sum in sub-paragraph~\ref{quota-active-vote} by 1 more than the number of remaining vacancies. + + \paragraphc\subparagraph If \textit{--quota} is \textit{hare} or \textit{hare_exact}, divide the sum in sub-paragraph~\ref{quota-active-vote} by the number of remaining vacancies. + + \subsection\paragraph If \textit{--round-quota} is disabled, the quotient is the \defn{quota}. + + \subsectionc\paragraph If \textit{--round-quota} is enabled and $n$ decimal places are requested: + + \paragraphc\subparagraph If \textit{--quota} is \textit{droop} or \textit{hare}, truncate the quotient to $n$ decimal places and add $10^{-n}$. The result is the \defn{quota}. + + \paragraphc\subparagraph If \textit{--quota} is \textit{droop_exact} or \textit{hare_exact}, truncate the quotient to $n$ decimal places. If the result is exact, it is the \defn{quota}. Otherwise, add $10^{-n}$, and the result is the \defn{quota}. + + \section{Bulk exclusion}\label{bulk-exclude} + + \subsection This section applies in subsections~\ref{bulk-exclude-xref1-s}\ref{bulk-exclude-xref1}, \ref{bulk-exclude-xref2-s}\ref{bulk-exclude-xref2}, \ref{bulk-exclude-xref4-s}\ref{bulk-exclude-xref4} and \ref{bulk-exclude-xref3-s}\ref{bulk-exclude-xref3}, if \textit{--bulk-exclude} is enabled, to determine which candidates (if any) can be bulk excluded. + + \subsection In a bulk exclusion, select for exclusion as many of the continuing candidates with the lowest progress totals as possible, provided that: + + \subsectionc\paragraph enough other continuing candidates remain to fill all remaining vacancies, and + + \subsectionc\paragraph the sum of the progress totals of the selected candidates, plus the total of any undistributed surpluses, is lower than the progress total of the candidate with the next lowest progress total. + % We call it an "undistributed" rather than "deferred" surplus, since this subsection is engaged when determining whether to defer a surplus! + + \subpart{Tie breaking} + + \section{Tie breaking generally}\label{ties} + + \subsection In order to break a tie, apply each strategy listed in \textit{--ties}, in the order listed, until a strategy is able to break the tie. + + \subsection If the strategy is \textit{backwards}, apply section~\ref{tie-backwards}. + + \subsection If the strategy is \textit{forwards}, apply section~\ref{tie-forwards}. + + \subsection If the strategy is \textit{random}, apply section~\ref{tie-random}. + + \subsection If the strategy is \textit{prompt}, apply section~\ref{tie-prompt}. + + \section{Backwards tie breaking}\label{tie-backwards} + + \subsection\label{tie-backwards-hi}In the \textit{backwards} strategy, if 2 or more candidates (\defn{tied candidates}) have the equal highest progress total, and it is necessary to break the tie:\nobreakpar + + \subsectionc\paragraph\label{tie-backwards-hi1}If 1 tied candidate had a higher progress total than any other tied candidate at the end of the previous stage, select that candidate. + + \subsectionc\paragraph\label{tie-backwards-hi2}If 2 or more tied candidates had (out of the tied candidates) the equal highest progress total at the end of the previous stage, each other tied candidate is no longer considered in the tie, and this subsection is applied to each preceding stage until 1 candidate is selected. + + \subsectionc\paragraph If no candidate can be selected under paragraphs~\ref{tie-backwards-hi1} and \ref{tie-backwards-hi2}, the tie cannot be broken under the \textit{backwards} strategy. + + \subsection\label{tie-backwards-lo}In the \textit{backwards} strategy, if 2 or more candidates (\defn{tied candidates}) have the equal lowest progress total, and it is necessary to break the tie: + + \subsectionc\paragraph\label{tie-backwards-lo1}If 1 tied candidate had a lower progress total than any other tied candidate at the end of the previous stage, select that candidate. + + \subsectionc\paragraph\label{tie-backwards-lo2}If 2 or more tied candidates had (out of the tied candidates) the equal lowest progress total at the end of the previous stage, each other tied candidate is no longer considered in the tie, and this subsection is applied to each preceding stage until 1 candidate is selected. + + \subsectionc\paragraph If no candidate can be selected under paragraphs~\ref{tie-backwards-lo1} and \ref{tie-backwards-lo2}, the tie cannot be broken under the \textit{backwards} strategy. + + \section{Forwards tie breaking}\label{tie-forwards} + + \subsection\label{tie-forwards-hi}In the \textit{forwards} strategy, if 2 or more candidates (\defn{tied candidates}) have the equal highest progress total, and it is necessary to break the tie: + + \subsectionc\paragraph\label{tie-forwards-hi1}If 1 tied candidate had a higher progress total than any other tied candidate at the end of the first stage, select that candidate. + + \subsectionc\paragraph\label{tie-forwards-hi2}If 2 or more tied candidates had (out of the tied candidates) the equal highest progress total at the end of the first stage, each other tied candidate is no longer considered in the tie, and this subsection is applied to each subsequent stage until 1 candidate is selected. + + \subsectionc\paragraph If no candidate can be selected under paragraphs~\ref{tie-forwards-hi1} and \ref{tie-forwards-hi2}, the tie cannot be broken under the \textit{forwards} strategy. + + \subsection\label{tie-forwards-lo}In the \textit{forwards} strategy, if 2 or more candidates (\defn{tied candidates}) have the equal lowest progress total, and it is necessary to break the tie: + + \subsectionc\paragraph\label{tie-forwards-lo1}If 1 tied candidate had a lower progress total than any other tied candidate at the end of the first stage, select that candidate. + + \subsectionc\paragraph\label{tie-forwards-lo2}If 2 or more tied candidates had (out of the tied candidates) the equal lowest progress total at the end of the first stage, each other tied candidate is no longer considered in the tie, and this subsection is applied to each subsequent stage until 1 candidate is selected. + + \subsectionc\paragraph If no candidate can be selected under paragraphs~\ref{tie-forwards-lo1} and \ref{tie-forwards-lo2}, the tie cannot be broken under the \textit{forwards} strategy. + + \section{Random tie breaking}\label{tie-random} + + \subsection In the \textit{random} strategy, a tie between 2 or more candidates is to be broken at random. + + \subsection The method of breaking the tie at random is implementation-defined. + + \section{Tie breaking by prompt}\label{tie-prompt} + + \subsection In the \textit{prompt} strategy, a tie between 2 or more candidates is to be broken as directed by the user. + + \subpart{Numeric representation} + + %\section{Numeric representation generally} + + \section{Rational arithmetic} + + \subsection This section applies when \textit{--numbers} is \textit{rational}. + + \subsection When this section applies, unless otherwise specified, all calculations must be performed without rounding, and the result represented exactly, as a fraction if necessary. + + \section{Fixed-point arithmetic} + + \subsection This section applies when \textit{--numbers} is \textit{fixed}. + + \subsection When this section applies, unless otherwise specified: + + \subsectionc\paragraph In subsections~\ref{surplus-wig-sf}, \ref{uig-value-received-s}\ref{surplus-uig-tv-p}\ref{surplus-uig-tv}, \ref{eg-value-received-s}\ref{surplus-eg-tv-p}\ref{surplus-eg-tv} and \ref{hare-stratify-sf-s}\ref{hare-stratify-sf} (in the calculation of the surplus fraction or transfer value), the calculation must be performed without rounding, and the quotient represented exactly, as a fraction if necessary. + + \subsectionc\paragraph For all other calculations, the result must be truncated to $n$ decimal places, where $n$ is given by \textit{--decimals}. + + \section{Guarded fixed-point arithmetic} + + \subsection This section applies when \textit{--numbers} is \textit{gfixed}. + + \subsection When this section applies, unless otherwise specified: + + \subsectionc\paragraph In subsections~\ref{surplus-wig-sf}, \ref{uig-value-received-s}\ref{surplus-uig-tv-p}\ref{surplus-uig-tv}, \ref{eg-value-received-s}\ref{surplus-eg-tv-p}\ref{surplus-eg-tv} and \ref{hare-stratify-sf-s}\ref{hare-stratify-sf} (in the calculation of the surplus fraction or transfer value), the calculation must be performed without rounding, and the quotient represented exactly, as a fraction if necessary. + + \subsectionc\paragraph For all other calculations, the result must be truncated to $2n$ decimal places, where $n$ is given by \textit{--decimals}. + + \subsection When this section applies, 2 numbers are considered equal, and neither greater or lesser than the other, if the difference between the 2 numbers is less than $\frac{10^{-n}}{2}$. + + \section{64-bit floating-point arithmetic} + + \subsection This section applies when \textit{--numbers} is \textit{float64}. + + \subsection When this section applies, unless otherwise specified: + + \subsectionc\paragraph In subsections~\ref{surplus-wig-sf}, \ref{uig-value-received-s}\ref{surplus-uig-tv-p}\ref{surplus-uig-tv}, \ref{eg-value-received-s}\ref{surplus-eg-tv-p}\ref{surplus-eg-tv} and \ref{hare-stratify-sf-s}\ref{hare-stratify-sf} (in the calculation of the surplus fraction or transfer value), the calculation must be performed without rounding, and the quotient represented exactly, as a fraction if necessary. + + \subsectionc\paragraph For all other calculations, the calculation must be performed in accordance with the \textit{IEEE Standard for Floating-Point Arithmetic} (IEEE 754) for double-precision binary floating-point (binary64) numbers, and the result represented as a binary64 number. + + \subpart{Interpretation} + + \section{Definitions} + + \subsection\defn{ballot} means a record of a voter's preferences. + + \subsection\defn{continuing candidate} means a candidate who is not withdrawn, elected or excluded. + + \subsection\defn{end of a stage}: see subsections~\ref{end-stage-1}, \ref{end-stage-2}, \ref{end-stage-3}, \ref{end-stage-4}, \ref{end-stage-5} and \ref{end-stage-6}. + + \subsection\defn{meet}: a continuing candidate \textit{meets} the quota (or vote required for election, as the case requires): + + \subsectionc\paragraph if \textit{--quota-criterion} is \textit{gt}: if the candidate's progress total is higher than the quota (or vote required for election), + + \subsectionc\paragraph if \textit{--quota-criterion} is \textit{geq}: if the candidate's progress total is higher than or equal to the quota (or vote required for election). + + %\subsection\defn{meet the vote required for election}: if \textit{--quota-mode} is \textit{ers97} or \textit{ers76}, a continuing candidate \textit{meets the vote required for election}: + %\subsectionc\paragraph if \textit{--quota-criterion} is \textit{gt}: if the candidate's progress total is higher than the vote required for election, + %\subsectionc\paragraph if \textit{--quota-criterion} is \textit{geq}: if the candidate's progress total is higher than or equal to the vote required for election. + + \subsection\defn{next available preference}, of a ballot, means the continuing candidate highest on the ballot's preferences, if there is such a candidate. + + \subsection\defn{non-transferable ballot} means a ballot which does not have a next available preference. + + \subsection\defn{parcel} means a sequence of ballots, with an associated value. + + \subsection\defn{progress total}, of a candidate, means the total votes credited to the candidate. + + \subsection\defn{quota} means the quota calculated in section~\ref{quota}. + + \subsection\defn{surplus}, of an elected candidate who has a progress total higher than the quota, means the difference between the candidate's progress total and the quota. + + \subsection\defn{transferable ballot} means a ballot which has a next available preference. + + %\subsection\defn{vote required for election}: see section~\ref{ers-vre}. +\end{document} diff --git a/docs/options.md b/docs/options.md index 4f23885..c94e02a 100644 --- a/docs/options.md +++ b/docs/options.md @@ -1,5 +1,7 @@ # Options and advanced options +**Note:** OpenTally is in the process of transitioning to being defined by formal functional specifications. A draft of the functional specifications can be found [here]({{ site.baseurl }}/docs/FnSpecs.pdf), which describes many of these options in greater detail. + ## Preset The preset dropdown allows you to choose from a hardcoded list of preloaded STV counting rules. These are: diff --git a/scripts/build_homepage.sh b/scripts/build_homepage.sh index 8cb4722..ba37a93 100755 --- a/scripts/build_homepage.sh +++ b/scripts/build_homepage.sh @@ -5,3 +5,4 @@ DESTDIR='/home/runassudo/Documents/Work/School Cloud Data/unenc/public/www/opent cd homepage bundle exec jekyll build -d "$DESTDIR" cd .. +cp docs/FnSpecs.pdf "$DESTDIR/docs"