votefair_ranking.cpp

//  VoteFairRanking.cpp or votefair_ranking.cpp
//
//  This application calculates VoteFair Ranking
//  results.  Specifically it calculates:
//
//  * VoteFair popularity ranking
//
//  * VoteFair representation ranking  
//
//  * VoteFair party ranking  
//
//  It does not calculate VoteFair
//  partial-proportional ranking because that
//  requires additional information, and the
//  method is simple enough to do using a
//  spreadsheet.
//
//  It does not calculate VoteFair Negotiation
//  Ranking (for use among legislators in a
//  legislature or parliament) because that method
//  must be done interactively.
//
//  For use when voters want a simple
//  single-winner method that is better than RCIPE
//  but not as good as VoteFair popularity
//  ranking, this application also calculates:
//
//  * Instant Pairwise Elimination (IPE)
//
//
// -----------------------------------------------
//
//  COPYRIGHT & LICENSE
//
//  (c) Copyright 1991 through 2022 by Richard
//  Fobes at www.VoteFair.org.  You can
//  redistribute and/or modify this
//  VoteFairRanking software under the MIT
//  software license terms that appear below.
//  (Also a copy of the license is included in the
//  "license" file.)
//
//  Conversion of this code into another
//  programming language is also covered by the
//  above 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.
//
//  Version 6.10 - In 2020 Richard Fobes added
//  functions to calculate methods that eliminate
//  one choice (candidate) at a time.
//
//  Version 6.20 - In early 2021 Richard Fobes
//  refactored the subroutines that calculate
//  one-by-one elimination methods.
//
//  Version 6.30 - In late May 2022 Richard Fobes
//  removed the code that calculated IRV and
//  RCIPE because those methods are now
//  calcluated in program: rcipe_stv.cpp
//  Also removed were calculations for methods
//  that had been added for comparison purposes.
//
//  Version 6.31 - In June 2022 removed a
//  potential bug.
//
// -----------------------------------------------
//
//  USAGE
//
//  This file (currently named
//  votefair_ranking.cpp or VoteFairRanking.cpp)
//  does the calculations for VoteFair 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.
//
//  The following sample code compiles and
//  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.
//
//  For detailed descriptions of VoteFair Ranking, see
//  www.VoteFair.org or the book "Ending The Hidden Unfairness In
//  U.S. Elections" by Richard Fobes.
//
//  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
//  within some of the function code below.
//
//
// -----------------------------------------------
//
//  LICENSE
//
//  This VoteFairRanking software is licensed
//  under the following MIT License terms.
//
//  MIT License for VoteFairRanking.cpp (or votefair_ranking.cpp)
//
//  Copyright (c) 2019 through 2022 by Richard Fobes at VoteFair.org
//
//  Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
//
//  The above copyright notice and this permission notice shall be included in all
//  copies or substantial portions of the Software.
//
//  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
//  SOFTWARE.
//
//
// -----------------------------------------------
//
//      IMPORTANT NOTE TO CODERS!
//
//  If you offer improvements to this code,
//  please use conventions that are easy to
//  convert into other programming languages.
//
//  Also, resist the temptation to add the
//  handling of choice names and any other
//  text that appears on ballots.  The
//  absense of that text makes it obvious
//  that this code is completely unbiased --
//  because the questions and choices are
//  identified by simple numbers, which
//  cannot be associated with specific
//  political positions.
//
//
// -----------------------------------------------


// -----------------------------------------------
//  Begin code.
// -----------------------------------------------


// -----------------------------------------------
//  Specify libraries needed.

#include <iostream>
#include <fstream>
#include <string>
#include <cstring>
#include <map>
#include <algorithm>
#include <cstdio>
#include <vector>


// -----------------------------------------------
//  Declare constants, specifically the true and
//  false values.  These are used instead of
//  language-specific codes because different
//  programming languages use different
//  conventions for their true/false logic, and
//  this approach allows for easier conversion
//  between programming languages).

const int global_true = 1 ;
const int global_false = 0 ;


// -----------------------------------------------
//  Declare global variables.


const int global_maximum_vote_info_list_length = 200000 ;
const int global_maximum_question_number = 20 ;
const int global_maximum_choice_number = 100 ;
const int global_maximum_twice_highest_possible_score = 999999 ;
const int global_maximum_output_results_length = 2000 ;
const int global_default_representation_levels_requested = 6 ;
const int global_limit_on_representation_rank_levels = 6 ;


//  Declare a list that stores the number of
//  choices for each question.

int global_choice_count_for_question[ 21 ] ;


//  Declare a variable for how many choices
//  can be handled for each question,
//  and declare lists that have that length.

int global_plurality_count_for_actual_choice[ 101 ] ;
int global_popularity_ranking_for_actual_choice[ 101 ] ;
int global_full_popularity_ranking_for_actual_choice[ 101 ] ;
int global_representation_ranking_for_actual_choice[ 101 ] ;
int global_full_representation_ranking_for_actual_choice[ 101 ] ;
int global_party_ranking_for_actual_choice[ 101 ] ;
int global_adjusted_choice_for_actual_choice[ 101 ] ;
int global_actual_choice_for_adjusted_choice[ 101 ] ;
int global_using_choice[ 101 ] ;
int global_ballot_preference_for_choice[ 101 ] ;
int global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ 101 ] ;
int global_adjusted_ranking_for_adjusted_choice_top_down_version[ 101 ] ;
int global_pair_counter_offset_for_first_adjusted_choice[ 101 ] ;
int global_log_info_choice_at_position[ 101 ] ;
int global_rank_to_normalize_for_adjusted_choice[ 101 ] ;
int global_normalized_ranking_level_for_adjusted_choice[ 101 ] ;
int global_choice_score_popularity_rank_for_actual_choice[ 101 ] ;
int global_insertion_sort_popularity_rank_for_actual_choice[ 101 ] ;
int global_sortable_sequence_used_during_normalization [ 101 ] ;
int global_tally_uses_of_choice_number[ 101 ] ;
int global_actual_choice_at_popularity_list_sequence_position[ 101 ] ;


//  Declare input-related and output-related lists.
//  Allow extra space for codes at end.

int global_vote_info_list[ 200005 ] ;
int global_output_results[ 2005 ] ;


//  Declare pairwise lists.

int global_adjusted_first_choice_number_in_pair[ 2001 ] ;
int global_adjusted_second_choice_number_in_pair[ 2001 ] ;
int global_tally_first_over_second_in_pair[ 2001 ] ;
int global_tally_second_over_first_in_pair[ 2001 ] ;
int global_tally_first_equal_second_in_pair[ 2001 ] ;


//  Input and output codes that identify
//  the meaning of the next number in the (coded) list.
//  These are NOT in the same order as the negative-number codes.
//  Also specify text words that can be used in the input
//  file, or can be requested to be used in the output file.

const int global_voteinfo_code_for_start_of_all_cases = -1 ;
const int global_voteinfo_code_for_end_of_all_cases = -2 ;
const int global_voteinfo_code_for_case_number = -3 ;
const int global_voteinfo_code_for_question_number = -4 ;
const int global_voteinfo_code_for_total_ballot_count = -5 ;
const int global_voteinfo_code_for_number_of_choices = -6 ;
const int global_voteinfo_code_for_start_of_all_vote_info = -7 ;
const int global_voteinfo_code_for_end_of_all_vote_info = -8 ;
const int global_voteinfo_code_for_start_of_ballot = -9 ;
const int global_voteinfo_code_for_end_of_ballot = -10 ;
//  The following ballot count indicates how many ballots have the same ranking.
const int global_voteinfo_code_for_ballot_count = -11 ;
const int global_voteinfo_code_for_preference_level = -12 ;
const int global_voteinfo_code_for_choice = -13 ;
const int global_voteinfo_code_for_tie = -14 ;
const int global_voteinfo_code_for_start_of_votefair_popularity_ranking_sequence_results = -15 ;
const int global_voteinfo_code_for_end_of_votefair_popularity_ranking_sequence_results = -16 ;
const int global_voteinfo_code_for_start_of_votefair_popularity_ranking_levels_results = -17 ;
const int global_voteinfo_code_for_end_of_votefair_popularity_ranking_levels_results = -18 ;
const int global_voteinfo_code_for_start_of_votefair_representation_ranking_sequence_results = -19 ;
const int global_voteinfo_code_for_end_of_votefair_representation_ranking_sequence_results = -20 ;
const int global_voteinfo_code_for_start_of_votefair_representation_ranking_levels_results = -21 ;
const int global_voteinfo_code_for_end_of_votefair_representation_ranking_levels_results = -22 ;
const int global_voteinfo_code_for_start_of_votefair_party_ranking_sequence_results = -23 ;
const int global_voteinfo_code_for_end_of_votefair_party_ranking_sequence_results = -24 ;
const int global_voteinfo_code_for_start_of_votefair_party_ranking_levels_results = -25 ;
const int global_voteinfo_code_for_end_of_votefair_party_ranking_levels_results = -26 ;
const int global_voteinfo_code_for_ranking_level = -27 ;
const int global_voteinfo_code_for_next_ranking_level = -28 ;
const int global_voteinfo_code_for_early_end_of_ranking = -29 ;
const int global_voteinfo_code_for_start_of_tally_table_results = -30 ;
const int global_voteinfo_code_for_end_of_tally_table_results = -31 ;
const int global_voteinfo_code_for_first_choice = -32 ;
const int global_voteinfo_code_for_second_choice = -33 ;
const int global_voteinfo_code_for_tally_first_over_second = -34 ;
const int global_voteinfo_code_for_tally_second_over_first = -35 ;
const int global_voteinfo_code_for_start_of_plurality_results = -36 ;
const int global_voteinfo_code_for_end_of_plurality_results = -37 ;
const int global_voteinfo_code_for_plurality_count = -38 ;
const int global_voteinfo_code_for_skip_case = -39 ;
const int global_voteinfo_code_for_skip_question = -40 ;
const int global_voteinfo_code_for_request_votefair_representation_rank = -41 ;
const int global_voteinfo_code_for_request_no_votefair_representation_rank = -42 ;
const int global_voteinfo_code_for_request_votefair_party_rank = -43 ;
const int global_voteinfo_code_for_request_no_votefair_party_rank = -44 ;
const int global_voteinfo_code_for_request_only_plurality_results = -45 ;
const int global_voteinfo_code_for_request_pairwise_counts = -46 ;
const int global_voteinfo_code_for_request_no_pairwise_counts = -47 ;
const int global_voteinfo_code_for_number_of_representation_levels_to_compute = -48 ;
const int global_voteinfo_code_for_request_text_output = -49 ;
const int global_voteinfo_code_for_request_instant_runoff_voting = -50 ;
const int global_voteinfo_code_for_request_instant_pairwise_elimination = -51 ;
const int global_voteinfo_code_for_request_rcipe_voting = -52 ;
const int global_voteinfo_code_for_winner_instant_runoff_voting = -53 ;
const int global_voteinfo_code_for_winner_instant_pairwise_elimination = -54 ;
const int global_voteinfo_code_for_winner_rcipe_voting = -55 ;
const int global_voteinfo_code_for_request_star_voting = -56 ;
const int global_voteinfo_code_for_winner_star_voting = -57 ;
const int global_voteinfo_code_for_request_pairwise_loser_elimination = -58 ;
const int global_voteinfo_code_for_winner_pairwise_loser_elimination = -59 ;
const int global_voteinfo_code_for_winner_irv_bottom_two_runoff = -60 ;
const int global_voteinfo_code_for_winner_borda_count = -61 ;
const int global_voteinfo_code_for_flag_as_interesting = -62 ;
const int global_voteinfo_code_for_winner_approval_voting = -63 ;
const int global_voteinfo_code_for_winner_condorcet = -64 ;
const int global_voteinfo_code_for_request_logging_off = -65 ;
const int global_voteinfo_code_for_winner_pairwise_support_count = -66 ;
const int global_voteinfo_code_for_number_of_equivalent_seats = -67 ;
const int global_voteinfo_code_for_request_quota_droop_not_hare = -68 ;
const int global_voteinfo_code_for_winner_next_seat = -69 ;
const int global_voteinfo_code_for_begin_tied_for_next_seat = -70 ;
const int global_voteinfo_code_for_end_tied_for_next_seat = -71 ;
const int global_voteinfo_code_for_counting_cycle_number = -72 ;
const int global_voteinfo_code_for_pairwise_losing_candidate = -73 ;
const int global_voteinfo_code_for_eliminated_candidate = -74 ;
const int global_voteinfo_code_for_quota_count_this_cycle = -75 ;
const int global_voteinfo_code_for_candidate_and_transfer_count = -76 ;
const int global_voteinfo_code_for_candidate_to_ignore = -77 ;
const int global_voteinfo_code_for_request_ignore_shared_rankings = -78 ;

const int global_voteinfo_code_for_invalid_input_word = -200 ;

std::map< std::string , int > global_voteinfo_code_for_alias_word ;

std::string global_text_for_voteinfo_code[ 400 ] ;


//  Declare the case number (variable).
//  It is received from the input file and copied
//  to the output file to allow verifying a match
//  between the ballots and the results.

int global_case_number ;


//  Declare the variables used to specify the
//  current relevant question number and choice
//  number.

int global_question_number ;
int global_choice_number ;


//  Specify an extra output file that contains a log
//  of actions for the purpose of monitoring or
//  debugging intermediate calculations.

std::ofstream log_out ;


//  Declare message strings.

std::string global_possible_error_message ;
std::string global_pairwise_matrix_text ;
std::string global_supplied_vote_info_text ;
std::string global_warning_end ;


//  Input/output-related pointers and variables.

int global_input_pointer_start_next_case ;
int global_pointer_to_current_ballot ;
int global_length_of_vote_info_list ;
int global_pointer_to_output_results ;
int global_length_of_result_info_list ;


//  Declare flags that indicate which results are to be calculated,
//  and what other choices to make.

int global_true_or_false_request_votefair_popularity_rank ;
int global_true_or_false_always_request_votefair_popularity_rank ;
int global_true_or_false_request_only_plurality_results ;
int global_true_or_false_always_request_only_plurality_results ;
int global_true_or_false_request_no_pairwise_counts ;
int global_true_or_false_always_request_no_pairwise_counts ;
int global_true_or_false_request_votefair_representation_rank ;
int global_true_or_false_always_request_votefair_representation_rank ;
int global_true_or_false_request_votefair_party_rank ;
int global_true_or_false_always_request_votefair_party_rank ;
int global_number_of_representation_levels_to_compute ;
int global_true_or_false_request_text_output ;


//  Declare miscellaneous variables.

int global_logging_info ;
int global_number_of_questions ;
int global_adjusted_choice_number ;
int global_adjusted_choice_count ;
int global_full_choice_count ;
int global_choice_count_at_top_popularity_ranking_level ;
int global_choice_count_at_full_top_popularity_ranking_level ;
int global_choice_count_at_full_second_representation_level ;
int global_ballot_info_repeat_count ;
int global_current_total_vote_count ;
int global_ballot_influence_amount ;
int global_pair_counter_maximum ;
int global_true_or_false_tally_table_created ;
int global_check_all_scores_choice_limit ;
int global_representation_levels_requested ;
int global_second_most_representative_actual_choice ;
int global_actual_choice_at_top_of_full_popularity_ranking ;
int global_actual_choice_at_second_representation_ranking ;
int global_count_of_popularity_rankings ;
int global_actual_choice_at_top_popularity_ranking_level ;
int global_true_or_false_always_request_dashrep_phrases_in_output ;
int global_code_associations_filename ;
int global_comparison_count ;
int global_sequence_score ;
int global_not_same_count ;
int global_sequence_score_using_choice_score_method ;
int global_sequence_score_using_insertion_sort_method ;
int global_sequence_score_using_all_scores_method ;
int global_top_choice_according_to_choice_specific_scores ;
int global_count_of_continuing_choices ;
int global_count_of_choices_at_pairwise_max_opposition_or_min_support ;
int global_count_of_choices_with_smallest_first_choice_count ;

float global_scale_for_logged_pairwise_counts ;

std::string global_ranking_type_being_calculated ;


// -----------------------------------------------
//  Declare variables, constants, and arrays for
//  counting methods that eliminate one choice
//  during each elimination round.  Currently only
//  Instant Pairwise Elimination (IPE) is calculated
//  this way.
//
//  For speed reasons, arrays are declared here,
//  even if a single function uses them.
//  These variables and lists use actual choice
//  numbers, not adjusted choice numbers.

int global_elimination_result_type ;
int global_choice_to_eliminate ;
int global_true_or_false_request_instant_pairwise_elimination ;
int global_true_or_false_find_largest_not_smallest ;
int global_true_or_false_find_pairwise_opposition_not_support ;

int global_integer_count_for_choice[ 101 ] ;
int global_list_of_choices_with_largest_or_smallest_count[ 101 ] ;
int global_list_of_choices_with_smallest_pairwise_support_count[ 101 ] ;
int global_list_of_choices_with_largest_pairwise_opposition_count[ 101 ] ;
int global_list_of_choices_with_smallest_single_pairwise_count[ 101 ] ;
int global_true_or_false_continuing_for_choice[ 101 ] ;
int global_true_or_false_continuing_subset_includes_choice[ 101 ] ;
int global_pairwise_opposition_or_support_count_for_choice[ 101 ] ;
int global_list_of_choices_having_pairwise_opposition_or_support[ 101 ] ;
int global_loss_count_for_choice[ 101 ] ;
int global_win_count_for_choice[ 101 ] ;


// -----------------------------------------------
//  convert_integer_to_text
//
//  This function is used instead of "std::to_string"
//  for compatibility with older C++ "string" libraries
//  that have a bug.  The bug is that the "to_string"
//  function is not recognized as being within the
//  "std" library, even though it is defined there.

std::string convert_integer_to_text( int supplied_integer )
{
    int unused_string_length ;
    char c_format_string[ 50 ] ;
    try
    {
        unused_string_length = sprintf( c_format_string , "%1d" , supplied_integer ) ;
        return ( std::string ) c_format_string ;
    }
    catch( ... )
    {
        return "NAN" ;
    }
}


// -----------------------------------------------
//  convert_float_to_text
//
//  To read why this function is here, see the comment
//  above for function: convert_integer_to_text

std::string convert_float_to_text( float supplied_float )
{
    std::string returned_string ;
    char c_format_string[ 50 ] ;
    int unused_string_length ;
    try
    {
        unused_string_length = sprintf( c_format_string , "%1f" , supplied_float ) ;
        returned_string = ( std::string ) c_format_string ;
        //  next line assumes the sprintf result always includes a decimal point
        returned_string.erase( returned_string.find_last_not_of( "0" ) + 1 , std::string::npos ) ;
        returned_string.erase( returned_string.find_last_not_of( "." ) + 1 , std::string::npos ) ;
        return returned_string ;
    }
    catch( ... )
    {
        return "NAN" ;
    }
}


// -----------------------------------------------
//  convert_text_to_integer
//
//  To read why this function is here, see the comment
//  above for function: convert_integer_to_text

int convert_text_to_integer( char * supplied_text )
{
    int equivalent_integer ;
    try
    {
        equivalent_integer = atoi( supplied_text ) ;
    }
    catch( ... )
    {
        equivalent_integer = -999 ;
    }
    return equivalent_integer ;
}


// -----------------------------------------------
//    do_initialization

void do_initialization( )
{

    int pointer ;
    int question_number ;
    int choice_number ;


// -----------------------------------------------
//  Initialize lists to zeros.

    for ( pointer = 0 ; pointer <= 2001 ; pointer ++ )
    {
        global_vote_info_list[ pointer ] = 0 ;
        global_output_results[ pointer ] = 0 ;
    }

    global_log_info_choice_at_position[ 0 ] = 0 ;

    for ( question_number = 0 ; question_number <= global_maximum_question_number ; question_number ++ )
    {
        global_choice_count_for_question[ question_number ] = 0 ;
    }

    for ( choice_number = 0 ; choice_number <= global_maximum_choice_number ; choice_number ++ )
    {
        global_plurality_count_for_actual_choice[ choice_number ] = 0 ;
        global_popularity_ranking_for_actual_choice[ choice_number ] = 0 ;
        global_full_popularity_ranking_for_actual_choice[ choice_number ] = 0 ;
        global_representation_ranking_for_actual_choice[ choice_number ] = 0 ;
        global_full_representation_ranking_for_actual_choice[ choice_number ] = 0 ;
        global_party_ranking_for_actual_choice[ choice_number ] = 0 ;
        global_adjusted_choice_for_actual_choice[ choice_number ] = 0 ;
        global_actual_choice_for_adjusted_choice[ choice_number ] = 0 ;
        global_using_choice[ choice_number ] = 0 ;
        global_ballot_preference_for_choice[ choice_number ] = 0 ;
        global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ choice_number ] = 0 ;
        global_adjusted_ranking_for_adjusted_choice_top_down_version[ choice_number ] = 0 ;
        global_pair_counter_offset_for_first_adjusted_choice[ choice_number ] = 0 ;
        global_log_info_choice_at_position[ choice_number ] = 0 ;
        global_rank_to_normalize_for_adjusted_choice[ choice_number ] = 0 ;
        global_choice_score_popularity_rank_for_actual_choice[ choice_number ] = 0 ;
        global_insertion_sort_popularity_rank_for_actual_choice[ choice_number ] = 0 ;
    }

    for ( pointer = 0 ; pointer <= 200 ; pointer ++ )
    {
        global_output_results[ pointer ] = 0 ;
        global_tally_first_over_second_in_pair[ pointer ] = 0 ;
        global_tally_second_over_first_in_pair[ pointer ] = 0 ;
        global_tally_first_equal_second_in_pair[ pointer ] = 0 ;
        global_adjusted_first_choice_number_in_pair[ pointer ] = 0 ;
        global_adjusted_second_choice_number_in_pair[ pointer ] = 0 ;
    }


// -----------------------------------------------
//  Reset logging flag.

    global_logging_info = global_true ;


// -----------------------------------------------
//  Associate text "words" with the code numbers,
//  which are negative numbers.

    global_voteinfo_code_for_alias_word[ "startallcases" ] = -1 ;
    global_voteinfo_code_for_alias_word[ "endallcases" ] = -2 ;
    global_voteinfo_code_for_alias_word[ "case" ] = -3 ;
    global_voteinfo_code_for_alias_word[ "q" ] = -4 ;
    global_voteinfo_code_for_alias_word[ "votes" ] = -5 ;
    global_voteinfo_code_for_alias_word[ "choices" ] = -6 ;
    global_voteinfo_code_for_alias_word[ "startcase" ] = -7 ;
    global_voteinfo_code_for_alias_word[ "endcase" ] = -8 ;
    global_voteinfo_code_for_alias_word[ "bal" ] = -9 ;
    global_voteinfo_code_for_alias_word[ "b" ] = -10 ;
    global_voteinfo_code_for_alias_word[ "x" ] = -11 ;
    global_voteinfo_code_for_alias_word[ "pref" ] = -12 ;
    global_voteinfo_code_for_alias_word[ "ch" ] = -13 ;
    global_voteinfo_code_for_alias_word[ "tie" ] = -14 ;
    global_voteinfo_code_for_alias_word[ "popularity-sequence" ] = -15 ;
    global_voteinfo_code_for_alias_word[ "end-pop-seq" ] = -16 ;
    global_voteinfo_code_for_alias_word[ "popularity-levels" ] = -17 ;
    global_voteinfo_code_for_alias_word[ "end-pop-levels" ] = -18 ;
    global_voteinfo_code_for_alias_word[ "rep-seq" ] = -19 ;
    global_voteinfo_code_for_alias_word[ "end-rep-seq" ] = -20 ;
    global_voteinfo_code_for_alias_word[ "rep-levels" ] = -21 ;
    global_voteinfo_code_for_alias_word[ "end-rep-levels" ] = -22 ;
    global_voteinfo_code_for_alias_word[ "party-seq" ] = -23 ;
    global_voteinfo_code_for_alias_word[ "end-party-seq" ] = -24 ;
    global_voteinfo_code_for_alias_word[ "party-levels" ] = -25 ;
    global_voteinfo_code_for_alias_word[ "end-party-levels" ] = -26 ;
    global_voteinfo_code_for_alias_word[ "level" ] = -27 ;
    global_voteinfo_code_for_alias_word[ "next-level" ] = -28 ;
    global_voteinfo_code_for_alias_word[ "end-seq-early" ] = -29 ;
    global_voteinfo_code_for_alias_word[ "tallies" ] = -30 ;
    global_voteinfo_code_for_alias_word[ "end-tallies" ] = -31 ;
    global_voteinfo_code_for_alias_word[ "ch1" ] = -32 ;
    global_voteinfo_code_for_alias_word[ "ch2" ] = -33 ;
    global_voteinfo_code_for_alias_word[ "1over2" ] = -34 ;
    global_voteinfo_code_for_alias_word[ "2over1" ] = -35 ;
    global_voteinfo_code_for_alias_word[ "plurality" ] = -36 ;
    global_voteinfo_code_for_alias_word[ "end-plurality" ] = -37 ;
    global_voteinfo_code_for_alias_word[ "plur" ] = -38 ;
    global_voteinfo_code_for_alias_word[ "case-skipped" ] = -39 ;
    global_voteinfo_code_for_alias_word[ "question-skipped" ] = -40 ;
    global_voteinfo_code_for_alias_word[ "request-rep" ] = -41 ;
    global_voteinfo_code_for_alias_word[ "request-no-rep" ] = -42 ;
    global_voteinfo_code_for_alias_word[ "request-party" ] = -43 ;
    global_voteinfo_code_for_alias_word[ "request-no-party" ] = -44 ;
    global_voteinfo_code_for_alias_word[ "request-plurality-only" ] = -45 ;
    global_voteinfo_code_for_alias_word[ "request-pairwise-counts" ] = -46 ;
    global_voteinfo_code_for_alias_word[ "request-no-pairwise-counts" ] = -47 ;
    global_voteinfo_code_for_alias_word[ "number-rep-levels-to-compute" ] = -48 ;
    global_voteinfo_code_for_alias_word[ "request-text-output" ] = -49 ;
    global_voteinfo_code_for_alias_word[ "request-instant-runoff-voting" ] = -50 ;
    global_voteinfo_code_for_alias_word[ "request-instant-pairwise-elimination" ] = -51 ;
    global_voteinfo_code_for_alias_word[ "request-rcipe-voting" ] = -52 ;
    global_voteinfo_code_for_alias_word[ "winner-instant-runoff-voting" ] = -53 ;
    global_voteinfo_code_for_alias_word[ "winner-instant-pairwise-elimination" ] = -54 ;
    global_voteinfo_code_for_alias_word[ "winner-rcipe-voting" ] = -55 ;
    global_voteinfo_code_for_alias_word[ "request-star-voting" ] = -56 ;
    global_voteinfo_code_for_alias_word[ "winner-star-voting" ] = -57 ;
    global_voteinfo_code_for_alias_word[ "request-pairwise-loser-elimination" ] = -58 ;
    global_voteinfo_code_for_alias_word[ "winner-pairwise-loser-elimination" ] = -59 ;
    global_voteinfo_code_for_alias_word[ "winner-irv-bottom-two-runoff" ] = -60 ;
    global_voteinfo_code_for_alias_word[ "winner-borda-count" ] = -61 ;
    global_voteinfo_code_for_alias_word[ "flag-as-interesting" ] = -62 ;
    global_voteinfo_code_for_alias_word[ "winner-approval-voting" ] = -63 ;
    global_voteinfo_code_for_alias_word[ "winner-condorcet" ] = -64 ;
    global_voteinfo_code_for_alias_word[ "request-logging-off" ] = -65 ;
    global_voteinfo_code_for_alias_word[ "winner-pairwise-support-count" ] = -66 ;
    global_voteinfo_code_for_alias_word[ "number-of-equivalent-seats" ] = -67 ;
    global_voteinfo_code_for_alias_word[ "request-quota-droop-not-hare" ] = -68 ;
    global_voteinfo_code_for_alias_word[ "winner-next-seat" ] = -69 ;
    global_voteinfo_code_for_alias_word[ "begin-tied-for-next-seat" ] = -70 ;
    global_voteinfo_code_for_alias_word[ "end-tied-for-next-seat" ] = -71 ;
    global_voteinfo_code_for_alias_word[ "counting-cycle-number" ] = -72 ;
    global_voteinfo_code_for_alias_word[ "pairwise-losing-candidate" ] = -73 ;
    global_voteinfo_code_for_alias_word[ "eliminated-candidate" ] = -74 ;
    global_voteinfo_code_for_alias_word[ "quota-count-this-cycle" ] = -75 ;
    global_voteinfo_code_for_alias_word[ "candidate-and-transfer-count" ] = -76 ;
    global_voteinfo_code_for_alias_word[ "candidate-to-ignore" ] = -77 ;
    global_voteinfo_code_for_alias_word[ "invalid-input-word" ] = -200 ;


// -----------------------------------------------
//  Open the extra output files.

    log_out.open ( "output_votefair_ranking_log.txt" , std::ios::out ) ;


// -----------------------------------------------
//  Define constants.

    std::string global_warning_end = "\n-----\n\n" ;


// -----------------------------------------------
//  Request that the output file use negative
//  code numbers in the output.
//  If text codes are preferred, either insert
//  the code "request_text_output" in the input file,
//  or maybe set this value to global_true.

    global_true_or_false_request_text_output = global_false ;


// -----------------------------------------------
//  Initialize the "always" versions of the
//  requests for specified results.

    global_true_or_false_always_request_votefair_popularity_rank = global_true ;
    global_true_or_false_always_request_only_plurality_results = global_false ;
    global_true_or_false_always_request_no_pairwise_counts = global_false ;
    global_true_or_false_always_request_votefair_representation_rank = global_false ;
    global_true_or_false_always_request_votefair_party_rank = global_false ;
    global_true_or_false_always_request_dashrep_phrases_in_output = global_false ;

    global_true_or_false_request_votefair_popularity_rank = global_true_or_false_always_request_votefair_popularity_rank ;
    global_true_or_false_request_only_plurality_results = global_true_or_false_always_request_only_plurality_results ;
    global_true_or_false_request_no_pairwise_counts = global_true_or_false_always_request_no_pairwise_counts ;
    global_true_or_false_request_votefair_representation_rank = global_true_or_false_always_request_votefair_representation_rank ;
    global_true_or_false_request_votefair_party_rank = global_true_or_false_always_request_votefair_party_rank ;


// -----------------------------------------------
//  Initialize zero and empty values.

    global_length_of_vote_info_list = 0 ;
    global_input_pointer_start_next_case = 0 ;
    global_pointer_to_output_results = 0 ;
    global_case_number = 0 ;
    global_question_number = 0 ;
    global_number_of_questions = 0 ;
    global_choice_number = 0 ;
    global_ballot_info_repeat_count = 0 ;
    global_current_total_vote_count = 0 ;
    global_pointer_to_current_ballot = 0 ;
    global_length_of_result_info_list = 0 ;
    global_ballot_influence_amount = 0 ;
    global_adjusted_choice_number = 0 ;
    global_adjusted_choice_count = 0 ;
    global_full_choice_count = 0 ;
    global_pair_counter_maximum = 0 ;
    global_choice_count_at_top_popularity_ranking_level = 0 ;
    global_choice_count_at_full_top_popularity_ranking_level = 0 ;
    global_choice_count_at_full_second_representation_level = 0 ;
    global_representation_levels_requested = 0 ;
    global_second_most_representative_actual_choice = 0 ;
    global_actual_choice_at_top_of_full_popularity_ranking = 0 ;
    global_actual_choice_at_second_representation_ranking = 0 ;
    global_elimination_result_type = 0 ;

    global_possible_error_message = "" ;
    global_ranking_type_being_calculated = "" ;
    global_pairwise_matrix_text = "" ;


// -----------------------------------------------
//  Initialize false values for requesting the
//  IPE method.

    global_true_or_false_request_instant_pairwise_elimination = global_false ;


// -----------------------------------------------
//  Poplulate the list global_text_for_voteinfo_code
//  using the information in the list
//  global_voteinfo_code_for_alias_word.

    for ( std::map< std::string , int >::iterator iteration_pointer = global_voteinfo_code_for_alias_word.begin( ) ; iteration_pointer != global_voteinfo_code_for_alias_word.end( ) ; ++ iteration_pointer )
    {
//        log_out << " " << iteration_pointer->first << "  " << iteration_pointer->second << std::endl ;
        global_text_for_voteinfo_code[ -1 * iteration_pointer->second ] = iteration_pointer->first ;
    }


// -----------------------------------------------
//  If needed, un-comment this code to view
//  bucket usage for associative list named
//  global_voteinfo_code_for_alias_word.

/*
    for ( unsigned pointer = 0; pointer < global_voteinfo_code_for_alias_word.bucket_count() ; ++pointer) {
        std::cout << "bucket #" << pointer << " contains:" ;
        for ( auto iteration_pointer = global_voteinfo_code_for_alias_word.begin(pointer) ; iteration_pointer != global_voteinfo_code_for_alias_word.end(pointer) ; ++iteration_pointer )
        {
            std::cout << " " << iteration_pointer->first ;
        }
        std::cout << std::endl ;
    }
*/


// -----------------------------------------------
//  Get ready to start calculations.

    global_case_number = 0 ;


// -----------------------------------------------
//  End of function do_initialization.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//    always_do_rep_and_party_ranking
//
//  Requests that VoteFair representation ranking and
//  VoteFair party ranking always be done -- except
//  when only plurality votes are requested (because
//  in those cases 1-2-3 ballots have not been used).
//
// -----------------------------------------------
// -----------------------------------------------

