README

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