215 lines
6.6 KiB
ReStructuredText
215 lines
6.6 KiB
ReStructuredText
.. 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``).
|
|
|