path: root/typhoon.sgml

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.0//EN">
  <book>
    <bookinfo>
      <title>Typhoon Chess Engine</title>
      <author>
        <firstname>Scott</firstname>
        <surname>Gasch</surname>
        <affiliation>
          <address><email>[email protected]</email></address>
        </affiliation>
      </author>
      <copyright>
        <year>2002-2006</year>
        <holder role="mailto:[email protected]">Scott Gasch</holder>
      </copyright>
      <pubdate role="rcs">$Date$</pubdate>
      <releaseinfo>$Id$</releaseinfo>
      <abstract>
        <para>
This is a user's guide for the <ulink
url="http://wannabe.guru.org/scott/hobbies/chess">typhoon chess
engine</ulink>.  Its intended audience is the set of people who have
downloaded a copy of my chess engine source code available at <ulink
url="http://wannabe.guru.org/svn/typhoon/trunk">
http://wannabe.guru.org/svn/typhoon/trunk</ulink> or have downloaded a
precompiled binary that someone else compiled.  The goal of this
manual is to document how to build and use the chess engine.  If you
don't care about how to use typhoon are instead looking for a more
technical discussion of how to write your own chess engine you might
try <ulink url="http://wannabe.guru.org/scott/hobbies/chess">
http://wannabe.guru.org/scott/hobbies/chess</ulink> or simply dig 
into the <ulink url="http://wannabe.guru.org/svn/typhoon/trunk"> 
source code</ulink> itself.
        </para>
        <para>
This user's guide is available in several formats:
      <itemizedlist>
      <listitem><para>One large HTML file: <ulink
      url="http://wannabe.guru.org/scott/hobbies/chess/typhoon.html">
      http://wannabe.guru.org/scott/hobbies/chess/typhoon.html</ulink>
      </para></listitem>
      <listitem><para>Plain (7 bit ASCII) text: <ulink
      url="http://wannabe.guru.org/scott/hobbies/chess/typhoon.txt">
      http://wannabe.guru.org/scott/hobbies/chess/typhoon.txt</ulink>
      </para></listitem>
      <listitem><para>Adobe PostScript: <ulink
      url="http://wannabe.guru.org/scott/hobbies/chess/typhoon.ps">
      http://wannabe.guru.org/scott/hobbies/chess/typhoon.ps</ulink>
      </para></listitem>
      <listitem><para>Adobe Portable Document Format (PDF): <ulink
      url="http://wannabe.guru.org/scott/hobbies/chess/typhoon.pdf">
      http://wannabe.guru.org/scott/hobbies/chess/typhoon.pdf</ulink>
      </para></listitem>
      <listitem><para>Microsoft Rich Text Format (RTF): <ulink
      url="http://wannabe.guru.org/scott/hobbies/chess/typhoon.rtf">
      http://wannabe.guru.org/scott/hobbies/chess/typhoon.rtf</ulink>
      </para></listitem>
      </itemizedlist>
      </abstract>
    </bookinfo>
  <chapter>
    <title>Preliminaries</title>
    <para>
This is a the user's guide for the typhoon chess engine.  It covers
how to build, install, configure and use the engine.
    </para>
    <para>
If you are impatient, have a look at the <link linkend="quickstart">
Quick Start Guide</link> section; it
will take you through the basics of getting the engine installed and
working.  Come back to the rest of the user's guide if you run into
difficulties.
    </para>
    <para>
Readers with more patience may skip the Quick Start and read the rest
of the guide in order for a run though of how to get the engine
installed and configured.  This will also familiarize you with more
advanced topics such as how to build your own opening book from PGN
files, how to instruct typhoon to use Eugene Nalimov format endgame
tablebases, how to run script files and how to execute commends
automatically at engine startup time.
    </para>
    <para>
Feel free to <ulink url="mailto:[email protected]">email
me</ulink> with questions or problems.  Before you do, though, please
read this guide and see if your query has been addressed already.
    </para>
    <sect1>
      <title>Introduction</title>
      <para>
Typhoon is a chess playing program that I've been working on for a
few years now as a hobby.  It's ugly, unpolished and full of
bugs.  While it has its moments of brilliance, it is not yet as strong
as some other freely available engines like Yace or Crafty.  If you
<link linkend="bugs">find a bug</link>, especially one related to 
playing strength, <ulink url="mailto:[email protected]">I'd 
like to hear about it.</ulink>
      </para>
      <para>
When I reach a point in this project where I am happy with the playing
strength, usability, stability and portability of the engine I'll
release it under the GPL or a similar license.  Until then please
consider the source code an alpha-quality prerelease.  Do not
redistribute, sell, or modify my chess engine.
      </para>
      <para>
Typhoon has a modest (and probably outdated) homepage on the Internet
at <ulink url="http://wannabe.guru.org/scott/hobbies/chess/">
http://wannabe.guru.org/scott/hobbies/chess/</ulink>.  Drop by and
have a look.  Typhoon has played in three (3) tournaments to date,
<ulink url= "http://www.vrichey.de/cct3/">CCT3</ulink>, <ulink url=
"http://www.vrichey.de/cct4/">CCT4</ulink> and <ulink url=
"http://www.vrichey.de/cct5/">CCT5</ulink>.  In CCT3 it placed 30th of
32.  In CCT4 it placed 15th of 46.  In CCT5 is placed 6th of 45.
The engine also plays from time to time on the <ulink
url="http://www.chessclub.com">Internet Chess Club</ulink> where it
maintains a <ulink
url="http://www.chessclub.com/cgi-bin/finger/finger.pl?handle=monsoon">
standard rating around 2500 and a blitz rating around 2700</ulink>.
      </para>
      <para>
Finally, all files in this archive except where otherwise noted are
Copyright (C) 2002-2006 by Scott Gasch.  They come with no warranty
of any kind.  There are known bugs in the engine.  If you choose to
use the chess engine then you do so at your own risk.  Caveat emptor.
      </para>
    </sect1>
    <sect1>
    <title>Acknowledgments </title>
      <para>
Thanks to all the members of the <ulink
url="http://www.talkchess.com"> Computer Chess Club (CCC)</ulink>
discussion board especially Bob Hyatt (<application>Cray
Blitz</application>, <application>Crafty</application>) and Bruce
Moreland (<application>Ferret</application>,
<application>Gerbil</application>) for their patience and willingness
to explain chess-programming concepts.
      </para>
      <para>
Thanks to Eugene Nalimov and Ernst Heniz
(<application>DarkThought</application>) for their continuing work on
high quality endgame tablebases.
      </para>
      <para>
Thanks to Tim Mann for his continuing work on
<application>xboard</application> /
<application>WinBoard</application>.  Thanks to Tom Kerrigan
(<application>TSCP</application>, <application>Stobor</application>)
for publishing <application>TSCP</application> source code which was
the first chess engine I read and the reason I became interested in
chess programming.  Thanks to Thorsten Greiner for writing and
publishing the source to his <application>Amy</application> program
and (again) to Bob Hyatt for writing and publishing the source to
<application>Crafty</application>.
      </para>
      <para>
Thanks (again) to Ernst Heinz for publishing his research on
computer chess.
      </para>
      <para>
Thanks to FM Vincent Diepeveen (<application>Diep</application>) for
his discussions and expert advice.  Many thanks to Dann Corbit for the
initial port of typhoon to the <application>Microsoft Visual
C/C++</application> and <application>Intel C++</application>
compilers.
      </para>
      <para>
Thanks to IM Mark Chapman for his help with opening book lines and his
patient expert analysis of chess positions.
      </para>
      <para>
Thanks to Peter McKenzie (<application>LambChop</application>,
<application>Warp</application>) for discussing chess programming
ideas and sharing his thoughts and advice.
      </para>
      <para>
Finally many thanks to Steve Timson
(<application>Chester</application>) for sharing his good ideas and
listening to my lousy ones... without his advice typhoon would surely
not be as strong as it is today.
      </para>
      <para>
The binaries included in the typhoon distribution are based, in part,
on code that I did not write.  Such code remains under the copyright 
notice of it's author.  I'm grateful to the original authors of the
code listed below for sharing it and giving me permission to use it.
      </para>
      <itemizedlist>
      <listitem>
      <para><filename>mtf.c</filename> (Mersenne Twister random number
      generator) is Copyright (C) 1997 by Makoto Matsumoto and Takuji
      Nishimura.  It has been included in typhoon with the authors'
      permissions. 
      </para></listitem>
      <listitem><para>
      (part of) <filename>system.c</filename>, specifically the case
      insensitive string comparison and manipulation functions, were
      taken from the source code for the BSD C runtime library when
      they were found to be not present on Win32.  This code was
      released under the BSD license and remains Copyright (C) 1987 by
      Regents of the University of California.
      </para></listitem>
      <listitem><para>
      <emphasis>Win32 timer code</emphasis> was donated by Dann Corbit
      during the initial port of typhoon to Win32.  It's used with the
      author's permission.  Thanks, Dann!
      </para></listitem>
      <listitem><para>
      <filename>egtb.cpp</filename> was written
      by Eugene Nalimov, released as part of crafty, and reused with
      the author's permission.
      </listitem>
      </itemizedlist>
    </sect1>
    <sect1 id="quickstart">
      <title>Quick Start Guide</title>
      <para>
This is the raw step-by-step guide for getting your copy working on
your computer.  If you have questions about any step, stop reading 
the Quick Start Guide and move on to the <link linkend="compile">
detailed explanation</link> later in this document.  In fact, if 
you are not impatient, go ahead and skip the whole Quick Start 
Guide; everything covered here is also covered more completely
later on.
      </para>
      <orderedlist>
      <listitem>
      <para>
Verify that you are either running some flavor of <application>Windows
NT (NT/2000/XP/Server 2003/Vista)</application>, <application>
FreeBSD</application>, <application>Linux</application> or <application>
OSX</application>.
      </para>
      </listitem>
      <listitem>
      <para>
Verify that you intend to run the chess engine on an x86
microprocessor (Intel Pentium, AMD Athlon, Intel-based Mac, etc...) 
      </para>
      </listitem>
      <listitem>
      <para>