void always_do_rep_and_party_ranking( )
{


// -----------------------------------------------
//  Request that VoteFair representation ranking
//  and VoteFair party ranking always be done.

    global_true_or_false_always_request_only_plurality_results = global_false ;
    global_true_or_false_always_request_votefair_popularity_rank = global_true ;
    global_true_or_false_always_request_votefair_representation_rank = global_true ;
    global_true_or_false_always_request_votefair_party_rank = global_true ;

    global_true_or_false_request_only_plurality_results = global_true_or_false_always_request_only_plurality_results ;
    global_true_or_false_request_votefair_popularity_rank = global_true_or_false_always_request_votefair_popularity_rank ;
    global_true_or_false_request_votefair_representation_rank = global_true_or_false_always_request_votefair_representation_rank ;
    global_true_or_false_request_votefair_party_rank = global_true_or_false_always_request_votefair_party_rank ;


// -----------------------------------------------
//  Function always_do_rep_and_party_ranking done.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//    pad_integer
//
//  Pads integer with spaces, to left side.
//  Also ensures value of zero shows as "0",
//  not blank.
//
// -----------------------------------------------
// -----------------------------------------------

std::string pad_integer( int input_integer , int pad_width )
{
    std::string output_text ;
    output_text = "" ;
    int text_length ;
    if ( input_integer == 0 )
    {
        output_text = "0" ;
    } else
    {
        output_text = convert_integer_to_text( input_integer ) ;
    }
    text_length = output_text.length( ) ;
    while ( text_length < pad_width )
    {
        output_text = " " + output_text ;
        text_length ++ ;
    }
    return output_text ;
//  End of function pad_integer.
}



// -----------------------------------------------
// -----------------------------------------------
//    pad_real
//
//  Pads a real number with spaces on left side
//  and, if needed, zeros on right side.
//  Also ensures value of zero shows as "0.00",
//  not blank.
//
// -----------------------------------------------
// -----------------------------------------------

std::string pad_real( float input_real_number , int pad_width )
{
    std::string output_text ;
    output_text = "" ;
    int text_length ;
    int decimal_length ;
    int decimal_point_position ;
    if ( input_real_number == 0.0 )
    {
        output_text = "0.00" ;
    } else
    {
        output_text = convert_float_to_text( ( (int) ( input_real_number * 100 ) ) / 100 ) ;
    }
    decimal_point_position = output_text.find( "." , 0 ) ;
    if ( decimal_point_position < 1 )
    {
        output_text += "." ;
        decimal_point_position = output_text.find( "." , 0 ) ;
    }
    text_length = output_text.length( ) ;
    decimal_length = text_length - decimal_point_position - 1 ;
    while ( decimal_length < 2 )
    {
        output_text = output_text + "0" ;
        decimal_length ++ ;
    }
    text_length = output_text.length( ) ;
    while ( text_length < pad_width )
    {
        output_text = " " + output_text ;
        text_length ++ ;
    }
    return output_text ;
//  End of function pad_real.
}



// -----------------------------------------------
// -----------------------------------------------
//     read_data
//
//  Reads numbers and codes from the standard input
//  file.
//
// -----------------------------------------------
// -----------------------------------------------

void read_data( )
{

    std::string input_line ;
    std::string input_text_word ;

    int input_number_count ;
    int next_number ;
    int previous_number ;
    int next_result_code ;


// -----------------------------------------------
//  Initialize local variables.

    previous_number = 0 ;
    input_number_count = 0 ;


// -----------------------------------------------
//  Begin loop to handle one line from the input file,
//  which is "standard input" (which means it's the
//  input file specified on the command line).
//
//  Although each code can be on a different line,
//  or all the codes and tokens can be on a single
//  line (if it is not too long), for clarity
//  each ballot can be on a separate line.

    for ( std::string input_line ; std::getline( std::cin , input_line ) ; )
    {
        std::size_t pointer_found = input_line.find_last_not_of( " \t\n\r" ) ;
        if ( pointer_found != std::string::npos )
        {
            input_line.erase( pointer_found + 1 ) ;
        } else
        {
            input_line.clear( ) ;
        }
        if ( global_logging_info == global_true ) { log_out << "[input line: " << input_line << "]" << std::endl ; } ;
        char input_line_c_version[ 2000 ] = "" ;
        std::size_t line_length = std::min( 2000 , (int) input_line.length() ) ;
        std::size_t line_length_copied = input_line.copy( input_line_c_version , line_length , 0 ) ;
        input_line_c_version[ line_length_copied ] = '\0' ;


// -----------------------------------------------
//  Begin loop to get first/next space-delimited
//  word (of text) from the input line.  It must be
//  either an integer or one of the special words
//  (tokens) defined during initialization.

        char * pointer_to_word ;
        // reminder: strtok modifies the string
        pointer_to_word = strtok( input_line_c_version , " ,." ) ;
        while ( pointer_to_word != NULL )
        {


// -----------------------------------------------
//  If the word is a text token, convert it into
//  its associated negative integer.

            input_text_word = pointer_to_word ;
            if ( global_voteinfo_code_for_alias_word.count( input_text_word ) > 0 )
            {
                next_number = global_voteinfo_code_for_alias_word[ input_text_word ] ;
                if ( global_logging_info == global_true ) { log_out << "[" << input_text_word << " converted to " << next_number << "]" ; } ;


// -----------------------------------------------
//  If the word was not a text token, attempt to
//  convert it into an integer.  If this conversion
//  is not successful, indicate an error and write
//  this error to the output files and then exit
//  the program.

            } else
            {
                try
                {
                    next_number = convert_text_to_integer( pointer_to_word ) ;
                    if ( global_logging_info == global_true ) { log_out << "[" << next_number << "]  " ; } ;
                }
                catch( ... )
                {
                    std::cout << "Error, invalid input word: " << pointer_to_word << std::endl ;
                    if ( global_logging_info == global_true ) { log_out << "[Warning: Input line contains non-numeric characters (" << pointer_to_word << "), so this case (" << global_case_number << ") cannot be calculated]\n" ; } ;
                    exit( EXIT_FAILURE ) ;
                }
            }


// -----------------------------------------------
//  If there is a request for no logging,
//  shut off logging now.

            if ( next_number == global_voteinfo_code_for_request_logging_off )
            {
                global_logging_info = global_false ;
            }


// -----------------------------------------------
//  Ensure the array that stores input numbers has
//  not become too long.

            if ( global_length_of_vote_info_list > global_maximum_vote_info_list_length )
            {
                std::cout << "Error: Too many vote-info numbers (" << global_length_of_vote_info_list << ") supplied, maximum is " << global_maximum_vote_info_list_length << "." ;
                break ;
            }


// -----------------------------------------------
//  Increment the list length, which also is used
//  as a pointer.
//  Note that list position zero ([0]) is not used!
//  A length of zero indicates the list is empty.

            global_length_of_vote_info_list ++ ;


// -----------------------------------------------
//  Store the supplied vote-info number.

            global_vote_info_list[ global_length_of_vote_info_list ] = next_number ;
//            if ( global_logging_info == global_true ) { log_out << "[" << next_number << "]" ; } ;


// -----------------------------------------------
//  Insert an end-of-info code number at the next
//  position, in case this is the last vote-info
//  number put into the list.

            global_vote_info_list[ global_length_of_vote_info_list + 1 ] = global_voteinfo_code_for_end_of_all_cases ;


// -----------------------------------------------
//  Repeat the loop for the next word (within the line).

            input_number_count ++ ;
            previous_number = next_number ;
            pointer_to_word = strtok( NULL, " ,." ) ;
//            std::cout << "Number count = " << input_number_count << std::endl ;
        }
        if ( global_logging_info == global_true ) { log_out << "\n[done handling input line]\n" ; }


// -----------------------------------------------
//  Repeat the loop for the next line of data from
//  the input file.

    }
    if ( global_logging_info == global_true ) { log_out << "[done getting input data]\n" ; }


// -----------------------------------------------
//  If less than two numbers were found, indicate
//  this no-data error.

    if ( input_number_count < 2 )
    {
        global_possible_error_message = "Error: Input file does not contain any data." ;
        global_length_of_result_info_list = 0 ;
        if ( global_logging_info == global_true ) { log_out << "[Error: Input file does not contain any data]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  End of function votefair_read_data.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//       put_next_result_info_number
//
// Puts the next result-info number into the array
// that stores the result information.
//
// -----------------------------------------------
// -----------------------------------------------

void put_next_result_info_number( int current_result_info_number )
{


// -----------------------------------------------
//  If the list has become too long,
//  insert the code that indicates the end
//  of the results, and then indicate an error.

    if ( global_pointer_to_output_results >= global_maximum_output_results_length )
    {
        global_output_results[ global_pointer_to_output_results ] = global_voteinfo_code_for_end_of_all_cases ;
        global_possible_error_message = "Error: Not enough room for results from all cases (size limit is " + convert_integer_to_text( global_maximum_output_results_length ) + ")." ;
        return ;
    }


// -----------------------------------------------
//  Put the next result-info number into the list.

    global_output_results[ global_pointer_to_output_results ] = current_result_info_number ;


// -----------------------------------------------
//  Increment the list pointer, and increment the
//  length of the list.

    global_pointer_to_output_results ++ ;
    global_length_of_result_info_list = global_pointer_to_output_results ;


// -----------------------------------------------
//  End of function put_next_result_info_number.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//       get_next_result_info_number
//
// Gets the next result-info number from the list
// that stores the result information.
//
// -----------------------------------------------
// -----------------------------------------------

int get_next_result_info_number( )
{

    int current_result_info_number ;


// -----------------------------------------------
//  If the end of the list has been reached,
//  return the code that indicates the end
//  of the results.

    if ( ( global_pointer_to_output_results >= global_length_of_result_info_list ) || ( global_pointer_to_output_results >= global_maximum_output_results_length ) )
    {
        return global_voteinfo_code_for_end_of_all_cases ;
    }


// -----------------------------------------------
//  If the pointer is negative, point to the
//  first item.

    if ( global_pointer_to_output_results < 0 )
    {
        global_pointer_to_output_results = 0 ;
    }


// -----------------------------------------------
//  Get the next result-info number.

    current_result_info_number = global_output_results[ global_pointer_to_output_results ] ;
//    if ( global_logging_info == global_true ) { log_out << "[" << current_result_info_number << "]" ; } ;


// -----------------------------------------------
//  If the end-of-all-cases code is encountered,
//  return with that value -- without changing
//  the pointer.

    if ( current_result_info_number == global_voteinfo_code_for_end_of_all_cases )
    {
        return global_voteinfo_code_for_end_of_all_cases ;
    }


// -----------------------------------------------
//  Increment the list pointer.

    global_pointer_to_output_results ++ ;


// -----------------------------------------------
//  Return the value.

    return current_result_info_number ;


// -----------------------------------------------
//  End of function get_next_result_info_number.

}



// -----------------------------------------------
// -----------------------------------------------
//     write_results
//
//  Writes the requested calculated results to the
//  standard output file.
//
// -----------------------------------------------
// -----------------------------------------------

void write_results( )
{

    int next_result_code ;
    std::string newline_or_space ;

    if ( global_logging_info == global_true ) { log_out << "\n[writing results to output]\n" ; } ;
    if ( global_logging_info == global_true ) { log_out << "\n[begin output result codes]" ; } ;


// -----------------------------------------------
//  Write the result code numbers to the standard
//  output file.

    newline_or_space = "" ;
    next_result_code = get_next_result_info_number( ) ;
    while ( next_result_code != global_voteinfo_code_for_end_of_all_cases )
    {
        std::cout << newline_or_space ;
        if ( next_result_code == 0 )
        {
            std::cout << "0" ;
        } else if ( next_result_code > 0 )
        {
            std::cout << convert_integer_to_text( next_result_code ) ;
        } else
        {
            if ( global_true_or_false_request_text_output == global_true )
            {
                std::cout << global_text_for_voteinfo_code[ -1 * next_result_code ] ;
                if ( newline_or_space == "" )
                {
                    newline_or_space = " " ;
                }
            } else
            {
                std::cout << convert_integer_to_text( next_result_code ) ;
                if ( newline_or_space == "" )
                {
                    newline_or_space = "\n" ;
                }
            }
        }
        if ( next_result_code > 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[" << next_result_code << "]" ; } ;
        } else if ( next_result_code < 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[" << next_result_code << " " << global_text_for_voteinfo_code[ -1 * next_result_code ] << "]" ; } ;
        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[0]" ; } ;
        }
        next_result_code = get_next_result_info_number( ) ;
    }
    std::cout << newline_or_space ;
    if ( global_true_or_false_request_text_output == global_true )
    {
        std::cout << global_text_for_voteinfo_code[ -1 * next_result_code ] ;
    } else
    {
        std::cout << convert_integer_to_text( global_voteinfo_code_for_end_of_all_cases ) ;
    }
    std::cout << newline_or_space << "0" << std::endl ;
    if ( global_logging_info == global_true ) { log_out << "\n[end output result codes]\n" ; } ;


// -----------------------------------------------
//  End of function write_results.

    return ;

}


// -----------------------------------------------
// -----------------------------------------------
//       check_vote_info_numbers
//
//  Checks the validity of the numbers in the vote-info
//  list, and requests skipping any cases or questions
//  that contain invalid data.  Also, counts the
//  number of questions in each case, and counts the
//  choices in each question.
//
// -----------------------------------------------
// -----------------------------------------------

void check_vote_info_numbers( )
{

    int question_number ;
    int choice_number ;
    int status_pair_just_handled ;
    int current_vote_info_number ;
    int previous_vote_info_number ;
    int next_vote_info_number ;
    int pointer_to_vote_info ;
    int within_ballots ;
    int choice_count_for_current_question ;
    int count_of_choices_marked_for_current_question ;


// -----------------------------------------------
//  Initialization.

    if ( global_logging_info == global_true ) { log_out << "\n[about to start checking vote-info numbers]\n" ; } ;
    for ( choice_number = 0 ; choice_number <= global_maximum_choice_number ; choice_number ++ )
    {
        global_tally_uses_of_choice_number[ choice_number ] = 0 ;
    }


// -----------------------------------------------
//  If the list of numbers is empty, indicate an
//  error.

    if ( global_length_of_vote_info_list < 2 )
    {
        global_possible_error_message = "Error: No data was supplied." ;
        return ;
    }


// -----------------------------------------------
//  Begin a loop that handles each vote-info
//  number in the list.

    current_vote_info_number = 0 ;
    previous_vote_info_number = 0 ;
    next_vote_info_number = 0 ;
    status_pair_just_handled = global_false ;
    global_ballot_info_repeat_count = 0 ;
    global_current_total_vote_count = 0 ;
    if ( global_logging_info == global_true ) { log_out << "\n[input voteinfo list length = " << global_length_of_vote_info_list << "]" << std::endl ; } ;
    if ( global_logging_info == global_true ) { log_out << "\n[begin checking vote info numbers]\n" ; } ;
    for ( pointer_to_vote_info = 1 ; pointer_to_vote_info <= global_length_of_vote_info_list ; pointer_to_vote_info ++ )
    {


// -----------------------------------------------
//  If this vote-info number was preceded by a
//  code that already handled this vote-info
//  number, repeat the loop for the next vote-info
//  number.

        if ( status_pair_just_handled == global_true )
        {
            status_pair_just_handled = global_false ;
            continue ;
        }
        status_pair_just_handled = global_false ;


// -----------------------------------------------
//  Get the current vote-info number, and adjacent
//  vote-info numbers.

        current_vote_info_number = global_vote_info_list[ pointer_to_vote_info ] ;
        if ( pointer_to_vote_info <= 1 )
        {
            previous_vote_info_number = 0 ;
        } else
        {
            previous_vote_info_number = global_vote_info_list[ pointer_to_vote_info - 1 ] ;
        }
        if ( pointer_to_vote_info + 1 > global_length_of_vote_info_list )
        {
            next_vote_info_number = 0 ;
        } else
        {
            next_vote_info_number = global_vote_info_list[ pointer_to_vote_info + 1 ] ;
        }
        if ( global_logging_info == global_true ) { log_out << "\n[" << current_vote_info_number << "]" ; } ;


// -----------------------------------------------
//  Ignore a code value of zero.

        if ( current_vote_info_number == 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[ignoring zero value]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for a case number.

        } else if ( current_vote_info_number == global_voteinfo_code_for_case_number )
        {
            if ( global_case_number != 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[error, second case number encountered, which is not allowed]" ; } ;
                global_possible_error_message = "Error: Second case number encountered, which is not valid." ;
                return ;
            }
            global_case_number = next_vote_info_number ;
            status_pair_just_handled = global_true ;
            if ( global_logging_info == global_true ) { log_out << "[case " << global_case_number << "]" ; } ;
            if ( global_case_number == 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[error, case number is zero, which is not valid]" ; } ;
                global_possible_error_message = "Error: Case number is zero, which is not valid." ;
                return ;
            }
            global_current_total_vote_count = 0 ;
            global_question_number = 0 ;
            global_number_of_questions = 0 ;
            within_ballots = global_false ;
            continue ;


// -----------------------------------------------
//  Handle the code for a question number.

        } else if ( current_vote_info_number == global_voteinfo_code_for_question_number )
        {
            status_pair_just_handled = global_true ;
            global_question_number = next_vote_info_number ;
            if ( global_question_number < 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[question number is less than one (" << global_question_number << ")]" ; } ;
                global_possible_error_message = "Error: Encountered question number less than one (" + convert_integer_to_text( global_question_number ) + ")." ;
                return ;
            } else if ( global_question_number > global_maximum_question_number )
            {
                if ( global_logging_info == global_true ) { log_out << "[too many questions (limit is " << global_maximum_question_number << "]" ; } ;
                global_possible_error_message = "Error: Two many questions (" + convert_integer_to_text( global_maximum_question_number ) + ")." ;
                return ;
            } else
            {
            	if ( global_number_of_questions < global_question_number )
            	{
                    global_number_of_questions = global_question_number ;
                }
                if ( global_logging_info == global_true ) { log_out << "[question " << global_question_number << "]" ; } ;
                count_of_choices_marked_for_current_question = 0 ;
            }
            continue ;


// -----------------------------------------------
//  Handle the code for a choice count.

        } else if ( current_vote_info_number == global_voteinfo_code_for_number_of_choices )
        {
            status_pair_just_handled = global_true ;
            global_choice_count_for_question[ global_question_number ] = next_vote_info_number ;
            choice_count_for_current_question = next_vote_info_number ;
            if ( global_logging_info == global_true ) { log_out << "[choice count " << choice_count_for_current_question << "]" ; } ;
            if ( global_question_number == 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[encountered choice count without question number]" ; } ;
                global_possible_error_message = "Error: Encountered choice count without question number." ;
                return ;
            }
            if ( ( choice_count_for_current_question < 1 ) || ( choice_count_for_current_question > global_maximum_choice_number ) )
            {
                if ( global_logging_info == global_true ) { log_out << "[invalid choice count (" << choice_count_for_current_question << ")]" ; } ;
                global_possible_error_message = "Error: Invalid choice count (" + convert_integer_to_text( choice_count_for_current_question ) + ")." ;
                return ;
            }
            continue ;


// -----------------------------------------------
//  Handle the code for a ballot count.

        } else if ( current_vote_info_number == global_voteinfo_code_for_ballot_count )
        {
            status_pair_just_handled = global_true ;
            global_ballot_info_repeat_count = next_vote_info_number ;
            if ( global_ballot_info_repeat_count < 1 )
            {
                if ( global_logging_info == global_true ) { log_out << "[ballot count number is less than one (" << global_ballot_info_repeat_count << ")]" ; } ;
                global_possible_error_message = "Error: Ballot count number is less than one (" + convert_integer_to_text( global_ballot_info_repeat_count ) + ")." ;
                return ;
            }
            if ( global_logging_info == global_true ) { log_out << "[bc " << global_ballot_info_repeat_count << "]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle a choice number.

        } else if ( current_vote_info_number > 0 )
        {
            global_choice_number = current_vote_info_number ;
            if ( global_choice_count_for_question[ global_question_number ] == 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[choice number appears before number of choices specified, question " << global_question_number << ", ballot vote count " << global_ballot_info_repeat_count << ", choice " << global_choice_number << ", at list position " << pointer_to_vote_info << ")]" ; } ;
                global_possible_error_message = "Error: Choice number appears before number of choices specified, question (" + convert_integer_to_text( global_question_number ) + ")." ;
                return ;
            } else if ( global_choice_number > global_choice_count_for_question[ global_question_number ] )
            {
                if ( global_logging_info == global_true ) { log_out << "[choice number exceeds indicated number of choices (case " << global_case_number << ", question " << global_question_number << ", ballot vote count " << global_ballot_info_repeat_count << ", choice " << global_choice_number << ", specified number " << global_choice_count_for_question[ global_question_number ] << ", at list position " << pointer_to_vote_info << ")]" ; } ;
                global_possible_error_message = "Error: Choice number exceeds indicated number of choices, question (" + convert_integer_to_text( global_question_number ) + ")." ;
                return ;
            }
            if ( global_tally_uses_of_choice_number[ global_choice_number ] > 1 )
            {
                if ( global_logging_info == global_true ) { log_out << "[choice number previously used in this ballot, question " << global_question_number << ", ballot vote count " << global_ballot_info_repeat_count << ", choice " << global_choice_number << ", at list position " << pointer_to_vote_info << ")]" ; } ;
                global_possible_error_message = "Error: Choice number previously used in same ballot, question (" + convert_integer_to_text( global_question_number ) + ")." ;
                return ;
            }
            global_tally_uses_of_choice_number[ global_choice_number ] = 1 ;
            count_of_choices_marked_for_current_question ++ ;
            if ( global_choice_number > global_choice_count_for_question[ global_question_number ] )
            {
                global_choice_count_for_question[ global_question_number ] = global_choice_number ;
            }
            global_current_total_vote_count += global_ballot_info_repeat_count ;
            global_ballot_info_repeat_count = 0 ;
            if ( global_logging_info == global_true ) { log_out << "[choice " << global_choice_number << "]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for a tie.

        } else if ( current_vote_info_number == global_voteinfo_code_for_tie )
        {
            if ( ( count_of_choices_marked_for_current_question < 1 ) || ( global_question_number < 1 ) )
            {
                if ( global_logging_info == global_true ) { log_out << "[invalid nesting of tied preference vote info number (question " << global_question_number << ", ballot vote count " << global_current_total_vote_count << ", at list position " << pointer_to_vote_info << ")]" ; } ;
                global_possible_error_message = "Error: Invalid nesting of tied preference vote info number (" + convert_integer_to_text( global_question_number ) + ")." ;
                return ;
            }
            if ( global_logging_info == global_true ) { log_out << "[+]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for the beginning of all the
//  ballots.

        } else if ( current_vote_info_number == global_voteinfo_code_for_start_of_all_vote_info )
        {
            if ( global_logging_info == global_true ) { log_out << "[begin ballots]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for the end of a ballot.

        } else if ( current_vote_info_number == global_voteinfo_code_for_end_of_ballot )
        {
            global_tally_uses_of_choice_number[ 0 ] = 0 ;
            if ( global_logging_info == global_true ) { log_out << "[end ballot]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for the number of
//  representation levels to calculate.

        } else if ( current_vote_info_number == global_voteinfo_code_for_number_of_representation_levels_to_compute )
        {
            status_pair_just_handled = global_true ;
            global_representation_levels_requested = next_vote_info_number ;
            global_true_or_false_request_votefair_representation_rank = global_true ;
            if ( global_logging_info == global_true ) { log_out << "[rank_levels_to_compute " << global_representation_levels_requested << "]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for the number of seats to be
//  filled in a multi-winner method.  Ignore this
//  number.

        } else if ( current_vote_info_number == global_voteinfo_code_for_number_of_equivalent_seats )
        {
            status_pair_just_handled = global_true ;
            if ( global_logging_info == global_true ) { log_out << "[ignored, seats to fill " << next_vote_info_number << "]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for a request to calculate
//  VoteFair representation ranking results,
//  VoteFair party ranking results, or only do
//  plurality counting.  If this request occurs
//  before the case number, apply this
//  request to all questions,
//  although a different request can be specified
//  (later) for a specific question.  If the
//  request does not appear before the first
//  ballot (in the case), indicate (in the log
//  file) an error, but allow this minor error.

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_only_plurality_results )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_only_plurality_results = global_true ;
                global_true_or_false_request_only_plurality_results = global_true_or_false_always_request_only_plurality_results ;
                global_true_or_false_always_request_no_pairwise_counts = global_true ;
                global_true_or_false_request_no_pairwise_counts = global_true_or_false_always_request_no_pairwise_counts ;
                global_true_or_false_always_request_votefair_representation_rank = global_false ;
                global_true_or_false_request_votefair_representation_rank = global_true_or_false_always_request_votefair_representation_rank ;
                global_true_or_false_always_request_votefair_party_rank = global_false ;
                global_true_or_false_request_votefair_party_rank = global_true_or_false_always_request_votefair_party_rank ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for only plurality counts]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_only_plurality_results = global_true ;
                global_true_or_false_request_no_pairwise_counts = global_true ;
                global_true_or_false_request_votefair_representation_rank = global_false ;
                global_true_or_false_request_votefair_party_rank = global_false ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for only plurality counts]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_pairwise_counts )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_no_pairwise_counts = global_false ;
                global_true_or_false_request_no_pairwise_counts = global_true_or_false_always_request_no_pairwise_counts ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for pairwise counts]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_no_pairwise_counts = global_false ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for pairwise counts]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_no_pairwise_counts )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_no_pairwise_counts = global_true ;
                global_true_or_false_request_no_pairwise_counts = global_true_or_false_always_request_no_pairwise_counts ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for no pairwise counts]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_no_pairwise_counts = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for no pairwise counts]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_votefair_representation_rank )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_votefair_representation_rank = global_true ;
                global_true_or_false_request_votefair_representation_rank = global_true_or_false_always_request_votefair_representation_rank ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for VoteFair representation ranking results]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_votefair_representation_rank = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for VoteFair representation ranking results]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_no_votefair_representation_rank )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_votefair_representation_rank = global_false ;
                global_true_or_false_request_votefair_representation_rank = global_true_or_false_always_request_votefair_representation_rank ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for no VoteFair representation ranking results]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_votefair_representation_rank = global_false ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for no VoteFair representation ranking results]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_votefair_party_rank )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_votefair_party_rank = global_true ;
                global_true_or_false_request_votefair_party_rank = global_true_or_false_always_request_votefair_party_rank ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for VoteFair party ranking results]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_votefair_party_rank = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for VoteFair party ranking results]" ; } ;
            }
            continue ;

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_no_votefair_party_rank )
        {
            if ( global_case_number < 1 )
            {
                global_true_or_false_always_request_votefair_party_rank = global_false ;
                global_true_or_false_request_votefair_party_rank = global_true_or_false_always_request_votefair_party_rank ;
                if ( global_logging_info == global_true ) { log_out << "[found all-cases request for no VoteFair party ranking results]" ; } ;
            } else if ( global_current_total_vote_count > 0 )
            {
                if ( global_logging_info == global_true ) { log_out << "[found special request after first ballot started, this request will be ignored]" ; } ;
            } else
            {
                global_true_or_false_request_votefair_party_rank = global_false ;
                if ( global_logging_info == global_true ) { log_out << "[found case-specific request for no VoteFair party ranking results]" ; } ;
            }
            continue ;



// -----------------------------------------------
//  Allow the logging info to be ignored -- for
//  faster execution when the details are not
//  important.

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_logging_off )
        {
            global_logging_info = global_false ;


// -----------------------------------------------
//  Handle the possible code that requests
//  calculating Instant Pairwise Elimination
//  (IPE).

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_instant_pairwise_elimination )
        {
            global_true_or_false_request_instant_pairwise_elimination = global_true ;
            if ( global_logging_info == global_true ) { log_out << "[request ipe]" ; } ;


// -----------------------------------------------
//  Handle the code for a request to use text
//  words -- instead of negative-number codes --
//  in output.

        } else if ( current_vote_info_number == global_voteinfo_code_for_request_text_output )
        {
            global_true_or_false_request_text_output = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[found request for text (instead of negative numbers) in output]" ; } ;
            continue ;


// -----------------------------------------------
//  Handle the code for the end of all cases
//  without yet encountering a case number.

        } else if ( ( current_vote_info_number == global_voteinfo_code_for_end_of_all_cases ) && ( global_case_number < 1 ) )
        {
            if ( global_logging_info == global_true ) { log_out << "[reached end of all cases, but no case has been started]" ; } ;
                std::cout << "Error: Reached end of all cases before case started (list position " << convert_integer_to_text( pointer_to_vote_info ) << ")" ;
            continue ;


// -----------------------------------------------
//  Handle the end of a case.

        } else if ( ( current_vote_info_number == global_voteinfo_code_for_end_of_all_cases ) || ( current_vote_info_number == global_voteinfo_code_for_end_of_all_vote_info ) )
        {
            if ( global_case_number > 0 )
            {
                if ( global_number_of_questions < 1 )
                {
                    if ( global_logging_info == global_true ) { log_out << "[no questions found]" ; } ;
                } else if ( global_current_total_vote_count < 1 )
                {
                    if ( global_logging_info == global_true ) { log_out << "[no ballots found]" ; } ;
                } else
                {
                    for ( global_question_number = 1 ; global_question_number <= global_number_of_questions ; global_question_number ++ )
                    {
                        if ( global_logging_info == global_true ) { log_out << "[question " << global_question_number << " has " << global_choice_count_for_question[ global_question_number ] << " choices]" ; } ;
                        if ( global_choice_count_for_question[ global_question_number ] == 1 )
                        {
                            if ( global_logging_info == global_true ) { log_out << "[only one choice in question " << global_question_number << "]" ; } ;
                            if ( global_logging_info == global_true ) { log_out << "[ignoring case " << global_case_number << "]" ; } ;
                            continue ;
                        } else if ( global_choice_count_for_question[ global_question_number ] < 1 )
                        {
                            if ( global_logging_info == global_true ) { log_out << "[no choices found for question " << global_question_number << "]" ; } ;
                            if ( global_logging_info == global_true ) { log_out << "[ignoring case " << global_case_number << "]" ; } ;
                            continue ;
                        }
                    }
                }
                if ( global_logging_info == global_true ) { log_out << "[case " << global_case_number << " ending without errors]" ; } ;
                if ( global_logging_info == global_true ) { log_out << "[total ballot count " << global_current_total_vote_count << "]" ; } ;
            } else if ( current_vote_info_number != global_voteinfo_code_for_case_number )
            {
                if ( global_logging_info == global_true ) { log_out << "[reached end of case or ballot info, but no case has been started]" ; } ;
                global_possible_error_message = "Error: Encountered case-specific vote-info number before case number specified." ;
                return ;
            }
            global_question_number = 0 ;
            continue ;


// -----------------------------------------------
//  Handle a positive number that appears before
//  the case number.

        } else if ( ( current_vote_info_number > 0 ) && ( global_case_number < 1 ) )
        {
            if ( global_logging_info == global_true ) { log_out << "[positive number encountered before case number specified]" ; } ;
            std::cout << "Error: Positive number (" << current_vote_info_number << ") encountered before case number specified.\n" ;
            continue ;


// -----------------------------------------------
//  Handle a positive number that appears before
//  the first question number.

        } else if ( ( current_vote_info_number > 0 ) && ( global_question_number < 1 ) )
        {
            if ( global_logging_info == global_true ) { log_out << "[choice number not preceded by question number (at list position " << pointer_to_vote_info << ")]" ; } ;
            std::cout << "Error: Positive number (" << current_vote_info_number << ") encountered before first case number.\n" ;
            continue ;


// -----------------------------------------------
//  If the code was not recognized, indicate this
//  situation in the log file, but do not indicate
//  an error (because it will be ignored).

        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[unrecognized code: " << current_vote_info_number << "]" ; } ;
            continue ;
        }


// -----------------------------------------------
//  Repeat the loop that gets the next vote-info
//  number in the list.

    }


// -----------------------------------------------
//  If the code for the end of all cases was not
//  the last code encountered, extend the list by
//  one more number, and insert the
//  end-of-all-cases code.

    if ( current_vote_info_number != global_voteinfo_code_for_end_of_all_cases )
    {
        global_length_of_vote_info_list ++ ;
        global_vote_info_list[ global_length_of_vote_info_list ] = global_voteinfo_code_for_end_of_all_cases ;
    }


// -----------------------------------------------
//  End of function check_vote_info_numbers.

    if ( global_logging_info == global_true ) { log_out << "\n[done checking vote info numbers]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            set_all_choices_as_used
//
//  Specifies that all the choices (for the current
//  question) are used (non-ignored).
//
// -----------------------------------------------
// -----------------------------------------------

void set_all_choices_as_used( )
{
    int actual_choice ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_using_choice[ actual_choice ] = global_true ;
    }
    if ( global_logging_info == global_true ) { log_out << "[setting all choices as used]\n" ; } ;
    return ;
}




// -----------------------------------------------
// -----------------------------------------------
//            reset_ballot_info_and_tally_table
//
//  Restarts the counting of ballot information at
//  the first ballot (in the current case).
//  Also sets up the adjusted (alias) choice numbers
//  and pair counters to exclude the choices being ignored.
//  Also creates and initializes the tally table.
//
// -----------------------------------------------
// -----------------------------------------------

void reset_ballot_info_and_tally_table( )
{

    int actual_choice ;
    int pair_counter ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int adjusted_choice ;


// -----------------------------------------------
//  Reset the ballot vote count.

    global_ballot_info_repeat_count = 0 ;
    global_current_total_vote_count = 0 ;


// -----------------------------------------------
//  Reset the value that normally counts each
//  ballot as having one vote.
//  At some steps in VoteFair representation
//  ranking it is set to a value less than one
//  for some ballots (based on how the voter
//  ranked choices that have already been
//  identified as winning choices).

    global_ballot_influence_amount = 1.0 ;


// -----------------------------------------------
//  Log which choices are not being used.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_using_choice[ actual_choice ] == global_false )
        {
            if ( global_logging_info == global_true ) { log_out << "[ignoring choice " << actual_choice << "]" ; } ;
        }
    }


// -----------------------------------------------
//  Set up the adjusted choice numbers, and the
//  adjusted choice count.

    global_adjusted_choice_count = 0 ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_using_choice[ actual_choice ] == global_true )
        {
            global_adjusted_choice_count ++ ;
            global_adjusted_choice_for_actual_choice[ actual_choice ] = global_adjusted_choice_count ;
            global_actual_choice_for_adjusted_choice[ global_adjusted_choice_count ] = actual_choice ;
            if ( global_logging_info == global_true ) { log_out << "[adjusted choice " << global_adjusted_choice_count << " corresponds to actual choice " << actual_choice << "]" ; } ;
        }
    }
    if ( global_logging_info == global_true ) { log_out << "[adjusted choice count is " << global_adjusted_choice_count << "]" << std::endl ; } ;


// -----------------------------------------------
//  Create the pairwise choice counters.
//  Also create an offset indexing that allows
//  the appropriate pair-counter number to be
//  easily calculated when the two choice
//  numbers are known.

    pair_counter = 0 ;
    global_pair_counter_maximum = 0 ;
    for ( adjusted_first_choice = 1 ; adjusted_first_choice < global_adjusted_choice_count ; adjusted_first_choice ++ )
    {
        global_pair_counter_offset_for_first_adjusted_choice[ adjusted_first_choice ] = pair_counter - adjusted_first_choice ;
        for ( adjusted_second_choice = adjusted_first_choice + 1 ; adjusted_second_choice <= global_adjusted_choice_count ; adjusted_second_choice ++ )
        {
            pair_counter ++ ;
            global_pair_counter_maximum ++ ;
            global_adjusted_first_choice_number_in_pair[ pair_counter ] = adjusted_first_choice ;
            global_adjusted_second_choice_number_in_pair[ pair_counter ] = adjusted_second_choice ;
        }
    }


// -----------------------------------------------
//  Create, and clear, the tally table.

    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        global_tally_first_over_second_in_pair[ pair_counter ] = 0 ;
        global_tally_second_over_first_in_pair[ pair_counter ] = 0 ;
        global_tally_first_equal_second_in_pair[ pair_counter ] = 0 ;
    }


// -----------------------------------------------
//  Initialize the plurality counts.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_plurality_count_for_actual_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  Reset the pointer to the beginning of the
//  ballots for the current case.

    global_pointer_to_current_ballot = global_input_pointer_start_next_case ;


// -----------------------------------------------
//  End of function reset_ballot_info_and_tally_table.

    return ;

}




// -----------------------------------------------
// -----------------------------------------------
//            internal_view_matrix
//
//  For monitoring purposes, writes to the log
//  a matrix with the pairwise counts.
//
// -----------------------------------------------
// -----------------------------------------------

void internal_view_matrix( )
{

    int matrix_row_number ;
    int matrix_column_number ;
    int pair_counter ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int actual_first_choice ;
    int actual_second_choice ;
    int tally ;
    int opposition_score ;
    int percentage ;
    int number_unpadded ;

    std::string sequence_string = "" ;
    std::string text_count ;
    std::string text_count_decimal ;
    std::string text_sequence_score ;
    std::string text_percentage ;

    std::size_t text_length_unused ;


// -----------------------------------------------
//  The sequence must be indicated in the list named
//  global_log_info_choice_at_position.
//  The number of choices is determined by the value
//  of global_adjusted_choice_count.


// -----------------------------------------------
//  Display the tally numbers in a matrix.

    if ( global_logging_info == global_true )
    {
        sequence_string = "" ;
        global_pairwise_matrix_text = "" ;
        global_sequence_score = 0 ;
        opposition_score = 0 ;
        if ( global_scale_for_logged_pairwise_counts < 0.000001 )
        {
            global_scale_for_logged_pairwise_counts = 1.0 ;
        }
        for ( matrix_row_number = 1 ; matrix_row_number <= global_adjusted_choice_count ; matrix_row_number ++ )
        {
            actual_first_choice = global_log_info_choice_at_position[ matrix_row_number ] ;
            adjusted_first_choice = global_adjusted_choice_for_actual_choice[ actual_first_choice ] ;
            if ( sequence_string.length( ) > 0 )
            {
                sequence_string += " , " ;
            }
            sequence_string += convert_integer_to_text( actual_first_choice ) ;
            global_pairwise_matrix_text += "[" ;
            for ( matrix_column_number = 1 ; matrix_column_number <= global_adjusted_choice_count ; matrix_column_number ++ )
            {
                actual_second_choice = global_log_info_choice_at_position[ matrix_column_number ] ;
                adjusted_second_choice = global_adjusted_choice_for_actual_choice[ actual_second_choice ] ;
                tally = 0 ;
                if ( actual_first_choice == actual_second_choice )
                {
                    text_count = " ---" ;
                    text_count_decimal = "  ----- " ;
                } else if ( actual_first_choice < actual_second_choice )
                {
                    pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ adjusted_first_choice ] + adjusted_second_choice ;
                    tally = ( int ) ( ( ( float ) ( global_tally_first_over_second_in_pair[ pair_counter ] ) * global_scale_for_logged_pairwise_counts ) + 0.5 ) ;
                    text_count = pad_integer( tally , 4 ) ;
                    text_count_decimal = pad_real( tally , 6 ) ;
                } else
                {
                    pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ adjusted_second_choice ] + adjusted_first_choice ;
                    tally = ( int ) ( ( ( float ) ( global_tally_second_over_first_in_pair[ pair_counter ] ) * global_scale_for_logged_pairwise_counts ) + 0.5 ) ;
                    text_count = pad_integer( tally , 4 ) ;
                    text_count_decimal = pad_real( tally , 6 ) ;
                }
                global_pairwise_matrix_text += "  " + text_count + "  " ;
                if ( matrix_column_number > matrix_row_number )
                {
                    global_sequence_score += tally ;
                } else
                {
                    opposition_score += tally ;
                }
            }
            global_pairwise_matrix_text += "]\n" ;
        }
        if ( ( global_sequence_score + opposition_score ) > 0 )
        {
            percentage = ( int ) ( ( ( ( float ) global_sequence_score / ( ( float ) ( global_sequence_score + opposition_score ) ) ) * 100 ) + 0.5 ) ;
        } else
        {
            percentage = 0 ;
        }
//        global_pairwise_matrix_text += "[global_sequence_score: " + convert_integer_to_text( global_sequence_score ) + "]\n" ;
//        global_pairwise_matrix_text += "[opposition_score: " + convert_integer_to_text( opposition_score ) + "]\n" ;
        text_sequence_score = convert_integer_to_text( global_sequence_score ) ;
        global_pairwise_matrix_text += "\n[above counts apply to sequence: " + sequence_string + "] [seq score = " + text_sequence_score + "]\n" ;
        text_percentage = convert_integer_to_text( percentage ) ;
        global_pairwise_matrix_text += "[percent support: " + text_percentage + "]\n" ;
        log_out << std::endl << global_pairwise_matrix_text << std::endl ;
    }


// -----------------------------------------------
//  Reset the scale value in case it is not
//  reset elsewhere.

    global_scale_for_logged_pairwise_counts = 1.0 ;


// -----------------------------------------------
//  End of function internal_view_matrix.

    return ;

}




// -----------------------------------------------
// -----------------------------------------------
//            comparison_for_normalize_ranking
//
//  Compares the ranking levels of two choices
//  based on adjusted choice pointers, for use
//  when sorting by ranking levels that are
//  separated by big gaps.
//  The lower rank number is sorted to come before,
//  not after, the higher rank number.
//
// -----------------------------------------------
// -----------------------------------------------

bool comparison_for_normalize_ranking( int adjusted_choice_one , int adjusted_choice_two )
{
//    log_out << "[comparing adjusted choice " << adjusted_choice_one << " at rank " << global_rank_to_normalize_for_adjusted_choice[ adjusted_choice_one ] << " and adjusted choice " << adjusted_choice_two << " at rank " <<  global_rank_to_normalize_for_adjusted_choice[ adjusted_choice_two ] << "]" << std::endl ;
    return ( global_rank_to_normalize_for_adjusted_choice[ adjusted_choice_one ] < global_rank_to_normalize_for_adjusted_choice[ adjusted_choice_two ] ) ;
}
//  End of function comparison_for_normalize_ranking.



// -----------------------------------------------
// -----------------------------------------------
//            normalize_ranking
//
// Normalizes ranking levels so that ranking levels
// are sequential integer numbers (with no numbers
// skipped).
//
// -----------------------------------------------
// -----------------------------------------------

void normalize_ranking( )
{

    int adjusted_choice ;
    int actual_choice ;
    int ranking_level ;
    int current_adjusted_choice ;
    int previous_adjusted_choice ;
    int new_ranking_level ;
    int sequence_position ;
    int true_or_false_log_details ;
    int adjusted_choice_one ;
    int adjusted_choice_two ;
    int sorted_position ;


// -----------------------------------------------
//  Hide (or show) details.

    true_or_false_log_details = global_false ;
    if ( global_logging_info == global_false )
    {
        true_or_false_log_details = global_false ;
    }


// -----------------------------------------------
//  Create a sequence of adjusted choice numbers that
//  will be rearranged during sorting.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        global_sortable_sequence_used_during_normalization[ adjusted_choice ] = adjusted_choice ;
    }


// -----------------------------------------------
//  Sort the adjusted choice numbers according to
//  their rank levels.
//  The sorting criteria is in the function named
//  comparison_for_normalize_ranking, and it sorts
//  based on the un-normalized ranking levels.
//  Sorting is not done directly in the original list
//  because the sort utility swaps values.

    std::sort( global_sortable_sequence_used_during_normalization + 1 , global_sortable_sequence_used_during_normalization + global_adjusted_choice_count + 1 , comparison_for_normalize_ranking ) ;


