This is gnugo.info, produced by makeinfo version 4.0b from gnugo.texi.

INFO-DIR-SECTION GNU games
START-INFO-DIR-ENTRY
* GNU go: (gnugo).          The GNU Go program
END-INFO-DIR-ENTRY


File: gnugo.info,  Node: Worms,  Next: Amalgamation,  Prev: Worms and Dragons,  Up: Worms and Dragons

Worms
=====

   The array `struct worm_data worm[MAX_BOARD]' collects information
about the worms. We will give definitions of the various fields. Each
field has constant value at each vertex of the worm. We will define
each field.


     struct worm_data {
       int color;
       int size;
       float effective_size;
       int origin;
       int liberties;
       int liberties2;
       int liberties3;
       int liberties4;
       int lunch;
       int cutstone;
       int cutstone2;
       int genus;
       int inessential;
       int invincible;
       int unconditional_status;
       int attack_points[MAX_TACTICAL_POINTS];
       int attack_codes[MAX_TACTICAL_POINTS];
       int defense_points[MAX_TACTICAL_POINTS];
       int defend_codes[MAX_TACTICAL_POINTS];
       int attack_threat_points[MAX_TACTICAL_POINTS];
       int attack_threat_codes[MAX_TACTICAL_POINTS];
       int defense_threat_points[MAX_TACTICAL_POINTS];
       int defense_threat_codes[MAX_TACTICAL_POINTS];
     };

   * `color'
          If the worm is `BLACK' or `WHITE', that is its color.
          Cavities (empty worms) have an additional attribute which we
          call "bordercolor". This will be one of `BLACK_BORDER',
          `WHITE_BORDER' or `GRAY_BORDER'. Specifically, if all the
          worms adjacent to a given empty worm have the same color
          (black or white) then we define that to be the bordercolor.
          Otherwise the bordercolor is gray.

          Rather than define a new field, we keep this data in the
          field color. Thus for every worm, the color field will have
          one of the following values: `BLACK', `WHITE', `GRAY_BORDER',
          `BLACK_BORDER' or `WHITE_BORDER'.  The last three categories
          are empty worms classified by bordercolor.

   * `size'
          This field contains the cardinality of the worm.

   * `effective_size'
          This is the number of stones in a worm plus the number of
          empty intersections that are at least as close to this worm
          as to any other worm. Intersections that are shared are
          counted with equal fractional values for each worm. This
          measures the direct territorial value of capturing a worm.
          "effective_size" is a floating point number.  Only
          intersections at a distance of 4 or less are counted.

   * `origin'
          Each worm has a distinguished member, called its "origin".
          The purpose of this field is to make it easy to determine
          when two vertices lie in the same worm: we compare their
          origin. Also if we wish to perform some test once for each
          worm, we simply perform it at the origin and ignore the other
          vertices. The origin is characterized by the test:
               worm[pos].origin == pos.

   * `liberties'

   * `liberties2'

   * `liberties3'

   * `liberties4'
          For a nonempty worm the field liberties is the number of
          liberties of the string. This is supplemented by
          `LIBERTIES2', `LIBERTIES3' and `LIBERTIES4', which are the
          number of second order, third order, and fourth order
          liberties, respectively.  The definition of liberties of
          order >1 is adapted to the problem of detecting the shape of
          the surrounding cavity. In particular we want to be able to
          see if a group is loosely surrounded. "a liberty of order n"
          is an empty vertex which may be connected to the string by
          placing n stones of the same color on the board, but no
          fewer. The path of connection may pass through an intervening
          group of the same color. The stones placed at distance >1 may
          not touch a group of the opposite color. Connections through
          ko are not permitted. Thus in the following configuration:

                         .XX...    We label the     .XX.4.
                         XO....    liberties of     XO1234
                         XO....    order < 5 of     XO1234
                         ......    the O group:     .12.4.
                         .X.X..                     .X.X..

          The convention that liberties of order >1 may not touch a
          group of the opposite color means that knight's moves and one
          space jumps are perceived as impenetrable barriers.  This is
          useful in determining when the string is becoming surrounded.

          The path may also not pass through a liberty at distance 1 if
          that liberty is flanked by two stones of the opposing color.
          This reflects the fact that the O stone is blocked from
          expansion to the left by the two X stones in the following
          situation:

                         X.
                         .O
                         X.
          We say that n is the "distance" of the liberty of order n
          from the dragon.

   * `lunch'
          If nonzero, `lunch' points to a boundary worm which can be
          easily captured.  (It does not matter whether or not the
          string can be defended.)

   We have two distinct notions of cutting stone, which we keep track
of in the separate fields `worm.cutstone' and `worm.cutstone2'.  We use
currently use both concepts in parallel.

   * `cutstone'
          This field is equal to 2 for cutting stones, 1 for potential
          cutting stones. Otherwise it is zero.  Definitions for this
          field: a "cutting stone" is one adjacent to two enemy
          strings, which do not have a liberty in common. The most
          common type of cutting string is in this situation:


                         XO
                         OX

          A "potential cutting stone" is adjacent to two enemy strings
          which do share a liberty. For example, X in:


                         XO
                         O.

          For cutting strings we set `worm[].cutstone=2'. For potential
          cutting strings we set `worm[].cutstone=1'.

   * `cutstone2'
          Cutting points are identified by the patterns in the
          connections database. Proper cuts are handled by the fact
          that attacking and defending moves also count as moves
          cutting or connecting the surrounding dragons.  The
          `cutstone2' field is set during `find_cuts()', called from
          `make_domains()'.

   * `genus'
          There are two separate notions of "genus" for worms and
          dragons. The dragon notion is more important, so
          `dragon[pos].genus' is a far more useful field than
          `worm[pos].genus'. Both fields are intended as approximations
          to the number of eyes. The "genus" of a string is the number
          of connected components of its complement, minus one. It is
          an approximation to the number of eyes of the string.

   * `inessential'
          An "inessential" string is one which meets a criterion
          designed to guarantee that it has no life potential unless a
          particular surrounding string of the opposite color can be
          killed. More precisely an "inessential string" is a string S
          of genus zero, not adjacent to any opponent string which can
          be easily captured, and which has no edge liberties or second
          order liberties, and which satisfies the following further
          property: If the string is removed from the board, then the
          empty worm E which is the worm closure of the set of vertices
          which it occupied has bordercolor the opposite of the removed
          string. The empty worm E (empty, that is, as a worm of the
          board modified by removal of S) consists of the union of
          support of S together with certain other empty worms which we
          call the "boundary components" of S.

          The inessential strings are used in the amalgamation of
          cavities in `make_dragons()'.

   * `invincible'
          An "invincible" worm is one which GNU Go thinks cannot be
          captured. Invincible worms are computed by the function
          `unconditional_life()' which tries to find those worms of the
          given color that can never be captured, even if the opponent
          is allowed an arbitrary number of consecutive moves.

   * unconditional_status
          Unconditional status is also set by the function
          `unconditional_life'. This is set ALIVE for stones which are
          invincible. Stones which can not be turned invincible even if
          the defender is allowed an arbitrary number of consecutive
          moves are given an unconditional status of DEAD. Empty points
          where the opponent cannot form an invincible worm are called
          unconditional territory. The unconditional status is set to
          `WHITE_BORDER' or `BLACK_BORDER' depending on who owns the
          territory. Finally, if a stone can be captured but is
          adjacent to unconditional territory of its own color, it is
          also given the unconditional status `ALIVE'. In all other
          cases the unconditional status is `UNKNOWN'.

          To make sense of these definitions it is important to notice
          that any stone which is alive in the ordinary sense (even if
          only in seki) can be transformed into an invincible group by
          some number of consecutive moves. Well, this is not entirely
          true because there is a rare class of seki groups not
          satisfying this condition. Exactly which these are is left as
          an exercise for the reader. Currently `unconditional_life',
          which strictly follows the definitions above, calls such seki
          groups unconditionally dead, which of course is a misfeature.
          It is possible to avoid this problem by making the algorithm
          slightly more complex, but this is left for a later revision.

   * `int attack_points[MAX_TACTICAL_POINTS]'

   * `attack_codes[MAX_TACTICAL_POINTS]'

   * `int defense_points[MAX_TACTICAL_POINTS];'

   * `int defend_codes[MAX_TACTICAL_POINTS];'
          If the tactical reading code (*note Tactical Reading::) finds
          that the worm can be attacked, `attack_points[0]' is a point
          of attack, and `attack_codes[0]' is the attack code, `WIN',
          `KO_A' or `KO_B'. If multiple attacks are known,
          `attack_points[k]' and `attack_codes[k]' are used. Similarly
          with the defense codes and defense points.

   * `int attack_threat_points[MAX_TACTICAL_POINTS];'

   * `int attack_threat_codes[MAX_TACTICAL_POINTS];'

   * `int defense_threat_points[MAX_TACTICAL_POINTS];'

   * `int defense_threat_codes[MAX_TACTICAL_POINTS];'
          These are points that threaten to attack or defend a worm.

   The function `makeworms()' will generate data for all worms.


File: gnugo.info,  Node: Amalgamation,  Next: Connection,  Prev: Worms,  Up: Worms and Dragons

Amalgamation
============

   A dragon, we have said, is a group of stones which are treated as a
unit. It is a working hypothesis that these stones will live or die
together. Thus the program will not expect to disconnect an opponent's
strings if they have been amalgamated into a single dragon.

   The function `make_dragons()' will amalgamate worms into dragons by
