diff options
| author | Scott Gasch <[email protected]> | 2016-06-01 20:32:18 -0700 |
|---|---|---|
| committer | Scott Gasch <[email protected]> | 2016-06-01 20:32:18 -0700 |
| commit | aea87c10177d2a8263ba0cc46f7ca71408bb9d0d (patch) | |
| tree | e408f41e61a53fed304dce2085e7366c4c8039e6 | |
| -rw-r--r-- | Makefile | 21 | ||||
| -rw-r--r-- | typhoon.sgml | 2148 |
2 files changed, 2169 insertions, 0 deletions
diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..800ada1 --- /dev/null +++ b/Makefile @@ -0,0 +1,21 @@ + +DOC?= typhoon + +FORMATS?= html ps pdf txt rtf + +INSTALL_COMPRESSED?= +INSTALL_ONLY_COMPRESSED?= + +SRCS= typhoon.sgml +DOC_PREFIX?= /usr/doc +WWW_ROOT?= /usr/local/www/data/scott +TARGETS= typhoon.html typhoon.txt typhoon.ps typhoon.rtf typhoon.pdf + +clean: + /bin/rm -f *.tex *.dvi *.css *.aux *.log *.out *~ $(TARGETS) + +install: $(TARGETS) docbook.css + /bin/cp -f docbook.css $(TARGETS) $(WWW_ROOT)/hobbies/chess + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/typhoon.sgml b/typhoon.sgml new file mode 100644 index 0000000..ff1c331 --- /dev/null +++ b/typhoon.sgml @@ -0,0 +1,2148 @@ +<!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> + |