// -----------------------------------------------
//  Normalize the ranking levels so that no
//  ranking levels are skipped.
//  While doing this, put into the
//  global_log_info_choice_at_position
//  list the actual choice numbers in the
//  calculated sequence -- so that the
//  internal_view_matrix function can use this
//  sequence to display the normalized results.

    previous_adjusted_choice = 0 ;
    sequence_position = 1 ;
    new_ranking_level = 0 ;
    if ( true_or_false_log_details == global_true ) { log_out << "[normalizing rank levels]" << std::endl ; } ;
    for ( sorted_position = 1 ; sorted_position <= global_adjusted_choice_count ; sorted_position ++ )
    {
        current_adjusted_choice = global_sortable_sequence_used_during_normalization[ sorted_position ] ;
        if ( global_rank_to_normalize_for_adjusted_choice[ current_adjusted_choice ] != global_rank_to_normalize_for_adjusted_choice[ previous_adjusted_choice ] )
        {
            new_ranking_level ++ ;
        }
        global_normalized_ranking_level_for_adjusted_choice[ current_adjusted_choice ] = new_ranking_level ;
        previous_adjusted_choice = current_adjusted_choice ;
        actual_choice = global_actual_choice_for_adjusted_choice[ current_adjusted_choice ] ;
        global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
        sequence_position ++ ;
        if ( true_or_false_log_details == global_true ) { log_out << "[rank of choice " << actual_choice << " (adjusted choice " << current_adjusted_choice << ") is now " << new_ranking_level << " (was " << 
global_rank_to_normalize_for_adjusted_choice[ current_adjusted_choice ] << ")]" << std::endl ; } ;
    }
    if ( true_or_false_log_details == global_true ) { log_out << "[normalization done]" << std::endl ; } ;


// -----------------------------------------------
//  Copy the results to overwrite the un-normalized
//  ranking levels.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] = global_normalized_ranking_level_for_adjusted_choice[ adjusted_choice ] ;
    }


// -----------------------------------------------
//  End of function normalize_ranking.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            compare_popularity_results
//
//  Compares the results of different methods for
//  calculating VoteFair popularity ranking.
//
// -----------------------------------------------
// -----------------------------------------------

void compare_popularity_results( )
{

    int actual_choice ;
    int adjusted_choice ;
    int sequence_position ;
    int ranking_level ;
    int ranking_level_official ;
    int ranking_level_choice_specific_pairwise_score ;
    int ranking_level_insertion_sort ;

    std::string comparison_of_methods_table ;
    std::string possible_text_insertion_sort_not_the_same ;
    std::string possible_text_choice_specific_pairwise_score_not_the_same ;
    std::string text_actual_choice ;

    std::size_t text_length_unused ;


// -----------------------------------------------
//  Sort the official ranking results into a list
//  that is used when listing choice rankings,
//  which means that within the same ranking,
//  a lower choice number appears before a higher
//  choice number.

    sequence_position = 1 ;
    for ( ranking_level = 0 ; ranking_level <= global_adjusted_choice_count ; ranking_level ++ )
    {
        for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
        {
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == ranking_level )
            {
                global_actual_choice_at_popularity_list_sequence_position[ sequence_position ] = actual_choice ;
                global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
                sequence_position ++ ;
            }
        }
    }


// -----------------------------------------------
//  Log a display of the tally numbers in
//  an array version.

    if ( global_logging_info == global_true )
    {
        log_out << "[compare pop results, ordered pairwise counts:]\n" ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  Convert the tally numbers into percentages,
//  and display those values.

    if ( global_logging_info == global_true )
    {
        log_out << "[compare pop results, total vote count is " << global_current_total_vote_count << "]" << std::endl ;
        global_scale_for_logged_pairwise_counts = 100.0 / ( ( float ) global_current_total_vote_count ) ;
        log_out << "[global_scale_for_logged_pairwise_counts: " + convert_float_to_text( global_scale_for_logged_pairwise_counts ) + "]\n" ;
        log_out << "[compare pop results, pairwise counts as percent numbers (if only scaled by total votes):]\n" ;
        internal_view_matrix( ) ;
        global_scale_for_logged_pairwise_counts = 1.0 ;
    }


// -----------------------------------------------
//  As a check, compare the results of the
//  different ranking calculations.
//  Sort the results by popularity.

    global_comparison_count ++ ;
    possible_text_insertion_sort_not_the_same = "InsSrt same" ;
    possible_text_choice_specific_pairwise_score_not_the_same = "CSPS same" ;
    comparison_of_methods_table = "[compare pop results, case " + convert_integer_to_text( global_case_number ) + " , question " + convert_integer_to_text( global_question_number ) + " , rank type = " + global_ranking_type_being_calculated + "]\n" ;
    comparison_of_methods_table += "[compare pop results, columns: official, insertion, estimated]\n" ;
    for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
    {
        actual_choice = global_actual_choice_at_popularity_list_sequence_position[ sequence_position ] ;
        adjusted_choice = global_adjusted_choice_for_actual_choice[ actual_choice ] ;
        ranking_level_official = global_popularity_ranking_for_actual_choice[ actual_choice ] ;
        ranking_level_choice_specific_pairwise_score = global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] ;
        ranking_level_insertion_sort = global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] ;
        text_actual_choice = convert_integer_to_text( actual_choice ) ;
        comparison_of_methods_table += "[choice " + text_actual_choice + " at levels " + convert_integer_to_text( ranking_level_official ) + " , " + convert_integer_to_text( ranking_level_insertion_sort ) + " , " + convert_integer_to_text( ranking_level_choice_specific_pairwise_score ) + "]" ;
        if ( ranking_level_official != ranking_level_insertion_sort )
        {
            possible_text_insertion_sort_not_the_same = "InsSrt NOT same" ;
            comparison_of_methods_table += " ****** " ;
        }
        if ( ranking_level_official != ranking_level_choice_specific_pairwise_score )
        {
            possible_text_choice_specific_pairwise_score_not_the_same = "CSPS NOT same" ;
            comparison_of_methods_table += " ------ " ;
        }
        comparison_of_methods_table += "\n" ;
    }
    if ( possible_text_insertion_sort_not_the_same == "InsSrt NOT same" )
    {
        global_not_same_count ++ ;
    }
    comparison_of_methods_table += "[" + possible_text_insertion_sort_not_the_same + "][" + possible_text_choice_specific_pairwise_score_not_the_same + "][case " + convert_integer_to_text( global_case_number ) + " question " + convert_integer_to_text( global_question_number ) + "]\n\n" ;
    if ( global_logging_info == global_true ) { log_out << comparison_of_methods_table << std::endl ; } ;


// -----------------------------------------------
//  Count how many rankings have been done.

    global_count_of_popularity_rankings ++ ;
//    if ( global_logging_info == global_true ) { log_out << "[count of popularity rankings: " << global_count_of_popularity_rankings << "]" << std::endl ; } ;


// -----------------------------------------------
//  End of function compare_popularity_results.

    if ( global_logging_info == global_true ) { log_out << "[compare pop results, exiting function]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            output_plurality_counts
//
//  Puts into the output results the plurality
//  counts.
//
// -----------------------------------------------
// -----------------------------------------------

void output_plurality_counts( )
{

    int actual_choice ;


// -----------------------------------------------
//  Put the plurality counts into the output
//  results list.

    put_next_result_info_number( global_voteinfo_code_for_start_of_plurality_results ) ;
    if ( global_logging_info == global_true ) { log_out << "[output, plurality counts:]\n" ; } ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        put_next_result_info_number( global_voteinfo_code_for_choice ) ;
        put_next_result_info_number( actual_choice ) ;
        put_next_result_info_number( global_voteinfo_code_for_plurality_count ) ;
        put_next_result_info_number( global_plurality_count_for_actual_choice[ actual_choice ] ) ;
        if ( global_plurality_count_for_actual_choice[ actual_choice ] > 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[output, plurality count for choice " << actual_choice << " is " << global_plurality_count_for_actual_choice[ actual_choice ] << "]" << std::endl ; } ;
        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[output, plurality count for choice " << actual_choice << " is " << "0" << "]" << std::endl ; } ;
        }
    }
    put_next_result_info_number( global_voteinfo_code_for_end_of_plurality_results ) ;


// -----------------------------------------------
//  End of function output_plurality_counts.

    return ;

}




// -----------------------------------------------
// -----------------------------------------------
//        output_tally_table_numbers
//
//  Puts the pairwise counts from the tally table
//  into the output list.
//
// -----------------------------------------------
// -----------------------------------------------

void output_tally_table_numbers( )
{

    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int actual_first_choice ;
    int actual_second_choice ;
    int pair_counter ;


// -----------------------------------------------
//  This function must be used while the pairwise
//  counts for all the choices are still in the
//  tally table.


// -----------------------------------------------
//  Output the pairwise counts from the tally table.

    put_next_result_info_number( global_voteinfo_code_for_start_of_tally_table_results ) ;
    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        adjusted_first_choice = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
        adjusted_second_choice = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;

        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;

        if ( ( adjusted_first_choice != actual_first_choice ) || ( adjusted_second_choice != actual_second_choice ) )
        {
            if ( global_logging_info == global_true ) { log_out << "[error: in output_tally_table_numbers function, actual and adjusted choice numbers do not match]" ; } ;
            global_possible_error_message = "Error: function output_tally_table_numbers used inappropriately." ;
            return ;
        }

        put_next_result_info_number( global_voteinfo_code_for_first_choice ) ;
        put_next_result_info_number( actual_first_choice ) ;

        put_next_result_info_number( global_voteinfo_code_for_second_choice ) ;
        put_next_result_info_number( actual_second_choice ) ;

        put_next_result_info_number( global_voteinfo_code_for_tally_first_over_second ) ;
        put_next_result_info_number( global_tally_first_over_second_in_pair[ pair_counter ] ) ;

        put_next_result_info_number( global_voteinfo_code_for_tally_second_over_first ) ;
        put_next_result_info_number( global_tally_second_over_first_in_pair[ pair_counter ] ) ;

    }
    put_next_result_info_number( global_voteinfo_code_for_end_of_tally_table_results ) ;


// -----------------------------------------------
//  End of function output_tally_table_numbers.

    return ;

}




// -----------------------------------------------
// -----------------------------------------------
//            output_ranking_results
//
//  Outputs the results of the requested VoteFair
//  Ranking results.  These results are supplied in
//  two forms: in their sequence order, and in order
//  of their choice number.
//
// -----------------------------------------------
// -----------------------------------------------

void output_ranking_results( )
{

    int actual_choice ;
    int ranking_level ;
    int ranking_type_number ;
    int ranking_type_number_for_popularity ;
    int ranking_type_number_for_representation ;
    int ranking_type_number_for_party ;
    int start_code ;
    int end_code ;
    int count_of_ranked_choices ;
    int sum_of_rankings ;
    int count_of_choices_found_at_this_ranking_level ;

    int sequence_start_code_for_ranking_type[ 201 ] ;
    int sequence_end_code_for_ranking_type[ 201 ] ;
    int levels_start_code_for_ranking_type[ 201 ] ;
    int levels_end_code_for_ranking_type[ 201 ] ;
    int ranking_level_result_for_actual_choice[ 201 ] ;

    std::string ranking_type_name ;
    std::string ranking_type_name_for_number[ 200 ] ;


// -----------------------------------------------
//  Set up lists that allow the different kinds
//  of ranking to have their associated code
//  numbers in indexed lists.

    ranking_type_number_for_popularity = 1 ;
    ranking_type_name_for_number[ ranking_type_number_for_popularity ] = "popularity" ;
    sequence_start_code_for_ranking_type[ ranking_type_number_for_popularity ] = global_voteinfo_code_for_start_of_votefair_popularity_ranking_sequence_results ;
    sequence_end_code_for_ranking_type[ ranking_type_number_for_popularity ] = global_voteinfo_code_for_end_of_votefair_popularity_ranking_sequence_results ;
    levels_start_code_for_ranking_type[ ranking_type_number_for_popularity ] = global_voteinfo_code_for_start_of_votefair_popularity_ranking_levels_results ;
    levels_end_code_for_ranking_type[ ranking_type_number_for_popularity ] = global_voteinfo_code_for_end_of_votefair_popularity_ranking_levels_results ;

    ranking_type_number_for_representation = 2 ;
    ranking_type_name_for_number[ ranking_type_number_for_representation ] = "representation" ;
    sequence_start_code_for_ranking_type[ ranking_type_number_for_representation ] = global_voteinfo_code_for_start_of_votefair_representation_ranking_sequence_results ;
    sequence_end_code_for_ranking_type[ ranking_type_number_for_representation ] = global_voteinfo_code_for_end_of_votefair_representation_ranking_sequence_results ;
    levels_start_code_for_ranking_type[ ranking_type_number_for_representation ] = global_voteinfo_code_for_start_of_votefair_representation_ranking_levels_results ;
    levels_end_code_for_ranking_type[ ranking_type_number_for_representation ] = global_voteinfo_code_for_end_of_votefair_representation_ranking_levels_results ;

    ranking_type_number_for_party = 3 ;
    ranking_type_name_for_number[ ranking_type_number_for_party ] = "party" ;
    sequence_start_code_for_ranking_type[ ranking_type_number_for_party ] = global_voteinfo_code_for_start_of_votefair_party_ranking_sequence_results ;
    sequence_end_code_for_ranking_type[ ranking_type_number_for_party ] = global_voteinfo_code_for_end_of_votefair_party_ranking_sequence_results ;
    levels_start_code_for_ranking_type[ ranking_type_number_for_party ] = global_voteinfo_code_for_start_of_votefair_party_ranking_levels_results ;
    levels_end_code_for_ranking_type[ ranking_type_number_for_party ] = global_voteinfo_code_for_end_of_votefair_party_ranking_levels_results ;


// -----------------------------------------------
//  Begin a loop that handles each of the three
//  different ranking types.

    for ( ranking_type_number = 1 ; ranking_type_number <= 3 ; ranking_type_number ++ )
    {
        ranking_type_name = ranking_type_name_for_number[ ranking_type_number ] ;


// -----------------------------------------------
//  Copy the ranking levels for the kind of
//  ranking being sent to the code-number
//  output list.

        sum_of_rankings = 0 ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( ranking_type_number == ranking_type_number_for_popularity )
            {
                ranking_level_result_for_actual_choice[ actual_choice ] = global_full_popularity_ranking_for_actual_choice[ actual_choice ] ;
            } else if ( ranking_type_number == ranking_type_number_for_representation )
            {
                ranking_level_result_for_actual_choice[ actual_choice ] = global_full_representation_ranking_for_actual_choice[ actual_choice ] ;
            } else if ( ranking_type_number == ranking_type_number_for_party )
            {
                ranking_level_result_for_actual_choice[ actual_choice ] = global_party_ranking_for_actual_choice[ actual_choice ] ;
            }
            sum_of_rankings += ranking_level_result_for_actual_choice[ actual_choice ] ;
        }


// -----------------------------------------------
//  If there are only zero ranking values,
//  create an error message, and skip the
//  outputting of these all-zero values.

        if ( sum_of_rankings < 1 )
        {
            if ( global_logging_info == global_true ) { log_out << "[output, all-zero results for " << ranking_type_name << " ranking, so none written]\n" ; } ;
            continue ; // was "next"
        }


// -----------------------------------------------
//  Output specified ranking results as coded
//  numbers in which each choice is associated
//  with a ranking level.

        if ( global_logging_info == global_true ) { log_out << "[output, ranking results for " << ranking_type_name << " ranking:]\n" ; } ;
        start_code = levels_start_code_for_ranking_type[ ranking_type_number ] ;
        put_next_result_info_number( start_code ) ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            ranking_level = ranking_level_result_for_actual_choice[ actual_choice ] ;
            put_next_result_info_number( global_voteinfo_code_for_choice ) ;
            put_next_result_info_number( actual_choice ) ;
            put_next_result_info_number( global_voteinfo_code_for_ranking_level ) ;
            put_next_result_info_number( ranking_level ) ;
            if ( global_logging_info == global_true ) { log_out << "[output, choice " << actual_choice << " is at ranking level " << ranking_level  << "]" << std::endl ; } ;
        }
        end_code = levels_end_code_for_ranking_type[ ranking_type_number ] ;
        put_next_result_info_number( end_code ) ;


// -----------------------------------------------
//  Output the ranking as a sequence of
//  choice numbers, with ties and transitions (to
//  the next ranking level) indicated.

        if ( global_logging_info == global_true ) { log_out << "[output, sequence results for " << ranking_type_name << " ranking:]\n" ; } ;
        start_code = sequence_start_code_for_ranking_type[ ranking_type_number ] ;
        put_next_result_info_number( start_code ) ;
        count_of_ranked_choices = 0 ;
        for ( ranking_level = 1 ; ranking_level <= global_full_choice_count ; ranking_level ++ )
        {
            count_of_choices_found_at_this_ranking_level = 0 ;
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( ranking_level_result_for_actual_choice[ actual_choice ] == ranking_level )
                {
                    if ( count_of_choices_found_at_this_ranking_level > 0 )
                    {
                        put_next_result_info_number( global_voteinfo_code_for_tie ) ;
                    } else if ( count_of_ranked_choices > 0 )
                    {
                        put_next_result_info_number( global_voteinfo_code_for_next_ranking_level ) ;
                    }
                    put_next_result_info_number( global_voteinfo_code_for_choice ) ;
                    put_next_result_info_number( actual_choice ) ;
                    if ( global_logging_info == global_true ) { log_out << "[output, choice " << actual_choice << " is next in sequence at ranking level " << ranking_level  << "]" << std::endl ; } ;
                    count_of_choices_found_at_this_ranking_level ++ ;
                    count_of_ranked_choices ++ ;
                }
            }
        }
        if ( count_of_ranked_choices < global_full_choice_count )
        {
            put_next_result_info_number( global_voteinfo_code_for_early_end_of_ranking ) ;
        }
        end_code = sequence_end_code_for_ranking_type[ ranking_type_number ] ;
        put_next_result_info_number( end_code ) ;
        if ( global_logging_info == global_true ) { log_out << "[output, end of " << ranking_type_name << " ranking sequence]\n" ; } ;


// -----------------------------------------------
//  Repeat the loop that handles each type of
//  ranking.

    }


// -----------------------------------------------
//  End of function output_ranking_results.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//          get_numbers_based_on_one_ballot
//
//  Gets the preference information from the next
//  ballot.  This information may include an optional
//  multiple-ballot count that indicates how many
//  ballots have the same specified preferences.
//
// -----------------------------------------------
// -----------------------------------------------

int get_numbers_based_on_one_ballot( )
{

    int current_vote_info_number ;
    int next_vote_info_number ;
    int current_question_number ;
    int preference_level ;
    int choice_number ;
    int choice_at_top_preference_level ;
    int choice_count_at_top_preference_level ;
    int count_of_encountered_ballot_counts ;

    std::string text_ballot_info ;


// -----------------------------------------------
//  Initialization.

    current_question_number = 0 ;
    choice_number = 0 ;
    count_of_encountered_ballot_counts = 0 ;
    choice_count_at_top_preference_level = 0 ;
    choice_at_top_preference_level = 0 ;
    preference_level = 1 ;


// -----------------------------------------------
//  In case any of the choice numbers are not
//  encountered, initialize all the preference
//  levels to the last level.

    for ( choice_number = 1 ; choice_number <= global_full_choice_count ; choice_number ++ )
    {
        global_ballot_preference_for_choice[ choice_number ] = global_full_choice_count ;
    }


// -----------------------------------------------
//  If the pointer is already at the end of the
//  ballots, return with a value of zero.

        current_vote_info_number = global_vote_info_list[ global_pointer_to_current_ballot ] ;
        if ( ( current_vote_info_number == global_voteinfo_code_for_end_of_all_vote_info ) || ( current_vote_info_number == global_voteinfo_code_for_case_number ) || ( current_vote_info_number == global_voteinfo_code_for_end_of_all_cases ) )
        {
            global_ballot_info_repeat_count = 0 ;
            if ( global_logging_info == global_true ) { log_out << "[end of ballots]\n" ; } ;
            return 0 ;
        }


// -----------------------------------------------
//  Initially assume that the ballot count is
//  one.

    global_ballot_info_repeat_count = 1 ;
    text_ballot_info = "q " + convert_integer_to_text( global_question_number ) + " " ;


// -----------------------------------------------
//  Repeat a loop that handles each vote-info
//  number within one ballot.

    while ( global_pointer_to_current_ballot < global_maximum_vote_info_list_length )
    {


// -----------------------------------------------
//  Get the current vote-info number and, just in
//  case it's needed, the one after it.

        current_vote_info_number = global_vote_info_list[ global_pointer_to_current_ballot ] ;
        if ( global_pointer_to_current_ballot < global_maximum_vote_info_list_length - 1 )
        {
            next_vote_info_number = global_vote_info_list[ global_pointer_to_current_ballot + 1 ] ;
        } else
        {
            next_vote_info_number = 0 ;
        }


// -----------------------------------------------
//  If the end of all the vote info, or the next
//  case number, or the end of all the cases,
//  has been reached, exit the loop.

        if ( ( current_vote_info_number == global_voteinfo_code_for_end_of_all_vote_info ) || ( current_vote_info_number == global_voteinfo_code_for_case_number ) || ( current_vote_info_number == global_voteinfo_code_for_end_of_all_cases ) )
        {
            break ;


// -----------------------------------------------
//  When the end of the ballot is reached, point
//  to the beginning of the next ballot and exit
//  the loop.

        } else if ( current_vote_info_number == global_voteinfo_code_for_end_of_ballot )
        {
            global_pointer_to_current_ballot ++ ;
            break ;


// -----------------------------------------------
//  If a ballot count (see next section) has been
//  encountered for a second time, the beginning
//  of the next ballot has been reached, so leave
//  the pointer pointing to the beginning of this
//  next ballot and exit the loop.

        } else if ( ( current_vote_info_number == global_voteinfo_code_for_ballot_count ) && ( count_of_encountered_ballot_counts > 0 ) )
        {
            break ;


// -----------------------------------------------
//  Get the count for the number of identical
//  ballots (that have the same ranking sequence).
//  This vote count will be returned, or a value
//  of zero will be returned when there are no
//  more ballots encountered.  Also count a
//  second ballot count in case an end-of-ballot
//  code is not used at the end of each ballot.

        } else if ( current_vote_info_number == global_voteinfo_code_for_ballot_count )
        {
            global_ballot_info_repeat_count = next_vote_info_number ;
            global_pointer_to_current_ballot ++ ;
            count_of_encountered_ballot_counts ++ ;


// -----------------------------------------------
//  Get the question number for the current
//  vote-info preference information.

        } else if ( current_vote_info_number == global_voteinfo_code_for_question_number )
        {
            current_question_number = next_vote_info_number ;
            global_pointer_to_current_ballot ++ ;


// -----------------------------------------------
//  If the current preference levels do not apply
//  to the question being handled, skip ahead
//  over the handling of other codes.

        } else if ( current_question_number == global_question_number )
        {


// -----------------------------------------------
//  If a preference level is explicitly supplied,
//  adjust the preference level.

            if ( current_vote_info_number == global_voteinfo_code_for_preference_level )
            {
                preference_level = next_vote_info_number ;
                global_pointer_to_current_ballot ++ ;


// -----------------------------------------------
//  Adjust the preference level at tied levels.

            } else if ( current_vote_info_number == global_voteinfo_code_for_tie )
            {
                preference_level -- ;
                if ( preference_level == 1 )
                {
                    choice_count_at_top_preference_level ++ ;
                    choice_at_top_preference_level = 0 ;
                }
                text_ballot_info += " tie" ;


// -----------------------------------------------
//  For a choice number, determine its preference
//  level.
//  If this choice is at the top preference level,
//  save it -- for possible use in plurality
//  counting.

            } else if ( current_vote_info_number > 0 )
            {
                choice_number = current_vote_info_number ;
                global_ballot_preference_for_choice[ choice_number ] = preference_level ;
                text_ballot_info += " " + convert_integer_to_text( choice_number ) ;
                if ( preference_level == 1 )
                {
                    choice_count_at_top_preference_level ++ ;
                    choice_at_top_preference_level = choice_number ;
                }
                preference_level ++ ;
            }


// -----------------------------------------------
//  Finish skipping over the handling of codes
//  that do not apply to the question being
//  handled.

        }


// -----------------------------------------------
//  Repeat the loop to handle the next
//  vote-info number.

        global_pointer_to_current_ballot ++ ;
    }


// -----------------------------------------------
//  If there was only one choice at the top
//  preference level, increment the plurality
//  count for that choice.

    if ( ( choice_count_at_top_preference_level == 1 ) && ( choice_at_top_preference_level > 0 ) )
    {
        global_plurality_count_for_actual_choice[ choice_at_top_preference_level ] += global_ballot_info_repeat_count ;
    }


// -----------------------------------------------
//  Accumulate the total ballot vote count.

    global_current_total_vote_count += global_ballot_info_repeat_count ;


// -----------------------------------------------
//  Return with the number of ballot counts
//  handled.  If zero, there are no
//  more ballots in this question.

    if ( global_logging_info == global_true ) { log_out << "[x " << global_ballot_info_repeat_count << " " << text_ballot_info << "]" ; } ;
    return global_ballot_info_repeat_count ;


// -----------------------------------------------
//  End of function get_numbers_based_on_one_ballot.

}



// -----------------------------------------------
// -----------------------------------------------
//        add_preferences_to_tally_table
//
//  Adds to the tally table the just-acquired
//  preference numbers (from the current ballot).
//
// -----------------------------------------------
// -----------------------------------------------

void add_preferences_to_tally_table( )
{

    int pair_counter ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int actual_first_choice ;
    int actual_second_choice ;
    int tally_amount ;


// -----------------------------------------------
//  Update the tally table with the current ballot information.
//  Normally the influence amount is one, but it can be
//  a fractional vote in some VoteFair representation
//  calculations.

    tally_amount = ( int ) ( ( ( ( float ) global_ballot_info_repeat_count ) * global_ballot_influence_amount ) + 0.5 ) ;
    if ( global_logging_info == global_true ) { log_out << "[tally preference amount: " << convert_integer_to_text( tally_amount ) << "]\n" ; } ;
    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        adjusted_first_choice = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
        adjusted_second_choice = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;
        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
        if ( global_ballot_preference_for_choice[ actual_first_choice ] < global_ballot_preference_for_choice[ actual_second_choice ] )
        {
            global_tally_first_over_second_in_pair[ pair_counter ] += tally_amount ;
        } else if ( global_ballot_preference_for_choice[ actual_first_choice ] > global_ballot_preference_for_choice[ actual_second_choice ] )
        {
            global_tally_second_over_first_in_pair[ pair_counter ] += tally_amount ;
        } else
        {
            global_tally_first_equal_second_in_pair[ pair_counter ] += tally_amount ;
        }
    }


// -----------------------------------------------
//  End of function add_preferences_to_tally_table.

    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            calc_all_sequence_scores
//
//  Calculates VoteFair popularity ranking
//  results by calculating every sequence score to
//  find the highest score, and regarding the
//  sequence (ranking) with the highest score to be
//  the overall ranking.  For details, see
//  www.VoteFair.org or Wikipedia's
//  "Condorcet-Kemeny method" article (which
//  currently redirects to the "Kemeny-Young method"
//  article) or the book titled "Ending The Hidden
//  Unfairness In U.S. Elections".
//
// If multiple sequences have the same highest score,
// calculate the average sequence position for each
// choice (but only for the sequences that have the
// highest score), and then normalize (remove gaps
// from) those rankings.
//
// -----------------------------------------------
// -----------------------------------------------

void calc_all_sequence_scores( )
{

    int score ;
    int highest_score ;
    int actual_choice ;
    int adjusted_choice ;
    int first_choice_number ;
    int second_choice_number ;
    int position_in_sequence ;
    int position_to_shift ;
    int sequence_count ;
    int sequence_position ;
    int removal_position ;
    int pair_counter ;
    int counter ;
    int main_loop_count ;
    int ranking_level ;
    int true_or_false_continue_loop ;
    int true_or_false_log_details ;
    int true_or_false_log_all_sequences_details ;
    int top_down_rank ;
    int bottom_up_rank ;
    int average ;
    int count_of_same_highest_score ;

    std::string sequence_info ;
    std::string  ranking_info ;
    std::string  ranking_changes_info ;
    std::string  score_info ;

    int sequence_count_at_position[ 201 ] ;
    int maximum_sequence_count_at_position[ 201 ] ;
    int sequence_position_for_adjusted_choice[ 201 ] ;
    int count_of_sequences_with_highest_ranking_for_adjusted_choice[ 201 ] ;
    int count_of_sequences_with_lowest_ranking_for_adjusted_choice[ 201 ] ;
    int sum_of_rankings_at_highest_score_for_adjusted_choice[ 201 ] ;
    int count_of_rankings_at_highest_score_for_adjusted_choice[ 201 ] ;
    int choice_in_remainder_position[ 201 ] ;


// -----------------------------------------------
//  Hide or show the details in the log file.

    true_or_false_log_details = global_true ;
    true_or_false_log_all_sequences_details = global_false ;
    if ( global_logging_info == global_false )
    {
        true_or_false_log_details = global_false ;
    }
    if ( true_or_false_log_details == global_false )
    {
        true_or_false_log_all_sequences_details = global_false ;
    }
    if ( global_logging_info == global_true )
    {
        log_out << "\n[all scores, beginning calc_all_sequence_scores function]\n" ;
        if ( true_or_false_log_details == global_true )
        {
            log_out << "[all scores, some details shown (change flag value to hide details)]\n" ;
            if ( true_or_false_log_all_sequences_details == global_false )
            {
                log_out << "[all scores, details for every sequence hidden (change flag value to view details)]\n" ;
            }
        } else
        {
            log_out << "[all scores, details hidden (change flag value to view details)]\n" ;
        }
    }


// -----------------------------------------------
//  In case of an early error, initialize the
//  ranking of each choice -- to zero.

    for ( adjusted_choice = 1; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_popularity_ranking_for_actual_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  If there are not at least two choices,
//  there is a program bug because that should
//  have already been checked.

    if ( global_adjusted_choice_count < 2 )
    {
        if ( global_logging_info == global_true ) { log_out << "[all scores, ERROR: number of (adjusted) choices is less than two]\n" ; } ;
        global_possible_error_message = "Error: Attempting to rank only a single choice." ;
        return ;
    }


// -----------------------------------------------
//  If there are too many choices, indicate an
//  error.

    if ( global_adjusted_choice_count > global_check_all_scores_choice_limit )
    {
        if ( global_logging_info == global_true ) { log_out << "[all scores, ERROR: number of (adjusted) choices exceeds limit (" << global_check_all_scores_choice_limit << ")]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Initialize the ranking information that is
//  tracked for each choice.
//  Initialize the counter that counts how many
//  sequences have the same highest sequence
//  score.  Also initialize the sum that adds the
//  ranking-sequence levels at which a highest
//  sequence score occurs.  If there is only one
//  sequence with the highest score, this sum
//  will equal that sequence position.
//
//  Also, for comparison purposes, initialize
//  two other rank-tracking values.  One such
//  value tracks the highest ranking
//  encountered (in a highest-score sequence),
//  and the other value tracks the lowest
//  ranking encountered (in a highest-score
//  sequence).  Also initialize the counts of
//  how many sequences have these highest or
//  lowest rankings.

    if ( true_or_false_log_details == global_true ) { log_out << "[all scores, beginning to calculate VoteFair popularity results]\n" ; } ;
    for ( adjusted_choice = 1; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        count_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] = 0 ;
        sum_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] = 0 ;
        global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ adjusted_choice ] = global_adjusted_choice_count + 1 ;
        global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] = 0 ;
        count_of_sequences_with_highest_ranking_for_adjusted_choice[ adjusted_choice ] = 0 ;
        count_of_sequences_with_lowest_ranking_for_adjusted_choice[ adjusted_choice ] = 0 ;
    }


// -----------------------------------------------
//  Calculate the number of possible sequences to
//  check, and log this number.

    if ( true_or_false_log_details == global_true )
    {
        sequence_count = 1 ;
        for ( counter = 2 ; counter <= global_adjusted_choice_count ; counter ++ )
        {
            sequence_count = sequence_count * counter ;
        }
        log_out << "[all scores, number of sequences to check is " << sequence_count << "]" ;
    }


// -----------------------------------------------
//  Initialize a list of numbers that will be
//  used to cycle through all the possible
//  sequences.  Also specify the maximum count
//  value that is allowed for each position in that list.

    for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
    {
        sequence_count_at_position[ sequence_position ] = 1 ;
        maximum_sequence_count_at_position[ sequence_position ] = global_adjusted_choice_count - sequence_position + 1 ;
    }
    if ( true_or_false_log_details == global_true ) { log_out << std::endl ; } ;


// -----------------------------------------------
//  Begin a loop that checks each possible
//  sequence, in terms of which choice is first,
//  which is second, etc.

    main_loop_count = 0 ;
    true_or_false_continue_loop = global_true ;
    highest_score = 0 ;
    count_of_same_highest_score = 0 ;
    while ( true_or_false_continue_loop == global_true )
    {
        main_loop_count ++ ;
        if ( main_loop_count > 10000 )
        {
            if ( global_logging_info == global_true ) { log_out << "[all scores, Warning: Too many choices (" << global_adjusted_choice_count << "), so only plurality results calculated]\n" ; } ;
            if ( global_logging_info == global_true ) { log_out << "[all scores, exiting main loop early]" ; } ;
            return ;
        }


// -----------------------------------------------
//  Initialize some logging text strings.

        sequence_info = " sequence: " ;
        ranking_info = "  ranking: " ;
        ranking_changes_info = "" ;
        global_log_info_choice_at_position[ 0 ] = 0 ;


// -----------------------------------------------
//  Put all the choice numbers into a
//  number-ordered list named
//  "choice_in_remainder_position".

        for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
        {
            adjusted_choice = sequence_position ;
            choice_in_remainder_position[ sequence_position ] = adjusted_choice ;
        }


// -----------------------------------------------
//  Generate the current sequence of choice numbers.
//  Put them in the list named
//  "sequence_position_for_adjusted_choice".
//  Base the sequence on the counters in the
//  counter list named "sequence_count_at_position".
//  While creating this, use the
//  "choice_in_remainder_position" list
//  to keep track of which choice numbers have
//  not yet been used in the sequence.

        for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
        {
            removal_position = sequence_count_at_position[ sequence_position ] ;
            adjusted_choice = choice_in_remainder_position[ removal_position ] ;
            sequence_info += adjusted_choice + " , " ;
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
            sequence_position_for_adjusted_choice[ adjusted_choice ] = sequence_position ;
            for ( position_to_shift = removal_position ; position_to_shift <= global_adjusted_choice_count - sequence_position ; position_to_shift ++ )
            {
                choice_in_remainder_position[ position_to_shift ] = choice_in_remainder_position[ position_to_shift + 1 ] ;
            }
        }


// -----------------------------------------------
//  Calculate the score for the current sequence.
//  It equals the sum of all the pairwise counts
//  (tally-table numbers) that apply to the
//  sequence.

        score = 0 ;
        for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
        {
            first_choice_number = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
            second_choice_number = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;
            if ( sequence_position_for_adjusted_choice[ first_choice_number ] < sequence_position_for_adjusted_choice[ second_choice_number ] )
            {
                score += global_tally_first_over_second_in_pair[ pair_counter ] ;
            } else
            {
                score += global_tally_second_over_first_in_pair[ pair_counter ] ;
            }
        }
        score_info = "score = " + convert_integer_to_text( score ) ;


// -----------------------------------------------
//  If the new score exceeds the previously
//  highest score, save this sequence as (so far)
//  having the highest score.
//  Also use the current sequence position as the
//  ranking position of each choice.

        if ( score >= highest_score )
        {
            if ( score > highest_score )
            {
                highest_score = score ;
                count_of_same_highest_score = 1 ;
                for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
                {
                    sequence_position = sequence_position_for_adjusted_choice[ adjusted_choice ] ;
                    count_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] = 1 ;
                    sum_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] = sequence_position ;
                    global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] = sequence_position ;
                    global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ adjusted_choice ] = sequence_position ;
                    count_of_sequences_with_highest_ranking_for_adjusted_choice[ adjusted_choice ] = 1 ;
                    count_of_sequences_with_lowest_ranking_for_adjusted_choice[ adjusted_choice ] = 1 ;
                    ranking_info += global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] + " ; " ;
                    ranking_changes_info += "      ranking of " + convert_integer_to_text( adjusted_choice ) + " set to " + convert_integer_to_text( sequence_position ) + "\n" ;
                }


// -----------------------------------------------
//  If the new score equals the previously highest
//  score, adjust the ranking level of any choices
//  that are in less-preferred (for top-down) or
//  most-preferred (for bottom-up) ranking positions
//  compared to the previous sequence with the
//  same highest score.

            } else
            {
                count_of_same_highest_score ++ ;
                for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
                {
                    sequence_position = sequence_position_for_adjusted_choice[ adjusted_choice ] ;
                    ranking_info += global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] + " , " ;
                    sum_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] += sequence_position ;
                    count_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] ++ ;
                    if ( sequence_position > global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] )
                    {
                        global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] = sequence_position ;
                        ranking_changes_info += "      top-down ranking of " + convert_integer_to_text( adjusted_choice ) + " reduced to " + convert_integer_to_text( sequence_position ) + "\n" ;
                        count_of_sequences_with_lowest_ranking_for_adjusted_choice[ adjusted_choice ] ++ ;
                    }
                    if ( sequence_position < global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ adjusted_choice ] )
                    {
                        global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ adjusted_choice ] = sequence_position ;
                        ranking_changes_info += "      bottom-up ranking of " + convert_integer_to_text( adjusted_choice ) + " increased to " + convert_integer_to_text( sequence_position ) + "\n" ;
                        count_of_sequences_with_highest_ranking_for_adjusted_choice[ adjusted_choice ] ++ ;
                    }
                }
            }

// -----------------------------------------------
//  If the current score equals or exceeds the
//  previously highest score, log this information.

            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                sequence_position = sequence_position_for_adjusted_choice[ adjusted_choice ] ;
                global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
            }
            if ( ( true_or_false_log_details == global_true ) && ( global_adjusted_choice_count <= 8 ) )
            {
                log_out << "[all scores, sequence  " ;
                for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
                {
                    actual_choice = global_log_info_choice_at_position[ sequence_position ] ;
                    log_out << actual_choice << " , " ;
                }
                log_out << "  has high score of " << highest_score << "]" << std::endl ;
                if ( main_loop_count == 1 )
                {
                    global_sequence_score_using_all_scores_method = 0 ;
                }
                log_out << "[all scores, current top or score-matched ranking:]\n" ;
                internal_view_matrix( ) ;
                global_sequence_score_using_all_scores_method = global_sequence_score ;
            }