maintaining separate arrays `worm[]' and `dragon[]' containing similar
data. Each dragon is a union of worms. Just as the data maintained in
`worm[]' is constant on each worm, the data in `dragon[]' is constant
on each dragon.

   "Amalgamation" of two worms means means in practice replacing the
origin of one worm by the origin of the other.  Amalgamation takes
place in two stages: first, the amalgamation of empty worms (cavities)
into empty dragons (caves); then, the amalgamation of colored worms into
dragons.

Amalgamation of cavities
========================

   As we have already defined it, a cavity is an empty worm. A cave is
an empty dragon.

   Under certain circumstances we want to amalgamate two or more
cavities into a single cave. This is done before we amalgamate strings.
An example where we wish to amalgamate two empty strings is the
following:


           OOOOO
          OOXXXOO
          OXaObXO
          OOXXXOO
           OOOOO

   The two empty worms at a and b are to be amalgamated.

   We have already defined a string to be "inessential" if it meets a
criterion designed to guarantee that it has no life potential unless a
particular surrounding string of the opposite color can be killed. An
"inessential string" is a string S of genus zero which is not a cutting
string or potential cutting string, and which has no edge liberties or
second order liberties (the last condition should be relaxed), and
which satisfies the following further property: If the string is
removed from the board, then the empty worm E which is the worm closure
of the set of vertices which it occupied has bordercolor the opposite
of the removed string.

   Thus in the previous example, after removing the inessential string
