pattern.c: Introduce CAPTURE_COUNTSTONES_MAX
[pachi/nmclean.git] / README
blob9225e4fbec25536e90334b1793d619040b0ae36a
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
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.
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.
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.
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:
56         ./pachi -t _1200 threads=8,max_tree_size=3072,pondering
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.
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.
84 Except UCT, Pachi supports a simple idiotbot-like engine and an example
85 treeless MonteCarlo-player. The MonteCarlo simulation ("playout")
86 policies are also pluggable, by default we use the one that makes use of
87 heavy domain knowledge.
89 Other special engines are also provided:
90 * a "distributed" engine for cluster play; the description at the top of
91   distributed/distributed.c should provide all the guidance
92 * a simple "replay" engine that will simply play moves according
93   to the playout policy suggestions
94 * a simple "patternplay" engine that will play moves according to the
95   learned patterns
96 * few other purely for development usage
99 Pachi can be used as a test opponent for development of other go-playing
100 programs. For example, to get the "plainest UCT" player, use:
102         ./pachi -t =5000 policy=ucb1,playout=light,prior=eqex=0,dynkomi=none
104 This will fix the number of playouts per move to 5000, switch the node
105 selection policy from ucb1amaf to ucb1 (i.e. disable RAVE), switch the
106 playouts from heuristic-heavy moggy to uniformly random light, stop
107 prioring the node values heuristically, and turn off dynamic komi.
109 You can of course selectively re-enable various features or tweak this
110 further. But please note that using Pachi in this mode is not tested
111 extensively, so check its performance in whatever version you test
112 before you use it as a reference.
114 Note that even in this "basic UCT" mode, Pachi optimizes tree search
115 by considering board symmetries at the beginning. Currently, there's no
116 easy option to turn that off. The easiest way is to tweak board.c so
117 that board_symmetry_update() has goto break_symmetry at the beginning
118 and board_clear has board->symmetry.type = SYM_NONE.
121 Analysis
122 --------
124 Pachi can also help you analyze your games by being able to provide
125 its opinion on various positions. The user interface is very rudimentary,
126 but the ability is certainly there.
128 There are currently several Pachi interfaces provided for this purpose.
130 Winrate Development
131 ~~~~~~~~~~~~~~~~~~~
133 Pachi can evaluate all moves within a given game and show how
134 the winrates for both players evolved - i.e. who was winning at which
135 game stage. This is implemented using the `tools/sgf-analyse.pl` script.
136 See the comment on top of the script about its usage.
138 Move Ranking
139 ~~~~~~~~~~~~
141 Pachi can evaluate all available moves in a given situation
142 and for each give a value between 0 and 1 representing perceived
143 likelihood of winning the game if one would play that move. I.e. it can
144 suggest which moves would be good and bad in a single given situation.
146 To achieve the latter, note the number of move at the situation you
147 want to evaluate and run the `tools/sgf-ratemove.sh` script.
148 See the comment on top of the script about its usage.
150 Pattern Move Hinting
151 ~~~~~~~~~~~~~~~~~~~~
153 Pachi can show instantenous pattern-based move suggestions very much
154 like for example Moyo Go Studio (though of course without a GUI).
155 You can use the Move Ranking method above (tools/sgf-ratemove.sh),
156 but pass it an extra parameter '-e patternplay'.
159 Framework
160 ---------
162 The aim of the software framework is to make it easy to plug your
163 engine to the common infrastructure and implement your ideas while
164 minimalizing the overhead of implementing the GTP, speed-optimized
165 board implementation, etc.  Also, there are premade random playout
166 and UCT tree engines, so that you can directly tweak only particular
167 policies.  The infrastructure is pretty fast and it should be quite
168 easy for you (or us) to extend it to provide more facilities for
169 your engine.
171 See the HACKING file for a more detailed developer's view of Pachi.
173 Also, if you are interested about Pachi's architecture, algorithms
174 etc., consider taking a look at Petr Baudis' Master's Thesis:
176         http://pasky.or.cz/go/prace.pdf
179 Licence
180 -------
182 Pachi is distributed under the GPLv2 licence (see the COPYING file for
183 details and full text of the licence); you are welcome to tweak it as
184 you wish (contributing back upstream is welcome) and distribute
185 it freely, but only together with the source code. You are welcome
186 to make private modifications to the code (e.g. try new algorithms and
187 approaches), use them internally or even to have your bot play on the
188 internet and enter competitions, but as soon as you want to release it
189 to the public, you need to release the source code as well.
191 One exception is the Autotest framework, which is licenced under the
192 terms of the MIT licence (close to public domain) - you are free to
193 use it any way you wish.