| 1 | This is gnugo.info, produced by makeinfo version 4.11 from gnugo.texi. |
| 2 | |
| 3 | INFO-DIR-SECTION GNU games |
| 4 | START-INFO-DIR-ENTRY |
| 5 | * GNU Go: (gnugo). The GNU Go program |
| 6 | END-INFO-DIR-ENTRY |
| 7 | |
| 8 | \1f |
| 9 | File: gnugo.info, Node: Top, Next: Introduction, Up: (dir) |
| 10 | |
| 11 | GNU Go Documentation |
| 12 | ******************** |
| 13 | |
| 14 | GNU Go |
| 15 | ****** |
| 16 | |
| 17 | This manual documents `GNU Go', a Go program and its sources. This is |
| 18 | Edition 3.8 of the `GNU Go Program Documentation' |
| 19 | |
| 20 | Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, |
| 21 | 2008 and 2009 Free Software Foundation (http://www.fsf.org), Inc. |
| 22 | |
| 23 | Permission is granted to make and distribute verbatim or modified |
| 24 | copies of this manual is given provided that the terms of the GNU Free |
| 25 | Documentation License (*note GFDL::, version 1.3 or any later version) |
| 26 | are respected. |
| 27 | |
| 28 | Permission is granted to make and distribute verbatim or modified |
| 29 | copies of the program GNU Go is given provided the terms of the GNU |
| 30 | General Public License (*note GPL::, version 3 or any later version) |
| 31 | are respected. |
| 32 | |
| 33 | * Menu: |
| 34 | |
| 35 | User's manual |
| 36 | * Introduction:: What is GNU Go ? |
| 37 | * Installation:: Installing GNU Go |
| 38 | * User Guide:: Using GNU Go |
| 39 | |
| 40 | An introduction to the GNU Go engine |
| 41 | * Overview:: Overview of the GNU Go engine |
| 42 | * Analyzing:: Analyzing GNU Go's moves |
| 43 | * Move Generation:: How GNU Go generates moves |
| 44 | * Worms and Dragons:: Dragons and Worms |
| 45 | * Eyes:: Eyes and half eyes |
| 46 | * Patterns:: Pattern database |
| 47 | * Tactical Reading:: Tactical and Connection Reading |
| 48 | * Pattern Based Reading:: Pattern Based Reading: Owl and Combinations |
| 49 | * Influence:: Influence Function |
| 50 | * Monte Carlo Go:: Monte Carlo GNU Go |
| 51 | |
| 52 | Infrastructure and Interfaces |
| 53 | * Libboard:: The basic go board library. |
| 54 | * SGF:: Handling SGF trees in memory |
| 55 | * DFA:: The DFA Pattern Matcher |
| 56 | * Utility Functions:: `utils.c' and `printutils.c' |
| 57 | * API:: API to the GNU Go engine |
| 58 | * GTP:: The Go Text Protocol |
| 59 | * Regression:: Regression testing |
| 60 | |
| 61 | Appendices |
| 62 | * Copying:: Software and Documentation Licenses |
| 63 | |
| 64 | Indices |
| 65 | * Concept Index:: Concept Index |
| 66 | * Functions Index:: Functions Index |
| 67 | |
| 68 | \1f |
| 69 | File: gnugo.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top |
| 70 | |
| 71 | 1 Introduction |
| 72 | ************** |
| 73 | |
| 74 | This is GNU Go 3.8, a Go program. Development versions of GNU Go may be |
| 75 | found at `http://www.gnu.org/software/gnugo/devel.html'. Contact us at |
| 76 | <gnugo@gnu.org> if you are interested in helping. |
| 77 | |
| 78 | * Menu: |
| 79 | |
| 80 | * About:: About GNU Go and this Manual |
| 81 | * Copyright:: Copyright |
| 82 | * Authors:: The Authors of GNU Go |
| 83 | * Thanks:: Acknowledgements |
| 84 | * Development:: Developing GNU Go |
| 85 | |
| 86 | \1f |
| 87 | File: gnugo.info, Node: About, Next: Copyright, Up: Introduction |
| 88 | |
| 89 | 1.1 About GNU Go and this Manual |
| 90 | ================================ |
| 91 | |
| 92 | The challenge of Computer Go is not to *beat* the computer, but to |
| 93 | *program* the computer. |
| 94 | |
| 95 | In Computer Chess, strong programs are capable of playing at the |
| 96 | highest level, even challenging such a player as Garry Kasparov. No Go |
| 97 | program exists that plays at the same level as the strongest human |
| 98 | players. |
| 99 | |
| 100 | To be sure, existing Go programs are strong enough to be interesting |
| 101 | as opponents, and the hope exists that some day soon a truly strong |
| 102 | program can be written. This is especially true in view of the |
| 103 | successes of Monte Carlo methods, and a general recent improvement of |
| 104 | computer Go. |
| 105 | |
| 106 | Before GNU Go, Go programs have always been distributed as binaries |
| 107 | only. The algorithms in these proprietary programs are secret. No-one |
| 108 | but the programmer can examine them to admire or criticise. As a |
| 109 | consequence, anyone who wished to work on a Go program usually had to |
| 110 | start from scratch. This may be one reason that Go programs have not |
| 111 | reached a higher level of play. |
| 112 | |
| 113 | Unlike most Go programs, GNU Go is Free Software. Its algorithms and |
| 114 | source code are open and documented. They are free for any one to |
| 115 | inspect or enhance. We hope this freedom will give GNU Go's descendents |
| 116 | a certain competetive advantage. |
| 117 | |
| 118 | Here is GNU Go's Manual. There are doubtless inaccuracies. The |
| 119 | ultimate documentation is in the commented source code itself. |
| 120 | |
| 121 | The first three chapters of this manual are for the general user. |
| 122 | Chapter 3 is the User's Guide. The rest of the book is for programmers, |
| 123 | or persons curious about how GNU Go works. Chapter 4 is a general |
| 124 | overview of the engine. Chapter 5 introduces various tools for looking |
| 125 | into the GNU Go engine and finding out why it makes a certain move, and |
| 126 | Chapters 6-7 form a general programmer's reference to the GNU Go API. |
| 127 | The remaining chapters are more detailed explorations of different |
| 128 | aspects of GNU Go's internals. |
| 129 | |
| 130 | \1f |
| 131 | File: gnugo.info, Node: Copyright, Next: Authors, Prev: About, Up: Introduction |
| 132 | |
| 133 | 1.2 Copyrights |
| 134 | ============== |
| 135 | |
| 136 | Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 and 2008 |
| 137 | by the Free Software Foundation except as noted below. |
| 138 | |
| 139 | All source files are distributed under the GNU General Public License |
| 140 | (*note GPL::, version 3 or any later version), except `gmp.c', `gmp.h', |
| 141 | `gtp.c', and `gtp.h'. |
| 142 | |
| 143 | The files `gtp.c' and `gtp.h' are copyright the Free Software |
| 144 | Foundation. In the interests of promoting the Go Text Protocol these |
| 145 | two files are licensed under a less restrictive license than the GPL |
| 146 | and are free for unrestricted use (*note GTP License::). |
| 147 | |
| 148 | The two files `gmp.c' and `gmp.h' were placed in the public domain |
| 149 | by William Shubert, their author, and are free for unrestricted use. |
| 150 | |
| 151 | Documentation files (including this manual) are distributed under |
| 152 | the GNU Free Documentation License (*note GFDL::, version 1.3 or any |
| 153 | later version). |
| 154 | |
| 155 | The files `regression/games/golois/*sgf' are copyright Tristan |
| 156 | Cazenave and are included with his permission. |
| 157 | |
| 158 | The SGF files in `regression/games/handtalk/' are copyright Jessie |
| 159 | Annala and are used with permission. |
| 160 | |
| 161 | The SGF files in `regression/games/mertin13x13/' are copyright Stefan |
| 162 | Mertin and are used with permission. |
| 163 | |
| 164 | The remaining SGF files are either copyright by the FSF or are in |
| 165 | the public domain. |
| 166 | |
| 167 | \1f |
| 168 | File: gnugo.info, Node: Authors, Next: Thanks, Prev: Copyright, Up: Introduction |
| 169 | |
| 170 | 1.3 Authors |
| 171 | =========== |
| 172 | |
| 173 | GNU Go maintainers are Daniel Bump, Gunnar Farneback and Arend Bayer. |
| 174 | GNU Go authors (in chronological order of contribution) are Man Li, |
| 175 | Wayne Iba, Daniel Bump, David Denholm, Gunnar Farneba"ck, Nils Lohner, |
| 176 | Jerome Dumonteil, Tommy Thorn, Nicklas Ekstrand, Inge Wallin, Thomas |
| 177 | Traber, Douglas Ridgway, Teun Burgers, Tanguy Urvoy, Thien-Thi Nguyen, |
| 178 | Heikki Levanto, Mark Vytlacil, Adriaan van Kessel, Wolfgang Manner, Jens |
| 179 | Yllman, Don Dailey, Maans Ullerstam, Arend Bayer, Trevor Morris, Evan |
| 180 | Berggren Daniel, Fernando Portela, Paul Pogonyshev, S.P. Lee and |
| 181 | Stephane Nicolet, Martin Holters, Grzegorz Leszczynski and Lee Fisher. |
| 182 | |
| 183 | \1f |
| 184 | File: gnugo.info, Node: Thanks, Next: Development, Prev: Authors, Up: Introduction |
| 185 | |
| 186 | 1.4 Thanks |
| 187 | ========== |
| 188 | |
| 189 | We would like to thank Arthur Britto, David Doshay, Tim Hunt, Matthias |
| 190 | Krings, Piotr Lakomy, Paul Leonard, Jean-Louis Martineau, Andreas |
| 191 | Roever and Pierce Wetter for helpful correspondence. |
| 192 | |
| 193 | Thanks to everyone who stepped on a bug (and sent us a report)! |
| 194 | |
| 195 | Thanks to Gary Boos, Peter Gucwa, Martijn van der Kooij, Michael |
| 196 | Margolis, Trevor Morris, Maans Ullerstam, Don Wagner and Yin Zheng for |
| 197 | help with Visual C++. |
| 198 | |
| 199 | Thanks to Alan Crossman, Stephan Somogyi, Pierce Wetter and Mathias |
| 200 | Wagner for help with Macintosh. And thanks to Marco Scheurer and |
| 201 | Shigeru Mabuchi for helping us find various problems. |
| 202 | |
| 203 | Thanks to Jessie Annala for the Handtalk games. |
| 204 | |
| 205 | Special thanks to Ebba Berggren for creating our logo, based on a |
| 206 | design by Tanguy Urvoy and comments by Alan Crossman. The old GNU Go |
| 207 | logo was adapted from Jamal Hannah's typing GNU: |
| 208 | `http://www.gnu.org/graphics/atypinggnu.html'. Both logos can be found |
| 209 | in `doc/newlogo.*' and `doc/oldlogo.*'. |
| 210 | |
| 211 | We would like to thank Stuart Cracraft, Richard Stallman and Man |
| 212 | Lung Li for their interest in making this program a part of GNU, |
| 213 | William Shubert for writing CGoban and gmp.c, Rene Grothmann for Jago |
| 214 | and Erik van Riper and his collaborators for NNGS. |
| 215 | |
| 216 | \1f |
| 217 | File: gnugo.info, Node: Development, Prev: Thanks, Up: Introduction |
| 218 | |
| 219 | 1.5 Development |
| 220 | =============== |
| 221 | |
| 222 | You can help make GNU Go the best Go program. |
| 223 | |
| 224 | This is a task-list for anyone who is interested in helping with GNU |
| 225 | Go. If you want to work on such a project you should correspond with us |
| 226 | until we reach a common vision of how the feature will work! |
| 227 | |
| 228 | A note about copyright. The Free Software Foundation has the |
| 229 | copyright to GNU Go. For this reason, before any code can be accepted |
| 230 | as a part of the official release of GNU Go, the Free Software |
| 231 | Foundation will want you to sign a copyright assignment. |
| 232 | |
| 233 | Of course you could work on a forked version without signing such a |
| 234 | disclaimer. You can also distribute such a forked version of the |
| 235 | program so long as you also distribute the source code to your |
| 236 | modifications under the GPL (*note GPL::). But if you want your changes |
| 237 | to the program to be incorporated into the version we distribute we |
| 238 | need you to assign the copyright. |
| 239 | |
| 240 | Please contact the GNU Go maintainers, Daniel Bump |
| 241 | (<bump@sporadic.stanford.edu>) and Gunnar Farneba"ck |
| 242 | (<gunnar@lysator.liu.se>), to get more information and the papers to |
| 243 | sign. |
| 244 | |
| 245 | Bug reports are very welcome, but if you can, send us bug FIXES as |
| 246 | well as bug reports. If you see some bad behavior, figure out what |
| 247 | causes it, and what to do about fixing it. And send us a patch! If you |
| 248 | find an interesting bug and cannot tell us how to fix it, we would be |
| 249 | happy to have you tell us about it anyway. Send us the sgf file (if |
| 250 | possible) and attach other relevant information, such as the GNU Go |
| 251 | version number. In cases of assertion failures and segmentation faults |
| 252 | we probably want to know what operating system and compiler you were |
| 253 | using, in order to determine if the problem is platform dependent. |
| 254 | |
| 255 | If you want to work on GNU Go you should subscribe to the GNU Go |
| 256 | development list. (http://lists.gnu.org/mailman/listinfo/gnugo-devel) |
| 257 | Discussion of bugs and feedback from established developers about new |
| 258 | projects or tuning the existing engine can be done on the list. |
| 259 | |
| 260 | \1f |
| 261 | File: gnugo.info, Node: Installation, Next: User Guide, Prev: Introduction, Up: Top |
| 262 | |
| 263 | 2 Installation |
| 264 | ************** |
| 265 | |
| 266 | You can get the most recent version of GNU Go ftp.gnu.org or a mirror |
| 267 | (see `http://www.gnu.org/order/ftp.html' for a list). You can read |
| 268 | about newer versions and get other information at |
| 269 | `http://www.gnu.org/software/gnugo/'. |
| 270 | |
| 271 | * Menu: |
| 272 | |
| 273 | * GNU/Linux and Unix:: GNU Linux and Unix Installation |
| 274 | * Configure Options:: Configure Options |
| 275 | * Windows and MS-DOS:: Windows Installation |
| 276 | * Macintosh:: Macintosh Installation |
| 277 | |
| 278 | \1f |
| 279 | File: gnugo.info, Node: GNU/Linux and Unix, Next: Configure Options, Up: Installation |
| 280 | |
| 281 | 2.1 GNU/Linux and Unix |
| 282 | ====================== |
| 283 | |
| 284 | Untar the sources, change to the directory gnugo-3.8. Now do: |
| 285 | |
| 286 | ./configure [OPTIONS] |
| 287 | make |
| 288 | |
| 289 | Several configure options will be explained in the next section. You |
| 290 | do not need to set these unless you are dissatisfied with GNU Go's |
| 291 | performance or wish to vary the experimental options. |
| 292 | |
| 293 | As an example, |
| 294 | |
| 295 | ./configure --enable-level=9 --enable-cosmic-gnugo |
| 296 | |
| 297 | will make a binary in which the default level is 9, and the experimental |
| 298 | "cosmic"' option is enabled. A list of all configure options can be |
| 299 | obtained by running `./configure --help'. Further information about the |
| 300 | experimental options can be found in the next section (*note Configure |
| 301 | Options::). |
| 302 | |
| 303 | After running configure and make, you have now made a binary called |
| 304 | `interface/gnugo'. Now (running as root) type |
| 305 | |
| 306 | make install |
| 307 | |
| 308 | to install `gnugo' in `/usr/local/bin'. |
| 309 | |
| 310 | There are different methods of using GNU Go. You may run it from the |
| 311 | command line by just typing: |
| 312 | |
| 313 | gnugo |
| 314 | |
| 315 | but it is nicer to run it using CGoban 1 (under X Window System), |
| 316 | Quarry, Jago (on any platform with a Java Runtime Environment) or other |
| 317 | client programs offering a GUI. |
| 318 | |
| 319 | You can get the most recent version of CGoban 1 from |
| 320 | `http://sourceforge.net/projects/cgoban1/'. The earlier version 1.12 is |
| 321 | available from `http://www.igoweb.org/~wms/comp/cgoban/index.html'. |
| 322 | The CGoban version number MUST be 1.9.1 at least or it won't work. |
| 323 | CGoban 2 will not work. |
| 324 | |
| 325 | *Note CGoban::, for instructions on how to run GNU Go from Cgoban, or |
| 326 | *Note Other Clients::, for Jago or other clients. |
| 327 | |
| 328 | Quarry is available at `http://home.gna.org/quarry/'. |
| 329 | |
| 330 | \1f |
| 331 | File: gnugo.info, Node: Configure Options, Next: Windows and MS-DOS, Prev: GNU/Linux and Unix, Up: Installation |
| 332 | |
| 333 | 2.2 Configure Options |
| 334 | ===================== |
| 335 | |
| 336 | There are three options which you should consider configuring, |
| 337 | particularly if you are dissatisfied with GNU Go's performance. |
| 338 | |
| 339 | * Menu: |
| 340 | |
| 341 | * Ram Cache:: Ram Cache |
| 342 | * Default Level:: Default Level |
| 343 | * Other Options:: Other Options |
| 344 | |
| 345 | \1f |
| 346 | File: gnugo.info, Node: Ram Cache, Next: Default Level, Up: Configure Options |
| 347 | |
| 348 | 2.2.1 Ram Cache |
| 349 | --------------- |
| 350 | |
| 351 | By default, GNU Go makes a cache of about 8 Megabytes in RAM for its |
| 352 | internal use. The cache is used to store intermediate results during |
| 353 | its analysis of the position. More precisely the default cache size is |
| 354 | 350000 entries, which translates to 8.01 MB on typical 32 bit platforms |
| 355 | and 10.68 MB on typical 64 bit platforms. |
| 356 | |
| 357 | Increasing the cache size will often give a modest speed improvement. |
| 358 | If your system has lots of RAM, consider increasing the cache size. But |
| 359 | if the cache is too large, swapping will occur, causing hard drive |
| 360 | accesses and degrading performance. If your hard drive seems to be |
| 361 | running excessively your cache may be too large. On GNU/Linux systems, |
| 362 | you may detect swapping using the program 'top'. Use the 'f' command to |
| 363 | toggle SWAP display. |
| 364 | |
| 365 | You may override the size of the default cache at compile time by |
| 366 | running one of: |
| 367 | |
| 368 | ./configure --enable-cache-size=n |
| 369 | |
| 370 | to set the cache size to `n' megabytes. For example |
| 371 | |
| 372 | ./configure --enable-cache-size=32 |
| 373 | |
| 374 | creates a cache of size 32 megabytes. If you omit this, your default |
| 375 | cache size will be 8-11 MB as discussed above. Setting cache size |
| 376 | negative also gives the default size. You must recompile and reinstall |
| 377 | GNU Go after reconfiguring it by running `make' and `make install'. |
| 378 | |
| 379 | You may override the compile-time defaults by running `gnugo' with |
| 380 | the option `--cache-size n', where `n' is the size in megabytes of the |
| 381 | cache you want, and `--level' where n is the level desired. We will |
| 382 | discuss setting these parameters next in detail. |
| 383 | |
| 384 | \1f |
| 385 | File: gnugo.info, Node: Default Level, Next: Other Options, Prev: Ram Cache, Up: Configure Options |
| 386 | |
| 387 | 2.2.2 Default Level |
| 388 | ------------------- |
| 389 | |
| 390 | GNU Go can play at different levels. Up to level 10 is supported. At |
| 391 | level 10 GNU Go is much more accurate but takes an average of about 1.6 |
| 392 | times longer to play than at level 8. |
| 393 | |
| 394 | The level can be set at run time using the `--level' option. If you |
| 395 | don't set this, the default level will be used. You can set the default |
| 396 | level with the configure option `--enable-level=n'. For example |
| 397 | |
| 398 | ./configure --enable-level=9 |
| 399 | |
| 400 | sets the default level to 9. If you omit this parameter, the compiler |
| 401 | sets the default level to 10. We recommend using level 10 unless you |
| 402 | find it too slow. If you decide you want to change the default you may |
| 403 | rerun configure and recompile the program. |
| 404 | |
| 405 | \1f |
| 406 | File: gnugo.info, Node: Other Options, Prev: Default Level, Up: Configure Options |
| 407 | |
| 408 | 2.2.3 Other Options |
| 409 | ------------------- |
| 410 | |
| 411 | Anything new in the engine is generally tested as an experimental option |
| 412 | which can be turned on or off at compile time or run time. Some |
| 413 | "experimental" options such as the break-in code are no longer |
| 414 | experimental but are enabled by default. |
| 415 | |
| 416 | This section can be skipped unless you are interested in the |
| 417 | experimental options. |
| 418 | |
| 419 | Moreover, some configure options were removed from the stable |
| 420 | release. For example it is known that the owl extension code can cause |
| 421 | crashes, so the configure option -enable-experimental-owl-ext was |
| 422 | disabled for 3.8. |
| 423 | |
| 424 | The term "default" must be clarified, since there are really two |
| 425 | sets of defaults at hand, runtime defaults specified in `config.h' and |
| 426 | compile time default values for the runtime defaults, contained in |
| 427 | `configure' (which is created by editing `configure.in' then running |
| 428 | `autoconf'. For example we find in `config.h' |
| 429 | |
| 430 | /* Center oriented influence. Disabled by default. */ |
| 431 | #define COSMIC_GNUGO 0 |
| 432 | |
| 433 | /* Break-in module. Enabled by default. */ |
| 434 | #define USE_BREAK_IN 1 |
| 435 | |
| 436 | This means that the experimental cosmic option, which causes GNU Go |
| 437 | to play a center-oriented game (and makes the engine weaker) is |
| 438 | disabled by default, but that the break-in module is used. These are |
| 439 | defaults which are used when GNU Go is run without command line |
| 440 | options. They can be overridden with the run time options: |
| 441 | |
| 442 | gnugo --cosmic-gnugo --without-break-in |
| 443 | |
| 444 | Alternatively you can configure GNU Go as follows: |
| 445 | |
| 446 | ./configure --enable-cosmic-gnugo --disable-experimental-break-in |
| 447 | |
| 448 | then recompile GNU Go. This changes the defaults in `config.h', so |
| 449 | that you do not have to pass any command line options to GNU Go at run |
| 450 | time to get the experimental owl extension turned on and the |
| 451 | experimental break-in code turned off. |
| 452 | |
| 453 | If you want to find out what experimental options were compiled into |
| 454 | your GNU Go binary you can run `gnugo --options' to find out. Here is a |
| 455 | list of experimental options in GNU Go. |
| 456 | |
| 457 | * `experimental-break-in'. Experimental break-in code (*note Break |
| 458 | Ins::). You should not need to configure this because the break in |
| 459 | code is enabled by default in level 10, and is turned off at level |
| 460 | 9. If you don't want the breakin code just play at level 9. |
| 461 | |
| 462 | * `cosmic-gnugo'. An experimental style which plays a center |
| 463 | oriented game and has a good winning rate against standard GNU Go, |
| 464 | though it makes GNU Go weaker against other opponents. |
| 465 | |
| 466 | * `large-scale'. Attempt to make large-scale captures. See: |
| 467 | |
| 468 | `http://lists.gnu.org/archive/html/gnugo-devel/2003-07/msg00209.html' |
| 469 | |
| 470 | for the philosophy of this option. This option makes the engine |
| 471 | slower. |
| 472 | |
| 473 | * `metamachine'. Enables the metamachine, which allows you to run |
| 474 | the engine in an experimental mode whereby it forks a new `gnugo' |
| 475 | process which acts as an "oracle." Has no effect unless combined |
| 476 | with the `--metamachine' run-time option. |
| 477 | |
| 478 | Other options are not experimental, and can be changed as configure |
| 479 | or runtime options. |
| 480 | |
| 481 | * `chinese-rules' Use Chinese (area) counting. |
| 482 | |
| 483 | * `resignation-allowed' Allow GNU Go to resign games. This is on by |
| 484 | default. |
| 485 | |
| 486 | \1f |
| 487 | File: gnugo.info, Node: Windows and MS-DOS, Next: Macintosh, Prev: Configure Options, Up: Installation |
| 488 | |
| 489 | 2.3 Compiling GNU Go on Microsoft platforms |
| 490 | =========================================== |
| 491 | |
| 492 | 2.3.1 Building with older visual studio |
| 493 | --------------------------------------- |
| 494 | |
| 495 | The distribution directories contain some .dsp and .dsw files with GNU |
| 496 | Go. These have been brought up to date in the sense that they should |
| 497 | work if you have the older VC++ with Visual Studio 6 but the |
| 498 | distributed .dsp and .dsw files will only be of use with older version |
| 499 | of Visual Studio. |
| 500 | |
| 501 | In most cases (unless you are building in Cygwin) the preferred way |
| 502 | to build GNU Go on Windows platforms is to use CMake. CMake understands |
| 503 | about many versions of Visual C/Visual Studio, and will generate |
| 504 | project/solution files for the tools installed on your system. So even |
| 505 | if you have Visual Studio 6 you may use CMake and dispense with the |
| 506 | distributed .dsp and .dsw files. |
| 507 | |
| 508 | 2.3.2 Building with Visual Studio project files |
| 509 | ----------------------------------------------- |
| 510 | |
| 511 | Before you compile the GNU Go source, you need to run CMake first, to |
| 512 | generate the build files you'll give to Visual Studio. |
| 513 | |
| 514 | From the cmd.exe command prompt, CD into the GNU Go source directory. |
| 515 | To confirm you're in the right place, you should see the file |
| 516 | 'CMakeLists.txt' in the top-level directory of the GNU Go code (as well |
| 517 | as others in lower subdirectories). |
| 518 | |
| 519 | Direct CMake to generate the new Visual Studio build files by typing: |
| 520 | |
| 521 | cmake CMakeLists.txt |
| 522 | |
| 523 | Compile the code by invoking the newly-created Solution file: |
| 524 | |
| 525 | vcbuild GNUGo.sln |
| 526 | |
| 527 | This will take a few moments, as CMake generates 4 debug/retail |
| 528 | targets: |
| 529 | |
| 530 | debug |
| 531 | release |
| 532 | minsizerel |
| 533 | relwithdebinfo |
| 534 | |
| 535 | For each of these targets, Visual Studio is generating a version of |
| 536 | gnugo.exe: |
| 537 | |
| 538 | interface\debug\gnugo.exe |
| 539 | interface\release\gnugo.exe |
| 540 | interface\minsizerel\gnugo.exe |
| 541 | interface\relwithdebinfo\gnugo.exe |
| 542 | |
| 543 | Additionally, there is an 'Install' target available, that will copy |
| 544 | the the gnugo.exe into the %ProgramFiles% directory. To do this, type: |
| 545 | |
| 546 | vcbuild INSTALL.vcproj |
| 547 | |
| 548 | This should result in copying GNU/Go into: |
| 549 | |
| 550 | "%ProgramFiles%\GNUGo\bin\gnugo.exe" --options |
| 551 | |
| 552 | In addition to command line use, CMake also has a GUI version. Users |
| 553 | of the Visual Studio GUI might prefer to use that. |
| 554 | |
| 555 | 2.3.3 Building with Nmake makefiles |
| 556 | ----------------------------------- |
| 557 | |
| 558 | GNU Go will also build using NMake makefiles. Optionally, instead of |
| 559 | Visual Studio project/solution files, you may direct CMake to generate |
| 560 | NMake makefiles. To generate the makefiles: |
| 561 | |
| 562 | cmake -G "NMake Makefiles" CMakeLists.txt |
| 563 | |
| 564 | The default rule for the makefile is 'all'. Use the 'help' rule to |
| 565 | show a list of available targets. |
| 566 | |
| 567 | nmake -f Makefile help |
| 568 | |
| 569 | To compile GNU Go: |
| 570 | |
| 571 | nmake -f Makefil, all |
| 572 | |
| 573 | One sysand 2009 tems, GNU GO may fail to build when using NMake |
| 574 | makefiles. only fails the first time run, run NMake again with the |
| 575 | 'clean all' targets, and it will compile the second and subsequent |
| 576 | times. |
| 577 | |
| 578 | nmake -f Makefile clean all |
| 579 | |
| 580 | Which will successfully generate a gnugo.exe. |
| 581 | |
| 582 | interface\gnugo.exe --options |
| 583 | |
| 584 | 2.3.4 Building with MinGW Makefiles |
| 585 | ----------------------------------- |
| 586 | |
| 587 | GNU Go can be built on Windows systems using MinGW. |
| 588 | |
| 589 | This development environment uses: the GCC compiler (gcc.exe, not |
| 590 | cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU |
| 591 | Make build tool (`mingw32-make.exe', not NMake), all from the Windows |
| 592 | shell (`cmd.exe', not sh/bash). |
| 593 | |
| 594 | For CMake to work, in addition to the base MinGW installation, the |
| 595 | C++ compiler (g++.exe) and GNU Make (mingw32-make.exe) need to be |
| 596 | installed. This was tested using GCC v3, not the experimental v4. To |
| 597 | debug, use GDB, as the GCC-generated symbols won't work with |
| 598 | NTSD/Windbg/Visual Studio. |
| 599 | |
| 600 | To create the makfiles, run CMake with the MinGW generator option: |
| 601 | |
| 602 | cmake -G "MinGW Makefiles" CMakeLists.txt |
| 603 | |
| 604 | To build GNU Go, from a cmd.exe shell, run GNU Make (against the |
| 605 | newly-created 'Makefile' and it's default 'all' target): |
| 606 | |
| 607 | mingw32-make |
| 608 | ..\interface\gnugo.exe --options |
| 609 | |
| 610 | 2.3.5 Building with MSYS makefiles (MinGW) |
| 611 | ------------------------------------------ |
| 612 | |
| 613 | GNU Go can be built on Windows systems using MSYS. |
| 614 | |
| 615 | This development environment uses: the GCC compiler (gcc.exe, not |
| 616 | cl.exe), the Microsoft C runtime libraries (MSCRT, not GLibC), the GNU |
| 617 | Make build tool (make, not NMake), all from the GNU Bash (sh.exe, not |
| 618 | cmd.exe). |
| 619 | |
| 620 | To create the makfiles, run CMake with the MSYS generator option: |
| 621 | |
| 622 | cmake -G "MSYS Makefiles" CMakeLists.txt |
| 623 | |
| 624 | Start MSYS's Bash shell, either clicking on a shortcut on from the |
| 625 | command line: |
| 626 | |
| 627 | cd /d c:\msys\1.0 |
| 628 | msys.bat |
| 629 | |
| 630 | To build GNU Go, from a Bash shell, run GNU Make (against the |
| 631 | newly-created 'Makefile' and it's default 'all' target): |
| 632 | |
| 633 | make |
| 634 | ../interface/gnugo.exe --options |
| 635 | |
| 636 | To debug, use GDB, as the GCC-generated symbols won't work with |
| 637 | NTSD/Windbg/Visual Studio. |
| 638 | |
| 639 | 2.3.6 Building on cygwin |
| 640 | ------------------------ |
| 641 | |
| 642 | With Cygwin, you should be able to |
| 643 | |
| 644 | tar zxvf gnugo-3.8.tar.gz |
| 645 | cd gnugo-3.8 |
| 646 | env CC='gcc -mno-cygwin' ./configure |
| 647 | make |
| 648 | |
| 649 | 2.3.7 Testing on Windows: |
| 650 | ------------------------- |
| 651 | |
| 652 | `regression/regress.cmd' is a simplified cmd.exe-centric port of the |
| 653 | main gnugo Unix shell script regress.sh. It can be used to help verify |
| 654 | that the generated binary might be operational. Read the script's |
| 655 | comment header for more information. For access to the full GNU Go |
| 656 | tests, use Unix, not Windows. |
| 657 | |
| 658 | To test: |
| 659 | |
| 660 | cd regression |
| 661 | regress.cmd ..\interface\gnugo.exe |
| 662 | |
| 663 | \1f |
| 664 | File: gnugo.info, Node: Macintosh, Prev: Windows and MS-DOS, Up: Installation |
| 665 | |
| 666 | 2.4 Macintosh |
| 667 | ============= |
| 668 | |
| 669 | If you have Mac OS X you can build GNU Go using Apple's compiler, which |
| 670 | is derived from GCC. You will need Xcode. |
| 671 | |
| 672 | One issue is that the configure test for socket support is too |
| 673 | conservative. On OS/X, the configure test fails, but actually socket |
| 674 | support exists. So if you want to be able to connect to the engine |
| 675 | through tcp/ip (using gtp) you may `configure --enable-socket-support'. |
| 676 | There will be an error message but you may build the engine and socket |
| 677 | support should work. |
| 678 | |
| 679 | \1f |
| 680 | File: gnugo.info, Node: User Guide, Next: Overview, Prev: Installation, Up: Top |
| 681 | |
| 682 | 3 Using GNU Go |
| 683 | ************** |
| 684 | |
| 685 | * Menu: |
| 686 | |
| 687 | * Documentation:: Getting Documentation |
| 688 | * CGoban:: Running GNU Go with CGoban |
| 689 | * Other Clients:: Other Clients |
| 690 | * Ascii:: The Ascii Interface |
| 691 | * Emacs:: GNU Go mode in Emacs |
| 692 | * GMP and GTP:: The Go Modem Protocol and Go Text Protocol |
| 693 | * Tournaments:: Computer Tournaments |
| 694 | * SGF Support:: The Smart Game Format |
| 695 | * Invoking GNU Go:: Command line options |
| 696 | |
| 697 | \1f |
| 698 | File: gnugo.info, Node: Documentation, Next: CGoban, Up: User Guide |
| 699 | |
| 700 | 3.1 Getting Documentation |
| 701 | ========================= |
| 702 | |
| 703 | You can obtain a printed copy of the manual by running `make gnugo.pdf' |
| 704 | in the `doc/'directory, then printing the resulting file. The manual |
| 705 | contains a great deal of information about the algorithms of GNU Go. |
| 706 | |
| 707 | On platforms supporting info documentation, you can usually install |
| 708 | the manual by executing `make install' (running as root) from the |
| 709 | `doc/' directory. This will create a file called `gnugo.info' (and a |
| 710 | few others) and copy them into a system directory such as |
| 711 | `/usr/local/share/info'. You may then add them to your info directory |
| 712 | tree with the command `install-info --info-file=[path to gnugo.info] |
| 713 | --info-dir=[path to dir]'. The info documentation can be read |
| 714 | conveniently from within Emacs by executing the command `Control-h i'. |
| 715 | |
| 716 | Documentation in `doc/' consists of a man page `gnugo.6', the info |
| 717 | files `gnugo.info', `gnugo.info-1', ... and the Texinfo files from |
| 718 | which the info files are built. The Texinfo documentation contains this |
| 719 | User's Guide and extensive information about the algorithms of GNU Go, |
| 720 | for developers. |
| 721 | |
| 722 | If you want a typeset copy of the Texinfo documentation, you can |
| 723 | `make gnugo.dvi', `make gnugo.ps', or `make gnugo.pdf' in the `doc/' |
| 724 | directory. (`make gnugo.pdf' only works after you have converted all |
| 725 | .eps-files in the doc/ directory to .pdf files, e.g. with the utility |
| 726 | epstopdf.) |
| 727 | |
| 728 | You can make an HTML version with the command `makeinfo --html |
| 729 | gnugo.texi'. If you have `texi2html', better HTML documentation may be |
| 730 | obtained by `make gnugo.html' in the `doc/' directory. |
| 731 | |
| 732 | User documentation can be obtained by running `gnugo --help' or `man |
| 733 | gnugo' from any terminal, or from the Texinfo documentation. |
| 734 | |
| 735 | Documentation for developers is in the Texinfo documentation, and in |
| 736 | comments throughout the source. Contact us at <gnugo@gnu.org> if you are |
| 737 | interested in helping to develop this program. |
| 738 | |
| 739 | \1f |
| 740 | File: gnugo.info, Node: CGoban, Next: Other Clients, Prev: Documentation, Up: User Guide |
| 741 | |
| 742 | 3.2 Running GNU Go via CGoban |
| 743 | ============================= |
| 744 | |
| 745 | There are two different programs called CGoban, both written by William |
| 746 | Shubert. In this documentation, CGoban means CGoban 1.x, the older |
| 747 | program. You should get a copy with version number 1.12 or higher. |
| 748 | |
| 749 | CGoban is an extremely nice way to run GNU Go. CGoban provides a |
| 750 | beautiful graphic user interface under X Window System. |
| 751 | |
| 752 | Start CGoban. When the CGoban Control panel comes up, select "Go |
| 753 | Modem". You will get the Go Modem Protocol Setup. Choose one (or both) |
| 754 | of the players to be "Program," and fill out the box with the path to |
| 755 | `gnugo'. After clicking OK, you get the Game Setup window. Choose |
| 756 | "Rules Set" to be Japanese (otherwise handicaps won't work). Set the |
| 757 | board size and handicap if you want. |
| 758 | |
| 759 | If you want to play with a komi, you should bear in mind that the |
| 760 | GMP does not have any provision for communicating the komi. Because of |
| 761 | this misfeature, unless you set the komi at the command line GNU Go |
| 762 | will have to guess it. It assumes the komi is 5.5 for even games, 0.5 |
| 763 | for handicap games. If this is not what you want, you can specify the |
| 764 | komi at the command line with the `--komi' option, in the Go Modem |
| 765 | Protocol Setup window. You have to set the komi again in the Game |
| 766 | Setup window, which comes up next. |
| 767 | |
| 768 | Click OK and you are ready to go. |
| 769 | |
| 770 | In the Go Modem Protocol Setup window, when you specify the path to |
| 771 | GNU Go, you can give it command line options, such as `--quiet' to |
| 772 | suppress most messages. Since the Go Modem Protocol preempts standard |
| 773 | I/O other messages are sent to stderr, even if they are not error |
| 774 | messages. These will appear in the terminal from which you started |
| 775 | CGoban. |
| 776 | |
| 777 | \1f |
| 778 | File: gnugo.info, Node: Other Clients, Next: Ascii, Prev: CGoban, Up: User Guide |
| 779 | |
| 780 | 3.3 Other Clients |
| 781 | ================= |
| 782 | |
| 783 | In addition to CGoban (*note CGoban::) there are a number of other good |
| 784 | clients that are capable of running GNU Go. Here are the ones that we |
| 785 | are aware of that are Free Software. This list is part of a larger list |
| 786 | of free Go programs that is maintained at |
| 787 | `http://www.gnu.org/software/gnugo/free_go_software.html'. |
| 788 | |
| 789 | * Quarry (`http://home.gna.org/quarry/') is a GPL'd client that |
| 790 | supports GTP. Works under GNU/Linux and requires GTK+ 2.x and |
| 791 | librsvg 2.5. Supports GNU Go as well as other engines. Can play |
| 792 | not only Go, but also a few other board games. |
| 793 | |
| 794 | * qGo (`http://sourceforge.net/projects/qgo/') is a full featured |
| 795 | Client for playing on the servers, SGF viewing/editing, and GNU Go |
| 796 | client written in C++ for GNU/Linux, Windows and Mac OS X. Can |
| 797 | play One Color Go. Licensed GPL and QPL. |
| 798 | |
| 799 | * ccGo (`http://ccdw.org/~cjj/prog/ccgo/') is a GPL'd client written |
| 800 | in C++ capable of playing with GNU Go, or on IGS. |
| 801 | |
| 802 | * RubyGo (`http://rubygo.rubyforge.org/') is a GPL'd client by J.-F. |
| 803 | Menon for IGS written in the scripting language Ruby. RubyGo is |
| 804 | capable of playing with GNU Go using the GTP. |
| 805 | |
| 806 | * Dingoui (`http://dingoui.sourceforge.net/') is a free GMP client |
| 807 | written in GTK+ which can run GNU Go. |
| 808 | |
| 809 | * Jago (`http://www.rene-grothmann.de/jago/') is a GPL'd Java client |
| 810 | which works for both Microsoft Windows and X Window System. |
| 811 | |
| 812 | * Sente Software's FreeGoban |
| 813 | (`http://www.sente.ch/software/goban/freegoban.html') is a |
| 814 | well-liked user interface for GNU Go (and potentially other |
| 815 | programs) distributed under the GPL. |
| 816 | |
| 817 | * Mac GNU Go |
| 818 | (`http://www1.u-netsurf.ne.jp/~future/HTML/macgnugo.html') is a |
| 819 | front end for GNU Go 3.2 with both English and Japanese versions. |
| 820 | License is GPL. |
| 821 | |
| 822 | * Quickiego (`http://www.geocities.com/secretmojo/QuickieGo/') is a |
| 823 | Mac interface to GNU Go 2.6. |
| 824 | |
| 825 | * Gogui (`http://sourceforge.net/projects/gogui/') from Markus |
| 826 | Enzenberger is a Java workbench that allows you to play with a gtp |
| 827 | (`http://www.lysator.liu.se/~gunnar/gtp') engine such as GNU Go. |
| 828 | Licence is GPL. Gogui does not support gmp or play on servers but |
| 829 | is potentially very useful for programmers working on GNU Go or |
| 830 | other engines. |
| 831 | |
| 832 | \1f |
| 833 | File: gnugo.info, Node: Ascii, Next: Emacs, Prev: Other Clients, Up: User Guide |
| 834 | |
| 835 | 3.4 Ascii Interface |
| 836 | =================== |
| 837 | |
| 838 | Even if you do not have any client program, you can play with GNU Go |
| 839 | using its default Ascii interface. Simply type `gnugo' at the command |
| 840 | line, and GNU Go will draw a board. Typing `help' will give a list of |
| 841 | options. At the end of the game, pass twice, and GNU Go will prompt you |
| 842 | through the counting. You and GNU Go must agree on the dead groups--you |
| 843 | can toggle the status of groups to be removed, and when you are done, |
| 844 | GNU Go will report the score. |
| 845 | |
| 846 | You can save the game at any point using the `save FILENAME' |
| 847 | command. You can reload the game from the resulting SGF file with the |
| 848 | command `gnugo -l FILENAME --mode ascii'. Reloading games is not |
| 849 | supported when playing with CGoban. However you can use CGoban to save |
| 850 | a file, then reload it in ascii mode. |
| 851 | |
| 852 | You may play games with a time limit against GNU Go in ascii mode. |
| 853 | For this, the Canadian time control system is used. (See |
| 854 | `http://en.wikipedia.org/wiki/Byoyomi' and |
| 855 | `http://senseis.xmp.net/?CanadianByoyomi'.) That is, you have a main |
| 856 | time to be followed by byo-yomi periods. After the main time is |
| 857 | exhausted you have a certain number of moves to be made in a certain |
| 858 | number of seconds. (*note Invoking GNU Go::) |
| 859 | |
| 860 | \1f |
| 861 | File: gnugo.info, Node: Emacs, Next: GMP and GTP, Prev: Ascii, Up: User Guide |
| 862 | |
| 863 | 3.5 GNU Go mode in Emacs |
| 864 | ======================== |
| 865 | |
| 866 | You can run GNU Go from Emacs. This has the advantage that you place |
| 867 | the stones using the cursor arrow keys or with the mouse, and you can |
| 868 | have a nice graphical display of the board within emacs. |
| 869 | |
| 870 | You will need the file `interface/gnugo.el'. There is a version of |
| 871 | this distributed with GNU Go but it only works with Emacs 21. Most |
| 872 | Emacsen are Emacs 22 however. Therefore you should get the latest |
| 873 | version of gnugo.el by Thien-Thi Nguyen, which you can find at |
| 874 | `http://www.gnuvola.org/software/j/gnugo/' or |
| 875 | `http://www.emacswiki.org/emacs/gnugo.el'. |
| 876 | |
| 877 | You will also need some xpm files for the graphical display. You can |
| 878 | either use those distributed by Thien-Thi Nguyen (at the first URL |
| 879 | above) or those distributed with GNU Go, either the file |
| 880 | `interface/gnugo-xpms.el' or (for high resolution displays) |
| 881 | `interface/gnugo-big-xpms.el'. |
| 882 | |
| 883 | Load the file `interface/gnugo.el' and `interface/gnugo-xpms.el'. |
| 884 | You may do this using the Emacs `M-x load-file' command. |
| 885 | |
| 886 | When you start a game with `M-x gnugo', you will first see an ascii |
| 887 | board. However typing `i' toggles a graphical board display which is |
| 888 | very nice. This is a pleasant way to play GNU Go. You may get help by |
| 889 | typing `C-x m'. |
| 890 | |
| 891 | \1f |
| 892 | File: gnugo.info, Node: GMP and GTP, Next: Tournaments, Prev: Emacs, Up: User Guide |
| 893 | |
| 894 | 3.6 The Go Modem Protocol and Go Text Protocol |
| 895 | ============================================== |
| 896 | |
| 897 | The Go Modem Protocol (GMP) was developed by Bruce Wilcox with input |
| 898 | from David Fotland, Anders Kierulf and others, according to the history |
| 899 | in `http://www.britgo.org/tech/gmp.html'. |
| 900 | |
| 901 | Any Go program _should_ support this protocol since it is a |
| 902 | standard. Since CGoban supports this protocol, the user interface for |
| 903 | any Go program can be done entirely through CGoban. The programmer can |
| 904 | concentrate on the real issues without worrying about drawing stones, |
| 905 | resizing the board and other distracting issues. |
| 906 | |
| 907 | GNU Go 3.0 introduced a new protocol, the Go Text Protocol (*note |
| 908 | GTP::) which we hope can serve the functions currently used by the GMP. |
| 909 | The GTP is becoming increasingly adopted by other programs as a method |
| 910 | of interprocess communication, both by computer programs and by |
| 911 | clients. Still the GMP is widely used in tournaments. |
| 912 | |
| 913 | \1f |
| 914 | File: gnugo.info, Node: Tournaments, Next: SGF Support, Prev: GMP and GTP, Up: User Guide |
| 915 | |
| 916 | 3.7 Computer Go Tournaments |
| 917 | =========================== |
| 918 | |
| 919 | Computer Tournaments currently use the Go Modem Protocol. The current |
| 920 | method followed in such tournaments is to connect the serial ports of |
| 921 | the two computers by a "null modem" cable. If you are running |
| 922 | GNU/Linux it is convenient to use CGoban. If your program is black, |
| 923 | set it up in the Go Modem Protocol Setup window as usual. For White, |
| 924 | select "Device" and set the device to `/dev/cua0' if your serial port |
| 925 | is COM1 and `/dev/cua1' if the port is COM2. |
| 926 | |
| 927 | \1f |
| 928 | File: gnugo.info, Node: SGF Support, Next: Invoking GNU Go, Prev: Tournaments, Up: User Guide |
| 929 | |
| 930 | 3.8 Smart Game Format |
| 931 | ===================== |
| 932 | |
| 933 | The Smart Game Format (SGF), is the standard format for storing Go |
| 934 | games. GNU Go supports both reading and writing SGF files. The SGF |
| 935 | specification (FF[4]) is at: `http://www.red-bean.com/sgf/' |
| 936 | |
| 937 | \1f |
| 938 | File: gnugo.info, Node: Invoking GNU Go, Prev: SGF Support, Up: User Guide |
| 939 | |
| 940 | 3.9 Invoking GNU Go: Command line options |
| 941 | ========================================= |
| 942 | |
| 943 | 3.9.1 Some basic options |
| 944 | ------------------------ |
| 945 | |
| 946 | * `--help', `-h' |
| 947 | |
| 948 | Print a help message describing the options. This will also |
| 949 | tell you the defaults of various parameters, most importantly |
| 950 | the level and cache size. The default values of these |
| 951 | parameters can be set before compiling by `configure'. If |
| 952 | you forget the defaults you can find out using `--help'. |
| 953 | |
| 954 | * `--boardsize SIZE' |
| 955 | |
| 956 | Set the board size |
| 957 | |
| 958 | * `--komi NUM' |
| 959 | |
| 960 | Set the komi |
| 961 | |
| 962 | * `--level LEVEL' |
| 963 | |
| 964 | GNU Go can play with different strengths and speeds. Level 10 |
| 965 | is the default. Decreasing the level will make GNU Go faster |
| 966 | but less accurate in its reading. |
| 967 | |
| 968 | * `--quiet', `--silent' |
| 969 | |
| 970 | Don't print copyright and other messages. Messages |
| 971 | specifically requested by other command line options, such as |
| 972 | `--trace', are not supressed. |
| 973 | |
| 974 | * `-l', `--infile FILENAME' |
| 975 | |
| 976 | Load the named SGF file. GNU Go will generate a move for the |
| 977 | player who is about to move. If you want to override this and |
| 978 | generate a move for the other player you may add the option |
| 979 | `--color <COLOR>' where <COLOR> is `black' or `white'. |
| 980 | |
| 981 | * `-L', `--until MOVE' |
| 982 | |
| 983 | Stop loading just before the indicated move is played. MOVE |
| 984 | can be either the move number or location. |
| 985 | |
| 986 | * `-o', `--outfile FILENAME' |
| 987 | |
| 988 | Write sgf output to file |
| 989 | |
| 990 | * `-O', `--output-flags FLAGS' |
| 991 | |
| 992 | Add useful information to the sgf file. Flags can be 'd', 'v' |
| 993 | or both (i.e. 'dv'). If 'd' is specified, dead and critical |
| 994 | dragons are marked in the sgf file. If 'v' is specified, move |
| 995 | valuations around the board are indicated. |
| 996 | |
| 997 | * `--mode MODE' |
| 998 | |
| 999 | Force the playing mode ('ascii', 'emacs,' 'gmp' or 'gtp'). |
| 1000 | The default is ASCII, but if no terminal is detected GMP (Go |
| 1001 | Modem Protocol) will be assumed. In practice this is usually |
| 1002 | what you want, so you may never need this option. |
| 1003 | |
| 1004 | * `--resign-allowed' |
| 1005 | |
| 1006 | GNU Go will resign games if this option is enabled. This is |
| 1007 | the default unless you build the engine with the configure |
| 1008 | option `--disable-resignation-allowed'. Unfortunately the Go |
| 1009 | Modem Protocol has no provision for passing a resignation, so |
| 1010 | this option has no effect in GMP mode. |
| 1011 | |
| 1012 | * `--never-resign' |
| 1013 | |
| 1014 | GNU Go will not resign games. |
| 1015 | |
| 1016 | * `--resign-allowed' |
| 1017 | |
| 1018 | GNU Go will resign lost games. This is the default. |
| 1019 | |
| 1020 | 3.9.2 Monte Carlo Options |
| 1021 | ------------------------- |
| 1022 | |
| 1023 | GNU Go can play Monte Carlo Go on a 9x9 board. (Not available for |
| 1024 | larger boards.) It makes quite a strong engine. Here are the command |
| 1025 | line options. |
| 1026 | |
| 1027 | * `--monte-carlo' |
| 1028 | |
| 1029 | Use Monte Carlo move generation (9x9 or smaller). |
| 1030 | |
| 1031 | * `--mc-games-per-level <number>' |
| 1032 | |
| 1033 | Number of Monte Carlo simulations per level. Default 8000. |
| 1034 | Thus at level 10, GNU Go simulates 80,000 games in order to |
| 1035 | generate a move. |
| 1036 | |
| 1037 | * `--mc-list-patterns' |
| 1038 | |
| 1039 | list names of builtin Monte Carlo patterns |
| 1040 | |
| 1041 | * `--mc-patterns <name>' |
| 1042 | |
| 1043 | Choose a built in Monte Carlo pattern database. The argument |
| 1044 | can be `mc_mogo_classic', `mc_montegnu_classic' or |
| 1045 | `mc_uniform'. |
| 1046 | |
| 1047 | * `--mc-load-patterns <filename>' |
| 1048 | |
| 1049 | read Monte Carlo patterns from file |
| 1050 | |
| 1051 | 3.9.3 Other general options |
| 1052 | --------------------------- |
| 1053 | |
| 1054 | * `-M', `--cache-size MEGS' |
| 1055 | |
| 1056 | Memory in megabytes used for caching of read results. The |
| 1057 | default size is 8 unless you configure gnugo with the command |
| 1058 | `configure --enable-cache-size=SIZE' before compiling to make |
| 1059 | SIZE the default (*note Installation::). GNU Go stores |
| 1060 | results of its reading calculations in a hash table (*note |
| 1061 | Hashing::). If the hash table is filled, it is emptied and |
| 1062 | the reading continues, but some reading may have to be |
| 1063 | repeated that was done earlier, so a larger cache size will |
| 1064 | make GNU Go run faster, provided the cache is not so large |
| 1065 | that swapping occurs. Swapping may be detected on GNU/Linux |
| 1066 | machines using the program `top'. However, if you have ample |
| 1067 | memory or if performance seems to be a problem you may want |
| 1068 | to increase the size of the cache using this option. |
| 1069 | |
| 1070 | * `--chinese-rules' |
| 1071 | |
| 1072 | Use Chinese rules. This means that the Chinese or Area |
| 1073 | Counting is followed. It may affect the score of the game by |
| 1074 | one point in even games, more if there is a handicap (since |
| 1075 | in Chinese Counting the handicap stones count for Black) or |
| 1076 | if either player passes during the game. |
| 1077 | |
| 1078 | * `--japanese-rules' |
| 1079 | |
| 1080 | Use Japanese Rules. This is the default unless you specify |
| 1081 | `--enable-chinese-rules' as a configure option. |
| 1082 | |
| 1083 | * `--play-out-aftermath' |
| 1084 | |
| 1085 | * `--capture-all-dead' |
| 1086 | |
| 1087 | These options cause GNU Go to play out moves that are usually |
| 1088 | left unplayed after the end of the game. Such moves lose |
| 1089 | points under Japanese rules but not Chinese rules. With |
| 1090 | `--play-out-aftermath', GNU Go may play inside its territory |
| 1091 | in order to reach a position where it considers every group |
| 1092 | demonstrably alive or dead. The option `--capture-all-dead' |
| 1093 | causes GNU Go to play inside its own territory to remove dead |
| 1094 | stones. |
| 1095 | |
| 1096 | * `--forbid-suicide' |
| 1097 | |
| 1098 | Do not allow suicide moves (playing a stone so that it ends |
| 1099 | up without liberties and is therefore immediately removed). |
| 1100 | This is the default. |
| 1101 | |
| 1102 | * `--allow-suicide' |
| 1103 | |
| 1104 | Allow suicide moves, except single-stone suicide. The latter |
| 1105 | would not change the board at all and pass should be used |
| 1106 | instead. |
| 1107 | |
| 1108 | * `--allow-all-suicide' |
| 1109 | |
| 1110 | Allow suicide moves, including single-stone suicide. This is |
| 1111 | only interesting in exceptional cases. Normally the |
| 1112 | `--allow-suicide' option should be used instead. |
| 1113 | |
| 1114 | * `--simple-ko' |
| 1115 | |
| 1116 | Do not allow an immediate recapture of a ko so that the |
| 1117 | previous position is recreated. Repetition of earlier |
| 1118 | positions than that are allowed. This is default. |
| 1119 | |
| 1120 | * `--no-ko' |
| 1121 | |
| 1122 | Allow all kinds of board repetition. |
| 1123 | |
| 1124 | * `--positional-superko' |
| 1125 | |
| 1126 | Forbid repetition of any earlier board position. This only |
| 1127 | applies to moves on the board; passing is always allowed. |
| 1128 | |
| 1129 | * `--situational-superko' |
| 1130 | |
| 1131 | Forbid repetition of any earlier board position with the same |
| 1132 | player to move. This only applies to moves on the board; |
| 1133 | passing is always allowed. |
| 1134 | |
| 1135 | * `--copyright': Display the copyright notice |
| 1136 | |
| 1137 | * `--version' or `-v': Print the version number |
| 1138 | |
| 1139 | * `--printsgf FILENAME': |
| 1140 | |
| 1141 | Create an SGF file containing a diagram of the board. Useful |
| 1142 | with `-l' and `-L' to create a diagram of the board from |
| 1143 | another sgf file. Illegal moves are indicated with the private |
| 1144 | `IL' property. This property is not used in the FF4 SGF |
| 1145 | specification, so we are free to preempt it. |
| 1146 | |
| 1147 | * `--options' |
| 1148 | |
| 1149 | Print which experimental configure options were compiled into |
| 1150 | the program (*note Other Options::). |
| 1151 | |
| 1152 | * `--orientation N' |
| 1153 | |
| 1154 | Combine with `-l'. The Go board can be oriented in 8 different |
| 1155 | ways, counting reflections and rotations of the position; |
| 1156 | this option selects an orientation (default 0). The parameter |
| 1157 | `n' is an integer between 0 and 7. |
| 1158 | |
| 1159 | 3.9.4 Other options affecting strength and speed |
| 1160 | ------------------------------------------------ |
| 1161 | |
| 1162 | * `--level AMOUNT' |
| 1163 | |
| 1164 | The higher the level, the deeper GNU Go reads. Level 10 is |
| 1165 | the default. If GNU Go plays too slowly on your machine, you |
| 1166 | may want to decrease it. |
| 1167 | |
| 1168 | This single parameter `--level' is the best way of choosing whether to |
| 1169 | play stronger or faster. It controls a host of other parameters which |
| 1170 | may themselves be set individually at the command line. The default |
| 1171 | values of these parameters may be found by running `gnugo --help'. |
| 1172 | |
| 1173 | Unless you are working on the program you probably don't need the |
| 1174 | remaining options in this category. Instead, just adjust the single |
| 1175 | variable `--level'. The following options are of use to developers |
| 1176 | tuning the program for performance and accuracy. For completeness, here |
| 1177 | they are. |
| 1178 | |
| 1179 | * `-D', `--depth DEPTH' |
| 1180 | |
| 1181 | Deep reading cutoff. When reading beyond this depth (default |
| 1182 | 16) GNU Go assumes that any string which can obtain 3 |
| 1183 | liberties is alive. Thus GNU Go can read ladders to an |
| 1184 | arbitrary depth, but will miss other types of capturing moves. |
| 1185 | |
| 1186 | * `-B', `--backfill-depth DEPTH' |
| 1187 | |
| 1188 | Deep reading cutoff. Beyond this depth (default 12) GNU Go |
| 1189 | will no longer try backfilling moves in its reading. |
| 1190 | |
| 1191 | * `--backfill2-depth DEPTH' |
| 1192 | |
| 1193 | Another depth controlling how deeply GNU Go looks for |
| 1194 | backfilling moves. The moves tried below `backfill2_depth' |
| 1195 | are generally more obscure and time intensive than those |
| 1196 | controlled by `backfill_depth', so this parameter has a lower |
| 1197 | default. |
| 1198 | |
| 1199 | * `-F', `--fourlib-depth DEPTH' |
| 1200 | |
| 1201 | Deep reading cutoff. When reading beyond this depth (default |
| 1202 | 7) GNU Go assumes that any string which can obtain 4 |
| 1203 | liberties is alive. |
| 1204 | |
| 1205 | * `-K', `--ko-depth DEPTH' |
| 1206 | |
| 1207 | Deep reading cutoff. Beyond this depth (default 8) GNU Go no |
| 1208 | longer tries very hard to analyze kos. |
| 1209 | |
| 1210 | * `--branch-depth DEPTH' |
| 1211 | |
| 1212 | This sets the `branch_depth', typically a little below the |
| 1213 | `depth'. Between `branch_depth' and `depth', attacks on |
| 1214 | strings with 3 liberties are considered but branching is |
| 1215 | inhibited, so fewer variations are considered. Below this |
| 1216 | depth (default 13), GNU Go still tries to attack strings with |
| 1217 | only 3 liberties, but only tries one move at each node. |
| 1218 | |
| 1219 | * `--break-chain-depth DEPTH' |
| 1220 | |
| 1221 | Set the `break_chain_depth'. Beyond this depth, GNU Go |
| 1222 | abandons some attempts to defend groups by trying to capture |
| 1223 | part of the surrounding chain. |
| 1224 | |
| 1225 | * `--aa-depth DEPTH' |
| 1226 | |
| 1227 | The reading function `atari_atari' looks for combinations |
| 1228 | beginning with a series of ataris, and culminating with some |
| 1229 | string having an unexpected change in status (e.g. alive to |
| 1230 | dead or critical). This command line optio sets the parameter |
| 1231 | `aa_depth' which determines how deeply this function looks |
| 1232 | for combinations. |
| 1233 | |
| 1234 | * `--superstring-depth' |
| 1235 | |
| 1236 | A superstring (*note Superstrings::) is an amalgamation of |
| 1237 | tightly strings. Sometimes the best way to attack or defend a |
| 1238 | string is by attacking or defending an element of the |
| 1239 | superstring. Such tactics are tried below |
| 1240 | `superstring_depth' and this command line option allows this |
| 1241 | parameter to be set. |
| 1242 | |
| 1243 | The preceeding options are documented with the reading code (*note |
| 1244 | Reading Basics::). |
| 1245 | |
| 1246 | * `--owl-branch' Below this depth Owl only considers one move. |
| 1247 | Default 8. |
| 1248 | |
| 1249 | * `--owl-reading' Below this depth Owl assumes the dragon has |
| 1250 | escaped. Default 20. |
| 1251 | |
| 1252 | * `--owl-node-limit' |
| 1253 | |
| 1254 | If the number of variations exceeds this limit, Owl assumes |
| 1255 | the dragon can make life. Default 1000. We caution the user |
| 1256 | that increasing `owl_node_limit' does not necessarily |
| 1257 | increase the strength of the program. |
| 1258 | |
| 1259 | * `--owl-node-limit N' |
| 1260 | |
| 1261 | If the number of variations exceeds this limit, Owl assumes |
| 1262 | the dragon can make life. Default 1000. We caution the user |
| 1263 | that increasing `owl_node_limit' does not necessarily |
| 1264 | increase the strength of the program. |
| 1265 | |
| 1266 | * `--owl-distrust N' |
| 1267 | |
| 1268 | Below this limit some owl reading is truncated. |
| 1269 | |
| 1270 | 3.9.5 Ascii mode options |
| 1271 | ------------------------ |
| 1272 | |
| 1273 | * `--color COLOR' |
| 1274 | |
| 1275 | Choose your color ('black' or 'white'). |
| 1276 | |
| 1277 | * `--handicap NUMBER' |
| 1278 | |
| 1279 | Choose the number of handicap stones (0-9) |
| 1280 | |
| 1281 | For more information about the following clock options see *Note |
| 1282 | Ascii::. |
| 1283 | |
| 1284 | * `--clock SECONDS' |
| 1285 | |
| 1286 | Initialize the timer. |
| 1287 | |
| 1288 | * `--byo-time SECONDS' |
| 1289 | |
| 1290 | Number of seconds per (Canadian) byo-yomi period |
| 1291 | |
| 1292 | * `--byo-period STONES' |
| 1293 | |
| 1294 | Number of stones per (Canadian) byo-yomi period |
| 1295 | |
| 1296 | 3.9.6 Development options |
| 1297 | ------------------------- |
| 1298 | |
| 1299 | * `--replay COLOR' |
| 1300 | |
| 1301 | Replay all moves in a game for either or both colors. If used |
| 1302 | with the `-o' option the game record is annotated with move |
| 1303 | values. This option requires `-l FILENAME'. The color can be: |
| 1304 | * white: replay white moves only |
| 1305 | |
| 1306 | * black: replay black moves only |
| 1307 | |
| 1308 | * both: replay all moves |
| 1309 | When the move found by genmove differs from the move in the |
| 1310 | sgf file the values of both moves are reported thus: |
| 1311 | |
| 1312 | Move 13 (white): GNU Go plays C6 (20.60) - Game move F4 (20.60) |
| 1313 | |
| 1314 | This option is useful if one wants to confirm that a change |
| 1315 | such as a speedup or other optimization has not affected the |
| 1316 | behavior of the engine. Note that when several moves have the |
| 1317 | same top value (or nearly equal) the move generated is not |
| 1318 | deterministic (though it can be made deterministic by |
| 1319 | starting with the same random seed). Thus a few deviations |
| 1320 | from the move in the sgf file are to be expected. Only if the |
| 1321 | two reported values differ should we conclude that the engine |
| 1322 | plays differently from the engine which generated the sgf |
| 1323 | file. *Note Regression::. |
| 1324 | |
| 1325 | * `-a', `--allpats' |
| 1326 | |
| 1327 | Test all patterns, even those smaller in value than the |
| 1328 | largest move found so far. This should never affect GNU Go's |
| 1329 | final move, and it will make it run slower. However this can |
| 1330 | be very useful when "tuning" GNU Go. It causes both the |
| 1331 | traces and the output file (`-o') to be more informative. |
| 1332 | |
| 1333 | * `-T', `--printboard': colored display of dragons. |
| 1334 | |
| 1335 | Use rxvt, xterm or Linux Console. (*note Colored Display::) |
| 1336 | |
| 1337 | * `--showtime' |
| 1338 | |
| 1339 | Print timing information to stderr. |
| 1340 | |
| 1341 | * `-E', `--printeyes': colored display of eye spaces |
| 1342 | |
| 1343 | Use rxvt, xterm or Linux Console. (*note Colored Display::) |
| 1344 | |
| 1345 | * `-d', `--debug LEVEL' |
| 1346 | |
| 1347 | Produce debugging output. The debug level is given in |
| 1348 | hexadecimal, using the bits defined in the following table |
| 1349 | from `engine/gnugo.h'. A list of these may be produced using |
| 1350 | `--debug-flags'. Here they are in hexadecimal: |
| 1351 | |
| 1352 | DEBUG_INFLUENCE 0x0001 |
| 1353 | DEBUG_EYES 0x0002 |
| 1354 | DEBUG_OWL 0x0004 |
| 1355 | DEBUG_ESCAPE 0x0008 |
| 1356 | DEBUG_MATCHER 0x0010 |
| 1357 | DEBUG_DRAGONS 0x0020 |
| 1358 | DEBUG_SEMEAI 0x0040 |
| 1359 | DEBUG_LOADSGF 0x0080 |
| 1360 | DEBUG_HELPER 0x0100 |
| 1361 | DEBUG_READING 0x0200 |
| 1362 | DEBUG_WORMS 0x0400 |
| 1363 | DEBUG_MOVE_REASONS 0x0800 |
| 1364 | DEBUG_OWL_PERFORMANCE 0x1000 |
| 1365 | DEBUG_LIFE 0x2000 |
| 1366 | DEBUG_FILLLIB 0x4000 |
| 1367 | DEBUG_READING_PERFORMANCE 0x8000 |
| 1368 | DEBUG_SCORING 0x010000 |
| 1369 | DEBUG_AFTERMATH 0x020000 |
| 1370 | DEBUG_ATARI_ATARI 0x040000 |
| 1371 | DEBUG_READING_CACHE 0x080000 |
| 1372 | DEBUG_TERRITORY 0x100000 |
| 1373 | DEBUG_OWL_PERSISTENT_CACHE 0X200000 |
| 1374 | DEBUG_TOP_MOVES 0x400000 |
| 1375 | DEBUG_MISCELLANEOUS 0x800000 |
| 1376 | DEBUG_ORACLE_STREAM 0x1000000 |
| 1377 | |
| 1378 | These debug flags are additive. If you want to turn on both |
| 1379 | dragon and worm debugging you can use `-d0x420'. |
| 1380 | |
| 1381 | * `--debug-flags' |
| 1382 | |
| 1383 | Print the list of debug flags |
| 1384 | |
| 1385 | * `-w', `--worms' |
| 1386 | |
| 1387 | Print more information about worm data. |
| 1388 | |
| 1389 | * `-m', `--moyo LEVEL' |
| 1390 | |
| 1391 | moyo debugging, show moyo board. The LEVEL is fully |
| 1392 | documented elsewhere (*note Influential Display::). |
| 1393 | |
| 1394 | * `-b', `--benchmark NUMBER' |
| 1395 | |
| 1396 | benchmarking mode - can be used with `-l'. Causes GNU Go to |
| 1397 | play itself repeatedly, seeding the start of the game with a |
| 1398 | few random moves. This method of testing the program is |
| 1399 | largely superceded by use of the `twogtp' program. |
| 1400 | |
| 1401 | * `-S', `--statistics' |
| 1402 | |
| 1403 | Print statistics (for debugging purposes). |
| 1404 | |
| 1405 | * `-t', `--trace' |
| 1406 | |
| 1407 | Print debugging information. Use twice for more detail. |
| 1408 | |
| 1409 | * `-r', `--seed SEED' |
| 1410 | |
| 1411 | Set random number seed. This can be used to guarantee that |
| 1412 | GNU Go will make the same decisions on multiple runs through |
| 1413 | the same game. If `seed' is zero, GNU Go will play a |
| 1414 | different game each time. |
| 1415 | |
| 1416 | * `--decide-string LOCATION' |
| 1417 | |
| 1418 | Invoke the tactical reading code (*note Tactical Reading:: to |
| 1419 | decide whether the string at LOCATION can be captured, and if |
| 1420 | so, whether it can be defended. If used with `-o', this will |
| 1421 | produce a variation tree in SGF. |
| 1422 | |
| 1423 | * `--decide-owl LOCATION' |
| 1424 | |
| 1425 | Invoke the owl code (*note The Owl Code::) to decide whether |
| 1426 | the dragon at LOCATION can be captured, and whether it can be |
| 1427 | defended. If used with `-o', this will produce a variation |
| 1428 | tree in SGF. |
| 1429 | |
| 1430 | * `--decide-connection LOCATION1/LOCATION2' |
| 1431 | |
| 1432 | Decide whether dragons at LOCATION1 and LOCATION2 can be |
| 1433 | connected. Useful in connection with `-o' to write the |
| 1434 | variations to an SGF file. |
| 1435 | |
| 1436 | * `--decide-dragon-data LOCATION' |
| 1437 | |
| 1438 | Print complete information about the status of the dragon at |
| 1439 | LOCATION. |
| 1440 | |
| 1441 | * `--decide-semeai LOCATION1/LOCATION2' |
| 1442 | |
| 1443 | At LOCATION1 and LOCATION2 are adjacent dragons of the |
| 1444 | opposite color. Neither is aliveby itself, and their fate |
| 1445 | (alive, dead or seki) depends on the outcome of a semeai |
| 1446 | (capturing race). Decide what happens. Useful in connection |
| 1447 | with `-o' to write the variations to an SGF file. |
| 1448 | |
| 1449 | * `--decide-tactical-semeai LOCATION1/LOCATION2' |
| 1450 | |
| 1451 | Similar to `--decide-semeai', except that moves proposed by |
| 1452 | the owl code are not considered. |
| 1453 | |
| 1454 | * `--decide-position' |
| 1455 | |
| 1456 | Try to attack and defend every dragon with dragon.escape<6. If |
| 1457 | used with `-o', writes the variations to an sgf file. |
| 1458 | |
| 1459 | * `--decide-eye LOCATION' |
| 1460 | |
| 1461 | Evaluates the eyespace at LOCATION and prints a report. You |
| 1462 | can get more information by adding `-d0x02' to the command |
| 1463 | line. (*note Eye Local Game Values::.) |
| 1464 | |
| 1465 | * `--decide-surrounded LOCATION' |
| 1466 | |
| 1467 | A dragon is _surrounded_ if it is contained in the convex |
| 1468 | hull of its unfriendly neighbor dragons. This does not mean |
| 1469 | that it cannot escape, but it is often a good indicator that |
| 1470 | the dragon is under attack. This option draws the convex hull |
| 1471 | of the neighbor dragons and decides whether the dragon at |
| 1472 | LOCATION is surrounded. |
| 1473 | |
| 1474 | * `--decide-combination' |
| 1475 | |
| 1476 | Calls the function `atari_atari' to decide whether there |
| 1477 | exist combinations on the board. |
| 1478 | |
| 1479 | * `--score METHOD' |
| 1480 | |
| 1481 | Requires `-l' to specify which game to score and `-L' if you |
| 1482 | want to score anywhere else than at the end of the game |
| 1483 | record. METHOD can be "estimate", "finish", or "aftermath". |
| 1484 | "finish" and "aftermath" are appropriate when the game is |
| 1485 | complete, or nearly so, and both try to supply an accurate |
| 1486 | final score. Notice that if the game is not already finished |
| 1487 | it will be played out, which may take quite a long time if |
| 1488 | the game is far from complete. The "estimate" method may be |
| 1489 | used to get a quick estimate during the middle of the game. |
| 1490 | Any of these options may be combined with `--chinese-rules' |
| 1491 | if you want to use Chinese (Area) counting. |
| 1492 | |
| 1493 | If the option `-o OUTPUTFILENAME' is provided, the result |
| 1494 | will also be written as a comment in the output file. For the |
| 1495 | "finish" and "aftermath" scoring algorithms, the selfplayed |
| 1496 | moves completing the game are also stored. |
| 1497 | |
| 1498 | * finish |
| 1499 | |
| 1500 | Finish the game by selfplaying until two passes, |
| 1501 | then determine the status of all stones and compute |
| 1502 | territory. |
| 1503 | |
| 1504 | * aftermath |
| 1505 | |
| 1506 | Finish the game by selfplaying until two passes, |
| 1507 | then accurately determine status of all stones by |
| 1508 | playing out the "aftermath", i.e. playing on until |
| 1509 | all stones except ones involved in seki have become |
| 1510 | either unconditionally (in the strongest sense) |
| 1511 | alive or unconditionally dead (or captured). Slower |
| 1512 | than `--score finish', and while these algorithms |
| 1513 | usually agree, if they differ, `--score aftermath' |
| 1514 | is most likely to be correct. |
| 1515 | |
| 1516 | * `--score aftermath --capture-all-dead --chinese-rules' |
| 1517 | |
| 1518 | This combination mandates *Tromp-Taylor* scoring. The |
| 1519 | Tromp-Taylor ruleset requires the game to be played out until |
| 1520 | all dead stones are removed, then uses area (Chinese) scoring. |
| 1521 | The option `--capture-all-dead' requires the aftermath code |
| 1522 | to finish capturing all dead stones. |
| 1523 | |
| 1524 | 3.9.7 Experimental options |
| 1525 | -------------------------- |
| 1526 | |
| 1527 | Most of these are available as configure options and are described in |
| 1528 | *note Other Options::. |
| 1529 | |
| 1530 | * `--options' |
| 1531 | |
| 1532 | Print which experimental configure options were compiled into |
| 1533 | the program. |
| 1534 | |
| 1535 | * `--with-break-in' |
| 1536 | |
| 1537 | * `--without-break-in' |
| 1538 | |
| 1539 | Use or do not use the experimental break-in code. This option |
| 1540 | has no effect at level 9 or below. The break in code is |
| 1541 | enabled by default at level 10, and the only difference |
| 1542 | between levels 9 and level 10 is that the break in code is |
| 1543 | disabled at level 9. |
| 1544 | |
| 1545 | * `--cosmic-gnugo' |
| 1546 | |
| 1547 | Use center oriented influence. |
| 1548 | |
| 1549 | * `--nofusekidb' |
| 1550 | |
| 1551 | Turn off the fuseki database. |
| 1552 | |
| 1553 | * `--nofuseki' |
| 1554 | |
| 1555 | Turn off fuseki moves entirely |
| 1556 | |
| 1557 | * `--nojosekidb' |
| 1558 | |
| 1559 | Turn off the joseki database. |
| 1560 | |
| 1561 | * `--mirror' |
| 1562 | |
| 1563 | Try to play mirror go. |
| 1564 | |
| 1565 | * `--mirror-limit N' |
| 1566 | |
| 1567 | Stop mirroring when N stones are on the board. |
| 1568 | |
| 1569 | \1f |
| 1570 | File: gnugo.info, Node: Overview, Next: Analyzing, Prev: User Guide, Up: Top |
| 1571 | |
| 1572 | 4 GNU Go engine overview |
| 1573 | ************************ |
| 1574 | |
| 1575 | This chapter is an overview of the GNU Go internals. Further |
| 1576 | documentation of how any one module or routine works may be found in |
| 1577 | later chapters or comments in the source files. |
| 1578 | |
| 1579 | GNU Go starts by trying to understand the current board position as |
| 1580 | good as possible. Using the information found in this first phase, and |
| 1581 | using additional move generators, a list of candidate moves is |
| 1582 | generated. Finally, each of the candidate moves is valued according to |
| 1583 | its territorial value (including captures or life-and-death effects), |
| 1584 | and possible strategical effects (such as strengthening a weak group). |
| 1585 | |
| 1586 | Note that while GNU Go does, of course, do a lot of reading to |
| 1587 | analyze possible captures, life and death of groups etc., it does not |
| 1588 | (yet) have a fullboard lookahead. |
| 1589 | |
| 1590 | * Menu: |
| 1591 | |
| 1592 | * Examining the Position:: Gathering Information |
| 1593 | * Move Generators:: Selecting Candidate Moves |
| 1594 | * Move Valuation:: Selecting the best Move |
| 1595 | * Detailed Sequence of Events:: Outline of `genmove()'. |
| 1596 | * Roadmap:: Description of the different files. |
| 1597 | * Coding Styles:: Coding conventions. |
| 1598 | * Navigating the Source:: Navigating the Source. |
| 1599 | |
| 1600 | \1f |
| 1601 | File: gnugo.info, Node: Examining the Position, Next: Move Generators, Up: Overview |
| 1602 | |
| 1603 | 4.1 Gathering Information |
| 1604 | ========================= |
| 1605 | |
| 1606 | This is by far the most important phase in the move generation. |
| 1607 | Misunderstanding life-and-death situations can cause gross mistakes. |
| 1608 | Wrong territory estimates will lead to inaccurate move valuations. Bad |
| 1609 | judgement of weaknesses of groups make strategic mistakes likely. |
| 1610 | |
| 1611 | This information gathering is done by the function |
| 1612 | `examine_position()'. It first calls `make_worms()'. |
| 1613 | |
| 1614 | Its first steps are very simple: it identifies sets of directly |
| 1615 | connected stones, called "worms", and notes their sizes and their |
| 1616 | number of liberties. |
| 1617 | |
| 1618 | Soon after comes the most important step of the worm analysis: the |
| 1619 | tactical reading code (*note Tactical Reading::) is called for every |
| 1620 | worm. It tries to read out which worms can be captured directly, giving |
| 1621 | up as soon as a worm can reach 5 liberties. If a worm can be captured, |
| 1622 | the engine of course looks for moves defending against this capture. |
| 1623 | Also, a lot of effort is made to find virtually all moves that achieve |
| 1624 | the capture or defense of a worm. |
| 1625 | |
| 1626 | After knowing which worms are tactically stable, we can make a first |
| 1627 | picture of the balance of power across the board: the *note Influence:: |
| 1628 | code is called for the first time. |
| 1629 | |
| 1630 | This is to aid the next step, the analysis of dragons. By a "dragon" |
| 1631 | we mean a group of stones that cannot be disconnected. |
| 1632 | |
| 1633 | Naturally the first step in the responsible function `make_dragons()' |
| 1634 | is to identify these dragons, i.e. determine which worms cannot be |
| 1635 | disconnected from each other. This is partly done by patterns, but in |
| 1636 | most cases the specialized readconnect code is called. This module does |
| 1637 | a minimax search to determine whether two given worms can be connected |
| 1638 | with, resp. disconnected from each other. |
| 1639 | |
| 1640 | Then we compute various measures to determine how strong or weak any |
| 1641 | given dragon is: |
| 1642 | * A crude estimate of the number of eyes is made. |
| 1643 | |
| 1644 | * The results of the influence computations is used to see which |
| 1645 | dragons are adjacent to own territory or a moyo. |
| 1646 | |
| 1647 | * A guess is made for the potential to escape if the dragon got |
| 1648 | under attack. |
| 1649 | |
| 1650 | For those dragons that are considered weak, a life and death analysis |
| 1651 | is made (*note The Owl Code::). If two dragons next to each other are |
| 1652 | found that are both not alive, we try to resolve this situation with |
| 1653 | the semeai module. |
| 1654 | |
| 1655 | For a more detailed reference of the worm and dragon analysis (and |
| 1656 | explanations of the data structures used to store the information), see |
| 1657 | *Note Worms and Dragons::. |
| 1658 | |
| 1659 | The influence code is then called second time to make a detailed |
| 1660 | analysis of likely territory. Of course, the life-and-death status of |
| 1661 | dragons are now taken into account. |
| 1662 | |
| 1663 | The territorial results of the influence module get corrected by the |
| 1664 | break-in module. This specifically tries to analyze where an opponent |
| 1665 | could break into an alleged territory, with sequences that would be too |
| 1666 | difficult to see for the influence code. |
| 1667 | |
| 1668 | \1f |
| 1669 | File: gnugo.info, Node: Move Generators, Next: Move Valuation, Prev: Examining the Position, Up: Overview |
| 1670 | |
| 1671 | 4.2 Move Generators |
| 1672 | =================== |
| 1673 | |
| 1674 | Once we have found out all about the position it is time to generate |
| 1675 | the best move. Moves are proposed by a number of different modules |
| 1676 | called "move generators". The move generators themselves do not set the |
| 1677 | values of the moves, but enumerate justifications for them, called |
| 1678 | "move reasons". The valuation of the moves comes last, after all moves |
| 1679 | and their reasons have been generated. |
| 1680 | |
| 1681 | For a list and explanation of move reasons used in GNU Go, and how |
| 1682 | they are evaluated, see *Note Move Generation::. |
| 1683 | |
| 1684 | There are a couple of move generators that only extract data found in |
| 1685 | the previous phase, examining the position: |
| 1686 | |
| 1687 | * `worm_reasons()' |
| 1688 | |
| 1689 | Moves that have been found to capture or defend a worm are |
| 1690 | proposed as candidates. |
| 1691 | |
| 1692 | * `owl_reasons()' |
| 1693 | |
| 1694 | The status of every dragon, as it has been determined by the |
| 1695 | owl code (*note The Owl Code::) in the previous phase, is |
| 1696 | reviewed. If the status is critical, the killing or defending |
| 1697 | move gets a corresponding move reason. |
| 1698 | |
| 1699 | * `semeai_move_reasons()' |
| 1700 | |
| 1701 | Similarly as `owl_reasons', this function proposes moves |
| 1702 | relevant for semeais. |
| 1703 | |
| 1704 | * `break_in_move_reasons()' |
| 1705 | |
| 1706 | This suggests moves that have been found to break into |
| 1707 | opponent's territory by the break-in module. |
| 1708 | |
| 1709 | The following move generators do additional work: |
| 1710 | |
| 1711 | * `fuseki()' |
| 1712 | |
| 1713 | Generate a move in the early fuseki, either in an empty |
| 1714 | corner of from the fuseki database. |
| 1715 | |
| 1716 | * `shapes()' |
| 1717 | |
| 1718 | This is probably the most important move generator. It finds |
| 1719 | patterns from `patterns/patterns.db', |
| 1720 | `patterns/patterns2.db', `patterns/fuseki.db', and the joseki |
| 1721 | files in the current position. Each pattern is matched in |
| 1722 | each of the 8 possible orientations obtainable by rotation and |
| 1723 | reflection. If the pattern matches, a so called "constraint" |
| 1724 | may be tested which makes use of reading to determine if the |
| 1725 | pattern should be used in the current situation. Such |
| 1726 | constraints can make demands on number of liberties of |
| 1727 | strings, life and death status, and reading out ladders, etc. |
| 1728 | The patterns may call helper functions, which may be hand |
| 1729 | coded (in `patterns/helpers.c') or autogenerated. |
| 1730 | |
| 1731 | The patterns can be of a number of different classes with |
| 1732 | different goals. There are e.g. patterns which try to attack |
| 1733 | or defend groups, patterns which try to connect or cut |
| 1734 | groups, and patterns which simply try to make good shape. (In |
| 1735 | addition to the large pattern database called by `shapes()', |
| 1736 | pattern matching is used by other modules for different tasks |
| 1737 | throughout the program. *Note Patterns::, for a complete |
| 1738 | documentation of patterns.) |
| 1739 | |
| 1740 | * `combinations()' |
| 1741 | |
| 1742 | See if there are any combination threats or atari sequences |
| 1743 | and either propose them or defend against them. |
| 1744 | |
| 1745 | * `revise_thrashing_dragon()' |
| 1746 | |
| 1747 | This module does not directly propose move: If we are clearly |
| 1748 | ahead, and the last move played by the opponent is part of a |
| 1749 | dead dragon, we want to attack that dragon again to be on the |
| 1750 | safe side. This is done be setting the status of this |
| 1751 | "thrashing dragon" to unkown and repeating the shape move |
| 1752 | generation and move valution. |
| 1753 | |
| 1754 | * `endgame_shapes()' |
| 1755 | |
| 1756 | If no move is found with a value greater than 6.0, this |
| 1757 | module matches a set of extra patterns which are designed for |
| 1758 | the endgame. The endgame patterns can be found in |
| 1759 | `patterns/endgame.db'. |
| 1760 | |
| 1761 | * `revise_semeai()' |
| 1762 | |
| 1763 | If no move is found, this module changes the status of |
| 1764 | opponent groups involved in a semeai from `DEAD' to |
| 1765 | `UNKNOWN'. After this, genmove runs `shapes' and |
| 1766 | `endgame_shapes' again to see if a new move turns up. |
| 1767 | |
| 1768 | * `fill_liberty()' |
| 1769 | |
| 1770 | Fill a common liberty. This is only used at the end of the |
| 1771 | game. If necessary a backfilling or backcapturing move is |
| 1772 | generated. |
| 1773 | |
| 1774 | \1f |
| 1775 | File: gnugo.info, Node: Move Valuation, Next: Detailed Sequence of Events, Prev: Move Generators, Up: Overview |
| 1776 | |
| 1777 | 4.3 Move Valuation |
| 1778 | ================== |
| 1779 | |
| 1780 | After the move generation modules have run, each proposed candidate |
| 1781 | move goes through a detailed valuation by the function |
| 1782 | `review_move_reasons'. This invokes some analysis to try to turn up |
| 1783 | other move reasons that may have been missed. |
| 1784 | |
| 1785 | The most important value of a move is its territorial effect. *note |
| 1786 | Influence and Territory:: explains in detail how this is determined. |
| 1787 | |
| 1788 | This value is modified for all move reasons that cannot be expressed |
| 1789 | directly in terms of territory, such as combination attacks (where it |
| 1790 | is not clear which of several strings will get captured), strategical |
| 1791 | effects, connection moves, etc. A large set heuristics is necessary |
| 1792 | here, e.g. to avoid duplication of such values. This is explained in |
| 1793 | more detail in *note Valuation::. |
| 1794 | |
| 1795 | \1f |
| 1796 | File: gnugo.info, Node: Detailed Sequence of Events, Next: Roadmap, Prev: Move Valuation, Up: Overview |
| 1797 | |
| 1798 | 4.4 Detailed Sequence of Events |
| 1799 | =============================== |
| 1800 | |
| 1801 | First comes the sequence of events when `examine_position()' is run |
| 1802 | from `genmove()'. This is for reference only. |
| 1803 | |
| 1804 | `purge_persistent_caches()' |
| 1805 | `make_worms()': |
| 1806 | `compute_effective_sizes()' |
| 1807 | `compute_unconditional_status()' |
| 1808 | `find_worm_attacks_and_defenses()': |
| 1809 | for each attackable worm: |
| 1810 | set `worm.attack' |
| 1811 | `change_attack()' to add the attack point |
| 1812 | `find_attack_patterns()' to find a few more attacks |
| 1813 | for each defensible worm: |
| 1814 | set `worm.attack' |
| 1815 | `change_defense()' to add the defense point |
| 1816 | `find_defense_patterns()' to find a few more defense moves |
| 1817 | find additional attacks and defenses by testing all |
| 1818 | immediate liberties |
| 1819 | find higher order liberties (for each worm) |
| 1820 | find cutting stones (for each worm) |
| 1821 | improve attacks and defenses: if capturing a string defends |
| 1822 | another friendly string, or kills an unfriendly one, we |
| 1823 | add points of defense or attack. Make repairs if adjacent |
| 1824 | strings can both be attacked but not defended. |
| 1825 | find worm lunches |
| 1826 | find worm threats |
| 1827 | identify inessential worms (such as nakade stones) |
| 1828 | `compute_worm_influence()': |
| 1829 | `find_influence_patterns()' |
| 1830 | `value_influence()' |
| 1831 | `segment_influence()' |
| 1832 | `make_dragons()': |
| 1833 | `find_cuts()' |
| 1834 | `find_connections()' |
| 1835 | `make_domains()' (determine eyeshapes) |
| 1836 | `find_lunches()' (adjacent strings that can be captured) |
| 1837 | `find_half_and_false_eyes()' |
| 1838 | `eye_computations()': Compute the value of each eye space. |
| 1839 | Store its attack and defense point. |
| 1840 | `analyze_false_eye_territory()' |
| 1841 | for each dragon `compute_dragon_genus()' |
| 1842 | for each dragon `compute_escape()' and set escape route data |
| 1843 | `resegment_initial_influence()' |
| 1844 | `compute_refined_dragon_weaknesses()' (called again after owl) |
| 1845 | for each dragon `compute_crude_status()' |
| 1846 | `find_neighbor_dragons()' |
| 1847 | for each dragon compute surround status |
| 1848 | for each weak dragon run `owl_attack()' and `owl_defend()' |
| 1849 | to determine points of attack and defense |
| 1850 | for each dragon compute dragon.status |
| 1851 | for each thrashing dragon compute owl threats |
| 1852 | for each dragon compute dragon.safety |
| 1853 | `revise_inessentiality()' |
| 1854 | `semeai()': |
| 1855 | for every semeai, run `owl_analyze_semeai()' |
| 1856 | `find_moves_to_make_seki()' |
| 1857 | `identify_thrashing_dragons()' |
| 1858 | `compute_dragon_influence()': |
| 1859 | `compute_influence()' |
| 1860 | `break_territories()' (*note Break Ins::) |
| 1861 | `compute_refined_dragon_weaknesses()' |
| 1862 | |
| 1863 | Now a summary of the sequence of events during the move generation |
| 1864 | and selection phases of `genmove()', which take place after the |
| 1865 | information gathering phase has been completed: |
| 1866 | |
| 1867 | `estimate_score()' |
| 1868 | `choose_strategy()' |
| 1869 | `collect_move_reasons()': |
| 1870 | `worm_reasons()': for each attack and defense point add a move reason |
| 1871 | `semeai_reasons()': for each dragon2.semeai point add a move reason |
| 1872 | `owl_reasons()': for each owl attack and defense point add a move reason |
| 1873 | `break_in_reasons()': for each breakin found add a move reason |
| 1874 | `fuseki()' |
| 1875 | `break_mirror_go()' |
| 1876 | `shapes()': match patterns around the board (*note Patterns Overview::) |
| 1877 | `combinations()': look for moves with a double meaning and other tricks |
| 1878 | `find_double_threats()' |
| 1879 | `atari_atari()' |
| 1880 | `review_move_reasons()' |
| 1881 | if ahead and there is a thrashing dragon, consider it |
| 1882 | alive and reconsider the position |
| 1883 | `endgame_shapes()' |
| 1884 | `endgame()' |
| 1885 | if no move found yet, revisit any semeai, change status of dead opponent |
| 1886 | to alive, then run `shapes()' and `endgame_shapes()' again |
| 1887 | if no move found yet, run `fill_liberty()' |
| 1888 | |
| 1889 | \1f |
| 1890 | File: gnugo.info, Node: Roadmap, Next: Coding Styles, Prev: Detailed Sequence of Events, Up: Overview |
| 1891 | |
| 1892 | 4.5 Roadmap |
| 1893 | =========== |
| 1894 | |
| 1895 | The GNU Go engine is contained in two directories, `engine/' and |
| 1896 | `patterns/'. Code related to the user interface, reading and writing of |
| 1897 | Smart Game Format files, and testing are found in the directories |
| 1898 | `interface/', `sgf/', and `regression/'. Code borrowed from other GNU |
| 1899 | programs is contained in `utils/'. That directory also includes some |
| 1900 | code developed within GNU Go which is not go specific. Documentation is |
| 1901 | in `doc/'. |
| 1902 | |
| 1903 | In this document we will describe some of the individual files |
| 1904 | comprising the engine code in `engine/' and `patterns/'. In `interface/' |
| 1905 | we mention two files: |
| 1906 | |
| 1907 | * `gmp.c' |
| 1908 | |
| 1909 | This is the Go Modem Protocol interface (courtesy of William |
| 1910 | Shubert and others). This takes care of all the details of |
| 1911 | exchanging setup and moves with Cgoban, or any other driving |
| 1912 | program recognizing the Go Modem Protocol. |
| 1913 | |
| 1914 | * `main.c' |
| 1915 | |
| 1916 | This contains `main()'. The `gnugo' target is thus built in |
| 1917 | the `interface/' directory. |
| 1918 | |
| 1919 | 4.5.1 Files in `engine/' |
| 1920 | ------------------------ |
| 1921 | |
| 1922 | In `engine/' there are the following files: |
| 1923 | |
| 1924 | * `aftermath.c' |
| 1925 | |
| 1926 | Contains algorithms which may be called at the end of the |
| 1927 | game to generate moves that will generate moves to settle the |
| 1928 | position, if necessary playing out a position to determine |
| 1929 | exactly the status of every group on the board, which GNU Go |
| 1930 | can get wrong, particularly if there is a seki. This module is |
| 1931 | the basis for the most accurate scoring algorithm available |
| 1932 | in GNU Go. |
| 1933 | |
| 1934 | * `board.c' |
| 1935 | |
| 1936 | This file contains code for the maintenance of the board. |
| 1937 | For example it contains the important function `trymove()' |
| 1938 | which tries a move on the board, and `popgo()' which removes |
| 1939 | it by popping the move stack. At the same time vital |
| 1940 | information such as the number of liberties for each string |
| 1941 | and their location is updated incrementally. |
| 1942 | |
| 1943 | * `breakin.c' |
| 1944 | |
| 1945 | Code to detect moves which can break into supposed territory |
| 1946 | and moves to prevent this. |
| 1947 | |
| 1948 | * `cache.c' and `cache.h' |
| 1949 | |
| 1950 | As a means of speeding up reading, computed results are |
| 1951 | cached so that they can be quickly reused if the same |
| 1952 | position is encountered through e.g. another move ordering. |
| 1953 | This is implemented using a hash table. |
| 1954 | |
| 1955 | * `clock.c' and `clock.h' |
| 1956 | |
| 1957 | Clock code, including code allowing GNU Go to automatically |
| 1958 | adjust its level in order to avoid losing on time in |
| 1959 | tournaments. |
| 1960 | |
| 1961 | * `combination.c' |
| 1962 | |
| 1963 | When something can (only) be captured through a series of |
| 1964 | ataris or other threats we call this a combination attack. |
| 1965 | This file contains code to find such attacks and moves to |
| 1966 | prevent them. |
| 1967 | |
| 1968 | * `dragon.c' |
| 1969 | |
| 1970 | This contains `make_dragons()'. This function is executed |
| 1971 | before the move-generating modules `shapes()' `semeai()' and |
| 1972 | the other move generators but after `make_worms()'. It tries |
| 1973 | to connect worms into dragons and collect important |
| 1974 | information about them, such as how many liberties each has, |
| 1975 | whether (in GNU Go's opinion) the dragon can be captured, if |
| 1976 | it lives, etc. |
| 1977 | |
| 1978 | * `endgame.c' |
| 1979 | |
| 1980 | Code to find certain types of endgame moves. |
| 1981 | |
| 1982 | * `filllib.c' |
| 1983 | |
| 1984 | Code to force filling of dame (backfilling if necessary) at |
| 1985 | the end of the game. |
| 1986 | |
| 1987 | * `fuseki.c' |
| 1988 | |
| 1989 | Generates fuseki (opening) moves from a database. Also |
| 1990 | generates moves in empty corners. |
| 1991 | |
| 1992 | * `genmove.c' |
| 1993 | |
| 1994 | This file contains `genmove()' and its supporting routines, |
| 1995 | particularly `examine_position()'. |
| 1996 | |
| 1997 | * `globals.c' |
| 1998 | |
| 1999 | This contains the principal global variables used by GNU Go. |
| 2000 | |
| 2001 | * `gnugo.h' |
| 2002 | |
| 2003 | This file contains declarations forming the public interface |
| 2004 | to the engine. |
| 2005 | |
| 2006 | * `hash.c' and `hash.h' |
| 2007 | |
| 2008 | Hashing code implementing Zobrist hashing. (*note Hashing::) |
| 2009 | The code in `hash.c' provides a way to hash board positions |
| 2010 | into compact descriptions which can be efficiently compared. |
| 2011 | The caching code in `cache.c' makes use of the board hashes |
| 2012 | when storing and retrieving read results. |
| 2013 | |
| 2014 | * `influence.c' and `influence.h'. |
| 2015 | |
| 2016 | This code determines which regions of the board are under the |
| 2017 | influence of either player. (*note Influence::) |
| 2018 | |
| 2019 | * `liberty.h' |
| 2020 | |
| 2021 | Header file for the engine. The name "liberty" connotes |
| 2022 | freedom (*note Copying::). |
| 2023 | |
| 2024 | * `matchpat.c' |
| 2025 | |
| 2026 | This file contains the pattern matcher `matchpat()', which |
| 2027 | looks for patterns at a particular board location. The actual |
| 2028 | patterns are in the `patterns/' directory. The function |
| 2029 | `matchpat()' is called by every module which does pattern |
| 2030 | matching, notably `shapes'. |
| 2031 | |
| 2032 | * `move_reasons.c' and `move_reasons.h' |
| 2033 | |
| 2034 | Code for keeping track of move reasons. |
| 2035 | |
| 2036 | * `movelist.c' |
| 2037 | |
| 2038 | Supporting code for lists of moves. |
| 2039 | |
| 2040 | * `optics.c' |
| 2041 | |
| 2042 | This file contains the code to recognize eye shapes, |
| 2043 | documented in *Note Eyes::. |
| 2044 | |
| 2045 | * `oracle.c' |
| 2046 | |
| 2047 | Code to fork off a second GNU Go process which can be used to |
| 2048 | simulate reading with top level information (e.g. dragon |
| 2049 | partitioning) available. |
| 2050 | |
| 2051 | * `owl.c' |
| 2052 | |
| 2053 | This file does life and death reading. Move generation is |
| 2054 | pattern based and the code in `optics.c' is used to evaluate |
| 2055 | the eyespaces for vital moves and independent life. A dragon |
| 2056 | can also live by successfully escaping. Semeai reading along |
| 2057 | the same principles is also implemented in this file. |
| 2058 | |
| 2059 | * `persistent.c' |
| 2060 | |
| 2061 | Persistent cache which allows reuse of read results at a |
| 2062 | later move or with additional stones outside an active area, |
| 2063 | which are those intersections thought to affect the read |
| 2064 | result. |
| 2065 | |
| 2066 | * `printutils.c' |
| 2067 | |
| 2068 | Print utilities. |
| 2069 | |
| 2070 | * `readconnect.c' and `readconnect.h' |
| 2071 | |
| 2072 | This file contains code to determine whether two strings can |
| 2073 | be connected or disconnected. |
| 2074 | |
| 2075 | * `reading.c' |
| 2076 | |
| 2077 | This file contains code to determine whether any given string |
| 2078 | can be attacked or defended. *Note Tactical Reading::, for |
| 2079 | details. |
| 2080 | |
| 2081 | * `semeai.c' |
| 2082 | |
| 2083 | This file contains `semeai()', the module which detects |
| 2084 | dragons in semeai. To determine the semeai results the semeai |
| 2085 | reading in `owl.c' is used. |
| 2086 | |
| 2087 | * `sgfdecide.c' |
| 2088 | |
| 2089 | Code to generate sgf traces for various types of reading. |
| 2090 | |
| 2091 | * `shapes.c' |
| 2092 | |
| 2093 | This file contains `shapes()', the module called by |
| 2094 | `genmove()' which tries to find moves which match a pattern |
| 2095 | (*note Patterns::). |
| 2096 | |
| 2097 | * `showbord.c' |
| 2098 | |
| 2099 | This file contains `showboard()', which draws an ASCII |
| 2100 | representation of the board, depicting dragons (stones with |
| 2101 | same letter) and status (color). This was the primary |
| 2102 | interface in GNU Go 1.2, but is now a debugging aid. |
| 2103 | |
| 2104 | * `surround.c' |
| 2105 | |
| 2106 | Code to determine whether a dragon is surrounded and to find |
| 2107 | moves to surround with or break out with. |
| 2108 | |
| 2109 | * `utils.c' |
| 2110 | |
| 2111 | An assortment of utilities, described in greater detail below. |
| 2112 | |
| 2113 | * `value_moves.c' |
| 2114 | |
| 2115 | This file contains the code which assigns values to every move |
| 2116 | after all the move reasons are generated. It also tries to |
| 2117 | generate certain kinds of additional move reasons. |
| 2118 | |
| 2119 | * `worm.c' |
| 2120 | |
| 2121 | This file contains `make_worms()', code which is run at the |
| 2122 | beginning of each move cycle, before the code in `dragon.c', |
| 2123 | to determine the attributes of every string. These attributes |
| 2124 | are things like liberties, wether the string can be captured |
| 2125 | (and how), etc |
| 2126 | |
| 2127 | 4.5.2 Files in `patterns/' |
| 2128 | -------------------------- |
| 2129 | |
| 2130 | The directory `patterns/' contains files related to pattern matching. |
| 2131 | Currently there are several types of patterns. A partial list: |
| 2132 | |
| 2133 | * move generation patterns in `patterns.db' and `patterns2.db' |
| 2134 | |
| 2135 | * move generation patterns in files `hoshi.db' etc. which are |
| 2136 | automatically build from the files `hoshi.sgf' etc. These comprise |
| 2137 | our small Joseki library. |
| 2138 | |
| 2139 | * patterns in `owl_attackpats.db', `owl_defendpats.db' and |
| 2140 | `owl_vital_apats.db'. These generate moves for the owl code (*note |
| 2141 | The Owl Code::). |
| 2142 | |
| 2143 | * Connection patterns in `conn.db' (*note Connections Database::) |
| 2144 | |
| 2145 | * Influence patterns in `influence.db' and `barriers.db' (*note |
| 2146 | Influence::) |
| 2147 | |
| 2148 | * eye patterns in `eyes.db' (*note Eyes::). |
| 2149 | |
| 2150 | The following list contains, in addition to distributed source files |
| 2151 | some intermediate automatically generated files such as `patterns.c'. |
| 2152 | These are C source files produced by "compiling" various pattern |
| 2153 | databases, or in some cases (such as `hoshi.db') themselves |
| 2154 | automatically generated pattern databases produced by "compiling" |
| 2155 | joseki files in Smart Game Format. |
| 2156 | |
| 2157 | * `conn.db' |
| 2158 | |
| 2159 | Database of connection patterns. |
| 2160 | |
| 2161 | * `conn.c' |
| 2162 | |
| 2163 | Automatically generated file, containing connection patterns |
| 2164 | in form of struct arrays, compiled by `mkpat' from `conn.db'. |
| 2165 | |
| 2166 | * `eyes.c' |
| 2167 | |
| 2168 | Automatically generated file, containing eyeshape patterns in |
| 2169 | form of struct arrays, compiled by `mkpat' from `eyes.db'. |
| 2170 | |
| 2171 | * `eyes.h' |
| 2172 | |
| 2173 | Header file for `eyes.c'. |
| 2174 | |
| 2175 | * `eyes.db' |
| 2176 | |
| 2177 | Database of eyeshape patterns. *Note Eyes::, for details. |
| 2178 | |
| 2179 | * `helpers.c' |
| 2180 | |
| 2181 | These are helper functions to assist in evaluating moves by |
| 2182 | matchpat. |
| 2183 | |
| 2184 | * `hoshi.sgf' |
| 2185 | |
| 2186 | Smart Game Format file containing 4-4 point openings |
| 2187 | |
| 2188 | * `hoshi.db' |
| 2189 | |
| 2190 | Automatically generated database of 4-4 point opening |
| 2191 | patterns, make by compiling `hoshi.sgf' |
| 2192 | |
| 2193 | * `joseki.c' |
| 2194 | |
| 2195 | Joseki compiler, which takes a joseki file in Smart Game |
| 2196 | Format, and produces a pattern database. |
| 2197 | |
| 2198 | * `komoku.sgf' |
| 2199 | |
| 2200 | Smart Game Format file containing 3-4 point openings |
| 2201 | |
| 2202 | * `komoku.db' |
| 2203 | |
| 2204 | Automatically generated database of 3-4 point opening |
| 2205 | patterns, make by compiling `komoku.sgf' |
| 2206 | |
| 2207 | * `mkeyes.c' |
| 2208 | |
| 2209 | Pattern compiler for the eyeshape databases. This program |
| 2210 | takes `eyes.db' as input and produces `eyes.c' as output. |
| 2211 | |
| 2212 | * `mkpat.c' |
| 2213 | |
| 2214 | Pattern compiler for the move generation and connection |
| 2215 | databases. Takes the file `patterns.db' together with the |
| 2216 | autogenerated Joseki pattern files `hoshi.db', `komoku.db', |
| 2217 | `sansan.db', `mokuhadzushi.db', `takamoku.db' and produces |
| 2218 | `patterns.c', or takes `conn.db' and produces `conn.c'. |
| 2219 | |
| 2220 | * `mokuhazushi.sgf' |
| 2221 | |
| 2222 | Smart Game Format file containing 5-3 point openings |
| 2223 | |
| 2224 | * `mokuhazushi.db' |
| 2225 | |
| 2226 | Pattern database compiled from mokuhadzushi.sgf |
| 2227 | |
| 2228 | * `sansan.sgf' |
| 2229 | |
| 2230 | Smart Game Format file containing 3-3 point openings |
| 2231 | |
| 2232 | * `sansan.db' |
| 2233 | |
| 2234 | Pattern database compiled from `sansan.sgf' |
| 2235 | |
| 2236 | * `takamoku.sgf' |
| 2237 | |
| 2238 | Smart Game Format file containing 5-4 point openings |
| 2239 | |
| 2240 | * `takamoku.db' |
| 2241 | |
| 2242 | Pattern database compiled from takamoku.sgf. |
| 2243 | |
| 2244 | * `patterns.c' |
| 2245 | |
| 2246 | Pattern data, compiled from patterns.db by mkpat. |
| 2247 | |
| 2248 | * `patterns.h' |
| 2249 | |
| 2250 | Header file relating to the pattern databases. |
| 2251 | |
| 2252 | * `patterns.db' and `patterns2.db' |
| 2253 | |
| 2254 | These contain pattern databases in human readable form. |
| 2255 | |
| 2256 | |
| 2257 | \1f |
| 2258 | File: gnugo.info, Node: Coding Styles, Next: Navigating the Source, Prev: Roadmap, Up: Overview |
| 2259 | |
| 2260 | 4.6 Coding styles and conventions |
| 2261 | ================================= |
| 2262 | |
| 2263 | 4.6.1 Coding Conventions |
| 2264 | ------------------------ |
| 2265 | |
| 2266 | Please follow the coding conventions at: |
| 2267 | `http://www.gnu.org/prep/standards_toc.html' |
| 2268 | |
| 2269 | Please preface every function with a brief description of its usage. |
| 2270 | |
| 2271 | Please help to keep this Texinfo documentation up-to-date. |
| 2272 | |
| 2273 | 4.6.2 Tracing |
| 2274 | ------------- |
| 2275 | |
| 2276 | A function `gprintf()' is provided. It is a cut-down `printf', |
| 2277 | supporting only `%c', `%d', `%s', and without field widths, etc. It |
| 2278 | does, however, add some useful facilities: |
| 2279 | |
| 2280 | * `%m' |
| 2281 | |
| 2282 | Takes two parameters, and displays a formatted board |
| 2283 | co-ordinate. |
| 2284 | |
| 2285 | * indentation |
| 2286 | |
| 2287 | Trace messages are automatically indented to reflect the |
| 2288 | current stack depth, so it is clear during read-ahead when it |
| 2289 | puts a move down or takes one back. |
| 2290 | |
| 2291 | * "outdent" |
| 2292 | |
| 2293 | As a workaround, `%o' at the beginning of the: format string |
| 2294 | suppresses the indentation. |
| 2295 | |
| 2296 | Normally `gprintf()' is wrapped in one of the following: |
| 2297 | |
| 2298 | `TRACE(fmt, ...)': |
| 2299 | |
| 2300 | Print the message if the 'verbose' variable > 0. (verbose is set |
| 2301 | by `-t' on the command line) |
| 2302 | |
| 2303 | `DEBUG(flags, fmt, ...)': |
| 2304 | |
| 2305 | While `TRACE' is intended to afford an overview of what GNU Go is |
| 2306 | considering, `DEBUG' allows occasional in depth study of a module, |
| 2307 | usually needed when something goes wrong. `flags' is one of the |
| 2308 | `DEBUG_*' symbols in `engine/gnugo.h'. The `DEBUG' macro tests to |
| 2309 | see if that bit is set in the `debug' variable, and prints the |
| 2310 | message if it is. The debug variable is set using the `-d' |
| 2311 | command-line option. |
| 2312 | |
| 2313 | The variable `verbose' controls the tracing. It can equal 0 (no |
| 2314 | trace), 1, 2, 3 or 4 for increasing levels of tracing. You can set the |
| 2315 | trace level at the command line by `-t' for `verbose=1', `-t -t' for |
| 2316 | `verbose=2', etc. But in practice if you want more verbose tracing than |
| 2317 | level 1 it is better to use GDB to reach the point where you want the |
| 2318 | tracing; you will often find that the variable `verbose' has been |
| 2319 | temporarily set to zero and you can use the GDB command `set var |
| 2320 | verbose=1' to turn the tracing back on. |
| 2321 | |
| 2322 | 4.6.3 Assertions |
| 2323 | ---------------- |
| 2324 | |
| 2325 | Related to tracing are assertions. Developers are strongly encouraged |
| 2326 | to pepper their code with assertions to ensure that data structures are |
| 2327 | as they expect. For example, the helper functions make assertions about |
| 2328 | the contents of the board in the vicinity of the move they are |
| 2329 | evaluating. |
| 2330 | |
| 2331 | `ASSERT()' is a wrapper around the standard C `assert()' function. |
| 2332 | In addition to the test, it takes an extra pair of parameters which are |
| 2333 | the co-ordinates of a "relevant" board position. If an assertion fails, |
| 2334 | the board position is included in the trace output, and `showboard()' |
| 2335 | and `popgo()' are called to unwind and display the stack. |
| 2336 | |
| 2337 | 4.6.4 FIXME |
| 2338 | ----------- |
| 2339 | |
| 2340 | We have adopted the convention of putting the word FIXME in comments to |
| 2341 | denote known bugs, etc. |
| 2342 | |
| 2343 | \1f |
| 2344 | File: gnugo.info, Node: Navigating the Source, Prev: Coding Styles, Up: Overview |
| 2345 | |
| 2346 | 4.7 Navigating the Source |
| 2347 | ========================= |
| 2348 | |
| 2349 | If you are using Emacs, you may find it fast and convenient to use |
| 2350 | Emacs' built-in facility for navigating the source. Switch to the root |
| 2351 | directory `gnugo-3.6/' and execute the command: |
| 2352 | |
| 2353 | find . -print|grep "\.[ch]$" | xargs etags |
| 2354 | |
| 2355 | This will build a file called `gnugo-3.6/TAGS'. Now to find any GNU |
| 2356 | Go function, type `M-.' and enter the command which you wish to find, |
| 2357 | or just `RET' if the cursor is at the name of the function sought. |
| 2358 | |
| 2359 | The first time you do this you will be prompted for the location of |
| 2360 | the TAGS table. Enter the path to `gnugo-3.6/TAGS', and henceforth you |
| 2361 | will be able to find any function with a minimum of keystrokes. |
| 2362 | |
| 2363 | \1f |
| 2364 | File: gnugo.info, Node: Analyzing, Next: Move Generation, Prev: Overview, Up: Top |
| 2365 | |
| 2366 | 5 Analyzing GNU Go's moves |
| 2367 | ************************** |
| 2368 | |
| 2369 | In this chapter we will discuss methods of finding out how GNU Go |
| 2370 | understands a given position. These methods will be of interest to |
| 2371 | anyone working on the program, or simply curious about its workings. |
| 2372 | |
| 2373 | In practice, most tuning of GNU Go is done in conjunction with |
| 2374 | maintaining the `regression/' directory (*note Regression::). |
| 2375 | |
| 2376 | We assume that you have a game GNU Go played saved as an sgf file, |
| 2377 | and you want to know why it made a certain move. |
| 2378 | |
| 2379 | * Menu: |
| 2380 | |
| 2381 | * Traces:: Analyzing traces in GNU Go 3.6 |
| 2382 | * Output File:: The Output File |
| 2383 | * Decide string:: Checking the reading code |
| 2384 | * Decide dragon:: Checking the owl code |
| 2385 | * GTP and GDB techniques:: GTP and GDB techniques |
| 2386 | * view.pike:: Debugging on a Graphic Board |
| 2387 | * Scoring:: Finding out the winner of the game |
| 2388 | * Colored Display:: Colored Display |
| 2389 | |
| 2390 | \1f |
| 2391 | File: gnugo.info, Node: Traces, Next: Output File, Up: Analyzing |
| 2392 | |
| 2393 | 5.1 Interpreting Traces |
| 2394 | ======================= |
| 2395 | |
| 2396 | A quick way to find out roughly the reason for a move is to run |
| 2397 | |
| 2398 | gnugo -l FILENAME -t -L MOVE NUMBER |
| 2399 | |
| 2400 | (You may also want to add `--quiet' to suppress the copyright |
| 2401 | message.) In GNU Go 3.6, the moves together with their reasons are |
| 2402 | listed, followed by a numerical analysis of the values given to each |
| 2403 | move. |
| 2404 | |
| 2405 | If you are tuning (*note Tuning::) you may want to add the `-a' |
| 2406 | option. This causes GNU Go to report all patterns matched, even ones |
| 2407 | that cannot affect the outcome of the move. The reasons for doing this |
| 2408 | is that you may want to modify a pattern already matched instead of |
| 2409 | introducing a new one. |
| 2410 | |
| 2411 | If you use the `-w' option, GNU Go will report the statuses of worms |
| 2412 | and dragons around the board. This type of information is available by |
| 2413 | different methods, however (*note view.pike::, *note Colored Display::). |
| 2414 | |
| 2415 | \1f |
| 2416 | File: gnugo.info, Node: Output File, Next: Decide string, Prev: Traces, Up: Analyzing |
| 2417 | |
| 2418 | 5.2 The Output File |
| 2419 | =================== |
| 2420 | |
| 2421 | If GNU Go is invoked with the option `-o filename' it will produce an |
| 2422 | output file. This option can be added at the command line in the Go |
| 2423 | Modem Protocol Setup Window of CGoban. The output file will show the |
| 2424 | locations of the moves considered and their weights. It is worth noting |
| 2425 | that by enlarging the CGoban window to its fullest size it can display |
| 2426 | 3 digit numbers. Dragons with status `DEAD' are labelled with an `X', |
| 2427 | and dragons with status `CRITICAL' are labelled with a `!'. |
| 2428 | |
| 2429 | If you have a game file which is not commented this way, or which |
| 2430 | was produced by a non-current version of GNU Go you may ask GNU Go to |
| 2431 | produce a commented version by running: |
| 2432 | |
| 2433 | gnugo --quiet -l <old file> --replay <color> -o <new file> |
| 2434 | |
| 2435 | Here <color> can be 'black,' 'white' or 'both'. The replay option will |
| 2436 | also help you to find out if your current version of GNU Go would play |
| 2437 | differently than the program that created the file. |
| 2438 | |
| 2439 | \1f |
| 2440 | File: gnugo.info, Node: Decide string, Next: Decide dragon, Prev: Output File, Up: Analyzing |
| 2441 | |
| 2442 | 5.3 Checking the reading code |
| 2443 | ============================= |
| 2444 | |
| 2445 | The `--decide-string' option is used to check the tactical reading code |
| 2446 | (*note Tactical Reading::). This option takes an argument, which is a |
| 2447 | location on the board in the usual algebraic notation (e.g. |
| 2448 | `--decide-string C17'). This will tell you whether the reading code (in |
| 2449 | `engine/reading.c') believes the string can be captured, and if so, |
| 2450 | whether it believes it can be defended, which moves it finds to attack |
| 2451 | or defend the move, how many nodes it searched in coming to these |
| 2452 | conclusions. Note that when GNU Go runs normally (not with |
| 2453 | `--decide-string') the points of attack and defense are computed when |
| 2454 | `make_worms()' runs and cached in `worm.attack' and `worm.defend'. |
| 2455 | |
| 2456 | If used with an output file (`-o FILENAME') `--decide-string' will |
| 2457 | produce a variation tree showing all the variations which are |
| 2458 | considered. This is a useful way of debugging the reading code, and |
| 2459 | also of educating yourself with the way it works. The variation tree |
| 2460 | can be displayed graphically using CGoban. |
| 2461 | |
| 2462 | At each node, the comment contains some information. For example you |
| 2463 | may find a comment: |
| 2464 | |
| 2465 | |
| 2466 | attack4-B at D12 (variation 6, hash 51180fdf) |
| 2467 | break_chain D12: 0 |
| 2468 | defend3 D12: 1 G12 (trivial extension) |
| 2469 | |
| 2470 | This is to be interpreted as follows. The node in question was |
| 2471 | generated by the function `attack3()' in `engine/reading.c', which was |
| 2472 | called on the string at `D12'. The data in parentheses tell you the |
| 2473 | values of `count_variations' and `hashdata.hashval'. |
| 2474 | |
| 2475 | The second value ("hash") you probably will not need to know unless |
| 2476 | you are debugging the hash code, and we will not discuss it. But the |
| 2477 | first value ("variation") is useful when using the debugger `gdb'. You |
| 2478 | can first make an output file using the `-o' option, then walk through |
| 2479 | the reading with `gdb', and to coordinate the SGF file with the |
| 2480 | debugger, display the value of `count_variations'. Specifically, from |
| 2481 | the debugger you can find out where you are as follows: |
| 2482 | |
| 2483 | (gdb) set dump_stack() |
| 2484 | B:D13 W:E12 B:E13 W:F12 B:F11 (variation 6) |
| 2485 | |
| 2486 | If you place yourself right after the call to `trymove()' which |
| 2487 | generated the move in question, then the variation number in the SGF |
| 2488 | file should match the variation number displayed by `dump_stack()', and |
| 2489 | the move in question will be the last move played (F11 in this example). |
| 2490 | |
| 2491 | This displays the sequence of moves leading up to the variation in |
| 2492 | question, and it also prints `count_variations-1'. |
| 2493 | |
| 2494 | The second two lines tell you that from this node, the function |
| 2495 | `break_chain()' was called at D12 and returned 0 meaning that no way |
| 2496 | was found of rescuing the string by attacking an element of the |
| 2497 | surrounding chain, and the function `defend3()' was called also at D12 |
| 2498 | and returned 1, meaning that the string can be defended, and that G12 |
| 2499 | is the move that defends it. If you have trouble finding the function |
| 2500 | calls which generate these comments, try setting `sgf_dumptree=1' and |
| 2501 | setting a breakpoint in `sgf_trace'. |
| 2502 | |
| 2503 | \1f |
| 2504 | File: gnugo.info, Node: Decide dragon, Next: GTP and GDB techniques, Prev: Decide string, Up: Analyzing |
| 2505 | |
| 2506 | 5.4 Checking the Owl Code |
| 2507 | ========================= |
| 2508 | |
| 2509 | You can similarly debug the Owl code using the option |
| 2510 | `--decide-dragon'. Usage is entirely similar to `--decide-string', and |
| 2511 | it can be used similarly to produce variation trees. These should be |
| 2512 | typically much smaller than the variation trees produced by |
| 2513 | `--decide-string'. |
| 2514 | |
| 2515 | \1f |
| 2516 | File: gnugo.info, Node: GTP and GDB techniques, Next: view.pike, Prev: Decide dragon, Up: Analyzing |
| 2517 | |
| 2518 | 5.5 GTP and GDB techniques |
| 2519 | ========================== |
| 2520 | |
| 2521 | You can use the Go Text Protocol (*note GTP::) to determine the |
| 2522 | statuses of dragons and other information needed for debugging. The GTP |
| 2523 | command `dragon_data P12' will list the dragon data of the dragon at |
| 2524 | `P12' and `worm_data' will list the worm data; other GTP commands may |
| 2525 | be useful as well. |
| 2526 | |
| 2527 | You can also conveniently get such information from GDB. A |
| 2528 | suggested `.gdbinit' file may be found in *Note Debugging::. Assuming |
| 2529 | this file is loaded, you can list the dragon data with the command: |
| 2530 | |
| 2531 | (gdb) dragon P12 |
| 2532 | |
| 2533 | Similarly you can get the worm data with `worm P12'. |
| 2534 | |
| 2535 | \1f |
| 2536 | File: gnugo.info, Node: view.pike, Next: Scoring, Prev: GTP and GDB techniques, Up: Analyzing |
| 2537 | |
| 2538 | 5.6 Debugging on a Graphical Board |
| 2539 | ================================== |
| 2540 | |
| 2541 | The quickest way to analyze most positions is to use the tool |
| 2542 | `view.pike' in the `regression' directory. It can be started with a |
| 2543 | testcase specified, e.g. `pike view.pike strategy:40' or at a move in |
| 2544 | an sgf file, e.g. `pike view.pike mistake.sgf:125'. When started it |
| 2545 | shows the position on a grapical board on which it also marks |
| 2546 | information like move values, dragon status, and so on. By clicking on |
| 2547 | the board further information about the valuation of moves, contents of |
| 2548 | various data structures, and other data can be made available. |
| 2549 | |
| 2550 | Specific information on how to use `view.pike' for influence tuning |
| 2551 | can be found in *Note Influence Tuning::. |
| 2552 | |
| 2553 | \1f |
| 2554 | File: gnugo.info, Node: Scoring, Next: Colored Display, Prev: view.pike, Up: Analyzing |
| 2555 | |
| 2556 | 5.7 Scoring the game |
| 2557 | ==================== |
| 2558 | |
| 2559 | GNU Go can score the game. Normally GNU Go will report its opinion about |
| 2560 | the score at the end of the game, but if you want this information about |
| 2561 | a game stored in a file, use the `--score' option (*note Invoking GNU |
| 2562 | Go::). |
| 2563 | |
| 2564 | \1f |
| 2565 | File: gnugo.info, Node: Colored Display, Prev: Scoring, Up: Analyzing |
| 2566 | |
| 2567 | 5.8 Colored Display |
| 2568 | =================== |
| 2569 | |
| 2570 | Various colored displays of the board may be obtained in a color |
| 2571 | `xterm' or `rxvt' window. Xterm will only work if xterm is compiled |
| 2572 | with color support. If the colors are not displayed on your xterm, try |
| 2573 | `rxvt'. You may also use the Linux console. The colored display will |
| 2574 | work best if the background color is black; if this is not the case you |
| 2575 | may want to edit your `.Xdefaults' file or add the options `-bg black |
| 2576 | -fg white' to `xterm' or `rxvt'. On Mac OS X put `setenv TERM |
| 2577 | xterm-color' in your `.tcshrc' file to enable color in the terminal. |
| 2578 | |
| 2579 | 5.8.1 Dragon Display |
| 2580 | -------------------- |
| 2581 | |
| 2582 | You can get a colored ASCII display of the board in which each dragon |
| 2583 | is assigned a different letter; and the different `matcher_status' |
| 2584 | values (`ALIVE', `DEAD', `UNKNOWN', `CRITICAL') have different colors. |
| 2585 | This is very handy for debugging. Actually two diagrams are generated. |
| 2586 | The reason for this is concerns the way the matcher status is computed. |
| 2587 | The dragon_status (*note Dragons::) is computed first, then for some, |
| 2588 | but not all dragons, a more accurate owl status is computed. The |
| 2589 | matcher status is the owl status if available; otherwise it is the |
| 2590 | dragon_status. Both the dragon_status and the owl_status are displayed. |
| 2591 | The color scheme is as follows: |
| 2592 | |
| 2593 | green = alive |
| 2594 | cyan = dead |
| 2595 | red = critical |
| 2596 | yellow = unknown |
| 2597 | magenta = unchecked |
| 2598 | |
| 2599 | To get the colored display, save a game in sgf format using CGoban, |
| 2600 | or using the `-o' option with GNU Go itself. |
| 2601 | |
| 2602 | Open an `xterm' or `rxvt' window. |
| 2603 | |
| 2604 | Execute `gnugo -l [filename] -L [movenum] -T' to get the colored |
| 2605 | display. |
| 2606 | |
| 2607 | Other useful colored displays may be obtained by using instead: |
| 2608 | |
| 2609 | 5.8.2 Eye Space Display |
| 2610 | ----------------------- |
| 2611 | |
| 2612 | Instead of `-T', try this with `-E'. This gives a colored display of |
| 2613 | the eyespaces, with marginal eye spaces marked `!' (*note Eyes::). |
| 2614 | |
| 2615 | \1f |
| 2616 | File: gnugo.info, Node: Move Generation, Next: Worms and Dragons, Prev: Analyzing, Up: Top |
| 2617 | |
| 2618 | 6 Move generation |
| 2619 | ***************** |
| 2620 | |
| 2621 | * Menu: |
| 2622 | |
| 2623 | * Move generation Intro:: Introduction. |
| 2624 | * Move Reasons:: Generation of move reasons. |
| 2625 | * Move Reason Details:: Detailed Descriptions of Move Reasons |
| 2626 | * Valuation:: Valuating the moves |
| 2627 | * End Game:: Endgame move generation |
| 2628 | |
| 2629 | \1f |
| 2630 | File: gnugo.info, Node: Move generation Intro, Next: Move Reasons, Up: Move Generation |
| 2631 | |
| 2632 | 6.1 Introduction |
| 2633 | ================ |
| 2634 | |
| 2635 | GNU Go 3.0 introduced a move generation scheme substantially different |
| 2636 | from earlier versions. In particular, it was different from the method |
| 2637 | of move generation in GNU Go 2.6. |
| 2638 | |
| 2639 | In the old scheme, various move generators suggested different moves |
| 2640 | with attached values. The highest such value then decided the move. |
| 2641 | There were two important drawbacks with this scheme: |
| 2642 | |
| 2643 | * Efficient multipurpose moves could only be found by patterns which |
| 2644 | explicitly looked for certain combinations, such as a simultaneous |
| 2645 | connection and cut. There was also no good way to e.g. choose among |
| 2646 | several attacking moves. |
| 2647 | |
| 2648 | * The absolute move values were increasingly becoming harder to tune |
| 2649 | with the increasing number of patterns. They were also fairly |
| 2650 | subjective and the tuning could easily break in unexpected ways |
| 2651 | when something changed, e.g. the worm valuation. |
| 2652 | |
| 2653 | The basic idea of the new move generation scheme is that the various |
| 2654 | move generators suggest reasons for moves, e.g. that a move captures |
| 2655 | something or connects two strings, and so on. When all reasons for the |
| 2656 | different moves have been found, the valuation starts. The primary |
| 2657 | advantages are |
| 2658 | |
| 2659 | * The move reasons are objective, in contrast to the move values in |
| 2660 | the old scheme. Anyone can verify whether a suggested move reason |
| 2661 | is correct. |
| 2662 | |
| 2663 | * The centralized move valuation makes tuning easier. It also allows |
| 2664 | for style dependent tuning, e.g. how much to value influence |
| 2665 | compared to territory. Another possibility is to increase the value |
| 2666 | of safe moves in a winning position. |
| 2667 | |
| 2668 | \1f |
| 2669 | File: gnugo.info, Node: Move Reasons, Next: Move Reason Details, Prev: Move generation Intro, Up: Move Generation |
| 2670 | |
| 2671 | 6.2 Generation of move reasons |
| 2672 | ============================== |
| 2673 | |
| 2674 | Each move generator suggests a number of moves. It justifies each move |
| 2675 | suggestion with one or move "move reasons". These move reasons are |
| 2676 | collected at each intersection where the moves are suggested for later |
| 2677 | valuation. Here is a partial list of of move reasons considered by GNU |
| 2678 | Go. (The complete list may be found in `move_reasons.h'.) |
| 2679 | |
| 2680 | `ATTACK_MOVE' |
| 2681 | `DEFEND_MOVE' |
| 2682 | Attack or defend a worm. |
| 2683 | |
| 2684 | `ATTACK_THREAT_MOVE' |
| 2685 | `DEFEND_THREAT_MOVE' |
| 2686 | Threaten to attack or defend a worm. |
| 2687 | |
| 2688 | `EITHER_MOVE' |
| 2689 | A move that either achieves one goal or another (at the moment |
| 2690 | this only used for attacks on worms). |
| 2691 | |
| 2692 | `ALL_MOVE' |
| 2693 | At the moment this is used for a move that defends two worms |
| 2694 | threatened by a double attack. |
| 2695 | |
| 2696 | `CONNECT_MOVE' |
| 2697 | `CUT_MOVE' |
| 2698 | Connect or cut two worms. |
| 2699 | |
| 2700 | `ANTISUJI_MOVE' |
| 2701 | Declare an antisuji or forbidden move. |
| 2702 | |
| 2703 | `SEMEAI_MOVE' |
| 2704 | `SEMEAI_THREAT' |
| 2705 | Win or threaten to win a semeai. |
| 2706 | |
| 2707 | `EXPAND_TERRITORY_MOVE' |
| 2708 | |
| 2709 | `EXPAND_MOYO_MOVE' |
| 2710 | Move expanding our territory/moyo. These reasons are at the moment |
| 2711 | treated identically. |
| 2712 | |
| 2713 | `VITAL_EYE_MOVE' |
| 2714 | A vital point for life and death. |
| 2715 | |
| 2716 | `STRATEGIC_ATTACK_MOVE' |
| 2717 | `STRATEGIC_DEFEND_MOVE' |
| 2718 | Moves added by 'a' and 'd' class patterns (*note Pattern |
| 2719 | Classification::) which (perhaps intangibly) attack or defend a |
| 2720 | dragon. |
| 2721 | |
| 2722 | `OWL_ATTACK_MOVE' |
| 2723 | `OWL_DEFEND_MOVE' |
| 2724 | An owl attack or defense move. |
| 2725 | |
| 2726 | `OWL_ATTACK_THREAT' |
| 2727 | `OWL_DEFEND_THREAT' |
| 2728 | A threat to owl attack or defend a group. |
| 2729 | |
| 2730 | `OWL_PREVENT_THREAT' |
| 2731 | A move to remove an owl threat. |
| 2732 | |
| 2733 | `UNCERTAIN_OWL_ATTACK' |
| 2734 | `UNCERTAIN_OWL_DEFENSE' |
| 2735 | An uncertain owl attack or defense. This means that the owl code |
| 2736 | could not decide the outcome, because the owl node limit was |
| 2737 | reached. |
| 2738 | |
| 2739 | `MY_ATARI_ATARI_MOVE' |
| 2740 | A move that starts a chain of ataris, eventually leading to a |
| 2741 | capture. |
| 2742 | |
| 2743 | `YOUR_ATARI_ATARI_MOVE' |
| 2744 | A move that if played by the opponent starts a chain of ataris for |
| 2745 | the opponent, leading to capture, which is also a safe move for |
| 2746 | us. Preemptively playing such a move almost always defends the |
| 2747 | threat. |
| 2748 | |
| 2749 | The attack and defend move types can have a suffix to denote moves |
| 2750 | whose result depends on a ko, e.g. `OWL_ATTACK_MOVE_GOOD_KO'. Here |
| 2751 | `..._GOOD_KO' and `..._BAD_KO' correspond to `KO_A' and `KO_B' as |
| 2752 | explained in *note Ko::. See `engine/move_reasons.h' for the full of |
| 2753 | move reasons. |
| 2754 | |
| 2755 | *NOTICE:* Some of these are reasons for *not* playing a move. |
| 2756 | |
| 2757 | More detailed discussion of these move reasons will be found in the |
| 2758 | next section. |
| 2759 | |
| 2760 | \1f |
| 2761 | File: gnugo.info, Node: Move Reason Details, Next: Valuation, Prev: Move Reasons, Up: Move Generation |
| 2762 | |
| 2763 | 6.3 Detailed Descriptions of various Move Reasons |
| 2764 | ================================================= |
| 2765 | |
| 2766 | * Menu: |
| 2767 | |
| 2768 | * Attack and Defense:: Worm Attack and Defense |
| 2769 | * Threats to Attack or Defend:: Worm Threats |
| 2770 | * Multi Attack or Defense:: Combined Attacks and Defenses |
| 2771 | * Cutting and Connecting:: Cutting and Connecting moves |
| 2772 | * Semeai:: Semeai winning moves |
| 2773 | * Making eyes:: Vital eye moves |
| 2774 | * Antisuji moves:: Never play these! |
| 2775 | * Territorial moves:: Block or expand territory |
| 2776 | * Owl attack and defense:: Owl Attack and Defense |
| 2777 | * Combination Attacks:: Coordinated threats such as double ataris |
| 2778 | |
| 2779 | \1f |
| 2780 | File: gnugo.info, Node: Attack and Defense, Next: Threats to Attack or Defend, Up: Move Reason Details |
| 2781 | |
| 2782 | 6.3.1 Attacking and defending moves |
| 2783 | ----------------------------------- |
| 2784 | |
| 2785 | A move which tactically captures a worm is called an "attack move" and a |
| 2786 | move which saves a worm from being tactically captured is called a |
| 2787 | "defense move". It is understood that a defense move can only exist if |
| 2788 | the worm can be captured, and that a worm without defense only is |
| 2789 | attacked by moves that decrease the liberty count or perform necessary |
| 2790 | backfilling. |
| 2791 | |
| 2792 | It is important that all moves which attack or defend a certain |
| 2793 | string are found, so that the move generation can make an informed |
| 2794 | choice about how to perform a capture, or find moves which capture |
| 2795 | and/or defend several worms. |
| 2796 | |
| 2797 | Attacking and defending moves are first found in `make_worms' while |
| 2798 | it evaluates the tactical status of all worms, although this step only |
| 2799 | gives one attack and defense (if any) move per worm. Immediately after, |
| 2800 | still in `make_worms', all liberties of the attacked worms are tested |
| 2801 | for additional attack and defense moves. More indirect moves are found |
| 2802 | by `find_attack_patterns' and `find_defense_patterns', which match the |
| 2803 | A (attack) and D (defense) class patterns in `patterns/attack.db' and |
| 2804 | `patterns/defense.db' As a final step, all moves which fill some |
| 2805 | purpose at all are tested whether they additionally attacks or defends |
| 2806 | some worm. (Only unstable worms are analyzed.) |
| 2807 | |
| 2808 | \1f |
| 2809 | File: gnugo.info, Node: Threats to Attack or Defend, Next: Multi Attack or Defense, Prev: Attack and Defense, Up: Move Reason Details |
| 2810 | |
| 2811 | 6.3.2 Threats to Attack or Defend |
| 2812 | --------------------------------- |
| 2813 | |
| 2814 | A threat to attack a worm, but where the worm can be defended is used as |
| 2815 | a secondary move reason. This move reason can enhance the value of a |
| 2816 | move so that it becomes sente. A threatening move without any other |
| 2817 | justification can also be used as a ko threat. The same is true for a |
| 2818 | move that threatens defense of a worm, but where the worm can still be |
| 2819 | captured if the attacker doesn't tenuki. |
| 2820 | |
| 2821 | Threats found by the owl code are called *owl threats* and they have |
| 2822 | their own owl reasons. |
| 2823 | |
| 2824 | \1f |
| 2825 | File: gnugo.info, Node: Multi Attack or Defense, Next: Cutting and Connecting, Prev: Threats to Attack or Defend, Up: Move Reason Details |
| 2826 | |
| 2827 | 6.3.3 Multiple attack or defense moves |
| 2828 | -------------------------------------- |
| 2829 | |
| 2830 | Sometimes a move attacks at least one of a number of worms or |
| 2831 | simultaneously defends all of several worms. These moves are noted by |
| 2832 | their own move reasons. |
| 2833 | |
| 2834 | \1f |
| 2835 | File: gnugo.info, Node: Cutting and Connecting, Next: Semeai, Prev: Multi Attack or Defense, Up: Move Reason Details |
| 2836 | |
| 2837 | 6.3.4 Cutting and connecting moves |
| 2838 | ---------------------------------- |
| 2839 | |
| 2840 | Moves which connect two distinct dragons are called `connecting moves'. |
| 2841 | Moves which prevent such connections are called "cutting moves". Cutting |
| 2842 | and connecting moves are primarily found by pattern matching, the `C' |
| 2843 | and `B' class patterns. |
| 2844 | |
| 2845 | A second source of cutting and connecting moves comes from the attack |
| 2846 | and defense of cutting stones. A move which attacks a worm |
| 2847 | automatically counts as a connecting move if there are multiple dragons |
| 2848 | adjacent to the attacked worm. Similarly a defending move counts as a |
| 2849 | cutting move. The action taken when a pattern of this type is found is |
| 2850 | to induce a connect or cut move reason. |
| 2851 | |
| 2852 | When a cut or connect move reason is registered, the involved dragons |
| 2853 | are of course stored. Thus the same move may cut and/or connect several |
| 2854 | pairs of dragons. |
| 2855 | |
| 2856 | \1f |
| 2857 | File: gnugo.info, Node: Semeai, Next: Making eyes, Prev: Cutting and Connecting, Up: Move Reason Details |
| 2858 | |
| 2859 | 6.3.5 Semeai winning moves |
| 2860 | -------------------------- |
| 2861 | |
| 2862 | A move which is necessary to win a capturing race is called a "semeai |
| 2863 | move". These are similar to attacking moves, except that they involve |
| 2864 | the simultaneous attack of one worm and the defense of another. As for |
| 2865 | attack and defense moves, it's important that all moves which win a |
| 2866 | semeai are found, so an informed choice can be made between them. |
| 2867 | |
| 2868 | Semeai move reasons should be set by the semeai module. However this |
| 2869 | has not been implemented yet. One might also wish to list moves which |
| 2870 | increase the lead in a semeai race (removes ko threats) for use as |
| 2871 | secondary move reasons. Analogously if we are behind in the race. |
| 2872 | |
| 2873 | \1f |
| 2874 | File: gnugo.info, Node: Making eyes, Next: Antisuji moves, Prev: Semeai, Up: Move Reason Details |
| 2875 | |
| 2876 | 6.3.6 Making or destroying eyes |
| 2877 | ------------------------------- |
| 2878 | |
| 2879 | A move which makes a difference in the number of eyes produced from an |
| 2880 | eye space is called an "eye move". It's not necessary that the eye is |
| 2881 | critical for the life and death of the dragon in question, although it |
| 2882 | will be valued substantially higher if this is the case. As usual it's |
| 2883 | important to find all moves that change the eye count. |
| 2884 | |
| 2885 | (This is part of what eye_finder was doing. Currently it only finds |
| 2886 | one vital point for each unstable eye space.) |
| 2887 | |
| 2888 | \1f |
| 2889 | File: gnugo.info, Node: Antisuji moves, Next: Territorial moves, Prev: Making eyes, Up: Move Reason Details |
| 2890 | |
| 2891 | 6.3.7 Antisuji moves |
| 2892 | -------------------- |
| 2893 | |
| 2894 | Moves which are locally inferior or for some other reason must not be |
| 2895 | played are called "antisuji moves". These moves are generated by pattern |
| 2896 | matching. Care must be taken with this move reason as the move under no |
| 2897 | circumstances will be played. |
| 2898 | |
| 2899 | \1f |
| 2900 | File: gnugo.info, Node: Territorial moves, Next: Owl attack and defense, Prev: Antisuji moves, Up: Move Reason Details |
| 2901 | |
| 2902 | 6.3.8 Territorial moves |
| 2903 | ----------------------- |
| 2904 | |
| 2905 | Any move that increases territory gets a move reason. This is the expand |
| 2906 | territory move reason. That move reason is added by the `e' patterns in |
| 2907 | `patterns/patterns.db'. Similarly the `E' patterns attempt to generate |
| 2908 | or mitigate a moyo, which is a region of influence not yet secure |
| 2909 | territory, yet valuable. Such a pattern sets the "expand moyo" move |
| 2910 | reason. |
| 2911 | |
| 2912 | \1f |
| 2913 | File: gnugo.info, Node: Owl attack and defense, Next: Combination Attacks, Prev: Territorial moves, Up: Move Reason Details |
| 2914 | |
| 2915 | 6.3.9 Attacking and Defending Dragons |
| 2916 | ------------------------------------- |
| 2917 | |
| 2918 | Just as the tactical reading code tries to determine when a worm can be |
| 2919 | attacked or defended, the owl code tries to determine when a dragon can |
| 2920 | get two eyes and live. The function `owl_reasons()' generates the |
| 2921 | corresponding move reasons. |
| 2922 | |
| 2923 | The owl attack and owl defense move reasons are self explanatory. |
| 2924 | |
| 2925 | The owl attack threat reason is generated if owl attack on an |
| 2926 | opponent's dragon fails but the owl code determines that the dragon can |
| 2927 | be killed with two consecutive moves. The killing moves are stored in |
| 2928 | `dragon[pos].owl_attack_point' and |
| 2929 | `dragon[pos].owl_second_attack_point'. |
| 2930 | |
| 2931 | Similarly if a friendly dragon is dead but two moves can revive it, |
| 2932 | an owl defense threat move reason is generated. |
| 2933 | |
| 2934 | The prevent threat reasons are similar but with the colors reversed: |
| 2935 | if the opponent has an attack threat move then a move which removes the |
| 2936 | threat gets a prevent threat move reason. |
| 2937 | |
| 2938 | The owl uncertain move reasons are generated when the owl code runs |
| 2939 | out of nodes. In order to prevent the owl code from running too long, a |
| 2940 | cap is put on the number of nodes one owl read can generate. If this is |
| 2941 | exceeded, the reading is cut short and the result is cached as usual, |
| 2942 | but marked uncertain. In this case an owl uncertain move reason may be |
| 2943 | generated. For example, if the owl code finds the dragon alive but is |
| 2944 | unsure, a move to defend may still be generated. |
| 2945 | |
| 2946 | \1f |
| 2947 | File: gnugo.info, Node: Combination Attacks, Prev: Owl attack and defense, Up: Move Reason Details |
| 2948 | |
| 2949 | 6.3.10 Combination Attacks |
| 2950 | -------------------------- |
| 2951 | |
| 2952 | The function `atari_atari' tries to find a sequence of ataris |
| 2953 | culminating in an unexpected change of status of any opponent string, |
| 2954 | from `ALIVE' to `CRITICAL'. Once such a sequence of ataris is found, it |
| 2955 | tries to shorten it by rejecting irrelevant moves. |
| 2956 | |
| 2957 | \1f |
| 2958 | File: gnugo.info, Node: Valuation, Next: End Game, Prev: Move Reason Details, Up: Move Generation |
| 2959 | |
| 2960 | 6.4 Valuation of suggested moves |
| 2961 | ================================ |
| 2962 | |
| 2963 | At the end of the move generation process, the function |
| 2964 | `value_move_reasons()' tries to assign values to the moves for the |
| 2965 | purpose of selecting the best move. The single purpose of the move |
| 2966 | valuation is to try to rank the moves so that the best move gets the |
| 2967 | highest score. In principle these values could be arbitrary, but in |
| 2968 | order to make it easier to evaluate how well the valuation performs, |
| 2969 | not to mention simplify the tuning, we try to assign values which are |
| 2970 | consistent with the usual methods of counting used by human Go players, |
| 2971 | as explained for example in _The Endgame_ by Ogawa and Davies. |
| 2972 | |
| 2973 | Moves are valued with respect to four different criteria. These are |
| 2974 | |
| 2975 | * territorial value |
| 2976 | |
| 2977 | * strategical value |
| 2978 | |
| 2979 | * shape value, |
| 2980 | |
| 2981 | * secondary value. |
| 2982 | |
| 2983 | All of these are floats and should be measured in terms of actual |
| 2984 | points. |
| 2985 | |
| 2986 | The territorial value is the total change of expected territory |
| 2987 | caused by this move. This includes changes in the status of groups if |
| 2988 | the move is an attack or a defense move. |
| 2989 | |
| 2990 | Beginning with GNU Go 3.0, the influence function plays an important |
| 2991 | role in estimating territory (*note Influence and Territory::). It is |
| 2992 | used to make a guess at each intersection how likely it is that it will |
| 2993 | become black or white territory. The territorial value sums up the |
| 2994 | changes in these valuations. |
| 2995 | |
| 2996 | Strategical value is a measure of the effect the move has on the |
| 2997 | safety of all groups on the board. Typically cutting and connecting |
| 2998 | moves have their main value here. Also edge extensions, enclosing moves |
| 2999 | and moves towards the center have high strategical value. The |
| 3000 | strategical value should be the sum of a fraction of the territorial |
| 3001 | value of the involved dragons. The fraction is determined by the change |
| 3002 | in safety of the dragon. |
| 3003 | |
| 3004 | Shape value is a purely local shape analysis. An important role of |
| 3005 | this measure is to offset mistakes made by the estimation of |
| 3006 | territorial values. In open positions it's often worth sacrificing a |
| 3007 | few points of (apparent) immediate profit to make good shape. Shape |
| 3008 | value is implemented by pattern matching, the Shape patterns. |
| 3009 | |
| 3010 | Secondary value is given for move reasons which by themselves are not |
| 3011 | sufficient to play the move. One example is to reduce the number of |
| 3012 | eyes for a dragon that has several or to attack a defenseless worm. |
| 3013 | |
| 3014 | When all these values have been computed, they are summed, possibly |
| 3015 | weighted (secondary value should definitely have a small weight), into |
| 3016 | a final move value. This value is used to decide the move. |
| 3017 | |
| 3018 | * Menu: |
| 3019 | |
| 3020 | * Territorial value:: How much territory does a move gain |
| 3021 | * Strategical value:: Strategical gains from a move |
| 3022 | * Shape factor:: Local shape |
| 3023 | * Minimum Value:: Minimum value |
| 3024 | * Secondary Value:: Other, more indirect, gains from a move |
| 3025 | * Threats and Followup Value:: Valuation of attack and defense threats |
| 3026 | |
| 3027 | \1f |
| 3028 | File: gnugo.info, Node: Territorial value, Next: Strategical value, Up: Valuation |
| 3029 | |
| 3030 | 6.4.1 Territorial Value |
| 3031 | ----------------------- |
| 3032 | |
| 3033 | The algorithm for computing territorial value is in the function |
| 3034 | `estimate_territorial_value'. As the name suggests, it seeks to |
| 3035 | estimate the change in territory. |
| 3036 | |
| 3037 | It considers all groups that are changed from alive to death or |
| 3038 | vice-versa due to this move. Also, it makes an assumption whether the |
| 3039 | move should be considered safe. If so, the influence module is called: |
| 3040 | The function `influence_delta_territory' estimates the territorial |
| 3041 | effect of both the stone played and of the changes of group status'. |
| 3042 | |
| 3043 | The result returned by the influence module is subject to a number of |
| 3044 | corrections. This is because some move reasons cannot be evaluated by a |
| 3045 | single call to the influence function, such as moves depending on a ko. |
| 3046 | |
| 3047 | \1f |
| 3048 | File: gnugo.info, Node: Strategical value, Next: Shape factor, Prev: Territorial value, Up: Valuation |
| 3049 | |
| 3050 | 6.4.2 Strategical Value |
| 3051 | ----------------------- |
| 3052 | |
| 3053 | Strategical defense or attack reasons are assigned to any move which |
| 3054 | matches a pattern of type `a' or `d'. These are moves which in some |
| 3055 | (often intangible) way tend to help strengthen or weaken a dragon. Of |
| 3056 | course strengthening a dragon which is already alive should not be |
| 3057 | given much value, but when the move reason is generated it is not |
| 3058 | necessary to check its status or safety. This is done later, during the |
| 3059 | valuation phase. |
| 3060 | |
| 3061 | \1f |
| 3062 | File: gnugo.info, Node: Shape factor, Next: Minimum Value, Prev: Strategical value, Up: Valuation |
| 3063 | |
| 3064 | 6.4.3 Shape Factor |
| 3065 | ------------------ |
| 3066 | |
| 3067 | In the value field of a pattern (*note Pattern Values::) one may |
| 3068 | specify a shape value. |
| 3069 | |
| 3070 | This is used to compute the shape factor, which multiplies the score |
| 3071 | of a move. We take the largest positive contribution to shape and add 1 |
| 3072 | for each additional positive contribution found. Then we take the |
| 3073 | largest negative contribution to shape, and add 1 for each additional |
| 3074 | negative contribution. The resulting number is raised to the power 1.05 |
| 3075 | to obtain the shape factor. |
| 3076 | |
| 3077 | The rationale behind this complicated scheme is that every shape |
| 3078 | point is very significant. If two shape contributions with values (say) |
| 3079 | 5 and 3 are found, the second contribution should be devalued to 1. |
| 3080 | Otherwise the engine is too difficult to tune since finding multiple |
| 3081 | contributions to shape can cause significant overvaluing of a move. |
| 3082 | |
| 3083 | \1f |
| 3084 | File: gnugo.info, Node: Minimum Value, Next: Secondary Value, Prev: Shape factor, Up: Valuation |
| 3085 | |
| 3086 | 6.4.4 Minimum Value |
| 3087 | ------------------- |
| 3088 | |
| 3089 | A pattern may assign a minimum (and sometimes also a maximum) value. |
| 3090 | For example the Joseki patterns have values which are prescribed in |
| 3091 | this way, or ones with a `value' field. One prefers not to use this |
| 3092 | approach but in practice it is sometimes needed. |
| 3093 | |
| 3094 | In the fuseki, there are often several moves with identical minimum |
| 3095 | value. GNU Go chooses randomly between such moves, which ensures some |
| 3096 | indeterminacy of GNU Go's play. Later in the game, GNU Go's genuine |
| 3097 | valuation of such a move is used as a secondary criterion. |
| 3098 | |
| 3099 | \1f |
| 3100 | File: gnugo.info, Node: Secondary Value, Next: Threats and Followup Value, Prev: Minimum Value, Up: Valuation |
| 3101 | |
| 3102 | 6.4.5 Secondary Value |
| 3103 | --------------------- |
| 3104 | |
| 3105 | Secondary move reasons are weighed very slightly. Such a move can tip |
| 3106 | the scales if all other factors are equal. |
| 3107 | |
| 3108 | \1f |
| 3109 | File: gnugo.info, Node: Threats and Followup Value, Prev: Secondary Value, Up: Valuation |
| 3110 | |
| 3111 | 6.4.6 Threats and Followup Value |
| 3112 | -------------------------------- |
| 3113 | |
| 3114 | Followup value refers to value which may acrue if we get two moves in a |
| 3115 | row in a local area. It is assigned for moves that threaten to attack |
| 3116 | or defend a worm or dragon. Also, since GNU Go 3.2 the influence module |
| 3117 | makes an assessment of the possible purely territorial followup moves. |
| 3118 | In cases where these two heuristics are not sufficient we add patterns |
| 3119 | with a `followup_value' autohelper macro. |
| 3120 | |
| 3121 | Usually, the followup value gives only a small contribution; e.g. if |
| 3122 | it the followup value is very large, then GNU Go treats the move as |
| 3123 | sente by doubling its value. However, if the largest move on the board |
| 3124 | is a ko which we cannot legally take, then such a move becomes |
| 3125 | attractive as a ko threat and the full followup value is taken into |
| 3126 | account. |
| 3127 | |
| 3128 | \1f |
| 3129 | File: gnugo.info, Node: End Game, Prev: Valuation, Up: Move Generation |
| 3130 | |
| 3131 | 6.5 End Game |
| 3132 | ============ |
| 3133 | |
| 3134 | Endgame moves are generated just like any other move by GNU Go. In fact, |
| 3135 | the concept of endgame does not exist explicitly, but if the largest |
| 3136 | move initially found is worth 6 points or less, an extra set of patterns |
| 3137 | in `endgame.db' is matched and the move valuation is redone. |
| 3138 | |
| 3139 | \1f |
| 3140 | File: gnugo.info, Node: Worms and Dragons, Next: Eyes, Prev: Move Generation, Up: Top |
| 3141 | |
| 3142 | 7 Worms and Dragons |
| 3143 | ******************* |
| 3144 | |
| 3145 | * Menu: |
| 3146 | |
| 3147 | * Worms:: Worms |
| 3148 | * Amalgamation:: How two Worms are amalgamated. |
| 3149 | * Connection:: Connections. |
| 3150 | * Half Eyes:: Half Eyes and False Eyes. |
| 3151 | * Dragons:: Union of WORMS. |
| 3152 | * Dragons in Color:: Colored display of DRAGONS. |
| 3153 | |
| 3154 | Before considering its move, GNU Go collects some data in several |
| 3155 | arrays. Two of these arrays, called `worm' and `dragon', are discussed |
| 3156 | in this document. Others are discussed in *Note Eyes::. |
| 3157 | |
| 3158 | This information is intended to help evaluate the connectedness, eye |
| 3159 | shape, escape potential and life status of each group. |
| 3160 | |
| 3161 | Later routines called by `genmove()' will then have access to this |
| 3162 | information. This document attempts to explain the philosophy and |
| 3163 | algorithms of this preliminary analysis, which is carried out by the |
| 3164 | two routines `make_worm()' and `make_dragon()' in `dragon.c'. |
| 3165 | |
| 3166 | A "worm" is a maximal set of stones on the board which are connected |
| 3167 | along the horizontal and vertical lines, and are of the same color. We |
| 3168 | often say "string" instead of worm. |
| 3169 | |
| 3170 | A "dragon" is a union of strings of the same color which will be |
| 3171 | treated as a unit. The dragons are generated anew at each move. If two |
| 3172 | strings are in the dragon, it is the computer's working hypothesis that |
| 3173 | they will live or die together and are effectively connected. |
| 3174 | |
| 3175 | The purpose of the dragon code is to allow the computer to formulate |
| 3176 | meaningful statements about life and death. To give one example, |
| 3177 | consider the following situation: |
| 3178 | |
| 3179 | OOOOO |
| 3180 | OOXXXOO |
| 3181 | OX...XO |
| 3182 | OXXXXXO |
| 3183 | OOOOO |
| 3184 | |
| 3185 | The X's here should be considered a single group with one three-space |
| 3186 | eye, but they consist of two separate strings. Thus we must amalgamate |
| 3187 | these two strings into a single dragon. Then the assertion makes sense, |
| 3188 | that playing at the center will kill or save the dragon, and is a vital |
| 3189 | point for both players. It would be difficult to formulate this |
| 3190 | statement if the X's are not perceived as a unit. |
| 3191 | |
| 3192 | The present implementation of the dragon code involves simplifying |
| 3193 | assumptions which can be refined in later implementations. |
| 3194 | |
| 3195 | \1f |
| 3196 | File: gnugo.info, Node: Worms, Next: Amalgamation, Up: Worms and Dragons |
| 3197 | |
| 3198 | 7.1 Worms |
| 3199 | ========= |
| 3200 | |
| 3201 | The array `struct worm_data worm[MAX_BOARD]' collects information about |
| 3202 | the worms. We will give definitions of the various fields. Each field |
| 3203 | has constant value at each vertex of the worm. We will define each |
| 3204 | field. |
| 3205 | |
| 3206 | |
| 3207 | struct worm_data { |
| 3208 | int color; |
| 3209 | int size; |
| 3210 | float effective_size; |
| 3211 | int origin; |
| 3212 | int liberties; |
| 3213 | int liberties2; |
| 3214 | int liberties3; |
| 3215 | int liberties4; |
| 3216 | int lunch; |
| 3217 | int cutstone; |
| 3218 | int cutstone2; |
| 3219 | int genus; |
| 3220 | int inessential; |
| 3221 | int invincible; |
| 3222 | int unconditional_status; |
| 3223 | int attack_points[MAX_TACTICAL_POINTS]; |
| 3224 | int attack_codes[MAX_TACTICAL_POINTS]; |
| 3225 | int defense_points[MAX_TACTICAL_POINTS]; |
| 3226 | int defend_codes[MAX_TACTICAL_POINTS]; |
| 3227 | int attack_threat_points[MAX_TACTICAL_POINTS]; |
| 3228 | int attack_threat_codes[MAX_TACTICAL_POINTS]; |
| 3229 | int defense_threat_points[MAX_TACTICAL_POINTS]; |
| 3230 | int defense_threat_codes[MAX_TACTICAL_POINTS]; |
| 3231 | }; |
| 3232 | |
| 3233 | * `color' |
| 3234 | |
| 3235 | The color of the worm. |
| 3236 | |
| 3237 | * `size' |
| 3238 | |
| 3239 | This field contains the cardinality of the worm. |
| 3240 | |
| 3241 | * `effective_size' |
| 3242 | |
| 3243 | This is the number of stones in a worm plus the number of |
| 3244 | empty intersections that are at least as close to this worm |
| 3245 | as to any other worm. Intersections that are shared are |
| 3246 | counted with equal fractional values for each worm. This |
| 3247 | measures the direct territorial value of capturing a worm. |
| 3248 | "effective_size" is a floating point number. Only |
| 3249 | intersections at a distance of 4 or less are counted. |
| 3250 | |
| 3251 | * `origin' |
| 3252 | |
| 3253 | Each worm has a distinguished member, called its "origin". |
| 3254 | The purpose of this field is to make it easy to determine |
| 3255 | when two vertices lie in the same worm: we compare their |
| 3256 | origin. Also if we wish to perform some test once for each |
| 3257 | worm, we simply perform it at the origin and ignore the other |
| 3258 | vertices. The origin is characterized by the test: |
| 3259 | worm[pos].origin == pos. |
| 3260 | |
| 3261 | * `liberties' |
| 3262 | |
| 3263 | * `liberties2' |
| 3264 | |
| 3265 | * `liberties3' |
| 3266 | |
| 3267 | * `liberties4' |
| 3268 | |
| 3269 | For a nonempty worm the field liberties is the number of |
| 3270 | liberties of the string. This is supplemented by |
| 3271 | `LIBERTIES2', `LIBERTIES3' and `LIBERTIES4', which are the |
| 3272 | number of second order, third order, and fourth order |
| 3273 | liberties, respectively. The definition of liberties of |
| 3274 | order >1 is adapted to the problem of detecting the shape of |
| 3275 | the surrounding empty space. In particular we want to be able |
| 3276 | to see if a group is loosely surrounded. A "liberty of order |
| 3277 | n" is an empty vertex which may be connected to the string by |
| 3278 | placing n stones of the same color on the board, but no |
| 3279 | fewer. The path of connection may pass through an intervening |
| 3280 | group of the same color. The stones placed at distance >1 may |
| 3281 | not touch a group of the opposite color. Connections through |
| 3282 | ko are not permitted. Thus in the following configuration: |
| 3283 | |
| 3284 | .XX... We label the .XX.4. |
| 3285 | XO.... liberties of XO1234 |
| 3286 | XO.... order < 5 of XO1234 |
| 3287 | ...... the O group: .12.4. |
| 3288 | .X.X.. .X.X.. |
| 3289 | |
| 3290 | The convention that liberties of order >1 may not touch a |
| 3291 | group of the opposite color means that knight's moves and one |
| 3292 | space jumps are perceived as impenetrable barriers. This is |
| 3293 | useful in determining when the string is becoming surrounded. |
| 3294 | |
| 3295 | The path may also not pass through a liberty at distance 1 if |
| 3296 | that liberty is flanked by two stones of the opposing color. |
| 3297 | This reflects the fact that the O stone is blocked from |
| 3298 | expansion to the left by the two X stones in the following |
| 3299 | situation: |
| 3300 | |
| 3301 | X. |
| 3302 | .O |
| 3303 | X. |
| 3304 | We say that n is the "distance" of the liberty of order n |
| 3305 | from the dragon. |
| 3306 | |
| 3307 | * `lunch' |
| 3308 | |
| 3309 | If nonzero, `lunch' points to a boundary worm which can be |
| 3310 | easily captured. (It does not matter whether or not the |
| 3311 | string can be defended.) |
| 3312 | |
| 3313 | We have two distinct notions of cutting stone, which we keep track |
| 3314 | of in the separate fields `worm.cutstone' and `worm.cutstone2'. We use |
| 3315 | currently use both concepts in parallel. |
| 3316 | |
| 3317 | * `cutstone' |
| 3318 | |
| 3319 | This field is equal to 2 for cutting stones, 1 for potential |
| 3320 | cutting stones. Otherwise it is zero. Definitions for this |
| 3321 | field: a "cutting stone" is one adjacent to two enemy |
| 3322 | strings, which do not have a liberty in common. The most |
| 3323 | common type of cutting string is in this situation: |
| 3324 | |
| 3325 | |
| 3326 | XO |
| 3327 | OX |
| 3328 | |
| 3329 | A "potential cutting stone" is adjacent to two enemy strings |
| 3330 | which do share a liberty. For example, X in: |
| 3331 | |
| 3332 | |
| 3333 | XO |
| 3334 | O. |
| 3335 | |
| 3336 | For cutting strings we set `worm[].cutstone=2'. For potential |
| 3337 | cutting strings we set `worm[].cutstone=1'. |
| 3338 | |
| 3339 | * `cutstone2' |
| 3340 | |
| 3341 | Cutting points are identified by the patterns in the |
| 3342 | connections database. Proper cuts are handled by the fact |
| 3343 | that attacking and defending moves also count as moves |
| 3344 | cutting or connecting the surrounding dragons. The |
| 3345 | `cutstone2' field is set during `find_cuts()', called from |
| 3346 | `make_domains()'. |
| 3347 | |
| 3348 | * `genus' |
| 3349 | |
| 3350 | There are two separate notions of "genus" for worms and |
| 3351 | dragons. The dragon notion is more important, so |
| 3352 | `dragon[pos].genus' is a far more useful field than |
| 3353 | `worm[pos].genus'. Both fields are intended as approximations |
| 3354 | to the number of eyes. The "genus" of a string is the number |
| 3355 | of connected components of its complement, minus one. It is |
| 3356 | an approximation to the number of eyes of the string. |
| 3357 | |
| 3358 | * `inessential' |
| 3359 | |
| 3360 | An "inessential" string is one which meets a criterion |
| 3361 | designed to guarantee that it has no life potential unless a |
| 3362 | particular surrounding string of the opposite color can be |
| 3363 | killed. More precisely an "inessential string" is a string S |
| 3364 | of genus zero, not adjacent to any opponent string which can |
| 3365 | be easily captured, and which has no edge liberties or second |
| 3366 | order liberties, and which satisfies the following further |
| 3367 | property: If the string is removed from the board, then the |
| 3368 | remaining cavity only borders worms of the opposite color. |
| 3369 | |
| 3370 | |
| 3371 | * `invincible' |
| 3372 | |
| 3373 | An "invincible" worm is one which GNU Go thinks cannot be |
| 3374 | captured. Invincible worms are computed by the function |
| 3375 | `unconditional_life()' which tries to find those worms of the |
| 3376 | given color that can never be captured, even if the opponent |
| 3377 | is allowed an arbitrary number of consecutive moves. |
| 3378 | |
| 3379 | * unconditional_status |
| 3380 | |
| 3381 | Unconditional status is also set by the function |
| 3382 | `unconditional_life'. This is set `ALIVE' for stones which are |
| 3383 | invincible. Stones which can not be turned invincible even if |
| 3384 | the defender is allowed an arbitrary number of consecutive |
| 3385 | moves are given an unconditional status of `DEAD'. Empty |
| 3386 | points where the opponent cannot form an invincible worm are |
| 3387 | called unconditional territory. The unconditional status is |
| 3388 | set to `WHITE_TERRITORY' or `BLACK_TERRITORY' depending on |
| 3389 | who owns the territory. Finally, if a stone can be captured |
| 3390 | but is adjacent to unconditional territory of its own color, |
| 3391 | it is also given the unconditional status `ALIVE'. In all |
| 3392 | other cases the unconditional status is `UNKNOWN'. |
| 3393 | |
| 3394 | To make sense of these definitions it is important to notice |
| 3395 | that any stone which is alive in the ordinary sense (even if |
| 3396 | only in seki) can be transformed into an invincible group by |
| 3397 | some number of consecutive moves. Well, this is not entirely |
| 3398 | true because there is a rare class of seki groups not |
| 3399 | satisfying this condition. Exactly which these are is left as |
| 3400 | an exercise for the reader. Currently `unconditional_life', |
| 3401 | which strictly follows the definitions above, calls such seki |
| 3402 | groups unconditionally dead, which of course is a misfeature. |
| 3403 | It is possible to avoid this problem by making the algorithm |
| 3404 | slightly more complex, but this is left for a later revision. |
| 3405 | |
| 3406 | * `int attack_points[MAX_TACTICAL_POINTS]' |
| 3407 | |
| 3408 | * `attack_codes[MAX_TACTICAL_POINTS]' |
| 3409 | |
| 3410 | * `int defense_points[MAX_TACTICAL_POINTS];' |
| 3411 | |
| 3412 | * `int defend_codes[MAX_TACTICAL_POINTS];' |
| 3413 | |
| 3414 | If the tactical reading code (*note Tactical Reading::) finds |
| 3415 | that the worm can be attacked, `attack_points[0]' is a point |
| 3416 | of attack, and `attack_codes[0]' is the attack code, `WIN', |
| 3417 | `KO_A' or `KO_B'. If multiple attacks are known, |
| 3418 | `attack_points[k]' and `attack_codes[k]' are used. Similarly |
| 3419 | with the defense codes and defense points. |
| 3420 | |
| 3421 | * `int attack_threat_points[MAX_TACTICAL_POINTS];' |
| 3422 | |
| 3423 | * `int attack_threat_codes[MAX_TACTICAL_POINTS];' |
| 3424 | |
| 3425 | * `int defense_threat_points[MAX_TACTICAL_POINTS];' |
| 3426 | |
| 3427 | * `int defense_threat_codes[MAX_TACTICAL_POINTS];' |
| 3428 | |
| 3429 | These are points that threaten to attack or defend a worm. |
| 3430 | |
| 3431 | The function `makeworms()' will generate data for all worms. |
| 3432 | |
| 3433 | \1f |
| 3434 | File: gnugo.info, Node: Amalgamation, Next: Connection, Prev: Worms, Up: Worms and Dragons |
| 3435 | |
| 3436 | 7.2 Amalgamation |
| 3437 | ================ |
| 3438 | |
| 3439 | A dragon, we have said, is a group of stones which are treated as a |
| 3440 | unit. It is a working hypothesis that these stones will live or die |
| 3441 | together. Thus the program will not expect to disconnect an opponent's |
| 3442 | strings if they have been amalgamated into a single dragon. |
| 3443 | |
| 3444 | The function `make_dragons()' will amalgamate worms into dragons by |
| 3445 | maintaining separate arrays `worm[]' and `dragon[]' containing similar |
| 3446 | data. Each dragon is a union of worms. Just as the data maintained in |
| 3447 | `worm[]' is constant on each worm, the data in `dragon[]' is constant |
| 3448 | on each dragon. |
| 3449 | |
| 3450 | Amalgamation of worms in GNU Go proceeds as follows. First we |
| 3451 | amalgamate all boundary components of an eyeshape. Thus in the |
| 3452 | following example: |
| 3453 | |
| 3454 | |
| 3455 | .OOOO. The four X strings are amalgamated into a |
| 3456 | OOXXO. single dragon because they are the boundary |
| 3457 | OX..XO components of a blackbordered cave. The |
| 3458 | OX..XO cave could contain an inessential string |
| 3459 | OOXXO. with no effect on this amalgamation. |
| 3460 | XXX... |
| 3461 | |
| 3462 | The code for this type of amalgamation is in the routine |
| 3463 | `dragon_eye()', discussed further in EYES. |
| 3464 | |
| 3465 | Next, we amalgamate strings which seem uncuttable. We amalgamate |
| 3466 | dragons which either share two or more common liberties, or share one |
| 3467 | liberty into the which the opponent cannot play without being captured. |
| 3468 | (ignores ko rule). |
| 3469 | |
| 3470 | |
| 3471 | X. X.X XXXX.XXX X.O |
| 3472 | .X X.X X......X X.X |
| 3473 | XXXXXX.X OXX |
| 3474 | |
| 3475 | A database of connection patterns may be found in `patterns/conn.db'. |
| 3476 | |
| 3477 | \1f |
| 3478 | File: gnugo.info, Node: Connection, Next: Half Eyes, Prev: Amalgamation, Up: Worms and Dragons |
| 3479 | |
| 3480 | 7.3 Connection |
| 3481 | ============== |
| 3482 | |
| 3483 | The fields `black_eye.cut' and `white_eye.cut' are set where the |
| 3484 | opponent can cut, and this is done by the B (break) class patterns in |
| 3485 | `conn.db'. There are two important uses for this field, which can be |
| 3486 | accessed by the autohelper functions `xcut()' and `ocut()'. The first |
| 3487 | use is to stop amalgamation in positions like |
| 3488 | |
| 3489 | |
| 3490 | ..X.. |
| 3491 | OO*OO |
| 3492 | X.O.X |
| 3493 | ..O.. |
| 3494 | |
| 3495 | where X can play at * to cut off either branch. What happens here is |
| 3496 | that first connection pattern CB1 finds the double cut and marks * as a |
| 3497 | cutting point. Later the C (connection) class patterns in conn.db are |
| 3498 | searched to find secure connections over which to amalgamate dragons. |
| 3499 | Normally a diagonal connection would be deemed secure and amalgamated |
| 3500 | by connection pattern CC101, but there is a constraint requiring that |
| 3501 | neither of the empty intersections is a cutting point. |
| 3502 | |
| 3503 | A weakness with this scheme is that X can only cut one connection, |
| 3504 | not both, so we should be allowed to amalgamate over one of the |
| 3505 | connections. This is performed by connection pattern CC401, which with |
| 3506 | the help of `amalgamate_most_valuable_helper()' decides which |
| 3507 | connection to prefer. |
| 3508 | |
| 3509 | The other use is to simplify making alternative connection patterns |
| 3510 | to the solid connection. Positions where the diag_miai helper thinks a |
| 3511 | connection is necessary are marked as cutting points by connection |
| 3512 | pattern 12. Thus we can write a connection pattern like `CC6': |
| 3513 | |
| 3514 | |
| 3515 | ?xxx? straight extension to connect |
| 3516 | XOO*? |
| 3517 | O...? |
| 3518 | |
| 3519 | :8,C,NULL |
| 3520 | |
| 3521 | ?xxx? |
| 3522 | XOOb? |
| 3523 | Oa..? |
| 3524 | |
| 3525 | ;xcut(a) && odefend_against(b,a) |
| 3526 | |
| 3527 | where we verify that a move at `*' would stop the enemy from safely |
| 3528 | playing at the cutting point, thus defending against the cut. |
| 3529 | |
| 3530 | \1f |
| 3531 | File: gnugo.info, Node: Half Eyes, Next: Dragons, Prev: Connection, Up: Worms and Dragons |
| 3532 | |
| 3533 | 7.4 Half Eyes and False Eyes |
| 3534 | ============================ |
| 3535 | |
| 3536 | A "half eye" is a place where, if the defender plays first, an eye will |
| 3537 | materialize, but where if the attacker plays first, no eye will |
| 3538 | materialize. A "false eye" is a vertex which is surrounded by a dragon |
| 3539 | yet is not an eye. Here is a half eye: |
| 3540 | |
| 3541 | |
| 3542 | XXXXX |
| 3543 | OO..X |
| 3544 | O.O.X |
| 3545 | OOXXX |
| 3546 | |
| 3547 | Here is a false eye: |
| 3548 | |
| 3549 | |
| 3550 | XXXXX |
| 3551 | XOO.X |
| 3552 | O.O.X |
| 3553 | OOXXX |
| 3554 | |
| 3555 | The "topological" algorithm for determining half and false eyes is |
| 3556 | described elsewhere (*note Eye Topology::). |
| 3557 | |
| 3558 | The half eye data is collected in the dragon array. Before this is |
| 3559 | done, however, an auxiliary array called half_eye_data is filled with |
| 3560 | information. The field `type' is 0, or else `HALF_EYE' or `FALSE_EYE' |
| 3561 | depending on which type is found; the fields `attack_point[]' point to |
| 3562 | up to 4 points to attack the half eye, and similarly `defense_point[]' |
| 3563 | gives points to defend the half eye. |
| 3564 | |
| 3565 | |
| 3566 | struct half_eye_data half_eye[MAX_BOARD]; |
| 3567 | |
| 3568 | struct half_eye_data { |
| 3569 | float value; /* Topological eye value */ |
| 3570 | int type; /* HALF_EYE or FALSE_EYE */ |
| 3571 | int num_attacks; /* Number of attacking points */ |
| 3572 | int attack_point[4]; /* The moves to attack a topological halfeye */ |
| 3573 | int num_defends; /* Number of defending points */ |
| 3574 | int defense_point[4]; /* The moves to defend a topological halfeye */ |
| 3575 | }; |
| 3576 | |
| 3577 | The array `struct half_eye_data half_eye[MAX_BOARD]' contains |
| 3578 | information about half and false eyes. If the type is `HALF_EYE' then |
| 3579 | up to four moves are recorded which can either attack or defend the |
| 3580 | eye. In rare cases the attack points could be different from the |
| 3581 | defense points. |
| 3582 | |
| 3583 | \1f |
| 3584 | File: gnugo.info, Node: Dragons, Next: Dragons in Color, Prev: Half Eyes, Up: Worms and Dragons |
| 3585 | |
| 3586 | 7.5 Dragons |
| 3587 | =========== |
| 3588 | |
| 3589 | The array `struct dragon_data dragon[MAX_BOARD]' collects information |
| 3590 | about the dragons. We will give definitions of the various fields. Each |
| 3591 | field has constant value at each vertex of the dragon. (Fields will be |
| 3592 | discussed below.) |
| 3593 | |
| 3594 | |
| 3595 | struct dragon_data { |
| 3596 | int color; /* its color */ |
| 3597 | int id; /* the index into the dragon2 array */ |
| 3598 | int origin; /* the origin of the dragon. Two vertices */ |
| 3599 | /* are in the same dragon iff they have */ |
| 3600 | /* same origin. */ |
| 3601 | int size; /* size of the dragon */ |
| 3602 | float effective_size; /* stones and surrounding spaces */ |
| 3603 | int crude_status; /* (ALIVE, DEAD, UNKNOWN, CRITICAL)*/ |
| 3604 | int status; /* best trusted status */ |
| 3605 | }; |
| 3606 | |
| 3607 | extern struct dragon_data dragon[BOARDMAX]; |
| 3608 | |
| 3609 | Other fields attached to the dragon are contained in the |
| 3610 | `dragon_data2' struct array. (Fields will be discussed below.) |
| 3611 | |
| 3612 | |
| 3613 | struct dragon_data2 { |
| 3614 | int origin; |
| 3615 | int adjacent[MAX_NEIGHBOR_DRAGONS]; |
| 3616 | int neighbors; |
| 3617 | int hostile_neighbors; |
| 3618 | int moyo_size; |
| 3619 | float moyo_territorial_value; |
| 3620 | int safety; |
| 3621 | float weakness; |
| 3622 | float weakness_pre_owl; |
| 3623 | int escape_route; |
| 3624 | struct eyevalue genus; |
| 3625 | int heye; |
| 3626 | int lunch; |
| 3627 | int surround_status; |
| 3628 | int surround_size; |
| 3629 | int semeais; |
| 3630 | int semeai_margin_of_safety; |
| 3631 | int semeai_defense_point; |
| 3632 | int semeai_defense_certain; |
| 3633 | int semeai_attack_point; |
| 3634 | int semeai_attack_certain; |
| 3635 | int owl_threat_status; |
| 3636 | int owl_status; |
| 3637 | int owl_attack_point; |
| 3638 | int owl_attack_code; |
| 3639 | int owl_attack_certain; |
| 3640 | int owl_second_attack_point; |
| 3641 | int owl_defense_point; |
| 3642 | int owl_defense_code; |
| 3643 | int owl_defense_certain; |
| 3644 | int owl_second_defense_point; |
| 3645 | int owl_attack_kworm; |
| 3646 | int owl_defense_kworm; |
| 3647 | }; |
| 3648 | |
| 3649 | extern struct dragon_data2 *dragon2; |
| 3650 | |
| 3651 | The difference between the two arrays is that the `dragon' array is |
| 3652 | indexed by the board, and there is a copy of the dragon data at every |
| 3653 | stone in the dragon, while there is only one copy of the dragon2 data. |
| 3654 | The dragons are numbered, and the `id' field of the dragon is a key |
| 3655 | into the dragon2 array. Two macros DRAGON and DRAGON2 are provided for |
| 3656 | gaining access to the two arrays. |
| 3657 | |
| 3658 | #define DRAGON2(pos) dragon2[dragon[pos].id] |
| 3659 | #define DRAGON(d) dragon[dragon2[d].origin] |
| 3660 | |
| 3661 | Thus if you know the position `pos' of a stone in the dragon you can |
| 3662 | access the dragon array directly, for example accessing the origin with |
| 3663 | `dragon[pos].origin'. However if you need a field from the dragon2 |
| 3664 | array, you can access it using the DRAGON2 macro, for example you can |
| 3665 | access its neighor dragons by |
| 3666 | |
| 3667 | for (k = 0; k < DRAGON2(pos).neighbors; k++) { |
| 3668 | int d = DRAGON2(pos).adjacent[k]; |
| 3669 | int apos = dragon2[d].origin; |
| 3670 | do_something(apos); |
| 3671 | } |
| 3672 | |
| 3673 | Similarly if you know the dragon number (which is `dragon[pos].id') |
| 3674 | then you can access the `dragon2' array directly, or you can access the |
| 3675 | `dragon' array using the DRAGON macro. |
| 3676 | |
| 3677 | Here are the definitions of each field in the `dragon' arrray. |
| 3678 | |
| 3679 | * `color' |
| 3680 | |
| 3681 | The color of the dragon. |
| 3682 | |
| 3683 | * `id' |
| 3684 | |
| 3685 | The dragon number, used as a key into the `dragon2' array. |
| 3686 | |
| 3687 | * origin |
| 3688 | |
| 3689 | The origin of the dragon is a unique particular vertex of the |
| 3690 | dragon, useful for determining when two vertices belong to |
| 3691 | the same dragon. Before amalgamation the worm origins are |
| 3692 | copied to the dragon origins. Amalgamation of two dragons |
| 3693 | amounts to changing the origin of one. |
| 3694 | |
| 3695 | * size |
| 3696 | |
| 3697 | The number of stones in the dragon. |
| 3698 | |
| 3699 | * effective size |
| 3700 | |
| 3701 | The sum of the effective sizes of the constituent worms. |
| 3702 | Remembering that vertices equidistant between two or more |
| 3703 | worms are counted fractionally in `worm.effective_size', this |
| 3704 | equals the cardinality of the dragon plus the number of empty |
| 3705 | vertices which are nearer this dragon than any other. |
| 3706 | |
| 3707 | * crude_status |
| 3708 | |
| 3709 | (ALIVE, DEAD, UNKNOWN, CRITICAL). An early measure of the life |
| 3710 | potential of the dragon. It is computed before the owl code is |
| 3711 | run and is superceded by the status as soon as that becomes |
| 3712 | available. |
| 3713 | |
| 3714 | * status |
| 3715 | |
| 3716 | The dragon status is the best measure of the dragon's health. |
| 3717 | It is computed after the owl code is run, then revised again |
| 3718 | when the semeai code is run. |
| 3719 | |
| 3720 | Here are definitions of the fields in the `dragon2' array. |
| 3721 | |
| 3722 | * origin |
| 3723 | |
| 3724 | The origin field is duplicated here. |
| 3725 | |
| 3726 | * adjacent |
| 3727 | |
| 3728 | * `adjacent[MAX_NEIGHBOR_DRAGONS]' |
| 3729 | |
| 3730 | Dragons of either color near the given one are called |
| 3731 | "neighbors". They are computed by the function |
| 3732 | `find_neighbor_dragons()'. The `dragon2.adjacent' array |
| 3733 | gives the dragon numbers of these dragons. |
| 3734 | |
| 3735 | * `neighbors' |
| 3736 | |
| 3737 | Dragons of either color near the given one are called |
| 3738 | "neighbors". They are computed by the function |
| 3739 | `find_neighbor_dragons()'. The `dragon2.adjacent' array |
| 3740 | gives the dragon numbers of these dragons. |
| 3741 | |
| 3742 | * neighbors |
| 3743 | |
| 3744 | The number of neighbor dragons. |
| 3745 | |
| 3746 | * hostile_neighbors |
| 3747 | |
| 3748 | The number of neighbor dragons of the opposite color. |
| 3749 | |
| 3750 | * moyo_size |
| 3751 | |
| 3752 | * float moyo_territorial_value |
| 3753 | |
| 3754 | The function `compute_surrounding_moyo_sizes()' assigns a |
| 3755 | size and a territorial value to the moyo around each dragon |
| 3756 | (*note Territory and Moyo::). This is the moyo size. They are |
| 3757 | recorded in these fields. |
| 3758 | |
| 3759 | * safety |
| 3760 | |
| 3761 | The dragon safety can take on one of the values |
| 3762 | - TACTICALLY_DEAD - a dragon consisting of a single worm |
| 3763 | found dead by the reading code (very reliable) |
| 3764 | |
| 3765 | - ALIVE - found alive by the owl or semeai code |
| 3766 | |
| 3767 | - STRONGLY_ALIVE - alive without much question |
| 3768 | |
| 3769 | - INVINCIBLE - definitively alive even after many tenukis |
| 3770 | |
| 3771 | - ALIVE_IN_SEKI - determined to be seki by the semeai code |
| 3772 | |
| 3773 | - CRITICAL - lives or dies depending on who moves first |
| 3774 | |
| 3775 | - DEAD - found to be dead by the owl code |
| 3776 | |
| 3777 | - INESSENTIAL - the dragon is unimportant (e.g. nakade |
| 3778 | stones) and dead |
| 3779 | |
| 3780 | * weakness |
| 3781 | |
| 3782 | * weakness_pre_owl |
| 3783 | |
| 3784 | A floating point measure of the safety of a dragon. The dragon |
| 3785 | weakness is a number between 0. and 1., higher numbers for |
| 3786 | dragons in greater need of safety. The field |
| 3787 | `weakness_pre_owl' is a preliminary computation before the |
| 3788 | owl code is run. |
| 3789 | |
| 3790 | * escape_route |
| 3791 | |
| 3792 | A measure of the dragon's potential to escape towards safety, |
| 3793 | in case it cannot make two eyes locally. Documentation may be |
| 3794 | found in *note Escape::. |
| 3795 | |
| 3796 | * struct eyevalue genus |
| 3797 | |
| 3798 | The approximate number of eyes the dragon can be expected to |
| 3799 | get. Not guaranteed to be accurate. The eyevalue struct, which |
| 3800 | is used throughout the engine, is declared thus: |
| 3801 | |
| 3802 | struct eyevalue { |
| 3803 | unsigned char a; /* # of eyes if attacker plays twice */ |
| 3804 | unsigned char b; /* # of eyes if attacker plays first */ |
| 3805 | unsigned char c; /* # of eyes if defender plays first */ |
| 3806 | unsigned char d; /* # of eyes if defender plays twice */ |
| 3807 | }; |
| 3808 | |
| 3809 | * heye |
| 3810 | |
| 3811 | Location of a half eye attached to the dragon. |
| 3812 | |
| 3813 | * lunch |
| 3814 | |
| 3815 | If nonzero, this is the location of a boundary string which |
| 3816 | can be captured. In contrast with worm lunches, a dragon |
| 3817 | lunch must be able to defend itself. |
| 3818 | |
| 3819 | * surround_status |
| 3820 | |
| 3821 | * surround_size |
| 3822 | |
| 3823 | In estimating the safety of a dragon it is useful to know if |
| 3824 | it is "surrounded". See *note Surrounded Dragons:: and the |
| 3825 | comments in `surround.c' for more information about the |
| 3826 | algorithm. Used in computing the escape_route, and also |
| 3827 | callable from patterns (currently used by CB258). |
| 3828 | |
| 3829 | * semeais |
| 3830 | |
| 3831 | * semeai_defense_point |
| 3832 | |
| 3833 | * semeai_defense_certain |
| 3834 | |
| 3835 | * semeai_attack_point |
| 3836 | |
| 3837 | * semeai_attack_certain |
| 3838 | |
| 3839 | If two dragons of opposite color both have the status CRITICAL |
| 3840 | or DEAD they are in a "semeai" (capturing race), and their |
| 3841 | status must be adjudicated by the function |
| 3842 | `owl_analyze_semeai()' in `owl.c', which attempts to |
| 3843 | determine which is alive, which dead, or if the result is |
| 3844 | seki, and whether it is important who moves first. The |
| 3845 | function `new_semeai()' in `semeai.c' attempts to revise the |
| 3846 | statuses and to generate move reasons based on these results. |
| 3847 | The field `dragon2.semeais' is nonzero if the dragon is an |
| 3848 | element of a semeai, and equals the number of semeais (seldom |
| 3849 | more than one). The semeai defense and attack points are |
| 3850 | locations the defender or attacker must move to win the |
| 3851 | semeai. The field `semeai_margin_of_safety' is intended to |
| 3852 | indicate whether the semeai is close or not but currently |
| 3853 | this field is not maintained. The fields |
| 3854 | `semeai_defense_certain' and `semeai_attack_certain' indicate |
| 3855 | that the semeai code was able to finish analysis without |
| 3856 | running out of nodes. |
| 3857 | |
| 3858 | * owl_status |
| 3859 | |
| 3860 | This is a classification similar to `dragon.crude_status', but |
| 3861 | based on the life and death reading in `owl.c'. The owl code |
| 3862 | (*note The Owl Code::) is skipped for dragons which appear |
| 3863 | safe by certain heuristics. If the owl code is not run, the |
| 3864 | owl status is `UNCHECKED'. If `owl_attack()' determines that |
| 3865 | the dragon cannot be attacked, it is classified as `ALIVE'. |
| 3866 | Otherwise, `owl_defend()' is run, and if it can be defended it |
| 3867 | is classified as `CRITICAL', and if not, as `DEAD'. |
| 3868 | |
| 3869 | * owl_attack_point |
| 3870 | |
| 3871 | If the dragon can be attacked this is the point to attack the |
| 3872 | dragon. |
| 3873 | |
| 3874 | * owl_attack_code |
| 3875 | |
| 3876 | The owl attack code, It can be WIN, KO_A, KO_B or 0 (*note |
| 3877 | Return Codes::). |
| 3878 | |
| 3879 | * owl_attack_certain |
| 3880 | |
| 3881 | The owl reading is able to finish analyzing the attack |
| 3882 | without running out of nodes. |
| 3883 | |
| 3884 | * owl_second_attack_point |
| 3885 | |
| 3886 | A second attack point. |
| 3887 | |
| 3888 | * owl_defense_point |
| 3889 | |
| 3890 | If the dragon can be defended, this is the place to play. |
| 3891 | |
| 3892 | * owl_defense_code |
| 3893 | |
| 3894 | The owl defense code, It can be WIN, KO_A, KO_B or 0 (*note |
| 3895 | Return Codes::). |
| 3896 | |
| 3897 | * owl_defense_certain |
| 3898 | |
| 3899 | The owl code is able to finish analyzing the defense without |
| 3900 | running out of nodes. |
| 3901 | |
| 3902 | * owl_second_defense_point |
| 3903 | |
| 3904 | A second owl defense point. |
| 3905 | |
| 3906 | \1f |
| 3907 | File: gnugo.info, Node: Dragons in Color, Prev: Dragons, Up: Worms and Dragons |
| 3908 | |
| 3909 | 7.6 Colored Dragon Display |
| 3910 | ========================== |
| 3911 | |
| 3912 | You can get a colored ASCII display of the board in which each dragon |
| 3913 | is assigned a different letter; and the different values of |
| 3914 | `dragon.status' values (`ALIVE', `DEAD', `UNKNOWN', `CRITICAL') have |
| 3915 | different colors. This is very handy for debugging. A second diagram |
| 3916 | shows the values of `owl.status'. If this is `UNCHECKED' the dragon is |
| 3917 | displayed in White. |
| 3918 | |
| 3919 | Save a game in sgf format using CGoban, or using the `-o' option with |
| 3920 | GNU Go itself. |
| 3921 | |
| 3922 | Open an `xterm' or `rxvt' window. You may also use the Linux |
| 3923 | console. Using the console, you may need to use "SHIFT-PAGE UP" to see |
| 3924 | the first diagram. Xterm will only work if it is compiled with color |
| 3925 | support--if you do not see the colors try `rxvt'. Make the background |
| 3926 | color black and the foreground color white. |
| 3927 | |
| 3928 | Execute: |
| 3929 | |
| 3930 | `gnugo -l [filename] -L [movenum] -T' to get the colored display. |
| 3931 | |
| 3932 | The color scheme: Green = `ALIVE'; Yellow = `UNKNOWN'; Cyan = `DEAD' |
| 3933 | and Red = `CRITICAL'. Worms which have been amalgamated into the same |
| 3934 | dragon are labelled with the same letter. |
| 3935 | |
| 3936 | Other useful colored displays may be obtained by using instead: |
| 3937 | |
| 3938 | * the option -E to display eye spaces (*note Eyes::). |
| 3939 | |
| 3940 | * the option -m 0x0180 to display territory, moyo and area (*note |
| 3941 | Territory and Moyo::). |
| 3942 | |
| 3943 | The colored displays are documented elsewhere (*note Colored |
| 3944 | Display::). |
| 3945 | |
| 3946 | \1f |
| 3947 | File: gnugo.info, Node: Eyes, Next: Patterns, Prev: Worms and Dragons, Up: Top |
| 3948 | |
| 3949 | 8 Eyes and Half Eyes |
| 3950 | ******************** |
| 3951 | |
| 3952 | The purpose of this Chapter is to describe the algorithm used in GNU Go |
| 3953 | to determine eyes. |
| 3954 | |
| 3955 | * Menu: |
| 3956 | |
| 3957 | * Local Games:: Local games |
| 3958 | * Eye Space:: Eye space |
| 3959 | * Eye Space as Local Game:: Eye space as local game |
| 3960 | * Eye Example:: An example |
| 3961 | * Graphs:: Underlying graphs |
| 3962 | * Eye Shape:: Pattern matching |
| 3963 | * Eye Local Game Values:: Pattern matching |
| 3964 | * Eye Topology:: False eyes and half eyes |
| 3965 | * Eye Topology with Ko:: False eyes and half eyes with ko |
| 3966 | * False Margins:: False margins |
| 3967 | * Eye Functions:: Functions in `optics.c' |
| 3968 | |
| 3969 | \1f |
| 3970 | File: gnugo.info, Node: Local Games, Next: Eye Space, Up: Eyes |
| 3971 | |
| 3972 | 8.1 Local games |
| 3973 | =============== |
| 3974 | |
| 3975 | The fundamental paradigm of combinatorial game theory is that games can |
| 3976 | be added and in fact form a group. If `G' and `H' are games, then `G+H' |
| 3977 | is a game in which each player on his turn has the option of playing in |
| 3978 | either move. We say that the game `G+H' is the sum of the local games |
| 3979 | `G' and `H'. |
| 3980 | |
| 3981 | Each connected eyespace of a dragon affords a local game which yields |
| 3982 | a local game tree. The score of this local game is the number of eyes |
| 3983 | it yields. Usually if the players take turns and make optimal moves, |
| 3984 | the end scores will differ by 0 or 1. In this case, the local game may |
| 3985 | be represented by a single number, which is an integer or half integer. |
| 3986 | Thus if `n(O)' is the score if `O' moves first, both players alternate |
| 3987 | (no passes) and make alternate moves, and similarly `n(X)', the game |
| 3988 | can be represented by `{n(O)|n(X)}'. Thus {1|1} is an eye, {2|1} is an |
| 3989 | eye plus a half eye, etc. |
| 3990 | |
| 3991 | The exceptional game {2|0} can occur, though rarely. We call an |
| 3992 | eyespace yielding this local game a CHIMERA. The dragon is alive if |
| 3993 | any of the local games ends up with a score of 2 or more, so {2|1} is |
| 3994 | not different from {3|1}. Thus {3|1} is NOT a chimera. |
| 3995 | |
| 3996 | Here is an example of a chimera: |
| 3997 | |
| 3998 | XXXXX |
| 3999 | XOOOX |
| 4000 | XO.OOX |
| 4001 | XX..OX |
| 4002 | XXOOXX |
| 4003 | XXXXX |
| 4004 | |
| 4005 | \1f |
| 4006 | File: gnugo.info, Node: Eye Space, Next: Eye Space as Local Game, Prev: Local Games, Up: Eyes |
| 4007 | |
| 4008 | 8.2 Eye spaces |
| 4009 | ============== |
| 4010 | |
| 4011 | In order that each eyespace be assignable to a dragon, it is necessary |
| 4012 | that all the dragons surrounding it be amalgamated (*note |
| 4013 | Amalgamation::). This is the function of `dragon_eye()'. |
| 4014 | |
| 4015 | An EYE SPACE for a black dragon is a collection of vertices adjacent |
| 4016 | to a dragon which may not yet be completely closed off, but which can |
| 4017 | potentially become eyespace. If an open eye space is sufficiently |
| 4018 | large, it will yield two eyes. Vertices at the edge of the eye space |
| 4019 | (adjacent to empty vertices outside the eye space) are called MARGINAL. |
| 4020 | |
| 4021 | Here is an example from a game: |
| 4022 | |
| 4023 | |
| 4024 | |. X . X X . . X O X O |
| 4025 | |X . . . . . X X O O O |
| 4026 | |O X X X X . . X O O O |
| 4027 | |O O O O X . O X O O O |
| 4028 | |. . . . O O O O X X O |
| 4029 | |X O . X X X . . X O O |
| 4030 | |X O O O O O O O X X O |
| 4031 | |. X X O . O X O . . X |
| 4032 | |X . . X . X X X X X X |
| 4033 | |O X X O X . X O O X O |
| 4034 | |
| 4035 | Here the `O' dragon which is surrounded in the center has open eye |
| 4036 | space. In the middle of this open eye space are three dead `X' stones. |
| 4037 | This space is large enough that O cannot be killed. We can abstract the |
| 4038 | properties of this eye shape as follows. Marking certain vertices as |
| 4039 | follows: |
| 4040 | |
| 4041 | |
| 4042 | |- X - X X - - X O X O |
| 4043 | |X - - - - - X X O O O |
| 4044 | |O X X X X - - X O O O |
| 4045 | |O O O O X - O X O O O |
| 4046 | |! . . . O O O O X X O |
| 4047 | |X O . X X X . ! X O O |
| 4048 | |X O O O O O O O X X O |
| 4049 | |- X X O - O X O - - X |
| 4050 | |X - - X - X X X X X X |
| 4051 | |O X X O X - X O O X O |
| 4052 | |
| 4053 | the shape in question has the form: |
| 4054 | |
| 4055 | |
| 4056 | !... |
| 4057 | .XXX.! |
| 4058 | |
| 4059 | The marginal vertices are marked with an exclamation point (`!'). |
| 4060 | The captured `X' stones inside the eyespace are naturally marked `X'. |
| 4061 | |
| 4062 | The precise algorithm by which the eye spaces are determined is |
| 4063 | somewhat complex. Documentation of this algorithm is in the comments in |
| 4064 | the source to the function `make_domains()' in `optics.c'. |
| 4065 | |
| 4066 | The eyespaces can be conveniently displayed using a colored ascii |
| 4067 | diagram by running `gnugo -E'. |
| 4068 | |
| 4069 | \1f |
| 4070 | File: gnugo.info, Node: Eye Space as Local Game, Next: Eye Example, Prev: Eye Space, Up: Eyes |
| 4071 | |
| 4072 | 8.3 The eyespace as local game |
| 4073 | ============================== |
| 4074 | |
| 4075 | In the abstraction, an eyespace consists of a set of vertices labelled: |
| 4076 | |
| 4077 | |
| 4078 | ! . X |
| 4079 | |
| 4080 | Tables of many eyespaces are found in the database |
| 4081 | `patterns/eyes.db'. Each of these may be thought of as a local game. |
| 4082 | The result of this game is listed after the eyespace in the form |
| 4083 | `:max,min', where `max' is the number of eyes the pattern yields if `O' |
| 4084 | moves first, while `min' is the number of eyes the pattern yields if |
| 4085 | `X' moves first. The player who owns the eye space is denoted `O' |
| 4086 | throughout this discussion. Since three eyes are no better than two, |
| 4087 | there is no attempt to decide whether the space yields two eyes or |
| 4088 | three, so max never exceeds 2. Patterns with min>1 are omitted from the |
| 4089 | table. |
| 4090 | |
| 4091 | For example, we have: |
| 4092 | |
| 4093 | Pattern 548 |
| 4094 | |
| 4095 | x |
| 4096 | xX.! |
| 4097 | |
| 4098 | :0111 |
| 4099 | |
| 4100 | Here notation is as above, except that `x' means `X' or `EMPTY'. |
| 4101 | The result of the pattern is not different if `X' has stones at these |
| 4102 | vertices or not. |
| 4103 | |
| 4104 | We may abstract the local game as follows. The two players `O' and |
| 4105 | `X' take turns moving, or either may pass. |
| 4106 | |
| 4107 | RULE 1: `O' for his move may remove any vertex marked `!' or marked |
| 4108 | `.'. |
| 4109 | |
| 4110 | RULE 2: `X' for his move may replace a `.' by an `X'. |
| 4111 | |
| 4112 | RULE 3: `X' may remove a `!'. In this case, each `.' adjacent to the |
| 4113 | `!' which is removed becomes a `!' . If an `X' adjoins the `!' which is |
| 4114 | removed, then that `X' and any which are connected to it are also |
| 4115 | removed. Any `.' which are adjacent to the removed `X''s then become |
| 4116 | `.'. |
| 4117 | |
| 4118 | Thus if `O' moves first he can transform the eyeshape in the above |
| 4119 | example to: |
| 4120 | |
| 4121 | ... or !... |
| 4122 | .XXX.! .XXX. |
| 4123 | |
| 4124 | However if `X' moves he may remove the `!' and the `.'s adjacent to |
| 4125 | the `!' become `!' themselves. Thus if `X' moves first he may transform |
| 4126 | the eyeshape to: |
| 4127 | |
| 4128 | !.. or !.. |
| 4129 | .XXX.! .XXX! |
| 4130 | |
| 4131 | NOTE: A nuance which is that after the `X:1', `O:2' exchange below, |
| 4132 | `O' is threatening to capture three X stones, hence has a half eye to |
| 4133 | the left of 2. This is subtle, and there are other such subtleties |
| 4134 | which our abstraction will not capture. Some of these at least can be |
| 4135 | dealt with by a refinements of the scheme, but we will content |
| 4136 | ourselves for the time being with a simplified model. |
| 4137 | |
| 4138 | |
| 4139 | |- X - X X - - X O X O |
| 4140 | |X - - - - - X X O O O |
| 4141 | |O X X X X - - X O O O |
| 4142 | |O O O O X - O X O O O |
| 4143 | |1 2 . . O O O O X X O |
| 4144 | |X O . X X X . 3 X O O |
| 4145 | |X O O O O O O O X X O |
| 4146 | |- X X O - O X O - - X |
| 4147 | |X - - X - X X X X X X |
| 4148 | |O X X O X - X O O X O |
| 4149 | |
| 4150 | We will not attempt to characterize the terminal states of the local |
| 4151 | game (some of which could be seki) or the scoring. |
| 4152 | |
| 4153 | \1f |
| 4154 | File: gnugo.info, Node: Eye Example, Next: Graphs, Prev: Eye Space as Local Game, Up: Eyes |
| 4155 | |
| 4156 | 8.4 An example |
| 4157 | ============== |
| 4158 | |
| 4159 | Here is a local game which yields exactly one eye, no matter who moves |
| 4160 | first: |
| 4161 | |
| 4162 | |
| 4163 | ! |
| 4164 | ... |
| 4165 | ...! |
| 4166 | |
| 4167 | Here are some variations, assuming `O' moves first. |
| 4168 | |
| 4169 | ! (start position) |
| 4170 | ... |
| 4171 | ...! |
| 4172 | |
| 4173 | |
| 4174 | ... (after `O''s move) |
| 4175 | ...! |
| 4176 | |
| 4177 | |
| 4178 | ... |
| 4179 | ..! |
| 4180 | |
| 4181 | |
| 4182 | ... |
| 4183 | .. |
| 4184 | |
| 4185 | |
| 4186 | .X. (nakade) |
| 4187 | .. |
| 4188 | |
| 4189 | Here is another variation: |
| 4190 | |
| 4191 | |
| 4192 | ! (start) |
| 4193 | ... |
| 4194 | ...! |
| 4195 | |
| 4196 | |
| 4197 | ! (after `O''s move) |
| 4198 | . . |
| 4199 | ...! |
| 4200 | |
| 4201 | |
| 4202 | ! (after `X''s move) |
| 4203 | . . |
| 4204 | ..X! |
| 4205 | |
| 4206 | |
| 4207 | . . |
| 4208 | ..X! |
| 4209 | |
| 4210 | |
| 4211 | . ! |
| 4212 | .! |
| 4213 | |
| 4214 | \1f |
| 4215 | File: gnugo.info, Node: Graphs, Next: Eye Shape, Prev: Eye Example, Up: Eyes |
| 4216 | |
| 4217 | 8.5 Graphs |
| 4218 | ========== |
| 4219 | |
| 4220 | It is a useful observation that the local game associated with an |
| 4221 | eyespace depends only on the underlying graph, which as a set consists |
| 4222 | of the set of vertices, in which two elements are connected by an edge |
| 4223 | if and only if they are adjacent on the Go board. For example the two |
| 4224 | eye shapes: |
| 4225 | |
| 4226 | |
| 4227 | .. |
| 4228 | .. |
| 4229 | |
| 4230 | and |
| 4231 | |
| 4232 | .... |
| 4233 | |
| 4234 | though distinct in shape have isomorphic graphs, and consequently they |
| 4235 | are isomorphic as local games. This reduces the number of eyeshapes in |
| 4236 | the database `patterns/eyes.db'. |
| 4237 | |
| 4238 | A further simplification is obtained through our treatment of half |
| 4239 | eyes and false eyes. Such patterns are identified by the topological |
| 4240 | analysis (*note Eye Topology::). |
| 4241 | |
| 4242 | A half eye is isomorphic to the pattern `(!.)' . To see this, |
| 4243 | consider the following two eye shapes: |
| 4244 | |
| 4245 | XOOOOOO |
| 4246 | X.....O |
| 4247 | XOOOOOO |
| 4248 | and: |
| 4249 | |
| 4250 | XXOOOOO |
| 4251 | XOa...O |
| 4252 | XbOOOOO |
| 4253 | XXXXXXX |
| 4254 | |
| 4255 | These are equivalent eyeshapes, with isomorphic local games {2|1}. |
| 4256 | The first has shape: |
| 4257 | |
| 4258 | |
| 4259 | !.... |
| 4260 | |
| 4261 | The second eyeshape has a half eye at `a' which is taken when `O' or |
| 4262 | `X' plays at `b'. This is found by the topological criterion (*note Eye |
| 4263 | Topology::). |
| 4264 | |
| 4265 | The graph of the eye_shape, ostensibly `....' is modified by |
| 4266 | replacing the left `.' by `!.' during graph matching. |
| 4267 | |
| 4268 | A false eye is isomorphic to the pattern `(!)' . To see this, |
| 4269 | consider the following eye shape: |
| 4270 | |
| 4271 | |
| 4272 | XXXOOOOOO |
| 4273 | X.Oa....O |
| 4274 | XXXOOOOOO |
| 4275 | |
| 4276 | This is equivalent to the two previous eyeshapes, with an isomorphic |
| 4277 | local game {2|1}. |
| 4278 | |
| 4279 | This eyeshape has a false eye at `a'. This is also found by the |
| 4280 | topological criterion. |
| 4281 | |
| 4282 | The graph of the eye_shape, ostensibly `.....' is modified by |
| 4283 | replacing the left `.' by `!'. This is made directly in the eye data, |
| 4284 | not only during graph matching. |
| 4285 | |
| 4286 | \1f |
| 4287 | File: gnugo.info, Node: Eye Shape, Next: Eye Local Game Values, Prev: Graphs, Up: Eyes |
| 4288 | |
| 4289 | 8.6 Eye shape analysis |
| 4290 | ====================== |
| 4291 | |
| 4292 | The patterns in `patterns/eyes.db' are compiled into graphs represented |
| 4293 | essentially by arrays in `patterns/eyes.c'. |
| 4294 | |
| 4295 | Each actual eye space as it occurs on the board is also compiled |
| 4296 | into a graph. Half eyes are handled as follows. Referring to the |
| 4297 | example |
| 4298 | |
| 4299 | XXOOOOO |
| 4300 | XOa...O |
| 4301 | XbOOOOO |
| 4302 | XXXXXX |
| 4303 | |
| 4304 | repeated from the preceding discussion, the vertex at `b' is added to |
| 4305 | the eyespace as a marginal vertex. The adjacency condition in the graph |
| 4306 | is a macro (in `optics.c'): two vertices are adjacent if they are |
| 4307 | physically adjacent, or if one is a half eye and the other is its key |
| 4308 | point. |
| 4309 | |
| 4310 | In `recognize_eyes()', each such graph arising from an actual |
| 4311 | eyespace is matched against the graphs in `eyes.c'. If a match is |
| 4312 | found, the result of the local game is known. If a graph cannot be |
| 4313 | matched, its local game is assumed to be {2|2}. |
| 4314 | |
| 4315 | \1f |
| 4316 | File: gnugo.info, Node: Eye Local Game Values, Next: Eye Topology, Prev: Eye Shape, Up: Eyes |
| 4317 | |
| 4318 | 8.7 Eye Local Game Values |
| 4319 | ========================= |
| 4320 | |
| 4321 | The game values in `eyes.db' are given in a simplified scheme which is |
| 4322 | flexible enough to represent most possibilities in a useful way. |
| 4323 | |
| 4324 | The colon line below the pattern gives the eye value of the matched |
| 4325 | eye shape. This consists of four digits, each of which is the number of |
| 4326 | eyes obtained during the following conditions: |
| 4327 | |
| 4328 | 1. The attacker moves first and is allowed yet another move because |
| 4329 | the defender plays tenuki. |
| 4330 | |
| 4331 | 2. The attacker moves first and the defender responds locally. |
| 4332 | |
| 4333 | 3. The defender moves first and the attacker responds locally. |
| 4334 | |
| 4335 | 4. The defender moves first and is allowed yet another move because |
| 4336 | the attacker plays tenuki. |
| 4337 | |
| 4338 | The first case does *not* necessarily mean that the attacker is |
| 4339 | allowed two consecutive moves. This is explained with an example later. |
| 4340 | |
| 4341 | Also, since two eyes suffice to live, all higher numbers also count |
| 4342 | as two. |
| 4343 | |
| 4344 | The following 15 cases are of interest: |
| 4345 | |
| 4346 | * 0000 0 eyes. |
| 4347 | |
| 4348 | * 0001 0 eyes, but the defender can threaten to make one eye. |
| 4349 | |
| 4350 | * 0002 0 eyes, but the defender can threaten to make two eyes. |
| 4351 | |
| 4352 | * 0011 1/2 eye, 1 eye if defender moves first, 0 eyes if attacker |
| 4353 | does. |
| 4354 | |
| 4355 | * 0012 3/4 eyes, 3/2 eyes if defender moves first, 0 eyes if |
| 4356 | attacker does. |
| 4357 | |
| 4358 | * 0022 1* eye, 2 eyes if defender moves first, 0 eyes if attacker |
| 4359 | does. |
| 4360 | |
| 4361 | * 0111 1 eye, attacker can threaten to destroy the eye. |
| 4362 | |
| 4363 | * 0112 1 eye, attacker can threaten to destroy the eye, defender can |
| 4364 | threaten to make another eye. |
| 4365 | |
| 4366 | * 0122 5/4 eyes, 2 eyes if defender moves first, 1/2 eye if attacker |
| 4367 | does. |
| 4368 | |
| 4369 | * 0222 2 eyes, attacker can threaten to destroy both. |
| 4370 | |
| 4371 | * 1111 1 eye. |
| 4372 | |
| 4373 | * 1112 1 eye, defender can threaten to make another eye. |
| 4374 | |
| 4375 | * 1122 3/2 eyes, 2 eyes if defender moves first, 1 eye if attacker |
| 4376 | does. |
| 4377 | |
| 4378 | * 1222 2 eyes, attacker can threaten to destroy one eye. |
| 4379 | |
| 4380 | * 2222 2 eyes. |
| 4381 | |
| 4382 | The 3/4, 5/4, and 1* eye values are the same as in Howard Landman's |
| 4383 | paper Eyespace Values in Go. Attack and defense points are only marked |
| 4384 | in the patterns when they have definite effects on the eye value, i.e. |
| 4385 | pure threats are not marked. |
| 4386 | |
| 4387 | Examples of all different cases can be found among the patterns in |
| 4388 | this file. Some of them might be slightly counterintuitive, so we |
| 4389 | explain one important case here. Consider |
| 4390 | |
| 4391 | Pattern 6141 |
| 4392 | |
| 4393 | X |
| 4394 | XX.@x |
| 4395 | |
| 4396 | :1122 |
| 4397 | |
| 4398 | which e.g. matches in this position: |
| 4399 | |
| 4400 | .OOOXXX |
| 4401 | OOXOXOO |
| 4402 | OXXba.O |
| 4403 | OOOOOOO |
| 4404 | |
| 4405 | Now it may look like `X' could take away both eyes by playing `a' |
| 4406 | followed by `b', giving 0122 as eye value. This is where the subtlety |
| 4407 | of the definition of the first digit in the eye value comes into play. |
| 4408 | It does not say that the attacker is allowed two consecutive moves but |
| 4409 | only that he is allowed to play "another move". The crucial property of |
| 4410 | this shape is that when `X' plays at a to destroy (at least) one eye, |
| 4411 | `O' can answer at `b', giving: |
| 4412 | |
| 4413 | |
| 4414 | .OOOXXX |
| 4415 | OO.OXOO |
| 4416 | O.cOX.O |
| 4417 | OOOOOOO |
| 4418 | |
| 4419 | Now `X' has to continue at `c' in order to keep `O' at one eye. |
| 4420 | After this `O' plays tenuki and `X' cannot destroy the remaining eye by |
| 4421 | another move. Thus the eye value is indeed 1122. |
| 4422 | |
| 4423 | As a final note, some of the eye values indicating a threat depend |
| 4424 | on suicide to be allowed, e.g. |
| 4425 | |
| 4426 | |
| 4427 | Pattern 301 |
| 4428 | |
| 4429 | X.X |
| 4430 | |
| 4431 | :1222 |
| 4432 | |
| 4433 | We always assume suicide to be allowed in this database. It is easy |
| 4434 | enough to sort out such moves at a higher level when suicide is |
| 4435 | disallowed. |
| 4436 | |
| 4437 | \1f |
| 4438 | File: gnugo.info, Node: Eye Topology, Next: Eye Topology with Ko, Prev: Eye Local Game Values, Up: Eyes |
| 4439 | |
| 4440 | 8.8 Topology of Half Eyes and False Eyes |
| 4441 | ======================================== |
| 4442 | |
| 4443 | A HALF EYE is a pattern where an eye may or may not materialize, |
| 4444 | depending on who moves first. Here is a half eye for `O': |
| 4445 | |
| 4446 | |
| 4447 | OOXX |
| 4448 | O.O. |
| 4449 | OO.X |
| 4450 | |
| 4451 | A FALSE EYE is an eye vertex which cannot become a proper eye. Here |
| 4452 | are two examples of false eyes for `O': |
| 4453 | |
| 4454 | |
| 4455 | OOX OOX |
| 4456 | O.O O.OO |
| 4457 | XOO OOX |
| 4458 | |
| 4459 | We describe now the topological algorithm used to find half eyes and |
| 4460 | false eyes. In this section we ignore the possibility of ko. |
| 4461 | |
| 4462 | False eyes and half eyes can locally be characterized by the status |
| 4463 | of the diagonal intersections from an eye space. For each diagonal |
| 4464 | intersection, which is not within the eye space, there are three |
| 4465 | distinct possibilities: |
| 4466 | |
| 4467 | * occupied by an enemy (`X') stone, which cannot be captured. |
| 4468 | |
| 4469 | * either empty and `X' can safely play there, or occupied by an |
| 4470 | `X' stone that can both be attacked and defended. |
| 4471 | |
| 4472 | * occupied by an `O' stone, an `X' stone that can be attacked but |
| 4473 | not defended, or it's empty and `X' cannot safely play there. |
| 4474 | |
| 4475 | We give the first possibility a value of two, the second a value of |
| 4476 | one, and the last a value of zero. Summing the values for the diagonal |
| 4477 | intersections, we have the following criteria: |
| 4478 | |
| 4479 | * sum >= 4: false eye |
| 4480 | |
| 4481 | * sum == 3: half eye |
| 4482 | |
| 4483 | * sum <= 2: proper eye |
| 4484 | |
| 4485 | If the eye space is on the edge, the numbers above should be |
| 4486 | decreased by 2. An alternative approach is to award diagonal points |
| 4487 | which are outside the board a value of 1. To obtain an exact |
| 4488 | equivalence we must however give value 0 to the points diagonally off |
| 4489 | the corners, i.e. the points with both coordinates out of bounds. |
| 4490 | |
| 4491 | The algorithm to find all topologically false eyes and half eyes is: |
| 4492 | |
| 4493 | For all eye space points with at most one neighbor in the eye space, |
| 4494 | evaluate the status of the diagonal intersections according to the |
| 4495 | criteria above and classify the point from the sum of the values. |
| 4496 | |
| 4497 | \1f |
| 4498 | File: gnugo.info, Node: Eye Topology with Ko, Next: False Margins, Prev: Eye Topology, Up: Eyes |
| 4499 | |
| 4500 | 8.9 Eye Topology with Ko |
| 4501 | ======================== |
| 4502 | |
| 4503 | This section extends the topological eye analysis to handle ko. We |
| 4504 | distinguish between a ko in favor of `O' and one in favor of `X': |
| 4505 | |
| 4506 | .?O? good for O |
| 4507 | OO.O |
| 4508 | O.O? |
| 4509 | XOX. |
| 4510 | .X.. |
| 4511 | .?O? good for X |
| 4512 | OO.O |
| 4513 | OXO? |
| 4514 | X.X. |
| 4515 | .X.. |
| 4516 | |
| 4517 | Preliminarily we give the former the symbolic diagonal value `a' and |
| 4518 | the latter the diagonal value `b'. We should clearly have `0 < a < 1 < |
| 4519 | b < 2'. Letting `e' be the topological eye value (still the sum of the |
| 4520 | four diagonal values), we want to have the following properties: |
| 4521 | |
| 4522 | e <= 2 - proper eye |
| 4523 | 2 < e < 3 - worse than proper eye, better than half eye |
| 4524 | e = 3 - half eye |
| 4525 | 3 < e < 4 - worse than half eye, better than false eye |
| 4526 | e >= 4 - false eye |
| 4527 | |
| 4528 | In order to determine the appropriate values of `a' and `b' we |
| 4529 | analyze the typical cases of ko contingent topological eyes: |
| 4530 | |
| 4531 | .X.. (slightly) better than proper eye |
| 4532 | (a) ..OO e < 2 |
| 4533 | OO.O |
| 4534 | O.OO e = 1 + a |
| 4535 | XOX. |
| 4536 | .X.. |
| 4537 | |
| 4538 | .X.. better than half eye, worse than proper eye |
| 4539 | (a') ..OO 2 < e < 3 |
| 4540 | OO.O |
| 4541 | OXOO e = 1 + b |
| 4542 | X.X. |
| 4543 | .X.. |
| 4544 | |
| 4545 | .X.. better than half eye, worse than proper eye |
| 4546 | (b) .XOO 2 < e < 3 |
| 4547 | OO.O |
| 4548 | O.OO e = 2 + a |
| 4549 | XOX. |
| 4550 | .X.. |
| 4551 | |
| 4552 | .X.. better than false eye, worse than half eye |
| 4553 | (b') .XOO 3 < e < 4 |
| 4554 | OO.O |
| 4555 | OXOO e = 2 + b |
| 4556 | X.X. |
| 4557 | .X.. |
| 4558 | |
| 4559 | .X.. |
| 4560 | XOX. (slightly) better than proper eye |
| 4561 | (c) O.OO e < 2 |
| 4562 | OO.O |
| 4563 | O.OO e = 2a |
| 4564 | XOX. |
| 4565 | .X.. |
| 4566 | |
| 4567 | .X.. |
| 4568 | XOX. proper eye, some aji |
| 4569 | (c') O.OO e ~ 2 |
| 4570 | OO.O |
| 4571 | OXOO e = a + b |
| 4572 | X.X. |
| 4573 | .X.. |
| 4574 | |
| 4575 | .X.. |
| 4576 | X.X. better than half eye, worse than proper eye |
| 4577 | (c'') OXOO 2 < e < 3 |
| 4578 | OO.O |
| 4579 | OXOO e = 2b |
| 4580 | X.X. |
| 4581 | .X.. |
| 4582 | |
| 4583 | .X... |
| 4584 | XOX.. better than half eye, worse than proper eye |
| 4585 | (d) O.O.X 2 < e < 3 |
| 4586 | OO.O. |
| 4587 | O.OO. e = 1 + 2a |
| 4588 | XOX.. |
| 4589 | .X... |
| 4590 | |
| 4591 | .X... |
| 4592 | XOX.. half eye, some aji |
| 4593 | (d') O.O.X e ~ 3 |
| 4594 | OO.O. |
| 4595 | OXOO. e = 1 + a + b |
| 4596 | X.X.. |
| 4597 | .X... |
| 4598 | |
| 4599 | .X... |
| 4600 | X.X.. better than false eye, worse than half eye |
| 4601 | (d'') OXO.X 3 < e < 4 |
| 4602 | OO.O. |
| 4603 | OXOO. e = 1 + 2b |
| 4604 | X.X.. |
| 4605 | .X... |
| 4606 | |
| 4607 | .X... |
| 4608 | XOX.. better than false eye, worse than half eye |
| 4609 | (e) O.OXX 3 < e < 4 |
| 4610 | OO.O. |
| 4611 | O.OO. e = 2 + 2a |
| 4612 | XOX.. |
| 4613 | .X... |
| 4614 | |
| 4615 | .X... |
| 4616 | XOX.. false eye, some aji |
| 4617 | (e') O.OXX e ~ 4 |
| 4618 | OO.O. |
| 4619 | OXOO. e = 2 + a + b |
| 4620 | X.X.. |
| 4621 | .X... |
| 4622 | |
| 4623 | .X... |
| 4624 | X.X.. (slightly) worse than false eye |
| 4625 | (e'') OXOXX 4 < e |
| 4626 | OO.O. |
| 4627 | OXOO. e = 2 + 2b |
| 4628 | X.X.. |
| 4629 | .X... |
| 4630 | |
| 4631 | It may seem obvious that we should use |
| 4632 | (i) a=1/2, b=3/2 |
| 4633 | but this turns out to have some drawbacks. These can be solved by |
| 4634 | using either of |
| 4635 | (ii) a=2/3, b=4/3 |
| 4636 | (iii) a=3/4, b=5/4 |
| 4637 | (iv) a=4/5, b=6/5 |
| 4638 | |
| 4639 | Summarizing the analysis above we have the following table for the |
| 4640 | four different choices of `a' and `b'. |
| 4641 | |
| 4642 | case symbolic a=1/2 a=2/3 a=3/4 a=4/5 desired |
| 4643 | value b=3/2 b=4/3 b=5/4 b=6/5 interval |
| 4644 | (a) 1+a 1.5 1.67 1.75 1.8 e < 2 |
| 4645 | (a') 1+b 2.5 2.33 2.25 2.2 2 < e < 3 |
| 4646 | (b) 2+a 2.5 2.67 2.75 2.8 2 < e < 3 |
| 4647 | (b') 2+b 3.5 3.33 3.25 3.2 3 < e < 4 |
| 4648 | (c) 2a 1 1.33 1.5 1.6 e < 2 |
| 4649 | (c') a+b 2 2 2 2 e ~ 2 |
| 4650 | (c'') 2b 3 2.67 2.5 2.4 2 < e < 3 |
| 4651 | (d) 1+2a 2 2.33 2.5 2.6 2 < e < 3 |
| 4652 | (d') 1+a+b 3 3 3 3 e ~ 3 |
| 4653 | (d'') 1+2b 4 3.67 3.5 3.4 3 < e < 4 |
| 4654 | (e) 2+2a 3 3.33 3.5 3.6 3 < e < 4 |
| 4655 | (e') 2+a+b 4 4 4 4 e ~ 4 |
| 4656 | (e'') 2+2b 5 4.67 4.5 4.4 4 < e |
| 4657 | |
| 4658 | We can notice that (i) fails for the cases (c"), (d), (d"), and (e). |
| 4659 | The other three choices get all values in the correct intervals. The |
| 4660 | main distinction between them is the relative ordering of (c") and (d) |
| 4661 | (or analogously (d") and (e)). If we do a more detailed analysis of |
| 4662 | these we can see that in both cases `O' can secure the eye |
| 4663 | unconditionally if he moves first while `X' can falsify it with ko if |
| 4664 | he moves first. The difference is that in (c"), `X' has to make the |
| 4665 | first ko threat, while in (d), O has to make the first ko threat. Thus |
| 4666 | (c") is better for O and ought to have a smaller topological eye value |
| 4667 | than (d). This gives an indication that (iv) is the better choice. |
| 4668 | |
| 4669 | We can notice that any value of `a', `b' satisfying `a+b=2' and |
| 4670 | `3/4<a<1' would have the same qualities as choice (iv) according to the |
| 4671 | analysis above. One interesting choice is `a=7/8, b=9/8' since these |
| 4672 | allow exact computations with floating point values having a binary |
| 4673 | mantissa. The latter property is shared by `a=3/4' and `a=1/2'. |
| 4674 | |
| 4675 | When there are three kos around the same eyespace, things become |
| 4676 | more complex. This case is, however, rare enough that we ignore it. |
| 4677 | |
| 4678 | \1f |
| 4679 | File: gnugo.info, Node: False Margins, Next: Eye Functions, Prev: Eye Topology with Ko, Up: Eyes |
| 4680 | |
| 4681 | 8.10 False Margins |
| 4682 | ================== |
| 4683 | |
| 4684 | The following situation is rare but special enough to warrant separate |
| 4685 | attention: |
| 4686 | |
| 4687 | OOOOXX |
| 4688 | OXaX.. |
| 4689 | ------ |
| 4690 | |
| 4691 | Here `a' may be characterized by the fact that it is adjacent to O's |
| 4692 | eyespace, and it is also adjacent to an X group which cannot be |
| 4693 | attacked, but that an X move at 'a' results in a string with only one |
| 4694 | liberty. We call this a "false margin". |
| 4695 | |
| 4696 | For the purpose of the eye code, O's eyespace should be parsed as |
| 4697 | `(X)', not `(X!)'. |
| 4698 | |
| 4699 | \1f |
| 4700 | File: gnugo.info, Node: Eye Functions, Prev: False Margins, Up: Eyes |
| 4701 | |
| 4702 | 8.11 Functions in `optics.c' |
| 4703 | ============================ |
| 4704 | |
| 4705 | The public function `make_domains()' calls the function |
| 4706 | `make_primary_domains()' which is static in `optics.c'. It's purpose is |
| 4707 | to compute the domains of influence of each color, used in determining |
| 4708 | eye shapes. *Note*: the term influence as used here is distinct from the |
| 4709 | influence in influence.c. |
| 4710 | |
| 4711 | For this algorithm the strings which are not lively are invisible. |
| 4712 | Ignoring these, the algorithm assigns friendly influence to |
| 4713 | |
| 4714 | 1. every vertex which is occupied by a (lively) friendly stone, |
| 4715 | |
| 4716 | 2. every empty vertex adjoining a (lively) friendly stone, |
| 4717 | |
| 4718 | 3. every empty vertex for which two adjoining vertices (not on the |
| 4719 | first line) in the (usually 8) surrounding ones have friendly |
| 4720 | influence, with two CAVEATS explained below. |
| 4721 | |
| 4722 | Thus in the following diagram, `e' would be assigned friendly |
| 4723 | influence if `a' and `b' have friendly influence, or `a' and `d'. It is |
| 4724 | not sufficent for `b' and `d' to have friendly influence, because they |
| 4725 | are not adjoining. |
| 4726 | |
| 4727 | uabc |
| 4728 | def |
| 4729 | ghi |
| 4730 | |
| 4731 | The constraint that the two adjoining vertices not lie on the first |
| 4732 | line prevents influence from leaking under a stone on the third line. |
| 4733 | |
| 4734 | The first CAVEAT alluded to above is that even if `a' and `b' have |
| 4735 | friendly influence, this does not cause `e' to have friendly influence |
| 4736 | if there is a lively opponent stone at `d'. This constraint prevents |
| 4737 | influence from leaking past knight's move extensions. |
| 4738 | |
| 4739 | The second CAVEAT is that even if `a' and `b' have friendly influence |
| 4740 | this does not cause `e' to have influence if there are lively opponent |
| 4741 | stones at `u' and at `c'. This prevents influence from leaking past |
| 4742 | nikken tobis (two space jumps). |
| 4743 | |
| 4744 | The corner vertices are handled slightly different. |
| 4745 | |
| 4746 | +--- |
| 4747 | |ab |
| 4748 | |cd |
| 4749 | |
| 4750 | We get friendly influence at `a' if we have friendly influence at |
| 4751 | `b' or `c' and no lively unfriendly stone at `b', `c' or `d'. |
| 4752 | |
| 4753 | Here are the public functions in `optics.c', except some simple |
| 4754 | access functions used by autohelpers. The statically declared functions |
| 4755 | are documented in the source code. |
| 4756 | |
| 4757 | * `void make_domains(struct eye_data b_eye[BOARDMAX], struct |
| 4758 | eye_data w_eye[BOARDMAX], int owl_call)' |
| 4759 | |
| 4760 | This function is called from `make_dragons()' and from |
| 4761 | `owl_determine_life()'. It marks the black and white domains |
| 4762 | (eyeshape regions) and collects some statistics about each |
| 4763 | one. |
| 4764 | |
| 4765 | * `void partition_eyespaces(struct eye_data eye[BOARDMAX], int |
| 4766 | color)' |
| 4767 | |
| 4768 | Find connected eyespace components and compute relevant |
| 4769 | statistics. |
| 4770 | |
| 4771 | * `void propagate_eye(int origin, struct eye_data eye[BOARDMAX])' |
| 4772 | |
| 4773 | propagate_eye(origin) copies the data at the (origin) to the |
| 4774 | rest of the eye (invariant fields only). |
| 4775 | |
| 4776 | * `int find_eye_dragons(int origin, struct eye_data eye[BOARDMAX], |
| 4777 | int eye_color, int dragons[], int max_dragons)' |
| 4778 | |
| 4779 | Find the dragon or dragons surrounding an eye space. Up to |
| 4780 | max_dragons dragons adjacent to the eye space are added to |
| 4781 | the dragon array, and the number of dragons found is returned. |
| 4782 | |
| 4783 | * `void compute_eyes(int pos, struct eyevalue *value, int |
| 4784 | *attack_point, int *defense_point, struct eye_data eye[BOARDMAX], |
| 4785 | struct half_eye_data heye[BOARDMAX], int add_moves)' |
| 4786 | |
| 4787 | Given an eyespace with origin `pos', this function computes |
| 4788 | the minimum and maximum numbers of eyes the space can yield. |
| 4789 | If max and min are different, then vital points of attack and |
| 4790 | defense are also generated. If `add_moves == 1', this |
| 4791 | function may add a move_reason for `color' at a vital point |
| 4792 | which is found by the function. If `add_moves == 0', set |
| 4793 | `color = EMPTY.' |
| 4794 | |
| 4795 | * `void compute_eyes_pessimistic(int pos, struct eyevalue *value, |
| 4796 | int *pessimistic_min, int *attack_point, int *defense_point, |
| 4797 | struct eye_data eye[BOARDMAX], struct half_eye_data |
| 4798 | heye[BOARDMAX])' |
| 4799 | |
| 4800 | This function works like `compute_eyes()', except that it |
| 4801 | also gives a pessimistic view of the chances to make eyes. |
| 4802 | Since it is intended to be used from the owl code, the option |
| 4803 | to add move reasons has been removed. |
| 4804 | |
| 4805 | * `void add_false_eye(int pos, struct eye_data eye[BOARDMAX], struct |
| 4806 | half_eye_data heye[BOARDMAX])' |
| 4807 | |
| 4808 | turns a proper eyespace into a margin. |
| 4809 | |
| 4810 | * `int is_eye_space(int pos)' |
| 4811 | |
| 4812 | * `int is_proper_eye_space(int pos)' |
| 4813 | |
| 4814 | These functions are used from constraints to identify eye |
| 4815 | spaces, primarily for late endgame moves. |
| 4816 | |
| 4817 | * `int max_eye_value(int pos)' |
| 4818 | |
| 4819 | Return the maximum number of eyes that can be obtained from |
| 4820 | the eyespace at `(i, j)'. This is most useful in order to |
| 4821 | determine whether the eyespace can be assumed to produce any |
| 4822 | territory at all. |
| 4823 | |
| 4824 | * `int is_marginal_eye_space(int pos)' |
| 4825 | |
| 4826 | * `int is_halfeye(struct half_eye_data heye[BOARDMAX], int pos)' |
| 4827 | |
| 4828 | * `int is_false_eye(struct half_eye_data heye[BOARDMAX], int pos)' |
| 4829 | |
| 4830 | These functions simply return information about an eyeshape |
| 4831 | that has already been analyzed. (They do no real work.) |
| 4832 | |
| 4833 | * `void find_half_and_false_eyes(int color, struct eye_data |
| 4834 | eye[BOARDMAX], struct half_eye_data heye[BOARDMAX], int |
| 4835 | find_mask[BOARDMAX])' |
| 4836 | |
| 4837 | Find topological half eyes and false eyes by analyzing the |
| 4838 | diagonal intersections, as described in the Texinfo |
| 4839 | documentation (Eyes/Eye Topology). |
| 4840 | |
| 4841 | * `float topological_eye(int pos, int color, struct eye_data |
| 4842 | my_eye[BOARDMAX],struct half_eye_data heye[BOARDMAX])' |
| 4843 | |
| 4844 | See Texinfo documentation (Eyes:Eye Topology). Returns: |
| 4845 | * 2 or less if `pos' is a proper eye for `color'; |
| 4846 | |
| 4847 | * between 2 and 3 if the eye can be made false only by ko |
| 4848 | |
| 4849 | * 3 if `pos' is a half eye; |
| 4850 | |
| 4851 | * between 3 and 4 if the eye can be made real only by ko |
| 4852 | |
| 4853 | * 4 or more if `pos' is a false eye. |
| 4854 | Attack and defense points for control of the diagonals are |
| 4855 | stored in the `heye[]' array. `my_eye' is the eye space |
| 4856 | information with respect to `color'. |
| 4857 | |
| 4858 | * `int obvious_false_eye(int pos, int color)' |
| 4859 | |
| 4860 | Conservative relative of `topological_eye()'. Essentially the |
| 4861 | same algorithm is used, but only tactically safe opponent |
| 4862 | strings on diagonals are considered. This may underestimate |
| 4863 | the false/half eye status, but it should never be |
| 4864 | overestimated. |
| 4865 | |
| 4866 | * `void set_eyevalue(struct eyevalue *e, int a, int b, int c, int d)' |
| 4867 | |
| 4868 | set parameters into the `struct eyevalue' as follows: (*note |
| 4869 | Eye Local Game Values::): |
| 4870 | struct eyevalue { /* number of eyes if: */ |
| 4871 | unsigned char a; /* attacker plays first twice */ |
| 4872 | unsigned char b; /* attacker plays first */ |
| 4873 | unsigned char c; /* defender plays first */ |
| 4874 | unsigned char d; /* defender plays first twice */ |
| 4875 | }; |
| 4876 | |
| 4877 | * `int min_eye_threat(struct eyevalue *e)' |
| 4878 | |
| 4879 | Number of eyes if attacker plays first twice (the threat of |
| 4880 | the first move by attacker). |
| 4881 | |
| 4882 | * `int min_eyes(struct eyevalue *e)' |
| 4883 | |
| 4884 | Number of eyes if attacker plays first followed by |
| 4885 | alternating play. |
| 4886 | |
| 4887 | * `int max_eyes(struct eyevalue *e)' |
| 4888 | |
| 4889 | Number of eyes if defender plays first followed by |
| 4890 | alternating play. |
| 4891 | |
| 4892 | * `int max_eye_threat(struct eyevalue *e)' |
| 4893 | |
| 4894 | Number of eyes if defender plays first twice (the threat of |
| 4895 | the first move by defender). |
| 4896 | |
| 4897 | * `void add_eyevalues(struct eyevalue *e1, struct eyevalue *e2, |
| 4898 | struct eyevalue *sum)' |
| 4899 | |
| 4900 | Add the eyevalues `*e1' and `*e2', leaving the result in |
| 4901 | *sum. It is safe to let `sum' be the same as `e1' or `e2'. |
| 4902 | |
| 4903 | * `char * eyevalue_to_string(struct eyevalue *e)' |
| 4904 | |
| 4905 | Produces a string containing the eyevalue. *Note*: the result |
| 4906 | string is stored in a statically allocated buffer which will |
| 4907 | be overwritten the next time this function is called. |
| 4908 | |
| 4909 | * `void test_eyeshape(int eyesize, int *eye_vertices)' /* Test |
| 4910 | whether the optics code evaluates an eyeshape consistently. */ |
| 4911 | |
| 4912 | * `int analyze_eyegraph(const char *coded_eyegraph, struct eyevalue |
| 4913 | *value, char *analyzed_eyegraph)' |
| 4914 | |
| 4915 | Analyze an eye graph to determine the eye value and vital |
| 4916 | moves. The eye graph is given by a string which is encoded |
| 4917 | with `%' for newlines and `O' for spaces. E.g., the eye graph |
| 4918 | |
| 4919 | ! |
| 4920 | .X |
| 4921 | !... |
| 4922 | |
| 4923 | is encoded as `OO!%O.X%!...'. (The encoding is needed for the |
| 4924 | GTP interface to this function.) The result is an eye value |
| 4925 | and a (nonencoded) pattern showing the vital moves, using the |
| 4926 | same notation as eyes.db. In the example above we would get |
| 4927 | the eye value 0112 and the graph (showing ko threat moves) |
| 4928 | |
| 4929 | |
| 4930 | .X |
| 4931 | !.*. |
| 4932 | |
| 4933 | If the eye graph cannot be realized, 0 is returned, 1 |
| 4934 | otherwise. |
| 4935 | |
| 4936 | \1f |
| 4937 | File: gnugo.info, Node: Patterns, Next: Tactical Reading, Prev: Eyes, Up: Top |
| 4938 | |
| 4939 | 9 The Pattern Code |
| 4940 | ****************** |
| 4941 | |
| 4942 | * Menu: |
| 4943 | |
| 4944 | * Patterns Overview:: Overview of the pattern database. |
| 4945 | * Pattern Classification:: The classification field |
| 4946 | * Pattern Values:: The value field |
| 4947 | * Helper Functions:: Helper Functions |
| 4948 | * Autohelpers and Constraints:: Automatic generation of helper functions. |
| 4949 | * Autohelper Actions:: Autohelper Actions |
| 4950 | * Autohelper Functions:: Autohelper Functions |
| 4951 | * Attack and Defense DB:: The Attack and defense moves database. |
| 4952 | * Connections Database:: The connection database. |
| 4953 | * Connection Functions:: Functions in `connections.c' |
| 4954 | * Tuning:: Tuning the pattern database. |
| 4955 | * PM Implementation:: Implementation. |
| 4956 | * Symmetry & transformations:: Symmetry and transformations. |
| 4957 | * Details:: Details of implementation. |
| 4958 | * Grid optimization:: The ``grid'' optimization. |
| 4959 | * Joseki Compiler:: The joseki compiler. |
| 4960 | * Ladders in Joseki:: Example: ladders in joseki. |
| 4961 | * Corner Matcher:: A special matcher for joseki patterns. |
| 4962 | * Editing Patterns:: Emacs major mode for pattern files. |
| 4963 | |
| 4964 | \1f |
| 4965 | File: gnugo.info, Node: Patterns Overview, Next: Pattern Classification, Up: Patterns |
| 4966 | |
| 4967 | 9.1 Overview |
| 4968 | ============ |
| 4969 | |
| 4970 | Several pattern databases are in the patterns directory. This chapter |
| 4971 | primarily discusses the patterns in `patterns.db', `patterns2.db', and |
| 4972 | the pattern files `hoshi.db' etc. which are compiled from the SGF |
| 4973 | files `hoshi.sgf' (*note Joseki Compiler::). There is no essential |
| 4974 | difference between these files, except that the ones in `patterns.db' |
| 4975 | and `patterns2.db' are hand written. They are concatenated before being |
| 4976 | compiled by `mkpat' into `patterns.c'. The purpose of the separate file |
| 4977 | `patterns2.db' is that it is handy to move patterns into a new |
| 4978 | directory in the course of organizing them. The patterns in |
| 4979 | `patterns.db' are more disorganized, and are slowly being moved to |
| 4980 | `patterns2.db'. |
| 4981 | |
| 4982 | During the execution of `genmove()', the patterns are matched in |
| 4983 | `shapes.c' in order to find move reasons. |
| 4984 | |
| 4985 | The same basic pattern format is used by `attack.db', `defense.db', |
| 4986 | `conn.db', `apats.db' and `dpats.db'. However these patterns are used |
| 4987 | for different purposes. These databases are discussed in other parts of |
| 4988 | this documentation. The patterns in `eyes.db' are entirely different |
| 4989 | and are documented elsewhere (*note Eyes::). |
| 4990 | |
| 4991 | The patterns described in the databases are ascii representations, of |
| 4992 | the form: |
| 4993 | |
| 4994 | Pattern EB112 |
| 4995 | |
| 4996 | |
| 4997 | ?X?.? jump under |
| 4998 | O.*oo |
| 4999 | O.... |
| 5000 | o.... |
| 5001 | ----- |
| 5002 | |
| 5003 | :8,ed,NULL |
| 5004 | |
| 5005 | Here `O' marks a friendly stone, `X' marks an enemy stone, `.' marks |
| 5006 | an empty vertex, `*' marks O's next move, `o' marks a square either |
| 5007 | containing `O' or empty but not `X'. (The symbol `x', which does not |
| 5008 | appear in this pattern, means `X' or `.'.) Finally `?' Indicates a |
| 5009 | location where we don't care what is there, except that it cannot be |
| 5010 | off the edge of the board. |
| 5011 | |
| 5012 | The line of `-''s along the bottom in this example is the edge of the |
| 5013 | board itself--this is an edge pattern. Corners can also be indicated. |
| 5014 | Elements are not generated for `?' markers, but they are not completely |
| 5015 | ignored - see below. |
| 5016 | |
| 5017 | The line beginning `:' describes various attributes of the pattern, |
| 5018 | such as its symmetry and its class. Optionally, a function called a |
| 5019 | "helper" can be provided to assist the matcher in deciding whether to |
| 5020 | accept move. Most patterns do not require a helper, and this field is |
| 5021 | filled with NULL. |
| 5022 | |
| 5023 | The matcher in `matchpat.c' searches the board for places where this |
| 5024 | layout appears on the board, and the callback function |
| 5025 | `shapes_callback()' in `shapes.c' registers the appropriate move |
| 5026 | reasons. |
| 5027 | |
| 5028 | After the pattern, there is some supplementary information in the |
| 5029 | format: |
| 5030 | |
| 5031 | :trfno, classification, [values], helper_function |
| 5032 | |
| 5033 | Here trfno represents the number of transformations of the pattern to |
| 5034 | consider, usually `8' (no symmetry, for historical reasons), or one of |
| 5035 | `|', `\', `/', `-', `+', `X', where the line represents the axis of |
| 5036 | symmetry. (E.g. `|' means symmetrical about a vertical axis.) |
| 5037 | |
| 5038 | The above pattern could equally well be written on the left edge: |
| 5039 | |
| 5040 | |
| 5041 | |oOO? |
| 5042 | |...X |
| 5043 | |..*? |
| 5044 | |..o. |
| 5045 | |..o? |
| 5046 | |
| 5047 | :8,ed,NULL |
| 5048 | |
| 5049 | The program `mkpat' is capable of parsing patterns written this way, |
| 5050 | or for that matter, on the top or right edges, or in any of the four |
| 5051 | corners. As a matter of convention all the edge patterns in |
| 5052 | `patterns.db' are written on the bottom edge or in the lower left |
| 5053 | corners. In the `patterns/' directory there is a program called |
| 5054 | `transpat' which can rotate or otherwise transpose patterns. This |
| 5055 | program is not built by default--if you think you need it, `make |
| 5056 | transpat' in the `patterns/' directory and consult the usage remarks at |
| 5057 | the beginning of `patterns/transpat.c'. |
| 5058 | |
| 5059 | \1f |
| 5060 | File: gnugo.info, Node: Pattern Classification, Next: Pattern Values, Prev: Patterns Overview, Up: Patterns |
| 5061 | |
| 5062 | 9.2 Pattern Attributes |
| 5063 | ====================== |
| 5064 | |
| 5065 | The attribute field in the `:' line of a pattern consists of a sequence |
| 5066 | of zero or more of the following characters, each with a different |
| 5067 | meaning. The attributes may be roughly classified as "constraints", |
| 5068 | which determine whether or not the pattern is matched, and "actions", |
| 5069 | which describe what is to be done when the pattern is matched, typically |
| 5070 | to add a move reason. |
| 5071 | |
| 5072 | 9.2.1 Constraint Pattern Attributes |
| 5073 | ----------------------------------- |
| 5074 | |
| 5075 | * `s' |
| 5076 | |
| 5077 | Safety of the move is not checked. This is appropriate for |
| 5078 | sacrifice patterns. If this classification is omitted, the |
| 5079 | matcher requires that the stone played cannot be trivially |
| 5080 | captured. Even with s classification, a check for legality is |
| 5081 | made, though. |
| 5082 | |
| 5083 | * `n' |
| 5084 | |
| 5085 | In addition to usual check that the stone played cannot be |
| 5086 | trivially captured, it is also confirmed that an opponent |
| 5087 | move here could not be captured. |
| 5088 | |
| 5089 | * `O' |
| 5090 | |
| 5091 | It is checked that every friendly (`O') stone of the pattern |
| 5092 | belongs to a dragon which has status (*note Dragons::) |
| 5093 | `ALIVE' or `UNKNOWN'. The `CRITICAL' matcher status is |
| 5094 | excluded. It is possible for a string to have `ALIVE' status |
| 5095 | and still be tactically critical, since it might be |
| 5096 | amalgamated into an ALIVE dragon, and the matcher status is |
| 5097 | constant on the dragon. Therefore, an additional test is |
| 5098 | performed: if the pattern contains a string which is |
| 5099 | tactically critical, and if `*' does not rescue it, the |
| 5100 | pattern is rejected. |
| 5101 | |
| 5102 | * `o' |
| 5103 | |
| 5104 | It is checked that every friendly (`O') stone of the pattern |
| 5105 | belongs to a dragon which is classified as `DEAD' or |
| 5106 | `UNKNOWN'. |
| 5107 | |
| 5108 | * `X' |
| 5109 | |
| 5110 | It is checked that every opponent (`X') stone of the pattern |
| 5111 | belongs to a dragon with status `ALIVE', `UNKNOWN' or |
| 5112 | `CRITICAL'. Note that there is an asymmetry with `O' |
| 5113 | patterns, where `CRITICAL' dragons are rejected. |
| 5114 | |
| 5115 | * `x' |
| 5116 | |
| 5117 | It is checked that every opponent (`X') stone of the pattern |
| 5118 | belongs to a dragon which is classified as `DEAD' or `UNKNOWN' |
| 5119 | |
| 5120 | 9.2.2 Action Attributes |
| 5121 | ----------------------- |
| 5122 | |
| 5123 | * `C' |
| 5124 | |
| 5125 | If two or more distinct O dragons occur in the pattern, the |
| 5126 | move is given the move reasons that it connects each pair of |
| 5127 | dragons. An exception is made for dragons where the underlying |
| 5128 | worm can be tactically captured and is not defended by the |
| 5129 | considered move. |
| 5130 | |
| 5131 | * `c' |
| 5132 | |
| 5133 | Add strategical defense move reason for all our dragons and a |
| 5134 | small shape bonus. This classification is appropriate for |
| 5135 | weak connection patterns. |
| 5136 | |
| 5137 | * `B' |
| 5138 | |
| 5139 | If two or more distinct `X' dragons occur in the pattern, the |
| 5140 | move is given the move reasons that it cuts each pair of |
| 5141 | dragons. |
| 5142 | |
| 5143 | * `e' |
| 5144 | |
| 5145 | The move makes or secures territory. |
| 5146 | |
| 5147 | * `E' |
| 5148 | |
| 5149 | The move attempts increase influence and create/expand a moyo. |
| 5150 | |
| 5151 | * `d' |
| 5152 | |
| 5153 | The move strategically defends all O dragons in the pattern, |
| 5154 | except those that can be tactically captured and are not |
| 5155 | tactically defended by this move. If any O dragon should |
| 5156 | happen to be perfectly safe already, this only reflects in |
| 5157 | the move reason being valued to zero. |
| 5158 | |
| 5159 | * `a' |
| 5160 | |
| 5161 | The move strategically attacks all `X' dragons in the pattern. |
| 5162 | |
| 5163 | * `J' |
| 5164 | |
| 5165 | Standard joseki move. Unless there is an urgent move on the |
| 5166 | board these moves are made as soon as they can be. This is |
| 5167 | equivalent to adding the `d' and `a' classifications together |
| 5168 | with a minimum accepted value of 27. |
| 5169 | |
| 5170 | * `F' |
| 5171 | |
| 5172 | This indicates a fuseki pattern. This is only effective |
| 5173 | together with either the `j' or `t' classification, and is |
| 5174 | used to ensure indeterministic play during fuseki. |
| 5175 | |
| 5176 | * `j' |
| 5177 | |
| 5178 | Slightly less urgent joseki move. These moves will be made |
| 5179 | after those with the `J' classification. This adds the `e' |
| 5180 | and `E' classifications. If the move has the `F' |
| 5181 | classification, it also gets a fixed value of 20.1, otherwise |
| 5182 | it gets a minimum accepted value of 20. (This makes sure that |
| 5183 | GNU Go chooses randomly between different moves that have |
| 5184 | `jF' as classification.) |
| 5185 | |
| 5186 | * `t' |
| 5187 | |
| 5188 | Minor joseki move (tenuki OK). This is equivalent to adding |
| 5189 | the `e' and `E' classifications together with either a fixed |
| 5190 | value of 15.07 (if the move has `F' classification) or a |
| 5191 | minimum value of 15 (otherwise). |
| 5192 | |
| 5193 | * `U' |
| 5194 | |
| 5195 | Urgent joseki move (never tenuki). This is equivalent to the |
| 5196 | `d' and `a' classifications together with a shape bonus of 15 |
| 5197 | and a minimum accepted value of 40. |
| 5198 | |
| 5199 | A commonly used class is `OX' (which rejects pattern if either side has |
| 5200 | dead stones). The string `-' may be used as a placeholder. (In fact any |
| 5201 | characters other than the above and `,' are ignored.) |
| 5202 | |
| 5203 | The types `o' and `O' could conceivably appear in a class, meaning it |
| 5204 | applies only to `UNKNOWN'. `X' and `x' could similarly be used together. |
| 5205 | All classes can be combined arbitrarily. |
| 5206 | |
| 5207 | \1f |
| 5208 | File: gnugo.info, Node: Pattern Values, Next: Helper Functions, Prev: Pattern Classification, Up: Patterns |
| 5209 | |
| 5210 | 9.3 Pattern Attributes |
| 5211 | ====================== |
| 5212 | |
| 5213 | The second and following fields in the `:' line of a pattern are |
| 5214 | optional and of the form `value1(x),value2(y),...'. The available set |
| 5215 | of values are as follows. |
| 5216 | |
| 5217 | * `terri(x)' |
| 5218 | |
| 5219 | Forces the territorial value of the move to be at least x. |
| 5220 | |
| 5221 | * `minterri(x)' |
| 5222 | |
| 5223 | Forces the territorial value of the move to be at least x. |
| 5224 | |
| 5225 | * `maxterri(x)' |
| 5226 | |
| 5227 | Forces the territorial value of the move to be at most x. |
| 5228 | |
| 5229 | * `value(x)' |
| 5230 | |
| 5231 | Forces the final value of the move to be at least x. |
| 5232 | |
| 5233 | * `minvalue(x)', `maxvalue(x)' |
| 5234 | |
| 5235 | Forces the final value of the move to be at least/most x. |
| 5236 | |
| 5237 | * `shape(x)' |
| 5238 | |
| 5239 | Adds x to the move's shape value. |
| 5240 | |
| 5241 | * `followup(x)' |
| 5242 | |
| 5243 | Adds x to the move's followup value. |
| 5244 | |
| 5245 | The meaning of these values is documented in *Note Move Generation::. |
| 5246 | |
| 5247 | \1f |
| 5248 | File: gnugo.info, Node: Helper Functions, Next: Autohelpers and Constraints, Prev: Pattern Values, Up: Patterns |
| 5249 | |
| 5250 | 9.4 Helper Functions |
| 5251 | ==================== |
| 5252 | |
| 5253 | Helper functions can be provided to assist the matcher in deciding |
| 5254 | whether to accept a pattern, register move reasons, and setting various |
| 5255 | move values. The helper is supplied with the compiled pattern entry in |
| 5256 | the table, and the (absolute) position on the board of the `*' point. |
| 5257 | |
| 5258 | One difficulty is that the helper must be able to cope with all the |
| 5259 | possible transformations of the pattern. To help with this, the OFFSET |
| 5260 | macro is used to transform relative pattern coordinates to absolute |
| 5261 | board locations. |
| 5262 | |
| 5263 | The actual helper functions are in `helpers.c'. They are declared in |
| 5264 | `patterns.h'. |
| 5265 | |
| 5266 | As an example to show how to write a helper function, we consider a |
| 5267 | hypothetical helper called `wedge_helper'. Such a helper used to exist, |
| 5268 | but has been replaced by a constraint. Due to its simplicity it's still |
| 5269 | a good example. The helper begins with a comment: |
| 5270 | |
| 5271 | /* |
| 5272 | |
| 5273 | ?O. ?Ob |
| 5274 | .X* aX* |
| 5275 | ?O. ?Oc |
| 5276 | |
| 5277 | :8,C,wedge_helper |
| 5278 | */ |
| 5279 | |
| 5280 | The image on the left is the actual pattern. On the right we've taken |
| 5281 | this image and added letters to label `apos', `bpos', and `cpos'. The |
| 5282 | position of *, the point where GNU Go will move if the pattern is |
| 5283 | adopted, is passed through the parameter `move'. |
| 5284 | |
| 5285 | int |
| 5286 | wedge_helper(ARGS) |
| 5287 | { |
| 5288 | int apos, bpos, cpos; |
| 5289 | int other = OTHER_COLOR(color); |
| 5290 | int success = 0; |
| 5291 | |
| 5292 | apos = OFFSET(0, -2); |
| 5293 | bpos = OFFSET(-1, 0); |
| 5294 | cpos = OFFSET(1, 0); |
| 5295 | |
| 5296 | if (TRYMOVE(move, color)) { |
| 5297 | if (TRYMOVE(apos, other)) { |
| 5298 | if (board[apos] == EMPTY || attack(apos, NULL)) |
| 5299 | success = 1; |
| 5300 | else if (TRYMOVE(bpos, color)) { |
| 5301 | if (!safe_move(cpos, other)) |
| 5302 | success = 1; |
| 5303 | popgo(); |
| 5304 | } |
| 5305 | popgo(); |
| 5306 | } |
| 5307 | popgo(); |
| 5308 | } |
| 5309 | |
| 5310 | return success; |
| 5311 | } |
| 5312 | |
| 5313 | The `OFFSET' lines tell GNU Go the positions of the three stones at |
| 5314 | `a', `b', and `c'. To decide whether the pattern guarantees a |
| 5315 | connection, we do some reading. First we use the `TRYMOVE' macro to |
| 5316 | place an `O' at `move' and let `X' draw back to `a'. Then we ask |
| 5317 | whether `O' can capture these stones by calling `attack()'. The test if |
| 5318 | there is a stone at `a' before calling `attack()' is in this position |
| 5319 | not really necessary but it's good practice to do so, because if the |
| 5320 | attacked stone should happen to already have been captured while |
| 5321 | placing stones, GNU Go would crash with an assertion failure. |
| 5322 | |
| 5323 | If this attack fails we let `O' connect at `b' and use the |
| 5324 | `safe_move()' function to examine whether a cut by `X' at `c' could be |
| 5325 | immediately captured. Before we return the result we need to remove the |
| 5326 | stones we placed from the reading stack. This is done with the function |
| 5327 | `popgo()'. |
| 5328 | |
| 5329 | \1f |
| 5330 | File: gnugo.info, Node: Autohelpers and Constraints, Next: Autohelper Actions, Prev: Helper Functions, Up: Patterns |
| 5331 | |
| 5332 | 9.5 Autohelpers and Constraints |
| 5333 | =============================== |
| 5334 | |
| 5335 | In addition to the hand-written helper functions in `helpers.c', GNU Go |
| 5336 | can automatically generate helper functions from a diagram with labels |
| 5337 | and an expression describing a constraint. The constraint diagram, |
| 5338 | specifying the labels, is placed below the `:' line and the constraint |
| 5339 | expression is placed below the diagram on line starting with a `;'. |
| 5340 | Constraints can only be used to accept or reject a pattern. If the |
| 5341 | constraint evaluates to zero (false) the pattern is rejected, otherwise |
| 5342 | it's accepted (still conditioned on passing all other tests of course). |
| 5343 | To give a simple example we consider a connection pattern. |
| 5344 | |
| 5345 | |
| 5346 | Pattern Conn311 |
| 5347 | |
| 5348 | O*. |
| 5349 | ?XO |
| 5350 | |
| 5351 | :8,C,NULL |
| 5352 | |
| 5353 | O*a |
| 5354 | ?BO |
| 5355 | |
| 5356 | ;oplay_attack_either(*,a,a,B) |
| 5357 | |
| 5358 | Here we have given the label `a' to the empty spot to the right of |
| 5359 | the considered move and the label `B' to the `X' stone in the pattern. |
| 5360 | In addition to these, `*' can also be used as a label. A label may be |
| 5361 | any lowercase or uppercase ascii letter except `OoXxt'. By convention |
| 5362 | we use uppercase letters for `X' stones and lowercase for `O' stones |
| 5363 | and empty intersections. When labeling a stone that's part of a larger |
| 5364 | string in the pattern, all stones of the string should be marked with |
| 5365 | the label. (These conventions are not enforced by the pattern compiler, |
| 5366 | but to make the database consistent and easy to read they should be |
| 5367 | followed.) |
| 5368 | |
| 5369 | The labels can now be used in the constraint expression. In this |
| 5370 | example we have a reading constraint which should be interpreted as |
| 5371 | "Play an `O' stone at `*' followed by an `X' stone at `a'. Accept the |
| 5372 | pattern if `O' now can capture either at `a' or at `B' (or both |
| 5373 | strings)." |
| 5374 | |
| 5375 | The functions that are available for use in the constraints are |
| 5376 | listed in the section `Autohelpers Functions' below. Technically the |
| 5377 | constraint expression is transformed by mkpat into an automatically |
| 5378 | generated helper function in `patterns.c'. The functions in the |
| 5379 | constraint are replaced by C expressions, often functions calls. In |
| 5380 | principle any valid C code can be used in the constraints, but there is |
| 5381 | in practice no reason to use anything more than boolean and arithmetic |
| 5382 | operators in addition to the autohelper functions. Constraints can |
| 5383 | span multiple lines, which are then concatenated. |
| 5384 | |
| 5385 | \1f |
| 5386 | File: gnugo.info, Node: Autohelper Actions, Next: Autohelper Functions, Prev: Autohelpers and Constraints, Up: Patterns |
| 5387 | |
| 5388 | 9.6 Autohelper Actions |
| 5389 | ====================== |
| 5390 | |
| 5391 | As a complement to the constraints, which only can accept or reject a |
| 5392 | pattern, one can also specify an action to perform when the pattern has |
| 5393 | passed all tests and finally has been accepted. |
| 5394 | |
| 5395 | Example: |
| 5396 | |
| 5397 | |
| 5398 | Pattern EJ4 |
| 5399 | |
| 5400 | ...*. continuation |
| 5401 | .OOX. |
| 5402 | ..XOX |
| 5403 | ..... |
| 5404 | ----- |
| 5405 | |
| 5406 | :8,Ed,NULL |
| 5407 | |
| 5408 | ...*. never play a here |
| 5409 | .OOX. |
| 5410 | .aXOX |
| 5411 | ..... |
| 5412 | ----- |
| 5413 | |
| 5414 | >antisuji(a) |
| 5415 | |
| 5416 | The line starting with `>' is the action line. In this case it tells |
| 5417 | the move generation that the move at a should not be considered, |
| 5418 | whatever move reasons are found by other patterns. The action line uses |
| 5419 | the labels from the constraint diagram. Both constraint and action can |
| 5420 | be used in the same pattern. If the action only needs to refer to `*', |
| 5421 | no constraint diagram is required. Like constraints, actions can span |
| 5422 | multiple lines. |
| 5423 | |
| 5424 | Here is a partial list of the autohelper macros which are typically |
| 5425 | called from action lines. This list is not complete. If you cannot find |
| 5426 | an autohelper macro in an action line in this list, consult `mkpat.c' to |
| 5427 | find out what function in the engine is actually called. If no macro |
| 5428 | exists which does what you want, you can add macros by editing the list |
| 5429 | in `mkpat.c'. |
| 5430 | |
| 5431 | * `antisuji(a);' |
| 5432 | |
| 5433 | Mark `a' as an antisuji, that is, a move that must never be |
| 5434 | played. |
| 5435 | |
| 5436 | * `replace(a,*)' |
| 5437 | |
| 5438 | This is appropriate if the move at `*' is definitely better |
| 5439 | than the move at `a'. The macro adds a point redistribution |
| 5440 | rule. Any points which are assigned to `a' during the move |
| 5441 | generation by any move reason are redistributed to `*'. |
| 5442 | |
| 5443 | * `prevent_attack_threat(a)' |
| 5444 | |
| 5445 | Add a reverse followup value because the opponent's move here |
| 5446 | would threaten to capture `a'. |
| 5447 | |
| 5448 | * `threaten_to_save(a)' |
| 5449 | |
| 5450 | Add a followup value because the move at `*' threatens to |
| 5451 | rescue the dead string at `a'. |
| 5452 | |
| 5453 | * `defend_against_atari(a)' |
| 5454 | |
| 5455 | Estimate the value of defending the string `a' which can be |
| 5456 | put into atari and add this as a reverse followup value. |
| 5457 | |
| 5458 | * `add_defend_both_move(a,b);' |
| 5459 | |
| 5460 | |
| 5461 | * `add_cut_move(c,d);' |
| 5462 | |
| 5463 | Add to the move reasons that the move at `*' threatens to cut |
| 5464 | `c' and `d'. |
| 5465 | |
| 5466 | \1f |
| 5467 | File: gnugo.info, Node: Autohelper Functions, Next: Attack and Defense DB, Prev: Autohelper Actions, Up: Patterns |
| 5468 | |
| 5469 | 9.7 Autohelper Functions |
| 5470 | ======================== |
| 5471 | |
| 5472 | The autohelper functions are translated into C code by the program in |
| 5473 | `mkpat.c'. To see exactly how the functions are implemented, consult |
| 5474 | the autohelper function definitions in that file. Autohelper functions |
| 5475 | can be used in both constraint and action lines. |
| 5476 | |
| 5477 | |
| 5478 | `lib(x)' |
| 5479 | `lib2(x)' |
| 5480 | `lib3(x)' |
| 5481 | `lib4(x)' |
| 5482 | |
| 5483 | Number of first, second, third, and fourth order liberties of a worm |
| 5484 | respectively. *Note Worms and Dragons::, the documentation on worms for |
| 5485 | definitions. |
| 5486 | |
| 5487 | |
| 5488 | `xlib(x)' |
| 5489 | `olib(x)' |
| 5490 | |
| 5491 | The number of liberties that an enemy or own stone, respectively, |
| 5492 | would obtain if played at the empty intersection `x'. |
| 5493 | |
| 5494 | `xcut(x)' |
| 5495 | `ocut(x)' |
| 5496 | |
| 5497 | Calls `cut_possible' (*note General Utilities::) to determine |
| 5498 | whether `X' or `O' can cut at the empty intersection `x'. |
| 5499 | |
| 5500 | `ko(x)' |
| 5501 | |
| 5502 | True if `x' is either a stone or an empty point involved in a ko |
| 5503 | position. |
| 5504 | |
| 5505 | `status(x)' |
| 5506 | |
| 5507 | The matcher status of a dragon. status(x) returns an integer that |
| 5508 | can have the values `ALIVE', `UNKNOWN', `CRITICAL', or `DEAD' (*note |
| 5509 | Worms and Dragons::). |
| 5510 | |
| 5511 | `alive(x)' |
| 5512 | `unknown(x)' |
| 5513 | `critical(x)' |
| 5514 | `dead(x)' |
| 5515 | |
| 5516 | Each function true if the dragon has the corresponding matcher |
| 5517 | status and false otherwise (*note Worms and Dragons::). |
| 5518 | |
| 5519 | `status(x)' |
| 5520 | |
| 5521 | Returns the status of the dragon at `x' (*note Worms and Dragons::). |
| 5522 | |
| 5523 | `genus(x)' |
| 5524 | |
| 5525 | The number of eyes of a dragon. It is only meaningful to compare this |
| 5526 | value against 0, 1, or 2. |
| 5527 | |
| 5528 | |
| 5529 | `xarea(x)' |
| 5530 | `oarea(x)' |
| 5531 | `xmoyo(x)' |
| 5532 | `omoyo(x)' |
| 5533 | `xterri(x)' |
| 5534 | `oterri(x)' |
| 5535 | |
| 5536 | These functions call `whose_territory()', `whose_moyo()' and |
| 5537 | `whose_area()' (*note Territory and Moyo::). For example `xarea(x)' |
| 5538 | evaluates to true if `x' is either a living enemy stone or an empty |
| 5539 | point within the opponent's "area". The function `oarea(x)' is |
| 5540 | analogous but with respect to our stones and area. The main difference |
| 5541 | between area, moyo, and terri is that area is a very far reaching kind |
| 5542 | of influence, moyo gives a more realistic estimate of what may turn in |
| 5543 | to territory, and terri gives the points that already are believed to |
| 5544 | be secure territory. |
| 5545 | |
| 5546 | `weak(x)' |
| 5547 | |
| 5548 | True for a dragon that is perceived as weak. |
| 5549 | |
| 5550 | |
| 5551 | `attack(x)' |
| 5552 | `defend(x)' |
| 5553 | |
| 5554 | Results of tactical reading. `attack(x)' is true if the worm can be |
| 5555 | captured, `defend(x)' is true if there also is a defending move. Please |
| 5556 | notice that `defend(x)' will return false if there is no attack on the |
| 5557 | worm. |
| 5558 | |
| 5559 | |
| 5560 | `safe_xmove(x)' |
| 5561 | `safe_omove(x)' |
| 5562 | |
| 5563 | True if an enemy or friendly stone, respectively, can safely be |
| 5564 | played at `x'. By safe it is understood that the move is legal and that |
| 5565 | it cannot be captured right away. |
| 5566 | |
| 5567 | |
| 5568 | `legal_xmove(x)' |
| 5569 | `legal_omove(x)' |
| 5570 | |
| 5571 | True if an enemy or friendly stone, respectively, can legally be |
| 5572 | played at x. |
| 5573 | |
| 5574 | |
| 5575 | o_somewhere(x,y,z, ...) |
| 5576 | x_somewhere(x,y,z, ...) |
| 5577 | |
| 5578 | True if O (respectively X) has a stone at one of the labelled |
| 5579 | vertices. In the diagram, these vertices should be marked with a `?'. |
| 5580 | |
| 5581 | |
| 5582 | odefend_against(x,y) |
| 5583 | xdefend_against(x,y) |
| 5584 | |
| 5585 | True if an own stone at `x' would stop the enemy from safely playing |
| 5586 | at `y', and conversely for the second function. |
| 5587 | |
| 5588 | |
| 5589 | `does_defend(x,y)' |
| 5590 | `does_attack(x,y)' |
| 5591 | |
| 5592 | True if a move at `x' defends/attacks the worm at `y'. For defense a |
| 5593 | move of the same color as `y' is tried and for attack a move of the |
| 5594 | opposite color. |
| 5595 | |
| 5596 | |
| 5597 | `xplay_defend(a,b,c,...,z)' |
| 5598 | `oplay_defend(a,b,c,...,z)' |
| 5599 | `xplay_attack(a,b,c,...,z)' |
| 5600 | `oplay_attack(a,b,c,...,z)' |
| 5601 | |
| 5602 | These functions make it possible to do more complex reading |
| 5603 | experiments in the constraints. All of them work so that first the |
| 5604 | sequence of moves `a',`b',`c',... is played through with alternating |
| 5605 | colors, starting with `X' or `O' as indicated by the name. Then it is |
| 5606 | tested whether the worm at `z' can be attacked or defended, |
| 5607 | respectively. It doesn't matter who would be in turn to move, a worm of |
| 5608 | either color may be attacked or defended. For attacks the opposite |
| 5609 | color of the string being attacked starts moving and for defense the |
| 5610 | same color starts. The defend functions return true if the worm cannot |
| 5611 | be attacked in the position or if it can be attacked but also defended. |
| 5612 | The attack functions return true if there is a way to capture the worm, |
| 5613 | whether or not it can also be defended. If there is no stone present at |
| 5614 | `z' after the moves have been played, it is assumed that an attack has |
| 5615 | already been successful or a defense has already failed. If some of |
| 5616 | the moves should happen to be illegal, typically because it would have |
| 5617 | been suicide, the following moves are played as if nothing has happened |
| 5618 | and the attack or defense is tested as usual. It is assumed that this |
| 5619 | convention will give the relevant result without requiring a lot of |
| 5620 | special cases. |
| 5621 | |
| 5622 | The special label `?' can be used to represent a tenuki. Thus |
| 5623 | `oplay_defend(a,?,b,c)' tries moves by `O' at `a' and `b', as if `X' |
| 5624 | plays the second move in another part of the board, then asks if `c' |
| 5625 | can be defended. The tenuki cannot be the first move of the sequence, |
| 5626 | nor does it need to be: instead of `oplay_defend(?,a,b,c)' you can use |
| 5627 | `xplay_defend(a,b,c)'. |
| 5628 | |
| 5629 | `xplay_defend_both(a,b,c,...,y,z)' |
| 5630 | `oplay_defend_both(a,b,c,...,y,z)' |
| 5631 | `xplay_attack_either(a,b,c,...,y,z)' |
| 5632 | `oplay_attack_either(a,b,c,...,y,z)' |
| 5633 | |
| 5634 | These functions are similar to the previous ones. The difference is |
| 5635 | that the last *two* arguments denote worms to be attacked or defended |
| 5636 | simultaneously. Obviously `y' and `z' must have the same color. If |
| 5637 | either location is empty, it is assumed that an attack has been |
| 5638 | successful or a defense has failed. The typical use for these functions |
| 5639 | is in cutting patterns, where it usually suffices to capture either |
| 5640 | cutstone. |
| 5641 | |
| 5642 | The function `xplay_defend_both' plays alternate moves beginning |
| 5643 | with an `X' at `a'. Then it passes the last two arguments to |
| 5644 | `defend_both' in `engine/utils.c'. This function checks to determine |
| 5645 | whether the two strings can be simultaneously defended. |
| 5646 | |
| 5647 | The function `xplay_attack_either' plays alternate moves beginning |
| 5648 | with an `X' move at `a'. Then it passes the last two arguments to |
| 5649 | `attack_either' in `engine/utils.c'. This function looks for a move |
| 5650 | which captures at least one of the two strings. In its current |
| 5651 | implementation `attack_either' only looks for uncoordinated attacks and |
| 5652 | would thus miss a double atari. |
| 5653 | |
| 5654 | `xplay_connect(a,b,c,...,y,z)' |
| 5655 | `oplay_connect(a,b,c,...,y,z)' |
| 5656 | `xplay_disconnect(a,b,c,...,y,z)' |
| 5657 | `oplay_disconnect(a,b,c,...,y,z)' |
| 5658 | |
| 5659 | The function `xplay_connect(a,b,c,...,y,z)' begins with an `X' move |
| 5660 | at `a', then an `O' move at `b', and so forth, then finally calls |
| 5661 | `string_connect()' to determine whether `x' and `y' can be connected. |
| 5662 | The other functions are similar (*note Connection Reading::). |
| 5663 | |
| 5664 | |
| 5665 | `xplay_break_through(a,b,c,...,x,y,z)' |
| 5666 | `oplay_break_through(a,b,c,...,x,y,z)' |
| 5667 | |
| 5668 | These functions are used to set up a position like |
| 5669 | |
| 5670 | |
| 5671 | .O. .y. |
| 5672 | OXO xXz |
| 5673 | |
| 5674 | and `X' aims at capturing at least one of `x', `y', and `z'. If this |
| 5675 | succeeds `1' is returned. If it doesn't, `X' tries instead to cut |
| 5676 | through on either side and if this succeeds, `2' is returned. Of course |
| 5677 | the same shape with opposite colors can also be used. |
| 5678 | |
| 5679 | Important notice: `x', `y', and `z' must be given in the order they |
| 5680 | have in the diagram above, or any reflection and/or rotation of it. |
| 5681 | |
| 5682 | seki_helper(x) |
| 5683 | |
| 5684 | Checks whether the string at `x' can attack any surrounding string. |
| 5685 | If so, return false as the move to create a seki (probably) wouldn't |
| 5686 | work. |
| 5687 | |
| 5688 | threaten_to_save(x) |
| 5689 | |
| 5690 | Calls `add_followup_value' to add as a move reason a conservative |
| 5691 | estimate of the value of saving the string `x' by capturing one opponent |
| 5692 | stone. |
| 5693 | |
| 5694 | area_stone(x) |
| 5695 | |
| 5696 | Returns the number of stones in the area around `x'. |
| 5697 | |
| 5698 | area_space(x) |
| 5699 | |
| 5700 | Returns the amount of space in the area around `x'. |
| 5701 | |
| 5702 | `eye(x)' |
| 5703 | `proper_eye(x)' |
| 5704 | `marginal_eye(x)' |
| 5705 | |
| 5706 | True if `x' is an eye space for either color, a non-marginal eye |
| 5707 | space for either color, or a marginal eye space for either color, |
| 5708 | respectively. |
| 5709 | |
| 5710 | `antisuji(x)' |
| 5711 | |
| 5712 | Tell the move generation that `x' is a substandard move that never |
| 5713 | should be played. |
| 5714 | |
| 5715 | same_dragon(x,y) |
| 5716 | same_worm(x,y) |
| 5717 | |
| 5718 | Return true if `x' and `y' are the same dragon or worm respectively. |
| 5719 | |
| 5720 | `dragonsize(x)' |
| 5721 | `wormsize(x)' |
| 5722 | |
| 5723 | Number of stones in the indicated dragon or worm. |
| 5724 | |
| 5725 | `add_connect_move(x,y)' |
| 5726 | `add_cut_move(x,y)' |
| 5727 | `add_attack_either_move(x,y)' |
| 5728 | `add_defend_both_move(x,y)' |
| 5729 | |
| 5730 | Explicitly notify the move generation about move reasons for the move |
| 5731 | in the pattern. |
| 5732 | |
| 5733 | `halfeye(x)' |
| 5734 | |
| 5735 | Returns true if the empty intersection at `x' is a half eye. |
| 5736 | |
| 5737 | `remove_attack(x)' |
| 5738 | |
| 5739 | Inform the tactical reading that a supposed attack does in fact not |
| 5740 | work. |
| 5741 | |
| 5742 | `potential_cutstone(x)' |
| 5743 | |
| 5744 | True if `cutstone2' field from worm data is larger than one. This |
| 5745 | indicates that saving the worm would introduce at least two new cutting |
| 5746 | points. |
| 5747 | |
| 5748 | `not_lunch(x,y)' |
| 5749 | |
| 5750 | Prevents the misreporting of `x' as lunch for `y'. For example, the |
| 5751 | following pattern tells GNU Go that even though the stone at `a' can be |
| 5752 | captured, it should not be considered "lunch" for the dragon at `b', |
| 5753 | because capturing it does not produce an eye: |
| 5754 | |
| 5755 | XO| ba| |
| 5756 | O*| O*| |
| 5757 | oo| oo| |
| 5758 | ?o| ?o| |
| 5759 | |
| 5760 | > not_lunch(a,b) |
| 5761 | |
| 5762 | `vital_chain(x)' |
| 5763 | |
| 5764 | Calls `vital_chain' to determine whether capturing the stone at `x' |
| 5765 | will result in one eye for an adjacent dragon. The current |
| 5766 | implementation just checks that the stone is not a singleton on the |
| 5767 | first line. |
| 5768 | |
| 5769 | `amalgamate(x,y)' |
| 5770 | |
| 5771 | Amalgamate (join) the dragons at `x' and `y' (*note Worms and |
| 5772 | Dragons::). |
| 5773 | |
| 5774 | `amalgamate_most_valuable(x,y,z)' |
| 5775 | |
| 5776 | Called when `x', `y', `z' point to three (preferably distinct) |
| 5777 | dragons, in situations such as this: |
| 5778 | |
| 5779 | |
| 5780 | .O.X |
| 5781 | X*OX |
| 5782 | .O.X |
| 5783 | |
| 5784 | In this situation, the opponent can play at `*', preventing the |
| 5785 | three dragons from becoming connected. However `O' can decide which cut |
| 5786 | to allow. The helper amalgamates the dragon at `y' with either `x' or |
| 5787 | `z', whichever is largest. |
| 5788 | |
| 5789 | make_proper_eye(x) |
| 5790 | |
| 5791 | This autohelper should be called when `x' is an eyespace which is |
| 5792 | misidentified as marginal. It is reclassified as a proper eyespace |
| 5793 | (*note Eye Space::). |
| 5794 | |
| 5795 | remove_halfeye(x) |
| 5796 | |
| 5797 | Remove a half eye from the eyespace. This helper should not be run |
| 5798 | after `make_dragons' is finished, since by that time the eyespaces have |
| 5799 | already been analyzed. |
| 5800 | |
| 5801 | remove_eyepoint(x) |
| 5802 | |
| 5803 | Remove an eye point. This function can only be used before the |
| 5804 | segmentation into eyespaces. |
| 5805 | |
| 5806 | `owl_topological_eye(x,y)' |
| 5807 | |
| 5808 | Here `x' is an empty intersection which may be an eye or half eye |
| 5809 | for some dragon, and `y' is a stone of the dragon, used only to |
| 5810 | determine the color of the eyespace in question. Returns the sum of the |
| 5811 | values of the diagonal intersections, relative to `x', as explained in |
| 5812 | *Note Eye Topology::, equal to 4 or more if the eye at `x' is false, 3 |
| 5813 | if it is a half eye, and 2 if it is a true eye. |
| 5814 | |
| 5815 | `owl_escape_value(x)' |
| 5816 | |
| 5817 | Returns the escape value at `x'. This is only useful in owl attack |
| 5818 | and defense patterns. |
| 5819 | |
| 5820 | \1f |
| 5821 | File: gnugo.info, Node: Attack and Defense DB, Next: Connections Database, Prev: Autohelper Functions, Up: Patterns |
| 5822 | |
| 5823 | 9.8 Attack and Defense Database |
| 5824 | =============================== |
| 5825 | |
| 5826 | The patterns in `attack.db' and `defense.db' are used to assist the |
| 5827 | tactical reading in finding moves that attacks or defends worms. The |
| 5828 | matching is performed during `make_worms()', at the time when the |
| 5829 | tactical status of all worms is decided. None of the classes described |
| 5830 | above are useful in these databases, instead we have two other classes. |
| 5831 | |
| 5832 | `D' |
| 5833 | For each `O' worm in the pattern that can be tactically captured |
| 5834 | (`worm[m][n].attack_code != 0'), the move at `*' is tried. If it |
| 5835 | is found to defend the stone, this is registered as a reason for |
| 5836 | the move `*' and the defense point of the worm is set to `*'. |
| 5837 | |
| 5838 | `A' |
| 5839 | For each `X' worm in the pattern, it's tested whether the move at |
| 5840 | `*' captures the worm. If that is the case, this is registered as |
| 5841 | a reason for the move at `*'. The attack point of the worm is set |
| 5842 | to `*' and if it wasn't attacked before, a defense is searched for. |
| 5843 | |
| 5844 | Furthermore, `A' patterns can only be used in `attack.db' and `D' |
| 5845 | patterns only in `defense.db'. Unclassified patterns may appear in |
| 5846 | these databases, but then they must work through actions to be |
| 5847 | effective. |
| 5848 | |
| 5849 | \1f |
| 5850 | File: gnugo.info, Node: Connections Database, Next: Connection Functions, Prev: Attack and Defense DB, Up: Patterns |
| 5851 | |
| 5852 | 9.9 The Connections Database |
| 5853 | ============================ |
| 5854 | |
| 5855 | The patterns in `conn.db' are used for helping `make_dragons()' |
| 5856 | amalgamate worms into dragons and to some extent for modifying eye |
| 5857 | spaces. The patterns in this database use the classifications `B', |
| 5858 | `C', and `e'. `B' patterns are used for finding cutting points, where |
| 5859 | amalgamation should not be performed, `C' patterns are used for finding |
| 5860 | existing connections, over which amalgamation is to be done, and `e' |
| 5861 | patterns are used for modifying eye spaces and reevaluating lunches. |
| 5862 | There are also some patterns without classification, which use action |
| 5863 | lines to have an impact. These are matched together with the `C' |
| 5864 | patterns. Further details and examples can be found in *Note Worms and |
| 5865 | Dragons::. |
| 5866 | |
| 5867 | We will illustrate these databases by example. In this situation: |
| 5868 | |
| 5869 | XOO |
| 5870 | O.O |
| 5871 | ... |
| 5872 | `X' cannot play safely at the cutting point, so the `O' dragons are |
| 5873 | to be amalgamated. Two patterns are matched here: |
| 5874 | |
| 5875 | Pattern CC204 |
| 5876 | |
| 5877 | O |
| 5878 | . |
| 5879 | O |
| 5880 | |
| 5881 | :+,C |
| 5882 | |
| 5883 | O |
| 5884 | A |
| 5885 | O |
| 5886 | |
| 5887 | ;!safe_xmove(A) && !ko(A) && !xcut(A) |
| 5888 | |
| 5889 | Pattern CC205 |
| 5890 | |
| 5891 | XO |
| 5892 | O. |
| 5893 | |
| 5894 | :\,C |
| 5895 | |
| 5896 | AO |
| 5897 | OB |
| 5898 | |
| 5899 | ;attack(A) || (!safe_xmove(B) && !ko(B) && !xcut(B)) |
| 5900 | |
| 5901 | The constraints are mostly clear. For example the second pattern |
| 5902 | should not be matched if the `X' stone cannot be attacked and `X' can |
| 5903 | play safely at `B', or if `B' is a ko. The constraint `!xcut(B)' means |
| 5904 | that connection has not previously been inhibited by `find_cuts'. For |
| 5905 | example consider this situation: |
| 5906 | |
| 5907 | |
| 5908 | OOXX |
| 5909 | O.OX |
| 5910 | X..O |
| 5911 | X.OO |
| 5912 | The previous pattern is matched here twice, yet `X' can push in and |
| 5913 | break one of the connections. To fix this, we include a pattern: |
| 5914 | |
| 5915 | Pattern CB11 |
| 5916 | |
| 5917 | ?OX? |
| 5918 | O!OX |
| 5919 | ?*!O |
| 5920 | ??O? |
| 5921 | |
| 5922 | :8,B |
| 5923 | |
| 5924 | ?OA? |
| 5925 | OaOB |
| 5926 | ?*bO |
| 5927 | ??O? |
| 5928 | |
| 5929 | ; !attack(A) && !attack(B) && !xplay_attack(*,a,b,*) && !xplay_attack(*,b,a,*) |
| 5930 | |
| 5931 | After this pattern is found, the `xcut' autohelper macro will return |
| 5932 | true at any of the points `*', `a' and `b'. Thus the patterns `CB204' |
| 5933 | and `CB205' will not be matched, and the dragons will not be |
| 5934 | amalgamated. |
| 5935 | |
| 5936 | \1f |
| 5937 | File: gnugo.info, Node: Connection Functions, Next: Tuning, Prev: Connections Database, Up: Patterns |
| 5938 | |
| 5939 | 9.10 Connections Functions |
| 5940 | ========================== |
| 5941 | |
| 5942 | Here are the public functions in `connections.c'. |
| 5943 | |
| 5944 | * `static void cut_connect_callback(int m, int n, int color, |
| 5945 | struct pattern *pattern, int ll, void *data)' |
| 5946 | |
| 5947 | Try to match all (permutations of) connection patterns at |
| 5948 | `(m,n)'. For each match, if it is a B pattern, set cutting |
| 5949 | point in worm data structure and make eye space marginal for |
| 5950 | the connection inhibiting entries of the pattern. If it is a |
| 5951 | `C' pattern, amalgamate the dragons in the pattern. |
| 5952 | |
| 5953 | * `void find_cuts(void)' |
| 5954 | |
| 5955 | Find cutting points which should inhibit amalgamations and |
| 5956 | sever the adjacent eye space. This goes through the |
| 5957 | connection database consulting only patterns of type B. When |
| 5958 | such a function is found, the function `cut_connect_callback' |
| 5959 | is invoked. |
| 5960 | |
| 5961 | * `void find_connections(void)' |
| 5962 | |
| 5963 | Find explicit connection patterns and amalgamate the involved |
| 5964 | dragons. This goes through the connection database |
| 5965 | consulting patterns except those of type B, E or e. When such |
| 5966 | a function is found, the function `cut_connect_callback' is |
| 5967 | invoked. |
| 5968 | |
| 5969 | * void modify_eye_spaces1(void) |
| 5970 | |
| 5971 | Find explicit connection patterns and amalgamate the involved |
| 5972 | dragons. This goes through the connection database |
| 5973 | consulting only patterns of type E (*note Connections |
| 5974 | Database::). When such a function is found, the function |
| 5975 | `cut_connect_callback' is invoked. |
| 5976 | |
| 5977 | * void modify_eye_spaces1(void) |
| 5978 | |
| 5979 | Find explicit connection patterns and amalgamate the involved |
| 5980 | dragons. This goes through the connection database |
| 5981 | consulting only patterns of type e (*note Connections |
| 5982 | Database::). When such a function is found, the function |
| 5983 | `cut_connect_callback' is invoked. |
| 5984 | |
| 5985 | \1f |
| 5986 | File: gnugo.info, Node: Tuning, Next: PM Implementation, Prev: Connection Functions, Up: Patterns |
| 5987 | |
| 5988 | 9.11 Tuning the Pattern databases |
| 5989 | ================================= |
| 5990 | |
| 5991 | Since the pattern databases, together with the valuation of move |
| 5992 | reasons, decide GNU Go's personality, much time can be devoted to |
| 5993 | "tuning" them. Here are some suggestions. |
| 5994 | |
| 5995 | If you want to experiment with modifying the pattern database, invoke |
| 5996 | with the `-a' option. This will cause every pattern to be evaluated, |
| 5997 | even when some of them may be skipped due to various optimizations. |
| 5998 | |
| 5999 | You can obtain a Smart Game Format (SGF) record of your game in at |
| 6000 | least two different ways. One is to use CGoban to record the game. You |
| 6001 | can also have GNU Go record the game in Smart Game Format, using the |
| 6002 | `-o' option. It is best to combine this with `-a'. Do not try to read |
| 6003 | the SGF file until the game is finished and you have closed the game |
| 6004 | window. This does not mean that you have to play the game out to its |
| 6005 | conclusion. You may close the CGoban window on the game and GNU Go will |
| 6006 | close the SGF file so that you can read it. |
| 6007 | |
| 6008 | If you record a game in SGF form using the `-o' option, GNU Go will |
| 6009 | add labels to the board to show all the moves it considered, with their |
| 6010 | values. This is an extremely useful feature, since one can see at a |
| 6011 | glance whether the right moves with appropriate weights are being |
| 6012 | proposed by the move generation. |
| 6013 | |
| 6014 | First, due to a bug of unknown nature, it occasionally happens that |
| 6015 | GNU Go will not receive the `SIGTERM' signal from CGoban that it needs |
| 6016 | to know that the game is over. When this happens, the SGF file ends |
| 6017 | without a closing parenthesis, and CGoban will not open the file. You |
| 6018 | can fix the file by typing: |
| 6019 | |
| 6020 | |
| 6021 | echo ")" >>[filename] |
| 6022 | |
| 6023 | at the command line to add this closing parenthesis. Or you could add |
| 6024 | the ) using an editor. |
| 6025 | |
| 6026 | Move values exceeding 99 (these should be rare) can be displayed by |
| 6027 | CGoban but you may have to resize the window in order to see all three |
| 6028 | digits. Grab the lower right margin of the CGoban window and pull it |
| 6029 | until the window is large. All three digits should be visible. |
| 6030 | |
| 6031 | If you are playing a game without the `-o' option and you wish to |
| 6032 | analyze a move, you may still use CGoban's "Save Game" button to get an |
| 6033 | SGF file. It will not have the values of the moves labelled, of course. |
| 6034 | |
| 6035 | Once you have a game saved in SGF format, you can analyze any |
| 6036 | particular move by running: |
| 6037 | |
| 6038 | |
| 6039 | gnugo -l [filename] -L [move number] -t -a -w |
| 6040 | |
| 6041 | to see why GNU Go made that move, and if you make changes to the |
| 6042 | pattern database and recompile the program, you may ask GNU Go to |
| 6043 | repeat the move to see how the behavior changes. If you're using emacs, |
| 6044 | it's a good idea to run GNU Go in a shell in a buffer (M-x shell) since |
| 6045 | this gives good navigation and search facilities. |
| 6046 | |
| 6047 | Instead of a move number, you can also give a board coordinate to |
| 6048 | `-L' in order to stop at the first move played at this location. If you |
| 6049 | omit the `-L' option, the move after those in the file will be |
| 6050 | considered. |
| 6051 | |
| 6052 | If a bad move is proposed, this can have several reasons. To begin |
| 6053 | with, each move should be valued in terms of actual points on the |
| 6054 | board, as accurately as can be expected by the program. If it's not, |
| 6055 | something is wrong. This may have two reasons. One possibility is that |
| 6056 | there are reasons missing for the move or that bogus reasons have been |
| 6057 | found. The other possibility is that the move reasons have been |
| 6058 | misevaluated by the move valuation functions. Tuning of patterns is |
| 6059 | with a few exceptions a question of fixing the first kind of problems. |
| 6060 | |
| 6061 | If there are bogus move reasons found, search through the trace |
| 6062 | output for the pattern that is responsible. (Some move reasons, e.g. |
| 6063 | most tactical attack and defense, do not originate from patterns. If no |
| 6064 | pattern produced the bogus move reason, it is not a tuning problem.) |
| 6065 | Probably this pattern was too general or had a faulty constraint. Try |
| 6066 | to make it more specific or correct bugs if there were any. If the |
| 6067 | pattern and the constraint looks right, verify that the tactical |
| 6068 | reading evaluates the constraint correctly. If not, this is either a |
| 6069 | reading bug or a case where the reading is too complicated for GNU Go. |
| 6070 | |
| 6071 | If a connecting move reason is found, but the strings are already |
| 6072 | effectively connected, there may be missing patterns in `conn.db'. |
| 6073 | Similarly, worms may be incorrectly amalgamated due to some too general |
| 6074 | or faulty pattern in `conn.db'. To get trace output from the matching |
| 6075 | of patterns in `conn.db' you need to add a second `-t' option. |
| 6076 | |
| 6077 | If a move reason is missing, there may be a hole in the database. It |
| 6078 | could also be caused by some existing pattern being needlessly |
| 6079 | specific, having a faulty constraint, or being rejected due to a |
| 6080 | reading mistake. Unless you are familiar with the pattern databases, it |
| 6081 | may be hard to verify that there really is a pattern missing. Look |
| 6082 | around the databases to try to get a feeling for how they are |
| 6083 | organized. (This is admittedly a weak point of the pattern databases, |
| 6084 | but the goal is to make them more organized with time.) If you decide |
| 6085 | that a new pattern is needed, try to make it as general as possible, |
| 6086 | without allowing incorrect matches, by using proper classification from |
| 6087 | among snOoXx and constraints. The reading functions can be put to good |
| 6088 | use. The reason for making the patterns as general as they can be is |
| 6089 | that we need a smaller number of them then, which makes the database |
| 6090 | much easier to maintain. Of course, if you need too complicated |
| 6091 | constraints, it's usually better to split the pattern. |
| 6092 | |
| 6093 | If a move has the correct set of reasons but still is misevaluated, |
| 6094 | this is usually not a tuning problem. There are, however, some |
| 6095 | possibilities to work around these mistakes with the use of patterns. |
| 6096 | In particular, if the territorial value is off because `delta_terri()' |
| 6097 | give strange results, the (min)terri and maxterri values can be set by |
| 6098 | patterns as a workaround. This is typically done by the endgame |
| 6099 | patterns, where we can know the (minimum) value fairly well from the |
| 6100 | pattern. If it should be needed, (min)value and maxvalue can be used |
| 6101 | similarly. These possibilities should be used conservatively though, |
| 6102 | since such patterns are likely to become obsolete when better (or at |
| 6103 | least different) functions for e.g. territory estimation are being |
| 6104 | developed. |
| 6105 | |
| 6106 | In order to choose between moves with the same move reasons, e.g. |
| 6107 | moves that connect two dragons in different ways, patterns with a |
| 6108 | nonzero shape value should be used. These should give positive shape |
| 6109 | values for moves that give good shape or good aji and negative values |
| 6110 | for bad shape and bad aji. Notice that these values are additive, so |
| 6111 | it's important that the matches are unique. |
| 6112 | |
| 6113 | Sente moves are indicated by the use of the pattern followup value. |
| 6114 | This can usually not be estimated very accurately, but a good rule is |
| 6115 | to be rather conservative. As usual it should be measured in terms of |
| 6116 | actual points on the board. These values are also additive so the same |
| 6117 | care must be taken to avoid unintended multiple matches. |
| 6118 | |
| 6119 | You can also get a visual display of the dragons using the `-T' |
| 6120 | option. The default GNU Go configuration tries to build a version with |
| 6121 | color support using either curses or the ansi escape sequences. You are |
| 6122 | more likely to find color support in rxvt than xterm, at least on many |
| 6123 | systems, so we recommend running: |
| 6124 | |
| 6125 | gnugo -l [filename] -L [move number] -T |
| 6126 | |
| 6127 | in an rxvt window. If you do not see a color display, and if your host |
| 6128 | is a GNU/Linux machine, try this again in the Linux console. |
| 6129 | |
| 6130 | Worms belonging to the same dragon are labelled with the same |
| 6131 | letters. The colors indicate the value of the field `dragon.safety', |
| 6132 | which is set in `moyo.c'. |
| 6133 | |
| 6134 | Green: GNU Go thinks the dragon is alive |
| 6135 | Yellow: Status unknown |
| 6136 | Blue: GNU Go thinks the dragon is dead |
| 6137 | Red: Status critical (1.5 eyes) or weak by the algorithm |
| 6138 | in `moyo.c' |
| 6139 | |
| 6140 | If you want to get the same game over and over again, you can |
| 6141 | eliminate the randomness in GNU Go's play by providing a fixed random |
| 6142 | seed with the `-r' option. |
| 6143 | |
| 6144 | \1f |
| 6145 | File: gnugo.info, Node: PM Implementation, Next: Symmetry & transformations, Prev: Tuning, Up: Patterns |
| 6146 | |
| 6147 | 9.12 Implementation |
| 6148 | =================== |
| 6149 | |
| 6150 | The pattern code in GNU Go is fairly straightforward conceptually, but |
| 6151 | because the matcher consumes a significant part of the time in choosing |
| 6152 | a move, the code is optimized for speed. Because of this there are |
| 6153 | implementation details which obscure things slightly. |
| 6154 | |
| 6155 | In GNU Go, the ascii `.db' files are precompiled into tables (see |
| 6156 | `patterns.h') by a standalone program `mkpat.c', and the resulting `.c' |
| 6157 | files are compiled and linked into the main GNU Go executable. |
| 6158 | |
| 6159 | Each pattern is compiled to a header, and a sequence of elements, |
| 6160 | which are (notionally) checked sequentially at every position and |
| 6161 | orientation of the board. These elements are relative to the pattern |
| 6162 | 'anchor' (or origin). One `X' or `O' stone is (arbitrarily) chosen to |
| 6163 | represent the origin of the pattern. (We cannot dictate one or the |
| 6164 | other since some patterns contain only one colour or the other.) All |
| 6165 | the elements are in co-ordinates relative to this position. So a |
| 6166 | pattern matches "at" board position `(m,n,o)' if the the pattern anchor |
| 6167 | stone is on `(m,n)', and the other elements match the board when the |
| 6168 | pattern is transformed by transformation number `o'. (See below for the |
| 6169 | details of the transformations, though these should not be necessary) |
| 6170 | |
| 6171 | \1f |
| 6172 | File: gnugo.info, Node: Symmetry & transformations, Next: Details, Prev: PM Implementation, Up: Patterns |
| 6173 | |
| 6174 | 9.13 Symmetry and transformations |
| 6175 | ================================= |
| 6176 | |
| 6177 | In general, each pattern must be tried in each of 8 different |
| 6178 | permutations, to reflect the symmetry of the board. But some patterns |
| 6179 | have symmetries which mean that it is unnecessary (and therefore |
| 6180 | inefficient) to try all eight. The first character after the `:' can be |
| 6181 | one of `8',`|',`\',`/', `X', `-', `+', representing the axes of |
| 6182 | symmetry. It can also be `O', representing symmetry under 180 degrees |
| 6183 | rotation. |
| 6184 | |
| 6185 | transformation I - | . \ l r / |
| 6186 | ABC GHI CBA IHG ADG CFI GDA IFC |
| 6187 | DEF DEF FED FED BEH BEH HEB HEB |
| 6188 | GHI ABC IHG CBA CFI ADG IFC GDA |
| 6189 | |
| 6190 | a b c d e f g h |
| 6191 | |
| 6192 | Then if the pattern has the following symmetries, the following are |
| 6193 | true: |
| 6194 | |
| 6195 | |
| 6196 | | c=a, d=b, g=e, h=f |
| 6197 | - b=a, c=d, e=f, g=h |
| 6198 | \ e=a, g=b, f=c, h=d |
| 6199 | / h=a, f=b, g=c, e=d |
| 6200 | O a=d, b=c, e=h, f=g |
| 6201 | X a=d=e=h, b=c=f=g |
| 6202 | + a=b=c=d, e=f=g=h |
| 6203 | |
| 6204 | We can choose to use transformations a,d,f,g as the unique |
| 6205 | transformations for patterns with either `|', `-', `\', or `/' symmetry. |
| 6206 | |
| 6207 | Thus we choose to order the transformations a,g,d,f,h,b,e,c and |
| 6208 | choose first 2 for `X' and `+', the first 4 for `|', `-', `/', and `\', |
| 6209 | the middle 4 for `O', and all 8 for non-symmetrical patterns. |
| 6210 | |
| 6211 | Each of the reflection operations (e-h) is equivalent to reflection |
| 6212 | about one arbitrary axis followed by one of the rotations (a-d). We |
| 6213 | can choose to reflect about the axis of symmetry (which causes no net |
| 6214 | change) and can therefore conclude that each of e-h is equivalent to |
| 6215 | the reflection (no-op) followed by a-d. This argument therefore |
| 6216 | extends to include `-' and `/' as well as `|' and `\'. |
| 6217 | |
| 6218 | \1f |
| 6219 | File: gnugo.info, Node: Details, Next: Grid optimization, Prev: Symmetry & transformations, Up: Patterns |
| 6220 | |
| 6221 | 9.14 Implementation Details |
| 6222 | =========================== |
| 6223 | |
| 6224 | 1. An entry in the pattern header states whether the anchor is an `X' |
| 6225 | or an `O'. This helps performance, since all transformations can be |
| 6226 | rejected at once if the anchor stone does not match. (Ideally, we |
| 6227 | could just define that the anchor is always `O' or always `X', but |
| 6228 | some patterns contain no `O' and some contain no `X'.) |
| 6229 | |
| 6230 | 2. The pattern header contains the size of the pattern (ie the |
| 6231 | co-ordinates of the top left and bottom right elements) relative to |
| 6232 | the anchor. This allows the pattern can be rejected quickly if |
| 6233 | there is not room for the pattern to fit around the anchor stone |
| 6234 | in a given orientation (ie it is too near the edge of the board). |
| 6235 | The bounding box information must first be transformed like the |
| 6236 | elements before it can be tested, and after transforming, we need |
| 6237 | to work out where the top-left and bottom-right corners are. |
| 6238 | |
| 6239 | 3. The edge constraints are implemented by notionally padding the |
| 6240 | pattern with rows or columns of `?' until it is exactly 19 (or |
| 6241 | whatever the current board size is) elements wide or high. Then the |
| 6242 | pattern is quickly rejected by (ii) above if it is not at the |
| 6243 | edge. So the example pattern above is compiled as if it was written |
| 6244 | |
| 6245 | |
| 6246 | "example" |
| 6247 | .OO???????????????? |
| 6248 | *XX???????????????? |
| 6249 | o?????????????????? |
| 6250 | :8,80 |
| 6251 | |
| 6252 | 4. The elements in a pattern are sorted so that non-space elements |
| 6253 | are checked before space elements. It is hoped that, for most of |
| 6254 | the game, more squares are empty, and so the pattern can be more |
| 6255 | quickly rejected doing it this way. |
| 6256 | |
| 6257 | 5. The actual tests are performed using an 'and-compare' sequence. |
| 6258 | Each board position is a 2-bit quantity. %00 for empty, %01 for |
| 6259 | `O', %10 for `X'. We can test for an exact match by and-ing with |
| 6260 | %11 (no-op), then comparing with 0, 1 or 2. The test for `o' is the |
| 6261 | same as a test for 'not-X', ie not %10. So and with %01 should |
| 6262 | give 0 if it matches. Similarly `x' is a test that bit 0 is not |
| 6263 | set. |
| 6264 | |
| 6265 | |
| 6266 | \1f |
| 6267 | File: gnugo.info, Node: Grid optimization, Next: Joseki Compiler, Prev: Details, Up: Patterns |
| 6268 | |
| 6269 | 9.15 The "Grid" Optimization |
| 6270 | ============================ |
| 6271 | |
| 6272 | The comparisons between pattern and board are performed as 2-bit |
| 6273 | bitwise operations. Therefore they can be performed in parallel, |
| 6274 | 16-at-a-time on a 32-bit machine. |
| 6275 | |
| 6276 | Suppose the board is layed out as follows : |
| 6277 | |
| 6278 | |
| 6279 | .X.O....OO |
| 6280 | XXXXO..... |
| 6281 | .X..OOOOOO |
| 6282 | X.X....... |
| 6283 | ....X...O. |
| 6284 | |
| 6285 | which is internally stored internally in a 2d array (binary) |
| 6286 | |
| 6287 | |
| 6288 | 00 10 00 01 00 00 00 00 01 01 |
| 6289 | 10 10 10 10 01 00 00 00 00 00 |
| 6290 | 00 10 00 00 01 01 01 01 01 01 |
| 6291 | 10 00 10 00 00 00 00 00 00 00 |
| 6292 | 00 00 00 00 10 00 00 00 01 00 |
| 6293 | |
| 6294 | we can compile this to a composite array in which each element stores |
| 6295 | the state of a 4x4 grid of squares : |
| 6296 | |
| 6297 | |
| 6298 | ???????? ???????? ???????? ... |
| 6299 | ??001000 00100001 10000100 |
| 6300 | ??101010 10101010 10101001 |
| 6301 | ??001000 00100000 10000001 |
| 6302 | |
| 6303 | ??001000 00100001 ... |
| 6304 | ??101010 10101010 |
| 6305 | ??001000 00100000 |
| 6306 | ??001000 10001000 |
| 6307 | |
| 6308 | ... |
| 6309 | |
| 6310 | ??100010 ... |
| 6311 | ??000000 |
| 6312 | ???????? |
| 6313 | ???????? |
| 6314 | |
| 6315 | Where '??' is off the board. |
| 6316 | |
| 6317 | We can store these 32-bit composites in a 2d merged-board array, |
| 6318 | substituting the illegal value %11 for '??'. |
| 6319 | |
| 6320 | Similarly, for each pattern, mkpat produces appropriate 32-bit |
| 6321 | and-value masks for the pattern elements near the anchor. It is a |
| 6322 | simple matter to test the pattern with a similar test to (5) above, but |
| 6323 | for 32-bits at a time. |
| 6324 | |
| 6325 | \1f |
| 6326 | File: gnugo.info, Node: Joseki Compiler, Next: Ladders in Joseki, Prev: Grid optimization, Up: Patterns |
| 6327 | |
| 6328 | 9.16 The Joseki Compiler |
| 6329 | ======================== |
| 6330 | |
| 6331 | GNU Go includes a joseki compiler in `patterns/joseki.c'. This processes |
| 6332 | an SGF file (with variations) and produces a sequence of patterns which |
| 6333 | can then be fed back into mkpat. The joseki database is currently in |
| 6334 | files in `patterns/' called `hoshi.sgf', `komoku.sgf', `sansan.sgf', |
| 6335 | `mokuhazushi.sgf' and `takamoku.sgf'. This division can be revised |
| 6336 | whenever need arises. |
| 6337 | |
| 6338 | The SGF files are transformed into the pattern database `.db' format |
| 6339 | by the program in `joseki.c'. These files are in turn transformed into C |
| 6340 | code by the program in `mkpat.c' and the C files are compiled and linked |
| 6341 | into the GNU Go binary. |
| 6342 | |
| 6343 | Not every node in the SGF file contributes a pattern. The nodes which |
| 6344 | contribute patterns have the joseki in the upper right corner, with the |
| 6345 | boundary marked with a square mark and other information to determine |
| 6346 | the resulting pattern marked in the comments. |
| 6347 | |
| 6348 | The intention is that the move valuation should be able to choose |
| 6349 | between the available variations by normal valuation. When this fails |
| 6350 | the primary workaround is to use shape values to increase or decrease |
| 6351 | the value. It is also possible to add antisuji variations to forbid |
| 6352 | popular suboptimal moves. As usual constraints can be used, e.g. to |
| 6353 | condition a variation on a working ladder. |
| 6354 | |
| 6355 | The joseki format has the following components for each SGF node: |
| 6356 | |
| 6357 | * A square mark (`SQ' or `MA' property) to decide how large part of |
| 6358 | the board should be included in the pattern. |
| 6359 | |
| 6360 | * A move (`W' or `B' property) with the natural interpretation. If |
| 6361 | the square mark is missing or the move is a pass, no pattern is |
| 6362 | produced for the node. |
| 6363 | |
| 6364 | * Optional labels (`LB' property), which must be a single letter |
| 6365 | each. If there is at least one label, a constraint diagram will be |
| 6366 | produced with these labels. |
| 6367 | |
| 6368 | * A comment (`C' property). As the first character it should have |
| 6369 | one of the following characters to decide its classification: |
| 6370 | - `U' - urgent move |
| 6371 | |
| 6372 | - `S' or `J' - standard move |
| 6373 | |
| 6374 | - `s' or `j' - lesser joseki |
| 6375 | |
| 6376 | - `T' - trick move |
| 6377 | |
| 6378 | - `t' - minor joseki move (tenuki OK) |
| 6379 | |
| 6380 | - `0' - antisuji (`A' can also be used) |
| 6381 | The rest of the line is ignored, as is the case of the letter. If |
| 6382 | neither of these is found, it's assumed to be a standard joseki |
| 6383 | move. |
| 6384 | |
| 6385 | In addition to this, rows starting with the following characters |
| 6386 | are recognized: |
| 6387 | - `#' - Comments. These are copied into the patterns file, |
| 6388 | above the diagram. |
| 6389 | |
| 6390 | - `;' - Constraints. These are copied into the patterns file, |
| 6391 | below the constraint diagram. |
| 6392 | |
| 6393 | - `>' - Actions. These are copied into the patterns file, below |
| 6394 | the constraint diagram. |
| 6395 | |
| 6396 | - `:' - Colon line. This is a little more complicated, but the |
| 6397 | colon line of the produced patterns always start out with |
| 6398 | ":8,s" for transformation number and sacrifice pattern class |
| 6399 | (it usually isn't a sacrifice, but it's pointless spending |
| 6400 | time checking for tactical safety). Then a joseki pattern |
| 6401 | class character is appended and finally what is included on |
| 6402 | the colon line in the comment for the SGF node. |
| 6403 | |
| 6404 | Example: If the comment in the SGF file looks like |
| 6405 | |
| 6406 | F |
| 6407 | :C,shape(3) |
| 6408 | ;xplay_attack(A,B,C,D,*) |
| 6409 | |
| 6410 | the generated pattern will have a colon line |
| 6411 | |
| 6412 | :8,sjC,shape(3) |
| 6413 | |
| 6414 | and a constraint |
| 6415 | |
| 6416 | ;xplay_attack(A,B,C,D,*) |
| 6417 | |
| 6418 | \1f |
| 6419 | File: gnugo.info, Node: Ladders in Joseki, Next: Corner Matcher, Prev: Joseki Compiler, Up: Patterns |
| 6420 | |
| 6421 | 9.17 Ladders in Joseki |
| 6422 | ====================== |
| 6423 | |
| 6424 | As an example of how to use autohelpers with the Joseki compiler, we |
| 6425 | consider an example where a Joseki is bad if a ladder fails. Assume we |
| 6426 | have the taisha and are considering connecting on the outside with the |
| 6427 | pattern |
| 6428 | |
| 6429 | --------+ |
| 6430 | ........| |
| 6431 | ........| |
| 6432 | ...XX...| |
| 6433 | ...OXO..| |
| 6434 | ...*O...| |
| 6435 | ....X...| |
| 6436 | ........| |
| 6437 | ........| |
| 6438 | |
| 6439 | But this is bad unless we have a ladder in our favor. To check this |
| 6440 | we add a constraint which may look like |
| 6441 | |
| 6442 | --------+ |
| 6443 | ........| |
| 6444 | ........| |
| 6445 | ...XX...| |
| 6446 | ...OXO..| |
| 6447 | ...*OAC.| |
| 6448 | ....DB..| |
| 6449 | ........| |
| 6450 | ........| |
| 6451 | |
| 6452 | ;oplay_attack(*,A,B,C,D) |
| 6453 | |
| 6454 | In order to accept the pattern we require that the constraint on the |
| 6455 | semicolon line evaluates to true. This particular constraint has the |
| 6456 | interpretation "Play with alternating colors, starting with `O', on the |
| 6457 | intersections `*', `A', `B', and `C'. Then check whether the stone at |
| 6458 | `D' can be captured." I.e. play to this position |
| 6459 | |
| 6460 | --------+ |
| 6461 | ........| |
| 6462 | ........| |
| 6463 | ...XX...| |
| 6464 | ...OXO..| |
| 6465 | ...OOXX.| |
| 6466 | ....XO..| |
| 6467 | ........| |
| 6468 | ........| |
| 6469 | |
| 6470 | and call `attack()' to see whether the lower `X' stone can be captured. |
| 6471 | This is not limited to ladders, but in this particular case the reading |
| 6472 | will of course involve a ladder. |
| 6473 | |
| 6474 | The constraint diagram above with letters is how it looks in the |
| 6475 | `.db' file. The joseki compiler knows how to create these from labels in |
| 6476 | the SGF node. `Cgoban' has an option to create one letter labels, but |
| 6477 | this ought to be a common feature for SGF editors. |
| 6478 | |
| 6479 | Thus in order to implement this example in SGF, one would add labels |
| 6480 | to the four intersections and a comment: |
| 6481 | |
| 6482 | ;oplay_attack(*,A,B,C,D) |
| 6483 | |
| 6484 | The appropriate constraint (autohelper macro) will then be added to |
| 6485 | the Joseki `.db' file. |
| 6486 | |
| 6487 | \1f |
| 6488 | File: gnugo.info, Node: Corner Matcher, Next: Editing Patterns, Prev: Ladders in Joseki, Up: Patterns |
| 6489 | |
| 6490 | 9.18 Corner Matcher |
| 6491 | =================== |
| 6492 | |
| 6493 | GNU Go uses a special matcher for joseki patterns. It has certain |
| 6494 | constraints on the patterns it can match, but is much faster and takes |
| 6495 | far less space to store patterns than the standard matcher. |
| 6496 | |
| 6497 | Patterns used with corner matcher have to qualify the following |
| 6498 | conditions: |
| 6499 | |
| 6500 | * They must be matchable only at a corner of the board (hence the |
| 6501 | name of the matcher). |
| 6502 | |
| 6503 | * They can consist only of `O', `X' and `.' elements. |
| 6504 | |
| 6505 | * Of all pattern values (*note Pattern Values::), corner matcher only |
| 6506 | support `shape(x)'. This is not because the matcher cannot handle |
| 6507 | other values in principle, just they are currently not used in |
| 6508 | joseki databases. |
| 6509 | |
| 6510 | Corner matcher was specifically designed for joseki patterns and |
| 6511 | they of course satisfy all the conditions above. With some |
| 6512 | modifications corner matcher could be used for fuseki patterns as well, |
| 6513 | but fullboard matcher does its work just fine. |
| 6514 | |
| 6515 | The main idea of the matcher is very same to the one of DFA matcher |
| 6516 | (*note Pattern matching with DFA::): check all available patterns at |
| 6517 | once, not a single pattern at a time. A modified version of DFA |
| 6518 | matcher could be used for joseki pattern matching, but its database |
| 6519 | would be very large. Corner matcher capitalizes on the fact that there |
| 6520 | are relatively few stones in each such pattern. |
| 6521 | |
| 6522 | Corner pattern database is organized into a tree. Nodes of the tree |
| 6523 | are called "variations". Variations represent certain sets of stones |
| 6524 | in a corner of the board. Root variation corresponds to an empty |
| 6525 | corner and a step down the tree is equivalent to adding a stone to the |
| 6526 | corner. Each variation has several properties: |
| 6527 | |
| 6528 | - stone position relative to the corner, |
| 6529 | |
| 6530 | - a flag determining whether the stone color must be equal to the |
| 6531 | first matched stone color, |
| 6532 | |
| 6533 | - number of stones in the corner area (see below) of the variation |
| 6534 | stone. |
| 6535 | |
| 6536 | By corner area we define a rectangle which corners are the current |
| 6537 | corner of the board and the position of the stone (inclusive). For |
| 6538 | instance, if the current board corner is A19 then corner area of a |
| 6539 | stone at C18 consists of A18, A19, B18, B19, C18 and C19. |
| 6540 | |
| 6541 | Variation which is a direct child of the root variation matches if |
| 6542 | there is any stone at the variation position and the stone is alone in |
| 6543 | its corner area. |
| 6544 | |
| 6545 | Variation at a deeper level of the tree matches if there is a stone |
| 6546 | of specified color in variation position and the number of stones in its |
| 6547 | corner area is equal to the number specified in variation structure. |
| 6548 | |
| 6549 | When a certain variation matches, all its children has to be checked |
| 6550 | recursively for a match. |
| 6551 | |
| 6552 | All leaf variations and some inner ones have patterns attached to |
| 6553 | them. For a pattern to match, it is required that its _parent_ |
| 6554 | variation matches. In addition, it is checked that pattern is being |
| 6555 | matched for the appropriate color (using its variation "stone color" |
| 6556 | field) and that the number of stones in the area where the pattern is |
| 6557 | being matched is indeed equal to the number of stones in the pattern. |
| 6558 | The "stone position" property of the pattern variation determines the |
| 6559 | move suggested by the pattern. |
| 6560 | |
| 6561 | Consider this joseki pattern which has four stones: |
| 6562 | |
| 6563 | ------+ |
| 6564 | ......| |
| 6565 | ......| |
| 6566 | .O*...| |
| 6567 | .XXO..| |
| 6568 | ......| |
| 6569 | ......| |
| 6570 | |
| 6571 | To encode it for the corner matcher, we have to use five variations, |
| 6572 | each next being a child of previous: |
| 6573 | |
| 6574 | Tree level Position Color Number of stones |
| 6575 | 1 R16 "same" 1 |
| 6576 | 2 P17 "same" 1 |
| 6577 | 3 Q16 "other" 2 |
| 6578 | 4 P16 "other" 4 |
| 6579 | 5 Q17 "same" 1 |
| 6580 | |
| 6581 | The fifth variation should have an attached pattern. Note that the |
| 6582 | stone color for the fifth variation is "same" because the first matched |
| 6583 | stone for this pattern is `O' which stands for the stones of the player |
| 6584 | to whom moves are being suggested with `*'. |
| 6585 | |
| 6586 | The tree consists of all variations for all patterns combined |
| 6587 | together. Variations for each patterns are sorted to allow very quick |
| 6588 | tree branch rejection and at the same time keep the database small |
| 6589 | enough. More details can be found in comments in file `mkpat.c' |
| 6590 | |
| 6591 | Corner matcher resides in `matchpat.c' in two functions: |
| 6592 | `corner_matchpat()' and `do_corner_matchpat()'. The former computes |
| 6593 | `num_stones[]' array which holds number of stones in corner areas of |
| 6594 | different intersections of the board for all possible transformations. |
| 6595 | `corner_matchpat()' also matches top-level variations. |
| 6596 | `do_corner_matchpat()' is responsible for recursive matching on the |
| 6597 | variation tree and calling callback function upon pattern match. |
| 6598 | |
| 6599 | Tree-like database for corner matcher is generated by `mkpat' |
| 6600 | program. Database generator consists of several functions, most |
| 6601 | important are: `corner_best_element()', `corner_variation_new()', |
| 6602 | `corner_follow_variation()' and `corner_add_pattern()'. |
| 6603 | |
| 6604 | \1f |
| 6605 | File: gnugo.info, Node: Editing Patterns, Prev: Corner Matcher, Up: Patterns |
| 6606 | |
| 6607 | 9.19 Emacs Mode for Editing Patterns |
| 6608 | ==================================== |
| 6609 | |
| 6610 | If you use GNU Emacs (XEmacs might work too), you can try a special |
| 6611 | mode for editing GNU Go pattern databases. The mode resides in |
| 6612 | `patterns/gnugo-db.el'. |
| 6613 | |
| 6614 | Copy the file to `emacs/site-lisp' directory. You can then load the |
| 6615 | mode with `(require 'gnugo-db)'. It makes sense to put this line into |
| 6616 | your configuration file (`~/.emacs'). You can either use |
| 6617 | `gnugo-db-mode' command to switch to pattern editing mode, or use the |
| 6618 | following code snippet to make Emacs do this automatically upon opening |
| 6619 | a file with `.db' suffix: |
| 6620 | |
| 6621 | (setq auto-mode-alist |
| 6622 | (append |
| 6623 | auto-mode-alist |
| 6624 | '(("\\.db\\'" . gnugo-db-mode)))) |
| 6625 | |
| 6626 | Pattern editing mode provides the following features: |
| 6627 | |
| 6628 | - highlighting of keywords (`Pattern', `goal_elements' and |
| 6629 | `callback_data') and comments, |
| 6630 | |
| 6631 | - making paragraphs equal to patterns (`M-h', `M-{', `M-}' and |
| 6632 | others operate on patterns), |
| 6633 | |
| 6634 | - commands for pattern creation with automatic name selection (`C-c |
| 6635 | C-p') and copying main diagram to constraint diagram (`C-c C-c'), |
| 6636 | |
| 6637 | - automated indentation of constraints and side comments (pattern |
| 6638 | descriptions). |
| 6639 | |
| 6640 | \1f |
| 6641 | File: gnugo.info, Node: DFA, Next: Utility Functions, Prev: SGF, Up: Top |
| 6642 | |
| 6643 | 10 The DFA pattern matcher |
| 6644 | ************************** |
| 6645 | |
| 6646 | In this chapter, we describe the principles of the GNU Go DFA pattern |
| 6647 | matcher. The aim of this system is to permit a fast pattern matching |
| 6648 | when it becomes time critical like in owl module (*note The Owl |
| 6649 | Code::). Since GNU Go 3.2, this is enabled by default. You can still |
| 6650 | get back the traditional pattern matcher by running `configure |
| 6651 | --disable-dfa' and then recompiling GNU Go. |
| 6652 | |
| 6653 | Otherwise, a finite state machine called a Deterministic Finite |
| 6654 | State Automaton (*note What is a DFA::) will be built off line from the |
| 6655 | pattern database. This is used at runtime to speedup pattern matching |
| 6656 | (*note Pattern matching with DFA:: and *note Incremental Algorithm::). |
| 6657 | The runtime speedup is at the cost of an increase in memory use and |
| 6658 | compile time. |
| 6659 | |
| 6660 | * Menu: |
| 6661 | |
| 6662 | * Introduction to the DFA:: Scanning the board along a path |
| 6663 | * What is a DFA:: A recall of language theory. |
| 6664 | * Pattern matching with DFA:: How to retrieve go patterns with a DFA? |
| 6665 | * Building the DFA:: Playing with explosives. |
| 6666 | * Incremental Algorithm:: The joy of determinism. |
| 6667 | * DFA Optimizations:: Some possible optimizations. |
| 6668 | |
| 6669 | \1f |
| 6670 | File: gnugo.info, Node: Introduction to the DFA, Next: What is a DFA, Up: DFA |
| 6671 | |
| 6672 | 10.1 Introduction to the DFA |
| 6673 | ============================ |
| 6674 | |
| 6675 | The general idea is as follows: |
| 6676 | |
| 6677 | For each intersection of the board, its neighbourhood is scanned |
| 6678 | following a predefined path. The actual path used does not matter very |
| 6679 | much; GNU Go uses a spiral as shown below. |
| 6680 | |
| 6681 | +---B--------------+ |
| 6682 | | C 4 A . . . . . .| |
| 6683 | D 5 1 3 9 . . . . .| |
| 6684 | E 6 2 8 . . X . . .| |
| 6685 | | F 7 . . . . . . .| |
| 6686 | | . +-> . . . . . .| |
| 6687 | | . . . . . . . . .| |
| 6688 | | . O . . . X . . .| |
| 6689 | | . . . . . . . . .| |
| 6690 | | . . . . . . . . .| |
| 6691 | +------------------+ |
| 6692 | |
| 6693 | In each step of the path, the pattern matcher jumps into a state |
| 6694 | determined by what it has found on the board so far. If we have |
| 6695 | successfully matched one or several patterns in this step, this state |
| 6696 | immediately tells us so (in its "attribute"). But the state also |
| 6697 | implicitly encodes which further patterns can still get matched: The |
| 6698 | information stored in the state contains in which state to jump next, |
| 6699 | depending on whether we find a black, white or empty intersection (or |
| 6700 | an intersection out of board) in the next step of the path. The state |
| 6701 | will also immediately tell us if we cannot find any further pattern (by |
| 6702 | telling us to jump into the "error" state). |
| 6703 | |
| 6704 | These sloppy explanations may become clearer with the definitions in |
| 6705 | the next section (*note What is a DFA::). |
| 6706 | |
| 6707 | Reading the board following a predefined path reduces the two |
| 6708 | dimentional pattern matching to a linear text searching problem. For |
| 6709 | example, this pattern |
| 6710 | |
| 6711 | ?X? |
| 6712 | .O? |
| 6713 | ?OO |
| 6714 | |
| 6715 | scanned following the path |
| 6716 | |
| 6717 | B |
| 6718 | C4A |
| 6719 | 5139 |
| 6720 | 628 |
| 6721 | 7 |
| 6722 | |
| 6723 | gives the string "OO?X.?*O*?*?" where "?" means 'don't care' and "*" |
| 6724 | means 'don't care, can even be out of board'. |
| 6725 | |
| 6726 | So we can forget that we are dealing with two dimensional patterns |
| 6727 | and consider linear patterns. |
| 6728 | |
| 6729 | \1f |
| 6730 | File: gnugo.info, Node: What is a DFA, Next: Pattern matching with DFA, Prev: Introduction to the DFA, Up: DFA |
| 6731 | |
| 6732 | 10.2 What is a DFA |
| 6733 | ================== |
| 6734 | |
| 6735 | The acronym DFA means Deterministic Finite state Automaton (See |
| 6736 | `http://www.eti.pg.gda.pl/~jandac/thesis/node12.html' or `Hopcroft & |
| 6737 | Ullman "Introduction to Language Theory"' for more details). DFA are |
| 6738 | common tools in compilers design (Read `Aho, Ravi Sethi, Ullman |
| 6739 | "COMPILERS: Principles, Techniques and Tools"' for a complete |
| 6740 | introduction), a lot of powerfull text searching algorithm like |
| 6741 | `Knuth-Morris-Pratt' or `Boyer-Moore' algorithms are based on DFA's |
| 6742 | (See `http://www-igm.univ-mlv.fr/~lecroq/string/' for a bibliography of |
| 6743 | pattern matching algorithms). |
| 6744 | |
| 6745 | Basically, a DFA is a set of "states" connected by labeled |
| 6746 | "transitions". The labels are the values read on the board, in GNU Go |
| 6747 | these values are EMPTY, WHITE, BLACK or OUT_BOARD, denoted respectively |
| 6748 | by '.','O','X' and '#'. |
| 6749 | |
| 6750 | The best way to represent a DFA is to draw its transition graph: the |
| 6751 | pattern "????..X" is recognized by the following DFA: |
| 6752 | |
| 6753 | .,X,O .,X,O .,X,O .,X,O . . X |
| 6754 | [1]------>[2]----->[3]----->[4]----->[5]--->[6]--->[7]--->[8 OK!] |
| 6755 | Start |
| 6756 | |
| 6757 | This means that starting from state [1], if you read '.','X' or 'O' |
| 6758 | on the board, go to state [2] and so on until you reach state [5]. |
| 6759 | From state [5], if you read '.', go to state [6] otherwise go to error |
| 6760 | state [0]. And so on until you reach state [8]. As soon as you reach |
| 6761 | state [8], you recognize Pattern "????..X" |
| 6762 | |
| 6763 | Adding a pattern like "XXo" ('o' is a wildcard for not 'X') will |
| 6764 | transform directly the automaton by synchronization product (*note |
| 6765 | Building the DFA::). Consider the following DFA: |
| 6766 | |
| 6767 | Start .,O .,X,O .,O,X .,X,O . . X |
| 6768 | [1]---->[2]----->[3]----->[4]------>[5]--->[6]---->[7]--->[8 OK!] |
| 6769 | | ^ ^ ^ |
| 6770 | | .,O | | | |
| 6771 | | ---- | | |
| 6772 | | | X | | |
| 6773 | | | --- .,X,O | |
| 6774 | | | | | |
| 6775 | | X | X | O,. | |
| 6776 | --------->[9]------>[A]--->[B OK!]- |
| 6777 | |
| 6778 | By adding a special "error" state and completing each state by a |
| 6779 | transition to error state when there is none, we transform easily a DFA |
| 6780 | in a "Complete Deterministic Finite state Automaton" (CDFA). The |
| 6781 | synchronization product (*note Building the DFA::) is only possible on |
| 6782 | CDFA's. |
| 6783 | |
| 6784 | Start .,O .,X,O .,O,X .,X,O . . X |
| 6785 | [1]---->[2]----->[3]----->[4]------>[5]--->[6]---->[7]--->[8 OK!] |
| 6786 | | ^ ^ ^ | | | |
| 6787 | | .,O | | | | | | |
| 6788 | | ---- | | | | | |
| 6789 | | | X | | |X,O | .,O |X,.,O |
| 6790 | | | --- .,X,O | | | | |
| 6791 | | | | | | | | |
| 6792 | | X | X | O,. | \ / \ / \ / |
| 6793 | --------->[9]------>[A]--->[B OK!]- [0 Error state !] |
| 6794 | |
| 6795 | The graph of a CDFA is coded by an array of states: The 0 state is |
| 6796 | the "error" state and the start state is 1. |
| 6797 | |
| 6798 | ---------------------------------------------------- |
| 6799 | state | . | O | X | # | att |
| 6800 | ---------------------------------------------------- |
| 6801 | 1 | 2 | 2 | 9 | 0 | |
| 6802 | 2 | 3 | 3 | 3 | 0 | |
| 6803 | 3 | 4 | 4 | 4 | 0 | |
| 6804 | 5 | 6 | 0 | 0 | 0 | |
| 6805 | 6 | 7 | 0 | 0 | 0 | |
| 6806 | 7 | 0 | 0 | 8 | 0 | |
| 6807 | 8 | 0 | 0 | 0 | 0 | Found pattern "????..X" |
| 6808 | 9 | 3 | 3 | A | 0 | |
| 6809 | A | B | B | 4 | 0 | |
| 6810 | B | 5 | 5 | 5 | 0 | Found pattern "XXo" |
| 6811 | ---------------------------------------------------- |
| 6812 | |
| 6813 | To each state we associate an often empty list of attributes which |
| 6814 | is the list of pattern indexes recognized when this state is reached. |
| 6815 | In '`dfa.h'' this is basically represented by two stuctures: |
| 6816 | |
| 6817 | ` |
| 6818 | /* dfa state */ |
| 6819 | typedef struct state |
| 6820 | { |
| 6821 | int next[4]; /* transitions for EMPTY, BLACK, WHITE and OUT_BOARD */ |
| 6822 | attrib_t *att; |
| 6823 | } |
| 6824 | state_t; |
| 6825 | |
| 6826 | /* dfa */ |
| 6827 | typedef struct dfa |
| 6828 | { |
| 6829 | attrib_t *indexes; /* Array of pattern indexes */ |
| 6830 | int maxIndexes; |
| 6831 | |
| 6832 | state_t *states; /* Array of states */ |
| 6833 | int maxStates; |
| 6834 | } |
| 6835 | dfa_t;' |
| 6836 | |
| 6837 | \1f |
| 6838 | File: gnugo.info, Node: Pattern matching with DFA, Next: Building the DFA, Prev: What is a DFA, Up: DFA |
| 6839 | |
| 6840 | 10.3 Pattern matching with DFA |
| 6841 | ============================== |
| 6842 | |
| 6843 | Recognizing with a DFA is very simple and thus very fast (See |
| 6844 | '`scan_for_pattern()'' in the '`engine/matchpat.c'' file). |
| 6845 | |
| 6846 | Starting from the start state, we only need to read the board |
| 6847 | following the spiral path, jump from states to states following the |
| 6848 | transitions labelled by the values read on the board and collect the |
| 6849 | patterns indexes on the way. If we reach the error state (zero), it |
| 6850 | means that no more patterns will be matched. The worst case complexity |
| 6851 | of this algorithm is o(m) where m is the size of the biggest pattern. |
| 6852 | |
| 6853 | Here is an example of scan: |
| 6854 | |
| 6855 | First we build a minimal DFA recognizing these patterns: "X..X", |
| 6856 | "X???", "X.OX" and "X?oX". Note that wildcards like '?','o', or 'x' |
| 6857 | give multiple out-transitions. |
| 6858 | |
| 6859 | ---------------------------------------------------- |
| 6860 | state | . | O | X | # | att |
| 6861 | ---------------------------------------------------- |
| 6862 | 1 | 0 | 0 | 2 | 0 | |
| 6863 | 2 | 3 | 10 | 10 | 0 | |
| 6864 | 3 | 4 | 7 | 9 | 0 | |
| 6865 | 4 | 5 | 5 | 6 | 0 | |
| 6866 | 5 | 0 | 0 | 0 | 0 | 2 |
| 6867 | 6 | 0 | 0 | 0 | 0 | 4 2 1 |
| 6868 | 7 | 5 | 5 | 8 | 0 | |
| 6869 | 8 | 0 | 0 | 0 | 0 | 4 2 3 |
| 6870 | 9 | 5 | 5 | 5 | 0 | |
| 6871 | 10 | 11 | 11 | 9 | 0 | |
| 6872 | 11 | 5 | 5 | 12 | 0 | |
| 6873 | 12 | 0 | 0 | 0 | 0 | 4 2 |
| 6874 | ---------------------------------------------------- |
| 6875 | |
| 6876 | We perform the scan of the string "X..XXO...." starting from state 1: |
| 6877 | |
| 6878 | Current state: 1, substring to scan : X..XXO.... |
| 6879 | |
| 6880 | We read an 'X' value, so from state 1 we must go to state 2. |
| 6881 | |
| 6882 | Current state: 2, substring to scan : ..XXO.... |
| 6883 | |
| 6884 | We read a '.' value, so from state 2 we must go to state 3 and so on |
| 6885 | ... |
| 6886 | |
| 6887 | Current state: 3, substring to scan : .XXO.... |
| 6888 | Current state: 4, substring to scan : XXO.... |
| 6889 | Current state: 6, substring to scan : XO.... |
| 6890 | Found pattern 4 |
| 6891 | Found pattern 2 |
| 6892 | Found pattern 1 |
| 6893 | |
| 6894 | After reaching state 6 where we match patterns 1,2 and 4, there is |
| 6895 | no out-transitions so we stop the matching. To keep the same match |
| 6896 | order as in the standard algorithm, the patterns indexes are collected |
| 6897 | in an array and sorted by indexes. |
| 6898 | |
| 6899 | \1f |
| 6900 | File: gnugo.info, Node: Building the DFA, Next: Incremental Algorithm, Prev: Pattern matching with DFA, Up: DFA |
| 6901 | |
| 6902 | 10.4 Building the DFA |
| 6903 | ===================== |
| 6904 | |
| 6905 | The most flavouring point is the building of the minimal DFA |
| 6906 | recognizing a given set of patterns. To perform the insertion of a new |
| 6907 | pattern into an already existing DFA one must completly rebuild the |
| 6908 | DFA: the principle is to build the minimal CDFA recognizing the new |
| 6909 | pattern to replace the original CDFA with its "synchronised product" by |
| 6910 | the new one. |
| 6911 | |
| 6912 | We first give a formal definition: Let L be the left CDFA and R be |
| 6913 | the right one. Let B be the "synchronised product" of L by R. Its |
| 6914 | states are the couples (l,r) where l is a state of L and r is a state |
| 6915 | of R. The state (0,0) is the error state of B and the state (1,1) is |
| 6916 | its initial state. To each couple (l,r) we associate the union of |
| 6917 | patterns recognized in both l and r. The transitions set of B is the |
| 6918 | set of transitions (l1,r1)--a-->(l2,r2) for each symbol 'a' such that |
| 6919 | both l1--a-->l2 in L and r1--a-->r2 in R. |
| 6920 | |
| 6921 | The maximal number of states of B is the product of the number of |
| 6922 | states of L and R but almost all this states are non reachable from the |
| 6923 | initial state (1,1). |
| 6924 | |
| 6925 | The algorithm used in function '`sync_product()'' builds the minimal |
| 6926 | product DFA only by keeping the reachable states. It recursively scans |
| 6927 | the product CDFA by following simultaneously the transitions of L and |
| 6928 | R. A hast table (`gtest') is used to check if a state (l,r) has already |
| 6929 | been reached, the reachable states are remapped on a new DFA. The CDFA |
| 6930 | thus obtained is minimal and recognizes the union of the two patterns |
| 6931 | sets. |
| 6932 | |
| 6933 | It is possible to construct a special pattern database that |
| 6934 | generates an "explosive" automaton: the size of the DFA is in the worst |
| 6935 | case exponential in the number of patterns it recognizes. But it |
| 6936 | doesn't occur in pratical situations: the DFA size tends to be |
| 6937 | "stable". By "stable" we mean that if we add a pattern which greatly |
| 6938 | increases the size of the DFA it also increases the chance that the |
| 6939 | next added pattern does not increase its size at all. Nevertheless |
| 6940 | there are many ways to reduce the size of the DFA. Good compression |
| 6941 | methods are explained in `Aho, Ravi Sethi, Ullman "COMPILERS: |
| 6942 | Principles, Techniques and Tools" chapter Optimization of DFA-based |
| 6943 | pattern matchers'. |
| 6944 | |
| 6945 | \1f |
| 6946 | File: gnugo.info, Node: Incremental Algorithm, Next: DFA Optimizations, Prev: Building the DFA, Up: DFA |
| 6947 | |
| 6948 | 10.5 Incremental Algorithm |
| 6949 | ========================== |
| 6950 | |
| 6951 | The incremental version of the DFA pattern matcher is not yet |
| 6952 | implemented in GNU Go but we explain here how it will work. By |
| 6953 | definition of a deterministic automaton, scanning the same string will |
| 6954 | reach the same states every time. |
| 6955 | |
| 6956 | Each reached state during pattern matching is stored in a stack |
| 6957 | `top_stack[i][j]' and `state_stack[i][j][stack_idx]' We use one stack |
| 6958 | by intersection `(i,j)'. A precomputed reverse path list allows to |
| 6959 | know for each couple of board intersections `(x,y)' its position |
| 6960 | `reverse(x,y)' in the spiral scan path starting from `(0,0)'. |
| 6961 | |
| 6962 | When a new stone is put on the board at `(lx,ly)', the only work of |
| 6963 | the pattern matcher is: |
| 6964 | |
| 6965 | ` |
| 6966 | for(each stone on the board at (i,j)) |
| 6967 | if(reverse(lx-i,ly-j) < top_stack[i][j]) |
| 6968 | { |
| 6969 | begin the dfa scan from the state |
| 6970 | state_stack[i][j][reverse(lx-i,ly-j)]; |
| 6971 | } |
| 6972 | ' |
| 6973 | |
| 6974 | In most situations reverse(lx-i,ly-j) will be inferior to |
| 6975 | top_stack[i][j]. This should speedup a lot pattern matching. |
| 6976 | |
| 6977 | \1f |
| 6978 | File: gnugo.info, Node: DFA Optimizations, Prev: Incremental Algorithm, Up: DFA |
| 6979 | |
| 6980 | 10.6 Some DFA Optimizations |
| 6981 | =========================== |
| 6982 | |
| 6983 | The DFA is constructed to minimize jumps in memory making some |
| 6984 | assumptions about the frequencies of the values: the EMPTY value is |
| 6985 | supposed to appear often on the board, so the the '.' transition are |
| 6986 | almost always successors in memory. The OUT_BOARD are supposed to be |
| 6987 | rare, so '#' transitions will almost always imply a big jump. |
| 6988 | |
| 6989 | \1f |
| 6990 | File: gnugo.info, Node: Tactical Reading, Next: Pattern Based Reading, Prev: Patterns, Up: Top |
| 6991 | |
| 6992 | 11 Tactical reading |
| 6993 | ******************* |
| 6994 | |
| 6995 | The process of visualizing potential moves done by you and your |
| 6996 | opponent to learn the result of different moves is called "reading". |
| 6997 | GNU Go does three distinct types of reading: "tactical reading" which |
| 6998 | typically is concerned with the life and death of individual strings, |
| 6999 | "Owl reading" which is concerned with the life and death of dragons, |
| 7000 | and "connection reading". In this Chapter, we document the tactical |
| 7001 | reading code, which is in `engine/reading.c'. |
| 7002 | |
| 7003 | * Menu: |
| 7004 | |
| 7005 | * Reading Basics:: Reading Basics |
| 7006 | * Hashing:: Hashing of positions |
| 7007 | * Persistent Cache:: Persistent Reading Cache |
| 7008 | * Ko:: Ko handling |
| 7009 | * A Ko Example:: A Ko Example |
| 7010 | * Another Ko Example:: Another Ko Example |
| 7011 | * Alternate Komaster Schemes:: Alternate Komaster Schemes |
| 7012 | * Superstrings:: Superstrings |
| 7013 | * Debugging:: Debugging the reading code |
| 7014 | * Connection Reading:: Connection Reading |
| 7015 | |
| 7016 | \1f |
| 7017 | File: gnugo.info, Node: Reading Basics, Next: Hashing, Up: Tactical Reading |
| 7018 | |
| 7019 | 11.1 Reading Basics |
| 7020 | =================== |
| 7021 | |
| 7022 | What we call _Tactical Reading_ is the analysis whether there is a |
| 7023 | direct capture of a single string, or whether there is a move to prevent |
| 7024 | such a direct capture. |
| 7025 | |
| 7026 | If the reading module finds out that the string can get captured, |
| 7027 | this answer should (usually) be trusted. However, if it says it can be |
| 7028 | defended, this does not say as much. It is often the case that such a |
| 7029 | string has no chance to make a life, but that it cannot be captured |
| 7030 | within the horizon (and the cutoff heuristics) of the tactical reading. |
| 7031 | |
| 7032 | The tactical reading is done by the functions in `engine/reading.c'. |
| 7033 | It is a minimax search that declares win for the attacker once he can |
| 7034 | physically take the string off board, whereas the defense is considered |
| 7035 | successful when the string has sufficiently many liberties. A string |
| 7036 | with five liberties is always considered alive. At higher depth within |
| 7037 | the search tree even fewer liberties cause GNU Go to give up the attack, |
| 7038 | *Note depthparams::. |
| 7039 | |
| 7040 | The reading code makes use of a stack onto which board positions can |
| 7041 | be pushed. The parameter `stackp' is zero if GNU Go is examining the |
| 7042 | true board position; if it is higher than zero, then GNU Go is |
| 7043 | examining a hypothetical position obtained by playing several moves. |
| 7044 | |
| 7045 | The most important public reading functions are `attack' and |
| 7046 | `find_defense'. These are wrappers for functions `do_attack' and |
| 7047 | `do_find_defense' which are declared statically in `reading.c'. The |
| 7048 | functions `do_attack' and `do_find_defense' call each other recursively. |
| 7049 | |
| 7050 | 11.1.1 Organization of the reading code |
| 7051 | --------------------------------------- |
| 7052 | |
| 7053 | The function `do_attack' and `do_find_defense' are wrappers themselves |
| 7054 | and call `attack1', `attack2', `attack3' or `attack4' resp. `defend1', |
| 7055 | `defend1', `defend1' or `defend1' depending on the number of liberties. |
| 7056 | |
| 7057 | These are fine-tuned to generate and try out the moves in an |
| 7058 | efficient order. They generate a few moves themselves (mostly direct |
| 7059 | liberties of the string), and then call helper functions called |
| 7060 | `..._moves' which suggest less obvious moves. Which of these functions |
| 7061 | get called depends on the number of liberties and of the current search |
| 7062 | depth. |
| 7063 | |
| 7064 | 11.1.2 Return Codes |
| 7065 | ------------------- |
| 7066 | |
| 7067 | The return codes of the reading (and owl) functions and owl can be `0', |
| 7068 | `KO_B', `KO_A' or `WIN'. Each reading function determines whether a |
| 7069 | particular player (assumed to have the move) can solve a specific |
| 7070 | problem, typically attacking or defending a string. |
| 7071 | |
| 7072 | A return code of `WIN' means success, 0 failure, while `KO_A' and |
| 7073 | `KO_B' are success conditioned on ko. A function returns `KO_A' if the |
| 7074 | position results in ko and that the player to move will get the first |
| 7075 | ko capture (so the opponent has to make the first ko threat). A return |
| 7076 | code of `KO_B' means that the player to move will have to make the |
| 7077 | first ko threat. |
| 7078 | |
| 7079 | If GNU Go is compiled with the configure option |
| 7080 | `--enable-experimental-owl-ext' then the owl functions also have |
| 7081 | possible return codes of `GAIN' and `LOSS'. A code of `GAIN' means that |
| 7082 | the attack (or defense) does not succeed, but that in the process of |
| 7083 | trying to attack or defend, an opponent's worm is captured. A code of |
| 7084 | `LOSS' means that the attack or defense succeeds, but that another |
| 7085 | friendly worm dies during the attack or defense. |
| 7086 | |
| 7087 | 11.1.3 Reading cutoff and depth parameters |
| 7088 | ------------------------------------------ |
| 7089 | |
| 7090 | Depth of reading is controlled by the parameters `depth' and |
| 7091 | `branch_depth'. The `depth' has a default value `DEPTH' (in |
| 7092 | `liberty.h'), which is set to 16 in the distribution, but it may also |
| 7093 | be set at the command line using the `-D' or `--depth' option. If |
| 7094 | `depth' is increased, GNU Go will be stronger and slower. GNU Go will |
| 7095 | read moves past depth, but in doing so it makes simplifying assumptions |
| 7096 | that can cause it to miss moves. |
| 7097 | |
| 7098 | Specifically, when `stackp > depth', GNU Go assumes that as soon as |
| 7099 | the string can get 3 liberties it is alive. This assumption is |
| 7100 | sufficient for reading ladders. |
| 7101 | |
| 7102 | The `branch_depth' is typically set a little below `depth'. Between |
| 7103 | `branch_depth' and `depth', attacks on strings with 3 liberties are |
| 7104 | considered, but branching is inhibited, so fewer variations are |
| 7105 | considered. |
| 7106 | |
| 7107 | %%Currently the reading code does not try to defend a string by |
| 7108 | %attacking a boundary string with more than two liberties. Because %of |
| 7109 | this restriction, it can make oversights. A symptom of this is %two |
| 7110 | adjacent strings, each having three or four liberties, each %classified |
| 7111 | as `DEAD'. To resolve such situations, a function %`small_semeai()' (in |
| 7112 | `engine/semeai.c') looks for such %pairs of strings and corrects their |
| 7113 | classification. |
| 7114 | |
| 7115 | The `backfill_depth' is a similar variable with a default 12. Below |
| 7116 | this depth, GNU Go will try "backfilling" to capture stones. For |
| 7117 | example in this situation: |
| 7118 | |
| 7119 | |
| 7120 | .OOOOOO. on the edge of the board, O can capture X but |
| 7121 | OOXXXXXO in order to do so he has to first play at a in |
| 7122 | .aObX.XO preparation for making the atari at b. This is |
| 7123 | -------- called backfilling. |
| 7124 | |
| 7125 | Backfilling is only tried with `stackp <= backfill_depth'. The |
| 7126 | parameter `backfill_depth' may be set using the `-B' option. |
| 7127 | |
| 7128 | The `fourlib_depth' is a parameter with a default of only 7. Below |
| 7129 | this depth, GNU Go will try to attack strings with four liberties. The |
| 7130 | `fourlib_depth' may be set using the `-F' option. |
| 7131 | |
| 7132 | The parameter `ko_depth' is a similar cutoff. If `stackp<ko_depth', |
| 7133 | the reading code will make experiments involving taking a ko even if it |
| 7134 | is not legal to do so (i.e., it is hypothesized that a remote ko threat |
| 7135 | is made and answered before continuation). This parameter may be set |
| 7136 | using the `-K' option. |
| 7137 | |
| 7138 | * `int attack(int str, int *move)' |
| 7139 | |
| 7140 | Determines if the string at `str' can be attacked, and if so, |
| 7141 | `*move' returns the attacking move, unless `*movei' is a null |
| 7142 | pointer. (Use null pointers if you are interested in the |
| 7143 | result of the attack but not the attacking move itself.) |
| 7144 | Returns `WIN', if the attack succeeds, 0 if it fails, and |
| 7145 | `KO_A' or `KO_B' if the result depends on ko *note Return |
| 7146 | Codes::. |
| 7147 | |
| 7148 | * `find_defense(int str, int *move)' |
| 7149 | |
| 7150 | Attempts to find a move that will save the string at `str'. It |
| 7151 | returns true if such a move is found, with `*move' the |
| 7152 | location of the saving move (unless `*move' is a null |
| 7153 | pointer). It is not checked that tenuki defends, so this may |
| 7154 | give an erroneous answer if `!attack(str)'. Returns `KO_A' |
| 7155 | or `KO_B' if the result depends on ko *Note Return Codes::. |
| 7156 | |
| 7157 | * `safe_move(int str, int color)' : |
| 7158 | |
| 7159 | The function `safe_move(str, color)' checks whether a move at |
| 7160 | `str' is illegal or can immediately be captured. If |
| 7161 | `stackp==0' the result is cached. If the move only can be |
| 7162 | captured by a ko, it's considered safe. This may or may not |
| 7163 | be a good convention. |
| 7164 | |
| 7165 | \1f |
| 7166 | File: gnugo.info, Node: Hashing, Next: Persistent Cache, Prev: Reading Basics, Up: Tactical Reading |
| 7167 | |
| 7168 | 11.2 Hashing of Positions |
| 7169 | ========================= |
| 7170 | |
| 7171 | To speed up the reading process, we note that a position can be reached |
| 7172 | in several different ways. In fact, it is a very common occurrence |
| 7173 | that a previously checked position is rechecked, often within the same |
| 7174 | search but from a different branch in the recursion tree. |
| 7175 | |
| 7176 | This wastes a lot of computing resources, so in a number of places, |
| 7177 | we store away the current position, the function we are in, and which |
| 7178 | worm is under attack or to be defended. When the search for this |
| 7179 | position is finished, we also store away the result of the search and |
| 7180 | which move made the attack or defense succeed. |
| 7181 | |
| 7182 | All this data is stored in a hash table, sometimes also called a |
| 7183 | transposition table, where Go positions are the key and results of the |
| 7184 | reading for certain functions and groups are the data. You can increase |
| 7185 | the size of the Hash table using the `-M' or `--memory' option *note |
| 7186 | Invoking GNU Go::. |
| 7187 | |
| 7188 | The hash table is created once and for all at the beginning of the |
| 7189 | game by the function `hashtable_new()'. Although hash memory is thus |
| 7190 | allocated only once in the game, the table is reinitialized at the |
| 7191 | beginning of each move by a call to `hashtable_clear()' from |
| 7192 | `genmove()'. |
| 7193 | |
| 7194 | * Menu: |
| 7195 | |
| 7196 | * Hash Calculation:: Calculation of the hash value |
| 7197 | * Hash Organization:: Organization of the hash table |
| 7198 | * Hash Structures:: Structures in `hash.h' |
| 7199 | |
| 7200 | \1f |
| 7201 | File: gnugo.info, Node: Hash Calculation, Next: Hash Organization, Up: Hashing |
| 7202 | |
| 7203 | 11.2.1 Calculation of the hash value |
| 7204 | ------------------------------------ |
| 7205 | |
| 7206 | The hash algorithm is called Zobrist hashing, and is a standard |
| 7207 | technique for go and chess programming. The algorithm as used by us |
| 7208 | works as follows: |
| 7209 | |
| 7210 | 1. First we define a "go position". This positions consists of |
| 7211 | * the actual board, i.e. the locations and colors of the stones |
| 7212 | |
| 7213 | * A "ko point", if a ko is going on. The ko point is defined as |
| 7214 | the empty point where the last single stone was situated |
| 7215 | before it was captured. |
| 7216 | |
| 7217 | It is not necessary to specify the color to move (white or black) |
| 7218 | as part of the position. The reason for this is that read results |
| 7219 | are stored separately for the various reading functions such as |
| 7220 | `attack3', and it is implicit in the calling function which player |
| 7221 | is to move. |
| 7222 | |
| 7223 | 2. For each location on the board we generate random numbers: |
| 7224 | * A number which is used if there is a white stone on this |
| 7225 | location |
| 7226 | |
| 7227 | * A number which is used if there is a black stone on this |
| 7228 | location |
| 7229 | |
| 7230 | * A number which is used if there is a ko on this location |
| 7231 | |
| 7232 | These random numbers are generated once at initialization time and |
| 7233 | then used throughout the life time of the hash table. |
| 7234 | |
| 7235 | 3. The hash key for a position is the XOR of all the random numbers |
| 7236 | which are applicable for the position (white stones, black stones, |
| 7237 | and ko position). |
| 7238 | |
| 7239 | \1f |
| 7240 | File: gnugo.info, Node: Hash Organization, Next: Hash Structures, Prev: Hash Calculation, Up: Hashing |
| 7241 | |
| 7242 | 11.2.2 Organization of the hash table |
| 7243 | ------------------------------------- |
| 7244 | |
| 7245 | The hash table consists of 3 parts: |
| 7246 | |
| 7247 | * An area which contains so called "Hash Nodes". Each hash node |
| 7248 | contains: |
| 7249 | - A go position as defined above. |
| 7250 | |
| 7251 | - A computed hash value for the position |
| 7252 | |
| 7253 | - A pointer to Read Results (see below) |
| 7254 | |
| 7255 | - A pointer to another hash node. |
| 7256 | |
| 7257 | * An area with so called Read Results. These are used to store |
| 7258 | which function was called in the go position, which string was |
| 7259 | under attack or to be defended, and the result of the reading. |
| 7260 | |
| 7261 | Each Read Result contains: |
| 7262 | - the function ID (an int between 0 and 255), the position of |
| 7263 | the string under attack and a depth value, which is used to |
| 7264 | determine how deep the search was when it was made, packed |
| 7265 | into one 32 bit integer. |
| 7266 | |
| 7267 | - The result of the search (a numeric value) and a position to |
| 7268 | play to get the result packed into one 32 bit integer. |
| 7269 | |
| 7270 | - A pointer to another Read Result. |
| 7271 | |
| 7272 | * An array of pointers to hash nodes. This is the hash table proper. |
| 7273 | |
| 7274 | |
| 7275 | When the hash table is created, these 3 areas are allocated using |
| 7276 | `malloc()'. When the hash table is populated, all contents are taken |
| 7277 | from the Hash nodes and the Read results. No further allocation is done |
| 7278 | and when all nodes or results are used, the hash table is full. |
| 7279 | Nothing is deleted from the hash table except when it is totally |
| 7280 | emptied, at which point it can be used again as if newly initialized. |
| 7281 | |
| 7282 | When a function wants to use the hash table, it looks up the current |
| 7283 | position using `hashtable_search()'. If the position doesn't already |
| 7284 | exist there, it can be entered using |
| 7285 | |
| 7286 | `hashtable_enter_position()'. |
| 7287 | |
| 7288 | Once the function has a pointer to the hash node containing a |
| 7289 | function, it can search for a result of a previous search using |
| 7290 | `hashnode_search()'. If a result is found, it can be used, and if not, |
| 7291 | a new result can be entered after a search using `hashnode_new_result()'. |
| 7292 | |
| 7293 | Hash nodes which hash to the same position in the hash table |
| 7294 | (collisions) form a simple linked list. Read results for the same |
| 7295 | position, created by different functions and different attacked or |
| 7296 | defended strings also form a linked list. |
| 7297 | |
| 7298 | This is deemed sufficiently efficient for now, but the representation |
| 7299 | of collisions could be changed in the future. It is also not |
| 7300 | determined what the optimum sizes for the hash table, the number of |
| 7301 | positions and the number of results are. |
| 7302 | |
| 7303 | \1f |
| 7304 | File: gnugo.info, Node: Hash Structures, Prev: Hash Organization, Up: Hashing |
| 7305 | |
| 7306 | 11.2.3 Hash Structures |
| 7307 | ---------------------- |
| 7308 | |
| 7309 | The basic hash structures are declared in `engine/hash.h' and |
| 7310 | `engine/cache.c' |
| 7311 | |
| 7312 | typedef struct hashposition_t { |
| 7313 | Compacttype board[COMPACT_BOARD_SIZE]; |
| 7314 | int ko_pos; |
| 7315 | } Hashposition; |
| 7316 | |
| 7317 | Represents the board and optionally the location of a ko, which is |
| 7318 | an illegal move. The player whose move is next is not recorded. |
| 7319 | |
| 7320 | typedef struct { |
| 7321 | Hashvalue hashval; |
| 7322 | Hashposition hashpos; |
| 7323 | } Hash_data; |
| 7324 | |
| 7325 | Represents the return value of a function (`hashval') and the board |
| 7326 | state (`hashpos'). |
| 7327 | |
| 7328 | typedef struct read_result_t { |
| 7329 | unsigned int data1; |
| 7330 | unsigned int data2; |
| 7331 | |
| 7332 | struct read_result_t *next; |
| 7333 | } Read_result; |
| 7334 | |
| 7335 | The data1 field packs into 32 bits the following fields: |
| 7336 | |
| 7337 | |
| 7338 | komaster: 2 bits (EMPTY, BLACK, WHITE, or GRAY) |
| 7339 | kom_pos : 10 bits (allows MAX_BOARD up to 31) |
| 7340 | routine : 4 bits (currently 10 different choices) |
| 7341 | str1 : 10 bits |
| 7342 | stackp : 5 bits |
| 7343 | |
| 7344 | The data2 field packs into 32 bits the following fields: |
| 7345 | |
| 7346 | |
| 7347 | status : 2 bits (0 free, 1 open, 2 closed) |
| 7348 | result1: 4 bits |
| 7349 | result2: 4 bits |
| 7350 | move : 10 bits |
| 7351 | str2 : 10 bits |
| 7352 | |
| 7353 | The `komaster' and `(kom_pos)' field are documented in *Note Ko::. |
| 7354 | |
| 7355 | When a new result node is created, 'status' is set to 1 'open'. |
| 7356 | This is then set to 2 'closed' when the result is entered. The main use |
| 7357 | for this is to identify open result nodes when the hashtable is |
| 7358 | partially cleared. Another potential use for this field is to identify |
| 7359 | repeated positions in the reading, in particular local double or triple |
| 7360 | kos. |
| 7361 | |
| 7362 | typedef struct hashnode_t { |
| 7363 | Hash_data key; |
| 7364 | Read_result * results; |
| 7365 | struct hashnode_t * next; |
| 7366 | } Hashnode; |
| 7367 | |
| 7368 | The hash table consists of hash nodes. Each hash node consists of |
| 7369 | The hash value for the position it holds, the position itself and the |
| 7370 | actual information which is purpose of the table from the start. |
| 7371 | |
| 7372 | There is also a pointer to another hash node which is used when the |
| 7373 | nodes are sorted into hash buckets (see below). |
| 7374 | |
| 7375 | typedef struct hashtable { |
| 7376 | size_t hashtablesize; /* Number of hash buckets */ |
| 7377 | Hashnode ** hashtable; /* Pointer to array of hashnode lists */ |
| 7378 | |
| 7379 | int num_nodes; /* Total number of hash nodes */ |
| 7380 | Hashnode * all_nodes; /* Pointer to all allocated hash nodes. */ |
| 7381 | int free_node; /* Index to next free node. */ |
| 7382 | |
| 7383 | int num_results; /* Total number of results */ |
| 7384 | Read_result * all_results; /* Pointer to all allocated results. */ |
| 7385 | int free_result; /* Index to next free result. */ |
| 7386 | } Hashtable; |
| 7387 | |
| 7388 | The hash table consists of three parts: |
| 7389 | |
| 7390 | * The hash table proper: a number of hash buckets with collisions |
| 7391 | being handled by a linked list. |
| 7392 | |
| 7393 | * The hash nodes. These are allocated at creation time and are |
| 7394 | never removed or reallocated in the current implementation. |
| 7395 | |
| 7396 | * The results of the searches. Since many different searches can be |
| 7397 | done in the same position, there should be more of these than hash |
| 7398 | nodes. |
| 7399 | |
| 7400 | \1f |
| 7401 | File: gnugo.info, Node: Persistent Cache, Next: Ko, Prev: Hashing, Up: Tactical Reading |
| 7402 | |
| 7403 | 11.3 Persistent Reading Cache |
| 7404 | ============================= |
| 7405 | |
| 7406 | Some calculations can be safely saved from move to move. If the |
| 7407 | opponent's move is not close to our worm or dragon, we do not have to |
| 7408 | reconsider the life or death of that group on the next move. So the |
| 7409 | result is saved in a persistent cache. Persistent caches are used for |
| 7410 | are used in the engine for several types of read results. |
| 7411 | |
| 7412 | * Tactical reading |
| 7413 | |
| 7414 | * Owl reading |
| 7415 | |
| 7416 | * Connection reading |
| 7417 | |
| 7418 | * Breakin code |
| 7419 | |
| 7420 | In this section we will discuss the persistent caching of tactical |
| 7421 | reading but the same principles apply to the other persistent caches. |
| 7422 | |
| 7423 | Persistent caching is an important performance feature. However it |
| 7424 | can lead to mistakes and debugging problems--situations where GNU Go |
| 7425 | generates the right move during debugging but plays a wrong move during |
| 7426 | a game. If you suspect a persistent cache effect you may try loading |
| 7427 | the sgf file with the `--replay' option and see if the mistake is |
| 7428 | repeated (*note Invoking GNU Go::). |
| 7429 | |
| 7430 | The function `store_persistent_cache()' is called only by `attack' |
| 7431 | and `find_defense', never from their static recursive counterparts |
| 7432 | `do_attack' and `do_defend'. The function |
| 7433 | `store_persistent_reading_cache()' attempts to cache the most expensive |
| 7434 | reading results. The function `search_persistent_reading_cache' |
| 7435 | attempts to retrieve a result from the cache. |
| 7436 | |
| 7437 | If all cache entries are occupied, we try to replace the least useful |
| 7438 | one. This is indicated by the score field, which is initially the |
| 7439 | number of nodes expended by this particular reading, and later |
| 7440 | multiplied by the number of times it has been retrieved from the cache. |
| 7441 | |
| 7442 | Once a (permanent) move is made, a number of cache entries |
| 7443 | immediately become invalid. These are cleaned away by the function |
| 7444 | `purge_persistent_reading_cache().' To have a criterion for when a |
| 7445 | result may be purged, the function `store_persistent_cache()' computes |
| 7446 | the "reading shadow" and "active area". If a permanent move is |
| 7447 | subsequently played in the active area, the cached result is |
| 7448 | invalidated. We now explain this algorithm in detail. |
| 7449 | |
| 7450 | The "reading shadow" is the concatenation of all moves in all |
| 7451 | variations, as well as locations where an illegal move has been tried. |
| 7452 | |
| 7453 | Once the read is finished, the reading shadow is expanded to the |
| 7454 | "active area" which may be cached. The intention is that as long as no |
| 7455 | stones are played in the active area, the cached value may safely be |
| 7456 | used. |
| 7457 | |
| 7458 | Here is the algorithm used to compute the active area. This |
| 7459 | algorithm is in the function `store_persistent_reading_cache()'. The |
| 7460 | most expensive readings so far are stored in the persistent cache. |
| 7461 | |
| 7462 | * The reading shadow and the string under attack are marked with the |
| 7463 | character `1'. We also include the successful move, which is most |
| 7464 | often a part of the reading shadow, but sometimes not, for example |
| 7465 | with the function `attack1()'. |
| 7466 | |
| 7467 | * Next the reading shadow is expanded by marking strings and empty |
| 7468 | vertices adjacent to the area marked `1' with the character `2'. |
| 7469 | |
| 7470 | * Next vertices adjacent to empty vertices marked `2' are labelled |
| 7471 | with the character `3'. |
| 7472 | |
| 7473 | * Next all vertices adjacent to previously marked vertices. These are |
| 7474 | marked `-1' instead of the more logical `4' because it is slightly |
| 7475 | faster to code this way. |
| 7476 | |
| 7477 | * If the stack pointer is >0 we add the moves already played from the |
| 7478 | moves stack with mark 4. |
| 7479 | |
| 7480 | \1f |
| 7481 | File: gnugo.info, Node: Ko, Next: A Ko Example, Prev: Persistent Cache, Up: Tactical Reading |
| 7482 | |
| 7483 | 11.4 Ko Handling |
| 7484 | ================ |
| 7485 | |
| 7486 | The principles of ko handling are the same for tactical reading and owl |
| 7487 | reading. |
| 7488 | |
| 7489 | We have already mentioned (*note Reading Basics::) that GNU Go uses |
| 7490 | a return code of `KO_A' or `KO_B' if the result depends on ko. The |
| 7491 | return code of `KO_B' means that the position can be won provided the |
| 7492 | player whose move calls the function can come up with a sufficiently |
| 7493 | large ko threat. In order to verify this, the function must simulate |
| 7494 | making a ko threat and having it answered by taking the ko even if it |
| 7495 | is illegal. We call such an experimental taking of the ko a |
| 7496 | "conditional" ko capture. |
| 7497 | |
| 7498 | Conditional ko captures are accomplished by the function `tryko()'. |
| 7499 | This function is like `trymove()' except that it does not require |
| 7500 | legality of the move in question. |
| 7501 | |
| 7502 | The static reading functions, and the global functions `do_attack' |
| 7503 | and `do_find_defense' consult parameters `komaster', `kom_pos', which |
| 7504 | are declared static in `board.c'. These mediate ko captures to prevent |
| 7505 | the occurrence of infinite loops. During reading, the komaster values |
| 7506 | are pushed and popped from a stack. |
| 7507 | |
| 7508 | Normally `komaster' is `EMPTY' but it can also be `BLACK', `WHITE', |
| 7509 | `GRAY_BLACK', `GRAY_WHITE' or `WEAK_KO'. The komaster is set to `color' |
| 7510 | when `color' makes a conditional ko capture. In this case `kom_pos' is |
| 7511 | set to the location of the captured ko stone. |
| 7512 | |
| 7513 | If the opponent is komaster, the reading functions will not try to |
| 7514 | take the ko at `kom_pos'. Also, the komaster is normally not allowed to |
| 7515 | take another ko. The exception is a nested ko, characterized by the |
| 7516 | condition that the captured ko stone is at distance 1 both vertically |
| 7517 | and horizontally from `kom_pos', which is the location of the last |
| 7518 | stone taken by the komaster. Thus in this situation: |
| 7519 | |
| 7520 | |
| 7521 | .OX |
| 7522 | OX*X |
| 7523 | OmOX |
| 7524 | OO |
| 7525 | |
| 7526 | Here if `m' is the location of `kom_pos', then the move at `*' is |
| 7527 | allowed. |
| 7528 | |
| 7529 | The rationale behind this rule is that in the case where there are |
| 7530 | two kos on the board, the komaster cannot win both, and by becoming |
| 7531 | komaster he has already chosen which ko he wants to win. But in the |
| 7532 | case of a nested ko, taking one ko is a precondition to taking the |
| 7533 | other one, so we allow this. |
| 7534 | |
| 7535 | If the komaster's opponent takes a ko, then both players have taken |
| 7536 | one ko. In this case `komaster' is set to `GRAY_BLACK' or `GRAY_WHITE' |
| 7537 | and after this further ko captures are even further restricted. |
| 7538 | |
| 7539 | If the ko at `kom_pos' is filled, then the komaster reverts to |
| 7540 | `EMPTY'. |
| 7541 | |
| 7542 | In detail, the komaster scheme is as follows. Color `O' is to move. |
| 7543 | This scheme is known as scheme 5 since in versions of GNU Go through |
| 7544 | 3.4, several different schemes were included. |
| 7545 | |
| 7546 | * 1. Komaster is EMPTY. |
| 7547 | - 1a. Unconditional ko capture is allowed. |
| 7548 | |
| 7549 | Komaster remains EMPTY if previous move was not a ko |
| 7550 | capture. Komaster is set to WEAK_KO if previous move |
| 7551 | was a ko capture and kom_pos is set to the old value of |
| 7552 | board_ko_pos. |
| 7553 | |
| 7554 | - 1b) Conditional ko capture is allowed. |
| 7555 | |
| 7556 | Komaster is set to O and kom_pos to the location of the |
| 7557 | ko, where a stone was just removed. |
| 7558 | |
| 7559 | * 2. Komaster is O: |
| 7560 | - 2a) Only nested ko captures are allowed. Kom_pos is moved to |
| 7561 | the new removed stone. |
| 7562 | |
| 7563 | - 2b) If komaster fills the ko at kom_pos then komaster reverts |
| 7564 | to EMPTY. |
| 7565 | |
| 7566 | * 3. Komaster is X: |
| 7567 | |
| 7568 | Play at kom_pos is not allowed. Any other ko capture is |
| 7569 | allowed. If O takes another ko, komaster becomes GRAY_X. |
| 7570 | |
| 7571 | * 4. Komaster is GRAY_O or GRAY_X: |
| 7572 | |
| 7573 | Ko captures are not allowed. If the ko at kom_pos is filled |
| 7574 | then the komaster reverts to EMPTY. |
| 7575 | |
| 7576 | * 5. Komaster is WEAK_KO: |
| 7577 | - 5a) After a non-ko move komaster reverts to EMPTY. |
| 7578 | |
| 7579 | - 5b) Unconditional ko capture is only allowed if it is nested |
| 7580 | ko capture. |
| 7581 | |
| 7582 | Komaster is changed to WEAK_X and kom_pos to the old |
| 7583 | value of board_ko_pos. |
| 7584 | |
| 7585 | - 5c) Conditional ko capture is allowed according to the rules |
| 7586 | of 1b. |
| 7587 | |
| 7588 | \1f |
| 7589 | File: gnugo.info, Node: A Ko Example, Next: Another Ko Example, Prev: Ko, Up: Tactical Reading |
| 7590 | |
| 7591 | 11.5 A Ko Example |
| 7592 | ================= |
| 7593 | |
| 7594 | To see the komaster scheme in action, consider this position from the |
| 7595 | file `regressions/games/life_and_death/tripod9.sgf'. We recommend |
| 7596 | studying this example by examining the variation file produced by the |
| 7597 | command: |
| 7598 | |
| 7599 | gnugo -l tripod9.sgf --decide-dragon C3 -o vars.sgf |
| 7600 | |
| 7601 | In the lower left hand corner, there are kos at A2 and B4. Black is |
| 7602 | unconditionally dead because if W wins either ko there is nothing B can |
| 7603 | do. |
| 7604 | |
| 7605 | |
| 7606 | 8 . . . . . . . . |
| 7607 | 7 . . O . . . . . |
| 7608 | 6 . . O . . . . . |
| 7609 | 5 O O O . . . . . |
| 7610 | 4 O . O O . . . . |
| 7611 | 3 X O X O O O O . |
| 7612 | 2 . X X X O . . . |
| 7613 | 1 X O . . . . . . |
| 7614 | A B C D E F G H |
| 7615 | |
| 7616 | This is how the komaster scheme sees this. B (i.e. X) starts by |
| 7617 | taking the ko at B4. W replies by taking the ko at A1. The board looks |
| 7618 | like this: |
| 7619 | |
| 7620 | |
| 7621 | 8 . . . . . . . . |
| 7622 | 7 . . O . . . . . |
| 7623 | 6 . . O . . . . . |
| 7624 | 5 O O O . . . . . |
| 7625 | 4 O X O O . . . . |
| 7626 | 3 X . X O O O O . |
| 7627 | 2 O X X X O . . . |
| 7628 | 1 . O . . . . . . |
| 7629 | A B C D E F G H |
| 7630 | |
| 7631 | Now any move except the ko recapture (currently illegal) at A1 loses |
| 7632 | for B, so B retakes the ko and becomes komaster. The board looks like |
| 7633 | this: |
| 7634 | |
| 7635 | |
| 7636 | 8 . . . . . . . . komaster: BLACK |
| 7637 | 7 . . O . . . . . kom_pos: A2 |
| 7638 | 6 . . O . . . . . |
| 7639 | 5 O O O . . . . . |
| 7640 | 4 O X O O . . . . |
| 7641 | 3 X . X O O O O . |
| 7642 | 2 . X X X O . . . |
| 7643 | 1 X O . . . . . . |
| 7644 | A B C D E F G H |
| 7645 | |
| 7646 | W takes the ko at B3 after which the komaster is `GRAY' and ko |
| 7647 | recaptures are not allowed. |
| 7648 | |
| 7649 | |
| 7650 | 8 . . . . . . . . komaster: GRAY |
| 7651 | 7 . . O . . . . . kom_pos: B4 |
| 7652 | 6 . . O . . . . . |
| 7653 | 5 O O O . . . . . |
| 7654 | 4 O . O O . . . . |
| 7655 | 3 X O X O O O O . |
| 7656 | 2 . X X X O . . . |
| 7657 | 1 X O . . . . . . |
| 7658 | A B C D E F G H |
| 7659 | |
| 7660 | Since B is not allowed any ko recaptures, there is nothing he can do |
| 7661 | and he is found dead. Thus the komaster scheme produces the correct |
| 7662 | result. |
| 7663 | |
| 7664 | \1f |
| 7665 | File: gnugo.info, Node: Another Ko Example, Next: Alternate Komaster Schemes, Prev: A Ko Example, Up: Tactical Reading |
| 7666 | |
| 7667 | 11.6 Another Ko Example |
| 7668 | ======================= |
| 7669 | |
| 7670 | We now consider an example to show why the komaster is reset to `EMPTY' |
| 7671 | if the ko is resolved in the komaster's favor. This means that the ko |
| 7672 | is filled, or else that is becomes no longer a ko and it is illegal for |
| 7673 | the komaster's opponent to play there. |
| 7674 | |
| 7675 | The position resulting under consideration is in the file |
| 7676 | `regressions/games/ko5.sgf'. This is the position: |
| 7677 | |
| 7678 | . . . . . . O O 8 |
| 7679 | X X X . . . O . 7 |
| 7680 | X . X X . . O . 6 |
| 7681 | . X . X X X O O 5 |
| 7682 | X X . X . X O X 4 |
| 7683 | . O X O O O X . 3 |
| 7684 | O O X O . O X X 2 |
| 7685 | . O . X O X X . 1 |
| 7686 | F G H J K L M N |
| 7687 | |
| 7688 | We recommend studying this example by examining the variation file |
| 7689 | produced by the command: |
| 7690 | |
| 7691 | gnugo -l ko5.sgf --quiet --decide-string L1 -o vars.sgf |
| 7692 | |
| 7693 | The correct resolution is that H1 attacks L1 unconditionally while K2 |
| 7694 | defends it with ko (code `KO_A'). |
| 7695 | |
| 7696 | After Black (X) takes the ko at K3, white can do nothing but retake |
| 7697 | the ko conditionally, becoming komaster. B cannot do much, but in one |
| 7698 | variation he plays at K4 and W takes at H1. The following position |
| 7699 | results: |
| 7700 | |
| 7701 | . . . . . . O O 8 |
| 7702 | X X X . . . O . 7 |
| 7703 | X . X X . . O . 6 |
| 7704 | . X . X X X O O 5 |
| 7705 | X X . X X X O X 4 |
| 7706 | . O X O O O X . 3 |
| 7707 | O O X O . O X X 2 |
| 7708 | . O O . O X X . 1 |
| 7709 | F G H J K L M N |
| 7710 | |
| 7711 | Now it is important the `O' is no longer komaster. Were `O' still |
| 7712 | komaster, he could capture the ko at N3 and there would be no way to |
| 7713 | finish off B. |
| 7714 | |
| 7715 | \1f |
| 7716 | File: gnugo.info, Node: Alternate Komaster Schemes, Next: Superstrings, Prev: Another Ko Example, Up: Tactical Reading |
| 7717 | |
| 7718 | 11.7 Alternate Komaster Schemes |
| 7719 | =============================== |
| 7720 | |
| 7721 | The following alternate schemes have been proposed. It is assumed that |
| 7722 | `O' is the player about to move. |
| 7723 | |
| 7724 | 11.7.1 Essentially the 2.7.232 scheme. |
| 7725 | -------------------------------------- |
| 7726 | |
| 7727 | * Komaster is EMPTY. |
| 7728 | - Unconditional ko capture is allowed. Komaster remains EMPTY. |
| 7729 | |
| 7730 | - Conditional ko capture is allowed. Komaster is set to O and |
| 7731 | `kom_pos' to the location of the ko, where a stone was just |
| 7732 | removed. |
| 7733 | |
| 7734 | * Komaster is O: |
| 7735 | - Conditional ko capture is not allowed. |
| 7736 | |
| 7737 | - Unconditional ko capture is allowed. Komaster parameters |
| 7738 | unchanged. |
| 7739 | |
| 7740 | * Komaster is X: |
| 7741 | - Conditional ko capture is not allowed. |
| 7742 | |
| 7743 | - Unconditional ko capture is allowed except for a move at |
| 7744 | `kom_pos'. Komaster parameters unchanged. |
| 7745 | |
| 7746 | 11.7.2 Revised 2.7.232 version |
| 7747 | ------------------------------ |
| 7748 | |
| 7749 | * Komaster is EMPTY. |
| 7750 | - Unconditional ko capture is allowed. Komaster remains EMPTY. |
| 7751 | |
| 7752 | - Conditional ko capture is allowed. Komaster is set to `O' and |
| 7753 | `kom_pos' to the location of the ko, where a stone was just |
| 7754 | removed. |
| 7755 | |
| 7756 | * Komaster is `O': |
| 7757 | - Ko capture (both kinds) is allowed only if after playing the |
| 7758 | move, `is_ko(kom_pos, X)' returns false. In that case, |
| 7759 | `kom_pos' is updated to the new ko position, i.e. the stone |
| 7760 | captured by this move. |
| 7761 | |
| 7762 | * Komaster is `X': |
| 7763 | - Conditional ko capture is not allowed. |
| 7764 | |
| 7765 | - Unconditional ko capture is allowed except for a move at |
| 7766 | `kom_pos'. Komaster parameters unchanged. |
| 7767 | |
| 7768 | \1f |
| 7769 | File: gnugo.info, Node: Superstrings, Next: Debugging, Prev: Alternate Komaster Schemes, Up: Tactical Reading |
| 7770 | |
| 7771 | 11.8 Superstrings |
| 7772 | ================= |
| 7773 | |
| 7774 | A _superstring_ is an extended string, where the extensions are through |
| 7775 | the following kinds of connections: |
| 7776 | |
| 7777 | 1. Solid connections (just like ordinary string). |
| 7778 | OO |
| 7779 | |
| 7780 | 2. Diagonal connection or one space jump through an intersection |
| 7781 | where an opponent move would be suicide or self-atari. |
| 7782 | ... |
| 7783 | O.O |
| 7784 | XOX |
| 7785 | X.X |
| 7786 | |
| 7787 | 3. Bamboo joint. |
| 7788 | OO |
| 7789 | .. |
| 7790 | OO |
| 7791 | |
| 7792 | 4. Diagonal connection where both adjacent intersections are empty. |
| 7793 | .O |
| 7794 | O. |
| 7795 | |
| 7796 | 5. Connection through adjacent or diagonal tactically captured stones. |
| 7797 | Connections of this type are omitted when the superstring code is |
| 7798 | called from `reading.c', but included when the superstring code is |
| 7799 | called from `owl.c'. |
| 7800 | |
| 7801 | Like a dragon, a superstring is an amalgamation of strings, but it is |
| 7802 | a much tighter organization of stones than a dragon, and its purpose is |
| 7803 | different. Superstrings are encountered already in the tactical reading |
| 7804 | because sometimes attacking or defending an element of the superstring |
| 7805 | is the best way to attack or defend a string. This is in contrast with |
| 7806 | dragons, which are ignored during tactical reading. |
| 7807 | |
| 7808 | \1f |
| 7809 | File: gnugo.info, Node: Debugging, Next: Connection Reading, Prev: Superstrings, Up: Tactical Reading |
| 7810 | |
| 7811 | 11.9 Debugging the reading code |
| 7812 | =============================== |
| 7813 | |
| 7814 | The reading code searches for a path through the move tree to determine |
| 7815 | whether a string can be captured. We have a tool for investigating this |
| 7816 | with the `--decidestring' option. This may be run with or without an |
| 7817 | output file. |
| 7818 | |
| 7819 | Simply running |
| 7820 | |
| 7821 | |
| 7822 | `gnugo -t -l [input file name] -L [movenumber] --decidestring [location]' |
| 7823 | |
| 7824 | will run `attack()' to determine whether the string can be captured. |
| 7825 | If it can, it will also run `find_defense()' to determine whether or |
| 7826 | not it can be defended. It will give a count of the number of |
| 7827 | variations read. The `-t' is necessary, or else GNU Go will not report |
| 7828 | its findings. |
| 7829 | |
| 7830 | If we add `-o OUTPUT FILE' GNU Go will produce an output file with |
| 7831 | all variations considered. The variations are numbered in comments. |
| 7832 | |
| 7833 | This file of variations is not very useful without a way of |
| 7834 | navigating the source code. This is provided with the GDB source file, |
| 7835 | listed at the end. You can source this from GDB, or just make it your |
| 7836 | GDB init file. |
| 7837 | |
| 7838 | If you are using GDB to debug GNU Go you may find it less confusing |
| 7839 | to compile without optimization. The optimization sometimes changes the |
| 7840 | order in which program steps are executed. For example, to compile |
| 7841 | `reading.c' without optimization, edit `engine/Makefile' to remove the |
| 7842 | string `-O2' from the file, touch `engine/reading.c' and make. Note |
| 7843 | that the Makefile is automatically generated and may get overwritten |
| 7844 | later. |
| 7845 | |
| 7846 | If in the course of reading you need to analyze a result where a |
| 7847 | function gets its value by returning a cached position from the hashing |
| 7848 | code, rerun the example with the hashing turned off by the command line |
| 7849 | option `--hash 0'. You should get the same result. (If you do not, |
| 7850 | please send us a bug report.) Don't run `--hash 0' unless you have a |
| 7851 | good reason to, since it increases the number of variations. |
| 7852 | |
| 7853 | With the source file given at the end of this document loaded, we |
| 7854 | can now navigate the variations. It is a good idea to use cgoban with a |
| 7855 | small `-fontHeight', so that the variation window takes in a big |
| 7856 | picture. (You can resize the board.) |
| 7857 | |
| 7858 | Suppose after perusing this file, we find that variation 17 is |
| 7859 | interesting and we would like to find out exactly what is going on here. |
| 7860 | |
| 7861 | The macro 'jt n' will jump to the n-th variation. |
| 7862 | |
| 7863 | |
| 7864 | (gdb) set args -l [filename] -L [move number] --decidestring [location] |
| 7865 | (gdb) tbreak main |
| 7866 | (gdb) run |
| 7867 | (gdb) jt 17 |
| 7868 | |
| 7869 | will then jump to the location in question. |
| 7870 | |
| 7871 | Actually the attack variations and defense variations are numbered |
| 7872 | separately. (But `find_defense()' is only run if `attack()' succeeds, |
| 7873 | so the defense variations may or may not exist.) It is redundant to |
| 7874 | have to tbreak main each time. So there are two macros avar and dvar. |
| 7875 | |
| 7876 | |
| 7877 | (gdb) avar 17 |
| 7878 | |
| 7879 | restarts the program, and jumps to the 17-th attack variation. |
| 7880 | |
| 7881 | |
| 7882 | (gdb) dvar 17 |
| 7883 | |
| 7884 | jumps to the 17-th defense variation. Both variation sets are found in |
| 7885 | the same sgf file, though they are numbered separately. |
| 7886 | |
| 7887 | Other commands defined in this file: |
| 7888 | |
| 7889 | |
| 7890 | |
| 7891 | `dump' will print the move stack. |
| 7892 | `nv' moves to the next variation |
| 7893 | `ascii i j' converts (i,j) to ascii |
| 7894 | |
| 7895 | ####################################################### |
| 7896 | ############### .gdbinit file ############### |
| 7897 | ####################################################### |
| 7898 | |
| 7899 | # this command displays the stack |
| 7900 | |
| 7901 | define dump |
| 7902 | set dump_stack() |
| 7903 | end |
| 7904 | |
| 7905 | # display the name of the move in ascii |
| 7906 | |
| 7907 | define ascii |
| 7908 | set gprintf("%o%m\n",$arg0,$arg1) |
| 7909 | end |
| 7910 | |
| 7911 | # display the all information about a dragon |
| 7912 | |
| 7913 | define dragon |
| 7914 | set ascii_report_dragon("$arg0") |
| 7915 | end |
| 7916 | |
| 7917 | define worm |
| 7918 | set ascii_report_worm("$arg0") |
| 7919 | end |
| 7920 | |
| 7921 | # move to the next variation |
| 7922 | |
| 7923 | define nv |
| 7924 | tbreak trymove |
| 7925 | continue |
| 7926 | finish |
| 7927 | next |
| 7928 | end |
| 7929 | |
| 7930 | # move forward to a particular variation |
| 7931 | |
| 7932 | define jt |
| 7933 | while (count_variations < $arg0) |
| 7934 | nv |
| 7935 | end |
| 7936 | nv |
| 7937 | dump |
| 7938 | end |
| 7939 | |
| 7940 | # restart, jump to a particular attack variation |
| 7941 | |
| 7942 | define avar |
| 7943 | delete |
| 7944 | tbreak sgffile_decidestring |
| 7945 | run |
| 7946 | tbreak attack |
| 7947 | continue |
| 7948 | jt $arg0 |
| 7949 | end |
| 7950 | |
| 7951 | # restart, jump to a particular defense variation |
| 7952 | |
| 7953 | define dvar |
| 7954 | delete |
| 7955 | tbreak sgffile_decidestring |
| 7956 | run |
| 7957 | tbreak attack |
| 7958 | continue |
| 7959 | finish |
| 7960 | next 3 |
| 7961 | jt $arg0 |
| 7962 | end |
| 7963 | |
| 7964 | \1f |
| 7965 | File: gnugo.info, Node: Connection Reading, Prev: Debugging, Up: Tactical Reading |
| 7966 | |
| 7967 | 11.10 Connection Reading |
| 7968 | ======================== |
| 7969 | |
| 7970 | GNU Go does reading to determine if strings can be connected. The |
| 7971 | algorithms for this are in `readconnect.c'. As with the reading code, |
| 7972 | the connection code is not pattern based. |
| 7973 | |
| 7974 | The connection code is invoked by the engine through the functions: |
| 7975 | |
| 7976 | * `int string_connect(int str1, int str2, int *move)' |
| 7977 | |
| 7978 | Returns `WIN' if `str1' and `str2' can be connected. |
| 7979 | |
| 7980 | * `int disconnect(int str1, int str2, int *move)' |
| 7981 | |
| 7982 | Returns `WIN' if `str1' and `str2' can be disconnected. |
| 7983 | |
| 7984 | To see the connection code in action, you may try the following |
| 7985 | example. |
| 7986 | |
| 7987 | gnugo --quiet -l connection3.sgf --decide-connection M3/N7 -o vars.sgf |
| 7988 | |
| 7989 | (The file `connection3.sgf' is in `regression/games'.) Examine the |
| 7990 | sgf file produced by this to see what kind of reading is done by the |
| 7991 | functions `string_connect()' and `string_disconnect()', which are |
| 7992 | called by the function `decide_connection'. |
| 7993 | |
| 7994 | One use of the connection code is used is through the autohelper |
| 7995 | macros `oplay_connect', `xplay_connect', `oplay_disconnect' and |
| 7996 | `xplay_disconnect' which are used in the connection databases. |
| 7997 | |
| 7998 | \1f |
| 7999 | File: gnugo.info, Node: Pattern Based Reading, Next: Influence, Prev: Tactical Reading, Up: Top |
| 8000 | |
| 8001 | 12 Pattern Based Reading |
| 8002 | ************************ |
| 8003 | |
| 8004 | In the tactical reading code in `reading.c', the code generating the |
| 8005 | moves which are tried are all hand coded in C, for efficiency. There is |
| 8006 | much to be said for another type of reading, in which the moves to be |
| 8007 | tried are generated from a pattern database. |
| 8008 | |
| 8009 | GNU Go does three main types of pattern based reading. First, there |
| 8010 | is the OWL code (Optics with Limit Negotiation) which attempts to read |
| 8011 | out to a point where the code in `engine/optics.c' (*note Eyes::) can |
| 8012 | be used to evaluate it. Like the tactical reading code, a persistent |
| 8013 | cache is employed to maintain some of the owl data from move to move. |
| 8014 | This is an essential speedup without which GNU Go would play too slowly. |
| 8015 | |
| 8016 | Secondly, there is the `engine/combination.c' which attempts to find |
| 8017 | combinations--situations where a series of threats eventually |
| 8018 | culminates in one that cannot be parried. |
| 8019 | |
| 8020 | Finally there is the semeai module. A *semeai* is a capturing race |
| 8021 | between two adjacent DEAD or CRITICAL dragons of opposite colors. The |
| 8022 | principal function, `owl_analyze_semeai()' is contained in `owl.c'. |
| 8023 | Due to the complex nature of semeais, the results of this function are |
| 8024 | more frequently wrong than the usual owl code. |
| 8025 | |
| 8026 | * Menu: |
| 8027 | |
| 8028 | * The Owl Code:: Life and death reading |
| 8029 | * Combinations:: Combinations |
| 8030 | |