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