 |
STAR++ v0.2.2
C++ implementation of STAR voting
|
|
STAR++ v0.2.2
C++ implementation of STAR voting
|
The Calculator class provides the means to determine the result of an election. More...
#include <star/calculator.h>
Public Types | |
| enum | Option { NoOptions = 0x00 , AllowTrueTies = 0x01 , CondorcetProtocol = 0x02 , DefactoWinner = 0x04 } |
| typedef QFlags< Option > | Options |
Signals | |
| void | calculationDetail (const QString &detail) const |
Public Member Functions | |
| Calculator (const Election *election=nullptr) | |
| ~Calculator () | |
| ElectionResult | calculateResult () |
| const Election * | election () const |
| Options | options () const |
| void | setElection (const Election *election) |
| void | setOptions (Options options) |
A Calculator acts as the actual apparatus through which election results are computed. Once an Election has been prepared, its outcome can be realized by constructing a Calculator instance for it via Calculator(const Election*), followed by calling calculateResult().
If running multiple elections, there is no need to create a Calculator for each one, as a single Calculator can be reused for subsequent elections by using setElection().
A Calculator features several configurable options that alter some aspects of winner determination. They can be set through setOptions() and queried by options(). Some of these options are directly sanctioned by the STAR voting project, while others are specific to this library; however, STAR voting ultimately allows alteration of fine election details as long as all parties involved agree upon them before an election is run.
NoOptions This is the default and leads Calculator to elect candidates by exactly following standard STAR procedure.
AllowTrueTies By default, the STAR election procedure will resort to breaking ties randomly if all other tiebreak procedures have been exhausted and a tie still remains. If this isn't acceptable for your particular purposes, this option instead leaves the current seat unfilled and ends the election prematurely if this situation occurs.
While not standard, this option is recognized by the STAR project.
CondorcetProtocol This adds the "Condorcet Protocol" as a fallback tiebreaker that is used before resorting to a random tiebreaker during a tie. First, this attempts to break the tie by checking which candidate had highest preference count (preferred the most times total) among all their head-to-head matchups. Then, if that fails, it tries to break the tie by checking which candidate had the greatest preference margin (their total preference count minus the total number of times they were preferred against).
While not standard, and also not recommended due to the added complexity, this option is recognized by the STAR project.
DefactoWinner This option was specifically created to solve a specific issue that is more likely to occur with smaller elections when AllowTrueTies is also turned on.
It it quite common that the first candidate seeded into the runoff for a given seat will end up winning that seat; however, if an unresolvable tie for second seed occurs then the runoff never happens and so that fact ends up being irrelevant. But because of that same fact, if a runoff was evaluated by hand between the first seed and each of the remainder stuck battling for second seed, one will find that much of the time the first seed wins against all of them.
Ending the election prematurely in this circumstance would be unfortunate, since it is essentially known that the first seed would win the seat anyway.
Enabling this option avoids the issue by simulating the runoffs between the first seed and each of the candidates tied for second seed. If the first does win all of the simulations, then they are declared the winner of that seat.
This option is completely non-standard and not recognized by the STAR project.
The Calculator::Options type is a typedef for QFlags< Calculator::Option>. It stores an OR combination of Calculator::Option values.
This enum represents the various rules that can be applied to a Calculator when determining the results of an Election.
| Star::Calculator::Calculator | ( | const Election * | election = nullptr | ) |
Creates a calculator set to evaluate the Election election.
|
default |
Destroys the calculator
| ElectionResult Star::Calculator::calculateResult | ( | ) |
Determines the outcome of the currently set election in accordance with the current options set and returns it as an ElectionResult.
If no election is set or the current one is invalid, a null ElectionResult is returned.
|
signal |
This signal is emitted at various points during the execution of calculateResult().
It provides numerous details about the entire calculation process that are useful for logging and gaining insight into the STAR election procedure.
| const Election * Star::Calculator::election | ( | ) | const |
Returns the current election that the calculator is set to evaluate, or nullptr if none is set.
| Calculator::Options Star::Calculator::options | ( | ) | const |
Returns the current option set of the calculator.
| void Star::Calculator::setElection | ( | const Election * | election | ) |
Sets the calculator to evaluate the Election election.
| void Star::Calculator::setOptions | ( | Options | options | ) |
Sets the calculator options set to options.
1.9.8