// -----------------------------------------------
//  Finish skipping over the sections that handle
//  a highest score.

        }


// -----------------------------------------------
//  For monitoring, display some key info -- for
//  every sequence checked.

        if ( ( true_or_false_log_all_sequences_details == global_true ) && ( global_adjusted_choice_count <= 8 ) )
        {
            log_out << sequence_info << "  " << score_info << std::endl ;
            log_out << ranking_info << std::endl ;
            log_out << ranking_changes_info << std::endl ;
        }


// -----------------------------------------------
//  Update the counters that are used to identify
//  the next sequence to be considered.
//  These counters are also used to identify when
//  all the sequences have been checked.

        position_in_sequence = global_adjusted_choice_count - 1 ;
        while ( position_in_sequence > 0 )
        {
            sequence_count_at_position[ position_in_sequence ] ++ ;
            if ( sequence_count_at_position[ position_in_sequence ] > maximum_sequence_count_at_position[ position_in_sequence ] )
            {
                sequence_count_at_position[ position_in_sequence ] = 1 ;
                position_in_sequence -- ;
                if ( position_in_sequence == 0 )
                {
                    true_or_false_continue_loop = global_false ;
                }
            } else
            {
                position_in_sequence = 0 ;
            }
        }


// -----------------------------------------------
//  Repeat the loop to check the next sequence.

    }


// -----------------------------------------------
//  For each choice, calculate the average
//  ranking for the sequences in which the score
//  was the highest score.  However, scale those
//  averages by the number of adjusted choices
//  minus one so that integer numbers can be
//  used.  Then normalize those values to produce
//  the final ranking.  Also, log the highest and
//  lowest ranking positions -- for the sequences
//  that have the same highest sequence score.

    if ( true_or_false_log_details == global_true ) { log_out << "[all scores, count of same highest score is " << count_of_same_highest_score << "]" << std::endl ; } ;
    if ( true_or_false_log_details == global_true ) { log_out << "[all scores, top-down and bottom-up and scaled-average values:]\n" ; } ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        top_down_rank = global_adjusted_ranking_for_adjusted_choice_top_down_version[ adjusted_choice ] ;
        bottom_up_rank = global_adjusted_ranking_for_adjusted_choice_bottom_up_version[ adjusted_choice ] ;
        average = int( ( ( global_adjusted_choice_count - 1 ) * sum_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] ) / count_of_rankings_at_highest_score_for_adjusted_choice[ adjusted_choice ] ) ;
        if ( true_or_false_log_details == global_true ) { log_out << "[  choice " << actual_choice << " , top-down ranking is " << top_down_rank << " (for " << count_of_sequences_with_highest_ranking_for_adjusted_choice[ adjusted_choice ] << " scores) , bottom-up ranking is " << bottom_up_rank << " (for " << count_of_sequences_with_lowest_ranking_for_adjusted_choice[ adjusted_choice ] << " scores) , scaled average " << average << "]" << std::endl ; } ;
        global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] = average ;
    }
    normalize_ranking( ) ;
    if ( true_or_false_log_details == global_true ) { log_out << "[all scores, final normalized results:]\n" ; } ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        ranking_level = global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] ;
        global_popularity_ranking_for_actual_choice[ actual_choice ] = ranking_level ;
        if ( true_or_false_log_details == global_true ) { log_out << "[  choice " << actual_choice << " is at top-down popularity level " << ranking_level  << "]" << std::endl ; } ;
    }


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.
//  Use the sequence that was determined when
//  normalization was done.

    true_or_false_log_details = global_true ;
    if ( true_or_false_log_details == global_true )
    {
        if ( global_logging_info == global_true ) { log_out << "[all scores, final popularity ranking:]\n" ; } ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  End of function calc_all_sequence_scores.

    if ( global_logging_info == global_true ) { log_out << "\n[all scores, exiting calc_all_sequence_scores function]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//     calc_votefair_choice_specific_pairwise_score_popularity_rank
//
//  Calculates VoteFair choice-specific pairwise-score
//  (CSPS) popularity ranking results.
//
//  This kind of ranking is useful for estimating
//  the overall ranking when there are many choices
//  (such as hundreds of choices) and fast results
//  are desired.   It is also used to estimate the
//  ranking before doing the VoteFair
//  insertion-sort popularity ranking calculations.
//  (If access to a computer is not available, this
//  CSPS method can be done using pen and paper and
//  a calculator.)
//
//  Example:
//
//  (A concise description follows this
//  example.  The description is easier to
//  understand after you have read this example.)
//
//  Consider an election (or survey) in which
//  there are five choices: A, B, C, D, E, and the
//  final ranking order is this alphabetical
//  order.
//
//  In this example the notation A>B
//  refers to how many voters pairwise prefer
//  choice A over choice B, and the notation
//  B>A refers to how many voters pairwise
//  prefer choice B over choice A.  This
//  notation always uses the "greater-than" symbol
//  ">", and never uses the "less-than" symbol
//  "<".
//
//  At the beginning of this ranking example,
//  suppose that the choices are arranged in the
//  order C, E, A, D, B.  The pairwise counts
//  for this arrangement are shown in this pairwise
//  matrix.
//
//        |       |       |       |       |       |
//        |   C   |   E   |   A   |   D   |   B   |
//        |       |       |       |       |       |
//   -----+-------+-------+-------+-------+-------+
//        | \     |       |       |       |       |
//    C   |   \   |  C>E  |  C>A  |  C>D  |  C>B  |
//        |     \ |       |       |       |       |
//   -----+-------+-------+-------+-------+-------+
//        |       | \     |       |       |       |
//    E   |  E>C  |   \   |  E>A  |  E>D  |  E>B  |
//        |       |     \ |       |       |       |
//   -----+-------+-------+-------+-------+-------+
//        |       |       | \     |       |       |
//    A   |  A>C  |  A>E  |   \   |  A>D  |  A>B  |
//        |       |       |     \ |       |       |
//   -----+-------+-------+-------+-------+-------+
//        |       |       |       | \     |       |
//    D   |  D>C  |  D>E  |  D>A  |   \   |  D>B  |
//        |       |       |       |     \ |       |
//   -----+-------+-------+-------+-------+-------+
//        |       |       |       |       | \     |
//    B   |  B>C  |  B>E  |  B>A  |  B>D  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  The diagonal line passes through empty
//  cells.  These cells are empty because they
//  would represent a choice's comparison with
//  itself, such as A>A.
//
//  The goal of these calculations is to change
//  the sequence so that the largest pairwise
//  counts move into the upper-right triangular
//  area, leaving the smallest pairwise counts in
//  the lower-left triangular area.  (This is
//  similar to the goal of VoteFair popularity
//  ranking.)
//
//  The first step is to calculate
//  choice-specific scores, with each choice having
//  a row score and a column
//  score.  For choice A, its row score
//  equals the sum of the pairwise counts in the
//  row labelled A, which equals A>B +
//  A>C + A>D + A>E.  The column
//  score for choice A is the sum of the
//  pairwise counts in the column labeled A,
//  which equals B>A + C>A + D>A +
//  E>A.  The row scores and column scores
//  for choices B, C, D, and E are calculated
//  similarly.
//
//  Next, all the row scores are compared to
//  determine which choice has the largest row
//  score.  In this example that score
//  would be the row score for choice A (because it
//  is first in alphabetical order).
//  Therefore choice A is moved into first
//  place.  The other choices remain in the
//  same order.  The resulting sequence is A,
//  C, E, D, B.  Here is the pairwise matrix
//  for the new sequence.  The pairwise counts
//  for the ranked choice (A) are surrounded by
//  asterisks:
//
//        |       |       |       |       |       |
//        |   A   |   C   |   E   |   D   |   B   |
//        |       |       |       |       |       |
//   -----*****************************************
//        * \     |       |       |       |       *
//    A   *   \   |  A>C  |  A>E  |  A>D  |  A>B  *
//        *     \ |       |       |       |       *
//   -----*-------*********************************
//        *       * \     |       |       |       |
//    C   *  C>A  *   \   |  C>E  |  C>D  |  C>B  |
//        *       *     \ |       |       |       |
//   -----*-------*-------+-------+-------+-------+
//        *       *       | \     |       |       |
//    E   *  E>A  *  E>C  |   \   |  E>D  |  E>B  |
//        *       *       |     \ |       |       |
//   -----*-------*-------+-------+-------+-------+
//        *       *       |       | \     |       |
//    D   *  D>A  *  D>C  |  D>E  |   \   |  D>B  |
//        *       *       |       |     \ |       |
//   -----*-------*-------+-------+-------+-------+
//        *       *       |       |       | \     |
//    B   *  B>A  *  B>C  |  B>E  |  B>D  |   \   |
//        *       *       |       |       |     \ |
//   -----*********-------+-------+-------+-------+
//
//  The row scores and column scores for the
//  remaining (unranked) choices are adjusted to
//  remove the pairwise counts that involve the
//  just-ranked choice (A).  The removed
//  pairwise counts are the ones surrounded by
//  asterisks.  Specifically, after
//  subtracting B>A, the row score for choice B
//  becomes B>C + B>D + B>E, and after
//  subtracting A>B, the column score for choice
//  B becomes C>B + D>B + E>B.
//
//  From among the remaining row scores the
//  highest score is found.  At this point
//  let's assume that both choice B and choice C
//  have the same highest row score.
//
//  In the case of a row-score tie, the
//  choice with the smallest column score --
//  from among the choices that have the same
//  largest row score -- is ranked
//  next.  This would be choice B.
//  Therefore, choice B is moved to the sequence
//  position just after choice A.  The
//  resulting sequence is A, B, C, E, D.
//  Below is the pairwise matrix for the new
//  sequence.  The pairwise counts for the
//  ranked choices are surrounded by asterisks.
//
//        |       |       |       |       |       |
//        |   A   |   B   |   C   |   E   |   D   |
//        |       |       |       |       |       |
//   -----*****************************************
//        * \     |       |       |       |       *
//    A   *   \   |  A>B  |  A>C  |  A>E  |  A>D  *
//        *     \ |       |       |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       | \     |       |       |       *
//    B   *  B>A  |   \   |  B>C  |  B>E  |  B>D  *
//        *       |     \ |       |       |       *
//   -----*-------+--------************************
//        *       |       * \     |       |       |
//    C   *  C>A  |  C>B  *   \   |  C>E  |  C>D  |
//        *       |       *     \ |       |       |
//   -----*-------+-------*-------+-------+-------+
//        *       |       *       | \     |       |
//    E   *  E>A  |  E>B  *  E>C  |   \   |  E>D  |
//        *       |       *       |     \ |       |
//   -----*-------+-------*-------+-------+-------+
//        *       |       *       |       | \     |
//    D   *  D>A  |  D>B  *  D>C  |  D>E  |   \   |
//        *       |       *       |       |     \ |
//   -----*****************-------+-------+-------+
//
//  The same ranking process is repeated.
//  The next choice to be ranked would be choice
//  C.   It would have the highest row score
//  -- and the smallest column score if there is a
//  row-score tie.   So choice C would be
//  identifed as the next choice in the ranked
//  sequence.   After that, choice D would
//  have the highest row score, and would be ranked
//  next.  Finally the only remaining choice,
//  choice E, would be ranked at the last (lowest)
//  position.
//
//  Here is the final pairwise matrix.
//
//        |       |       |       |       |       |
//        |   A   |   B   |   C   |   D   |   E   |
//        |       |       |       |       |       |
//   -----*****************************************
//        * \     |       |       |       |       *
//    A   *   \   |  A>B  |  A>C  |  A>D  |  A>E  *
//        *     \ |       |       |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       | \     |       |       |       *
//    B   *  B>A  |   \   |  B>C  |  B>D  |  B>E  *
//        *       |     \ |       |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       | \     |       |       *
//    C   *  C>A  |  C>B  |   \   |  C>D  |  C>E  *
//        *       |       |     \ |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       |       | \     |       *
//    D   *  D>A  |  D>B  |  D>C  |   \   |  D>E  *
//        *       |       |       |     \ |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       |       |       | \     *
//    E   *  E>A  |  E>B  |  E>C  |  E>D  |   \   *
//        *       |       |       |       |     \ *
//   -----*****************************************
//
//  The choices are now fully ranked according
//  to the Choice-Specific Pairwise-Count
//  method.
//
//  If only a single winner is needed, the
//  first-ranked choice should not necessarily be
//  selected as the winner.  Instead, the
//  pairwise counts should be checked for a
//  possible Condorcet winner, which may be second
//  or third in the CSPS ranking result.
//
//  Concise description of the calculation method:
//
//  A row score and a column score
//  is calculated for each choice.  The
//  row score is the sum of the pairwise counts in
//  which the specified choice is preferred over
//  each of the other choices.  The column
//  score is the sum of the pairwise counts in
//  which each other choice is preferred over the
//  specified choice.
//
//  For the choices that have not yet been
//  ranked, all the row scores are compared to find
//  the highest row score.  The choice
//  that has the highest row score is moved to the
//  most-popular or next-most popular position in
//  the ranking results.
//
//  If more than one choice is
//  tied with the highest row score, the
//  choice with the smallest column score is
//  chosen.  If more than one choice has the
//  same row score and the same column score, the
//  choices are regarded as tied.
//
//  After each choice has been ranked, the
//  scores for the remaining (unranked) choices are
//  adjusted by subtracting from all the
//  remaining scores the pairwise counts that
//  involve the just-ranked choice.
//
//  The process of ranking each choice and
//  adjusting the remaining scores is
//  repeated until only one choice remains,
//  and it is ranked in the bottom (least-popular)
//  position.
//
//  (This description of the VoteFair choice-specific
//  pairwise-score method was copied from
//  www.VoteFair.org with permission.)
//
// -----------------------------------------------
// -----------------------------------------------

void calc_votefair_choice_specific_pairwise_score_popularity_rank( )
{

    int adjusted_choice ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int adjusted_choice_being_displaced ;
    int adjusted_choice_with_largest_score ;
    int adjusted_choice_not_yet_sorted ;
    int actual_choice ;
    int actual_first_choice ;
    int actual_second_choice ;
    int actual_choice_with_largest_score ;
    int actual_choice_not_yet_sorted ;
    int actual_choice_being_displaced ;
    int sequence_position ;
    int new_position_of_choice_being_moved ;
    int previous_position_of_choice_being_moved ;
    int sequence_position_of_choice_not_yet_sorted ;
    int ranking_level ;
    int main_loop_count ;
    int pair_counter ;
    int tally_first_over_second ;
    int tally_second_over_first ;
    int row_score ;
    int column_score ;
    int largest_row_score ;
    int smallest_column_score ;
    int largest_column_score ;
    int row_score_reduction ;
    int column_score_reduction ;
    int count_of_choices_sorted ;
    int true_or_false_log_details ;
    int count_of_tied_scores ;
    int difference_between_tallies ;
    int largest_positive_difference ;
    int list_pointer ;
    int tie_count_limit ;
    int first_pointer ;
    int second_pointer ;

    int row_score_for_adjusted_choice[ 201 ] ;
    int column_score_for_adjusted_choice[ 201 ] ;
    int position_in_sequence_for_adjusted_choice[ 201 ] ;
    int adjusted_choice_in_rank_sequence_position[ 201 ] ;
    int adjusted_choice_at_tie_count[ 201 ] ;


// -----------------------------------------------
//  Hide or show the details in the log file.

    true_or_false_log_details = global_true ;
    if ( global_logging_info == global_true )
    {
        log_out << "\n[choice-score, beginning calc_votefair_choice_specific_pairwise_score_popularity_rank function]\n" ;
        if ( true_or_false_log_details == global_true )
        {
            log_out << "[choice-score, details shown (change flag value to hide details)]\n" ;
        } else
        {
            log_out << "[choice-score, details hidden (change flag value to view details)]\n" ;
        }
    } else
    {
        true_or_false_log_details = global_false ;
    }


// -----------------------------------------------
//  Initialize the scale value for the logged
//  pairwise counts.

    global_scale_for_logged_pairwise_counts = 1.0 ;


// -----------------------------------------------
//  Initialize the results in case of an early
//  exit.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  If there are not at least two choices,
//  indicate an error.

    if ( global_adjusted_choice_count < 2 )
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, ERROR: number of (adjusted) choices is less than two]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Initialize the choice sequence.  Just use
//  numerical order.  Also initialize other
//  values.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        sequence_position = adjusted_choice ;
        adjusted_choice_in_rank_sequence_position[ sequence_position ] = adjusted_choice ;
        position_in_sequence_for_adjusted_choice[ adjusted_choice ] = sequence_position ;
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] = 0 ;
    }
    adjusted_choice_with_largest_score = 0 ;
    global_top_choice_according_to_choice_specific_scores = 0 ;
    global_sequence_score_using_choice_score_method = 0 ;


// -----------------------------------------------
//  Initialize the value that keeps track of how many
//  choices are in the group of highest-ranked
//  choices.

    count_of_choices_sorted = 0 ;


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.

    if ( true_or_false_log_details == global_true )
    {
        for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
        {
            adjusted_choice = adjusted_choice_in_rank_sequence_position[ sequence_position ] ;
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
        }
        if ( global_logging_info == global_true ) { log_out << "[choice-score, initial ranking:]\n" ; } ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  Sum the tally counts in each column and each
//  row.
//  (The position of each choice in the
//  array/matrix does not affect these sums.)
//  The "pair counter" is an index that accesses
//  each combination of (adjusted) choice
//  numbers, where the first choice number is
//  less than the second choice number.
//  As a visual representation this means that
//  the pairwise tallies (counts) for the
//  upper-right diagonal and the lower-left
//  diagonal (triangular areas of the pairwise
//  matrix) are stored in the
//  global_tally_first_over_second_in_pair
//  and
//  global_tally_second_over_first_in_pair
//  lists (not necessarily respectively).

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        row_score_for_adjusted_choice[ adjusted_choice ] = 0 ;
        column_score_for_adjusted_choice[ adjusted_choice ] = 0 ;
    }
    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        adjusted_first_choice = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
        adjusted_second_choice = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;
        row_score_for_adjusted_choice[ adjusted_first_choice ] += global_tally_first_over_second_in_pair[ pair_counter ] ;
        row_score_for_adjusted_choice[ adjusted_second_choice ] += global_tally_second_over_first_in_pair[ pair_counter ] ;
        column_score_for_adjusted_choice[ adjusted_first_choice ] += global_tally_second_over_first_in_pair[ pair_counter ] ;
        column_score_for_adjusted_choice[ adjusted_second_choice ] += global_tally_first_over_second_in_pair[ pair_counter ] ;
        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, for first choice " << actual_first_choice << " and second choice " << actual_second_choice << " , tally first over second is " << global_tally_first_over_second_in_pair[ pair_counter ] << " , and tally second over first is " << global_tally_second_over_first_in_pair[ pair_counter ] << "]" << std::endl ; } ;
    }


// -----------------------------------------------
//  Display (in the log file) the current column
//  and row scores.  Also save the largest
//  column score.

    largest_column_score = 0 ;
    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, current column and row scores:]\n" ; } ;
    for ( sequence_position = count_of_choices_sorted + 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
    {
        adjusted_choice = adjusted_choice_in_rank_sequence_position[ sequence_position ] ;
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        if ( true_or_false_log_details == global_true ) { log_out << "[  for choice " << actual_choice << " row score is " << row_score_for_adjusted_choice[ adjusted_choice ] << " and column score is " << column_score_for_adjusted_choice[ adjusted_choice ] << "]" << std::endl ; } ;
        if ( column_score_for_adjusted_choice[ adjusted_choice ] > largest_column_score )
        {
            largest_column_score = column_score_for_adjusted_choice[ adjusted_choice ] ;
        }
    }
    if ( true_or_false_log_details == global_true ) { log_out << std::endl ; } ;


// -----------------------------------------------
//  Begin a loop that identifies which choice
//  to move into the first/next-highest or
//  last/lowest sequence position.
//  The loop is exited in the middle (not here).

    main_loop_count = 0 ;
    while ( main_loop_count < global_adjusted_choice_count + 10 )
    {
        main_loop_count ++ ;


// -----------------------------------------------
//  Prevent an endless loop.

        if ( main_loop_count > 10000 )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, loop counter has exceeded limit, probably because the choice count (" << global_full_choice_count << ") is so large, so exiting choice-score rank]" ; } ;
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] = 0 ;
            }
            break ;
        }


// -----------------------------------------------
//  If there is only one choice remaining, rank
//  it at the middle, between the two sorted lists.

        if ( count_of_choices_sorted + 1 == global_adjusted_choice_count )
        {
            adjusted_choice = adjusted_choice_in_rank_sequence_position[ count_of_choices_sorted + 1 ] ;
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] = count_of_choices_sorted + 1 ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, middle case, no choices unsorted, so done sorting]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  If all the choices have been sorted, exit
//  the loop.

        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, most-popular sorted list length is " << count_of_choices_sorted << "]" << std::endl ; } ;
        if ( count_of_choices_sorted >= global_adjusted_choice_count )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, no choices unsorted, so done sorting]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  Identify which choice has the largest
//  choice-specific score-based row score.
//  If there is a tie between row scores,
//  choose the choice with the smallest
//  column score.  If there are multiple tied
//  choices, save those choice numbers in a list.

        largest_row_score = -1 ;
        smallest_column_score = largest_column_score ;
        adjusted_choice_with_largest_score = 0 ;
        count_of_tied_scores = 0 ;
        for ( sequence_position = count_of_choices_sorted + 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
        {
            adjusted_choice = adjusted_choice_in_rank_sequence_position[ sequence_position ] ;
            row_score = row_score_for_adjusted_choice[ adjusted_choice ] ;
            column_score = column_score_for_adjusted_choice[ adjusted_choice ] ;
            if ( ( row_score > largest_row_score ) || ( ( row_score == largest_row_score ) && ( column_score < smallest_column_score ) ) )
            {
                adjusted_choice_with_largest_score = adjusted_choice ;
                largest_row_score = row_score ;
                smallest_column_score = column_score ;
                count_of_tied_scores = 1 ;
                adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_choice_with_largest_score ;
                actual_choice_with_largest_score = global_actual_choice_for_adjusted_choice[ adjusted_choice_with_largest_score ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, starting new tied list, adding to tied list, choice " << actual_choice_with_largest_score << " (row score is " << largest_row_score << " and column score is " << smallest_column_score << ")]\n" ; } ;
            } else if ( row_score == largest_row_score )
            {
                adjusted_choice_with_largest_score = adjusted_choice ;
                count_of_tied_scores ++ ;
                adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_choice_with_largest_score ;
                actual_choice_with_largest_score = global_actual_choice_for_adjusted_choice[ adjusted_choice_with_largest_score ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, adding to tied list, choice " << actual_choice_with_largest_score << " (row score is " << largest_row_score << " and column score is " << smallest_column_score << ")]\n" ; } ;
            }
        }


// -----------------------------------------------
//  Specify the limit for the number of tied
//  choices for which it is worth the time to
//  see if the choices with the same highest scores
//  can be sorted.  This number should NOT
//  exceed about 5 at the most.  If it is one,
//  the lowest-numbered choice will be sorted
//  into the next position.

        tie_count_limit = 1 ;
        if ( tie_count_limit < 1 )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[ERROR: choice-score, tie_count_limit (" << count_of_tied_scores << ") is too small]\n" ; } ;
            global_possible_error_message += "Error: Value of tie_count_limit " + convert_integer_to_text( tie_count_limit ) + " is less than one, which is too small." ;
            return ;
        }


// -----------------------------------------------
//  If only one choice has the highest score,
//  save it, and skip over the next sections
//  that deal with ties.
//  If this choice is the highest-ranked choice,
//  make it available for possible tie-breaking
//  use in the insertion-sort calculations.

        if ( count_of_tied_scores == 1 )
        {
            adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_choice_with_largest_score ;
            actual_choice_with_largest_score = global_actual_choice_for_adjusted_choice[ adjusted_choice_with_largest_score ] ;
            if ( count_of_choices_sorted == 0 )
            {
                global_top_choice_according_to_choice_specific_scores = actual_choice_with_largest_score ;
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, no tie, only choice " << actual_choice_with_largest_score << "]" << std::endl ; } ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice_with_largest_score << " has largest row score " << largest_row_score << " (and a possible tie-breaking column score of " << smallest_column_score << ")]\n" ; } ;


// -----------------------------------------------
//  If there are too many tied choices, pick the
//  first one as the next choice to sort.
//  Keep in mind that this algorithm estimates
//  the ranking, and depends on the
//  insertion-sort algorithm to refine the exact
//  ranking.  Also, the method of resolving a
//  tie (below) is not always correct.

        } else if ( count_of_tied_scores > tie_count_limit )
        {
            count_of_tied_scores = 1 ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, there is a tie among " << count_of_tied_scores << " choices, which is too many, so only choice " << adjusted_choice_at_tie_count[ count_of_tied_scores ] << " is picked]\n" ; } ;


// -----------------------------------------------
//  If more than one choice has the same highest
//  row score, without a tie-breaking column score,
//  begin to identify which
//  choice has the best (highest) pairwise
//  comparison with each of the other tied
//  choices.

        } else
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, tie involving " << count_of_tied_scores << " choices]\n" ; } ;


// -----------------------------------------------
//  For each pair of tied choices, calculate the
//  difference between the relevant pairwise
//  counts (tally numbers), and identify the
//  largest such difference, and choose to sort
//  the choice that is associated with the
//  largest positive difference.

            largest_positive_difference = 0 ;
            for ( first_pointer = 1 ; first_pointer < count_of_tied_scores ; first_pointer ++ )
            {
                adjusted_first_choice = adjusted_choice_at_tie_count[ first_pointer ] ;
                actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, first choice is " << actual_first_choice << "]" << std::endl ; } ;
                for ( second_pointer = first_pointer + 1 ; second_pointer <= count_of_tied_scores ; second_pointer ++ )
                {
                    adjusted_second_choice = adjusted_choice_at_tie_count[ second_pointer ] ;
                    actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, second choice is " << actual_second_choice << "]" << std::endl ; } ;
                    pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ adjusted_first_choice ] + adjusted_second_choice ;
                    tally_first_over_second = global_tally_first_over_second_in_pair[ pair_counter ] ;
                    tally_second_over_first = global_tally_second_over_first_in_pair[ pair_counter ] ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, first tied choice " << actual_first_choice << " and second tied choice " << actual_second_choice << " have tallies " << tally_first_over_second << " and " << tally_second_over_first << "]" << std::endl ; } ;
                    difference_between_tallies = tally_first_over_second - tally_second_over_first ;
                    if ( difference_between_tallies > 0 )
                    {
                        if ( difference_between_tallies > largest_positive_difference )
                        {
                            largest_positive_difference = difference_between_tallies ;
                            count_of_tied_scores = 1 ;
                            adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_first_choice ;
                            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice << " is first choice chosen so far]\n" ; } ;
                        } else if ( difference_between_tallies == largest_positive_difference )
                        {
                            count_of_tied_scores ++ ;
                            adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_first_choice ;
                            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice << " is added to list as chosen so far]\n" ; } ;
                        }
                    } else if ( difference_between_tallies < 0 )
                    {
                        if ( ( - difference_between_tallies ) > largest_positive_difference )
                        {
                            largest_positive_difference = - difference_between_tallies ;
                            count_of_tied_scores = 1 ;
                            adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_second_choice ;
                            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice << " is first choice chosen so far]\n" ; } ;
                        } else if ( ( - difference_between_tallies ) == largest_positive_difference )
                        {
                            count_of_tied_scores ++ ;
                            largest_positive_difference = - difference_between_tallies ;
                            adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_second_choice ;
                            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice << " is added to list as chosen so far]\n" ; } ;
                        }
                    } else
                    {
                        largest_positive_difference = 0 ;
                        count_of_tied_scores ++ ;
                        adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_first_choice ;
                        count_of_tied_scores ++ ;
                        adjusted_choice_at_tie_count[ count_of_tied_scores ] = adjusted_second_choice ;
                        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
                        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
                        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, tie at zero, so both choices " << actual_first_choice << " and " << actual_second_choice << " are chosen so far]\n" ; } ;
                    }
                    main_loop_count ++ ;
                    if ( main_loop_count > 10000 )
                    {
                        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, loop counter has exceeded limit while handling tied scores, which means the value of tie_count_limit (which is " << tie_count_limit << ") is too large ]" ; } ;
                        break ;
                    }
                }
            }


// -----------------------------------------------
//  Terminate the branches that handle situations
//  in which more than one choice has the same highest
//  row score (and the lowest column score if there
//  is a tie in the row scores).

            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, will repeat loop if another tied choice]\n" ; } ;
        }


// -----------------------------------------------
//  Specify the ranking level.

        ranking_level = count_of_choices_sorted + 1 ;
        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, ranking level is " << ranking_level << "]" << std::endl ; } ;


// -----------------------------------------------
//  Begin a loop that repeats only if there are
//  multiple choices that are tied at the same
//  ranking level, in which case the loop
//  repeats for each such choice.  Otherwise this
//  loop is executed only once.

        for ( list_pointer = 1 ; list_pointer <= count_of_tied_scores ; list_pointer ++ )
        {
            adjusted_choice_with_largest_score = adjusted_choice_at_tie_count[ list_pointer ] ;
            actual_choice_with_largest_score = global_actual_choice_for_adjusted_choice[ adjusted_choice_with_largest_score ] ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, next-ranked choice is " << actual_choice_with_largest_score << "]" << std::endl ; } ;


// -----------------------------------------------
//  Rank the specified choice at the current ranking
//  level.

            global_choice_score_popularity_rank_for_actual_choice[ actual_choice_with_largest_score ] = ranking_level ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice_with_largest_score << " ranked at level " << ranking_level << "]" << std::endl ; } ;


// -----------------------------------------------
//  Move the specified choice to the bottom of
//  the highest-ranked choices.
//  To make room in the sequence, move
//  whichever choice is already there.
//  If the choice is already in the correct
//  row and column, skip ahead.

            count_of_choices_sorted ++ ;
            new_position_of_choice_being_moved = count_of_choices_sorted ;
            previous_position_of_choice_being_moved = position_in_sequence_for_adjusted_choice[ adjusted_choice_with_largest_score ] ;
            if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, moving choice " << actual_choice_with_largest_score << " from position " << previous_position_of_choice_being_moved << " to position " << new_position_of_choice_being_moved << "]" << std::endl ; } ;
            if ( new_position_of_choice_being_moved != previous_position_of_choice_being_moved )
            {
                adjusted_choice_being_displaced = adjusted_choice_in_rank_sequence_position[ new_position_of_choice_being_moved ] ;
                actual_choice_being_displaced = global_actual_choice_for_adjusted_choice[ adjusted_choice_being_displaced ] ;

                adjusted_choice_in_rank_sequence_position[ new_position_of_choice_being_moved ] = adjusted_choice_with_largest_score ;

                position_in_sequence_for_adjusted_choice[ adjusted_choice_with_largest_score ] = new_position_of_choice_being_moved ;

                adjusted_choice_in_rank_sequence_position[ previous_position_of_choice_being_moved ] = adjusted_choice_being_displaced ;

                position_in_sequence_for_adjusted_choice[ adjusted_choice_being_displaced ] = previous_position_of_choice_being_moved ;

            } else
            {
                if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, no move needed]\n" << std::endl ; } ;

            }

            if ( true_or_false_log_details == global_true ) { log_out << std::endl ; } ;


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.

            if ( true_or_false_log_details == global_true )
            {
                for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
                {
                    adjusted_choice = adjusted_choice_in_rank_sequence_position[ sequence_position ] ;
                    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
                }
                log_out << "[choice-score, intermediate ranking:]\n" ;
                internal_view_matrix( ) ;
            }
            global_sequence_score_using_choice_score_method = global_sequence_score ;


// -----------------------------------------------
//  Skip ahead if the last choice has been sorted.

            if ( count_of_choices_sorted < global_adjusted_choice_count )
            {


// -----------------------------------------------
//  Reduce each row score and each column score by
//  the pairwise counts that are associated with
//  the choice that was just sorted.  This
//  updates the row and column scores to apply to
//  only the unsorted choices.
//  In case the number of choices is large (such
//  as hundreds of choices), access the tally
//  counts efficiently (and without creating an
//  extra array that converts from choice-number
//  combinations into pair numbers).

                for ( sequence_position_of_choice_not_yet_sorted = count_of_choices_sorted + 1 ; sequence_position_of_choice_not_yet_sorted <= global_adjusted_choice_count ; sequence_position_of_choice_not_yet_sorted ++ )
                {
                    adjusted_choice_not_yet_sorted = adjusted_choice_in_rank_sequence_position[ sequence_position_of_choice_not_yet_sorted ] ;
                    if ( adjusted_choice_with_largest_score < adjusted_choice_not_yet_sorted )
                    {
                        pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ adjusted_choice_with_largest_score ] + adjusted_choice_not_yet_sorted ;
                        column_score_reduction = global_tally_first_over_second_in_pair[ pair_counter ] ;
                        row_score_reduction = global_tally_second_over_first_in_pair[ pair_counter ] ;
                    } else
                    {
                        pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ adjusted_choice_not_yet_sorted ] + adjusted_choice_with_largest_score ;
                        row_score_reduction = global_tally_first_over_second_in_pair[ pair_counter ] ;
                        column_score_reduction = global_tally_second_over_first_in_pair[ pair_counter ] ;
                    }
                    actual_choice_not_yet_sorted = global_actual_choice_for_adjusted_choice[ adjusted_choice_not_yet_sorted ] ;
                    row_score_for_adjusted_choice[ adjusted_choice_not_yet_sorted ] -= row_score_reduction ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, for choice " << actual_choice_not_yet_sorted << " row score reduced by " << row_score_reduction << "]" << std::endl ; } ;
                    column_score_for_adjusted_choice[ adjusted_choice_not_yet_sorted ] -= column_score_reduction ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, for choice " << actual_choice_not_yet_sorted << " column score reduced by " << column_score_reduction << "]" << std::endl ; } ;
                }


// -----------------------------------------------
//  Display the updated row and column scores.

                if ( true_or_false_log_details == global_true )
                {
                    log_out << "[choice-score, current row and column scores:]\n" ;
                    for ( sequence_position = count_of_choices_sorted + 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
                    {
                        adjusted_choice = adjusted_choice_in_rank_sequence_position[ sequence_position ] ;
                        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                        log_out << "[  for choice " << actual_choice << " row score is " << row_score_for_adjusted_choice[ adjusted_choice ] << " and column score is " << column_score_for_adjusted_choice[ adjusted_choice ] << "]" << std::endl ;
                    }
                    log_out << std::endl ;
                }


// -----------------------------------------------
//  Finish skipping ahead if the last choice has
//  been sorted.

            }


// -----------------------------------------------
//  Repeat the loop that is repeated only if there
//  is a tie.

        }


// -----------------------------------------------
//  Repeat the loop that identifies which choice to
//  sort next.

    }


// -----------------------------------------------
//  Normalize the results.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] = global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] ;
    }
    normalize_ranking( ) ;
    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, final normalized ranking levels]\n" ; } ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        ranking_level = global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] ;
        global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] = ranking_level ;
        if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, choice " << actual_choice << " at normalized rank level " << ranking_level << "]" << std::endl ; } ;
    }


// -----------------------------------------------
//  Log the calculated ranking levels.

    if ( true_or_false_log_details == global_true ) { log_out << "[choice-score, final results:]\n" ; } ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        if ( true_or_false_log_details == global_true ) { log_out << "[  choice " << actual_choice << " is at ranking level " << global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] << "]" << std::endl ; } ;
    }


