bishbosh(1) manual page

Description

A chess-game which can be rendered natively in a terminal (emulator) using raw ASCII, or used as a chess-engine by a separate GUI (xboard).

It permits:

Castling
En-passant
Resignation
Draw by Stale-mate, the Seventy-five move rule, Five-fold Repetition, or Insufficient Material.

It features:

Unlimited roll-back of moves.
Configurable https://en.wikipedia.org/wiki/Chess_notation.
The ability to read PGN-databases of standard openings & archived games, in which it can match both https://chessprogramming.wikispaces.com/Transposition s & colour-flipped (https://chessprogramming.wikispaces.com/Color+Flipping) positions.
Automation of the moves for either, neither, or both players. Both the evaluation of moves & the search for the optimum, are highly configurable; see section-5 of the man-pages.
Optional hints for manual players.
https://chessprogramming.wikispaces.com/Pondering .

Some understanding of the algorithm used to automatically select moves, is useful either when configuring this application or when interpreting the esoteric feedback available after move-selection (given "--verbosity=Deafening"). The algorithm first compares the position with those in the referenced PGN-databases; a looser criterion than whether a matching move-sequence exists. It then partitions all matching archived positions, based on whether the current side was ultimately victorious. The next move will be selected randomly from the subset of victorious matching positions, in preference to the non-victorious subset.

On failure to match the position with an archived game, the tree of all possible moves until the end of the game, is constructed & statically sorted to advance the subsequent evaluation of capture-moves, using either https://chessprogramming.wikispaces.com/MVV-LVA or https://chessprogramming.wikispaces.com/Static+Exchange+Evaluation . On each move, this tree’s non-capture moves are dynamically sorted using the https://chessprogramming.wikispaces.com/Killer+Heuristic & the https://chessprogramming.wikispaces.com/History+Heuristic .
This tree is then searched using a https://chessprogramming.wikispaces.com/Negamax algorithm with https://chessprogramming.wikispaces.com/Alpha-Beta pruning, over a constant configurable number of plies, to find the optimal move according to the weighted-mean of various criteria described in section-5 of the man-pages.
Shortcuts in the search for the optimal move are taken on encountering either https://chessprogramming.wikispaces.com/Repetitions in the move-sequence, or transpositions (https://chessprogramming.wikispaces.com/Transposition) of sibling games.

Options

Input

-i File-path, --inputConfigFilePath=File-path; there is no default.: Read the mandatory configuration from the specified XML-file,

Execution

-r[Int], --randomSeed[=Int]: Optionally takes an argument with which to seed the single pseudo-random number-generator used for all random operations. See "randomSeed" in section-5 of the man-pages.
In the absence of the whole field, the random-number generator will be seeded unpredictably from the operating-system. In the absence of just the argument, "0" will be inferred.
N.B.: this application only makes significant use of the random-generator when selecting a move from any configured PGN-databases (see "pgnOptions" in section-5 of the man-pages); move-selection is otherwise deterministic.

Output

--verbosity=(Silent|Normal|Verbose|Deafening), defaulting to "Normal".: Defines the quantity of ancillary output required. See "verbosity" in section-5 of the man-pages.
--printMoveTree=<Int>: Print the tree of all possible moves in the configured notation, each annotated by a fitness-evaluation for the resulting position, truncated to the specified number of plies; see section-5 of the man-pages for details.

Generic Program-information

-v, --version: Outputs version-information & then exits.
-?, --help: Displays a usage-message & then exits.

Runtime

Command-line Interpreter

This application understands a simple command-language, consisting of:

a move specified in the configured notation.
a ’?’, to generate a usage-message.
a case-insensitive command (which one may abbreviate), prefixed by a ’:’. The available commands are:

Command Arguments Description

======= ========= ===========

:hint

:print object

:quit

:resign

:restart

:rollBack [Int]

:save

:set searchDepth Int

:swap

Hardware-requirements.

This application benefits from the availability of multiple cores (see the "+RTS -N" option).
If one references large PGN-databases from the configuration (see "pgnOptions" in section-5 of the man-pages), or configures a large "searchDepth" (see "searchOptions" in section-5 of the man-pages), then correspondingly large amounts of RAM will be required.

Exit-status

0 on success, & >0 if an error occurs.

Examples

bishbosh --verbosity=Verbose -i ~/.cabal/share/*/bishbosh-*/config/Raw/bishbosh_white.xml

The application has been instructed to provide a relatively large amount of feedback.
One of the packaged configuration-files has been referenced, which automates White’s moves & specifies a raw ASCII interface; on MS-Windows you’ll need to issue this from a terminal-emulator which understands https://en.wikipedia.org/wiki/ANSI_escape_code . This path includes both an architecture-specific & a version-specific directory, which are represented as globs & expanded by bash; on MS-Windows you may need to be more explicit.
CAVEAT: assumes that the executable exists on $PATH, otherwise an explicit path will be required.

bishbosh --verbosity=Deafening -i ~/.cabal/share/*/bishbosh-*/config/Raw/bishbosh_black.xml
+RTS -N -H100M -RTS

The application has been instructed to provide maximal feedback.
One of the packaged configuration-files has been referenced, which automates Black’s moves & also references some packaged PGN-databases.
For performance, the run-time system has been explicitly instructed to fully utilise the available CPU-cores, & to set a large minimum size for the heap to satisfy its craving for RAM; actually similar defaults have been predefined.

xboard -fcp "bishbosh -i $HOME/.cabal/share/x86_64-linux-ghc-8.0.2/bishbosh-0.0.0.2/config/CECP/bishbosh_black.xml"

Instruct the xboard GUI to use bishbosh as its first engine; winboard is the equivalent GUI for MS-Windows.
N.B.: bishbosh & its arguments are delimited by double-quotes, so that they are interpreted by xboard as a single argument.
CAVEAT: the hard-coded architecture-specific & version-specific directories may need to be edited.

Files

File-name	Contents
=========	========
bishbosh.svg	A module-dependency graph for this application.
*config/{CECP,Raw}/.xml**	Sample configuration-files.
man/man5/bishbosh.5	Section-5 of the man-pages for this product, describing the configuration-file format.
*pgn/.pgn**	Sample PGN-databases; https://en.wikipedia.org/wiki/Portable_Game_Notation .
*~/.bishbosh/.txt**	Persisted games, stored in a user-specific directory.
https://www.gnu.org/software/xboard	A GUI for chess-engines.

Author

Written by Dr. Alistair Ward.

Bugs

The implementation of commands is synchronous.
The implementation of CECP is minimal.
Performance is uncompetitive with imperative implementations of similar algorithms.

Reporting Bugs

Report bugs to "bishbosh@functionalley.com".

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/ .

Name

Synopsis