.. _control file: The control file ---------------- .. contents:: Page contents :local: :backlinks: none .. _sample control file: Sample control file ^^^^^^^^^^^^^^^^^^^ Here is a sample control file for a playoff tournament:: competition_type = 'playoff' description = """ This is a sample control file. It illustrates player definitions, common settings, and game settings. """ record_games = True stderr_to_log = False players = { # GNU Go level 1 'gnugo-l1' : Player("gnugo --mode=gtp --chinese-rules " "--capture-all-dead --level=1"), # GNU Go level 2 'gnugo-l2' : Player("gnugo --mode=gtp --chinese-rules " "--capture-all-dead --level=2"), # Fuego at 5000 playouts per move 'fuego-5k' : Player("fuego --quiet", startup_gtp_commands=[ "go_param timelimit 999999", "uct_max_memory 350000000", "uct_param_search number_threads 1", "uct_param_player reuse_subtree 0", "uct_param_player ponder 0", "uct_param_player max_games 5000", ]), } board_size = 9 komi = 6 matchups = [ Matchup('gnugo-l1', 'fuego-5k', board_size=13, handicap=2, handicap_style='free', komi=0, scorer='players', number_of_games=5), Matchup('gnugo-l2', 'fuego-5k', alternating=True, scorer='players', move_limit=200), Matchup('gnugo-l1', 'gnugo-l2', komi=0.5, scorer='internal'), ] File format ^^^^^^^^^^^ The control file is a plain text configuration file. It is interpreted in the same way as a Python source file. See the :ref:`sample control file` above for an example of the syntax. .. __: http://docs.python.org/release/2.7/reference/index.html The control file is made up of a series of top-level :dfn:`settings`, in the form of assignment statements: :samp:`{setting_name} = {value}`. Each top-level setting should begin on a new line, in the leftmost column of the file. Settings which use brackets of any kind can be split over multiple lines between elements (for example, lists can be split at the commas). Comments are introduced by the ``#`` character, and continue until the end of the line. In general, the order of settings in the control file isn't significant (except for list members). But note that :setting:`competition_type` must come first. See :ref:`data types` below for the representation of values. See the `Python language reference`__ for a formal specification. The settings which are common to all competition types are listed below. Further settings are given on the page documenting each competition type. .. caution:: while the ringmaster will give error messages for unacceptable setting values, it will ignore attempts to set a nonexistent setting (this is because you're allowed to define variables of your own in the control file and use them in later setting definitions). If you wish, you can use arbitrary Python expressions in the control file; see :ref:`control file techniques` below. .. caution:: all Python code in the control file will be executed; a hostile party with write access to a control file can cause the ringmaster to execute arbitrary code. On a shared system, do not make the competition directory or the control file world-writeable. The recommended filename extension for the control file is :file:`.ctl`. .. _data types: Data types ^^^^^^^^^^ The following data types are used for values of settings: String A literal string of characters in single or double quotes, eg ``'gnugo-l1'`` or ``"free"``. Strings containing non-ASCII characters should be encoded as UTF-8 (Python unicode objects are also accepted). Strings can be broken over multiple lines by writing adjacent literals separated only by whitespace; see the :setting-cls:`Player` definitions in the example above. Backslash escapes can be used in strings, such as ``\n`` for a newline. Alternatively, three (single or double) quotes can be used for a multi-line string; see ``description`` in the example above. Identifier A (short) string made up of any combination of ASCII letters, numerals, and the punctuation characters ``- ! $ % & * + - . : ; < = > ? ^ _ ~``. Boolean A truth value, written as ``True`` or ``False``. Integer A whole number, written as a decimal literal, eg ``19`` or ``-1``. Float A floating-point number, written as a decimal literal, eg ``6`` or ``6.0`` or ``6.5``. List A sequence of values of uniform type, written with square brackets separated by commas, eg ``["max_playouts 3000", "initial_wins 5"]``. An extra comma after the last item is harmless. Dictionary An explicit map of keys of uniform type to values of uniform type, written with curly brackets, colons, and commas, eg ``{'p1' : True, 'p2' : False}``. An extra comma after the last item is harmless. .. _file and directory names: File and directory names ^^^^^^^^^^^^^^^^^^^^^^^^ When values in the control file are file or directory names, non-absolute names are interpreted relative to the :ref:`competition directory `. If a file or directory name begins with ``~``, home directory expansion is applied (see :func:`os.path.expanduser`). .. _common settings: Common settings ^^^^^^^^^^^^^^^ The following settings can appear at the top level of the control file for all competition types. .. setting:: competition_type String: ``"playoff"``, ``"allplayall"``, ``"mc_tuner"``, or ``"ce_tuner"`` Determines the type of tournament or tuning event. This must be set on the first line in the control file (not counting blank lines and comments). .. setting:: description String (default ``None``) A text description of the competition. This will be included in the :ref:`competition report file `. Leading and trailing whitespace is ignored. .. setting:: record_games Boolean (default ``True``) Write |sgf| :ref:`game records `. .. setting:: stderr_to_log Boolean (default ``True``) Redirect all players' standard error streams to the :ref:`event log `. See :ref:`standard error`. .. _player codes: .. index:: player code .. setting:: players Dictionary mapping identifiers to :setting-cls:`Player` definitions (see :ref:`player configuration`). Describes the |gtp| engines that can be used in the competition. If you wish to use the same program with different settings, each combination of settings must be given its own :setting-cls:`Player` definition. See :ref:`control file techniques` below for a compact way to define several similar Players. The dictionary keys are the :dfn:`player codes`; they are used to identify the players in reports and the |sgf| game records, and elsewhere in the control file to specify how players take part in the competition. See the pages for specific competition types for the way in which players are selected from the :setting:`!players` dictionary. It's fine to have player definitions here which aren't used in the competition. These definitions will be ignored, and no corresponding engines will be run. .. _player configuration: Player configuration ^^^^^^^^^^^^^^^^^^^^ .. setting-cls:: Player A :setting-cls:`!Player` definition has the same syntax as a Python function call: :samp:`Player({arguments})`. Apart from :setting:`command`, the arguments should be specified using keyword form (see the examples for particular arguments below). All arguments other than :setting:`command` are optional. .. tip:: For results to be meaningful, you should normally configure players to use a fixed amount of computing power, paying no attention to the amount of real time that passes, and make sure :term:`pondering` is not turned on. The arguments are: .. setting:: command String or list of strings This is the only required :setting-cls:`Player` argument. It can be specified either as the first argument, or using a keyword :samp:`command="{...}"`. It specifies the executable which will provide the player, and its command line arguments. The player subprocess is executed directly, not run via a shell. The :setting:`!command` can be either a string or a list of strings. If it is a string, it is split using rules similar to a Unix shell's (see :func:`shlex.split`). In either case, the first element is taken as the executable name and the remainder as its arguments. If the executable name does not contain a ``/``, it is searched for on the the :envvar:`!PATH`. Otherwise it is handled as described in :ref:`file and directory names `. Example:: Player("~/src/fuego-svn/fuegomain/fuego --quiet") .. setting:: cwd String (default ``None``) The working directory for the player. If this is left unset, the player's working directory will be the working directory from when the ringmaster was launched (which may not be the competition directory). Use ``cwd="."`` to specify the competition directory. .. tip:: If an engine writes debugging information to its working directory, use :setting:`cwd` to get it out of the way:: Player('mogo', cwd='~/tmp') .. setting:: environ Dictionary mapping strings to strings (default ``None``) This specifies environment variables to be set in the player process, in addition to (or overriding) those inherited from its parent. Note that there is no special handling in this case for values which happen to be file or directory names. Example:: Player('goplayer', environ={'GOPLAYER-DEBUG' : 'true'}) .. setting:: discard_stderr Boolean (default ``False``) Redirect the player's standard error stream to :file:`/dev/null`. See :ref:`standard error`. Example:: Player('mogo', discard_stderr=True) .. setting:: startup_gtp_commands List of strings, or list of lists of strings (default ``None``) |gtp| commands to send at the beginning of each game. See :ref:`playing games`. Each command can be specified either as a single string or as a list of strings (with each |gtp| argument in a single string). For example, the following are equivalent:: Player('fuego', startup_gtp_commands=[ "uct_param_player ponder 0", "uct_param_player max_games 5000"]) Player('fuego', startup_gtp_commands=[ ["uct_param_player", "ponder", "0"], ["uct_param_player", "max_games", "5000"]]) .. setting:: gtp_aliases Dictionary mapping strings to strings (default ``None``) This is a map of |gtp| command names to command names, eg:: Player('fuego', gtp_aliases={'gomill-cpu_time' : 'cputime'}) When the ringmaster would normally send :gtp:`gomill-cpu_time`, it will send :gtp:`!cputime` instead. The command names are case-sensitive. There is no mechanism for altering arguments. .. setting:: is_reliable_scorer Boolean (default ``True``) If the :setting:`scorer` setting is ``players``, the ringmaster normally asks each player that implements the :gtp:`!final_score` |gtp| command to report the game result. Setting :setting:`!is_reliable_scorer` to ``False`` for a player causes that player never to be asked. .. setting:: allow_claim Boolean (default ``False``) Permits the player to claim a win (using the |gtp| extension :gtp:`gomill-genmove_ex`). See :ref:`claiming wins`. .. _game settings: Game settings ^^^^^^^^^^^^^ The following settings describe how a particular game is to be played. They are not all used in every competition type, and may be specified in some other way than a top level control file setting; see the page documenting a particular competition type for details. .. setting:: board_size Integer The size of Go board to use for the game (eg ``19`` for a 19x19 game). The ringmaster is willing to use board sizes from 2 to 25. .. setting:: komi Float The :term:`komi` to use for the game. You can specify any floating-point value, and it will be passed on to the |gtp| engines unchanged, but normally only integer or half-integer values will be useful. Negative values are allowed. .. setting:: handicap Integer (default ``None``) The number of handicap stones to give Black at the start of the game. See also :setting:`handicap_style`. See the `GTP specification`_ for the rules about what handicap values are permitted for different board sizes (in particular, values less than 2 are never allowed). .. setting:: handicap_style String: ``"fixed"`` or ``"free"`` (default ``"fixed"``) Determines whether the handicap stones are placed on prespecified points, or chosen by the Black player. See the `GTP specification`_ for more details. This is ignored if :setting:`handicap` is unset. .. _GTP specification: http://www.lysator.liu.se/~gunnar/gtp/gtp2-spec-draft2/gtp2-spec.html#SECTION00051000000000000000 .. setting:: move_limit Integer (default ``1000``) The maximum number of moves to allow in a game. If this limit is reached, the game is stopped; see :ref:`playing games`. .. setting:: scorer String: ``"players"`` or ``"internal"`` (default ``"players"``) Determines whether the game result is determined by the engines, or by the ringmaster. See :ref:`Scoring ` and :setting:`is_reliable_scorer`. .. setting:: internal_scorer_handicap_compensation String: ``"no"``, ``"full"`` or ``"short"`` (default ``"full"``) Specifies whether White is given extra points to compensate for Black's handicap stones; see :ref:`Scoring ` for details. This setting has no effect for games which are played without handicap, and it has no effect when :setting:`scorer` is set to ``"players"``. Changing the control file between runs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Changing the control file between runs of the same competition (or after the final run) is allowed. For example, in a playoff tournament it's fine to increase a completed matchup's :pl-setting:`number_of_games` and set the competition off again. The intention is that nothing surprising should happen if you change the control file; of course if you change settings which affect player behaviour then result summaries might not be meaningful. In particular, if you change a :setting-cls:`Player` definition, the new definition will be used when describing the player in reports; there'll be no record of the earlier definition, or which games were played under it. If you change descriptive text, you can use the :action:`report` command line action to remake the report file. The page documenting each competition type has more detail on what it is safe to change. .. _control file techniques: Control file techniques ^^^^^^^^^^^^^^^^^^^^^^^ As the control file is just Python code, it's possible to use less direct methods to specify the values of settings. One convenient way to define a number of similar players is to define a function which returns a :setting-cls:`Player` object. For example, the player definitions in the sample control file could be rewritten as follows:: def gnugo(level): return Player("gnugo --mode=gtp --chinese-rules " "--capture-all-dead --level=%d" % level) def fuego(playouts_per_move, additional_commands=[]): commands = [ "go_param timelimit 999999", "uct_max_memory 350000000", "uct_param_search number_threads 1", "uct_param_player reuse_subtree 0", "uct_param_player ponder 0", "uct_param_player max_games %d" % playouts_per_move, ] return Player( "fuego --quiet", startup_gtp_commands=commands+additional_commands) players = { 'gnugo-l1' : gnugo(level=1), 'gnugo-l2' : gnugo(level=2), 'fuego-5k' : fuego(playouts_per_move=5000) } If you assign to a setting more than once, the final value is the one that counts. Settings specified above as having default ``None`` can be assigned the value ``None``, which will be equivalent to leaving them unset. Importing parts of the Python standard library (or other Python libraries that you have installed) is allowed.