// -----------------------------------------------
//  End of function calc_votefair_choice_specific_pairwise_score_popularity_rank.

    if ( global_logging_info == global_true ) { log_out << "\n[choice-score, exiting calc_votefair_choice_specific_pairwise_score_popularity_rank function]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//       calc_votefair_insertion_sort_popularity_rank
//
//  Calculates VoteFair popularity ranking results
//  using the "insertion-sort" sorting algorithm.
//
//  VoteFair popularity ranking is described in
//  Wikipedia, and is mathematically equivalent
//  to the Condorcet-Kemeny method.  The
//  following comments explain the algorithm used
//  here, which quickly calculates the ranking
//  results.  This explanation is important
//  because some academic sources claim that
//  the computations cannot be done quickly if
//  there is a large number of choices being
//  ranked.
//
//  Although the goal of VoteFair popularity
//  ranking is to find the sequence that has the
//  highest sequence score, the scores themselves
//  do not need to be calculated.  This
//  concept is similar to not needing to know the
//  elevation of every point in a region in order
//  to know that a specific mountain peak  is the
//  highest elevation in that region.  By not
//  calculating all the sequence scores, the
//  calculation time can be greatly reduced
//  compared to the method that calculates all the
//  sequence scores.
//
//  The algorithm described here assumes that
//  the choices already have been pre-sorted using
//  the Choice-Specific Pairwise-Score (CSPS)
//  algorithm.  That algorithm is part of this
//  full calculation algorithm.
//
//  The full algorithm repeatedly uses a
//  variation of the "insertion-sort" sorting
//  algorithm, so that algorithm is described
//  first.
//
//  Insertion-sort algorithm applied to finding
//  maximum sequence score:
//
//  This explanation clarifies how the
//  well-known insertion-sort algorithm is applied
//  to VoteFair popularity ranking in a way that
//  greatly reduces the number of calculations
//  needed to find maximum sequence scores.
//  (This  method is just part of the full
//  algorithm, which is explained in the next
//  section.)
//
//  Consider an example in which there are five
//  choices named A, B, C, D, and E, with a final
//  sort order that matches this alphabetical
//  order.
//
//  Notation: The notation A>B refers to how
//  many voters pairwise prefer choice A over
//  choice B, and the notation B>A refers to how
//  many voters pairwise prefer choice B over
//  choice A.  This notation always uses the
//  "greater-than" symbol ">", and never uses
//  the "less-than" symbol "<".
//
//  At an intermediate stage in this sorting
//  example, suppose that the choices A, C, and E
//  have been sorted -- into this correct
//  order -- and choice B is about to be
//  sorted, and choice D remains unsorted.
//  The pairwise counts for this arrangement are
//  shown below.  The asterisks show the
//  separation between sorted choices and unsorted
//  choices.
//
//        |       |       |       |       |       |
//        |   A   |   C   |   E   |   B   |   D   |
//        |       |       |       |       |       |
//   -----*************************-------+-------+
//        * \     |       |       *       |       |
//    A   *   \   |  A>C  |  A>E  *  A>B  |  A>D  |
//        *     \ |       |       *       |       |
//   -----+-------+-------+-------+-------+-------+
//        *       | \     |       *       |       |
//    C   *  C>A  |   \   |  C>E  *  C>B  |  C>D  |
//        *       |     \ |       *       |       |
//   -----+-------+-------+-------+-------+-------+
//        *       |       | \     *       |       |
//    E   *  E>A  |  E>C  |   \   *  E>B  |  E>D  |
//        *       |       |     \ *       |       |
//   -----*************************-------+-------+
//        |       |       |       | \     |       |
//    B   |  B>A  |  B>C  |  B>E  |   \   |  B>D  |
//        |       |       |       |     \ |       |
//   -----+-------+-------+-------+-------+-------+
//        |       |       |       |       | \     |
//    D   |  D>A  |  D>C  |  D>E  |  D>B  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  The diagonal line passes through empty cells
//  -- that would otherwise represent a
//  choice's comparison with itself, such as
//  A>A.
//
//  The diagonal line also is the border between
//  the upper-right triangular area and the
//  lower-left triangular area.  The sequence
//  score for the current sequence is the sum of
//  all the pairwise counts in the upper-right
//  triangular area (currently A>C + A>E +
//  A>B + A>D + C>E + C>B + C>D +
//  E>B + E>D + B>D).
//
//  The goal of these calculations is to find
//  the maximum sequence score, which means the
//  goal is to change the sequence so that the
//  largest pairwise counts move into the
//  upper-right triangular area, leaving the
//  smallest pairwise counts in the lower-left
//  triangular area.
//
//  The first step in sorting choice B is to
//  consider the possibility of moving it to the
//  left of choice E, which would form the sequence
//  A, C, B, E.  Here is the pairwise-count
//  matrix for this sequence.  The asterisks
//  now include choice B because this is a possible
//  sort order.
//
//        |       |       |       |       |       |
//        |   A   |   C   |   B   |   E   |   D   |
//        |       |       |       |       |       |
//   -----*********************************-------+
//        * \     |       |       |       *       |
//    A   *   \   |  A>C  |  A>B  |  A>E  *  A>D  |
//        *     \ |       |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       | \     |       |       *       |
//    C   *  C>A  |   \   |  C>B  |  C>E  *  C>D  |
//        *       |     \ |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       | \     |       *       |
//    B   *  B>A  |  B>C  |   \   |  B>E  *  B>D  |
//        *       |       |     \ |  ---  *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       |       | \     *       |
//    E   *  E>A  |  E>C  |  E>B  |   \   *  E>D  |
//        *       |       |  ---  |     \ *       |
//   -----*********************************-------+
//        |       |       |       |       | \     |
//    D   |  D>A  |  D>C  |  D>B  |  D>E  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  The only pairwise counts that crossed the
//  diagonal line are the (underlined) counts
//  B>E and E>B, which swapped places.
//  All the other pairwise counts that move do not
//  cross the diagonal line; they stay on the same
//  side of the diagonal line.
//
//  As a result, the score for this sequence,
//  compared to the score for the previous
//  sequence, increases (or decreases if negative)
//  by the amount B>E minus E>B.  In
//  this case (assuming there are no complications
//  that are explained later) the sequence score
//  has increased because in the final
//  (alphabetical) sort order, choice B appears
//  before choice E.
//
//  The next step in sorting choice B is to
//  consider the possibility of moving it to the
//  left of choice C, which would form the sequence
//  A, B, C, E.  Here is the pairwise-count
//  matrix for this sequence.
//
//        |       |       |       |       |       |
//        |   A   |   B   |   C   |   E   |   D   |
//        |       |       |       |       |       |
//   -----*********************************-------+
//        * \     |       |       |       *       |
//    A   *   \   |  A>B  |  A>C  |  A>E  *  A>D  |
//        *     \ |       |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       | \     |       |       *       |
//    B   *  B>A  |   \   |  B>C  |  B>E  *  B>D  |
//        *       |     \ |  ---  |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       | \     |       *       |
//    C   *  C>A  |  C>B  |   \   |  C>E  *  C>D  |
//        *       |  ---  |     \ |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       |       | \     *       |
//    E   *  E>A  |  E>B  |  E>C  |   \   *  E>D  |
//        *       |       |       |     \ *       |
//   -----*********************************-------+
//        |       |       |       |       | \     |
//    D   |  D>A  |  D>B  |  D>C  |  D>E  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  The only pairwise counts that crossed the
//  diagonal line are the (underlined) counts
//  B>C and C>B, which swapped places.
//  The other pairwise counts that moved remained
//  on the same side of the diagonal line.
//
//  The score for this sequence increases (or
//  decreases if negative) by the amount B>C
//  minus C>B.  In this case the sequence
//  score has increased because (in the final
//  alphabetical order) choice B appears before
//  choice C.
//
//  The final step in sorting choice B is to
//  consider the possibility of moving it to the
//  left of choice A, which would form the sequence
//  B, A, C, E.  Here is the matrix for this
//  sequence.
//
//        |       |       |       |       |       |
//        |   B   |   A   |   C   |   E   |   D   |
//        |       |       |       |       |       |
//   -----*********************************-------+
//        * \     |       |       |       *       |
//    B   *   \   |  B>A  |  B>C  |  B>E  *  B>D  |
//        *     \ |  ---  |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       | \     |       |       *       |
//    A   *  A>B  |   \   |  A>C  |  A>E  *  A>D  |
//        *  ---  |     \ |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       | \     |       *       |
//    C   *  C>B  |  C>A  |   \   |  C>E  *  C>D  |
//        *       |       |     \ |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       |       | \     *       |
//    E   *  E>B  |  E>A  |  E>C  |   \   *  E>D  |
//        *       |       |       |     \ *       |
//   -----*********************************-------+
//        |       |       |       |       | \     |
//    D   |  D>B  |  D>A  |  D>C  |  D>E  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  The only pairwise counts that crossed the
//  diagonal line are the (underlined) counts
//  B>A and A>B, which swapped places.
//  The other pairwise counts that moved remained
//  on the same side of the diagonal line.
//
//  The score for this sequence increases (or
//  decreases if negative) by the amount B>A
//  minus A>B.  In this case the sequence
//  score has decreased because (in the final
//  alphabetical order) choice B appears after, not
//  before, choice A.
//
//  At this point choice B has been tested at
//  each position within the sorted portion.
//  The  maximum sequence score (for the sorted
//  portion) occurred when it was between choices A
//  and C.  As a result, choice B will be
//  moved to the position between choices A and
//  C.
//
//  Notice that the full sequence score did not
//  need to be calculated in order to find this
//  "local" maximum.  These calculations only
//  need to keep track of increases and decreases
//  that occur as the being-sorted choice swaps
//  places with successive already-sorted
//  choices.
//
//  The pairwise-count matrix with choice B in
//  the second sort-order position (between A and
//  C) is shown below.  Now choice D is the
//  only unsorted choice.
//
//        |       |       |       |       |       |
//        |   A   |   B   |   C   |   E   |   D   |
//        |       |       |       |       |       |
//   -----*********************************-------+
//        * \     |       |       |       *       |
//    A   *   \   |  A>B  |  A>C  |  A>E  *  A>D  |
//        *     \ |       |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       | \     |       |       *       |
//    B   *  B>A  |   \   |  B>C  |  B>E  *  B>D  |
//        *       |     \ |       |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       | \     |       *       |
//    C   *  C>A  |  C>B  |   \   |  C>E  *  C>D  |
//        *       |       |     \ |       *       |
//   -----*-------+-------+-------+-------*-------+
//        *       |       |       | \     *       |
//    E   *  E>A  |  E>B  |  E>C  |   \   *  E>D  |
//        *       |       |       |     \ *       |
//   -----*********************************-------+
//        |       |       |       |       | \     |
//    D   |  D>A  |  D>B  |  D>C  |  D>E  |   \   |
//        |       |       |       |       |     \ |
//   -----+-------+-------+-------+-------+-------+
//
//  Choice D would be sorted in the same
//  way.  Of course the maximum sequence score
//  would occur when choice D is between choices C
//  and E, so D is moved there.
//
//        |       |       |       |       |       |
//        |   A   |   B   |   C   |   D   |   E   |
//        |       |       |       |       |       |
//   -----*****************************************
//        * \     |       |       |       |       *
//    A   *   \   |  A>B  |  A>C  |  A>D  |  A>E  *
//        *     \ |       |       |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       | \     |       |       |       *
//    B   *  B>A  |   \   |  B>C  |  B>D  |  B>E  *
//        *       |     \ |       |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       | \     |       |       *
//    C   *  C>A  |  C>B  |   \   |  C>D  |  C>E  *
//        *       |       |     \ |       |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       |       | \     |       *
//    D   *  D>A  |  D>B  |  D>C  |   \   |  D>E  *
//        *       |       |       |     \ |       *
//   -----*-------+-------+-------+-------+-------*
//        *       |       |       |       | \     *
//    E   *  E>A  |  E>B  |  E>C  |  E>D  |   \   *
//        *       |       |       |       |     \ *
//   -----*****************************************
//
//  Now there are no more choices to sort, so
//  the resulting sequence is A, B, C, D, E.
//  In this sequence the full sequence score
//  -- which equals A>B + A>C + A>D +
//  A>E + B>C + B>D + B>E + C>D +
//  C>E + D>E -- is likely to be the
//  highest possible sequence score.
//
//  Additional calculations, as described below,
//  are needed because in rare cases it is possible
//  that moving two or more choices at the same
//  time could produce a higher sequence
//  score.  This concept is analogous to
//  climbing a mountain in foggy conditions by
//  always heading in the locally higher direction
//  and ending up at the top of a peak and then,
//  when the fog clears, seeing a higher peak.
//
//  Full calculation method for VoteFair popularity ranking:
//
//  This is a description of the full algorithm
//  used to calculate VoteFair popularity ranking
//  results.
//
//  The algorithm begins by calculating the
//  Choice-Specific Pairwise-Score ranking.
//  This pre-sort is a required part of the
//  process.  Without it, some unusual cases
//  can cause the calculations to fail to find the
//  sequence with the highest score.  This
//  pre-sort is analogous to starting a search for
//  the highest mountain peak within a mountain
//  range instead of starting the search within a
//  large valley.
//
//  The next step is to apply the insertion-sort
//  method as described in the section above,
//  including starting at the left/highest end.
//
//  To ensure that all possible moves of each
//  choice are considered, the insertion-sort
//  method is done in both directions.
//  Sorting in both directions means that in some
//  sorting passes sorting moves choices to the
//  left, as explained in the above example.
//  In other sorting passes sorting starts by
//  considering the right-most choice as the first
//  sorted choice, and choices move to the right,
//  into the sorted portion.  This convention
//  ensures movement for choices that need to move
//  right, instead of left, in order to cause an
//  increase in the score.
//
//  Complications can arise when there is
//  "circular ambiguity", so additional steps are
//  used.  The most common cases of circular
//  ambiguity involve several choices that are tied
//  for the same sort-order position.
//
//  A key part of dealing with circular
//  ambiguity is to follow this convention:
//  whenever a choice can produce the same,
//  highest, sequence score at more than one
//  position, the choice is moved to the farthest
//  of those highest-sequence-score positions.
//
//  Another part of dealing with these
//  complications is to sort the sequence multiple
//  times.
//
//  During the second sorting pass, if there is
//  no circular ambiguity, the sequence of the
//  choices in the pairwise matrix remains the
//  same.  This lack of movement (when there
//  is no circular ambiguity) occurs because the
//  sorted and unsorted portions are
//  adjacent.  Specifically, each choice to be
//  sorted is already at the top (for left-movement
//  sorting) or bottom (for right-movement sorting)
//  of the "unsorted" portion, and it is being
//  moved to the bottom (for left-movement sorting)
//  or top (for right-movement sorting) of
//  the "sorted" portion.  In such cases
//  the only thing that moves is the boundary
//  between the sorted choices and unsorted
//  choices.
//
//  However, in cases that involve circular
//  ambiguity, the positions of some choices will
//  change during the second and later sorting
//  passes.  This happens because the
//  convention (as explained above) is to move each
//  choice as far as it will go, within the limits
//  of maximizing the sequence score.
//
//  During the sorting passes the highest
//  sort-order (sequence) position of each choice
//  is tracked, and the lowest sort-order position
//  of each choice is tracked.  These highest
//  and lowest positions are reset (to current
//  positions) whenever the sequence score
//  increases to a higher score.  At the end
//  of the sorting process the highest and lowest
//  positions reveal which choices are tied at the
//  same popularity ranking level.
//
//  Using the insertion-sort example, if choices
//  B, C, and D can be in any order and still
//  produce the same highest sequence score, then
//  each of these choices would move to the left of
//  the other two each time it is sorted, and each
//  of these choices would have the same
//  highest-ranked position of second place, and
//  each would have the same lowest-ranked position
//  of fourth place. Because these three choices
//  have the same highest and lowest positions,
//  they are easily identified as tied (at the same
//  popularity ranking).
//
//  More complex cases of circular ambiguity can
//  occur.  To deal with these cases, and to
//  ensure the correctness of the "winner" (the
//  most popular choice), the sorting process is
//  repeated for the top half (plus one) of the
//  highest-ranked choices, and this sub-set
//  sorting is repeated until there are just three
//  choices.  For example, if there are 12
//  choices, the sorting process is done for 12
//  choices, then the top 7 choices, then the top 4
//  choices, and finally the top 3 choices.
//  Then the highest-ranked choice (or the choices
//  that are tied at the top) is kept at the
//  highest rank while the other choices are sorted
//  a final time.  (If, instead, the
//  least-popular choice is the most important one
//  to identify correctly, the data supplied to
//  this algorithm can be inverted according to
//  preference levels, and then the calculated
//  ranking can be reversed.)
//
//  As a clarification, the extra sub-set
//  sorting is done only if more than one sequence
//  has the same highest sequence score.  This
//  point is significant if the distinction between
//  VoteFair popularity ranking and the
//  Condorcet-Kemeny method is relevant.
//  Specifically, the Condorcet-Kemeny method does
//  not indicate how such "tied" sequence scores
//  should be resolved, whereas VoteFair popularity
//  ranking resolves such "tied" sequence scores as
//  part of its calculation process.
//
//  After all the sorting has been done, the
//  highest and lowest ranking levels are used to
//  determine the results.  For each choice
//  its highest and lowest ranking levels
//  are added together (which equals twice their
//  average) and then multiplied times a
//  constant.  The constant equals 10 times
//  the number of choices minus one.  These
//  numbers are converted to integers, and then
//  these "averaged scaled integerized" values are
//  used as the non-normalized ranking
//  levels.  Two or more choices are ranked at
//  the same level if they have the same
//  "averaged-scaled-integerized" ranking
//  values.
//
//  The final calculation step is to normalize
//  the "averaged-scaled-integerized" ranking
//  levels so that the normalized ranking levels
//  are consecutive, namely 1, 2, 3, etc. (so that
//  no ranking levels are skipped).
//
//  The result is a ranking that identifies
//  which choice is first-most popular, which
//  choice is second-most popular, and so on down
//  to which choice is least popular.  Ties
//  can occur at any level.
//
//  Calculation time:
//
//  The full algorithm used to calculate
//  VoteFair popularity ranking results  has a
//  calculation time that is less than or equal to
//  the following polynomial function:
//
//    T = A + ( B * N ) + ( C * ( N * N ) )
//
//  where T is the calculation time, N is the
//  number of choices, and A and B and C are
//  constants.  (In mathematical notation, N *
//  N would be written as N squared.)  This
//  function includes the calculation time required
//  for the Choice-Specific Pairwise-Score (CSPS)
//  pre-sort calculations.
//
//  This time contrasts with the slow execution
//  times  of the "NP-hard" approach, in which
//  every sequence score is calculated in order to
//  find the sequence with the highest score.
//  If every sequence score were calculated (from
//  scratch), the calculation time would be
//  proportional to:
//
//    N! * N * N
//
//  where N is the number of choices, N! is N
//  factorial (2 * 3 * 4 * ... * N), and N * N
//  equals N squared.  Note that N factorial
//  equals the number of possible sequences, and N
//  squared times one-half approximately equals the
//  number of pairwise counts that are added to
//  calculate each sequence score.
//
//  This clarification about calculation time is
//  included because there is an academically
//  common -- yet mistaken -- belief that
//  calculating the "Condorcet-Kemeny method" is
//  "NP-hard" and cannot be calculated in a time
//  that is proportional to a polynomial function
//  of N (the number of choices).
//
//  (c) Copyright 2011 Richard Fobes at VoteFair.org
//
//  (This description copied from VoteFair.org
//  with permission.)
//
// -----------------------------------------------
// -----------------------------------------------

void calc_votefair_insertion_sort_popularity_rank( )
{

    int adjusted_choice ;
    int adjusted_choice_to_move ;
    int new_adjusted_choice ;
    int new_adjusted_choice_count ;
    int starting_adjusted_choice_number ;
    int local_adjusted_choice_count ;
    int tally_adjusted_choice_for_choice_to_move ;
    int tally_adjusted_choice_for_choice_at_destination ;
    int actual_choice ;
    int actual_choice_to_move ;
    int actual_choice_at_destination ;
    int count_of_choices_in_top_half ;
    int number_of_choices_to_shift ;
    int sequence_position ;
    int destination_sequence_position ;
    int source_sequence_position ;
    int to_position ;
    int from_position ;
    int position_of_choice_to_move ;
    int position_number ;
    int actual_destination ;
    int possible_destination ;
    int maximum_move_distance_allowed ;
    int direction_increment ;
    int distance_to_possible_destination ;
    int number_of_positions_sorted ;
    int ranking_level ;
    int special_ranking_level ;
    int highest_rank ;
    int lowest_rank ;
    int choice_counter ;
    int pair_counter ;
    int score_increase ;
    int tally_choice_to_move_over_choice_at_destination ;
    int tally_choice_at_destination_over_choice_to_move ;
    int largest_subset_sum ;
    int final_stage_reached_at_main_loop_count ;
    int pass_number ;
    int sort_pass_counter ;
    int sort_pass_count_at_last_move ;
    int sort_pass_counter_maximum ;
    int recent_sort_pass_count_in_direction_left ;
    int recent_sort_pass_count_in_direction_right ;
    int pass_count_at_last_score_increase ;
    int reached_stable_condition_at_pass_count ;
    int count_of_sequences_with_same_highest_score ;
    int main_loop_count ;
    int main_loop_maximum_count ;
    int scale_value ;
    int true_or_false_log_details ;
    int highest_rank_threshold ;
    int count_of_highest_ranked_choices ;
    int count_of_lower_ranked_choices ;
    int adjusted_choice_overall ;
    int possible_ranking_level ;
    int actual_first_choice ;
    int actual_second_choice ;
    int tally_adjusted_first_choice ;
    int tally_adjusted_second_choice ;
    int tally_first_over_second ;
    int tally_second_over_first ;

    int local_actual_choice_for_adjusted_choice[ 201 ] ;
    int actual_choice_at_new_adjusted_choice[ 201 ] ;
    int actual_choice_in_insertion_rank_sequence_position[ 201 ] ;
    int highest_insertion_sort_sequence_position_for_actual_choice[ 201 ] ;
    int lowest_insertion_sort_sequence_position_for_actual_choice[ 201 ] ;
    int pass_number_at_last_rerank_for_adjusted_choice[ 201 ] ;
    int adjusted_choice_count_at_stage[ 201 ] ;
    int highest_ranked_actual_choice_at_count[ 201 ] ;
    int lower_ranked_actual_choice_at_count[ 201 ] ;
    int local_adjusted_choice_for_actual_choice[ 201 ] ;


// -----------------------------------------------
//  Hide or show the details in the log file.
//  This choice can slow down the software
//  because it creates a large log file.

    true_or_false_log_details = global_true ;
    if ( global_logging_info == global_false )
    {
        true_or_false_log_details = global_false ;
    }
    if ( global_logging_info == global_true )
    {
        log_out << "\n[insertion sort, beginning calc_votefair_insertion_sort_popularity_rank function]\n" ;
        if ( true_or_false_log_details == global_true )
        {
            log_out << "[insertion sort, details shown (change flag value to hide details)]\n" ;
        } else
        {
            log_out << "[insertion sort, details hidden (change flag value to view details)]\n" ;
        }
    }


// -----------------------------------------------
//  Set the results to zero in case an error is
//  encountered.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] = 0 ;
        pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice ] = 0 ;
    }


// -----------------------------------------------
//  If there are not at least two choices,
//  indicate an error.

    if ( global_adjusted_choice_count < 2 )
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, ERROR: number of (adjusted) choices is less than two]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  If the total vote count is zero, indicate an
//  error.

    if ( global_current_total_vote_count < 1 )
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, ERROR: number of votes is zero]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Initialize the choice sequence.  Use the
//  sequence calculated by the choice-specific
//  score-based ranking calculations.
//
//  In case there are no results from those calculations,
//  initialize the sequence to be in numeric
//  order (choice 1, choice 2, etc.).
//  However, in complex cases, numeric order
//  may produce the wrong results!

    for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
    {
        adjusted_choice = sequence_position ;
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        actual_choice_in_insertion_rank_sequence_position[ sequence_position ] = actual_choice ;
    }
    adjusted_choice = 1 ;
    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
    if ( global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] > 0 )
    {
        sequence_position = 1 ;
        for ( ranking_level = 1 ; ranking_level <= global_adjusted_choice_count ; ranking_level ++ )
        {
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                if ( global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] == ranking_level )
                {
                    actual_choice_in_insertion_rank_sequence_position[ sequence_position ] = actual_choice ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, put choice " << actual_choice << " into sequence position " << sequence_position << "]" << std::endl ; } ;
                    sequence_position ++ ;
                    if ( sequence_position > global_adjusted_choice_count )
                    {
                        break ;
                    }
                }
            }
        }
    } else
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[ERROR: the results of the choice-specific score-based calculations are not available, so the results might not be correct!]\n" ; } ;
    }


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.

    if ( true_or_false_log_details == global_true )
    {
        for ( sequence_position = 1 ; sequence_position <= global_adjusted_choice_count ; sequence_position ++ )
        {
            actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
            global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
        }
        log_out << "[insertion sort, initial ranking:]\n" ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  Use a local value for the adjusted choice
//  count.  This allows the count to change.

    local_adjusted_choice_count = global_adjusted_choice_count ;


// -----------------------------------------------
//  Create lists that associate adjusted choice
//  numbers with actual choice numbers, in both
//  directions.  These local values are used
//  instead of the global values because these
//  adjusted choice numbers will change.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        local_actual_choice_for_adjusted_choice[ adjusted_choice ] = actual_choice ;
        local_adjusted_choice_for_actual_choice[ actual_choice ] = adjusted_choice ;
    }


// -----------------------------------------------
//  Begin a loop that repeats in order to handle
//  the different stages in the calculations,
//  where the different stages sort either all
//  the choices or a subset of the choices.
//  This loop does not exit here; it exits when
//  the stages are all done.
//  Note that this loop is only repeated if
//  more than one sequence has the same highest
//  sequence score.

    global_sequence_score_using_insertion_sort_method = 0 ;
    count_of_sequences_with_same_highest_score = 0 ;
    final_stage_reached_at_main_loop_count = 0 ;
    main_loop_maximum_count = 10 ;
    for ( main_loop_count = 1 ; main_loop_count <= main_loop_maximum_count ; main_loop_count ++ )
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, main-loop number is " << main_loop_count << "]" << std::endl ; } ;


// -----------------------------------------------
//  If this is the "starting" stage, sort all the
//  choices (starting with the sort order
//  calculated by the choice-specific score-based
//  method).

        if ( main_loop_count == 1 )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in main loop, first/start stage, so sorting all choices]\n" ; } ;
        }


// -----------------------------------------------
//  If the final stage is complete, exit the loop.

        if ( ( final_stage_reached_at_main_loop_count > 0 ) && ( main_loop_count >= final_stage_reached_at_main_loop_count ) )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in main loop, final stage done, so exiting main loop]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  If at least one pass of sorting has been done
//  and the total number of choices is 2, the
//  sorting is done, so exit the main loop.

        if ( ( main_loop_count > 1 ) && ( global_adjusted_choice_count <= 2 ) )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, choice count is just one or two, sorting is done, so exiting main loop]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  If this is not the starting stage, and is not
//  the final stage (checked above), and at least
//  one pass of sub-sorting has been done, and
//  the number of sub-sorted choices is now 3 or
//  less, request starting the final stage.

        if ( ( main_loop_count > 1 ) && ( local_adjusted_choice_count <= 3 ) && ( local_adjusted_choice_count < global_adjusted_choice_count ) )
        {
            final_stage_reached_at_main_loop_count = main_loop_count ;
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, count of choices just sub-sorted (" << local_adjusted_choice_count << ") is three or less, so starting final stage]\n" ; } ;
        }


// -----------------------------------------------
//  If this is not the starting stage, and is not the
//  final stage, attempt to reduce the number
//  of choices being sorted.  Identify the choices
//  in the top half, plus the next-ranked choice.
//  If appropriate, these choices will be sub-sorted.

        if ( ( main_loop_count > 1 ) && ( local_adjusted_choice_count > 3 ) )
        {
            new_adjusted_choice_count = int( ( local_adjusted_choice_count / 2 ) + 1 ) ;
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, finding " << new_adjusted_choice_count << " choices at highest rankings]\n" ; } ;
            for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                actual_choice_at_new_adjusted_choice[ adjusted_choice ] = 0 ;
            }
            count_of_choices_in_top_half = 0 ;
            for ( highest_rank_threshold = 1 ; highest_rank_threshold <= local_adjusted_choice_count ; highest_rank_threshold ++ )
            {
                for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    highest_rank = highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] ;
                    if ( highest_rank == highest_rank_threshold )
                    {
                        count_of_choices_in_top_half ++ ;
                        new_adjusted_choice = count_of_choices_in_top_half ;
                        actual_choice_at_new_adjusted_choice[ new_adjusted_choice ] = actual_choice ;
                        if ( true_or_false_log_details == global_true ) { log_out << "[  choice " << actual_choice << " (at ranking level " << highest_rank << ") will be sub-sorted as adjusted choice " << new_adjusted_choice << "]" << std::endl ; } ;
                    }
                }
                if ( count_of_choices_in_top_half >= new_adjusted_choice_count )
                {
                    break ;
                }
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, found " << count_of_choices_in_top_half << " choices at highest rankings]\n" ; } ;


// -----------------------------------------------
//  If the just-calculated number of choices to be
//  sub-sorted is less than three, or has not
//  changed (been reduced), request starting the final
//  stage (which will sort all the choices except
//  the highest-ranked choice).

            if ( count_of_choices_in_top_half < 3 )
            {
                final_stage_reached_at_main_loop_count = main_loop_count ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, count of choices to sub-sort (" << local_adjusted_choice_count << ") is less than three, so starting final stage]\n" ; } ;
            } else if ( count_of_choices_in_top_half == local_adjusted_choice_count )
            {
                final_stage_reached_at_main_loop_count = main_loop_count ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, count of choices to sub-sort (" << local_adjusted_choice_count << ") did not change (which would cause an endless loop), so starting final stage]\n" ; } ;


// -----------------------------------------------
//  If the number of choices to be sub-sorted is
//  less than the previous number of choices
//  sorted, but is not less than three, prepare to sort them
//  by shifting the specified number of top-ranked
//  choices into the lowest-numbered sequence
//  positions.

            } else
            {
                local_adjusted_choice_count = count_of_choices_in_top_half ;
                adjusted_choice_count_at_stage[ main_loop_count ] = local_adjusted_choice_count ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, now adjusted choice count is " << local_adjusted_choice_count << "]" << std::endl ; } ;
                for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = actual_choice_at_new_adjusted_choice[ adjusted_choice ] ;
                    local_adjusted_choice_for_actual_choice[ actual_choice ] = adjusted_choice ;
                    local_actual_choice_for_adjusted_choice[ adjusted_choice ] = actual_choice ;
                    sequence_position = adjusted_choice ;
                    actual_choice_in_insertion_rank_sequence_position[ sequence_position ] = actual_choice ;
                }
            }
        }


// -----------------------------------------------
//  If this is the final stage, identify the
//  highest-ranked choices -- based on having
//  been at the highest sequence position (during
//  the most recent sorting pass) -- and save
//  them separately.  Also create a list of the
//  other choices.

        if ( final_stage_reached_at_main_loop_count == main_loop_count )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, starting final stage]\n" ; } ;
            count_of_highest_ranked_choices = 0 ;
            count_of_lower_ranked_choices = 0 ;
            for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                if ( highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] == 1 )
                {
                    count_of_highest_ranked_choices ++ ;
                    highest_ranked_actual_choice_at_count[ count_of_highest_ranked_choices ] = actual_choice ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, choice " << actual_choice << " is at highest rank]\n" ; } ;
                } else
                {
                    count_of_lower_ranked_choices ++ ;
                    lower_ranked_actual_choice_at_count[ count_of_lower_ranked_choices ] = actual_choice ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = global_adjusted_choice_count ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = global_adjusted_choice_count ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, choice " << actual_choice << " is at lower rank]\n" ; } ;
                }
            }


// -----------------------------------------------
//  If all the choices are tied at the highest
//  level, indicate this situation and exit the
//  main loop.

            if ( count_of_highest_ranked_choices == global_adjusted_choice_count )
            {
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, all the choices are tied at the highest level]\n" ; } ;
                for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = 1 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = 1 ;
                    sequence_position = actual_choice ;
                    actual_choice_in_insertion_rank_sequence_position[ sequence_position ] = actual_choice ;
                    local_actual_choice_for_adjusted_choice[ adjusted_choice ] = actual_choice ;
                    local_adjusted_choice_for_actual_choice[ actual_choice ] = adjusted_choice ;
                }
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, exiting main loop]\n" ; } ;
                break ;
            }


// -----------------------------------------------
//  If this is the final stage, put all the choices
//  that are not at the highest rank into a sequence
//  for final sorting.  Use the sequence calculated
//  by VoteFair choice-specific score-based ranking.

            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, preparing to sub-sort the choices that are not highest ranked]\n" ; } ;
            local_adjusted_choice_count = global_adjusted_choice_count - count_of_highest_ranked_choices ;
            new_adjusted_choice = 1 ;
            for ( adjusted_choice_overall = 1 ; adjusted_choice_overall <= global_adjusted_choice_count ; adjusted_choice_overall ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice_overall ] ;
                if ( highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] > 1 )
                {
                    local_adjusted_choice_for_actual_choice[ actual_choice ] = new_adjusted_choice ;
                    local_actual_choice_for_adjusted_choice[ new_adjusted_choice ] = actual_choice ;
                    new_adjusted_choice ++ ;
                }
            }
            sequence_position = 1 ;
            for ( possible_ranking_level = 1 ; possible_ranking_level <= global_adjusted_choice_count ; possible_ranking_level ++ )
            {
                for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    if ( possible_ranking_level == global_choice_score_popularity_rank_for_actual_choice[ actual_choice ] )
                    {
                        actual_choice_in_insertion_rank_sequence_position[ sequence_position ] = actual_choice ;
                        if ( true_or_false_log_details == global_true ) { log_out << "[  choice " << actual_choice << " is at sequence position " << sequence_position << " and is now adjusted choice " << adjusted_choice << "]" << std::endl ; } ;
                        sequence_position ++ ;
                    }
                }
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, will sort all other choices]\n" ; } ;
        }


// -----------------------------------------------
//  Initialize the values that keep track of
//  each choice's highest and lowest positions.

        for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
        {
            actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
            adjusted_choice = local_adjusted_choice_for_actual_choice[ actual_choice ] ;
            highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = sequence_position ;
            lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = sequence_position ;
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, next in sequence is choice " << actual_choice << "]" << std::endl ; } ;
        }


// -----------------------------------------------
//  Log the starting sequence.

        if ( true_or_false_log_details == global_true )
        {
            log_out << "\n[insertion sort, in sort-pass loop, starting sequence is: " ;
            for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
            {
                actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
                log_out << actual_choice << " , " ;
            }
            log_out << "]" << std::endl ;
        }


// -----------------------------------------------
//  Initialize values that are used in the
//  upcoming loop that repeatedly sorts the
//  choices.

        direction_increment = 1 ;
        starting_adjusted_choice_number = 1 ;
        sort_pass_count_at_last_move = 0 ;
        sort_pass_counter_maximum = 10 ;
        pass_count_at_last_score_increase = 0 ;
        recent_sort_pass_count_in_direction_left = 0 ;
        recent_sort_pass_count_in_direction_right = 0 ;
        reached_stable_condition_at_pass_count = 0 ;


// -----------------------------------------------
//  Begin a loop that repeatedly sorts the
//  choices.  Normally the loop does not reach
//  the maximum loop count used here.

        for ( sort_pass_counter = 1 ; sort_pass_counter <= sort_pass_counter_maximum ; sort_pass_counter ++ )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, sort pass counter = " << sort_pass_counter << ", last left sort count is " << recent_sort_pass_count_in_direction_left << ", last right sort count = " << recent_sort_pass_count_in_direction_right << "]" << std::endl ; } ;


// -----------------------------------------------
//  If there is just one choice, indicate its
//  sort order, and exit the sort-pass loop.

            if ( local_adjusted_choice_count == 1 )
            {
                actual_choice = actual_choice_in_insertion_rank_sequence_position[ 1 ] ;
                highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = 1 ;
                lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = 1 ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, only one choice, so no need to sort it]\n" ; } ;
                break ;
            }


// -----------------------------------------------
//  If there are just two choices, just look at
//  the two relevant pairwise-count numbers,
//  sort the two choices accordingly, and then
//  exit the sort-pass loop.

            if ( local_adjusted_choice_count == 2 )
            {
                actual_first_choice = actual_choice_in_insertion_rank_sequence_position[ 1 ] ;
                actual_second_choice = actual_choice_in_insertion_rank_sequence_position[ 2 ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, only two choices, " << actual_second_choice << " and " << actual_first_choice << "]" << std::endl ; } ;
                tally_adjusted_first_choice = global_adjusted_choice_for_actual_choice[ actual_first_choice ] ;
                tally_adjusted_second_choice = global_adjusted_choice_for_actual_choice[ actual_second_choice ] ;
                if ( tally_adjusted_first_choice < tally_adjusted_second_choice )
                {
                    pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ tally_adjusted_first_choice ] + tally_adjusted_second_choice ;
                    tally_first_over_second = global_tally_first_over_second_in_pair[ pair_counter ] ;
                    tally_second_over_first = global_tally_second_over_first_in_pair[ pair_counter ] ;
                } else
                {
                    pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ tally_adjusted_second_choice ] + tally_adjusted_first_choice ;
                    tally_first_over_second = global_tally_second_over_first_in_pair[ pair_counter ] ;
                    tally_second_over_first = global_tally_first_over_second_in_pair[ pair_counter ] ;
                }
                if ( tally_first_over_second == tally_second_over_first )
                {
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 1 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 1 ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 1 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 1 ;
                    actual_choice_in_insertion_rank_sequence_position[ 1 ] = actual_first_choice ;
                    actual_choice_in_insertion_rank_sequence_position[ 2 ] = actual_second_choice ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, choice " << actual_first_choice << " and choice " << actual_second_choice << " are tied as highest-ranked]\n" ; } ;
                } else if ( tally_first_over_second > tally_second_over_first )
                {
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 1 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 1 ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 2 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 2 ;
                    actual_choice_in_insertion_rank_sequence_position[ 1 ] = actual_first_choice ;
                    actual_choice_in_insertion_rank_sequence_position[ 2 ] = actual_second_choice ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, choice " << actual_first_choice << " is ranked higher than choice " << actual_second_choice << "]" << std::endl ; } ;
                } else
                {
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 2 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_first_choice ] = 2 ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 1 ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_second_choice ] = 1 ;
                    actual_choice_in_insertion_rank_sequence_position[ 1 ] = actual_second_choice ;
                    actual_choice_in_insertion_rank_sequence_position[ 2 ] = actual_first_choice ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, choice " << actual_second_choice << " is ranked higher than choice " << actual_first_choice << "]" << std::endl ; } ;
                }
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, only two choices, they are now sorted]\n" ; } ;
                break ;
            }


// -----------------------------------------------
//  Exit the sorting process when there have
//  been at least two sorting passes (one each
//  direction) during which the total score has
//  not increased, and then after two more
//  passes to ensure the choices have all moved
//  as far as possible in each direction.
//  The "extra" sorting passes
//  ensure that cycles ("ties") have had a
//  chance to move the involved ("tied")
//  choices to their highest and lowest
//  position values.
//  Also, when the sorted sequence is stable,
//  set a counter that is used to determine
//  if more than one sequence has the same
//  highest sequence score.

            if ( ( sort_pass_counter >= reached_stable_condition_at_pass_count + 2 ) && ( reached_stable_condition_at_pass_count > 0 ) )
            {
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, two extra sorting passes have been done (after stable condition reached), so exiting sorting process]\n" ; } ;
                break ;
            }
            if ( ( sort_pass_counter > pass_count_at_last_score_increase + 1 ) && ( recent_sort_pass_count_in_direction_left > pass_count_at_last_score_increase ) && ( recent_sort_pass_count_in_direction_right > pass_count_at_last_score_increase ) && ( recent_sort_pass_count_in_direction_left > 0 ) && ( recent_sort_pass_count_in_direction_right > 0 ) && ( reached_stable_condition_at_pass_count <= 0 ) )
            {
                reached_stable_condition_at_pass_count = sort_pass_counter ;
                count_of_sequences_with_same_highest_score = 1 ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, sorting has been done in both directions since the last score increase, so indicating stable condition, so will do two more sorting passes]\n" ; } ;
            }


// -----------------------------------------------
//  Change the sorting direction for different
//  sorting passes.  When the direction_increment
//  value is positive one, the sorting starts at
//  the highest-ranked (left) end and moves
//  choices left (to the higher-ranked positions).
//  When the direction_increment value is
//  negative one, sorting starts at the
//  lowest-ranked (right) end and moves choices
//  to the right (to the lower-ranked positions).
//  This symmetry ensures that tied choices pass
//  through the same highest and lowest rank
//  positions, and that each choice can move to
//  every possible position.

            if ( sort_pass_counter == 1 )
            {
                direction_increment = 1 ;
            } else if ( sort_pass_counter == reached_stable_condition_at_pass_count )
            {
                direction_increment = direction_increment * -1 ;
            } else if ( sort_pass_counter == reached_stable_condition_at_pass_count + 1 )
            {
                direction_increment = direction_increment * -1 ;
            } else if ( ( sort_pass_counter == sort_pass_count_at_last_move + 1 ) && ( sort_pass_counter == pass_count_at_last_score_increase + 2 ) )
            {
                direction_increment = direction_increment ;
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, keeping sort direction the same -- because last move was during pass count " << sort_pass_count_at_last_move << " and last score increase was during pass count " << pass_count_at_last_score_increase << "]" << std::endl ; } ;
            } else
            {
                direction_increment = direction_increment * -1 ;
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, changing to opposite sort direction]\n" ; } ;
            }
            if ( direction_increment == 1 )
            {
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, movement direction is left]\n" ; } ;
            } else
            {
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, movement direction is right]\n" ; } ;
            }