at the center the worm closure of the center vertex consists of an empty
worm of size 3 including a and b. The latter are the boundary
components.

   The last condition in the definition of inessential worms excludes
examples such as this:


             OOOO
            OXXOO
           OXX.XO
           OX.XXO
           OOXXO
            OOO

   Neither of the two X strings should be considered inessential
(together they form a live group!) and indeed after removing one of
them the resulting space has gray bordercolor, so by this definition
these worms are not inessential.

   Some strings which should by rights be considered inessential will be
missed by this criterion.

   The algorithm for amalgamation of empty worms consists of
amalgamating the boundary components of any inessential worm. The
resulting dragon has bordercolor the opposite of the removed string.

   Any dragon consisting of a single cavity has bordercolor equal to
that of the cavity.

Amalgamation of strings
=======================

   Amalgamation of nonempty worms in GNU Go 3.0 proceeds as follows.
First we amalgamate all boundary components of an eyeshape. Thus in the
following example:


     .OOOO.       The four X strings are amalgamated into a
     OOXXO.       single dragon because they are the boundary
     OX..XO       components of a blackbordered cave. The
     OX..XO       cave could contain an inessential string
     OOXXO.       with no effect on this amalgamation.
     XXX...

   The code for this type of amalgamation is in the routine
`dragon_eye()', discussed further in EYES.

   Next, we amalgamate strings which seem uncuttable. We amalgamate
dragons which either share two or more common liberties, or share one
liberty into the which the opponent cannot play without being captured.
(ignores ko rule).


        X.    X.X     XXXX.XXX         X.O
        .X    X.X     X......X         X.X
                      XXXXXX.X         OXX

   A database of connection patterns may be found in `patterns/conn.db'.


File: gnugo.info,  Node: Connection,  Next: Half Eyes,  Prev: Amalgamation,  Up: Worms and Dragons

Connection
==========

   The fields `black_eye.cut' and `white_eye.cut' are set where the
opponent can cut, and this is done by the B (break) class patterns in
`conn.db'.  There are two important uses for this field, which can be
accessed by the autohelper functions `xcut()' and `ocut()'. The first
use is to stop amalgamation in positions like


     ..X..
     OO*OO
     X.O.X
     ..O..

where X can play at * to cut off either branch. What happens here is
that first connection pattern CB1 finds the double cut and marks * as a
cutting point. Later the C (connection) class patterns in conn.db are
searched to find secure connections over which to amalgamate dragons.
Normally a diagonal connection would be deemed secure and amalgamated
by connection pattern CC101, but there is a constraint requiring that
neither of the empty intersections is a cutting point.

   A weakness with this scheme is that X can only cut one connection,
not both, so we should be allowed to amalgamate over one of the
connections.  This is performed by connection pattern CC401, which with
the help of `amalgamate_most_valuable_helper()' decides which
connection to prefer.

   The other use is to simplify making alternative connection patterns
to the solid connection. Positions where the diag_miai helper thinks a
connection is necessary are marked as cutting points by connection
pattern 12. Thus we can write a connection pattern like `CC6':


     ?xxx?     straight extension to connect
     XOO*?
     O...?
     
     :8,C,NULL
     
     ?xxx?
     XOOb?
     Oa..?
     
     ;xcut(a) && odefend_against(b,a)

where we verify that a move at `*' would stop the enemy from safely
playing at the cutting point, thus defending against the cut.


File: gnugo.info,  Node: Half Eyes,  Next: Dragons,  Prev: Connection,  Up: Worms and Dragons

Half Eyes and False Eyes
========================

   A "half eye" is a place where, if the defender plays first, an eye
will materialize, but where if the attacker plays first, no eye will
materialize. A "false eye" is a vertex which is surrounded by a dragon
yet is not an eye. Here is a half eye:


     XXXXX
     OO..X
     O.O.X
     OOXXX

   Here is a false eye:


     XXXXX
     XOO.X
     O.O.X
     OOXXX

   The "topological" algorithm for determining half and false eyes is
described elsewhere (*note Eye Topology::).

   The half eye data is collected in the dragon array. Before this is
done, however, an auxiliary array called half_eye_data is filled with
information. The field `type' is 0, or else `HALF_EYE' or `FALSE_EYE'
depending on which type is found; the fields `attack_point[]' point to
up to 4 points to attack the half eye, and similarly `defense_point[]'
gives points to defend the half eye.


     struct half_eye_data half_eye[MAX_BOARD];
     
     struct half_eye_data {
       float value;          /* Topological eye value */
       int type;             /* HALF_EYE or FALSE_EYE */
       int num_attacks;      /* Number of attacking points */
       int attack_point[4];  /* The moves to attack a topological halfeye */
       int num_defends;      /* Number of defending points */
       int defense_point[4]; /* The moves to defend a topological halfeye */
     };

   The array `struct half_eye_data half_eye[MAX_BOARD]' contains
