Merge pull request #50 from lemonsqueeze/can_countercap
[pachi.git] / README
blob4ed30386c842d2344e37560f4836a45cf4313a46
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.
6 Installation
7 ------------
9 To build Pachi, simply type:
11         make
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.)
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.
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.
28 Engine
29 ------
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.
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.
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.
50 How to run
51 ~~~~~~~~~~
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:
57         ./pachi -t _1200 threads=8,max_tree_size=3072
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.
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:
67         ./pachi -f book.dat ...
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.
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.
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.
83 DCNN support
84 ~~~~~~~~~~~~
86 Pachi can use a neural network as source of good moves to consider.
87 Currently this makes it about 1 stone stronger and tends to make the games
88 more pretty.
90 First, build Pachi with DCNN support:
91 - Install Caffe library (http://caffe.berkeleyvision.org)
92   CPU only build is fine, no need for GPU, cuda or the other optional
93   dependencies.
94 - Edit Makefile, set DCNN=1, point it to where caffe is installed and build.
96 Install dcnn files in current directory where pachi will run.
97 Detlef Schmicker's 54% dcnn can be found at:  
98   http://physik.de/CNNlast.tar.gz
100 More information about this dcnn can be found at:
101   http://computer-go.org/pipermail/computer-go/2015-December/008324.html
103 If you want to use a network with different inputs you'll have to tweak
104 dcnn.cpp to accomodate it. Pachi will check for "golast19.prototxt" and
105 "golast.trained" files on startup and use them if present when
106 playing on 19x19. For now dcnn and pondering can't be used together
107 (pondering data is thrown away).
110 Greedy Pachi
111 ~~~~~~~~~~~~
113 Normally, Pachi cares only for win or loss and does not take into
114 account the point amount. This means that it will play slack endgame
115 when winning and crazy moves followed with a resign when losing.
117 It may give you a more pleasurable playing experience if Pachi
118 _does_ take into account the point size, strives for a maximum
119 (reasonable) win margin when winning and minimal point loss when
120 losing. This is possible by using the maximize_score parameter, e.g.:
122         ./pachi -t _1200 threads=8,maximize_score
124 This enables an aggressive dynamic komi usage and end result margin
125 is included in node values aside of winrate. Pachi will also enter
126 scoring even when losing (normally, Pachi will never pass in that case).
127 Note that if you pass any 'dynkomi' parameter to Pachi, you will reset
128 the values set by 'maximize_score'.
130 Note that Pachi in this mode may be slightly weaker, and result margin
131 should not be taken into account when judging either player's strength.
132 During the game, the winning/losing margin can be approximated from
133 Pachi's "extra komi" or "xkomi" reporting in the progress messages.
135 Experiments and Testing
136 ~~~~~~~~~~~~~~~~~~~~~~~
138 Except UCT, Pachi supports a simple idiotbot-like engine and an example
139 treeless MonteCarlo-player. The MonteCarlo simulation ("playout")
140 policies are also pluggable, by default we use the one that makes use of
141 heavy domain knowledge.
143 Other special engines are also provided:
144 * a "distributed" engine for cluster play; the description at the top of
145   distributed/distributed.c should provide all the guidance
146 * a simple "replay" engine that will simply play moves according
147   to the playout policy suggestions
148 * a simple "patternplay" engine that will play moves according to the
149   learned patterns
150 * few other purely for development usage
152 Pachi can be used as a test opponent for development of other go-playing
153 programs. For example, to get the "plainest UCT" player, use:
155         ./pachi -t =5000 policy=ucb1,playout=light,prior=eqex=0,dynkomi=none,pondering=0,pass_all_alive
157 This will fix the number of playouts per move to 5000, switch the node
158 selection policy from ucb1amaf to ucb1 (i.e. disable RAVE), switch the
159 playouts from heuristic-heavy moggy to uniformly random light, stop
160 prioring the node values heuristically, turn off dynamic komi, disable
161 thinking on the opponent's time and make sure Pachi passes only when
162 just 10% alive stones remain on the board (to avoid disputes during
163 counting).
165 You can of course selectively re-enable various features or tweak this
166 further. But please note that using Pachi in this mode is not tested
167 extensively, so check its performance in whatever version you test
168 before you use it as a reference.
170 Note that even in this "basic UCT" mode, Pachi optimizes tree search
171 by considering board symmetries at the beginning. Currently, there's no
172 easy option to turn that off. The easiest way is to tweak board.c so
173 that board_symmetry_update() has goto break_symmetry at the beginning
174 and board_clear has board->symmetry.type = SYM_NONE.
177 Analysis
178 --------
180 Pachi can also help you analyze your games by being able to provide
181 its opinion on various positions. The user interface is very rudimentary,
182 but the ability is certainly there.
184 There are currently several Pachi interfaces provided for this purpose.
186 Winrate Development
187 ~~~~~~~~~~~~~~~~~~~
189 Pachi can evaluate all moves within a given game and show how
190 the winrates for both players evolved - i.e. who was winning at which
191 game stage. This is implemented using the `tools/sgf-analyse.pl` script.
192 See the comment on top of the script about its usage.
194 Move Ranking
195 ~~~~~~~~~~~~
197 Pachi can evaluate all available moves in a given situation
198 and for each give a value between 0 and 1 representing perceived
199 likelihood of winning the game if one would play that move. I.e. it can
200 suggest which moves would be good and bad in a single given situation.
202 To achieve the latter, note the number of move at the situation you
203 want to evaluate and run the `tools/sgf-ratemove.sh` script.
204 See the comment on top of the script about its usage.
206 Pattern Move Hinting
207 ~~~~~~~~~~~~~~~~~~~~
209 Pachi can show instantenous pattern-based move suggestions very much
210 like for example Moyo Go Studio (though of course without a GUI).
211 You can use the Move Ranking method above (tools/sgf-ratemove.sh),
212 but pass it an extra parameter '-e patternplay'.
215 Framework
216 ---------
218 The aim of the software framework is to make it easy to plug your
219 engine to the common infrastructure and implement your ideas while
220 minimalizing the overhead of implementing the GTP, speed-optimized
221 board implementation, etc.  Also, there are premade random playout
222 and UCT tree engines, so that you can directly tweak only particular
223 policies.  The infrastructure is pretty fast and it should be quite
224 easy for you (or us) to extend it to provide more facilities for
225 your engine.
227 See the HACKING file for a more detailed developer's view of Pachi.
229 Also, if you are interested about Pachi's architecture, algorithms
230 etc., consider taking a look at Petr Baudis' Master's Thesis:
232         http://pasky.or.cz/go/prace.pdf
234 ...or a slightly newer scientific paper on Pachi:
236         http://pasky.or.cz/go/pachi-tr.pdf
239 Licence
240 -------
242 Pachi is distributed under the GPLv2 licence (see the COPYING file for
243 details and full text of the licence); you are welcome to tweak it as
244 you wish (contributing back upstream is welcome) and distribute
245 it freely, but only together with the source code. You are welcome
246 to make private modifications to the code (e.g. try new algorithms and
247 approaches), use them internally or even to have your bot play on the
248 internet and enter competitions, but as soon as you want to release it
249 to the public, you need to release the source code as well.
251 One exception is the Autotest framework, which is licenced under the
252 terms of the MIT licence (close to public domain) - you are free to
253 use it any way you wish.