// -----------------------------------------------
//  For each sorting direction, save the sorting
//  pass number for the most recent sorting done
//  in that direction.

            if ( direction_increment == 1 )
            {
                recent_sort_pass_count_in_direction_left = sort_pass_counter ;
            } else
            {
                recent_sort_pass_count_in_direction_right = sort_pass_counter ;
            }


// -----------------------------------------------
//  Begin a loop that moves each unsorted choice
//  into the sorted segment.
//  Start by regarding the choice in the
//  highest-ranked (left-most) sequence position
//  as being the first item in the sorted list.
//  The "number_of_positions_sorted" value
//  counts how many of the first (left-most)
//  sequence positions have been sorted, so this
//  number separates the sequence into a sorted
//  list on the left and an unsorted list on
//  the right.

            for ( number_of_positions_sorted = 1 ; number_of_positions_sorted < local_adjusted_choice_count ; number_of_positions_sorted ++ )
            {
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, number of positions sorted is " <<  number_of_positions_sorted << "]" << std::endl ; } ;


// -----------------------------------------------
//  Identify which choice will be moved from the
//  unsorted portion of the list into the sorted
//  portion.

                if ( direction_increment == 1 )
                {
                    position_of_choice_to_move = number_of_positions_sorted + 1 ;
                } else
                {
                    position_of_choice_to_move = local_adjusted_choice_count - number_of_positions_sorted ;
                }
                actual_choice_to_move = actual_choice_in_insertion_rank_sequence_position[ position_of_choice_to_move ] ;
                adjusted_choice_to_move = local_adjusted_choice_for_actual_choice[ actual_choice_to_move ] ;
                if ( true_or_false_log_details == global_true ) { log_out << std::endl ; } ;
                if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, check if need to move choice " <<  actual_choice_to_move << "]" << std::endl ; } ;


// -----------------------------------------------
//  If this choice has already traveled to the
//  farthest position in this direction, skip
//  this choice.

                if ( direction_increment == 1 )
                {
                    if ( highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] == 1 )
                    {
                        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, choice " <<  adjusted_choice_to_move << " has already been to the highest ranking]\n" ; } ;
                        continue ; // was "next"
                    }
                } else
                {
                    if ( lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] == local_adjusted_choice_count )
                    {
                        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, choice " <<  adjusted_choice_to_move << " has already been to the lowest ranking]\n" ; } ;
                        continue ; // was "next"
                    }
                }


// -----------------------------------------------
//  Begin a loop that checks each sorted
//  position as a possible destination for the
//  unsorted choice being moved.

                maximum_move_distance_allowed = number_of_positions_sorted ;
                actual_destination = position_of_choice_to_move ;
                score_increase = 0 ;
                largest_subset_sum = -99999 ;
                for ( distance_to_possible_destination = 1 ; distance_to_possible_destination <= maximum_move_distance_allowed ; distance_to_possible_destination ++ )
                {
                    if ( direction_increment == 1 )
                    {
                        possible_destination = position_of_choice_to_move - distance_to_possible_destination ;
                    } else
                    {
                        possible_destination = position_of_choice_to_move + distance_to_possible_destination ;
                    }
                    actual_choice_at_destination = actual_choice_in_insertion_rank_sequence_position[ possible_destination ] ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, possible destination to far side of choice " <<  actual_choice_at_destination << "]" ; } ;


// -----------------------------------------------
//  Calculate the increase -- or decrease if
//  negative -- in the sequence score that
//  would occur if the unsorted choice was to be
//  moved to the specified destination (within
//  the sorted portion).  The subset sums already
//  include the tally counts that apply to any
//  already-checked positions between the moved
//  choice and the target choice.
//  This approach speeds up the calculation
//  time compared to fully calculating each
//  sequence score from scratch.

                    tally_adjusted_choice_for_choice_to_move = global_adjusted_choice_for_actual_choice[ actual_choice_to_move ] ;
                    tally_adjusted_choice_for_choice_at_destination = global_adjusted_choice_for_actual_choice[ actual_choice_at_destination ] ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[tally choice numbers: " << actual_choice_to_move << " (" << tally_adjusted_choice_for_choice_to_move << ") --> " << actual_choice_at_destination << " (" << tally_adjusted_choice_for_choice_at_destination << ")]" ; } ;
                    if ( tally_adjusted_choice_for_choice_to_move < tally_adjusted_choice_for_choice_at_destination )
                    {
                        pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ tally_adjusted_choice_for_choice_to_move ] + tally_adjusted_choice_for_choice_at_destination ;
                        if ( direction_increment == 1 )
                        {
                            tally_choice_to_move_over_choice_at_destination = global_tally_first_over_second_in_pair[ pair_counter ] ;
                            tally_choice_at_destination_over_choice_to_move = global_tally_second_over_first_in_pair[ pair_counter ] ;
                        } else
                        {
                            tally_choice_to_move_over_choice_at_destination = global_tally_second_over_first_in_pair[ pair_counter ] ;
                            tally_choice_at_destination_over_choice_to_move = global_tally_first_over_second_in_pair[ pair_counter ] ;
                        }
                    } else
                    {
                        pair_counter = global_pair_counter_offset_for_first_adjusted_choice[ tally_adjusted_choice_for_choice_at_destination ] + tally_adjusted_choice_for_choice_to_move ;
                        if ( direction_increment == 1 )
                        {
                            tally_choice_to_move_over_choice_at_destination = global_tally_second_over_first_in_pair[ pair_counter ] ;
                            tally_choice_at_destination_over_choice_to_move = global_tally_first_over_second_in_pair[ pair_counter ] ;
                        } else
                        {
                            tally_choice_to_move_over_choice_at_destination = global_tally_first_over_second_in_pair[ pair_counter ] ;
                            tally_choice_at_destination_over_choice_to_move = global_tally_second_over_first_in_pair[ pair_counter ] ;
                        }
                    }
                    if ( true_or_false_log_details == global_true ) { log_out << "[tallies: " << tally_choice_to_move_over_choice_at_destination << "  " << tally_choice_at_destination_over_choice_to_move << "]" ; } ;
                    score_increase += tally_choice_to_move_over_choice_at_destination - tally_choice_at_destination_over_choice_to_move ;


// -----------------------------------------------
//  Keep track of which destination position
//  would increase the sequence score by the
//  largest positive amount, and regard that as
//  the expected destination.
//  If the choice being moved is at the same
//  ranking level as another choice -- because
//  it has the same sequence score -- then move
//  the choice to the higher level (left-most
//  position) so that the choices skip over
//  each other, which is the characteristic
//  that is used to keep track of equal
//  rankings.

                    if ( score_increase > 0 )
                    {
                        pass_count_at_last_score_increase = sort_pass_counter ;
                        if ( true_or_false_log_details == global_true ) { log_out << "[new highest score reached]" ; } ;
                    }
                    if ( score_increase >= 0 )
                    {
                        if ( score_increase > largest_subset_sum )
                        {
                            largest_subset_sum = score_increase ;
                            actual_destination = possible_destination ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[new largest subset sum is " << largest_subset_sum << "]" << std::endl ; } ;
                        } else if ( score_increase == largest_subset_sum )
                        {
                            actual_destination = possible_destination ;
                            if ( true_or_false_log_details == global_true ) { log_out << "[equal tally sums, will move choice to farthest position]\n" ; } ;
                        } else
                        {
                            if ( true_or_false_log_details == global_true ) { log_out << "[current subset sum (" << score_increase << ") is not largest]\n" ; } ;
                        }
                    } else
                    {
                        if ( true_or_false_log_details == global_true ) { log_out << "[subset sum (" << score_increase << ") is negative]\n" ; } ;
                    }


// -----------------------------------------------
//  Repeat the loop that checks each position in
//  the sorted list as a possible destination for
//  the choice being moved.

                }


// -----------------------------------------------
//  If the choice should remain where it is, skip
//  over the next few sections of code (that
//  would move the choice).
//  After the choices have stabilized into a
//  sorted sequence, this lack of movement will
//  be typical because a "move" from the
//  unsorted segment to the sorted segment does
//  not involve a change in the sequence position,
//  just a change in the boundary between the
//  sorted and sorted segments (which are
//  adjacent).

                if ( position_of_choice_to_move == actual_destination )
                {
                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, no need to move choice " << actual_choice_to_move << "]" << std::endl ; } ;
                } else
                {


// -----------------------------------------------
//  Move the choice to the sequence position that
//  produces the biggest increase in the overall
//  sequence score.
//  For the choices being skipped over (by the
//  choice being moved), update their highest
//  or lowest sequence position value -- if the
//  move involves moving them outside of their
//  previous range.

                    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in sort-pass loop, need to move choice " << actual_choice_to_move << " from position " << position_of_choice_to_move << " to position " << actual_destination << "]" << std::endl ; } ;
                    count_of_sequences_with_same_highest_score ++ ;
                    sort_pass_count_at_last_move = sort_pass_counter ;
                    if ( direction_increment == 1 )
                    {
                        number_of_choices_to_shift = position_of_choice_to_move - actual_destination ;
                    } else
                    {
                        number_of_choices_to_shift = actual_destination - position_of_choice_to_move ;
                    }
                    for ( position_number = 1 ; position_number <= number_of_choices_to_shift ; position_number ++ )
                    {
                        if ( direction_increment == 1 )
                        {
                            from_position = position_of_choice_to_move - position_number ;
                            to_position = from_position + 1 ;
                        } else
                        {
                            from_position = position_of_choice_to_move + position_number ;
                            to_position = from_position - 1 ;
                        }
                        actual_choice = actual_choice_in_insertion_rank_sequence_position[ from_position ] ;
                        actual_choice_in_insertion_rank_sequence_position[ to_position ] = actual_choice ;
                        adjusted_choice = local_adjusted_choice_for_actual_choice[ actual_choice ] ;
                        if ( to_position > lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] )
                        {
                            lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = to_position ;
                            pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice ] = sort_pass_counter ;
                        }
                        if ( to_position < highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] )
                        {
                            highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = to_position ;
                            pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice ] = sort_pass_counter ;
                        }
                    }
                    actual_choice_in_insertion_rank_sequence_position[ actual_destination ] = actual_choice_to_move ;


// -----------------------------------------------
//  For the choice being moved, update its highest
//  or lowest sequence position value -- if this
//  move involves moving it outside of its
//  previous range.
//  The highest-and-lowest position information
//  is needed to determine which choices are
//  repeatedly skipping over each other, and that
//  indicates which choices are tied, and at what
//  ranking levels.

                    if ( actual_destination < highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] )
                    {
                        highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] = actual_destination ;
                        pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice_to_move ] = sort_pass_counter ;
                    }
                    if ( actual_destination > lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] )
                    {
                        lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] = actual_destination ;
                        pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice_to_move ] = sort_pass_counter ;
                    }


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.

                    if ( true_or_false_log_details == global_true )
                    {
                        if ( local_adjusted_choice_count == global_adjusted_choice_count )
                        {
                            for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
                            {
                                actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
                                global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
                            }
                            internal_view_matrix( ) ;
                            if ( global_sequence_score > global_sequence_score_using_insertion_sort_method )
                            {
                                global_sequence_score_using_insertion_sort_method = global_sequence_score ;
                                log_out << "\n[insertion sort, new sequence score is: " << global_sequence_score_using_insertion_sort_method << "]" << std::endl ;
                            }
                        } else
                        {
                            log_out << "\n[insertion sort, current sub-sort sequence is: " ;
                            for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
                            {
                                actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
                                log_out << actual_choice << " , " ;
                            }
                            log_out << "]" << std::endl ;
                        }
                    }


// -----------------------------------------------
//  Finish skipping the code that moves a choice
//  to a new sequence position.

                }


// -----------------------------------------------
//  Repeat the loop that moves each unsorted choice
//  into the sorted segment.

            }


// -----------------------------------------------
//  For monitoring, display the highest and lowest
//  rankings -- unless the values are about to be
//  reset.

            if ( true_or_false_log_details == global_true )
            {
                if ( sort_pass_counter != pass_count_at_last_score_increase )
                {
                    log_out << std::endl ;
                    for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
                    {
                        actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                        highest_rank = highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] ;
                        lowest_rank = lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] ;
                        log_out << "[insertion sort, in sort-pass loop, choice " << actual_choice << " has been at highest " << highest_rank << " and lowest " << lowest_rank << "]" << std::endl ;
                    }
                }
            }


// -----------------------------------------------
//  If the total score increased during this
//  sorting pass, reset the highest and lowest
//  sequence-position values according to the
//  current sort order, and reset the flag
//  that might have indicated a stable condition.

            if ( sort_pass_counter == pass_count_at_last_score_increase )
            {
                if ( true_or_false_log_details == global_true ) { log_out << "\n[insertion sort, in sort-pass loop, score increased during this pass, so initializing highest and lowest positions for all choices]\n" ; } ;
                reached_stable_condition_at_pass_count = 0 ;
                count_of_sequences_with_same_highest_score = 0 ;
                for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
                {
                    actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
                    adjusted_choice = local_adjusted_choice_for_actual_choice[ actual_choice ] ;
                    highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = sequence_position ;
                    lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] = sequence_position ;
                }
            }


// -----------------------------------------------
//  Log the movement of any choices during this
//  sorting pass.

            if ( true_or_false_log_details == global_true )
            {
                if ( sort_pass_count_at_last_move == sort_pass_counter )
                {
                    log_out << "\n[insertion sort, in sort-pass loop, at least one choice moved during this sorting pass]\n" ;
                } else
                {
                    log_out << "\n[insertion sort, in sort-pass loop, no choices moved during this sorting pass]\n" ;
                }

                for ( adjusted_choice = 1 ; adjusted_choice <= local_adjusted_choice_count ; adjusted_choice ++ )
                {
                    pass_number = pass_number_at_last_rerank_for_adjusted_choice[ adjusted_choice ] ;
                    if ( pass_number == sort_pass_counter )
                    {
                        actual_choice = local_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                        log_out << "[insertion sort, in sort-pass loop, choice " << actual_choice << " moved during this pass]\n" ;
                    }
                }
                log_out << std::endl ;
            }


// -----------------------------------------------
//  Repeat the loop that sorts the choices (until
//  they stabilize).

        }


// -----------------------------------------------
//  Log the ending sequence.

        if ( true_or_false_log_details == global_true )
        {
            log_out << "\n[insertion sort, in main loop, ending sequence is: " ;
            for ( sequence_position = 1 ; sequence_position <= local_adjusted_choice_count ; sequence_position ++ )
            {
                actual_choice = actual_choice_in_insertion_rank_sequence_position[ sequence_position ] ;
                log_out << actual_choice << " , " ;
            }
            log_out << "]" << std::endl ;
        }


// -----------------------------------------------
//  If only one sequence has the highest sequence
//  score, do not do any sub-set sorting (to
//  ensure finding correct most-popular choice).

        if ( ( main_loop_count == 1 ) && ( count_of_sequences_with_same_highest_score == 1 ) )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, only one sequence has highest sequence score, so exiting main loop]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  If this is the final stage, put the highest-
//  ranked choice (or choices) back into the full
//  sequence, at the highest ranking.
//  Also adjust the values that keep track of
//  each choice's highest and lowest positions.

        if ( final_stage_reached_at_main_loop_count == main_loop_count )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, wrapping up final stage]\n" ; } ;
            source_sequence_position = local_adjusted_choice_count ;
            for ( destination_sequence_position = global_adjusted_choice_count ; destination_sequence_position >= global_adjusted_choice_count - local_adjusted_choice_count + 1 ; destination_sequence_position -- )
            {
                actual_choice_to_move = actual_choice_in_insertion_rank_sequence_position[ source_sequence_position ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[lower choice " << actual_choice_to_move << " is restored to adjusted choice " << adjusted_choice_to_move << "]" << std::endl ; } ;
                actual_choice_in_insertion_rank_sequence_position[ destination_sequence_position ] = actual_choice_to_move ;
                adjusted_choice_to_move = global_adjusted_choice_for_actual_choice[ actual_choice_to_move ] ;
                highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] += global_adjusted_choice_count - local_adjusted_choice_count ;
                lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] += global_adjusted_choice_count - local_adjusted_choice_count ;
                if ( true_or_false_log_details == global_true ) { log_out << "[choice " << actual_choice_to_move << " has highest sequence position " << highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] << " and lowest sequence position " << lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice_to_move ] << "]" << std::endl ; } ;
                source_sequence_position -- ;
            }
            for ( destination_sequence_position = 1 ; destination_sequence_position <= count_of_highest_ranked_choices ; destination_sequence_position ++ )
            {
                choice_counter = destination_sequence_position ;
                actual_choice = highest_ranked_actual_choice_at_count[ choice_counter ] ;
                actual_choice_in_insertion_rank_sequence_position[ destination_sequence_position ] = actual_choice ;
                adjusted_choice = global_adjusted_choice_for_actual_choice[ actual_choice ] ;
                if ( true_or_false_log_details == global_true ) { log_out << "[highest choice " << actual_choice << " is restored to adjusted choice " << adjusted_choice << "]" << std::endl ; } ;
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, in main loop, done with final stage, exiting main loop]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  Repeat the loop to do the next stage of
//  calculations.

    }


// -----------------------------------------------
//  If, at the end of the multiple sorting
//  passes, any of the choices were still moving,
//  this indicates that some choices are tied (at
//  the same ranking level), so determine
//  which choices are tied, and at which levels.
//  If no choices have moved, use the following
//  code anyway because it normalizes the
//  ranking levels.
//  For each choice, multiply the sum of
//  the highest and lowest ranking level by
//  a constant (10 times the number of choices minus one)
//  and convert the result to an integer.
//  Use these "averaged scaled integerized"
//  ranking levels to calculate normalized
//  (and normal) ranking levels, where
//  choices are ranked at the same level if
//  they have the same
//  averaged-scaled-integerized values.

    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, calculating averaged-scaled-integerized levels]\n" ; } ;
    scale_value = 10 * ( global_adjusted_choice_count - 1 ) ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        highest_rank = highest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] ;
        lowest_rank = lowest_insertion_sort_sequence_position_for_actual_choice[ actual_choice ] ;
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, done, choice " << actual_choice << " has been at highest rank level " << highest_rank << " and lowest rank level " << lowest_rank << "]" << std::endl ; } ;
        special_ranking_level = int( ( highest_rank + lowest_rank ) * scale_value ) ;
        global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] = special_ranking_level ;
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, choice " << actual_choice << " at special rank level " << special_ranking_level << "]" << std::endl ; } ;
    }
    normalize_ranking( ) ;
    if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, final normalized ranking levels]\n" ; } ;
    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        ranking_level = global_rank_to_normalize_for_adjusted_choice[ adjusted_choice ] ;
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] = ranking_level ;
        if ( true_or_false_log_details == global_true ) { log_out << "[insertion sort, choice " << actual_choice << " at normalized rank level " << ranking_level << "]" << std::endl ; } ;
    }


// -----------------------------------------------
//  For monitoring, display the tally numbers in
//  an array/matrix arrangement.
//  Use the sequence that was determined when
//  normalization was done.

    if ( true_or_false_log_details == global_true )
    {
        log_out << "[insertion sort, final insertion-sort popularity ranking:]\n" ;
        internal_view_matrix( ) ;
        if ( global_sequence_score > global_sequence_score_using_insertion_sort_method )
        {
            global_sequence_score_using_insertion_sort_method = global_sequence_score ;
            log_out << "\n[insertion sort, new sequence score is: " << global_sequence_score_using_insertion_sort_method << "]" << std::endl ;
        }
    }


// -----------------------------------------------
//  Log the calculated ranking levels.

    if ( true_or_false_log_details == global_true )
    {
        log_out << "[insertion sort, final results:]\n" ;
        for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
        {
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            log_out << "[  choice " << actual_choice << " is at ranking level " << global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] << "]" << std::endl ;
        }
    }


// -----------------------------------------------
//  End of function calc_votefair_insertion_sort_popularity_rank.

    if ( global_logging_info == global_true ) { log_out << "\n[insertion sort, exiting calc_votefair_insertion_sort_popularity_rank function]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            calc_votefair_popularity_rank
//
//  Handles the overhead actions for calculating
//  VoteFair popularity ranking results, as
//  described in the book "Ending The Hidden
//  Unfairness In U.S. Elections", and as
//  described in Wikipedia as the "Condorcet-Kemeny
//  method" (which redirects to the "Kemeny-Young
//  method" article).  See VoteFair.org for details.
//
//  These results are used in situations where
//  a single seat is being filled (and there is
//  only one such seat), or to determine the full
//  ranking of choices, or to correctly identify
//  the least-popular choice (where that choice
//  is a contestant who is eliminated before the
//  next round of the contest).
//
// -----------------------------------------------
// -----------------------------------------------

void calc_votefair_popularity_rank( )
{

    int actual_choice ;
    int adjusted_choice ;
    int ranking_level ;
    int twice_highest_possible_score ;
    int ranking_level_from_all_scores_calc ;


// -----------------------------------------------
//  Initialize the result rankings -- to zeros, which
//  indicate that no ranking has been done.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        if ( global_using_choice[ actual_choice ] == global_true )
        {
            global_popularity_ranking_for_actual_choice[ actual_choice ] = 0 ;
        }
    }
    global_choice_count_at_top_popularity_ranking_level = 0 ;
    global_actual_choice_at_top_popularity_ranking_level = 0 ;


// -----------------------------------------------
//  Initialize the insertion-sort rankings to zeros,
//  which indicate that no ranking has been done.

    for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
    {
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        if ( global_using_choice[ actual_choice ] == global_true )
        {
            global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] = 0 ;
        }
    }


// -----------------------------------------------
//  If the total of the vote counts is zero,
//  there is a code bug, so indicate an error.

    if ( global_current_total_vote_count <= 0 )
    {
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, zero counts on ballots]\n" ; } ;
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, Error: Case " << global_case_number << " has triggered a program bug caused by a failure to check for zero vote counts]\n" ; } ;
        global_possible_error_message += "Error: Unexpectedly the vote count is zero." ;
        return ;
    }


// -----------------------------------------------
//  If there are not at least two choices,
//  indicate an error and return.

    if ( global_adjusted_choice_count < 2 )
    {
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, ERROR: number of (adjusted) choices is less than two]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Do VoteFair choice-specific pairwise-score
//  (CSPS) ranking.

    if ( global_logging_info == global_true ) { log_out << "[popularity rank, VoteFair choice-score ranking calculations beginning]\n" ; } ;
    calc_votefair_choice_specific_pairwise_score_popularity_rank( ) ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, VoteFair choice-score ranking calculations done]\n" ; } ;


// -----------------------------------------------
//  Do VoteFair popularity ranking using the
//  insertion-sort method, starting with the
//  ranking that was calculated by the
//  choice-specific pairwise-score (CSPS)
//  method.

    if ( global_logging_info == global_true ) { log_out << "[popularity rank, VoteFair insertion-sort popularity ranking calculations beginning]\n" ; } ;
    calc_votefair_insertion_sort_popularity_rank( ) ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, VoteFair insertion-sort popularity ranking calculations done]\n" ; } ;


// -----------------------------------------------
//  Optionally, in the future, do a cross-check
//  that uses the all-scores method to rank the
//  top six choices.  This cross-check would
//  identify theoretically possible situations
//  in which the highest-ranked choice is not
//  the highest-ranked choice in a sequence that
//  has the single (untied) highest sequence
//  score.  Cases that involve multiple sequences
//  with the same highest sequence score are not
//  relevant for matching Condorcet-Kemeny
//  results because that method does not specify
//  how multiple same-highest-score cases should
//  be resolved.


// -----------------------------------------------
//  If there are too many choices, or if there
//  are too many ballots that could combine with
//  the number of choices to produce an overflow
//  in the highest sequence score, skip the
//  calculations (done in the next section)
//  that check all the sequence scores.

    global_check_all_scores_choice_limit = 6 ;
    twice_highest_possible_score = global_adjusted_choice_count * global_adjusted_choice_count * global_current_total_vote_count ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, adjusted choice count is " << global_adjusted_choice_count << "]" << std::endl ; } ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, total vote count is " << global_current_total_vote_count << "]" << std::endl ; } ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, twice highest possible score is " << twice_highest_possible_score << "]" << std::endl ; } ;

    if ( ( global_adjusted_choice_count <= global_check_all_scores_choice_limit ) && ( twice_highest_possible_score <= global_maximum_twice_highest_possible_score ) )
    {


// -----------------------------------------------
//  Do VoteFair popularity ranking calculations
//  by calculating all the sequence scores and
//  finding the sequence with the highest score.

        if ( global_logging_info == global_true ) { log_out << "[popularity rank, calling calc_all_sequence_scores function]\n" ; } ;
        calc_all_sequence_scores( ) ;
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, returned from calc_all_sequence_scores function]\n" ; } ;
    }


// -----------------------------------------------
//  If the full-score calculations were not done,
//  and the insertion-sort calculations were done,
//  use the results from the insertion-sort
//  calculations.

    int ranking_level_from_insertion_sort_calc ;

    adjusted_choice = 1 ;
    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
    ranking_level_from_all_scores_calc = global_popularity_ranking_for_actual_choice[ actual_choice ] ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, sample choice " << actual_choice << " is at popularity level " << ranking_level_from_all_scores_calc  << "]" << std::endl ; } ;
    ranking_level_from_insertion_sort_calc = global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] ;
    if ( global_logging_info == global_true ) { log_out << "[popularity rank, sample choice " << actual_choice << " is at insert-sort popularity level " << ranking_level_from_insertion_sort_calc  << "]" << std::endl ; } ;
    if ( ( ranking_level_from_all_scores_calc == 0 ) && ( ranking_level_from_insertion_sort_calc != 0 ) )
    {
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, using insertion-sort ranking results (because all-score method not done]\n" ; } ;
        {
            global_sequence_score_using_all_scores_method = 0 ;
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                ranking_level = global_insertion_sort_popularity_rank_for_actual_choice[ actual_choice ] ;
                global_popularity_ranking_for_actual_choice[ actual_choice ] = ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[  choice " << actual_choice << " is at popularity level " << ranking_level  << "]" << std::endl ; } ;
            }
        }
    }


// -----------------------------------------------
//  If the full-score calculations were not done,
//  create a warning message that applies to the
//  current question, and request only plurality
//  counts, and skip over the next section.

    adjusted_choice = 1 ;
    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
    if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 0 )
    {
        if ( global_logging_info == global_true ) { log_out << "[popularity rank, Warning: Too many choices (" << global_adjusted_choice_count << ") for this software version (which handles " << global_check_all_scores_choice_limit << "), so only plurality results calculated]\n" ; } ;
        global_true_or_false_request_only_plurality_results = global_true ;
    } else
    {


// -----------------------------------------------
//  For use by the VoteFair representation
//  ranking and VoteFair party ranking
//  functions, count the number of choices
//  that are ranked as most popular.
//  If there is just one top-ranked choice,
//  make it available as a single value.
//  Otherwise set the single value to zero.

        adjusted_choice = 1 ;
        actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
        if ( global_popularity_ranking_for_actual_choice[ actual_choice ] > 0 )
        {
            global_choice_count_at_top_popularity_ranking_level = 0 ;
            global_actual_choice_at_top_popularity_ranking_level = 0 ;
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
                {
                    global_choice_count_at_top_popularity_ranking_level ++ ;
                    if ( global_choice_count_at_top_popularity_ranking_level == 1 )
                    {
                        global_actual_choice_at_top_popularity_ranking_level = actual_choice ;
                    } else
                    {
                        global_actual_choice_at_top_popularity_ranking_level = 0 ;
                    }
                    if ( global_logging_info == global_true ) { log_out << "[popularity rank, choice " << actual_choice << " is at top ranking level]\n" ; } ;
                }
            }
            if ( global_logging_info == global_true ) { log_out << "[popularity rank, count of most-popular choices is " << global_choice_count_at_top_popularity_ranking_level << "]" << std::endl ; } ;
            if ( global_logging_info == global_true ) { log_out << "[popularity rank, if only one top choice, choice number is " << global_actual_choice_at_top_popularity_ranking_level << "]" << std::endl ; } ;
        }


// -----------------------------------------------
//  Finish skipping the above section if the
//  calculations were not done.

    }


// -----------------------------------------------
//  Compare the results with other calculation
//  methods.

    compare_popularity_results( ) ;


// -----------------------------------------------
//  End of function calc_votefair_popularity_rank.

    if ( global_logging_info == global_true ) { log_out << "[popularity rank, done calculating VoteFair popularity ranking results for question " << global_question_number << " in case " << global_case_number << "]" << std::endl ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            calc_votefair_representation_rank
//
//  Calculates VoteFair representation ranking
//  results, as described in the book "Ending The
//  Hidden Unfairness In U.S. Elections."
//  These results are used in situations where
//  more than one choice is selected, such as
//  when there is more than one seat being filled,
//  or when there is more than one activity
//  (for participation) being offered at the
//  same time (and attendance at both activities
//  is not possible).
//  The first-most representative choice is the most
//  popular based on VoteFair popularity ranking,
//  which is calculated before arriving here.
//  Therefore, this function identifies the
//  VoteFair-based second-most representative,
//  third-most representative, etc. choices
//  in an election.
//
// -----------------------------------------------
// -----------------------------------------------

void calc_votefair_representation_rank( )
{

    int actual_choice ;
    int adjusted_choice ;
    int most_preferred_choice ;
    int previous_most_representative_choice ;
    int ignored_vote_count ;
    int non_ignored_vote_count ;
    int alternative_most_preferred_choice ;
    int vote_count_for_reduced_influence ;
    int tie_exists ;
    int number_of_representation_levels_ranked ;
    int number_of_choices_rep_ranked ;
    int single_nonranked_choice ;
    int initial_choice_count_for_rep_ranking ;
    int true_or_false_log_details ;

    float reduced_influence_amount ;

    std::string text_reduced_influence_amount ;
    std::size_t text_length_unused ;


// -----------------------------------------------
//  Hide or show the details in the log file.

    true_or_false_log_details = global_false ;
    if ( global_logging_info == global_true )
    {
        log_out << "\n[rep ranking, beginning calc_votefair_representation_rank function]\n" ;
        if ( true_or_false_log_details == global_true )
        {
            log_out << "[rep ranking, details shown (change flag value to hide details)]\n" ;
        } else
        {
            log_out << "[rep ranking, details hidden (change flag value to view details)]\n" ;
        }
    }


// -----------------------------------------------
//  Starting representation calculations.

    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, starting representation calculations]\n" ; } ;


// -----------------------------------------------
//  Count the number of choices to be ranked.
//  Also initialize the list that keeps track of
//  which choices have been "representation"
//  ranked so far.
//  Assume that not all the choices are
//  involved (which applies to calculations
//  needed by VoteFair party ranking), which
//  means that if a choice is not being used
//  (overall), then it is not involved in this
//  ranking.
//  Also initialize the list that holds the
//  results -- to indicate which choices were
//  not ranked in case of an early exit.

    initial_choice_count_for_rep_ranking = 0 ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_using_choice[ actual_choice ] == global_true )
        {
            global_representation_ranking_for_actual_choice[ actual_choice ] = 0 ;
            initial_choice_count_for_rep_ranking ++ ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, need to rank choice " << actual_choice << "]" << std::endl ; } ;
        } else
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, will not be ranking choice " << actual_choice << "]" << std::endl ; } ;
        }
    }
    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, number of choices to rank is " << initial_choice_count_for_rep_ranking << " (out of " << global_full_choice_count << " choices)]\n" ; } ;


// -----------------------------------------------
//  If there are not at least two choices,
//  indicate an error.

    if ( initial_choice_count_for_rep_ranking < 2 )
    {
        if ( global_logging_info == global_true ) { log_out << "[rep ranking, ERROR: number of choices for representation ranking is less than two]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  If there are only two choices, indicate that
//  the second choice (not the most popular
//  choice) is ranked second.  However, if there
//  is a tie at the top level, indicate those
//  two choices as tied for representation
//  ranking.

    if ( initial_choice_count_for_rep_ranking == 2 )
    {
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, number of choices for representation ranking is two]\n" ; } ;
        if ( global_choice_count_at_top_popularity_ranking_level == 1 )
        {
            most_preferred_choice = global_actual_choice_at_top_popularity_ranking_level ;
            global_representation_ranking_for_actual_choice[ most_preferred_choice ] = 1 ;
            global_using_choice[ most_preferred_choice ] = global_false ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, first-most-representative choice is " << most_preferred_choice << "]" << std::endl ; } ;
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( ( global_using_choice[ actual_choice ] == global_true ) && ( actual_choice != most_preferred_choice ) )
                {
                    global_representation_ranking_for_actual_choice[ actual_choice ] = 2 ;
                    global_second_most_representative_actual_choice = actual_choice ;
                    global_using_choice[ actual_choice ] = global_false ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, second-most-representative choice is " << actual_choice << "]" << std::endl ; } ;
                    break ;
                }
            }
        } else
        {
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( global_using_choice[ actual_choice ] == global_true )
                {
                    global_representation_ranking_for_actual_choice[ actual_choice ] = 1 ;
                    global_using_choice[ actual_choice ] = global_false ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, two-way tie, most representative choice is " << actual_choice << "]" << std::endl ; } ;
                }
            }
        }
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, the only two choices have been ranked, done with representation ranking]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Specify how many representation levels
//  should be calculated.
//  It cannot exceed the maximum allowance.
//  This is used as a minimum, and is exceeded if
//  there are ties or if just one choice remains.

    if ( global_representation_levels_requested > global_limit_on_representation_rank_levels )
    {
        global_representation_levels_requested = global_limit_on_representation_rank_levels ;
    }
    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, will calculate " << global_representation_levels_requested << " representation levels]\n" ; } ;


// -----------------------------------------------
//  If no representation calculations should
//  be done, indicate that and return.

    if ( global_representation_levels_requested < 1 )
    {
        if ( global_logging_info == global_true ) { log_out << "[rep ranking, no representation calculations were requested]\n" ; } ;
        return ;
    }


// -----------------------------------------------
// -----------------------------------------------
//  Begin the loop that identifies each pair of
//  most-representative choices.
//
//  Assume that the most popular choice has
//  already been determined.
//
//  The first time through this loop, most of the
//  first half of the loop identifies the
//  second-most representative choice, and
//  the second half of the loop identifies the
//  third-most representative choice (which is
//  the most popular choice among the remaining
//  choices, without any representation
//  adjustment.
//  The second time through this loop the
//  fourth-most representative and fifth-most
//  representative choices are identified.
//  Etc.

    number_of_choices_rep_ranked = 0 ;
    number_of_representation_levels_ranked = 0 ;
    global_second_most_representative_actual_choice = 0 ;
    while ( global_true )
    {


// -----------------------------------------------
//  Count the next representation level.

        number_of_representation_levels_ranked ++ ;
        if ( global_logging_info == global_true ) { log_out << "[rep ranking, identifying choices at representation level " << number_of_representation_levels_ranked << "]" << std::endl ; } ;


// -----------------------------------------------
//  Using the VoteFair popularity ranking results,
//  if there is just one currently most preferred
//  choice (among the remaining choices), identify
//  it as the first-most (or next-most)
//  representative choice.

        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, there are " << global_choice_count_at_top_popularity_ranking_level << " choices at the most popular level]\n" ; } ;
        if ( global_choice_count_at_top_popularity_ranking_level == 1 )
        {
            most_preferred_choice = global_actual_choice_at_top_popularity_ranking_level ;
            global_representation_ranking_for_actual_choice[ most_preferred_choice ] = number_of_representation_levels_ranked ;
            global_using_choice[ most_preferred_choice ] = global_false ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << most_preferred_choice << " is at rep level " << number_of_representation_levels_ranked << " (at repcase 1)]\n" ; } ;
            number_of_choices_rep_ranked ++ ;
            previous_most_representative_choice = most_preferred_choice ;


// -----------------------------------------------
//  If there is a tie at this level, rank the tied
//  choices at the current representation ranking
//  level, rank the remaining choices at the next
//  level, indicate that a tie-breaking vote must be
//  introduced before the full representation
//  ranking can be determined, and exit the main loop.

        } else if ( global_choice_count_at_top_popularity_ranking_level > 1 )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, at this representation ranking a tie -- among " << global_choice_count_at_top_popularity_ranking_level << " choices -- has been encountered]\n" ; } ;
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
                {
                    global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked ;
                } else
                {
                    global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked + 1 ;
                }
                global_using_choice[ actual_choice ] = global_false ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << actual_choice << " is at rep level " << global_representation_ranking_for_actual_choice[ actual_choice ] << " (at repcase 2)]\n" ; } ;
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because of tie]\n" ; } ;
            break ;
        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[rep ranking, ERROR: zero choices popularity ranked, so program bug!]\n" ; } ;
            return ;
        }


// -----------------------------------------------
//  If there is just one remaining choice, rank it
//  as least representative, and exit the loop.

        if ( number_of_choices_rep_ranked == initial_choice_count_for_rep_ranking - 1 )
        {
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( global_using_choice[ actual_choice ] == global_true )
                {
                    single_nonranked_choice = actual_choice ;
                    break ;
                }
            }
            number_of_representation_levels_ranked ++ ;
            global_representation_ranking_for_actual_choice[ single_nonranked_choice ] = number_of_representation_levels_ranked ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << single_nonranked_choice << " is the only choice remaining]\n" ; } ;
            global_using_choice[ single_nonranked_choice ] = global_false ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << single_nonranked_choice << " is at rep level " << number_of_representation_levels_ranked << " (at repcase 3)]\n" ; } ;
            number_of_choices_rep_ranked ++ ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because ranked last choice]\n" ; } ;
            global_using_choice[ previous_most_representative_choice ] = global_false ;
            break ;
        }