information about half and false eyes.  If the type is `HALF_EYE' then
up to four moves are recorded which can either attack or defend the
eye. In rare cases the attack points could be different from the
defense points.


File: gnugo.info,  Node: Dragons,  Next: Dragons in Color,  Prev: Half Eyes,  Up: Worms and Dragons

Dragons
=======

   The array `struct dragon_data dragon[MAX_BOARD]' collects
information about the dragons. We will give definitions of the various
fields. Each field has constant value at each vertex of the dragon.


     struct dragon_data {
       int color;
       int id;
       int origin;
       int size;
       float effective_size;
       int status;
       int owl_threat_status;
       int owl_status;
       int owl_attack_point;
       int owl_attack_code;
       int owl_attack_certain;
       int owl_second_attack_point;
       int owl_defense_point;
       int owl_defense_code;
       int owl_defense_certain;
       int owl_second_defense_point;
       int matcher_status;
     };
     
     extern struct dragon_data dragon[BOARDMAX];

   Other fields attached to the dragon are contained in the
`dragon_data2' struct array.


     struct dragon_data2 {
       int origin;
       int adjacent[MAX_NEIGHBOR_DRAGONS];
       int neighbors;
       int hostile_neighbors;
       int moyo;
       int safety;
       int escape_route;
       int genus;
       int heyes;
       int heye;
       int lunch;
       int semeai;
       int semeai_margin_of_safety;
     };
     
     extern struct dragon_data2 *dragon2;

   The difference between the two arrays is that the `dragon' array is
indexed by the board, and there is a copy of the dragon data at every
stone in the dragon, while there is only one copy of the dragon2 data.
The dragons are numbered, and the `id' field of the dragon is a key
into the dragon2 array. Two macros DRAGON and DRAGON2 are provided for
gaining access to the two arrays.

     #define DRAGON2(pos) dragon2[dragon[pos].id]
     #define DRAGON(d) dragon[dragon2[d].origin]

   Thus if you know the position `pos' of a stone in the dragon you can
access the dragon array directly, for example accessing the origin with
`dragon[pos].origin'. However if you need a field from the dragon2
array, you can access it using the DRAGON2 macro, for example you can
access its neighor dragons by

     for (k = 0; k < DRAGON2(pos).neighbors; k++) {
       int d = DRAGON2(pos).adjacent[k];
       int apos = dragon2[d].origin;
       do_something(apos);
     }

   Similarly if you know the dragon number (which is `dragon[pos].id')
