1. Overview
-----------

The program Schweizer.exe makes pairings for swiss tournaments. It uses an
optimization algorithm. It does NOT follow the official FIDE pairing
rules, but it uses criteria from these rules to make the pairings.

Usage: Call it from the command line

    Schweizer.exe <input PGN file name> <output PGN file name>

File names that contain spaces, must be put in double qoutation marks.

The program reads the participants names and the results from the rounds
already played from the input PGN file.

It writes PGN file with unterminated games [Result "*"] with the pairings.

Games like the following are allowed in the input file and are written to the
output file, when someone recieved a BYE. These are the only games with a
result different from "*" in the output file.
    [White "Someone"]
    [Black "BYE"]
    [Round "1"]
    [Result "1-0"]
    1-0

"BYE" is a reserved name, that must not be used as a name for a real
participant.


2. controlling the program
--------------------------

The only command line parameters the program needs are the names of the input
PGN file and the output PGN file.  In tournaments where some rounds have
already been played, it is sometimes sufficient, to use the PGN file with the
result from these rounds as input file.

To manage participants (especially for the first round) and to get some
control over the optimization process, the %-escape mechanism from the PGN
specification is used. A '%' character at the beginning of a line in the input
PGN file allows to insert some commands.


2.1 managing participants
-------------------------

2.1.1 inserting participants
----------------------------

Every participant, that appears in the input file, is known to the pairing
program and will get an opponent. This is even true for unterminated games.

So it is possible to put games like the following in the input file to
insert the participants for the first round.
    [White "new participant 1"]
    [WhiteElo "1234"]
    [Black "new participant 2"]
    [BlackElo "2345"]
    [Result "*"]
    *

A better way to tell the program, who will play, is the new-command. The
first form is for participants with an ELO number, the second for participants
without one.
	%new "new participant 1" "1234"
	%new "new participant 1"

Late entries are possible, after some rounds already have been played.



2.1.2 replacing participants
----------------------------

In tournaments between computer chess engines one might want to replace
one engine version by another. This is done by
	%rename "old name" "new name"

After that "old name" and "new name" are considered synonym. "new name"
will be written to the output file.

"new name" must not appear before the %rename command in the input file.
After the %rename command both names are allowed (in different rounds).

The %rename command is allowed even if names are not known to the program.
In this case the command
	%rename "old name" "new name"
works like there is a line
	%new "old name"
before it.


2.1.3 removing participants
---------------------------

After the command
	%remove "name"
the participant "name" no longer plays in the tournament. The score, other
players got from games against him, are still considered in the optimization
process.


2.1.4 returning participants
----------------------------

Participants that have been removed from the tournament with the %remove-
command, can return some rounds later with
    %comeback "name"

The %comeback-command is allowed even if the name of the participant is not
known to the program. In this case
	%comeback "name"
works like
	%new "name"


2.2 Parameters for optimization
-------------------------------

You can change some weights for the optimization process by placing special
commands in the input PGN file. In the following list, each such command
is listed with its default value.

%PairRepeated "99999.9"
Evaluation for two Players, who already played against each other. This is
a case that must be avoided, so the value has to be very high.

%Colour "8.0"
Evaluation for the difference of games with white and black.

%Colour2 "2.0"
Evaluation for two consecutive games with the same color.

%Colour3 "40.0"
Evaluation for three consecutive games with the same color.

%Score "25.0"
Evaluation for the score difference of two opponents.

%ScoreBYE "200.0"
Evaluation for the score of the player receiving a BYE.

%Float1 "20.0"
The opponent in the round before the last round had a higher/lower score.

%Float2 "60.0"
The opponent in the last round had a higher/lower score.

%Float3 "150.0"
The opponent in the last two rounds both had a higher/lower score.

%Rank "1.0"
Evaluation of the players rank (based on Buchholz and ELO number). All
participants in a score basket should have a similar rank distance.

%ColourRank "0.01"
The better player gets an advantage when chosing colours.


2.3 Debugging
-------------

With a line
	%Debug "1"
in the input file, additional comments with the evaluation of the pairings
are written to the output file.

With
	%Seed "<Zahl>"
you can change the starting value for the random number generator that is used
for the optimization process. Normally the results should be independent from
the seed value, at least very similar, but differences are possible. Every
value different from 0, makes reproducable results, so when you run the
program again, you get exactly the same result.


3. technical details
--------------------

When the program has run without an error, it will terminate with exit code 0.
When an error has occured, a message is written to stderr and the program
exits with code 1.
