.TH bishbosh 1 .SH NAME \fBbishbosh\fR - Plays Chess .SH SYNOPSIS \fBbishbosh\fR [\fIOPTIONS\fR] .SH DESCRIPTION .PP 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 (\fBxboard\fR). .PP It permits: .IP \(bu Castling .IP \(bu En-passant .IP \(bu Resignation .IP \(bu Draw by \fIStale-mate\fR, the \fISeventy-five move rule\fR, \fIFive-fold Repetition\fR, or \fIInsufficient Material\fR. .PP It features: .IP \(bu Unlimited roll-back of moves. .IP \(bu Configurable <\fBhttps://en.wikipedia.org/wiki/Chess_notation\fR>. .IP \(bu The ability to read (optionally compressed) PGN-databases of standard openings & archived games, in which it can match both transpositions (<\fBhttps://www.chessprogramming.org/Transposition\fR>)s & colour-flipped (<\fBhttps://www.chessprogramming.org/Color_Flipping\fR>) positions. .IP \(bu Automation of the moves for either, neither, or both players. Both the evaluation of moves & the search for the optimum, are highly configurable; see \fBsection-5\fR of the man-pages. .IP \(bu Optional hints for manual players. .IP \(bu <\fBhttps://www.chessprogramming.org/Pondering\fR>. .SS Implementation 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 "\fB--verbosity=Deafening\fR"). 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. .PP 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 <\fBhttps://www.chessprogramming.org/MVV-LVA\fR> or <\fBhttps://www.chessprogramming.org/Static_Exchange_Evaluation\fR>. On each move, this tree's non-capture moves are dynamically sorted using the <\fBhttps://www.chessprogramming.org/Killer_Heuristic\fR> & the <\fBhttps://www.chessprogramming.org/History_Heuristic\fR>. .br This tree is then searched using a <\fBhttps://www.chessprogramming.org/Negamax\fR> algorithm with <\fBhttps://www.chessprogramming.org/Alpha-Beta\fR> pruning, over a constant configurable number of plies, to find the optimal move according to the weighted-mean of various criteria described in \fBsection-5\fR of the man-pages. .br Shortcuts in the search for the optimal move are taken on encountering either <\fBhttps://www.chessprogramming.org/Repetitions\fR> in the move-sequence, or transpositions (<\fBhttps://www.chessprogramming.org/Transposition\fR>) of sibling games. .SH OPTIONS .SS "Input" .TP \fB-i\fR \fIFile-path\fR, \fB--inputConfigFilePath=\fR\fIFile-path\fR; there is no default. Read the mandatory configuration from the specified XML-file, .SS "Execution" .TP \fB-r\fR[\fIInt\fR], \fB--randomSeed\fR[\fB=\fR\fIInt\fR] Optionally takes an argument with which to seed the single pseudo-random number-generator used for all random operations. See "\fBrandomSeed\fR" in \fBsection-5\fR of the man-pages. .br 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, "\fB0\fR" will be inferred. .br N.B.: this application only makes significant use of the random-generator when selecting a move from any configured PGN-databases (see "\fBpgnOptions\fR" in \fBsection-5\fR of the man-pages); move-selection is otherwise deterministic. .SS "Output" .TP \fB--verbosity=\fR(\fBSilent\fR|\fBNormal\fR|\fBVerbose\fR|\fBDeafening\fR), defaulting to "\fBNormal\fR". Defines the quantity of ancillary output required. See "\fBverbosity\fR" in \fBsection-5\fR of the man-pages. .TP \fB--printMoveTree\fR=\fIInt\fR 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 \fBsection-5\fR of the man-pages for details. .TP .B --checkPickler Validates the specification of the internal XML-pickler & then exits. .TP \fB--generateDTD\fR[\fB=\fR\fIInt\fR] Generates an approximate DTD from the internal XML-pickler & then exits. The optional integer defines the \fBHXT\fR trace-level, valid values for which exist in the closed interval \fB[0 .. 4]\fR. .TP .B --formatPieceSquareTableForGNUPlot Prints the piece-square table in a format suitable for \fBGNUPlot\fR & then exits. .SS "Generic Program-information" .TP \fB-v\fR, \fB--version\fR Outputs version-information & then exits. .TP \fB-?\fR, \fB--help\fR Displays a usage-message & then exits. .SH RUNTIME .SS Command-line Interpreter This application understands a simple command-language, consisting of: .IP \(bu a move specified in the configured notation. .IP \(bu a '\fB?\fR', to generate a usage-message. .IP \(bu a case-insensitive command (which one may abbreviate), prefixed by a '\fB:\fR'. The available commands are: .TS lb lb lb l l l lb li . Command Arguments Description ======= ========= =========== :hint Request a move-suggestion. :print object Print the specified static data; either "\fBconfiguration\fR" or "\fBhelp\fR". :quit Exit the application. The current game-state will be saved, provided \fBpersistence\fR (see "\fBpgnOptions\fR" in \fBsection-5\fR of the man-pages) hasn't been disabled. :report object Report the specified dynamic data, one of; "\fBavailableMoves\fR", "\fBboard\fR", "\fBEPD\fR", "\fBFEN\fR", "\fBgame\fR", "\fBmaxPositionInstances\fR", "\fBmoves\fR", "\fBPGN\fR", "\fBreversiblePlyCount\fR". :resign Resign the game. :restart Start a new game. :rollBack [Int] Roll-back the optionally specified number of plies (half moves), defaulting to "\fB2\fR" when there's one manual player & "\fB1\fR" when both players are manual. :save Save the current game-state in "\fB~/.bishbosh\fR"; this is automatic unless explicitly un-configured. :set object Specify "\fBEPD\fR " to define the position using \fBExtended Position Description\fR or "\fBsearchDepth\fR " to define the number of plies to search. :swap Swap sides. If the moves of one side were automated, then this will cause automation of the moves of the other side. .TE .SS Hardware-requirements. .IP \(bu This application benefits from the availability of multiple cores (see the "\fB+RTS -N\fR" option). .IP \(bu If one references large PGN-databases from the configuration (see "\fBpgnOptions\fR" in \fBsection-5\fR of the man-pages), or configures a large "\fBsearchDepth\fR" (see "\fBsearchOptions\fR" in \fBsection-5\fR of the man-pages), then correspondingly large amounts of RAM will be required. .SH EXIT-STATUS \fB0\fR on success, & >\fB0\fR if an error occurs. .SH EXAMPLES .nf .B bishbosh --verbosity=Verbose -i ~/.cabal/share/*/bishbosh-*/config/Raw/bishbosh_white.xml .fi .IP \(bu The application has been instructed to provide a relatively large amount of feedback. .IP \(bu One of the packaged configuration-files has been referenced, which automates White's moves & specifies a raw ASCII interface; on \fBMS-Windows\fR you'll need to issue this from a terminal-emulator which understands <\fBhttps://en.wikipedia.org/wiki/ANSI_escape_code\fR>. This path includes both an architecture-specific & a version-specific directory, which are represented as globs & expanded by \fBbash\fR; on \fBMS-Windows\fR you may need to be more explicit. .IP \(bu CAVEAT: assumes that the executable exists on \fB$PATH\fR, otherwise an explicit path will be required. .PP .nf .B bishbosh --verbosity=Deafening -i ~/.cabal/share/*/bishbosh-*/config/Raw/bishbosh_black.xml +RTS -N -H100M -RTS .fi .IP \(bu The application has been instructed to provide maximal feedback. .IP \(bu One of the packaged configuration-files has been referenced, which automates Black's moves & also references some packaged PGN-databases. .IP \(bu 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. .PP .nf \fBxboard -fcp "bishbosh -i $HOME/.cabal/share/x86_64-linux-ghc-8.10.1/bishbosh-0.1.0.0/config/CECP/bishbosh_black.xml +RTS -N"\fR .fi .IP \(bu Instruct the \fBxboard\fR GUI (which must be independently installed) to use \fBbishbosh\fR as its first engine; \fBwinboard\fR is the equivalent GUI for \fBMS-Windows\fR. .IP \(bu N.B.: \fBbishbosh\fR & its arguments are delimited by double-quotes, so that they are interpreted by \fBxboard\fR as a single argument. .IP \(bu CAVEAT: the hard-coded architecture-specific & version-specific directories may need to be edited. .IP \(bu \fBmake xboard\fR encapsulates this requirement. .SH FILES .TS lb lb l l lb l . File-name Contents ========= ======== config/{CECP,Raw}/*.xml Sample configuration-files. makefile Facilitates common tasks. man/man5/bishbosh.5 \fBSection-5\fR of the man-pages for this product, describing the configuration-file format. man/man1/duel.1 The man-page for an application to facilitate a battle between instances of \fBbishbosh\fR. pgn/*.pgn Sample PGN-databases; <\fBhttps://en.wikipedia.org/wiki/Portable_Game_Notation\fR>. ~/.bishbosh/*.txt Persisted games, stored in a user-specific directory & config-specific file. A GUI for chess-engines. .TE .SH AUTHOR Written by Dr. Alistair Ward. .SH BUGS .IP \(bu The implementation of commands is synchronous. .IP \(bu The implementation of CECP is minimal. .IP \(bu Performance is uncompetitive with imperative implementations of similar algorithms. .SS "REPORTING BUGS" Report bugs to "\fBbishbosh@functionalley.com\fR". .SH COPYRIGHT Copyright \(co 2018 Dr. Alistair Ward .PP 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. .PP 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. .PP You should have received a copy of the GNU General Public License along with this program. If not, see <\fBhttps://www.gnu.org/licenses/\fR>. .SH "SEE ALSO" .IP \(bu Home-page: <\fBhttps://functionalley.com/BishBosh/bishbosh.html\fR>. .IP \(bu <\fBhttps://hackage.haskell.org/package/bishbosh\fR>. .IP \(bu <\fBhttps://github.com/functionalley/BishBosh\fR>. .IP \(bu Source-documentation is generated by "\fBHaddock\fR", & is available in the distribution. .IP \(bu <\fBhttps://www.haskell.org/haddock/\fR>.