.. index:: playoffs
.. _playoff tournament:
Playoff tournaments
^^^^^^^^^^^^^^^^^^^
:setting:`competition_type` string: ``"playoff"``.
In a playoff tournament the control file explicitly describes one or more
pairings of players (:dfn:`matchups`).
Each matchup is treated independently: different matchups can use different
board sizes, handicap arrangements, and so on.
The tournament runs until :pl-setting:`number_of_games` have been played for
each matchup (indefinitely, if :pl-setting:`number_of_games` is unset).
.. contents:: Page contents
:local:
:backlinks: none
.. _sample_playoff_control_file:
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'),
]
.. _playoff_control_file_settings:
Control file settings
"""""""""""""""""""""
The following settings can be set at the top level of the control file:
All :ref:`common settings <common settings>`.
All :ref:`game settings <game settings>`, and the matchup settings
:pl-setting:`alternating` and :pl-setting:`number_of_games` described below;
these will be used for any matchups which don't explicitly override them.
.. pl-setting:: matchups
List of :pl-setting-cls:`Matchup` definitions (see :ref:`matchup
configuration`).
This defines which players will compete against each other, and the game
settings they will use.
The only required settings are :setting:`competition_type`,
:setting:`players`, and :pl-setting:`matchups`.
.. _matchup configuration:
Matchup configuration
"""""""""""""""""""""
.. pl-setting-cls:: Matchup
A :pl-setting-cls:`!Matchup` definition has the same syntax as a Python
function call: :samp:`Matchup({arguments})`.
The first two arguments should be the :ref:`player codes <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 :pl-setting:`id` and
:pl-setting:`name`) can be specified at the top level of the control file.
The :setting:`board_size` and :setting:`komi` arguments must be given for all
matchups (either explicitly or as defaults); the rest are all optional.
.. caution:: a default :setting:`komi` or :pl-setting:`alternating` setting
will be applied even to handicap games.
All :ref:`game settings <game settings>` can be used as matchup arguments, and
also the following:
.. _matchup id:
.. pl-setting:: id
Identifier
A short string (usually one to three characters) which is used to identify
the matchup. Matchup ids appear in the :ref:`game ids <game id>` (and so in
the |sgf| filenames), and are used in the :doc:`tournament results API
<tournament_results>`.
If this is left unspecified, the matchup id will be the index of the matchup
in the :pl-setting:`matchups` list (formatted as a decimal string, starting
from ``"0"``).
.. pl-setting:: name
String
A string used to describe the matchup in reports. By default, this has the
form :samp:`{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).
.. pl-setting:: 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.
.. pl-setting:: 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 :pl-setting:`!number_of_games` to ``0`` provides a way to effectively
disable a matchup in future runs, without forgetting its results.
Reporting
"""""""""
The :ref:`live display <live_display>` and :ref:`competition report
<competition report file>` 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 :term:`jigos <jigo>` 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
:setting:`move_limit`), a count will be shown for each matchup. :ref:`void
games` are not shown in these reports.
If there is more than one matchup between the same pair of players, use the
matchup :pl-setting:`name` setting to distinguish them.
Changing the control file between runs
""""""""""""""""""""""""""""""""""""""
If you change a :pl-setting-cls:`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 :pl-setting-cls:`Matchup` definition to have different players
(ie, player codes), the ringmaster will refuse to run the competition.
If you delete a :pl-setting-cls:`Matchup` definition, results from that
matchup won't be displayed during future runs, but will be included (with some
missing information) in the :action:`report` and :action:`show` output.
If you add a :pl-setting-cls:`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 :pl-setting:`number_of_games`.
If more games have been played than the new limit, they will not be forgotten.
In practice, you shouldn't delete :pl-setting-cls:`Matchup` definitions (if
you don't want any more games to be played, set :pl-setting:`number_of_games`
to ``0``).