uct/tree.h

   1 #ifndef PACHI_UCT_TREE_H
   2 #define PACHI_UCT_TREE_H
   3
   4 /* Management of UCT trees. See diagram below for the node structure.
   5  *
   6  * Two allocation methods are supported for the tree nodes:
   7  *
   8  * - calloc/free: each node is allocated with one calloc.
   9  *   After a move, all nodes except the subtree rooted at
  10  *   the played move are freed one by one with free().
  11  *   Since this can be very slow (seen 9s and loss on time because
  12  *   of this) the nodes are freed in a background thread.
  13  *   We still reserve enough memory for the next move in case
  14  *   the background thread doesn't free nodes fast enough.
  15  *
  16  * - fast_alloc: a large buffer is allocated once, and each
  17  *   node allocation takes some of this buffer. After a move
  18  *   is played, no memory if freed if the buffer still has
  19  *   enough free space. Otherwise the subtree rooted at the
  20  *   played move is copied to a temporary buffer, pruning it
  21  *   if necessary to fit in this small buffer. We copy by
  22  *   preference nodes with largest number of playouts.
  23  *   Then the temporary buffer is copied back to the original
  24  *   buffer, which has now plenty of space.
  25  *   Once the fast_alloc mode is proven reliable, the
  26  *   calloc/free method will be removed. */
  27
  28 #include <stdbool.h>
  29 #include <pthread.h>
  30 #include "move.h"
  31 #include "stats.h"
  32 #include "probdist.h"
  33
  34 struct board;
  35 struct uct;
  36
  37 /*
  38  *            +------+
  39  *            | node |
  40  *            +------+
  41  *          / <- parent
  42  * +------+   v- sibling +------+
  43  * | node | ------------ | node |
  44  * +------+              +------+
  45  *    | <- children          |
  46  * +------+   +------+   +------+   +------+
  47  * | node | - | node |   | node | - | node |
  48  * +------+   +------+   +------+   +------+
  49  */
  50
  51 /* TODO: Performance would benefit from a reorganization:
  52  * (i) Allocate all children of a node within a single block.
  53  * (ii) Keep all u stats together, and all amaf stats together.
  54  * Currently, rave_update is top source of cache misses, and
  55  * there is large memory overhead for having all nodes separate. */
  56
  57 struct tree_node {
  58         hash_t hash;
  59         struct tree_node *parent, *sibling, *children;
  60
  61         /*** From here on, struct is saved/loaded from opening tbook */
  62
  63         unsigned short depth; // just for statistics
  64
  65         /* Common Fate Graph distance from parent, but at most TREE_NODE_D_MAX+1 */
  66 #define TREE_NODE_D_MAX 3
  67         unsigned char d;
  68
  69 #define TREE_HINT_INVALID 1 // don't go to this node, invalid move
  70         unsigned char hints;
  71
  72         /* coord is usually coord_t, but this is very space-sensitive. */
  73 #define node_coord(n) ((int) (n)->coord)
  74         short coord;
  75
  76         /* In case multiple threads walk the tree, is_expanded is set
  77          * atomically. Only the first thread setting it expands the node.
  78          * The node goes through 3 states:
  79          *   1) children == null, is_expanded == false: leaf node
  80          *   2) children == null, is_expanded == true: one thread currently expanding
  81          *   2) children != null, is_expanded == true: fully expanded node */
  82         bool is_expanded;
  83
  84         struct move_stats u;
  85         struct move_stats prior;
  86         /* XXX: Should be way for policies to add their own stats */
  87         struct move_stats amaf;
  88         /* Stats before starting playout; used for distributed engine. */
  89         struct move_stats pu;
  90         /* Criticality information; information about final board owner
  91          * of the tree coordinate corresponding to the node */
  92         struct move_stats winner_owner; // owner == winner
  93         struct move_stats black_owner; // owner == black
  94 };
  95
  96 struct tree_hash;
  97
  98 struct tree {
  99         struct board *board;
 100         struct tree_node *root;
 101         struct board_symmetry root_symmetry;
 102         enum stone root_color;
 103
 104         /* Whether to use any extra komi during score counting. This is
 105          * tree-specific variable since this can arbitrarily change between
 106          * moves. */
 107         bool use_extra_komi;
 108         /* The value of applied extra komi. For DYNKOMI_LINEAR, this value
 109          * is only informative, the actual value is computed per simulation
 110          * based on leaf node depth. */
 111         floating_t extra_komi;
 112         /* Score in simulations, averaged over all branches, in the last
 113          * search episode. */
 114         struct move_stats avg_score;
 115
 116         /* We merge local (non-tenuki) sequences for both colors, occuring
 117          * anywhere in the tree; nodes are created on-demand, special 'pass'
 118          * nodes represent tenuki. Only u move_stats are used, prior and amaf
 119          * is ignored. Values in root node are ignored. */
 120         /* The value corresponds to black-to-play as usual; i.e. if white
 121          * succeeds in its replies, the values will be low. */
 122         struct tree_node *ltree_black;
 123         /* ltree_white has white-first sequences as children. */
 124         struct tree_node *ltree_white;
 125         /* Aging factor; 2 means halve all playout values after each turn.
 126          * 1 means don't age at all. */
 127         floating_t ltree_aging;
 128
 129         /* Hash table used when working as slave for the distributed engine.
 130          * Maps coordinate path to tree node. */
 131         struct tree_hash *htable;
 132         int hbits;
 133
 134         // Statistics
 135         int max_depth;
 136         volatile unsigned long nodes_size; // byte size of all allocated nodes
 137         unsigned long max_tree_size; // maximum byte size for entire tree, > 0 only for fast_alloc
 138         unsigned long max_pruned_size;
 139         unsigned long pruning_threshold;
 140         void *nodes; // nodes buffer, only for fast_alloc
 141 };
 142
 143 /* Warning: all functions below except tree_expand_node & tree_leaf_node are THREAD-UNSAFE! */
 144 struct tree *tree_init(struct board *board, enum stone color, unsigned long max_tree_size,
 145                        unsigned long max_pruned_size, unsigned long pruning_threshold, floating_t ltree_aging, int hbits);
 146 void tree_done(struct tree *tree);
 147 void tree_dump(struct tree *tree, int thres);
 148 void tree_save(struct tree *tree, struct board *b, int thres);
 149 void tree_load(struct tree *tree, struct board *b);
 150
 151 struct tree_node *tree_get_node(struct tree *tree, struct tree_node *node, coord_t c, bool create);
 152 struct tree_node *tree_garbage_collect(struct tree *tree, struct tree_node *node);
 153 void tree_promote_node(struct tree *tree, struct tree_node **node);
 154 bool tree_promote_at(struct tree *tree, struct board *b, coord_t c);
 155
 156 void tree_expand_node(struct tree *tree, struct tree_node *node, struct board *b, enum stone color, struct uct *u, int parity);
 157 struct tree_node *tree_lnode_for_node(struct tree *tree, struct tree_node *ni, struct tree_node *lni, int tenuki_d);
 158
 159 static bool tree_leaf_node(struct tree_node *node);
 160
 161 #define tree_node_parity(tree, node) \
 162         ((((node)->depth ^ (tree)->root->depth) & 1) ? -1 : 1)
 163
 164 /* Get black parity from parity within the tree. */
 165 #define tree_parity(tree, parity) \
 166         (tree->root_color == S_WHITE ? (parity) : -1 * (parity))
 167
 168 /* Get a 0..1 value to maximize; @parity is parity within the tree. */
 169 #define tree_node_get_value(tree, parity, value) \
 170         (tree_parity(tree, parity) > 0 ? value : 1 - value)
 171
 172 static inline bool
 173 tree_leaf_node(struct tree_node *node)
 174 {
 175         return !(node->children);
 176 }
 177
 178 static inline floating_t
 179 tree_node_criticality(const struct tree *t, const struct tree_node *node)
 180 {
 181         /* cov(player_gets, player_wins) =
 182          * [The argument: If 'gets' and 'wins' is uncorrelated, b_gets * b_wins
 183          * is valid way to obtain winner_gets. The more correlated it is, the
 184          * more distorted the result.]
 185          * = winner_gets - (b_gets * b_wins + w_gets * w_wins)
 186          * = winner_gets - (b_gets * b_wins + (1 - b_gets) * (1 - b_wins))
 187          * = winner_gets - (b_gets * b_wins + 1 - b_gets - b_wins + b_gets * b_wins)
 188          * = winner_gets - (2 * b_gets * b_wins - b_gets - b_wins + 1) */
 189         return node->winner_owner.value
 190                 - (2 * node->black_owner.value * node->u.value
 191                    - node->black_owner.value - node->u.value + 1);
 192 }
 193
 194 #endif