19. The Go Text Protocol
19.1 The Go Text Protocol
GNU Go 3.0 introduced a new interface, the Go Text Protocol, abbreviated
GTP. The intention was to make an interface that is better suited for
machine-machine communication than the ascii interface and simpler, more
powerful, and more flexible than the Go Modem Protocol.
There are two versions of the protocol. Version 1 was used with GNU Go
3.0 and 3.2. GNU Go 3.4 and later versions use protocol version 2. The
specification of GTP version 2 is available at
http://www.lysator.liu.se/~gunnar/gtp/. GNU Go 3.4 is the
reference implementation for GTP version 2, but all but the most common
commands are to be regarded as private extensions of the protocol.
The GTP has a variety of applications. For GNU Go the first use was in
regression testing (see section 20. Regression testing), followed by communication with
the NNGS go server and for automated test games against itself and other
programs. Now there are also many graphical user interfaces available
supporting GTP, as well as bridges to other Go servers than NNGS.
19.2 Running GNU Go in GTP mode
To start GNU Go in GTP mode, simply invoke it with the option
`--mode gtp'. You will not get a prompt or any other output to
start with but GNU Go is silently waiting for GTP commands.
A sample GTP session may look as follows:
| virihaure 462% ./gnugo --mode gtp
1 boardsize 7
=1
2 clear_board
=2
3 play black D5
=3
4 genmove white
=4 C3
5 play black C3
?5 illegal move
6 play black E3
=6
7 showboard
=7
A B C D E F G
7 . . . . . . . 7
6 . . . . . . . 6
5 . . + X + . . 5
4 . . . + . . . 4
3 . . O . X . . 3
2 . . . . . . . 2 WHITE (O) has captured 0 stones
1 . . . . . . . 1 BLACK (X) has captured 0 stones
A B C D E F G
8 quit
=8
|
Commands are given on a single line, starting by an optional identity
number, followed by the command name and its arguments.
If the command is successful, the response starts by an equals sign
(`='), followed by the identity number of the command (if any) and
then the result. In this example all results were empty strings except
for command 4 where the answer was the white move at C3, and command 7
where the result was a diagram of the current board position. The
response ends by two consecutive newlines.
Failing commands are signified by a question mark (`?') instead of
an equals sign, as in the response to command 5.
The detailed specification of the protocol can be found at
http://www.lysator.liu.se/~gunnar/gtp/. The available commands in
GNU Go may always be listed using the command list_commands
.
They are also documented in See section 19.6 GTP command reference.
19.3 GTP applications
GTP is an asymmetric protocol involving two parties which we call
controller and engine. The controller sends all commands and the engine
only responds to these commands. GNU Go implements the engine end of the
protocol.
With the source code of GNU Go is also distributed a number of
applications implementing the controller end. Among the most interesting of
these are:
- `regression/regress.awk'
Script to run regressions. The script sends GTP commands to set up and
evaluate positions to the engine and then analyzes the responses from
the engine. More information about GTP based regression testing can be
found in the regression chapter (see section 20. Regression testing).
- `regression/regress.pl'
Perl script to run regressions, giving output which together with the
CGI script `regression/regress.plx' generates HTML views of the
regressions.
- `regression/regress.pike'
Pike script to run regressions. More feature-rich and powerful than
`regress.awk'.
- `regression/view.pike'
Pike script to examine a single regression testcase through a graphical
board. This gives an easy way to inspect many of the GNU Go internals.
- `interface/gtp_examples/twogtp'
Perl script to play two engines against each other. The script
essentially sets up both engines with desired boardsize, handicap, and
komi, then relays moves back and forth between the engines.
- `interface/gtp_examples/twogtp-a'
An alternative Perl implementation of twogtp.
- `interface/gtp_examples/twogtp.py'
Implementation of twogtp in Python. Has more features than the Perl
variants.
- `interface/gtp_examples/twogtp.pike'
Implementation of twogtp in Pike. Has even more features than the Python
variant.
- `interface/gtp_examples/2ptkgo.pl'
Variation of twogtp which includes a graphical board.
More GTP applications, including bridges to go servers and graphical
user interfaces, are listed at
http://www.lysator.liu.se/~gunnar/gtp/.
19.4 The Metamachine
An interesting application of the GTP is the concept of
using GNU Go as an "Oracle" that can be consulted by another
process. This could be another computer program that asks GNU Go
to generate future board positions, then evaluate them.
David Doshay at the University of California at Santa Cruz has done
interesting experiments with a parallel engine, known as SlugGo, that is based
on GNU Go. These are described in
http://lists.gnu.org/archive/html/gnugo-devel/2004-08/msg00060.html.
The "Metamachine" experiment is a more modest approach using the GTP to
communicate with a GNU Go process that is used as an oracle. The following
scheme is used.
- The GNU Go "oracle" is asked to generate its top moves using
the GTP
top_moves
commands.
- Both moves are tried and
estimate_score
is called
from the resulting board position.
- The higher scoring position is selected as the engine's move.
This scheme does not produce a stronger engine, but it is
suggestive, and the SlugGo experiment seems to show that a
more elaborate scheme along the same lines could produce
a stronger engine.
Two implementations are distributed with GNU Go. Both make use of
fork
and pipe
system calls, so they require a Unix-like
environment. The Metamachine has been tested under GNU/Linux.
Important: If the Metamachine terminates normally, the GNU Go
process will be killed. However there is a danger that
something will go wrong. When you are finished running the
Metamachine, it is a good idea to run ps -A|grep gnugo
or ps -aux|grep gnugo
to make sure there are no
unterminated processes. (If there are, just kill them.)
19.4.1 The Standalone Metamachine
In `interface/gtp_examples/metamachine.c' is a standalone
implementation of the Metamachine. Compile it with
cc -o metamachine metamachine.c
and run it. It forks
a gnugo
process with which it communicates through the
GTP, to use as an oracle.
The following scheme is followed:
| stdin pipe a
GTP client ----> Metamachine -----> GNU Go
<---- <-----
stdout pipe b
|
Most commands issued by the client are passed along
verbatim to GNU Go by the Metamachine. The exception
is gg_genmove, which is intercepted then processed differently,
as described above. The client is unaware of this, and only
knows that it issued a gg_genmove command and received a reply.
Thus to the the Metamachine appears as an ordinary GTP engine.
Usage: no arguments gives normal GTP behavior.
metamachine --debug
sends diagnostics to stderr.
19.4.2 GNU Go as a Metamachine
Alternatively, you may compile GNU Go with the configure option
`--enable-metamachine'. This causes the file
oracle.c
to be compiled, which contains the Metamachine
code. This has no effect on the engine unless you run GNU
Go with the runtime option `--metamachine'. Thus
you must use both the configure and the runtime option
to get the Metamachine.
This method is better than the standalone program since
you have access to GNU Go's facilities. For example, you
can run the Metamachine with CGoban or in Ascii mode this
way.
You can get traces by adding the command line
`-d0x1000000'. In debugging the Metamachine, a danger is
that any small oversight in designing the program can cause the
forked process and the controller to hang, each one waiting for
a response from the other. If this seems to happen it is useful
to know that you can attach gdb
to a running process and
find out what it is doing.
19.5 Adding new GTP commands
The implementation of GTP in GNU Go is distributed over three files,
`interface/gtp.h', `interface/gtp.c', and
`interface/play_gtp.c'. The first two implement a small library of
helper functions which can be used also by other programs. In the
interest of promoting the GTP they are licensed with minimal
restrictions (see section A.3 The Go Text Protocol License). The actual GTP commands are
implemented in `play_gtp.c', which has knowledge about the engine
internals.
To see how a simple but fairly typical command is implemented we look at
gtp_countlib()
(a GNU Go private extension command):
| static int
gtp_countlib(char *s)
{
int i, j;
if (!gtp_decode_coord(s, &i, &j))
return gtp_failure("invalid coordinate");
if (BOARD(i, j) == EMPTY)
return gtp_failure("vertex must not be empty");
return gtp_success("%d", countlib(POS(i, j)));
}
|
The arguments to the command are passed in the string s
. In this
case we expect a vertex as argument and thus try to read it with
gtp_decode_coord()
from `gtp.c'.
A correctly formatted response should start with either `=' or
`?', followed by the identity number (if one was sent), the actual
result, and finally two consecutive newlines. It is important to get
this formatting correct since the controller in the other end relies on
it. Naturally the result itself cannot contain two consecutive newlines
but it may be split over several lines by single newlines.
The easiest way to generate a correctly formatted response is with one
of the functions gtp_failure()
and gtp_success()
, assuming
that their formatted output does not end with a newline.
Sometimes the output is too complex for use with gtp_success, e.g. if
we want to print vertices, which gtp_success() does not
support. Then we have to fall back to the construction in e.g.
gtp_genmove()
:
| static int
gtp_genmove(char *s)
{
[...]
gtp_start_response(GTP_SUCCESS);
gtp_print_vertex(i, j);
return gtp_finish_response();
}
|
Here gtp_start_response()
writes the equal sign and the identity
number while gtp_finish_response()
adds the final two newlines.
The next example is from gtp_list_commands()
:
| static int
gtp_list_commands(char *s)
{
int k;
UNUSED(s);
gtp_start_response(GTP_SUCCESS);
for (k = 0; commands[k].name != NULL; k++)
gtp_printf("%s\n", commands[k].name);
gtp_printf("\n");
return GTP_OK;
}
|
As we have said, the response should be finished with two newlines.
Here we have to finish up the response ourselves since we already have
one newline in place from the last command printed in the loop.
In order to add a new GTP command to GNU Go, the following pieces of
code need to be inserted in `play_gtp.c':
- A function declaration using the
DECLARE
macro in the list
starting at line 68.
- An entry in the
commands[]
array starting at line 200.
- An implementation of the function handling the command.
Useful helper functions in `gtp.c'/`gtp.h' are:
gtp_printf()
for basic formatted printing.
gtp_mprintf()
for printing with special format codes for
vertices and colors.
gtp_success()
and gtp_failure()
for simple responses.
gtp_start_response()
and gtp_end_response()
for more
complex responses.
gtp_print_vertex()
and gtp_print_vertices()
for
printing one or multiple vertices.
gtp_decode_color()
to read in a color from the command arguments.
gtp_decode_coord()
to read in a vertex from the command arguments.
gtp_decode_move()
to read in a move, i.e. color plus
vertex, from the command arguments.
19.6 GTP command reference
This section lists the GTP commands implemented in GNU Go along with
some information about each command. Each entry in the list has the
following fields:
- Function: What this command does.
- Arguments: What other information, if any, this command requires.
Typical values include none or vertex or integer (there
are others).
- Fails: Circumstances which cause this command to fail.
- Returns: What is displayed after the = and before the two
newlines. Typical values include nothing or a move coordinate
or some status string (there are others).
- Status: How this command relates to the standard GTP version 2
commands. If nothing else is specified it is a GNU Go private extension.
Without further ado, here is the big list (in no particular order):
- quit: Quit
@verbatim
Arguments: none
Fails: never
Returns: nothing
Status: GTP version 2 standard command.
- protocol_version: Report protocol version.
@verbatim
Arguments: none
Fails: never
Returns: protocol version number
Status: GTP version 2 standard command.
- name: Report the name of the program.
@verbatim
Arguments: none
Fails: never
Returns: program name
Status: GTP version 2 standard command.
- version: Report the version number of the program.
@verbatim
Arguments: none
Fails: never
Returns: version number
Status: GTP version 2 standard command.
- boardsize: Set the board size to NxN and clear the board.
@verbatim
Arguments: integer
Fails: board size outside engine's limits
Returns: nothing
Status: GTP version 2 standard command.
- query_boardsize: Find the current boardsize
@verbatim
Arguments: none
Fails: never
Returns: board_size
- clear_board: Clear the board.
@verbatim
Arguments: none
Fails: never
Returns: nothing
Status: GTP version 2 standard command.
- orientation: Set the orienation to N and clear the board
@verbatim
Arguments: integer
Fails: illegal orientation
Returns: nothing
- query_orientation: Find the current orientation
@verbatim
Arguments: none
Fails: never
Returns: orientation
- komi: Set the komi.
@verbatim
Arguments: float
Fails: incorrect argument
Returns: nothing
Status: GTP version 2 standard command.
- get_komi: Get the komi
@verbatim
Arguments: none
Fails: never
Returns: Komi
- black: Play a black stone at the given vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex, illegal move
Returns: nothing
Status: Obsolete GTP version 1 command.
- playwhite: Play a white stone at the given vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex, illegal move
Returns: nothing
Status: Obsolete GTP version 1 command.
- play: Play a stone of the given color at the given vertex.
@verbatim
Arguments: color, vertex
Fails: invalid vertex, illegal move
Returns: nothing
Status: GTP version 2 standard command.
- fixed_handicap: Set up fixed placement handicap stones.
@verbatim
Arguments: number of handicap stones
Fails: invalid number of stones for the current boardsize
Returns: list of vertices with handicap stones
Status: GTP version 2 standard command.
- place_free_handicap: Choose free placement handicap stones and put them on the board.
@verbatim
Arguments: number of handicap stones
Fails: invalid number of stones
Returns: list of vertices with handicap stones
Status: GTP version 2 standard command.
- set_free_handicap: Put free placement handicap stones on the board.
@verbatim
Arguments: list of vertices with handicap stones
Fails: board not empty, bad list of vertices
Returns: nothing
Status: GTP version 2 standard command.
- get_handicap: Get the handicap
@verbatim
Arguments: none
Fails: never
Returns: handicap
- loadsgf: Load an sgf file, possibly up to a move number or the first occurence of a move.
@verbatim
Arguments: filename + move number, vertex, or nothing
Fails: missing filename or failure to open or parse file
Returns: color to play
Status: GTP version 2 standard command.
- color: Return the color at a vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex
Returns: "black", "white", or "empty"
- list_stones: List vertices with either black or white stones.
@verbatim
Arguments: color
Fails: invalid color
Returns: list of vertices
- countlib: Count number of liberties for the string at a vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: Number of liberties.
- findlib: Return the positions of the liberties for the string at a vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: Sorted space separated list of vertices.
- accuratelib: Determine which liberties a stone of given color will get if played at given vertex.
@verbatim
Arguments: move (color + vertex)
Fails: invalid color, invalid vertex, occupied vertex
Returns: Sorted space separated list of liberties
- accurate_approxlib: Determine which liberties a stone of given color will get if played at given vertex.
@verbatim
Arguments: move (color + vertex)
Fails: invalid color, invalid vertex, occupied vertex
Returns: Sorted space separated list of liberties
Supposedly identical in behavior to the above function and
can be retired when this is confirmed.
- is_legal: Tell whether a move is legal.
@verbatim
Arguments: move
Fails: invalid move
Returns: 1 if the move is legal, 0 if it is not.
- all_legal: List all legal moves for either color.
@verbatim
Arguments: color
Fails: invalid color
Returns: Sorted space separated list of vertices.
- captures: List the number of captures taken by either color.
@verbatim
Arguments: color
Fails: invalid color
Returns: Number of captures.
- last_move: Return the last move.
@verbatim
Arguments: none
Fails: no previous move known
Returns: Color and vertex of last move.
- move_history: Print the move history in reverse order
@verbatim
Arguments: none
Fails: never
Returns: List of moves played in reverse order in format:
color move (one move per line)
- trymove: Play a stone of the given color at the given vertex.
@verbatim
Arguments: move (color + vertex)
Fails: invalid color, invalid vertex, illegal move
Returns: nothing
- tryko: Play a stone of the given color at the given vertex, allowing illegal ko capture.
@verbatim
Arguments: move (color + vertex)
Fails: invalid color, invalid vertex, illegal move
Returns: nothing
- popgo: Undo a trymove or tryko.
@verbatim
Arguments: none
Fails: stack empty
Returns: nothing
- clear_cache: clear the caches.
@verbatim
Arguments: none.
Fails: never.
Returns: nothing.
- attack: Try to attack a string.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: attack code followed by attack point if attack code nonzero.
- attack_either: Try to attack either of two strings
@verbatim
Arguments: two vertices
Fails: invalid vertex, empty vertex
Returns: attack code against the strings. Guarantees there
exists a move which will attack one of the two
with attack_code, but does not return the move.
- defend: Try to defend a string.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: defense code followed by defense point if defense code nonzero.
- does_attack: Examine whether a specific move attacks a string tactically.
@verbatim
Arguments: vertex (move), vertex (dragon)
Fails: invalid vertex, empty vertex
Returns: attack code
- does_defend: Examine whether a specific move defends a string tactically.
@verbatim
Arguments: vertex (move), vertex (dragon)
Fails: invalid vertex, empty vertex
Returns: attack code
- ladder_attack: Try to attack a string strictly in a ladder.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: attack code followed by attack point if attack code nonzero.
- increase_depths: Increase depth values by one.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- decrease_depths: Decrease depth values by one.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- owl_attack: Try to attack a dragon.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: attack code followed by attack point if attack code nonzero.
- owl_defend: Try to defend a dragon.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: defense code followed by defense point if defense code nonzero.
- owl_threaten_attack: Try to attack a dragon in 2 moves.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: attack code followed by the two attack points if
attack code nonzero.
- owl_threaten_defense: Try to defend a dragon with 2 moves.
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: defense code followed by the 2 defense points if
defense code nonzero.
- owl_does_attack: Examine whether a specific move attacks a dragon.
@verbatim
Arguments: vertex (move), vertex (dragon)
Fails: invalid vertex, empty vertex
Returns: attack code
- owl_does_defend: Examine whether a specific move defends a dragon.
@verbatim
Arguments: vertex (move), vertex (dragon)
Fails: invalid vertex, empty vertex
Returns: defense code
- owl_connection_defends: Examine whether a connection defends involved dragons.
@verbatim
Arguments: vertex (move), vertex (dragon1), vertex (dragon2)
Fails: invalid vertex, empty vertex
Returns: defense code
- defend_both: Try to defend both of two strings
@verbatim
Arguments: two vertices
Fails: invalid vertex, empty vertex
Returns: defend code for the strings. Guarantees there
exists a move which will defend both of the two
with defend_code, but does not return the move.
- owl_substantial: Determine whether capturing a string gives a living dragon
@verbatim
Arguments: vertex
Fails: invalid vertex, empty vertex
Returns: 1 if dragon can live, 0 otherwise
- analyze_semeai: Analyze a semeai
@verbatim
Arguments: dragona, dragonb
Fails: invalid vertices, empty vertices
Returns: semeai defense result, semeai attack result, semeai move
- analyze_semeai_after_move: Analyze a semeai after a move have been made.
@verbatim
Arguments: color, vertex, dragona, dragonb
Fails: invalid vertices
Returns: semeai defense result, semeai attack result, semeai move
- tactical_analyze_semeai: Analyze a semeai, not using owl
@verbatim
Arguments: dragona, dragonb
Fails: invalid vertices, empty vertices
Returns: status of dragona, dragonb assuming dragona moves first
- connect: Try to connect two strings.
@verbatim
Arguments: vertex, vertex
Fails: invalid vertex, empty vertex, vertices of different colors
Returns: connect result followed by connect point if successful.
- disconnect: Try to disconnect two strings.
@verbatim
Arguments: vertex, vertex
Fails: invalid vertex, empty vertex, vertices of different colors
Returns: disconnect result followed by disconnect point if successful.
- break_in: Try to break from string into area.
@verbatim
Arguments: vertex, vertices
Fails: invalid vertex, empty vertex.
Returns: result followed by break in point if successful.
- block_off: Try to block string from area.
@verbatim
Arguments: vertex, vertices
Fails: invalid vertex, empty vertex.
Returns: result followed by block point if successful.
- eval_eye: Evaluate an eye space
@verbatim
Arguments: vertex
Fails: invalid vertex
Returns: Minimum and maximum number of eyes. If these differ an
attack and a defense point are additionally returned.
If the vertex is not an eye space or not of unique color,
a single -1 is returned.
- dragon_status: Determine status of a dragon.
@verbatim
Arguments: optional vertex
Fails: invalid vertex, empty vertex
Returns: status ("alive", "critical", "dead", or "unknown"),
attack point, defense point. Points of attack and
defense are only given if the status is critical.
If no vertex is given, the status is listed for all
dragons, one per row in the format "A4: alive".
FIXME: Should be able to distinguish between life in seki
and independent life. Should also be able to identify ko.
- same_dragon: Determine whether two stones belong to the same dragon.
@verbatim
Arguments: vertex, vertex
Fails: invalid vertex, empty vertex
Returns: 1 if the vertices belong to the same dragon, 0 otherwise
- unconditional_status: Determine the unconditional status of a vertex.
@verbatim
Arguments: vertex
Fails: invalid vertex
Returns: unconditional status ("undecided", "alive", "dead",
"white_territory", "black_territory"). Occupied vertices can
be undecided, alive, or dead. Empty vertices can be
undecided, white territory, or black territory.
- combination_attack: Find a move by color capturing something through a combination attack.
@verbatim
Arguments: color
Fails: invalid color
Returns: Recommended move, PASS if no move found
- combination_defend: If color can capture something through a combination attack, list moves by the opponent of color
to defend against this attack.
@verbatim
Arguments: color
Fails: invalid color
Returns: Recommended moves, PASS if no combination attack found.
- aa_confirm_safety: Run atari_atari_confirm_safety().
@verbatim
Arguments: move, optional int
Fails: invalid move
Returns: success code, if failure also defending move
- genmove_black: Generate and play the supposedly best black move.
@verbatim
Arguments: none
Fails: never
Returns: a move coordinate or "PASS"
Status: Obsolete GTP version 1 command.
- genmove_white: Generate and play the supposedly best white move.
@verbatim
Arguments: none
Fails: never
Returns: a move coordinate or "PASS"
Status: Obsolete GTP version 1 command.
- genmove: Generate and play the supposedly best move for either color.
@verbatim
Arguments: color to move
Fails: invalid color
Returns: a move coordinate or "PASS" (or "resign" if resignation_allowed)
Status: GTP version 2 standard command.
- reg_genmove: Generate the supposedly best move for either color.
@verbatim
Arguments: color to move
Fails: invalid color
Returns: a move coordinate (or "PASS")
Status: GTP version 2 standard command.
- gg_genmove: Generate the supposedly best move for either color.
@verbatim
Arguments: color to move, optionally a random seed
Fails: invalid color
Returns: a move coordinate (or "PASS")
This differs from reg_genmove in the optional random seed.
- restricted_genmove: Generate the supposedly best move for either color from a choice of allowed vertices.
@verbatim
Arguments: color to move, allowed vertices
Fails: invalid color, invalid vertex, no vertex listed
Returns: a move coordinate (or "PASS")
- kgs-genmove_cleanup: Generate and play the supposedly best move for either color, not passing until all dead opponent stones have been removed.
@verbatim
Arguments: color to move
Fails: invalid color
Returns: a move coordinate (or "PASS")
Status: KGS specific command.
A similar command, but possibly somewhat different, will likely be added
to GTP version 3 at a later time.
- level: Set the playing level.
@verbatim
Arguments: int
Fails: incorrect argument
Returns: nothing
- undo: Undo one move
@verbatim
Arguments: none
Fails: If move history is too short.
Returns: nothing
Status: GTP version 2 standard command.
- gg-undo: Undo a number of moves
@verbatim
Arguments: optional int
Fails: If move history is too short.
Returns: nothing
- time_settings: Set time allowance
@verbatim
Arguments: int main_time, int byo_yomi_time, int byo_yomi_stones
Fails: syntax error
Returns: nothing
Status: GTP version 2 standard command.
- time_left: Report remaining time
@verbatim
Arguments: color color, int time, int stones
Fails: syntax error
Returns: nothing
Status: GTP version 2 standard command.
- final_score: Compute the score of a finished game.
@verbatim
Arguments: Optional random seed
Fails: never
Returns: Score in SGF format (RE property).
Status: GTP version 2 standard command.
- final_status: Report the final status of a vertex in a finished game.
@verbatim
Arguments: Vertex, optional random seed
Fails: invalid vertex
Returns: Status in the form of one of the strings "alive", "dead",
"seki", "white_territory", "black_territory", or "dame".
- final_status_list: Report vertices with a specific final status in a finished game.
@verbatim
Arguments: Status in the form of one of the strings "alive", "dead",
"seki", "white_territory", "black_territory", or "dame".
An optional random seed can be added.
Fails: missing or invalid status string
Returns: Vertices having the specified status. These are split with
one string on each line if the vertices are nonempty (i.e.
for "alive", "dead", and "seki").
Status: GTP version 2 standard command.
However, "dame", "white_territory", and "black_territory"
are private extensions.
- estimate_score: Estimate the score
@verbatim
Arguments: None
Fails: never
Returns: upper and lower bounds for the score
- experimental_score: Estimate the score, taking into account which player moves next
@verbatim
Arguments: Color to play
Fails: Invalid color
Returns: Score.
This function generates a move for color, then adds the
value of the move generated to the value of the position.
Critical dragons are awarded to the opponent since the
value of rescuing a critical dragon is taken into account
in the value of the move generated.
- reset_life_node_counter: Reset the count of life nodes.
@verbatim
Arguments: none
Fails: never
Returns: nothing
Note: This function is obsolete and only remains for backwards
compatibility.
- get_life_node_counter: Retrieve the count of life nodes.
@verbatim
Arguments: none
Fails: never
Returns: number of life nodes
Note: This function is obsolete and only remains for backwards
compatibility.
- reset_owl_node_counter: Reset the count of owl nodes.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- get_owl_node_counter: Retrieve the count of owl nodes.
@verbatim
Arguments: none
Fails: never
Returns: number of owl nodes
- reset_reading_node_counter: Reset the count of reading nodes.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- get_reading_node_counter: Retrieve the count of reading nodes.
@verbatim
Arguments: none
Fails: never
Returns: number of reading nodes
- reset_trymove_counter: Reset the count of trymoves/trykos.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- get_trymove_counter: Retrieve the count of trymoves/trykos.
@verbatim
Arguments: none
Fails: never
Returns: number of trymoves/trykos
- reset_connection_node_counter: Reset the count of connection nodes.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- get_connection_node_counter: Retrieve the count of connection nodes.
@verbatim
Arguments: none
Fails: never
Returns: number of connection nodes
- test_eyeshape: Test an eyeshape for inconsistent evaluations
@verbatim
Arguments: Eyeshape vertices
Fails: Bad vertices
Returns: Failure reports on stderr.
- analyze_eyegraph: Compute an eyevalue and vital points for an eye graph
@verbatim
Arguments: Eyeshape encoded in string
Fails: Bad eyeshape, analysis failed
Returns: Eyevalue, vital points
- cputime: Returns elapsed CPU time in seconds.
@verbatim
Arguments: none
Fails: never
Returns: Total elapsed (user + system) CPU time in seconds.
- showboard: Write the position to stdout.
@verbatim
Arguments: none
Fails: never
Returns: nothing
Status: GTP version 2 standard command.
- dump_stack: Dump stack to stderr.
@verbatim
Arguments: none
Fails: never
Returns: nothing
- initial_influence: Return information about the initial influence function.
@verbatim
Arguments: color to move, what information
Fails: never
Returns: Influence data formatted like:
0.51 1.34 3.20 6.60 9.09 8.06 1.96 0.00 0.00
0.45 1.65 4.92 12.19 17.47 15.92 4.03 0.00 0.00
.
.
.
0.00 0.00 0.00 0.00 0.00 100.00 75.53 41.47 23.41
The available choices of information are:
white_influence (float)
black_influence (float)
white_strength (float)
black_strength (float)
white_attenuation (float)
black_attenuation (float)
white_permeability (float)
black_permeability (float)
territory_value (float)
influence_regions (int)
non_territory (int)
The encoding of influence_regions is as follows:
4 white stone
3 white territory
2 white moyo
1 white area
0 neutral
-1 black area
-2 black moyo
-3 black territory
-4 black stone
- move_influence: Return information about the influence function after a move.
@verbatim
Arguments: move, what information
Fails: never
Returns: Influence data formatted like for initial_influence.
- move_probabilities: List probabilities of each move being played (when non-zero). If no previous genmove command has been issued, the result
of this command will be meaningless.
@verbatim
Arguments: none
Fails: never
Returns: Move, probabilty pairs, one per row.
- move_uncertainty: Return the number of bits of uncertainty in the move. If no previous genmove command has been issued, the result
of this command will be meaningless.
@verbatim
Arguments: none
Fails: never
Returns: bits of uncertainty
- followup_influence: Return information about the followup influence after a move.
@verbatim
Arguments: move, what information
Fails: never
Returns: Influence data formatted like for initial_influence.
- worm_data: Return the information in the worm data structure.
@verbatim
Arguments: optional vertex
Fails: never
Returns: Worm data formatted like:
A19:
color black
size 10
effective_size 17.83
origin A19
liberties 8
liberties2 15
liberties3 10
liberties4 8
attack PASS
attack_code 0
lunch B19
defend PASS
defend_code 0
cutstone 2
cutstone2 0
genus 0
inessential 0
B19:
color white
.
.
.
inessential 0
C19:
...
If an intersection is specified, only data for this one will be returned.
- worm_stones: List the stones of a worm
@verbatim
Arguments: the location, "BLACK" or "WHITE"
Fails: if called on an empty or off-board location
Returns: list of stones
- worm_cutstone: Return the cutstone field in the worm data structure.
@verbatim
Arguments: non-empty vertex
Fails: never
Returns: cutstone
- dragon_data: Return the information in the dragon data structure.
@verbatim
Arguments: optional intersection
Fails: never
Returns: Dragon data formatted in the corresponding way to worm_data.
- dragon_stones: List the stones of a dragon
@verbatim
Arguments: the location
Fails: if called on an empty or off-board location
Returns: list of stones
- eye_data: Return the information in the eye data structure.
@verbatim
Arguments: color, vertex
Fails: never
Returns: eye data fields and values, one pair per row
- half_eye_data: Return the information in the half eye data structure.
@verbatim
Arguments: vertex
Fails: never
Returns: half eye data fields and values, one pair per row
- start_sgftrace: Start storing moves executed during reading in an sgf tree in memory.
@verbatim
Arguments: none
Fails: never
Returns: nothing
Warning: You had better know what you're doing if you try to use this
command.
- finish_sgftrace: Finish storing moves in an sgf tree and write it to file.
@verbatim
Arguments: filename
Fails: never
Returns: nothing
Warning: You had better know what you're doing if you try to use this
command.
- printsgf: Dump the current position as a static sgf file to filename, or as output if filename is missing or "-"
@verbatim
Arguments: optional filename
Fails: never
Returns: nothing if filename, otherwise the sgf
- tune_move_ordering: Tune the parameters for the move ordering in the tactical reading.
@verbatim
Arguments: MOVE_ORDERING_PARAMETERS integers
Fails: incorrect arguments
Returns: nothing
- echo: Echo the parameter
@verbatim
Arguments: string
Fails: never
Returns: nothing
- echo_err: Echo the parameter to stdout AND stderr
@verbatim
Arguments: string
Fails: never
Returns: nothing
- help: List all known commands
@verbatim
Arguments: none
Fails: never
Returns: list of known commands, one per line
Status: GTP version 2 standard command.
- known_command: Tell whether a command is known.
@verbatim
Arguments: command name
Fails: never
Returns: "true" if command exists, "false" if not
Status: GTP version 2 standard command.
- report_uncertainty: Turn uncertainty reports from owl_attack and owl_defend on or off.
@verbatim
Arguments: "on" or "off"
Fails: invalid argument
Returns: nothing
- get_random_seed: Get the random seed
@verbatim
Arguments: none
Fails: never
Returns: random seed
- set_random_seed: Set the random seed
@verbatim
Arguments: integer
Fails: invalid data
Returns: nothing
- is_surrounded: Determine if a dragon is surrounded
@verbatim
Arguments: vertex (dragon)
Fails: invalid vertex, empty vertex
Returns: 1 if surrounded, 2 if weakly surrounded, 0 if not
- does_surround: Determine if a move surrounds a dragon
@verbatim
Arguments: vertex (move), vertex (dragon)
Fails: invalid vertex, empty (dragon, nonempty (move)
Returns: 1 if (move) surrounds (dragon)
- surround_map: Report the surround map for dragon at a vertex
@verbatim
Arguments: vertex (dragon), vertex (mapped location)
Fails: invalid vertex, empty dragon
Returns: value of surround map at (mapped location), or -1 if
dragon not surrounded.
- set_search_diamond: limit search, and establish a search diamond
@verbatim
Arguments: pos
Fails: invalid value
Returns: nothing
- reset_search_mask: unmark the entire board for limited search
@verbatim
Arguments: none
Fails: never
Returns: nothing
- limit_search: sets the global variable limit_search
@verbatim
Arguments: value
Fails: invalid arguments
Returns: nothing
- set_search_limit: mark a vertex for limited search
@verbatim
Arguments: position
Fails: invalid arguments
Returns: nothing
- draw_search_area: Draw search area. Writes to stderr.
@verbatim
Arguments: none
Fails: never
Returns: nothing
This document was generated
by on June, 18 2005
using texi2html