Commit | Line | Data |
---|---|---|
7eeb782e AT |
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 |