If you plan to compile the engine from source code, follow the
steps below.  If you have a precompiled binary for your system
you can skip these.
        <orderedlist>
        <listitem>
        <para>
        You will need either <application>gcc, g++</application>, and
        <application>gmake</application> or the <application>Microsoft 
        Visual C++</application> compiler.
        </para>
        </listitem>
        <listitem>
        <para>
        You will also need a copy of the <application>nasm</application>
        assembler.
        </para>
        </listitem>
        <listitem>
        <para>
        Copy the source code to a directory on your machine (or
        <link linkend="svn">use Subversion</link> to get a
        snapshot).
        </para>
        </listitem>
        <listitem>
        <para>
        If you're using <application>gcc, g++</application> and
        <application>gmake</application> have a look at
        <filename>GNUmakefile</filename> and make sure all 
        variables look reasonable to you.  Then, from the 
        commandline type <userinput>make PERF_COUNTERS=1</userinput>.  
        This will produce a binary image
        called <filename>typhoon</filename> if all goes well.
        </para>
        <para>
        If you're using <application>MSVC</application>, select 
        the "Release" configuration and build it.  If all
        goes well it will produce a binary called <filename>
        typhoon.exe</filename> in the <filename>Release/</filename>
        subdirectory.  Note that you may have to edit
        the project settings to point to where <filename>nasm.exe
        </filename> can be found on your system.
        </para>
        </listitem>
        <listitem>
        <para>
        If you want to build a multithreaded version of the engine
        with <application>gcc</application>, add
        <userinput>MP=1</userinput> to your <application>gmake
        </application> commandline.  If
        you're interested in building a multithreaded engine with
        <application>MSVC</application> just build the "MP Release"
        configuration.
        </para>
        </listitem>
        </orderedlist>
      </para>
      </listitem>
      <listitem>
      <para>
      All you need to play chess is the typhoon binary itself and
      some chessboard GUI program (like Tim Mann's <ulink
      url="http://www.tim-mann.org/xboard.html"><application>
      xboard</application> (or <application>winboard</application>)
      </ulink>).  To run typhoon under <application>xboard</application>
      just type <userinput>xboard -fcp /path/to/typhoon</userinput>.  
      Note that typhoon requires version 4.2.3 or higher of
      <application>xboard</application> (or 
      <application>WinBoard</application>).  
      There is also a <link linkend="winboard">section 
      about using typhoon under <application>xboard</application>
      or <application>WinBoard</application></link> later in this guide.
      </para>
      <para>
      If you want an opening book you can either download one from
      <ulink url="http://wannabe.guru.org/scott/hobbies/chess/books">my
      site</ulink> or build your own from PGN.  If you're interested
      in the latter, <link linkend="makebook">see the guide section
      about building a book from scratch</link>.
      </para>
      <para>
      If you're interested in doing anything non-trivial with
      the engine you'll probably want to read the sections on
      <link linkend="commandline">commandline arguments</link>, 
      <link linkend="commands">commands</link>, and 
      <link linkend="egtb">tablebases</link> later in this document.
      </para>
      </listitem>
      </orderedlist>
      <para>
If you have any problems, please read the rest of this guide before
<ulink url="mailto:[email protected]">emailing me</ulink>.
      </para>
    </sect1>
    <sect1>
      <title>System Requirements</title>
      <para>
Typhoon only runs on x86 microprocessor based systems.  This means
that your Intel Pentium or AMD Athlon system will work.  This also
means that more recent Apple Macs will run the program.  I have
not yet ported the code to any other processor architecture.
It's possible that there will be a native AMD64 port of typhoon
in the future (namely, when I buy a machine).
      </para>
      <para>
Typhoon only runs under <application>Windows NT</application>
(<application>Windows NT 4.0</application>, <application>Windows 2000
</application>, <application>Windows XP</application>, <application>
Windows Server 2003</application>, <application>Windows Vista
</application>), <application>FreeBSD</application>, 
<application>Linux</application> and <application>OSX</application>.
      </para>
      <para>
Specifically, the engine, when built with Microsoft Visual C/C++, is
known not to work with <application>Windows 95</application>,
<application>Windows 98</application>, and <application>Windows
ME</application>.  Some third parties have reported that the engine
does work under <application>Windows 98</application> when built with
Cygwin but I have never tried this configuration.  If you're not sure
what version of Windows you are using, click "start" then "run" then
type <userinput>winver</userinput>.  If the version reported is
greater than or equal to 5.0 then your operating system can definitely
run typhoon.
      </para>
      <para>
The codebase may build on other operating systems for Intel-based 
processors.  If <application>gcc</application> and <application>
nasm</application> are available for your platform of choice, give 
it a try and <ulink url="mailto:[email protected]">let me know
</ulink> how it goes.
      </para>
      <para>
If you got a precompiled version of typhoon from some third party then,
of course, you need to make sure the version you received was built for
your system.
      </para>
<note>
<para>
I do <emphasis>not</emphasis> currently provide a precompiled version
of the code and that running any program someone else built for you
is inherently risky.  Make sure you trust the source of such an image
and be careful running it.  If you're unsure of the integrity of the
source of the precompiled package it's better to build your own.
</para>
</note>
      <para>
To run the engine your computer should have something reasonable like
at least 128Mb or memory and around 10Mb of free hard drive space for an
opening book.
      </para>
      <para>
The engine does not need to be run with administrative privileges but if
you do run it with elevated privileges it will do some nice things like
try to lock its memory and run with slightly raised priority.
      </para>
      <para>
While a chess GUI (like <application>xboard</application>, 
<application>WinBoard</application>, or
<application>Arena</application>) is not technically "required" 
in order to typhoon, they make the experience more enjoyable. 
The engine itself has no UI to speak of -- it is its only
output is text based. Therefore it's strongly recommended that you
download and install some GUI frontend to use with typhoon.
There is a <link linkend="winboard">section</link> later in this
guide that describes where to get <application>WinBoard</application>
and how to get the engine working with it.
      </para>
    </sect1>
    <sect1 id="compile">
    <title>Compilation Guide</title>
      <para>
If you want to compile the chess engine from source code (which may be
your only option since at present I do not distribute binary images of
the engine) you will probably need to use 
<application>gcc/g++</application> with GNU
<application>make</application>, <application>gcc/g++</application>
with BSD-style <application>make</application> or <application>Microsoft
Visual C/C++</application>.
      </para>
      <para>
I've built typhoon successfully on pretty much every version
of <application>gcc</application> from 2.8 onward. I've also used 
all of the Microsoft compilers from <application>VC6.0</application>
onward. As far as I know any of these should work fine with the
caveat that the <filename>typhoon.sln</filename> file currently
checked in and available on the source site is for 
<application>Microsoft Visual C/C++ 2003</application>.
      </para>
<note>
<para>
I have never tried using <application>mingw</application> 
(<application>gcc</application> for <application>Windows</application>)
or Intel's <application>icc</application> (which claims to compile 
<application>MSVC</application> projects) so if you try one let me know
how it goes. The code is reasonably compiler agnostic so getting it to
build on some other random C/C++ compiler should be relatively
painless... I hope.  If you have any success porting the codebase
to another toolset, please <ulink url="mailto:[email protected]">
drop me a line</ulink>.
</para>
</note>
      <para>
In order to build <filename>x86.asm</filename> you will also need a copy of 
the <ulink url="http://nasm.sourceforge.net/wakka.php?wakka=HomePage">
Netwide Assembler (<application>nasm</application>)</ulink>.  Some
(much hairier) alternatives are to translate the assembly language 
to work with some other assembler or to just use the C-language 
versions of the routines in <filename>x86.asm</filename>.  Neither 
option is recommended.  Make sure that if you are building typhoon
on a Mac you have a version of <application>nasm</application> that
can produce mach0 format object files (i.e. it supports the 
<userinput>-f macho</userinput> commandline flag).
      </para>
      <para>
Start by copying everything from <ulink
url="http://wannabe.guru.org/svn/typhoon/trunk">svn/typhoon/trunk</ulink>
into a directory on your machine.  While you can do this manually (or
with wget/fetch), a cool alternative is to use <ulink
url="http://subversion.tigris.org/"><application>Subversion</application>
</ulink> (a version control system) to <link linkend="svn">check out
a read-only snapshot of the code</link> from my server.  The reason
I do not have a pre-packaged code archive is because the code you can
download from the URL above is a current snapshot of the chess engine; 
when you use the URL above you are getting the most recent update of
the engine available.
      </para>
      <para>
Have a look at the <filename>README</filename> file to humor me.  
Then, what happens next depends largely on what compiler you have
chosen to use.
      </para>
      <para>
If you decided on the <application>gcc/g++/gmake</application>
toolset, take a look at the <filename>GNUmakefile</filename>.  
You might want to change some variables such as CC, CXX and NASM,
and CPU based on the system you plan to build with.  The defaults 
are probably reasonable in most cases.
      </para>
      <para>
If you have a BSD-style <application>make</application>, take a
look at <filename>Makefile</filename> instead.
      </para>
      <para>
In order to build a single threaded release version of the chess
engine, type <userinput>make PERF_COUNTERS=1</userinput>.
A multithreaded release version is almost the same, just add an
<userinput>MP=1</userinput> to the line.  Whereas both <application>
Linux</application> and <application>FreeBSD</application> based
systems require explicit no build flags, to build for Apple
<application>OSX</application> systems you should add an additional
<userinput>OSX=1</userinput> to the build commandline.
      </para>
      <para>
