Ticket #180: draqo-doc.diff

doc/board.texi

@@ -71 +71 @@
 @group
 
 int           board_size;
-Intersection  board[MAXSIZE];
+Intersection  board[BOARDSIZE];
 int           board_ko_pos;
 
 float         komi;
 int           white_captured;
 int           black_captured;
 
-Hash_data     hashdata;
+Hash_data     board_hash;
 @end group
 @end example
 
-The description of the @code{Position} struct is applicable to these
+The description of the @code{board_state} struct is applicable to these
 variables also, so we won't duplicate it here.  All these variables are
 globals for performance reasons.  Behind these variables, there are a
 number of other private data structures.  These implement incremental
 handling of strings, liberties and other properties 
-(@pxref{Incremental Board}). The variable @code{hashdata} contains information
+(@pxref{Incremental Board}). The variable @code{board_hash} contains information
 about the hash value for the current position (@pxref{Hashing}).
 
 These variables should never be manipulated directly, since they are
@@ -181 +181 @@
 #define NS           (MAX_BOARD + 1)
 #define WE           1
 #define SOUTH(pos)   ((pos) + NS)
-#define WEST(pos)    ((pos) - 1)
+#define WEST(pos)    ((pos) - WE)
 #define NORTH(pos)   ((pos) - NS)
-#define EAST(pos)    ((pos) + 1)
+#define EAST(pos)    ((pos) + WE)
 @end example
 
 There are also shorthand macros @code{SW}, @code{NW}, @code{NE},
@@ -209 +209 @@
 often one computation is sufficient for 1D-coordinate where we would need
 two with two 2D-coordinates: If we, for example, want to have the
 coordinate of the upper right of @code{pos}, we can do this with
-@code{NORTH(EAST(pos))} instead of @code{(i+1, j-1)}.
+@code{NE(pos)} instead of @code{(i+1, j-1)}.
 
 @strong{Important}: The 2D coordinate @code{(-1,-1)}, which is used for
 pass and sometimes to indicate no point, maps to the 1D coordinate
@@ -240 +240 @@
 a point on the board. 
 
 Often one wants to traverse the board, carrying out some function
-at every vertex. Here are two possible ways of doing this:
-
-@example
-  int m, n;
-  for (m = 0; m < board_size; m++)
-    for (n = 0; n < board_size; n++) @{
-      do_something(POS(m, n));
-    @}
-@end example
-
-Or:
+at every vertex. Here are the best way of doing this (other
+implemantations were tested and are slower on 19x19 board):
 
 @example
   int pos;
@@ -273 +264 @@
 @item Number of stones in the string.
 @item Origin of the string, i.e. a canonical reference point, defined
 to be the stone with smallest 1D board coordinate.
-@item A list of the stones in the string.
+@item A list of the stones in the string (linked in a cycle).
 @item Number of liberties.
 @item A list of the liberties. If there are too many liberties the list is
 truncated.
@@ -281 +272 @@
 @item A list of the neighbor strings.
 @end itemize
 
-The basic data structure is
+The basic data structures are
 
 @example
 struct string_data @{
@@ -290 +281 @@
   int origin;                      /* Coordinates of "origin", i.e. */
                                    /* "upper left" stone. */
   int liberties;                   /* Number of liberties. */
-  int libs[MAX_LIBERTIES];         /* Coordinates of liberties. */
   int neighbors;                   /* Number of neighbor strings */
-  int neighborlist[MAXCHAIN];      /* List of neighbor string numbers. */
   int mark;                        /* General purpose mark. */
 @};
 
-struct string_data string[MAX_STRINGS];
+struct string_liberties_data @{
+  int list[MAX_LIBERTIES];         /* Coordinates of liberties. */
+@};
+
+struct string_neighbors_data @{
+  int list[MAXCHAIN];              /* List of neighbor string numbers. */
+@};
+
+static struct string_data string[MAX_STRINGS];
+static struct string_liberties_data string_libs[MAX_STRINGS];
+static struct string_neighbors_data string_neighbors[MAX_STRINGS];
 @end example
 
-It should be clear that almost all information is stored in the
-@code{string} array. To get a mapping from the board coordinates to the
-@code{string} array we have
+It should be clear that almost all information is stored in these
+arrays. They are splitted because of caching purposes - if one doesn't
+need libs or neighbors, accessing string_data is faster, because @code{list}
+arrays are quite big.
+
+To get a mapping from the board coordinates to these arrays we have
 
 @example
 static int string_number[BOARDMAX];
 @end example
 
 @noindent
-which contains indices into the @code{string} array. This information is only
+which contains indices into these arrays. This information is only
 valid at nonempty vertices, however, so it is necessary to first
 verify that @code{board[pos] != EMPTY}.
 
-The @code{string_data} structure does not include an array of the stone
-coordinates. This information is stored in a separate array:
+A string stones coordinates are stored in a separate array:
 
 @example
 static int next_stone[BOARDMAX];
@@ -335 +336 @@
 static int liberty_mark;
 static int string_mark;
 static int next_string;
-static int strings_initialized = 0;
 @end example
 
 The @code{ml} array and @code{liberty_mark} are used to "mark" liberties on
@@ -349 +349 @@
 individual strings.
 
 @code{next_string} gives the number of the next available entry in the
-@code{string} array. Then @code{strings_initialized} is set to one when
-all data structures are known to be up to date. Given an arbitrary board
-position in the @samp{board} array, this is done by calling
-@code{incremental_board_init()}. It is not necessary to call this
-function explicitly since any other function that needs the information
-does this if it has not been done.
+@code{string} array.
+
+To initialize all the structures of the incremental board one need to
+call @code{new_position} function, which builds all information based
+on the actual state of the board (in @code{board} variable).
 
 The interesting part of the code is the incremental update of the data
 structures when a stone is played and subsequently removed. To
 understand the strategies involved in adding a stone it is necessary
 to first know how undoing a move works. The idea is that as soon as
-some piece of information is about to be changed, the old value is
-pushed onto a stack which stores the value and its address. The stack
-is built from the following structures:
+some piece of information is about to be changed, the old value (or
+an intersection state) is pushed onto a stack which stores the value
+and its address. The stack is built from the following structures (we
+have two stacks really, because Intersection can have different type
+than int):
 
 @example
 struct change_stack_entry @{
@@ -370 +371 @@
   int value;
 @};
 
-struct change_stack_entry change_stack[STACK_SIZE];
-int change_stack_index;
+struct vertex_stack_entry @{
+  Intersection *address;
+  int value;
+@};
+
+static struct change_stack_entry change_stack[STACK_SIZE];
+static struct change_stack_entry *change_stack_pointer;
+
+static struct vertex_stack_entry vertex_stack[STACK_SIZE];
+static struct vertex_stack_entry *vertex_stack_pointer;
 @end example
 
 @noindent
 and manipulated with the macros
 
 @example
+CLEAR_STACKS()
 BEGIN_CHANGE_RECORD()
 PUSH_VALUE(v)
+PUSH_VERTEX(v)
 POP_MOVE()
 @end example
 
 Calling @code{BEGIN_CHANGE_RECORD()} stores a null pointer in the address
 field to indicate the start of changes for a new move. As mentioned
-earlier @code{PUSH_VALUE()} stores a value and its corresponding address.
+earlier @code{PUSH_VALUE()} and @code{PUSH_VERTEX()} stores a value and its
+corresponding address.
 Assuming that all changed information has been duly pushed onto the
 stack, undoing the move is only a matter of calling @code{POP_MOVE()},
 which simply assigns the values to the addresses in the reverse order
-until the null pointer is reached. This description is slightly
-simplified because this stack can only store 'int' values and we need
-to also store changes to the board. Thus we have two parallel stacks
-where one stores @code{int} values and the other one stores
-@code{Intersection} values.
+until the null pointer is reached.
 
 When a new stone is played on the board, first captured opponent
 strings, if any, are removed. In this step we have to push the board
@@ -438 +446 @@
 The often used construction
 
 @example
-    pos = FIRST_STONE(s);
+    first_stone = FIRST_STONE(s);
+    pos = first_stone;
     do @{
         ...
         pos = NEXT_STONE(pos);
-    @} while (!BACK_TO_FIRST_STONE(s, pos));
+    @} while (pos != first_stone);
 @end example
 
 @noindent
 traverses the stones of the string with number @samp{s} exactly once,
 with @code{pos} holding the coordinates. In general @code{pos} is
 used as board coordinate and @samp{s} as an index into the
-@code{string} array or sometimes a pointer to an entry in the
-@code{string} array.
+@code{string}, @code{string_libs} or @code{string_neighbors} array.
 
 @node Some Board Functions
 @section Some Board Functions
