[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
3.1 Getting Documentation | ||
3.2 Running GNU Go via CGoban | Running GNU Go with CGoban | |
3.3 Other Clients | ||
3.4 Ascii Interface | The Ascii Interface | |
3.5 GNU Go mode in Emacs | ||
3.6 The Go Modem Protocol and Go Text Protocol | ||
3.7 Computer Go Tournaments | Computer Tournaments | |
3.8 Smart Game Format | The Smart Game Format | |
3.9 Invoking GNU Go: Command line options | Command line options |
You can obtain a printed copy of the manual by running make
gnugo.pdf
in the ‘doc/’directory, then printing the resulting file. The
manual contains a great deal of information about the algorithms of GNU Go.
On platforms supporting info documentation, you can usually
install the manual by executing `make install' (running as
root) from the ‘doc/’ directory. This will create a file
called ‘gnugo.info’ (and a few others) and copy them into
a system directory such as ‘/usr/local/share/info’. You
may then add them to your info directory tree with the command
install-info --info-file=[path to gnugo.info] --info-dir=[path to dir]
.
The info documentation can be read conveniently from within Emacs by executing
the command Control-h i
.
Documentation in ‘doc/’ consists of a man page ‘gnugo.6’, the info files ‘gnugo.info’, ‘gnugo.info-1’, ... and the Texinfo files from which the info files are built. The Texinfo documentation contains this User's Guide and extensive information about the algorithms of GNU Go, for developers.
If you want a typeset copy of the Texinfo documentation, you can
make gnugo.dvi
, make gnugo.ps
, or make
gnugo.pdf
in the ‘doc/’ directory. (make gnugo.pdf
only
works after you have converted all .eps-files in the doc/ directory to
.pdf files, e.g. with the utility epstopdf.)
You can make an HTML version with the command makeinfo --html
gnugo.texi
. If you have texi2html
, better HTML documentation
may be obtained by make gnugo_ovr.html
in the ‘doc/’
directory.
User documentation can be obtained by running gnugo --help
or man gnugo
from any terminal, or from the Texinfo
documentation.
Documentation for developers is in the Texinfo documentation, and in comments throughout the source. Contact us at [email protected] if you are interested in helping to develop this program.
There are two different programs called CGoban, both written by William Shubert. In this documentation, CGoban means CGoban 1.x, the older program. You should get a copy with version number 1.12 or higher.
CGoban is an extremely nice way to run GNU Go. CGoban provides a beautiful graphic user interface under X Window System.
Start CGoban. When the CGoban Control panel comes up, select “Go Modem”. You will get the Go Modem Protocol Setup. Choose one (or both) of the players to be “Program,” and fill out the box with the path to ‘gnugo’. After clicking OK, you get the Game Setup window. Choose “Rules Set” to be Japanese (otherwise handicaps won't work). Set the board size and handicap if you want.
If you want to play with a komi, you should bear in mind that the GMP does not have any provision for communicating the komi. Because of this misfeature, unless you set the komi at the command line GNU Go will have to guess it. It assumes the komi is 5.5 for even games, 0.5 for handicap games. If this is not what you want, you can specify the komi at the command line with the ‘--komi’ option, in the Go Modem Protocol Setup window. You have to set the komi again in the Game Setup window, which comes up next.
Click OK and you are ready to go.
In the Go Modem Protocol Setup window, when you specify the path to GNU Go, you can give it command line options, such as ‘--quiet’ to suppress most messages. Since the Go Modem Protocol preempts standard I/O other messages are sent to stderr, even if they are not error messages. These will appear in the terminal from which you started CGoban.
In addition to CGoban (see section Running GNU Go via CGoban) there are a number of other good clients that are capable of running GNU Go. Here are the ones that we are aware of that are Free Software. This list is part of a larger list of free Go programs that is maintained at http://www.gnu.org/software/gnugo/free_go_software.html.
Even if you do not have any client program, you can play with GNU Go
using its default Ascii interface. Simply type gnugo
at the command line, and GNU Go will draw a board. Typing
help
will give a list of options. At the end of the
game, pass twice, and GNU Go will prompt you through the
counting. You and GNU Go must agree on the dead groups—you
can toggle the status of groups to be removed, and when you
are done, GNU Go will report the score.
You can save the game at any point using the save filename
command. You can reload the game from the resulting SGF file with
the command gnugo -l filename --mode ascii
. Reloading
games is not supported when playing with CGoban. However you can
use CGoban to save a file, then reload it in ascii mode.
You may play games with a time limit against GNU Go in ascii mode. For this, the Canadian time control system is used. (See http://en.wikipedia.org/wiki/Byoyomi and http://senseis.xmp.net/?CanadianByoyomi.) That is, you have a main time to be followed by byo-yomi periods. After the main time is exhausted you have a certain number of moves to be made in a certain number of seconds. (see section Invoking GNU Go: Command line options)
You can run GNU Go from Emacs. This has the advantage that you place the stones using the cursor arrow keys or with the mouse, and you can have a nice graphical display of the board within emacs.
You will need the file ‘interface/gnugo.el’. There is a version of this distributed with GNU Go but it only works with Emacs 21. Most Emacsen are Emacs 22 however. Therefore you should get the latest version of gnugo.el by Thien-Thi Nguyen, which you can find at http://www.gnuvola.org/software/j/gnugo/ or http://www.emacswiki.org/emacs/gnugo.el.
You will also need some xpm files for the graphical display. You can either use those distributed by Thien-Thi Nguyen (at the first URL above) or those distributed with GNU Go, either the file ‘interface/gnugo-xpms.el’ or (for high resolution displays) ‘interface/gnugo-big-xpms.el’.
Load the file ‘interface/gnugo.el’ and
‘interface/gnugo-xpms.el’. You may do this using the
Emacs M-x load-file
command.
When you start a game with M-x gnugo
,
you will first see an ascii board. However typing `i'
toggles a graphical board display which is very nice.
This is a pleasant way to play GNU Go. You may get
help by typing C-x m
.
The Go Modem Protocol (GMP) was developed by Bruce Wilcox with input from David Fotland, Anders Kierulf and others, according to the history in http://www.britgo.org/tech/gmp.html.
Any Go program should support this protocol since it is a standard. Since CGoban supports this protocol, the user interface for any Go program can be done entirely through CGoban. The programmer can concentrate on the real issues without worrying about drawing stones, resizing the board and other distracting issues.
GNU Go 3.0 introduced a new protocol, the Go Text Protocol (see section The Go Text Protocol) which we hope can serve the functions currently used by the GMP. The GTP is becoming increasingly adopted by other programs as a method of interprocess communication, both by computer programs and by clients. Still the GMP is widely used in tournaments.
Computer Tournaments currently use the Go Modem Protocol. The current method followed in such tournaments is to connect the serial ports of the two computers by a “null modem” cable. If you are running GNU/Linux it is convenient to use CGoban. If your program is black, set it up in the Go Modem Protocol Setup window as usual. For White, select “Device” and set the device to ‘/dev/cua0’ if your serial port is COM1 and ‘/dev/cua1’ if the port is COM2.
The Smart Game Format (SGF), is the standard format for storing Go games. GNU Go supports both reading and writing SGF files. The SGF specification (FF[4]) is at: http://www.red-bean.com/sgf/
Print a help message describing the options. This will also tell you the defaults of various parameters, most importantly the level and cache size. The default values of these parameters can be set before compiling by
configure
. If you forget the defaults you can find out using ‘--help’.
Set the board size
Set the komi
GNU Go can play with different strengths and speeds. Level 10 is the default. Decreasing the level will make GNU Go faster but less accurate in its reading.
Don't print copyright and other messages. Messages specifically requested by other command line options, such as ‘--trace’, are not supressed.
Load the named SGF file. GNU Go will generate a move for the player who is about to move. If you want to override this and generate a move for the other player you may add the option ‘--color <color>’ where <color> is
black
orwhite
.
Stop loading just before the indicated move is played. move can be either the move number or location.
Write sgf output to file
Add useful information to the sgf file. Flags can be 'd', 'v' or both (i.e. 'dv'). If 'd' is specified, dead and critical dragons are marked in the sgf file. If 'v' is specified, move valuations around the board are indicated.
Force the playing mode ('ascii', 'emacs,' 'gmp' or 'gtp'). The default is ASCII, but if no terminal is detected GMP (Go Modem Protocol) will be assumed. In practice this is usually what you want, so you may never need this option.
GNU Go will resign games if this option is enabled. This is the default unless you build the engine with the configure option ‘--disable-resignation-allowed’. Unfortunately the Go Modem Protocol has no provision for passing a resignation, so this option has no effect in GMP mode.
GNU Go will not resign games.
GNU Go will resign lost games. This is the default.
GNU Go can play Monte Carlo Go on a 9x9 board. (Not available for larger boards.) It makes quite a strong engine. Here are the command line options.
Use Monte Carlo move generation (9x9 or smaller).
Number of Monte Carlo simulations per level. Default 8000. Thus at level 10, GNU Go simulates 80,000 games in order to generate a move.
list names of builtin Monte Carlo patterns
Choose a built in Monte Carlo pattern database. The argument can be ‘mc_mogo_classic’, ‘mc_montegnu_classic’ or ‘mc_uniform’.
read Monte Carlo patterns from file
Memory in megabytes used for caching of read results. The default size is 8 unless you configure gnugo with the command
configure --enable-cache-size=size
before compiling to make size the default (see section Installation). GNU Go stores results of its reading calculations in a hash table (see section Hashing of Positions). If the hash table is filled, it is emptied and the reading continues, but some reading may have to be repeated that was done earlier, so a larger cache size will make GNU Go run faster, provided the cache is not so large that swapping occurs. Swapping may be detected on GNU/Linux machines using the programtop
. However, if you have ample memory or if performance seems to be a problem you may want to increase the size of the cache using this option.
Use Chinese rules. This means that the Chinese or Area Counting is followed. It may affect the score of the game by one point in even games, more if there is a handicap (since in Chinese Counting the handicap stones count for Black) or if either player passes during the game.
Use Japanese Rules. This is the default unless you specify ‘--enable-chinese-rules’ as a configure option.
These options cause GNU Go to play out moves that are usually left unplayed after the end of the game. Such moves lose points under Japanese rules but not Chinese rules. With ‘--play-out-aftermath’, GNU Go may play inside its territory in order to reach a position where it considers every group demonstrably alive or dead. The option ‘--capture-all-dead’ causes GNU Go to play inside its own territory to remove dead stones.
Do not allow suicide moves (playing a stone so that it ends up without liberties and is therefore immediately removed). This is the default.
Allow suicide moves, except single-stone suicide. The latter would not change the board at all and pass should be used instead.
Allow suicide moves, including single-stone suicide. This is only interesting in exceptional cases. Normally the ‘--allow-suicide’ option should be used instead.
Do not allow an immediate recapture of a ko so that the previous position is recreated. Repetition of earlier positions than that are allowed. This is default.
Allow all kinds of board repetition.
Forbid repetition of any earlier board position. This only applies to moves on the board; passing is always allowed.
Forbid repetition of any earlier board position with the same player to move. This only applies to moves on the board; passing is always allowed.
Create an SGF file containing a diagram of the board. Useful with ‘-l’ and ‘-L’ to create a diagram of the board from another sgf file. Illegal moves are indicated with the private
IL
property. This property is not used in the FF4 SGF specification, so we are free to preempt it.
Print which experimental configure options were compiled into the program (see section Other Options).
Combine with ‘-l’. The Go board can be oriented in 8 different ways, counting reflections and rotations of the position; this option selects an orientation (default 0). The parameter ‘n’ is an integer between 0 and 7.
The higher the level, the deeper GNU Go reads. Level 10 is the default. If GNU Go plays too slowly on your machine, you may want to decrease it.
This single parameter ‘--level’ is the best way of
choosing whether to play stronger or faster. It controls
a host of other parameters which may themselves be set
individually at the command line. The default values of
these parameters may be found by running gnugo --help
.
Unless you are working on the program you probably don't need the remaining options in this category. Instead, just adjust the single variable ‘--level’. The following options are of use to developers tuning the program for performance and accuracy. For completeness, here they are.
Deep reading cutoff. When reading beyond this depth (default 16) GNU Go assumes that any string which can obtain 3 liberties is alive. Thus GNU Go can read ladders to an arbitrary depth, but will miss other types of capturing moves.
Deep reading cutoff. Beyond this depth (default 12) GNU Go will no longer try backfilling moves in its reading.
Another depth controlling how deeply GNU Go looks for backfilling moves. The moves tried below
backfill2_depth
are generally more obscure and time intensive than those controlled bybackfill_depth
, so this parameter has a lower default.
Deep reading cutoff. When reading beyond this depth (default 7) GNU Go assumes that any string which can obtain 4 liberties is alive.
Deep reading cutoff. Beyond this depth (default 8) GNU Go no longer tries very hard to analyze kos.
This sets the
branch_depth
, typically a little below thedepth
. Betweenbranch_depth
anddepth
, attacks on strings with 3 liberties are considered but branching is inhibited, so fewer variations are considered. Below this depth (default 13), GNU Go still tries to attack strings with only 3 liberties, but only tries one move at each node.
Set the
break_chain_depth
. Beyond this depth, GNU Go abandons some attempts to defend groups by trying to capture part of the surrounding chain.
The reading function
atari_atari
looks for combinations beginning with a series of ataris, and culminating with some string having an unexpected change in status (e.g. alive to dead or critical). This command line optio sets the parameteraa_depth
which determines how deeply this function looks for combinations.
A superstring (see section Superstrings) is an amalgamation of tightly strings. Sometimes the best way to attack or defend a string is by attacking or defending an element of the superstring. Such tactics are tried below
superstring_depth
and this command line option allows this parameter to be set.
The preceeding options are documented with the reading code (see section Reading Basics).
If the number of variations exceeds this limit, Owl assumes the dragon can make life. Default 1000. We caution the user that increasing
owl_node_limit
does not necessarily increase the strength of the program.
If the number of variations exceeds this limit, Owl assumes the dragon can make life. Default 1000. We caution the user that increasing
owl_node_limit
does not necessarily increase the strength of the program.
Below this limit some owl reading is truncated.
Choose your color ('black' or 'white').
Choose the number of handicap stones (0–9)
For more information about the following clock options see See section Ascii Interface.
Initialize the timer.
Number of seconds per (Canadian) byo-yomi period
Number of stones per (Canadian) byo-yomi period
Replay all moves in a game for either or both colors. If used with the ‘-o’ option the game record is annotated with move values. This option requires ‘-l filename’. The color can be:
- white: replay white moves only
- black: replay black moves only
- both: replay all moves
When the move found by genmove differs from the move in the sgf file the values of both moves are reported thus:
Move 13 (white): GNU Go plays C6 (20.60) - Game move F4 (20.60)This option is useful if one wants to confirm that a change such as a speedup or other optimization has not affected the behavior of the engine. Note that when several moves have the same top value (or nearly equal) the move generated is not deterministic (though it can be made deterministic by starting with the same random seed). Thus a few deviations from the move in the sgf file are to be expected. Only if the two reported values differ should we conclude that the engine plays differently from the engine which generated the sgf file. See section Regression testing.
Test all patterns, even those smaller in value than the largest move found so far. This should never affect GNU Go's final move, and it will make it run slower. However this can be very useful when "tuning" GNU Go. It causes both the traces and the output file (‘-o’) to be more informative.
Use rxvt, xterm or Linux Console. (see section Colored Display)
Print timing information to stderr.
Use rxvt, xterm or Linux Console. (see section Colored Display)
Produce debugging output. The debug level is given in hexadecimal, using the bits defined in the following table from ‘engine/gnugo.h’. A list of these may be produced using ‘--debug-flags’. Here they are in hexadecimal:
DEBUG_INFLUENCE 0x0001 DEBUG_EYES 0x0002 DEBUG_OWL 0x0004 DEBUG_ESCAPE 0x0008 DEBUG_MATCHER 0x0010 DEBUG_DRAGONS 0x0020 DEBUG_SEMEAI 0x0040 DEBUG_LOADSGF 0x0080 DEBUG_HELPER 0x0100 DEBUG_READING 0x0200 DEBUG_WORMS 0x0400 DEBUG_MOVE_REASONS 0x0800 DEBUG_OWL_PERFORMANCE 0x1000 DEBUG_LIFE 0x2000 DEBUG_FILLLIB 0x4000 DEBUG_READING_PERFORMANCE 0x8000 DEBUG_SCORING 0x010000 DEBUG_AFTERMATH 0x020000 DEBUG_ATARI_ATARI 0x040000 DEBUG_READING_CACHE 0x080000 DEBUG_TERRITORY 0x100000 DEBUG_OWL_PERSISTENT_CACHE 0X200000 DEBUG_TOP_MOVES 0x400000 DEBUG_MISCELLANEOUS 0x800000 DEBUG_ORACLE_STREAM 0x1000000These debug flags are additive. If you want to turn on both dragon and worm debugging you can use ‘-d0x420’.
Print the list of debug flags
Print more information about worm data.
moyo debugging, show moyo board. The level is fully documented elsewhere (see section Colored display and debugging of influence).
benchmarking mode - can be used with ‘-l’. Causes GNU Go to play itself repeatedly, seeding the start of the game with a few random moves. This method of testing the program is largely superceded by use of the
twogtp
program.
Print statistics (for debugging purposes).
Print debugging information. Use twice for more detail.
Set random number seed. This can be used to guarantee that GNU Go will make the same decisions on multiple runs through the same game. If
seed
is zero, GNU Go will play a different game each time.
Invoke the tactical reading code (see section Tactical reading to decide whether the string at location can be captured, and if so, whether it can be defended. If used with ‘-o’, this will produce a variation tree in SGF.
Invoke the owl code (see section The Owl Code) to decide whether the dragon at location can be captured, and whether it can be defended. If used with ‘-o’, this will produce a variation tree in SGF.
Decide whether dragons at location1 and location2 can be connected. Useful in connection with ‘-o’ to write the variations to an SGF file.
Print complete information about the status of the dragon at location.
At location1 and location2 are adjacent dragons of the opposite color. Neither is aliveby itself, and their fate (alive, dead or seki) depends on the outcome of a semeai (capturing race). Decide what happens. Useful in connection with ‘-o’ to write the variations to an SGF file.
Similar to ‘--decide-semeai’, except that moves proposed by the owl code are not considered.
Try to attack and defend every dragon with dragon.escape<6. If used with ‘-o’, writes the variations to an sgf file.
Evaluates the eyespace at location and prints a report. You can get more information by adding ‘-d0x02’ to the command line. (see section Eye Local Game Values.)
A dragon is surrounded if it is contained in the convex hull of its unfriendly neighbor dragons. This does not mean that it cannot escape, but it is often a good indicator that the dragon is under attack. This option draws the convex hull of the neighbor dragons and decides whether the dragon at location is surrounded.
Calls the function
atari_atari
to decide whether there exist combinations on the board.
Requires ‘-l’ to specify which game to score and ‘-L’ if you want to score anywhere else than at the end of the game record. method can be "estimate", "finish", or "aftermath". "finish" and "aftermath" are appropriate when the game is complete, or nearly so, and both try to supply an accurate final score. Notice that if the game is not already finished it will be played out, which may take quite a long time if the game is far from complete. The "estimate" method may be used to get a quick estimate during the middle of the game. Any of these options may be combined with ‘--chinese-rules’ if you want to use Chinese (Area) counting.
If the option ‘-o outputfilename’ is provided, the result will also be written as a comment in the output file. For the "finish" and "aftermath" scoring algorithms, the selfplayed moves completing the game are also stored.
- finish
Finish the game by selfplaying until two passes, then determine the status of all stones and compute territory.
- aftermath
Finish the game by selfplaying until two passes, then accurately determine status of all stones by playing out the "aftermath", i.e. playing on until all stones except ones involved in seki have become either unconditionally (in the strongest sense) alive or unconditionally dead (or captured). Slower than ‘--score finish’, and while these algorithms usually agree, if they differ, ‘--score aftermath’ is most likely to be correct.
--score aftermath --capture-all-dead --chinese-rules
This combination mandates Tromp-Taylor scoring. The Tromp-Taylor ruleset requires the game to be played out until all dead stones are removed, then uses area (Chinese) scoring. The option ‘--capture-all-dead’ requires the aftermath code to finish capturing all dead stones.
Most of these are available as configure options and are described in Other Options.
Print which experimental configure options were compiled into the program.
Use or do not use the experimental break-in code. This option has no effect at level 9 or below. The break in code is enabled by default at level 10, and the only difference between levels 9 and level 10 is that the break in code is disabled at level 9.
Use center oriented influence.
Turn off the fuseki database.
Turn off fuseki moves entirely
Turn off the joseki database.
Try to play mirror go.
Stop mirroring when n stones are on the board.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Daniel Bump on February, 19 2009 using texi2html 1.78.