then you can access the `dragon2' array directly, or you can access the
`dragon' array using the DRAGON macro.

   Here are the definitions of each field in the `dragon' arrray.

   * `color'
          For strings, this is `BLACK' or `WHITE'.  For caves, it is
          `BLACK_BORDER', `WHITE_BORDER' or `GRAY_BORDER'. The meaning
          of these concepts is the same as for worms.

   * `id'
          The dragon number. This is a key into the `dragon2' array.

   * `origin'
          The origin of the dragon is a unique particular vertex of the
          dragon, useful for determining when two vertices belong to
          the same dragon. Before amalgamation the worm origins are
          copied to the dragon origins. Amalgamation of two dragons
          amounts to changing the origin of one.

   * `size'
          This is the cardinality of the dragon.

   * `effective_size'
          The sum of the effective sizes of the constituent worms.
          Remembering that vertices equidistant between two or more
          worms are counted fractionally in `worm.effective_size', this
          equals the cardinality of the dragon plus the number of empty
          vertices which are nearer this dragon than any other.

   * `genus'
          The "genus" of a nonempty dragon consists of the number of
          distinct adjacent caves whose bordercolor is the color of the
          dragon, minus the number of false eyes found. The genus is a
          computable approximation to the number of eyes a dragon has.

   * `escape_route'
          This is a measure of the escape potential of the dragon. If
          `dragon.escape_route' is large, GNU Go believes that the
          dragon can escape, so finding two eyes locally becomes less
          urgent. Further documentation may be found else where (*note
          Escape::).

   * `status'
          An attempt is made to classify the dragons as `ALIVE',
          `DEAD', `CRITICAL' or `UNKNOWN'. The `CRITICAL'
          classification means that the fate of the dragon depends on
          who moves first in the area. The exact definition is in the
          function `compute_dragon_status()'. If the dragon is found to
          be surrounded, the status is `DEAD' if it has less than 1.5
          eyes or if the reading code determines that it can be killed,
          `ALIVE' if it has 2 or more eyes, and `CRITICAL' if it has
          1.5 eyes. A lunch generally counts as a half eye in these
          calculations. If it has less than 2 eyes but seems possibly
          able to escape, the status may be `UNKNOWN'.

   * `owl_status'
          This is a classification similar to `dragon.status', but
          based on the life and death reading in `owl.c'.  The owl code
          (*note The Owl Code::) is only run on dragons with
          dragon.escape_route>5 and dragon2.moyo>10. If these
          conditions are not met, the owl status is `UNCHECKED'.  If
          `owl_attack()' determines that the dragon cannot be attacked,
          it is classified as `ALIVE'. Otherwise, `owl_defend()' is
          run, and if it can be defended it is classified as
          `CRITICAL', and if not, as `DEAD'.

   * `owl_attack_code'
          If the owl code finds that the dragon can be attacked, this
          is the attack code. It may be `WIN', `KO_A', `KO_B', or (if
          the dragon cannot be attacked) 0.

   * `owl_attack_point'
          If the owl code finds that the dragon can be attacked, this
          is the point of attack.

   * `owl_attack_certain'
          The function `owl_attack', which is used to set
          `owl_attack_code' and `owl_attack_point', is given an upper
          bound of `owl_node_limit' in the number of nodes it is
          allowed to generate. If this is exceeded the result is
          considered uncertain and this flag is set.

   * `owl_second_attack_point'
          Under certain circumstances the owl function
          `owl_threaten_attack' is asked if the dragon can be killed
          with two moves in a row. If two such killing moves are found,
          they are cached in `owl_attacki_point'
          `(owl_second_attack_point'.

   * `owl_defense_code'
          If the owl code finds that the dragon can be defended, this
          is the defense code (`WIN', `KO_A', `KO_B'); otherwise it is
          0.

   * `owl_defense_point'
          If the owl code finds that the dragon can be defended, this
          is the move.

   * `owl_defense_certain'

   * `owl_second_defense_point' Similar to `owl_attack_certain' and
     `owl_second_attack_point'.

   * `matcher_status'
          This is the status used by the pattern matcher. If
          `owl_status' is available (not `UNCHECKED') this is used.
          Otherwise, we use the `status' field, except that we upgrade
          `DEAD' to `UNKNOWN'.

   Here are definitions of each field in the `dragon2' array.

   * `origin'
          Duplicates the origin field from the dragon array.

   * `adjacent[MAX_NEIGHBOR_DRAGONS]'
          An array of adjacent dragons.

   * `neighbors'
          The number of adjacent dragons.

   * `hostile_neighbors'
          The number of adjacent dragons of the opposite color.

   * `moyo'
          Size of the surrounding influence moyo. Computed by
          `compute_surrounding_moyo_sizes()', calling the influence
          code.

   * `safety'
          This is a finer measure of dragon safety than
          `matcher_status'.  In addition to the values `ALIVE', `DEAD'
          and `CRITICAL' it can take the values `INESSENTIAL',
          `TACTICALLY_DEAD', `WEAK', `WEAKLY_ALIVE', `ALIVE_IN_SEKI',
          `STRONGLY_ALIVE' and `INVINCIBLE'.

   * `escape_route'
          A measure of the escape potential of the dragon. Further
          documentation may be found elsewhere (*note Escape::).

   * `genus'
          The "genus" of a nonempty dragon consists of the number of
          distinct adjacent caves whose bordercolor is the color of the
          dragon, minus the number of false eyes found. The genus is a
          computable approximation to the number of eyes a dragon has.

   * `heyes'
          This is the number of half eyes the dragon has. A "half eye"
          is a pattern where an eye may or may not materialize,
          depending on who moves first.

   * `heye'
          If any half eyes are found, this field points to a move which
          will create an eye.

   * `lunch'
          If nonzero, this field points to the location of a boundary
          worm which can be easily capture. In contrast with the worm
          version of this parameter we exclude strings which cannot be
          saved.

   * `semeai'
          True if the dragon is part of a semeai.

   * `semeai_margin_of_safety'
          Small if the semeai is close. Currently not reliable.


File: gnugo.info,  Node: Dragons in Color,  Next: Worm and Dragon Functions,  Prev: Dragons,  Up: Worms and Dragons

Colored Dragon Display
======================

   You can get a colored ASCII display of the board in which each dragon
is assigned a different letter; and the different values of
`dragon.status' values (`ALIVE', `DEAD', `UNKNOWN', `CRITICAL') have
different colors. This is very handy for debugging.  A second diagram
shows the values of `owl.status'. If this is `UNCHECKED' the dragon is
displayed in White.

   Save a game in sgf format using CGoban, or using the `-o' option with
GNU Go itself.

   Open an `xterm' or `rxvt' window. You may also use the Linux
console.  Using the console, you may need to use "SHIFT-PAGE UP" to see
the first diagram. Xterm will only work if it is compiled with color
support--if you do not see the colors try `rxvt'. Make the background
color black and the foreground color white.

   Execute:

   `gnugo -l [filename] -L [movenum] -T' to get the colored display.

   The color scheme: Green = `ALIVE'; Yellow = `UNKNOWN'; Cyan = `DEAD'