@@ -489 +497 @@
 the komaster scheme (@pxref{Ko}).
 
 @itemize @bullet
-@item @code{int trymove(int pos, int color, const char *message)}
+@item @code{int trymove(int pos, int color, const char *message, int str)}
 @findex trymove
 @quotation
 Returns true if @code{(pos)} is a legal move for @code{color}. In that
@@ -498 +506 @@
 with @option{--decide-string} or with @option{-o}), the string
 @code{*message} will be inserted in the SGF file as a comment. The
 comment will also refer to the string at @code{str} if this is not
-@code{0}. The value of @code{str} can be NO_MOVE if it is not needed but
-otherwise the location of @code{str} is included in the comment.
+@code{NO_MOVE}. The value of @code{str} can be @code{NO_MOVE} if it is
+not needed but otherwise the location of @code{str} is included in the
+comment. @strong{NOTE}: including str in comment isn't implemented for
+now
 @end quotation
 @item @code{int tryko(int pos, int color, const char *message)}
 @findex tryko

doc/dfa.texi

@@ -1 +1 @@
 In this chapter, we describe the principles of the GNU Go DFA
 pattern matcher.  The aim of this system is to permit a fast
-pattern matching when it becomes time critical like in owl
-module (@ref{The Owl Code}). Since GNU Go 3.2, this is enabled
+pattern matching. Since GNU Go 3.2, this is enabled
 by default. You can still get back the traditional pattern matcher
 by running @command{configure --disable-dfa} and then recompiling
 GNU Go. 

doc/dragon.texi

@@ -17 +17 @@
 Later routines called by @code{genmove()} will then have access to this
 information. This document attempts to explain the philosophy and
 algorithms of this preliminary analysis, which is carried out by the
-two routines @code{make_worm()} and @code{make_dragon()} in 
-@file{dragon.c}.
+two routines @code{make_worms()} (in @file{worm.c}) and
+@code{make_dragons()} (in @file{dragon.c}).
 
 @cindex dragon
 @cindex worm
@@ -83 +83 @@
   int unconditional_status;
   int attack_points[MAX_TACTICAL_POINTS];
   int attack_codes[MAX_TACTICAL_POINTS];
+  int discarded_attacks[MAX_TACTICAL_POINTS];
   int defense_points[MAX_TACTICAL_POINTS];
   int defend_codes[MAX_TACTICAL_POINTS];
+  int discarded_defenses[MAX_TACTICAL_POINTS];
   int attack_threat_points[MAX_TACTICAL_POINTS];
-  int attack_threat_codes[MAX_TACTICAL_POINTS]; 
+  int attack_threat_codes[MAX_TACTICAL_POINTS];
+  int discarded_att_threats[MAX_TACTICAL_POINTS];
   int defense_threat_points[MAX_TACTICAL_POINTS];
   int defense_threat_codes[MAX_TACTICAL_POINTS];
+  int discarded_def_threats[MAX_TACTICAL_POINTS];
 @};
 @end example
 
@@ -109 +113 @@
 other worm. Intersections that are shared are counted with equal
 fractional values for each worm. This measures the direct territorial
 value of capturing a worm. @dfn{effective_size} is a floating point number.
-Only intersections at a distance of 4 or less are counted.
+Only intersections at a distance (empty vertices between a worm and an
+intersection) of 5 or less are counted.
 @end quotation
 @item @code{origin}
 @quotation
@@ -220 +225 @@
 @end quotation
 @item @code{cutstone2} 
 @quotation
-Cutting points are identified by the patterns in the connections
-database. Proper cuts are handled by the fact that attacking and
+Number of potential cuts involving the worm. Cutting points are
+identified by the patterns in the connections database. Proper
+cuts are handled by the fact that attacking and
 defending moves also count as moves cutting or connecting the
 surrounding dragons.  The @code{cutstone2} field is set during 
 @code{find_cuts()}, called from @code{make_domains()}.
@@ -248 +254 @@
 opposite color can be killed. More precisely an
 @dfn{inessential string} is a string S of genus zero,
 not adjacent to any opponent string which can be easily
-captured, and which has no edge liberties or second
+captured, which is not cutstone, and which has up to
+2 edge liberties and no second
 order liberties, and which satisfies the following
 further property: If the string is removed from the
 board, then the remaining cavity only borders worms of the
@@ -266 +273 @@
 even if the opponent is allowed an arbitrary number of consecutive
 moves.
 @end quotation
-@item unconditional_status
+@item @code{unconditional_status}
 @quotation
 Unconditional status is also set by the function
 @code{unconditional_life}. This is set @code{ALIVE} for stones which are
@@ -285 +292 @@
 transformed into an invincible group by some number of consecutive
 moves. Well, this is not entirely true because there is a rare class of
 seki groups not satisfying this condition. Exactly which these are is
-left as an exercise for the reader. Currently @code{unconditional_life},
-which strictly follows the definitions above, calls such seki groups
-unconditionally dead, which of course is a misfeature. It is possible to
-avoid this problem by making the algorithm slightly more complex, but
-this is left for a later revision.
+shown in a comment in @file{unconditional.c}.
 @end quotation
-@item @code{int attack_points[MAX_TACTICAL_POINTS]}
-@item @code{attack_codes[MAX_TACTICAL_POINTS]}
+@item @code{int attack_points[MAX_TACTICAL_POINTS];}
+@item @code{int attack_codes[MAX_TACTICAL_POINTS];}
 @item @code{int defense_points[MAX_TACTICAL_POINTS];}
 @item @code{int defend_codes[MAX_TACTICAL_POINTS];}
 @quotation
@@ -310 +313 @@
 @quotation
 These are points that threaten to attack or defend a worm.
 @end quotation
+@item @code{int discarded_attacks[MAX_TACTICAL_POINTS];}
+@item @code{int discarded_defenses[MAX_TACTICAL_POINTS];}
+@item @code{int discarded_att_threats[MAX_TACTICAL_POINTS];}
+@item @code{int discarded_def_threats[MAX_TACTICAL_POINTS];}
+@quotation
+These are checked points that haven't led to any positive result.
+Used to not check the same point more than once.
+@end quotation
 @end itemize
 
 The function @code{makeworms()} will generate data for all worms.
@@ -343 +354 @@
 XXX...       
 
 @end example
-@findex dragon_eye
-
-The code for this type of amalgamation is in the routine
-@code{dragon_eye()}, discussed further in EYES.
 
 Next, we amalgamate strings which seem uncuttable. We amalgamate dragons
 which either share two or more common liberties, or share one liberty
@@ -367 +374 @@
 @section Connection
 @cindex connections
 
-The fields @code{black_eye.cut} and @code{white_eye.cut} are set where the
+The fields in @code{cutting_points} are set where the
 opponent can cut, and this is done by the B (break) class patterns in
-@file{conn.db}.  There are two important uses for this field, which can be
+@file{conn.db}.  There are two important uses for this table, which can be
 accessed by the autohelper functions @code{xcut()} and @code{ocut()}. The
 first use is to stop amalgamation in positions like
 
@@ -534 +541 @@
   int safety;
   float weakness;
   float weakness_pre_owl;
+  float strategic_size;
   int escape_route;
   struct eyevalue genus;
   int heye;
@@ -541 +549 @@
   int surround_status;
   int surround_size;
   int semeais;
-  int semeai_margin_of_safety;
+  int semeai_defense_code;
   int semeai_defense_point;
-  int semeai_defense_certain;  
+  int semeai_defense_certain;
+  int semeai_defense_target;
+  int semeai_attack_code;
   int semeai_attack_point;
   int semeai_attack_certain;
+  int semeai_attack_target;
   int owl_threat_status;
   int owl_status;
   int owl_attack_point;
   int owl_attack_code;
   int owl_attack_certain;
+  int owl_attack_node_count;
   int owl_second_attack_point;
   int owl_defense_point;
   int owl_defense_code;
@@ -607 +619 @@
 @quotation
 The dragon number, used as a key into the @code{dragon2} array.
 @end quotation
-@item origin
+@item @code{origin}
 @cindex dragon origin
 @quotation
 The origin of the dragon is a unique particular vertex
@@ -616 +628 @@
 copied to the dragon origins. Amalgamation of two dragons
 amounts to changing the origin of one.
 @end quotation
-@item size
+@item @code{size}
 @cindex dragon size
 @quotation
 The number of stones in the dragon.
 @end quotation
-@item effective size
+@item @code{effective size}
 @cindex effective size
 @quotation
 The sum of the effective sizes of the constituent worms.
