Included gomill framework for SGF and GTP support, and sketched out SGF game-loading code.
This commit is contained in:
parent
700a6a2f32
commit
692dc294d6
119 changed files with 27458 additions and 3 deletions
534
gomill/docs/settings.rst
Normal file
534
gomill/docs/settings.rst
Normal file
|
@ -0,0 +1,534 @@
|
|||
.. _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 <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 <competition report file>`. Leading and
|
||||
trailing whitespace is ignored.
|
||||
|
||||
|
||||
.. setting:: record_games
|
||||
|
||||
Boolean (default ``True``)
|
||||
|
||||
Write |sgf| :ref:`game records <game records>`.
|
||||
|
||||
|
||||
.. setting:: stderr_to_log
|
||||
|
||||
Boolean (default ``True``)
|
||||
|
||||
Redirect all players' standard error streams to the :ref:`event log
|
||||
<logging>`. 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 <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 <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 <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.
|
||||
|
Loading…
Add table
Add a link
Reference in a new issue