Contents page | Winboard setup | Command line parameters | Commands reference | Licence and Warranty

# Commands Reference: Book Commands

badd | - add data to the current opening book.
bcreate | - create a new empty opening book, and select it.
bk | - probe for the current position in the opening book.
book | - select a new primary opening book to use.
bset | - change settings used for move probabilities from book.

##

The badd command

### Summary

The badd command allows games from pgn format files to be imported into the currently selected primary opening book.

### Format

`

      badd [-d DEPTH] [-w|-b] [-bias BIAS] file.pgn

`

### Parameters

``

      -d DEPTH      Limit depth of import from file.pgn to DEPTH ply (half moves).
                    The default value for DEPTH is 40.
      -w            Add this file only for white to move.
      -b            Add this file only for black to move.
      -bias BIAS    Change bias to BIAS (0.0...3.75).  Default value is 1.0.
      file.pgn      Pgn file containing games to import.

### Details: -d DEPTH

With this parameter you can limit the number of moves that are imported from the beginning of the each game in the pgn file. By default, the depth value is set to 40. If you want to import all moves, just specify a large number (e.g. "-d 99999".)

### Details: -w|-b

With these options you can restrict which moves in a position are considered by the engine.

### Details: -bias BIAS

This options allows the bias to be changed while this pgn file is being imported.

What does that mean? The BIAS changes the WEIGHT of a move in the opening book. Increasing the BIAS (>1.0) makes it more likely that this move will be chosen, and decreasing the BIAS (<1.0) makes it less likely.

For a more detailed explanation of how BIAS is used to calculate the probability of a move, see the section below about the bk command.

### Details: file.pgn

This is the name of the file from which you want to extract the games that are to be imported into the opening book.

### Examples

`

      badd MyBookFile.pgn

      badd -w -d 30 MyWhiteBookFile.pgn
      badd -b -d 30 MyBlackBookFile.pgn

      badd -d 30 -bias 1.0 MyWideBookFile.pgn
      badd -d 30 -bias 10.0 MyThinBookFile.pgn

`

##

The bcreate command

### Summary

The bcreate command is used to create new opening books. It also selects a newly created book to be the current primary opening book.

### Format

`

      bcreate bookfile.hbk

`

### Parameters

`

      bookfile.hbk   Name of the new book file to create.

`

### Details

This command will create a new empty opening book file, that contains 0 positions. If the creation succeeds, it then selects this new book file as the current priomary opening book (as if the command "book bookfile.hbk" had also been entered.)

### Examples

`

      bcreate MyNewOpeningBook.hbk

`

##

The bk command

### Summary

This command is used to probe the primary opening book. It can also be used to switch book usage on or off.

### Format

`

      bk [on|off]

`

### Details

This command looks up the current position in the primary opening book, and prints out the details of any moves it finds.

The output looks like this:

`
      >bk
      Book file "primary.hbk" contains 67061 positions
      Games threshold: 3
      Game score bias: 5.00
         Move     Games   White%   Bias     Weight      Prob%   Flags
      -------   -------   ------   ----   --------   --------   --------------------
          Nf3       596    55.0%   1.00      448.0    14.538%   WTM BTM
           b3         3    66.7%   1.00        4.0     0.130%   WTM BTM
           c4       559    53.4%   1.00      374.5    12.153%   WTM BTM
           d4      1377    53.6%   1.00      938.5    30.456%   WTM BTM
           e4      2003    53.1%   1.00     1316.5    42.723%   WTM BTM
`

``

      Move    Tells us a move from the current position that is in book.
      Games   Number of games in which this move has been played.
      White%  The average score for White when this move was played.
      Bias    An amount to bias the weight of a move by.
      Weight  The final wieght calculated for a move.
      Prob%   The probability that this move will be played in a game.
      Flags   Flags that can include WTM, BTM, VGOOD, GOOD, BAD, VBAD.

The Weight of a move is basically Games * Score * Bias, but there are some exceptions, and some ways of changing the Weight using specific biases and hinting.

For programmers that are interested, some psuedo code follows:

`
      let THRESHOLD = value of Threshold book parameter	(=3 above)
      if Games < THRESHOLD
        let Weight = 0
      else if White-to-move AND no WTM flag
        let Weight = 0
      else if Black-to-move AND no BTM flag
        let Weight = 0
      else
        let SCOREBIAS = value of ScoreBias book parameter (=5.00 above)
        if White-to-move
          let PROBWIN = White% / 100
        else
          let PROBWIN = 1 - White% / 100
        endif

        let SCORE = MAX(0, 0.5 + (PROBWIN - 0.5) * SCOREBIAS)

        if Flags contains VBAD
          let ANNOT = value of VBadBias book parameter (default = 0)
        else if Flags contains BAD
          let ANNOT = value of BadBias book parameter (default = 0.5)
        else if Flags contains GOOD
          let ANNOT = value of GoodBias book parameter (default = 2)
        else if Flags contains VGOOD
          let ANNOT = value of VGoodBias book parameter (default = 10)
        else
          let ANNOT = 1
        endif

        let Weight = Games * SCORE * ANNOT * Bias
      endif

      let TOTALWEIGHT = sum of all Weights
      let Prob% = 100.0 * Weight / TOTALWEIGHT
`

### Examples

`

      bk
      bk on
      bk off

`

##

The book command

### Summary

Use this command to select which book file to use as the primary opening book.

### Format

`

      book bookfile.hbk

`

### Parameters

`

      bookfile.hbk   Name of the new book to use as the primary book file.

`

### Details

This command is used to select the primary book file to use. The default name of the primary book file is "primary.hbk".

### Examples

`

      book primary.hbk
      book MyPrimaryBook.hbk

`

##

The bset command

### Summary

This command shows the current engine book parameters, and allows them to be changed.

### Format

`

      bset [PARAMETER VALUE]

`

### Parameters

`

      PARAMETER    This is the name of a book parameter that you wish to change.
      VALUE        This is the new value of the book parameter

`

### Details

If you want to see the values of the current book parameters, just type bset on its own, e.g.:

`
      >bset
      Engine book parameters
      ----------------------
      Threshold      3
      ScoreBias   5.00
      VGoodBias  10.00
      GoodBias    2.00
      BadBias     0.50
      VBadBias    0.00
`

These parameters are actually stored in the book file. The engine uses them to change the way that it chooses moves using the information from the book file. See the bk section for more details about the calculations the engine makes to get a probability for playing a move.

### Examples

`

      bset
      bset Threshold 3
      bset ScoreGain 5

`

Send e-mail to chess@7sun.com.
Page last updated by Tim Foden on the 16th March 2003.