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