and Red = `CRITICAL'. Worms which have been amalgamated into the same
dragon are labelled with the same letter.

   Other useful colored displays may be obtained by using instead:

   * the option -E to display eye spaces (*note Eyes::).

   * the option -m 1 to display territory (*note Moyo::).

   The colored displays are documented elsewhere (*note Colored
Display::).


File: gnugo.info,  Node: Worm and Dragon Functions,  Prev: Dragons in Color,  Up: Worms and Dragons

Worm and Dragon Functions
=========================

   Here are the public functions in `engine/worm.c':

   * `void make_worms(int save_verbose)'
          This function finds all worms and assembles some data about
          them.  Each worm is marked with an origin.  This is an
          arbitrarily chosen element of the worm, in practice the
          algorithm puts the origin at the first element when they are
          given the lexicographical order, though its location is
          irrelevant for applications. To see if two stones lie in the
          same worm, compare their origins.

   * `int is_same_worm(int w1, int w2) '
          Test whether two worms are the same. Used by autohelpers.
          Before this function can be called, build_worms must have
          been run.

   * `int is_worm_origin(int w, int pos)'
          Test whether the origin of the worm at `w' is `pos'.

   * `void change_defense(int str, int move, int dcode)'
          `change_defense(str, move, dcode)' is used to add and remove
          defense points. It can also be used to change the defense
          code. The meaning of the call is that the string `str' can be
          defended by `move' with defense code `dcode'. If `dcode' is
          zero, the move is removed from the list of defense moves if
          it was previously listed.

   * `void change_attack(int str, int move, int acode)'
          `change_attack(str, move, acode)' is used to add and remove
          attack points. It can also be used to change the attack code.
          The meaning of the call is that the string `str' can be
          attacked by `move' with attack code `acode'. If `acode' is
          zero, the move is removed from the list of attack moves if it
          was previously listed.

   * `void change_defense_threat(int str, int move, int dcode)'
          Used to add and remove defense threat points. It can also be
          used to change the defense threat code. The meaning of the
          call is that the string `str' can threaten to be defended by
          `move' with defense threat code `dcode'. If `dcode' is zero,
          the move is removed from the list of defense threat moves if
          it was previously listed.

   * `void change_attack_threat(int str, int move, int acode)'
          Used to add and remove attack threat points. It can also be
          used to change the attack threat code. The meaning of the
          call is that the string `str' can threaten to be attacked by
          `move' with attack threat code `acode'. If `acode' is zero,
          the move is removed from the list of attack threat moves if
          it was previously listed.

   * `int attack_move_known(int move, int str)'
          Check whether `move' is listed as an attack point for `str'
          and return the attack code. If `move' is not listed, return 0.

   * `int defense_move_known(int move, int str)'
          Check whether `move' is listed as a defense point for `str'
          and return the defense code. If `move' is not listed, return
          0.

   * `int attack_threat_move_known(int move, int str)'
          Check whether `move' is listed as an attack threat point for
          `str' and return the attack threat code. If `move' is not
          listed, return 0.

   * `int defense_threat_move_known(int move, int str)'
          Check whether `move' is listed as a defense threat point for
          `str' and return the defense threat code. If `move' is not
          listed, return 0.

   * `void propagate_worm(int pos)'
          propagate_worm() takes the worm data at one stone and copies
          it to the remaining members of the worm.

   Here are the public functions in `engine/dragon.c':

   * `void make_dragons(int color, int stop_before_owl, int
     save_verbose)'
          This basic function finds all dragons and collects some basic
          information about them in the dragon array. `color' is the
          player in turn to move. This does in no way affect the
          information collected about the dragons, but it does affect
          what information is passed on to the move generation code. If
          `color == EMPTY' no information at all is passed on to the
          move generation.

   * `void show_dragons(void)'
          print status info on all dragons. (Can be invoked from gdb).

   * `int is_same_dragon(int d1, int d2)'
          Test whether two dragons are the same. Used by autohelpers
          and elsewhere.

   * `int are_neighbor_dragons(int d1, int d2)'
          Test whether two dragons are neighbors.

   * `void ascii_report_dragon(char *string)'

   * `void report_dragon(int m, int n)'
          For use in gdb, print details of the dragon.  Add this to
          your `.gdbinit' file:

               define dragon
               set ascii_report_dragon("$arg0")
               end

          Now 'dragon S8' will report the details of the S8 dragon.


File: gnugo.info,  Node: Eyes,  Next: Patterns,  Prev: Worms and Dragons,  Up: Top

Eyes and Half Eyes
******************

   The purpose of this Chapter is to describe the algorithm used in GNU
Go 3.0 to determine eyes. There are actually two alternative
algorithms: the graph-based algorithm in `optics.c', and the algorithm
based on reading in `life.c'. The life code is slower than the graph
based algorithm, but sometimes more accurate. You can enable it by
using the option `--life'.

* Menu:

* Local Games::                 Local games
* Eye Space::                   Eye space
* Eye Space as Local Game::     Eye space as local game
* Eye Example::                 An example
* Graphs::                      Underlying graphs
* Eye Shape::                   Pattern matching
* Eye Topology::                False eyes and half eyes
* Eye Topology with Ko::        False eyes and half eyes with ko
* False Margins::               False margins
* Eye Functions::               Functions in `optics.c'


File: gnugo.info,  Node: Local Games,  Next: Eye Space,  Prev: Eyes,  Up: Eyes

Local games
===========

   Each connected eyespace of a dragon affords a local game which yields
a local game tree. The score of this local game is the number of eyes
it yields. Usually if the players take turns and make optimal moves,
the end scores will differ by 0 or 1. In this case, the local game may
be represented by a single number, which is an integer or half integer.
Thus if `n(O)' is the score if `O' moves first, both players alternate
(no passes) and make alternate moves, and similarly `n(X)', the game
can be represented by `{n(O)|n(X)}'. Thus {1|1} is an eye, {2|1} is an
eye plus a half eye, etc.

   The exceptional game {2|0} can occur, though rarely. We call an