@@ -630 +642 @@
 cardinality of the dragon plus the number of empty vertices which are
 nearer this dragon than any other.
 @end quotation
-@item crude_status
+@item @code{crude_status}
 @quotation
 (ALIVE, DEAD, UNKNOWN, CRITICAL). An early measure of the life
 potential of the dragon. It is computed before the owl code is
 run and is superceded by the status as soon as that becomes
 available.
 @end quotation
-@item status
+@item @code{status}
 @cindex dragon status
 @quotation
 The dragon status is the best measure of the dragon's health.
@@ -649 +661 @@
 Here are definitions of the fields in the @code{dragon2} array.
 
 @itemize @bullet
-@item origin
+@item @code{origin}
 @quotation
 The origin field is duplicated here.
 @end quotation
-@item adjacent
 @item @code{adjacent[MAX_NEIGHBOR_DRAGONS]}
-@cindex neighbor dragons
-@cindex adjacent dragons
-@findex find_neighbor_dragons
-@quotation
-Dragons of either color near the given one are called @dfn{neighbors}.
-They are computed by the function @code{find_neighbor_dragons()}.
-The @code{dragon2.adjacent} array gives the dragon numbers of
-these dragons.
-@end quotation
 @item @code{neighbors}
 @cindex neighbor dragons
 @cindex adjacent dragons
@@ -671 +673 @@
 @quotation
 Dragons of either color near the given one are called @dfn{neighbors}.
 They are computed by the function @code{find_neighbor_dragons()}.
-The @code{dragon2.adjacent} array gives the dragon numbers of
-these dragons.
+The @code{adjacent} array gives the dragon numbers of
+these dragons and @code{neighbors} gives the number of them.
 @end quotation
-@item neighbors
-@quotation
-The number of neighbor dragons.
-@end quotation
-@item hostile_neighbors
+@item @code{hostile_neighbors}
 @quotation
 The number of neighbor dragons of the opposite color.
 @end quotation
-@item moyo_size
-@item float moyo_territorial_value
+@item @code{moyo_size}
+@item @code{moyo_territorial_value}
 @findex compute_surrounding_moyo_sizes
 @quotation
 The function @code{compute_surrounding_moyo_sizes()} assigns
@@ -691 +689 @@
 each dragon (@pxref{Territory and Moyo}). This is the 
 moyo size. They are recorded in these fields.
 @end quotation
-@item safety
+@item @code{safety}
 @cindex dragon safety
 @quotation
 The dragon safety can take on one of the values
@@ -707 +705 @@
 @item INESSENTIAL - the dragon is unimportant (e.g. nakade stones) and dead
 @end itemize
 @end quotation
-@item weakness
-@item weakness_pre_owl
+@item @code{weakness}
+@item @code{weakness_pre_owl}
 @cindex dragon weakness
 @cindex weakness
 @quotation
@@ -717 +715 @@
 dragons in greater need of safety. The field @code{weakness_pre_owl}
 is a preliminary computation before the owl code is run.
 @end quotation
-@item escape_route
+@item @code{strategic_size}
+@cindex strategic_size
+@quotation
+An effective size including weakness of neighbors.
+@end quotation
+@item @code{escape_route}
 @cindex dragon escape_route
 @cindex escape_route
 @findex compute_escape
@@ -726 +729 @@
 in case it cannot make two eyes locally. Documentation
 may be found in @ref{Escape}.
 @end quotation
-@item struct eyevalue genus
+@item @code{genus}
 @cindex dragon genus
 @cindex genus
 @quotation
@@ -744 +747 @@
 
 @end example
 @end quotation
-@item heye
+@item @code{heye}
 @quotation
 Location of a half eye attached to the dragon.
 @end quotation
-@item lunch
+@item @code{lunch}
 @cindex dragon lunch
 @cindex lunch
 @quotation
@@ -756 +759 @@
 can be captured. In contrast with worm lunches, a dragon
 lunch must be able to defend itself.
 @end quotation
-@item surround_status
-@item surround_size
+@item @code{surround_status}
+@item @code{surround_size}
 @cindex surround_status
 @cindex surround_size
 @cindex surround
@@ -766 +769 @@
 it is @dfn{surrounded}. See @ref{Surrounded Dragons} and
 the comments in @file{surround.c} for more information about the
 algorithm.  Used in computing the escape_route, and also callable
-from patterns (currently used by CB258).  
+from patterns.  
 @end quotation
-@item semeais
-@item semeai_defense_point
-@item semeai_defense_certain
-@item semeai_attack_point
-@item semeai_attack_certain
-@cindex semeai
+@item @code{semeais}
+@item @code{semeai_defense_code}
+@item @code{semeai_defense_point}
+@item @code{semeai_defense_certain}
+@item @code{semeai_defense_target}
+@item @code{semeai_attack_code}
+@item @code{semeai_attack_point}
+@item @code{semeai_attack_certain}
+@item @code{semeai_attack_target}
+@cindex semeais
+@cindex semeai_defense_code
 @cindex semeai_defense_point
 @cindex semeai_defense_certain
+@cindex semeai_defense_target
+@cindex semeai_attack_code
 @cindex semeai_attack_point
 @cindex semeai_attack_certain
+@cindex semeai_attack_target
 @quotation
 If two dragons of opposite color both have the status CRITICAL
 or DEAD they are in a @dfn{semeai} (capturing race), and their
@@ -785 +796 @@
 @code{owl_analyze_semeai()} in @file{owl.c}, which attempts to
 determine which is alive, which dead, or if the result is
 seki, and whether it is important who moves first. The
-function @file{new_semeai()} in @file{semeai.c} attempts
+function @code{semeai()} in @file{semeai.c} attempts
 to revise the statuses and to generate move reasons based
 on these results. The field @code{dragon2.semeais} is nonzero
 if the dragon is an element of a semeai, and equals the
 number of semeais (seldom more than one). The semeai defense
 and attack points are locations the defender or attacker
-must move to win the semeai. The field @code{semeai_margin_of_safety}
-is intended to indicate whether the semeai is close or not
-but currently this field is not maintained. The fields
+must move to win the semeai and the result code of these moves is
+also stored. In @code{semeai_defense_target} and
+@code{semeai_attack_target} an origin of an opponent dragon in
+semeai, on which the move has impact, is stored. The fields
 @code{semeai_defense_certain} and @code{semeai_attack_certain}
 indicate that the semeai code was able to finish analysis
 without running out of nodes.
 @end quotation
-@item owl_status
+@item @code{owl_threat_status}
+@quotation
+Informs, whether the dragon has any defense or attack threats
+(@code{CAN_THREATEN_ATTACK} or @code{CAN_THREATEN_DEFENSE}).
+@end quotation
+@item @code{owl_status}
 @quotation
 This is a classification similar to @code{dragon.crude_status}, but
 based on the life and death reading in @file{owl.c}.
@@ -810 +827 @@
 @code{owl_defend()} is run, and if it can be defended it
 is classified as @code{CRITICAL}, and if not, as @code{DEAD}.
 @end quotation
-@item owl_attack_point
+@item @code{owl_attack_point}
 @cindex owl_attack_point
 @quotation
 If the dragon can be attacked this is the point to attack the dragon.
 @end quotation
-@item owl_attack_code
+@item @code{owl_attack_code}
 @cindex owl_attack_code
 @quotation
-The owl attack code, It can be WIN, KO_A, KO_B or 0 (@pxref{Return Codes}).
+The owl attack code, It can be WIN, KO_A, GAIN, LOSS,
+KO_B or 0 (@pxref{Return Codes}).
 @end quotation
-@item owl_attack_certain
+@item @code{owl_attack_certain}
 @cindex owl_attack_certain
 @quotation
 The owl reading is able to finish analyzing the attack
 without running out of nodes.
 @end quotation
-@item owl_second_attack_point
+@item @code{owl_attack_node_count}
+@cindex owl_attack_node_count
+@quotation
+Number of nodes used during analyze of attack move.
+@end quotation
+@item @code{owl_second_attack_point}
 @cindex owl_second_attack_point
 @quotation
 A second attack point.
 @end quotation
-@item owl_defense_point
+@item @code{owl_defense_point}
 @cindex owl_defense_point
 @quotation
 If the dragon can be defended, this is the place to play.
 @end quotation
-@item owl_defense_code
+@item @code{owl_defense_code}
 @cindex owl_defense_code
 @quotation
-The owl defense code, It can be WIN, KO_A, KO_B or 0 (@pxref{Return Codes}).
+The owl defense code, It can be WIN, KO_A, GAIN, LOSS,
+KO_B or 0 (@pxref{Return Codes}).
 @end quotation