// -----------------------------------------------
//  If no more representation calculations are
//  needed, exit the main loop.

        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, number of rep ranked choices is " << number_of_choices_rep_ranked << "]" << std::endl ; } ;
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, current representation level is " << number_of_representation_levels_ranked << " (for repcase 3)]\n" ; } ;
        if ( ( number_of_choices_rep_ranked >= initial_choice_count_for_rep_ranking ) || ( number_of_representation_levels_ranked  >= global_representation_levels_requested ) )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because no more representation ranking needed]\n" ; } ;
            global_using_choice[ previous_most_representative_choice ] = global_false ;
            break ;
        }


// -----------------------------------------------
//  Indicate the previously most popular choice is
//  no longer considered in the remaining steps.

        global_using_choice[ previous_most_representative_choice ] = global_false ;
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << previous_most_representative_choice << " is ignored]\n" ; } ;


// -----------------------------------------------
// -----------------------------------------------
//  Restart at the beginning of all the ballots.

        reset_ballot_info_and_tally_table( ) ;


// -----------------------------------------------
//  Specify the normal influence of one vote per ballot.

        global_ballot_influence_amount = 1.0 ;


// -----------------------------------------------
//  Ignore any ballot in which the previous
//  most representative choice
//  (from among the non-ignored choices)
//  is ranked at the first preference level.
//
//  For the remaining ballots, ignore the
//  previous most representative choice
//  and convert the remaining ballot information
//  into numbers in a new tally table.

        if ( global_logging_info == global_true ) { log_out << "[rep ranking, now excluding ballots that rank choice " << previous_most_representative_choice << " as most preferred, and excluding that choice from the available choices]\n" ; } ;
        non_ignored_vote_count = 0 ;
        while ( global_true )
        {
            global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
            if ( global_ballot_info_repeat_count < 1 )
            {
                break ;
            }
            if ( global_ballot_preference_for_choice[ previous_most_representative_choice ] > 1 )
            {
                add_preferences_to_tally_table( ) ;
                non_ignored_vote_count += global_ballot_info_repeat_count ;
            } else
            {
                if ( global_logging_info == global_true ) { log_out << "[rep ranking, excluded]\n" ; } ;
            }
        }


// -----------------------------------------------
//  Calculate the number of votes ignored and the
//  number of votes not ignored.

        ignored_vote_count = global_current_total_vote_count - non_ignored_vote_count ;
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, " << non_ignored_vote_count << " ballots tallied, " << ignored_vote_count << " ballots ignored]\n" ; } ;


// -----------------------------------------------
//  If all the ballots were ignored, skip ahead to
//  calculate the popularity of the remaining choices.

        if ( non_ignored_vote_count == 0 )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, all the ballots have been ignored, so skipping several sections of code and then will calculate the popularity of the remaining choices]\n" ; } ;
        } else
        {


// -----------------------------------------------
//  Based on the information in the tally table,
//  and with some choices ignored,
//  identify the overall popularity ranking.

            if ( global_logging_info == global_true ) { log_out << "[rep ranking, ranking remaining choices (case 1)]\n" ; } ;
            calc_votefair_popularity_rank( ) ;


// -----------------------------------------------
//  Identify the first-most preferred choice.

            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, there are " << global_choice_count_at_top_popularity_ranking_level << " choices at the most popular level]\n" ; } ;
            if ( global_choice_count_at_top_popularity_ranking_level == 1 )
            {
                alternative_most_preferred_choice = global_actual_choice_at_top_popularity_ranking_level ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << alternative_most_preferred_choice << " is most preferred]\n" ; } ;
            } else if ( global_choice_count_at_top_popularity_ranking_level > 1 )
            {


// -----------------------------------------------
//  If there is a tie at this level, indicate it
//  and exit the main loop.

                tie_exists = global_true ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, two or more choices are tied as most-popular among the voters who did not rank the first-most representative choice at the first preference level]\n" ; } ;
                number_of_representation_levels_ranked ++ ;
                for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
                    {
                        global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked ;
                    } else
                    {
                        global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked + 1 ;
                    }
                    global_using_choice[ actual_choice ] = global_false ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << actual_choice << " is at rep level " << global_representation_ranking_for_actual_choice[ actual_choice ] << " (at repcase 4)]\n" ; } ;
                }
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because of tie]\n" ; } ;
                global_using_choice[ previous_most_representative_choice ] = global_false ;
                break ;
            } else
            {
                if ( global_logging_info == global_true ) { log_out << "[rep ranking, ERROR: zero choices popularity ranked, so program bug!]\n" ; } ;
                return ;
            }


// -----------------------------------------------
//  Ignore the previous most representative choice
//  in the remaining calculations.

            global_using_choice[ previous_most_representative_choice ] = global_false ;


// -----------------------------------------------
// -----------------------------------------------
//  Again restart at the beginning of all the ballots.

            reset_ballot_info_and_tally_table( ) ;


// -----------------------------------------------
//  Count the number of ballots in which
//  the previous most representative choice is
//  preferred over the alternative-most-preferred choice,
//  which was just identified.

            if ( global_logging_info == global_true ) { log_out << "[rep ranking, counting ballots that rank choice " << previous_most_representative_choice << " as preferred more than choice " << alternative_most_preferred_choice << "]" << std::endl ; } ;
            vote_count_for_reduced_influence = 0 ;
            while ( global_true )
            {
                global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
                if ( global_ballot_info_repeat_count < 1 )
                {
                    break ;
                }
                if ( global_ballot_preference_for_choice[ previous_most_representative_choice ] <= global_ballot_preference_for_choice[ alternative_most_preferred_choice ] )
                {
                    vote_count_for_reduced_influence += global_ballot_info_repeat_count ;
                    if ( global_logging_info == global_true ) { log_out << "[rep ranking, counted]\n" ; } ;
                }
            }
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, vote count for reduced influence is " << vote_count_for_reduced_influence << "]" << std::endl ; } ;


// -----------------------------------------------
//  Calculate the reduced influence that is appropriate
//  for voters who are already well-represented by the
//  first-most representative choice.

            if ( vote_count_for_reduced_influence >= 1 )
            {
                reduced_influence_amount = ( ( ( float ) vote_count_for_reduced_influence ) - ( ( ( float ) global_current_total_vote_count ) / 2.0 ) ) / ( ( float ) vote_count_for_reduced_influence ) ;
                if ( global_logging_info == global_true ) { log_out << "[rep ranking, influence reduced by: " << reduced_influence_amount << "]" << std::endl ; } ;
            } else
            {
                reduced_influence_amount = 0 ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, no ballots need their influence reduced]\n" ; } ;
            }
            if ( reduced_influence_amount < 0 )
            {
                reduced_influence_amount = 0 ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, the number calculated for the amount of reduced influence is less than zero, so a zero value is used instead]\n" ; } ;
            }


// -----------------------------------------------
// -----------------------------------------------
//  Again restart at the beginning of all the ballots.

            reset_ballot_info_and_tally_table( ) ;


// -----------------------------------------------
//  Again convert the ballot information into
//  numbers in a new tally table.  Reduce the
//  influence of any ballot in which the previous
//  most representative choice is preferred over
//  the alternative-most-preferred choice.
//  For other ballots, use the normal amount of
//  influence.  However, scale the decimal
//  values to integer numbers -- so that tied
//  situations are correctly handled.

            text_reduced_influence_amount = convert_float_to_text( reduced_influence_amount ) ;
            if ( global_logging_info == global_true ) { log_out << "[rep ranking, calculating popularity ranking with reduced influence -- of " << text_reduced_influence_amount << " -- for the " << vote_count_for_reduced_influence << " ballots that prefer choice " << previous_most_representative_choice << " more than choice " << alternative_most_preferred_choice << ", and scaling decimal pairwise counts by " << ( vote_count_for_reduced_influence * 10 ) << "]" << std::endl ; } ;
            while ( global_true )
            {
                global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
                if ( global_ballot_info_repeat_count < 1 )
                {
                    break ;
                }
                if ( global_ballot_preference_for_choice[ previous_most_representative_choice ] <= global_ballot_preference_for_choice[ alternative_most_preferred_choice ] )
                {
                    global_ballot_influence_amount = ( int ) ( ( reduced_influence_amount * ( ( float ) vote_count_for_reduced_influence ) * 10.0 ) + 0.5 ) ;
                    if ( global_logging_info == global_true ) { log_out << "[rep ranking, one ballot, influence reduced to " << convert_float_to_text( global_ballot_influence_amount ) << "]\n" ; } ;
                } else
                {
                    global_ballot_influence_amount = ( int ) ( ( 1.0 * ( ( float ) vote_count_for_reduced_influence ) * 10.0 ) + 0.5 ) ;
                    if ( global_logging_info == global_true ) { log_out << "[rep ranking, one ballot, at full influence " << convert_float_to_text( global_ballot_influence_amount ) << "]\n" ; } ;
                }
                add_preferences_to_tally_table( ) ;
            }


// -----------------------------------------------
//  Based on the information in the tally table,
//  identify the overall popularity ranking.

            if ( global_logging_info == global_true ) { log_out << "[rep ranking, ranking remaining choices (case 2)]\n" ; } ;
            calc_votefair_popularity_rank( ) ;


// -----------------------------------------------
//  Count the next representation level.

            number_of_representation_levels_ranked ++ ;
            if ( global_logging_info == global_true ) { log_out << "[rep ranking, identifying choices at representation ranking " << number_of_representation_levels_ranked << "]" << std::endl ; } ;


// -----------------------------------------------
//  If there is just one currently most preferred
//  choice, identify it as the next-most representative
//  choice based on the reduced influence of the
//  identified ballots.

            if ( global_choice_count_at_top_popularity_ranking_level == 1 )
            {
                most_preferred_choice = global_actual_choice_at_top_popularity_ranking_level ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << most_preferred_choice << " is most preferred]\n" ; } ;
                global_representation_ranking_for_actual_choice[ most_preferred_choice ] = number_of_representation_levels_ranked ;
                global_using_choice[ most_preferred_choice ] = global_false ;
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << most_preferred_choice << " is at rep level " << number_of_representation_levels_ranked << " (at repcase 6)]\n" ; } ;
                number_of_choices_rep_ranked ++ ;
                previous_most_representative_choice = most_preferred_choice ;


// -----------------------------------------------
//  If there is a tie at this level, list the tied
//  choices, indicate that a tie-breaking vote must be
//  introduced before the next-most representative
//  choices can be identified, and exit the main loop.

            } else
            {
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, at this representation ranking -- after reducing the influence of well-represented voters -- a tie has been encountered.  A tie-breaking vote is needed to go further]\n" ; } ;
                for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
                {
                    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                    if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
                    {
                        global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked ;
                    } else
                    {
                        global_representation_ranking_for_actual_choice[ actual_choice ] = number_of_representation_levels_ranked + 1 ;
                    }
                    global_using_choice[ actual_choice ] = global_false ;
                    if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << actual_choice << " is at rep level " << global_representation_ranking_for_actual_choice[ actual_choice ] << " (at repcase 7)]\n" ; } ;
                }
                if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because of tie]\n" ; } ;
                break ;
            }


// -----------------------------------------------
//  This is where the code skips ahead to if all
//  the voters indicate the previous-most
//  representative choice as their first choice.

        }


// -----------------------------------------------
// -----------------------------------------------
//  If there is just one remaining choice, rank it
//  as least representative, and exit the loop.

        if ( initial_choice_count_for_rep_ranking - number_of_choices_rep_ranked == 1 )
        {
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( global_using_choice[ actual_choice ] == global_true )
                {
                    single_nonranked_choice = actual_choice ;
                    break ;
                }
            }
            number_of_representation_levels_ranked ++ ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << single_nonranked_choice << " is the only choice remaining]\n" ; } ;
            global_representation_ranking_for_actual_choice[ single_nonranked_choice ] = number_of_representation_levels_ranked ;
            global_using_choice[ single_nonranked_choice ] = global_false ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, choice " << single_nonranked_choice << " is at rep level " << number_of_representation_levels_ranked << " (at repcase 8)]\n" ; } ;
            number_of_choices_rep_ranked ++ ;
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because ranked last choice]\n" ; } ;
            break ;
        }


// -----------------------------------------------
//  If no more representation calculations are
//  needed, exit the main loop.

        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, number of rep ranked choices is " << number_of_choices_rep_ranked << "]" << std::endl ; } ;
        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, next representation level is " << number_of_representation_levels_ranked << " (for repcase 8)]\n" ; } ;
        if ( ( number_of_choices_rep_ranked >= initial_choice_count_for_rep_ranking ) || ( number_of_representation_levels_ranked  >= global_representation_levels_requested ) )
        {
            if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, exiting loop because no more representation ranking needed]\n" ; } ;
            break ;
        }


// -----------------------------------------------
// -----------------------------------------------
//  Restart at the beginning of the ballots, and
//  initialize the tally table.

        reset_ballot_info_and_tally_table( ) ;


// -----------------------------------------------
//  Specify the normal influence of one vote per ballot.

        global_ballot_influence_amount = 1.0 ;


// -----------------------------------------------
//  Convert the ballot information -- for the
//  remaining choices -- into preferences in a
//  new tally table.

        if ( true_or_false_log_details == global_true ) { log_out << "[rep ranking, calculating popularity ranking for remaining choices]\n" ; } ;
        while ( global_true )
        {
            global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
            if ( global_ballot_info_repeat_count < 1 )
            {
                break ;
            }
            add_preferences_to_tally_table( ) ;
        }


// -----------------------------------------------
//  Based on the information in the tally table,
//  identify the overall popularity ranking.

        if ( global_logging_info == global_true ) { log_out << "[rep ranking, ranking remaining choices (case 3)]\n" ; } ;
        calc_votefair_popularity_rank( ) ;


// -----------------------------------------------
// -----------------------------------------------
//  Repeat the loop that identifies each pair of
//  most-representative choices.

    }


// -----------------------------------------------
// -----------------------------------------------
//  End of function calc_votefair_representation_rank.

    if ( global_logging_info == global_true ) { log_out << "\n[rep ranking, done doing representation calculations]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//            calc_votefair_party_rank
//
//  Calculates VoteFair party ranking results, as
//  described in the book "Ending The Hidden
//  Unfairness In U.S. Elections."
//  These results are used to determine the
//  maximum number of candidates each
//  political party is allowed to offer
//  in one election.  The number of allowed
//  candidates will vary according to the
//  election type, with less-important elections
//  not having any limits, and very important
//  elections, such as for U.S. President, allowing
//  two candidates each from the first-ranked and
//  second-ranked parties, one candidate each from
//  the next three or four parties, and no
//  candidates from any other parties.
//
// -----------------------------------------------
// -----------------------------------------------

void calc_votefair_party_rank( )
{

    int actual_choice ;
    int adjusted_choice ;
    int first_party_choice ;
    int second_party_choice ;
    int third_party_choice ;
    int next_party_choice ;
    int party_ranking_level ;
    int count_of_parties_ranked ;
    int non_ignored_vote_count ;
    int choice_specific_ranking_level ;


// -----------------------------------------------
//  Also do other initialization.

    if ( global_logging_info == global_true ) { log_out << "\n[party ranking, beginning VoteFair party ranking calculations]\n" ; } ;
    global_ballot_influence_amount = 1.0 ;
    count_of_parties_ranked = 0 ;
    first_party_choice = 0 ;
    second_party_choice = 0 ;
    third_party_choice = 0 ;
    party_ranking_level = 1 ;


// -----------------------------------------------
//  If there are no choices, return.

    if ( global_full_choice_count < 1 )
    {
        if ( global_logging_info == global_true ) { log_out << "[party ranking, Warning, no choices to rank for VoteFair party ranking]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Initialize the party ranking results to all
//  be unranked.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_party_ranking_for_actual_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  If there is only one choice, indicate that
//  the party is ranked in first place, and
//  then return.

    if ( global_full_choice_count == 1 )
    {
        global_party_ranking_for_actual_choice[ 1 ] = 1 ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, only one choice to rank, so done with party ranking]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Identify the first-ranked political party
//  as the most-popular party according to
//  VoteFair popularity ranking.
//  Instead of re-calculating, use the results
//  that were saved before VoteFair representation
//  ranking results were calculated.

    if ( global_choice_count_at_full_top_popularity_ranking_level == 1 )
    {
        party_ranking_level = 1 ;
        first_party_choice = global_actual_choice_at_top_of_full_popularity_ranking ;
        global_party_ranking_for_actual_choice[ first_party_choice ] = party_ranking_level ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, most preferred, is choice " << first_party_choice << "]" << std::endl ; } ;
        count_of_parties_ranked = 1 ;
        party_ranking_level ++ ;


// -----------------------------------------------
//  If there is a two-way tie at this first level,
//  use these two choices as the top two political
//  parties (with neither being identified as more
//  popular than the other).  In this case the
//  next party ranking level will be 3.

    } else if ( global_choice_count_at_full_top_popularity_ranking_level == 2 )
    {
        party_ranking_level = 1 ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, there is a two-way tie for first choice, so a tie-breaking ballot must be added]\n" ; } ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( global_full_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
            {
                if ( first_party_choice == 0 )
                {
                    first_party_choice = actual_choice ;
                    global_party_ranking_for_actual_choice[ first_party_choice ] = party_ranking_level ;
                } else if ( second_party_choice == 0 )
                {
                    second_party_choice = actual_choice ;
                    global_party_ranking_for_actual_choice[ second_party_choice ] = party_ranking_level ;
                    break ;
                }
            }
        }
        if ( global_logging_info == global_true ) { log_out << "[party ranking, tie at top between " << first_party_choice << " and " << second_party_choice << "]" << std::endl ; } ;
        count_of_parties_ranked  = 2 ;
        party_ranking_level = 3 ;


// -----------------------------------------------
//  If there is any other kind of tie at this
//  first level, indicate that a tie-breaking
//  vote must be introduced before the
//  next-ranked party can be identified, rank
//  the tied choices at level one, rank the
//  remaining choices at level three, and
//  exit this function.

    } else
    {
        party_ranking_level = 1 ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, there is a tie for first choice, so a tie-breaking ballot must be added]\n" ; } ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( global_full_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, tied choice: " << actual_choice << "]" << std::endl ; } ;
            } else if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = 3 ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, at (bottom) level 3 is choice " << actual_choice << "]" << std::endl ; } ;
            }
        }
        if ( global_logging_info == global_true ) { log_out << "[party ranking, exit multi_pop_tie, done with party ranking]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Specify that the second-ranked party is the
//  same as the second-ranked choice according to
//  VoteFair representation ranking (which has
//  already been calculated).

    if ( count_of_parties_ranked == 1 )
    {
        if ( global_choice_count_at_full_second_representation_level == 1 )
        {
            party_ranking_level = 2 ;
            second_party_choice = global_actual_choice_at_second_representation_ranking ;
            global_party_ranking_for_actual_choice[ second_party_choice ] = 2 ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, second-most preferred, is choice " << second_party_choice << "]" << std::endl ; } ;
            count_of_parties_ranked ++ ;
            party_ranking_level ++ ;


// -----------------------------------------------
//  If the VoteFair representation ranking
//  results had a tie in the
//  second-most-representative position,
//  indicate that a tie-breaking vote must be
//  introduced before the next-ranked party
//  can be identified, rank the tied choices at
//  level two, rank the remaining choices at
//  level three, and then exit this function.

        } else
        {
            party_ranking_level = 2 ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, there is a tie for second choice, so a tie-breaking ballot must be added]\n" ; } ;
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( global_logging_info == global_true ) { log_out << "[party ranking, representation rank for choice " << actual_choice << " is " << global_full_representation_ranking_for_actual_choice[ actual_choice ] << "]" << std::endl ; } ;
                if ( global_full_representation_ranking_for_actual_choice[ actual_choice ] == 2 )
                {
                    global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                    count_of_parties_ranked ++ ;
                    if ( global_logging_info == global_true ) { log_out << "[party ranking, tied choice: " << actual_choice << "]" << std::endl ; } ;
                } else if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
                {
                    global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level + 1 ;
                    if ( global_logging_info == global_true ) { log_out << "[party ranking, at bottom level " << party_ranking_level << ", is choice " << actual_choice << "]" << std::endl ; } ;
                }
            }
            if ( global_logging_info == global_true ) { log_out << "[party ranking, exit rep_tie, done with party ranking]\n" ; } ;
            return ;
        }
    }


// -----------------------------------------------
//  If there are only two choices (total),
//  return.

    if ( global_full_choice_count == 2 )
    {
        if ( global_logging_info == global_true ) { log_out << "[party ranking, only two choices, so done]\n" ; } ;
        return ;


// -----------------------------------------------
//  If there are only three choices, rank the
//  remaining party at the next ranking level.

    } else if ( global_full_choice_count == 3 )
    {
        party_ranking_level = 3 ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, party at third (and bottom) level is " << actual_choice << "]" << std::endl ; } ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, only three choices, so done with party ranking]\n" ; } ;
                return ;
            }
        }
    }


// -----------------------------------------------
//  Update which choices have not yet been party
//  ranked.

    set_all_choices_as_used( ) ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_party_ranking_for_actual_choice[ actual_choice ] > 0 )
        {
            global_using_choice[ actual_choice ] = global_false ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, ignoring choice " << actual_choice << "]" ; } ;
        }
    }


// -----------------------------------------------
//  For the third ranking, re-count the ballots
//  but ignore the ballots in which the first
//  choice -- even if tied (ranked at the same
//  level as another choice) -- is the
//  first-ranked or second-ranked party.

    if ( global_logging_info == global_true ) { log_out << "[party ranking, now excluding ballots that rank choice " << first_party_choice << " or " << second_party_choice << " as most preferred, even if there is a tie on the ballot]\n" ; } ;
    reset_ballot_info_and_tally_table( ) ;
    if ( global_logging_info == global_true ) { log_out << std::endl ; } ;
    non_ignored_vote_count = 0 ;
    while ( global_true )
    {
        global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
        if ( global_ballot_info_repeat_count < 1 )
        {
            break ;
        } else
        {
            if ( ( global_ballot_preference_for_choice[ first_party_choice ] > 1 ) && ( global_ballot_preference_for_choice[ second_party_choice ] > 1 ) )
            {
                add_preferences_to_tally_table( ) ;
                non_ignored_vote_count += global_ballot_info_repeat_count ;
                if ( global_logging_info == global_true ) { log_out << std::endl ; } ;
            } else
            {
                if ( global_logging_info == global_true ) { log_out << "[ignored]\n" ; } ;
            }
        }
    }


// -----------------------------------------------
//  If at least one ballot meets this criteria,
//  identify the most popular party according to
//  the just-counted ballots (for the remaining
//  choices), and use that most-popular choice as
//  the third-ranked political party.

    if ( non_ignored_vote_count >= 1 )
    {
        global_ranking_type_being_calculated = "party" ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, doing VoteFair popularity ranking as part of party ranking, but only with " << non_ignored_vote_count << " ballots meeting criteria]\n" ; } ;
        calc_votefair_popularity_rank( ) ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, ranking choices based on ballots meeting criteria]\n" ; } ;
        if ( global_choice_count_at_top_popularity_ranking_level == 1 )
        {
            third_party_choice = global_actual_choice_at_top_popularity_ranking_level ;
            global_party_ranking_for_actual_choice[ third_party_choice ] = party_ranking_level ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, third-most preferred, is choice " << third_party_choice << "]" << std::endl ; } ;
            count_of_parties_ranked ++ ;
            party_ranking_level ++ ;


// -----------------------------------------------
//  If there is a tie -- based on using just the
//  ballots that meet the indicated criteria --
//  then indicate a tie among those parties,
//  then rank the remaining parties at the next
//  level, and then exit the function.

        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[party ranking, there is a tie for third choice, so a tie-breaking ballot must be added]\n" ; } ;
            for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
            {
                actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
                if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
                {
                    global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                    count_of_parties_ranked ++ ;
                    if ( global_logging_info == global_true ) { log_out << "[party ranking, tied choice: " << actual_choice << "]" << std::endl ; } ;
                } else if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
                {
                    global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level + 1 ;
                    if ( global_logging_info == global_true ) { log_out << "[party ranking, at bottom level " << party_ranking_level << ", is choice " << actual_choice << "]" << std::endl ; } ;
                }
            }
            if ( global_logging_info == global_true ) { log_out << "[party ranking, exit some_ballots_tie, done with party ranking]\n" ; } ;
            return ;
        }
    } else
    {
        if ( global_logging_info == global_true ) { log_out << "[party ranking, zero ballots meet criteria]\n" ; } ;
    }


// -----------------------------------------------
//  If there are no choices remaining, exit the
//  function.

    if ( global_full_choice_count - count_of_parties_ranked == 0 )
    {
        if ( global_logging_info == global_true ) { log_out << "[party ranking, all choices ranked, so done with party ranking]\n" ; } ;
        return ;


// -----------------------------------------------
//  If there is only one choice remaining, rank
//  it at the bottom, and exit the function.

    } else if ( global_full_choice_count - count_of_parties_ranked == 1 )
    {
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, final party choice is " << actual_choice << "]" << std::endl ; } ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, no more choices, so done with party ranking]\n" ; } ;
                return ;
            }
        }
    }


// -----------------------------------------------
//  Update which choices have not yet been party
//  ranked.

    set_all_choices_as_used( ) ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_party_ranking_for_actual_choice[ actual_choice ] > 0 )
        {
            global_using_choice[ actual_choice ] = global_false ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, ignoring choice " << actual_choice << "]" << std::endl ; } ;
        }
    }


// -----------------------------------------------
//  Specify the fourth (or possibly third)
//  ranking to be the first choice -- among the
//  remaining choices, using all the ballots --
//  according to VoteFair popularity ranking.

    reset_ballot_info_and_tally_table( ) ;
    if ( global_logging_info == global_true ) { log_out << "[party ranking, now considering all ballots]\n" ; } ;
    while ( global_true )
    {
        global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
        if ( global_ballot_info_repeat_count < 1 )
        {
            break ;
        } else
        {
            add_preferences_to_tally_table( ) ;
        }
    }
    if ( global_logging_info == global_true ) { log_out << "[party ranking, using popularity ranking to identify next party choice]\n" ; } ;
    calc_votefair_popularity_rank( ) ;
    if ( global_choice_count_at_top_popularity_ranking_level == 1 )
    {
        next_party_choice = global_actual_choice_at_top_popularity_ranking_level ;
        global_party_ranking_for_actual_choice[ next_party_choice ] = party_ranking_level ;
        if ( global_logging_info == global_true ) { log_out << "[party ranking, next most preferred, is choice " << next_party_choice << "]" << std::endl ; } ;
        count_of_parties_ranked ++ ;
        party_ranking_level ++ ;


// -----------------------------------------------
//  If there was a tie, indicate which parties
//  (choices) are tied at this level, and rank
//  the remaining parties at the bottom, then
//  exit the function.

    } else
    {
        if ( global_logging_info == global_true ) { log_out << "[party ranking, there is a tie for first choice, so a tie-breaking ballot must be added]\n" ; } ;
        for ( adjusted_choice = 1 ; adjusted_choice <= global_adjusted_choice_count ; adjusted_choice ++ )
        {
            actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
            if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, tied choice: " << actual_choice << "]" << std::endl ; } ;
            } else if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level + 1 ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, at bottom level " << party_ranking_level << ", is choice " << actual_choice << "]" << std::endl ; } ;
            }
        }
        if ( global_logging_info == global_true ) { log_out << "[party ranking, exit post_rep_pop_tie, done with party ranking]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  If there is only one choice remaining,
//  identify it as the final choice, and then
//  exit the function.

    if ( global_full_choice_count - count_of_parties_ranked == 1 )
    {
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
            {
                global_party_ranking_for_actual_choice[ actual_choice ] = party_ranking_level ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, final party choice is " << actual_choice << "]" << std::endl ; } ;
                if ( global_logging_info == global_true ) { log_out << "[party ranking, exit post_rep_pop_last, no more choices, so done]\n" ; } ;
                return ;
            }
        }
    }


// -----------------------------------------------
//  Use VoteFair representation ranking to
//  rank the remaining parties.

    global_ranking_type_being_calculated = "party-representation" ;
    if ( global_logging_info == global_true ) { log_out << "[party ranking, transition from party ranking to representation ranking calculations]\n" ; } ;
    global_representation_levels_requested = global_full_choice_count - count_of_parties_ranked ;
    calc_votefair_representation_rank( ) ;
    if ( global_logging_info == global_true ) { log_out << "[party ranking, transition back to party ranking from representation ranking calculations]\n" ; } ;
    if ( global_logging_info == global_true ) { log_out << "[party ranking, current ranking level is " << party_ranking_level << "]" << std::endl ; } ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_party_ranking_for_actual_choice[ actual_choice ] == 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[party ranking, choice " << actual_choice << " is at rep-rank level " << global_representation_ranking_for_actual_choice[ actual_choice ] << "]" << std::endl ; } ;
            choice_specific_ranking_level = party_ranking_level - 2 + global_representation_ranking_for_actual_choice[ actual_choice ] ;
            global_party_ranking_for_actual_choice[ actual_choice ] = choice_specific_ranking_level ;
            if ( global_logging_info == global_true ) { log_out << "[party ranking, at party-ranked level " << choice_specific_ranking_level << " is choice " << actual_choice << "]" << std::endl ; } ;
        }
    }


// -----------------------------------------------
//  End of function calc_votefair_party_rank.

    if ( global_logging_info == global_true ) { log_out << "[party ranking, done with party ranking]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//       calculate_results_for_one_question
//
//  Calculates voting results for one question
//  (contest) in an election/poll/survey.
//
// -----------------------------------------------
// -----------------------------------------------

void calculate_results_for_one_question( )
{

    int actual_choice ;
    int adjusted_choice ;
    int ranking_level ;
    int popularity_level ;
    int representation_level ;
    int party_level ;
    int current_vote_info_number ;
    int sequence_position ;
    int context_question_number ;
    int total_vote_count_for_current_question ;

    std::string possible_text_rep_not_the_same ;
    std::string possible_text_party_not_the_same ;
    std::string comparison_of_methods_table ;


// -----------------------------------------------
//  These values must already be set:
//  (They are not checked for validity because
//  that is done before getting here.)
//      global_input_pointer_start_next_case
//      global_case_number
//      global_question_number
//      global_full_choice_count


// -----------------------------------------------
//  In case it is needed, initialize a prefix for
//  any warning message that refers to this
//  question.

    if ( global_logging_info == global_true ) { log_out << "[one question, beginning to do calculations for question " << global_question_number << "]" << std::endl ; } ;


// -----------------------------------------------
//  Clear the result lists in case some
//  calculations are not done.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_plurality_count_for_actual_choice[ actual_choice ] = 0 ;
        global_popularity_ranking_for_actual_choice[ actual_choice ] = 0 ;
        global_full_popularity_ranking_for_actual_choice[ actual_choice ] = 0 ;
        global_representation_ranking_for_actual_choice[ actual_choice ] = 0 ;
        global_full_representation_ranking_for_actual_choice[ actual_choice ] = 0 ;
        global_party_ranking_for_actual_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  Set up pointers and lists and values that
//  will be used for this question.

    if ( global_logging_info == global_true ) { log_out << std::endl ; } ;
    set_all_choices_as_used( ) ;
    reset_ballot_info_and_tally_table( ) ;
    global_ballot_influence_amount = 1.0 ;
    global_ballot_info_repeat_count = 0 ;
    global_current_total_vote_count = 0 ;
    if ( global_logging_info == global_true ) { log_out << std::endl ; } ;


// -----------------------------------------------
//  At the beginning of the vote info, look for
//  any requests regarding which calculations
//  should, or should not, be done.  Only check
//  as far as the end of the first ballot.
//  Also update the
//  "global_input_pointer_start_next_case"
//  pointer to skip over the code that indicates
//  how many choices are in each question.

    context_question_number = 0 ;
    global_pointer_to_current_ballot = global_input_pointer_start_next_case ;
    while ( global_pointer_to_current_ballot < global_maximum_vote_info_list_length )
    {
        current_vote_info_number = global_vote_info_list[ global_pointer_to_current_ballot ] ;
        if ( ( current_vote_info_number == global_voteinfo_code_for_end_of_ballot ) || ( current_vote_info_number == global_voteinfo_code_for_end_of_all_vote_info ) || ( current_vote_info_number == global_voteinfo_code_for_case_number ) || ( current_vote_info_number == global_voteinfo_code_for_end_of_all_cases ) )
        {
            break ;
        } else if ( current_vote_info_number == global_voteinfo_code_for_question_number )
        {
            global_pointer_to_current_ballot ++ ;
            context_question_number = global_vote_info_list[ global_pointer_to_current_ballot ] ;
        } else if ( current_vote_info_number == global_voteinfo_code_for_number_of_choices )
        {
            global_pointer_to_current_ballot ++ ;
            global_input_pointer_start_next_case = global_pointer_to_current_ballot + 1 ;
        } else if ( context_question_number == global_question_number )
        {
            if ( current_vote_info_number == global_voteinfo_code_for_request_only_plurality_results )
            {
                global_true_or_false_request_only_plurality_results = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[one question, request for only plurality results]" ; } ;
            } else if ( current_vote_info_number == global_voteinfo_code_for_request_no_pairwise_counts )
            {
                global_true_or_false_request_no_pairwise_counts = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[one question, request for no pairwise counts]" ; } ;
            } else if ( current_vote_info_number == global_voteinfo_code_for_request_votefair_representation_rank )
            {
                global_true_or_false_request_votefair_representation_rank = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[one question, request for representation ranking results]" ; } ;
            } else if ( current_vote_info_number == global_voteinfo_code_for_request_votefair_party_rank )
            {
                global_true_or_false_request_votefair_party_rank = global_true ;
                if ( global_logging_info == global_true ) { log_out << "[one question, request for party ranking results]" ; } ;
            }
        }
        global_pointer_to_current_ballot ++ ;
    }


// -----------------------------------------------
//  Log the status for what is being requested,
//  for this question and for all questions.

    if ( global_logging_info == global_true )
    {
        log_out << "[one question, requests: " ;
        if ( global_true_or_false_request_only_plurality_results == global_true )
        {
            log_out << "request for only plurality results" ;
        } else
        {
            log_out << "no special request for only plurality results" ;
        }
        if ( global_true_or_false_request_no_pairwise_counts == global_true )
        {
            log_out << " ; request for no pairwise counts" ;
        } else
        {
            log_out << " ; pairwise counts will be included" ;
        }
        if ( global_true_or_false_request_votefair_representation_rank == global_true )
        {
            log_out << " ; request for VoteFair representation ranking results" ;
        } else
        {
            log_out << " ; request for no VoteFair representation ranking results" ;
        }
        if ( global_true_or_false_request_votefair_party_rank == global_true )
        {
            log_out << " ; request for VoteFair party ranking results" ;
        } else
        {
            log_out << " ; request for no VoteFair party ranking results" ;
        }
        if ( global_true_or_false_request_text_output == global_true )
        {
            log_out << " ; request for text words in output" ;
        } else
        {
            log_out << " ; request for negative-number codes in output" ;
        }
        log_out << "]" << std::endl ;
    }


// -----------------------------------------------
//  If there are not at least two choices,
//  indicate an error.

    if ( global_adjusted_choice_count < 2 )
    {
        if ( global_logging_info == global_true ) { log_out << "[one question, ERROR: number of (adjusted) choices is less than two]\n" ; } ;
        return ;
    }


// -----------------------------------------------
//  Do the pairwise counting -- for all the
//  ballots and all the choices, with no special
//  weighting.
//  As part of getting the ballot information,
//  count the plurality results.
//  Also, if any requests for specific results
//  -- such as plurality counts only -- are
//  encountered, set the appropriate flag.

    global_pointer_to_current_ballot = global_input_pointer_start_next_case ;
    global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
    while ( global_ballot_info_repeat_count > 0 )
    {
        add_preferences_to_tally_table( ) ;
        global_ballot_info_repeat_count = get_numbers_based_on_one_ballot( ) ;
    }
    total_vote_count_for_current_question = global_current_total_vote_count ;
    if ( global_logging_info == global_true ) { log_out << "[one question, total vote count is " << total_vote_count_for_current_question << "]" << std::endl ; } ;


// -----------------------------------------------
//  If there were no ballots, indicate this in
//  the results, and exit this function.

    if ( total_vote_count_for_current_question == 0 )
    {
        if ( global_logging_info == global_true ) { log_out << "[one question, no ballots for this question, so no calculations done]\n" ; } ;
        if ( global_logging_info == global_true ) { log_out << "[one question, this question has no ballots]\n" ; } ;
        put_next_result_info_number( global_voteinfo_code_for_skip_question ) ;
        return ;
    }


// -----------------------------------------------
//  Output the plurality results.

    output_plurality_counts( ) ;


// -----------------------------------------------
//  If only plurality results are requested,
//  exit this function.

    if ( global_true_or_false_request_only_plurality_results == global_true )
    {
        if ( global_logging_info == global_true ) { log_out << "[one question, only plurality results requested, so further calculations not done]\n" ; } ;
        if ( global_logging_info == global_true ) { log_out << "[one question, all done for question " << global_question_number << " in case " << global_case_number << "]" << std::endl ; } ;
        return ;
    }


// -----------------------------------------------
//  Log a display of the tally numbers in
//  an array version.

    if ( global_logging_info == global_true )
    {
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            global_log_info_choice_at_position[ actual_choice ] = actual_choice ;
        }
        log_out << "[one question, full pairwise counts ranking:]\n" ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  Unless suppressed, output the pairwise counts
//  -- while the pairwise counts for all the
//  choices are still in the tally table.

    if ( global_true_or_false_request_no_pairwise_counts == global_false )
    {
        output_tally_table_numbers( ) ;
        if ( global_logging_info == global_true ) { log_out << "[one question, pairwise counts put into output list]\n" ; } ;
    }


// -----------------------------------------------
//  Do the VoteFair popularity ranking
//  calculations.

    global_ranking_type_being_calculated = "popularity" ;
    if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair popularity ranking calculations beginning]\n" ; } ;
    global_pointer_to_current_ballot = global_input_pointer_start_next_case ;
    calc_votefair_popularity_rank( ) ;
    if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair popularity ranking calculations done]\n" ; } ;
    if ( global_possible_error_message != "" )
    {
        return ;
    }


// -----------------------------------------------
//  If the popularity results were not calculated,
//  the error message has already been written,
//  so just return.

    adjusted_choice = 1 ;
    actual_choice = global_actual_choice_for_adjusted_choice[ adjusted_choice ] ;
    if ( global_popularity_ranking_for_actual_choice[ actual_choice ] == 0 )
    {
        return ;
    }