eyespace yielding this local game a CHIMERA.  The dragon is alive if
any of the local games ends up with a score of 2 or more, so {2|1} is
not different from {3|1}. Thus {3|1} is NOT a chimera.

   Here is an example of a chimera:

     XXXXX
     XOOOX
     XO.OOX
     XX..OX
     XXOOXX
     XXXXX


File: gnugo.info,  Node: Eye Space,  Next: Eye Space as Local Game,  Prev: Local Games,  Up: Eyes

Eye spaces
==========

   In order that each eyespace be assignable to a dragon, it is
necessary that all the dragons surrounding it be amalgamated (*note
Amalgamation::). This is the function of `dragon_eye()'.

   An EYE SPACE for a black dragon is a collection of vertices adjacent
to a dragon which may not yet be completely closed off, but which can
potentially become eyespace. If an open eye space is sufficiently
large, it will yield two eyes. Vertices at the edge of the eye space
(adjacent to empty vertices outside the eye space) are called MARGINAL.

   Here is an example from a game:


      |. X . X X . . X O X O
      |X . . . . . X X O O O
      |O X X X X . . X O O O
      |O O O O X . O X O O O
      |. . . . O O O O X X O
      |X O . X X X . . X O O
      |X O O O O O O O X X O
      |. X X O . O X O . . X
      |X . . X . X X X X X X
      |O X X O X . X O O X O

   Here the `O' dragon which is surrounded in the center has open eye
space. In the middle of this open eye space are three dead `X' stones.
This space is large enough that O cannot be killed. We can abstract the
properties of this eye shape as follows.  Marking certain vertices as
follows:


      |- X - X X - - X O X O
      |X - - - - - X X O O O
      |O X X X X - - X O O O
      |O O O O X - O X O O O
      |! . . . O O O O X X O
      |X O . X X X . ! X O O
      |X O O O O O O O X X O
      |- X X O - O X O - - X
      |X - - X - X X X X X X
      |O X X O X - X O O X O

the shape in question has the form:


     !...
       .XXX.!

   The marginal vertices are marked with an exclamation point (`!').
The captured `X' stones inside the eyespace are naturally marked `X'.

   The precise algorithm by which the eye spaces are determined is
somewhat complex. Documentation of this algorithm is in the comments in
the source to the function `make_domains()' in `optics.c'.

   The eyespaces can be conveniently displayed using a colored ascii
diagram by running `gnugo -E'.


File: gnugo.info,  Node: Eye Space as Local Game,  Next: Eye Example,  Prev: Eye Space,  Up: Eyes

The eyespace as local game
==========================

   In the abstraction, an eyespace consists of a set of vertices
labelled:


     !  .  X

   Tables of many eyespaces are found in the database
`patterns/eyes.db'. Each of these may be thought of as a local game.
The result of this game is listed after the eyespace in the form
`:max,min', where `max' is the number of eyes the pattern yields if `O'
moves first, while `min' is the number of eyes the pattern yields if
`X' moves first. The player who owns the eye space is denoted `O'
throughout this discussion. Since three eyes are no better than two,
there is no attempt to decide whether the space yields two eyes or
three, so max never exceeds 2. Patterns with min>1 are omitted from the
table.

   For example, we have:

     Pattern 548
     
      x
     x*x!
     
     :2,1

   Here notation is as above, except that `x' means `X' or `EMPTY'.
The result of the pattern is not different if `X' has stones at these
vertices or not.

   We may abstract the local game as follows. The two players `O' and
`X' take turns moving, or either may pass.

   RULE 1: `O' for his move may remove any vertex marked `!' or marked
`.'.

   RULE 2: `X' for his move may replace a `.' by an `X'.

   RULE 3: `X' may remove a `!'. In this case, each `.' adjacent to the
`!' which is removed becomes a `!' . If an `X' adjoins the `!' which is
removed, then that `X' and any which are connected to it are also
removed. Any `.' which are adjacent to the removed `X''s then become
`.'.

   Thus if `O' moves first he can transform the eyeshape in the above
example to:

      ...            or      !...
       .XXX.!                  .XXX.

   However if `X' moves he may remove the `!' and the `.'s adjacent to
the `!' become `!' themselves. Thus if `X' moves first he may transform
the eyeshape to:

      !..           or    !..
       .XXX.!              .XXX!

   NOTE: A nuance which is that after the `X:1', `O:2' exchange below,
