Commit | Line | Data |
---|---|---|
7eeb782e AT |
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 |