README

   1 Pachi can refer to: a simple modular framework for programs playing
   2 the game of Go/Weiqi/Baduk, and a reasonably strong engine built
   3 within this framework.
   4
   5
   6 Installation
   7 ------------
   8
   9 To build Pachi, simply type:
  10
  11         make
  12
  13 The resulting binary program `pachi` is a GTP client; connect to it
  14 with your favorite Go program interface (e.g. gogui or qgo), or use
  15 kgsGtp to connect it to KGS.  (DO NOT make the GTP interface accessible
  16 directly to untrusted users since the parser is not secure - see the
  17 HACKING file for details.)
  18
  19 The pachi program can take many parameters, as well as the particular
  20 engine being used; the defaults should be fine for initial usage,
  21 see below for some more tips.
  22
  23 In case you hit compilation issues (e.g. when building on MacOS/X)
  24 or want to change the build configuration, check the user configurable
  25 section at the top of the Makefile.
  26
  27
  28 Engine
  29 ------
  30
  31 The default engine plays by Chinese rules and should be about 7d KGS
  32 strength on 9x9. On 19x19 (using e.g. six-way Intel i7), it can hold
  33 a solid KGS 2d rank.  When using a large cluster (64 machines,
  34 20 cores each), it maintains KGS 3d to 4d and has won e.g. a 7-stone
  35 handicap game against Zhou Junxun 9p.
  36
  37 By default, Pachi currently uses the UCT engine that combines
  38 Monte Carlo approach with tree search; UCB1AMAF tree policy using
  39 the RAVE method is used for tree search, while the Moggy playout
  40 policy using 3x3 patterns and various tactical checks is used for
  41 the semi-random Monte Carlo playouts.  Large-scale board patterns
  42 are used in the tree search.
  43
  44 At the same time, we keep trying a wide variety of other approaches
  45 and enhancements. Pachi is an active research platform and quite a few
  46 improvements have been already achieved. We rigorously play-test new
  47 features and enable them by default only when they give a universal
  48 strength boost.
  49
  50 How to run
  51 ~~~~~~~~~~
  52
  53 By default, Pachi will run on a single CPU core, taking up to 1.4GiB
  54 of memory and taking a little under 15 seconds per move.  You can
  55 adjust these parameters by passing it extra command line options:
  56
  57         ./pachi -t _1200 threads=8,max_tree_size=3072
  58
  59 This will make Pachi play with time settings 20:00 S.D. with 8 threads,
  60 taking up to 3GiB of memory (+ several tens MiB as a constant overhead)
  61 and thinking during the opponent's turn as well.
  62
  63 Pachi can use an opening book in a Fuego-compatible format - you can
  64 obtain one at http://gnugo.baduk.org/fuegoob.htm and use it in Pachi
  65 with the -f parameter:
  66
  67         ./pachi -f book.dat ...
  68
  69 You may wish to append some custom Pachi opening book lines to book.dat;
  70 take them from the book.dat.extra file. If using the default Fuego book,
  71 you may want to remove the lines listed in book.dat.bad.
  72
  73 Pachi can also use a pattern database to improve its playing performance.
  74 You can get it at http://pachi.or.cz/pat/ - you will also find further
  75 instructions there.
  76
  77 For now, there is no comprehensive documentation of options, but you
  78 can get a pretty good idea by looking at the uct_state_init() function
  79 in uct/uct.c - you will find the list of UCT engine options there, each
  80 with a description. At any rate, usually the three options above are
  81 the only ones you really want to tweak.
  82
  83 Greedy Pachi
  84 ~~~~~~~~~~~~
  85
  86 Normally, Pachi cares only for win or loss and does not take into
  87 account the point amount. This means that it will play slack endgame
  88 when winning and crazy moves followed with a resign when losing.
  89
  90 It may give you a more pleasurable playing experience if Pachi
  91 _does_ take into account the point size, strives for a maximum
  92 (reasonable) win margin when winning and minimal point loss when
  93 losing. This is possible by using the maximize_score parameter, e.g.:
  94
  95         ./pachi -t _1200 threads=8,maximize_score
  96
  97 This enables an aggressive dynamic komi usage and end result margin
  98 is included in node values aside of winrate. Pachi will also enter
  99 scoring even when losing (normally, Pachi will never pass in that case).
 100 Note that if you pass any 'dynkomi' parameter to Pachi, you will reset
 101 the values set by 'maximize_score'.
 102
 103 Note that Pachi in this mode may be slightly weaker, and result margin
 104 should not be taken into account when judging either player's strength.
 105 During the game, the winning/losing margin can be approximated from
 106 Pachi's "extra komi" or "xkomi" reporting in the progress messages.
 107
 108 Experiments and Testing
 109 ~~~~~~~~~~~~~~~~~~~~~~~
 110
 111 Except UCT, Pachi supports a simple idiotbot-like engine and an example
 112 treeless MonteCarlo-player. The MonteCarlo simulation ("playout")
 113 policies are also pluggable, by default we use the one that makes use of
 114 heavy domain knowledge.
 115
 116 Other special engines are also provided:
 117 * a "distributed" engine for cluster play; the description at the top of
 118   distributed/distributed.c should provide all the guidance
 119 * a simple "replay" engine that will simply play moves according
 120   to the playout policy suggestions
 121 * a simple "patternplay" engine that will play moves according to the
 122   learned patterns
 123 * few other purely for development usage
 124
 125 Pachi can be used as a test opponent for development of other go-playing
 126 programs. For example, to get the "plainest UCT" player, use:
 127
 128         ./pachi -t =5000 policy=ucb1,playout=light,prior=eqex=0,dynkomi=none,pondering=0,pass_all_alive
 129
 130 This will fix the number of playouts per move to 5000, switch the node
 131 selection policy from ucb1amaf to ucb1 (i.e. disable RAVE), switch the
 132 playouts from heuristic-heavy moggy to uniformly random light, stop
 133 prioring the node values heuristically, turn off dynamic komi, disable
 134 thinking on the opponent's time and make sure Pachi passes only when
 135 just 10% alive stones remain on the board (to avoid disputes during
 136 counting).
 137
 138 You can of course selectively re-enable various features or tweak this
 139 further. But please note that using Pachi in this mode is not tested
 140 extensively, so check its performance in whatever version you test
 141 before you use it as a reference.
 142
 143 Note that even in this "basic UCT" mode, Pachi optimizes tree search
 144 by considering board symmetries at the beginning. Currently, there's no
 145 easy option to turn that off. The easiest way is to tweak board.c so
 146 that board_symmetry_update() has goto break_symmetry at the beginning
 147 and board_clear has board->symmetry.type = SYM_NONE.
 148
 149
 150 Analysis
 151 --------
 152
 153 Pachi can also help you analyze your games by being able to provide
 154 its opinion on various positions. The user interface is very rudimentary,
 155 but the ability is certainly there.
 156
 157 There are currently several Pachi interfaces provided for this purpose.
 158
 159 Winrate Development
 160 ~~~~~~~~~~~~~~~~~~~
 161
 162 Pachi can evaluate all moves within a given game and show how
 163 the winrates for both players evolved - i.e. who was winning at which
 164 game stage. This is implemented using the `tools/sgf-analyse.pl` script.
 165 See the comment on top of the script about its usage.
 166
 167 Move Ranking
 168 ~~~~~~~~~~~~
 169
 170 Pachi can evaluate all available moves in a given situation
 171 and for each give a value between 0 and 1 representing perceived
 172 likelihood of winning the game if one would play that move. I.e. it can
 173 suggest which moves would be good and bad in a single given situation.
 174
 175 To achieve the latter, note the number of move at the situation you
 176 want to evaluate and run the `tools/sgf-ratemove.sh` script.
 177 See the comment on top of the script about its usage.
 178
 179 Pattern Move Hinting
 180 ~~~~~~~~~~~~~~~~~~~~
 181
 182 Pachi can show instantenous pattern-based move suggestions very much
 183 like for example Moyo Go Studio (though of course without a GUI).
 184 You can use the Move Ranking method above (tools/sgf-ratemove.sh),
 185 but pass it an extra parameter '-e patternplay'.
 186
 187
 188 Framework
 189 ---------
 190
 191 The aim of the software framework is to make it easy to plug your
 192 engine to the common infrastructure and implement your ideas while
 193 minimalizing the overhead of implementing the GTP, speed-optimized
 194 board implementation, etc.  Also, there are premade random playout
 195 and UCT tree engines, so that you can directly tweak only particular
 196 policies.  The infrastructure is pretty fast and it should be quite
 197 easy for you (or us) to extend it to provide more facilities for
 198 your engine.
 199
 200 See the HACKING file for a more detailed developer's view of Pachi.
 201
 202 Also, if you are interested about Pachi's architecture, algorithms
 203 etc., consider taking a look at Petr Baudis' Master's Thesis:
 204
 205         http://pasky.or.cz/go/prace.pdf
 206
 207 ...or a slightly newer scientific paper on Pachi:
 208
 209         http://pasky.or.cz/go/pachi-tr.pdf
 210
 211
 212 Licence
 213 -------
 214
 215 Pachi is distributed under the GPLv2 licence (see the COPYING file for
 216 details and full text of the licence); you are welcome to tweak it as
 217 you wish (contributing back upstream is welcome) and distribute
 218 it freely, but only together with the source code. You are welcome
 219 to make private modifications to the code (e.g. try new algorithms and
 220 approaches), use them internally or even to have your bot play on the
 221 internet and enter competitions, but as soon as you want to release it
 222 to the public, you need to release the source code as well.
 223
 224 One exception is the Autotest framework, which is licenced under the
 225 terms of the MIT licence (close to public domain) - you are free to
 226 use it any way you wish.