-@item owl_defense_certain
+@item @code{owl_defense_certain}
 @cindex owl_defense_certain
 @quotation
 The owl code is able to finish analyzing the defense without
 running out of nodes.
 @end quotation
-@item owl_second_defense_point
+@item @code{owl_second_defense_point}
 @cindex owl_second_defense_point
 @quotation
 A second owl defense point.
 @end quotation
+@item @code{owl_attack_kworm}
+@cindex owl_attack_kworm
+@quotation
+Position of a worm, which can be killed during attack on the dragon
+(@code{owl_attack_code} has to be @code{GAIN}).
+@end quotation
+@item @code{owl_defense_kworm}
+@cindex owl_defense_kworm
+@quotation
+Position of our worm (part of the dragon) abandoned during defense of
+the dragon (@code{owl_defend_code} has to be @code{LOSS}).
+@end quotation
 @end itemize
 
 @node Dragons in Color

doc/install.texi

@@ -130 +130 @@
 @node Default Level
 @subsection Default Level
 
-GNU Go can play at different levels. Up to level 10 is
-supported. At level 10 GNU Go is much more accurate but takes
-an average of about 1.6 times longer to play than at level 8.
+GNU Go can play at different levels. Level may be as high as you wish
+but it will make GNU Go play slower (up to level 12 is recommended). At
+level 10 GNU Go is much more accurate but takes an average of about 1.6
+times longer to play than at level 8.
 
 The level can be set at run time using the @option{--level} option.
 If you don't set this, the default level will be used. You
@@ -146 +147 @@
 @noindent
 sets the default level to 9. If you omit this parameter,
 the compiler sets the default level to 10. We recommend
-using level 10 unless you find it too slow. If you decide
+using level 12 unless you find it too slow. If you decide
 you want to change the default you may rerun configure
 and recompile the program.
 
@@ -235 +236 @@
 This is on by default.
 @end itemize
 
+There is one more option, which allows disabling of all unneeded
+things in code - like stats, asserts, etc. It should be used only
+to generate final release of the program and can be changed only
+as configure option.
+
+@itemize @bullet
+@item @code{final-release} Disable unneeded things.
+@end itemize
+
 @node Windows and MS-DOS, Macintosh, Configure Options, Installation
 @section Compiling GNU Go on Microsoft platforms
 

doc/move_generation.texi

@@ -214 +214 @@
 the simultaneous attack of one worm and the defense of another. As for
 attack and defense moves, it's important that all moves which win a
 semeai are found, so an informed choice can be made between them.
+Semeai move reasons are set by the semeai module.
+
+One might also wish to list moves which increase the lead in a semeai
+race (removes ko threats) for use as secondary move reasons. Analogously,
+if we are behind in the race. However this has not been implemented yet.
 
-Semeai move reasons should be set by the semeai module. However this
-has not been implemented yet. One might also wish to list moves
-which increase the lead in a semeai race (removes ko threats) for use
-as secondary move reasons. Analogously if we are behind in the race.
 
 @node  Making eyes
 @subsection Making or destroying eyes
@@ -229 +230 @@
 will be valued substantially higher if this is the case. As usual it's
 important to find all moves that change the eye count.
 
-(This is part of what eye_finder was doing. Currently it only finds
-one vital point for each unstable eye space.)
+The eye module (@file{optics.c}) is handling this. It uses eyes patterns
+database @file{patterns/eyes.db}.
 
 @node  Antisuji moves
 @subsection Antisuji moves
@@ -247 +248 @@
 territory move reason. That move reason is added by the @samp{e}
 patterns in @file{patterns/patterns.db}. Similarly the @samp{E} patterns
 attempt to generate or mitigate a moyo, which is a region of influence
-not yet secure territory, yet valuable. Such a pattern sets the ``expand
-moyo'' move reason.
+not yet secure territory, yet valuable. There are also other patterns for
+reducing territory, invasions and making bariers (to defend before
+invasions) - they are in @file{patterns/influence.db} and
+@file{patterns/barriers.db}. These patterns set the ``expand moyo'',
+``expand territory'' and ``invasion'' move reasons. They also have
+influence on a move territorial valuation.
 
 @node Owl attack and defense
 @subsection Attacking and Defending Dragons
@@ -310 +315 @@
 as explained for example in @emph{The Endgame} by Ogawa
 and Davies.
 
-Moves are valued with respect to four different criteria. These are
+Moves are valued with respect to four different main criteria. These
+are
 
 @itemize @bullet
 @item territorial value
@@ -362 +368 @@
 * Minimum Value::                 Minimum value
 * Secondary Value::               Other, more indirect, gains from a move
 * Threats and Followup Value::    Valuation of attack and defense threats
+* Additional ko value::    Additional threat value for a ko fight
 @end menu
 
 @node Territorial value
@@ -384 +391 @@
 
 @node Strategical value
 @subsection Strategical Value
+@findex estimate_strategical_value
 
 Strategical defense or attack reasons are assigned to any move
 which matches a pattern of type @samp{a} or @samp{d}. These are
@@ -394 +402 @@
 to check its status or safety. This is done later, during
 the valuation phase.
 
+The whole algorithm is placed in @code{estimate_strategical_value}.
+
 @node Shape factor
 @subsection Shape Factor
 
@@ -451 +461 @@
 which we cannot legally take, then such a move becomes attractive as a ko
 threat and the full followup value is taken into account.
 
+@node Additional ko value
+@subsection Additional ko value
+
+Some moves give us additional threats and some give them to an opponent.
+In such situations we should give some bonus or penalty for creating ko
+threats. As for now only positive contribution is counted.
+
 @node End Game
 @section End Game
 

doc/patterns.texi

@@ -85 +85 @@
 Elements are not generated for @samp{?} markers, but they are not
 completely ignored - see below.
         
-The line beginning @samp{:} describes various attributes of the pattern, such
-as its symmetry and its class. Optionally, a function called a
-``helper'' can be provided to assist the matcher in deciding whether
-to accept move. Most patterns do not require a helper, and this field
-is filled with NULL.
-
 @findex shapes_callback
 The matcher in @file{matchpat.c} searches the board for places where this
 layout appears on the board, and the callback function
@@ -100 +94 @@
 After the pattern, there is some supplementary information in the format:
 @example
 
-  :trfno, classification, [values], helper_function
+  :trfno, attributes, [values], helper_function
 
 @end example
 
@@ -110 +104 @@
 represents the axis of symmetry. (E.g. @samp{|} means symmetrical about a
 vertical axis.)
 
+@code{helper_function} is a function that can be provided to assist the matcher
+in deciding whether to accept move. Most patterns do not require a helper,
+and this field is filled with NULL.
+
 The above pattern could equally well be written on the left edge:
 
 @example
@@ -127 +125 @@
 way, or for that matter, on the top or right edges, or in any
 of the four corners. As a matter of convention all the edge patterns 
 in @file{patterns.db} are written on the bottom edge or in the lower left
-corners. In the @file{patterns/} directory there is a program called
-@code{transpat} which can rotate or otherwise transpose patterns.
-This program is not built by default---if you think you need it,
-@code{make transpat} in the @file{patterns/} directory and
-consult the usage remarks at the beginning of @file{patterns/transpat.c}.
+corners.
 
 @node  Pattern Classification
 @section Pattern Attributes
@@ -415 +409 @@
 need to remove the stones we placed from the reading stack. This is done
 with the function @code{popgo()}.
 
+IMPORTANT: The macro @code{OFFSET} is not used anymore, because it has
+fixed coordinates and patterns can be now rotated randomly by DFA
+optimizer. All helpers that require usage of this macro have to be moved
+to autohelpers.
+
 @node  Autohelpers and Constraints
 @section Autohelpers and Constraints
 
@@ -566 +565 @@
 The autohelper functions are translated into C code by the program in
 @file{mkpat.c}. To see exactly how the functions are implemented,
 consult the autohelper function definitions in that file. Autohelper
-functions can be used in both constraint and action lines.
+functions can be used in both constraint and action lines. Here is
+a partial list of them:
 
 @example
 
@@ -1063 +1063 @@
 
 The patterns in @file{conn.db} are used for helping @code{make_dragons()}
 amalgamate worms into dragons and to some extent for modifying eye spaces.
-The patterns in this database use the classifications @samp{B}, 
-@samp{C}, and @samp{e}. @samp{B} patterns are used for finding cutting points,
+The patterns in this database use the classifications @samp{B} and 
+@samp{C}. @samp{B} patterns are used for finding cutting points,
 where amalgamation should not be performed, @samp{C} patterns are used for
