.. 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 `. All :ref:`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 ` 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 ` 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 ` (and so in the |sgf| filenames), and are used in the :doc:`tournament results API `. 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 ` and :ref:`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 :term:`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 :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``).