GNU Backgammon


Node:Top, Next:, Up:(dir)

GNU Backgammon

This manual describes how to use GNU Backgammon to play and analyse backgammon games and matches. It corresponds to version 0.14.3-devel (updated in October, 2003).


Node:Introduction, Next:, Previous:Top, Up:Top

Introduction

GNU Backgammon works on


GNU Backgammon is available in different languages


GNU Backgammon comes with


With GNU Backgammon you may play


Gnubgs analysing functions allow you to


You can


GNU Backgammon imports matches and sessions from


GNU Backgammon exports positions, games, matches and sessions into


With GNU Backgammon you may choose between the following dice generators


GNU Backgammon comes with several databases for handling bearoffs and match equities, i.e.


But don't forget ... GNU Backgammon is work in progress. Don't blame us if


Don't forget also ...


Node:For the impatient, Next:, Previous:Introduction, Up:Top

For the impatient


Node:Installing the binaries, Next:, Up:For the impatient

Installing the binaries


Node:Playing a game, Previous:Installing the binaries, Up:For the impatient

Playing a game


Node:How to play backgammon, Next:, Previous:For the impatient, Up:Top

How to play backgammon

The rules presented in this chapter were written by Tom Keith for the Backgammon Galore web site, and are included here with his permission.


Node:Rules of Backgammon, Next:, Up:How to play backgammon

Rules of Backgammon

Setup

Backgammon is a game for two players, played on a board consisting of twenty-four narrow triangles called points. The triangles alternate in color and are grouped into four quadrants of six triangles each. The quadrants are referred to as a player's home board and outer board, and the opponent's home board and outer board. The home and outer boards are separated from each other by a ridge down the center of the board called the bar.

rulfig1.png Figure 1. A board with the checkers in their initial position.

An alternate arrangement is the reverse of the one shown here, with the home board on the left and the outer board on the right.

The points are numbered for either player starting in that player's home board. The outermost point is the twenty-four point, which is also the opponent's one point. Each player has fifteen checkers of his own color. The initial arrangement of checkers is: two on each player's twenty-four point, five on each player's thirteen point, three on each player's eight point, and five on each player's six point.

Both players have their own pair of dice and a dice cup used for shaking. A doubling cube, with the numerals 2, 4, 8, 16, 32, and 64 on its faces, is used to keep track of the current stake of the game.

Object of the Game

The object of the game is for a player to move all of his checkers into his own home board and then bear them off. The first player to bear off all of his checkers wins the game.

rulfig2.png Figure 2. Direction of movement of White's checkers. Red's checkers move in the opposite direction.

Movement of the Checkers

To start the game, each player throws a single die. This determines both the player to go first and the numbers to be played. If equal numbers come up, then both players roll again until they roll different numbers. The player throwing the higher number now moves his checkers according to the numbers showing on both dice. After the first roll, the players throw two dice and alternate turns.

The roll of the dice indicates how many points, or pips, the player is to move his checkers. The checkers are always moved forward, to a lower-numbered point. The following rules apply:

  1. A checker may be moved only to an open point, one that is not occupied by two or more opposing checkers.
  2. The numbers on the two dice constitute separate moves. For example, if a player rolls 5 and 3, he may move one checker five spaces to an open point and another checker three spaces to an open point, or he may move the one checker a total of eight spaces to an open point, but only if the intermediate point (either three or five spaces from the starting point) is also open.

    rulfig3.png Figure 3. Two ways that White can play a roll of 53.

  3. A player who rolls doubles plays the numbers shown on the dice twice. A roll of 6 and 6 means that the player has four sixes to use, and he may move any combination of checkers he feels appropriate to complete this requirement.
  4. A player must use both numbers of a roll if this is legally possible (or all four numbers of a double). When only one number can be played, the player must play that number. Or if either number can be played but not both, the player must play the larger one. When neither number can be used, the player loses his turn. In the case of doubles, when all four numbers cannot be played, the player must play as many numbers as he can.

Hitting and Entering

A point occupied by a single checker of either color is called a blot. If an opposing checker lands on a blot, the blot is hit and placed on the bar.

Any time a player has one or more checkers on the bar, his first obligation is to enter those checker(s) into the opposing home board. A checker is entered by moving it to an open point corresponding to one of the numbers on the rolled dice.

For example, if a player rolls 4 and 6, he may enter a checker onto either the opponent's four point or six point, so long as the prospective point is not occupied by two or more of the opponent's checkers.

rulfig4.png Figure 4. If White rolls 64 with a checker on the bar, he must enter the checker onto Red's four point since Red's six point is not open.

If neither of the points is open, the player loses his turn. If a player is able to enter some but not all of his checkers, he must enter as many as he can and then forfeit the remainder of his turn.

After the last of a player's checkers has been entered, any unused numbers on the dice must be played, by moving either the checker that was entered or a different checker.

Bearing Off

Once a player has moved all of his fifteen checkers into his home board, he may commence bearing off. A player bears off a checker by rolling a number that corresponds to the point on which the checker resides, and then removing that checker from the board. Thus, rolling a 6 permits the player to remove a checker from the six point.

If there is no checker on the point indicated by the roll, the player must make a legal move using a checker on a higher-numbered point. If there are no checkers on higher-numbered points, the player is permitted (and required) to remove a checker from the highest point on which one of his checkers resides. A player is under no obligation to bear off if he can make an otherwise legal move.

rulfig5.png Figure 5. White rolls 64 and bears off two checkers.

A player must have all of his active checkers in his home board in order to bear off. If a checker is hit during the bear-off process, the player must bring that checker back to his home board before continuing to bear off. The first player to bear off all fifteen checkers wins the game.

Doubling

Backgammon is played for an agreed stake per point. Each game starts at one point. During the course of the game, a player who feels he has a sufficient advantage may propose doubling the stakes. He may do this only at the start of his own turn and before he has rolled the dice.

A player who is offered a double may refuse, in which case he concedes the game and pays one point. Otherwise, he must accept the double and play on for the new higher stakes. A player who accepts a double becomes the owner of the cube and only he may make the next double.

Subsequent doubles in the same game are called redoubles. If a player refuses a redouble, he must pay the number of points that were at stake prior to the redouble. Otherwise, he becomes the new owner of the cube and the game continues at twice the previous stakes. There is no limit to the number of redoubles in a game.

Gammons and Backgammons

At the end of the game, if the losing player has borne off at least one checker, he loses only the value showing on the doubling cube (one point, if there have been no doubles). However, if the loser has not borne off any of his checkers, he is gammoned and loses twice the value of the doubling cube. Or, worse, if the loser has not borne off any of his checkers and still has a checker on the bar or in the winner's home board, he is backgammoned and loses three times the value of the doubling cube.

Optional Rules

The following optional rules are in widespread use.

Automatic doubles
If identical numbers are thrown on the first roll, the stakes are doubled. The doubling cube is turned to 2 and remains in the middle. Players usually agree to limit the number of automatic doubles to one per game.
Beavers
When a player is doubled, he may immediately redouble (beaver) while retaining possession of the cube. The original doubler has the option of accepting or refusing as with a normal double.
The Jacoby Rule
Gammons and backgammons count only as a single game if neither player has offered a double during the course of the game. This rule speeds up play by eliminating situations where a player avoids doubling so he can play on for a gammon.

Irregularities

  1. The dice must be rolled together and land flat on the surface of the right-hand section of the board. The player must reroll both dice if a die lands outside the right-hand board, or lands on a checker, or does not land flat.
  2. A turn is completed when the player picks up his dice. If the play is incomplete or otherwise illegal, the opponent has the option of accepting the play as made or of requiring the player to make a legal play. A play is deemed to have been accepted as made when the opponent rolls his dice or offers a double to start his own turn.
  3. If a player rolls before his opponent has completed his turn by picking up the dice, the player's roll is voided. This rule is generally waived any time a play is forced or when there is no further contact between the opposing forces.


Node:Match Play, Previous:Rules of Backgammon, Up:How to play backgammon

Rules for Match Play

When backgammon tournaments are held to determine an overall winner, the usual style of competition is match play. Competitors are paired off, and each pair plays a series of games to decide which player progresses to the next round of the tournament. This series of games is called a match.

Matches are played to a specified number of points. The first player to accumulate the required points wins the match. Points are awarded in the usual manner: one for a single game, two for a gammon, and three for a backgammon. The doubling cube is used, so the winner receives the value of the game multiplied by the final value of the doubling cube.