-finding existing connections, over which amalgamation is to be done, and 
-@samp{e} patterns are used for modifying eye spaces and reevaluating lunches.
+finding existing connections, over which amalgamation is to be done.
 There are also some patterns without classification, which use action lines to
 have an impact. These are matched together with the @samp{C} patterns. Further
 details and examples can be found in @xref{Worms and Dragons}.
@@ -1181 +1180 @@
 @findex find_connections
 @quotation 
 Find explicit connection patterns and amalgamate the involved dragons.
-This goes through the connection database consulting patterns except those of
-type B, E or e. When such a function is found, the function
+This goes through the connection database consulting only patterns of type C.
+When such a function is found, the function
 @code{cut_connect_callback} is invoked.
 @end quotation
-@item void modify_eye_spaces1(void)
-@findex modify_eye_spaces1
-@quotation 
-Find explicit connection patterns and amalgamate the involved dragons.
-This goes through the connection database consulting only patterns
-of type E (@pxref{Connections Database}). When such a function is found, the
-function @code{cut_connect_callback} is invoked.  
-@end quotation
-@item void modify_eye_spaces1(void)
-@findex modify_eye_spaces1
-@quotation 
-Find explicit connection patterns and amalgamate the involved dragons.
-This goes through the connection database consulting only patterns
-of type e (@pxref{Connections Database}). When such a function is found, the
-function @code{cut_connect_callback} is invoked.  
-@end quotation
 @end itemize
 
 @node  Tuning
@@ -1397 +1380 @@
 @file{patterns.h}) by a standalone program @file{mkpat.c}, and the resulting 
 @file{.c} files are compiled and linked into the main GNU Go executable.
 
+IMPORTANT: After any change in patterns, which uses DFA pattern matching, one
+should optimize pattern databases, in which the changes was made. This is done
+by running a part of @file{optimize} script in @file{patterns} directory. Run
+only parts of this script, which refers to desired databases, because it takes
+a very long time to execute.
+
 Each pattern is compiled to a header, and a sequence of elements,
 which are (notionally) checked sequentially at every position and
 orientation of the board. These elements are relative to the pattern

doc/reading.texi

@@ -66 +66 @@
 
 The function @code{do_attack} and @code{do_find_defense} are wrappers
 themselves and call @code{attack1}, @code{attack2}, @code{attack3} or
-@code{attack4} resp.  @code{defend1}, @code{defend1}, @code{defend1}
-or @code{defend1} depending on the number of liberties.
+@code{attack4} resp.  @code{defend1}, @code{defend2}, @code{defend3}
+or @code{defend4} depending on the number of liberties.
 
 These are fine-tuned to generate and try out the moves in an efficient
 order. They generate a few moves themselves (mostly direct liberties
@@ -123 +123 @@
 3 liberties are considered, but branching is inhibited, so fewer
 variations are considered.
 
-%@findex small_semeai
-%Currently the reading code does not try to defend a string by
-%attacking a boundary string with more than two liberties. Because
-%of this restriction, it can make oversights. A symptom of this is
-%two adjacent strings, each having three or four liberties, each
-%classified as @code{DEAD}. To resolve such situations, a function
-%@code{small_semeai()} (in @file{engine/semeai.c}) looks for such
-%pairs of strings and corrects their classification.
-
 The @code{backfill_depth} is a similar variable with a default 12. Below
 this depth, GNU Go will try "backfilling" to capture stones.
 For example in this situation:
@@ -173 +164 @@
 be attacked, and if so, @code{*move} returns the attacking move,
 unless @code{*movei} is a null pointer. (Use null pointers if
 you are interested in the result of the attack but not the
-attacking move itself.) Returns @code{WIN}, if the attack succeeds,
-0 if it fails, and @code{KO_A} or @code{KO_B} if the result depends on ko
-@ref{Return Codes}.
+attacking move itself.) Returns a result code of the move
+@xref{Return Codes}.
 @end quotation
 @findex find_defense
 @item @code{find_defense(int str, int *move)}
 @quotation 
-Attempts to find a move that will save the string at @code{str}. It
-returns true if such a move is found, with @code{*move} the location
+Attempts to find a move that will save the string at @code{str}, and if
+so, @code{*move} returns the location
 of the saving move (unless @code{*move} is a null pointer). It is not
 checked that tenuki defends, so this may give an erroneous answer if
-@code{!attack(str)}.  Returns @code{KO_A} or @code{KO_B} if the
-result depends on ko @xref{Return Codes}. 
+@code{!attack(str)}.  Returns a result code of the move
+@xref{Return Codes}. 
 @end quotation
 @findex safe_move
 @item @code{safe_move(int str, int color)} :
 @quotation
 The function @code{safe_move(str, color)} checks whether a move at
 @code{str} is illegal or can immediately be captured. If @code{stackp==0}
-the result is cached. If the move only can be captured by a ko, it's
-considered safe. This may or may not be a good convention.
+the result is cached. Returns a result code of an attack on the placed
+stone.
 @end quotation
 @end itemize
 
@@ -225 +215 @@
 option @pxref{Invoking GNU Go}.
 
 The hash table is created once and for all at the beginning of
-the game by the function @code{hashtable_new()}. Although hash
+the game by the function @code{reading_cache_init()}. Although hash
 memory is thus allocated only once in the game, the table is
 reinitialized at the beginning of each move by a call to
-@code{hashtable_clear()} from @code{genmove()}.
+@code{reading_cache_clear()} from @code{genmove()}.
 
 @menu
 * Hash Calculation::            Calculation of the hash value
 * Hash Organization::           Organization of the hash table
-* Hash Structures::             Structures in @file{hash.h}
 @end menu
 
 @node Hash Calculation
@@ -249 +238 @@
 @enumerate
 @item First we define a @dfn{go position}.  This positions consists of
 @itemize @bullet
-@item the actual board, i.e. the locations and colors of the stones
-@item A @dfn{ko point}, if a ko is going on.  The ko point is defined as
+@item the actual board, i.e. the locations and colors of the stones;
+@item a @dfn{ko point}, if a ko is going on; the ko point is defined as
 the empty point where the last single stone was situated before
 it was captured.
 @end itemize
 
+In addition to that we include some more information into the hash code,
+that describes stored analisys results:
+@itemize @bullet
+@item a @dfn{komaster} and @dfn{kom_pos}, @xref{Ko},
+@item an ID (an int between 0 and 255) of a function used to calculate
+the results;
+@item a target of analisys (up to two positions on a board);
+@item sometimes some extra information used by various functions.
+@end itemize
+
 It is not necessary to specify the color to move (white or black)
 as part of the position. The reason for this is that read results
 are stored separately for the various reading functions such as
 @code{attack3}, and it is implicit in the calling function which
 player is to move.
 
-@item For each location on the board we generate random numbers:
-@itemize @bullet
-@item A number which is used if there is a white stone on this location
-@item A number which is used if there is a black stone on this location
-@item A number which is used if there is a ko on this location
-@end itemize
-
+@item For each of the above information (excluding extra information)
+we generate tables with random numbers for each: function, komaster
+status or position on a board.
 These random numbers are generated once at initialization time and
 then used throughout the life time of the hash table.
 
 @item The hash key for a position is the XOR of all the random numbers
-which are applicable for the position (white stones, black stones, and
-ko position).
+which are applicable for the position. If extra information is needed
+it is passed by a function as a hash code which is XORed into the
+resulting hash key.
 @end enumerate
 
 @node Hash Organization
 @subsection Organization of the hash table
 
