Playoff tournaments

competition_type string: "playoff".

In a playoff tournament the control file explicitly describes one or more pairings of players (matchups).

Each matchup is treated independently: different matchups can use different board sizes, handicap arrangements, and so on.

The tournament runs until number_of_games have been played for each matchup (indefinitely, if number_of_games is unset).

Page contents

Sample control file

Here is a sample control file, illustrating how matchups are specified:

competition_type = 'playoff'

players = {
    'gnugo-l1' : Player("gnugo --mode=gtp --chinese-rules "
                        "--capture-all-dead --level=1"),

    'gnugo-l2' : Player("gnugo --mode=gtp --chinese-rules "
                        "--capture-all-dead --level=2"),
    }

board_size = 9
komi = 6

matchups = [
    Matchup('gnugo-l1', 'gnugo-l2', board_size=13,
            handicap=2, handicap_style='free', komi=0,
            scorer='players', number_of_games=5),

    Matchup('gnugo-l1', 'gnugo-l2', alternating=True,
            scorer='players', move_limit=200),

    Matchup('gnugo-l1', 'gnugo-l2',
            komi=0.5,
            scorer='internal'),
    ]

Control file settings

The following settings can be set at the top level of the control file:

All common settings.

All game settings, and the matchup settings alternating and number_of_games described below; these will be used for any matchups which don’t explicitly override them.

matchups

List of Matchup definitions (see Matchup configuration).

This defines which players will compete against each other, and the game settings they will use.

The only required settings are competition_type, players, and matchups.

Matchup configuration

A Matchup definition has the same syntax as a Python function call: Matchup(arguments).

The first two arguments should be the player codes for the two players involved in the matchup. The remaining arguments should be specified in keyword form. For example:

Matchup('gnugo-l1', 'fuego-5k', board_size=13, komi=6)

Defaults for matchup arguments (other than id and name) can be specified at the top level of the control file.

The board_size and komi arguments must be given for all matchups (either explicitly or as defaults); the rest are all optional.

Caution

a default komi or alternating setting will be applied even to handicap games.

All game settings can be used as matchup arguments, and also the following:

id

Identifier

A short string (usually one to three characters) which is used to identify the matchup. Matchup ids appear in the game ids (and so in the SGF filenames), and are used in the tournament results API.

If this is left unspecified, the matchup id will be the index of the matchup in the matchups list (formatted as a decimal string, starting from "0").

name

String

A string used to describe the matchup in reports. By default, this has the form player code vs player code; you may wish to change it if you have more than one matchup between the same pair of players (perhaps with different komi or handicap).

alternating

Boolean (default False)

If this is True, the players will swap colours in successive games. Otherwise, the player given as the first argument always takes Black.

number_of_games

Integer (default None)

The total number of games to play in the matchup. If you leave this unset, there will be no limit.

Changing number_of_games to 0 provides a way to effectively disable a matchup in future runs, without forgetting its results.

Reporting

The live display and competition report show each matchup’s results in the following form:

gnugo-l1 v gnugo-l2 (5/5 games)
board size: 9   komi: 7.5
           wins              black        white      avg cpu
gnugo-l1      2 40.00%       1 33.33%     1 50.00%      1.23
gnugo-l2      3 60.00%       1 50.00%     2 66.67%      1.39
                             2 40.00%     3 60.00%

or, if the players have not alternated colours:

gnugo-l1 v gnugo-l2 (5/5 games)
board size: 9   komi: 7.5
           wins                   avg cpu
gnugo-l1      0   0.00%   (black)    0.49
gnugo-l2      5 100.00%   (white)    0.48

Any jigos are counted as half a win for each player. If any games have been lost by forfeit, a count will be shown for each player. If any games have unknown results (because they could not be scored, or reached the move_limit), a count will be shown for each matchup. Void games are not shown in these reports.

If there is more than one matchup between the same pair of players, use the matchup name setting to distinguish them.

Changing the control file between runs

If you change a Matchup definition, the new definition will be used when describing the matchup in reports; there’ll be no record of the earlier definition, or which games were played under it.

If you change a Matchup definition to have different players (ie, player codes), the ringmaster will refuse to run the competition.

If you delete a Matchup definition, results from that matchup won’t be displayed during future runs, but will be included (with some missing information) in the report and show output.

If you add a Matchup definition, put it at the end of the list (or else explicitly specify the matchup ids).

It’s safe to increase or decrease a matchup’s number_of_games. If more games have been played than the new limit, they will not be forgotten.

In practice, you shouldn’t delete Matchup definitions (if you don’t want any more games to be played, set number_of_games to 0).