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 Engine
   7 ------
   8
   9 The default engine plays by Chinese rules and should be about
  10 3d KGS strength on 9x9. On 19x19, it might be about KGS 2k, assuming
  11 reasonable hardware, e.g. two-core Athlon64 machine.  On a higher-end
  12 (e.g. six-way Intel i7) machine, it can hold a solid KGS 1d rank.
  13 When using a large cluster (64 machines, 20 cores each), it will
  14 maintain KGS 3d and has won a 7-stone handicap against Zhou Junxun 9p.
  15
  16 By default, Pachi currently uses the UCT engine that combines
  17 Monte Carlo approach with tree search; UCB1AMAF tree policy using
  18 the RAVE method is used for tree search, while the Moggy playout
  19 policy using 3x3 patterns and various tactical checks is used for
  20 the semi-random Monte Carlo playouts.
  21
  22 At the same time, we keep trying a wide variety of other approaches
  23 and enhancements. Pachi is an active research platform and quite a few
  24 improvements have been already achieved. We rigorously play-test new
  25 features and enable them by default only when they give a universal
  26 strength boost.
  27
  28
  29 By default, Pachi will run on a single CPU core, taking up to 3GiB
  30 of memory, not pondering, etc. You can adjust these parameters by
  31 passing it extra command-line options:
  32
  33         ./zzgo -t _1200 threads=8,max_tree_size=500,fast_alloc,pondering
  34
  35 This will make Pachi play with time settings 20:00 S.D. (unless it
  36 gets told otherwise over GTP), with 8 threads, taking up to 500MiB
  37 of memory (+ several tens MiB as a constant overhead). 'fast_alloc'
  38 is just a good idea to do in case of memory-sensitive runs (will become
  39 default soon). 'pondering' will make Pachi keep thinking during the
  40 opponent's turn.
  41
  42 For now, there is no comprehensive documentation of options, but you
  43 can get a pretty good idea by looking at the uct_state_init() function
  44 in uct/uct.c - you will find the list of UCT engine options there, each
  45 with a description.
  46
  47
  48 Except UCT, Pachi supports a simple idiotbot-like engine and an example
  49 treeless MonteCarlo-player. The MonteCarlo simulation ("playout")
  50 policies are also pluggable, by default we use the one that makes use of
  51 heavy domain knowledge.
  52
  53 Other special engines are also provided:
  54 * a "distributed" engine for cluster play; the description at the top of
  55   distributed/distributed.c should provide all the guidance
  56 * a simple "replay" engine that will simply play moves according
  57   to the playout policy suggestions
  58 * few other purely for development usage
  59
  60
  61 Pachi can be used as a test opponent for development of other go-playing
  62 programs. For example, to get the "plainest UCT" player, use:
  63
  64         ./zzgo -t =5000 policy=ucb1,playout=light,prior=eqex=0,dynkomi=none
  65
  66 This will fix the number of playouts per move to 5000, switch the node
  67 selection policy from ucb1amaf to ucb1 (i.e. disable RAVE), switch the
  68 playouts from heuristic-heavy moggy to uniformly random light, stop
  69 prioring the node values heuristically, and turn off dynamic komi.
  70
  71 You can of course selectively re-enable various features or tweak this
  72 further. But please note that using Pachi in this mode is not tested
  73 extensively, so check its performance in whatever version you test
  74 before you use it as a reference.
  75
  76 Note that even in this "basic UCT" mode, Pachi optimizes tree search
  77 by considering board symmetries at the beginning. Currently, there's no
  78 easy option to turn that off. The easiest way is to tweak board.c so
  79 that board_symmetry_update() has goto break_symmetry at the beginning
  80 and board_clear has board->symmetry.type = SYM_NONE.
  81
  82
  83 Analysis
  84 --------
  85
  86 Pachi can also help you analyze your games by being able to provide
  87 its opinion on various positions. The user interface is very rudimentary,
  88 but the ability is certainly there.
  89
  90 There are currently two Pachi interfaces provided for this purpose. One
  91 possibility is to evaluate all moves within a given game and show how
  92 the winrates for both players evolved - i.e. who was winning at which
  93 game stage. This is implemented using the `tools/sgf-analyse.pl` script.
  94 See the comment on top of the script about its usage.
  95
  96 Alternatively, Pachi can evaluate all available moves in a given situation
  97 and for each give a value between 0 and 1 representing perceived
  98 likelihood of winning the game if one would play that move. I.e. it can
  99 suggest which moves would be good and bad in a single given situation.
 100
 101 To achieve the latter, follow few simple steps:
 102
 103 1. Take an SGF record of your game and generate a GTP file from it:
 104
 105         tools/sgf2gtp.pl <file.sgf >file.gtp
 106
 107 2. Open the file.gtp in your favorite plaintext editor and trim it after
 108 (remove all lines following) the move producing the situation you wish
 109 to analyze.
 110
 111 3. Instead, add the following line at the bottom of file.gtp:
 112
 113         0 uct_evaluate black
 114
 115 (replace `black` with `white` if it is white to play).
 116
 117 4. Run Pachi as follows:
 118
 119         ./zzgo -t =500 -d 0 <file.gtp | sed -n '/^=0/,${s/^=0 //;p}'
 120
 121 If you want to know more details on what is Pachi thinking about the
 122 various moves, remove the `-d 0` and `| sed -n ...` parts. To improve
 123 the accuracy of values (at the expense of run time), raise the value
 124 of 500 (try 2000 or 10000; 100000 will usually already take couple of
 125 hours). The values will be most useful in the middle game; in fuseki
 126 and most yose situations, expect a lot of noise.
 127
 128
 129 Framework
 130 ---------
 131
 132 The aim of the software framework is to make it easy to plug your
 133 engine to the common infrastructure and implement your ideas while
 134 minimalizing the overhead of implementing the GTP, speed-optimized
 135 board implementation, etc.  Also, there are premade random playout
 136 and UCT tree engines, so that you can directly tweak only particular
 137 policies.  The infrastructure is pretty fast and it should be quite
 138 easy for you (or us) to extend it to provide more facilities for
 139 your engine.
 140
 141 See the HACKING file for a more detailed developer's view of Pachi.
 142
 143
 144 Licence
 145 -------
 146
 147 Pachi is distributed under the GPLv2 licence (see the COPYING file for
 148 details and full text of the licence); you are welcome to tweak it as
 149 you wish (contributing back upstream is welcome) and distribute
 150 it freely, but only together with the source code. You are welcome
 151 to make private modifications to the code (e.g. try new algorithms and
 152 approaches), use them internally or even to have your bot play on the
 153 internet and enter competitions, but as soon as you want to release it
 154 to the public, you need to release the source code as well.
 155
 156 One exception is the Autotest framework, which is licenced under the
 157 terms of the MIT licence (close to public domain) - you are free to
 158 use it any way you wish.
 159
 160
 161 Installation
 162 ------------
 163
 164 To build Pachi, simply type:
 165
 166         make
 167
 168 The resulting binary program `zzgo` (named that way from historical
 169 reasons) is a GTP client; connect to it using your favorite Go program
 170 interface (e.g. gogui or qgo), or use kgsGtp to connect it to KGS.
 171 (DO NOT make the GTP interface accessible directly to untrusted users
 172 since the parser is not secure - see the HACKING file for details.)
 173
 174 The zzgo binary can take many parameters, as well as the particular
 175 engine being used; the defaults should be fine for initial usage,
 176 see above for some more tips.
 177
 178 In case you hit compilation issues (e.g. when building on MacOS/X)
 179 or want to change the build configuration, check the user configurable
 180 section at the top of the Makefile.