While we're on the subject, here's a list of the preprocessor 
symbols that you can use when building typhoon and their effects:
      <informaltable>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Preprocessor symbol</entry>
            <entry>Effect on image</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>DEBUG</entry>
            <entry>Produces a much slower image that has extra checks
            enabled.  Symbols are not stripped.  See <link
            linkend="debug">the section about DEBUG builds</link> for
            more information.</entry>
          </row>
          <row>
            <entry>TEST</entry>
            <entry>Bakes some unit testcases into the image, enables
            the <userinput>test</userinput> command.  Refer to
            <link linkend="test">the section about TEST builds</link>
            for more information.</entry>
          </row>
          <row>
            <entry>ASM</entry>
            <entry>Causes <application>gcc</application> to produce
            intermediate assembly language (<filename>.s</filename>) 
            files during the build.</entry>
          </row>
          <row>
            <entry>EVAL_DUMP</entry>
            <entry>Causes the engine to pay attention to all terms
            affecting a position's evaluation and be dump them
            after every eval.  Read <link linkend="evaldump">
            the section about EVAL_DUMP builds</link> to learn
            more.</entry>
          </row>
          <row>
            <entry>EVAL_TIME</entry>
            <entry>Causes the engine to pay attention to how many
            processor cycles it spends evaluating each position.
            </entry>
          </row>
          <row>
            <entry>PERF_COUNTERS</entry>
            <entry>Enables several performance related counters
            in the engine.</entry>
          </row>
          <row>
            <entry>BOUNDS_CHECKING</entry>
            <entry>If you have patched your version of <application>
            gcc</application> to include <userinput>-fbounds-checking
            </userinput>, this builds an image with baked in
            bounds checking support.</entry>
          </row>
          <row>
            <entry>MP</entry>
            <entry>Enables the threadpool and search-splitting code
            needed to support more than one thread searching at a
            time.</entry>
          </row>
          <row>
            <entry>DUMP_TREE</entry>
            <entry>Produces dumps of search trees in XML format.  Tree
            dump files can be viewed with a web browser or using the
            <application>typhoonui.exe</application> viewer in the 
            <application>Subversion</application> repository.
            </entry>
          </row>
          <row>
            <entry>OSX</entry>
            <entry>Produces a binary for Intel-based Apple Macs</entry>
          </row>
        </tbody>
      </tgroup>
      </informaltable>
      </para>
      <para>
Building with <application>MSVC</application> involves selecting a
configuration and compiling.  You probably want to build "Release"
or "MP Release".  The only wrinkle is that in the custom build step
you will probably have to set the path to
<application>nasm</application> on your system.  The resulting image
will be either <filename>Release\typhoon.exe</filename> or 
<filename>MP Release\typhoon.exe</filename> depending on which 
configuration you built.
      </para>
      <para>
The image you build can run stand-alone as a text-based chess engine
with no opening book.  But if you want to run in a more comfortable
manner, read on to the next sections which cover the details of setup.
    </sect1>
    <sect1 id="svn">
      <title>Using <application>Subversion</application> to get Typhoon</title>
      <para>
I use the <application>Subversion</application> version control system to 
develop typhoon.  If you have <application>svn</application>
installed on your system you can use it to check out a read-only
snapshot of the source code on your machine, keep up to date with
changes I make, access file histories, project branches and change
logs.
      </para>
      <para>
Just use the URL <filename>http://wannabe.guru.org/svn/typhoon</filename>
as your repository path.  To get the initial snapshot of the code
issue the <userinput>svn checkout</userinput> command from a directory
you created to house the typhoon source code:
      </para>
<screen>
svn checkout http://wannabe.guru.org/svn/typhoon/trunk
</screen>
      <para>
The command <userinput>svn co</userinput> is a shorthand version of 
<userinput>svn checkout</userinput>.  Also, if you want more of the
typhoon project than just the current code, you can omit the
<userinput>/trunk</userinput> from the end of your command.  Warning,
this will checkout a bunch of papers, PGN files, opening books,
etc; the disk space requirements for the full repository are non 
trivial.
      </para>
      <para>
In order to synchronize your enlistment with the current state of the
code on my machine, use the <userinput>svn up</userinput> command.
Another useful commands is <userinput>svn log
http://wannabe.guru.org/svn/typhoon</userinput> which will give you a
high level overview of what changed from revision to revision.  An
alternative is <ulink
url="http://wannabe.guru.org/cgi-bin/svn.pl?operation=log">http://wannabe.guru.org/cgi-bin/svn.pl?operation=log</ulink>.
Using <userinput>svn diff</userinput> allows you to see source code
changes at a file level.
      </para>
<screen>
svn up
</screen>
<para>
When I am actively developing the engine I make at least one checkin
a week (usually more like one a day).  So if you want to track the 
bleeding edge, this is the way to do it.
</para>
    </sect1>
    <sect1 id="install">
      <title>Installation Guide</title>
      <para>
Once you have a typhoon binary image (either from building it 
yourself or from downloading a precompiled binary from some third
party) you may want to do some simple setup work.
      </para>
      <orderedlist>
      <listitem>
      <para>
The first thing you may want to do is to install Tim Mann's graphical
chessboard.  The UNIX version is called <application>
xboard</application> and the Windows version is called <application>
WinBoard</application>.  Both can be obtained from the site <ulink
url="http://www.tim-mann.org">http://www.tim-mann.org</ulink>.  This program
will provide a nice graphical user interface to typhoon which is a
text-based engine.  Without it you'll be stuck looking at chessboards
on a commandline interface.  There is a <link linkend="winboard">chapter 
later in this guide</link> about how to configure the engine to work 
under WinBoard.
      </para>
      <para>
An alternative to <application>xboard</application>/<application>
WinBoard</application> is <application>Arena</application>, another 
graphical chessboard program which can be downloaded at <ulink
url="http://www.playwitharena.com/">http://www.playwitharena.com</ulink>.
While I have only done preliminary testing with Arena, typhoon seems to 
work just fine as a WB2 engine under <application>Arena
1.99beta2</application>.  Since I haven't done much with Arena, if
you want to add typhoon as an Arena engine you're on your own.
      </para>
      </listitem>
      <listitem>
      <para>
After you've installed either <application>xboard</application>, 
<application>WinBoard</application> or <application>Arena</application>
you'll need to copy the typhoon image into some directory on your hard
drive.  I usually use <filename>C:\typhoon</filename> but you can put
it wherever you like.  I'll be referring to the directory you put 
the image in as the "typhoon installation directory" from now on in 
this guide.
      </para>
      </listitem>
      <listitem>
      <para>
You now have all you need to play chess.  However, without an opening
move library the engine will play the same opening moves every game.
If you want an opening move library you have two choices: either
download one or build one yourself.  
      </para>
      <para>
The former choice is easier and I have several opening books available
on my server.  You can get them from <ulink
url="http://wannabe.guru.org/scott/hobbies/chess/books">
http://wannabe.guru.org/scott/hobbies/chess/books</ulink>.  The larger
the file, the more opening moves in the library.  If you choose to
download an opening library file, just pick one and save it to the
typhoon installation directory as <filename>book.bin</filename>.
      </para>
      <para>
The advantage of building your own opening library is that it's an
easy way to tailor the playing style of the engine.  It will only play
the opening lines you train it with.  To go this route you will need
a PGN file full of games you want the engine to learn opening moves
from.  Read <link linkend="makebook">the section about making a
custom opening book</link> for detailed instructions.
      </para>
      </listitem>
      <listitem>
      <para>
Just as an opening library is a database of common opening moves for
the engine to use, an endgame tablebase is a database of endgame
positions that the engine can access during the endgame.  Typhoon
knows how to read Eugene Nalimov format EGTB files which are the same 
ones that the popular engine Crafty uses.  These files are quite
large; all 3-4-5 man files are over 7Gb in size compressed.  A 
good resource for learning more aboue EGTB files (including
where to get them) is 
<ulink url="http://www.aarontay.per.sg/Winboard/egtb.html">
http://www.aarontay.per.sg/Winboard/egtb.html</ulink>.
      </para>
      <para>
If you have EGTB files on your disk you can tell typhoon where they are
using the "--egtbpath" commandline argument.  This flag preceeds a 
quoted, semi-colon delimited path:
      </para>
<screen>
typhoon --egtbpath "C:\egtb\three;C:\egtb\four;C:\egtb\five"
</screen>
      <para>
You will know that typhoon found and could use the EGTB files if you
see it produce a message like "Found 5-men endgame table bases."
during startup.
<link linkend="egtb">More information about the use of EGTB
files</link> appears later in the guide.
      </para>
      </listitem>
      <listitem>
      <para>
The final thing you'll need to do to run the engine on your computer
is set the hash table sizes based on the amount of memory you have
in your computer.  If you run the engine stand-alone (i.e. not under
a GUI like WinBoard) you can issue the command "dump sizes" to see 
how much memory the pawn hash table and main hash table are using.
As you can see, the default is for the engine to use just over
300Mb of physical memory:
      </para>
<screen>
white(1): <userinput>dump sizes</userinput>
sizeof(PAWN_HASH_ENTRY). . . . . . . . . 88 bytes
sizeof(HASH_ENTRY) . . . . . . . . . . . 16 bytes
sizeof(MOVE) . . . . . . . . . . . . . . 4 bytes
sizeof(ATTACK_BITV). . . . . . . . . . . 4 bytes
sizeof(SQUARE) . . . . . . . . . . . . . 8 bytes
sizeof(POSITION) . . . . . . . . . . . . 1428 bytes
sizeof(MOVE_STACK) . . . . . . . . . . . 233992 bytes
sizeof(PLY_INFO) . . . . . . . . . . . . 424 bytes
sizeof(COUNTERS) . . . . . . . . . . . . 236 bytes
sizeof(SEARCHER_THREAD_CONTEXT). . . . . 264056 bytes
sizeof(GAME_OPTIONS) . . . . . . . . . . 1136 bytes
sizeof(MOVE_TIMER) . . . . . . . . . . . 40 bytes
sizeof(PIECE_DATA) . . . . . . . . . . . 16 bytes
sizeof(VECTOR_DELTA) . . . . . . . . . . 4 bytes
sizeof(GAME_PLAYER). . . . . . . . . . . 16 bytes
sizeof(GAME_HEADER). . . . . . . . . . . 64 bytes
sizeof(GAME_MOVE). . . . . . . . . . . . 60 bytes
sizeof(GAME_DATA). . . . . . . . . . . . 72 bytes
sizeof(SEE_LIST) . . . . . . . . . . . . 196 bytes
sizeof(BOOK_ENTRY) . . . . . . . . . . . 36 bytes
-------------------------------------------------
Current pawn hash table size . . . . . . 46137344 bytes (~44 Mb)
Current main hash table size . . . . . . 268435456 bytes (~256 Mb)
</screen>
      <para>
If this amount exceeds the amount of physical memory on your machine
the engine will be extremely slow.  It is possible to reduce the
memory footprint of the engine by setting the sizes of the main hash
table and the pawn hash table.  To do so, use the "--hash" and 
"--pawnhash" commandline options.  These flags take an argument which
is the number of entries in the table.  This number must be an even 
power of two.  For example:
      </para>
<screen>
typhoon --hash 16384 --pawnhash 1024
</screen>
      <para>