-The hash table consists of 3 parts:
-
-@cindex Hash node
-@cindex Read result
-
-@itemize @bullet
-@item An area which contains so called @dfn{Hash Nodes}. Each hash node
-contains:
-@itemize @minus
-@item A go position as defined above.
-@item A computed hash value for the position
-@item A pointer to Read Results (see below)
-@item A pointer to another hash node.
-@end itemize
-
-@item An area with so called Read Results.  These are used to store
-which function was called in the go position, which string was
-under attack or to be defended, and the result of the reading.
-
-Each Read Result contains: 
-@itemize @minus
-@item the function ID (an int between 0 and 255), the position of the
-string under attack and a depth value, which is used to
-determine how deep the search was when it was made, packed into
-one 32 bit integer. 
-@item The result of the search (a numeric value) and a position to
-play to get the result packed into one 32 bit integer. 
-@item A pointer to another Read Result.
-@end itemize
-
-@item An array of pointers to hash nodes.  This is the hash table
-proper.
-
-@end itemize
-
-When the hash table is created, these 3 areas are allocated using
-@code{malloc()}.  When the hash table is populated, all contents are taken
-from the Hash nodes and the Read results. No further allocation is
-done and when all nodes or results are used, the hash table is full.
-Nothing is deleted from the hash table except when it is totally
-emptied, at which point it can be used again as if newly initialized.
-
-@findex hashtable_search
-When a function wants to use the hash table, it looks up the current
-position using @code{hashtable_search()}. If the position doesn't already
-exist there, it can be entered using
-
-@findex hashtable_enter_position
-@code{hashtable_enter_position()}.  
-
-@findex hashtable_enter_position
-Once the function has a pointer to the hash node containing a
-function, it can search for a result of a previous search using
-@code{hashnode_search()}.  If a result is found, it can be used, and
-if not, a new result can be entered after a search using 
-@findex hashnode_new_result
-@code{hashnode_new_result()}.
-
-Hash nodes which hash to the same position in the hash table
-(collisions) form a simple linked list.  Read results for the same
-position, created by different functions and different attacked or
-defended strings also form a linked list.
-
-This is deemed sufficiently efficient for now, but the representation
-of collisions could be changed in the future.  It is also not
-determined what the optimum sizes for the hash table, the number of
-positions and the number of results are.
-
-@node Hash Structures
-@subsection Hash Structures
-
 The basic hash structures are declared in @file{engine/hash.h} and
-@file{engine/cache.c}
+@file{engine/cache.h}
 
-@example
-typedef struct hashposition_t @{
-  Compacttype  board[COMPACT_BOARD_SIZE];
-  int          ko_pos;
-@} Hashposition;
-@end example
-
-Represents the board and optionally the location of a ko,
-which is an illegal move. The player whose move is next
-is not recorded.
+The hash table consists of an array of pointers to hash entries and
+variable that defines number of the entries.
 
 @example
 typedef struct @{
-  Hashvalue     hashval;
-  Hashposition  hashpos;
-@} Hash_data;
-@end example
+  unsigned int num_entries;
+  Hashentry *entries;
+@} Transposition_table;
 
-Represents the return value of a function (@code{hashval}) and
-the board state (@code{hashpos}).
-
-@example
-typedef struct read_result_t @{
-  unsigned int data1;   
-  unsigned int data2;
-
-  struct read_result_t *next;
-@} Read_result;
+Transposition_table ttable;
 @end example
 
-The data1 field packs into 32 bits the following fields:
-
-@example
+@cindex Hash entry
 
-komaster:  2 bits (EMPTY, BLACK, WHITE, or GRAY)
-kom_pos : 10 bits (allows MAX_BOARD up to 31)
-routine :  4 bits (currently 10 different choices)
-str1    : 10 bits
-stackp  :  5 bits
-
-@end example
-
-The data2 field packs into 32 bits the following fields:
+The @dfn{Hash Entry} consists of two @dfn{Hash Nodes}. One is the
+most reliable node and the second is the newest. The reliability is
+computed based on cost of the function, which created a node and
+depth of analysis for that node (the lower depth the more reliable
+results).
 
 @example
-
-status :   2 bits (0 free, 1 open, 2 closed)
-result1:   4 bits
-result2:   4 bits
-move   :  10 bits
-str2   :  10 bits
-
+typedef struct @{
+  Hashnode most_reliable;
+  Hashnode newest;
+@} Hashentry;
 @end example
 
-The @code{komaster} and @code{(kom_pos)} field are
-documented in @xref{Ko}.
+@cindex Hash node
 
-When a new result node is created, 'status' is set to 1 'open'.
-This is then set to 2 'closed' when the result is entered. The main
-use for this is to identify open result nodes when the hashtable is
-partially cleared. Another potential use for this field is to
-identify repeated positions in the reading, in particular local
-double or triple kos.
+Each hash node contains a computed hash value (as defined above)
+and @dfn{Read Results}.
 
 @example
-typedef struct hashnode_t @{
-  Hash_data            key;
-  Read_result        * results;
-  struct hashnode_t  * next;
+typedef struct @{
+  Hash_data key;
+  HASHNODE_DATATYPE data; /* 32-bit value */
 @} Hashnode;
 @end example
 
-The hash table consists of hash nodes.  Each hash node consists of
-The hash value for the position it holds, the position itself and
-the actual information which is purpose of the table from the start.
+@cindex Read result
 
-There is also a pointer to another hash node which is used when
-the nodes are sorted into hash buckets (see below).
+Read Results are used to store which function was called in the go
+position, which string was under attack or to be defended, and the
+result of the reading. The result is packed into one 32 bit integer.
+Each Read Result contains: 
+@itemize @minus
+@item a remaining (to the max depth) depth value, which is used to
+determine how deep the search was when node was stored (5 bits); 
+@item the results of the search (two numeric values - 2 x 4 bits);
+@item a cost of a function which stored the result (an arbitrary
+numeric value) (4 bits);
+@item a move to play to get the result (10 bits).
+@end itemize
 
 @example
-typedef struct hashtable @{
-  size_t         hashtablesize; /* Number of hash buckets */
-  Hashnode    ** hashtable;     /* Pointer to array of hashnode lists */
+#define hn_create_data(remaining_depth, value1, value2, move, cost) \
+    ((((value1)         & 0x0f)  << 23) \
+   | (((value2)         & 0x0f)  << 19) \
+   | (((move)           & 0x3ff) <<  9) \
+   | (((cost)           & 0x0f)  <<  5) \
+   | (((remaining_depth & 0x1f)/*<<  0*/)))
+@end example
 
-  int            num_nodes;     /* Total number of hash nodes */
-  Hashnode     * all_nodes;     /* Pointer to all allocated hash nodes. */
-  int            free_node;     /* Index to next free node. */
+When the hash table is created, the hash entries are allocated using
+@code{malloc()}. After that, no further allocation is
+done and when all nodes or results are used, the hash table is full.
+Nothing is deleted, instead nodes are replaced by newer or more
+reliable nodes (when collision occurs).
 
-  int            num_results;   /* Total number of results */
-  Read_result  * all_results;   /* Pointer to all allocated results. */
-  int            free_result;   /* Index to next free result. */
-@} Hashtable;
-@end example
+@findex tt_get
+When a function wants to use the hash table, it looks up the current
+position using @code{tt_get()}. If the position doesn't already
+exist there, it can be entered using
 
-The hash table consists of three parts:
+@findex tt_update
+@code{tt_update()}.  
 
-@itemize @bullet
-@item The hash table proper: a number of hash buckets with collisions
-being handled by a linked list.
-@item The hash nodes.  These are allocated at creation time and are 
-never removed or reallocated in the current implementation.
-@item The results of the searches.  Since many different searches can
-be done in the same position, there should be more of these than
-hash nodes.
-@end itemize
+@findex tt_update
+There are several macros which store the result and return it from
+a searching functions. They are named @code{READ_RETURN0},
+@code{READ_RETURN}, @code{READ_RETURN_SEMEAI}, @code{READ_RETURN_CONN},
+@code{READ_RETURN_HASH} and @code{READ_RETURN2} and can be found in
+@file{engine/cache.h}.
 
 @node Persistent Cache
 @section Persistent Reading Cache
@@ -475 +378 @@
 Some calculations can be safely saved from move to move. If the
 opponent's move is not close to our worm or dragon, we do not have to
 reconsider the life or death of that group on the next move. So
-the result is saved in a persistent cache. Persistent caches are used for
+the result is saved in a persistent cache. Persistent caches
 are used in the engine for several types of read results.
 
 @itemize @bullet
@@ -610 +513 @@
 
 The rationale behind this rule is that in the case where there are
 two kos on the board, the komaster cannot win both, and by becoming
-komaster he has already chosen which ko he wants to win. But in the
-case of a nested ko, taking one ko is a precondition to taking the
-other one, so we allow this.
+komaster he has already chosen which ko he wants to win (the same reasoning
+applies to WEAK_KO rule). But in the case of a nested ko, taking one ko is
+a precondition to taking the other one, so we allow this.
 
 If the komaster's opponent takes a ko, then both players have taken one ko. In
 this case @code{komaster} is set to @code{GRAY_BLACK} or @code{GRAY_WHITE} and
@@ -628 +531 @@
 @itemize @bullet
 @item 1. Komaster is EMPTY.
 @itemize @minus
-@item 1a. Unconditional ko capture is allowed.
+@item 1a) Unconditional ko capture is allowed.
 @quotation
 Komaster remains EMPTY if previous move was not a ko capture.
 Komaster is set to WEAK_KO if previous move was a ko capture
@@ -642 +545 @@
 @end itemize
 @item 2. Komaster is O:
 @itemize @minus
