| 1 | In this Chapter, we document some of the utilities which may be |
| 2 | called from the GNU Go engine. |
| 3 | |
| 4 | @menu |
| 5 | * General Utilities:: Utilities from @file{engine/utils.c} |
| 6 | * Print Utilities:: Utilities from @file{engine/printutils.c} |
| 7 | * Board Utilities:: Utilities from @file{engine/board.c} |
| 8 | * Influence Utilities:: Utilities from @file{engine/influence.c} |
| 9 | @end menu |
| 10 | |
| 11 | @node General Utilities |
| 12 | @section General Utilities |
| 13 | |
| 14 | Utility functions from @file{engine/utils.c}. Many of these |
| 15 | functions underlie autohelper functions (@pxref{Autohelper Functions}). |
| 16 | |
| 17 | |
| 18 | @itemize @bullet |
| 19 | @item @code{void change_dragon_status(int dr, int status)} |
| 20 | @findex change_dragon_status |
| 21 | @quotation |
| 22 | Change the status of all the stones in the dragon at @code{dr}. |
| 23 | @end quotation |
| 24 | @item @code{int defend_against(int move, int color, int apos)} |
| 25 | @findex defend_against |
| 26 | @quotation |
| 27 | Check whether a move at @code{move} stops the enemy from playing at (apos). |
| 28 | @end quotation |
| 29 | @item @code{int cut_possible(int pos, int color)} |
| 30 | @quotation |
| 31 | Returns true if @code{color} can cut at @code{pos}, or if connection through |
| 32 | @code{pos} is inhibited. This information is collected by @code{find_cuts()}, |
| 33 | using the B patterns in the connections database. |
| 34 | @end quotation |
| 35 | @item @code{int does_attack(int move, int str)} |
| 36 | @findex does_attack |
| 37 | @quotation |
| 38 | returns true if the move at @code{move} attacks @code{str}. This means that it captures |
| 39 | the string, and that @code{str} is not already dead. |
| 40 | @end quotation |
| 41 | @item @code{int does_defend(int move, int str)} |
| 42 | @findex does_defend |
| 43 | @quotation |
| 44 | @code{does_defend(move, str)} returns true if the move at @code{move} |
| 45 | defends @code{str}. This means that it defends the string, and that |
| 46 | @code{str} can be captured if no defense is made. |
| 47 | @end quotation |
| 48 | @item @code{int somewhere(int color, int last_move, ...)} |
| 49 | @findex somewhere |
| 50 | @quotation |
| 51 | Example: @code{somewhere(WHITE, 2, apos, bpos, cpos)}. |
| 52 | Returns true if one of the vertices listed satisfies |
| 53 | @code{board[pos]==color}. Here num_moves is the number of moves minus one. |
| 54 | If the check is true the dragon is not allowed to be dead. This |
| 55 | check is only valid if @code{stackp==0}. |
| 56 | @end quotation |
| 57 | @item @code{int visible_along_edge(int color, int apos, int bpos)} |
| 58 | @quotation |
| 59 | Search along the edge for the first visible stone. Start at apos |
| 60 | and move in the direction of bpos. Return 1 if the first visible |
| 61 | stone is of the given color. It is required that apos and bpos are |
| 62 | at the same distance from the edge. |
| 63 | @end quotation |
| 64 | @item @code{int test_symmetry_after_move(int move, int color, int strict)} |
| 65 | @findex test_symmetry_after_move |
| 66 | @quotation |
| 67 | Is the board symmetric (or rather antisymmetric) with respect to |
| 68 | mirroring in tengen after a specific move has been played? If the |
| 69 | move is PASS_MOVE, check the current board. |
| 70 | If strict is set we require that each stone is matched by a stone |
| 71 | of the opposite color at the mirrored vertex. Otherwise we only |
| 72 | require that each stone is matched by a stone of either color. |
| 73 | @end quotation |
| 74 | @item @code{int play_break_through_n(int color, int num_moves, ...)} |
| 75 | @findex play_break_through_n |
| 76 | @quotation |
| 77 | The function @code{play_break_through_n()} plays a sequence of moves, |
| 78 | alternating between the players and starting with color. After |
| 79 | having played through the sequence, the three last coordinate pairs |
| 80 | gives a position to be analyzed by @code{break_through()}, to see whether |
| 81 | either color has managed to enclose some stones and/or connected |
| 82 | his own stones. If any of the three last positions is empty, it's |
| 83 | assumed that the enclosure has failed, as well as the attempt to |
| 84 | connect. If one or more of the moves to play turns out to be illegal for |
| 85 | some reason, the rest of the sequence is played anyway, and |
| 86 | @code{break_through()} is called as if nothing special happened. |
| 87 | Like @code{break_through()}, this function returns 1 if the attempt to |
| 88 | break through was succesful and 2 if it only managed to cut |
| 89 | through. |
| 90 | @end quotation |
| 91 | @item @code{int play_attack_defend_n(int color, int do_attack, int num_moves, ...)} |
| 92 | @item @code{int play_attack_defend2_n(int color, int do_attack, int num_moves, ...)} |
| 93 | @findex play_attack_defend2_n |
| 94 | @findex play_attack_defend_n |
| 95 | @quotation |
| 96 | The function @code{play_attack_defend_n()} plays a sequence of moves, |
| 97 | alternating between the players and starting with @code{color}. After |
| 98 | having played through the sequence, the last coordinate pair gives |
| 99 | a target to attack or defend, depending on the value of do_attack. |
| 100 | If there is no stone present to attack or defend, it is assumed |
| 101 | that it has already been captured. If one or more of the moves to |
| 102 | play turns out to be illegal for some reason, the rest of the |
| 103 | sequence is played anyway, and attack/defense is tested as if |
| 104 | nothing special happened. Conversely, |
| 105 | @code{play_attack_defend2_n()} plays a sequence of moves, |
| 106 | alternating between the players and starting with @code{color}. After |
| 107 | having played through the sequence, the two last coordinate pairs |
| 108 | give two targets to simultaneously attack or defend, depending on |
| 109 | the value of do_attack. If there is no stone present to attack or |
| 110 | defend, it is assumed that it has already been captured. If one or |
| 111 | more of the moves to play turns out to be illegal for some reason, |
| 112 | the rest of the sequence is played anyway, and attack/defense is |
| 113 | tested as if nothing special happened. A typical use of these functions is to |
| 114 | set up a ladder in an autohelper and see whether it works or not. |
| 115 | @end quotation |
| 116 | @item @code{int play_connect_n(int color, int do_connect, int num_moves, ...)} |
| 117 | @findex play_connect_n |
| 118 | @quotation |
| 119 | Plays a sequence of moves, alternating between the players and starting |
| 120 | with @code{color}. After having played through the sequence, the two last |
| 121 | coordinates give two targets that should be connected or disconnected, |
| 122 | depending on the value of do_connect. If there is no stone present to |
| 123 | connect or disconnect, it is assumed that the connection has failed. If |
| 124 | one or more of the moves to play turns out to be illegal for some |
| 125 | reason, the rest of the sequence is played anyway, and |
| 126 | connection/disconnection is tested as if nothing special happened. |
| 127 | Ultimately the connection is decided by the functions |
| 128 | @code{string_connect} and @code{disconnect} (@pxref{Connection Reading}). |
| 129 | @end quotation |
| 130 | @item @code{void set_depth_values(int level)} |
| 131 | @findex set_depth_values |
| 132 | @quotation |
| 133 | It is assumed in reading a ladder if @code{stackp >= depth} that |
| 134 | as soon as a bounding stone is in atari, the string is safe. |
| 135 | Similar uses are made of the other depth parameters such |
| 136 | as @code{backfill_depth} and so forth. In short, simplifying |
| 137 | assumptions are made when @code{stackp} is large. Unfortunately any such |
| 138 | scheme invites the ``horizon effect,'' in which a stalling move is perceived |
| 139 | as a win, by pushing the refutation past the ``horizon''---the value of |
| 140 | @code{stackp} in which the reading assumptions are relaxed. To avoid the depth |
| 141 | it is sometimes necessary to increase the depth parameters. This |
| 142 | function can be used to set the various reading depth parameters. If |
| 143 | @code{mandated_depth_value} is not -1 that value is used; otherwise the depth |
| 144 | values are set as a function of level. The parameter |
| 145 | @code{mandated_depth_value} can be set at the command line to force a |
| 146 | particular value of depth; normally it is -1. |
| 147 | @end quotation |
| 148 | @item @code{void modify_depth_values(int n)} |
| 149 | @findex modify_depth_values |
| 150 | @quotation |
| 151 | Modify the various tactical reading depth parameters. This is |
| 152 | typically used to avoid horizon effects. By temporarily increasing |
| 153 | the depth values when trying some move, one can avoid that an |
| 154 | irrelevant move seems effective just because the reading hits a |
| 155 | depth limit earlier than it did when reading only on relevant |
| 156 | moves. |
| 157 | @end quotation |
| 158 | @item @code{void increase_depth_values(void)} |
| 159 | @findex increase_depth_values |
| 160 | @quotation |
| 161 | @code{modify_depth_values(1)}. |
| 162 | @end quotation |
| 163 | @item @code{void decrease_depth_values(void)} |
| 164 | @findex decrease_depth_values |
| 165 | @quotation |
| 166 | @code{modify_depth_values(-1)}. |
| 167 | @end quotation |
| 168 | @item @code{void restore_depth_values()} |
| 169 | @findex restore_depth_values |
| 170 | @quotation |
| 171 | Sets @code{depth} and so forth to their saved values. |
| 172 | @end quotation |
| 173 | @item @code{void set_temporary_depth_values(int d, int b, int b2, int bc, int ss, int br, int f, int k)} |
| 174 | @quotation |
| 175 | Explicitly set the depth values. This function is currently never |
| 176 | called. |
| 177 | @end quotation |
| 178 | @item @code{int confirm_safety(int move, int color, int *defense_point, char safe_stones[BOARDMAX])} |
| 179 | @findex confirm_safety |
| 180 | @quotation |
| 181 | Check that the move at color doesn't involve any kind of blunder, |
| 182 | regardless of size. |
| 183 | @end quotation |
| 184 | @item @code{float blunder_size(int move, int color, int *defense_point, char safe_stones[BOARDMAX])} |
| 185 | @findex blunder_size |
| 186 | @quotation |
| 187 | This function will detect some blunders. If the move reduces the number of |
| 188 | liberties of an adjacent friendly string, there is a danger that the move |
| 189 | could backfire, so the function checks that no friendly worm which was |
| 190 | formerly not attackable becomes attackable, and it checks that no opposing |
| 191 | worm which was not defendable becomes defendable. It returns the estimated |
| 192 | size of the blunder, or 0.0 if nothing bad has happened. The array |
| 193 | @code{safe_stones[]} contains the stones that are supposedly safe after |
| 194 | @code{move}. It may be @code{NULL}. For use when called from |
| 195 | @code{fill_liberty()}, this function may optionally return a point of defense, |
| 196 | which, if taken, will presumably make the move at @code{move} safe on a |
| 197 | subsequent turn. |
| 198 | @end quotation |
| 199 | @item @code{int double_atari(int move, int color, float *value, char safe_stones[BOARDMAX])} |
| 200 | @findex double_atari |
| 201 | @quotation |
| 202 | Returns true if a move by (color) fits the following shape: |
| 203 | @example |
| 204 | X* (O=color) |
| 205 | OX |
| 206 | @end example |
| 207 | capturing one of the two @samp{X} strings. The name is a slight misnomer since |
| 208 | this includes attacks which are not necessarily double ataris, though the |
| 209 | common double atari is the most important special case. If @code{safe_stones |
| 210 | != NULL}, then only attacks on stones marked as safe are tried. The value of |
| 211 | the double atari attack is returned in value (unless value is @code{NULL}), |
| 212 | and the attacked stones are marked unsafe. |
| 213 | @end quotation |
| 214 | @item @code{void unconditional_life(int unconditional_territory[BOARDMAX], int color)} |
| 215 | @findex unconditional_life |
| 216 | @quotation |
| 217 | Find those worms of the given color that can never be captured, even if the |
| 218 | opponent is allowed an arbitrary number of consecutive moves. The coordinates |
| 219 | of the origins of these worms are written to the worm arrays and the number of |
| 220 | non-capturable worms is returned. The algorithm is to cycle through the worms |
| 221 | until none remains or no more can be captured. A worm is removed when it is |
| 222 | found to be capturable, by letting the opponent try to play on all its |
| 223 | liberties. If the attack fails, the moves are undone. When no more worm can be |
| 224 | removed in this way, the remaining ones are unconditionally alive. After |
| 225 | this, unconditionally dead opponent worms and unconditional territory are |
| 226 | identified. To find these, we continue from the position obtained at the end |
| 227 | of the previous operation (only unconditionally alive strings remain for |
| 228 | color) with the following steps: |
| 229 | |
| 230 | @enumerate |
| 231 | @item Play opponent stones on all liberties of the unconditionally |
| 232 | alive strings except where illegal. (That the move order may |
| 233 | determine exactly which liberties can be played legally is not |
| 234 | important. Just pick an arbitrary order). |
| 235 | @item |
| 236 | Recursively extend opponent strings in atari, except where this |
| 237 | would be suicide. |
| 238 | @item |
| 239 | Play an opponent stone anywhere it can get two empty |
| 240 | neighbors. (I.e. split big eyes into small ones). |
| 241 | @item |
| 242 | an opponent stone anywhere it can get one empty |
| 243 | neighbor. (I.e. reduce two space eyes to one space eyes.) |
| 244 | Remaining opponent strings in atari and remaining liberties of the |
| 245 | unconditionally alive strings constitute the unconditional |
| 246 | territory. |
| 247 | Opponent strings from the initial position placed on |
| 248 | unconditional territory are unconditionally dead. |
| 249 | On return, @code{unconditional_territory[][]} is 1 where color has |
| 250 | unconditionally alive stones, 2 where it has unconditional |
| 251 | territory, and 0 otherwise. |
| 252 | @end enumerate |
| 253 | @end quotation |
| 254 | @item @code{void who_wins(int color, FILE *outfile)} |
| 255 | @quotation |
| 256 | Score the game and determine the winner |
| 257 | @end quotation |
| 258 | @item @code{void find_superstring(int str, int *num_stones, int *stones)} |
| 259 | @findex find_superstring |
| 260 | @cindex superstring |
| 261 | @quotation |
| 262 | Find the stones of an extended string, where the extensions are |
| 263 | through the following kinds of connections: |
| 264 | @enumerate |
| 265 | @item Solid connections (just like ordinary string). |
| 266 | @example |
| 267 | OO |
| 268 | @end example |
| 269 | @item Diagonal connection or one space jump through an intersection |
| 270 | where an opponent move would be suicide or self-atari. |
| 271 | @example |
| 272 | ... |
| 273 | O.O |
| 274 | XOX |
| 275 | X.X |
| 276 | @end example |
| 277 | @item |
| 278 | Bamboo joint. |
| 279 | @example |
| 280 | OO |
| 281 | .. |
| 282 | OO |
| 283 | @end example |
| 284 | @item Diagonal connection where both adjacent intersections are empty. |
| 285 | @example |
| 286 | .O |
| 287 | O. |
| 288 | @end example |
| 289 | @item Connection through adjacent or diagonal tactically captured stones. |
| 290 | Connections of this type are omitted when the superstring code is |
| 291 | called from reading.c, but included when the superstring code is |
| 292 | called from owl.c |
| 293 | @end enumerate |
| 294 | @end quotation |
| 295 | @item @code{void find_superstring_liberties(int str, int *num_libs, int *libs, int liberty_cap)} |
| 296 | @findex find_superstring_liberties |
| 297 | @quotation |
| 298 | This function computes the superstring at @code{str} as described above, but |
| 299 | omitting connections of type 5. Then it constructs a list of liberties of the |
| 300 | superstring which are not already liberties of @code{str}. If |
| 301 | @code{liberty_cap} is nonzero, only liberties of substrings of the superstring |
| 302 | which have fewer than @code{liberty_cap} liberties are generated. |
| 303 | @end quotation |
| 304 | @item @code{void find_proper_superstring_liberties(int str, int *num_libs, int *libs, int liberty_cap)} |
| 305 | @findex find_proper_superstring_liberties |
| 306 | @quotation |
| 307 | This function is the same as find_superstring_liberties, but it omits those |
| 308 | liberties of the string @code{str}, presumably since those have already been |
| 309 | treated elsewhere. If @code{liberty_cap} is nonzero, only liberties of |
| 310 | substrings of the superstring which have at most @code{liberty_cap} liberties |
| 311 | are generated. |
| 312 | @end quotation |
| 313 | @item @code{void find_superstring_stones_and_liberties(int str, int *num_stones, int *stones, int *num_libs, int *libs, int liberty_cap)} |
| 314 | @findex find_superstring_stones_and_liberties |
| 315 | @quotation |
| 316 | This function computes the superstring at @code{str} as described above, |
| 317 | but omitting connections of type 5. Then it constructs a list of |
| 318 | liberties of the superstring which are not already liberties of |
| 319 | @code{str}. If liberty_cap is nonzero, only liberties of substrings of the |
| 320 | superstring which have fewer than liberty_cap liberties are |
| 321 | generated. |
| 322 | @end quotation |
| 323 | @item @code{void superstring_chainlinks(int str, int *num_adj, int adjs[MAXCHAIN], int liberty_cap)} |
| 324 | @findex superstring_chainlinks |
| 325 | @quotation |
| 326 | analogous to chainlinks, this function finds boundary chains of the |
| 327 | superstring at @code{str}, including those which are boundary chains of |
| 328 | @code{str} itself. If @code{liberty_cap != 0}, only those boundary chains with |
| 329 | @code{<= liberty_cap} liberties are reported. |
| 330 | @end quotation |
| 331 | @item @code{void proper_superstring_chainlinks(int str, int *num_adj, int adjs[MAXCHAIN], int liberty_cap)} |
| 332 | @findex proper_superstring_chainlingks |
| 333 | @quotation |
| 334 | analogous to chainlinks, this function finds boundary chains of the |
| 335 | superstring at @code{str}, omitting those which are boundary chains of |
| 336 | @code{str} itself. If @code{liberty_cap != 0}, only those boundary chains with |
| 337 | @code{<= liberty_cap} liberties are reported. |
| 338 | @end quotation |
| 339 | @item @code{void start_timer(int n)} |
| 340 | @findex start_timer |
| 341 | @cindex timers |
| 342 | @quotation |
| 343 | Start a timer. GNU Go has four internal timers available for |
| 344 | assessing the time spent on various tasks. |
| 345 | @end quotation |
| 346 | @item @code{double time_report(int n, const char *occupation, int move, double mintime)} |
| 347 | @findex time_report |
| 348 | @quotation |
| 349 | Report time spent and restart the timer. Make no report if elapsed |
| 350 | time is less than mintime. |
| 351 | @end quotation |
| 352 | @end itemize |
| 353 | |
| 354 | @node Print Utilities |
| 355 | @section Print Utilities |
| 356 | @cindex formatted printing |
| 357 | |
| 358 | Functions in @file{engine/printutils.c} do formatted printing similar to |
| 359 | @code{printf} and its allies. The following formats are recognized: |
| 360 | |
| 361 | @itemize @bullet |
| 362 | @item @code{%c}, @code{%d}, @code{%f}, @code{%s}, @code{%x} |
| 363 | @quotation |
| 364 | These have their usual meaning in formatted output, printing |
| 365 | a character, integer, float, string or hexadecimal, respectively. |
| 366 | @end quotation |
| 367 | @item @code{%o} |
| 368 | @quotation |
| 369 | `Outdent.' Normally output is indented by @code{2*stackp} spaces, |
| 370 | so that the depth can be seen at a glance in traces. At the |
| 371 | beginning of a format, this @code{%o} inhibits the indentation. |
| 372 | @end quotation |
| 373 | @item @code{%H} |
| 374 | @quotation |
| 375 | Print a hashvalue. |
| 376 | @end quotation |
| 377 | @item @code{%C} |
| 378 | @quotation |
| 379 | Print a color as a string. |
| 380 | @end quotation |
| 381 | @item @code{%m}, @code{%2m} (synonyms) |
| 382 | @quotation |
| 383 | Takes 2 integers and writes a move, using the two dimensional |
| 384 | board representation (@pxref{The Board Array}) |
| 385 | @end quotation |
| 386 | @item @code{%1m} |
| 387 | @quotation |
| 388 | Takes 1 integers and writes a move, using the one dimensional |
| 389 | board representation (@pxref{The Board Array}) |
| 390 | @end quotation |
| 391 | @end itemize |
| 392 | |
| 393 | We list the non statically declared functions in @file{printutils.c}. |
| 394 | |
| 395 | @itemize @bullet |
| 396 | @item @code{void gfprintf(FILE *outfile, const char *fmt, ...)} |
| 397 | @findex gfprintf |
| 398 | @quotation |
| 399 | Formatted output to @file{outfile}. |
| 400 | @end quotation |
| 401 | @item @code{int gprintf(const char *fmt, ...)} |
| 402 | @findex gprintf |
| 403 | @quotation |
| 404 | Formatted output to stderr. Always returns 1 to allow use in short-circuit |
| 405 | logical expressions. |
| 406 | @end quotation |
| 407 | @item @code{int mprintf(const char *fmt, ...)} |
| 408 | @findex mprintf |
| 409 | @quotation |
| 410 | Formatted output to stdout. |
| 411 | @end quotation |
| 412 | @item @code{DEBUG(level, fmt, args...)} |
| 413 | @findex DEBUG |
| 414 | @quotation |
| 415 | If @code{level & debug}, do formatted output to stderr. Otherwise, ignore. |
| 416 | @end quotation |
| 417 | @item @code{void abortgo(const char *file, int line, const char *msg, int pos)} |
| 418 | @findex abortgo |
| 419 | @quotation |
| 420 | Print debugging output in an error situation, then exit. |
| 421 | @end quotation |
| 422 | @item @code{const char * color_to_string(int color)} |
| 423 | @findex color_to_string |
| 424 | @quotation |
| 425 | Convert a color value to a string |
| 426 | @end quotation |
| 427 | @item @code{const char * location_to_string(int pos)} |
| 428 | @findex location_to_string |
| 429 | @quotation |
| 430 | Convert a location to a string |
| 431 | @end quotation |
| 432 | @item @code{void location_to_buffer(int pos, char *buf)} |
| 433 | @findex location_to_buffer |
| 434 | @quotation |
| 435 | Convert a location to a string, writing to a buffer. |
| 436 | @end quotation |
| 437 | @item @code{int string_to_location(int boardsize, char *str, int *m, int *n)} |
| 438 | @findex string_to_location |
| 439 | @quotation |
| 440 | Get the @code{(m, n)} coordinates in the standard GNU Go coordinate system |
| 441 | from the string @code{str}. This means that @samp{m} is the nth row from the |
| 442 | top and @samp{n} is the column. Both coordinates are between 0 and |
| 443 | @code{boardsize-1}, inclusive. Return 1 if ok, otherwise return 0; |
| 444 | @end quotation |
| 445 | @item @code{int is_hoshi_point(int m, int n)} |
| 446 | @findex is_hoshi_point |
| 447 | True if the coordinate is a hoshi point. |
| 448 | @item @code{void draw_letter_coordinates(FILE *outfile)} |
| 449 | @findex draw_letter_coordinates |
| 450 | Print a line with coordinate letters above the board. |
| 451 | @item @code{void simple_showboard(FILE *outfile)} |
| 452 | @findex simple_showboard |
| 453 | @quotation |
| 454 | Bare bones version of @code{showboard(0)}. No fancy options, no hint of |
| 455 | color, and you can choose where to write it. |
| 456 | @end quotation |
| 457 | @end itemize |
| 458 | |
| 459 | The following functions are in @file{showbord.c}. Not all public |
| 460 | functions in that file are listed here. |
| 461 | |
| 462 | @itemize |
| 463 | @item @code{void showboard(int xo)} |
| 464 | @findex showboard |
| 465 | @quotation |
| 466 | Show go board. |
| 467 | @example |
| 468 | xo=0: black and white XO board for ascii game |
| 469 | xo=1: colored dragon display |
| 470 | xo=2: colored eye display |
| 471 | xo=3: colored owl display |
| 472 | xo=4: colored matcher status display |
| 473 | @end example |
| 474 | @end quotation |
| 475 | @item @code{const char * status_to_string(int status)} |
| 476 | @findex status_to_string |
| 477 | @quotation |
| 478 | Convert a status value to a string. |
| 479 | @end quotation |
| 480 | @item @code{const char * safety_to_string(int status)} |
| 481 | @findex safety_to_string |
| 482 | @quotation |
| 483 | Convert a safety value to a string. |
| 484 | @end quotation |
| 485 | @item @code{const char * result_to_string(int result)} |
| 486 | @findex result_to_string |
| 487 | @quotation |
| 488 | Convert a read result to a string |
| 489 | @end quotation |
| 490 | @end itemize |
| 491 | |
| 492 | @node Board Utilities |
| 493 | @section Board Utilities |
| 494 | |
| 495 | The functions documented in this section are from @file{board.c}. Other |
| 496 | functions in @file{board.c} are described in @xref{Some Board Functions}. |
| 497 | |
| 498 | @itemize @bullet |
| 499 | @item @code{void store_board(struct board_state *state)} |
| 500 | @findex store_board |
| 501 | @quotation |
| 502 | Save board state. |
| 503 | @end quotation |
| 504 | @item @code{void restore_board(struct board_state *state)} |
| 505 | @findex restore_board |
| 506 | @quotation |
| 507 | Restore a saved board state. |
| 508 | @end quotation |
| 509 | @item @code{void clear_board(void)} |
| 510 | @findex clear_board |
| 511 | @quotation |
| 512 | Clear the internal board. |
| 513 | @end quotation |
| 514 | @item @code{void dump_stack(void)} |
| 515 | @findex dump_stack |
| 516 | @quotation |
| 517 | for use under GDB prints the move stack. |
| 518 | @end quotation |
| 519 | @item @code{void add_stone(int pos, int color)} |
| 520 | @findex add_stone |
| 521 | @quotation |
| 522 | Place a stone on the board and update the board_hash. This operation |
| 523 | destroys all move history. |
| 524 | @end quotation |
| 525 | @item @code{void remove_stone(int pos)} |
| 526 | @findex remove_stone |
| 527 | @quotation |
| 528 | Remove a stone from the board and update the board_hash. This |
| 529 | operation destroys the move history. |
| 530 | @end quotation |
| 531 | @item @code{int is_pass(int pos)} |
| 532 | @findex is_pass |
| 533 | @quotation |
| 534 | Test if the move is a pass or not. Return 1 if it is. |
| 535 | @end quotation |
| 536 | @item @code{int is_legal(int pos, int color)} |
| 537 | @findex is_legal |
| 538 | @quotation |
| 539 | Determines whether the move @code{color} at @code{pos} is legal. |
| 540 | @end quotation |
| 541 | @item @code{int is_suicide(int pos, int color)} |
| 542 | @findex is_suicide |
| 543 | @quotation |
| 544 | Determines whether the move @code{color} at @code{pos} would be a suicide. |
| 545 | This is the case if |
| 546 | @enumerate |
| 547 | @item There is no neighboring empty intersection. |
| 548 | @item There is no neighboring opponent string with exactly one liberty. |
| 549 | @item There is no neighboring friendly string with more than one liberty. |
| 550 | @end enumerate |
| 551 | @end quotation |
| 552 | @item @code{int is_illegal_ko_capture(int pos, int color)} |
| 553 | @findex is_illegal_ko_capture |
| 554 | @quotation |
| 555 | Determines whether the move @code{color} at @code{pos} would be an illegal ko |
| 556 | capture. |
| 557 | @end quotation |
| 558 | @item @code{int is_edge_vertex(int pos)} |
| 559 | @findex is_edge_vertex |
| 560 | @quotation |
| 561 | Determine whether vertex is on the edge. |
| 562 | @end quotation |
| 563 | @item @code{int edge_distance(int pos)} |
| 564 | @findex edge_distance |
| 565 | @quotation |
| 566 | Distance to the edge. |
| 567 | @end quotation |
| 568 | @item @code{int is_corner_vertex(int pos)} |
| 569 | @findex is_corner_vertex |
| 570 | @quotation |
| 571 | Determine whether vertex is a corner. |
| 572 | @end quotation |
| 573 | @item @code{int get_komaster()} |
| 574 | @findex get_komaster |
| 575 | @item @code{int get_kom_pos()} |
| 576 | @findex get_kom_pos |
| 577 | @quotation |
| 578 | Public functions to access the variable @code{komaster} and @code{kom_pos}, |
| 579 | which are static in @file{board.c}. |
| 580 | @end quotation |
| 581 | @end itemize |
| 582 | |
| 583 | Next we come to @code{countlib()} and its allies, which |
| 584 | address the problem of determining how many liberties a |
| 585 | string has. Although @code{countlib()} addresses this |
| 586 | basic question, other functions can often get the needed |
| 587 | information more quickly, so there are a number of |
| 588 | different functions in this family. |
| 589 | |
| 590 | @itemize @bullet |
| 591 | @item @code{int countlib(int str)} |
| 592 | @findex countlib |
| 593 | @quotation |
| 594 | Count the number of liberties of the string at @code{pos}. There |
| 595 | must be a stone at this location. |
| 596 | @end quotation |
| 597 | @item @code{int findlib(int str, int maxlib, int *libs)} |
| 598 | @findex findlib |
| 599 | @quotation |
| 600 | Find the liberties of the string at @code{str}. This location must not be |
| 601 | empty. The locations of up to maxlib liberties are written into |
| 602 | @code{libs[]}. The full number of liberties is returned. If you want the |
| 603 | locations of all liberties, whatever their number, you should pass |
| 604 | @code{MAXLIBS} as the value for @code{maxlib} and allocate space for |
| 605 | @code{libs[]} accordingly. |
| 606 | @end quotation |
| 607 | @item @code{int fastlib(int pos, int color, int ignore_captures)} |
| 608 | @findex fastlib |
| 609 | @quotation |
| 610 | Count the liberties a stone of the given color would get if played |
| 611 | at @code{pos}. The intent of this function is to be as fast as possible, not |
| 612 | necessarily complete. But if it returns a positive value (meaning |
| 613 | it has succeeded), the value is guaranteed to be correct. Captures are ignored |
| 614 | based if the @code{ignore_captures} field is nonzero. The location @code{pos} |
| 615 | must be empty. The function fails if there are more than two neighbor strings |
| 616 | of the same color. In this case, the return value is -1. Captures are |
| 617 | handled in a very limited way, so if ignore_capture is 0, and a capture is |
| 618 | required, it will often return -1. |
| 619 | @end quotation |
| 620 | @item @code{int approxlib(int pos, int color, int maxlib, int *libs)} |
| 621 | @findex approxlib |
| 622 | @quotation |
| 623 | Find the liberties a stone of the given color would get if played at |
| 624 | @code{pos}, ignoring possible captures of opponent stones. The location |
| 625 | @code{pos} must be empty. If @code{libs != NULL}, the locations of up to |
| 626 | @code{maxlib} liberties are written into @code{libs[]}. The counting of |
| 627 | liberties may or may not be halted when @code{maxlib} is reached. The number |
| 628 | of liberties found is returned, which may be less than the total number of |
| 629 | liberties if @code{maxlib} is small. If you want the number or the locations |
| 630 | of all liberties, however many they are, you should pass @code{MAXLIBS} as the |
| 631 | value for maxlib and allocate space for @code{libs[]} accordingly. |
| 632 | @end quotation |
| 633 | @item @code{int accuratelib(int pos, int color, int maxlib, int *libs)} |
| 634 | @findex accuratelib |
| 635 | @quotation |
| 636 | Find the liberties a stone of the given color would get if played at |
| 637 | @code{pos}. This function takes into consideration all captures. Its return |
| 638 | value is exact in that sense it counts all the liberties, unless @code{maxlib} |
| 639 | allows it to stop earlier. The location @code{pos} must be empty. If |
| 640 | @code{libs != NULL}, the locations of up to @code{maxlib} liberties are |
| 641 | written into @code{libs[]}. The counting of liberties may or may not be halted |
| 642 | when @code{maxlib} is reached. The number of found liberties is returned. |
| 643 | This function guarantees that liberties which are not results of captures come |
| 644 | first in @code{libs[]} array. To find whether all the liberties starting from |
| 645 | a given one are results of captures, one may use @code{if (board[libs[k]] != |
| 646 | EMPTY)} construction. If you want the number or the locations of all |
| 647 | liberties, however many they are, you should pass @code{MAXLIBS} as the value |
| 648 | for @code{maxlib} and allocate space for @code{libs[]} accordingly. |
| 649 | @end quotation |
| 650 | @end itemize |
| 651 | |
| 652 | Next we have some general utility functions. |
| 653 | |
| 654 | @itemize @bullet |
| 655 | @item @code{int count_common_libs(int str1, int str2)} |
| 656 | @findex count_common_libs |
| 657 | @quotation |
| 658 | Find the number of common liberties of the two strings. |
| 659 | @end quotation |
| 660 | @item @code{int find_common_libs(int str1, int str2, int maxlib, int *libs)} |
| 661 | @findex find_common_libs |
| 662 | @quotation |
| 663 | Find the common liberties of the two strings. The locations of up to |
| 664 | @code{maxlib} common liberties are written into @code{libs[]}. The full |
| 665 | number of common liberties is returned. If you want the locations of all |
| 666 | common liberties, whatever their number, you should pass @code{MAXLIBS} as the |
| 667 | value for @code{maxlib} and allocate space for @code{libs[]} accordingly. |
| 668 | @end quotation |
| 669 | @item @code{int have_common_lib(int str1, int str2, int *lib)} |
| 670 | @findex have_common_lib |
| 671 | @quotation |
| 672 | Determine whether two strings have at least one common liberty. |
| 673 | If they do and @code{lib != NULL}, one common liberty is returned in |
| 674 | @code{*lib}. |
| 675 | @end quotation |
| 676 | @item @code{int countstones(int str)} |
| 677 | @findex countstones |
| 678 | @quotation |
| 679 | Report the number of stones in a string. |
| 680 | @end quotation |
| 681 | @item @code{int findstones(int str, int maxstones, int *stones)} |
| 682 | @findex findstones |
| 683 | @quotation |
| 684 | Find the stones of the string at @code{str}. The location must not be |
| 685 | empty. The locations of up to maxstones stones are written into |
| 686 | @code{stones[]}. The full number of stones is returned. |
| 687 | @end quotation |
| 688 | @item @code{int chainlinks(int str, int adj[MAXCHAIN])} |
| 689 | @findex chainlinks |
| 690 | @quotation |
| 691 | This very useful function returns (in the @code{adj} array) the chains |
| 692 | surrounding the string at @code{str}. The number of chains is returned. |
| 693 | @end quotation |
| 694 | @item @code{int chainlinks2(int str, int adj[MAXCHAIN], int lib)} |
| 695 | @findex chainlinks2 |
| 696 | @quotation |
| 697 | Returns (in @code{adj} array) those chains surrounding the string at |
| 698 | @code{str}, which has exactly @code{lib} liberties. The number of such chains |
| 699 | is returned. |
| 700 | @end quotation |
| 701 | @item @code{int chainlinks3(int str, int adj[MAXCHAIN], int lib)} |
| 702 | @findex chainlinks3 |
| 703 | @quotation |
| 704 | Returns (in @code{adj} array) the chains surrounding |
| 705 | the string at @code{str}, which have less or equal @code{lib} liberties. |
| 706 | The number of such chains is returned. |
| 707 | @end quotation |
| 708 | @item @code{int extended_chainlinks(int str, int adj[MAXCHAIN], int both_colors)} |
| 709 | @findex extended_chainlinks |
| 710 | @quotation |
| 711 | Returns (in the @code{adj} array) the opponent strings being directly adjacent |
| 712 | to @code{str} or having a common liberty with @code{str}. The number of such |
| 713 | strings is returned. If the both_colors parameter is true, also own strings |
| 714 | sharing a liberty are returned. |
| 715 | @end quotation |
| 716 | @item @code{int find_origin(int str)} |
| 717 | @findex find_origin |
| 718 | @quotation |
| 719 | Find the origin of a string, i.e. the point with the smallest 1D board |
| 720 | coordinate. The idea is to have a canonical reference point for a |
| 721 | string. |
| 722 | @end quotation |
| 723 | @item @code{int is_self_atari(int pos, int color)} |
| 724 | @findex is_self_atari |
| 725 | @quotation |
| 726 | Determine whether a move by color at @code{pos} would be a self atari, |
| 727 | i.e. whether it would get more than one liberty. This function |
| 728 | returns true also for the case of a suicide move. |
| 729 | @end quotation |
| 730 | @item @code{int liberty_of_string(int pos, int str)} |
| 731 | @findex liberty_of_string |
| 732 | @quotation |
| 733 | Returns true if @code{pos} is a liberty of the string at @code{str}. |
| 734 | @end quotation |
| 735 | @item @code{int second_order_liberty_of_string(int pos, int str)} |
| 736 | @findex second_order_liberty_of_string |
| 737 | @quotation |
| 738 | Returns true if @code{pos} is a second order liberty of the string at str. |
| 739 | @end quotation |
| 740 | @item @code{int neighbor_of_string(int pos, int str)} |
| 741 | @findex neighbor_of_string |
| 742 | @quotation |
| 743 | Returns true if @code{pos} is adjacent to the string at @code{str}. |
| 744 | @end quotation |
| 745 | @item @code{int has_neighbor(int pos, int color)} |
| 746 | @findex has_neighbor |
| 747 | @quotation |
| 748 | Returns true if @code{pos} has a neighbor of @code{color}. |
| 749 | @end quotation |
| 750 | @item @code{int same_string(int str1, int str2)} |
| 751 | @findex same_string |
| 752 | @quotation |
| 753 | Returns true if @code{str1} and @code{str2} belong to the same string. |
| 754 | @end quotation |
| 755 | @item @code{int adjacent_strings(int str1, int str2)} |
| 756 | @findex adjacent_strings |
| 757 | @quotation |
| 758 | Returns true if the strings at @code{str1} and @code{str2} are adjacent. |
| 759 | @end quotation |
| 760 | @item @code{int is_ko(int pos, int color, int *ko_pos)} |
| 761 | @findex is_ko |
| 762 | @quotation |
| 763 | Return true if the move @code{pos} by @code{color} is a ko capture |
| 764 | (whether capture is legal on this move or not). If so, |
| 765 | and if @code{ko_pos} is not a @code{NULL} pointer, then |
| 766 | @code{*ko_pos} returns the location of the captured ko stone. |
| 767 | If the move is not a ko capture, @code{*ko_pos} is set to 0. |
| 768 | A move is a ko capture if and only if |
| 769 | @enumerate |
| 770 | @item All neighbors are opponent stones. |
| 771 | @item The number of captured stones is exactly one. |
| 772 | @end enumerate |
| 773 | @end quotation |
| 774 | @item @code{int is_ko_point(int pos)} |
| 775 | @findex is_ko_point |
| 776 | @quotation |
| 777 | Return true if @code{pos} is either a stone, which if captured would give |
| 778 | ko, or if @code{pos} is an empty intersection adjacent to a ko stone. |
| 779 | @end quotation |
| 780 | @item @code{int does_capture_something(int pos, int color)} |
| 781 | @findex does_capture_something |
| 782 | @quotation |
| 783 | Returns 1 if at least one string is captured when color plays at @code{pos}. |
| 784 | @end quotation |
| 785 | @item @code{void mark_string(int str, char mx[BOARDMAX], char mark)} |
| 786 | @findex mark_string |
| 787 | @quotation |
| 788 | For each stone in the string at pos, set @code{mx} to value mark. If |
| 789 | some of the stones in the string are marked prior to calling this |
| 790 | function, only the connected unmarked stones starting from pos |
| 791 | are guaranteed to become marked. The rest of the string may or may |
| 792 | not become marked. (In the current implementation, it will.) |
| 793 | @end quotation |
| 794 | @item @code{int move_in_stack(int pos, int cutoff)} |
| 795 | @findex move_in_stack |
| 796 | @quotation |
| 797 | Returns true if at least one move has been played at pos |
| 798 | at deeper than level @code{cutoff} in the reading tree. |
| 799 | @end quotation |
| 800 | @item @code{int stones_on_board(int color)} |
| 801 | @findex stones_on_board |
| 802 | @quotation |
| 803 | Return the number of stones of the indicated color(s) on the board. |
| 804 | This only counts stones in the permanent position, not stones placed |
| 805 | by @code{trymove()} or @code{tryko()}. Use |
| 806 | @code{stones_on_board(BLACK | WHITE)} to get |
| 807 | the total number of stones on the board. |
| 808 | @end quotation |
| 809 | @end itemize |
| 810 | |
| 811 | @node Influence Utilities |
| 812 | @section Utilities from @file{engine/influence.c} |
| 813 | |
| 814 | We will only list here a portion of the public functions in @code{influence.c}. |
| 815 | The influence code is invoked through the function @code{compute_influence} |
| 816 | (@pxref{Influence Usage}). It is invoked as follows. |
| 817 | |
| 818 | @itemize @bullet |
| 819 | @item @code{void compute_influence(int color, const char safe_stones[BOARDMAX], const float strength[BOARDMAX], struct influence_data *q, int move, const char *trace_message)} |
| 820 | @findex compute_influence |
| 821 | @quotation |
| 822 | Compute the influence values for both colors. |
| 823 | The caller must |
| 824 | @itemize @minus |
| 825 | @item set up the @code{board[]} state |
| 826 | @item mark safe stones with @code{INFLUENCE_SAFE_STONE}, dead stones with 0 |
| 827 | @item mark stones newly saved by a move with @code{INFLUENCE_SAVED_STONE} |
| 828 | (this is relevant if the influence_data *q is reused to compute |
| 829 | a followup value for this move). |
| 830 | @end itemize |
| 831 | Results will be stored in q. |
| 832 | @code{move} has no effects except toggling debugging. Set it to -1 |
| 833 | for no debug output at all (otherwise it will be controlled by |
| 834 | the @option{-m} command line option). It is assumed that @code{color} is in turn to move. (This affects the |
| 835 | barrier patterns (class A, D) and intrusions (class B)). Color |
| 836 | @end quotation |
| 837 | @end itemize |
| 838 | |
| 839 | Other functions in @file{influence.c} are of the nature of utilities |
| 840 | which may be useful throughout the engine. We list the most useful |
| 841 | ones here. |
| 842 | |
| 843 | @itemize @bullet |
| 844 | @item @code{void influence_mark_non_territory(int pos, int color)} |
| 845 | @findex influence_mark_non_territory |
| 846 | @quotation |
| 847 | Called from actions for @samp{t} patterns in @file{barriers.db}. |
| 848 | Marks @code{pos} as not being territory for @code{color}. |
| 849 | @end quotation |
| 850 | @item @code{int whose_territory(const struct influence_data *q, int pos)} |
| 851 | @findex whose_territory |
| 852 | @quotation |
| 853 | Return the color of the territory at @code{pos}. If it's territory for |
| 854 | neither color, @code{EMPTY} is returned. |
| 855 | @end quotation |
| 856 | @item @code{int whose_moyo(const struct influence_data *q, int pos)} |
| 857 | @findex whose_moyo |
| 858 | @quotation |
| 859 | Return the color who has a moyo at @code{pos}. If neither color has a |
| 860 | moyo there, @code{EMPTY} is returned. The definition of moyo in terms of the |
| 861 | influences is totally ad hoc. |
| 862 | @end quotation |
| 863 | @item @code{int whose_area(const struct influence_data *q, int pos)} |
| 864 | @findex whose_area |
| 865 | @quotation |
| 866 | Return the color who has dominating influence (``area'') at @code{pos}. |
| 867 | If neither color dominates the influence there, EMPTY is returned. |
| 868 | The definition of area in terms of the influences is totally ad hoc. |
| 869 | @end quotation |
| 870 | @end itemize |
| 871 | |
| 872 | |
| 873 | |