Matches are normally played using the Crawford rule. The Crawford rule states that if one player reaches a score one point short of the match, neither player may offer a double in the immediately following game. This one game without doubling is called the Crawford game. Once the Crawford game has been played, if the match has not yet been decided, the doubling cube is active again.

Match to 5  White   Black 
Game 1:  White wins 2 points   2 0  Doubling Allowed
Game 2:Black wins 1 point 2 1
Game 3:White wins 2 points4 1
Game 4:Black wins 1 point 4 2   Crawford Game
Game 5:Black wins 2 points4 4  Doubling Allowed
Game 6:White wins 2 points6 4
In this example, White and Black are playing a 5-point match. After three games White has 4 points, which is just one point short of what he needs. That triggers the Crawford rule which says there can be no doubling in next game, Game 4.

There is no bonus for winning more than the required number of points in match play. The sole goal is to win the match, and the size of the victory doesn't matter.

Automatic doubles, beavers, and the Jacoby rule are not used in match play.


Node:Installing the software, Next:, Previous:How to play backgammon, Up:Top

Installing the software


Node:Installing a MS Windows binary, Next:, Up:Installing the software

Installing a MS Windows binary

For an installation of GNU Backgammon on MS Windows operating systems you need at least this build from gnubg. You'll find a file setup.exe, which is approximately 11 mb. If you want daily builds, go to Nardy Pillards page at http://users.skynet.be/bk228456/GNUBgW.htm and read his documentation carefully. If you download everything, you'll have these packages:

Nardy's builds include a daily snapshot of the gnubg.exe and some addons. If you like daily builds, get either the "old layout", the "new layout" or the "no gui" binary (*.exe). You may also download a language package for Windows. Be aware, that the translation is still work in progress. Only the english and the german translation are (nearly) fully available.

Part I (Main program): After downloading the software "doubleclick" on setup.exe. You will be asked whether you want to install GNU Backgammon for windows. Click on yes. In the following window accept the license agreement and click on next. Then choose a directory where GNU Backgammon shall be installed. After this select the MS Windows menu entry and whether or not a desktop and a quick launch icon shall be created.

The installation program will install all necessary files on your disk and finally ask you whether GNU Backgammon shall be launched or not. Now you are ready to play.

Part II (Daily snapshots): If you like current snapshots, get the files from Nardy's page at http://users.skynet.be/bk228456/GNUBgW.htm. The files gnubg-[date]Zip.exe or gnubg-old-[date]Zip.exe contain only the binary gnubg.exe.

If you like the new style with panels and a 3D-board layout get gnubg-[date]Zip.exe and the additional package board-3Dfiles.exe. Doubleclick on the file, select your installation directory and click on extract. Be catious: the binary will now overwrite the "old" gnubg.exe.

For the old layout (seperate windows, no 3D-board) choose gnubg-old-[date]Zip.exe. You will now have a second program file in you GNU Backgammon directory called gnubg-old.exe.