-@item 2a) Only nested ko captures are allowed. Kom_pos is moved to the
-new removed stone.
-@item 2b) If komaster fills the ko at kom_pos then komaster reverts to
-EMPTY.
+@item 2a) Only nested ko captures are allowed.
+@quotation
+Kom_pos is moved to the new removed stone.
+@end quotation
+@item 2b) If the ko has been resolved in favor of the komaster (when the ko
+is filled or kom_pos is no longer a ko because of some capture) then the
+komaster reverts to EMPTY.
 @end itemize
 @item 3. Komaster is X:
+@itemize @minus
+@item
+Play at kom_pos is not allowed if it is the ko recapture. Any other ko capture
+is allowed.
 @quotation
-Play at kom_pos is not allowed. Any other ko capture
-is allowed. If O takes another ko, komaster becomes GRAY_X.
+If O takes another ko, komaster becomes GRAY_X.
 @end quotation
+@end itemize
 @item  4. Komaster is GRAY_O or GRAY_X:
-@quotation
-Ko captures are not allowed. If the ko at kom_pos is
-filled then the komaster reverts to EMPTY.
-@end quotation
+@itemize @minus
+@item
+Ko captures are not allowed. If the ko has been resolved in favor of
+the komaster (when the ko is filled or kom_pos is no longer a ko because
+of some capture) then the komaster reverts to EMPTY.
+@end itemize
 @item 5. Komaster is WEAK_KO:
 @itemize @minus
 @item 5a) After a non-ko move komaster reverts to EMPTY.
 @item 5b) Unconditional ko capture is only allowed if it is nested ko capture.
 @quotation
-Komaster is changed to WEAK_X and kom_pos to the old value of
-board_ko_pos.
+Kom_pos is moved to the old value of board_ko_pos.
 @end quotation
 @item 5c) Conditional ko capture is allowed according to the rules of 1b.
 @end itemize
@@ -801 +712 @@
 The correct resolution is that H1 attacks L1 unconditionally while K2
 defends it with ko (code @code{KO_A}).
 
-After Black (X) takes the ko at K3, white can do nothing
+After Black (X) takes the ko at K2, white can do nothing
 but retake the ko conditionally, becoming komaster. B cannot
 do much, but in one variation he plays at K4 and W takes
 at H1. The following position results:
@@ -821 +732 @@
 @end example
 
 Now it is important the @samp{O} is no longer komaster. Were @samp{O}
-still komaster, he could capture the ko at N3 and there would be
+still komaster, he couldn't capture the ko at N3 and there would be
 no way to finish off B.
 
 

doc/using.texi

@@ -496 +496 @@
 Use Japanese Rules. This is the default unless you specify
 @option{--enable-chinese-rules} as a configure option.
 @end quotation
