NAME

gopair - Perl script to generate go tournament pairings

SYNOPSIS

$ gopair [ options ] [ round_number ]

DESCRIPTION

gopair uses the Pair perl extension to find the locally best pairings according to criteria determined by some register.tde directives. A normal handicapped pairing (##HANDICAPS MAX) uses the following Pair scores:

-1   * abs(rating difference)
-1.5 * abs (wins difference)
-2   * (belong to the same club) 
-16  * (already played each other)

A non-handicapped pairing (## HANDICAPS MIN) uses these scores:

 0   * abs(rating difference)
-1.5 * abs (wins difference)
 0   * (belong to the same club) 
-16  * (already played each other)

Additionally, early round pairings are adjusted so that the 'best' opponent is artifically knocked down a few places so that the most interesting games are delayed until later rounds.

OPTIONS

With no options, gopair reads the register.tde file and all available round files (of the form 1.tde, 2.tde...). gopair then generates pairings for the next round following the last available round file. Output files are N.tde and pairs_N.txt (where N is the number following the last available round file).

The following options modify gopair default behavior:

-rr, -best

Normally, gopair uses the 'Best' pairing algorithm (as described in perldoc Algorithm::Pair::Best). Best pairing can lead to bad results when the number of players is only slightly greater than the number of rounds to be played. Specifically, it might pair early rounds such that in the final round, there is no choice but to pair people who have already played each other.

In this case, round-robin pairing is better. Use -rr, or better, add the following directive to the register.tde file:

## PAIR ROUND_ROBIN

gopair will abort if best (the default) pairing is selected and round-robin appears to be better. If you really need to use best pairing in this case, over-ride the abort by adding:

## PAIR BEST

to the register.tde file.

-nr

When pairing a handicap tournament (##HANDICAPS MAX), gopair attempts to read a ratings adjustment file of the form 'rats_N.txt'. If such a file is not found, or if it is found but it's older than its corresponding result file (N.tde where N is the previous round), gopair runs the 'rats' script to create an up-to-date ratings adjustment file. The adjusted ratings are used instead of the entry-time ratings in register.tde to pair the next round.

Generation and reading of the ratings adjustment file can be suppressed with the -nr (no ratings) option.

For non-handicapped tournaments it is better to use the:

##HANDICAPS MIN

directive in the register.tde file (which also prevents ratings adjustment) because there is no chance to accidentally forget to suppress ratings adjustments for a round.

If you wish to pair a handicapped tournament but prevent ratings adjustments, it is better to use:

## NORATS

in register.tde which is equivilent to the -nr option.

Ratings adjustment is never performed when pairing round 1.

-nu

If games are found in the round files that do not yet have a result (i.e. the result is not 'w', 'W', 'b', or 'B'), gopair prints a warning message and asks if you wish to proceed. The query can be suppressed with the -nu (no unfinished) option.

-ow

If the round that gopair is attempting to create already exists, gopair normally prints a warning and asks if you wish to proceed. The warning and query can be suppressed with the -ow (overwrite) option.

-nh

gopair normally tries to pair a handicap tournament. This is not appropriate for an 'open' tournament, for example. Handicapping can be turned of by adding a directive to the register.tde file:

## HANDICAPS MIN

or by using the -nh (no handicaps) option. The directive in the register.tde file is preferred because it reduces the chance that rounds might be paired with handicapping left on by mistake.

When handicapping is disabled, the pairing score ignores both the difference in rating and whether or not players belong to the same club. (see DESCRIPTION above). In addition, handicap stones for all games is set to -0, and komi for all games is set to either 7.5 for ING rules or 6.5 for non-ING rules.

-ne

gopair normally adjusts early round pairing to reduce the chance of pairing the most interesting matches in the first rounds. The -ne option or the:

## NOEARLY

directive suppresses this adjustment.

Early round adjustment is done by changing the cached pairing scores after an initial scoring sort. The top N-1 candidates for the top 2 * N players get 2 * the score of candidate N added to their score. This drops the first N-1 candidates to somewhere below candidate N. N is the total number of rounds minus the current round number minus 2.

The adjustment is fairly strong in round 1, relatively mild in the third to the last round, and there is no adjustment for the last two rounds.

-bye id

Forces player id to be the BYE player for this round. If id is not a valid AGA ID, gopair aborts with an error. Using -bye when there are an even number of players to pair has no effect (see -drop). Only one -bye option is accepted, and if provided, it over-rides BYE players in the register.tde file.

-drop id

Force player id to be the DROPped for this round. If id is not a valid AGA ID, gopair aborts with an error. Any number of -drops may be used.

N (where N is a round number)

gopair attempts to pair round N. If round N already exists, a warning is issued and gopair asks if you wish to proceed (see the -ow option above). If any round less than N does not exists, gopair aborts with an error.

BYEs

BYEs are assigned when there are an odd number of players to pair (after all DROPped players have been removed). If any players are assigned as BYE players in the register.tde file, those players are the entire pool of BYE candidates. Otherwise, the BYE candidates consist of the middle 80% of players (sorted by rating) who have already lost some games (except in round 1), and who have not already missed one or more rounds (due to DROPs or BYEs). The final BYE player for the round is chosen randomly from amongst the candidates. Re-running gopair will most likely choose a different random BYE player (unless the -bye option is used).

*.tde FILES

The *.tde files all follow the standard American Go Association (AGA) defined formats. In particular, in the register.tde file, gopair recognizes the:

## RULES ...

directive with respect to ING and non-ING komi and handicapping, the:

## NOEARLY

directive to suppress early-round adjustments, and:

## HANDICAPS MIN

directive to turn off handicapping. Also, name lines in the register.tde file that include BYE or DROP are recognized as BYE candidates or players who have DROPped out, respectively. In addition, if a name line includes one or more DROPn tokens in the comment field, that player is DROPped for round 'n'.

Example:

USA54321  Foo, A.  10k CLUB=foobar  bye  # drop2
TMP65432  Bar, B.   2k CLUB=foobar       # drop3, DROP5

Player A. Foo is a BYE candidate (first choice to receive BYEs if there are an odd number of players), and he will NOT be paired in round 2 (regardless of BYEs). Player B. Bar will not be paired in rounds 3 or 5.

SEE ALSO

o tdfind(1) - prepare register.tde for an AGA Go tournament

o rats(1) - calculate new ratings from game results

o around(1) - old Accelerat pairing script (use gopair instead)

o aradjust(1) - adjust pairings and enter results for a round

o tscore(1) - score a tournament

o send2AGA(1) - prepare tournament result for sending to AGA

o Games::Go::AGATourn(3) - perl module provides AGA file support

o Algorithm::Pair::Best(3) - generalized pairing algorithm

AUTHOR

Reid Augustin, <reid@netchip.com>

COPYRIGHT AND LICENSE

Copyright (C) 1995, 2004, 2005 by Reid Augustin

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.

cpanm Games::Go::Erf

perl -MCPAN -e shell
install Games::Go::Erf