// -----------------------------------------------
//  Save the VoteFair popularity ranking results
//  that apply to all the choices (because the
//  rankings will be overwritten if VoteFair
//  representation ranking or VoteFair party
//  ranking calculations are done).
//  Also save the top-ranked choice -- if it is
//  a single winning choice -- for use by
//  the representation and party ranking
//  calculations.

    global_choice_count_at_full_top_popularity_ranking_level = 0 ;
    global_actual_choice_at_top_of_full_popularity_ranking = 0 ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_full_popularity_ranking_for_actual_choice[ actual_choice ] = global_popularity_ranking_for_actual_choice[ actual_choice ] ;
        if ( global_full_popularity_ranking_for_actual_choice[ actual_choice ] == 1 )
        {
            global_actual_choice_at_top_of_full_popularity_ranking = actual_choice ;
            global_choice_count_at_full_top_popularity_ranking_level ++ ;
        }
    }
    if ( global_choice_count_at_full_top_popularity_ranking_level != 1 )
    {
        global_actual_choice_at_top_of_full_popularity_ranking = 0 ;
    }
    if ( global_logging_info == global_true ) { log_out << "[one question, number of most-popular choices is " << global_choice_count_at_full_top_popularity_ranking_level << "]" << std::endl ; } ;
    if ( global_logging_info == global_true ) { log_out << "[one question, if only one top choice, choice number is " << global_actual_choice_at_top_of_full_popularity_ranking << "]" << std::endl ; } ;


// -----------------------------------------------
//  Log a display of the tally numbers with the
//  choices in popularity ranking sequence.

    if ( global_logging_info == global_true )
    {
        sequence_position = 1 ;
        for ( ranking_level = 1 ; ranking_level <= global_full_choice_count ; ranking_level ++ )
        {
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( global_full_popularity_ranking_for_actual_choice[ actual_choice ] == ranking_level )
                {
                    global_log_info_choice_at_position[ sequence_position ] = actual_choice ;
                    sequence_position ++ ;
                }
            }
        }
        log_out << "[one question, pairwise counts in VoteFair popularity ranking sequence:]\n" ;
        internal_view_matrix( ) ;
    }


// -----------------------------------------------
//  Determine how many levels of representation
//  ranking should be done.
//
//  If VoteFair party ranking results are
//  requested, request at least two levels of
//  VoteFair representation ranking results.

    if ( global_true_or_false_request_votefair_representation_rank == global_true )
    {
        global_representation_levels_requested = global_default_representation_levels_requested ;
        if ( global_representation_levels_requested > global_limit_on_representation_rank_levels )
        {
            global_representation_levels_requested = global_limit_on_representation_rank_levels ;
            if ( global_logging_info == global_true ) { log_out << "[one question, for representation ranking, calculation limit used]\n" ; } ;
        }
    } else
    {
        global_representation_levels_requested = 0 ;
        if ( global_logging_info == global_true ) { log_out << "[one question, no representation ranking requested]\n" ; } ;
    }
    if ( global_logging_info == global_true ) { log_out << "[representation ranking levels requested is " << global_representation_levels_requested << "]" << std::endl ; } ;
    if ( global_true_or_false_request_votefair_party_rank == global_true )
    {
        if ( global_representation_levels_requested < 2 )
        {
            global_representation_levels_requested = 2 ;
            if ( global_logging_info == global_true ) { log_out << "[one question, for party ranking, minimum of two representation levels requested]\n" ; } ;
        }
    }
    if ( total_vote_count_for_current_question < 2 )
    {
        global_representation_levels_requested = 0 ;
        if ( global_logging_info == global_true ) { log_out << "[one question, not at least two ballots, so no representation levels calculated]\n" ; } ;
    }


// -----------------------------------------------
//  If requested, do VoteFair representation
//  ranking -- using all the choices.

    if ( global_representation_levels_requested > 1 )
    {
        global_ranking_type_being_calculated = "representation" ;
        if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair representation ranking calculations beginning]\n" ; } ;
        global_pointer_to_current_ballot = global_input_pointer_start_next_case ;
        set_all_choices_as_used( ) ;
        calc_votefair_representation_rank( ) ;
        if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair representation ranking calculations end]\n" ; } ;


// -----------------------------------------------
//  If they were calculated, save the VoteFair
//  representation ranking results that apply
//  to all the choices (because these rankings
//  will be overwritten if VoteFair party
//  ranking calculations are done).
//  Also save the second-ranked representation
//  choice -- if it does not involve a tie --
//  for use by the party ranking calculations.

        global_choice_count_at_full_second_representation_level = 0 ;
        global_actual_choice_at_second_representation_ranking = 0 ;
        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            global_full_representation_ranking_for_actual_choice[ actual_choice ] = global_representation_ranking_for_actual_choice[ actual_choice ] ;
            if ( global_full_representation_ranking_for_actual_choice[ actual_choice ] == 2 )
            {
                global_actual_choice_at_second_representation_ranking = actual_choice ;
                global_choice_count_at_full_second_representation_level ++ ;
            }
        }
        if ( global_choice_count_at_full_second_representation_level != 1 )
        {
            global_actual_choice_at_second_representation_ranking = 0 ;
        }
        if ( global_logging_info == global_true ) { log_out << "[one question, number of second-most-representative choices is " << global_choice_count_at_full_second_representation_level << "]" << std::endl ; } ;
        if ( global_logging_info == global_true ) { log_out << "[one question, if only one top choice, choice number is " << global_actual_choice_at_second_representation_ranking << "]" << std::endl ; } ;


// -----------------------------------------------
//  If VoteFair party ranking results
//  have been requested, calculate them.

        if ( global_true_or_false_request_votefair_party_rank == global_true )
        {
            if ( total_vote_count_for_current_question < 3 )
            {
                if ( global_logging_info == global_true ) { log_out << "[one question, not at least three ballots, so no party ranking done]\n" ; } ;
            } else
            {
                global_ranking_type_being_calculated = "party" ;
                if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair party ranking calculations beginning]\n" ; } ;
                calc_votefair_party_rank( ) ;
                if ( global_logging_info == global_true ) { log_out << "[one question, VoteFair party ranking calculations done]\n" ; } ;
            }
        }
    }


// -----------------------------------------------
//  Output the VoteFair Ranking results, which may
//  include: VoteFair popularity ranking
//  results, VoteFair representation ranking
//  results, and VoteFair popularity ranking results.

    output_ranking_results( ) ;
    if ( global_logging_info == global_true ) { log_out << "[one question, all done for question " << global_question_number << " in case " << global_case_number << "]" << std::endl ; } ;


// -----------------------------------------------
//  In the log file show a comparison of the
//  results for different ranking methods:
//  popularity, representation, and party.

    if ( ( global_logging_info == global_true ) && ( ( global_true_or_false_request_votefair_popularity_rank == global_true ) || ( global_true_or_false_request_votefair_representation_rank == global_true ) ) )
    {
        possible_text_rep_not_the_same = "rep same" ;
        possible_text_party_not_the_same = "par same" ;
        comparison_of_methods_table = "[one question, case " + convert_integer_to_text( global_case_number ) + " , question " + convert_integer_to_text( global_question_number ) + " , comparison of popularity, representation, and party ranking]\n" ;
        for ( sequence_position = 1 ; sequence_position <= global_full_choice_count + 1 ; sequence_position ++ )
        {
            popularity_level = sequence_position ;
            if ( sequence_position == global_full_choice_count + 1 )
            {
                popularity_level = 0 ;
            }
            for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
            {
                if ( popularity_level == global_full_popularity_ranking_for_actual_choice[ actual_choice ] )
                {
                    representation_level = global_full_representation_ranking_for_actual_choice[ actual_choice ] ;
                    comparison_of_methods_table += "[  choice " + convert_integer_to_text( actual_choice ) + " at popularity level " + convert_integer_to_text( popularity_level ) + " , representation level " + convert_integer_to_text( representation_level ) ;
                    if ( global_true_or_false_request_votefair_party_rank == global_true )
                    {
                        party_level = global_party_ranking_for_actual_choice[ actual_choice ] ;
                        comparison_of_methods_table += " , party level " + convert_integer_to_text( party_level ) ;
                    } else
                    {
                        party_level = representation_level ;
                    }
                    comparison_of_methods_table += "]" ;
                    if ( popularity_level != representation_level )
                    {
                        possible_text_rep_not_the_same = "rep not same" ;
                        comparison_of_methods_table += " **** " ;
                    }
                    if ( representation_level != party_level )
                    {
                        possible_text_party_not_the_same = "par not same" ;
                        comparison_of_methods_table += " **** " ;
                    }
                    comparison_of_methods_table += "\n" ;
                }
            }
        }
        comparison_of_methods_table += "\n[" + possible_text_rep_not_the_same + "]\n[" + possible_text_party_not_the_same + "]\n" ;
        log_out << comparison_of_methods_table << std::endl ;
    }


// -----------------------------------------------
//  End of function calculate_results_for_one_question.

    if ( global_logging_info == global_true ) { log_out << "[one question handled]\n" ; } ;
    return ;

}



// -----------------------------------------------
// -----------------------------------------------
//      do_votefair_calculations
//
//  Does the requested calculations for all the
//  questions (although other functions do the
//  actual calculations).
//
// -----------------------------------------------
// -----------------------------------------------

void do_votefair_calculations( )
{


// -----------------------------------------------
//  Clear the output list.

    global_pointer_to_output_results = 0 ;
    global_output_results[ global_pointer_to_output_results ] = global_voteinfo_code_for_end_of_all_cases ;


// -----------------------------------------------
//  Indicate the case number in the results list.

    put_next_result_info_number( global_voteinfo_code_for_case_number ) ;
    put_next_result_info_number( global_case_number ) ;


// -----------------------------------------------
//  Point to the voteinfo data that follows the
//  case number.

    global_input_pointer_start_next_case = 1 ;
    while ( global_vote_info_list[ global_input_pointer_start_next_case ] != global_voteinfo_code_for_case_number )
    {
        global_input_pointer_start_next_case ++ ;
    }
    global_input_pointer_start_next_case ++ ;
    global_input_pointer_start_next_case ++ ;


// -----------------------------------------------
//  Write the total ballot count.

    put_next_result_info_number( global_voteinfo_code_for_total_ballot_count ) ;
    put_next_result_info_number( global_current_total_vote_count ) ;


// -----------------------------------------------
//  Begin a loop that handles each question.
//  Question numbers are sequential; no
//  question numbers are skipped.

    if ( global_logging_info == global_true ) { log_out << "\n[there are " << global_number_of_questions << " questions]\n" ; } ;
    for ( global_question_number = 1 ; global_question_number <= global_number_of_questions ; global_question_number ++ )
        {


// -----------------------------------------------
//  Indicate the question number in the results list.

        put_next_result_info_number( global_voteinfo_code_for_question_number ) ;
        put_next_result_info_number( global_question_number ) ;
        if ( global_logging_info == global_true ) { log_out << "\n[all questions, case " << global_case_number << ", question " << global_question_number << "]" << std::endl ; } ;


// -----------------------------------------------
//  Get the number of choices for this question.

        global_full_choice_count = global_choice_count_for_question[ global_question_number ] ;
        if ( global_logging_info == global_true ) { log_out << "[all questions, actual choice count = " << global_full_choice_count << "]" ; } ;


// -----------------------------------------------
//  Do the calculations for this question.

        calculate_results_for_one_question( ) ;


// -----------------------------------------------
//  Repeat the loop that handles the next question.

        if ( global_logging_info == global_true ) { log_out << "[this question done, repeating loop for next question]\n" ; } ;
    }


// -----------------------------------------------
//  End of function votefair_do_calculations_all_questions.

    if ( global_logging_info == global_true ) { log_out << "[all questions done, exiting function]\n" ; } ;
    return ;

}


// -----------------------------------------------
// -----------------------------------------------
//        elim_choice_to_eliminate
//
//  This function eliminates the choice specified
//  in global_choice_to_eliminate.
//
// -----------------------------------------------
// -----------------------------------------------

void elim_choice_to_eliminate( )
{


// -----------------------------------------------
//  Eliminate the specified choice.

    global_true_or_false_continuing_for_choice[ global_choice_to_eliminate ] = global_false ;
    if ( global_logging_info == global_true ) { log_out << "[eliminating choice " << global_choice_to_eliminate << "]" << std::endl ; } ;


// -----------------------------------------------
//  End of function elim_choice_to_eliminate.

    return ;

}


// -----------------------------------------------
// -----------------------------------------------
//        elim_if_just_one_then_winner
//
//  This function counts the number of
//  not-yet-eliminated choices, and if there is
//  just one then identifies the choice as the
//  winner.
//
// -----------------------------------------------
// -----------------------------------------------

int elim_if_just_one_then_winner( )
{

    int actual_choice ;
    int possible_single_continuing_choice ;
    int winner_of_elimination_rounds ;


// -----------------------------------------------
//  Initialization.

    winner_of_elimination_rounds = 0 ;


// -----------------------------------------------
//  Count the number of choices remaining (not yet
//  eliminated).

    global_count_of_continuing_choices = 0 ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_true_or_false_continuing_for_choice[ actual_choice ] == global_true )
        {
            global_count_of_continuing_choices ++ ;
            possible_single_continuing_choice = actual_choice ;
        }
    }
    if ( global_logging_info == global_true ) { log_out << "[continuing choice count is " << global_count_of_continuing_choices << "]" << std::endl ; } ;


// -----------------------------------------------
//  If there is only one choice remaining, indicate
//  it is the winner, and store the result.

    if ( global_count_of_continuing_choices < 2 )
    {
        winner_of_elimination_rounds = possible_single_continuing_choice ;
        put_next_result_info_number( global_elimination_result_type ) ;
        put_next_result_info_number( winner_of_elimination_rounds ) ;
        if ( global_logging_info == global_true ) { log_out << "[elimination winner is choice " << convert_integer_to_text( winner_of_elimination_rounds ) << "]" << std::endl ; } ;


// -----------------------------------------------
//  Compare the winner with the VoteFair winner.

        if ( global_logging_info == global_true ) { log_out << "[winner according to VoteFair popularity ranking is choice " << convert_integer_to_text( global_actual_choice_at_top_of_full_popularity_ranking ) << "]" << std::endl ; } ;
        if ( winner_of_elimination_rounds == global_actual_choice_at_top_of_full_popularity_ranking )
        {
            if ( global_logging_info == global_true ) { log_out << "[agrees with VoteFair ranking result]" << std::endl ; } ;
        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[IPE winner is different from VoteFair ranking winner]" << std::endl ; } ;
        }
    }


// -----------------------------------------------
//  End of function elim_if_just_one_then_winner.

    return winner_of_elimination_rounds ;

}


// -----------------------------------------------
// -----------------------------------------------
//        elim_count_pairwise_losses
//
//  This function counts the number of pairwise
//  losses for each choice.
//
// -----------------------------------------------
// -----------------------------------------------

int elim_count_pairwise_losses( )
{

    int pair_counter ;
    int actual_choice ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int actual_first_choice ;
    int actual_second_choice ;


// -----------------------------------------------
//  Initialization.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_loss_count_for_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  Count the number of pairwise loses for each
//  choice.

    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        adjusted_first_choice = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
        adjusted_second_choice = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;
        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
        if ( global_true_or_false_continuing_for_choice[ actual_first_choice ] == global_false )
        {
            continue ;
        }
        if ( global_true_or_false_continuing_for_choice[ actual_second_choice ] == global_false )
        {
            continue ;
        }
        if ( global_tally_first_over_second_in_pair[ pair_counter ] < global_tally_second_over_first_in_pair[ pair_counter ] )
        {
            global_loss_count_for_choice[ actual_first_choice ] ++ ;
            if ( global_logging_info == global_true ) { log_out << "[vote counts for choice " << actual_second_choice << " over choice " << actual_first_choice << " are " << global_tally_second_over_first_in_pair[ pair_counter ] << " versus " << global_tally_first_over_second_in_pair[ pair_counter ] << "]" << std::endl ; } ;
        } else if ( global_tally_second_over_first_in_pair[ pair_counter ] < global_tally_first_over_second_in_pair[ pair_counter ] )
        {
            global_loss_count_for_choice[ actual_second_choice ] ++ ;
            if ( global_logging_info == global_true ) { log_out << "[vote counts for choice " << actual_first_choice << " over choice " << actual_second_choice << " are " << global_tally_first_over_second_in_pair[ pair_counter ] << " versus " << global_tally_second_over_first_in_pair[ pair_counter ] << "]" << std::endl ; } ;
        } else
        {
            if ( global_logging_info == global_true ) { log_out << "[vote counts for choice " << actual_first_choice << " and choice " << actual_second_choice << " are " << global_tally_first_over_second_in_pair[ pair_counter ] << " and " << global_tally_second_over_first_in_pair[ pair_counter ] << "]" << std::endl ; } ;
        }
    }


// -----------------------------------------------
//  End of function elim_count_pairwise_losses.

    return 0 ;

}


// -----------------------------------------------
// -----------------------------------------------
//        elim_find_pairwise_loser
//
//  This function identifies which choice, if
//  any, loses all its pairwise contests.  The array
//  "global_true_or_false_continuing_for_choice"
//  specifies which choices are not yet eliminated.
//  This function's return value equals the actual
//  choice number of the pairwise loser, or else
//  equals zero to indicate that no pairwise
//  loser was found.
//  In academic literature the pairwise loser is
//  referred to as the Condorcet loser.
//
// -----------------------------------------------
// -----------------------------------------------

int elim_find_pairwise_loser( )
{

    int actual_choice ;


// -----------------------------------------------
//  Count the number of pairwise loses for each
//  choice.

    elim_count_pairwise_losses( ) ;


// -----------------------------------------------
//  If there is a pairwise loser, identify it.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_true_or_false_continuing_for_choice[ actual_choice ] == global_true )
        {
            if ( global_loss_count_for_choice[ actual_choice ] > 0 )
            {
                if ( global_loss_count_for_choice[ actual_choice ] == global_count_of_continuing_choices - 1 )
                {
                    if ( global_logging_info == global_true ) { log_out << "[found pairwise loser, choice " << actual_choice << "]" << std::endl ; } ;
                    return actual_choice ;
                }
            }
        }
    }


// -----------------------------------------------
//  End of function elim_find_pairwise_loser

    return 0 ;

}


// -----------------------------------------------
// -----------------------------------------------
//        elim_find_largest
//        elim_find_smallest
//        (elim_find_largest_or_smallest)
//
//  These functions find the largest or smallest
//  integer from among the choice-specific numbers
//  in the list named:
//    global_integer_count_for_choice[ ]
//
//  Negative numbers are ignored!!!
//  (Negative numbers are used to indicate ignored
//  integers.)
//
//  It returns the count of how many choices have
//  the largest, or smallest, count.
//
//  Upon return, the choice numbers that have the
//  largest, or smallest, count are in the list:
//    global_list_of_choices_with_largest_or_smallest_count[ ]
//
//  If there is no tie, the list of choices will
//  have only one valid choice number in array
//  position 1 (not position zero).
//
// -----------------------------------------------
// -----------------------------------------------

int elim_find_largest_or_smallest( )
{

    int largest_or_smallest_count = -1 ;
    int actual_choice = 0 ;
    int count_of_choices_at_largest_or_smallest_count = 0 ;
    int true_or_false_largest_or_smallest_count_initialized = global_false ;

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( ( global_integer_count_for_choice[ actual_choice ] >= 0 ) && ( ( true_or_false_largest_or_smallest_count_initialized != global_true ) || ( ( global_true_or_false_find_largest_not_smallest == global_true ) && ( global_integer_count_for_choice[ actual_choice ] > largest_or_smallest_count ) ) || ( ( global_true_or_false_find_largest_not_smallest == global_false ) && ( global_integer_count_for_choice[ actual_choice ] < largest_or_smallest_count ) ) ) )
        {
            true_or_false_largest_or_smallest_count_initialized = global_true ;
            largest_or_smallest_count = global_integer_count_for_choice[ actual_choice ] ;
            count_of_choices_at_largest_or_smallest_count = 1 ;
            global_list_of_choices_with_largest_or_smallest_count[ count_of_choices_at_largest_or_smallest_count ] = actual_choice ;
        } else if ( ( global_integer_count_for_choice[ actual_choice ] >= 0 ) && ( global_integer_count_for_choice[ actual_choice ] == largest_or_smallest_count ) )
        {
            count_of_choices_at_largest_or_smallest_count ++ ;
            global_list_of_choices_with_largest_or_smallest_count[ count_of_choices_at_largest_or_smallest_count ] = actual_choice ;
        }
    }
    return count_of_choices_at_largest_or_smallest_count ;

}

int elim_find_largest( )
{
    int largest_count ;
    global_true_or_false_find_largest_not_smallest = global_true ;
    largest_count = elim_find_largest_or_smallest( ) ;
    return largest_count ;
}

int elim_find_smallest( )
{
    int smallest_count ;
    global_true_or_false_find_largest_not_smallest = global_false ;
    smallest_count = elim_find_largest_or_smallest( ) ;
    return smallest_count ;
}

// -----------------------------------------------
//  End of functions:
//    elim_find_largest_or_smallest
//    elim_find_largest
//    elim_find_smallest


// -----------------------------------------------
// -----------------------------------------------
//        elim_find_pairwise_opposition_or_support
//        elim_find_largest_pairwise_opposition
//        elim_find_smallest_pairwise_support
//
//  These functions identify which choice has the
//  highest pairwise opposition count or has the
//  smallest pairwise support count.
//  Only the choices listed in the list:
//  "global_true_or_false_continuing_subset_includes_choice"
//  are included in the pairwise counting.  Ties
//  are possible.  The variable:
//  "global_count_of_choices_at_pairwise_max_opposition_or_min_support"
//  indicates how many choices have the highest
//  pairwise opposition count or the smallest
//  pairwise support count.  The actual choice
//  numbers are stored in the list:
//  "global_list_of_choices_having_pairwise_opposition_or_support"
//  (which is a single item if there is no tie).
//  This function does not eliminate any choice.
//
// -----------------------------------------------
// -----------------------------------------------

void elim_find_pairwise_opposition_or_support( )
{

    int pair_counter ;
    int actual_choice ;
    int adjusted_first_choice ;
    int adjusted_second_choice ;
    int actual_first_choice ;
    int actual_second_choice ;
    int choice_count ;


// -----------------------------------------------
//  Initialization.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_pairwise_opposition_or_support_count_for_choice[ actual_choice ] = 0 ;
    }


// -----------------------------------------------
//  Calculate the pairwise opposition count, or
//  pairwise support count if that is flagged,
//  for each choice for which the value of
//  "global_true_or_false_continuing_subset_includes_choice"
//  is true, and only consider contributions from
//  other choices that have not yet been eliminated.

    for ( pair_counter = 1 ; pair_counter <= global_pair_counter_maximum ; pair_counter ++ )
    {
        adjusted_first_choice = global_adjusted_first_choice_number_in_pair[ pair_counter ] ;
        adjusted_second_choice = global_adjusted_second_choice_number_in_pair[ pair_counter ] ;
        actual_first_choice = global_actual_choice_for_adjusted_choice[ adjusted_first_choice ] ;
        actual_second_choice = global_actual_choice_for_adjusted_choice[ adjusted_second_choice ] ;
        if ( global_true_or_false_continuing_subset_includes_choice[ actual_first_choice ] == global_false )
        {
            continue ;
        }
        if ( global_true_or_false_continuing_subset_includes_choice[ actual_second_choice ] == global_false )
        {
            continue ;
        }

        if ( global_true_or_false_find_pairwise_opposition_not_support == global_true )
        {
            global_pairwise_opposition_or_support_count_for_choice[ actual_first_choice ] += global_tally_second_over_first_in_pair[ pair_counter ] ;
            global_pairwise_opposition_or_support_count_for_choice[ actual_second_choice ] += global_tally_first_over_second_in_pair[ pair_counter ] ;
        } else
        {
            global_pairwise_opposition_or_support_count_for_choice[ actual_first_choice ] += global_tally_first_over_second_in_pair[ pair_counter ] ;
            global_pairwise_opposition_or_support_count_for_choice[ actual_second_choice ] += global_tally_second_over_first_in_pair[ pair_counter ] ;
        }
    }


// -----------------------------------------------
//  Identify which choice has the largest pairwise
//  opposition count or the smallest pairwise
//  support count. Allow for ties.

    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        if ( global_true_or_false_continuing_subset_includes_choice[ actual_choice ] == global_true )
        {
            global_integer_count_for_choice[ actual_choice ] = global_pairwise_opposition_or_support_count_for_choice[ actual_choice ] ;
            if ( global_true_or_false_find_pairwise_opposition_not_support == global_true )
            {
                if ( global_logging_info == global_true ) { log_out << "[pairwise opposition count for choice " << actual_choice << " is " << global_pairwise_opposition_or_support_count_for_choice[ actual_choice ] << "]" << std::endl ; } ;
            } else
            {
                if ( global_logging_info == global_true ) { log_out << "[pairwise support count for choice " << actual_choice << " is " << global_pairwise_opposition_or_support_count_for_choice[ actual_choice ] << "]" << std::endl ; } ;
            }
        } else
        {
            global_integer_count_for_choice[ actual_choice ] = -1 ;
        }
    }

    if ( global_true_or_false_find_pairwise_opposition_not_support == global_true )
    {
        global_count_of_choices_at_pairwise_max_opposition_or_min_support = elim_find_largest( ) ;
    } else
    {
        global_count_of_choices_at_pairwise_max_opposition_or_min_support = elim_find_smallest( ) ;
    }

    for ( choice_count = 1 ; choice_count <= global_count_of_choices_at_pairwise_max_opposition_or_min_support ; choice_count ++ )
    {
        global_list_of_choices_having_pairwise_opposition_or_support[ choice_count ] =
        global_list_of_choices_with_largest_or_smallest_count[ choice_count ] ;
    }


// -----------------------------------------------
//  End of function elim_find_pairwise_opposition_or_support.

    return ;

}

void elim_find_largest_pairwise_opposition( )
{
    if ( global_logging_info == global_true ) { log_out << "\n[checking pairwise opposition counts]" << std::endl ; } ;
    global_true_or_false_find_pairwise_opposition_not_support = global_true ;
    elim_find_pairwise_opposition_or_support( ) ;
    return ;
}

void elim_find_smallest_pairwise_support( )
{
    if ( global_logging_info == global_true ) { log_out << "\n[checking pairwise support counts]" << std::endl ; } ;
    global_true_or_false_find_pairwise_opposition_not_support = global_false ;
    elim_find_pairwise_opposition_or_support( ) ;
    return ;
}


// -----------------------------------------------
//  End of functions:
//        elim_find_pairwise_opposition_or_support
//        elim_find_largest_pairwise_opposition
//        elim_find_smallest_pairwise_support


// -----------------------------------------------
// -----------------------------------------------
//        method_instant_pairwise_elimination
//
//  This function implements the method named
//  "Instant Pairwise Elimination" (IPE).  It
//  does rounds of elimination and eliminates the
//  Condorcet loser or otherwise (when there is
//  not such a choice) eliminates the choice with
//  the largest pairwise opposition count.  If
//  there is a tie, it eliminates the choice with
//  the smallest pairwise support count.
//
// -----------------------------------------------
// -----------------------------------------------

void method_instant_pairwise_elimination( )
{

    int actual_choice ;
    int elimination_round_count ;
    int pointer_to_list_of_tied_choices ;
    int condorcet_loser ;
    int choice_with_largest_opposition_count ;


// -----------------------------------------------
//  Initialization.

    global_elimination_result_type = global_voteinfo_code_for_winner_instant_pairwise_elimination ;
    if ( global_logging_info == global_true ) { log_out << "\n[doing elimination method IPE]" << std::endl ; } ;
    for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
    {
        global_true_or_false_continuing_for_choice[ actual_choice ] = global_true ;
    }


// -----------------------------------------------
//  Begin the loop that handles each round of
//  elimination.

    for ( elimination_round_count = 1 ; elimination_round_count <= global_full_choice_count + 1 ; elimination_round_count ++ )
    {
        if ( global_logging_info == global_true ) { log_out << "\n[begin loop that does one IPE elimination]" << std::endl ; } ;


// -----------------------------------------------
//  If the number of choices remaining (not yet
//  eliminated) is one, identify it as the winner,
//  store the result, and exit this function.

        actual_choice = elim_if_just_one_then_winner( ) ;
        if ( actual_choice > 0 )
        {
            return ;
        }


// -----------------------------------------------
//  Identify a Condorcet loser -- "pairwise losing
//  candidate" -- if there is one.

        condorcet_loser = elim_find_pairwise_loser( ) ;


// -----------------------------------------------
//  Copy into the list
//  "global_true_or_false_continuing_subset_includes_choice"
//  the choices that are continuing (not yet eliminated).
//  This allows the same functions to be used for two
//  different calculation methods.

        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            global_true_or_false_continuing_subset_includes_choice[ actual_choice ] = global_true_or_false_continuing_for_choice[ actual_choice ] ;
        }


// -----------------------------------------------
//  Identify which choice has the largest pairwise
//  opposition count.

        choice_with_largest_opposition_count = 0 ;
        elim_find_largest_pairwise_opposition( ) ;
        if ( global_count_of_choices_at_pairwise_max_opposition_or_min_support == 1 )
        {
            choice_with_largest_opposition_count = global_list_of_choices_having_pairwise_opposition_or_support[ 1 ] ;
        }


// -----------------------------------------------
//  For analysis purposes, identify when the
//  Condorcet loser is not the same choice as the
//  choice with the largest opposition count.

        if ( ( condorcet_loser > 0 ) && ( choice_with_largest_opposition_count > 0 ) && ( choice_with_largest_opposition_count != condorcet_loser ) )
        {
            if ( global_logging_info == global_true ) { log_out << "[choice " << condorcet_loser << " is a Condorcet loser but does not have the single largest pairwise opposition count]" << std::endl ; } ;
        }


// -----------------------------------------------
//  If there is a Condorcet loser, eliminate that
//  choice.

        if ( condorcet_loser > 0 )
        {
            global_choice_to_eliminate = condorcet_loser ;
            elim_choice_to_eliminate( ) ;
            if ( global_logging_info == global_true ) { log_out << "[choice " << condorcet_loser << " is eliminated as the Condorcet loser]" << std::endl ; } ;
            continue ;
        }


// -----------------------------------------------
//  If there is only one choice with the largest
//  pairwise opposition count, eliminate it.

        if ( choice_with_largest_opposition_count > 0 )
        {
            if ( global_logging_info == global_true ) { log_out << "[choice " << choice_with_largest_opposition_count << " has the single largest pairwise opposition count]" << std::endl ; } ;
            global_choice_to_eliminate = choice_with_largest_opposition_count ;
            elim_choice_to_eliminate( ) ;
            continue ;
        }


// -----------------------------------------------
//  There is a tie, so from among the tied choices
//  calculate the pairwise support counts and
//  eliminate the choices with the smallest such
//  pairwise support counts unless no more choices
//  would remain.

        for ( actual_choice = 1 ; actual_choice <= global_full_choice_count ; actual_choice ++ )
        {
            global_true_or_false_continuing_subset_includes_choice[ actual_choice ] = global_false ;
        }
        for ( pointer_to_list_of_tied_choices = 1 ; pointer_to_list_of_tied_choices <= global_count_of_choices_at_pairwise_max_opposition_or_min_support ; pointer_to_list_of_tied_choices ++ )
        {
            actual_choice = global_list_of_choices_having_pairwise_opposition_or_support[ pointer_to_list_of_tied_choices ] ;
            global_true_or_false_continuing_subset_includes_choice[ actual_choice ] = global_true ;
            if ( global_logging_info == global_true ) { log_out << "[one of the tied choices with the largest pairwise opposition count is choice " << actual_choice << "]" << std::endl ; } ;
        }
        if ( global_logging_info == global_true ) { log_out << "[there are " << global_count_of_choices_at_pairwise_max_opposition_or_min_support << " choices that have the same largest pairwise opposition count, and the pairwise support count will be used to resolve this tie]" << std::endl ; } ;
        elim_find_smallest_pairwise_support( ) ;
        if ( global_count_of_choices_at_pairwise_max_opposition_or_min_support < global_count_of_continuing_choices )
        {
            for ( pointer_to_list_of_tied_choices = 1 ; pointer_to_list_of_tied_choices <= global_count_of_choices_at_pairwise_max_opposition_or_min_support ; pointer_to_list_of_tied_choices ++ )
            {
                actual_choice = global_list_of_choices_having_pairwise_opposition_or_support[ pointer_to_list_of_tied_choices ] ;
                if ( global_logging_info == global_true ) { log_out << "[IPE, one of the tied choices to eliminate is choice " << actual_choice << "]" << std::endl ; } ;
                global_choice_to_eliminate = actual_choice ;
                elim_choice_to_eliminate( ) ;
            }
            continue ;
        }


// -----------------------------------------------
//  The tie cannot be resolved, so list the
//  tied choices in the log file without trying to
//  further resolve this tie.

        put_next_result_info_number( global_elimination_result_type ) ;
        put_next_result_info_number( global_voteinfo_code_for_tie ) ;
        for ( pointer_to_list_of_tied_choices = 1 ; pointer_to_list_of_tied_choices <= global_count_of_choices_at_pairwise_max_opposition_or_min_support ; pointer_to_list_of_tied_choices ++ )
        {
            actual_choice = global_list_of_choices_having_pairwise_opposition_or_support[ pointer_to_list_of_tied_choices ] ;
            if ( global_logging_info == global_true ) { log_out << "[one of the tied choices is choice " << actual_choice << "]" << std::endl ; } ;
        }
        if ( global_logging_info == global_true ) { log_out << "[there are " << global_count_of_choices_at_pairwise_max_opposition_or_min_support << " choices that have the same smallest pairwise support count]" << std::endl ; } ;
        break ;


// -----------------------------------------------
//  Repeat the loop that handles each round of
//  elimination.

    }


// -----------------------------------------------
//  Log the result.

    if ( global_logging_info == global_true ) { log_out << "\n[IPE ch " << global_full_choice_count << " bal " << global_current_total_vote_count << "]" << std::endl ; } ;


// -----------------------------------------------
//  End of function method_instant_pairwise_elimination.

    return ;

}


// -----------------------------------------------
// -----------------------------------------------
//  Execution starts here.
//  Do initialization, then do the processing.

int main() {

    int winner_ipe = 0 ;


// -----------------------------------------------
//  Initialization.

    do_initialization( ) ;


// -----------------------------------------------
//  Read input data from standard input (which
//  typically is a file).

    read_data( ) ;


// -----------------------------------------------
//  Check for errors in the vote-info number list,
//  and get some needed values such as the number
//  of questions in each case, the number of
//  choices in each question, and requests that
//  apply to all the cases.

    check_vote_info_numbers( ) ;


// -----------------------------------------------
//  If there have not yet been any errors,
//  do the VoteFair ranking calculations.

    if ( global_possible_error_message.length() < 10 )
    {
        if ( global_logging_info == global_true ) { log_out << "\n[starting calculations]" ; } ;
        do_votefair_calculations( ) ;
    } else
    {
        if ( global_logging_info == global_true ) { log_out << "\n\n[calculations not done because input data is not valid]\n\n" << global_possible_error_message << std::endl ; } ;
    }


// -----------------------------------------------
//  If requested, find the winner according to
//  Instant Pairwise Elimination (IPE).
//
//  If anything other than VoteFair popularity
//  ranking was done, do not calculate this method
//  because the pairwise counts might not refer to
//  the un-modified ballots.

    if ( ( global_true_or_false_request_instant_pairwise_elimination == global_true ) && ( global_possible_error_message.length() < 10 ) )
    {
        if ( ( global_true_or_false_always_request_only_plurality_results == global_true ) || ( global_true_or_false_request_only_plurality_results == global_true ) || ( global_true_or_false_always_request_no_pairwise_counts == global_true ) || ( global_true_or_false_request_no_pairwise_counts == global_true ) || ( global_true_or_false_always_request_votefair_representation_rank == global_true ) || ( global_true_or_false_request_votefair_representation_rank == global_true ) || ( global_true_or_false_always_request_votefair_party_rank == global_true ) || ( global_true_or_false_request_votefair_party_rank == global_true ) )
        {
            if ( global_logging_info == global_true ) { log_out << "\n[calculating IPE method requires doing VoteFair popularity calculations without also doing any other kind of VoteFair ranking]" << std::endl ; } ;
        } else
        {
            method_instant_pairwise_elimination( ) ;
            winner_ipe = global_output_results[ global_pointer_to_output_results - 1 ] ;
        }
    }


// -----------------------------------------------
//  Write the results to standard output (which
//  typically is a file).  If there is a major
//  error, a simple error code is written.

    put_next_result_info_number( global_voteinfo_code_for_end_of_all_cases ) ;
    global_length_of_result_info_list = global_pointer_to_output_results + 1 ;
    if ( global_logging_info == global_true ) { log_out << "\n[all results, length of output list is " << global_length_of_result_info_list << "]" << std::endl ; } ;
    global_pointer_to_output_results = 0 ;
    write_results( ) ;


// -----------------------------------------------
//  End of "main" code.

    if ( global_logging_info == global_true ) { log_out << "\n[results written, all done]\n" ; } ;

}



// -----------------------------------------------
// -----------------------------------------------
//
//  End of all code.
//
// -----------------------------------------------
// -----------------------------------------------


// -----------------------------------------------
//
//  AUTHOR
//
//  Richard Fobes, www.VoteFair.org
//
//
// -----------------------------------------------
//
//  BUGS
//
//  Please report any bugs or feature requests on GitHub,
//  at the CPSolver account, in the VoteFairRanking project
//  area.  Thank you!
//
//
// -----------------------------------------------
//
//  SUPPORT
//
//  You can find documentation for this code on GitHub,
//  in the CPSolver account, in the VoteFair Ranking project
//  areas.
//
//  You can find details about VoteFair Ranking at: www.VoteFair.org
//
//
// -----------------------------------------------
//
//  ACKNOWLEDGEMENTS
//
//  Richard Fobes designed VoteFair Ranking and developed the
//  original version of this code over a period of many years.
//  Richard Fobes is the author of the books titled "The Creative
//  Problem Solver's Toolbox" and "Ending The Hidden Unfairness
//  In U.S. Elections."
//
//
// -----------------------------------------------
//
//  COPYRIGHT & LICENSE
//
//  (c) Copyright 1991 through 2022 by Richard Fobes at www.VoteFair.org.
//  You can redistribute and/or modify this VoteFairRanking software
//  under the MIT software license terms as written below.
//  (A copy of the license is included in the LICENSE file.)
//
//  Conversion of this code into another programming language
//  is also covered by the above license terms.
//
//  The mathematical algorithms of VoteFair Ranking are in the public domain.
//
//
// -----------------------------------------------
//
//  End of VoteFairRanking.cpp