+@item @option{--autolevel}
+@quotation
+Turns on level adjusting according to the left time. It doesn't apply to
+GTP mode (which is turned on by GTP commands).
+@end quotation
+@item @option{--min-level @var{amount}}
+@quotation
+If the time is running out, sets the minimum level with which GNU Go
+will play. If lower level is set with --level option, it sets
+--min-level to that lower value too. Used only when --autolevel is
+turned on.
+@end quotation
+@item @option{--max-level @var{amount}}
+@quotation
+If much time is left, sets the maximum level with which GNU Go will
+play. If higher level is set with --level option, it sets --max-level
+to that higher value too. Used only when --autolevel is turned on.
+@end quotation
 @item @option{--forbid-suicide} 
 @quotation
 Do not allow suicide moves (playing a stone so that it ends up without
@@ -582 +600 @@
 accuracy. For completeness, here they are.
 
 @itemize @bullet
+@item @option{--print-levels}
+@quotation
+Prints info about each level of play of GNU Go.
+@end quotation
+@end itemize
+
+@itemize @bullet
 @item @option{-D}, @option{--depth @var{depth}}
 @cindex depth
 @quotation
@@ -621 +646 @@
 depth (default 13), GNU Go still tries to attack strings with only
 3 liberties, but only tries one move at each node.
 @end quotation
-@item @option{--break_chain-cutoff @var{depth}}
+@item @option{--break_chain-depth @var{depth}}
 @quotation
 Set the @code{break_chain_depth}. Beyond this depth, GNU Go abandons
 some attempts to defend groups by trying to capture part of the surrounding
@@ -643 +668 @@
 Such tactics are tried below @code{superstring_depth} and this
 command line option allows this parameter to be set.
 @end quotation
+@item @option{--semeai-node-limit @var{n}}
+@quotation
+If the number of variations exceeds this limit, Owl stops analyzing
+semeai moves. Default 500.
+@end quotation
 @end itemize
 
 The preceeding options are documented with the reading code
@@ -724 +754 @@
 GNU Go. It causes both the traces and the output file (@option{-o}) to
 be more informative.
 @end quotation
+@item @option{--limit-search @var{location}}
+@quotation
+Limits the area of allowed moves to a diamond with radius 6 with center
+at @var{location}.
+@end quotation
 @item @option{-T}, @option{--printboard}: colored display of dragons.
 @quotation
 Use rxvt, xterm or Linux Console. (@pxref{Colored Display})
@@ -732 +767 @@
 @quotation
 Print timing information to stderr.
 @end quotation
+@item @option{--showscore}
+@quotation
+Print scoring information to stderr.
+@end quotation
 @item @option{-E}, @option{--printeyes}: colored display of eye spaces
 @quotation
 Use rxvt, xterm or Linux Console. (@pxref{Colored Display})
@@ -799 +838 @@
 @quotation
 Print statistics (for debugging purposes).
 @end quotation
+@item @option{--profile-patterns}
+@quotation
+Print statistics for pattern usage.
+@end quotation
 @item @option{-t}, @option{--trace}
 @quotation
 Print debugging information. Use twice for more detail.
@@ -919 +962 @@
 The option @option{--capture-all-dead} requires the aftermath
 code to finish capturing all dead stones.
 @end quotation
+@item @option{--play-out-aftermath}
+@quotation
+Forces playing of aftermath (see --score).
+@end quotation
 @end itemize
 
 @subsection Experimental options

doc/utils.texi

@@ -35 +35 @@
 @item @code{int does_attack(int move, int str)}
 @findex does_attack
 @quotation
-returns true if the move at @code{move} attacks @code{str}. This means that it captures
-the string, and that @code{str} is not already dead.  
+returns the result code for an attack on the string @code{'str'} by the move
+@code{'move'}. However, if the move does not improve the attack result compared
+to tenuki, 0 is returned. In particular if the string is already captured,
+@code{does_attack()} always returns 0.
 @end quotation
 @item @code{int does_defend(int move, int str)}
 @findex does_defend
 @quotation
-@code{does_defend(move, str)} returns true if the move at @code{move}
-defends @code{str}. This means that it defends the string, and that
-@code{str} can be captured if no defense is made.
+returns the result code for a defense on the string @code{'str'} by the move
+@code{'move'}. However, if the move does not improve the defense result compared
+to tenuki, 0 is returned. If the string (str) can't be captured if no defense
+is made, 0 is returned too.
 @end quotation
 @item @code{int somewhere(int color, int last_move, ...)}
 @findex somewhere
@@ -514 +517 @@
 @item @code{void dump_stack(void)}
 @findex dump_stack
 @quotation
-for use under GDB prints the move stack.
+For use under GDB prints the move stack.
+@end quotation
+@item @code{void dump_incremental_board(void)}
+@findex dump_incremental_board
+@quotation
+Debug function. Dump all incremental board information.
 @end quotation
 @item @code{void add_stone(int pos, int color)}
 @findex add_stone
@@ -588 +596 @@
 different functions in this family.
 
 @itemize @bullet
-@item @code{int countlib(int str)}
+@item @code{int countlib(int str_pos)}
 @findex countlib
 @quotation
-Count the number of liberties of the string at @code{pos}. There
-must be a stone at this location.
+Count the number of liberties of the string at @code{str_pos}. @code{str_pos}
+must not be empty.
 @end quotation
-@item @code{int findlib(int str, int maxlib, int *libs)}
+@item @code{int findlib(int str_pos, int maxlib, int *libs)}
 @findex findlib
 @quotation
-Find the liberties of the string at @code{str}. This location must not be
-empty. The locations of up to maxlib liberties are written into
-@code{libs[]}. The full number of liberties is returned.  If you want the
-locations of all liberties, whatever their number, you should pass
-@code{MAXLIBS} as the value for @code{maxlib} and allocate space for
-@code{libs[]} accordingly.
+Find the liberties of the string at @code{str_pos}. @code{str_pos} must not be
+empty. The locations of up to maxlib liberties are written into @code{libs[]}.
+The full number of liberties is returned.  If you want the locations of all
+liberties, whatever their number, you should pass @code{MAXLIBS} as the value
+for @code{maxlib} and allocate space for @code{libs[]} accordingly.
 @end quotation
 @item @code{int fastlib(int pos, int color, int ignore_captures)}
 @findex fastlib
@@ -652 +659 @@
 Next we have some general utility functions.
 
 @itemize @bullet
-@item @code{int count_common_libs(int str1, int str2)}
+@item @code{int count_common_libs(int str1_pos, int str2_pos)}
 @findex count_common_libs
 @quotation
 Find the number of common liberties of the two strings.
 @end quotation
-@item @code{int find_common_libs(int str1, int str2, int maxlib, int *libs)}
+@item @code{int find_common_libs(int str1_pos, int str2_pos, int maxlib, int *libs)}
 @findex find_common_libs
 @quotation
 Find the common liberties of the two strings. The locations of up to
@@ -666 +673 @@
 common liberties, whatever their number, you should pass @code{MAXLIBS} as the
 value for @code{maxlib} and allocate space for @code{libs[]} accordingly.
 @end quotation
-@item @code{int have_common_lib(int str1, int str2, int *lib)}
+@item @code{int have_common_lib(int str1_pos, int str2_pos, int *lib)}
 @findex have_common_lib
 @quotation
 Determine whether two strings have at least one common liberty.
 If they do and @code{lib != NULL}, one common liberty is returned in 
 @code{*lib}.
 @end quotation
-@item @code{int countstones(int str)}
+@item @code{int countstones(int str_pos)}
 @findex countstones
 @quotation
 Report the number of stones in a string.
 @end quotation
-@item @code{int findstones(int str, int maxstones, int *stones)}
+@item @code{int count_adjacent_stones(int str1_pos, int str2_pos, int maxstones)}
+@findex count_adjacent_stones
+@quotation
+Counts how many stones in one string are directly adjacent to the second
+string. A limit can be given in the @code{maxstones} parameter so that the
+function returns immediately.
+@end quotation
+@item @code{int findstones(int str_pos, int maxstones, int *stones)}
 @findex findstones
 @quotation
-Find the stones of the string at @code{str}. The location must not be
-empty. The locations of up to maxstones stones are written into
-@code{stones[]}. The full number of stones is returned.
+Find the stones of the string at @code{str_pos}. The locations of up
+to maxstones stones are written into @code{stones[]}. The full number of
+stones is returned.
 @end quotation
-@item @code{int  chainlinks(int str, int adj[MAXCHAIN])}
+@item @code{int chainlinks(int str_pos, int adj[MAXCHAIN])}
 @findex chainlinks
 @quotation
 This very useful function returns (in the @code{adj} array) the chains
-surrounding the string at @code{str}. The number of chains is returned.
+surrounding the string at @code{str_pos}. The number of chains is returned.
 @end quotation
-@item @code{int chainlinks2(int str, int adj[MAXCHAIN], int lib)}
+@item @code{int chainlinks2(int str_pos, int adj[MAXCHAIN], int lib)}
 @findex chainlinks2
 @quotation
 Returns (in @code{adj} array) those chains surrounding the string at
-@code{str}, which has exactly @code{lib} liberties. The number of such chains
+@code{str_pos}, which has exactly @code{lib} liberties. The number of such chains
 is returned.
 @end quotation
-@item @code{int chainlinks3(int str, int adj[MAXCHAIN], int lib)}
+@item @code{int chainlinks3(int str_pos, int adj[MAXCHAIN], int lib)}
 @findex chainlinks3
 @quotation
 Returns (in @code{adj} array) the chains surrounding
-the string at @code{str}, which have less or equal @code{lib} liberties.
+the string at @code{str_pos}, which have less or equal @code{lib} liberties.
 The number of such chains is returned.
 @end quotation
-@item @code{int extended_chainlinks(int str, int adj[MAXCHAIN], int both_colors)}
+@item @code{int extended_chainlinks(int str_pos, int adj[MAXCHAIN], int both_colors)}
 @findex extended_chainlinks
 @quotation
 Returns (in the @code{adj} array) the opponent strings being directly adjacent
-to @code{str} or having a common liberty with @code{str}. The number of such
-strings is returned.  If the both_colors parameter is true, also own strings
+to string at @code{str_pos} or having a common liberty with @code{str_nr}. The number
+of such strings is returned.  If the both_colors parameter is true, also own strings
 sharing a liberty are returned.
 @end quotation
-@item @code{int find_origin(int str)}
+@item @code{int find_origin(int str_pos)}
 @findex find_origin
 @quotation
 Find the origin of a string, i.e. the point with the smallest 1D board
@@ -727 +741 @@
 i.e. whether it would get more than one liberty. This function
 returns true also for the case of a suicide move.
 @end quotation
-@item @code{int liberty_of_string(int pos, int str)}
+@item @code{int liberty_of_string(int pos, int str_pos)}
 @findex liberty_of_string
 @quotation
-Returns true if @code{pos} is a liberty of the string at @code{str}.
+Returns true if @code{pos} is a liberty of the string at @code{str_pos}. Checks
+whether pos is a liberty.
+@end quotation
+@item @code{int liberty_of_string2(int pos, int str_pos)}
+@findex liberty_of_string2
+@quotation
+Returns true if @code{pos} is a liberty of the string at @code{str_pos}.
+@code{str_pos} must be a liberty.
 @end quotation
-@item @code{int second_order_liberty_of_string(int pos, int str)}
+@item @code{int second_order_liberty_of_string(int pos, int str_pos)}
 @findex second_order_liberty_of_string
 @quotation
-Returns true if @code{pos} is a second order liberty of the string at str.
+Returns true if @code{pos} is a second order liberty of the string at
+@code{str_pos}.
 @end quotation
-@item @code{int neighbor_of_string(int pos, int str)}
+@item @code{int are_neighbors(int pos1, int pos2)}
+@findex are_neighbors
+@quotation
+Returns true if the empty vertex or the string at @code{pos1} is
+adjacent to the empty vertex or the string at @code{pos2}.
+@end quotation
+@item @code{int neighbor_of_string(int pos, int str_pos)}
 @findex neighbor_of_string
 @quotation
-Returns true if @code{pos} is adjacent to the string at @code{str}.
+Returns true if @code{pos} is adjacent to the string at @code{str_pos}.
 @end quotation
 @item @code{int has_neighbor(int pos, int color)}
 @findex has_neighbor
 @quotation
-Returns true if @code{pos} has a neighbor of @code{color}.
+Returns true if @code{pos} has a neighbor of color @code{color}.
+@end quotation
+@item @code{int find_neighbor(int pos, int color)}
+@findex find_neighbor
+@quotation
+If @code{pos} has exactly one neighbor of color @code{color} returns
+position of this neighbor. Otherwise returns -1.
 @end quotation
-@item @code{int same_string(int str1, int str2)}
+@item @code{int same_string(int str1_pos, int str2_pos)}
 @findex same_string
 @quotation
-Returns true if @code{str1} and @code{str2} belong to the same string.
+Returns true if @code{str1_pos} and @code{str2_pos} belong to the same string.
 @end quotation
-@item @code{int adjacent_strings(int str1, int str2)}
+@item @code{int adjacent_strings(int str1_pos, int str2_pos)}
 @findex adjacent_strings
 @quotation
-Returns true if the strings at @code{str1} and @code{str2} are adjacent.
+Returns true if the strings at @code{str1_pos} and @code{str2_pos} are adjacent.
 @end quotation
 @item @code{int is_ko(int pos, int color, int *ko_pos)}
 @findex is_ko
@@ -777 +811 @@
 Return true if @code{pos} is either a stone, which if captured would give
 ko, or if @code{pos} is an empty intersection adjacent to a ko stone.
 @end quotation
+@item @code{int is_superko_violation(int pos, int color, enum ko_rules type)}
+@findex is_superko_violation
+@quotation
+Return true if a move by @code{color} at @code{pos} is a superko violation
+according to the specified type of ko rules. This function does not
+detect simple ko unless it's also a superko violation.
+@end quotation
 @item @code{int does_capture_something(int pos, int color)}
 @findex does_capture_something
 @quotation
@@ -797 +838 @@
 Returns true if at least one move has been played at pos
 at deeper than level @code{cutoff} in the reading tree.
 @end quotation
+@item @code{void get_move_from_stack(int k, int *move, int *color)}
+@findex get_move_from_stack
+@quotation
+Retrieve a move from the move stack.
+@end quotation
 @item @code{int stones_on_board(int color)}
 @findex stones_on_board
 @quotation