anna/pygo
1
0
Fork 0
Code Pull requests Releases Activity Actions

Included gomill framework for SGF and GTP support, and sketched out SGF game-loading code.

Browse source
This commit is contained in:
Anna Rose Wiggins 2012-04-21 04:27:05 -04:00
parent 700a6a2f32
commit 692dc294d6
119 changed files with 27458 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

534
gomill/docs/settings.rst Normal file
View 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.