Commit | Line | Data |
---|---|---|
7eeb782e AT |
1 | This is gnugo.info, produced by makeinfo version 4.11 from gnugo.texi. |
2 | ||
3 | INFO-DIR-SECTION GNU games | |
4 | START-INFO-DIR-ENTRY | |
5 | * GNU Go: (gnugo). The GNU Go program | |
6 | END-INFO-DIR-ENTRY | |
7 | ||
8 | \1f | |
9 | File: gnugo.info, Node: The Owl Code, Next: Combinations, Up: Pattern Based Reading | |
10 | ||
11 | 12.1 The Owl Code | |
12 | ================= | |
13 | ||
14 | The life and death code in `optics.c', described elsewhere (*note | |
15 | Eyes::), works reasonably well as long as the position is in a | |
16 | "terminal position", which we define to be one where there are no moves | |
17 | left which can expand the eye space, or limit it. In situations where | |
18 | the dragon is surrounded, yet has room to thrash around a bit making | |
19 | eyes, a simple application of the graph-based analysis will not work. | |
20 | Instead, a bit of reading is needed to reach a terminal position. | |
21 | ||
22 | The defender tries to expand his eyespace, the attacker to limit it, | |
23 | and when neither finds an effective move, the position is evaluated. We | |
24 | call this type of life and death reading "Optics With | |
25 | Limit-negotiation" (OWL). The module which implements it is in | |
26 | `engine/owl.c'. | |
27 | ||
28 | There are two reasonably small databases | |
29 | `patterns/owl_defendpats.db' and `patterns/owl_attackpats.db' of | |
30 | expanding and limiting moves. The code in `owl.c' generates a small | |
31 | move tree, allowing the attacker only moves from `owl_attackpats.db', | |
32 | and the defender only moves from `owl_defendpats.db'. In addition to | |
33 | the moves suggested by patterns, vital moves from the eye space | |
34 | analysis are also tested. | |
35 | ||
36 | A third database, `owl_vital_apats.db' includes patterns which | |
37 | override the eyespace analysis done by the optics code. Since the | |
38 | eyeshape graphs ignore the complications of shortage of liberties and | |
39 | cutting points in the surrounding chains, the static analysis of | |
40 | eyespace is sometimes wrong. The problem is when the optics code says | |
41 | that a dragon definitely has 2 eyes, but it isn't true due to shortage | |
42 | of liberties, so the ordinary owl patterns never get into play. In | |
43 | such situations `owl_vital_apats.db' is the only available measure to | |
44 | correct mistakes by the optics. Currently the patterns in | |
45 | `owl_vital_apats.db' are only matched when the level is 9 or greater. | |
46 | ||
47 | The owl code is tuned by editing these three pattern databases, | |
48 | principally the first two. | |
49 | ||
50 | A node of the move tree is considered `terminal' if no further moves | |
51 | are found from `owl_attackpats.db' or `owl_defendpats.db', or if the | |
52 | function `compute_eyes_pessimistic()' reports that the group is | |
53 | definitely alive. At this point, the status of the group is evaluated. | |
54 | The functions `owl_attack()' and `owl_defend()', with usage similar to | |
55 | `attack()' and `find_defense()', make use of the owl pattern databases | |
56 | to generate the move tree and decide the status of the group. | |
57 | ||
58 | The function `compute_eyes_pessimistic()' used by the owl code is | |
59 | very conservative and only feels certain about eyes if the eyespace is | |
60 | completely closed (i.e. no marginal vertices). | |
61 | ||
62 | The maximum number of moves tried at each node is limited by the | |
63 | parameter `MAX_MOVES' defined at the beginning of `engine/owl.c'. The | |
64 | most most valuable moves are tried first, with the following | |
65 | restrictions: | |
66 | ||
67 | * If `stackp > owl_branch_depth' then only one move is tried per | |
68 | variation. | |
69 | ||
70 | * If `stackp > owl_reading_depth' then the reading terminates, and | |
71 | the situation is declared a win for the defender (since deep | |
72 | reading may be a sign of escape). | |
73 | ||
74 | * If the node count exceeds `owl_node_limit', the reading also | |
75 | terminates with a win for the defender. | |
76 | ||
77 | * Any pattern with value 99 is considered a forced move: no other | |
78 | move is tried, and if two such moves are found, the function | |
79 | returns false. This is only relevant for the attacker. | |
80 | ||
81 | * Any pattern in `patterns/owl_attackpats.db' and | |
82 | `patterns/owl_defendpats.db' with value 100 is considered a win: if | |
83 | such a pattern is found by `owl_attack' or `owl_defend', the | |
84 | function returns true. This feature must be used most carefully. | |
85 | ||
86 | The functions `owl_attack()' and `owl_defend()' may, like `attack()' | |
87 | and `find_defense()', return an attacking or defending move through | |
88 | their pointer arguments. If the position is already won, `owl_attack()' | |
89 | may or may not return an attacking move. If it finds no move of | |
90 | interest, it will return `PASS', that is, `0'. The same goes for | |
91 | `owl_defend()'. | |
92 | ||
93 | When `owl_attack()' or `owl_defend()' is called, the dragon under | |
94 | attack is marked in the array `goal'. The stones of the dragon | |
95 | originally on the board are marked with goal=1; those added by | |
96 | `owl_defend()' are marked with goal=2. If all the original strings of | |
97 | the original dragon are captured, `owl_attack()' considers the dragon | |
98 | to be defeated, even if some stones added later can make a live group. | |
99 | ||
100 | Only dragons with small escape route are studied when the functions | |
101 | are called from `make_dragons()'. | |
102 | ||
103 | The owl code can be conveniently tested using the `--decide-owl | |
104 | LOCATION' option. This should be used with `-t' to produce a useful | |
105 | trace, `-o' to produce an SGF file of variations produced when the life | |
106 | and death of the dragon at LOCATION is checked, or both. | |
107 | `--decide-position' performs the same analysis for all dragons with | |
108 | small escape route. | |
109 | ||
110 | \1f | |
111 | File: gnugo.info, Node: Combinations, Prev: The Owl Code, Up: Pattern Based Reading | |
112 | ||
113 | 12.2 Combination reading | |
114 | ======================== | |
115 | ||
116 | It may happen that no single one of a set of worms can be killed, yet | |
117 | there is a move that guarantees that at least one can be captured. The | |
118 | simplest example is a double atari. The purpose of the code in | |
119 | `combination.c' is to find such moves. | |
120 | ||
121 | For example, consider the following situation: | |
122 | ||
123 | ||
124 | +--------- | |
125 | |....OOOOX | |
126 | |....OOXXX | |
127 | |..O.OXX.. | |
128 | |.OXO.OX.. | |
129 | |.OX..OO.. | |
130 | |.XXOOOXO. | |
131 | |..*XXOX.. | |
132 | |....XOX.. | |
133 | |.XX..X... | |
134 | |X........ | |
135 | ||
136 | Every `X' stone in this position is alive. However the move at `*' | |
137 | produces a position in which at least one of four strings will get | |
138 | captured. This is a _combination_. | |
139 | ||
140 | The driving function is called `atari_atari' because typically a | |
141 | combination involves a sequence of ataris culminating in a capture, | |
142 | though sometimes the moves involved are not ataris. For example in the | |
143 | above example, the first move at `*' is _not_ an atari, though after | |
144 | `O' defends the four stones above, a sequence of ataris ensues | |
145 | resulting in the capture of some string. | |
146 | ||
147 | Like the owl functions `atari_atari' does pattern-based reading. The | |
148 | database generating the attacking moves is `aa_attackpats.db'. One | |
149 | danger with this function is that the first atari tried might be | |
150 | irrelevant to the actual combination. To detect this possibility, once | |
151 | we've found a combination, we mark that first move as forbidden, then | |
152 | try again. If no combination of the same size or larger turns up, then | |
153 | the first move was indeed essential. | |
154 | ||
155 | * `void combinations(int color)' | |
156 | ||
157 | Generate move reasons for combination attacks and defenses | |
158 | against them. This is one of the move generators called from | |
159 | genmove(). | |
160 | ||
161 | * `int atari_atari(int color, int *attack_move, char | |
162 | defense_moves[BOARDMAX], int save_verbose)' | |
163 | ||
164 | Look for a combination for `color'. For the purpose of the | |
165 | move generation, returns the size of the smallest of the | |
166 | worms under attack. | |
167 | ||
168 | * `int atari_atari_confirm_safety(int color, int move, int *defense, | |
169 | int minsize, const char saved_dragons[BOARDMAX], const char | |
170 | saved_worms[BOARDMAX])' | |
171 | ||
172 | Tries to determine whether a move is a blunder. Wrapper | |
173 | around atari_atari_blunder_size. Check whether a combination | |
174 | attack of size at least `minsize' appears after move at | |
175 | `move' has been made. The arrays `saved_dragons[]' and | |
176 | `saved_worms[]' should be one for stones belonging to dragons | |
177 | or worms respectively, which are supposedly saved by `move'. | |
178 | ||
179 | * `int atari_atari_blunder_size(int color, int move, int *defense, | |
180 | const char safe_stones[BOARDMAX])' | |
181 | ||
182 | This function checks whether any new combination attack | |
183 | appears after move at (move) has been made, and returns its | |
184 | size (in points). `safe_stones' marks which of our stones | |
185 | are supposedly safe after this move. | |
186 | ||
187 | \1f | |
188 | File: gnugo.info, Node: Influence, Next: Monte Carlo Go, Prev: Pattern Based Reading, Up: Top | |
189 | ||
190 | 13 Influence Function | |
191 | ********************* | |
192 | ||
193 | * Menu: | |
194 | ||
195 | * Influential Concepts:: Conceptual Outline of Influence | |
196 | * Territory and Moyo:: Territory, Moyo and Area | |
197 | * Influence Usage:: Where influence gets used in the engine | |
198 | * Influence and Territory:: Influence and Territory | |
199 | * Territorial Details:: Details of the Territory Valuation | |
200 | * The Influence Core:: The Core of the Influence Function | |
201 | * The Influence Algorithm:: The algorithm of `accumlate_influence()' | |
202 | * Permeability:: Permeability | |
203 | * Escape:: Escape | |
204 | * Break Ins:: Break Ins | |
205 | * Surrounded Dragons:: Surrounded Dragons | |
206 | * Influential Patterns:: Patterns used by the Influence module | |
207 | * Influential Display:: Colored display and debugging of influence | |
208 | * Influence Tuning:: Influence tuning with view.pike | |
209 | ||
210 | \1f | |
211 | File: gnugo.info, Node: Influential Concepts, Next: Territory and Moyo, Up: Influence | |
212 | ||
213 | 13.1 Conceptual Outline of Influence | |
214 | ==================================== | |
215 | ||
216 | We define call stones "lively" if they cannot be tactically attacked, | |
217 | or if they have a tactical defense and belong to the player whose turn | |
218 | it is. Similarly, stones that cannot be strategically attacked (in the | |
219 | sense of the life-and-death analysis), or that have a strategical | |
220 | defense and belong to the player to move, are called "alive". If we | |
221 | want to use the influence function before deciding the strategical | |
222 | status, all lively stones count as alive. | |
223 | ||
224 | Every alive stone on the board works as an influence source, with | |
225 | influence of its color radiating outwards in all directions. The | |
226 | strength of the influence declines exponentially with the distance from | |
227 | the source. | |
228 | ||
229 | Influence can only flow unhindered if the board is empty, however. | |
230 | All lively stones (regardless of color) act as influence barriers, as do | |
231 | connections between enemy stones that can't be broken through. For | |
232 | example the one space jump counts as a barrier unless either of the | |
233 | stones can be captured. Notice that it doesn't matter much if the | |
234 | connection between the two stones can be broken, since in that case | |
235 | there would come influence from both directions anyway. | |
236 | ||
237 | From the influence of both colors we compute a territorial value | |
238 | between -1.0 and +1.0 for each intersection, which can be seen as the | |
239 | likely hood of it becoming territory for either color. | |
240 | ||
241 | In order to avoid finding bogus territory, we add extra influence | |
242 | sources at places where an invasion can be launched, e.g. at 3-3 under | |
243 | a handicap stone, in the middle of wide edge extensions and in the | |
244 | center of large open spaces anywhere. Similarly we add extra influence | |
245 | sources where intrusions can be made into what otherwise looks as solid | |
246 | territory, e.g. monkey jumps. These intrusions depend on whose turn we | |
247 | assume it to be. | |
248 | ||
249 | All these extra influence sources, as well as connections, are | |
250 | controlled by a pattern database, which consists of the two files | |
251 | patterns/influence.db and patterns/barriers.db. The details are | |
252 | explained in *note Influential Patterns::. | |
253 | ||
254 | \1f | |
255 | File: gnugo.info, Node: Territory and Moyo, Next: Influence Usage, Prev: Influential Concepts, Up: Influence | |
256 | ||
257 | 13.2 Territory, Moyo and Area | |
258 | ============================= | |
259 | ||
260 | Using the influence code, empty regions of the board are partitioned in | |
261 | three ways. A vertex may be described as White or Black's "territory", | |
262 | "moyo" or "area". The functions `whose_territory()', `whose_moyo()' and | |
263 | `whose_area()' will return a color, or EMPTY if it belongs to one | |
264 | player or the other in one of these classifications. | |
265 | ||
266 | * Territory | |
267 | ||
268 | Those parts of the board which are expected to materialize as | |
269 | actual points for one player or the other at the end of the | |
270 | game are considered "territory". | |
271 | ||
272 | * Moyo | |
273 | ||
274 | Those parts of the board which are either already territory | |
275 | or more generally places where a territory can easily | |
276 | materialize if the opponent neglects to reduce are considered | |
277 | "moyo". "moyo". | |
278 | ||
279 | * Area | |
280 | ||
281 | Those parts of the board where one player or the other has a | |
282 | stronger influence than his opponent are considered "area". | |
283 | ||
284 | Generally territory is moyo and moyo is area. To get a feeling for | |
285 | these concepts, load an sgf file in a middle game position with the | |
286 | option `-m 0x0180' and examine the resulting diagrams (*note | |
287 | Influential Display::). | |
288 | ||
289 | \1f | |
290 | File: gnugo.info, Node: Influence Usage, Next: Influence and Territory, Prev: Territory and Moyo, Up: Influence | |
291 | ||
292 | 13.3 Where influence gets used in the engine | |
293 | ============================================ | |
294 | ||
295 | The information obtained from the influence computation is used in a | |
296 | variety of places in the engine, and the influence module is called | |
297 | several times in the process of the move generation. The details of the | |
298 | influence computation vary according to the needs of the calling | |
299 | function. | |
300 | ||
301 | After GNU Go has decided about the tactical stability of strings, the | |
302 | influence module gets called the first time. Here all lively stones act | |
303 | as an influence source of default strength 100. The result is stored in | |
304 | the variables `initial_influence' and `initial_opposite_influence', and | |
305 | it is used as an important information for guessing the strength of | |
306 | dragons. For example, a dragon that is part of a moyo of size 25 is | |
307 | immediately considered alive. For dragons with a smaller moyo size, a | |
308 | life-and-death analysis will be done by the owl code (see *note Pattern | |
309 | Based Reading::). A dragon with a moyo size of only 5 will be | |
310 | considered weak, even if the owl code has decided that it cannot be | |
311 | killed. | |
312 | ||
313 | As a tool for both the owl code and the strength estimate of dragons, | |
314 | an "escape" influence gets computed for each dragon (*note Escape::). | |
315 | ||
316 | Once all dragons have been evaluated, the influence module is called | |
317 | again and the variables `initial_influence' and | |
318 | `initial_opposite_influence' get overwritten. Of course, the dragon | |
319 | status', which are available now, are taken into account. Stones | |
320 | belonging to a dead dragon will not serve as an influence source, and | |
321 | the strengths of other stones get adjusted according to the strength of | |
322 | their respective dragon. | |
323 | ||
324 | The result of this run is the most important tool for move | |
325 | evaluation. All helper functions of patterns as explained in *note | |
326 | Patterns:: that refer to influence results (e. g. `olib(*)' etc.) | |
327 | actually use these results. Further, `initial_influence' serves as the | |
328 | reference for computing the territorial value of a move. That is, from | |
329 | the influence strengths stored in `initial_influence', a territory | |
330 | value is assigned to each intersection. This value is supposed to | |
331 | estimate the likelyhood that this intersection will become white or | |
332 | black territory. | |
333 | ||
334 | Then, for each move that gets considered in the function | |
335 | `value_moves', the influence module is called again via the function | |
336 | `compute_move_influence' to assess the likely territorial balance after | |
337 | this move, and the result is compared with the state before that move. | |
338 | ||
339 | An additional influence computation is done in order to compute the | |
340 | followup value of a move. Some explainations are in *note Territorial | |
341 | Details::. | |
342 | ||
343 | Some of the public functions from `influence.c' which are used | |
344 | throughout the engine are listed in *note Influence Utilities::. | |
345 | ||
346 | \1f | |
347 | File: gnugo.info, Node: Influence and Territory, Next: Territorial Details, Prev: Influence Usage, Up: Influence | |
348 | ||
349 | 13.4 Influence and Territory | |
350 | ============================ | |
351 | ||
352 | In this section we consider how the influence function is used to | |
353 | estimate territory in the function `estimate_territorial_value()'. | |
354 | ||
355 | A move like `*' by `O' below is worth one point: | |
356 | ||
357 | OXXX. | |
358 | OX.XX | |
359 | O*a.X | |
360 | OX.XX | |
361 | OXXX. | |
362 | ||
363 | This is evaluated by the influence function in the following way: We | |
364 | first assign territory under the assumption that X moves first in all | |
365 | local positions in the original position; then we reassing territory, | |
366 | again under the assumption that `X' moves first in all local positions, | |
367 | but after we let `O' make the move at `*'. These two territory | |
368 | assignments are compared and the difference gives the territorial value | |
369 | of the move. | |
370 | ||
371 | Technically, the assumption that `X' plays first everywhere is | |
372 | implemented via an asymmetric pattern database in `barriers.db'. What | |
373 | exactly is a safe connection that stops hostile influence from passing | |
374 | through is different for `O' and `X'; of course such a connection has | |
375 | to be tighter for stones with color `O'. Also, additional intrusion | |
376 | influence sources are added for `X' in places where `X' stones have | |
377 | natural followup moves. | |
378 | ||
379 | In this specific example above, the asymmetry (before any move has | |
380 | been made) would turn out as follows: If `X' is in turn to move, the | |
381 | white influence would get stopped by a barrier at `*', leaving 4 points | |
382 | of territory for `X'. However, if `O' was next to move, then a | |
383 | followup move for the white stones at the left would be assumed in the | |
384 | form of an extra ("intrusion") influence source at `*'. This would get | |
385 | stopped at `a', leaving three points of territory. | |
386 | ||
387 | Returning to the valuation of a move by `O' at `*', we get a value | |
388 | of 1 for the move at `*'. However, of course this move is sente once | |
389 | it is worth playing, and should therefore (in miai counting) be awarded | |
390 | an effective value of 2. Hence we need to recognize the followup value | |
391 | of a move. GNU Go 3.0 took care of this by using patterns in | |
392 | `patterns.db' that enforced an explicit followup value. Versions from | |
393 | 3.2 on instead compute a seperate followup influence to each move | |
394 | considered. In the above example, an intrusion source will be added at | |
395 | `a' as a followup move to `*'. This destroys all of Black's territory | |
396 | and hence gives a followup value of 3. | |
397 | ||
398 | The pattern based followup value are still needed at some places, | |
399 | however. | |
400 | ||
401 | To give another example, consider this position where we want to | |
402 | estimate the value of an `O' move at `*': | |
403 | ||
404 | OOOXXX | |
405 | ..OX.. | |
406 | ..OX.. | |
407 | ...*.. | |
408 | ------ | |
409 | ||
410 | Before the move we assume `X' moves first in the local position (and | |
411 | that `O' has to connect), which gives territory like this (lower case | |
412 | letter identify territory for each player): | |
413 | ||
414 | OOOXXX | |
415 | ooOXxx | |
416 | o.OXxx | |
417 | o...xx | |
418 | ------ | |
419 | ||
420 | Then we let `O' make the move at `*' and assume `X' moves first | |
421 | again next. The territory then becomes (`X' is also assumed to have to | |
422 | connect): | |
423 | ||
424 | OOOXXX | |
425 | ooOXxx | |
426 | ooOX.x | |
427 | oo.O.x | |
428 | ------ | |
429 | ||
430 | We see that this makes a difference in territory of 4, which is what | |
431 | influence_delta_territory() should report. Then again, we have followup | |
432 | value, and here also a reverse followup value. The reverse followup | |
433 | value, which in this case will be so high that the move is treated as | |
434 | reverse sente, is added by an explicit pattern. Other sources for | |
435 | followup or reverse followup values are threats to capture a rescue a | |
436 | string of stones. See the code and comments in the function | |
437 | `value_move_reaons' for how followup and reverse followup values are | |
438 | used to adjust the effective move value. | |
439 | ||
440 | To give an example of territorial value where something is captured, | |
441 | consider the `O' move at `*' here, | |
442 | ||
443 | XXXXXXXO | |
444 | X.OOOOXO | |
445 | X.O..O*O | |
446 | -------- | |
447 | ||
448 | As before we first let the influence function determine territory | |
449 | assuming X moves first, i.e. with a captured group: | |
450 | ||
451 | XXXXXXXO | |
452 | XxyyyyXO | |
453 | Xxyxxy.O | |
454 | -------- | |
455 | ||
456 | Here `y' indicates `X' territory + captured stone, i.e. these count | |
457 | for two points. After the `O' move at `*' we instead get | |
458 | ||
459 | XXXXXXXO | |
460 | X.OOOOXO | |
461 | X.OooOOO | |
462 | -------- | |
463 | ||
464 | and we see that `X' has 16 territory fewer and `O' has two territory | |
465 | more, for a total difference of 18 points. | |
466 | ||
467 | That the influence function counts the value of captured stones was | |
468 | introduced in GNU Go 3.2. Previously this was instead done using the | |
469 | effective_size heuristic. The effective size is the number of stones | |
470 | plus the surrounding empty spaces which are closer to this string or | |
471 | dragon than to any other stones. Here the `O' string would thus have | |
472 | effective size 6 (number of stones) + 2 (interior eye) + 2*0.5 (the two | |
473 | empty vertices to the left of the string, split half each with the | |
474 | surrounding X string) + 1*0.33 (the connection point, split between | |
475 | three strings) = 9.33. As noted this value was doubled, giving 18.67 | |
476 | which is reasonably close to the correct value of 18. The effective size | |
477 | heuristic is still used in certain parts of the move valuation where we | |
478 | can't easily get a more accurate value from the influence function (e. | |
479 | g. attacks depending on a ko, attack threats). | |
480 | ||
481 | Note that this section only describes the territorial valuation of a | |
482 | move. Apart from that, GNU Go uses various heuristics in assigning a | |
483 | strategical value (weakening and strengthening of other stones on the | |
484 | board) to a move. Also, the influence function isn't quite as well | |
485 | tuned as the examples above may seem to claim. But it should give a | |
486 | fairly good idea of how the design is intended. | |
487 | ||
488 | Another matter is that so far we have only considered the change in | |
489 | secure territory. GNU Go 3.2 and later versions use a revised | |
490 | heuristic, which is explained in the next section, to assign probable | |
491 | territory to each player. | |
492 | ||
493 | \1f | |
494 | File: gnugo.info, Node: Territorial Details, Next: The Influence Core, Prev: Influence and Territory, Up: Influence | |
495 | ||
496 | 13.5 Details of the Territory Valuation | |
497 | ======================================= | |
498 | ||
499 | This section explains how GNU Go assigns a territorial value to an | |
500 | intersection once the white and black influence have been computed. | |
501 | The intention is that an intersection that has a chance of xx% of | |
502 | becoming white territory is counted as 0.xx points of territory for | |
503 | white, and similar for black. | |
504 | ||
505 | The algorithm in the function `new_value_territory' goes roughly as | |
506 | follows: | |
507 | ||
508 | If `wi' is the white influence at a point, and `bi' the black | |
509 | influence, then ` value = ( (wi-bi)/ (wi+bi) )^3' (positive values | |
510 | indicates likley white territory, negative stand for black territory) | |
511 | turns out to be very simple first guess that is still far off, but | |
512 | reasonable enough to be useful. | |
513 | ||
514 | This value is then suspect a number of corrections. Assume that this | |
515 | first guess resulted in a positive value. | |
516 | ||
517 | If both `bi' and `wi' are small, it gets reduced. What exactly is | |
518 | "small" depends on whether the intersection is close to a corner or an | |
519 | edge of the board, since it is easier to claim territory in the corner | |
520 | than in the center. | |
521 | ||
522 | Then the value at each intersection is degraded to the minimum value | |
523 | of its neighbors. This can be seen as a second implementation of the | |
524 | proverb saying that there is no territory in the center of the board. | |
525 | This step substantially reduces the size of spheres of territory that | |
526 | are open at several sides. | |
527 | ||
528 | Finally, there are a number of patterns that explicitly forbid GNU | |
529 | Go to count territory at some intersections. This is used e. g. for | |
530 | false eyes that will eventually have to be filled in. Also, points for | |
531 | prisoners are added. | |
532 | ||
533 | To fine tune this scheme, some revisions have been made to the | |
534 | influence computations that are relevant for territorial evaluation. | |
535 | This includes a reduced default attenuation and some revised pattern | |
536 | handling. | |
537 | ||
538 | \1f | |
539 | File: gnugo.info, Node: The Influence Core, Next: The Influence Algorithm, Prev: Territorial Details, Up: Influence | |
540 | ||
541 | 13.6 The Core of the Influence Function | |
542 | ======================================= | |
543 | ||
544 | The basic influence radiation process can efficiently be implemented as | |
545 | a breadth first search for adjacent and more distant points, using a | |
546 | queue structure. | |
547 | ||
548 | Influence barriers can be found by pattern matching, assisted by | |
549 | reading through constraints and/or helpers. Wall structures, invasion | |
550 | points and intrusion points can be found by pattern matching as well. | |
551 | ||
552 | When influence is computed, the basic idea is that there are a number | |
553 | of influence sources on the board, whose contributions are summed to | |
554 | produce the influence values. For the time being we can assume that the | |
555 | living stones on the board are the influence sources, although this is | |
556 | not the whole story. | |
557 | ||
558 | The function `compute_influence()' contains a loop over the board, | |
559 | and for each influence source on the board, the function | |
560 | `accumulate_influence()' is called. This is the core of the influence | |
561 | function. Before we get into the details, this is how the influence | |
562 | field from a single isolated influence source of strength 100 turns out | |
563 | (with an attenuation of 3.0): | |
564 | ||
565 | 0 0 0 0 0 0 0 0 0 0 0 | |
566 | 0 0 0 0 1 1 1 0 0 0 0 | |
567 | 0 0 0 1 2 3 2 1 0 0 0 | |
568 | 0 0 1 3 5 11 5 3 1 0 0 | |
569 | 0 1 2 5 16 33 16 5 2 1 0 | |
570 | 0 1 3 11 33 X 33 11 3 1 0 | |
571 | 0 1 2 5 16 33 16 5 2 1 0 | |
572 | 0 0 1 3 5 11 5 3 1 0 0 | |
573 | 0 0 0 1 2 3 2 1 0 0 0 | |
574 | 0 0 0 0 1 1 1 0 0 0 0 | |
575 | 0 0 0 0 0 0 0 0 0 0 0 | |
576 | ||
577 | These values are in reality floating point numbers but have been | |
578 | rounded down to the nearest integer for presentation. This means that | |
579 | the influence field does not stop when the numbers become zeroes. | |
580 | ||
581 | Internally `accumulate_influence()' starts at the influence source | |
582 | and spreads influence outwards by means of a breadth first propagation, | |
583 | implemented in the form of a queue. The order of propagation and the | |
584 | condition that influence only is spread outwards guarantee that no | |
585 | intersection is visited more than once and that the process terminates. | |
586 | In the example above, the intersections are visited in the following | |
587 | order: | |
588 | ||
589 | + + + + + + + + + + + | |
590 | + 78 68 66 64 63 65 67 69 79 + | |
591 | + 62 46 38 36 35 37 39 47 75 + | |
592 | + 60 34 22 16 15 17 23 43 73 + | |
593 | + 58 32 14 6 3 7 19 41 71 + | |
594 | + 56 30 12 2 0 4 18 40 70 + | |
595 | + 57 31 13 5 1 8 20 42 72 + | |
596 | + 59 33 21 10 9 11 24 44 74 + | |
597 | + 61 45 28 26 25 27 29 48 76 + | |
598 | + 77 54 52 50 49 51 53 55 80 + | |
599 | + + + + + + + + + + + | |
600 | ||
601 | The visitation of intersections continues in the same way on the | |
602 | intersections marked '`+' and further outwards. In a real position | |
603 | there will be stones and tight connections stopping the influence from | |
604 | spreading to certain intersections. This will disrupt the diagram | |
605 | above, but the main property of the propagation still remains, i.e. no | |
606 | intersection is visited more than once and after being visited no more | |
607 | influence will be propagated to the intersection. | |
608 | ||
609 | \1f | |
610 | File: gnugo.info, Node: The Influence Algorithm, Next: Permeability, Prev: The Influence Core, Up: Influence | |
611 | ||
612 | 13.7 The Influence Algorithm | |
613 | ============================ | |
614 | ||
615 | Let `(m, n)' be the coordinates of the influence source and `(i, j)' | |
616 | the coordinates of a an intersection being visited during propagation, | |
617 | using the same notation as in the `accumulate_influence()' function. | |
618 | Influence is now propagated to its eight closest neighbors, including | |
619 | the diagonal ones, according to the follow scheme: | |
620 | ||
621 | For each of the eight directions `(di, dj)', do: | |
622 | ||
623 | 1. Compute the scalar product `di*(i-m) + dj*(j-n)' between the | |
624 | vectors `(di,dj)' and `(i,j) - (m,n)' | |
625 | ||
626 | 2. If this is negative or zero, the direction is not outwards and we | |
627 | continue with the next direction. The exception is when we are | |
628 | visiting the influence source, i.e. the first intersection, when | |
629 | we spread influence in all directions anyway. | |
630 | ||
631 | 3. If `(i+di, j+dj)' is outside the board or occupied we also | |
632 | continue with the next direction. | |
633 | ||
634 | 4. Let S be the strength of the influence at `(i, j)'. The influence | |
635 | propagated to `(i+di, j+dj)' from this intersection is given by | |
636 | `P*(1/A)*D*S', where the three different kinds of damping are: | |
637 | ||
638 | * The permeability `P', which is a property of the board | |
639 | intersections. Normally this is one, i.e. unrestricted | |
640 | propagation, but to stop propagation through e.g. one step | |
641 | jumps, the permeability is set to zero at such intersections | |
642 | through pattern matching. This is further discussed below. | |
643 | ||
644 | * The attenuation `A', which is a property of the influence | |
645 | source and different in different directions. By default this | |
646 | has the value 3 except diagonally where the number is twice | |
647 | as much. By modifying the attenuation value it is possible to | |
648 | obtain influence sources with a larger or a smaller effective | |
649 | range. | |
650 | ||
651 | * The directional damping `D', which is the squared cosine of | |
652 | the angle between `(di,dj)' and `(i,j) - (m,n)'. The idea is | |
653 | to stop influence from "bending" around an interfering stone | |
654 | and get a continuous behavior at the right angle cutoff. The | |
655 | choice of the squared cosine for this purpose is rather | |
656 | arbitrary, but has the advantage that it can be expressed as a | |
657 | rational function of `m', `n', `i', `j', `di', and `dj', | |
658 | without involving any trigonometric or square root | |
659 | computations. When we are visiting the influence source we | |
660 | let by convention this factor be one. | |
661 | ||
662 | Influence is typically contributed from up to three neighbors | |
663 | "between" this intersection and the influence source. These values are | |
664 | simply added together. As pointed out before, all contributions will | |
665 | automatically have been made before the intersection itself is visited. | |
666 | ||
667 | When the total influence for the whole board is computed by | |
668 | `compute_influence()', `accumulate_influence()' is called once for each | |
669 | influence source. These invocations are totally independent and the | |
670 | influence contributions from the different sources are added together. | |
671 | ||
672 | \1f | |
673 | File: gnugo.info, Node: Permeability, Next: Escape, Prev: The Influence Algorithm, Up: Influence | |
674 | ||
675 | 13.8 Permeability | |
676 | ================= | |
677 | ||
678 | The permeability at the different points is initially one at all empty | |
679 | intersections and zero at occupied intersections. To get a useful | |
680 | influence function we need to modify this, however. Consider the | |
681 | following position: | |
682 | ||
683 | |...... | |
684 | |OOOO.. | |
685 | |...O.. | |
686 | |...a.X ('a' empty intersection) | |
687 | |...O.. | |
688 | |...OOO | |
689 | |.....O | |
690 | +------ | |
691 | ||
692 | The corner is of course secure territory for `O' and clearly the `X' | |
693 | stone has negligible effect inside this position. To stop `X' influence | |
694 | from leaking into the corner we use pattern matching (pattern | |
695 | Barrier1/Barrier2 in `barriers.db') to modify the permeability for `X' | |
696 | at this intersection to zero. `O' can still spread influence through | |
697 | this connection. | |
698 | ||
699 | Another case that needs to be mentioned is how the permeability | |
700 | damping is computed for diagonal influence radiation. For horizontal | |
701 | and vertical radiation we just use the permeability (for the relevant | |
702 | color) at the intersection we are radiating from. In the diagonal case | |
703 | we additionally multiply with the maximum permeability at the two | |
704 | intersections we are trying to squeeze between. The reason for this can | |
705 | be found in the diagram below: | |
706 | ||
707 | |...X |...X | |
708 | |OO.. |Oda. | |
709 | |..O. |.bc. | |
710 | |..O. |..O. | |
711 | +---- +---- | |
712 | ||
713 | We don't want `X' influence to be spread from `a' to `b', and since | |
714 | the permeability at both c and d is zero, the rule above stops this. | |
715 | ||
716 | \1f | |
717 | File: gnugo.info, Node: Escape, Next: Break Ins, Prev: Permeability, Up: Influence | |
718 | ||
719 | 13.9 Escape | |
720 | =========== | |
721 | ||
722 | One application of the influence code is in computing the | |
723 | `dragon.escape_route' field. This is computed by the function | |
724 | `compute_escape()' as follows. First, every intersection is assigned | |
725 | an escape value, ranging between 0 and 4, depending on the influence | |
726 | value of the opposite color. | |
727 | ||
728 | The `escape_route' field is modified by the code in `surround.c' | |
729 | (*note Surrounded Dragons::). It is divided by two for weakly surrounded | |
730 | dragons, and set to zero for surrounded ones. | |
731 | ||
732 | In addition to assiging an escape value to empty vertices, we also | |
733 | assign an escape value to friendly dragons. This value can range from 0 | |
734 | to 6 depending on the status of the dragon, with live dragons having | |
735 | value 6. | |
736 | ||
737 | Then we sum the values of the resulting influence escape values over | |
738 | the intersections (including friendly dragons) at distance 4, that is, | |
739 | over those intersections which can be joined to the dragon by a path of | |
740 | length 4 (and no shorter path) not passing adjacent to any unfriendly | |
741 | dragon. In the following example, we sum the influence escape value | |
742 | over the four vertices labelled '4'. | |
743 | ||
744 | ||
745 | . . . . . . . . . . . . . . . . . . | |
746 | . . . . . X . . O . . . . . X . . O | |
747 | . . X . . . . . O . . X . 2 . 4 . O | |
748 | X . . . . . . . . X . . 1 1 2 3 4 . | |
749 | X O . O . . . . O X O 1 O 1 2 3 4 O | |
750 | X O . O . . . . . X O 1 O 1 . 4 . . | |
751 | X O . . . X . O O X O 1 . . X . . O | |
752 | . . . X . . . . . . 1 . X . . . . . | |
753 | X . . . . X . . . X . . . . X . . . | |
754 | . . . . . . . . . . . . . . . . . . | |
755 | ||
756 | Since the dragon is trying to reach safety, the reader might wonder | |
757 | why `compute_influence()' is called with the opposite color of the | |
758 | dragon contemplating escape. To explain this point, we first remind | |
759 | the reader why there is a color parameter to `compute_influence()'. | |
760 | Consider the following example position: | |
761 | ||
762 | ...XX... | |
763 | OOO..OOO | |
764 | O......O | |
765 | O......O | |
766 | -------- | |
767 | ||
768 | Whether the bottom will become O territory depends on who is in turn | |
769 | to play. This is implemented with the help of patterns in barriers.db, | |
770 | so that X influence is allowed to leak into the bottom if X is in turn | |
771 | to move but not if O is. There are also "invade" patterns which add | |
772 | influence sources in sufficiently open parts of the board which are | |
773 | handled differently depending on who is in turn to move. | |
774 | ||
775 | In order to decide the territorial value of an O move in the third | |
776 | line gap above, influence is first computed in the original position | |
777 | with the opponent (i.e. X) in turn to move. Then the O stone is played | |
778 | to give: | |
779 | ||
780 | ||
781 | ...XX... | |
782 | OOO.OOOO | |
783 | O......O | |
784 | O......O | |
785 | -------- | |
786 | ||
787 | Now influence is computed once more, also this time with X in turn to | |
788 | move. The difference in territory (as computed from the influence | |
789 | values) gives the territorial value of the move. | |
790 | ||
791 | Exactly how influence is computed for use in the escape route | |
792 | estimation is all ad hoc. But it makes sense to assume the opponent | |
793 | color in turn to move so that the escape possibilities aren't | |
794 | overestimated. After we have made a move in the escape direction it is | |
795 | after all the opponent's turn. | |
796 | ||
797 | The current escape route mechanism seems good enough to be useful | |
798 | but is not completely reliable. Mostly it seems to err on the side of | |
799 | being too optimistic. | |
800 | ||
801 | \1f | |
802 | File: gnugo.info, Node: Break Ins, Next: Surrounded Dragons, Prev: Escape, Up: Influence | |
803 | ||
804 | 13.10 Break Ins | |
805 | =============== | |
806 | ||
807 | The code in `breakin.c' break-ins into territories that require deeper | |
808 | tactical reading and are thus impossible to detect for the influence | |
809 | module. It gets run after the influence module and revises its | |
810 | territory valuations. | |
811 | ||
812 | The break-in code makes use of two public functions in | |
813 | `readconnect.c', | |
814 | ||
815 | * int break_in(int str, const char goal[BOARDMAX], int *move) | |
816 | ||
817 | Returns WIN if `str' can connect to the area `goal[]' (which | |
818 | may or may not contain stones), if the string's owner gets | |
819 | the first move. | |
820 | ||
821 | * int block_off(int str, const char goal[BOARDMAX], int *move) | |
822 | ||
823 | Returns WIN if `str' cannot connect to the area `goal[]' | |
824 | (which may or may not contain stones), if the other color | |
825 | moves first. | |
826 | ||
827 | These functions are public front ends to their counterparts | |
828 | `recursive_break_in' and `recursive_block_off', which call each other | |
829 | recursively. | |
830 | ||
831 | The procedure is as follows: We look at all big (>= 10) territory | |
832 | regions as detected by the influence code. Using the computation of | |
833 | connection distances from readconnect.c, we compute all nearby vertices | |
834 | of this territory. We look for the closest safe stones belonging to the | |
835 | opponent. | |
836 | ||
837 | For each such string `str' we call | |
838 | ||
839 | * `break_in(str, territory)' if the opponent is assumed to be next | |
840 | to move, | |
841 | ||
842 | * `block_off(str, territory)' if the territory owner is next. | |
843 | ||
844 | If the break in is successful resp. the blocking unsuccessful, we | |
845 | shrink the territory, and see whether the opponent can still break in. | |
846 | We repeat this until the territory is shrunk so much that the opponent | |
847 | can no longer reach it. | |
848 | ||
849 | To see the break in code in action run GNU Go on the file | |
850 | `regression/games/break_in.sgf' with the option `-d0x102000'. Among the | |
851 | traces you will find: | |
852 | ||
853 | Trying to break in from D7 to: | |
854 | E9 (1) F9 (1) G9 (1) E8 (1) F8 (1) G8 (1) | |
855 | H8 (1) G7 (1) H7 (1) J7 (1) H6 (1) J6 (1) | |
856 | H5 (1) J5 (1) H4 (1) J4 (1) H3 (1) J3 (1) | |
857 | H2 (1) J2 (1) | |
858 | block_off D7, result 0 PASS (355, 41952 nodes, 0.73 seconds) | |
859 | E9 (1) F9 (1) G9 (1) E8 (1) F8 (1) G8 (1) | |
860 | H8 (1) G7 (1) H7 (1) J7 (1) H6 (1) J6 (1) | |
861 | H5 (1) J5 (1) H4 (1) J4 (1) H3 (1) J3 (1) | |
862 | H2 (1) J2 (1) | |
863 | B:F4 | |
864 | Erasing territory at E8 -b. | |
865 | Erasing territory at G3 -b. | |
866 | Now trying to break to smaller goal: | |
867 | F9 (1) G9 (1) F8 (1) G8 (1) H8 (1) G7 (1) | |
868 | H7 (1) J7 (1) H6 (1) J6 (1) H5 (1) J5 (1) | |
869 | H4 (1) J4 (1) H3 (1) J3 (1) H2 (1) J2 (1) | |
870 | ||
871 | This means that the function `break_in' is called with the goal | |
872 | marked 'a' in the following diagram. The code attempts to find out | |
873 | whether it is possible to connect into this area from the string at | |
874 | `D7'. | |
875 | ||
876 | A B C D E F G H J | |
877 | 9 . . . . a a a . . 9 | |
878 | 8 . . . . a a a a . 8 | |
879 | 7 . . . X O O a a a 7 | |
880 | 6 . . . X X X O a a 6 | |
881 | 5 . . . . + . . a a 5 | |
882 | 4 . . . X . . O a a 4 | |
883 | 3 . . . . X . . a a 3 | |
884 | 2 . . . . . . O a a 2 | |
885 | 1 . . . . . . . . . 1 | |
886 | A B C D E F G H J | |
887 | ||
888 | A breakin is found, so the goal is shrunk by removing `E9' and `J2', | |
889 | then break_in is called again. | |
890 | ||
891 | In order to see what reading is actually done in order to do this | |
892 | break in, you may load GNU Go in gtp mode, then issue the commands: | |
893 | ||
894 | loadsgf break_in.sgf | |
895 | = black | |
896 | ||
897 | start_sgftrace | |
898 | = | |
899 | ||
900 | break_in D7 E9 F9 G9 E8 F8 G8 H8 G7 H7 J7 H6 J6 H5 J5 H4 J4 H3 J3 H2 J2 | |
901 | = 1 E8 | |
902 | ||
903 | finish_sgftrace vars.sgf | |
904 | = | |
905 | ||
906 | start_sgftrace | |
907 | = | |
908 | ||
909 | break_in D7 F9 G9 F8 G8 H8 G7 H7 J7 H6 J6 H5 J5 H4 J4 H3 J3 H2 J2 | |
910 | = 1 G7 | |
911 | ||
912 | finish_sgftrace vars1.sgf | |
913 | ||
914 | This will produce two sgf files containing the variations caused by | |
915 | these calls to the breakin code. The second file, `vars1.sgf' will | |
916 | contain quite a few variations. | |
917 | ||
918 | The break in code makes a list of break ins which are found. When | |
919 | it is finished, the function `add_expand_territory_move' is called for | |
920 | each break in, adding a move reason. | |
921 | ||
922 | The break in code is slow, and only changes a few moves by the engine | |
923 | per game. Nevertheless we believe that it contributes substantially to | |
924 | the strength of the program. The break in code is enabled by default in | |
925 | GNU Go 3.6 at level 10, and disabled at level 9. In fact, this is the | |
926 | *only* difference between levels 9 and 10 in GNU Go 3.6. | |
927 | ||
928 | \1f | |
929 | File: gnugo.info, Node: Surrounded Dragons, Next: Influential Patterns, Prev: Break Ins, Up: Influence | |
930 | ||
931 | 13.11 Surrounded Dragons | |
932 | ======================== | |
933 | ||
934 | When is a dragon surrounded? | |
935 | ||
936 | As has been pointed out by Bruce Wilcox, the geometric lines | |
937 | connecting groups of the opposite color are often important. It is very | |
938 | hard to prevent the escape of this `O' dragon: | |
939 | ||
940 | .......... | |
941 | .....O.... | |
942 | .X.......X | |
943 | .X...O...X | |
944 | .......... | |
945 | .......... | |
946 | ---------- | |
947 | ||
948 | On the other hand, this dragon is in grave danger: | |
949 | ||
950 | .......... | |
951 | .......... | |
952 | .X.......X | |
953 | .....O.... | |
954 | .X.......X | |
955 | .X...O...X | |
956 | .......... | |
957 | .......... | |
958 | ---------- | |
959 | ||
960 | The difference between these two positions is that in the first, the | |
961 | `O' dragon crosses the line connecting the top two `X' stones. | |
962 | ||
963 | Code in `surround.c' implements a test for when a dragon is | |
964 | surrounded. The idea is to compute the convex hull of the _surround | |
965 | set_, that is, the set stones belonging to unfriendly neighbor dragons. | |
966 | If the dragon is contained within that hull. If it is, it is said to be | |
967 | _surrounded_. | |
968 | ||
969 | In practice this scheme is modified slightly. The implementation | |
970 | uses various algorithms to compute distances and hostile stones are | |
971 | discarded from the surround set when a pair other hostile ones can be | |
972 | found which makes the considered one useless. For example, in the | |
973 | following position the bottom `O' stone would get discarded. | |
974 | ||
975 | O.X.O | |
976 | ..... | |
977 | .O.O. | |
978 | ..... | |
979 | ..O.. | |
980 | ||
981 | Also, points are added to the surround set below stones on the | |
982 | second and third lines. This should account for the edge being a | |
983 | natural barrier. | |
984 | ||
985 | In order to compute distances between corners of the convex hull a | |
986 | sorting by angle algorithm has been implemented. If the distance | |
987 | between a pair enclosing stones is large, the surround status gets | |
988 | decreased to `WEAKLY_SURROUNDED', or even 0 for very large ones. | |
989 | ||
990 | The sorting by angle must be explained. A small diagram will | |
991 | probably help : | |
992 | ||
993 | .O.O. | |
994 | O...O | |
995 | ..X.. | |
996 | O...O | |
997 | .O.O. | |
998 | ||
999 | The sorting algorithm will generate this: | |
1000 | ||
1001 | .4.5. | |
1002 | 3...6 | |
1003 | ..X.. | |
1004 | 2...7 | |
1005 | .1.8. | |
1006 | ||
1007 | That is, the points are sorted by ascending order of the measure of | |
1008 | the angle S-G-O, where S is SOUTH, G the (approximated) gravity center | |
1009 | of the goal, and O the position of the considered hostile stones. | |
1010 | ||
1011 | The necessity of such sorting appears when one tries to measure | |
1012 | distances between enclosing stones without sorting them, just by using | |
1013 | directly the existing left and right corners arrays. In some positions, | |
1014 | the results will be inconsistent. Imagine, for example a position where | |
1015 | for instance the points 1,2,3,4,6 and 7 were in the left arrary, | |
1016 | leaving only 5 and 8 in the right array. Because of the large distance | |
1017 | between 5 and 8, the dragon would have declared weak surrounded or not | |
1018 | surrounded at all. Such cases are rare but frequent enough to require | |
1019 | the angle sorting. | |
1020 | ||
1021 | The following position: | |
1022 | ||
1023 | O.X.O | |
1024 | ..... | |
1025 | .O.O. | |
1026 | ||
1027 | This is "more" surrounded than the following position: | |
1028 | ||
1029 | O.XXXXXX.O | |
1030 | .......... | |
1031 | .O......O. | |
1032 | ||
1033 | In the second case, the surround status would be lowered to | |
1034 | `WEAKLY_SURROUNDED'. | |
1035 | ||
1036 | The surround code is used to modify the escape_route field in the | |
1037 | dragon2 data array. When a dragon is WEAKLY_SURROUNDED, the | |
1038 | escape_route is divided by 2. If the dragon is SURROUNDED, escape_route | |
1039 | is simply set to 0. | |
1040 | ||
1041 | \1f | |
1042 | File: gnugo.info, Node: Influential Patterns, Next: Influential Display, Prev: Surrounded Dragons, Up: Influence | |
1043 | ||
1044 | 13.12 Patterns used by the Influence module | |
1045 | =========================================== | |
1046 | ||
1047 | This section explains the details of the pattern databases used for the | |
1048 | influence computation. | |
1049 | ||
1050 | First, we have the patterns in `influence.db', which get matched | |
1051 | symmetrically for both colors. | |
1052 | ||
1053 | * `E' | |
1054 | ||
1055 | These patterns add extra influence sources close to some | |
1056 | shapes like walls. This tries to reflect their extra | |
1057 | strength. These patterns are not used in the influence | |
1058 | computations relevant for territory valuations, but they are | |
1059 | useful for getting a better estimate of strengths of groups. | |
1060 | ||
1061 | * `I' | |
1062 | ||
1063 | These patterns add extra influence sources at typical | |
1064 | invasion points. Usually they are of small strength. If they | |
1065 | additionally have the class `s', the extra influence source | |
1066 | is added for both colors. Otherwise, only the player assumed | |
1067 | to be next to move gets the benefit. | |
1068 | ||
1069 | The patterns in `barriers.db' get matched only for `O' being the | |
1070 | player next to move. | |
1071 | ||
1072 | * `A' | |
1073 | ||
1074 | Connections between `X' stones that stop influence of `O'. | |
1075 | They have to be tight enough that `O' cannot break through, | |
1076 | even though he is allowed to move first. | |
1077 | ||
1078 | * `D' | |
1079 | ||
1080 | Connections between `O' stones that stop influence of `X'. The | |
1081 | stones involved can be more loosely connected than those in | |
1082 | `A' patterns. | |
1083 | ||
1084 | * `B' | |
1085 | ||
1086 | These indicate positions of followup moves for the `O' stone | |
1087 | marked with `Q' in the pattern. They are used to reduce the | |
1088 | territory e. g. where a monkey jump is possible. Also, they | |
1089 | are used in the computation of the followup influence, if the | |
1090 | `Q' stone was the move played (or a stone saved by the move | |
1091 | played). | |
1092 | ||
1093 | * `t' | |
1094 | ||
1095 | These patterns indicate intersections where one color will | |
1096 | not be able to get territory, for example in a false eye. The | |
1097 | points are set with a call to the helper non_oterritory or | |
1098 | non_xterritory in the action of the pattern. | |
1099 | ||
1100 | The intrusion patterns (`B') are more powerful than the description | |
1101 | above might suggest. They can be very helpful in identifying weak shapes | |
1102 | (by adding an intrusion source for the opponent where he can break | |
1103 | through). A negative inference for this is that a single bad `B' | |
1104 | pattern, e. g. one that has a wrong constraint, typically causes 5 to | |
1105 | 10 `FAIL's in the regression test suite. | |
1106 | ||
1107 | Influence Patterns can have autohelper constraints as usual. As for | |
1108 | the constraint attributes, there are (additionally to the usual ones | |
1109 | `O', `o', `X' and `x'), attributes `Y' and `FY'. A pattern marked with | |
1110 | `Y' will only be used in the influence computations relevant for the | |
1111 | territory valuation, while `FY' patterns only get used in the other | |
1112 | influence computations. | |
1113 | ||
1114 | The action of an influence pattern is at the moment only used for | |
1115 | non-territory patterns as mentioned above, and as a workaround for a | |
1116 | problem with `B' patterns in the followup influence. | |
1117 | ||
1118 | To see why this workaround is necessary, consider the follwoing | |
1119 | situation: | |
1120 | ||
1121 | ||
1122 | ..XXX | |
1123 | .a*.O | |
1124 | .X.O. | |
1125 | ..XXO | |
1126 | ||
1127 | (Imagine that there is `X' territory on the left.) | |
1128 | ||
1129 | The move by `O' at `*' has a natural followup move at `a'. So, in | |
1130 | the computation of the followup influence for `*', there would be an | |
1131 | extra influence source for `O' at `a' which would destroy a lot of | |
1132 | black territory on the left. This would give a big followup value, and | |
1133 | in effect the move `*' would be treated as sente. | |
1134 | ||
1135 | But of course it is gote, since `X' will answer at `a', which both | |
1136 | stops the possible intrusion and threatens to capture `*'. This | |
1137 | situation is in fact quite common. | |
1138 | ||
1139 | Hence we need an additional constraint that can tell when an | |
1140 | intrusion pattern can be used in followup influence. This is done by | |
1141 | misusing the action line: An additional line | |
1142 | ||
1143 | >return <condition>; | |
1144 | ||
1145 | gets added to the pattern. The `condition' should be true if the | |
1146 | intrusion cannot be stopped in sente. In the above example, the relevant | |
1147 | intrusion pattern will have an action line of the form | |
1148 | ||
1149 | >return (!xplay_attack(a,b)); | |
1150 | ||
1151 | where `b' refers to the stone at `*'. In fact, almost all | |
1152 | followup-specific constraints look similar to this. | |
1153 | ||
1154 | \1f | |
1155 | File: gnugo.info, Node: Influential Display, Next: Influence Tuning, Prev: Influential Patterns, Up: Influence | |
1156 | ||
1157 | 13.13 Colored display and debugging of influence | |
1158 | ================================================ | |
1159 | ||
1160 | There are various ways to obtain detailed information about the | |
1161 | influence computations. Colored diagrams showing influence are possible | |
1162 | from a colored xterm or rxvt window. | |
1163 | ||
1164 | There are two options controlling when to generate diagrams: | |
1165 | ||
1166 | * `-m 0x08' or `-m 8' | |
1167 | ||
1168 | Show diagrams for the initial influence computation. This is | |
1169 | done twice, the first time before `make_dragons()' is run and | |
1170 | the second time after. The difference is that dead dragons | |
1171 | are taken into account the second time. Tactically captured | |
1172 | worms are taken into account both times. | |
1173 | ||
1174 | * `--debug-influence LOCATION' | |
1175 | ||
1176 | Show influence diagrams after the move at the given location. | |
1177 | An important limitation of this option is that it's only | |
1178 | effective for moves that the move generation is considering. | |
1179 | ||
1180 | The other options control which diagrams should be generated in these | |
1181 | situations. You have to specify at least one of the options above and | |
1182 | at least one of the options below to generate any output. | |
1183 | ||
1184 | * The options below must be combined with one of the two previous | |
1185 | ones, or the diagram will not be printed. For example to print the | |
1186 | influence diagram, you may combine 0x08 and 0x010, and use the option | |
1187 | `-m 0x018'.* | |
1188 | ||
1189 | * `-m 0x010' or `-m 16' | |
1190 | ||
1191 | Show colored display of territory/moyo/area regions. | |
1192 | - territory: cyan | |
1193 | ||
1194 | - moyo: yellow | |
1195 | ||
1196 | - area: red | |
1197 | This feature is very useful to get an immediate impression of | |
1198 | the influence regions as GNU Go sees them. | |
1199 | ||
1200 | * `-m 0x20' or `-m 32' | |
1201 | ||
1202 | Show numerical influence values for white and black. These | |
1203 | come in two separate diagrams, the first one for white, the | |
1204 | second one for black. Notice that the influence values are | |
1205 | represented by floats and thus have been rounded in these | |
1206 | diagrams. | |
1207 | ||
1208 | * `-m 0x40' or `-m 64' | |
1209 | ||
1210 | This generates two diagrams showing the permeability for | |
1211 | black and white influence on the board. | |
1212 | ||
1213 | * `-m 0x80' or `-m 128' | |
1214 | ||
1215 | This shows the strength of the influence sources for black | |
1216 | and white across the board. You will see sources at each | |
1217 | lively stone (with strength depending on the strength of this | |
1218 | stone), and sources contributed by patterns. | |
1219 | ||
1220 | * `-m 0x100' or `-m 256' | |
1221 | ||
1222 | This shows the attenuation with which the influence sources | |
1223 | spread influence across the board. Low attenuation indicates | |
1224 | far-reaching influence sources. | |
1225 | ||
1226 | * `-m 0x200' or `-m 512' | |
1227 | ||
1228 | This shows the territory valuation of GNU Go. Each | |
1229 | intersection is shown with a value between -1.0 and +1.0 (or | |
1230 | -2 resp. +2 if there is a dead stone on this intersection). | |
1231 | Positive values indicate territory for white. A value of -0.5 | |
1232 | thus indicates a point where black has a 50% chance of | |
1233 | getting territory. | |
1234 | ||
1235 | Finally, there is the debug option `-d 0x1' which turns on on | |
1236 | `DEBUG_INFLUENCE'. This gives a message for each influence pattern that | |
1237 | gets matched. Unfortunately, these are way too many messages making it | |
1238 | tedious to navigate the output. However, if you discover an influence | |
1239 | source with `-m 0x80' that looks wrong, the debug output can help you | |
1240 | to quickly find out the responsible pattern. | |
1241 | ||
1242 | \1f | |
1243 | File: gnugo.info, Node: Influence Tuning, Prev: Influential Display, Up: Influence | |
1244 | ||
1245 | 13.14 Influence Tuning with `view.pike' | |
1246 | ======================================= | |
1247 | ||
1248 | A useful program in the regression directory is `view.pike'. To run | |
1249 | it, you need Pike, which you may download from | |
1250 | `http://pike.ida.liu.se/'. | |
1251 | ||
1252 | The test case `endgame:920' fails in GNU Go 3.6. We will explain how | |
1253 | to fix it. | |
1254 | ||
1255 | Start by firing up view.pike on testcase endgame:920, e.g. by running | |
1256 | `pike view.pike endgame:920' in the regression directory. | |
1257 | ||
1258 | We see from the first view of move values that filling dame at P15 is | |
1259 | valued highest with 0.17 points while the correct move at C4 is valued | |
1260 | slightly lower with 0.16. The real problem is of course that C4 is | |
1261 | worth a full point and thus should be valued about 1.0. | |
1262 | ||
1263 | Now click on C4 to get a list of move reasons and move valuation | |
1264 | information. Everything looks okay except that change in territory is | |
1265 | 0.00 rather than 1.00 as it ought to be. | |
1266 | ||
1267 | We can confirm this by choosing the "delta territory for..." button | |
1268 | and again clicking C4. Now B5 should have been marked as one point of | |
1269 | change in territory, but it's not. | |
1270 | ||
1271 | Next step is to enter the influence debug tool. Press the "influence" | |
1272 | button, followed by "black influence, dragons known," and "territory | |
1273 | value." This shows the expected territory if black locally moves first | |
1274 | everywhere (thus "black influence"). Here we can see that B5 is | |
1275 | incorrectly considered as 1.0 points of white territory. | |
1276 | ||
1277 | We can compare this with the territory after a white move at C4 | |
1278 | (still assuming that black locally moves first everywhere after that) by | |
1279 | pressing "after move influence for..." and clicking C4. This looks | |
1280 | identical, as expected since delta territory was 0, but here it is | |
1281 | correct that B5 is 1.0 points of territory for white. | |
1282 | ||
1283 | The most straightforward solution to this problem is to add a | |
1284 | non-territory pattern, saying that white can't get territory on B5 if | |
1285 | black moves first. The nonterritory patterns are in `barriers.db'. | |
1286 | ||
1287 | Pattern Nonterritory56 | |
1288 | ||
1289 | ... | |
1290 | X.O | |
1291 | ?O. | |
1292 | ||
1293 | :8,t | |
1294 | ||
1295 | eac | |
1296 | XbO | |
1297 | ?Od | |
1298 | ||
1299 | ;oplay_attack(a,b,c,d,d) | |
1300 | ||
1301 | >non_xterritory(e); | |
1302 | ||
1303 | In these patterns it's always assumed that `O' moves first and thus | |
1304 | it says that `X' can't get territory at `B5' (`e' in the pattern). Now | |
1305 | we need to be a bit careful however since after `O' plays at `a' and | |
1306 | `X' cuts in at `b', it may well happen that `O' needs to defend around | |
1307 | `d', allowing `X' to cut at `c', possibly making the nonterritory | |
1308 | assumption invalid. It's difficult to do this entirely accurate, but | |
1309 | the constraint above is fairly conservative and should guarantee that | |
1310 | `a' is safe in most, although not all, cases. | |
1311 | ||
1312 | \1f | |
1313 | File: gnugo.info, Node: Monte Carlo Go, Next: Libboard, Prev: Influence, Up: Top | |
1314 | ||
1315 | 14 Monte Carlo Go | |
1316 | ***************** | |
1317 | ||
1318 | In Monte Carlo Go the engine plays random games to the end, generating | |
1319 | moves from a pattern database within the context of the algorithm UCT | |
1320 | (upper confidence bounds applied to trees). This algorithm allowed the | |
1321 | program MoGo (`http://www.lri.fr/~gelly/MoGo.htm', to become the first | |
1322 | computer program to defeat a professional while taking a 9 stone | |
1323 | handicap (`http://senseis.xmp.net/?MoGo'). | |
1324 | ||
1325 | GNU Go 3.8 can play 9x9 Go with the option `--monte-carlo' using the | |
1326 | UCT algorithm. For command line options, see *Note Invoking GNU Go::. | |
1327 | ||
1328 | During reading, the engine makes incremental updates of local 3x3 | |
1329 | neighborhood, suicide status, self-atari status, and number of stones | |
1330 | captured, for each move. | |
1331 | ||
1332 | GNU Go's simulations (Monte Carlo games) are pattern generated. The | |
1333 | random playout move generation is distributed strictly proportional to | |
1334 | move values computed by table lookup from a local context consisting of | |
1335 | 3x3 neighborhood, opponent suicide status, own and opponent self-atari | |
1336 | status, number of stones captured by own and opponent move, and | |
1337 | closeness to the previous move. Let's call this local context simply "a | |
1338 | pattern" and the table "pattern values" or simply "patterns". | |
1339 | ||
1340 | There are three built-in databases that you can select using the | |
1341 | option `--mc-patterns <name>', where `<name>' is one of | |
1342 | ||
1343 | * `mc_montegnu_classic' | |
1344 | ||
1345 | * `mc_mogo_classic' | |
1346 | ||
1347 | * `mc_uniform' | |
1348 | ||
1349 | The first of these is an approximation of the previous random move | |
1350 | generation algorithm. The `mogo_classic' pattern values is an | |
1351 | approximation of the simulation policy used by early versions of MoGo, | |
1352 | as published in the report odification of UCT with Patterns in | |
1353 | Monte-Carlo Go (http://hal.inria.fr/inria-00117266) RR-6062, by Sylvain | |
1354 | Gelly, Yizao Wang, Rémi Munos, and Olivier Teytaud. The uniform pattern | |
1355 | values is the so called "light" playout which chooses uniformly between | |
1356 | all legal moves except single point proper eyes. | |
1357 | ||
1358 | If you're not satisfied with these you can also tune your own | |
1359 | pattern values with a pattern database file and load it at runtime with | |
1360 | `--mc-load-patterns <name>' adding your own pattern database. | |
1361 | ||
1362 | Let's start with the uniform pattern values. Those are defined by the | |
1363 | file `patterns/mc_uniform.db', which looks like this: | |
1364 | ||
1365 | ||
1366 | oOo | |
1367 | O*O | |
1368 | oO? | |
1369 | ||
1370 | :0 | |
1371 | ||
1372 | oOo | |
1373 | O*O | |
1374 | --- | |
1375 | ||
1376 | :0 | |
1377 | ||
1378 | |Oo | |
1379 | |*O | |
1380 | +-- | |
1381 | ||
1382 | :0 | |
1383 | ||
1384 | Patterns are always exactly 3x3 in size with the move at the center | |
1385 | point. The symbols are the usual for GNU Go pattern databases: | |
1386 | ||
1387 | * move | |
1388 | O own stone (i.e. the same color as the color to move) | |
1389 | o own stone or empty | |
1390 | X opponent stone | |
1391 | x opponent stone or empty | |
1392 | ? own stone, opponent stone, or empty | |
1393 | | vertical edge | |
1394 | - horizontal edge | |
1395 | + corner | |
1396 | ||
1397 | There's also a new symbol: | |
1398 | ||
1399 | % own stone, opponent stone, empty, or edge | |
1400 | ||
1401 | After the pattern comes a line starting with a colon. In all these | |
1402 | patterns it says that the pattern has a move value of 0, i.e. must not | |
1403 | be played. Unmatched patterns have a default value of 1. When all move | |
1404 | values are zero for both players, the playout will stop. Including the | |
1405 | three patterns above is important because otherwise the playouts would | |
1406 | be likely to go on indefinitely, or as it actually happens be | |
1407 | terminated at a hard-coded limit of 600 moves. Also place these | |
1408 | patterns at the top of the database because when multiple patterns | |
1409 | match, the first one is used, regardless of the values. | |
1410 | ||
1411 | When using only these patterns you will probably notice that it plays | |
1412 | rather heavy, trying hard to be solidly connected. This is because | |
1413 | uniform playouts are badly biased with a high probability of non-solid | |
1414 | connections being cut apart. To counter this you could try a pattern | |
1415 | like | |
1416 | ||
1417 | ?X? | |
1418 | O*O | |
1419 | x.? | |
1420 | ||
1421 | :20,near | |
1422 | ||
1423 | to increase the probability that the one-point jump is reinforced | |
1424 | when threatened. Here we added the property "near", which means that the | |
1425 | pattern only applies if the previous move was played "near" this move. | |
1426 | Primarily "near" means within the surrounding 3x3 neighborhood but it | |
1427 | also includes certain cases of liberties of low-liberty strings | |
1428 | adjacent to the previous move, e.g. the move to extend out of an atari | |
1429 | created by the previous move. You have to read the source to find out | |
1430 | the exact rules for nearness. | |
1431 | ||
1432 | We could also be even more specific and say | |
1433 | ||
1434 | ?X? | |
1435 | O*O | |
1436 | x.? | |
1437 | ||
1438 | :20,near,osafe,xsafe | |
1439 | ||
1440 | to exclude the cases where this move is a self atari (osafe) or would | |
1441 | be a self-atari for the opponent (xsafe). | |
1442 | ||
1443 | It may also be interesting to see the effect of capturing stones. A | |
1444 | catch-all pattern for captures would be | |
1445 | ||
1446 | ?X% | |
1447 | ?*% | |
1448 | %%% | |
1449 | ||
1450 | :10,ocap1,osafe | |
1451 | :20,ocap2 | |
1452 | :30,ocap3 | |
1453 | ||
1454 | where we have used multiple colon lines to specify different move | |
1455 | values depending on the number of captured stones; value 10 for a | |
1456 | single captured stone, value 20 for two captured stones, and value 30 | |
1457 | for three or more captured stones. Here we also excluded self-atari | |
1458 | moves in the case of 1 captured stone in order to avoid getting stuck | |
1459 | in triple-ko in the playouts (there's no superko detection in the | |
1460 | playouts). | |
1461 | ||
1462 | The full set of pattern properties is as follows: | |
1463 | ||
1464 | `near' | |
1465 | The move is "near" the previous move. | |
1466 | ||
1467 | `far' | |
1468 | The move is not "near" the previous move. | |
1469 | ||
1470 | `osafe' | |
1471 | The move is not a self-atari. | |
1472 | ||
1473 | `ounsafe' | |
1474 | The move is a self-atari. | |
1475 | ||
1476 | `xsafe' | |
1477 | The move would not be a self-atari for the opponent. | |
1478 | ||
1479 | `xunsafe' | |
1480 | The move would be a self-atari for the opponent. | |
1481 | ||
1482 | `xsuicide' | |
1483 | The move would be suicide for the opponent | |
1484 | ||
1485 | `xnosuicide' | |
1486 | The move would not be suicide for the opponent. | |
1487 | ||
1488 | `ocap0' | |
1489 | The move captures zero stones. | |
1490 | ||
1491 | `ocap1' | |
1492 | The move captures one stone. | |
1493 | ||
1494 | `ocap2' | |
1495 | The move captures two stones. | |
1496 | ||
1497 | `ocap3' | |
1498 | The move captures three or more stones. | |
1499 | ||
1500 | `ocap1+' | |
1501 | The move captures one or more stones. | |
1502 | ||
1503 | `ocap1-' | |
1504 | The move captures at most one stone. | |
1505 | ||
1506 | `ocap2+' | |
1507 | The move captures two or more stones. | |
1508 | ||
1509 | `ocap2-' | |
1510 | The move captures at most two stones. | |
1511 | ||
1512 | `xcap0' | |
1513 | An opponent move would capture zero stones. | |
1514 | ||
1515 | `xcap1' | |
1516 | An opponent move would capture one stone. | |
1517 | ||
1518 | `xcap2' | |
1519 | An opponent move would capture two stones. | |
1520 | ||
1521 | `xcap3' | |
1522 | An opponent move would capture three or more stones. | |
1523 | ||
1524 | `xcap1+' | |
1525 | An opponent move would capture one or more stones. | |
1526 | ||
1527 | `xcap1-' | |
1528 | An opponent move would capture at most one stone. | |
1529 | ||
1530 | `xcap2+' | |
1531 | An opponent move would capture two or more stones. | |
1532 | ||
1533 | `xcap2-' | |
1534 | An opponent move would capture at most two stones. | |
1535 | ||
1536 | These can be combined arbitrarily but all must be satisfied for the | |
1537 | pattern to take effect. If contradictory properties are combined, the | |
1538 | pattern will never match. | |
1539 | ||
1540 | 14.0.1 Final Remarks | |
1541 | -------------------- | |
1542 | ||
1543 | * Move values are unsigned 32-bit integers. To avoid overflow in | |
1544 | computations it is highly recommended to keep the values below | |
1545 | 10000000 or so. | |
1546 | ||
1547 | * There is no speed penalty for having lots of patterns in the | |
1548 | database. The average time per move is approximately constant | |
1549 | (slightly dependent on how often stones are captured or become low | |
1550 | on liberties) and the time per game mostly depends on the average | |
1551 | game length. | |
1552 | ||
1553 | * For more complex pattern databases, see | |
1554 | `patterns/mc_montegnu_classic.db' and | |
1555 | `patterns/mc_mogo_classic.db'. | |
1556 | ||
1557 | Nobody really knows how to tune the random playouts to get as strong | |
1558 | engine as possible. Please play with this and report any interesting | |
1559 | findings, especially if you're able to make it substantially stronger | |
1560 | than the `montegnu_classic' patterns. | |
1561 | ||
1562 | \1f | |
1563 | File: gnugo.info, Node: Libboard, Next: SGF, Prev: Monte Carlo Go, Up: Top | |
1564 | ||
1565 | 15 The Board Library | |
1566 | ******************** | |
1567 | ||
1568 | * Menu: | |
1569 | ||
1570 | * Board Data Structures:: Board Data Structures | |
1571 | * The Board Array:: One-dimensional board array | |
1572 | * Incremental Board:: Incremental board data structures | |
1573 | * Some Board Functions:: Explanation of some board functions | |
1574 | ||
1575 | The foundation of the GNU Go engine is a library of very efficient | |
1576 | routines for handling go boards. This board library, called | |
1577 | `libboard', can be used for those programs that only need a basic go | |
1578 | board but no AI capability. One such program is `patterns/joseki.c', | |
1579 | which compiles joseki pattern databases from SGF files. | |
1580 | ||
1581 | If you want to use the board library in your own program, you need | |
1582 | all the .c-files listed under libboard_SOURCES in engine/Makefile.am, | |
1583 | and the files in the directories sgf/ and utils/. Then you should | |
1584 | include engine/board.h in your code. | |
1585 | ||
1586 | The library consists of the following files: | |
1587 | ||
1588 | * `board.h' | |
1589 | ||
1590 | The public interface to the board library. | |
1591 | ||
1592 | * `board.c' | |
1593 | ||
1594 | The basic board code. It uses incremental algorithms for | |
1595 | keeping track of strings and liberties on the go board. | |
1596 | ||
1597 | * `boardlib.c' | |
1598 | ||
1599 | This contains all global variable of the board library. | |
1600 | ||
1601 | * `hash.c' | |
1602 | ||
1603 | Code for hashing go positions. | |
1604 | ||
1605 | * `sgffile.c' | |
1606 | ||
1607 | Implementation of output file in SGF format. | |
1608 | ||
1609 | * `printutils.c' | |
1610 | ||
1611 | Utilities for printing go boards and other things. | |
1612 | ||
1613 | ||
1614 | To use the board library, you must include `liberty.h' just like | |
1615 | when you use the whole engine, but of course you cannot use all the | |
1616 | functions declared in it, i.e. the functions that are part of the | |
1617 | engine, but not part of the board library. You must link your | |
1618 | application with `libboard.a'. | |
1619 | ||
1620 | \1f | |
1621 | File: gnugo.info, Node: Board Data Structures, Next: The Board Array, Up: Libboard | |
1622 | ||
1623 | 15.1 Board Data structures | |
1624 | ========================== | |
1625 | ||
1626 | The basic data structures of the board correspond tightly to the | |
1627 | `board_state' struct described in *Note The Board State::. They are all | |
1628 | stored in global variables for efficiency reasons, the most important | |
1629 | of which are: | |
1630 | ||
1631 | ||
1632 | int board_size; | |
1633 | Intersection board[MAXSIZE]; | |
1634 | int board_ko_pos; | |
1635 | ||
1636 | float komi; | |
1637 | int white_captured; | |
1638 | int black_captured; | |
1639 | ||
1640 | Hash_data hashdata; | |
1641 | ||
1642 | The description of the `Position' struct is applicable to these | |
1643 | variables also, so we won't duplicate it here. All these variables are | |
1644 | globals for performance reasons. Behind these variables, there are a | |
1645 | number of other private data structures. These implement incremental | |
1646 | handling of strings, liberties and other properties (*note Incremental | |
1647 | Board::). The variable `hashdata' contains information about the hash | |
1648 | value for the current position (*note Hashing::). | |
1649 | ||
1650 | These variables should never be manipulated directly, since they are | |
1651 | only the front end for the incremental machinery. They can be read, but | |
1652 | should only be written by using the functions described in the next | |
1653 | section. If you write directly to them, the incremental data structures | |
1654 | will become out of sync with each other, and a crash is the likely | |
1655 | result. | |
1656 | ||
1657 | \1f | |
1658 | File: gnugo.info, Node: The Board Array, Next: Incremental Board, Prev: Board Data Structures, Up: Libboard | |
1659 | ||
1660 | 15.2 The Board Array | |
1661 | ==================== | |
1662 | ||
1663 | GNU Go represents the board in a one-dimensional array called `board'. | |
1664 | For some purposes a two dimensional indexing of the board by parameters | |
1665 | `(i,j)' might be used. | |
1666 | ||
1667 | The `board' array includes out-of-board markers around the board. To | |
1668 | make the relation to the old two-dimensional board representation | |
1669 | clear, this figure shows how the 1D indices correspond to the 2D | |
1670 | indices when MAX_BOARD is 7. | |
1671 | ||
1672 | j -1 0 1 2 3 4 5 6 | |
1673 | i +---------------------------------- | |
1674 | -1| 0 1 2 3 4 5 6 7 | |
1675 | 0| 8 9 10 11 12 13 14 15 | |
1676 | 1| 16 17 18 19 20 21 22 23 | |
1677 | 2| 24 25 26 27 28 29 30 31 | |
1678 | 3| 32 33 34 35 36 37 38 39 | |
1679 | 4| 40 41 42 43 44 45 46 47 | |
1680 | 5| 48 49 50 51 52 53 54 55 | |
1681 | 6| 56 57 58 59 60 61 62 63 | |
1682 | 7| 64 65 66 67 68 69 70 71 72 | |
1683 | ||
1684 | To convert between a 1D index `pos' and a 2D index `(i,j)', the | |
1685 | macros `POS', `I', and `J' are provided, defined as below: | |
1686 | ||
1687 | #define POS(i, j) ((MAX_BOARD + 2) + (i) * (MAX_BOARD + 1) + (j)) | |
1688 | #define I(pos) ((pos) / (MAX_BOARD + 1) - 1) | |
1689 | #define J(pos) ((pos) % (MAX_BOARD + 1) - 1) | |
1690 | ||
1691 | All 1D indices not corresponding to points on the board have the out | |
1692 | of board marker value `GRAY'. Thus if `board_size' and `MAX_BOARD' both | |
1693 | are 7, this looks like | |
1694 | ||
1695 | j -1 0 1 2 3 4 5 6 | |
1696 | i +---------------------------------- | |
1697 | -1| # # # # # # # # | |
1698 | 0| # . . . . . . . | |
1699 | 1| # . . . . . . . | |
1700 | 2| # . . . . . . . | |
1701 | 3| # . . . . . . . | |
1702 | 4| # . . . . . . . | |
1703 | 5| # . . . . . . . | |
1704 | 6| # . . . . . . . | |
1705 | 7| # # # # # # # # # | |
1706 | ||
1707 | The indices marked `#' have value `GRAY'. If `MAX_BOARD' is 7 and | |
1708 | `board_size' is only 5: | |
1709 | ||
1710 | j -1 0 1 2 3 4 5 6 | |
1711 | i +---------------------------------- | |
1712 | -1| # # # # # # # # | |
1713 | 0| # . . . . . # # | |
1714 | 1| # . . . . . # # | |
1715 | 2| # . . . . . # # | |
1716 | 3| # . . . . . # # | |
1717 | 4| # . . . . . # # | |
1718 | 5| # # # # # # # # | |
1719 | 6| # # # # # # # # | |
1720 | 7| # # # # # # # # # | |
1721 | ||
1722 | Navigation on the board is done by the `SOUTH', `WEST', `NORTH', and | |
1723 | `EAST' macros, | |
1724 | ||
1725 | #define NS (MAX_BOARD + 1) | |
1726 | #define WE 1 | |
1727 | #define SOUTH(pos) ((pos) + NS) | |
1728 | #define WEST(pos) ((pos) - 1) | |
1729 | #define NORTH(pos) ((pos) - NS) | |
1730 | #define EAST(pos) ((pos) + 1) | |
1731 | ||
1732 | There are also shorthand macros `SW', `NW', `NE', `SE', `SS', `WW', | |
1733 | `NN', `EE' for two step movements. | |
1734 | ||
1735 | Any movement from a point on the board to an adjacent or diagonal | |
1736 | vertex is guaranteed to produce a valid index into the board array, and | |
1737 | the color found is GRAY if it is not on the board. To do explicit tests | |
1738 | for out of board there are two macros | |
1739 | ||
1740 | #define ON_BOARD(pos) (board[pos] != GRAY) | |
1741 | #define ON_BOARD1(pos) (((unsigned) (pos) < BOARDSIZE) && board[pos] != GRAY) | |
1742 | ||
1743 | where the first one should be used in the algorithms and the second | |
1744 | one is useful for assertion tests. | |
1745 | ||
1746 | The advantage of a one-dimensional board array is that it gives a | |
1747 | significant performance advantage. We need only one variable to | |
1748 | determine a board position, which means that many functions need less | |
1749 | arguments. Also, often one computation is sufficient for 1D-coordinate | |
1750 | where we would need two with two 2D-coordinates: If we, for example, | |
1751 | want to have the coordinate of the upper right of `pos', we can do this | |
1752 | with `NORTH(EAST(pos))' instead of `(i+1, j-1)'. | |
1753 | ||
1754 | *Important*: The 2D coordinate `(-1,-1)', which is used for pass and | |
1755 | sometimes to indicate no point, maps to the 1D coordinate `0', not to | |
1756 | `-1'. Instead of a plain `0', use one of the macros `NO_MOVE' or | |
1757 | `PASS_MOVE'. | |
1758 | ||
1759 | A loop over multiple directions is straightforwardly written: | |
1760 | ||
1761 | for (k = 0; k < 4; k++) { | |
1762 | int d = delta[k]; | |
1763 | do_something(pos + d); | |
1764 | } | |
1765 | ||
1766 | The following constants are useful for loops over the entire board | |
1767 | and allocation of arrays with a 1-1 mapping to the board. | |
1768 | ||
1769 | #define BOARDSIZE ((MAX_BOARD + 2) * (MAX_BOARD + 1) + 1) | |
1770 | #define BOARDMIN (MAX_BOARD + 2) | |
1771 | #define BOARDMAX (MAX_BOARD + 1) * (MAX_BOARD + 1) | |
1772 | ||
1773 | `BOARDSIZE' is the actual size of the 1D board array, `BOARDMIN' is | |
1774 | the first index corresponding to a point on the board, and `BOARDMAX' | |
1775 | is one larger than the last index corresponding to a point on the board. | |
1776 | ||
1777 | Often one wants to traverse the board, carrying out some function at | |
1778 | every vertex. Here are two possible ways of doing this: | |
1779 | ||
1780 | int m, n; | |
1781 | for (m = 0; m < board_size; m++) | |
1782 | for (n = 0; n < board_size; n++) { | |
1783 | do_something(POS(m, n)); | |
1784 | } | |
1785 | ||
1786 | Or: | |
1787 | ||
1788 | int pos; | |
1789 | for (pos = BOARDMIN; pos < BOARDMAX; pos++) { | |
1790 | if (ON_BOARD(pos)) | |
1791 | do_something(pos); | |
1792 | } | |
1793 | ||
1794 | \1f | |
1795 | File: gnugo.info, Node: Incremental Board, Next: Some Board Functions, Prev: The Board Array, Up: Libboard | |
1796 | ||
1797 | 15.3 Incremental Board data structures | |
1798 | ====================================== | |
1799 | ||
1800 | In addition to the global board state, the algorithms in `board.c' | |
1801 | implement a method of incremental updates that keeps track of the | |
1802 | following information for each string: | |
1803 | ||
1804 | * The color of the string. | |
1805 | ||
1806 | * Number of stones in the string. | |
1807 | ||
1808 | * Origin of the string, i.e. a canonical reference point, defined to | |
1809 | be the stone with smallest 1D board coordinate. | |
1810 | ||
1811 | * A list of the stones in the string. | |
1812 | ||
1813 | * Number of liberties. | |
1814 | ||
1815 | * A list of the liberties. If there are too many liberties the list | |
1816 | is truncated. | |
1817 | ||
1818 | * The number of neighbor strings. | |
1819 | ||
1820 | * A list of the neighbor strings. | |
1821 | ||
1822 | The basic data structure is | |
1823 | ||
1824 | struct string_data { | |
1825 | int color; /* Color of string, BLACK or WHITE */ | |
1826 | int size; /* Number of stones in string. */ | |
1827 | int origin; /* Coordinates of "origin", i.e. */ | |
1828 | /* "upper left" stone. */ | |
1829 | int liberties; /* Number of liberties. */ | |
1830 | int libs[MAX_LIBERTIES]; /* Coordinates of liberties. */ | |
1831 | int neighbors; /* Number of neighbor strings */ | |
1832 | int neighborlist[MAXCHAIN]; /* List of neighbor string numbers. */ | |
1833 | int mark; /* General purpose mark. */ | |
1834 | }; | |
1835 | ||
1836 | struct string_data string[MAX_STRINGS]; | |
1837 | ||
1838 | It should be clear that almost all information is stored in the | |
1839 | `string' array. To get a mapping from the board coordinates to the | |
1840 | `string' array we have | |
1841 | ||
1842 | static int string_number[BOARDMAX]; | |
1843 | ||
1844 | which contains indices into the `string' array. This information is only | |
1845 | valid at nonempty vertices, however, so it is necessary to first verify | |
1846 | that `board[pos] != EMPTY'. | |
1847 | ||
1848 | The `string_data' structure does not include an array of the stone | |
1849 | coordinates. This information is stored in a separate array: | |
1850 | ||
1851 | static int next_stone[BOARDMAX]; | |
1852 | ||
1853 | This array implements cyclic linked lists of stones. Each vertex | |
1854 | contains a pointer to another (possibly the same) vertex. Starting at | |
1855 | an arbitrary stone on the board, following these pointers should | |
1856 | traverse the entire string in an arbitrary order before coming back to | |
1857 | the starting point. As for the 'string_number' array, this information | |
1858 | is invalid at empty points on the board. This data structure has the | |
1859 | good properties of requiring fixed space (regardless of the number of | |
1860 | strings) and making it easy to add a new stone or join two strings. | |
1861 | ||
1862 | Additionally the code makes use of some work variables: | |
1863 | ||
1864 | static int ml[BOARDMAX]; | |
1865 | static int liberty_mark; | |
1866 | static int string_mark; | |
1867 | static int next_string; | |
1868 | static int strings_initialized = 0; | |
1869 | ||
1870 | The `ml' array and `liberty_mark' are used to "mark" liberties on | |
1871 | the board, e.g. to avoid counting the same liberty twice. The | |
1872 | convention is that if `ml[pos]' has the same value as `liberty_mark', | |
1873 | then `pos' is marked. To clear all marks it suffices to increase the | |
1874 | value of `liberty_mark', since it is never allowed to decrease. | |
1875 | ||
1876 | The same relation holds between the `mark' field of the `string_data' | |
1877 | structure and `string_mark'. Of course these are used for marking | |
1878 | individual strings. | |
1879 | ||
1880 | `next_string' gives the number of the next available entry in the | |
1881 | `string' array. Then `strings_initialized' is set to one when all data | |
1882 | structures are known to be up to date. Given an arbitrary board | |
1883 | position in the `board' array, this is done by calling | |
1884 | `incremental_board_init()'. It is not necessary to call this function | |
1885 | explicitly since any other function that needs the information does | |
1886 | this if it has not been done. | |
1887 | ||
1888 | The interesting part of the code is the incremental update of the | |
1889 | data structures when a stone is played and subsequently removed. To | |
1890 | understand the strategies involved in adding a stone it is necessary to | |
1891 | first know how undoing a move works. The idea is that as soon as some | |
1892 | piece of information is about to be changed, the old value is pushed | |
1893 | onto a stack which stores the value and its address. The stack is built | |
1894 | from the following structures: | |
1895 | ||
1896 | struct change_stack_entry { | |
1897 | int *address; | |
1898 | int value; | |
1899 | }; | |
1900 | ||
1901 | struct change_stack_entry change_stack[STACK_SIZE]; | |
1902 | int change_stack_index; | |
1903 | ||
1904 | and manipulated with the macros | |
1905 | ||
1906 | BEGIN_CHANGE_RECORD() | |
1907 | PUSH_VALUE(v) | |
1908 | POP_MOVE() | |
1909 | ||
1910 | Calling `BEGIN_CHANGE_RECORD()' stores a null pointer in the address | |
1911 | field to indicate the start of changes for a new move. As mentioned | |
1912 | earlier `PUSH_VALUE()' stores a value and its corresponding address. | |
1913 | Assuming that all changed information has been duly pushed onto the | |
1914 | stack, undoing the move is only a matter of calling `POP_MOVE()', which | |
1915 | simply assigns the values to the addresses in the reverse order until | |
1916 | the null pointer is reached. This description is slightly simplified | |
1917 | because this stack can only store 'int' values and we need to also | |
1918 | store changes to the board. Thus we have two parallel stacks where one | |
1919 | stores `int' values and the other one stores `Intersection' values. | |
1920 | ||
1921 | When a new stone is played on the board, first captured opponent | |
1922 | strings, if any, are removed. In this step we have to push the board | |
1923 | values and the `next_stone' pointers for the removed stones, and update | |
1924 | the liberties and neighbor lists for the neighbors of the removed | |
1925 | strings. We do not have to push all information in the 'string' entries | |
1926 | of the removed strings however. As we do not reuse the entries they | |
1927 | will remain intact until the move is pushed and they are back in use. | |
1928 | ||
1929 | After this we put down the new stone and get three distinct cases: | |
1930 | ||
1931 | 1. The new stone is isolated, i.e. it has no friendly neighbor. | |
1932 | ||
1933 | 2. The new stone has exactly one friendly neighbor. | |
1934 | ||
1935 | 3. The new stone has at least two friendly neighbors. | |
1936 | ||
1937 | The first case is easiest. Then we create a new string by using the | |
1938 | number given by `next_string' and increasing this variable. The string | |
1939 | will have size one, `next_stone' points directly back on itself, the | |
1940 | liberties can be found by looking for empty points in the four | |
1941 | directions, possible neighbor strings are found in the same way, and | |
1942 | those need also to remove one liberty and add one neighbor. | |
1943 | ||
1944 | In the second case we do not create a new string but extend the | |
1945 | neighbor with the new stone. This involves linking the new stone into | |
1946 | the cyclic chain, if needed moving the origin, and updating liberties | |
1947 | and neighbors. Liberty and neighbor information also needs updating for | |
1948 | the neighbors of the new stone. | |
1949 | ||
1950 | In the third case finally, we need to join already existing strings. | |
1951 | In order not to have to store excessive amounts of information, we | |
1952 | create a new string for the new stone and let it assimilate the | |
1953 | neighbor strings. Thus all information about those can simply be left | |
1954 | around in the 'string' array, exactly as for removed strings. Here it | |
1955 | becomes a little more complex to keep track of liberties and neighbors | |
1956 | since those may have been shared by more than one of the joined | |
1957 | strings. Making good use of marks it all becomes rather straightforward | |
1958 | anyway. | |
1959 | ||
1960 | The often used construction | |
1961 | ||
1962 | pos = FIRST_STONE(s); | |
1963 | do { | |
1964 | ... | |
1965 | pos = NEXT_STONE(pos); | |
1966 | } while (!BACK_TO_FIRST_STONE(s, pos)); | |
1967 | ||
1968 | traverses the stones of the string with number `s' exactly once, with | |
1969 | `pos' holding the coordinates. In general `pos' is used as board | |
1970 | coordinate and `s' as an index into the `string' array or sometimes a | |
1971 | pointer to an entry in the `string' array. | |
1972 | ||
1973 | \1f | |
1974 | File: gnugo.info, Node: Some Board Functions, Prev: Incremental Board, Up: Libboard | |
1975 | ||
1976 | 15.4 Some Board Functions | |
1977 | ========================= | |
1978 | ||
1979 | *Reading*, often called *search* in computer game theory, is a | |
1980 | fundamental process in GNU Go. This is the process of generating | |
1981 | hypothetical future boards in order to determine the answer to some | |
1982 | question, for example "can these stones live." Since these are | |
1983 | hypothetical future positions, it is important to be able to undo them, | |
1984 | ultimately returning to the present board. Thus a move stack is | |
1985 | maintained during reading. When a move is tried, by the function | |
1986 | `trymove', or its variant `tryko'. This function pushes the current | |
1987 | board on the stack and plays a move. The stack pointer `stackp', which | |
1988 | keeps track of the position, is incremented. The function `popgo()' | |
1989 | pops the move stack, decrementing `stackp' and undoing the last move | |
1990 | made. | |
1991 | ||
1992 | Every successful `trymove()' must be matched with a `popgo()'. Thus | |
1993 | the correct way of using this function is: | |
1994 | ||
1995 | ||
1996 | if (trymove(pos, color, ... )) { | |
1997 | ... [potentially lots of code here] | |
1998 | popgo(); | |
1999 | } | |
2000 | ||
2001 | In case the move is a ko capture, the legality of the capture is | |
2002 | subject to the komaster scheme (*note Ko::). | |
2003 | ||
2004 | * `int trymove(int pos, int color, const char *message)' | |
2005 | ||
2006 | Returns true if `(pos)' is a legal move for `color'. In that | |
2007 | case, it pushes the board on the stack and makes the move, | |
2008 | incrementing `stackp'. If the reading code is recording | |
2009 | reading variations (as with `--decide-string' or with `-o'), | |
2010 | the string `*message' will be inserted in the SGF file as a | |
2011 | comment. The comment will also refer to the string at `str' | |
2012 | if this is not `0'. The value of `str' can be NO_MOVE if it | |
2013 | is not needed but otherwise the location of `str' is included | |
2014 | in the comment. | |
2015 | ||
2016 | * `int tryko(int pos, int color, const char *message)' | |
2017 | ||
2018 | `tryko()' pushes the position onto the stack, and makes a move | |
2019 | `pos' of `color'. The move is allowed even if it is an | |
2020 | illegal ko capture. It is to be imagined that `color' has | |
2021 | made an intervening ko threat which was answered and now the | |
2022 | continuation is to be explored. Return 1 if the move is legal | |
2023 | with the above caveat. Returns zero if it is not legal | |
2024 | because of suicide. | |
2025 | ||
2026 | * `void popgo()' | |
2027 | ||
2028 | Pops the move stack. This function must (eventually) be | |
2029 | called after a succesful `trymove' or `tryko' to restore the | |
2030 | board position. It undoes all the changes done by the call to | |
2031 | `trymove/tryko' and leaves the board in the same state as it | |
2032 | was before the call. | |
2033 | ||
2034 | *NOTE*: If `trymove/tryko' returns `0', i.e. the tried move | |
2035 | was not legal, you must *not* call `popgo'. | |
2036 | ||
2037 | * `int komaster_trymove(int pos, int color, const char *message, int | |
2038 | str, int *is_conditional_ko, int consider_conditional_ko)' | |
2039 | ||
2040 | Variation of `trymove'/`tryko' where ko captures (both | |
2041 | conditional and unconditional) must follow a komaster scheme | |
2042 | (*note Ko::). | |
2043 | ||
2044 | ||
2045 | As you see, `trymove()' plays a move which can be easily retracted | |
2046 | (with `popgo()') and it is call thousands of times per actual game move | |
2047 | as GNU Go analyzes the board position. By contrast the function | |
2048 | `play_move()' plays a move which is intended to be permanent, though it | |
2049 | is still possible to undo it if, for example, the opponent retracts a | |
2050 | move. | |
2051 | ||
2052 | * `void play_move(int pos, int color)' | |
2053 | ||
2054 | Play a move. If you want to test for legality you should | |
2055 | first call `is_legal()'. This function strictly follows the | |
2056 | algorithm: | |
2057 | 1. Place a stone of given color on the board. | |
2058 | ||
2059 | 2. If there are any adjacent opponent strings without | |
2060 | liberties, remove them and increase the prisoner count. | |
2061 | ||
2062 | 3. If the newly placed stone is part of a string without | |
2063 | liberties, remove it and increase the prisoner count. | |
2064 | In spite of the name "permanent move", this move can | |
2065 | (usually) be unplayed by `undo_move()', but it is | |
2066 | significantly more costly than unplaying a temporary move. | |
2067 | There are limitations on the available move history, so under | |
2068 | certain circumstances the move may not be possible to unplay | |
2069 | at a later time. | |
2070 | ||
2071 | * `int undo_move(int n)' | |
2072 | ||
2073 | Undo `n' permanent moves. Returns 1 if successful and 0 if it | |
2074 | fails. If `n' moves cannot be undone, no move is undone. | |
2075 | ||
2076 | Other board functions are documented in *Note Board Utilities::. | |
2077 | ||
2078 | \1f | |
2079 | File: gnugo.info, Node: SGF, Next: DFA, Prev: Libboard, Up: Top | |
2080 | ||
2081 | 16 Handling SGF trees in memory | |
2082 | ******************************* | |
2083 | ||
2084 | "SGF" - Smart Game Format - is a file format which is used for storing | |
2085 | game records for a number of different games, among them chess and go. | |
2086 | The format is a framework with special adaptions to each game. This is | |
2087 | not a description of the file format standard. Too see the exact | |
2088 | definition of the file format, see `http://www.red-bean.com/sgf/'. | |
2089 | ||
2090 | GNU Go contains a library to handle go game records in the SGF | |
2091 | format in memory and to read and write SGF files. This library - | |
2092 | `libsgf.a' - is in the `sgf' subdirectory. To use the SGF routines, | |
2093 | include the file `sgftree.h'. | |
2094 | ||
2095 | Each game record is stored as a tree of "nodes", where each node | |
2096 | represents a state of the game, often after some move is made. Each node | |
2097 | contains zero or more "properties", which gives meaning to the node. | |
2098 | There can also be a number of "child nodes" which are different | |
2099 | variations of the game tree. The first child node is the main variation. | |
2100 | ||
2101 | Here is the definition of `SGFNode', and `SGFProperty', the data | |
2102 | structures which are used to encode the game tree. | |
2103 | ||
2104 | ||
2105 | typedef struct SGFProperty_t { | |
2106 | struct SGFProperty_t *next; | |
2107 | short name; | |
2108 | char value[1]; | |
2109 | } SGFProperty; | |
2110 | ||
2111 | typedef struct SGFNode_t { | |
2112 | SGFProperty *props; | |
2113 | struct SGFNode_t *parent; | |
2114 | struct SGFNode_t *child; | |
2115 | struct SGFNode_t *next; | |
2116 | } SGFNode; | |
2117 | ||
2118 | Each node of the SGF tree is stored in an `SGFNode' struct. It has a | |
2119 | pointer to a linked list of properties (see below) called `props'. It | |
2120 | also has a pointer to a linked list of children, where each child is a | |
2121 | variation which starts at this node. The variations are linked through | |
2122 | the `next' pointer and each variation continues through the `child' | |
2123 | pointer. Each and every node also has a pointer to its parent node (the | |
2124 | `parent' field), except the top node whose parent pointer is `NULL'. | |
2125 | ||
2126 | An SGF property is encoded in the `SGFPoperty' struct. It is linked | |
2127 | in a list through the `next' field. A property has a `name' which is | |
2128 | encoded in a short int. Symbolic names of properties can be found in | |
2129 | `sgf_properties.h'. | |
2130 | ||
2131 | Some properties also have a value, which could be an integer, a | |
2132 | floating point value, a character or a string. These values can be | |
2133 | accessed or set through special functions. | |
2134 | ||
2135 | 16.1 The SGFTree datatype | |
2136 | ========================= | |
2137 | ||
2138 | Sometimes we just want to record an ongoing game or something similarly | |
2139 | simple and not do any sofisticated tree manipulation. In that case we | |
2140 | can use the simplified interface provided by `SGFTree' below. | |
2141 | ||
2142 | ||
2143 | typedef struct SGFTree_t { | |
2144 | SGFNode *root; | |
2145 | SGFNode *lastnode; | |
2146 | } SGFTree; | |
2147 | ||
2148 | An `SGFTree' contains a pointer to the root node of an SGF tree and | |
2149 | a pointer to the node that we last accessed. Most of the time this will | |
2150 | be the last move of an ongoing game. | |
2151 | ||
2152 | Most of the functions which manipulate an `SGFTree' work exactly | |
2153 | like their `SGFNode' counterparts, except that they work on the current | |
2154 | node of the tree. | |
2155 | ||
2156 | All the functions below that take arguments `tree' and `node' will | |
2157 | work on: | |
2158 | ||
2159 | 1. `node' if non-`NULL' | |
2160 | ||
2161 | 2. `tree->lastnode' if non-`NULL' | |
2162 | ||
2163 | 3. The current end of the game tree. | |
2164 | in that order. | |
2165 | ||
2166 | \1f | |
2167 | File: gnugo.info, Node: API, Next: GTP, Prev: Utility Functions, Up: Top | |
2168 | ||
2169 | 17 Application Programmers Interface to GNU Go | |
2170 | ********************************************** | |
2171 | ||
2172 | If you want to write your own interface to GNU Go, or if you want to | |
2173 | create a go application using the GNU Go engine, this chapter is of | |
2174 | interest to you. | |
2175 | ||
2176 | First an overview: GNU Go consists of two parts: the GNU Go engine | |
2177 | and a program (user interface) which uses this engine. These are linked | |
2178 | together into one binary. The current program implements the following | |
2179 | user modes: | |
2180 | ||
2181 | * An interactive board playable on ASCII terminals | |
2182 | ||
2183 | * solo play - GNU Go plays against itself | |
2184 | ||
2185 | * replay - a mode which lets the user investigate moves in an | |
2186 | existing SGF file. | |
2187 | ||
2188 | * GMP - Go Modem Protocol, a protocol for automatic play between two | |
2189 | computers. | |
2190 | ||
2191 | * GTP - Go Text Protocol, a more general go protocol, *note GTP::. | |
2192 | ||
2193 | The GNU Go engine can be used in other applications. For example, | |
2194 | supplied with GNU Go is another program using the engine, called | |
2195 | `debugboard', in the directory `interface/debugboard/'. The program | |
2196 | debugboard lets the user load SGF files and can then interactively look | |
2197 | at different properties of the position such as group status and eye | |
2198 | status. | |
2199 | ||
2200 | The purpose of this Chapter is to show how to interface your own | |
2201 | program such as `debugboard' with the GNU Go engine. | |
2202 | ||
2203 | Figure 1 describes the structure of a program using the GNU Go | |
2204 | engine. | |
2205 | ||
2206 | +-----------------------------------+ | |
2207 | | | | |
2208 | | Go application | | |
2209 | | | | |
2210 | +-----+----------+------+ | | |
2211 | | | | | | | |
2212 | | | Game | | | | |
2213 | | | handling | | | | |
2214 | | | | | | | |
2215 | | +----+-----+ | | | |
2216 | | SGF | Move | | | |
2217 | | handling | generation | | | |
2218 | | | | | | |
2219 | +----------+------------+-----------+ | |
2220 | | | | |
2221 | | Board handling | | |
2222 | | | | |
2223 | +-----------------------------------+ | |
2224 | ||
2225 | Figure 1: The structure of a program using the GNU Go engine | |
2226 | ||
2227 | The foundation is a library called `libboard.a' which provides | |
2228 | efficient handling of a go board with rule checks for moves, with | |
2229 | incremental handling of connected strings of stones and with methods to | |
2230 | efficiently hash go positions. | |
2231 | ||
2232 | On top of this, there is a library which helps the application use | |
2233 | Smart Game Format (SGF) files, with complete handling of game trees in | |
2234 | memory and in files. This library is called `libsgf.a' | |
2235 | ||
2236 | The main part of the code within GNU Go is the move generation | |
2237 | library which given a position generates a move. This part of the | |
2238 | engine can also be used to manipulate a go position, add or remove | |
2239 | stones, do tactical and strategic reading and to query the engine for | |
2240 | legal moves. These functions are collected into `libengine.a'. | |
2241 | ||
2242 | The game handling code helps the application programmer keep tracks | |
2243 | of the moves in a game. Games can be saved to SGF files and then later | |
2244 | be read back again. These are also within `libengine.a'. | |
2245 | ||
2246 | The responsibility of the application is to provide the user with a | |
2247 | user interface, graphical or not, and let the user interact with the | |
2248 | engine. | |
2249 | ||
2250 | * Menu: | |
2251 | ||
2252 | * Getting Started:: How to use the engine in your program | |
2253 | * Basic Data Structures:: Basic Data Structures in the Engine | |
2254 | * The Board State:: The board_state `struct' | |
2255 | * Positional Functions:: Functions which manipulate a Position | |
2256 | ||
2257 | \1f | |
2258 | File: gnugo.info, Node: Getting Started, Next: Basic Data Structures, Up: API | |
2259 | ||
2260 | 17.1 How to use the engine in your own program: getting started | |
2261 | =============================================================== | |
2262 | ||
2263 | To use the GNU Go engine in your own program you must include the file | |
2264 | `gnugo.h'. This file describes the whole public API. There is another | |
2265 | file, `liberty.h', which describes the internal interface within the | |
2266 | engine. If you want to make a new module within the engine, e.g. for | |
2267 | suggesting moves you will have to include this file also. In this | |
2268 | section we will only describe the public interface. | |
2269 | ||
2270 | Before you do anything else, you have to call the function | |
2271 | `init_gnugo()'. This function initializes everything within the engine. | |
2272 | It takes one parameter: the number of megabytes the engine can use for | |
2273 | the internal hash table. In addition to this the engine will use a few | |
2274 | megabytes for other purposes such as data describing groups (liberties, | |
2275 | life status, etc), eyes and so on. | |
2276 | ||
2277 | \1f | |
2278 | File: gnugo.info, Node: Basic Data Structures, Next: The Board State, Prev: Getting Started, Up: API | |
2279 | ||
2280 | 17.2 Basic Data Structures in the Engine | |
2281 | ======================================== | |
2282 | ||
2283 | There are some basic definitions in gnugo.h which are used everywhere. | |
2284 | The most important of these are the numeric declarations of colors. | |
2285 | Each intersection on the board is represented by one of these: | |
2286 | ||
2287 | ||
2288 | color value | |
2289 | EMPTY 0 | |
2290 | WHITE 1 | |
2291 | BLACK 2 | |
2292 | ||
2293 | There is a macro, `OTHER_COLOR(color)' which can be used to get the | |
2294 | other color than the parameter. This macro can only be used on `WHITE' | |
2295 | or `BLACK', but not on `EMPTY'. | |
2296 | ||
2297 | GNU Go uses two different representations of the board, for most | |
2298 | purposes a one-dimensional one, but for a few purposes a two | |
2299 | dimensional one (*note Libboard::). The one-dimensional board was | |
2300 | introduced before GNU Go 3.2, while the two-dimensional board dates | |
2301 | back to the ancestral program written by Man Lung Li before 1995. The | |
2302 | API still uses the two-dimensional board, so the API functions have not | |
2303 | changed much since GNU Go 3.0. | |
2304 | ||
2305 | \1f | |
2306 | File: gnugo.info, Node: The Board State, Next: Positional Functions, Prev: Basic Data Structures, Up: API | |
2307 | ||
2308 | 17.3 The board_state struct | |
2309 | =========================== | |
2310 | ||
2311 | A basic data structure in the engine is the `board_state' struct. This | |
2312 | structure is internal to the engine and is defined in `liberty.h'. | |
2313 | ||
2314 | ||
2315 | typedef unsigned char Intersection; | |
2316 | ||
2317 | struct board_state { | |
2318 | int board_size; | |
2319 | ||
2320 | Intersection board[BOARDSIZE]; | |
2321 | int board_ko_pos; | |
2322 | int black_captured; | |
2323 | int white_captured; | |
2324 | ||
2325 | Intersection initial_board[BOARDSIZE]; | |
2326 | int initial_board_ko_pos; | |
2327 | int initial_white_captured; | |
2328 | int initial_black_captured; | |
2329 | int move_history_color[MAX_MOVE_HISTORY]; | |
2330 | int move_history_pos[MAX_MOVE_HISTORY]; | |
2331 | int move_history_pointer; | |
2332 | ||
2333 | float komi; | |
2334 | int move_number; | |
2335 | }; | |
2336 | ||
2337 | Here `Intersection' stores `EMPTY', `WHITE' or `BLACK'. It is | |
2338 | currently defined as an `unsigned char' to make it reasonably efficient | |
2339 | in both storage and access time. The board state contains an array of | |
2340 | `Intersection''s representing the board. The move history is contained | |
2341 | in the struct. Also contained in the struct is the location of a ko | |
2342 | (`EMPTY') if the last move was not a ko capture, the komi, the number | |
2343 | of captures, and corresponding data for the initial position at the | |
2344 | beginning of the move history. | |
2345 | ||
2346 | \1f | |
2347 | File: gnugo.info, Node: Positional Functions, Prev: The Board State, Up: API | |
2348 | ||
2349 | 17.4 Functions which manipulate a Position | |
2350 | ========================================== | |
2351 | ||
2352 | All the functions in the engine that manipulate Positions have names | |
2353 | prefixed by `gnugo_'. These functions still use the two-dimensional | |
2354 | representation of the board (*note The Board Array::). Here is a | |
2355 | complete list, as prototyped in `gnugo.h': | |
2356 | ||
2357 | * `void init_gnugo(float memory)' | |
2358 | ||
2359 | Initialize the gnugo engine. This needs to be called once | |
2360 | only. | |
2361 | ||
2362 | * `void gnugo_clear_board(int boardsize)' | |
2363 | ||
2364 | Clear the board. | |
2365 | ||
2366 | * `void gnugo_set_komi(float new_komi)' | |
2367 | ||
2368 | Set the komi. | |
2369 | ||
2370 | * `void gnugo_add_stone(int i, int j, int color)' | |
2371 | ||
2372 | Place a stone on the board | |
2373 | ||
2374 | * `void gnugo_remove_stone(int i, int j)' | |
2375 | ||
2376 | Remove a stone from the board | |
2377 | ||
2378 | * `int gnugo_is_pass(int i, int j)' | |
2379 | ||
2380 | Return true if (i,j) is PASS_MOVE | |
2381 | ||
2382 | * `void gnugo_play_move(int i, int j, int color)' | |
2383 | ||
2384 | Play a move and start the clock | |
2385 | ||
2386 | * `int gnugo_undo_move(int n)' | |
2387 | ||
2388 | Undo n permanent moves. Returns 1 if successful and 0 if it | |
2389 | fails. If n moves cannot be undone, no move is undone. | |
2390 | ||
2391 | * `int gnugo_play_sgfnode(SGFNode *node, int to_move)' | |
2392 | ||
2393 | Perform the moves and place the stones from the SGF node on | |
2394 | the board. Return the color of the player whose turn it is to | |
2395 | move. | |
2396 | ||
2397 | * `int gnugo_play_sgftree(SGFNode *root, int *until, SGFNode | |
2398 | **curnode)' | |
2399 | ||
2400 | Play the moves in ROOT UNTIL movenumber is reached. Return | |
2401 | the color of the player whose turn it is to move. | |
2402 | ||
2403 | * `int gnugo_is_legal(int i, int j, int color)' | |
2404 | ||
2405 | Interface to `is_legal()'. | |
2406 | ||
2407 | * `int gnugo_is_suicide(int i, int j, int color)' | |
2408 | ||
2409 | Interface to `is_suicide()'. | |
2410 | ||
2411 | * `int gnugo_placehand(int handicap)' | |
2412 | ||
2413 | Interface to placehand. Sets up handicap pieces and returns | |
2414 | the number of placed handicap stones. | |
2415 | ||
2416 | * `void gnugo_recordboard(SGFNode *root)' | |
2417 | ||
2418 | Interface to `sgffile_recordboard()' | |
2419 | ||
2420 | * `int gnugo_sethand(int handicap, SGFNode *node)' | |
2421 | ||
2422 | Interface to placehand. Sets up handicap stones and returns | |
2423 | the number of placed handicap stones, updating the sgf file | |
2424 | ||
2425 | * `float gnugo_genmove(int *i, int *j, int color, int *resign)' | |
2426 | ||
2427 | Interface to `genmove()'. | |
2428 | ||
2429 | * `int gnugo_attack(int m, int n, int *i, int *j)' | |
2430 | ||
2431 | Interface to `attack()'. | |
2432 | ||
2433 | * `int gnugo_find_defense(int m, int n, int *i, int *j)' | |
2434 | ||
2435 | Interface to `find_defense()'. | |
2436 | ||
2437 | * `void gnugo_who_wins(int color, FILE *outfile)' | |
2438 | ||
2439 | Interface to `who_wins()'. | |
2440 | ||
2441 | * `float gnugo_estimate_score(float *upper, float *lower)' | |
2442 | ||
2443 | Put upper and lower score estimates into `*upper', `*lower' | |
2444 | and return the average. A positive score favors white. In | |
2445 | computing the upper bound, `CRITICAL' dragons are awarded to | |
2446 | white; in computing the lower bound, they are awarded to | |
2447 | black. | |
2448 | ||
2449 | * `void gnugo_examine_position(int color, int how_much)' | |
2450 | ||
2451 | Interface to `examine_position'. | |
2452 | ||
2453 | * `int gnugo_get_komi()' | |
2454 | ||
2455 | Report the komi. | |
2456 | ||
2457 | * `void gnugo_get_board(int b[MAX_BOARD][MAX_BOARD])' | |
2458 | ||
2459 | Place the board into the `b' array. | |
2460 | ||
2461 | * `int gnugo_get_boardsize()' | |
2462 | ||
2463 | Report the board size. | |
2464 | ||
2465 | * `int gnugo_get_move_number()' | |
2466 | ||
2467 | Report the move number. | |
2468 | ||
2469 | 17.5 Game handling | |
2470 | ================== | |
2471 | ||
2472 | The functions (in *note Positional Functions::) are all that are needed | |
2473 | to create a fully functional go program. But to make the life easier | |
2474 | for the programmer, there is a small set of functions specially | |
2475 | designed for handling ongoing games. | |
2476 | ||
2477 | The data structure describing an ongoing game is the `Gameinfo'. It | |
2478 | is defined as follows: | |
2479 | ||
2480 | ||
2481 | typedef struct { | |
2482 | int handicap; | |
2483 | ||
2484 | int to_move; /* whose move it currently is */ | |
2485 | SGFTree game_record; /* Game record in sgf format. */ | |
2486 | ||
2487 | int computer_player; /* BLACK, WHITE, or EMPTY (used as BOTH) */ | |
2488 | ||
2489 | char outfilename[128]; /* Trickle file */ | |
2490 | FILE *outfile; | |
2491 | } Gameinfo; | |
2492 | ||
2493 | The meaning of `handicap' should be obvious. `to_move' is the color | |
2494 | of the side whose turn it is to move. | |
2495 | ||
2496 | The SGF tree `game_record' is used to store all the moves in the | |
2497 | entire game, including a header node which contains, among other | |
2498 | things, komi and handicap. | |
2499 | ||
2500 | If one or both of the opponents is the computer, the field | |
2501 | `computer_player' is used. Otherwise it can be ignored. | |
2502 | ||
2503 | GNU Go can use a trickle file to continuously save all the moves of | |
2504 | an ongoing game. This file can also contain information about internal | |
2505 | state of the engine such as move reasons for various locations or move | |
2506 | valuations. The name of this file should be stored in `outfilename' and | |
2507 | the file pointer to the open file is stored in `outfile'. If no trickle | |
2508 | file is used, `outfilename[0]' will contain a null character and | |
2509 | `outfile' will be set to `NULL'. | |
2510 | ||
2511 | 17.5.1 Functions which manipulate a Gameinfo | |
2512 | -------------------------------------------- | |
2513 | ||
2514 | All the functions in the engine that manipulate Gameinfos have names | |
2515 | prefixed by `gameinfo_'. Here is a complete list, as prototyped in | |
2516 | `gnugo.h': | |
2517 | ||
2518 | * `void gameinfo_clear(Gameinfo *ginfo, int boardsize, float komi)' | |
2519 | ||
2520 | Initialize the `Gameinfo' structure. | |
2521 | ||
2522 | * `void gameinfo_print(Gameinfo *ginfo)' | |
2523 | ||
2524 | Print a gameinfo. | |
2525 | ||
2526 | * `void gameinfo_load_sgfheader(Gameinfo *gameinfo, SGFNode *head)' | |
2527 | ||
2528 | Reads header info from sgf structure and sets the appropriate | |
2529 | variables. | |
2530 | ||
2531 | * `void gameinfo_play_move(Gameinfo *ginfo, int i, int j, int color)' | |
2532 | ||
2533 | Make a move in the game. Return 1 if the move was legal. In | |
2534 | that case the move is actually done. Otherwise return 0. | |
2535 | ||
2536 | * `int gameinfo_play_sgftree_rot(Gameinfo *gameinfo, SGFNode *head, | |
2537 | const char *untilstr, int orientation)' | |
2538 | ||
2539 | Play the moves in an SGF tree. Walk the main variation, | |
2540 | actioning the properties into the playing board. Returns the | |
2541 | color of the next move to be made. Head is an sgf tree. | |
2542 | Untilstr is an optional string of the form either 'L12' or | |
2543 | '120' which tells it to stop playing at that move or move | |
2544 | number. When debugging, this is the location of the move | |
2545 | being examined. | |
2546 | ||
2547 | * `int gameinfo_play_sgftree(Gameinfo *gameinfo, SGFNode *head, | |
2548 | const char *untilstr)' | |
2549 | ||
2550 | Same as previous function, using standard orientation. | |
2551 | ||
2552 | \1f | |
2553 | File: gnugo.info, Node: Utility Functions, Next: API, Prev: DFA, Up: Top | |
2554 | ||
2555 | 18 Utility Functions | |
2556 | ******************** | |
2557 | ||
2558 | In this Chapter, we document some of the utilities which may be called | |
2559 | from the GNU Go engine. | |
2560 | ||
2561 | * Menu: | |
2562 | ||
2563 | * General Utilities:: Utilities from `engine/utils.c' | |
2564 | * Print Utilities:: Utilities from `engine/printutils.c' | |
2565 | * Board Utilities:: Utilities from `engine/board.c' | |
2566 | * Influence Utilities:: Utilities from `engine/influence.c' | |
2567 | ||
2568 | \1f | |
2569 | File: gnugo.info, Node: General Utilities, Next: Print Utilities, Up: Utility Functions | |
2570 | ||
2571 | 18.1 General Utilities | |
2572 | ====================== | |
2573 | ||
2574 | Utility functions from `engine/utils.c'. Many of these functions | |
2575 | underlie autohelper functions (*note Autohelper Functions::). | |
2576 | ||
2577 | * `void change_dragon_status(int dr, int status)' | |
2578 | ||
2579 | Change the status of all the stones in the dragon at `dr'. | |
2580 | ||
2581 | * `int defend_against(int move, int color, int apos)' | |
2582 | ||
2583 | Check whether a move at `move' stops the enemy from playing | |
2584 | at (apos). | |
2585 | ||
2586 | * `int cut_possible(int pos, int color)' | |
2587 | ||
2588 | Returns true if `color' can cut at `pos', or if connection | |
2589 | through `pos' is inhibited. This information is collected by | |
2590 | `find_cuts()', using the B patterns in the connections | |
2591 | database. | |
2592 | ||
2593 | * `int does_attack(int move, int str)' | |
2594 | ||
2595 | returns true if the move at `move' attacks `str'. This means | |
2596 | that it captures the string, and that `str' is not already | |
2597 | dead. | |
2598 | ||
2599 | * `int does_defend(int move, int str)' | |
2600 | ||
2601 | `does_defend(move, str)' returns true if the move at `move' | |
2602 | defends `str'. This means that it defends the string, and that | |
2603 | `str' can be captured if no defense is made. | |
2604 | ||
2605 | * `int somewhere(int color, int last_move, ...)' | |
2606 | ||
2607 | Example: `somewhere(WHITE, 2, apos, bpos, cpos)'. Returns | |
2608 | true if one of the vertices listed satisfies | |
2609 | `board[pos]==color'. Here num_moves is the number of moves | |
2610 | minus one. If the check is true the dragon is not allowed to | |
2611 | be dead. This check is only valid if `stackp==0'. | |
2612 | ||
2613 | * `int visible_along_edge(int color, int apos, int bpos)' | |
2614 | ||
2615 | Search along the edge for the first visible stone. Start at | |
2616 | apos and move in the direction of bpos. Return 1 if the first | |
2617 | visible stone is of the given color. It is required that apos | |
2618 | and bpos are at the same distance from the edge. | |
2619 | ||
2620 | * `int test_symmetry_after_move(int move, int color, int strict)' | |
2621 | ||
2622 | Is the board symmetric (or rather antisymmetric) with respect | |
2623 | to mirroring in tengen after a specific move has been played? | |
2624 | If the move is PASS_MOVE, check the current board. If strict | |
2625 | is set we require that each stone is matched by a stone of | |
2626 | the opposite color at the mirrored vertex. Otherwise we only | |
2627 | require that each stone is matched by a stone of either color. | |
2628 | ||
2629 | * `int play_break_through_n(int color, int num_moves, ...)' | |
2630 | ||
2631 | The function `play_break_through_n()' plays a sequence of | |
2632 | moves, alternating between the players and starting with | |
2633 | color. After having played through the sequence, the three | |
2634 | last coordinate pairs gives a position to be analyzed by | |
2635 | `break_through()', to see whether either color has managed to | |
2636 | enclose some stones and/or connected his own stones. If any | |
2637 | of the three last positions is empty, it's assumed that the | |
2638 | enclosure has failed, as well as the attempt to connect. If | |
2639 | one or more of the moves to play turns out to be illegal for | |
2640 | some reason, the rest of the sequence is played anyway, and | |
2641 | `break_through()' is called as if nothing special happened. | |
2642 | Like `break_through()', this function returns 1 if the | |
2643 | attempt to break through was succesful and 2 if it only | |
2644 | managed to cut through. | |
2645 | ||
2646 | * `int play_attack_defend_n(int color, int do_attack, int num_moves, | |
2647 | ...)' | |
2648 | ||
2649 | * `int play_attack_defend2_n(int color, int do_attack, int | |
2650 | num_moves, ...)' | |
2651 | ||
2652 | The function `play_attack_defend_n()' plays a sequence of | |
2653 | moves, alternating between the players and starting with | |
2654 | `color'. After having played through the sequence, the last | |
2655 | coordinate pair gives a target to attack or defend, depending | |
2656 | on the value of do_attack. If there is no stone present to | |
2657 | attack or defend, it is assumed that it has already been | |
2658 | captured. If one or more of the moves to play turns out to be | |
2659 | illegal for some reason, the rest of the sequence is played | |
2660 | anyway, and attack/defense is tested as if nothing special | |
2661 | happened. Conversely, `play_attack_defend2_n()' plays a | |
2662 | sequence of moves, alternating between the players and | |
2663 | starting with `color'. After having played through the | |
2664 | sequence, the two last coordinate pairs give two targets to | |
2665 | simultaneously attack or defend, depending on the value of | |
2666 | do_attack. If there is no stone present to attack or defend, | |
2667 | it is assumed that it has already been captured. If one or | |
2668 | more of the moves to play turns out to be illegal for some | |
2669 | reason, the rest of the sequence is played anyway, and | |
2670 | attack/defense is tested as if nothing special happened. A | |
2671 | typical use of these functions is to set up a ladder in an | |
2672 | autohelper and see whether it works or not. | |
2673 | ||
2674 | * `int play_connect_n(int color, int do_connect, int num_moves, ...)' | |
2675 | ||
2676 | Plays a sequence of moves, alternating between the players | |
2677 | and starting with `color'. After having played through the | |
2678 | sequence, the two last coordinates give two targets that | |
2679 | should be connected or disconnected, depending on the value | |
2680 | of do_connect. If there is no stone present to connect or | |
2681 | disconnect, it is assumed that the connection has failed. If | |
2682 | one or more of the moves to play turns out to be illegal for | |
2683 | some reason, the rest of the sequence is played anyway, and | |
2684 | connection/disconnection is tested as if nothing special | |
2685 | happened. Ultimately the connection is decided by the | |
2686 | functions `string_connect' and `disconnect' (*note Connection | |
2687 | Reading::). | |
2688 | ||
2689 | * `void set_depth_values(int level)' | |
2690 | ||
2691 | It is assumed in reading a ladder if `stackp >= depth' that | |
2692 | as soon as a bounding stone is in atari, the string is safe. | |
2693 | Similar uses are made of the other depth parameters such as | |
2694 | `backfill_depth' and so forth. In short, simplifying | |
2695 | assumptions are made when `stackp' is large. Unfortunately | |
2696 | any such scheme invites the "horizon effect," in which a | |
2697 | stalling move is perceived as a win, by pushing the | |
2698 | refutation past the "horizon"--the value of `stackp' in which | |
2699 | the reading assumptions are relaxed. To avoid the depth it is | |
2700 | sometimes necessary to increase the depth parameters. This | |
2701 | function can be used to set the various reading depth | |
2702 | parameters. If `mandated_depth_value' is not -1 that value is | |
2703 | used; otherwise the depth values are set as a function of | |
2704 | level. The parameter `mandated_depth_value' can be set at the | |
2705 | command line to force a particular value of depth; normally | |
2706 | it is -1. | |
2707 | ||
2708 | * `void modify_depth_values(int n)' | |
2709 | ||
2710 | Modify the various tactical reading depth parameters. This is | |
2711 | typically used to avoid horizon effects. By temporarily | |
2712 | increasing the depth values when trying some move, one can | |
2713 | avoid that an irrelevant move seems effective just because | |
2714 | the reading hits a depth limit earlier than it did when | |
2715 | reading only on relevant moves. | |
2716 | ||
2717 | * `void increase_depth_values(void)' | |
2718 | ||
2719 | `modify_depth_values(1)'. | |
2720 | ||
2721 | * `void decrease_depth_values(void)' | |
2722 | ||
2723 | `modify_depth_values(-1)'. | |
2724 | ||
2725 | * `void restore_depth_values()' | |
2726 | ||
2727 | Sets `depth' and so forth to their saved values. | |
2728 | ||
2729 | * `void set_temporary_depth_values(int d, int b, int b2, int bc, int | |
2730 | ss, int br, int f, int k)' | |
2731 | ||
2732 | Explicitly set the depth values. This function is currently | |
2733 | never called. | |
2734 | ||
2735 | * `int confirm_safety(int move, int color, int *defense_point, char | |
2736 | safe_stones[BOARDMAX])' | |
2737 | ||
2738 | Check that the move at color doesn't involve any kind of | |
2739 | blunder, regardless of size. | |
2740 | ||
2741 | * `float blunder_size(int move, int color, int *defense_point, char | |
2742 | safe_stones[BOARDMAX])' | |
2743 | ||
2744 | This function will detect some blunders. If the move reduces | |
2745 | the number of liberties of an adjacent friendly string, there | |
2746 | is a danger that the move could backfire, so the function | |
2747 | checks that no friendly worm which was formerly not | |
2748 | attackable becomes attackable, and it checks that no opposing | |
2749 | worm which was not defendable becomes defendable. It returns | |
2750 | the estimated size of the blunder, or 0.0 if nothing bad has | |
2751 | happened. The array `safe_stones[]' contains the stones that | |
2752 | are supposedly safe after `move'. It may be `NULL'. For use | |
2753 | when called from `fill_liberty()', this function may | |
2754 | optionally return a point of defense, which, if taken, will | |
2755 | presumably make the move at `move' safe on a subsequent turn. | |
2756 | ||
2757 | * `int double_atari(int move, int color, float *value, char | |
2758 | safe_stones[BOARDMAX])' | |
2759 | ||
2760 | Returns true if a move by (color) fits the following shape: | |
2761 | X* (O=color) | |
2762 | OX | |
2763 | capturing one of the two `X' strings. The name is a slight | |
2764 | misnomer since this includes attacks which are not | |
2765 | necessarily double ataris, though the common double atari is | |
2766 | the most important special case. If `safe_stones != NULL', | |
2767 | then only attacks on stones marked as safe are tried. The | |
2768 | value of the double atari attack is returned in value (unless | |
2769 | value is `NULL'), and the attacked stones are marked unsafe. | |
2770 | ||
2771 | * `void unconditional_life(int unconditional_territory[BOARDMAX], | |
2772 | int color)' | |
2773 | ||
2774 | Find those worms of the given color that can never be | |
2775 | captured, even if the opponent is allowed an arbitrary number | |
2776 | of consecutive moves. The coordinates of the origins of these | |
2777 | worms are written to the worm arrays and the number of | |
2778 | non-capturable worms is returned. The algorithm is to cycle | |
2779 | through the worms until none remains or no more can be | |
2780 | captured. A worm is removed when it is found to be | |
2781 | capturable, by letting the opponent try to play on all its | |
2782 | liberties. If the attack fails, the moves are undone. When no | |
2783 | more worm can be removed in this way, the remaining ones are | |
2784 | unconditionally alive. After this, unconditionally dead | |
2785 | opponent worms and unconditional territory are identified. To | |
2786 | find these, we continue from the position obtained at the end | |
2787 | of the previous operation (only unconditionally alive strings | |
2788 | remain for color) with the following steps: | |
2789 | ||
2790 | 1. Play opponent stones on all liberties of the | |
2791 | unconditionally alive strings except where illegal. | |
2792 | (That the move order may determine exactly which | |
2793 | liberties can be played legally is not important. Just | |
2794 | pick an arbitrary order). | |
2795 | ||
2796 | 2. Recursively extend opponent strings in atari, except | |
2797 | where this would be suicide. | |
2798 | ||
2799 | 3. Play an opponent stone anywhere it can get two empty | |
2800 | neighbors. (I.e. split big eyes into small ones). | |
2801 | ||
2802 | 4. an opponent stone anywhere it can get one empty | |
2803 | neighbor. (I.e. reduce two space eyes to one space eyes.) | |
2804 | Remaining opponent strings in atari and remaining | |
2805 | liberties of the unconditionally alive strings | |
2806 | constitute the unconditional territory. Opponent | |
2807 | strings from the initial position placed on | |
2808 | unconditional territory are unconditionally dead. On | |
2809 | return, `unconditional_territory[][]' is 1 where color | |
2810 | has unconditionally alive stones, 2 where it has | |
2811 | unconditional territory, and 0 otherwise. | |
2812 | ||
2813 | * `void who_wins(int color, FILE *outfile)' | |
2814 | ||
2815 | Score the game and determine the winner | |
2816 | ||
2817 | * `void find_superstring(int str, int *num_stones, int *stones)' | |
2818 | ||
2819 | Find the stones of an extended string, where the extensions | |
2820 | are through the following kinds of connections: | |
2821 | 1. Solid connections (just like ordinary string). | |
2822 | OO | |
2823 | ||
2824 | 2. Diagonal connection or one space jump through an | |
2825 | intersection where an opponent move would be suicide or | |
2826 | self-atari. | |
2827 | ... | |
2828 | O.O | |
2829 | XOX | |
2830 | X.X | |
2831 | ||
2832 | 3. Bamboo joint. | |
2833 | OO | |
2834 | .. | |
2835 | OO | |
2836 | ||
2837 | 4. Diagonal connection where both adjacent intersections | |
2838 | are empty. | |
2839 | .O | |
2840 | O. | |
2841 | ||
2842 | 5. Connection through adjacent or diagonal tactically | |
2843 | captured stones. Connections of this type are omitted | |
2844 | when the superstring code is called from reading.c, but | |
2845 | included when the superstring code is called from owl.c | |
2846 | ||
2847 | * `void find_superstring_liberties(int str, int *num_libs, int | |
2848 | *libs, int liberty_cap)' | |
2849 | ||
2850 | This function computes the superstring at `str' as described | |
2851 | above, but omitting connections of type 5. Then it constructs | |
2852 | a list of liberties of the superstring which are not already | |
2853 | liberties of `str'. If `liberty_cap' is nonzero, only | |
2854 | liberties of substrings of the superstring which have fewer | |
2855 | than `liberty_cap' liberties are generated. | |
2856 | ||
2857 | * `void find_proper_superstring_liberties(int str, int *num_libs, | |
2858 | int *libs, int liberty_cap)' | |
2859 | ||
2860 | This function is the same as find_superstring_liberties, but | |
2861 | it omits those liberties of the string `str', presumably | |
2862 | since those have already been treated elsewhere. If | |
2863 | `liberty_cap' is nonzero, only liberties of substrings of the | |
2864 | superstring which have at most `liberty_cap' liberties are | |
2865 | generated. | |
2866 | ||
2867 | * `void find_superstring_stones_and_liberties(int str, int | |
2868 | *num_stones, int *stones, int *num_libs, int *libs, int | |
2869 | liberty_cap)' | |
2870 | ||
2871 | This function computes the superstring at `str' as described | |
2872 | above, but omitting connections of type 5. Then it constructs | |
2873 | a list of liberties of the superstring which are not already | |
2874 | liberties of `str'. If liberty_cap is nonzero, only liberties | |
2875 | of substrings of the superstring which have fewer than | |
2876 | liberty_cap liberties are generated. | |
2877 | ||
2878 | * `void superstring_chainlinks(int str, int *num_adj, int | |
2879 | adjs[MAXCHAIN], int liberty_cap)' | |
2880 | ||
2881 | analogous to chainlinks, this function finds boundary chains | |
2882 | of the superstring at `str', including those which are | |
2883 | boundary chains of `str' itself. If `liberty_cap != 0', only | |
2884 | those boundary chains with `<= liberty_cap' liberties are | |
2885 | reported. | |
2886 | ||
2887 | * `void proper_superstring_chainlinks(int str, int *num_adj, int | |
2888 | adjs[MAXCHAIN], int liberty_cap)' | |
2889 | ||
2890 | analogous to chainlinks, this function finds boundary chains | |
2891 | of the superstring at `str', omitting those which are | |
2892 | boundary chains of `str' itself. If `liberty_cap != 0', only | |
2893 | those boundary chains with `<= liberty_cap' liberties are | |
2894 | reported. | |
2895 | ||
2896 | * `void start_timer(int n)' | |
2897 | ||
2898 | Start a timer. GNU Go has four internal timers available for | |
2899 | assessing the time spent on various tasks. | |
2900 | ||
2901 | * `double time_report(int n, const char *occupation, int move, | |
2902 | double mintime)' | |
2903 | ||
2904 | Report time spent and restart the timer. Make no report if | |
2905 | elapsed time is less than mintime. | |
2906 | ||
2907 | \1f | |
2908 | File: gnugo.info, Node: Print Utilities, Next: Board Utilities, Prev: General Utilities, Up: Utility Functions | |
2909 | ||
2910 | 18.2 Print Utilities | |
2911 | ==================== | |
2912 | ||
2913 | Functions in `engine/printutils.c' do formatted printing similar to | |
2914 | `printf' and its allies. The following formats are recognized: | |
2915 | ||
2916 | * `%c', `%d', `%f', `%s', `%x' | |
2917 | ||
2918 | These have their usual meaning in formatted output, printing | |
2919 | a character, integer, float, string or hexadecimal, | |
2920 | respectively. | |
2921 | ||
2922 | * `%o' | |
2923 | ||
2924 | `Outdent.' Normally output is indented by `2*stackp' spaces, | |
2925 | so that the depth can be seen at a glance in traces. At the | |
2926 | beginning of a format, this `%o' inhibits the indentation. | |
2927 | ||
2928 | * `%H' | |
2929 | ||
2930 | Print a hashvalue. | |
2931 | ||
2932 | * `%C' | |
2933 | ||
2934 | Print a color as a string. | |
2935 | ||
2936 | * `%m', `%2m' (synonyms) | |
2937 | ||
2938 | Takes 2 integers and writes a move, using the two dimensional | |
2939 | board representation (*note The Board Array::) | |
2940 | ||
2941 | * `%1m' | |
2942 | ||
2943 | Takes 1 integers and writes a move, using the one dimensional | |
2944 | board representation (*note The Board Array::) | |
2945 | ||
2946 | We list the non statically declared functions in `printutils.c'. | |
2947 | ||
2948 | * `void gfprintf(FILE *outfile, const char *fmt, ...)' | |
2949 | ||
2950 | Formatted output to `outfile'. | |
2951 | ||
2952 | * `int gprintf(const char *fmt, ...)' | |
2953 | ||
2954 | Formatted output to stderr. Always returns 1 to allow use in | |
2955 | short-circuit logical expressions. | |
2956 | ||
2957 | * `int mprintf(const char *fmt, ...)' | |
2958 | ||
2959 | Formatted output to stdout. | |
2960 | ||
2961 | * `DEBUG(level, fmt, args...)' | |
2962 | ||
2963 | If `level & debug', do formatted output to stderr. Otherwise, | |
2964 | ignore. | |
2965 | ||
2966 | * `void abortgo(const char *file, int line, const char *msg, int | |
2967 | pos)' | |
2968 | ||
2969 | Print debugging output in an error situation, then exit. | |
2970 | ||
2971 | * `const char * color_to_string(int color)' | |
2972 | ||
2973 | Convert a color value to a string | |
2974 | ||
2975 | * `const char * location_to_string(int pos)' | |
2976 | ||
2977 | Convert a location to a string | |
2978 | ||
2979 | * `void location_to_buffer(int pos, char *buf)' | |
2980 | ||
2981 | Convert a location to a string, writing to a buffer. | |
2982 | ||
2983 | * `int string_to_location(int boardsize, char *str, int *m, int *n)' | |
2984 | ||
2985 | Get the `(m, n)' coordinates in the standard GNU Go | |
2986 | coordinate system from the string `str'. This means that `m' | |
2987 | is the nth row from the top and `n' is the column. Both | |
2988 | coordinates are between 0 and `boardsize-1', inclusive. | |
2989 | Return 1 if ok, otherwise return 0; | |
2990 | ||
2991 | * `int is_hoshi_point(int m, int n)' True if the coordinate is a | |
2992 | hoshi point. | |
2993 | ||
2994 | * `void draw_letter_coordinates(FILE *outfile)' Print a line with | |
2995 | coordinate letters above the board. | |
2996 | ||
2997 | * `void simple_showboard(FILE *outfile)' | |
2998 | ||
2999 | Bare bones version of `showboard(0)'. No fancy options, no | |
3000 | hint of color, and you can choose where to write it. | |
3001 | ||
3002 | The following functions are in `showbord.c'. Not all public | |
3003 | functions in that file are listed here. | |
3004 | ||
3005 | * `void showboard(int xo)' | |
3006 | ||
3007 | Show go board. | |
3008 | xo=0: black and white XO board for ascii game | |
3009 | xo=1: colored dragon display | |
3010 | xo=2: colored eye display | |
3011 | xo=3: colored owl display | |
3012 | xo=4: colored matcher status display | |
3013 | ||
3014 | * `const char * status_to_string(int status)' | |
3015 | ||
3016 | Convert a status value to a string. | |
3017 | ||
3018 | * `const char * safety_to_string(int status)' | |
3019 | ||
3020 | Convert a safety value to a string. | |
3021 | ||
3022 | * `const char * result_to_string(int result)' | |
3023 | ||
3024 | Convert a read result to a string | |
3025 | ||
3026 | \1f | |
3027 | File: gnugo.info, Node: Board Utilities, Next: Influence Utilities, Prev: Print Utilities, Up: Utility Functions | |
3028 | ||
3029 | 18.3 Board Utilities | |
3030 | ==================== | |
3031 | ||
3032 | The functions documented in this section are from `board.c'. Other | |
3033 | functions in `board.c' are described in *Note Some Board Functions::. | |
3034 | ||
3035 | * `void store_board(struct board_state *state)' | |
3036 | ||
3037 | Save board state. | |
3038 | ||
3039 | * `void restore_board(struct board_state *state)' | |
3040 | ||
3041 | Restore a saved board state. | |
3042 | ||
3043 | * `void clear_board(void)' | |
3044 | ||
3045 | Clear the internal board. | |
3046 | ||
3047 | * `void dump_stack(void)' | |
3048 | ||
3049 | for use under GDB prints the move stack. | |
3050 | ||
3051 | * `void add_stone(int pos, int color)' | |
3052 | ||
3053 | Place a stone on the board and update the board_hash. This | |
3054 | operation destroys all move history. | |
3055 | ||
3056 | * `void remove_stone(int pos)' | |
3057 | ||
3058 | Remove a stone from the board and update the board_hash. This | |
3059 | operation destroys the move history. | |
3060 | ||
3061 | * `int is_pass(int pos)' | |
3062 | ||
3063 | Test if the move is a pass or not. Return 1 if it is. | |
3064 | ||
3065 | * `int is_legal(int pos, int color)' | |
3066 | ||
3067 | Determines whether the move `color' at `pos' is legal. | |
3068 | ||
3069 | * `int is_suicide(int pos, int color)' | |
3070 | ||
3071 | Determines whether the move `color' at `pos' would be a | |
3072 | suicide. This is the case if | |
3073 | 1. There is no neighboring empty intersection. | |
3074 | ||
3075 | 2. There is no neighboring opponent string with exactly one | |
3076 | liberty. | |
3077 | ||
3078 | 3. There is no neighboring friendly string with more than | |
3079 | one liberty. | |
3080 | ||
3081 | * `int is_illegal_ko_capture(int pos, int color)' | |
3082 | ||
3083 | Determines whether the move `color' at `pos' would be an | |
3084 | illegal ko capture. | |
3085 | ||
3086 | * `int is_edge_vertex(int pos)' | |
3087 | ||
3088 | Determine whether vertex is on the edge. | |
3089 | ||
3090 | * `int edge_distance(int pos)' | |
3091 | ||
3092 | Distance to the edge. | |
3093 | ||
3094 | * `int is_corner_vertex(int pos)' | |
3095 | ||
3096 | Determine whether vertex is a corner. | |
3097 | ||
3098 | * `int get_komaster()' | |
3099 | ||
3100 | * `int get_kom_pos()' | |
3101 | ||
3102 | Public functions to access the variable `komaster' and | |
3103 | `kom_pos', which are static in `board.c'. | |
3104 | ||
3105 | Next we come to `countlib()' and its allies, which address the | |
3106 | problem of determining how many liberties a string has. Although | |
3107 | `countlib()' addresses this basic question, other functions can often | |
3108 | get the needed information more quickly, so there are a number of | |
3109 | different functions in this family. | |
3110 | ||
3111 | * `int countlib(int str)' | |
3112 | ||
3113 | Count the number of liberties of the string at `pos'. There | |
3114 | must be a stone at this location. | |
3115 | ||
3116 | * `int findlib(int str, int maxlib, int *libs)' | |
3117 | ||
3118 | Find the liberties of the string at `str'. This location must | |
3119 | not be empty. The locations of up to maxlib liberties are | |
3120 | written into `libs[]'. The full number of liberties is | |
3121 | returned. If you want the locations of all liberties, | |
3122 | whatever their number, you should pass `MAXLIBS' as the value | |
3123 | for `maxlib' and allocate space for `libs[]' accordingly. | |
3124 | ||
3125 | * `int fastlib(int pos, int color, int ignore_captures)' | |
3126 | ||
3127 | Count the liberties a stone of the given color would get if | |
3128 | played at `pos'. The intent of this function is to be as fast | |
3129 | as possible, not necessarily complete. But if it returns a | |
3130 | positive value (meaning it has succeeded), the value is | |
3131 | guaranteed to be correct. Captures are ignored based if the | |
3132 | `ignore_captures' field is nonzero. The location `pos' must | |
3133 | be empty. The function fails if there are more than two | |
3134 | neighbor strings of the same color. In this case, the return | |
3135 | value is -1. Captures are handled in a very limited way, so | |
3136 | if ignore_capture is 0, and a capture is required, it will | |
3137 | often return -1. | |
3138 | ||
3139 | * `int approxlib(int pos, int color, int maxlib, int *libs)' | |
3140 | ||
3141 | Find the liberties a stone of the given color would get if | |
3142 | played at `pos', ignoring possible captures of opponent | |
3143 | stones. The location `pos' must be empty. If `libs != NULL', | |
3144 | the locations of up to `maxlib' liberties are written into | |
3145 | `libs[]'. The counting of liberties may or may not be halted | |
3146 | when `maxlib' is reached. The number of liberties found is | |
3147 | returned, which may be less than the total number of | |
3148 | liberties if `maxlib' is small. If you want the number or the | |
3149 | locations of all liberties, however many they are, you should | |
3150 | pass `MAXLIBS' as the value for maxlib and allocate space for | |
3151 | `libs[]' accordingly. | |
3152 | ||
3153 | * `int accuratelib(int pos, int color, int maxlib, int *libs)' | |
3154 | ||
3155 | Find the liberties a stone of the given color would get if | |
3156 | played at `pos'. This function takes into consideration all | |
3157 | captures. Its return value is exact in that sense it counts | |
3158 | all the liberties, unless `maxlib' allows it to stop earlier. | |
3159 | The location `pos' must be empty. If `libs != NULL', the | |
3160 | locations of up to `maxlib' liberties are written into | |
3161 | `libs[]'. The counting of liberties may or may not be halted | |
3162 | when `maxlib' is reached. The number of found liberties is | |
3163 | returned. This function guarantees that liberties which are | |
3164 | not results of captures come first in `libs[]' array. To find | |
3165 | whether all the liberties starting from a given one are | |
3166 | results of captures, one may use `if (board[libs[k]] != | |
3167 | EMPTY)' construction. If you want the number or the | |
3168 | locations of all liberties, however many they are, you should | |
3169 | pass `MAXLIBS' as the value for `maxlib' and allocate space | |
3170 | for `libs[]' accordingly. | |
3171 | ||
3172 | Next we have some general utility functions. | |
3173 | ||
3174 | * `int count_common_libs(int str1, int str2)' | |
3175 | ||
3176 | Find the number of common liberties of the two strings. | |
3177 | ||
3178 | * `int find_common_libs(int str1, int str2, int maxlib, int *libs)' | |
3179 | ||
3180 | Find the common liberties of the two strings. The locations | |
3181 | of up to `maxlib' common liberties are written into `libs[]'. | |
3182 | The full number of common liberties is returned. If you want | |
3183 | the locations of all common liberties, whatever their number, | |
3184 | you should pass `MAXLIBS' as the value for `maxlib' and | |
3185 | allocate space for `libs[]' accordingly. | |
3186 | ||
3187 | * `int have_common_lib(int str1, int str2, int *lib)' | |
3188 | ||
3189 | Determine whether two strings have at least one common | |
3190 | liberty. If they do and `lib != NULL', one common liberty is | |
3191 | returned in `*lib'. | |
3192 | ||
3193 | * `int countstones(int str)' | |
3194 | ||
3195 | Report the number of stones in a string. | |
3196 | ||
3197 | * `int findstones(int str, int maxstones, int *stones)' | |
3198 | ||
3199 | Find the stones of the string at `str'. The location must not | |
3200 | be empty. The locations of up to maxstones stones are written | |
3201 | into `stones[]'. The full number of stones is returned. | |
3202 | ||
3203 | * `int chainlinks(int str, int adj[MAXCHAIN])' | |
3204 | ||
3205 | This very useful function returns (in the `adj' array) the | |
3206 | chains surrounding the string at `str'. The number of chains | |
3207 | is returned. | |
3208 | ||
3209 | * `int chainlinks2(int str, int adj[MAXCHAIN], int lib)' | |
3210 | ||
3211 | Returns (in `adj' array) those chains surrounding the string | |
3212 | at `str', which has exactly `lib' liberties. The number of | |
3213 | such chains is returned. | |
3214 | ||
3215 | * `int chainlinks3(int str, int adj[MAXCHAIN], int lib)' | |
3216 | ||
3217 | Returns (in `adj' array) the chains surrounding the string at | |
3218 | `str', which have less or equal `lib' liberties. The number | |
3219 | of such chains is returned. | |
3220 | ||
3221 | * `int extended_chainlinks(int str, int adj[MAXCHAIN], int | |
3222 | both_colors)' | |
3223 | ||
3224 | Returns (in the `adj' array) the opponent strings being | |
3225 | directly adjacent to `str' or having a common liberty with | |
3226 | `str'. The number of such strings is returned. If the | |
3227 | both_colors parameter is true, also own strings sharing a | |
3228 | liberty are returned. | |
3229 | ||
3230 | * `int find_origin(int str)' | |
3231 | ||
3232 | Find the origin of a string, i.e. the point with the smallest | |
3233 | 1D board coordinate. The idea is to have a canonical | |
3234 | reference point for a string. | |
3235 | ||
3236 | * `int is_self_atari(int pos, int color)' | |
3237 | ||
3238 | Determine whether a move by color at `pos' would be a self | |
3239 | atari, i.e. whether it would get more than one liberty. This | |
3240 | function returns true also for the case of a suicide move. | |
3241 | ||
3242 | * `int liberty_of_string(int pos, int str)' | |
3243 | ||
3244 | Returns true if `pos' is a liberty of the string at `str'. | |
3245 | ||
3246 | * `int second_order_liberty_of_string(int pos, int str)' | |
3247 | ||
3248 | Returns true if `pos' is a second order liberty of the string | |
3249 | at str. | |
3250 | ||
3251 | * `int neighbor_of_string(int pos, int str)' | |
3252 | ||
3253 | Returns true if `pos' is adjacent to the string at `str'. | |
3254 | ||
3255 | * `int has_neighbor(int pos, int color)' | |
3256 | ||
3257 | Returns true if `pos' has a neighbor of `color'. | |
3258 | ||
3259 | * `int same_string(int str1, int str2)' | |
3260 | ||
3261 | Returns true if `str1' and `str2' belong to the same string. | |
3262 | ||
3263 | * `int adjacent_strings(int str1, int str2)' | |
3264 | ||
3265 | Returns true if the strings at `str1' and `str2' are adjacent. | |
3266 | ||
3267 | * `int is_ko(int pos, int color, int *ko_pos)' | |
3268 | ||
3269 | Return true if the move `pos' by `color' is a ko capture | |
3270 | (whether capture is legal on this move or not). If so, and if | |
3271 | `ko_pos' is not a `NULL' pointer, then `*ko_pos' returns the | |
3272 | location of the captured ko stone. If the move is not a ko | |
3273 | capture, `*ko_pos' is set to 0. A move is a ko capture if | |
3274 | and only if | |
3275 | 1. All neighbors are opponent stones. | |
3276 | ||
3277 | 2. The number of captured stones is exactly one. | |
3278 | ||
3279 | * `int is_ko_point(int pos)' | |
3280 | ||
3281 | Return true if `pos' is either a stone, which if captured | |
3282 | would give ko, or if `pos' is an empty intersection adjacent | |
3283 | to a ko stone. | |
3284 | ||
3285 | * `int does_capture_something(int pos, int color)' | |
3286 | ||
3287 | Returns 1 if at least one string is captured when color plays | |
3288 | at `pos'. | |
3289 | ||
3290 | * `void mark_string(int str, char mx[BOARDMAX], char mark)' | |
3291 | ||
3292 | For each stone in the string at pos, set `mx' to value mark. | |
3293 | If some of the stones in the string are marked prior to | |
3294 | calling this function, only the connected unmarked stones | |
3295 | starting from pos are guaranteed to become marked. The rest | |
3296 | of the string may or may not become marked. (In the current | |
3297 | implementation, it will.) | |
3298 | ||
3299 | * `int move_in_stack(int pos, int cutoff)' | |
3300 | ||
3301 | Returns true if at least one move has been played at pos at | |
3302 | deeper than level `cutoff' in the reading tree. | |
3303 | ||
3304 | * `int stones_on_board(int color)' | |
3305 | ||
3306 | Return the number of stones of the indicated color(s) on the | |
3307 | board. This only counts stones in the permanent position, | |
3308 | not stones placed by `trymove()' or `tryko()'. Use | |
3309 | `stones_on_board(BLACK | WHITE)' to get the total number of | |
3310 | stones on the board. | |
3311 | ||
3312 | \1f | |
3313 | File: gnugo.info, Node: Influence Utilities, Prev: Board Utilities, Up: Utility Functions | |
3314 | ||
3315 | 18.4 Utilities from `engine/influence.c' | |
3316 | ======================================== | |
3317 | ||
3318 | We will only list here a portion of the public functions in | |
3319 | `influence.c'. The influence code is invoked through the function | |
3320 | `compute_influence' (*note Influence Usage::). It is invoked as follows. | |
3321 | ||
3322 | * `void compute_influence(int color, const char | |
3323 | safe_stones[BOARDMAX], const float strength[BOARDMAX], struct | |
3324 | influence_data *q, int move, const char *trace_message)' | |
3325 | ||
3326 | Compute the influence values for both colors. The caller must | |
3327 | - set up the `board[]' state | |
3328 | ||
3329 | - mark safe stones with `INFLUENCE_SAFE_STONE', dead | |
3330 | stones with 0 | |
3331 | ||
3332 | - mark stones newly saved by a move with | |
3333 | `INFLUENCE_SAVED_STONE' (this is relevant if the | |
3334 | influence_data *q is reused to compute a followup value | |
3335 | for this move). | |
3336 | Results will be stored in q. `move' has no effects except | |
3337 | toggling debugging. Set it to -1 for no debug output at all | |
3338 | (otherwise it will be controlled by the `-m' command line | |
3339 | option). It is assumed that `color' is in turn to move. (This | |
3340 | affects the barrier patterns (class A, D) and intrusions | |
3341 | (class B)). Color | |
3342 | ||
3343 | Other functions in `influence.c' are of the nature of utilities | |
3344 | which may be useful throughout the engine. We list the most useful ones | |
3345 | here. | |
3346 | ||
3347 | * `void influence_mark_non_territory(int pos, int color)' | |
3348 | ||
3349 | Called from actions for `t' patterns in `barriers.db'. Marks | |
3350 | `pos' as not being territory for `color'. | |
3351 | ||
3352 | * `int whose_territory(const struct influence_data *q, int pos)' | |
3353 | ||
3354 | Return the color of the territory at `pos'. If it's territory | |
3355 | for neither color, `EMPTY' is returned. | |
3356 | ||
3357 | * `int whose_moyo(const struct influence_data *q, int pos)' | |
3358 | ||
3359 | Return the color who has a moyo at `pos'. If neither color | |
3360 | has a moyo there, `EMPTY' is returned. The definition of moyo | |
3361 | in terms of the influences is totally ad hoc. | |
3362 | ||
3363 | * `int whose_area(const struct influence_data *q, int pos)' | |
3364 | ||
3365 | Return the color who has dominating influence ("area") at | |
3366 | `pos'. If neither color dominates the influence there, EMPTY | |
3367 | is returned. The definition of area in terms of the | |
3368 | influences is totally ad hoc. | |
3369 | ||
3370 | \1f | |
3371 | File: gnugo.info, Node: GTP, Next: Regression, Prev: API, Up: Top | |
3372 | ||
3373 | 19 The Go Text Protocol | |
3374 | *********************** | |
3375 | ||
3376 | * Menu: | |
3377 | ||
3378 | * The Go Text Protocol:: The Go Text Protocol | |
3379 | * Running in GTP mode:: Running GNU Go in GTP mode | |
3380 | * GTP applications:: GTP applications | |
3381 | * The Metamachine:: The Metamachine | |
3382 | * Adding new GTP commands:: Adding new GTP commands | |
3383 | * GTP command reference:: Details on every GTP command | |
3384 | ||
3385 | \1f | |
3386 | File: gnugo.info, Node: The Go Text Protocol, Next: Running in GTP mode, Up: GTP | |
3387 | ||
3388 | 19.1 The Go Text Protocol | |
3389 | ========================= | |
3390 | ||
3391 | GNU Go 3.0 introduced a new interface, the Go Text Protocol, abbreviated | |
3392 | GTP. The intention was to make an interface that is better suited for | |
3393 | machine-machine communication than the ascii interface and simpler, more | |
3394 | powerful, and more flexible than the Go Modem Protocol. | |
3395 | ||
3396 | There are two versions of the protocol. Version 1 was used with GNU | |
3397 | Go 3.0 and 3.2. GNU Go 3.4 and later versions use protocol version 2. | |
3398 | The specification of GTP version 2 is available at | |
3399 | `http://www.lysator.liu.se/~gunnar/gtp/'. GNU Go 3.4 is the reference | |
3400 | implementation for GTP version 2, but all but the most common commands | |
3401 | are to be regarded as private extensions of the protocol. | |
3402 | ||
3403 | The GTP has a variety of applications. For GNU Go the first use was | |
3404 | in regression testing (*note Regression::), followed by communication | |
3405 | with the NNGS go server and for automated test games against itself and | |
3406 | other programs. Now there are also many graphical user interfaces | |
3407 | available supporting GTP, as well as bridges to other Go servers than | |
3408 | NNGS. | |
3409 | ||
3410 | \1f | |
3411 | File: gnugo.info, Node: Running in GTP mode, Next: GTP applications, Prev: The Go Text Protocol, Up: GTP | |
3412 | ||
3413 | 19.2 Running GNU Go in GTP mode | |
3414 | =============================== | |
3415 | ||
3416 | To start GNU Go in GTP mode, simply invoke it with the option `--mode | |
3417 | gtp'. You will not get a prompt or any other output to start with but | |
3418 | GNU Go is silently waiting for GTP commands. | |
3419 | ||
3420 | A sample GTP session may look as follows: | |
3421 | ||
3422 | virihaure 462% ./gnugo --mode gtp | |
3423 | 1 boardsize 7 | |
3424 | =1 | |
3425 | ||
3426 | 2 clear_board | |
3427 | =2 | |
3428 | ||
3429 | 3 play black D5 | |
3430 | =3 | |
3431 | ||
3432 | 4 genmove white | |
3433 | =4 C3 | |
3434 | ||
3435 | 5 play black C3 | |
3436 | ?5 illegal move | |
3437 | ||
3438 | 6 play black E3 | |
3439 | =6 | |
3440 | ||
3441 | 7 showboard | |
3442 | =7 | |
3443 | A B C D E F G | |
3444 | 7 . . . . . . . 7 | |
3445 | 6 . . . . . . . 6 | |
3446 | 5 . . + X + . . 5 | |
3447 | 4 . . . + . . . 4 | |
3448 | 3 . . O . X . . 3 | |
3449 | 2 . . . . . . . 2 WHITE (O) has captured 0 stones | |
3450 | 1 . . . . . . . 1 BLACK (X) has captured 0 stones | |
3451 | A B C D E F G | |
3452 | ||
3453 | 8 quit | |
3454 | =8 | |
3455 | ||
3456 | Commands are given on a single line, starting by an optional identity | |
3457 | number, followed by the command name and its arguments. | |
3458 | ||
3459 | If the command is successful, the response starts by an equals sign | |
3460 | (`='), followed by the identity number of the command (if any) and then | |
3461 | the result. In this example all results were empty strings except for | |
3462 | command 4 where the answer was the white move at C3, and command 7 | |
3463 | where the result was a diagram of the current board position. The | |
3464 | response ends by two consecutive newlines. | |
3465 | ||
3466 | Failing commands are signified by a question mark (`?') instead of | |
3467 | an equals sign, as in the response to command 5. | |
3468 | ||
3469 | The detailed specification of the protocol can be found at | |
3470 | `http://www.lysator.liu.se/~gunnar/gtp/'. The available commands in GNU | |
3471 | Go may always be listed using the command `list_commands'. They are | |
3472 | also documented in *Note GTP command reference::. | |
3473 | ||
3474 | \1f | |
3475 | File: gnugo.info, Node: GTP applications, Next: The Metamachine, Prev: Running in GTP mode, Up: GTP | |
3476 | ||
3477 | 19.3 GTP applications | |
3478 | ===================== | |
3479 | ||
3480 | GTP is an asymmetric protocol involving two parties which we call | |
3481 | controller and engine. The controller sends all commands and the engine | |
3482 | only responds to these commands. GNU Go implements the engine end of the | |
3483 | protocol. | |
3484 | ||
3485 | With the source code of GNU Go is also distributed a number of | |
3486 | applications implementing the controller end. Among the most | |
3487 | interesting of these are: | |
3488 | ||
3489 | * `regression/regress.awk' | |
3490 | ||
3491 | Script to run regressions. The script sends GTP commands to | |
3492 | set up and evaluate positions to the engine and then analyzes | |
3493 | the responses from the engine. More information about GTP | |
3494 | based regression testing can be found in the regression | |
3495 | chapter (*note Regression::). | |
3496 | ||
3497 | * `regression/regress.pl' | |
3498 | ||
3499 | Perl script to run regressions, giving output which together | |
3500 | with the CGI script `regression/regress.plx' generates HTML | |
3501 | views of the regressions. | |
3502 | ||
3503 | * `regression/regress.pike' | |
3504 | ||
3505 | Pike script to run regressions. More feature-rich and | |
3506 | powerful than `regress.awk'. | |
3507 | ||
3508 | * `regression/view.pike' | |
3509 | ||
3510 | Pike script to examine a single regression testcase through a | |
3511 | graphical board. This gives an easy way to inspect many of | |
3512 | the GNU Go internals. | |
3513 | ||
3514 | * `interface/gtp_examples/twogtp' | |
3515 | ||
3516 | Perl script to play two engines against each other. The script | |
3517 | essentially sets up both engines with desired boardsize, | |
3518 | handicap, and komi, then relays moves back and forth between | |
3519 | the engines. | |
3520 | ||
3521 | * `interface/gtp_examples/twogtp-a' | |
3522 | ||
3523 | An alternative Perl implementation of twogtp. | |
3524 | ||
3525 | * `interface/gtp_examples/twogtp.py' | |
3526 | ||
3527 | Implementation of twogtp in Python. Has more features than | |
3528 | the Perl variants. | |
3529 | ||
3530 | * `interface/gtp_examples/twogtp.pike' | |
3531 | ||
3532 | Implementation of twogtp in Pike. Has even more features than | |
3533 | the Python variant. | |
3534 | ||
3535 | * `interface/gtp_examples/2ptkgo.pl' | |
3536 | ||
3537 | Variation of twogtp which includes a graphical board. | |
3538 | ||
3539 | More GTP applications, including bridges to go servers and graphical | |
3540 | user interfaces, are listed at `http://www.lysator.liu.se/~gunnar/gtp/'. | |
3541 | ||
3542 | \1f | |
3543 | File: gnugo.info, Node: The Metamachine, Next: Adding new GTP commands, Prev: GTP applications, Up: GTP | |
3544 | ||
3545 | 19.4 The Metamachine | |
3546 | ==================== | |
3547 | ||
3548 | An interesting application of the GTP is the concept of using GNU Go as | |
3549 | an "Oracle" that can be consulted by another process. This could be | |
3550 | another computer program that asks GNU Go to generate future board | |
3551 | positions, then evaluate them. | |
3552 | ||
3553 | David Doshay at the University of California at Santa Cruz has done | |
3554 | interesting experiments with a parallel engine, known as SlugGo, that | |
3555 | is based on GNU Go. These are described in | |
3556 | `http://lists.gnu.org/archive/html/gnugo-devel/2004-08/msg00060.html'. | |
3557 | ||
3558 | The "Metamachine" experiment is a more modest approach using the GTP | |
3559 | to communicate with a GNU Go process that is used as an oracle. The | |
3560 | following scheme is used. | |
3561 | ||
3562 | * The GNU Go "oracle" is asked to generate its top moves using the | |
3563 | GTP `top_moves' commands. | |
3564 | ||
3565 | * Both moves are tried and `estimate_score' is called from the | |
3566 | resulting board position. | |
3567 | ||
3568 | * The higher scoring position is selected as the engine's move. | |
3569 | ||
3570 | This scheme does not produce a stronger engine, but it is | |
3571 | suggestive, and the SlugGo experiment seems to show that a more | |
3572 | elaborate scheme along the same lines could produce a stronger engine. | |
3573 | ||
3574 | Two implementations are distributed with GNU Go. Both make use of | |
3575 | `fork' and `pipe' system calls, so they require a Unix-like | |
3576 | environment. The Metamachine has been tested under GNU/Linux. | |
3577 | ||
3578 | *Important:* If the Metamachine terminates normally, the GNU Go | |
3579 | process will be killed. However there is a danger that something will | |
3580 | go wrong. When you are finished running the Metamachine, it is a good | |
3581 | idea to run `ps -A|grep gnugo' or `ps -aux|grep gnugo' to make sure | |
3582 | there are no unterminated processes. (If there are, just kill them.) | |
3583 | ||
3584 | 19.4.1 The Standalone Metamachine | |
3585 | --------------------------------- | |
3586 | ||
3587 | In `interface/gtp_examples/metamachine.c' is a standalone | |
3588 | implementation of the Metamachine. Compile it with `cc -o metamachine | |
3589 | metamachine.c' and run it. It forks a `gnugo' process with which it | |
3590 | communicates through the GTP, to use as an oracle. | |
3591 | ||
3592 | The following scheme is followed: | |
3593 | ||
3594 | stdin pipe a | |
3595 | GTP client ----> Metamachine -----> GNU Go | |
3596 | <---- <----- | |
3597 | stdout pipe b | |
3598 | ||
3599 | Most commands issued by the client are passed along verbatim to GNU | |
3600 | Go by the Metamachine. The exception is gg_genmove, which is | |
3601 | intercepted then processed differently, as described above. The client | |
3602 | is unaware of this, and only knows that it issued a gg_genmove command | |
3603 | and received a reply. Thus to the the Metamachine appears as an | |
3604 | ordinary GTP engine. | |
3605 | ||
3606 | Usage: no arguments gives normal GTP behavior. `metamachine | |
3607 | --debug' sends diagnostics to stderr. | |
3608 | ||
3609 | 19.4.2 GNU Go as a Metamachine | |
3610 | ------------------------------ | |
3611 | ||
3612 | Alternatively, you may compile GNU Go with the configure option | |
3613 | `--enable-metamachine'. This causes the file `oracle.c' to be compiled, | |
3614 | which contains the Metamachine code. This has no effect on the engine | |
3615 | unless you run GNU Go with the runtime option `--metamachine'. Thus you | |
3616 | must use both the configure and the runtime option to get the | |
3617 | Metamachine. | |
3618 | ||
3619 | This method is better than the standalone program since you have | |
3620 | access to GNU Go's facilities. For example, you can run the Metamachine | |
3621 | with CGoban or in Ascii mode this way. | |
3622 | ||
3623 | You can get traces by adding the command line `-d0x1000000'. In | |
3624 | debugging the Metamachine, a danger is that any small oversight in | |
3625 | designing the program can cause the forked process and the controller | |
3626 | to hang, each one waiting for a response from the other. If this seems | |
3627 | to happen it is useful to know that you can attach `gdb' to a running | |
3628 | process and find out what it is doing. | |
3629 | ||
3630 | \1f | |
3631 | File: gnugo.info, Node: Adding new GTP commands, Next: GTP command reference, Prev: The Metamachine, Up: GTP | |
3632 | ||
3633 | 19.5 Adding new GTP commands | |
3634 | ============================ | |
3635 | ||
3636 | The implementation of GTP in GNU Go is distributed over three files, | |
3637 | `interface/gtp.h', `interface/gtp.c', and `interface/play_gtp.c'. The | |
3638 | first two implement a small library of helper functions which can be | |
3639 | used also by other programs. In the interest of promoting the GTP they | |
3640 | are licensed with minimal restrictions (*note GTP License::). The | |
3641 | actual GTP commands are implemented in `play_gtp.c', which has | |
3642 | knowledge about the engine internals. | |
3643 | ||
3644 | To see how a simple but fairly typical command is implemented we | |
3645 | look at `gtp_countlib()' (a GNU Go private extension command): | |
3646 | ||
3647 | static int | |
3648 | gtp_countlib(char *s) | |
3649 | { | |
3650 | int i, j; | |
3651 | if (!gtp_decode_coord(s, &i, &j)) | |
3652 | return gtp_failure("invalid coordinate"); | |
3653 | ||
3654 | if (BOARD(i, j) == EMPTY) | |
3655 | return gtp_failure("vertex must not be empty"); | |
3656 | ||
3657 | return gtp_success("%d", countlib(POS(i, j))); | |
3658 | } | |
3659 | ||
3660 | The arguments to the command are passed in the string `s'. In this | |
3661 | case we expect a vertex as argument and thus try to read it with | |
3662 | `gtp_decode_coord()' from `gtp.c'. | |
3663 | ||
3664 | A correctly formatted response should start with either `=' or `?', | |
3665 | followed by the identity number (if one was sent), the actual result, | |
3666 | and finally two consecutive newlines. It is important to get this | |
3667 | formatting correct since the controller in the other end relies on it. | |
3668 | Naturally the result itself cannot contain two consecutive newlines but | |
3669 | it may be split over several lines by single newlines. | |
3670 | ||
3671 | The easiest way to generate a correctly formatted response is with | |
3672 | one of the functions `gtp_failure()' and `gtp_success()', assuming that | |
3673 | their formatted output does not end with a newline. | |
3674 | ||
3675 | Sometimes the output is too complex for use with gtp_success, e.g. if | |
3676 | we want to print vertices, which gtp_success() does not support. Then | |
3677 | we have to fall back to the construction in e.g. `gtp_genmove()': | |
3678 | ||
3679 | static int | |
3680 | gtp_genmove(char *s) | |
3681 | { | |
3682 | [...] | |
3683 | gtp_start_response(GTP_SUCCESS); | |
3684 | gtp_print_vertex(i, j); | |
3685 | return gtp_finish_response(); | |
3686 | } | |
3687 | ||
3688 | Here `gtp_start_response()' writes the equal sign and the identity | |
3689 | number while `gtp_finish_response()' adds the final two newlines. The | |
3690 | next example is from `gtp_list_commands()': | |
3691 | ||
3692 | static int | |
3693 | gtp_list_commands(char *s) | |
3694 | { | |
3695 | int k; | |
3696 | UNUSED(s); | |
3697 | ||
3698 | gtp_start_response(GTP_SUCCESS); | |
3699 | ||
3700 | for (k = 0; commands[k].name != NULL; k++) | |
3701 | gtp_printf("%s\n", commands[k].name); | |
3702 | ||
3703 | gtp_printf("\n"); | |
3704 | return GTP_OK; | |
3705 | } | |
3706 | ||
3707 | As we have said, the response should be finished with two newlines. | |
3708 | Here we have to finish up the response ourselves since we already have | |
3709 | one newline in place from the last command printed in the loop. | |
3710 | ||
3711 | In order to add a new GTP command to GNU Go, the following pieces of | |
3712 | code need to be inserted in `play_gtp.c': | |
3713 | 1. A function declaration using the `DECLARE' macro in the list | |
3714 | starting at line 68. | |
3715 | ||
3716 | 2. An entry in the `commands[]' array starting at line 200. | |
3717 | ||
3718 | 3. An implementation of the function handling the command. | |
3719 | ||
3720 | Useful helper functions in `gtp.c'/`gtp.h' are: | |
3721 | * `gtp_printf()' for basic formatted printing. | |
3722 | ||
3723 | * `gtp_mprintf()' for printing with special format codes for | |
3724 | vertices and colors. | |
3725 | ||
3726 | * `gtp_success()' and `gtp_failure()' for simple responses. | |
3727 | ||
3728 | * `gtp_start_response()' and `gtp_end_response()' for more complex | |
3729 | responses. | |
3730 | ||
3731 | * `gtp_print_vertex()' and `gtp_print_vertices()' for printing one | |
3732 | or multiple vertices. | |
3733 | ||
3734 | * `gtp_decode_color()' to read in a color from the command arguments. | |
3735 | ||
3736 | * `gtp_decode_coord()' to read in a vertex from the command | |
3737 | arguments. | |
3738 | ||
3739 | * `gtp_decode_move()' to read in a move, i.e. color plus vertex, | |
3740 | from the command arguments. | |
3741 | ||
3742 | \1f | |
3743 | File: gnugo.info, Node: GTP command reference, Prev: Adding new GTP commands, Up: GTP | |
3744 | ||
3745 | 19.6 GTP command reference | |
3746 | ========================== | |
3747 | ||
3748 | This section lists the GTP commands implemented in GNU Go along with | |
3749 | some information about each command. Each entry in the list has the | |
3750 | following fields: | |
3751 | ||
3752 | * Function: What this command does. | |
3753 | ||
3754 | * Arguments: What other information, if any, this command requires. | |
3755 | Typical values include "none" or "vertex" or "integer" (there are | |
3756 | others). | |
3757 | ||
3758 | * Fails: Circumstances which cause this command to fail. | |
3759 | ||
3760 | * Returns: What is displayed after the "=" and before the two | |
3761 | newlines. Typical values include "nothing" or "a move coordinate" | |
3762 | or some status string (there are others). | |
3763 | ||
3764 | * Status: How this command relates to the standard GTP version 2 | |
3765 | commands. If nothing else is specified it is a GNU Go private | |
3766 | extension. | |
3767 | ||
3768 | Without further ado, here is the big list (in no particular order). | |
3769 | ||
3770 | Note: if new commands are added by editing `interface/play_gtp.c' | |
3771 | this list could become incomplete. You may rebuild this list in | |
3772 | `doc/gtp-commands.texi' with the command `make gtp-commands' in the | |
3773 | `doc/' directory. This may require GNU sed. | |
3774 | ||
3775 | * quit: Quit | |
3776 | Arguments: none | |
3777 | Fails: never | |
3778 | Returns: nothing | |
3779 | ||
3780 | Status: GTP version 2 standard command. | |
3781 | ||
3782 | ||
3783 | * protocol_version: Report protocol version. | |
3784 | Arguments: none | |
3785 | Fails: never | |
3786 | Returns: protocol version number | |
3787 | ||
3788 | Status: GTP version 2 standard command. | |
3789 | ||
3790 | ||
3791 | * name: Report the name of the program. | |
3792 | Arguments: none | |
3793 | Fails: never | |
3794 | Returns: program name | |
3795 | ||
3796 | Status: GTP version 2 standard command. | |
3797 | ||
3798 | ||
3799 | * version: Report the version number of the program. | |
3800 | Arguments: none | |
3801 | Fails: never | |
3802 | Returns: version number | |
3803 | ||
3804 | Status: GTP version 2 standard command. | |
3805 | ||
3806 | ||
3807 | * boardsize: Set the board size to NxN and clear the board. | |
3808 | Arguments: integer | |
3809 | Fails: board size outside engine's limits | |
3810 | Returns: nothing | |
3811 | ||
3812 | Status: GTP version 2 standard command. | |
3813 | ||
3814 | ||
3815 | * query_boardsize: Find the current boardsize | |
3816 | Arguments: none | |
3817 | Fails: never | |
3818 | Returns: board_size | |
3819 | ||
3820 | ||
3821 | * clear_board: Clear the board. | |
3822 | Arguments: none | |
3823 | Fails: never | |
3824 | Returns: nothing | |
3825 | ||
3826 | Status: GTP version 2 standard command. | |
3827 | ||
3828 | ||
3829 | * orientation: Set the orienation to N and clear the board | |
3830 | Arguments: integer | |
3831 | Fails: illegal orientation | |
3832 | Returns: nothing | |
3833 | ||
3834 | ||
3835 | * query_orientation: Find the current orientation | |
3836 | Arguments: none | |
3837 | Fails: never | |
3838 | Returns: orientation | |
3839 | ||
3840 | ||
3841 | * komi: Set the komi. | |
3842 | Arguments: float | |
3843 | Fails: incorrect argument | |
3844 | Returns: nothing | |
3845 | ||
3846 | Status: GTP version 2 standard command. | |
3847 | ||
3848 | ||
3849 | * get_komi: Get the komi | |
3850 | Arguments: none | |
3851 | Fails: never | |
3852 | Returns: Komi | |
3853 | ||
3854 | ||
3855 | * black: Play a black stone at the given vertex. | |
3856 | Arguments: vertex | |
3857 | Fails: invalid vertex, illegal move | |
3858 | Returns: nothing | |
3859 | ||
3860 | Status: Obsolete GTP version 1 command. | |
3861 | ||
3862 | ||
3863 | * playwhite: Play a white stone at the given vertex. | |
3864 | Arguments: vertex | |
3865 | Fails: invalid vertex, illegal move | |
3866 | Returns: nothing | |
3867 | ||
3868 | Status: Obsolete GTP version 1 command. | |
3869 | ||
3870 | ||
3871 | * play: Play a stone of the given color at the given vertex. | |
3872 | Arguments: color, vertex | |
3873 | Fails: invalid vertex, illegal move | |
3874 | Returns: nothing | |
3875 | ||
3876 | Status: GTP version 2 standard command. | |
3877 | ||
3878 | ||
3879 | * fixed_handicap: Set up fixed placement handicap stones. | |
3880 | Arguments: number of handicap stones | |
3881 | Fails: invalid number of stones for the current boardsize | |
3882 | Returns: list of vertices with handicap stones | |
3883 | ||
3884 | Status: GTP version 2 standard command. | |
3885 | ||
3886 | ||
3887 | * place_free_handicap: Choose free placement handicap stones and put | |
3888 | them on the board. | |
3889 | Arguments: number of handicap stones | |
3890 | Fails: invalid number of stones | |
3891 | Returns: list of vertices with handicap stones | |
3892 | ||
3893 | Status: GTP version 2 standard command. | |
3894 | ||
3895 | ||
3896 | * set_free_handicap: Put free placement handicap stones on the board. | |
3897 | Arguments: list of vertices with handicap stones | |
3898 | Fails: board not empty, bad list of vertices | |
3899 | Returns: nothing | |
3900 | ||
3901 | Status: GTP version 2 standard command. | |
3902 | ||
3903 | ||
3904 | * get_handicap: Get the handicap | |
3905 | Arguments: none | |
3906 | Fails: never | |
3907 | Returns: handicap | |
3908 | ||
3909 | ||
3910 | * loadsgf: Load an sgf file, possibly up to a move number or the | |
3911 | first occurence of a move. | |
3912 | Arguments: filename + move number, vertex, or nothing | |
3913 | Fails: missing filename or failure to open or parse file | |
3914 | Returns: color to play | |
3915 | ||
3916 | Status: GTP version 2 standard command. | |
3917 | ||
3918 | ||
3919 | * color: Return the color at a vertex. | |
3920 | Arguments: vertex | |
3921 | Fails: invalid vertex | |
3922 | Returns: "black", "white", or "empty" | |
3923 | ||
3924 | ||
3925 | * list_stones: List vertices with either black or white stones. | |
3926 | Arguments: color | |
3927 | Fails: invalid color | |
3928 | Returns: list of vertices | |
3929 | ||
3930 | ||
3931 | * countlib: Count number of liberties for the string at a vertex. | |
3932 | Arguments: vertex | |
3933 | Fails: invalid vertex, empty vertex | |
3934 | Returns: Number of liberties. | |
3935 | ||
3936 | ||
3937 | * findlib: Return the positions of the liberties for the string at a | |
3938 | vertex. | |
3939 | Arguments: vertex | |
3940 | Fails: invalid vertex, empty vertex | |
3941 | Returns: Sorted space separated list of vertices. | |
3942 | ||
3943 | ||
3944 | * accuratelib: Determine which liberties a stone of given color will | |
3945 | get if played at given vertex. | |
3946 | Arguments: move (color + vertex) | |
3947 | Fails: invalid color, invalid vertex, occupied vertex | |
3948 | Returns: Sorted space separated list of liberties | |
3949 | ||
3950 | ||
3951 | * accurate_approxlib: Determine which liberties a stone of given | |
3952 | color will get if played at given vertex. | |
3953 | Arguments: move (color + vertex) | |
3954 | Fails: invalid color, invalid vertex, occupied vertex | |
3955 | Returns: Sorted space separated list of liberties | |
3956 | ||
3957 | Supposedly identical in behavior to the above function and | |
3958 | can be retired when this is confirmed. | |
3959 | ||
3960 | ||
3961 | * is_legal: Tell whether a move is legal. | |
3962 | Arguments: move | |
3963 | Fails: invalid move | |
3964 | Returns: 1 if the move is legal, 0 if it is not. | |
3965 | ||
3966 | ||
3967 | * all_legal: List all legal moves for either color. | |
3968 | Arguments: color | |
3969 | Fails: invalid color | |
3970 | Returns: Sorted space separated list of vertices. | |
3971 | ||
3972 | ||
3973 | * captures: List the number of captures taken by either color. | |
3974 | Arguments: color | |
3975 | Fails: invalid color | |
3976 | Returns: Number of captures. | |
3977 | ||
3978 | ||
3979 | * last_move: Return the last move. | |
3980 | Arguments: none | |
3981 | Fails: no previous move known | |
3982 | Returns: Color and vertex of last move. | |
3983 | ||
3984 | ||
3985 | * move_history: Print the move history in reverse order | |
3986 | Arguments: none | |
3987 | Fails: never | |
3988 | Returns: List of moves played in reverse order in format: | |
3989 | color move (one move per line) | |
3990 | ||
3991 | ||
3992 | * invariant_hash: Return the rotation/reflection invariant board | |
3993 | hash. | |
3994 | Arguments: none | |
3995 | Fails: never | |
3996 | Returns: Invariant hash for the board as a hexadecimal number. | |
3997 | ||
3998 | ||
3999 | * invariant_hash_for_moves: Return the rotation/reflection invariant | |
4000 | board hash obtained by playing all the possible moves for the | |
4001 | given color. | |
4002 | Arguments: color | |
4003 | Fails: invalid color | |
4004 | Returns: List of moves + invariant hash as a hexadecimal number, | |
4005 | one pair of move + hash per line. | |
4006 | ||
4007 | ||
4008 | * trymove: Play a stone of the given color at the given vertex. | |
4009 | Arguments: move (color + vertex) | |
4010 | Fails: invalid color, invalid vertex, illegal move | |
4011 | Returns: nothing | |
4012 | ||
4013 | ||
4014 | * tryko: Play a stone of the given color at the given vertex, | |
4015 | allowing illegal ko capture. | |
4016 | Arguments: move (color + vertex) | |
4017 | Fails: invalid color, invalid vertex, illegal move | |
4018 | Returns: nothing | |
4019 | ||
4020 | ||
4021 | * popgo: Undo a trymove or tryko. | |
4022 | Arguments: none | |
4023 | Fails: stack empty | |
4024 | Returns: nothing | |
4025 | ||
4026 | * clear_cache: clear the caches. | |
4027 | Arguments: none. | |
4028 | Fails: never. | |
4029 | Returns: nothing. | |
4030 | ||
4031 | ||
4032 | * attack: Try to attack a string. | |
4033 | Arguments: vertex | |
4034 | Fails: invalid vertex, empty vertex | |
4035 | Returns: attack code followed by attack point if attack code nonzero. | |
4036 | ||
4037 | ||
4038 | * attack_either: Try to attack either of two strings | |
4039 | Arguments: two vertices | |
4040 | Fails: invalid vertex, empty vertex | |
4041 | Returns: attack code against the strings. Guarantees there | |
4042 | exists a move which will attack one of the two | |
4043 | with attack_code, but does not return the move. | |
4044 | ||
4045 | ||
4046 | * defend: Try to defend a string. | |
4047 | Arguments: vertex | |
4048 | Fails: invalid vertex, empty vertex | |
4049 | Returns: defense code followed by defense point if defense code nonzero. | |
4050 | ||
4051 | ||
4052 | * does_attack: Examine whether a specific move attacks a string | |
4053 | tactically. | |
4054 | Arguments: vertex (move), vertex (dragon) | |
4055 | Fails: invalid vertex, empty vertex | |
4056 | Returns: attack code | |
4057 | ||
4058 | ||
4059 | * does_defend: Examine whether a specific move defends a string | |
4060 | tactically. | |
4061 | Arguments: vertex (move), vertex (dragon) | |
4062 | Fails: invalid vertex, empty vertex | |
4063 | Returns: attack code | |
4064 | ||
4065 | ||
4066 | * ladder_attack: Try to attack a string strictly in a ladder. | |
4067 | Arguments: vertex | |
4068 | Fails: invalid vertex, empty vertex | |
4069 | Returns: attack code followed by attack point if attack code nonzero. | |
4070 | ||
4071 | ||
4072 | * increase_depths: Increase depth values by one. | |
4073 | Arguments: none | |
4074 | Fails: never | |
4075 | Returns: nothing | |
4076 | ||
4077 | ||
4078 | * decrease_depths: Decrease depth values by one. | |
4079 | Arguments: none | |
4080 | Fails: never | |
4081 | Returns: nothing | |
4082 | ||
4083 | ||
4084 | * owl_attack: Try to attack a dragon. | |
4085 | Arguments: vertex | |
4086 | Fails: invalid vertex, empty vertex | |
4087 | Returns: attack code followed by attack point if attack code nonzero. | |
4088 | ||
4089 | ||
4090 | * owl_defend: Try to defend a dragon. | |
4091 | Arguments: vertex | |
4092 | Fails: invalid vertex, empty vertex | |
4093 | Returns: defense code followed by defense point if defense code nonzero. | |
4094 | ||
4095 | ||
4096 | * owl_threaten_attack: Try to attack a dragon in 2 moves. | |
4097 | Arguments: vertex | |
4098 | Fails: invalid vertex, empty vertex | |
4099 | Returns: attack code followed by the two attack points if | |
4100 | attack code nonzero. | |
4101 | ||
4102 | ||
4103 | * owl_threaten_defense: Try to defend a dragon with 2 moves. | |
4104 | Arguments: vertex | |
4105 | Fails: invalid vertex, empty vertex | |
4106 | Returns: defense code followed by the 2 defense points if | |
4107 | defense code nonzero. | |
4108 | ||
4109 | ||
4110 | * owl_does_attack: Examine whether a specific move attacks a dragon. | |
4111 | Arguments: vertex (move), vertex (dragon) | |
4112 | Fails: invalid vertex, empty vertex | |
4113 | Returns: attack code | |
4114 | ||
4115 | ||
4116 | * owl_does_defend: Examine whether a specific move defends a dragon. | |
4117 | Arguments: vertex (move), vertex (dragon) | |
4118 | Fails: invalid vertex, empty vertex | |
4119 | Returns: defense code | |
4120 | ||
4121 | ||
4122 | * owl_connection_defends: Examine whether a connection defends | |
4123 | involved dragons. | |
4124 | Arguments: vertex (move), vertex (dragon1), vertex (dragon2) | |
4125 | Fails: invalid vertex, empty vertex | |
4126 | Returns: defense code | |
4127 | ||
4128 | ||
4129 | * defend_both: Try to defend both of two strings | |
4130 | Arguments: two vertices | |
4131 | Fails: invalid vertex, empty vertex | |
4132 | Returns: defend code for the strings. Guarantees there | |
4133 | exists a move which will defend both of the two | |
4134 | with defend_code, but does not return the move. | |
4135 | ||
4136 | ||
4137 | * owl_substantial: Determine whether capturing a string gives a | |
4138 | living dragon | |
4139 | Arguments: vertex | |
4140 | Fails: invalid vertex, empty vertex | |
4141 | Returns: 1 if dragon can live, 0 otherwise | |
4142 | ||
4143 | ||
4144 | * analyze_semeai: Analyze a semeai | |
4145 | Arguments: dragona, dragonb | |
4146 | Fails: invalid vertices, empty vertices | |
4147 | Returns: semeai defense result, semeai attack result, semeai move | |
4148 | ||
4149 | ||
4150 | * analyze_semeai_after_move: Analyze a semeai after a move have been | |
4151 | made. | |
4152 | Arguments: color, vertex, dragona, dragonb | |
4153 | Fails: invalid vertices | |
4154 | Returns: semeai defense result, semeai attack result, semeai move | |
4155 | ||
4156 | ||
4157 | * tactical_analyze_semeai: Analyze a semeai, not using owl | |
4158 | Arguments: dragona, dragonb | |
4159 | Fails: invalid vertices, empty vertices | |
4160 | Returns: status of dragona, dragonb assuming dragona moves first | |
4161 | ||
4162 | ||
4163 | * connect: Try to connect two strings. | |
4164 | Arguments: vertex, vertex | |
4165 | Fails: invalid vertex, empty vertex, vertices of different colors | |
4166 | Returns: connect result followed by connect point if successful. | |
4167 | ||
4168 | ||
4169 | * disconnect: Try to disconnect two strings. | |
4170 | Arguments: vertex, vertex | |
4171 | Fails: invalid vertex, empty vertex, vertices of different colors | |
4172 | Returns: disconnect result followed by disconnect point if successful. | |
4173 | ||
4174 | ||
4175 | * break_in: Try to break from string into area. | |
4176 | Arguments: vertex, vertices | |
4177 | Fails: invalid vertex, empty vertex. | |
4178 | Returns: result followed by break in point if successful. | |
4179 | ||
4180 | ||
4181 | * block_off: Try to block string from area. | |
4182 | Arguments: vertex, vertices | |
4183 | Fails: invalid vertex, empty vertex. | |
4184 | Returns: result followed by block point if successful. | |
4185 | ||
4186 | * eval_eye: Evaluate an eye space | |
4187 | Arguments: vertex | |
4188 | Fails: invalid vertex | |
4189 | Returns: Minimum and maximum number of eyes. If these differ an | |
4190 | attack and a defense point are additionally returned. | |
4191 | If the vertex is not an eye space or not of unique color, | |
4192 | a single -1 is returned. | |
4193 | ||
4194 | * dragon_status: Determine status of a dragon. | |
4195 | Arguments: optional vertex | |
4196 | Fails: invalid vertex, empty vertex | |
4197 | Returns: status ("alive", "critical", "dead", or "unknown"), | |
4198 | attack point, defense point. Points of attack and | |
4199 | defense are only given if the status is critical. | |
4200 | If no vertex is given, the status is listed for all | |
4201 | dragons, one per row in the format "A4: alive". | |
4202 | ||
4203 | FIXME: Should be able to distinguish between life in seki | |
4204 | and independent life. Should also be able to identify ko. | |
4205 | ||
4206 | * same_dragon: Determine whether two stones belong to the same | |
4207 | dragon. | |
4208 | Arguments: vertex, vertex | |
4209 | Fails: invalid vertex, empty vertex | |
4210 | Returns: 1 if the vertices belong to the same dragon, 0 otherwise | |
4211 | ||
4212 | * unconditional_status: Determine the unconditional status of a | |
4213 | vertex. | |
4214 | Arguments: vertex | |
4215 | Fails: invalid vertex | |
4216 | Returns: unconditional status ("undecided", "alive", "dead", | |
4217 | "white_territory", "black_territory"). Occupied vertices can | |
4218 | be undecided, alive, or dead. Empty vertices can be | |
4219 | undecided, white territory, or black territory. | |
4220 | ||
4221 | * combination_attack: Find a move by color capturing something | |
4222 | through a combination attack. | |
4223 | Arguments: color | |
4224 | Fails: invalid color | |
4225 | Returns: Recommended move, PASS if no move found | |
4226 | ||
4227 | * combination_defend: If color can capture something through a | |
4228 | combination attack, list moves by the opponent of color | |
4229 | to defend against this attack. | |
4230 | Arguments: color | |
4231 | Fails: invalid color | |
4232 | Returns: Recommended moves, PASS if no combination attack found. | |
4233 | ||
4234 | * aa_confirm_safety: Run atari_atari_confirm_safety(). | |
4235 | Arguments: move, optional int | |
4236 | Fails: invalid move | |
4237 | Returns: success code, if failure also defending move | |
4238 | ||
4239 | ||
4240 | * genmove_black: Generate and play the supposedly best black move. | |
4241 | Arguments: none | |
4242 | Fails: never | |
4243 | Returns: a move coordinate or "PASS" | |
4244 | ||
4245 | Status: Obsolete GTP version 1 command. | |
4246 | ||
4247 | ||
4248 | * genmove_white: Generate and play the supposedly best white move. | |
4249 | Arguments: none | |
4250 | Fails: never | |
4251 | Returns: a move coordinate or "PASS" | |
4252 | ||
4253 | Status: Obsolete GTP version 1 command. | |
4254 | ||
4255 | ||
4256 | * genmove: Generate and play the supposedly best move for either | |
4257 | color. | |
4258 | Arguments: color to move | |
4259 | Fails: invalid color | |
4260 | Returns: a move coordinate or "PASS" (or "resign" if resignation_allowed) | |
4261 | ||
4262 | Status: GTP version 2 standard command. | |
4263 | ||
4264 | ||
4265 | * reg_genmove: Generate the supposedly best move for either color. | |
4266 | Arguments: color to move | |
4267 | Fails: invalid color | |
4268 | Returns: a move coordinate (or "PASS") | |
4269 | ||
4270 | Status: GTP version 2 standard command. | |
4271 | ||
4272 | ||
4273 | * gg_genmove: Generate the supposedly best move for either color. | |
4274 | Arguments: color to move, optionally a random seed | |
4275 | Fails: invalid color | |
4276 | Returns: a move coordinate (or "PASS") | |
4277 | ||
4278 | This differs from reg_genmove in the optional random seed. | |
4279 | ||
4280 | ||
4281 | * restricted_genmove: Generate the supposedly best move for either | |
4282 | color from a choice of allowed vertices. | |
4283 | Arguments: color to move, allowed vertices | |
4284 | Fails: invalid color, invalid vertex, no vertex listed | |
4285 | Returns: a move coordinate (or "PASS") | |
4286 | ||
4287 | ||
4288 | * kgs-genmove_cleanup: Generate and play the supposedly best move | |
4289 | for either color, not passing until all dead opponent stones have | |
4290 | been removed. | |
4291 | Arguments: color to move | |
4292 | Fails: invalid color | |
4293 | Returns: a move coordinate (or "PASS") | |
4294 | ||
4295 | Status: KGS specific command. | |
4296 | ||
4297 | A similar command, but possibly somewhat different, will likely be added | |
4298 | to GTP version 3 at a later time. | |
4299 | ||
4300 | ||
4301 | * level: Set the playing level. | |
4302 | Arguments: int | |
4303 | Fails: incorrect argument | |
4304 | Returns: nothing | |
4305 | ||
4306 | * undo: Undo one move | |
4307 | Arguments: none | |
4308 | Fails: If move history is too short. | |
4309 | Returns: nothing | |
4310 | ||
4311 | Status: GTP version 2 standard command. | |
4312 | ||
4313 | * gg-undo: Undo a number of moves | |
4314 | Arguments: optional int | |
4315 | Fails: If move history is too short. | |
4316 | Returns: nothing | |
4317 | ||
4318 | * time_settings: Set time allowance | |
4319 | Arguments: int main_time, int byo_yomi_time, int byo_yomi_stones | |
4320 | Fails: syntax error | |
4321 | Returns: nothing | |
4322 | ||
4323 | Status: GTP version 2 standard command. | |
4324 | ||
4325 | * time_left: Report remaining time | |
4326 | Arguments: color color, int time, int stones | |
4327 | Fails: syntax error | |
4328 | Returns: nothing | |
4329 | ||
4330 | Status: GTP version 2 standard command. | |
4331 | ||
4332 | ||
4333 | * final_score: Compute the score of a finished game. | |
4334 | Arguments: Optional random seed | |
4335 | Fails: never | |
4336 | Returns: Score in SGF format (RE property). | |
4337 | ||
4338 | Status: GTP version 2 standard command. | |
4339 | ||
4340 | ||
4341 | * final_status: Report the final status of a vertex in a finished | |
4342 | game. | |
4343 | Arguments: Vertex, optional random seed | |
4344 | Fails: invalid vertex | |
4345 | Returns: Status in the form of one of the strings "alive", "dead", | |
4346 | "seki", "white_territory", "black_territory", or "dame". | |
4347 | ||
4348 | ||
4349 | * final_status_list: Report vertices with a specific final status in | |
4350 | a finished game. | |
4351 | Arguments: Status in the form of one of the strings "alive", "dead", | |
4352 | "seki", "white_territory", "black_territory", or "dame". | |
4353 | An optional random seed can be added. | |
4354 | Fails: missing or invalid status string | |
4355 | Returns: Vertices having the specified status. These are split with | |
4356 | one string on each line if the vertices are nonempty (i.e. | |
4357 | for "alive", "dead", and "seki"). | |
4358 | ||
4359 | Status: GTP version 2 standard command. | |
4360 | However, "dame", "white_territory", and "black_territory" | |
4361 | are private extensions. | |
4362 | ||
4363 | * estimate_score: Estimate the score | |
4364 | Arguments: None | |
4365 | Fails: never | |
4366 | Returns: upper and lower bounds for the score | |
4367 | ||
4368 | * experimental_score: Estimate the score, taking into account which | |
4369 | player moves next | |
4370 | Arguments: Color to play | |
4371 | Fails: Invalid color | |
4372 | Returns: Score. | |
4373 | ||
4374 | This function generates a move for color, then adds the | |
4375 | value of the move generated to the value of the position. | |
4376 | Critical dragons are awarded to the opponent since the | |
4377 | value of rescuing a critical dragon is taken into account | |
4378 | in the value of the move generated. | |
4379 | ||
4380 | ||
4381 | * reset_life_node_counter: Reset the count of life nodes. | |
4382 | Arguments: none | |
4383 | Fails: never | |
4384 | Returns: nothing | |
4385 | ||
4386 | Note: This function is obsolete and only remains for backwards | |
4387 | compatibility. | |
4388 | ||
4389 | ||
4390 | * get_life_node_counter: Retrieve the count of life nodes. | |
4391 | Arguments: none | |
4392 | Fails: never | |
4393 | Returns: number of life nodes | |
4394 | ||
4395 | Note: This function is obsolete and only remains for backwards | |
4396 | compatibility. | |
4397 | ||
4398 | ||
4399 | * reset_owl_node_counter: Reset the count of owl nodes. | |
4400 | Arguments: none | |
4401 | Fails: never | |
4402 | Returns: nothing | |
4403 | ||
4404 | ||
4405 | * get_owl_node_counter: Retrieve the count of owl nodes. | |
4406 | Arguments: none | |
4407 | Fails: never | |
4408 | Returns: number of owl nodes | |
4409 | ||
4410 | ||
4411 | * reset_reading_node_counter: Reset the count of reading nodes. | |
4412 | Arguments: none | |
4413 | Fails: never | |
4414 | Returns: nothing | |
4415 | ||
4416 | ||
4417 | * get_reading_node_counter: Retrieve the count of reading nodes. | |
4418 | Arguments: none | |
4419 | Fails: never | |
4420 | Returns: number of reading nodes | |
4421 | ||
4422 | ||
4423 | * reset_trymove_counter: Reset the count of trymoves/trykos. | |
4424 | Arguments: none | |
4425 | Fails: never | |
4426 | Returns: nothing | |
4427 | ||
4428 | ||
4429 | * get_trymove_counter: Retrieve the count of trymoves/trykos. | |
4430 | Arguments: none | |
4431 | Fails: never | |
4432 | Returns: number of trymoves/trykos | |
4433 | ||
4434 | ||
4435 | * reset_connection_node_counter: Reset the count of connection nodes. | |
4436 | Arguments: none | |
4437 | Fails: never | |
4438 | Returns: nothing | |
4439 | ||
4440 | ||
4441 | * get_connection_node_counter: Retrieve the count of connection | |
4442 | nodes. | |
4443 | Arguments: none | |
4444 | Fails: never | |
4445 | Returns: number of connection nodes | |
4446 | ||
4447 | ||
4448 | * test_eyeshape: Test an eyeshape for inconsistent evaluations | |
4449 | Arguments: Eyeshape vertices | |
4450 | Fails: Bad vertices | |
4451 | Returns: Failure reports on stderr. | |
4452 | ||
4453 | ||
4454 | * analyze_eyegraph: Compute an eyevalue and vital points for an eye | |
4455 | graph | |
4456 | Arguments: Eyeshape encoded in string | |
4457 | Fails: Bad eyeshape, analysis failed | |
4458 | Returns: Eyevalue, vital points | |
4459 | ||
4460 | ||
4461 | * cputime: Returns elapsed CPU time in seconds. | |
4462 | Arguments: none | |
4463 | Fails: never | |
4464 | Returns: Total elapsed (user + system) CPU time in seconds. | |
4465 | ||
4466 | ||
4467 | * showboard: Write the position to stdout. | |
4468 | Arguments: none | |
4469 | Fails: never | |
4470 | Returns: nothing | |
4471 | ||
4472 | Status: GTP version 2 standard command. | |
4473 | ||
4474 | ||
4475 | * dump_stack: Dump stack to stderr. | |
4476 | Arguments: none | |
4477 | Fails: never | |
4478 | Returns: nothing | |
4479 | ||
4480 | ||
4481 | * initial_influence: Return information about the initial influence | |
4482 | function. | |
4483 | Arguments: color to move, what information | |
4484 | Fails: never | |
4485 | Returns: Influence data formatted like: | |
4486 | ||
4487 | 0.51 1.34 3.20 6.60 9.09 8.06 1.96 0.00 0.00 | |
4488 | 0.45 1.65 4.92 12.19 17.47 15.92 4.03 0.00 0.00 | |
4489 | . | |
4490 | . | |
4491 | . | |
4492 | 0.00 0.00 0.00 0.00 0.00 100.00 75.53 41.47 23.41 | |
4493 | ||
4494 | The available choices of information are: | |
4495 | ||
4496 | white_influence (float) | |
4497 | black_influence (float) | |
4498 | white_strength (float) | |
4499 | black_strength (float) | |
4500 | white_attenuation (float) | |
4501 | black_attenuation (float) | |
4502 | white_permeability (float) | |
4503 | black_permeability (float) | |
4504 | territory_value (float) | |
4505 | influence_regions (int) | |
4506 | non_territory (int) | |
4507 | ||
4508 | The encoding of influence_regions is as follows: | |
4509 | 4 white stone | |
4510 | 3 white territory | |
4511 | 2 white moyo | |
4512 | 1 white area | |
4513 | 0 neutral | |
4514 | -1 black area | |
4515 | -2 black moyo | |
4516 | -3 black territory | |
4517 | -4 black stone | |
4518 | ||
4519 | ||
4520 | * move_influence: Return information about the influence function | |
4521 | after a move. | |
4522 | Arguments: move, what information | |
4523 | Fails: never | |
4524 | Returns: Influence data formatted like for initial_influence. | |
4525 | ||
4526 | ||
4527 | * move_probabilities: List probabilities of each move being played | |
4528 | (when non-zero). If no previous genmove command has been issued, | |
4529 | the result of this command will be meaningless. | |
4530 | Arguments: none | |
4531 | Fails: never | |
4532 | Returns: Move, probabilty pairs, one per row. | |
4533 | ||
4534 | ||
4535 | * move_uncertainty: Return the number of bits of uncertainty in the | |
4536 | move. If no previous genmove command has been issued, the result | |
4537 | of this command will be meaningless. | |
4538 | Arguments: none | |
4539 | Fails: never | |
4540 | Returns: bits of uncertainty | |
4541 | ||
4542 | ||
4543 | * followup_influence: Return information about the followup | |
4544 | influence after a move. | |
4545 | Arguments: move, what information | |
4546 | Fails: never | |
4547 | Returns: Influence data formatted like for initial_influence. | |
4548 | ||
4549 | ||
4550 | * worm_data: Return the information in the worm data structure. | |
4551 | Arguments: optional vertex | |
4552 | Fails: never | |
4553 | Returns: Worm data formatted like: | |
4554 | ||
4555 | A19: | |
4556 | color black | |
4557 | size 10 | |
4558 | effective_size 17.83 | |
4559 | origin A19 | |
4560 | liberties 8 | |
4561 | liberties2 15 | |
4562 | liberties3 10 | |
4563 | liberties4 8 | |
4564 | attack PASS | |
4565 | attack_code 0 | |
4566 | lunch B19 | |
4567 | defend PASS | |
4568 | defend_code 0 | |
4569 | cutstone 2 | |
4570 | cutstone2 0 | |
4571 | genus 0 | |
4572 | inessential 0 | |
4573 | B19: | |
4574 | color white | |
4575 | . | |
4576 | . | |
4577 | . | |
4578 | inessential 0 | |
4579 | C19: | |
4580 | ... | |
4581 | ||
4582 | If an intersection is specified, only data for this one will be returned. | |
4583 | ||
4584 | ||
4585 | * worm_stones: List the stones of a worm | |
4586 | Arguments: the location, "BLACK" or "WHITE" | |
4587 | Fails: if called on an empty or off-board location | |
4588 | Returns: list of stones | |
4589 | ||
4590 | ||
4591 | * worm_cutstone: Return the cutstone field in the worm data | |
4592 | structure. | |
4593 | Arguments: non-empty vertex | |
4594 | Fails: never | |
4595 | Returns: cutstone | |
4596 | ||
4597 | ||
4598 | * dragon_data: Return the information in the dragon data structure. | |
4599 | Arguments: optional intersection | |
4600 | Fails: never | |
4601 | Returns: Dragon data formatted in the corresponding way to worm_data. | |
4602 | ||
4603 | ||
4604 | * dragon_stones: List the stones of a dragon | |
4605 | Arguments: the location | |
4606 | Fails: if called on an empty or off-board location | |
4607 | Returns: list of stones | |
4608 | ||
4609 | ||
4610 | * eye_data: Return the information in the eye data structure. | |
4611 | Arguments: color, vertex | |
4612 | Fails: never | |
4613 | Returns: eye data fields and values, one pair per row | |
4614 | ||
4615 | ||
4616 | * half_eye_data: Return the information in the half eye data | |
4617 | structure. | |
4618 | Arguments: vertex | |
4619 | Fails: never | |
4620 | Returns: half eye data fields and values, one pair per row | |
4621 | ||
4622 | ||
4623 | * start_sgftrace: Start storing moves executed during reading in an | |
4624 | sgf tree in memory. | |
4625 | Arguments: none | |
4626 | Fails: never | |
4627 | Returns: nothing | |
4628 | ||
4629 | Warning: You had better know what you're doing if you try to use this | |
4630 | command. | |
4631 | ||
4632 | ||
4633 | * finish_sgftrace: Finish storing moves in an sgf tree and write it | |
4634 | to file. | |
4635 | Arguments: filename | |
4636 | Fails: never | |
4637 | Returns: nothing | |
4638 | ||
4639 | Warning: You had better know what you're doing if you try to use this | |
4640 | command. | |
4641 | ||
4642 | ||
4643 | * printsgf: Dump the current position as a static sgf file to | |
4644 | filename, or as output if filename is missing or "-" | |
4645 | Arguments: optional filename | |
4646 | Fails: never | |
4647 | Returns: nothing if filename, otherwise the sgf | |
4648 | ||
4649 | ||
4650 | * tune_move_ordering: Tune the parameters for the move ordering in | |
4651 | the tactical reading. | |
4652 | Arguments: MOVE_ORDERING_PARAMETERS integers | |
4653 | Fails: incorrect arguments | |
4654 | Returns: nothing | |
4655 | ||
4656 | ||
4657 | * echo: Echo the parameter | |
4658 | Arguments: string | |
4659 | Fails: never | |
4660 | Returns: nothing | |
4661 | ||
4662 | ||
4663 | * echo_err: Echo the parameter to stdout AND stderr | |
4664 | Arguments: string | |
4665 | Fails: never | |
4666 | Returns: nothing | |
4667 | ||
4668 | ||
4669 | * help: List all known commands | |
4670 | Arguments: none | |
4671 | Fails: never | |
4672 | Returns: list of known commands, one per line | |
4673 | ||
4674 | Status: GTP version 2 standard command. | |
4675 | ||
4676 | ||
4677 | * known_command: Tell whether a command is known. | |
4678 | Arguments: command name | |
4679 | Fails: never | |
4680 | Returns: "true" if command exists, "false" if not | |
4681 | ||
4682 | Status: GTP version 2 standard command. | |
4683 | ||
4684 | ||
4685 | * report_uncertainty: Turn uncertainty reports from owl_attack and | |
4686 | owl_defend on or off. | |
4687 | Arguments: "on" or "off" | |
4688 | Fails: invalid argument | |
4689 | Returns: nothing | |
4690 | ||
4691 | ||
4692 | * get_random_seed: Get the random seed | |
4693 | Arguments: none | |
4694 | Fails: never | |
4695 | Returns: random seed | |
4696 | ||
4697 | ||
4698 | * set_random_seed: Set the random seed | |
4699 | Arguments: integer | |
4700 | Fails: invalid data | |
4701 | Returns: nothing | |
4702 | ||
4703 | ||
4704 | * advance_random_seed: Advance the random seed by a number of games. | |
4705 | Arguments: integer | |
4706 | Fails: invalid data | |
4707 | Returns: New random seed. | |
4708 | ||
4709 | ||
4710 | * is_surrounded: Determine if a dragon is surrounded | |
4711 | Arguments: vertex (dragon) | |
4712 | Fails: invalid vertex, empty vertex | |
4713 | Returns: 1 if surrounded, 2 if weakly surrounded, 0 if not | |
4714 | ||
4715 | ||
4716 | * does_surround: Determine if a move surrounds a dragon | |
4717 | Arguments: vertex (move), vertex (dragon) | |
4718 | Fails: invalid vertex, empty (dragon, nonempty (move) | |
4719 | Returns: 1 if (move) surrounds (dragon) | |
4720 | ||
4721 | * surround_map: Report the surround map for dragon at a vertex | |
4722 | Arguments: vertex (dragon), vertex (mapped location) | |
4723 | Fails: invalid vertex, empty dragon | |
4724 | Returns: value of surround map at (mapped location), or -1 if | |
4725 | dragon not surrounded. | |
4726 | ||
4727 | ||
4728 | * set_search_diamond: limit search, and establish a search diamond | |
4729 | Arguments: pos | |
4730 | Fails: invalid value | |
4731 | Returns: nothing | |
4732 | ||
4733 | ||
4734 | * reset_search_mask: unmark the entire board for limited search | |
4735 | Arguments: none | |
4736 | Fails: never | |
4737 | Returns: nothing | |
4738 | ||
4739 | ||
4740 | * limit_search: sets the global variable limit_search | |
4741 | Arguments: value | |
4742 | Fails: invalid arguments | |
4743 | Returns: nothing | |
4744 | ||
4745 | ||
4746 | * set_search_limit: mark a vertex for limited search | |
4747 | Arguments: position | |
4748 | Fails: invalid arguments | |
4749 | Returns: nothing | |
4750 | ||
4751 | ||
4752 | * draw_search_area: Draw search area. Writes to stderr. | |
4753 | Arguments: none | |
4754 | Fails: never | |
4755 | Returns: nothing | |
4756 | ||
4757 | \1f | |
4758 | File: gnugo.info, Node: Regression, Next: Copying, Prev: GTP, Up: Top | |
4759 | ||
4760 | 20 Regression testing | |
4761 | ********************* | |
4762 | ||
4763 | The standard purpose of regression testing is to avoid getting the same | |
4764 | bug twice. When a bug is found, the programmer fixes the bug and adds a | |
4765 | test to the test suite. The test should fail before the fix and pass | |
4766 | after the fix. When a new version is about to be released, all the tests | |
4767 | in the regression test suite are run and if an old bug reappears, this | |
4768 | will be seen quickly since the appropriate test will fail. | |
4769 | ||
4770 | The regression testing in GNU Go is slightly different. A typical | |
4771 | test case involves specifying a position and asking the engine what | |
4772 | move it would make. This is compared to one or more correct moves to | |
4773 | decide whether the test case passes or fails. It is also stored whether | |
4774 | a test case is expected to pass or fail, and deviations in this status | |
4775 | signify whether a change has solved some problem and/or broken something | |
4776 | else. Thus the regression tests both include positions highlighting some | |
4777 | mistake being done by the engine, which are waiting to be fixed, and | |
4778 | positions where the engine does the right thing, where we want to detect | |
4779 | if a change breaks something. | |
4780 | ||
4781 | * Menu: | |
4782 | ||
4783 | * Regression Testing:: Regression Testing in GNU Go | |
4784 | * Test Suites:: Test Suites | |
4785 | * Running the Regressions:: Running the Regression Tests | |
4786 | * Running regress.pike:: Running regress.pike | |
4787 | * Viewing with Emacs:: Viewing tests with Emacs | |
4788 | * HTML Views:: HTML Views | |
4789 | ||
4790 | \1f | |
4791 | File: gnugo.info, Node: Regression Testing, Next: Test Suites, Up: Regression | |
4792 | ||
4793 | 20.1 Regression testing in GNU Go | |
4794 | ================================= | |
4795 | ||
4796 | Regression testing is performed by the files in the `regression/' | |
4797 | directory. The tests are specified as GTP commands in files with the | |
4798 | suffix `.tst', with corresponding correct results and expected | |
4799 | pass/fail status encoded in GTP comments following the test. To run a | |
4800 | test suite the shell scripts `test.sh', `eval.sh', and `regress.sh' can | |
4801 | be used. There are also Makefile targets to do this. If you `make | |
4802 | all_batches' most of the tests are run. The Pike script `regress.pike' | |
4803 | can also be used to run all tests or a subset of the tests. | |
4804 | ||
4805 | Game records used by the regression tests are stored in the | |
4806 | directory `regression/games/' and its subdirectories. | |
4807 | ||
4808 | \1f | |
4809 | File: gnugo.info, Node: Test Suites, Next: Running the Regressions, Prev: Regression Testing, Up: Regression | |
4810 | ||
4811 | 20.2 Test suites | |
4812 | ================ | |
4813 | ||
4814 | The regression tests are grouped into suites and stored in files as GTP | |
4815 | commands. A part of a test suite can look as follows: | |
4816 | # Connecting with ko at B14 looks best. Cutting at D17 might be | |
4817 | # considered. B17 (game move) is inferior. | |
4818 | loadsgf games/strategy25.sgf 61 | |
4819 | 90 gg_genmove black | |
4820 | #? [B14|D17] | |
4821 | ||
4822 | # The game move at P13 is a suicidal blunder. | |
4823 | loadsgf games/strategy25.sgf 249 | |
4824 | 95 gg_genmove black | |
4825 | #? [!P13] | |
4826 | ||
4827 | loadsgf games/strategy26.sgf 257 | |
4828 | 100 gg_genmove black | |
4829 | #? [M16]* | |
4830 | ||
4831 | Lines starting with a hash sign, or in general anything following a | |
4832 | hash sign, are interpreted as comments by the GTP mode and thus ignored | |
4833 | by the engine. GTP commands are executed in the order they appear, but | |
4834 | only those on numbered lines are used for testing. The comment lines | |
4835 | starting with `#?' are magical to the regression testing scripts and | |
4836 | indicate correct results and expected pass/fail status. The string | |
4837 | within brackets is matched as a regular expression against the response | |
4838 | from the previous numbered GTP command. A particular useful feature of | |
4839 | regular expressions is that by using `|' it is possible to specify | |
4840 | alternatives. Thus `B14|D17' above means that if either `B14' or `D17' | |
4841 | is the move generated in test case 90, it passes. There is one | |
4842 | important special case to be aware of. If the correct result string | |
4843 | starts with an exclamation mark, this is excluded from the regular | |
4844 | expression but afterwards the result of the matching is negated. Thus | |
4845 | `!P13' in test case 95 means that any move except `P13' is accepted as | |
4846 | a correct result. | |
4847 | ||
4848 | In test case 100, the brackets on the `#?' line is followed by an | |
4849 | asterisk. This means that the test is expected to fail. If there is no | |
4850 | asterisk, the test is expected to pass. The brackets may also be | |
4851 | followed by a `&', meaning that the result is ignored. This is | |
4852 | primarily used to report statistics, e.g. how many tactical reading | |
4853 | nodes were spent while running the test suite. | |
4854 | ||
4855 | \1f | |
4856 | File: gnugo.info, Node: Running the Regressions, Next: Running regress.pike, Prev: Test Suites, Up: Regression | |
4857 | ||
4858 | 20.3 Running the Regression Tests | |
4859 | ================================= | |
4860 | ||
4861 | `./test.sh blunder.tst' runs the tests in `blunder.tst' and prints the | |
4862 | results of the commands on numbered lines, which may look like: | |
4863 | ||
4864 | 1 E5 | |
4865 | 2 F9 | |
4866 | 3 O18 | |
4867 | 4 B7 | |
4868 | 5 A4 | |
4869 | 6 E4 | |
4870 | 7 E3 | |
4871 | 8 A3 | |
4872 | 9 D9 | |
4873 | 10 J9 | |
4874 | 11 B3 | |
4875 | 12 C6 | |
4876 | 13 C6 | |
4877 | ||
4878 | This is usually not very informative, however. More interesting is | |
4879 | `./eval.sh blunder.tst' which also compares the results above against | |
4880 | the correct ones in the test file and prints a report for each test on | |
4881 | the form: | |
4882 | ||
4883 | 1 failed: Correct '!E5', got 'E5' | |
4884 | 2 failed: Correct 'C9|H9', got 'F9' | |
4885 | 3 PASSED | |
4886 | 4 failed: Correct 'B5|C5|C4|D4|E4|E3|F3', got 'B7' | |
4887 | 5 PASSED | |
4888 | 6 failed: Correct 'D4', got 'E4' | |
4889 | 7 PASSED | |
4890 | 8 failed: Correct 'B4', got 'A3' | |
4891 | 9 failed: Correct 'G8|G9|H8', got 'D9' | |
4892 | 10 failed: Correct 'G9|F9|C7', got 'J9' | |
4893 | 11 failed: Correct 'D4|E4|E5|F4|C6', got 'B3' | |
4894 | 12 failed: Correct 'D4', got 'C6' | |
4895 | 13 failed: Correct 'D4|E4|E5|F4', got 'C6' | |
4896 | ||
4897 | The result of a test can be one of four different cases: | |
4898 | ||
4899 | * `passed': An expected pass | |
4900 | ||
4901 | This is the ideal result. | |
4902 | ||
4903 | * `PASSED': An unexpected pass | |
4904 | ||
4905 | This is a result that we are hoping for when we fix a bug. An old | |
4906 | test case that used to fail is now passing. | |
4907 | ||
4908 | * `failed': An expected failure | |
4909 | ||
4910 | The test failed but this was also what we expected, unless we were | |
4911 | trying to fix the particular mistake highlighted by the test case. | |
4912 | These tests show weaknesses of the GNU Go engine and are good | |
4913 | places to search if you want to detect an area which needs | |
4914 | improvement. | |
4915 | ||
4916 | * `FAILED': An unexpected failure | |
4917 | ||
4918 | This should nominally only happen if something is broken by a | |
4919 | change. However, sometimes GNU Go passes a test, but for the wrong | |
4920 | reason or for a combination of wrong reasons. When one of these | |
4921 | reasons is fixed, the other one may shine through so that the test | |
4922 | suddenly fails. When a test case unexpectedly fails, it is | |
4923 | necessary to make a closer examination in order to determine | |
4924 | whether a change has broken something. | |
4925 | ||
4926 | ||
4927 | If you want a less verbose report, `./regress.sh . blunder.tst' does | |
4928 | the same thing as the previous command, but only reports unexpected | |
4929 | results. The example above is compressed to | |
4930 | ||
4931 | 3 unexpected PASS! | |
4932 | 5 unexpected PASS! | |
4933 | 7 unexpected PASS! | |
4934 | ||
4935 | For convenience the tests are also available as makefile targets. For | |
4936 | example, `make blunder' runs the tests in the blunder test suite by | |
4937 | executing `eval.sh blunder.tst'. `make all_batches' runs all test | |
4938 | suites in a sequence using the `regress.sh' script. | |
4939 | ||
4940 | \1f | |
4941 | File: gnugo.info, Node: Running regress.pike, Next: Viewing with Emacs, Prev: Running the Regressions, Up: Regression | |
4942 | ||
4943 | 20.4 Running regress.pike | |
4944 | ========================= | |
4945 | ||
4946 | A more powerful way to run regressions is with the script | |
4947 | `regress.pike'. This requires that you have Pike | |
4948 | (`http://pike.ida.liu.se') installed. | |
4949 | ||
4950 | Executing `./regress.pike' without arguments will run all testsuites | |
4951 | that `make all_batches' would run. The difference is that unexpected | |
4952 | results are reported immediately when they have been found (instead of | |
4953 | after the whole file has been run) and that statistics of time | |
4954 | consumption and node usage is presented for each test file and in total. | |
4955 | ||
4956 | To run a single test suite do e.g. `./regress.pike nicklas3.tst' or | |
4957 | `./regress.pike nicklas3'. The result may look like: | |
4958 | nicklas3 2.96 614772 3322 469 | |
4959 | Total nodes: 614772 3322 469 | |
4960 | Total time: 2.96 (3.22) | |
4961 | Total uncertainty: 0.00 | |
4962 | The numbers here mean that the test suite took 2.96 seconds of | |
4963 | processor time and 3.22 seconds of real time. The consumption of | |
4964 | reading nodes was 614772 for tactical reading, 3322 for owl reading, | |
4965 | and 469 for connection reading. The last line relates to the | |
4966 | variability of the generated moves in the test suite, and 0 means that | |
4967 | none was decided by the randomness contribution to the move valuation. | |
4968 | Multiple testsuites can be run by e.g. `./regress.pike owl ld_owl owl1'. | |
4969 | ||
4970 | It is also possible to run a single testcase, e.g. `./regress.pike | |
4971 | strategy:6', a number of testcases, e.g. `./regress.pike | |
4972 | strategy:6,23,45', a range of testcases, e.g. `./regress.pike | |
4973 | strategy:13-15' or more complex combinations e.g. `./regress.pike | |
4974 | strategy:6,13-15,23,45 nicklas3:602,1403'. | |
4975 | ||
4976 | There are also command line options to choose what engine to run, | |
4977 | what options to send to the engine, to turn on verbose output, and to | |
4978 | use a file to specify which testcases to run. Run `./regress.pike | |
4979 | --help' for a complete and up to date list of options. | |
4980 | ||
4981 | \1f | |
4982 | File: gnugo.info, Node: Viewing with Emacs, Next: HTML Views, Prev: Running regress.pike, Up: Regression | |
4983 | ||
4984 | 20.5 Viewing tests with Emacs | |
4985 | ============================= | |
4986 | ||
4987 | To get a quick regression view, you may use the graphical display mode | |
4988 | available with Emacs (*note Emacs::). You will want the cursor in the | |
4989 | regression buffer when you enter `M-x gnugo', so that GNU Go opens in | |
4990 | the correct directory. A good way to be in the right directory is to | |
4991 | open the window of the test you want to investigate. Then you can cut | |
4992 | and past GTP commands directly from the test to the minibuffer, using | |
4993 | the `:' command from Emacs. Although Emacs mode does not have a | |
4994 | coordinate grid, you may get an ascii board with the coordinate grid | |
4995 | using `: showboard' command. | |
4996 | ||
4997 | \1f | |
4998 | File: gnugo.info, Node: HTML Views, Prev: Viewing with Emacs, Up: Regression | |
4999 | ||
5000 | 20.6 HTML Regression Views | |
5001 | ========================== | |
5002 | ||
5003 | Extremely useful HTML Views of the regression tests may be produced | |
5004 | using two perl scripts `regression/regress.pl' and | |
5005 | `regression/regress.plx'. | |
5006 | ||
5007 | 1. The driver program (regress.pl) which: | |
5008 | * Runs the regression tests, invoking GNU Go. | |
5009 | ||
5010 | * Captures the trace output, board position, and pass/fail | |
5011 | status, sgf output, and dragon status information. | |
5012 | ||
5013 | 2. The interface to view the captured output (regress.plx) which: | |
5014 | * Never invokes GNU Go. | |
5015 | ||
5016 | * Displays the captured output in helpful formats (i.e. HTML). | |
5017 | ||
5018 | 20.6.1 Setting up the HTML regression Views | |
5019 | ------------------------------------------- | |
5020 | ||
5021 | There are many ways configuring Apache to permit CGI scripts, all of | |
5022 | them are featured in Apache documentation, which can be found at | |
5023 | `http://httpd.apache.org/docs/2.0/howto/cgi.html' | |
5024 | ||
5025 | Below you will find one example. | |
5026 | ||
5027 | This documentation assumes an Apache 2.0 included in Fedora Core | |
5028 | distribution, but it should be fairly close to the config for other | |
5029 | distributions. | |
5030 | ||
5031 | First, you will need to configure Apache to run CGI scripts in the | |
5032 | directory you wish to serve the html views from. In | |
5033 | `/etc/httpd/conf/httpd.conf' there should be a line: | |
5034 | ||
5035 | `DocumentRoot "/var/www/html"' | |
5036 | ||
5037 | Search for a line `<Directory "/path/to/directory">', where | |
5038 | `/path/to/directory' is the same as provided in `DocumentRoot', then | |
5039 | add `ExecCGI' to list of `Options'. The whole section should look like: | |
5040 | ||
5041 | <Directory "/var/www/html"> | |
5042 | ... | |
5043 | Options ... ExecCGI | |
5044 | ... | |
5045 | </Directory> | |
5046 | ||
5047 | This allows CGI scripts to be executed in the directory used by | |
5048 | regress.plx. Next, you need to tell Apache that `.plx' is a CGI script | |
5049 | ending. Your `httpd.conf' file should contain a line: | |
5050 | ||
5051 | `AddHandler cgi-script ...' | |
5052 | ||
5053 | If there isn't already, add it; add `.plx' to the list of extensions, | |
5054 | so line should look like: | |
5055 | ||
5056 | `AddHandler cgi-script ... .plx' | |
5057 | ||
5058 | You will also need to make sure you have the necessary modules | |
5059 | loaded to run CGI scripts; mod_cgi and mod_mime should be sufficient. | |
5060 | Your `httpd.conf' should have the relevant `LoadModule cgi_module | |
5061 | modules/mod_cgi.so' and `LoadModule mime_module modules/mod_mime.so' | |
5062 | lines; uncomment them if necessary. | |
5063 | ||
5064 | Next, you need to put a copy of `regress.plx' in the `DocumentRoot' | |
5065 | directory `/var/www/html' or it subdirectories where you plan to serve | |
5066 | the html views from. | |
5067 | ||
5068 | You will also need to install the Perl module GD | |
5069 | (`http://search.cpan.org/dist/GD/'), available from CPAN. | |
5070 | ||
5071 | Finally, run `regression/regress.pl' to create the xml data used to | |
5072 | generate the html views (to do all regression tests run | |
5073 | `regression/regress.pl -a 1'); then, copy the `html/' directory to the | |
5074 | same directory as `regress.plx' resides in. | |
5075 | ||
5076 | At this point, you should have a working copy of the html regression | |
5077 | views. | |
5078 | ||
5079 | Additional notes for Debian users: The Perl GD module can be | |
5080 | installed by `apt-get install libgd-perl'. It may suffice to add this to | |
5081 | the apache2 configuration: | |
5082 | ||
5083 | <Directory "/var/www/regression"> | |
5084 | Options +ExecCGI | |
5085 | AddHandler cgi-script .plx | |
5086 | RedirectMatch ^/regression$ /regression/regress.plx | |
5087 | </Directory> | |
5088 | ||
5089 | and then make a link from `/var/www/regression' to the GNU Go | |
5090 | regression directory. The `RedirectMatch' statement is only needed to | |
5091 | set up a shorter entry URL. | |
5092 | ||
5093 | \1f | |
5094 | File: gnugo.info, Node: Copying, Next: Concept Index, Prev: Regression, Up: Top | |
5095 | ||
5096 | Appendix A Copying | |
5097 | ****************** | |
5098 | ||
5099 | The program GNU Go is distributed under the terms of the GNU General | |
5100 | Public License (GPL). Its documentation is distributed under the terms | |
5101 | of the GNU Free Documentation License (GFDL). | |
5102 | ||
5103 | * Menu: | |
5104 | ||
5105 | * GPL:: The GNU General Public License | |
5106 | * GFDL:: The GNU Free Documentation License | |
5107 | * GTP License:: The Go Text Protocol License | |
5108 | ||
5109 | \1f | |
5110 | File: gnugo.info, Node: GPL, Next: GFDL, Prev: Copying, Up: Copying | |
5111 | ||
5112 | A.1 GNU GENERAL PUBLIC LICENSE | |
5113 | ============================== | |
5114 | ||
5115 | Version 3, 29 June 2007 | |
5116 | ||
5117 | Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> | |
5118 | Everyone is permitted to copy and distribute verbatim copies | |
5119 | of this license document, but changing it is not allowed. | |
5120 | ||
5121 | Preamble | |
5122 | ======== | |
5123 | ||
5124 | The GNU General Public License is a free, copyleft license for software | |
5125 | and other kinds of works. | |
5126 | ||
5127 | The licenses for most software and other practical works are designed | |
5128 | to take away your freedom to share and change the works. By contrast, | |
5129 | the GNU General Public License is intended to guarantee your freedom to | |
5130 | share and change all versions of a program-to make sure it remains free | |
5131 | software for all its users. We, the Free Software Foundation, use the | |
5132 | GNU General Public License for most of our software; it applies also to | |
5133 | any other work released this way by its authors. You can apply it to | |
5134 | your programs, too. | |
5135 | ||
5136 | When we speak of free software, we are referring to freedom, not | |
5137 | price. Our General Public Licenses are designed to make sure that you | |
5138 | have the freedom to distribute copies of free software (and charge for | |
5139 | them if you wish), that you receive source code or can get it if you | |
5140 | want it, that you can change the software or use pieces of it in new | |
5141 | free programs, and that you know you can do these things. | |
5142 | ||
5143 | To protect your rights, we need to prevent others from denying you | |
5144 | these rights or asking you to surrender the rights. Therefore, you have | |
5145 | certain responsibilities if you distribute copies of the software, or if | |
5146 | you modify it: responsibilities to respect the freedom of others. | |
5147 | ||
5148 | For example, if you distribute copies of such a program, whether | |
5149 | gratis or for a fee, you must pass on to the recipients the same | |
5150 | freedoms that you received. You must make sure that they, too, receive | |
5151 | or can get the source code. And you must show them these terms so they | |
5152 | know their rights. | |
5153 | ||
5154 | Developers that use the GNU GPL protect your rights with two steps: | |
5155 | (1) assert copyright on the software, and (2) offer you this License | |
5156 | giving you legal permission to copy, distribute and/or modify it. | |
5157 | ||
5158 | For the developers' and authors' protection, the GPL clearly explains | |
5159 | that there is no warranty for this free software. For both users' and | |
5160 | authors' sake, the GPL requires that modified versions be marked as | |
5161 | changed, so that their problems will not be attributed erroneously to | |
5162 | authors of previous versions. | |
5163 | ||
5164 | Some devices are designed to deny users access to install or run | |
5165 | modified versions of the software inside them, although the manufacturer | |
5166 | can do so. This is fundamentally incompatible with the aim of | |
5167 | protecting users' freedom to change the software. The systematic | |
5168 | pattern of such abuse occurs in the area of products for individuals to | |
5169 | use, which is precisely where it is most unacceptable. Therefore, we | |
5170 | have designed this version of the GPL to prohibit the practice for those | |
5171 | products. If such problems arise substantially in other domains, we | |
5172 | stand ready to extend this provision to those domains in future versions | |
5173 | of the GPL, as needed to protect the freedom of users. | |
5174 | ||
5175 | Finally, every program is threatened constantly by software patents. | |
5176 | States should not allow patents to restrict development and use of | |
5177 | software on general-purpose computers, but in those that do, we wish to | |
5178 | avoid the special danger that patents applied to a free program could | |
5179 | make it effectively proprietary. To prevent this, the GPL assures that | |
5180 | patents cannot be used to render the program non-free. | |
5181 | ||
5182 | The precise terms and conditions for copying, distribution and | |
5183 | modification follow. | |
5184 | ||
5185 | TERMS AND CONDITIONS | |
5186 | 0. DEFINITIONS | |
5187 | ||
5188 | "This License" refers to version 3 of the GNU General Public | |
5189 | License. | |
5190 | ||
5191 | "Copyright" also means copyright-like laws that apply to other | |
5192 | kinds of works, such as semiconductor masks. | |
5193 | ||
5194 | "The Program" refers to any copyrightable work licensed under this | |
5195 | License. Each licensee is addressed as "you". "Licensees" and | |
5196 | "recipients" may be individuals or organizations. | |
5197 | ||
5198 | To "modify" a work means to copy from or adapt all or part of the | |
5199 | work in a fashion requiring copyright permission, other than the | |
5200 | making of an exact copy. The resulting work is called a "modified | |
5201 | version" of the earlier work or a work "based on" the earlier work. | |
5202 | ||
5203 | A "covered work" means either the unmodified Program or a work | |
5204 | based on the Program. | |
5205 | ||
5206 | To "propagate" a work means to do anything with it that, without | |
5207 | permission, would make you directly or secondarily liable for | |
5208 | infringement under applicable copyright law, except executing it | |
5209 | on a computer or modifying a private copy. Propagation includes | |
5210 | copying, distribution (with or without modification), making | |
5211 | available to the public, and in some countries other activities as | |
5212 | well. | |
5213 | ||
5214 | To "convey" a work means any kind of propagation that enables other | |
5215 | parties to make or receive copies. Mere interaction with a user | |
5216 | through a computer network, with no transfer of a copy, is not | |
5217 | conveying. | |
5218 | ||
5219 | An interactive user interface displays "Appropriate Legal Notices" | |
5220 | to the extent that it includes a convenient and prominently visible | |
5221 | feature that (1) displays an appropriate copyright notice, and (2) | |
5222 | tells the user that there is no warranty for the work (except to | |
5223 | the extent that warranties are provided), that licensees may | |
5224 | convey the work under this License, and how to view a copy of this | |
5225 | License. If the interface presents a list of user commands or | |
5226 | options, such as a menu, a prominent item in the list meets this | |
5227 | criterion. | |
5228 | ||
5229 | ||
5230 | 1. SOURCE CODE | |
5231 | ||
5232 | The "source code" for a work means the preferred form of the work | |
5233 | for making modifications to it. "Object code" means any non-source | |
5234 | form of a work. | |
5235 | ||
5236 | A "Standard Interface" means an interface that either is an | |
5237 | official standard defined by a recognized standards body, or, in | |
5238 | the case of interfaces specified for a particular programming | |
5239 | language, one that is widely used among developers working in that | |
5240 | language. | |
5241 | ||
5242 | The "System Libraries" of an executable work include anything, | |
5243 | other than the work as a whole, that (a) is included in the normal | |
5244 | form of packaging a Major Component, but which is not part of that | |
5245 | Major Component, and (b) serves only to enable use of the work | |
5246 | with that Major Component, or to implement a Standard Interface | |
5247 | for which an implementation is available to the public in source | |
5248 | code form. A "Major Component", in this context, means a major | |
5249 | essential component (kernel, window system, and so on) of the | |
5250 | specific operating system (if any) on which the executable work | |
5251 | runs, or a compiler used to produce the work, or an object code | |
5252 | interpreter used to run it. | |
5253 | ||
5254 | The "Corresponding Source" for a work in object code form means all | |
5255 | the source code needed to generate, install, and (for an executable | |
5256 | work) run the object code and to modify the work, including | |
5257 | scripts to control those activities. However, it does not include | |
5258 | the work's System Libraries, or general-purpose tools or generally | |
5259 | available free programs which are used unmodified in performing | |
5260 | those activities but which are not part of the work. For example, | |
5261 | Corresponding Source includes interface definition files | |
5262 | associated with source files for the work, and the source code for | |
5263 | shared libraries and dynamically linked subprograms that the work | |
5264 | is specifically designed to require, such as by intimate data | |
5265 | communication or control flow between those subprograms and other | |
5266 | parts of the work. | |
5267 | ||
5268 | The Corresponding Source need not include anything that users can | |
5269 | regenerate automatically from other parts of the Corresponding | |
5270 | Source. | |
5271 | ||
5272 | The Corresponding Source for a work in source code form is that | |
5273 | same work. | |
5274 | ||
5275 | ||
5276 | 2. BASIC PERMISSIONS | |
5277 | ||
5278 | All rights granted under this License are granted for the term of | |
5279 | copyright on the Program, and are irrevocable provided the stated | |
5280 | conditions are met. This License explicitly affirms your unlimited | |
5281 | permission to run the unmodified Program. The output from running | |
5282 | a covered work is covered by this License only if the output, | |
5283 | given its content, constitutes a covered work. This License | |
5284 | acknowledges your rights of fair use or other equivalent, as | |
5285 | provided by copyright law. | |
5286 | ||
5287 | You may make, run and propagate covered works that you do not | |
5288 | convey, without conditions so long as your license otherwise | |
5289 | remains in force. You may convey covered works to others for the | |
5290 | sole purpose of having them make modifications exclusively for | |
5291 | you, or provide you with facilities for running those works, | |
5292 | provided that you comply with the terms of this License in | |
5293 | conveying all material for which you do not control copyright. | |
5294 | Those thus making or running the covered works for you must do so | |
5295 | exclusively on your behalf, under your direction and control, on | |
5296 | terms that prohibit them from making any copies of your | |
5297 | copyrighted material outside their relationship with you. | |
5298 | ||
5299 | Conveying under any other circumstances is permitted solely under | |
5300 | the conditions stated below. Sublicensing is not allowed; section | |
5301 | 10 makes it unnecessary. | |
5302 | ||
5303 | ||
5304 | 3. PROTECTING USERS' LEGAL RIGHTS FROM ANTI-CIRCUMVENTION LAW | |
5305 | ||
5306 | No covered work shall be deemed part of an effective technological | |
5307 | measure under any applicable law fulfilling obligations under | |
5308 | article 11 of the WIPO copyright treaty adopted on 20 December | |
5309 | 1996, or similar laws prohibiting or restricting circumvention of | |
5310 | such measures. | |
5311 | ||
5312 | When you convey a covered work, you waive any legal power to forbid | |
5313 | circumvention of technological measures to the extent such | |
5314 | circumvention is effected by exercising rights under this License | |
5315 | with respect to the covered work, and you disclaim any intention | |
5316 | to limit operation or modification of the work as a means of | |
5317 | enforcing, against the work's users, your or third parties' legal | |
5318 | rights to forbid circumvention of technological measures. | |
5319 | ||
5320 | ||
5321 | 4. CONVEYING VERBATIM COPIES | |
5322 | ||
5323 | You may convey verbatim copies of the Program's source code as you | |
5324 | receive it, in any medium, provided that you conspicuously and | |
5325 | appropriately publish on each copy an appropriate copyright notice; | |
5326 | keep intact all notices stating that this License and any | |
5327 | non-permissive terms added in accord with section 7 apply to the | |
5328 | code; keep intact all notices of the absence of any warranty; and | |
5329 | give all recipients a copy of this License along with the Program. | |
5330 | ||
5331 | You may charge any price or no price for each copy that you convey, | |
5332 | and you may offer support or warranty protection for a fee. | |
5333 | ||
5334 | ||
5335 | 5. CONVEYING MODIFIED SOURCE VERSIONS | |
5336 | ||
5337 | You may convey a work based on the Program, or the modifications to | |
5338 | produce it from the Program, in the form of source code under the | |
5339 | terms of section 4, provided that you also meet all of these | |
5340 | conditions: | |
5341 | ||
5342 | a) The work must carry prominent notices stating that you modified | |
5343 | it, and giving a relevant date. | |
5344 | ||
5345 | b) The work must carry prominent notices stating that it is | |
5346 | released under this License and any conditions added under section | |
5347 | 7. This requirement modifies the requirement in section 4 to | |
5348 | "keep intact all notices". | |
5349 | ||
5350 | c) You must license the entire work, as a whole, under this | |
5351 | License to anyone who comes into possession of a copy. This | |
5352 | License will therefore apply, along with any applicable section 7 | |
5353 | additional terms, to the whole of the work, and all its parts, | |
5354 | regardless of how they are packaged. This License gives no | |
5355 | permission to license the work in any other way, but it does not | |
5356 | invalidate such permission if you have separately received it. | |
5357 | ||
5358 | d) If the work has interactive user interfaces, each must display | |
5359 | Appropriate Legal Notices; however, if the Program has | |
5360 | interactive interfaces that do not display Appropriate Legal | |
5361 | Notices, your work need not make them do so. | |
5362 | ||
5363 | A compilation of a covered work with other separate and independent | |
5364 | works, which are not by their nature extensions of the covered | |
5365 | work, and which are not combined with it such as to form a larger | |
5366 | program, in or on a volume of a storage or distribution medium, is | |
5367 | called an "aggregate" if the compilation and its resulting | |
5368 | copyright are not used to limit the access or legal rights of the | |
5369 | compilation's users beyond what the individual works permit. | |
5370 | Inclusion of a covered work in an aggregate does not cause this | |
5371 | License to apply to the other parts of the aggregate. | |
5372 | ||
5373 | ||
5374 | 6. CONVEYING NON-SOURCE FORMS | |
5375 | ||
5376 | You may convey a covered work in object code form under the terms | |
5377 | of sections 4 and 5, provided that you also convey the | |
5378 | machine-readable Corresponding Source under the terms of this | |
5379 | License, in one of these ways: | |
5380 | ||
5381 | a) Convey the object code in, or embodied in, a physical product | |
5382 | (including a physical distribution medium), accompanied by the | |
5383 | Corresponding Source fixed on a durable physical medium | |
5384 | customarily used for software interchange. | |
5385 | ||
5386 | b) Convey the object code in, or embodied in, a physical product | |
5387 | (including a physical distribution medium), accompanied by a | |
5388 | written offer, valid for at least three years and valid for as | |
5389 | long as you offer spare parts or customer support for that product | |
5390 | model, to give anyone who possesses the object code either (1) a | |
5391 | copy of the Corresponding Source for all the software in the | |
5392 | product that is covered by this License, on a durable physical | |
5393 | medium customarily used for software interchange, for a price no | |
5394 | more than your reasonable cost of physically performing this | |
5395 | conveying of source, or (2) access to copy the Corresponding | |
5396 | Source from a network server at no charge. | |
5397 | ||
5398 | c) Convey individual copies of the object code with a copy of the | |
5399 | written offer to provide the Corresponding Source. This | |
5400 | alternative is allowed only occasionally and noncommercially, and | |
5401 | only if you received the object code with such an offer, in | |
5402 | accord with subsection 6b. | |
5403 | ||
5404 | d) Convey the object code by offering access from a designated | |
5405 | place (gratis or for a charge), and offer equivalent access to the | |
5406 | Corresponding Source in the same way through the same place at | |
5407 | no further charge. You need not require recipients to copy the | |
5408 | Corresponding Source along with the object code. If the place | |
5409 | to copy the object code is a network server, the Corresponding | |
5410 | Source may be on a different server (operated by you or a | |
5411 | third party) that supports equivalent copying facilities, | |
5412 | provided you maintain clear directions next to the object code | |
5413 | saying where to find the Corresponding Source. Regardless of | |
5414 | what server hosts the Corresponding Source, you remain | |
5415 | obligated to ensure that it is available for as long as needed | |
5416 | to satisfy these requirements. | |
5417 | ||
5418 | e) Convey the object code using peer-to-peer transmission, provided | |
5419 | you inform other peers where the object code and Corresponding | |
5420 | Source of the work are being offered to the general public at no | |
5421 | charge under subsection 6d. | |
5422 | ||
5423 | A separable portion of the object code, whose source code is | |
5424 | excluded from the Corresponding Source as a System Library, need | |
5425 | not be included in conveying the object code work. | |
5426 | ||
5427 | A "User Product" is either (1) a "consumer product", which means | |
5428 | any tangible personal property which is normally used for | |
5429 | personal, family, or household purposes, or (2) anything designed | |
5430 | or sold for incorporation into a dwelling. In determining whether | |
5431 | a product is a consumer product, doubtful cases shall be resolved | |
5432 | in favor of coverage. For a particular product received by a | |
5433 | particular user, "normally used" refers to a typical or common use | |
5434 | of that class of product, regardless of the status of the | |
5435 | particular user or of the way in which the particular user | |
5436 | actually uses, or expects or is expected to use, the product. A | |
5437 | product is a consumer product regardless of whether the product | |
5438 | has substantial commercial, industrial or non-consumer uses, | |
5439 | unless such uses represent the only significant mode of use of the | |
5440 | product. | |
5441 | ||
5442 | "Installation Information" for a User Product means any methods, | |
5443 | procedures, authorization keys, or other information required to | |
5444 | install and execute modified versions of a covered work in that | |
5445 | User Product from a modified version of its Corresponding Source. | |
5446 | The information must suffice to ensure that the continued | |
5447 | functioning of the modified object code is in no case prevented or | |
5448 | interfered with solely because modification has been made. | |
5449 | ||
5450 | If you convey an object code work under this section in, or with, | |
5451 | or specifically for use in, a User Product, and the conveying | |
5452 | occurs as part of a transaction in which the right of possession | |
5453 | and use of the User Product is transferred to the recipient in | |
5454 | perpetuity or for a fixed term (regardless of how the transaction | |
5455 | is characterized), the Corresponding Source conveyed under this | |
5456 | section must be accompanied by the Installation Information. But | |
5457 | this requirement does not apply if neither you nor any third party | |
5458 | retains the ability to install modified object code on the User | |
5459 | Product (for example, the work has been installed in ROM). | |
5460 | ||
5461 | The requirement to provide Installation Information does not | |
5462 | include a requirement to continue to provide support service, | |
5463 | warranty, or updates for a work that has been modified or | |
5464 | installed by the recipient, or for the User Product in which it | |
5465 | has been modified or installed. Access to a network may be denied | |
5466 | when the modification itself materially and adversely affects the | |
5467 | operation of the network or violates the rules and protocols for | |
5468 | communication across the network. | |
5469 | ||
5470 | Corresponding Source conveyed, and Installation Information | |
5471 | provided, in accord with this section must be in a format that is | |
5472 | publicly documented (and with an implementation available to the | |
5473 | public in source code form), and must require no special password | |
5474 | or key for unpacking, reading or copying. | |
5475 | ||
5476 | ||
5477 | 7. ADDITIONAL TERMS | |
5478 | ||
5479 | "Additional permissions" are terms that supplement the terms of | |
5480 | this License by making exceptions from one or more of its | |
5481 | conditions. Additional permissions that are applicable to the | |
5482 | entire Program shall be treated as though they were included in | |
5483 | this License, to the extent that they are valid under applicable | |
5484 | law. If additional permissions apply only to part of the Program, | |
5485 | that part may be used separately under those permissions, but the | |
5486 | entire Program remains governed by this License without regard to | |
5487 | the additional permissions. | |
5488 | ||
5489 | When you convey a copy of a covered work, you may at your option | |
5490 | remove any additional permissions from that copy, or from any part | |
5491 | of it. (Additional permissions may be written to require their own | |
5492 | removal in certain cases when you modify the work.) You may place | |
5493 | additional permissions on material, added by you to a covered work, | |
5494 | for which you have or can give appropriate copyright permission. | |
5495 | ||
5496 | Notwithstanding any other provision of this License, for material | |
5497 | you add to a covered work, you may (if authorized by the copyright | |
5498 | holders of that material) supplement the terms of this License | |
5499 | with terms: | |
5500 | ||
5501 | a) Disclaiming warranty or limiting liability differently from the | |
5502 | terms of sections 15 and 16 of this License; or | |
5503 | ||
5504 | b) Requiring preservation of specified reasonable legal notices or | |
5505 | author attributions in that material or in the Appropriate Legal | |
5506 | Notices displayed by works containing it; or | |
5507 | ||
5508 | c) Prohibiting misrepresentation of the origin of that material, or | |
5509 | requiring that modified versions of such material be marked in | |
5510 | reasonable ways as different from the original version; or | |
5511 | ||
5512 | d) Limiting the use for publicity purposes of names of licensors or | |
5513 | authors of the material; or | |
5514 | ||
5515 | e) Declining to grant rights under trademark law for use of some | |
5516 | trade names, trademarks, or service marks; or | |
5517 | ||
5518 | f) Requiring indemnification of licensors and authors of that | |
5519 | material by anyone who conveys the material (or modified versions | |
5520 | of it) with contractual assumptions of liability to the | |
5521 | recipient, for any liability that these contractual | |
5522 | assumptions directly impose on those licensors and authors. | |
5523 | ||
5524 | All other non-permissive additional terms are considered "further | |
5525 | restrictions" within the meaning of section 10. If the Program as | |
5526 | you received it, or any part of it, contains a notice stating that | |
5527 | it is governed by this License along with a term that is a further | |
5528 | restriction, you may remove that term. If a license document | |
5529 | contains a further restriction but permits relicensing or | |
5530 | conveying under this License, you may add to a covered work | |
5531 | material governed by the terms of that license document, provided | |
5532 | that the further restriction does not survive such relicensing or | |
5533 | conveying. | |
5534 | ||
5535 | If you add terms to a covered work in accord with this section, you | |
5536 | must place, in the relevant source files, a statement of the | |
5537 | additional terms that apply to those files, or a notice indicating | |
5538 | where to find the applicable terms. | |
5539 | ||
5540 | Additional terms, permissive or non-permissive, may be stated in | |
5541 | the form of a separately written license, or stated as exceptions; | |
5542 | the above requirements apply either way. | |
5543 | ||
5544 | ||
5545 | 8. TERMINATION | |
5546 | ||
5547 | You may not propagate or modify a covered work except as expressly | |
5548 | provided under this License. Any attempt otherwise to propagate or | |
5549 | modify it is void, and will automatically terminate your rights | |
5550 | under this License (including any patent licenses granted under | |
5551 | the third paragraph of section 11). | |
5552 | ||
5553 | However, if you cease all violation of this License, then your | |
5554 | license from a particular copyright holder is reinstated (a) | |
5555 | provisionally, unless and until the copyright holder explicitly and | |
5556 | finally terminates your license, and (b) permanently, if the | |
5557 | copyright holder fails to notify you of the violation by some | |
5558 | reasonable means prior to 60 days after the cessation. | |
5559 | ||
5560 | Moreover, your license from a particular copyright holder is | |
5561 | reinstated permanently if the copyright holder notifies you of the | |
5562 | violation by some reasonable means, this is the first time you have | |
5563 | received notice of violation of this License (for any work) from | |
5564 | that copyright holder, and you cure the violation prior to 30 days | |
5565 | after your receipt of the notice. | |
5566 | ||
5567 | Termination of your rights under this section does not terminate | |
5568 | the licenses of parties who have received copies or rights from | |
5569 | you under this License. If your rights have been terminated and | |
5570 | not permanently reinstated, you do not qualify to receive new | |
5571 | licenses for the same material under section 10. | |
5572 | ||
5573 | ||
5574 | 9. ACCEPTANCE NOT REQUIRED FOR HAVING COPIES | |
5575 | ||
5576 | You are not required to accept this License in order to receive or | |
5577 | run a copy of the Program. Ancillary propagation of a covered work | |
5578 | occurring solely as a consequence of using peer-to-peer | |
5579 | transmission to receive a copy likewise does not require | |
5580 | acceptance. However, nothing other than this License grants you | |
5581 | permission to propagate or modify any covered work. These actions | |
5582 | infringe copyright if you do not accept this License. Therefore, | |
5583 | by modifying or propagating a covered work, you indicate your | |
5584 | acceptance of this License to do so. | |
5585 | ||
5586 | ||
5587 | 10. AUTOMATIC LICENSING OF DOWNSTREAM RECIPIENTS | |
5588 | ||
5589 | Each time you convey a covered work, the recipient automatically | |
5590 | receives a license from the original licensors, to run, modify and | |
5591 | propagate that work, subject to this License. You are not | |
5592 | responsible for enforcing compliance by third parties with this | |
5593 | License. | |
5594 | ||
5595 | An "entity transaction" is a transaction transferring control of an | |
5596 | organization, or substantially all assets of one, or subdividing an | |
5597 | organization, or merging organizations. If propagation of a | |
5598 | covered work results from an entity transaction, each party to that | |
5599 | transaction who receives a copy of the work also receives whatever | |
5600 | licenses to the work the party's predecessor in interest had or | |
5601 | could give under the previous paragraph, plus a right to | |
5602 | possession of the Corresponding Source of the work from the | |
5603 | predecessor in interest, if the predecessor has it or can get it | |
5604 | with reasonable efforts. | |
5605 | ||
5606 | You may not impose any further restrictions on the exercise of the | |
5607 | rights granted or affirmed under this License. For example, you | |
5608 | may not impose a license fee, royalty, or other charge for | |
5609 | exercise of rights granted under this License, and you may not | |
5610 | initiate litigation (including a cross-claim or counterclaim in a | |
5611 | lawsuit) alleging that any patent claim is infringed by making, | |
5612 | using, selling, offering for sale, or importing the Program or any | |
5613 | portion of it. | |
5614 | ||
5615 | ||
5616 | 11. PATENTS | |
5617 | ||
5618 | A "contributor" is a copyright holder who authorizes use under this | |
5619 | License of the Program or a work on which the Program is based. | |
5620 | The work thus licensed is called the contributor's "contributor | |
5621 | version". | |
5622 | ||
5623 | A contributor's "essential patent claims" are all patent claims | |
5624 | owned or controlled by the contributor, whether already acquired or | |
5625 | hereafter acquired, that would be infringed by some manner, | |
5626 | permitted by this License, of making, using, or selling its | |
5627 | contributor version, but do not include claims that would be | |
5628 | infringed only as a consequence of further modification of the | |
5629 | contributor version. For purposes of this definition, "control" | |
5630 | includes the right to grant patent sublicenses in a manner | |
5631 | consistent with the requirements of this License. | |
5632 | ||
5633 | Each contributor grants you a non-exclusive, worldwide, | |
5634 | royalty-free patent license under the contributor's essential | |
5635 | patent claims, to make, use, sell, offer for sale, import and | |
5636 | otherwise run, modify and propagate the contents of its | |
5637 | contributor version. | |
5638 | ||
5639 | In the following three paragraphs, a "patent license" is any | |
5640 | express agreement or commitment, however denominated, not to | |
5641 | enforce a patent (such as an express permission to practice a | |
5642 | patent or covenant not to sue for patent infringement). To | |
5643 | "grant" such a patent license to a party means to make such an | |
5644 | agreement or commitment not to enforce a patent against the party. | |
5645 | ||
5646 | If you convey a covered work, knowingly relying on a patent | |
5647 | license, and the Corresponding Source of the work is not available | |
5648 | for anyone to copy, free of charge and under the terms of this | |
5649 | License, through a publicly available network server or other | |
5650 | readily accessible means, then you must either (1) cause the | |
5651 | Corresponding Source to be so available, or (2) arrange to deprive | |
5652 | yourself of the benefit of the patent license for this particular | |
5653 | work, or (3) arrange, in a manner consistent with the requirements | |
5654 | of this License, to extend the patent license to downstream | |
5655 | recipients. "Knowingly relying" means you have actual knowledge | |
5656 | that, but for the patent license, your conveying the covered work | |
5657 | in a country, or your recipient's use of the covered work in a | |
5658 | country, would infringe one or more identifiable patents in that | |
5659 | country that you have reason to believe are valid. | |
5660 | ||
5661 | If, pursuant to or in connection with a single transaction or | |
5662 | arrangement, you convey, or propagate by procuring conveyance of, a | |
5663 | covered work, and grant a patent license to some of the parties | |
5664 | receiving the covered work authorizing them to use, propagate, | |
5665 | modify or convey a specific copy of the covered work, then the | |
5666 | patent license you grant is automatically extended to all | |
5667 | recipients of the covered work and works based on it. | |
5668 | ||
5669 | A patent license is "discriminatory" if it does not include within | |
5670 | the scope of its coverage, prohibits the exercise of, or is | |
5671 | conditioned on the non-exercise of one or more of the rights that | |
5672 | are specifically granted under this License. You may not convey a | |
5673 | covered work if you are a party to an arrangement with a third | |
5674 | party that is in the business of distributing software, under | |
5675 | which you make payment to the third party based on the extent of | |
5676 | your activity of conveying the work, and under which the third | |
5677 | party grants, to any of the parties who would receive the covered | |
5678 | work from you, a discriminatory patent license (a) in connection | |
5679 | with copies of the covered work conveyed by you (or copies made | |
5680 | from those copies), or (b) primarily for and in connection with | |
5681 | specific products or compilations that contain the covered work, | |
5682 | unless you entered into that arrangement, or that patent license | |
5683 | was granted, prior to 28 March 2007. | |
5684 | ||
5685 | Nothing in this License shall be construed as excluding or limiting | |
5686 | any implied license or other defenses to infringement that may | |
5687 | otherwise be available to you under applicable patent law. | |
5688 | ||
5689 | ||
5690 | 12. NO SURRENDER OF OTHERS' FREEDOM | |
5691 | ||
5692 | If conditions are imposed on you (whether by court order, | |
5693 | agreement or otherwise) that contradict the conditions of this | |
5694 | License, they do not excuse you from the conditions of this | |
5695 | License. If you cannot convey a covered work so as to satisfy | |
5696 | simultaneously your obligations under this License and any other | |
5697 | pertinent obligations, then as a consequence you may not convey it | |
5698 | at all. For example, if you agree to terms that obligate you to | |
5699 | collect a royalty for further conveying from those to whom you | |
5700 | convey the Program, the only way you could satisfy both those | |
5701 | terms and this License would be to refrain entirely from conveying | |
5702 | the Program. | |
5703 | ||
5704 | ||
5705 | 13. USE WITH THE GNU AFFERO GENERAL PUBLIC LICENSE | |
5706 | ||
5707 | Notwithstanding any other provision of this License, you have | |
5708 | permission to link or combine any covered work with a work licensed | |
5709 | under version 3 of the GNU Affero General Public License into a | |
5710 | single combined work, and to convey the resulting work. The terms | |
5711 | of this License will continue to apply to the part which is the | |
5712 | covered work, but the special requirements of the GNU Affero | |
5713 | General Public License, section 13, concerning interaction through | |
5714 | a network will apply to the combination as such. | |
5715 | ||
5716 | ||
5717 | 14. REVISED VERSIONS OF THIS LICENSE | |
5718 | ||
5719 | The Free Software Foundation may publish revised and/or new | |
5720 | versions of the GNU General Public License from time to time. | |
5721 | Such new versions will be similar in spirit to the present | |
5722 | version, but may differ in detail to address new problems or | |
5723 | concerns. | |
5724 | ||
5725 | Each version is given a distinguishing version number. If the | |
5726 | Program specifies that a certain numbered version of the GNU | |
5727 | General Public License "or any later version" applies to it, you | |
5728 | have the option of following the terms and conditions either of | |
5729 | that numbered version or of any later version published by the | |
5730 | Free Software Foundation. If the Program does not specify a | |
5731 | version number of the GNU General Public License, you may choose | |
5732 | any version ever published by the Free Software Foundation. | |
5733 | ||
5734 | If the Program specifies that a proxy can decide which future | |
5735 | versions of the GNU General Public License can be used, that | |
5736 | proxy's public statement of acceptance of a version permanently | |
5737 | authorizes you to choose that version for the Program. | |
5738 | ||
5739 | Later license versions may give you additional or different | |
5740 | permissions. However, no additional obligations are imposed on any | |
5741 | author or copyright holder as a result of your choosing to follow a | |
5742 | later version. | |
5743 | ||
5744 | ||
5745 | 15. DISCLAIMER OF WARRANTY | |
5746 | ||
5747 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY | |
5748 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE | |
5749 | COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" | |
5750 | WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, | |
5751 | INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
5752 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE | |
5753 | RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. | |
5754 | SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL | |
5755 | NECESSARY SERVICING, REPAIR OR CORRECTION. | |
5756 | ||
5757 | ||
5758 | 16. LIMITATION OF LIABILITY. | |
5759 | ||
5760 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN | |
5761 | WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES | |
5762 | AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU | |
5763 | FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR | |
5764 | CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE | |
5765 | THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA | |
5766 | BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD | |
5767 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER | |
5768 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF | |
5769 | THE POSSIBILITY OF SUCH DAMAGES. | |
5770 | ||
5771 | ||
5772 | 17. INTERPRETATION OF SECTIONS 15 AND 16 | |
5773 | ||
5774 | If the disclaimer of warranty and limitation of liability provided | |
5775 | above cannot be given local legal effect according to their terms, | |
5776 | reviewing courts shall apply local law that most closely | |
5777 | approximates an absolute waiver of all civil liability in | |
5778 | connection with the Program, unless a warranty or assumption of | |
5779 | liability accompanies a copy of the Program in return for a fee. | |
5780 | ||
5781 | ||
5782 | How to Apply These Terms to your New Programs | |
5783 | ============================================= | |
5784 | ||
5785 | If you develop a new program, and you want it to be of the greatest | |
5786 | possible use to the public, the best way to achieve this is to make it | |
5787 | free software which everyone can redistribute and change under these | |
5788 | terms. | |
5789 | ||
5790 | To do so, attach the following notices to the program. It is safest | |
5791 | to attach them to the start of each source file to most effectively | |
5792 | state the exclusion of warranty; and each file should have at least the | |
5793 | "copyright" line and a pointer to where the full notice is found. | |
5794 | ||
5795 | <one line to give the program's name and a brief idea of what it | |
5796 | does.> Copyright (C) <year> <name of author> | |
5797 | ||
5798 | This program is free software: you can redistribute it and/or modify | |
5799 | it under the terms of the GNU General Public License as published by | |
5800 | the Free Software Foundation, either version 3 of the License, or | |
5801 | (at your option) any later version. | |
5802 | ||
5803 | This program is distributed in the hope that it will be useful, | |
5804 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
5805 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
5806 | General Public License for more details. | |
5807 | ||
5808 | You should have received a copy of the GNU General Public License | |
5809 | along with this program. If not, see <http://www.gnu.org/licenses/>. | |
5810 | ||
5811 | Also add information on how to contact you by electronic and paper | |
5812 | mail. | |
5813 | ||
5814 | If the program does terminal interaction, make it output a short | |
5815 | notice like this when it starts in an interactive mode: | |
5816 | ||
5817 | <program> Copyright (C) <year> <name of author> This program | |
5818 | comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This | |
5819 | is free software, and you are welcome to redistribute it under | |
5820 | certain conditions; type `show c' for details. | |
5821 | ||
5822 | The hypothetical commands `show w' and `show c' should show the | |
5823 | appropriate parts of the General Public License. Of course, your | |
5824 | program's commands might be different; for a GUI interface, you would | |
5825 | use an "about box". | |
5826 | ||
5827 | You should also get your employer (if you work as a programmer) or | |
5828 | school, if any, to sign a "copyright disclaimer" for the program, if | |
5829 | necessary. For more information on this, and how to apply and follow | |
5830 | the GNU GPL, see <http://www.gnu.org/licenses/>. | |
5831 | ||
5832 | The GNU General Public License does not permit incorporating your | |
5833 | program into proprietary programs. If your program is a subroutine | |
5834 | library, you may consider it more useful to permit linking proprietary | |
5835 | applications with the library. If this is what you want to do, use the | |
5836 | GNU Lesser General Public License instead of this License. But first, | |
5837 | please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. | |
5838 | ||
5839 | \1f | |
5840 | File: gnugo.info, Node: GFDL, Next: GTP License, Prev: GPL, Up: Copying | |
5841 | ||
5842 | A.2 GNU FREE DOCUMENTATION LICENSE | |
5843 | ================================== | |
5844 | ||
5845 | Version 1.3, 3 November 2008 | |
5846 | ||
5847 | Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. | |
5848 | `http://fsf.org/' | |
5849 | ||
5850 | Everyone is permitted to copy and distribute verbatim copies | |
5851 | of this license document, but changing it is not allowed. | |
5852 | ||
5853 | 0. PREAMBLE | |
5854 | ||
5855 | The purpose of this License is to make a manual, textbook, or other | |
5856 | functional and useful document "free" in the sense of freedom: to | |
5857 | assure everyone the effective freedom to copy and redistribute it, | |
5858 | with or without modifying it, either commercially or | |
5859 | noncommercially. Secondarily, this License preserves for the | |
5860 | author and publisher a way to get credit for their work, while not | |
5861 | being considered responsible for modifications made by others. | |
5862 | ||
5863 | This License is a kind of "copyleft", which means that derivative | |
5864 | works of the document must themselves be free in the same sense. | |
5865 | It complements the GNU General Public License, which is a copyleft | |
5866 | license designed for free software. | |
5867 | ||
5868 | We have designed this License in order to use it for manuals for | |
5869 | free software, because free software needs free documentation: a | |
5870 | free program should come with manuals providing the same freedoms | |
5871 | that the software does. But this License is not limited to | |
5872 | software manuals; it can be used for any textual work, regardless | |
5873 | of subject matter or whether it is published as a printed book. | |
5874 | We recommend this License principally for works whose purpose is | |
5875 | instruction or reference. | |
5876 | ||
5877 | 1. APPLICABILITY AND DEFINITIONS | |
5878 | ||
5879 | This License applies to any manual or other work, in any medium, | |
5880 | that contains a notice placed by the copyright holder saying it | |
5881 | can be distributed under the terms of this License. Such a notice | |
5882 | grants a world-wide, royalty-free license, unlimited in duration, | |
5883 | to use that work under the conditions stated herein. The | |
5884 | "Document", below, refers to any such manual or work. Any member | |
5885 | of the public is a licensee, and is addressed as "you". You | |
5886 | accept the license if you copy, modify or distribute the work in a | |
5887 | way requiring permission under copyright law. | |
5888 | ||
5889 | A "Modified Version" of the Document means any work containing the | |
5890 | Document or a portion of it, either copied verbatim, or with | |
5891 | modifications and/or translated into another language. | |
5892 | ||
5893 | A "Secondary Section" is a named appendix or a front-matter section | |
5894 | of the Document that deals exclusively with the relationship of the | |
5895 | publishers or authors of the Document to the Document's overall | |
5896 | subject (or to related matters) and contains nothing that could | |
5897 | fall directly within that overall subject. (Thus, if the Document | |
5898 | is in part a textbook of mathematics, a Secondary Section may not | |
5899 | explain any mathematics.) The relationship could be a matter of | |
5900 | historical connection with the subject or with related matters, or | |
5901 | of legal, commercial, philosophical, ethical or political position | |
5902 | regarding them. | |
5903 | ||
5904 | The "Invariant Sections" are certain Secondary Sections whose | |
5905 | titles are designated, as being those of Invariant Sections, in | |
5906 | the notice that says that the Document is released under this | |
5907 | License. If a section does not fit the above definition of | |
5908 | Secondary then it is not allowed to be designated as Invariant. | |
5909 | The Document may contain zero Invariant Sections. If the Document | |
5910 | does not identify any Invariant Sections then there are none. | |
5911 | ||
5912 | The "Cover Texts" are certain short passages of text that are | |
5913 | listed, as Front-Cover Texts or Back-Cover Texts, in the notice | |
5914 | that says that the Document is released under this License. A | |
5915 | Front-Cover Text may be at most 5 words, and a Back-Cover Text may | |
5916 | be at most 25 words. | |
5917 | ||
5918 | A "Transparent" copy of the Document means a machine-readable copy, | |
5919 | represented in a format whose specification is available to the | |
5920 | general public, that is suitable for revising the document | |
5921 | straightforwardly with generic text editors or (for images | |
5922 | composed of pixels) generic paint programs or (for drawings) some | |
5923 | widely available drawing editor, and that is suitable for input to | |
5924 | text formatters or for automatic translation to a variety of | |
5925 | formats suitable for input to text formatters. A copy made in an | |
5926 | otherwise Transparent file format whose markup, or absence of | |
5927 | markup, has been arranged to thwart or discourage subsequent | |
5928 | modification by readers is not Transparent. An image format is | |
5929 | not Transparent if used for any substantial amount of text. A | |
5930 | copy that is not "Transparent" is called "Opaque". | |
5931 | ||
5932 | Examples of suitable formats for Transparent copies include plain | |
5933 | ASCII without markup, Texinfo input format, LaTeX input format, | |
5934 | SGML or XML using a publicly available DTD, and | |
5935 | standard-conforming simple HTML, PostScript or PDF designed for | |
5936 | human modification. Examples of transparent image formats include | |
5937 | PNG, XCF and JPG. Opaque formats include proprietary formats that | |
5938 | can be read and edited only by proprietary word processors, SGML or | |
5939 | XML for which the DTD and/or processing tools are not generally | |
5940 | available, and the machine-generated HTML, PostScript or PDF | |
5941 | produced by some word processors for output purposes only. | |
5942 | ||
5943 | The "Title Page" means, for a printed book, the title page itself, | |
5944 | plus such following pages as are needed to hold, legibly, the | |
5945 | material this License requires to appear in the title page. For | |
5946 | works in formats which do not have any title page as such, "Title | |
5947 | Page" means the text near the most prominent appearance of the | |
5948 | work's title, preceding the beginning of the body of the text. | |
5949 | ||
5950 | The "publisher" means any person or entity that distributes copies | |
5951 | of the Document to the public. | |
5952 | ||
5953 | A section "Entitled XYZ" means a named subunit of the Document | |
5954 | whose title either is precisely XYZ or contains XYZ in parentheses | |
5955 | following text that translates XYZ in another language. (Here XYZ | |
5956 | stands for a specific section name mentioned below, such as | |
5957 | "Acknowledgements", "Dedications", "Endorsements", or "History".) | |
5958 | To "Preserve the Title" of such a section when you modify the | |
5959 | Document means that it remains a section "Entitled XYZ" according | |
5960 | to this definition. | |
5961 | ||
5962 | The Document may include Warranty Disclaimers next to the notice | |
5963 | which states that this License applies to the Document. These | |
5964 | Warranty Disclaimers are considered to be included by reference in | |
5965 | this License, but only as regards disclaiming warranties: any other | |
5966 | implication that these Warranty Disclaimers may have is void and | |
5967 | has no effect on the meaning of this License. | |
5968 | ||
5969 | 2. VERBATIM COPYING | |
5970 | ||
5971 | You may copy and distribute the Document in any medium, either | |
5972 | commercially or noncommercially, provided that this License, the | |
5973 | copyright notices, and the license notice saying this License | |
5974 | applies to the Document are reproduced in all copies, and that you | |
5975 | add no other conditions whatsoever to those of this License. You | |
5976 | may not use technical measures to obstruct or control the reading | |
5977 | or further copying of the copies you make or distribute. However, | |
5978 | you may accept compensation in exchange for copies. If you | |
5979 | distribute a large enough number of copies you must also follow | |
5980 | the conditions in section 3. | |
5981 | ||
5982 | You may also lend copies, under the same conditions stated above, | |
5983 | and you may publicly display copies. | |
5984 | ||
5985 | 3. COPYING IN QUANTITY | |
5986 | ||
5987 | If you publish printed copies (or copies in media that commonly | |
5988 | have printed covers) of the Document, numbering more than 100, and | |
5989 | the Document's license notice requires Cover Texts, you must | |
5990 | enclose the copies in covers that carry, clearly and legibly, all | |
5991 | these Cover Texts: Front-Cover Texts on the front cover, and | |
5992 | Back-Cover Texts on the back cover. Both covers must also clearly | |
5993 | and legibly identify you as the publisher of these copies. The | |
5994 | front cover must present the full title with all words of the | |
5995 | title equally prominent and visible. You may add other material | |
5996 | on the covers in addition. Copying with changes limited to the | |
5997 | covers, as long as they preserve the title of the Document and | |
5998 | satisfy these conditions, can be treated as verbatim copying in | |
5999 | other respects. | |
6000 | ||
6001 | If the required texts for either cover are too voluminous to fit | |
6002 | legibly, you should put the first ones listed (as many as fit | |
6003 | reasonably) on the actual cover, and continue the rest onto | |
6004 | adjacent pages. | |
6005 | ||
6006 | If you publish or distribute Opaque copies of the Document | |
6007 | numbering more than 100, you must either include a | |
6008 | machine-readable Transparent copy along with each Opaque copy, or | |
6009 | state in or with each Opaque copy a computer-network location from | |
6010 | which the general network-using public has access to download | |
6011 | using public-standard network protocols a complete Transparent | |
6012 | copy of the Document, free of added material. If you use the | |
6013 | latter option, you must take reasonably prudent steps, when you | |
6014 | begin distribution of Opaque copies in quantity, to ensure that | |
6015 | this Transparent copy will remain thus accessible at the stated | |
6016 | location until at least one year after the last time you | |
6017 | distribute an Opaque copy (directly or through your agents or | |
6018 | retailers) of that edition to the public. | |
6019 | ||
6020 | It is requested, but not required, that you contact the authors of | |
6021 | the Document well before redistributing any large number of | |
6022 | copies, to give them a chance to provide you with an updated | |
6023 | version of the Document. | |
6024 | ||
6025 | 4. MODIFICATIONS | |
6026 | ||
6027 | You may copy and distribute a Modified Version of the Document | |
6028 | under the conditions of sections 2 and 3 above, provided that you | |
6029 | release the Modified Version under precisely this License, with | |
6030 | the Modified Version filling the role of the Document, thus | |
6031 | licensing distribution and modification of the Modified Version to | |
6032 | whoever possesses a copy of it. In addition, you must do these | |
6033 | things in the Modified Version: | |
6034 | ||
6035 | A. Use in the Title Page (and on the covers, if any) a title | |
6036 | distinct from that of the Document, and from those of | |
6037 | previous versions (which should, if there were any, be listed | |
6038 | in the History section of the Document). You may use the | |
6039 | same title as a previous version if the original publisher of | |
6040 | that version gives permission. | |
6041 | ||
6042 | B. List on the Title Page, as authors, one or more persons or | |
6043 | entities responsible for authorship of the modifications in | |
6044 | the Modified Version, together with at least five of the | |
6045 | principal authors of the Document (all of its principal | |
6046 | authors, if it has fewer than five), unless they release you | |
6047 | from this requirement. | |
6048 | ||
6049 | C. State on the Title page the name of the publisher of the | |
6050 | Modified Version, as the publisher. | |
6051 | ||
6052 | D. Preserve all the copyright notices of the Document. | |
6053 | ||
6054 | E. Add an appropriate copyright notice for your modifications | |
6055 | adjacent to the other copyright notices. | |
6056 | ||
6057 | F. Include, immediately after the copyright notices, a license | |
6058 | notice giving the public permission to use the Modified | |
6059 | Version under the terms of this License, in the form shown in | |
6060 | the Addendum below. | |
6061 | ||
6062 | G. Preserve in that license notice the full lists of Invariant | |
6063 | Sections and required Cover Texts given in the Document's | |
6064 | license notice. | |
6065 | ||
6066 | H. Include an unaltered copy of this License. | |
6067 | ||
6068 | I. Preserve the section Entitled "History", Preserve its Title, | |
6069 | and add to it an item stating at least the title, year, new | |
6070 | authors, and publisher of the Modified Version as given on | |
6071 | the Title Page. If there is no section Entitled "History" in | |
6072 | the Document, create one stating the title, year, authors, | |
6073 | and publisher of the Document as given on its Title Page, | |
6074 | then add an item describing the Modified Version as stated in | |
6075 | the previous sentence. | |
6076 | ||
6077 | J. Preserve the network location, if any, given in the Document | |
6078 | for public access to a Transparent copy of the Document, and | |
6079 | likewise the network locations given in the Document for | |
6080 | previous versions it was based on. These may be placed in | |
6081 | the "History" section. You may omit a network location for a | |
6082 | work that was published at least four years before the | |
6083 | Document itself, or if the original publisher of the version | |
6084 | it refers to gives permission. | |
6085 | ||
6086 | K. For any section Entitled "Acknowledgements" or "Dedications", | |
6087 | Preserve the Title of the section, and preserve in the | |
6088 | section all the substance and tone of each of the contributor | |
6089 | acknowledgements and/or dedications given therein. | |
6090 | ||
6091 | L. Preserve all the Invariant Sections of the Document, | |
6092 | unaltered in their text and in their titles. Section numbers | |
6093 | or the equivalent are not considered part of the section | |
6094 | titles. | |
6095 | ||
6096 | M. Delete any section Entitled "Endorsements". Such a section | |
6097 | may not be included in the Modified Version. | |
6098 | ||
6099 | N. Do not retitle any existing section to be Entitled | |
6100 | "Endorsements" or to conflict in title with any Invariant | |
6101 | Section. | |
6102 | ||
6103 | O. Preserve any Warranty Disclaimers. | |
6104 | ||
6105 | If the Modified Version includes new front-matter sections or | |
6106 | appendices that qualify as Secondary Sections and contain no | |
6107 | material copied from the Document, you may at your option | |
6108 | designate some or all of these sections as invariant. To do this, | |
6109 | add their titles to the list of Invariant Sections in the Modified | |
6110 | Version's license notice. These titles must be distinct from any | |
6111 | other section titles. | |
6112 | ||
6113 | You may add a section Entitled "Endorsements", provided it contains | |
6114 | nothing but endorsements of your Modified Version by various | |
6115 | parties--for example, statements of peer review or that the text | |
6116 | has been approved by an organization as the authoritative | |
6117 | definition of a standard. | |
6118 | ||
6119 | You may add a passage of up to five words as a Front-Cover Text, | |
6120 | and a passage of up to 25 words as a Back-Cover Text, to the end | |
6121 | of the list of Cover Texts in the Modified Version. Only one | |
6122 | passage of Front-Cover Text and one of Back-Cover Text may be | |
6123 | added by (or through arrangements made by) any one entity. If the | |
6124 | Document already includes a cover text for the same cover, | |
6125 | previously added by you or by arrangement made by the same entity | |
6126 | you are acting on behalf of, you may not add another; but you may | |
6127 | replace the old one, on explicit permission from the previous | |
6128 | publisher that added the old one. | |
6129 | ||
6130 | The author(s) and publisher(s) of the Document do not by this | |
6131 | License give permission to use their names for publicity for or to | |
6132 | assert or imply endorsement of any Modified Version. | |
6133 | ||
6134 | 5. COMBINING DOCUMENTS | |
6135 | ||
6136 | You may combine the Document with other documents released under | |
6137 | this License, under the terms defined in section 4 above for | |
6138 | modified versions, provided that you include in the combination | |
6139 | all of the Invariant Sections of all of the original documents, | |
6140 | unmodified, and list them all as Invariant Sections of your | |
6141 | combined work in its license notice, and that you preserve all | |
6142 | their Warranty Disclaimers. | |
6143 | ||
6144 | The combined work need only contain one copy of this License, and | |
6145 | multiple identical Invariant Sections may be replaced with a single | |
6146 | copy. If there are multiple Invariant Sections with the same name | |
6147 | but different contents, make the title of each such section unique | |
6148 | by adding at the end of it, in parentheses, the name of the | |
6149 | original author or publisher of that section if known, or else a | |
6150 | unique number. Make the same adjustment to the section titles in | |
6151 | the list of Invariant Sections in the license notice of the | |
6152 | combined work. | |
6153 | ||
6154 | In the combination, you must combine any sections Entitled | |
6155 | "History" in the various original documents, forming one section | |
6156 | Entitled "History"; likewise combine any sections Entitled | |
6157 | "Acknowledgements", and any sections Entitled "Dedications". You | |
6158 | must delete all sections Entitled "Endorsements." | |
6159 | ||
6160 | 6. COLLECTIONS OF DOCUMENTS | |
6161 | ||
6162 | You may make a collection consisting of the Document and other | |
6163 | documents released under this License, and replace the individual | |
6164 | copies of this License in the various documents with a single copy | |
6165 | that is included in the collection, provided that you follow the | |
6166 | rules of this License for verbatim copying of each of the | |
6167 | documents in all other respects. | |
6168 | ||
6169 | You may extract a single document from such a collection, and | |
6170 | distribute it individually under this License, provided you insert | |
6171 | a copy of this License into the extracted document, and follow | |
6172 | this License in all other respects regarding verbatim copying of | |
6173 | that document. | |
6174 | ||
6175 | 7. AGGREGATION WITH INDEPENDENT WORKS | |
6176 | ||
6177 | A compilation of the Document or its derivatives with other | |
6178 | separate and independent documents or works, in or on a volume of | |
6179 | a storage or distribution medium, is called an "aggregate" if the | |
6180 | copyright resulting from the compilation is not used to limit the | |
6181 | legal rights of the compilation's users beyond what the individual | |
6182 | works permit. When the Document is included in an aggregate, this | |
6183 | License does not apply to the other works in the aggregate which | |
6184 | are not themselves derivative works of the Document. | |
6185 | ||
6186 | If the Cover Text requirement of section 3 is applicable to these | |
6187 | copies of the Document, then if the Document is less than one half | |
6188 | of the entire aggregate, the Document's Cover Texts may be placed | |
6189 | on covers that bracket the Document within the aggregate, or the | |
6190 | electronic equivalent of covers if the Document is in electronic | |
6191 | form. Otherwise they must appear on printed covers that bracket | |
6192 | the whole aggregate. | |
6193 | ||
6194 | 8. TRANSLATION | |
6195 | ||
6196 | Translation is considered a kind of modification, so you may | |
6197 | distribute translations of the Document under the terms of section | |
6198 | 4. Replacing Invariant Sections with translations requires special | |
6199 | permission from their copyright holders, but you may include | |
6200 | translations of some or all Invariant Sections in addition to the | |
6201 | original versions of these Invariant Sections. You may include a | |
6202 | translation of this License, and all the license notices in the | |
6203 | Document, and any Warranty Disclaimers, provided that you also | |
6204 | include the original English version of this License and the | |
6205 | original versions of those notices and disclaimers. In case of a | |
6206 | disagreement between the translation and the original version of | |
6207 | this License or a notice or disclaimer, the original version will | |
6208 | prevail. | |
6209 | ||
6210 | If a section in the Document is Entitled "Acknowledgements", | |
6211 | "Dedications", or "History", the requirement (section 4) to | |
6212 | Preserve its Title (section 1) will typically require changing the | |
6213 | actual title. | |
6214 | ||
6215 | 9. TERMINATION | |
6216 | ||
6217 | You may not copy, modify, sublicense, or distribute the Document | |
6218 | except as expressly provided under this License. Any attempt | |
6219 | otherwise to copy, modify, sublicense, or distribute it is void, | |
6220 | and will automatically terminate your rights under this License. | |
6221 | ||
6222 | However, if you cease all violation of this License, then your | |
6223 | license from a particular copyright holder is reinstated (a) | |
6224 | provisionally, unless and until the copyright holder explicitly | |
6225 | and finally terminates your license, and (b) permanently, if the | |
6226 | copyright holder fails to notify you of the violation by some | |
6227 | reasonable means prior to 60 days after the cessation. | |
6228 | ||
6229 | Moreover, your license from a particular copyright holder is | |
6230 | reinstated permanently if the copyright holder notifies you of the | |
6231 | violation by some reasonable means, this is the first time you have | |
6232 | received notice of violation of this License (for any work) from | |
6233 | that copyright holder, and you cure the violation prior to 30 days | |
6234 | after your receipt of the notice. | |
6235 | ||
6236 | Termination of your rights under this section does not terminate | |
6237 | the licenses of parties who have received copies or rights from | |
6238 | you under this License. If your rights have been terminated and | |
6239 | not permanently reinstated, receipt of a copy of some or all of | |
6240 | the same material does not give you any rights to use it. | |
6241 | ||
6242 | 10. FUTURE REVISIONS OF THIS LICENSE | |
6243 | ||
6244 | The Free Software Foundation may publish new, revised versions of | |
6245 | the GNU Free Documentation License from time to time. Such new | |
6246 | versions will be similar in spirit to the present version, but may | |
6247 | differ in detail to address new problems or concerns. See | |
6248 | `http://www.gnu.org/copyleft/'. | |
6249 | ||
6250 | Each version of the License is given a distinguishing version | |
6251 | number. If the Document specifies that a particular numbered | |
6252 | version of this License "or any later version" applies to it, you | |
6253 | have the option of following the terms and conditions either of | |
6254 | that specified version or of any later version that has been | |
6255 | published (not as a draft) by the Free Software Foundation. If | |
6256 | the Document does not specify a version number of this License, | |
6257 | you may choose any version ever published (not as a draft) by the | |
6258 | Free Software Foundation. If the Document specifies that a proxy | |
6259 | can decide which future versions of this License can be used, that | |
6260 | proxy's public statement of acceptance of a version permanently | |
6261 | authorizes you to choose that version for the Document. | |
6262 | ||
6263 | 11. RELICENSING | |
6264 | ||
6265 | "Massive Multiauthor Collaboration Site" (or "MMC Site") means any | |
6266 | World Wide Web server that publishes copyrightable works and also | |
6267 | provides prominent facilities for anybody to edit those works. A | |
6268 | public wiki that anybody can edit is an example of such a server. | |
6269 | A "Massive Multiauthor Collaboration" (or "MMC") contained in the | |
6270 | site means any set of copyrightable works thus published on the MMC | |
6271 | site. | |
6272 | ||
6273 | "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 | |
6274 | license published by Creative Commons Corporation, a not-for-profit | |
6275 | corporation with a principal place of business in San Francisco, | |
6276 | California, as well as future copyleft versions of that license | |
6277 | published by that same organization. | |
6278 | ||
6279 | "Incorporate" means to publish or republish a Document, in whole or | |
6280 | in part, as part of another Document. | |
6281 | ||
6282 | An MMC is "eligible for relicensing" if it is licensed under this | |
6283 | License, and if all works that were first published under this | |
6284 | License somewhere other than this MMC, and subsequently | |
6285 | incorporated in whole or in part into the MMC, (1) had no cover | |
6286 | texts or invariant sections, and (2) were thus incorporated prior | |
6287 | to November 1, 2008. | |
6288 | ||
6289 | The operator of an MMC Site may republish an MMC contained in the | |
6290 | site under CC-BY-SA on the same site at any time before August 1, | |
6291 | 2009, provided the MMC is eligible for relicensing. | |
6292 | ||
6293 | ||
6294 | ADDENDUM: How to use this License for your documents | |
6295 | ==================================================== | |
6296 | ||
6297 | To use this License in a document you have written, include a copy of | |
6298 | the License in the document and put the following copyright and license | |
6299 | notices just after the title page: | |
6300 | ||
6301 | Copyright (C) YEAR YOUR NAME. | |
6302 | Permission is granted to copy, distribute and/or modify this document | |
6303 | under the terms of the GNU Free Documentation License, Version 1.3 | |
6304 | or any later version published by the Free Software Foundation; | |
6305 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover | |
6306 | Texts. A copy of the license is included in the section entitled ``GNU | |
6307 | Free Documentation License''. | |
6308 | ||
6309 | If you have Invariant Sections, Front-Cover Texts and Back-Cover | |
6310 | Texts, replace the "with...Texts." line with this: | |
6311 | ||
6312 | with the Invariant Sections being LIST THEIR TITLES, with | |
6313 | the Front-Cover Texts being LIST, and with the Back-Cover Texts | |
6314 | being LIST. | |
6315 | ||
6316 | If you have Invariant Sections without Cover Texts, or some other | |
6317 | combination of the three, merge those two alternatives to suit the | |
6318 | situation. | |
6319 | ||
6320 | If your document contains nontrivial examples of program code, we | |
6321 | recommend releasing these examples in parallel under your choice of | |
6322 | free software license, such as the GNU General Public License, to | |
6323 | permit their use in free software. | |
6324 | ||
6325 | \1f | |
6326 | File: gnugo.info, Node: GTP License, Prev: GFDL, Up: Copying | |
6327 | ||
6328 | A.3 The Go Text Protocol License | |
6329 | ================================ | |
6330 | ||
6331 | In order to facilitate the use of the Go Text Protocol, the two files | |
6332 | `gtp.c' and `gtp.h' are licensed under the following terms. | |
6333 | ||
6334 | Copyright 2001 by the Free Software Foundation. | |
6335 | ||
6336 | Permission is hereby granted, free of charge, to any person | |
6337 | obtaining a copy of this file `gtp.x', to deal in the Software without | |
6338 | restriction, including without limitation the rights to use, copy, | |
6339 | modify, merge, publish, distribute, and/or sell copies of the Software, | |
6340 | and to permit persons to whom the Software is furnished to do so, | |
6341 | provided that the above copyright notice(s) and this permission notice | |
6342 | appear in all copies of the Software and that both the above copyright | |
6343 | notice(s) and this permission notice appear in supporting documentation. | |
6344 | ||
6345 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
6346 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
6347 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT | |
6348 | OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR | |
6349 | HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL | |
6350 | INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING | |
6351 | FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, | |
6352 | NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION | |
6353 | WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
6354 | ||
6355 | Except as contained in this notice, the name of a copyright holder | |
6356 | shall not be used in advertising or otherwise to promote the sale, use | |
6357 | or other dealings in this Software without prior written authorization | |
6358 | of the copyright holder. | |
6359 | ||
6360 | \1f | |
6361 | File: gnugo.info, Node: Concept Index, Next: Functions Index, Prev: Copying, Up: Top | |
6362 | ||
6363 | Concept Index | |
6364 | ************* | |
6365 | ||
6366 | \0\b[index\0\b] | |
6367 | * Menu: | |
6368 | ||
6369 | * aa_confirm_safety: GTP command reference. | |
6370 | (line 492) | |
6371 | * accurate_approxlib: GTP command reference. | |
6372 | (line 207) | |
6373 | * accuratelib: GTP command reference. | |
6374 | (line 200) | |
6375 | * adjacent dragons: Dragons. (line 145) | |
6376 | * advance_random_seed: GTP command reference. | |
6377 | (line 960) | |
6378 | * all_legal: GTP command reference. | |
6379 | (line 223) | |
6380 | * amalgamation of worms into dragons: Amalgamation. (line 6) | |
6381 | * analyze_eyegraph: GTP command reference. | |
6382 | (line 710) | |
6383 | * analyze_semeai: GTP command reference. | |
6384 | (line 400) | |
6385 | * analyze_semeai_after_move: GTP command reference. | |
6386 | (line 406) | |
6387 | * API: API. (line 26) | |
6388 | * area: Territory and Moyo. (line 6) | |
6389 | * ascii description of shapes: Patterns Overview. (line 27) | |
6390 | * ascii interface: Ascii. (line 6) | |
6391 | * ascii mode: Invoking GNU Go. (line 336) | |
6392 | * attack: GTP command reference. | |
6393 | (line 288) | |
6394 | * attack shapes database: Patterns Overview. (line 6) | |
6395 | * attack_either: GTP command reference. | |
6396 | (line 294) | |
6397 | * autohelper actions: Autohelper Actions. (line 6) | |
6398 | * Autohelpers: Autohelpers and Constraints. | |
6399 | (line 6) | |
6400 | * automaton: DFA. (line 29) | |
6401 | * black: GTP command reference. | |
6402 | (line 111) | |
6403 | * block_off: GTP command reference. | |
6404 | (line 437) | |
6405 | * board_state: The Board State. (line 6) | |
6406 | * boardsize: GTP command reference. | |
6407 | (line 63) | |
6408 | * break_in: GTP command reference. | |
6409 | (line 431) | |
6410 | * cache: Invoking GNU Go. (line 119) | |
6411 | * cache-size: Invoking GNU Go. (line 119) | |
6412 | * captures: GTP command reference. | |
6413 | (line 229) | |
6414 | * CGoban: CGoban. (line 6) | |
6415 | * clear_board: GTP command reference. | |
6416 | (line 77) | |
6417 | * clear_cache: GTP command reference. | |
6418 | (line 284) | |
6419 | * color: GTP command reference. | |
6420 | (line 175) | |
6421 | * color (dragon): Dragons. (line 98) | |
6422 | * colored display <1>: Dragons in Color. (line 6) | |
6423 | * colored display: Colored Display. (line 6) | |
6424 | * combination_attack: GTP command reference. | |
6425 | (line 479) | |
6426 | * combination_defend: GTP command reference. | |
6427 | (line 485) | |
6428 | * command line options: Invoking GNU Go. (line 6) | |
6429 | * connect: GTP command reference. | |
6430 | (line 419) | |
6431 | * connection shapes database <1>: Connections Database. | |
6432 | (line 6) | |
6433 | * connection shapes database: Patterns Overview. (line 6) | |
6434 | * connections: Connection. (line 6) | |
6435 | * connections database: Connections Database. | |
6436 | (line 6) | |
6437 | * corner matcher: Corner Matcher. (line 6) | |
6438 | * countlib: GTP command reference. | |
6439 | (line 187) | |
6440 | * cputime: GTP command reference. | |
6441 | (line 717) | |
6442 | * cutting stone: Worms. (line 124) | |
6443 | * cutting stone, potential: Worms. (line 133) | |
6444 | * data structures: Basic Data Structures. | |
6445 | (line 6) | |
6446 | * debugging on a graphical board: view.pike. (line 6) | |
6447 | * debugging options: Invoking GNU Go. (line 415) | |
6448 | * Debugging the reading code: Debugging. (line 6) | |
6449 | * decide-dragon: Decide dragon. (line 6) | |
6450 | * decide-string: Decide string. (line 6) | |
6451 | * decrease_depths: GTP command reference. | |
6452 | (line 334) | |
6453 | * defence shapes database: Patterns Overview. (line 6) | |
6454 | * defend: GTP command reference. | |
6455 | (line 302) | |
6456 | * defend_both: GTP command reference. | |
6457 | (line 385) | |
6458 | * depth: Invoking GNU Go. (line 242) | |
6459 | * Depth of reading: Tactical Reading. (line 6) | |
6460 | * description of shapes: Patterns Overview. (line 27) | |
6461 | * dfa: DFA. (line 29) | |
6462 | * dfa.c: DFA. (line 29) | |
6463 | * dfa.h: DFA. (line 29) | |
6464 | * disconnect: GTP command reference. | |
6465 | (line 425) | |
6466 | * distance from liberty to dragon: Worms. (line 109) | |
6467 | * does_attack: GTP command reference. | |
6468 | (line 308) | |
6469 | * does_defend: GTP command reference. | |
6470 | (line 315) | |
6471 | * does_surround: GTP command reference. | |
6472 | (line 972) | |
6473 | * dragon: Worms and Dragons. (line 27) | |
6474 | * dragon escape_route: Dragons. (line 207) | |
6475 | * dragon genus: Dragons. (line 213) | |
6476 | * dragon lunch: Dragons. (line 230) | |
6477 | * dragon number: Dragons. (line 100) | |
6478 | * dragon origin: Dragons. (line 104) | |
6479 | * dragon safety: Dragons. (line 176) | |
6480 | * dragon size: Dragons. (line 112) | |
6481 | * dragon status: Dragons. (line 131) | |
6482 | * dragon weakness: Dragons. (line 199) | |
6483 | * dragon_data: GTP command reference. | |
6484 | (line 854) | |
6485 | * dragon_status: GTP command reference. | |
6486 | (line 452) | |
6487 | * dragon_stones: GTP command reference. | |
6488 | (line 860) | |
6489 | * dragons: Dragons. (line 6) | |
6490 | * draw_search_area: GTP command reference. | |
6491 | (line 1008) | |
6492 | * dump_stack: GTP command reference. | |
6493 | (line 731) | |
6494 | * echo: GTP command reference. | |
6495 | (line 913) | |
6496 | * echo_err: GTP command reference. | |
6497 | (line 919) | |
6498 | * editing pattern database: Editing Patterns. (line 6) | |
6499 | * editing patterns: Editing Patterns. (line 6) | |
6500 | * effective size: Dragons. (line 116) | |
6501 | * effective size (worm): Worms. (line 48) | |
6502 | * eliminate the randomness: Tuning. (line 155) | |
6503 | * emacs mode: Emacs. (line 6) | |
6504 | * escape_route: Dragons. (line 207) | |
6505 | * estimate_score: GTP command reference. | |
6506 | (line 621) | |
6507 | * eval_eye: GTP command reference. | |
6508 | (line 444) | |
6509 | * experimental_score: GTP command reference. | |
6510 | (line 626) | |
6511 | * eye shapes database: Patterns Overview. (line 6) | |
6512 | * eye space display: Colored Display. (line 48) | |
6513 | * eye_data: GTP command reference. | |
6514 | (line 866) | |
6515 | * false eye: Half Eyes. (line 6) | |
6516 | * fast pattern matching: DFA. (line 29) | |
6517 | * final_score: GTP command reference. | |
6518 | (line 589) | |
6519 | * final_status: GTP command reference. | |
6520 | (line 597) | |
6521 | * final_status_list: GTP command reference. | |
6522 | (line 605) | |
6523 | * findlib: GTP command reference. | |
6524 | (line 193) | |
6525 | * finish_sgftrace: GTP command reference. | |
6526 | (line 889) | |
6527 | * finite state automaton: DFA. (line 29) | |
6528 | * fixed_handicap: GTP command reference. | |
6529 | (line 135) | |
6530 | * FIXME: Coding Styles. (line 83) | |
6531 | * followup_influence: GTP command reference. | |
6532 | (line 799) | |
6533 | * format of the pattern database: Patterns Overview. (line 27) | |
6534 | * formatted printing: Print Utilities. (line 6) | |
6535 | * GDB <1>: Debugging. (line 30) | |
6536 | * GDB: GTP and GDB techniques. | |
6537 | (line 6) | |
6538 | * generation of helper functions: Autohelpers and Constraints. | |
6539 | (line 6) | |
6540 | * genmove: GTP command reference. | |
6541 | (line 512) | |
6542 | * genmove_black: GTP command reference. | |
6543 | (line 496) | |
6544 | * genmove_white: GTP command reference. | |
6545 | (line 504) | |
6546 | * genus: Dragons. (line 213) | |
6547 | * genus (worm): Worms. (line 155) | |
6548 | * get_connection_node_counter: GTP command reference. | |
6549 | (line 697) | |
6550 | * get_handicap: GTP command reference. | |
6551 | (line 160) | |
6552 | * get_komi: GTP command reference. | |
6553 | (line 105) | |
6554 | * get_life_node_counter: GTP command reference. | |
6555 | (line 646) | |
6556 | * get_owl_node_counter: GTP command reference. | |
6557 | (line 661) | |
6558 | * get_random_seed: GTP command reference. | |
6559 | (line 948) | |
6560 | * get_reading_node_counter: GTP command reference. | |
6561 | (line 673) | |
6562 | * get_trymove_counter: GTP command reference. | |
6563 | (line 685) | |
6564 | * gg-undo: GTP command reference. | |
6565 | (line 571) | |
6566 | * gg_genmove: GTP command reference. | |
6567 | (line 529) | |
6568 | * GMP: GMP and GTP. (line 6) | |
6569 | * GNU Go's GDB commands: Debugging. (line 82) | |
6570 | * go position: Hash Calculation. (line 10) | |
6571 | * grid optimization: Details. (line 6) | |
6572 | * GTP <1>: GTP and GDB techniques. | |
6573 | (line 6) | |
6574 | * GTP: GMP and GTP. (line 6) | |
6575 | * GTP command reference: GTP command reference. | |
6576 | (line 6) | |
6577 | * half eye: Half Eyes. (line 6) | |
6578 | * half_eye_data: GTP command reference. | |
6579 | (line 872) | |
6580 | * Hash node: Hash Organization. (line 8) | |
6581 | * Hashing of positions: Hashing. (line 6) | |
6582 | * help: GTP command reference. | |
6583 | (line 925) | |
6584 | * helper functions in pattern matching: Helper Functions. (line 6) | |
6585 | * how GNU Go learns new joseki: Joseki Compiler. (line 6) | |
6586 | * How to debug the reading code: Debugging. (line 6) | |
6587 | * implementation of pattern matching <1>: Corner Matcher. (line 6) | |
6588 | * implementation of pattern matching: PM Implementation. (line 6) | |
6589 | * increase_depths: GTP command reference. | |
6590 | (line 328) | |
6591 | * inessential string: Worms. (line 165) | |
6592 | * initial_influence: GTP command reference. | |
6593 | (line 737) | |
6594 | * installation: GNU/Linux and Unix. (line 6) | |
6595 | * invariant_hash: GTP command reference. | |
6596 | (line 248) | |
6597 | * invariant_hash_for_moves: GTP command reference. | |
6598 | (line 255) | |
6599 | * invincible worm: Worms. (line 178) | |
6600 | * invoking GNU Go: Invoking GNU Go. (line 6) | |
6601 | * is_legal: GTP command reference. | |
6602 | (line 217) | |
6603 | * is_surrounded: GTP command reference. | |
6604 | (line 966) | |
6605 | * jago: Other Clients. (line 6) | |
6606 | * joseki <1>: Corner Matcher. (line 6) | |
6607 | * joseki: Joseki Compiler. (line 6) | |
6608 | * kgs-genmove_cleanup: GTP command reference. | |
6609 | (line 544) | |
6610 | * known_command: GTP command reference. | |
6611 | (line 933) | |
6612 | * komi: GTP command reference. | |
6613 | (line 97) | |
6614 | * ladder_attack: GTP command reference. | |
6615 | (line 322) | |
6616 | * last_move: GTP command reference. | |
6617 | (line 235) | |
6618 | * level <1>: GTP command reference. | |
6619 | (line 557) | |
6620 | * level: Invoking GNU Go. (line 225) | |
6621 | * level of play: Invoking GNU Go. (line 25) | |
6622 | * liberties (worm): Worms. (line 74) | |
6623 | * liberties, higher order (worm): Worms. (line 74) | |
6624 | * licence, documentation (GFDL): GFDL. (line 3) | |
6625 | * licence, program (GPL): GPL. (line 3) | |
6626 | * limit_search: GTP command reference. | |
6627 | (line 996) | |
6628 | * list_stones: GTP command reference. | |
6629 | (line 181) | |
6630 | * loadsgf: GTP command reference. | |
6631 | (line 166) | |
6632 | * lunch: Dragons. (line 230) | |
6633 | * lunch (worm): Worms. (line 114) | |
6634 | * matchpat.c: DFA. (line 29) | |
6635 | * Monte Carlo Go: Monte Carlo Go. (line 6) | |
6636 | * move generation: Move Generators. (line 6) | |
6637 | * move generators: Move Generators. (line 6) | |
6638 | * move reasons <1>: Move Reasons. (line 6) | |
6639 | * move reasons: Move Generators. (line 6) | |
6640 | * move_history: GTP command reference. | |
6641 | (line 241) | |
6642 | * move_influence: GTP command reference. | |
6643 | (line 776) | |
6644 | * move_probabilities: GTP command reference. | |
6645 | (line 783) | |
6646 | * move_uncertainty: GTP command reference. | |
6647 | (line 791) | |
6648 | * moyo: Territory and Moyo. (line 6) | |
6649 | * name: GTP command reference. | |
6650 | (line 47) | |
6651 | * neighbor dragons: Dragons. (line 145) | |
6652 | * orientation: GTP command reference. | |
6653 | (line 85) | |
6654 | * origin (worm): Worms. (line 58) | |
6655 | * output file: Output File. (line 6) | |
6656 | * owl_attack: GTP command reference. | |
6657 | (line 340) | |
6658 | * owl_attack_certain: Dragons. (line 296) | |
6659 | * owl_attack_code: Dragons. (line 291) | |
6660 | * owl_attack_point: Dragons. (line 286) | |
6661 | * owl_connection_defends: GTP command reference. | |
6662 | (line 378) | |
6663 | * owl_defend: GTP command reference. | |
6664 | (line 346) | |
6665 | * owl_defense_certain: Dragons. (line 314) | |
6666 | * owl_defense_code: Dragons. (line 309) | |
6667 | * owl_defense_point: Dragons. (line 305) | |
6668 | * owl_does_attack: GTP command reference. | |
6669 | (line 366) | |
6670 | * owl_does_defend: GTP command reference. | |
6671 | (line 372) | |
6672 | * owl_second_attack_point: Dragons. (line 301) | |
6673 | * owl_second_defense_point: Dragons. (line 319) | |
6674 | * owl_substantial: GTP command reference. | |
6675 | (line 393) | |
6676 | * owl_threaten_attack: GTP command reference. | |
6677 | (line 352) | |
6678 | * owl_threaten_defense: GTP command reference. | |
6679 | (line 359) | |
6680 | * pattern attributes: Pattern Classification. | |
6681 | (line 6) | |
6682 | * pattern database <1>: DFA. (line 29) | |
6683 | * pattern database: Patterns Overview. (line 6) | |
6684 | * pattern matching <1>: DFA. (line 29) | |
6685 | * pattern matching: Patterns Overview. (line 6) | |
6686 | * pattern matching optimization: Details. (line 6) | |
6687 | * pattern overview: Patterns Overview. (line 6) | |
6688 | * pattern.c: Patterns Overview. (line 6) | |
6689 | * pattern.h: Patterns Overview. (line 6) | |
6690 | * persistent cache: Persistent Cache. (line 6) | |
6691 | * place_free_handicap: GTP command reference. | |
6692 | (line 143) | |
6693 | * play: GTP command reference. | |
6694 | (line 127) | |
6695 | * playwhite: GTP command reference. | |
6696 | (line 119) | |
6697 | * popgo: GTP command reference. | |
6698 | (line 277) | |
6699 | * position: Hash Calculation. (line 10) | |
6700 | * position struct: Basic Data Structures. | |
6701 | (line 6) | |
6702 | * potential cutting stone: Worms. (line 133) | |
6703 | * printsgf: GTP command reference. | |
6704 | (line 899) | |
6705 | * product: DFA. (line 29) | |
6706 | * protocol_version: GTP command reference. | |
6707 | (line 39) | |
6708 | * qGo: Other Clients. (line 6) | |
6709 | * quarry: Other Clients. (line 6) | |
6710 | * query_boardsize: GTP command reference. | |
6711 | (line 71) | |
6712 | * query_orientation: GTP command reference. | |
6713 | (line 91) | |
6714 | * quit: GTP command reference. | |
6715 | (line 33) | |
6716 | * Read result: Hash Organization. (line 8) | |
6717 | * Reading code: Tactical Reading. (line 6) | |
6718 | * Reading code debugging tools: Debugging. (line 6) | |
6719 | * reading DEPTH: Tactical Reading. (line 6) | |
6720 | * Reading optimisation: Hashing. (line 6) | |
6721 | * Reading process: Tactical Reading. (line 6) | |
6722 | * reading return codes: Reading Basics. (line 51) | |
6723 | * reading shadow: Persistent Cache. (line 50) | |
6724 | * reading.c <1>: Reading Basics. (line 122) | |
6725 | * reading.c: Tactical Reading. (line 6) | |
6726 | * reading.h: Tactical Reading. (line 6) | |
6727 | * reg_genmove: GTP command reference. | |
6728 | (line 521) | |
6729 | * report_uncertainty: GTP command reference. | |
6730 | (line 941) | |
6731 | * reset_connection_node_counter: GTP command reference. | |
6732 | (line 691) | |
6733 | * reset_life_node_counter: GTP command reference. | |
6734 | (line 637) | |
6735 | * reset_owl_node_counter: GTP command reference. | |
6736 | (line 655) | |
6737 | * reset_reading_node_counter: GTP command reference. | |
6738 | (line 667) | |
6739 | * reset_search_mask: GTP command reference. | |
6740 | (line 990) | |
6741 | * reset_trymove_counter: GTP command reference. | |
6742 | (line 679) | |
6743 | * restricted_genmove: GTP command reference. | |
6744 | (line 537) | |
6745 | * return codes: Reading Basics. (line 51) | |
6746 | * same_dragon: GTP command reference. | |
6747 | (line 464) | |
6748 | * scoring: Scoring. (line 6) | |
6749 | * semeai: Dragons. (line 254) | |
6750 | * semeai_attack_certain: Dragons. (line 254) | |
6751 | * semeai_attack_point: Dragons. (line 254) | |
6752 | * semeai_defense_certain: Dragons. (line 254) | |
6753 | * semeai_defense_point: Dragons. (line 254) | |
6754 | * set_free_handicap: GTP command reference. | |
6755 | (line 152) | |
6756 | * set_random_seed: GTP command reference. | |
6757 | (line 954) | |
6758 | * set_search_diamond: GTP command reference. | |
6759 | (line 984) | |
6760 | * set_search_limit: GTP command reference. | |
6761 | (line 1002) | |
6762 | * SGF (Smart Game Format): SGF Support. (line 6) | |
6763 | * SGF files in memory: SGF. (line 6) | |
6764 | * shape attributes: Pattern Classification. | |
6765 | (line 6) | |
6766 | * showboard: GTP command reference. | |
6767 | (line 723) | |
6768 | * Smart Game Format: SGF Support. (line 6) | |
6769 | * Speedup of reading process: Hashing. (line 6) | |
6770 | * start_sgftrace: GTP command reference. | |
6771 | (line 879) | |
6772 | * string: Worms and Dragons. (line 27) | |
6773 | * superstring: General Utilities. (line 249) | |
6774 | * surround: Dragons. (line 238) | |
6775 | * surround_map: GTP command reference. | |
6776 | (line 979) | |
6777 | * surround_size: Dragons. (line 238) | |
6778 | * surround_status: Dragons. (line 238) | |
6779 | * symmetry and transformations: Symmetry & transformations. | |
6780 | (line 6) | |
6781 | * symmetry and transformations of shapes: Symmetry & transformations. | |
6782 | (line 6) | |
6783 | * tactical_analyze_semeai: GTP command reference. | |
6784 | (line 413) | |
6785 | * teaching josekis to GNU Go: Joseki Compiler. (line 6) | |
6786 | * territory: Territory and Moyo. (line 6) | |
6787 | * test_eyeshape: GTP command reference. | |
6788 | (line 704) | |
6789 | * The Go Modem Protocol and Go Text Protocol: GMP and GTP. (line 6) | |
6790 | * the joseki compiler: Joseki Compiler. (line 6) | |
6791 | * time_left: GTP command reference. | |
6792 | (line 583) | |
6793 | * time_settings: GTP command reference. | |
6794 | (line 576) | |
6795 | * timers: General Utilities. (line 328) | |
6796 | * traces: Traces. (line 6) | |
6797 | * Transposition table: Hashing. (line 6) | |
6798 | * Trying hypothetical moves: Tactical Reading. (line 6) | |
6799 | * tryko: GTP command reference. | |
6800 | (line 270) | |
6801 | * trymove: GTP command reference. | |
6802 | (line 264) | |
6803 | * tune_move_ordering: GTP command reference. | |
6804 | (line 906) | |
6805 | * tuning GNU Go: Traces. (line 6) | |
6806 | * tuning the pattern database: Tuning. (line 6) | |
6807 | * tuning the shapes database: Tuning. (line 6) | |
6808 | * UCT algorithm: Monte Carlo Go. (line 6) | |
6809 | * unconditional_status: GTP command reference. | |
6810 | (line 470) | |
6811 | * undo: GTP command reference. | |
6812 | (line 564) | |
6813 | * Usage of the stack in reading: Tactical Reading. (line 6) | |
6814 | * version: GTP command reference. | |
6815 | (line 55) | |
6816 | * weakness: Dragons. (line 199) | |
6817 | * worm <1>: Worms. (line 6) | |
6818 | * worm: Worms and Dragons. (line 27) | |
6819 | * worm_cutstone: GTP command reference. | |
6820 | (line 847) | |
6821 | * worm_data: GTP command reference. | |
6822 | (line 806) | |
6823 | * worm_stones: GTP command reference. | |
6824 | (line 841) | |
6825 | * Zobrist hashing algorithm: Hashing. (line 6) | |
6826 |