Patternscan process_pattern(): Enlarge allocation step 1024 -> 1048576

[pachi.git] / README

Pachi can refer to: a simple modular framework for programs playing
the game of Go/Weiqi/Baduk, and a reasonably strong engine built
within this framework.


Installation
------------

To build Pachi, simply type:

        make

The resulting binary program `pachi` is a GTP client; connect to it
with your favorite Go program interface (e.g. gogui or qgo), or use
kgsGtp to connect it to KGS.  (DO NOT make the GTP interface accessible
directly to untrusted users since the parser is not secure - see the
HACKING file for details.)

The pachi program can take many parameters, as well as the particular
engine being used; the defaults should be fine for initial usage,
see below for some more tips.

In case you hit compilation issues (e.g. when building on MacOS/X)
or want to change the build configuration, check the user configurable
section at the top of the Makefile.


Engine
------

The default engine plays by Chinese rules and should be about
3d KGS strength on 9x9. On 19x19, it might be about KGS 2k, assuming
reasonable hardware, e.g. two-core Athlon64 machine.  On a higher-end
(e.g. six-way Intel i7) machine, it can hold a solid KGS 1d rank.
When using a large cluster (64 machines, 20 cores each), it maintains
KGS 3d and has won a 7-stone handicap game against Zhou Junxun 9p.

By default, Pachi currently uses the UCT engine that combines
Monte Carlo approach with tree search; UCB1AMAF tree policy using
the RAVE method is used for tree search, while the Moggy playout
policy using 3x3 patterns and various tactical checks is used for
the semi-random Monte Carlo playouts.

At the same time, we keep trying a wide variety of other approaches
and enhancements. Pachi is an active research platform and quite a few
improvements have been already achieved. We rigorously play-test new
features and enable them by default only when they give a universal
strength boost.


By default, Pachi will run on a single CPU core, taking up to 1.4GiB
of memory, not pondering and taking completely arbitrary amount of time
per turn. You can adjust these parameters by passing it extra command
line options:

        ./pachi -t _1200 threads=8,max_tree_size=3072,pondering

This will make Pachi play with time settings 20:00 S.D. (unless it
gets told otherwise over GTP), with 8 threads, taking up to 3GiB
of memory (+ several tens MiB as a constant overhead) and thinking
during the opponent's turn as well.

Pachi can use an opening book in a Fuego-compatible format - you can
obtain one at http://gnugo.baduk.org/fuegoob.htm and use it in Pachi
with the -f parameter:

        ./pachi -f book.dat ...

You may wish to append some custom Pachi opening book lines to book.dat;
take them from the book.dat.extra file. If using the default Fuego book,
you may want to remove the lines listed in book.dat.bad.

For now, there is no comprehensive documentation of options, but you
can get a pretty good idea by looking at the uct_state_init() function
in uct/uct.c - you will find the list of UCT engine options there, each
with a description. At any rate, usually the three options above are
the only ones you really want to tweak.


Except UCT, Pachi supports a simple idiotbot-like engine and an example
treeless MonteCarlo-player. The MonteCarlo simulation ("playout")
policies are also pluggable, by default we use the one that makes use of
heavy domain knowledge.

Other special engines are also provided:
* a "distributed" engine for cluster play; the description at the top of
  distributed/distributed.c should provide all the guidance
* a simple "replay" engine that will simply play moves according
  to the playout policy suggestions
* few other purely for development usage


Pachi can be used as a test opponent for development of other go-playing
programs. For example, to get the "plainest UCT" player, use:

        ./pachi -t =5000 policy=ucb1,playout=light,prior=eqex=0,dynkomi=none

This will fix the number of playouts per move to 5000, switch the node
selection policy from ucb1amaf to ucb1 (i.e. disable RAVE), switch the
playouts from heuristic-heavy moggy to uniformly random light, stop
prioring the node values heuristically, and turn off dynamic komi.

You can of course selectively re-enable various features or tweak this
further. But please note that using Pachi in this mode is not tested
extensively, so check its performance in whatever version you test
before you use it as a reference.

Note that even in this "basic UCT" mode, Pachi optimizes tree search
by considering board symmetries at the beginning. Currently, there's no
easy option to turn that off. The easiest way is to tweak board.c so
that board_symmetry_update() has goto break_symmetry at the beginning
and board_clear has board->symmetry.type = SYM_NONE.


Analysis
--------

Pachi can also help you analyze your games by being able to provide
its opinion on various positions. The user interface is very rudimentary,
but the ability is certainly there.

There are currently two Pachi interfaces provided for this purpose. One
possibility is to evaluate all moves within a given game and show how
the winrates for both players evolved - i.e. who was winning at which
game stage. This is implemented using the `tools/sgf-analyse.pl` script.
See the comment on top of the script about its usage.

Alternatively, Pachi can evaluate all available moves in a given situation
and for each give a value between 0 and 1 representing perceived
likelihood of winning the game if one would play that move. I.e. it can
suggest which moves would be good and bad in a single given situation.

To achieve the latter, follow few simple steps:

1. Take an SGF record of your game and generate a GTP file from it:

        tools/sgf2gtp.pl <file.sgf >file.gtp

2. Open the file.gtp in your favorite plaintext editor and trim it after
(remove all lines following) the move producing the situation you wish
to analyze.

3. Instead, add the following line at the bottom of file.gtp:

        0 uct_evaluate black

(replace `black` with `white` if it is white to play).

4. Run Pachi as follows:

        ./pachi -t =500 -d 0 <file.gtp | sed -n '/^=0/,${s/^=0 //;p}'

If you want to know more details on what is Pachi thinking about the
various moves, remove the `-d 0` and `| sed -n ...` parts. To improve
the accuracy of values (at the expense of run time), raise the value
of 500 (try 2000 or 10000; 100000 will usually already take couple of
hours). The values will be most useful in the middle game; in fuseki
and most yose situations, expect a lot of noise.


Framework
---------

The aim of the software framework is to make it easy to plug your
engine to the common infrastructure and implement your ideas while
minimalizing the overhead of implementing the GTP, speed-optimized
board implementation, etc.  Also, there are premade random playout
and UCT tree engines, so that you can directly tweak only particular
policies.  The infrastructure is pretty fast and it should be quite
easy for you (or us) to extend it to provide more facilities for
your engine.

See the HACKING file for a more detailed developer's view of Pachi.

Also, if you are interested about Pachi's architecture, algorithms
etc., consider taking a look at Petr Baudis' Master's Thesis:

        http://pasky.or.cz/go/prace.pdf


Licence
-------

Pachi is distributed under the GPLv2 licence (see the COPYING file for
details and full text of the licence); you are welcome to tweak it as
you wish (contributing back upstream is welcome) and distribute
it freely, but only together with the source code. You are welcome
to make private modifications to the code (e.g. try new algorithms and
approaches), use them internally or even to have your bot play on the
internet and enter competitions, but as soon as you want to release it
to the public, you need to release the source code as well.

One exception is the Autotest framework, which is licenced under the
terms of the MIT licence (close to public domain) - you are free to
use it any way you wish.