Updated README: Equal sign not required with `--mode` flag.

[sgk-go] / doc / analyze.texi

In this chapter we will discuss methods of finding
out how GNU Go understands a given position. These
methods will be of interest to anyone working on the
program, or simply curious about its workings.

In practice, most tuning of GNU Go is done in conjunction
with maintaining the @file{regression/} directory
(@pxref{Regression}).

We assume that you have a game GNU Go played saved
as an sgf file, and you want to know why it made a
certain move.

@menu
* Traces::			Analyzing traces in GNU Go 3.6
* Output File::			The Output File
* Decide string::		Checking the reading code
* Decide dragon::		Checking the owl code
* GTP and GDB techniques::      GTP and GDB techniques
* view.pike::                   Debugging on a Graphic Board
* Scoring::                     Finding out the winner of the game
* Colored Display::             Colored Display
@end menu

@node Traces
@section Interpreting Traces
@cindex traces
@cindex tuning GNU Go

A quick way to find out roughly the reason for a move is to run

@example
gnugo -l @var{filename} -t -L @var{move number}
@end example

(You may also want to add @option{--quiet} to suppress the copyright
message.) In GNU Go 3.6, the moves together with their reasons are
listed, followed by a numerical analysis of the values given to each
move.

If you are tuning (@pxref{Tuning}) you may want to add the @option{-a}
option. This causes GNU Go to report all patterns matched, even ones
that cannot affect the outcome of the move. The reasons for doing
this is that you may want to modify a pattern already matched 
instead of introducing a new one.

If you use the @option{-w} option, GNU Go will report the statuses of
worms and dragons around the board. This type of information is
available by different methods, however (@pxref{view.pike},
@pxref{Colored Display}).

@node Output File
@section The Output File
@cindex output file

If GNU Go is invoked with the option @option{-o filename} it will
produce an output file. This option can be added at the command line
in the Go Modem Protocol Setup Window of CGoban. The output file will
show the locations of the moves considered and their weights. It is
worth noting that by enlarging the CGoban window to its fullest size
it can display 3 digit numbers. Dragons with status @code{DEAD} are
labelled with an @samp{X}, and dragons with status @code{CRITICAL} are
labelled with a @samp{!}.

If you have a game file which is not commented this way, or
which was produced by a non-current version of GNU Go you may
ask GNU Go to produce a commented version by running:

@example
gnugo --quiet -l <old file> --replay <color> -o <new file>
@end example

@noindent
Here <color> can be 'black,' 'white' or 'both'. The replay
option will also help you to find out if your current version
of GNU Go would play differently than the program that created
the file.

@node Decide string
@section Checking the reading code
@cindex decide-string

The @option{--decide-string} option is used to check the tactical reading code
(@pxref{Tactical Reading}). This option takes an argument, which is a location
on the board in the usual algebraic notation (e.g. 
@option{--decide-string C17}). This will tell you whether the reading code (in
@file{engine/reading.c}) believes the string can be captured, and if so,
whether it believes it can be defended, which moves it finds to attack or
defend the move, how many nodes it searched in coming to these
conclusions. Note that when GNU Go runs normally (not with
@option{--decide-string}) the points of attack and defense are 
computed when @code{make_worms()} runs and cached in
@code{worm.attack} and @code{worm.defend}. 

If used with an output file (@option{-o @var{filename}}) 
@option{--decide-string} will produce a variation tree showing
all the variations which are considered. This is a useful way
of debugging the reading code, and also of educating yourself
with the way it works. The variation tree can be displayed
graphically using CGoban. 

At each node, the comment contains some information. For example you
may find a comment:

@example

attack4-B at D12 (variation 6, hash 51180fdf)
break_chain D12: 0
defend3 D12: 1 G12 (trivial extension)

@end example

This is to be interpreted as follows. The node in question
was generated by the function @code{attack3()} in @file{engine/reading.c},
which was called on the string at @code{D12}. The data in 
parentheses tell you the values of @code{count_variations} and
@code{hashdata.hashval}. 

The second value (``hash'') you probably will not need to know
unless you are debugging the hash code, and we will not discuss it.
But the first value (``variation'') is useful when using the debugger
@command{gdb}. You can first make an output file using
the @option{-o} option, then walk through the reading with
@command{gdb}, and to coordinate the SGF file with the debugger,
display the value of @code{count_variations}. Specifically,
from the debugger you can find out where you are as follows:

@example
(gdb) set dump_stack()
B:D13 W:E12 B:E13 W:F12 B:F11  (variation 6)
@end example

