//  VoteFairRanking.cpp or votefair_ranking.cpp
//
//  This application calculates VoteFair Ranking results.
//  Specifically it calculates:
//
//  * VoteFair popularity ranking
//
//  * VoteFair representation ranking  
//
//  * VoteFair party ranking  
//
//  VoteFair Ranking is described at www.VoteFair.org and in the book
//  "Ending The Hidden Unfairness In U.S. Elections" by Richard Fobes.
//  The components of VoteFair Ranking that are implemented here are
//  briefly described below in the ABOUT section.  Additional details
//  are explained within the source code.
//
//
// -----------------------------------------------
//
//  COPYRIGHT & LICENSE
//
//  (c) Copyright 1991 through 2019 by Richard Fobes at www.VoteFair.org.
//  You can redistribute and/or modify this VoteFairRanking software
//  under the MIT software license terms that appear in the source-code file.
//  Also a copy of the license is included in the LICENSE file.
//  Conversion of this code into another programming language
//  is also covered by these license terms.
//
//
// -----------------------------------------------
//
//  VERSION
//
//  Version 6.00 - In 2019 Richard Fobes ported
//  portions of the Perl library version (5.00)
//  into this standalone C++ version.
//  See the Perl-version history for earlier
//  developments.
//
//
// -----------------------------------------------
//
//  USAGE
//
//  The following sample code executes this software under a typical
//  Windows environment with the g++ compiler and the mingw32 library
//  already installed.
//
//      path=C:\Program Files (x86)\mingw-w64\i686-8.1.0-posix-dwarf-rt_v6-rev0\mingw32\bin\
//
//      g++ votefair_ranking.cpp -o votefair_ranking
//
//      .\votefair_ranking < input_votefair_ranking_case_123.txt > output_votefair_ranking_case_123.txt
//
//  This usage assumes that file input_votefair_ranking_case_123.txt
//  contains appropriately formatted election/survey/poll data for
//  case numbered 123, and it writes the coded results to file
//  output_votefair_ranking_case_123.txt.
//
//  Typically the input file is generated by other software, and
//  typically the output file is used as input to other software.
//  An example of such software is the "VoteFair-polls" code on
//  GitHub (in the CPSolver repository).
//
//  The mathematical algorithms of VoteFair Ranking are in the
//  public domain.
//
//
// -----------------------------------------------
//
//  ABOUT
//
//  This software calculates VoteFair Ranking results.  The portions
//  of VoteFair Ranking implemented here are:
//
//  * VoteFair popularity ranking.  This voting method calculates the
//  full popularity ranking of all candidates (or choices in the case
//  of a survey) from most popular and second-most popular down to
//  least popular.  It uses the preference information collected on
//  1-2-3 ballots or ranked ballots (or any equivalent way of
//  expressing "ranked" preferences).  When a single position
//  is being filled, the most popular candidate is declared the winner.
//  This calculation method is mathematically equivalent to the
//  Condorcet-Kemeny election method.  See below about very rare cases
//  when this software can yield results that do not match VoteFair
//  popularity ranking.
//
//  * VoteFair representation ranking.  This voting method is used to
//  elect a second candidate who represents the voters who are not
//  well-represented by the most-popular candidate, or to fill
//  multiple board-of-director positions, or to choose a second
//  simultaneous activity in addition to the most popular activity.
//  This method reduces the influence of the voters who are already
//  well-represented by the most popular candidate (or choice), and
//  it does so in a way that protects against strategic voting.  If
//  instead the second-most popular candidate as identified by
//  VoteFair popularity ranking were chosen, the same voters who
//  prefer the first winner also can determine the second winner, and
//  this can leave large numbers of other voters unrepresented.
//  Additional levels of representation ranking can be used to fill
//  additional seats, although VoteFair partial-proportional ranking
//  should be used instead if "proportional representation" of
//  political parties is needed, especially for the purpose of
//  defeating attempts to gerrymander district boundaries.
//  This ranking provides "proportional representation."  It ignores
//  political-party associations, yet when used in a governmental
//  election the winners are typically from different political
//  parties (unless just one party offers great candidates and the
//  other parties offer bad candidates).
//
//  * VoteFair party ranking.  This voting method ranks political
//  parties according to a different kind of "popularity".  The
//  results can be used in high-stakes elections to limit the number
//  of candidates allowed by each party.  In such cases the two or
//  three political parties that are ranked highest can be limited to
//  offering just two candidates from each party, and lower-ranked
//  parties can be allowed to offer one candidate each, and any
//  additional parties can be prohibited from offering any candidate
//  (because those parties are too unpopular and too
//  unrepresentative).  Such limits have not been needed in the past
//  because the fear of vote splitting has limited each political
//  party to offering just one candidate in each contest.
//
//  Note that VoteFair partial-proportional ranking is not calculated
//  by this software because it requires knowing the results of many
//  elections, and because those results can be calculated using a
//  simple spreadsheet.
//
//  In addition to being useful for elections, VoteFair Ranking also
//  is useful for calculating results for surveys and polls, ranking
//  the popularity of songs and movies, and much more.
//
//  In mathematical terms, VoteFair Ranking is useful for doing
//  "combinatorial optimization" and may be useful for solving the
//  "linear ordering problem".  See Wikipedia for details about these
//  terms.
//
//  VoteFair popularity ranking calculations are mathematically
//  equivalent to the Condorcet-Kemeny vote-counting method.
//
//  Clarification: For reasons of computation time, there are some
//  very rare cases for which this software can produce results that
//  differ from full VoteFair popularity ranking results.
//  These exceptions involve more choices (candidates) than the
//  value of the constant named "global_check_all_scores_choice_limit",
//  which currently has a default value of 6.
//  In those rare cases, the software estimates which top (6) choices
//  are the most popular, and then does the full VoteFair popularity
//  ranking to determine which of those top choices is most popular.
//  The rare cases in which the estimation method produces different
//  results involve one or more rock-paper-scissors-like cycles
//  that include the top choices, which is a rare combination.
//  As an analogy, those cases are like finding the highest
//  sand dune in a desert, whereas most cases are like finding
//  the highest mountain peak in a mountain range.
//  As the number of ballots increases (such as beyond 50 ballots),
//  the likelihood of such cycles greatly decreases.
//  If this difference is important, the value of the constant
//  "global_check_all_scores_choice_limit" can be increased, but
//  that change will dramatically increase calculation time,
//  to the point of requiring years of computation time for values
//  even as small as 20.  Therefore, values larger than 12 are not
//  recommended.
//
//  Additional details about the calculations appear within comments
//  in the source-code file.
//
// -----------------------------------------------