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