The above command allocates a hash table of 16384 (2^14) entries and
a pawn hash table of 1024 (2^10) entries.  Since each main hash entry
is 16 bytes in size, the total memory used by 16384 main hash entries
is approximately 256kb.  Likewise each pawn hash entry is currently 
88 bytes in size making the total memory used by 1024 of them around
88kb.
      </para>
      <para>
If you don't understand any of this, just use the numbers in the 
sample above.  Since they are very low the engine will definitely 
not use too much memory for your computer.  If you did 
understand the paragraph above and care about "optimal performance" then
you should set the engine to use as much memory as you can spare.
More hash table entries means a higher hash hit percentage and a faster
search in most cases.
      </para>
      </listitem>
      </orderedlist>
    </sect1>
  </chapter>
  <chapter id="running">
    <title>Running Typhoon</title>
    <para>
This chapter covers typhoon's commandline arguments and command
parser.  It gives a list of useful commands for interacting with the
engine.  Note that if you are running the engine under
<application>WinBoard</application> or some other GUI front end then
your interface will send the commands to typhoon on your behalf.  This
is a much easier way to interact with engine and is recommended for
most users.  The following sections assumes you are an advanced user
and running typhoon in text mode in order to interact with the program
directly.
    </para>
    <sect1 id="commandline">
    <title>Commandline Arguments</title>
      <para>
The following section covers the commandline arguments available when
starting the engine and the affect of each on its behavior.
      <orderedlist>
      <listitem>
      <para>
The <emphasis>--cpus</emphasis> argument, followed by a number, can
be used with multiprocessor builds of typhoon to indicate how many
searcher threads should be created.  The number of searcher threads
should be set to the number of processors in the system:
      </para>
      <screen>
typhoon --cpus 2
      </screen>
      </listitem>
      <listitem>
      <para>
The flag <emphasis>--command</emphasis>, followed by a quoted string,
can be used to pass an initial command to the engine.  Typhoon will 
execute the initial command before processing any user input.  The
initial command is often used to specify a script to execute.
      </para>
<screen>
typhoon --command "bench"
</screen>
      </listitem>
      <listitem>
      <para>
The <emphasis>--hash</emphasis> and <emphasis>--pawnhash</emphasis>
arguments take a number indicating the size of the main hash table
and pawn hash table respectively.  These sizes must be even powers
of two or they will be rounded down.  These commands allow you to
tailor engine memory usage to the size of physical memory on your
system.  See the <link linkend="install">installation guide</link>
for a full discussion of how this argument works.
      </para>
<screen>
typhoon --hash 16384 --pawnhash 1024
</screen>
      </listitem>
      <listitem>
      <para>
Use <emphasis>--egtbpath</emphasis> with a quoted string in order to
set the path in which the engine should search for Nalimov format
EGTB files.  The string can contain more than one directory if the
different directories are separated by semi-colons (;).
      </para>
<screen>
typhoon --egtbpath "C:\TB\three;C:\TB\four;C:\TB\five"
</screen>
      </listitem>
      <listitem>
      <para>
Use <emphasis>--batch</emphasis> to indicate that the engine should 
never listen to user input from the console.  This flag takes no
additional parameters and must be used in conjunction with the 
<emphasis>--command</emphasis> flag.  The presence of
<emphasis>--batch</emphasis> causes the engine to skip starting
an input thread and exit immediately after executing the initial
command.
      </para>
      <screen>
typhoon --command "script C:\ECM.EPD" --batch
      </screen>
      </listitem>
      </orderedlist>
    </sect1>      
    <sect1>
    <title>Entering Moves</title>
      <para>
The most common input you'll probably send to the engine is a chess
move.  Typhoon understands moves in two (2) formats: Standard Algebraic
Notation (SAN) and the <userinput>d2d4</userinput> format.  When you 
enter a move in one of these formats that affects a piece of the side
on move, the move will be made and the board redrawn.
      </para>
    </sect1>
    <sect1 id="commands">
    <title><application>WinBoard</application> Commands</title>
      <para>
