| 1 | In this chapter we will discuss methods of finding |
| 2 | out how GNU Go understands a given position. These |
| 3 | methods will be of interest to anyone working on the |
| 4 | program, or simply curious about its workings. |
| 5 | |
| 6 | In practice, most tuning of GNU Go is done in conjunction |
| 7 | with maintaining the @file{regression/} directory |
| 8 | (@pxref{Regression}). |
| 9 | |
| 10 | We assume that you have a game GNU Go played saved |
| 11 | as an sgf file, and you want to know why it made a |
| 12 | certain move. |
| 13 | |
| 14 | @menu |
| 15 | * Traces:: Analyzing traces in GNU Go 3.6 |
| 16 | * Output File:: The Output File |
| 17 | * Decide string:: Checking the reading code |
| 18 | * Decide dragon:: Checking the owl code |
| 19 | * GTP and GDB techniques:: GTP and GDB techniques |
| 20 | * view.pike:: Debugging on a Graphic Board |
| 21 | * Scoring:: Finding out the winner of the game |
| 22 | * Colored Display:: Colored Display |
| 23 | @end menu |
| 24 | |
| 25 | @node Traces |
| 26 | @section Interpreting Traces |
| 27 | @cindex traces |
| 28 | @cindex tuning GNU Go |
| 29 | |
| 30 | A quick way to find out roughly the reason for a move is to run |
| 31 | |
| 32 | @example |
| 33 | gnugo -l @var{filename} -t -L @var{move number} |
| 34 | @end example |
| 35 | |
| 36 | (You may also want to add @option{--quiet} to suppress the copyright |
| 37 | message.) In GNU Go 3.6, the moves together with their reasons are |
| 38 | listed, followed by a numerical analysis of the values given to each |
| 39 | move. |
| 40 | |
| 41 | If you are tuning (@pxref{Tuning}) you may want to add the @option{-a} |
| 42 | option. This causes GNU Go to report all patterns matched, even ones |
| 43 | that cannot affect the outcome of the move. The reasons for doing |
| 44 | this is that you may want to modify a pattern already matched |
| 45 | instead of introducing a new one. |
| 46 | |
| 47 | If you use the @option{-w} option, GNU Go will report the statuses of |
| 48 | worms and dragons around the board. This type of information is |
| 49 | available by different methods, however (@pxref{view.pike}, |
| 50 | @pxref{Colored Display}). |
| 51 | |
| 52 | @node Output File |
| 53 | @section The Output File |
| 54 | @cindex output file |
| 55 | |
| 56 | If GNU Go is invoked with the option @option{-o filename} it will |
| 57 | produce an output file. This option can be added at the command line |
| 58 | in the Go Modem Protocol Setup Window of CGoban. The output file will |
| 59 | show the locations of the moves considered and their weights. It is |
| 60 | worth noting that by enlarging the CGoban window to its fullest size |
| 61 | it can display 3 digit numbers. Dragons with status @code{DEAD} are |
| 62 | labelled with an @samp{X}, and dragons with status @code{CRITICAL} are |
| 63 | labelled with a @samp{!}. |
| 64 | |
| 65 | If you have a game file which is not commented this way, or |
| 66 | which was produced by a non-current version of GNU Go you may |
| 67 | ask GNU Go to produce a commented version by running: |
| 68 | |
| 69 | @example |
| 70 | gnugo --quiet -l <old file> --replay <color> -o <new file> |
| 71 | @end example |
| 72 | |
| 73 | @noindent |
| 74 | Here <color> can be 'black,' 'white' or 'both'. The replay |
| 75 | option will also help you to find out if your current version |
| 76 | of GNU Go would play differently than the program that created |
| 77 | the file. |
| 78 | |
| 79 | @node Decide string |
| 80 | @section Checking the reading code |
| 81 | @cindex decide-string |
| 82 | |
| 83 | The @option{--decide-string} option is used to check the tactical reading code |
| 84 | (@pxref{Tactical Reading}). This option takes an argument, which is a location |
| 85 | on the board in the usual algebraic notation (e.g. |
| 86 | @option{--decide-string C17}). This will tell you whether the reading code (in |
| 87 | @file{engine/reading.c}) believes the string can be captured, and if so, |
| 88 | whether it believes it can be defended, which moves it finds to attack or |
| 89 | defend the move, how many nodes it searched in coming to these |
| 90 | conclusions. Note that when GNU Go runs normally (not with |
| 91 | @option{--decide-string}) the points of attack and defense are |
| 92 | computed when @code{make_worms()} runs and cached in |
| 93 | @code{worm.attack} and @code{worm.defend}. |
| 94 | |
| 95 | If used with an output file (@option{-o @var{filename}}) |
| 96 | @option{--decide-string} will produce a variation tree showing |
| 97 | all the variations which are considered. This is a useful way |
| 98 | of debugging the reading code, and also of educating yourself |
| 99 | with the way it works. The variation tree can be displayed |
| 100 | graphically using CGoban. |
| 101 | |
| 102 | At each node, the comment contains some information. For example you |
| 103 | may find a comment: |
| 104 | |
| 105 | @example |
| 106 | |
| 107 | attack4-B at D12 (variation 6, hash 51180fdf) |
| 108 | break_chain D12: 0 |
| 109 | defend3 D12: 1 G12 (trivial extension) |
| 110 | |
| 111 | @end example |
| 112 | |
| 113 | This is to be interpreted as follows. The node in question |
| 114 | was generated by the function @code{attack3()} in @file{engine/reading.c}, |
| 115 | which was called on the string at @code{D12}. The data in |
| 116 | parentheses tell you the values of @code{count_variations} and |
| 117 | @code{hashdata.hashval}. |
| 118 | |
| 119 | The second value (``hash'') you probably will not need to know |
| 120 | unless you are debugging the hash code, and we will not discuss it. |
| 121 | But the first value (``variation'') is useful when using the debugger |
| 122 | @command{gdb}. You can first make an output file using |
| 123 | the @option{-o} option, then walk through the reading with |
| 124 | @command{gdb}, and to coordinate the SGF file with the debugger, |
| 125 | display the value of @code{count_variations}. Specifically, |
| 126 | from the debugger you can find out where you are as follows: |
| 127 | |
| 128 | @example |
| 129 | (gdb) set dump_stack() |
| 130 | B:D13 W:E12 B:E13 W:F12 B:F11 (variation 6) |
| 131 | @end example |
| 132 | |
| 133 | If you place yourself right after the call to @code{trymove()} |
| 134 | which generated the move in question, then the variation number |
| 135 | in the SGF file should match the variation number displayed by |
| 136 | @code{dump_stack()}, and the move in question will be the |
| 137 | last move played (F11 in this example). |
| 138 | |
| 139 | This displays the sequence of moves leading up to the variation |
| 140 | in question, and it also prints @code{count_variations-1}. |
| 141 | |
| 142 | The second two lines tell you that from this node, the function |
| 143 | @code{break_chain()} was called at D12 and returned 0 meaning |
| 144 | that no way was found of rescuing the string by attacking |
| 145 | an element of the surrounding chain, and the function |
| 146 | @code{defend3()} was called also at D12 and returned 1, |
| 147 | meaning that the string can be defended, and that |
| 148 | G12 is the move that defends it. If you have trouble |
| 149 | finding the function calls which generate these comments, |
| 150 | try setting @code{sgf_dumptree=1} and setting a breakpoint in |
| 151 | @code{sgf_trace}. |
| 152 | |
| 153 | @node Decide dragon |
| 154 | @section Checking the Owl Code |
| 155 | @cindex decide-dragon |
| 156 | |
| 157 | You can similarly debug the Owl code using the option |
| 158 | @option{--decide-dragon}. Usage is entirely similar to |
| 159 | @option{--decide-string}, and it can be used similarly |
| 160 | to produce variation trees. These should be typically |
| 161 | much smaller than the variation trees produced by |
| 162 | @option{--decide-string}. |
| 163 | |
| 164 | @node GTP and GDB techniques |
| 165 | @section GTP and GDB techniques |
| 166 | @cindex GDB |
| 167 | @cindex GTP |
| 168 | |
| 169 | You can use the Go Text Protocol (@pxref{GTP}) to determine |
| 170 | the statuses of dragons and other information needed for |
| 171 | debugging. The GTP command @command{dragon_data P12} will list |
| 172 | the dragon data of the dragon at @code{P12} and |
| 173 | @command{worm_data} will list the worm data; other GTP |
| 174 | commands may be useful as well. |
| 175 | |
| 176 | You can also conveniently get such information from GDB. |
| 177 | A suggested @file{.gdbinit} file may be found in |
| 178 | @xref{Debugging}. Assuming this file is loaded, you can |
| 179 | list the dragon data with the command: |
| 180 | |
| 181 | @example |
| 182 | (gdb) dragon P12 |
| 183 | @end example |
| 184 | |
| 185 | Similarly you can get the worm data with @command{worm P12}. |
| 186 | |
| 187 | @node view.pike |
| 188 | @section Debugging on a Graphical Board |
| 189 | @cindex debugging on a graphical board |
| 190 | |
| 191 | The quickest way to analyze most positions is to use the tool |
| 192 | @file{view.pike} in the @file{regression} directory. It can be started |
| 193 | with a testcase specified, e.g. @command{pike view.pike strategy:40} or |
| 194 | at a move in an sgf file, e.g. @command{pike view.pike mistake.sgf:125}. |
| 195 | When started it shows the position on a grapical board on which it also |
| 196 | marks information like move values, dragon status, and so on. By |
| 197 | clicking on the board further information about the valuation of moves, |
| 198 | contents of various data structures, and other data can be made |
| 199 | available. |
| 200 | |
| 201 | Specific information on how to use @file{view.pike} for influence tuning |
| 202 | can be found in @xref{Influence Tuning}. |
| 203 | |
| 204 | @node Scoring |
| 205 | @section Scoring the game |
| 206 | @cindex scoring |
| 207 | |
| 208 | GNU Go can score the game. Normally GNU Go will report its opinion about |
| 209 | the score at the end of the game, but if you want this information about |
| 210 | a game stored in a file, use the @option{--score} option (@pxref{Invoking |
| 211 | GNU Go}). |
| 212 | |
| 213 | @node Colored Display |
| 214 | @section Colored Display |
| 215 | @cindex colored display |
| 216 | |
| 217 | Various colored displays of the board may be obtained in a color |
| 218 | @command{xterm} or @command{rxvt} window. Xterm will only work if xterm is |
| 219 | compiled with color support. If the colors are not displayed on your xterm, |
| 220 | try @command{rxvt}. You may also use the Linux console. The colored display |
| 221 | will work best if the background color is black; if this is not the case you |
| 222 | may want to edit your @file{.Xdefaults} file or add the options |
| 223 | @option{-bg black -fg white} to @command{xterm} or @command{rxvt}. |
| 224 | On Mac OS X put @command{setenv TERM xterm-color} in your @file{.tcshrc} |
| 225 | file to enable color in the terminal. |
| 226 | |
| 227 | @subsection Dragon Display |
| 228 | |
| 229 | You can get a colored ASCII display of the board in which each dragon |
| 230 | is assigned a different letter; and the different @code{matcher_status} values |
| 231 | (@code{ALIVE}, @code{DEAD}, @code{UNKNOWN}, @code{CRITICAL}) have different |
| 232 | colors. This is very handy for debugging. Actually two diagrams are generated. |
| 233 | The reason for this is concerns the way the matcher status is computed. |
| 234 | The dragon_status (@pxref{Dragons}) is computed first, then for some, but not |
| 235 | all dragons, a more accurate owl status is computed. The matcher status is |
| 236 | the owl status if available; otherwise it is the dragon_status. Both the |
| 237 | dragon_status and the owl_status are displayed. The color scheme is as |
| 238 | follows: |
| 239 | |
| 240 | @example |
| 241 | green = alive |
| 242 | cyan = dead |
| 243 | red = critical |
| 244 | yellow = unknown |
| 245 | magenta = unchecked |
| 246 | @end example |
| 247 | |
| 248 | To get the colored display, save a game in sgf format using CGoban, or using |
| 249 | the @option{-o} option with GNU Go itself. |
| 250 | |
| 251 | Open an @command{xterm} or @command{rxvt} window. |
| 252 | |
| 253 | Execute @command{gnugo -l [filename] -L [movenum] -T} to get the colored |
| 254 | display. |
| 255 | |
| 256 | Other useful colored displays may be obtained by using instead: |
| 257 | |
| 258 | @subsection Eye Space Display |
| 259 | @cindex eye space display |
| 260 | |
| 261 | Instead of @option{-T}, try this with @option{-E}. This gives a colored |
| 262 | display of the eyespaces, with marginal eye spaces marked @samp{!} |
| 263 | (@pxref{Eyes}). |
| 264 | |
| 265 | |