If you place yourself right after the call to @code{trymove()}
which generated the move in question, then the variation number
in the SGF file should match the variation number displayed by
@code{dump_stack()}, and the move in question will be the
last move played (F11 in this example).

This displays the sequence of moves leading up to the variation
in question, and it also prints @code{count_variations-1}.

The second two lines tell you that from this node, the function
@code{break_chain()} was called at D12 and returned 0 meaning
that no way was found of rescuing the string by attacking
an element of the surrounding chain, and the function
@code{defend3()} was called also at D12 and returned 1,
meaning that the string can be defended, and that
G12 is the move that defends it. If you have trouble
finding the function calls which generate these comments,
try setting @code{sgf_dumptree=1} and setting a breakpoint in
@code{sgf_trace}.

@node Decide dragon
@section Checking the Owl Code
@cindex decide-dragon

You can similarly debug the Owl code using the option
@option{--decide-dragon}. Usage is entirely similar to
@option{--decide-string}, and it can be used similarly
to produce variation trees. These should be typically
much smaller than the variation trees produced by
@option{--decide-string}.

@node GTP and GDB techniques
@section GTP and GDB techniques
@cindex GDB
@cindex GTP

You can use the Go Text Protocol (@pxref{GTP}) to determine
the statuses of dragons and other information needed for
debugging. The GTP command @command{dragon_data P12} will list
the dragon data of the dragon at @code{P12} and
@command{worm_data} will list the worm data; other GTP
commands may be useful as well.

You can also conveniently get such information from GDB.
A suggested @file{.gdbinit} file may be found in
@xref{Debugging}. Assuming this file is loaded, you can
list the dragon data with the command:

@example
(gdb) dragon P12
@end example

Similarly you can get the worm data with @command{worm P12}.

@node view.pike
@section Debugging on a Graphical Board
@cindex debugging on a graphical board

The quickest way to analyze most positions is to use the tool
@file{view.pike} in the @file{regression} directory. It can be started
with a testcase specified, e.g. @command{pike view.pike strategy:40} or
at a move in an sgf file, e.g. @command{pike view.pike mistake.sgf:125}.
When started it shows the position on a grapical board on which it also
marks information like move values, dragon status, and so on. By
clicking on the board further information about the valuation of moves,
contents of various data structures, and other data can be made
available.

Specific information on how to use @file{view.pike} for influence tuning
can be found in @xref{Influence Tuning}.

@node Scoring
@section Scoring the game
@cindex scoring

GNU Go can score the game. Normally GNU Go will report its opinion about
the score at the end of the game, but if you want this information about
a game stored in a file, use the @option{--score} option (@pxref{Invoking
GNU Go}).

@node  Colored Display
@section Colored Display
@cindex colored display

Various colored displays of the board may be obtained in a color
@command{xterm} or @command{rxvt} window. Xterm will only work if xterm is
compiled with color support. If the colors are not displayed on your xterm,
try @command{rxvt}.  You may also use the Linux console. The colored display
will work best if the background color is black; if this is not the case you
may want to edit your @file{.Xdefaults} file or add the options
@option{-bg black -fg white} to @command{xterm} or @command{rxvt}.
On Mac OS X put @command{setenv TERM xterm-color} in your @file{.tcshrc}
file to enable color in the terminal.

@subsection Dragon Display

You can get a colored ASCII display of the board in which each dragon
is assigned a different letter; and the different @code{matcher_status} values
(@code{ALIVE}, @code{DEAD}, @code{UNKNOWN}, @code{CRITICAL}) have different
colors. This is very handy for debugging. Actually two diagrams are generated.
The reason for this is concerns the way the matcher status is computed.
The dragon_status (@pxref{Dragons}) is computed first, then for some, but not
all dragons, a more accurate owl status is computed. The matcher status is
the owl status if available; otherwise it is the dragon_status. Both the
dragon_status and the owl_status are displayed. The color scheme is as
follows:

@example
green = alive
cyan = dead
red = critical
yellow = unknown
magenta = unchecked
@end example

To get the colored display, save a game in sgf format using CGoban, or using
the @option{-o} option with GNU Go itself.

Open an @command{xterm} or @command{rxvt} window. 

Execute @command{gnugo -l [filename] -L [movenum] -T} to get the colored 
display.

Other useful colored displays may be obtained by using instead:

@subsection Eye Space Display
@cindex eye space display

Instead of @option{-T}, try this with @option{-E}. This gives a colored
display of the eyespaces, with marginal eye spaces marked @samp{!}
(@pxref{Eyes}).