Part III (Support for different languages: If there is a package supporting your native language, you may download this package also. Doubleclick on the locale_[lang].exe, and the installer will put all necessary files into your GNU Backgammon directory. After copying the files a README file will open with instructions how to activate the language.

Part IV (Command Line Interface): For using the "non-gui" version of GNU Backgammon you only have to additionally install gnubg_nogui-[date]Zip.exe. Again doubleclick on the binary gnubg_nogui-[date]Zip.exe. Be aware that possible older version of gnubg-no-gui.exe will be overwritten. Accept the warning and click on ok. Choose the directory of your GNU Backgammon installation and click on extract.

Part V (Additional python support): If you need additional support for the scripting language python you also have to install the package libpython22Zip.exe.


Node:Installing a Linux rpm-package, Next:, Previous:Installing a MS Windows binary, Up:Installing the software

Installing a Linux rpm-package

Get the rpm packages from the Linux download section at GNU Backgammon webpage. You'll need the main package gnubg-[version].rpm, the databases gnubg-databases.rpm and the sound packages gnubg-sound.rpm. As root do a

#: rpm -ihv gnubg*.rpm

If you want to update GNU Backgammon you will mostly need only the new main package. Then you can update gnubg with

#: rpm -Uhv gnubg-[version].rpm

Some people like to compile GNU Backgammon from the source-rpms. In this case you have to download the package gnubg-[version].src.rpm. As root do a

#: rpm --rebuild gnubg-[version].src.rpm

For people who want to verify the packages we put a public key on public key ace. Download the key and import it with

#: gpg --import pubkey_ace.asc
#: rpm --verify [package] (for rpm version 3)

or

#: rpm --import pubkey_ace.asc
#: rpm --checksig [package] (for rpm version 4)


Node:Installing a FreeBSD package or port, Next:, Previous:Installing a Linux rpm-package, Up:Installing the software

Installing a FreeBSD package or port

fixme


Node:Compiling and installing the source, Previous:Installing a FreeBSD package or port, Up:Installing the software

Compiling and installing the source

Download the sources from GNU Backgammon sources. We try to put daily snapshots there. Be aware, that these sources may not compile!

Unzip and untar the sources and change into the source directory:

#: tar -xzvf gnubg-[version].tar.gz
#: cd gnubg-[version]

Copy at least the file gnubg.weights into the source directory. Then do a

#: aclocal -I m4
#: autoconf
#: automake --add-missing
#: ./configure
#: make
#: make install

The first three commands may not be necessary depending on your system. The command ./configure includes some options you may like to use. You can get all options with

#: ./configure --help


Node:Starting GNU Backgammon, Next:, Previous:Installing the software, Up:Top

Starting GNU Backgammon


Node:The graphical interface, Next:, Up:Starting GNU Backgammon

The graphical interface


Node:Using a terminal, Previous:The graphical interface, Up:Starting GNU Backgammon

Using a terminal


Node:Playing backgammon, Next:, Previous:Starting GNU Backgammon, Up:Top

Playing backgammon


Node:Starting a game or match or session, Next:, Up:Playing backgammon

Starting a game or match or session


Node:Moving the checkers, Next:, Previous:Starting a game or match or session, Up:Playing backgammon

Moving the checkers


Node:Using the doubling cube, Previous:Moving the checkers, Up:Playing backgammon

Using the doubling cube


Node:Saving games, Next:, Previous:Playing backgammon, Up:Top

Saving games


Node:Saving a game, Next:, Up:Saving games

Saving a game


Node:Saving a match, Next:, Previous:Saving a game, Up:Saving games

Saving a match


Node:Saving a session, Next:, Previous:Saving a match, Up:Saving games

Saving a session


Node:Saving a position, Previous:Saving a session, Up:Saving games

Saving a position


Node:Opening files, Next:, Previous:Saving games, Up:Top

Opening files


Node:Opening a game, Next:, Up:Opening files

Opening a game


Node:Opening a match, Next:, Previous:Opening a game, Up:Opening files

Opening a match


Node:Opening a session, Next:, Previous:Opening a match, Up:Opening files

Opening a session


Node:Opening a position, Previous:Opening a session, Up:Opening files

Opening a position


Node:Import files, Next:, Previous:Opening files, Up:Top

Import files

gnubg can import matches produced by various other programs or online servers. For example, you can import matches played on GamesGrid or FIBS. gnubg can export positions, matches, or money session to a number of formats; some suitable for printing, some suitable for including in emails or Usenet postings, and others suitable for publishing on the world wide web or for posting to backgammon forums.

The following sections describe how to import and export positions, matches, and sessions with gnubg.

Jellyfish .pos

gnubg can import positions in Jellyfish .pos format. To import a position file using the GUI select a file from File->Import->.pos position.

The .pos position format is documented at The Jellyfish Position File Format.

Jellyfish .mat

gnubg can also import matches and money sessions in the .mat format. This format is often used to move games between different programs, as most programs (e.g., Jellyfish, Snowie, BGBlitz, and others) support import and export of this format.

To import a match or money session in the .mat format, select a file from File->Import->.mat match.

Note that at least one program (BBGT) is known to write multiple matches in the same .mat file. In this case gnubg will only read the first match. If you wish to import all matches from such a .mat file, you'll manually have to split the file into files containing the individual matches.

GamesGrid .sgg

gnubg can import matches and money sessions played on GamesGrid if saved in the SGG format. Currently, gnubg doesn't support import of the native undocumented .cbg format. Also note that gnubg does not analyse table stakes, so imported money sessions will be analysed as a normal money session.

To import an SGG file using the GUI select a file using the menu entry File->Import->.sgg match.

FIBS oldmoves

gnubg can import matches and money sessions from FIBS in the oldmoves format. Most of the GUIs for playing on FIBS supports saving of matches either in the oldmoves format or in Jellyfish .mat format.

To import an oldmoves file using the GUI select a file using the menu entry File->Import->FIBS oldmoves.

Note that gnubg will only read the first match in the file. If you wish to import all matches from a file containing more than more game, you'll manually have to split it.

TrueMoneyGames .tmg

gnubg can also import matches and money sessions played on TrueMoneyGames saved in the TMG format (file suffix .tmg). Please note that gnubg does not analyse table stakes, so imported money sessions will be analysed as a normal money session.

To import an TMG file using the GUI select a file using the menu entry File->Import->TrueMoneyGames .tmg match.

Hans Berliner BKG format

Matches written in the Hans Berliner BKG format can be imported into gnubg. To import an BKG file using the GUI select a file using the menu entry File->Import->BKG session.

Snowie .txt position format

gnubg can import positions written in the Snowie .txt position format. Please note that very important distinction between Snowie .txt position and Snowie Standard Text. The former is used for position and the latter is an extension of the Jellyfish .mat format, and can be imported in gnubg using the .mat importer.

gnubg can also export positions to Snowie .txt format for easy exchange of positions with Snowie users.

To import an Snowie .txt position file using the GUI select a file using the menu entry File->Import->Snowie .txt position file.

Batch import

gnubg doesn't support batch import and analysis using the GUI, but batch import is possible with the command line version of gnubg.

Under Unix execute:

gnubg -t < input-file > output-file

Under Windows it depends on how your version of gnubg was build. For example, if you use the build by Øystein Johansen you should execute

gnubg-no-gui.exe < input-file > output-file

The input-file must be carefully prepared. For example, it could look like:

import sgg file1.sgg
analyse match
save match file1.sgf
import sgg file2.sgg
analyse match
save match file1.sgf
import mat file3.mat
analyse match
save match file3.sgf

If you wish to adjust your setting for the analysis you can include commands like:

set analysis chequerplay evaluation plies 2
set analysis cubedecision evaluation plies 3
[...]

See the command reference for further details regarding the commands available in gnubg.

Other formats

There are a number of utilities written that can read and write positions, matches, and money sessions in other formats than the ones gnubg has direct support for. Bunny's Zone Converter can be used to convert matches saved on MSN Gaming Zone to Jellyfish .mat format which can be imported into gnubg.

The neural net backgammon program BGBlitz can read Gamesgrid .cbg, FIBS/W logfiles, MacFIBS logfiles and other formats which can be written back in the .mat format for importing into gnubg.

Tips and tricks

If you want to exchange the playes, i.e., gnubg has imported you as the top player rather than the bottom player, select them menu entry Game->Swap Players.


Node:Export files, Next:, Previous:Import files, Up:Top

Export files

Export game in Jellyfish .gam

You can export the current game in the Jellyfish .gam format. This is useful if you wish import a specific game into Jellyfish. Other programs may read the file as well, since the format is identical to the Jellyfish .mat format.

export game gam filename: Export the current game in Jellyfish .gam format to filename.

Export positions, games, matches and sessions in HTML

gnubg can export the current position, game, match or session in HTML if you wish to publish it on the web. A sample match with the World Cup Final 2002 from Monte Carlo is available for viewing (FIXME: put a match on gnu.org or gnubg.org instead).

gnubg exports in validating XHTML 1.0 with the use of CSS style sheets. You may add your own style sheet to the exported HTML files if you wish to override the default layout, e.g., change colors or fonts.

The board is made up from hundreds of pictures. Currently, you can choose between three different sets of pictures: (a) the BBS images used by Kit Woolsey's GammOnLine e-magazine, Danish Backgammon Federation's web-based discussion group and others, (b) the fibs2html images used by the Joseph Heled's program fibs2html, and (c) images generated by gnubg itself. The images generated by gnubg will have the same design as your current design, and honours your settings on clockwise or anti-clockwise movement and board numbering (on, off, dynamic).

If you export a match or session to HTML gnubg will write the individual games to separate files. For example, if you export to file foo.html the first game is exported to foo.html, the second game to foo_002.html, the third game to foo_003.html and so forth.

The output from the HTML export can be customised. For example, it's possible to leave out the analysis or parts of the analysis. Also, you may enter a specific URL to the pictures used to compose the board which is useful for posting positions on web-based discussion groups such as Kit Woolsey's GammOnLine, the Danish Backgammon Federation's Debat Forum, or you may opt to use a default set of images available from the gnubg web site at FIXME Add images to www.gnubg.org!.

See Export, for full details regarding the options available for HTML export.

Description of the CSS stylesheet

As mentioned above gnubg writes a CSS stylesheet along with the generated XHTML file. The CSS stylesheet may be written verbatim in the header section of the XHTML file, to an external file named gnubg.css, or inside the tags using the style attribute. If you wish to make any modifications to the stylesheet without modifying the actual source code of gnubg you have to choose one of the first two methods. Note that the special export for Kit Woolsey's GammOnLine uses the third method since the XHTML is pasted into a web page without the possibility to modify the header section of the page where the style sheet is defined. Thus, it's not possible to modify the style of the generated XHTML for GammOnLine without modifications of the source code or extensive search and replace in the geneated XHTML.

Below follows a description of the CSS classes used in the XHTML export:

Class Description
.movetable Style applied to the entire table used for the move analysis
.moveheader The header of the move analysis table
.movenumber The rank number of a move in the move analysis
.moveply The column indicating the number of plies or rollout
.movemove The formatted move, e.g., 13/7 8/7.
.moveequity The column with the equity or MWC.
.movethemove Special style for row that contains the actual move chosen by the player
.moveodd Special style for the odd rows. Can be used to give an alternating color for the rows.
.percent Style for the game winning probabilities and equities in the move analysis.
.blunder Emphasize blunders, e.g., "Alert: missed double" or "Alert: bad move".
.joker Emphasize very good or bad rolls, e.g., "Alert: unlucky roll".
.stattable The style applied to the entire table with game, match, and session statistics
.stattableheader The header row of the statistics table
.result Style for the text indicating the outcome of the game or match, e.g., "Joern Thyssen wins 16 points".
.tiny Currently unsued.
.cubedecision The style applied to the entire cube decision table
.cubedecisionheader Style for the header row of the cube decision table
.cubeequity Style for any equity or MWC in the cube decision table
.cubeaction Style for the text indicating the correct cube action
.cubeply Style for the text that states the level of evaluation
.cubeprobs Style for the game winning probabilities in the cube decision table
.comment The style applied to the entire table used for annotations or comments, e.g., the kibitzing from imported SGG files
.commentheader The style applied to the header row of the annotations' table
.number Currently unsued
.fontfamily Style applied to the entire body of the XHTML document.
.block Style applied to the images in the export to avoid gaps between individual pictures both horisontally and vertically.
.positionid Style for the Position ID and match ID.

export position html filename: Export the current position in HTML to filename.

export game html filename: Export the current game in HTML to filename.

export match html filename: Export the current match in HTML to filename.

export session html filename: Export the current session in HTML to filename.

Export games, matches, and sessions in LaTeX

writeme

Export match or session in Jellyfish .mat

You can export an entire match or session into Jellyfish .mat format. This is very useful if you want to import a match or session into other programs as most other backgammon programs are able to read it.

export match mat filename: export the match in Jellyfish .mat format to filename.

Export games, matches, and sessions in PDF

writeme

Export games, matches, and sessions in PostScript

writeme

Export position in Jellyfish .pos

writeme

Export position in Snowie .txt position format

writeme

Export positions, games, matches, and sessions in plain text


Node:Settings, Next:, Previous:Export files, Up:Top

Settings


Node:Player, Next:, Up:Settings

Player


Node:Appearance, Next:, Previous:Player, Up:Settings

Appearance


Node:Options, Next:, Previous:Appearance, Up:Settings

Options


Node:Advanced options, Next:, Previous:Options, Up:Settings

Advanced options


Node:Evaluation, Next:, Previous:Advanced options, Up:Settings

Evaluation

Movefilters

gnubg uses a technique called "move filters" in order to prune the complete list of legal moves when analysing chequer play decisions. Move filters can be considering a generalising of the search space used in earlier versions of gnubg.

A move filter for a given ply, say, 2-ply, consists of four parameters for each subply:

  1. whether to analyse at all at this subply,
  2. the number of moves always accepted at the given level,
  3. the number of extra moves to add,
  4. the threshold for adding extra moves.

For example, for 2-ply chequer play decisions there are two movefilters: one for pruning at 0-ply, and another for pruning at 1-ply. The predefined setting "Normal" has: accept 0 moves and add up to 8 moves within 0.16 at 0-ply, and no pruning at 1-ply.

Consider the opening position where 6-2 has been rolled:

 GNU Backgammon  Position ID: 4HPwATDgc/ABMA
                 Match ID   : cAkZAAAAAAAA
 +13-14-15-16-17-18------19-20-21-22-23-24-+     O: gnubg
 | X           O    |   | O              X |     0 points
 | X           O    |   | O              X |
 | X           O    |   | O                |
 | X                |   | O                |
 | X                |   | O                |
v|                  |BAR|                  |     (Cube: 1)
 | O                |   | X                |
 | O                |   | X                |
 | O           X    |   | X                |
 | O           X    |   | X              O |     Rolled 24
 | O           X    |   | X              O |     0 points
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     X: jth
Pip counts: O 167, X 167

gnubg starts by finding all possible moves and evaluate those at 0-ply:

    1. Cubeful 0-ply    8/4 6/4                      Eq.:  +0.207
       0.548 0.172 0.009 - 0.452 0.121 0.005
        0-ply cubeful [expert]
    2. Cubeful 0-ply    13/11 13/9                   Eq.:  +0.050 ( -0.156)
       0.509 0.155 0.009 - 0.491 0.137 0.007
        0-ply cubeful [expert]
    3. Cubeful 0-ply    24/20 13/11                  Eq.:  +0.049 ( -0.158)
       0.513 0.137 0.007 - 0.487 0.132 0.004
        0-ply cubeful [expert]
    4. Cubeful 0-ply    24/22 13/9                   Eq.:  +0.037 ( -0.170)
       0.508 0.142 0.007 - 0.492 0.134 0.004
        0-ply cubeful [expert]
    5. Cubeful 0-ply    24/22 24/20                  Eq.:  -0.008 ( -0.215)
       0.501 0.121 0.006 - 0.499 0.133 0.003
        0-ply cubeful [expert]
    6. Cubeful 0-ply    24/18                        Eq.:  -0.015 ( -0.222)
       0.502 0.121 0.006 - 0.498 0.140 0.004
        0-ply cubeful [expert]
    7. Cubeful 0-ply    24/20 6/4                    Eq.:  -0.023 ( -0.229)
       0.497 0.132 0.007 - 0.503 0.144 0.005
        0-ply cubeful [expert]
    8. Cubeful 0-ply    13/9 6/4                     Eq.:  -0.026 ( -0.233)
       0.494 0.146 0.008 - 0.506 0.151 0.009
        0-ply cubeful [expert]
[10 moves deleted]

Accoring to the move filter the first 0 moves are accepted. The equity of the best move is +0.207, and according to the movefilter we add up to 8 extra moves if they're within 0.160, that is, if they have equity higher than +0.047. Move 4-18 all have equity lower that +0.047, so the move list after pruning at 0-ply consists of move 1-3. According to the move filter we do not perform any pruning at 1-ply, so move 1-3 are submitted for evaluation at 2-ply;

    1. Cubeful 2-ply    8/4 6/4                      Eq.:  +0.197
       0.546 0.172 0.008 - 0.454 0.123 0.005
        2-ply cubeful 100% speed [world class]
    2. Cubeful 2-ply    24/20 13/11                  Eq.:  +0.058 ( -0.138)
       0.515 0.141 0.007 - 0.485 0.130 0.005
        2-ply cubeful 100% speed [world class]
    3. Cubeful 2-ply    13/11 13/9                   Eq.:  +0.050 ( -0.147)
       0.508 0.156 0.007 - 0.492 0.136 0.006
        2-ply cubeful 100% speed [world class]
    4. Cubeful 0-ply    24/22 13/9                   Eq.:  +0.037 ( -0.159)
       0.508 0.142 0.007 - 0.492 0.134 0.004
        0-ply cubeful [expert]
    5. Cubeful 0-ply    24/22 24/20                  Eq.:  -0.008 ( -0.205)
       0.501 0.121 0.006 - 0.499 0.133 0.003
        0-ply cubeful [expert]
    6. Cubeful 0-ply    24/18                        Eq.:  -0.015 ( -0.212)
       0.502 0.121 0.006 - 0.498 0.140 0.004
        0-ply cubeful [expert]
    7. Cubeful 0-ply    24/20 6/4                    Eq.:  -0.023 ( -0.219)
       0.497 0.132 0.007 - 0.503 0.144 0.005
        0-ply cubeful [expert]
    8. Cubeful 0-ply    13/9 6/4                     Eq.:  -0.026 ( -0.222)
       0.494 0.146 0.008 - 0.506 0.151 0.009
        0-ply cubeful [expert]

If we instead request a 4-ply chequer play decision, gnubg will use the move filters defined for 4-ply:

Ply Accept moves Extra moves Threshold for extra moves
0 0 8 0.160
1 no pruning
2 0 2 0.040
3 no pruning

The 4-ply move filter is identical to the 2-ply for pruning at 0-ply, so after 0-ply we have the same three moves as above. Since there is no pruning at 1-ply these three moves are evaluated at 2-ply as above. There is no pruning at 3-ply.

At 4-ply we do not accept any moves, but add up to two moves if there within 0.040 from the best move. Since the second best move is -0.138 worse than the best move, we do not accept any moves to be evaluated at 4-ply. Hence gnubg will actually not evaluate any moves on 4-ply.

The predefined movefilters all have "accept 0 moves", in order to facilitate fast decisions and analysis, i.e., no need to waste much time over obvious moves.

For post-mortem analysis it may be worthwhile to ensure that gnubg analyses at least two moves at the specified ply. To do this, specify "accept 2 moves" in the move filters you use for analysis. However, do note that gnubg will force evaluation at the specified ply if the actual move made is doubtful. This ensures that all errors and blunders are evaluted at the same level.


Node:Analysis, Next:, Previous:Evaluation, Up:Settings

Analysis


Node:Rollouts, Next:, Previous:Analysis, Up:Settings

Rollouts


Node:Export, Previous:Rollouts, Up:Settings

Export


Node:Analysis and rollouts, Next:, Previous:Settings, Up:Top

Analysing and rollouts


Node:Evaluating a position, Next:, Up:Analysis and rollouts

Evaluating a position


Node:Evaluating a cube decision, Next:, Previous:Evaluating a position, Up:Analysis and rollouts

Evaluating a cube decision


Node:Rollout of moves, Next:, Previous:Evaluating a cube decision, Up:Analysis and rollouts

Rollout of moves


Node:Rollout of cube decisions, Next:, Previous:Rollout of moves, Up:Analysis and rollouts

Rollout of cube decisions

Quasi-Random Dice

Quasi-Random Dice are used to reduce the element of luck in rollouts. Instead of selecting purely random dice, gnubg will ensure a uniform distribution of the first roll of the rollout. If 36 trials is requested, one game will start with 11, two games with 21, two games with 31, etc. In general, if n * 36 games is requested, n games will start with 11, 2*n games with 21 etc. This is called rotation of the first roll. Similarly, if n*1296 trials is requested, the second roll will be rotated, such that n games will start with 11-11, 2*n games with 11-21, 4*n games with 21-21, etc. The third roll be also be rotated if the number of trials is proportional to 46656.

Suppose a user stops a 1296 trial rollout after 36 games. The 36 games would have had the following rolls for the first two rolls of each game: 11-11, 21-11, 12-11, 31-11, 13-11, ..., 66-11 Obviously such a rollout will give skewed results since the second roll was 11 for all games! To avoid this problem gnubg will randomise the sequence of rolls such that it is guaranteed that for any sample of 36 games you have exactly one game with first roll 11, exactly one game with second roll 11, etc. This is called stratification.

gnubg will actually also rotate and stratify rollouts where the number of trials are not multiples of 36, 1296, etc. The distribution of rolls is obviously not uniform any longer in this case, but it will still provide some reduction of the luck, i.e., no 37 trial rollout will have 3 games with a initial 66.

Before the first game of a rollout, gnubg creates a psuedo random array which it will use for all the games in the rollout. In effect it has already decided the roll sequence it will use for up to 128 rolls in every game of the rollout. In other words, for a normal rollout where games don't go over 64 moves, every single game of every possible rollout length has already had its dice sequence determined. During the rollout of game n, sequence n will be used, for game n+1 sequence n+1, etc. If it's a rollout as initial position, then whenever the current sequence starts with a double, the sequence is skipped and the dice routine moves on to the next sequence. Say an rollout as initial position is about to start using sequence 275, but that sequence begins with a double. The dice routine moves to sequence 276. On the following game, it will use sequence 277 (it remembers how many it has already skipped).

So, if you select rollout as initial position and 36 games, then you will get a prefect set of rolls for games 1..30 and the first 6 rolls of the next perfect set (the same rolls you would have gotton for games 31..36 if you'd asked for 1080 games or 10800 games or 92 games or whatever.

The dice sequence doesn't know how man trials it will be asked for, it simply generates sequences such that for a normal rollout (rollout as initial position) every 36 (30) games you get all possible 1st rolls, every 1296 (1080) games get every possible first 2 rolls, every 46656 (38880) games you get full sets of 3 rolls, etc.


Node:Analysing a saved game or match or session, Next:, Previous:Rollout of cube decisions, Up:Analysis and rollouts

Analysing a saved game or match or session

gnubg allows


Node:Output of an analysis, Next:, Previous:Analysing a saved game or match or session, Up:Analysis and rollouts

Output of an analysis

Chequer play analysis

Cube decision analysis

Game, match, or session statistics

You can get a summary of the analysis from the game, match, or session analysis. The game analysis is a summary for the current game whereas the match or session statistics is a summary of all the games in the match or session. The match analysis is available in the GUI from Analysis->Match Statistics or at the botton of exported files.

Chequer play statistics

This section provides a summary of the chequer play statistics. The following information is available

Luck analysis

This section provides information about how Ms. Fortuna distributed her luck. The following information is available:

Thresholds for marking of rolls:

Deviation of equity from average Roll is marked
>0.6 very lucky
0.3 - 0.6 lucky
-0.3 - 0.3 unmarked
-0.6 - -0.3 unlucky
< -0.6 very unlucky

Luck ratings:

Normalised luck rate per move Luck rating
> 0.10 Cheater :-)
0.06 - 0.10 Go to Las Vegas immediately
0.02 - 0.06 Good dice, man!
-0.02 - 0.02 none
-0.06 - -0.02 Better luck next time
-0.06 - -0.10 Go to bed
< -0.10 Haaa-haaa

Cube statistics

This section provides a summary of the cube decision statistics: the number of cube decisions, missed doubles, etc.

Overall rating

The last section is the overall summary.

Threshold for ratings:

Normalised total error rate per move Rating
0.000 - 0.002 Supernatural
0.002 - 0.005 World Class
0.005 - 0.008 Expert
0.008 - 0.012 Advanced
0.012 - 0.018 Intermediate
0.018 - 0.026 Casual Player
0.026 - 0.035 Beginner
> 0.035 Awful!


Node:Equities, Previous:Output of an analysis, Up:Analysis and rollouts

Equities

Introduction

gnubg works with many different kinds of equities. The equity is defined as the expected value of the position. However, this value can be expressed in several different metrics and may be calculated with or without taking the effect of the cube into consideration. In the following section we will describe the equities used and calculated by gnubg.

Money equity

This is the value of the position in money game, e.g., if you equity is +0.4 an you are playing money game with a $1 stake, you will win $0.40 on average. The money equity can be calculated with or without taking the effect of the doubling cube into consideration, or cubeful or cubeless. The cubeless equity can be calculated from the basic formulae: 2*p(w)-1+2(p(wg)-p(lg))+3(p(wbg)-p(lbg)). Evaluating the cubeful equity is much more difficult; it can either be estimated from the cubeless equitity by using transformations as outlined by Rick Janowski or by constructing a neural net that directly outputs cubeful equities. gnubg uses the former approach (see chapter Cubeful equities).

Match Winning Chance

In match play we're generally not particular interested in the outcome of the individual games as much as the outcome of the entire match, so the interesting quantity for match play is match winning chance (MWC). As for the money equity the MWC can be calculated with and without the effect of the doubling cube. The MWCs are generally calculated with the use of a match equity table, which contains the chance of winning the match before a game starts, e.g., if the score is 0-0 in a 1pt match each player has 50% chance of winning the match before the game starts assuming they're of equal skill.

The cubeless MWC is calculated as: MWC(cubeless) = p(w) * MWC(w) + p(l) * MWC(l) + p(wg) * MWC(wg) + p(lg) * MWC(lg) + p(wbg) * MWC(wbg) * p(lbg) * MWC(lbg).

For example, if the w/g/bg distribution is 0 30 60 - 40 10 0 and the match score is 1-3 to 5 with the cube on 2 the cubeless MWC is:

MWC(cubeless)= 30% * 50% + 30% * 0% + 30% * 100% + 10% * 0% + 0% * 100% + 0% * 0% = 45%,

so the cubeless MWC is 45%.

Evaluating the cubeful MWC is more difficult, and as for the cubeful money equity it's possible to estimate cubeful MWCs from transformation on the w/g/bg distribution or directly calculate it from neural nets. gnubg uses the former approach, but the formulae are currently not published.

Normalised equity

It's generally very difficult to compare MWCs. For example, it's hardly worth mentioning a 0.5% MWC error at DMP where as it's a huge error at 0-0 to 7. It is therefore of interesting to normalise the MWCs to some common scale. The most often used normalisation is Normalised Money Game Equity (NEMG) where the MWC for any game is transformed into the same interval as money game, i.e., -3 to +3 (due to anomalies at certain match scores the NEMG can go below -3 and above +3). The transformation is linear:

NEMG = 2 * (MWC-MWC(l))/(MWC(w)-MWC(l)) - 1

In other words, extrapolation with the following two extrapolation points: (MWC(w),+1) and (MWC(l),-1).

For example, suppose the score is 3-1 to 5 with the cube on 2: MWC(l)=0% and MWC(w)=50%:

MWC NEMG
0% -1
25% 0
50% +1
75% +2
100% +3

Note that a w/g/bg distribution of 0 100 100 - 0 0 0 gives a NEMG of +3 whereas the corresponding money equity is only +2. This is because the gammon price is high for that particular score. When both players are far from winning the match, e.g., 0-0 to 17 or 1-0 to 17, NEMG is very close to the ususal money equity.

NEMG can be calculated from both cubeless and cubeful MWCs.

A word of caution: A cubeless NEMG calculated from a cubeless MWC could be named "cubeless equity", but in most backgammon litterature this term seems to be reserved for the cubeless money equity.


Node:Position and match IDs, Next:, Previous:Analysis and rollouts, Up:Top

Position and match IDs


Node:A technical description of the position ID, Next:, Up:Position and match IDs

A technical description of the position ID

Introduction

This section describes a method for compactly recording a backgammon position. It demonstrates how to encode a position into 10 binary bytes, which is useful for minimising the space used when recording large numbers of positions in memory or on disk. There is also an ASCII representation in 14 characters, which is convenient for output to the screen, for copying and pasting to transfer positions between programs which support the format, and for communicating positions via Usenet news or e-mail. The 10 byte binary format is called the key, and the 14 character ASCII format is the ID.

Key format

The key is essentially a bit string (imagine you start with an empty sequence of bits, and continue adding either "0" or "1" to the end). The way to build up a sequence that corresponds to a given position is:

  1. For every point around the board (starting at the ace point of the player on roll, continuing around to the 24 point and ending at the bar):
    1. append as many 1s as the player on roll has on that point (if any).
    2. append a 0.
  2. For every point around the board (starting at the ace point of the opponent, continuing around to the opponent's 24 point and ending at the bar):
    1. append as many 1s as the opponent has on that point (if any).
    2. append a 0.
    3. Pad out the string to 80 bits with 0s.

The worst-case representation will require 80 bits: you can see that there are always 50 0 bits even if there are no chequers at all. Each player has a maximum of 15 chequers in play (not yet borne off) which require a 1 bit wherever they are positioned. That's 30 bits to take of all chequers, plus the 50 bits of overhead for a total of 80 bits (the last bit is always 0 and isn't strictly necessary, but it makes the code slightly easier). This bit string should be stored in little-endian order when packed into bytes (ie. the first bits in the string are stored in the least significant bits of the first byte).

As an example, here's what the starting position looks like in the key format:

0 0 0 0 0 player on roll has no chequers on ace to 5 points
11111 0 5 chequers on the 6 point
0 empty bar
111 0 3 on the 8
0 0 0 0 no others in our outfield
11111 0 5 on the midpoint
0 0 0 0 0 none in the opponent's outfield
0 0 0 0 0 or in opponent's board, until...
11 0 two on the 24 point
0 none on the bar
0 0 0 0 0 opponent has no chequers on ace to 5 points
11111 0 5 chequers on the 6 point
0 empty bar
111 0 3 on the 8
0 0 0 0 no others in opponent's outfield
11111 0 5 on the midpoint
0 0 0 0 0 none in our outfield
0 0 0 0 0 or in our board, until...
11 0 two on the 24 point
0 none on the bar

so altogether it's:

00000111110011100000111110000000000011000000011111001110000011111000000000001100

In little endian bytes it looks like:

11100000 01110011 11110000 00000001 00110000 11100000 01110011 11110000 00000001 00110000 0xE0 0x73 0xF0 0x01 0x30 0xE0 0x73 0xF0 0x01 0x30

so the 10 byte key (in hex) is E0 73 F0 01 30 E0 73 F0 01 30. ID format

The ID format is simply the Base64 encoding of the key. (Technically, a Base64 encoding of 80 binary bits should consist of 14 characters followed by two = padding characters, but this padding is omitted in the ID format.)

To continue the above example, splitting the 10 8-bit bytes into 14 6-bit groups gives:

111000 000111 001111 110000 000000 010011 000011 100000 011100 111111 000000 000001 001100 000000

In Base64 encoding, these groups are respectively represented as:

4 H P w A T D g c / A B M A

So, the position ID of the chequers at the start of the game is simply:

4HPwATDgc/ABMA

You can set the board in gnubg either by writing the position ID into the position text input field in the GUI or by executing the command set board 4HPwATDgc/ABMA.

Notes


Node:A technical description of the match ID, Previous:A technical description of the position ID, Up:Position and match IDs

A technical description of the match ID

Introduction

This section describes how the match ID is calculated. The match ID can be used for easy exchange of positions for gnubg users in conjuction with the position ID. The match key is a 9 byte representation of the match score, match length, value of cube, owner of cube, Crawford game flag, player on roll, player to make a decision, doubled flag, resigned flag, and the dice rolled. The match ID is the 12 character Base64 encoding of the match key.

Match key

The match key is a bit string of length 66:

  1. Bit 1-4 contains the 2-logarithm of the cube value. For example, a 8-cube is encoded as 0011 binary (or 3), since 2 to the power of 3 is 8. The maximum value of the cube in with this encoding is 2 to the power of 15, i.e., a 32768-cube.
  2. Bit 5-6 contains the cube owner. 00 if player 0 owns the cube, 01 if player 1 owns the cube, or 11 for a centered cube.
  3. Bit 7 is the player on roll or the player who did roll (0 and 1 for player 0 and 1, respectively).
  4. Bit 8 is the Crawford flag: 1 if this game is the Crawford game, 0 otherwise.
  5. Bit 9-11 is the game state: 000 for no game started, 001 for playing a game, 010 if the game is over, 011 if the game was resigned, or 100 if the game was ended by dropping a cube.
  6. Bit 12 indicates whose turn it is. For example, suppose player 0 is on roll then bit 7 above will be 0. Player 0 now decides to double, this will make bit 12 equal to 1, since it is now player 1's turn to decide whether she takes or passes the cube.
  7. Bit 13 indicates whether an doubled is being offered. 0 if no double is being offered and 1 if a double is being offered.
  8. Bit 14-15 indicates whether an resignation was offered. 00 for no resignation, 01 for resign of a sigle game, 10 for resign of a gammon, or 11 for resign of a backgammon. The player offering the resignation is the inverse of bit 12, e.g., if player 0 resigns a gammon then bit 12 will be 1 (as it is now player 1 now has to decide whether to accept or reject the resignation) and bit 13-14 will be 10 for resign of a gammon.
  9. Bit 16-18 and bit 19-21 is the first and second die, respectively. 0 if the dice has not yet be rolled, otherwise the binary encoding of the dice, e.g., if 5-2 was rolled bit 16-21 will be 101-010.
  10. Bit 22 to 36 is the match length. The maximum value for the match length is 32767. A matchscore of zero indicates that the game is a money game.
  11. Bit 37-51 and bit 52-66 is the score for player 0 and player 1 respectively. The maximum value of the match score is 32767.

For example, assume the score is 2-4 in a 9 point match with player 0 holding a 2-cube, and player 1 has just rolled 52. The match key for this will be (note that the bit order is reversed below for readability)

1000 00 1 0 100 1 0 00 101 010 100100000000000 010000000000000 001000000000000

In little endian the bytes looks like:

01000001 10001001 00101010 00000001 00100000 00000000 00100000 00000000 00

0x41 0x89 0x2A 0x01 0x20 0x00 0x20 0x00 0x00

Match ID

Analogous to the position ID from the previous section the match ID format is simply the Base64 encoding of the key.

To continue the example above, the 9 8-bit bytes are grouped into 12 6-bits groups:

010000 011000 100100 101010 000000 010010 000000 000000 001000 000000 000000 000000

In Base64 encoding, the groups are represented as:

Q Y k q A S A A I A A A

So, the match id is simply:

QYkqASAAIAAA

If someone post a match ID you can set up the position in gnubg by writing or pasting it into the Match ID text input field on the main window, or by executing the command set matchid QYkqASAAIAAA.


Node:Cubeful equities, Next:, Previous:Position and match IDs, Up:Top

Cubeful equities

This chapter is a brief description of how gnubg calculates cubeful equities. The formulae build directly on the work by Rick Janowski Take-Points in Money Games from 1993.

Basic formulae for cubeful equities

The basic formulae for cubeful equities as derived by Janowski is

E(cubeful) = E(dead) * (1-x) + E(live) * x,

where E(dead) is the dead cube equity (cubeless equity) calculated from the standard formulae. E(live) is the cubeful equity assuming a fully live cube. We'll return to that in the next section. x is the cube efficiency. x=0 gives E(cubeful)=E(dead) as one extreme and x=1 gives E(cubeful)=E(live) as the other extreme. In reality x is somewhere in between, which typical values around 0.6 - 0.8.

Janowski's article doesn't mention cubeful equities, so we use the straightforward generalisation

MWC(cubeful) = MWC(dead) * (1-x) + MWC(live) * x.

as MWC is the entity that is used for match play evaluations.

Live cube equities

The live cube equity is the equity assuming that the equity changes continuously, so that doubles and takes occurs exactly at the double point and take point. For gammonless play this is the well-known take point of 20%. Janowski derives the more general formula

TP = (L-0.5)/(W+L+0.5)

where W is the average cubeless value of games ultimately won, and L is the average cubeless value of games ultimately lost. For example, for the following position

 GNU Backgammon  Position ID: 4HPMwQCMz+AIIQ
                 Match ID   : cAkAAAAAAAAA
 +13-14-15-16-17-18------19-20-21-22-23-24-+     O: gnubg
 | X  O     X  O    |   | O  X           X |     0 points
 | X  O        O    |   | O                |
 | X           O    |   | O                |
 |                  |   | O                |
 |                  |   | O                |
v|                  |BAR|                  |     (Cube: 1)
 |                  |   | X                |
 |                  |   | X                |
 | O                |   | X                |
 | O           X  O |   | X        X       |     On roll
 | O           X  O |   | X        X       |     0 points
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     X: jth

gnubg evaluates

        Win     W(g)    W(bg)   L(g)    L(bg)
static: 0.454   0.103   0.001   0.106   0.003

and hence W=(0.454 + 0.103 + 0.001)/0.454=1.229 and L=(0.556+0.106+0.003)/0.556) = 1.196. For gammonless positions, e.g., a race, W=1 and L=1.

