| 1 | @menu |
| 2 | * Documentation:: Getting Documentation |
| 3 | * CGoban:: Running GNU Go with CGoban |
| 4 | * Other Clients:: Other Clients |
| 5 | * Ascii:: The Ascii Interface |
| 6 | * Emacs:: GNU Go mode in Emacs |
| 7 | * GMP and GTP:: The Go Modem Protocol and Go Text Protocol |
| 8 | * Tournaments:: Computer Tournaments |
| 9 | * SGF Support:: The Smart Game Format |
| 10 | * Invoking GNU Go:: Command line options |
| 11 | @end menu |
| 12 | |
| 13 | @node Documentation |
| 14 | |
| 15 | @section Getting Documentation |
| 16 | |
| 17 | You can obtain a printed copy of the manual by running @command{make |
| 18 | gnugo.pdf} in the @file{doc/}directory, then printing the resulting file. The |
| 19 | manual contains a great deal of information about the algorithms of GNU Go. |
| 20 | |
| 21 | On platforms supporting info documentation, you can usually |
| 22 | install the manual by executing `make install' (running as |
| 23 | root) from the @file{doc/} directory. This will create a file |
| 24 | called @file{gnugo.info} (and a few others) and copy them into |
| 25 | a system directory such as @file{/usr/local/share/info}. You |
| 26 | may then add them to your info directory tree with the command |
| 27 | @command{install-info --info-file=[path to gnugo.info] --info-dir=[path to dir]}. |
| 28 | The info documentation can be read conveniently from within Emacs by executing |
| 29 | the command @command{Control-h i}. |
| 30 | |
| 31 | Documentation in @file{doc/} consists of a man page @file{gnugo.6}, the |
| 32 | info files @file{gnugo.info}, @file{gnugo.info-1}, ... and the |
| 33 | Texinfo files from which the info files are built. The Texinfo |
| 34 | documentation contains this User's Guide and extensive information |
| 35 | about the algorithms of GNU Go, for developers. |
| 36 | |
| 37 | If you want a typeset copy of the Texinfo documentation, you can |
| 38 | @command{make gnugo.dvi}, @command{make gnugo.ps}, or @command{make |
| 39 | gnugo.pdf} in the @file{doc/} directory. (@command{make gnugo.pdf} only |
| 40 | works after you have converted all .eps-files in the doc/ directory to |
| 41 | .pdf files, e.g. with the utility epstopdf.) |
| 42 | |
| 43 | You can make an HTML version with the command @command{makeinfo --html |
| 44 | gnugo.texi}. If you have @command{texi2html}, better HTML documentation |
| 45 | may be obtained by @command{make gnugo.html} in the @file{doc/} |
| 46 | directory. |
| 47 | |
| 48 | User documentation can be obtained by running @command{gnugo --help} |
| 49 | or @command{man gnugo} from any terminal, or from the Texinfo |
| 50 | documentation. |
| 51 | |
| 52 | Documentation for developers is in the Texinfo documentation, and in comments |
| 53 | throughout the source. Contact us at @email{gnugo@@gnu.org} if you are |
| 54 | interested in helping to develop this program. |
| 55 | |
| 56 | @node CGoban |
| 57 | @section Running GNU Go via CGoban |
| 58 | @cindex CGoban |
| 59 | |
| 60 | There are two different programs called CGoban, both written by |
| 61 | William Shubert. In this documentation, CGoban means CGoban 1.x, |
| 62 | the older program. You should get a copy with version number 1.12 |
| 63 | or higher. |
| 64 | |
| 65 | CGoban is an extremely nice way to run GNU Go. CGoban provides a |
| 66 | beautiful graphic user interface under X Window System. |
| 67 | |
| 68 | Start CGoban. When the CGoban Control panel comes up, select ``Go |
| 69 | Modem''. You will get the Go Modem Protocol Setup. Choose one (or |
| 70 | both) of the players to be ``Program,'' and fill out the box with the |
| 71 | path to @file{gnugo}. After clicking OK, you get the Game Setup |
| 72 | window. Choose ``Rules Set'' to be Japanese (otherwise handicaps |
| 73 | won't work). Set the board size and handicap if you want. |
| 74 | |
| 75 | If you want to play with a komi, you should bear in mind that |
| 76 | the GMP does not have any provision for communicating the komi. |
| 77 | Because of this misfeature, unless you set the komi at the command |
| 78 | line GNU Go will have to guess it. It assumes the komi is 5.5 for |
| 79 | even games, 0.5 for handicap games. If this is not what you want, |
| 80 | you can specify the komi at the command line with the |
| 81 | @option{--komi} option, in the Go Modem Protocol Setup window. |
| 82 | You have to set the komi again in the Game Setup window, which |
| 83 | comes up next. |
| 84 | |
| 85 | Click OK and you are ready to go. |
| 86 | |
| 87 | In the Go Modem Protocol Setup window, when you specify the path to |
| 88 | GNU Go, you can give it command line options, such as @option{--quiet} to |
| 89 | suppress most messages. Since the Go Modem Protocol preempts standard |
| 90 | I/O other messages are sent to stderr, even if they are not error |
| 91 | messages. These will appear in the terminal from which you started |
| 92 | CGoban. |
| 93 | |
| 94 | @node Other Clients |
| 95 | @section Other Clients |
| 96 | @cindex jago |
| 97 | @cindex quarry |
| 98 | @cindex qGo |
| 99 | |
| 100 | In addition to CGoban (@pxref{CGoban}) there are a number of |
| 101 | other good clients that are capable of running GNU Go. Here |
| 102 | are the ones that we are aware of that are Free Software. This |
| 103 | list is part of a larger list of free Go programs that is maintained |
| 104 | at @url{http://www.gnu.org/software/gnugo/free_go_software.html}. |
| 105 | |
| 106 | @itemize @bullet |
| 107 | @item Quarry (@url{http://home.gna.org/quarry/}) is a GPL'd |
| 108 | client that supports GTP. Works under GNU/Linux and requires |
| 109 | GTK+ 2.x and librsvg 2.5. Supports GNU Go as well as other |
| 110 | engines. Can play not only Go, but also a few other board |
| 111 | games. |
| 112 | @item qGo (@url{http://sourceforge.net/projects/qgo/}) is a |
| 113 | full featured Client for playing on the servers, SGF viewing/editing, |
| 114 | and GNU Go client written in C++ for GNU/Linux, Windows and Mac OS X. |
| 115 | Can play One Color Go. Licensed GPL and QPL. |
| 116 | @item ccGo (@url{http://ccdw.org/~cjj/prog/ccgo/}) is a GPL'd client |
| 117 | written in C++ capable of playing with GNU Go, or on IGS. |
| 118 | @item RubyGo (@url{http://rubygo.rubyforge.org/}) is a GPL'd |
| 119 | client by J.-F. Menon for IGS written in the scripting language Ruby. |
| 120 | RubyGo is capable of playing with GNU Go using the GTP. |
| 121 | @item Dingoui (@url{http://dingoui.sourceforge.net/}) is a free |
| 122 | GMP client written in GTK+ which can run GNU Go. |
| 123 | @item Jago (@url{http://www.rene-grothmann.de/jago/}) |
| 124 | is a GPL'd Java client which works for both Microsoft Windows |
| 125 | and X Window System. |
| 126 | @item Sente Software's FreeGoban |
| 127 | (@url{http://www.sente.ch/software/goban/freegoban.html}) is a |
| 128 | well-liked user interface for GNU Go (and potentially other |
| 129 | programs) distributed under the GPL. |
| 130 | @item Mac GNU Go (@url{http://www1.u-netsurf.ne.jp/~future/HTML/macgnugo.html}) is a front end for GNU Go 3.2 with both |
| 131 | English and Japanese versions. License is GPL. |
| 132 | @item Quickiego (@url{http://www.geocities.com/secretmojo/QuickieGo/}) |
| 133 | is a Mac interface to GNU Go 2.6. |
| 134 | @item Gogui (@url{http://sourceforge.net/projects/gogui/}) from |
| 135 | Markus Enzenberger is a Java workbench that allows you to play |
| 136 | with a gtp (@url{http://www.lysator.liu.se/~gunnar/gtp}) |
| 137 | engine such as GNU Go. Licence is GPL. Gogui does not |
| 138 | support gmp or play on servers but is potentially very useful for programmers |
| 139 | working on GNU Go or other engines. |
| 140 | @end itemize |
| 141 | |
| 142 | @node Ascii |
| 143 | @section Ascii Interface |
| 144 | @cindex ascii interface |
| 145 | |
| 146 | Even if you do not have any client program, you can play with GNU Go |
| 147 | using its default Ascii interface. Simply type @command{gnugo} |
| 148 | at the command line, and GNU Go will draw a board. Typing |
| 149 | @command{help} will give a list of options. At the end of the |
| 150 | game, pass twice, and GNU Go will prompt you through the |
| 151 | counting. You and GNU Go must agree on the dead groups---you |
| 152 | can toggle the status of groups to be removed, and when you |
| 153 | are done, GNU Go will report the score. |
| 154 | |
| 155 | You can save the game at any point using the @command{save @var{filename}} |
| 156 | command. You can reload the game from the resulting SGF file with |
| 157 | the command @command{gnugo -l @var{filename} --mode ascii}. Reloading |
| 158 | games is not supported when playing with CGoban. However you can |
| 159 | use CGoban to save a file, then reload it in ascii mode. |
| 160 | |
| 161 | You may play games with a time limit against GNU Go in |
| 162 | ascii mode. For this, the Canadian time control system |
| 163 | is used. (See @uref{http://en.wikipedia.org/wiki/Byoyomi} |
| 164 | and @uref{http://senseis.xmp.net/?CanadianByoyomi}.) |
| 165 | That is, you have a main time to be followed by byo-yomi |
| 166 | periods. After the main time is exhausted you have a certain |
| 167 | number of moves to be made in a certain number of seconds. |
| 168 | (@pxref{Invoking GNU Go}) |
| 169 | |
| 170 | @node Emacs |
| 171 | @section GNU Go mode in Emacs |
| 172 | @cindex emacs mode |
| 173 | |
| 174 | You can run GNU Go from Emacs. This has the advantage |
| 175 | that you place the stones using the cursor arrow keys |
| 176 | or with the mouse, and you can have a nice graphical display of the board |
| 177 | within emacs. |
| 178 | |
| 179 | You will need the file @file{interface/gnugo.el}. There is |
| 180 | a version of this distributed with GNU Go but it only |
| 181 | works with Emacs 21. Most Emacsen are Emacs 22 however. |
| 182 | Therefore you should get the latest version of |
| 183 | gnugo.el by Thien-Thi Nguyen, which you can find at |
| 184 | @uref{http://www.gnuvola.org/software/j/gnugo/} or |
| 185 | @uref{http://www.emacswiki.org/emacs/gnugo.el}. |
| 186 | |
| 187 | You will also need some xpm files for the graphical |
| 188 | display. You can either use those distributed by |
| 189 | Thien-Thi Nguyen (at the first URL above) or those |
| 190 | distributed with GNU Go, either the file |
| 191 | @file{interface/gnugo-xpms.el} or (for high resolution |
| 192 | displays) @file{interface/gnugo-big-xpms.el}. |
| 193 | |
| 194 | Load the file @file{interface/gnugo.el} and |
| 195 | @file{interface/gnugo-xpms.el}. You may do this using the |
| 196 | Emacs @command{M-x load-file} command. |
| 197 | |
| 198 | When you start a game with @command{M-x gnugo}, |
| 199 | you will first see an ascii board. However typing `i' |
| 200 | toggles a graphical board display which is very nice. |
| 201 | This is a pleasant way to play GNU Go. You may get |
| 202 | help by typing @command{C-x m}. |
| 203 | |
| 204 | @node GMP and GTP |
| 205 | @section The Go Modem Protocol and Go Text Protocol |
| 206 | @cindex GMP |
| 207 | @cindex GTP |
| 208 | @cindex The Go Modem Protocol and Go Text Protocol |
| 209 | |
| 210 | @paragraphindent 3 |
| 211 | The Go Modem Protocol (GMP) was developed by Bruce Wilcox with input from |
| 212 | David Fotland, Anders Kierulf and others, according to the history in |
| 213 | @url{http://www.britgo.org/tech/gmp.html}. |
| 214 | |
| 215 | Any Go program @emph{should} support this protocol since it is a |
| 216 | standard. Since CGoban supports this protocol, the user interface for |
| 217 | any Go program can be done entirely through CGoban. The programmer can |
| 218 | concentrate on the real issues without worrying about drawing stones, |
| 219 | resizing the board and other distracting issues. |
| 220 | |
| 221 | GNU Go 3.0 introduced a new protocol, the Go Text Protocol |
| 222 | (@pxref{GTP}) which we hope can serve the functions currently |
| 223 | used by the GMP. The GTP is becoming increasingly adopted by |
| 224 | other programs as a method of interprocess communication, |
| 225 | both by computer programs and by clients. Still the GMP is |
| 226 | widely used in tournaments. |
| 227 | |
| 228 | @node Tournaments |
| 229 | |
| 230 | @section Computer Go Tournaments |
| 231 | |
| 232 | Computer Tournaments currently use the Go Modem Protocol. |
| 233 | The current method followed in such tournaments is to connect |
| 234 | the serial ports of the two computers by a ``null modem'' cable. |
| 235 | If you are running GNU/Linux it is convenient to use CGoban. |
| 236 | If your program is black, set it up in the Go Modem Protocol |
| 237 | Setup window as usual. For White, select ``Device'' and set |
| 238 | the device to @file{/dev/cua0} if your serial port is COM1 |
| 239 | and @file{/dev/cua1} if the port is COM2. |
| 240 | |
| 241 | @node SGF Support |
| 242 | @section Smart Game Format |
| 243 | @cindex SGF (Smart Game Format) |
| 244 | @cindex Smart Game Format |
| 245 | |
| 246 | The Smart Game Format (SGF), is the standard format for storing Go games. |
| 247 | GNU Go supports both reading and writing SGF files. The SGF specification |
| 248 | (FF[4]) is at: |
| 249 | @url{http://www.red-bean.com/sgf/} |
| 250 | |
| 251 | @node Invoking GNU Go |
| 252 | @section Invoking GNU Go: Command line options |
| 253 | @cindex command line options |
| 254 | @cindex invoking GNU Go |
| 255 | |
| 256 | @subsection Some basic options |
| 257 | @itemize |
| 258 | @item @option{--help}, @option{-h} |
| 259 | @quotation |
| 260 | Print a help message describing the options. This will also |
| 261 | tell you the defaults of various parameters, most importantly |
| 262 | the level and cache size. The default values of these |
| 263 | parameters can be set before compiling by @command{configure}. |
| 264 | If you forget the defaults you can find out using @option{--help}. |
| 265 | @end quotation |
| 266 | @item @option{--boardsize @var{size}} |
| 267 | @quotation |
| 268 | Set the board size |
| 269 | @end quotation |
| 270 | @item @option{--komi @var{num}} |
| 271 | @quotation |
| 272 | Set the komi |
| 273 | @end quotation |
| 274 | @item @option{--level @var{level}} |
| 275 | @cindex level of play |
| 276 | @quotation |
| 277 | GNU Go can play with different strengths and speeds. Level 10 |
| 278 | is the default. Decreasing the level will make GNU Go faster |
| 279 | but less accurate in its reading. |
| 280 | @end quotation |
| 281 | @item @option{--quiet}, @option{--silent} |
| 282 | @quotation |
| 283 | Don't print copyright and other messages. Messages specifically |
| 284 | requested by other command line options, such as @option{--trace}, |
| 285 | are not supressed. |
| 286 | @end quotation |
| 287 | @item @option{-l}, @option{--infile @var{filename}} |
| 288 | @quotation |
| 289 | Load the named SGF file. GNU Go will generate a move for |
| 290 | the player who is about to move. If you want to override this |
| 291 | and generate a move for the other player you may add the |
| 292 | option @option{--color @var{<color>}} where @var{<color>} is |
| 293 | @code{black} or @code{white}. |
| 294 | @end quotation |
| 295 | @item @option{-L}, @option{--until @var{move}} |
| 296 | @quotation |
| 297 | Stop loading just before the indicated move is played. @var{move} can |
| 298 | be either the move number or location. |
| 299 | @end quotation |
| 300 | @item @option{-o}, @option{--outfile @var{filename}} |
| 301 | @quotation |
| 302 | Write sgf output to file |
| 303 | @end quotation |
| 304 | @item @option{-O}, @option{--output-flags @var{flags}} |
| 305 | @quotation |
| 306 | Add useful information to the sgf file. Flags can be 'd', 'v' or |
| 307 | both (i.e. 'dv'). If 'd' is specified, dead and critical dragons |
| 308 | are marked in the sgf file. If 'v' is specified, move valuations |
| 309 | around the board are indicated. |
| 310 | @end quotation |
| 311 | @item @option{--mode @var{mode}} |
| 312 | @quotation |
| 313 | Force the playing mode ('ascii', 'emacs,' 'gmp' or 'gtp'). The default is |
| 314 | ASCII, but if no terminal is detected GMP (Go Modem Protocol) will be |
| 315 | assumed. In practice this is usually what you want, so you may never |
| 316 | need this option. |
| 317 | @end quotation |
| 318 | @item @option{--resign-allowed} |
| 319 | @quotation |
| 320 | GNU Go will resign games if this option is enabled. This is the default unless |
| 321 | you build the engine with the configure option |
| 322 | @option{--disable-resignation-allowed}. Unfortunately |
| 323 | the Go Modem Protocol has no provision for passing a resignation, |
| 324 | so this option has no effect in GMP mode. |
| 325 | @end quotation |
| 326 | @item @option{--never-resign} |
| 327 | @quotation |
| 328 | GNU Go will not resign games. |
| 329 | @end quotation |
| 330 | @item @option{--resign-allowed} |
| 331 | @quotation |
| 332 | GNU Go will resign lost games. This is the default. |
| 333 | @end quotation |
| 334 | @end itemize |
| 335 | |
| 336 | @subsection Monte Carlo Options |
| 337 | |
| 338 | GNU Go can play Monte Carlo Go on a 9x9 board. (Not |
| 339 | available for larger boards.) It makes quite a strong |
| 340 | engine. Here are the command line options. |
| 341 | |
| 342 | @itemize |
| 343 | @item @option{--monte-carlo} |
| 344 | @quotation |
| 345 | Use Monte Carlo move generation (9x9 or smaller). |
| 346 | @end quotation |
| 347 | @item @option{--mc-games-per-level <number>} |
| 348 | @quotation |
| 349 | Number of Monte Carlo simulations per level. Default 8000. |
| 350 | Thus at level 10, GNU Go simulates 80,000 games in order |
| 351 | to generate a move. |
| 352 | @end quotation |
| 353 | @item @option{--mc-list-patterns} |
| 354 | @quotation |
| 355 | list names of builtin Monte Carlo patterns |
| 356 | @end quotation |
| 357 | @item @option{--mc-patterns <name>} |
| 358 | @quotation |
| 359 | Choose a built in Monte Carlo pattern database. The |
| 360 | argument can be @file{mc_mogo_classic}, @file{mc_montegnu_classic} |
| 361 | or @file{mc_uniform}. |
| 362 | @end quotation |
| 363 | @item @option{--mc-load-patterns <filename>} |
| 364 | @quotation |
| 365 | read Monte Carlo patterns from file |
| 366 | @end quotation |
| 367 | @end itemize |
| 368 | |
| 369 | @subsection Other general options |
| 370 | @itemize |
| 371 | @item @option{-M}, @option{--cache-size @var{megs}} |
| 372 | @quotation |
| 373 | @cindex cache-size |
| 374 | @cindex cache |
| 375 | Memory in megabytes used for caching of read results. The default size |
| 376 | is 8 unless you configure gnugo with the command @command{configure |
| 377 | --enable-cache-size=@var{size}} before compiling to make @var{size} the |
| 378 | default (@pxref{Installation}). GNU Go stores results of its reading |
| 379 | calculations in a hash table (@pxref{Hashing}). If the hash table is |
| 380 | filled, it is emptied and the reading continues, but some reading may |
| 381 | have to be repeated that was done earlier, so a larger cache size will |
| 382 | make GNU Go run faster, provided the cache is not so large that swapping |
| 383 | occurs. Swapping may be detected on GNU/Linux machines using the program |
| 384 | @command{top}. However, if you have ample memory or if performance seems |
| 385 | to be a problem you may want to increase the size of the cache using |
| 386 | this option. |
| 387 | @end quotation |
| 388 | @item @option{--chinese-rules} |
| 389 | @quotation |
| 390 | Use Chinese rules. This means that the Chinese or Area Counting is |
| 391 | followed. It may affect the score of the game by one point in even |
| 392 | games, more if there is a handicap (since in Chinese Counting the |
| 393 | handicap stones count for Black) or if either player passes during the |
| 394 | game. |
| 395 | @end quotation |
| 396 | @item @option{--japanese-rules} |
| 397 | @quotation |
| 398 | Use Japanese Rules. This is the default unless you specify |
| 399 | @option{--enable-chinese-rules} as a configure option. |
| 400 | @end quotation |
| 401 | @item @option{--play-out-aftermath} |
| 402 | @item @option{--capture-all-dead} |
| 403 | @quotation |
| 404 | These options cause GNU Go to play out moves that are usually left |
| 405 | unplayed after the end of the game. Such moves lose points under |
| 406 | Japanese rules but not Chinese rules. With |
| 407 | @option{--play-out-aftermath}, GNU Go may play inside its |
| 408 | territory in order to reach a position where it considers every |
| 409 | group demonstrably alive or dead. The option |
| 410 | @option{--capture-all-dead} causes GNU Go to play inside its own |
| 411 | territory to remove dead stones. |
| 412 | @end quotation |
| 413 | @item @option{--forbid-suicide} |
| 414 | @quotation |
| 415 | Do not allow suicide moves (playing a stone so that it ends up without |
| 416 | liberties and is therefore immediately removed). This is the default. |
| 417 | @end quotation |
| 418 | @item @option{--allow-suicide} |
| 419 | @quotation |
| 420 | Allow suicide moves, except single-stone suicide. The latter would not |
| 421 | change the board at all and pass should be used instead. |
| 422 | @end quotation |
| 423 | @item @option{--allow-all-suicide} |
| 424 | @quotation |
| 425 | Allow suicide moves, including single-stone suicide. This is only |
| 426 | interesting in exceptional cases. Normally the |
| 427 | @option{--allow-suicide} option should be used instead. |
| 428 | @end quotation |
| 429 | @item @option{--simple-ko} |
| 430 | @quotation |
| 431 | Do not allow an immediate recapture of a ko so that the previous |
| 432 | position is recreated. Repetition of earlier positions than that are |
| 433 | allowed. This is default. |
| 434 | @end quotation |
| 435 | @item @option{--no-ko} |
| 436 | @quotation |
| 437 | Allow all kinds of board repetition. |
| 438 | @end quotation |
| 439 | @item @option{--positional-superko} |
| 440 | @quotation |
| 441 | Forbid repetition of any earlier board position. This only applies to |
| 442 | moves on the board; passing is always allowed. |
| 443 | @end quotation |
| 444 | @item @option{--situational-superko} |
| 445 | @quotation |
| 446 | Forbid repetition of any earlier board position with the same player |
| 447 | to move. This only applies to moves on the board; passing is always |
| 448 | allowed. |
| 449 | @end quotation |
| 450 | @item @option{--copyright}: Display the copyright notice |
| 451 | @item @option{--version} or @option{-v}: Print the version number |
| 452 | @item @option{--printsgf @var{filename}}: |
| 453 | @quotation |
| 454 | Create an SGF file containing a diagram of the board. Useful with |
| 455 | @option{-l} and @option{-L} to create a diagram of the board from |
| 456 | another sgf file. Illegal moves are indicated with the private |
| 457 | @code{IL} property. This property is not used in the FF4 SGF |
| 458 | specification, so we are free to preempt it. |
| 459 | @end quotation |
| 460 | @item @option{--options} |
| 461 | @quotation |
| 462 | Print which experimental configure options were compiled into the program |
| 463 | (@pxref{Other Options}). |
| 464 | @end quotation |
| 465 | @item @option{--orientation @var{n}} |
| 466 | @quotation |
| 467 | Combine with @option{-l}. The Go board can be oriented in 8 different |
| 468 | ways, counting reflections and rotations of the position; this option |
| 469 | selects an orientation (default 0). The parameter @samp{n} is an integer |
| 470 | between 0 and 7. |
| 471 | @end quotation |
| 472 | @end itemize |
| 473 | |
| 474 | @subsection Other options affecting strength and speed |
| 475 | |
| 476 | @itemize @bullet |
| 477 | @item @option{--level @var{amount}} |
| 478 | @cindex level |
| 479 | @quotation |
| 480 | The higher the level, the deeper GNU Go reads. Level 10 is the default. |
| 481 | If GNU Go plays too slowly on your machine, you may want to decrease it. |
| 482 | @end quotation |
| 483 | @end itemize |
| 484 | |
| 485 | This single parameter @option{--level} is the best way of |
| 486 | choosing whether to play stronger or faster. It controls |
| 487 | a host of other parameters which may themselves be set |
| 488 | individually at the command line. The default values of |
| 489 | these parameters may be found by running @command{gnugo --help}. |
| 490 | |
| 491 | Unless you are working on the program you probably don't |
| 492 | need the remaining options in this category. Instead, |
| 493 | just adjust the single variable @option{--level}. The |
| 494 | following options are of use to developers tuning the |
| 495 | program for performance and accuracy. For completeness, |
| 496 | here they are. |
| 497 | |
| 498 | @itemize @bullet |
| 499 | @item @option{-D}, @option{--depth @var{depth}} |
| 500 | @cindex depth |
| 501 | @quotation |
| 502 | Deep reading cutoff. When reading beyond this depth (default 16) GNU |
| 503 | Go assumes that any string which can obtain 3 liberties is alive. Thus |
| 504 | GNU Go can read ladders to an arbitrary depth, but will miss other |
| 505 | types of capturing moves. |
| 506 | @end quotation |
| 507 | @item @option{-B}, @option{--backfill-depth @var{depth}} |
| 508 | @quotation |
| 509 | Deep reading cutoff. Beyond this depth (default 12) GNU Go will no |
| 510 | longer try backfilling moves in its reading. |
| 511 | @end quotation |
| 512 | @item @option{--backfill2-depth @var{depth}} |
| 513 | @quotation |
| 514 | Another depth controlling how deeply GNU Go looks for backfilling |
| 515 | moves. The moves tried below @code{backfill2_depth} are generally more obscure |
| 516 | and time intensive than those controlled by @code{backfill_depth}, so this |
| 517 | parameter has a lower default. |
| 518 | @end quotation |
| 519 | @item @option{-F}, @option{--fourlib-depth @var{depth}} |
| 520 | @quotation |
| 521 | Deep reading cutoff. When reading beyond this depth (default 7) GNU |
| 522 | Go assumes that any string which can obtain 4 liberties is alive. |
| 523 | @end quotation |
| 524 | @item @option{-K}, @option{--ko-depth @var{depth}} |
| 525 | @quotation |
| 526 | Deep reading cutoff. Beyond this depth (default 8) GNU Go no longer |
| 527 | tries very hard to analyze kos. |
| 528 | @end quotation |
| 529 | @item @option{--branch-depth @var{depth}} |
| 530 | @quotation |
| 531 | This sets the @code{branch_depth}, typically a little below the |
| 532 | @code{depth}. Between @code{branch_depth} and @code{depth}, |
| 533 | attacks on strings with 3 liberties are considered but branching |
| 534 | is inhibited, so fewer variations are considered. Below this |
| 535 | depth (default 13), GNU Go still tries to attack strings with only |
| 536 | 3 liberties, but only tries one move at each node. |
| 537 | @end quotation |
| 538 | @item @option{--break-chain-depth @var{depth}} |
| 539 | @quotation |
| 540 | Set the @code{break_chain_depth}. Beyond this depth, GNU Go abandons |
| 541 | some attempts to defend groups by trying to capture part of the surrounding |
| 542 | chain. |
| 543 | @end quotation |
| 544 | @item @option{--aa-depth @var{depth}} |
| 545 | @quotation |
| 546 | The reading function @code{atari_atari} looks for combinations beginning |
| 547 | with a series of ataris, and culminating with some string having an |
| 548 | unexpected change in status (e.g. alive to dead or critical). This |
| 549 | command line optio sets the parameter @code{aa_depth} which determines |
| 550 | how deeply this function looks for combinations. |
| 551 | @end quotation |
| 552 | @item @option{--superstring-depth} |
| 553 | @quotation |
| 554 | A superstring (@pxref{Superstrings}) is an amalgamation of |
| 555 | tightly strings. Sometimes the best way to attack or defend a |
| 556 | string is by attacking or defending an element of the superstring. |
| 557 | Such tactics are tried below @code{superstring_depth} and this |
| 558 | command line option allows this parameter to be set. |
| 559 | @end quotation |
| 560 | @end itemize |
| 561 | |
| 562 | The preceeding options are documented with the reading code |
| 563 | (@pxref{Reading Basics}). |
| 564 | |
| 565 | @itemize @bullet |
| 566 | @item @option{--owl-branch} Below this depth Owl only considers |
| 567 | one move. Default 8. |
| 568 | @item @option{--owl-reading} Below this depth Owl assumes the |
| 569 | dragon has escaped. Default 20. |
| 570 | @item @option{--owl-node-limit} |
| 571 | @quotation |
| 572 | If the number of variations exceeds this limit, Owl assumes the dragon can |
| 573 | make life. Default 1000. We caution the user that increasing |
| 574 | @code{owl_node_limit} does not necessarily increase the strength of the |
| 575 | program. |
| 576 | @end quotation |
| 577 | @item @option{--owl-node-limit @var{n}} |
| 578 | @quotation |
| 579 | If the number of variations exceeds this limit, Owl assumes the dragon can |
| 580 | make life. Default 1000. We caution the user that increasing |
| 581 | @code{owl_node_limit} does not necessarily increase the strength of the |
| 582 | program. |
| 583 | @end quotation |
| 584 | @item @option{--owl-distrust @var{n}} |
| 585 | @quotation |
| 586 | Below this limit some owl reading is truncated. |
| 587 | @end quotation |
| 588 | @end itemize |
| 589 | |
| 590 | @subsection Ascii mode options |
| 591 | @cindex ascii mode |
| 592 | |
| 593 | @itemize |
| 594 | @item @option{--color @var{color}} |
| 595 | @quotation |
| 596 | Choose your color ('black' or 'white'). |
| 597 | @end quotation |
| 598 | @item @option{--handicap @var{number}} |
| 599 | @quotation |
| 600 | Choose the number of handicap stones (0--9) |
| 601 | @end quotation |
| 602 | @end itemize |
| 603 | |
| 604 | For more information about the following clock options see @xref{Ascii}. |
| 605 | |
| 606 | @itemize |
| 607 | @item @option{--clock @var{seconds}} |
| 608 | @quotation |
| 609 | Initialize the timer. |
| 610 | @end quotation |
| 611 | @item @option{--byo-time @var{seconds}} |
| 612 | @quotation |
| 613 | Number of seconds per (Canadian) byo-yomi period |
| 614 | @end quotation |
| 615 | @item @option{--byo-period @var{stones}} |
| 616 | @quotation |
| 617 | Number of stones per (Canadian) byo-yomi period |
| 618 | @end quotation |
| 619 | @end itemize |
| 620 | |
| 621 | @subsection Development options |
| 622 | |
| 623 | @itemize |
| 624 | @item @option{--replay @var{color}} |
| 625 | @quotation |
| 626 | Replay all moves in a game for either or both colors. If used with the |
| 627 | @option{-o} option the game record is annotated with move values. This |
| 628 | option requires @option{-l @var{filename}}. The color can be: |
| 629 | @itemize |
| 630 | @item white: replay white moves only |
| 631 | @item black: replay black moves only |
| 632 | @item both: replay all moves |
| 633 | @end itemize |
| 634 | When the move found by genmove differs from the move in the sgf |
| 635 | file the values of both moves are reported thus: |
| 636 | |
| 637 | @example |
| 638 | Move 13 (white): GNU Go plays C6 (20.60) - Game move F4 (20.60) |
| 639 | @end example |
| 640 | |
| 641 | This option is useful if one wants to confirm that a change such as a |
| 642 | speedup or other optimization has not affected the behavior of the |
| 643 | engine. Note that when several moves have the same top value (or |
| 644 | nearly equal) the move generated is not deterministic (though it can be |
| 645 | made deterministic by starting with the same random seed). Thus a few |
| 646 | deviations from the move in the sgf file are to be expected. Only if the |
| 647 | two reported values differ should we conclude that the engine plays |
| 648 | differently from the engine which generated the sgf file. |
| 649 | @xref{Regression}. |
| 650 | @end quotation |
| 651 | @item @option{-a}, @option{--allpats} |
| 652 | @quotation |
| 653 | Test all patterns, even those smaller in value than the largest move |
| 654 | found so far. This should never affect GNU Go's final move, and it |
| 655 | will make it run slower. However this can be very useful when "tuning" |
| 656 | GNU Go. It causes both the traces and the output file (@option{-o}) to |
| 657 | be more informative. |
| 658 | @end quotation |
| 659 | @item @option{-T}, @option{--printboard}: colored display of dragons. |
| 660 | @quotation |
| 661 | Use rxvt, xterm or Linux Console. (@pxref{Colored Display}) |
| 662 | @end quotation |
| 663 | @item @option{--showtime} |
| 664 | @quotation |
| 665 | Print timing information to stderr. |
| 666 | @end quotation |
| 667 | @item @option{-E}, @option{--printeyes}: colored display of eye spaces |
| 668 | @quotation |
| 669 | Use rxvt, xterm or Linux Console. (@pxref{Colored Display}) |
| 670 | @end quotation |
| 671 | @item @option{-d}, @option{--debug @var{level}} |
| 672 | @quotation |
| 673 | Produce debugging output. The debug level is given in hexadecimal, using the |
| 674 | bits defined in the following table from @file{engine/gnugo.h}. A list of |
| 675 | these may be produced using @option{--debug-flags}. Here they are in |
| 676 | hexadecimal: |
| 677 | |
| 678 | @cindex debugging options |
| 679 | @example |
| 680 | DEBUG_INFLUENCE 0x0001 |
| 681 | DEBUG_EYES 0x0002 |
| 682 | DEBUG_OWL 0x0004 |
| 683 | DEBUG_ESCAPE 0x0008 |
| 684 | DEBUG_MATCHER 0x0010 |
| 685 | DEBUG_DRAGONS 0x0020 |
| 686 | DEBUG_SEMEAI 0x0040 |
| 687 | DEBUG_LOADSGF 0x0080 |
| 688 | DEBUG_HELPER 0x0100 |
| 689 | DEBUG_READING 0x0200 |
| 690 | DEBUG_WORMS 0x0400 |
| 691 | DEBUG_MOVE_REASONS 0x0800 |
| 692 | DEBUG_OWL_PERFORMANCE 0x1000 |
| 693 | DEBUG_LIFE 0x2000 |
| 694 | DEBUG_FILLLIB 0x4000 |
| 695 | DEBUG_READING_PERFORMANCE 0x8000 |
| 696 | DEBUG_SCORING 0x010000 |
| 697 | DEBUG_AFTERMATH 0x020000 |
| 698 | DEBUG_ATARI_ATARI 0x040000 |
| 699 | DEBUG_READING_CACHE 0x080000 |
| 700 | DEBUG_TERRITORY 0x100000 |
| 701 | DEBUG_OWL_PERSISTENT_CACHE 0X200000 |
| 702 | DEBUG_TOP_MOVES 0x400000 |
| 703 | DEBUG_MISCELLANEOUS 0x800000 |
| 704 | DEBUG_ORACLE_STREAM 0x1000000 |
| 705 | @end example |
| 706 | |
| 707 | These debug flags are additive. If you want to turn on both |
| 708 | dragon and worm debugging you can use @option{-d0x420}. |
| 709 | @end quotation |
| 710 | @item @option{--debug-flags} |
| 711 | @quotation |
| 712 | Print the list of debug flags |
| 713 | @end quotation |
| 714 | @item @option{-w}, @option{--worms} |
| 715 | @quotation |
| 716 | Print more information about worm data. |
| 717 | @end quotation |
| 718 | @item @option{-m}, @option{--moyo @var{level}} |
| 719 | @quotation |
| 720 | moyo debugging, show moyo board. The @var{level} is fully |
| 721 | documented elsewhere (@pxref{Influential Display}). |
| 722 | @end quotation |
| 723 | @item @option{-b}, @option{--benchmark @var{number}} |
| 724 | @quotation |
| 725 | benchmarking mode - can be used with @option{-l}. Causes GNU Go to play itself |
| 726 | repeatedly, seeding the start of the game with a few random moves. This method |
| 727 | of testing the program is largely superceded by use of the @command{twogtp} |
| 728 | program. |
| 729 | @end quotation |
| 730 | @item @option{-S}, @option{--statistics} |
| 731 | @quotation |
| 732 | Print statistics (for debugging purposes). |
| 733 | @end quotation |
| 734 | @item @option{-t}, @option{--trace} |
| 735 | @quotation |
| 736 | Print debugging information. Use twice for more detail. |
| 737 | @end quotation |
| 738 | @item @option{-r}, @option{--seed @var{seed}} |
| 739 | @quotation |
| 740 | Set random number seed. This can be used to guarantee that GNU Go will make |
| 741 | the same decisions on multiple runs through the same game. If @code{seed} is |
| 742 | zero, GNU Go will play a different game each time. |
| 743 | @end quotation |
| 744 | @item @option{--decide-string @var{location}} |
| 745 | @quotation |
| 746 | Invoke the tactical reading code (@pxref{Tactical Reading} to decide |
| 747 | whether the string at @var{location} can be captured, and if so, whether it |
| 748 | can be defended. If used with @option{-o}, this will produce a variation tree |
| 749 | in SGF. |
| 750 | @end quotation |
| 751 | @item @option{--decide-owl @var{location}} |
| 752 | @quotation |
| 753 | Invoke the owl code (@pxref{The Owl Code}) to decide whether the dragon at |
| 754 | @var{location} can be captured, and whether it can be defended. If used with |
| 755 | @option{-o}, this will produce a variation tree in SGF. |
| 756 | @end quotation |
| 757 | @item @option{--decide-connection @var{location1}/@var{location2}} |
| 758 | @quotation |
| 759 | Decide whether dragons at @var{location1} and @var{location2} can be connected. |
| 760 | Useful in connection with @option{-o} to write the variations to an SGF file. |
| 761 | @end quotation |
| 762 | @item @option{--decide-dragon-data @var{location}} |
| 763 | @quotation |
| 764 | Print complete information about the status of the dragon at @var{location}. |
| 765 | @end quotation |
| 766 | @item @option{--decide-semeai @var{location1}/@var{location2}} |
| 767 | @quotation |
| 768 | At @var{location1} and @var{location2} are adjacent dragons of the |
| 769 | opposite color. Neither is aliveby itself, and their fate (alive, |
| 770 | dead or seki) depends on the outcome of a semeai (capturing race). |
| 771 | Decide what happens. Useful in connection with @option{-o} to |
| 772 | write the variations to an SGF file. |
| 773 | @end quotation |
| 774 | @item @option{--decide-tactical-semeai @var{location1}/@var{location2}} |
| 775 | @quotation |
| 776 | Similar to @option{--decide-semeai}, except that moves proposed by the |
| 777 | owl code are not considered. |
| 778 | @end quotation |
| 779 | @item @option{--decide-position} |
| 780 | @quotation |
| 781 | Try to attack and defend every dragon with dragon.escape<6. If |
| 782 | used with @option{-o}, writes the variations to an sgf file. |
| 783 | @end quotation |
| 784 | @item @option{--decide-eye @var{location}} |
| 785 | @quotation |
| 786 | Evaluates the eyespace at @var{location} and prints a report. You can get |
| 787 | more information by adding @option{-d0x02} to the command line. |
| 788 | (@pxref{Eye Local Game Values}.) |
| 789 | @end quotation |
| 790 | @item @option{--decide-surrounded @var{location}} |
| 791 | @quotation |
| 792 | A dragon is @emph{surrounded} if it is contained in the convex hull of |
| 793 | its unfriendly neighbor dragons. This does not mean that it cannot escape, |
| 794 | but it is often a good indicator that the dragon is under attack. This |
| 795 | option draws the convex hull of the neighbor dragons and decides whether |
| 796 | the dragon at @var{location} is surrounded. |
| 797 | @end quotation |
| 798 | @item @option{--decide-combination} |
| 799 | @quotation |
| 800 | Calls the function @code{atari_atari} to decide whether there |
| 801 | exist combinations on the board. |
| 802 | @end quotation |
| 803 | @item @option{--score @var{method}} |
| 804 | @quotation |
| 805 | Requires @option{-l} to specify which game to score and @option{-L} if |
| 806 | you want to score anywhere else than at the end of the game record. |
| 807 | @var{method} can be "estimate", "finish", or "aftermath". "finish" and |
| 808 | "aftermath" are appropriate when the game is complete, or nearly so, and |
| 809 | both try to supply an accurate final score. Notice that if the game is |
| 810 | not already finished it will be played out, which may take quite a long |
| 811 | time if the game is far from complete. The "estimate" method may be used |
| 812 | to get a quick estimate during the middle of the game. Any of these |
| 813 | options may be combined with @option{--chinese-rules} if you want to use |
| 814 | Chinese (Area) counting. |
| 815 | |
| 816 | If the option @option{-o @var{outputfilename}} is provided, the result |
| 817 | will also be written as a comment in the output file. For the "finish" |
| 818 | and "aftermath" scoring algorithms, the selfplayed moves completing the |
| 819 | game are also stored. |
| 820 | |
| 821 | @itemize |
| 822 | @item finish |
| 823 | @quotation |
| 824 | Finish the game by selfplaying until two passes, then determine the |
| 825 | status of all stones and compute territory. |
| 826 | @end quotation |
| 827 | @item aftermath |
| 828 | @quotation |
| 829 | Finish the game by selfplaying until two passes, then accurately |
| 830 | determine status of all stones by playing out the "aftermath", i.e. |
| 831 | playing on until all stones except ones involved in seki have become |
| 832 | either unconditionally (in the strongest sense) alive or unconditionally |
| 833 | dead (or captured). Slower than @option{--score finish}, and while these |
| 834 | algorithms usually agree, if they differ, @option{--score aftermath} is |
| 835 | most likely to be correct. |
| 836 | @end quotation |
| 837 | @end itemize |
| 838 | @end quotation |
| 839 | @item @code{--score aftermath --capture-all-dead --chinese-rules} |
| 840 | @quotation |
| 841 | This combination mandates @strong{Tromp-Taylor} scoring. The |
| 842 | Tromp-Taylor ruleset requires the game to be played out until |
| 843 | all dead stones are removed, then uses area (Chinese) scoring. |
| 844 | The option @option{--capture-all-dead} requires the aftermath |
| 845 | code to finish capturing all dead stones. |
| 846 | @end quotation |
| 847 | @end itemize |
| 848 | |
| 849 | @subsection Experimental options |
| 850 | |
| 851 | Most of these are available as configure options and are |
| 852 | described in @ref{Other Options}. |
| 853 | |
| 854 | @itemize @bullet |
| 855 | @item @option{--options} |
| 856 | @quotation |
| 857 | Print which experimental configure options were compiled into the program. |
| 858 | @end quotation |
| 859 | @item @option{--with-break-in} |
| 860 | @item @option{--without-break-in} |
| 861 | @quotation |
| 862 | Use or do not use the experimental break-in code. This option |
| 863 | has no effect at level 9 or below. The break in code is enabled |
| 864 | by default at level 10, and the only difference between levels |
| 865 | 9 and level 10 is that the break in code is disabled at level 9. |
| 866 | @end quotation |
| 867 | @item @option{--cosmic-gnugo} |
| 868 | @quotation |
| 869 | Use center oriented influence. |
| 870 | @end quotation |
| 871 | @item @option{--nofusekidb} |
| 872 | @quotation |
| 873 | Turn off the fuseki database. |
| 874 | @end quotation |
| 875 | @item @option{--nofuseki} |
| 876 | @quotation |
| 877 | Turn off fuseki moves entirely |
| 878 | @end quotation |
| 879 | @item @option{--nojosekidb} |
| 880 | @quotation |
| 881 | Turn off the joseki database. |
| 882 | @end quotation |
| 883 | @item @option{--mirror} |
| 884 | @quotation |
| 885 | Try to play mirror go. |
| 886 | @end quotation |
| 887 | @item @option{--mirror-limit @var{n}} |
| 888 | @quotation |
| 889 | Stop mirroring when @var{n} stones are on the board. |
| 890 | @end quotation |
| 891 | @end itemize |