Typhoon supports many commands that are part of the
<application>WinBoard</application> protocol.  These commands are
fully documented in Tim Mann's xboard engine interface document at
<ulink url="http://www.tim-mann.org/xboard/engine-intf.html">
http://www.tim-mann.org/xboard/engine-intf.html</ulink>.  I will
briefly discuss a subset of them here.
      </para>
      <itemizedlist>
      <listitem>
      <para><emphasis>xboard</emphasis>, <emphasis>random</emphasis>,
      <emphasis>hint</emphasis>, and <emphasis>variant</emphasis>, and
      <emphasis>edit</emphasis> are not implemented in typhoon and are
      basically no-ops.  Typhoon can only play regular chess, no
      variants are supported.  To edit a position typhoon uses the
      newer opcode <userinput>setboard</userinput>.
      </para>
      <listitem>
      <para><emphasis>quit</emphasis> is used to exit the chess
      program.
      </para>
      <listitem>
      <para><emphasis>new</emphasis> is used to start a new game.
      This sets the computer to play black, resets the maximum search
      depth, resets the board, and clears all internal data
      structures.
      </para>
      <listitem>
      <para><emphasis>force</emphasis> puts the engine in "force
      mode" which means it plays neither side.
      </para>
      <listitem>
      <para><emphasis>white</emphasis> and <emphasis>black</emphasis>
      are used to tell the engine what color the opponent plays and
      what side has the move currently.  For example
      <userinput>white</userinput> means the engine should play black
      and that it is current white's turn to move.
      </para>
      <listitem>
      <para><emphasis>sd</emphasis> can be used as an alternative to
      <userinput>set SearchDepthLimit</userinput> to set the maximum
      depth in ply that the engine should search a position.  The
      maximum value is 63, the minimum is 1.
      </para>
      <listitem>
      <para><emphasis>st</emphasis> can be used to query or set the
      clock.  If <userinput>st</userinput> is followed by a parameter
      the clock is switched into fixed time per move mode and the
      parameter specifies the number of seconds to search per move.
      </para>
      <listitem>
      <para><emphasis>time</emphasis> can be used in addition to
      <userinput>set ComputerTimeRemainingSec</userinput> to notify
      the engine about how much time remains on its clock.  This value
      affects time per move allocation.
      </para>
      <listitem>
      <para><emphasis>otim</emphasis> can be used in addition to
      <userinput>set OpponentTimeRemainingSec</userinput> to notify
      the engine about how much time remains on the opponent's clock.
      This value affects draw-value calculation.
      </para>
      <listitem>
      <para><emphasis>go</emphasis> tells the engine that it plays the
      side on move and to begin searching immediately.
      </para>
      <listitem>
      <para><emphasis>?</emphasis> can be used to interrupt the search
      and instruct the engine to "move now".
      </para>
      <listitem>
      <para><emphasis>result</emphasis> is used to report the end of a
      game and its result.  It requires an argument to indicate the
      result and allows an optional comment.  For example:
      <userinput>result 1-0 {black resigns}</userinput>,
      <userinput>result 1/2-1/2 {stalemate}</userinput>.  The optional
      comment, if supplied, becomes the result description in the PGN
      header of the game.  This command triggers book learning and
      prints out a PGN record of the game.
      </para>
      <listitem>
      <para><emphasis>undo</emphasis> and <emphasis>remove</emphasis>
      can be used to take back one half-move or one full-move
      respectively.
      </para>
      <listitem>
      <para><emphasis>easy</emphasis> and <emphasis>hard</emphasis>
      instruct the engine to ponder (think on the opponent's time) or
      not to ponder respectively.
      </para>
      <listitem>
      <para><emphasis>name</emphasis> can be used in addition to
      <userinput>set OpponentName</userinput> to set the name of the
      opponent.  This is used to construct PGN headers.
      </para>
      <listitem>
      <para id="rating"><emphasis>rating</emphasis> can be used in
      addition to <userinput>set ComputerRating</userinput> or
      <userinput>set OpponentRating</userinput> to set the ELO rating
      of the computer and its opponent.  This information is used in
      draw value calculation and PGN header construction.  The
      <userinput>rating</userinput> command requires two (2)
      parameters; the first is the computer's rating and the second is
      the opponent's rating.
      </para>
      <listitem>
      <para><emphasis>computer</emphasis> can be used in addition to
      <userinput>set OpponentIsComputer true</userinput> to inform the
      engine that is it playing against another computer.  This
      setting changes draw value calculation and affects some position
      evaluation terms.
      </para>
      <listitem>
      <para><emphasis>rated</emphasis> and
      <emphasis>unrated</emphasis> can be used to inform the engine
      that the game it is playing is rated or unrated.  Typhoon uses
      this information in draw value calculation and when deciding
      whether to allow a move takeback.  This is not part of the
      <application>WinBoard</application> protocol but rather is a 
      hack I added to my copy of <application>WinBoard</application>
      in order to accommodate move takebacks on Internet Chess
      Servers.
      </para>
      <listitem>
      <para><emphasis>level</emphasis> is used setup the chess clock.
      This command takes three (3) parameters.  The first is the number of
      moves per time period, the second is the computer's starting
      clock value and the third is the increment added to the
      computer's clock per move.
      </para>
      <listitem>
      <para><emphasis>setboard</emphasis> is used to setup a position
      on the chessboard.  It requires an argument which is the
      position to setup in FEN format.
      </para>
      </itemizedlist>      
    </sect1>
    <sect1>
    <title>Miscellaneous Commands</title>
      <para>
There are still some other commands that have been hacked in and are
not part of the <application>WinBoard</application> protocol.  These
commands may change at any time and should not be relied upon to
remain constant in future versions.  
      </para>
      <para>
Note also that these commands are hard to access when the engine is
running under <application> WinBoard</application>.  If you want
to use them you might consider running the engine from the console.
      </para>
      <itemizedlist>
      <listitem>
      <para>
      <emphasis>board</emphasis> can be used to dump a text-mode
      drawing of the current board position as well as the current
      FEN.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>pgn</emphasis> can be used to dump a PGN record of 
      the current game.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>fen</emphasis> can be used to display the current 
      board position in FEN format.  With an argument this command
      behaves the same way that <userinput>setboard</userinput> does:
      it sets the current board position.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>avoid</emphasis>, <emphasis>solution</emphasis>,
      <emphasis>id</emphasis> and <emphasis>script</emphasis> are 
      commands normally used to set test positions for the engine.
      They are covered in more detail in another section.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>bench</emphasis> is a command to run an engine speed
      benchmark.  It is discussed in detail in another section.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>book</emphasis> is a command to manage opening books
      and is discussed in detail in another section.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>dump</emphasis> and <emphasis>test</emphasis> are 
      commands to show internal engine state and run self diagnostic
      checks.  See the source code for details.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>eval</emphasis> can be used to display a static 
      evaluation score of the current board position.  If the engine
      is built with EVAL_DUMP defined it will display the terms
      that combined to arrive at the eval score.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>help</emphasis> displays a brief command list.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>set</emphasis> is used to show or change the state of
      engine variables.  It is discussed in detail in another section.
      </para>
      </listitem>
      <listitem>
      <para>
      <emphasis>version</emphasis> is used to display the version
      number and build configuration of the engine.
      </para>
      </listitem>
      </itemizedlist>
    </sect1>
    <sect1>
    <title>Typhoon Variables</title>
      <para>
Many aspects of the engine's behavior can be controlled by setting the
values of variables.  Variables in typhoon are names that hold some 
value.  Variables can hold numbers, strings, times, boolean flags,
and so on.  To view the present state of a variable or to change it
you use the <userinput>set</userinput> command.
      </para>
      <para>
With no arguments, <userinput>set</userinput> displays the present
state of all system variables:
      </para>
<screen>
<userinput>set</userinput>
AnnounceOpening              => "TRUE"
BatchMode                    => "FALSE"
BlackPlayer                  => "typhoon"
BlackRating                  => 0
BlackDescription             => "Ver: 1.00 Build Time: 09:08:03 Jul  4 2006"
BlackIsComputer              => "TRUE"
BookFileName                 => "book.bin"
BookProbeFailures            => 0
ComputerTimeRemainingSec     => 600
EGTBPath                     => "C:\egtb\three;C:\egtb\four;C:\egtb\five"
GameDescription              => "(null)"
GameLocation                 => "(null)"
GameIsRated                  => "FALSE"
GameResultComment            => "(null)"
LastEval                     => 0
LogfileName                  => "typhoon.log"
MoveToPonder                 => "(null)"
MovesPerTimePeriod           => 4294967295
OpponentTimeRemainingSec     => 600
PendingInputEvents           => 0
PonderingNow                 => "FALSE"
PostLines                    => "TRUE"
SearchDepthLimit             => 63
SearchTimeLimit              => 0
SearchStartedTime            => 0.000000
SearchSoftTimeLimit          => 0.000000
SearchHardTimeLimit          => 0.000000
SearchNodesBetweenTimeCheck  => 0
ThinkOnOpponentsTime         => "TRUE"
ThinkingNow                  => "FALSE"
TournamentMode               => "FALSE"
VerbosePosting               => "FALSE"
WhitePlayer                  => "(null)"
WhiteRating                  => 0
WhiteDescription             => "(null)"
WhiteIsComputer              => "FALSE"
Xboard                       => "FALSE"
</screen>
      <para>
When used with one argument, <userinput>set</userinput> displays the
value of a subset of the engine variables that begin with the user
supplied argument.  For example:
      </para>
<screen>
<userinput>set s</userinput>
SearchDepthLimit             => 63
SearchTimeLimit              => 0
SearchStartedTime            => 0.000000
SearchSoftTimeLimit          => 0.000000
SearchHardTimeLimit          => 0.000000
SearchNodesBetweenTimeCheck  => 0
</screen>
      <para>
In order to set the value of any variable, use the 
<userinput>set</userinput> command with two arguments: the first to
indicate what variable name is being set and the second to supply a
new value for that variable.  For example:
      </para>
<screen>
<userinput>set tourn t</userinput>
</screen>
      <para>
Note that some variables are read only and cannot be set manually.
To change such variables I'm afraid you're stuck editing the source
code.
      </para>
      <para>
When you use the <userinput>set</userinput> command, the letter case
of a variable name is not significant; the names "WhitePlayer" and
"whiteplayer" refer to the same variable in typhoon.  Additionally as
you noticed in the example above, you may abbreviate any variable or
value name when using the set command as long as the abbreviation is
unique.  For example you could use <userinput>set tourn t</userinput>
to achieve the same result as <userinput>set TournamentMode
True</userinput> with less typing.
      </para>
    </sect1>
  <chapter id="book">
    <title>Opening Book</title>
    <para>
A chess engine's opening book is a library of moves in different
positions that it can access and play in leu of a searching for a
move.  These moves are usually drawn from well known opening lines
played by human masters.  The primary purpose of an opening book is to
impart some level of understanding of opening theory to the engine.  A
secondary goal of an opening book is to vary the deterministic play of
the engine.
    </para>
    <sect1>
    <title>Opening Book Commands</title>
      <para>
Commands affecting typhoon's opening book are prefixed with the
<userinput>book</userinput> opcode.  They are:
      </para>
      <itemizedlist>
      <listitem><para>
      <emphasis>book name</emphasis>, which sets the opening book
      filename.  If you do not use this command the engine defaults
      to using <filename>book.bin</filename> as the opening book.  
      If you want to use something else or to create a new opening 
      book, use this command to override the name of the opening 
      book file.
      </para>
<screen>
<userinput>book name newbook.bin</userinput>
</screen>
      </listitem> 

      <listitem><para>
      <emphasis>book import</emphasis>, which can be used to import
      book learning from an old book into a new one or to merge
      opening lines from a PGN file into the current opening book.
      Any book editing or learning that takes place in a position is
      recorded in typhoon's <filename>book.edt</filename> file.  If
      you wish to apply these book changes to another book in the
      future, use <userinput>book input</userinput>.  This command
      also is how you create or merge new lines into the opening
      book.  For more information about creating an opening book, 
      <link linkend="makebook">see the appropriate section</link>.
      </para>
<screen>
<userinput>book import /home/scott/typhoon/pgn/twic.pgn</userinput>
</screen>
      </listitem> 
      <listitem><para>
      <emphasis>book dump learning</emphasis>, which shows book
      learning in the current position.
      </para></listitem> 
      <listitem><para>
      <emphasis>book dump moves</emphasis>, which shows a list of all
      moves in the opening book at the current position.
      </para></listitem> 
      <listitem><para>
      <emphasis>book tourn</emphasis>, which displays or toggles
      tournament mode.  This is equivalent to the <userinput>set
      TournamentMode</userinput> command.
      </para></listitem> 
      <listitem><para>
      <emphasis>book openings</emphasis>, which sets the name of the
      book opening lines file for use when announcing opening lines.
      </para></listitem> 
      </itemizedlist>
    </sect1>
    <sect1>
    <title>Downloading a Pre-built Opening Book</title>
      <para>
Creating your own custom opening book has the advantage of allowing
you complete control over what line are included.  But it requires
some time, a machine with a lot of memory, and a good source of PGN
data.
      </para>
      <para>
If you want to save yourself the trouble of making a custom opening
book you can choose from several pre-built typhoon books which are
available at <ulink url="http://wannabe.guru.org/scott/hobbies/chess/books">
http://wannabe.guru.org/scott/hobbies/chess/books</ulink>.
      </para>
    </sect1>
    <sect1 id="makebook">
    <title>Building a Custom Opening Book</title>
      <para>
You may want to build a custom opening book with typhoon.  This
section will describe the process for you and give a few tips about
book building.
      </para>
      <para>
To begin you will need to collect the games you want to include in
your custom book into a single PGN file.  PGN is a standard format for
storing chess games in text files.  Programs like the freely available
<application>scid</application> which can be obtained from <ulink
url="http://scid.sourceforge.net/">http://scid.sourceforge.net/</ulink>
can be very helpful when you are trying to organize and maintain large
collections of chess games.  Commercial programs like <application>
ChessBase</application> do a good job too, of course.
      </para>
      <para>
Typhoon knows how to read PGN format files and import the moves from
each game in the PGN file into it's opening book.  However at this
time typhoon's PGN reader is a little picky about what it can process.
In general it's pretty good but it will not read games with move lists
that do not have a space between the move number and the move.  It
also can become confused by variations or comments in the PGN
notation.  I suggest you use a chess database to normalize the PGN
file you intend to use for your opening book before sending it through
typhoon.
      </para>
      <para>
Once you have your PGN file ready you have to decide whether you want
to merge the openings in the PGN file with typhoon's book or create a
new book from scratch.  The engine has an opening book filename that 
you can set via the <userinput>book name</userinput> command.  If this
file exists then the engine will append new openings to it.  If this
file does not exist then the engine will create it.  By default, this
file is called <filename>book.bin</filename>.  Here's how to override
the default:
      </para>
      <screen>
white(1): <userinput>book name D:\typhoon\regence.bin</userinput>
Opening book name set to "D:\typhoon\regence.bin"
      </screen>
      <para>
Now that you have set the name of the opening book you can import your
PGN file to create the new opening lines.  To do this type
<userinput>book import
<replaceable>file.pgn</replaceable></userinput>.  
Of course replace
<userinput><replaceable>file.pgn</replaceable></userinput>
with the
name of your PGN file.  Typhoon will read the PGN file one game at a
time and store the moves in the book file in BookName.  If typhoon
encounters a game containing an error or a move it does not understand
it will output a line like "** BAD Game NNNN (line NNNNNN)
saw=XXX... skipped" and discard all moves in that game.
Unfortunately the PGN parser is fairly picky which is why normalizing
your PGN input using a chess database program before building a book
is a good idea.  Here's what to expect:
      </para>
      <screen>
white(1): <userinput>book import D:\typhoon\pgn\misc\regence.pgn</userinput>
The opening book D:\typhoon\regence.bin does not exists, creating new book
Stage 1: reading and parsing PGN
** BAD Game 19498 (line 416067) saw="xc2"... skipped.
** BAD Game 53900 (line 1148893) saw="Rxf8+"... skipped.
** BAD Game 72836 (line 1560210) saw="O-O"... skipped.
Done reading PGN.
Straining out unpopular positions to compact buffer...
Compacting the opening book... one moment.
Done, compacted 2517462 positions into 135201.
Sorting the book... this may take a while.
Merging book and writing to disk.
Book successfully built...
      </screen>
<note>
<para>
Book building can take quite a while, especially on a machine with
limited memory.  I suggest you have at least 1Gb of memory to build
a large opening book.  If you find that building a book takes multiple
hours you can decrease the number of entries in typhoon's "membook" by
adjusting the MemBookSize variable.  Note that the smaller you make
the "membook", though, the more often typhoon will flush unpopular
positions from the opening book.  Everytime this happens you risk
losing good book lines.
</para>
<para>
It is safe to terminate typhoon while it is building an opening book if 
it takes too long.  However there is no way to pick up where it left off
and all work on the opening book will be lost.
</para>
</note>
      <para>
When you have finished building an opening book I recommend you exit
typhoon and restart the engine.  This is not strictly required but is
a good idea.  Once you have <userinput>quit</userinput> typhoon you
can check to make sure your new book exists.  To use it, simply use
the <userinput>book name</userinput> command to instruct typhoon to
use an alternate opening book.  An alternative is to rename the file
you downloaded as <filename>book.bin</filename>, the engine's default
opening book name.
      </para>
      <screen>
white(1): <userinput>quit</userinput>
Freeing dynamic memory allocations...
Closing logfile...
Terminating input thread...

D:\typhoon\Release><userinput>dir ..\regence.bin</userinput>
 Volume in drive D is New Volume
 Volume Serial Number is 1412-36C8

 Directory of D:\typhoon

10/10/2002  04:14 PM         4,867,236 regence.bin
               1 File(s)      4,867,236 bytes
               0 Dir(s)  58,596,573,184 bytes free
      </screen>
    </sect1>
    <sect1>
    <title>Book Learning</title>
      <para>
At the end of every game typhoon adjusts its opening book by updating
the win/loss statistics on the line of opening moves it just saw
played.  This leads to a positive/negative reinforcement of different
openings and, hopefully, to superior play over a long period of time.
Typhoon will not adjust the opening book after bullet games, after it
beats a low-rated opponent, or after it is beaten by a high rated
opponent (<link linkend="rating">see the <userinput>rating</userinput>
command</link>).  It will also not adjust the opening book if the
losing side lost by forfeit.
      </para>
      <para>
When typhoon adjusts the opening book it records the learning in a
file on disk called <filename>bklearn.dat</filename> as well as in
the book file.  This allows you to view the learning information 
periodically and watch which opening lines are receiving what kind 
of reinforcement.
      </para>
      <para>
Unfortunately typhoon cannot learn new opening moves from game play -- 
it can simply change the weight of moves it already knows in a given
position.  In order to teach typhoon new moves, use the <userinput>
book import</userinput> command to merge a new PGN file with the 
current opening book.
      </para>
<screen>
STDIN> result 0-1 {MoonShot checkmated}

[Event "Rated blitz computer chess game"]
[White "MoonShot (computer)"]
[Black "typhoon 0.906 (00:42:58, Oct  8 2002) (computer)"]
[WhiteElo "2795"]
[BlackElo "2731"]
[Result "0-1"]
[Opening: "[B92] Sicilian : Najdorf, Opovcensky Variation"]
[Description: "{MoonShot checkmated}"]

1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6
6. Be2 e5 7. Nb3 Be7 8. O-O O-O 9. Be3 Be6 10. f4 exf4
11. Rxf4 Nc6 12. Nd5 Bxd5 13. exd5 Ne5 14. a4 Nfd7 15. Rb4 b6
16. Qf1 a5 17. Rb5 Bg5 18. Bd4 Rc8 19. c3 Re8 20. Re1 Nc4
21. Bxc4 Rxe1 22. Qxe1 Rxc4 23. Nd2 Rxa4 24. Qd1 Rxd4 25. cxd4 Be3
26. Kh1 Bxd4 27. b4 a4 28. Nf3 Be3 29. Qxa4 Qc8 30. Qa3 Bf2
31. h3 Qc4 32. Qa8 Nf8 33. Qe8 h5 34. g3 Qd3 35. Kg2 Be3
36. Ng1 Qc2 37. Kh1 Qf2 38. Qxe3 Qxe3 39. Kg2 Nd7 40. g4 Qd3
41. Rxb6 Nxb6 42. Nf3 Nxd5 43. Kg3 h4 44. Kf2 Qe3 45. Kf1 Nf4
46. Nxh4 g5 47. b5 gxh4 48. b6 Qe2 49. Kg1 Qg2
{MoonShot checkmated}

               |     c5 (+0.00)
               |     d6 (+0.00)
               |   cxd4 (+0.00)
               |    Nf6 (+0.00)
               |     a6 (+0.00)
               |     e5 (+0.00)
               |    Be7 (+0.00)
               |    O-O (+0.00)
               |    Be6 (+0.00)
               |   exf4 (+0.00)
               |    Nc6 (+0.00)
               |   Bxd5 (+0.00)
               |    Ne5 (+0.00)
               |   Nfd7 (-0.90)
               |     b6 (-0.79)
               |     a5 (-0.08)
               |    Bg5 (-0.12)
               |    Rc8 (+0.32)
               |    Re8 (-0.02)
               |    Nc4 (+0.14)
               |   Rxe1 (+0.67)
               |   Rxc4 (+0.22)
               |   Rxa4 (+0.72)
               |   Rxd4 (+0.63)
               |    Be3 (+0.78)
               |   Bxd4 (+0.75)
               |     a4 (+0.75)
               |    Be3 (+0.81)
               |    Qc8 (+1.21)
               |    Bf2 (+1.33)
               |    Qc4 (+2.87)
               |    Nf8 (+4.59)
               |     h5 (+6.03)
               |*    Qd3 (+9.50)
               |*   Be3 (+12.06)
               |*   Qc2 (+13.36)
               |**   Qf2 (+13.78)
               |**  Qxe3 (+14.91)
               |**   Nd7 (+15.16)
               |**   Qd3 (+15.44)
               |**  Nxb6 (+16.04)
               |**  Nxd5 (+17.53)
               |********   h4  (+57.50)
               |********   Qe3 (+57.52)
               |********   Nf4 (+57.56)
               |********    g5 (+57.60)
               |********  gxh4 (+57.62)
               |********   Qe2 (+57.64)
               |********   Qg2 (+57.66)

BookLearn: Revising opening book line...
BookLearn: Changed 26 book positions.
</screen>
    </sect1>
  </chapter>
  <chapter id="egtb">
    <title>Endgame Tablebases</title>
    <para>
Endgame tablebases are special databases that contain game theoretic
information about different board configurations with very few pieces
left on the board.  When a chess engine finds a position in a
tablebase it will play perfectly by using the tablebase data.  For
example, by accessing a tablebase an engine might instantly determine
that a certain configuration of king vs. king, knight and bishop is a
mate in 38 for the stronger side.  
    </para>
    <para>
Eugene Nalimov has created a collection of endgame tablebases that
typhoon knows how to access during its search.  At present all 3, 4
and 5 man endgames have a corresponding tablebase and some 6 man
endgames also have a tablebase.  The drawback of tablebases is they
require a large amount of hard disk space to store and are slow to
access.  The benefit of tablebases is that they can drastically
improve engine endgame play in certain positions.
    </para>
    <para>
This chapter is about tablebases, where to find them, how to generate
them, how to validate them, how to compress them, and how to use them
with typhoon.
    </para>
    <sect1>
    <title>An Overview of Tablebases</title>
      <para>
As the previous section explains, tablebases are endgame databases
that contain information the engine can use to play perfectly in some
endgames with a low number of pieces on the board.  There are ten (10)
3-man tablebases, sixty (60) 4-man tablebases, and two-hundred twenty
(220) 5-main tablebases.  At present some 6-man tablebases have been
generated but are not in wide use because of their large disk space
requirements.
      </para>
      <para>
Typhoon uses Nalimov format tablebases.  These tablebases come two (2)
ways: compressed and uncompressed.  Typhoon can use either type.  The
compressed variety use much less disk space than their uncompressed
equivalents and are only slightly slower to access.  Nalimov
tablebases are compressed with a program called
<filename>datacomp.exe</filename>.  You can distinguish compressed
files from uncompressed ones by looking at the extension: compressed
tablebases end with <filename>.emd</filename>.
      </para>
      <para>
To store all 3 and 4-man tablebases (compressed) on your hard drive
you will need approximately 31Mb.  If you want to store all 3, 4 and
5-man tablebases (compressed) you'll need more like 7.5Gb of drive
space.  It is estimated that the full set of 6-man tablebases (when
they are available) will consume approximately 1Tb (1024Gb) of drive
space.  And for you psychopaths out there, if you wrote one tablebase
entry on every atom in the universe you could still not store a 32-man
endgame tablebase file.
      </para>
      <para>
Now that you know how much of your hard drive these things will use
you may (or may not) want to know where to get them.  One option is to
download them from Bob Hyatt's FTP site at <ulink
url="http://ftp.cis.uab.edu/pub/hyatt/TB">http://ftp.cis.uab.edu/pub/hyatt/TB
</ulink>.  Remember we're talking about transferring 7.5Gb of data;
you'll need a nice fast connection to even consider this.  With a 56K
modem this will take 40 hours (at least) -- probably more.
      </para>
      <para>
An alternative to transferring the tablebases is to generate them on
your own computer.  This way you only have to download the program
that makes the tablebases -- when it runs it will use your computer's
CPU to compute the tablebase data and save it on your hard drive.  The
<filename>tbexe.zip</filename> and <filename>tbgen.zip</filename>
files on the above FTP site contain the program, source code, and a
README file that explains the generation process.  I have never been
though this personally but I have heard that it takes about one week
of processing time on a computer with a reasonably fast processor and
large amount of memory to generate a full set of 3, 4 and 5-man EGTBs.
It should also be noted that the generation program creates
<emphasis>uncompressed</emphasis> tablebase files so you will need
approximately 40Gb of drive space to attempt this.  Once you have
generated the tablebases, though, you can use
<filename>datacomp.exe</filename> to compress them and save some
space.
      </para>
      <para>
Another choice is to buy these tablebases on CD.  <ulink
url="http://www.chessbase.com">Chessbase</ulink>, <ulink
url="www.gambitsoft.net">Gambitsoft</ulink>, and <ulink
url="http://store.convekta.com/">Convekta</ulink> all sell sets of
Nalimov tablebases on multiple CDs/DVDs.
      </para>
      <para>
Finally, this section would be incomplete without a link to Aaron
Tay's great frequently asked question (FAQ) list about endgame
tablebases which is online at <ulink
url="http://www.chesskit.com/aarontay/Winboard/egtb.html">
http://www.chesskit.com/aarontay/Winboard/egtb.html</ulink>.  This
helpful page covers different tablebase formats, how to validate your
tablebases, how to generate your tablebases and more.
      </para>
    </sect1>
    <sect1>
    <title>Using Nalimov Format Tablebases with Typhoon</title>
      <para>
Once you have some Nalimov format tablebase files (compressed or
uncompressed) getting typhoon to use them is pretty easy.  Use the
<userinput>set egtbpath</userinput> command to tell typhoon where on
your hard drive to look for the tablebase files.  If your tablebase
files are in more than one directory, just separate the directories by
semi-colons (;).
      </para>
<screen>
<userinput>set egtbpath D:\typhoon\egtb\three;D:\typhoon\egtb\four</userinput>
Rescanning EGTB path...
...Found 4-men endgame table bases.
</screen>
      <para>
When you change the value of the <userinput>EGTBPath</userinput>
variable typhoon automatically rescans the path looking for tablebase
files.  Scanning can take a few seconds.  If everything goes well you
will see a message like "...Found N-men endgame table bases".
      </para>
      <note>
      <para>
It is recommended you use complete sets of endgame tablebase files.
If you try to use 5-man tablebases without some 4-man tablebases or
4-man tablebases without some 3-man tablebases the engine can become
confused and misplay endgames.  It is acceptable to use only some
5-man files if you have all 4-man and 3-man files, though.  Likewise
it is acceptable to use some 6-man files if you have all 3, 4 and
5-man files to support them.
      </para>
      </note>
    </sect1>
  </chapter>
  <chapter>
    <title>Benchmarks</title>
    <para>
Benchmarking is the process of measuring the speed of the chess
engine.  This chapter deals with how to run and interpret the 
results of the benchmark.
    </para>
    <sect1>
    <title>The <userinput>bench</userinput> Command</title>
      <para>
The command to begin a benchmark is <userinput>bench</userinput>.  Be
aware that the benchmarking process can take a while and be prepared 
to wait.  
      </para>
      <para>
The <userinput>bench</userinput> command runs the same benchmark
that Bob Hyatt built into the <application>Crafty</application> 
chess engine (at least the copy of <application>Crafty</application> 
that I have, which is a few versions out of date).  It consists of
searching in a series of positions and computing the overall nodes
(positions) per second during the searches.  This is a good overall
speed test for typhoon.
      </para>
<screen>
<userinput>bench</userinput>
Beginning Bob Hyatt's crafty benchmark sequence.
This takes a while -- please be patient.

DEPTH LIMIT --> stop searching now
move c3c2
DEPTH LIMIT --> stop searching now
move e5e6
DEPTH LIMIT --> stop searching now
move f4f5
DEPTH LIMIT --> stop searching now
move d7f5
DEPTH LIMIT --> stop searching now
move b7e4
DEPTH LIMIT --> stop searching now
move c8f5

Benchmark results:
  122409037 nodes searched
  495 sec
  247057 overall nps
</screen>
    </sect1>
    <sect1>
    <title>Benchmark Results</title>

      <para>
Please see <ulink
  url="http://wannabe.guru.org/scott/hobbies/chess/benchmarks.html">http://wannabe.guru.org/scott/hobbies/chess/benchmarks.html</ulink>
  for up-to-date benchmark results.  If you benchmark typhoon and your
  system is not on the list below please <ulink
  url="mailto:[email protected]"> email me</ulink> your results
  and I will include them here.  </para>
    </sect1>
  </chapter>
  <chapter>
    <title>Test Suites</title>
    <para>
One way to measure the strength of a chess engine is to run it
against a test suite -- a collection of positions and solution moves 
(or moves to avoid).  Typhoon supports running test suites and this
chapter deals with how to run a test suite against the engine.  It
also contains a table of test suite results reported by other users.
    </para>
    <sect1>
    <title>Test Suite Commands</title>
      <para>
The typhoon commands that support test suites are
<userinput>solution</userinput>, <userinput>avoid</userinput>,
<userinput>id</userinput>, and <userinput>script</userinput>.  The
<userinput>solution</userinput> command sets up a solution move;
typhoon can handle up to three (3) solutions per position.  The
<userinput>avoid</userinput> command sets up a move to avoid; typhoon
can handle up to three (3) avoid moves per position.  The
<userinput>id</userinput> command simply adds a free form text name
for a test position.  And the <userinput>script</userinput> command
reads the contents of a file on disk and treats everything in it as
user input.
      </para>
      <note>
      <para>
You can set up either <userinput>solution</userinput> moves or
<userinput>avoid</userinput> moves but not both in the same position.
      </para>
      </note>
      <para>
Here's an example of how these commands work together.
      </para>
<screen>
<userinput>st 5</userinput>
<userinput>script \typhoon\tests\wac.epd</userinput>
SCRIPT> <userinput>setboard 2rr3k/pp3pp1/1nnqbN1p/3pN3/2pP4/2P3Q1/PPB4P/R4RK1 w - -</userinput>
SCRIPT> <userinput>solution Qg6</userinput>
SCRIPT> <userinput>id "WAC.001"</userinput>
SCRIPT> <userinput>go</userinput>

 1u   -1.91  00:00:00.08  486          PV= 1. Qe3 Nxe5 [Q] 2. dxe5 [Q] <-2.00>
 1u   -1.56  00:00:00.11  556          PV= 1. Ne8 <-2.00>
 1.   -1.56  00:00:00.12  576          PV= 1. Ne8 <-2.00>
 2.   -1.18  00:00:00.21  1099         PV= 1. Ne8 Qf8 <-2.00>
 3+   -0.35  00:00:00.30  3727         Qg6! ++
FORCED MATE --> stop searching now
 3.  +MATE1  00:00:00.40  8406         PV= 1. Qg6 fxg6 2. Nxg6+ [+] [MATE]
tellothers depth=3, score=+MATE1, n=8406, nps=20863, PV= 1. Qg6 fxg6 2. Nxg6+ [+] [MATE]
move g3g6
...
</screen>
      <para>
In the above example the user first types <userinput>st 5</userinput>.
This sets the clock to fixed-time-per-move mode and tells the engine
to search exactly five (5) seconds per position.  Next the user types
<userinput>script /typhoon/tests/wac.epd</userinput>.  This begins the
execution of a script file.  From now on typhoon will take commands
from this script file one at a time until the file has been completely
executed.  Commands that typhoon reads from a script have "SCRIPT>"
printed before them.  The script uses <userinput>setboard</userinput>,
<userinput>solution</userinput> and <userinput>id</userinput> to set
up a test position, a solution move, and the position name.  Then the
script sends typhoon the <userinput>go</userinput> command and the
engine starts thinking.  Because the engine has been told to search
exactly five (5) seconds per move, it will stop searching this
position when five (5) seconds are up.  At this time it will count the
position as solved if the move it plays matches any of the solution
move(s) (or does not match any of the avoid move(s)).  It also keeps
track of how long it took to see the correct move.  Once a script has
finished running completely typhoon will print out some final
statistics about the test suite run and begin to watch the keyboard
for commands again.
     </para>
<screen>
TEST SCRIPT execution complete.  Final statistics:
    correct solutions   : 272
    incorrect solutions : 28
    total problems      : 300
    total nodecount     : 40376223
    avg. search speed   : 125601.9 nps
    avg. solution time  : 0.4 sec
    avg. 1st move beta  : 0.936

Time-to-solution histogram:
00.00s .. 00.20s: ******************************* (73)
00.20s .. 00.40s: ************************************************** (119)
00.40s .. 00.60s: ************** (31)
00.60s .. 00.80s: ******* (15)
00.80s .. 01.00s: *********** (34)
   not solved   : **************** (28)
</screen>
    </sect1>
    <sect1>
    <title>Test Suite Results</title>
      <para>
Here are some test suite results obtained by typhoon running on my
development machine which is an AMD Athlon XP 1.533Ghz / 512Mb.  In
the table the suite abbreviation "ECM" refers to <ulink
url="http://wannabe.guru.org/scott/hobbies/ECM.EPD">"Encyclopedia of
Chess Middlegames"</ulink> and "WAC" refers to <ulink
url="http://wannabe.guru.org/scott/hobbies/chess/WAC.EPD">"Win At
Chess"</ulink>
      </para>
      <informaltable>
      <tgroup cols="4">
        <thead>
          <row>
            <entry>suite</entry>
            <entry>sec/move</entry>
            <entry>score</entry>
            <entry>date</entry>
            <entry>hardware</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>ECM</entry>
            <entry>20</entry>
            <entry>674 / 879</entry>
            <entry>Dec 22, 2004</entry>
            <entry>Dual 1.533ghz Athlon MP</entry>
          </row>
          <row>
            <entry>WAC</entry>
            <entry>20</entry>
            <entry>296 / 300</entry>
            <entry>Jan 11, 2002</entry>
            <entry>Dual 1.533ghz Athlon MP</entry>
          </row>
        </tbody>
      </informaltable>
    </sect1>
  </chapter>
  <chapter id="winboard">
    <title>Advanced WinBoard Configuration</title>
    <para>
This chapter covers how to get typhoon running under
<application>WinBoard</application>, a free, open source graphical
front-end for chess engines.  For more information about
<application>WinBoard</application> or to download it, see <ulink
url="http://www.tim-mann.org/xboard.html">http://www.tim-mann.org/xboard.html
</ulink>.  This chapter is also relevant to
<application>xboard</application>, WinBoard's X11-based version.  More
information about these chess GUI programs is also available in
<ulink url="http://www.aarontay.per.sg/Winboard/Winboard.html">
Aaron Tay's WinBoard FAQ</ulink>.
    <para>
    <sect1>
    <title>Playing Locally</title>
      <para>
Probably the most common way you will want to use typhoon with
<application>WinBoard</application> is to play local chess matches
against the program using <application>WinBoard</application> as the
display.  To do this you will need to use
<application>WinBoard's</application> <filename>-fcp</filename> and
<filename>-fd</filename> commandline options like this:
      </para>
      <screen>
<userinput>winboard -fcp "typhoon" -fd <replaceable>typhoon_directory</replaceable></userinput>
      </screen>
      <para>
The <filename>-fcp</filename> option sets
<application>WinBoard's</application> <emphasis>first chess
program</emphasis> and the <filename>-fd</filename> sets the
<emphasis>first chess program directory</emphasis>.  You should use
the directory you installed typhoon in after the
<filename>-fd</filename> option.  Once
<application>WinBoard</application> is running, set the "Machine Plays
Black" or "Machine Plays White" menu option.
      </para>
      <para>
Probably the best way to remember this is to create a little batch
file to start up <application>WinBoard</application> for playing
locally against typhoon.
      </para>
      <note>
      <para>
Typhoon's thinking lines may not be compatible with 
<application>WinBoard</application> and can cause it to crash when you
enable the "Show Thinking" menu option.  I advise you not to do this.
      </para>
      <para>
Also, typhoon's support for "Analysis Mode" in
<application>WinBoard</application> is incomplete at the time of
writing and may lead to problems.  Please don't enable either of these
WinBoard features for now.  Both shortcomings will be addressed in
future releases of the engine.
      </para>
      </note>
      <para>
If everything is working right typhoon should play instantly in the
early moves of a new game.  If typhoon has to think for more and a
second or two about early moves it may not see the opening book.
      </para>
      <para>
If you run into trouble getting typhoon to work under
<application>WinBoard</application> I suggest looking at
<filename>typhoon.log</filename>.  This file, which is created by
typhoon every time it is invoked, will contain a record of the
interaction between the engine and <application>WinBoard</application>
and may help to isolate the problem.  You can also enable
<application>WinBoard</application> logging by using the
<filename>-debug</filename> commandline option to
<application>WinBoard</application>.  This will cause the creation of
<filename>winboard.log</filename> which also may help you track down
the problem.
      </para>
    </sect1>
    <sect1>
    <title>Engine vs. Engine Matches</title>
      <para>
With <application>WinBoard</application> it's possible to play one
chess engine against another.  This section explains how to set this
up and how to run engine vs. engine matches as fairly as possible.
      </para>
      <para>
To run two engines under <application>WinBoard</application> just use
both the <filename>-fcp</filename> and the <filename>-scp</filename>
commandline options.  <filename>-fcp</filename> sets the
<emphasis>first chess program</emphasis> while
<filename>-scp</filename> sets the <emphasis>second chess
program</emphasis>.  You may want to use the related
<filename>-fd</filename> and <filename>-sd</filename> options too.
Then, once <application>WinBoard</application> is running, set the
"Machine Plays Both" option and watch them fight.
      </para>
      <para>
It's really not advisable to test engines by playing them under
WinBoard on a single processor machine.  However running on a 
two single-threaded engines on a multi-processor (or multi-core)
machine is a great way to test engines. 
      </para>
      <para>
If you do choose to run an engine vs. engine match on a single
processor machines you should turn off pondering on both engines so
that they do not constantly compete for system processor resources.
The next step is to make sure that each engine has equal access to the
machine's memory.  When playing engine-engine matches, you should set
the hash table sizes of both engines by hand to roughly half the total
memory on the machine.  Be absolutely sure that combined memory
requirements of the two engines does not exceed the amount of physical
memory on your machine or you will run into swapping which will slow
the engine(s) down severely.
      </para>
    </sect1>
    <sect1>
    <title>Playing on an Internet Chess Server</title>
      <para>
Internet Chess Servers are machines on the Internet that allow
multiple people/engines to connect and play chess against one
another.  <application>WinBoard</application> knows how to connect to
and communicate with these servers and therefore you can use it to
play typhoon against other people and machines connected to the same
Internet Chess Server.  This is a good way to test two chess engines
because when they play over the Internet, unlike when they both play
on the same machine, they do not have to fight each other for access
to the processor and memory resources of a single computer.
      </para>
      <note>
      <para>
It's unethical and against the rules of most Internet Chess Servers to
use a computer engine to make moves on a human account.  Your human
rating should not be aided by machine and your opponents have the
right to know they are playing against a computer.  Most Internet
Chess Server administrators are pretty good at catching people who
cheat and banning them from playing.  Please don't use typhoon to
cheat on Internet Chess Servers!  Likewise, if you are running typhoon
on a chess server I would be grateful if you would list the program
name and hardware configuration in your account's finger notes.
      </para>
      </note>
      <para>
To connect to an Internet Chess Server with typhoon+WinBoard use the
following commandline options when invoking
<application>WinBoard</application> in addition to the normal
<filename>-fcp</filename> and <filename>-fd</filename> options
described in the last sections: <filename>-zp</filename> (enable chess
engine to ICS code), <filename>-ics</filename> (connect to ICS
server), <filename>-icshost</filename> (ICS server hostname),
<filename>-xpopup</filename> (no popup windows),
<filename>-xautoraise</filename> (no popup windows),
<filename>-xexit</filename> (no popup windows), and
<filename>-reuse</filename> (no need to restart the engine process,
reuse the current one).  You may also want to use
<filename>-icsHelper</filename> (program name to use to connect to the
ICS, something like timestamp.exe or timeseal.exe),
<filename>-zippyPassword</filename> and
<filename>-zippyPassword2</filename> (passwords are for controlling
the chess engine remotely).  For more information about what these
commands do, see the documentation in
<filename>winboard.hlp</filename> and
<filename>README.zippy</filename>, both of which are included with
<application>WinBoard</application>.
      </para>
      <para>
Here's a sample script based on the one I use to connect typhoon to the
<ulink url="http://www.chessclub.com">Internet Chess Club</ulink>.
This script loops forever restarting the engine and
<application>WinBoard</application> if they lose connection to the ICS
server or terminate for some reason.  You can break out of the script
by pressing ^C.
      </para>
<screen>
@echo off
:again
cd /d C:\typhoon
"C:\program files\winboard\winboard.exe" /zp /ics /icshost
 chessclub.com /icshelper C:\progra~1\winboard\timestamp.exe /fcp
 C:\typhoon\release\typhoon.exe /xzt /xexit /xpopup /xautoraise 
 /reuse /debug /zippyPassword xxx /zippyPassword2 yyy
sleep 3
kill -f typhoon.exe
kill -f winboard.exe
sleep 3
goto :again
</screen>
      <para>
There are many different Internet Chess Servers on the 'Net.  Some are
free, others cost money to use.  Some are very busy and others are
pretty sparsely used.  There's a list of chess servers on Tim Mann's
website at <ulink url="http://www.tim-mann.org/ics.html">
http://www.tim-mann.org/ics.html</ulink>.
      </para>
    </sect1>
  </chapter>

  <chapter id="bugs">
    <title>Testing Typhoon</title>
    <para>
Typhoon was released in the present, somewhat buggy state mainly 
so that I could benefit from a large pool of testers.  Therefore,
I am very interested in reports about how the engine does.  This
chapter is about how you can help test typhoon.  Thanks for 
helping to make the engine stronger!
    </para>
    <sect1 id="debug">
    <title>A DEBUG build</title>
      <para>
With a simple modification to the build instructions presented in 
<link linkend="compile">an earlier section</link> it is possible to
produce a DEBUG build of the chess engine.  A DEBUG build is an
engine that runs much more slowly than normal because it is very
carefully double checking every calculation for errors.  If an
error is found a DEBUG build makes it easier to understand and
fix the problem than a normal build.
      </para>
      <para>
In order to make your own DEBUG build, just add <userinput>DEBUG=1
</userinput> to the commandline when you build the engine.  The
engine will be called <filename>_typhoon</filename> instead of
the usual <filename>typhoon</filename>.
      <para>
I try to run DEBUG builds of the engine for long periods of time
in order to expose bugs.  If you have a spare machine and some time
it would be great if you would be willing to do the same.  If your
DEBUG build crashes, <ulink url="mailto:[email protected]">
send me an email</ulink> with the message and output of the 
<userinput>version</userinput> command.
      </para>
    <sect1 id="test">
    <title>A TEST build</title>
      <para>
A TEST build is one that has some extra testcode compiled into it.
TEST builds will also run the testcode once automatically at startup.
I run TEST builds periodically in order to make sure that I have not
broken anything with my changes.  TEST builds are also helpful when
you are trying to port the engine to a new platform; if you get a
TEST build to run cleanly (especially a TEST/DEBUG build) then you
can be pretty sure the port is good.
      </para>
      <para>
If you want to build your own TEST engine, just add <userinput>TEST=1
</userinput> to the <application>make</application> commandline.
      </para>
    </sect1>
    <sect1 id="evaldump">
    <title>An EVAL_DUMP build</title>
      <para>
An image built with the <userinput>EVAL_DUMP</userinput> preprocessor
symbol defined will output several debugging messages every time it
runs the evaluation routine (see <filename>eval.c</filename>).  It
will also break down the terms contributing to the eval score when
the user types the <userinput>dump eval</userinput> command.
      </para>
      <para>
These features are useful if you are curious as to what the engine
thinks of a position.  Of course, it doesn't make sense to run the
evaluator on a position that is not quiet.
      </para>
      <para>
Since the engine produces output everytime it runs an evaluation and
because the engine typically runs the evaluation routine hundreds of
thousands of times per second, you should not attempt to search with
an engine build using the EVAL_DUMP flag.  It's too verbose.
      </para>
      <para>
If you find a position where you think the engine's evaluation is
totally wrong, please send it to me.  While I can't promise anything
(some positions are too complicated for static analysis), I will 
definitely take a look.
      </para>
    <sect1>
    <title>Typhoon Crashes</title>
      <para>
The engine should hardly ever crash.  If you find a reproducible way
to crash the engine I definitely want to hear about it.  Please 
<ulink url="mailto:[email protected]">send me an email</ulink>
describing how you managed to crash the engine and the output of 
the <userinput>version</userinput> command.  
      </para>
      <para>
If you have a <filename>typhoon.core</filename> file, send that along
with a copy of your <filename>typhoon</filename> image.  Better yet,
build <link linkend="debug">a DEBUG build</link>, crash it,
and send me the <filename>_typhoon.core</filename>, and <filename>
_typhoon</filename> files.  That makes it easier to figure out what 
went wrong.
      </para>
    </sect1>
    <sect1>
    <title>Typhoon Blunders</title>
      <para>
While not as severe as outright engine crashes, I am also interested
in positions where the program makes a terrible move.  I'm not a
strong chessplayer so your impressions about the engine's strengths,
weaknesses, trends that indicate errors in judgment, and so on are 
also very welcome.  Please <ulink url="mailto:[email protected]">
email them to me</ulink> along with the output of the 
<userinput>version</userinput> command.
      </para>
    </sect1>
  </chapter>
  </book>