The live cube equity is now based on piecewise linear interpolation between the points (0%,-L%), (TP,-1), (CP,+1), and (100%,+W): if my winning chance is 0 I lose L points, at my take point I lose 1 point, at my cash point I cash 1 point, and when I have a certain win I win W points:

mgtp.png Figure X Cubeful equities

For match play there is no simple formula, since redoubles can only occur a limited number of times.

The live cube take point is generally calculated as

TP(live, n Cube)=TP(dead, n cube) * (1 - TP(live, 2n cube)

So to calculate the live cube take points for a 1-cube at 3-0 to 7 we need the live cube take points for the 4-cube and the 2-cube. For the position above and using Woolsey's match equity table the live cube take point are:

Cube value TP for X TP for O
4 0% 41%
2 15% 38.5%
1 24.5% 27.3%

The calculation of these are left as an exercise to the reader.

Ignoring backgammons, the gammon rates for O and X are 0.106/54.6=19% and 0.103/0.454=22%, respectively. If O wins the game his MWC will be

81% * MWC(-3,-7) + 19% * MWC(-2,-7) = 78%

and if X wins his MWC will be

78% * MWC(-4,-6) + 22% * MWC(-4,-5) = 41%.

If O cashes 1 point he has MWC(-3,-7)=76% and if X cashes he has MWC(-4,-6)=36%. Analogous to money game the live cube MWC is calculated as piecewise linear interpolation between (0%,22%), (24.5%,24%), (72.7%,36%), and (100%,41%) (from X's point of view):

mptp.png Figure X Fully live cubeful MWC

0-ply Cubeful equities

Having established the live cube equities and MWCs we're now in position to calculate the 0-ply cubeful equities.

Let's start with money game: the cubeless equity is -0.097 and the live cube equity can be determined from Figure X as -0.157. Thus, the cubeful equity is -0.138.

For the match play example at the score 3-0 the cubeless MWC is 29.1% and from Figure X using wins=45.4% we can determine the live cube MWC to be 29.2%. Using a value of x=0.68 we arrive at a cubeful MWC of 29.17%.

n-ply Cubeful equities

The previous section concerned the calculation of 0-ply cubeful equities, so how so gnubg calculate cubeful 2-ply equities? The answer is: by simple recursion:

Equity=0
Loop over 21 dice rolls
   Find best move for given roll
   Equity = Equity + Evaluate n-1 ply equity for resulting position
End Loop
Equity = Equity/36

Note that evaluating the n-1 ply equity involves a cube decision, since the opponent may double, so gnubg will actually calculate the two n-1 ply equities: (a) assuming no double, and (b) assuming double, take. These two equities are combined with the equity for a pass, and the optimum of these three is added to the resulting equity. For a cubeful 2-ply evaluation gnubg will end up calculating the following cubeful 0-ply equities: centred 1-cube, opponent owns 2-cube, owned 4-cube, and opponent owns 8-cube.

Note that the 2-ply level does not use the cube efficiency, it's not used until at the 0-ply level, but it's possible to calculate an effective one by isolating x in the basic cube formulae:

x(eff) = (E(2-ply cubeful) - E(2-ply dead))/(E(2-ply live)-E(2-ply dead)).

The cube efficiency

The cube efficiency is obviously an important parameter, unfortunately there haven't been much investigation carried out, so gnubg basically uses the values 0.6-0.7 originally suggested by Rick Janowski:

Position Class x (Cube efficiency)
Two-sided (exact) bearoff n/a
One-sided bearoff 0.6
Crashed 0.68
Contact 0.68
Race linear interpolation between 0.6 and 0.7

For race gnubg uses linear interpolation based on pip count for the player on roll. A pip count of 40 gives x=0.6 and 120 gives x=0.7. If the pip count is below 40 or above 120 values of x=0.6 and x=0.7 are used, respectively.

For the two sided bearoff positions the cubeful money equity is already available from the database, so for money game there is no need to calculate cubeful equities via Janowski's formulae. However, the cubeful equities for money game cannot be used for match play. Instead of using a fixed value of x, say, 0.6, gnubg will calculate an effective value based on the cubeful money equity. The cubeful MWC is calculated as usual, but with the calculated x.

There is obviously room for improvements. For example, holding games should intuitively have a lower cube efficiency, since it's very difficult to double effectively: either it's not good enough or you've lost the market by a mile after rolling a high double or hitting a single shot. Similarly, backgames will often have a low cube efficiency, whereas blitzes have may have a higher cube efficiency.

Cube decisions

gnubg's cube decisions are simple based on calculations of cubeful equities. For a double decision gnubg calculates the cubeful equity for "no double" and the cubeful equity for "double, take". Combined with the equity for "double, pass", it's possible to determine the correct cube action.

Figure X shows the relevant cubeful equities for O and X's cube decisions in sample position from earlier.

mgcd.png Figure X Cubeful equities

On 0-ply X will double when the green curve (O owns 2-cube) is above the red curve (centered cube), and O will take as long as the green curve is below 1. Similarly, O will double when the blue curve (X owns 2-cube) is below the red curve (centered cube), and X takes as long as the blue curve is above -1.

Note that gnubg doesn't calculate the take point or double point explicitly. The cube decision is simply made by comparing equities from Figure X.

Beyond the simple model

Janowski has developed two other models for cubeful equities. The first is a generalisation of the one used by gnubg; it introduces two cube efficiencies instead of one. Often you may see that the cube efficiencies are different for the two players, and the "refined general model" as it is named by Janowski, tries to take this into consideration by using different cube efficiency parameters for the two players. For example, the blitzer may have another cube efficiency that the blitzee.

The second model is not published, but redefines the cube efficiency into a value that can be understood more intuitively and calculate easily from rollouts.


Node:Training, Next:, Previous:Cubeful equities, Up:Top

Training


Node:Scripting, Next:, Previous:Training, Up:Top

Scripting

Accessing gnubg Python shell

To access the Python shell, either type > from the command line or select Windows->Python Shell(IDLE...) from the GUI.

gnubg module functions

board()
command(cmd)
evaluate()
evalcontext()
eq2mwc()
mwc2eq()
cubeinfo()
met()
positionid()
positionfromid()
positionkey()
positionfromkey()
positionbearoff()
positionfrombearoff()
navigate([next=N,[game=N]])
Match navigation.

Without any arguments, go to first move of first match.

With next == N, move forward N game records.

With game == N, move forward/backward N games.

Navigate never wraps around.

On success, returns None. If unable to complete the requsted number of moves, returns a pair of (next-remaining,game-remaining).

match([analysis=1/0, boards=1/0, statistics=0/1, verbose=0/1])
Return the current match. For example,
> m = gnubg.match()

Takes the following optional keyword arguments:

analysis
When 0, discard analysis data. default is 1.
boards
When 1, add current board to move/double records. Default is 1.
statistics
When 1, include game and match statistics. Default is 0.
verbose
When 1, include derived analysis values. Default is 0.

Match description

gnubg.match() returns a dictionary containing the following items:

match-info
General match info. match-info
games
A sequence, one elemet per game. game
stats (optional)
Match statistics.

Match info

A dictionary containing the following items:

match-length

variation
One of Standard,Nackgammon, Hypergammon1, Hypergammon2 or Hypergammon3.
rules (optional)
Additional rules used. A subset of NoCube, Crawford and Jacoby.
X
O
Per player information. Each a dictionary containing rating and name.
annotator (optional)
round (optional)
place (optional)
date (optional)
Sequence of (Day,Month,Year).
event (optional)
default-eval-context
Default evaluation context. A dictionary in the same format as returned by evalcontext().
default-rollout-context
Default rollout context.

Example,

>>> m['match-info']
{'match-length': 25, 'rules': ('Crawford',), 'default-eval-context': {'plies': 2, 'deterministic': 1, 'reduced': 0, 'noise': 0.0, 'cubeful': 1}, 'annotator': 'GNU 0.14', 'O': {'rating': '0 (Exp 0)', 'name': 'Moshe Tissona'}, 'round': 'Final', 'place': 'Monte Carlo', 'variation': 'Standard', 'default-rollout-context': {'n-truncation': 11, 'initial-position': 0, 'trials': 0, 'stop-on-std': 0, 'variance-reduction': 1, 'late-eval': 0, 'truncated-rollouts': 0, 'truncate-bearoff2': 1, 'cubeful': 1, 'truncate-bearoffOS': 1, 'seed': 1177750272, 'quasi-random-dice': 1, 'minimum-games': 144}, 'date': (13, 7, 2003), 'X': {'rating': '0 (Exp 0)', 'name': 'Jon Royset'}, 'event': 'World Championship 2003'}

Python game

A dictionary containing the following items:

info
General game info. For example,
>>> m['games'][0]['info']
{'points-won': 1, 'score-X': 0, 'score-O': 0, 'winner': 'X', 'resigned': False}

If no winner is specified, winner is None.

>>> m['games'][2]['info']
{'score-X': 2, 'winner': None, 'score-O': 0}

game
A Sequence of actions. actions
stats (optional)
Game statistics. Similar entries to Analyse->Game statistics from the GUI.

Game actions

Each action is a dictionary


Node:Bearoff databases, Next:, Previous:Scripting, Up:Top

Bearoff databases

This section describes what kind of bearoff databases you can use with gnubg as well as how you may obtain these.


Node:Introduction to bearoff databases, Next:, Up:Bearoff databases

Introduction to bearoff databases

There are two kind of bearoff databases: two-sided (exact) bearoff databases or one-sided (approximative) bearoff databases.

Two-sided bearoff databases

Two-sided bearoff databases contain exact probabilities or equities for winning.

For example, for less than 6 chequers inside the home quadrant, each side has 924 different positions, for a total of 924 * 924 = 853,776 positions possible. The bearoff database will contain the exact winning probability for each of these 853,776 positions. Typically, the database also includes cubeful equities for money game. Cubeful equities for match play is generally not included as it is dependent on match score and cube level.

Consider the following position:

 GNU Backgammon  Position ID: CgAAEAEAAAAAAA
                 Match ID   : cIkMAAAAAAAA
 +13-14-15-16-17-18------19-20-21-22-23-24-+     O: gnubg
 |                  |   |          O  O    | OOO 0 points
 |                  |   |                  | OOO
 |                  |   |                  | OOO
 |                  |   |                  | OO
 |                  |   |                  | OO
v|                  |BAR|                  |     (Cube: 1)
 |                  |   |                  | XX
 |                  |   |                  | XX
 |                  |   |                  | XXX
 |                  |   |                  | XXX On Roll
 |                  |   |    X        X    | XXX 0 points
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     X: jth

Using a two-sided bearoff database will yield that player X has 67.1% cubeless chance of winning. The database also gives cubeful money equities of +0.3441, +0.3210, and +0.1605 for X owning cube, centred cube, and O owning cube, respectively. So it's an initial double since +0.3210 >= 2 * +0.1605. However it's not a redouble since +0.3441 >= 2 * 0.1605.

The major problem with two-sided databases is that the size increases incredible fast with the number of points and chequers:

Chequers Points Number of positions
6 6 853,776
7 6 2,944,656
8 6 9,018,009
...
15 6 2,944,581,696
...
15 24 18,528,584,051,601,162,496

gnubg stores the equity for each position with a precision of approximately 0.00003 which requires 2 bytes of storage. Hence, storing one cubeless and three cubeful equities requires a total of 8 bytes per position. This gives the following storage requirements for n chequers inside the home quadrant:

Chequers Points Number of positions Size/MB
6 6 853,776 6
7 6 2,944,656 22
8 6 9,018,009 68
9 6 25,050,025 191
10 6 64,128,064 489
11 6 153,165,376 1,168
12 6 344,622,096 2,629
13 6 736,145,424 5,616
14 6 1,502,337,600 11,461
15 6 2,944,581,696 22,465

For the typical user the limit is probably 10 or 11 chequers unless she owns vast amounts of disk space. Also, the time to generate these databases increases proportionally with the size. The 15 chequer database takes at least 3,500 times the time it takes to generate the 6 point database. For example, on the author's 1GHz Pentium III it takes approximately 6 minutes to generate the 6 points database, hence it would take at least 21,000 minutes or approximately 15 days to generate the 15 point database on the same computer.

One-sided bearoff databases

Instead of looking at both player's positions simultaneously large savings can be obtained by looking at each side independently. For each position we tabulate the probability P(n) what the player will bear all chequers off in n rolls; P(n) is the one sided bearoff distribution. Assume player 0 and player 1 has one sided bearoff distributions P0(n) and P1(n), respectively. The chance of player 0 bearing all chequers off before player 1 is:

p = sum(i=0 to infinity) P0(i) [ sum(j=i to infinity) P1(j) ]

For example, consider the following position:

 GNU Backgammon  Position ID: 2x0AAOi2AQAAAA
                 Match ID   : cAkAAAAAAAAA
 +13-14-15-16-17-18------19-20-21-22-23-24-+     O: gnubg
 |                  |   |       O  O  O  O | O   0 points
 |                  |   |       O  O  O  O | O
 |                  |   |       O  O       | O
 |                  |   |                  | O
 |                  |   |                  | O
v|                  |BAR|                  |     (Cube: 1)
 |                  |   |                  | X
 |                  |   |                  | X
 |                  |   |             X    | X
 |                  |   |    X  X  X  X    | X   On roll
 |                  |   |    X  X  X  X  X | X   0 points
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     X: jth

The one sided bearoff distributions are

Rolls jth gnubg
3 1.917% 2.811%
4 18.749% 28.403%
5 44.271% 50.307%
6 32.998% 18.114%
7 2.029% 0.363%
8 0.037% 0.002%

Applying the formula above gives:

1.917% * 100% + 18.749% * 97.189% + 44.271% * 68.786% ... + 0.037% * 0.02% = 56.7%

The cubeless gwc's calculated from one sided bearoff distributions are usually quite good, although no thorough investigations have been performed so far. Although the databases are one sided they can also give correct moves in "desperation" scenarios.

By storing the probability to bearoff at least one chequer, it's also possible to calculate gammon probabilities, as the chance of being gammoned is the probability that my opponent bears all chequers off before I bear at least one chequer off. Analogously, it's possible to calculate the chance of gammoning the opponent.

The storage requirements are much smaller than for the equivalent two sided databases.

Chequers Points Number of positions
15 6 54,264
15 7 170,544
15 8 490,314
15 9 1,307,504
15 10 3,268,870
15 11 7,726,160
15 12 17,383,860
15 13 37,442,160
15 14 77,558,760
15 15 155,117,250
15 16 300,540,195
15 17 565,722,720
15 18 1,037,158,320

For example, 15 chequers on 6 points is only 54,264 positions for the one sided bearoff database compared to 294,458,696 positions for the equivalent two sided bearoff database. However, for each position we need to store an array of probabilities. For example, for 15 chequers on the 18 point we have to store 15 non-zero probabilities compared to only one in the two sided bearoff database. The table below gives approximate database sizes for gnubg's one sided databases (both bearoff and gammon distributions):

Chequers Points Size in MB
15 6 1.4
15 7 5
15 8 15
15 9 42
15 10 112
15 11 284
15 12 682
15 13 1,543
15 14 approx 4,300
15 15 approx 10,700
15 16 approx 26,700
15 17 approx 66,700
15 18 approx 166,000

So, the practical limit is probably around the 11 to 13 point, depending on the disk space available.

gnubg can generate one sided bearoff database where the exact bearoff distribution is approximated by a normal distribution: instead of storing up to 15 or 20 non-zero probabilities only two parameters characterising the normal distribution has to be stored: the mean and the variance. The approximative distributions yields reasonably accurate gwc's and gammon probabilities compared to the exact one sided bearoff database. The size of the these approximative databases are roughly a quarter of the exact one, hence the limit is around the 13 to 15 point depending on the disk space available. The option to use approximative bearoff databases is work in progress!

As with the two sided bearoff databases it can be a rather time consuming task to generate one sided databases. The 10 point database takes approximately 2 hours to generate on the author's 1 GHz Pentium III. The 12 point database may more than one day!

Hypergammon databases

gnubg can also play Hypergammon; a variant of backgammon with only 3 chequers, but with counting gammons and backgammons. The starting position is

 GNU Backgammon  Position ID: AACgAgAAKgAAAA
                 Match ID   : cAkAAAAAAAAA
 +13-14-15-16-17-18------19-20-21-22-23-24-+     O: gnubg
 |                  |   |          X  X  X |     0 points
 |                  |   |                  |
 |                  |   |                  |
 |                  |   |                  |
 |                  |   |                  |
v|                  |BAR|                  |     (Cube: 1)
 |                  |   |                  |
 |                  |   |                  |
 |                  |   |                  |
 |                  |   |                  |     On roll
 |                  |   |          O  O  O |     0 points
 +12-11-10--9--8--7-------6--5--4--3--2--1-+     X: jth
Pip counts: O 69, X 69

gnubg can also play the two-chequer and one-chequer variations as well. Although it looks very simple to play, Hypergammon is in fact quite difficult to play correctly.

There are 3,276 possible ways to distribute 3 (or less) chequers over 25 points (the 24 points plus the bar). This gives a total of 10,732,176 possible two sided positions. However, many these are illegal:

Position type Number of positions
Game over 6,551
Race (no contact) 587,926
Contact 7,365,427
Illegal positions 2,772,272
Total 10,732,176

So there is close to 8 million legal positions for Hypergammon. Since this is a relative small number it's possible to tabulate the game winning chance, cubeless equity, or cubeful equities for all positions.

Due to the contact positions it is not possible to generate such a database in one run; instead the process is iterative: (a) "guess" equities for the 8 million positions, (b) use these equities to calculate 1-ply equities for all positions, and (c) if the equities change significantly then go back to step (c).


Node:Bearoff databases with GNU Backgammon, Next:, Previous:Introduction to bearoff databases, Up:Bearoff databases

Bearoff databases with GNU Backgammon

gnubg works with both one sided and two sided bearoff databases. Currently, it works with up to four databases; two of each kind. Two of the databases are read into memory for fast access, but of course these are limited to very sm