`O' is threatening to capture three X stones, hence has a half eye to
the left of 2.  This is subtle, and there are other such subtleties
which our abstraction will not capture. Some of these at least can be
dealt with by a refinements of the scheme, but we will content
ourselves for the time being with a simplified model.


      |- X - X X - - X O X O
      |X - - - - - X X O O O
      |O X X X X - - X O O O
      |O O O O X - O X O O O
      |1 2 . . O O O O X X O
      |X O . X X X . 3 X O O
      |X O O O O O O O X X O
      |- X X O - O X O - - X
      |X - - X - X X X X X X
      |O X X O X - X O O X O

   We will not attempt to characterize the terminal states of the local
game (some of which could be seki) or the scoring.


File: gnugo.info,  Node: Eye Example,  Next: Graphs,  Prev: Eye Space as Local Game,  Up: Eyes

An example
==========

   Here is a local game which yields exactly one eye, no matter who
moves first:


     !
     ...
     ...!

   Here are some variations, assuming `O' moves first.

     !        (start position)
     ...
     ...!
     
     
     ...      (after `O''s move)
     ...!
     
     
     ...
     ..!
     
     
     ...
     ..
     
     
     .X.       (nakade)
     ..

   Here is another variation:


     !         (start)
     ...
     ...!
     
     
     !         (after `O''s move)
     . .
     ...!
     
     
     !         (after `X''s move)
     . .
     ..X!
     
     
     . .
     ..X!
     
     
     . !
     .!


File: gnugo.info,  Node: Graphs,  Next: Eye Shape,  Prev: Eye Example,  Up: Eyes

Graphs
======

   It is a useful observation that the local game associated with an
eyespace depends only on the underlying graph, which as a set consists
of the set of vertices, in which two elements are connected by an edge
if and only if they are adjacent on the Go board. For example the two
eye shapes:


     ..
      ..
     
     and
     
     ....

though distinct in shape have isomorphic graphs, and consequently they
are isomorphic as local games. This reduces the number of eyeshapes in
the database `patterns/eyes.db'.

   A further simplification is obtained through our treatment of half
eyes and false eyes. Such patterns are identified by the topological
analysis (*note Eye Topology::).

   A half eye is isomorphic to the pattern `(!.)' . To see this,
consider the following two eye shapes:

     XOOOOOO
     X.....O
     XOOOOOO
     and:
     
     XXOOOOO
     XOa...O
     XbOOOOO
     XXXXXXX

   These are equivalent eyeshapes, with isomorphic local games {2|1}.
The first has shape:


     !....

   The second eyeshape has a half eye at `a' which is taken when `O' or
`X' plays at `b'. This is found by the topological criterion (*note Eye
Topology::).

   The graph of the eye_shape, ostensibly `....' is modified by
replacing the left `.' by `!.' during graph matching.

   A false eye is isomorphic to the pattern `(!)' . To see this,
consider the following eye shape:


     XXXOOOOOO
     X.Oa....O
     XXXOOOOOO

   This is equivalent to the two previous eyeshapes, with an isomorphic
local game {2|1}.

   This eyeshape has a false eye at `a'. This is also found by the
topological criterion.

   The graph of the eye_shape, ostensibly `.....' is modified by
replacing the left `.' by `!'. This is made directly in the eye data,
not only during graph matching.


File: gnugo.info,  Node: Eye Shape,  Next: Eye Topology,  Prev: Graphs,  Up: Eyes

Eye shape analysis
==================

   The patterns in `patterns/eyes.db' are compiled into graphs
represented essentially by arrays in `patterns/eyes.c'.

   Each actual eye space as it occurs on the board is also compiled
into a graph. Half eyes are handled as follows.  Referring to the
example

     XXOOOOO
     XOa...O
     XbOOOOO
     XXXXXX

repeated from the preceding discussion, the vertex at `b' is added to
the eyespace as a marginal vertex. The adjacency condition in the graph
is a macro (in `optics.c'): two vertices are adjacent if they are
physically adjacent, or if one is a half eye and the other is its key
point.

   In `recognize_eyes()', each such graph arising from an actual
eyespace is matched against the graphs in `eyes.c'.  If a match is
found, the result of the local game is known. If a graph cannot be
matched, its local game is assumed to be {2|2}.


File: gnugo.info,  Node: Eye Topology,  Next: Eye Topology with Ko,  Prev: Eye Shape,  Up: Eyes

Topology of Half Eyes and False Eyes
====================================

   A HALF EYE is a pattern where an eye may or may not materialize,
depending on who moves first. Here is a half eye for `O':


        OOXX
        O.O.
        OO.X

   A FALSE EYE is a cave which cannot become an eye. Here are two
examples of false eyes for `O':


        OOX         OOX
        O.O         O.OO
        XOO         OOX

   We describe now the topological algorithm used to find half eyes and
false eyes. In this section we ignore the possibility of ko.

   False eyes and half eyes can locally be characterized by the status
of the diagonal intersections from an eye space. For each diagonal
intersection, which is not within the eye space, there are three
distinct possibilities:

   * occupied by an enemy (`X') stone, which cannot be captured.

   * either empty and `X' can safely play there, or occupied    by an
     `X' stone that can both be attacked and defended.

   * occupied by an `O' stone, an `X' stone that can be attacked    but
     not defended, or it's empty and `X' cannot safely play there.

   We give the first possibility a value of two, the second a value of
one, and the last a value of zero. Summing the values for the diagonal
intersections, we have the following criteria:

   * sum >= 4: false eye

   * sum == 3: half eye

   * sum <= 2: proper eye

   If the eye space is on the edge, the numbers above should be
decreased by 2. An alternative approach is to award diagonal points
which are outside the board a value of 1. To obtain an exact
equivalence we must however give value 0 to the points diagonally off
the corners, i.e.  the points with both coordinates out of bounds.

   The algorithm to find all topologically false eyes and half eyes is:

   For all eye space points with at most one neighbor in the eye space,
evaluate the status of the diagonal intersections according to the
criteria above and classify the point from the sum of the values.

