.TH bishbosh 5 .SH DESCRIPTION This man-page describes the configuration of the application; its invocation is described in \fBsection-1\fR of the man-pages. .SH CONFIGURATION Configuration is read from an XML-file referenced from the command-line. The grammar of this file is defined in "\fBconfig/bishbosh.dtd\fR" or more precisely using \fBRELAX NG\fR in "\fBconfig/bishbosh.rng\fR", whereas the semantics of the more important fields is described below. .SS Options .IP \(bu \fBmaximumPlies\fR \fIInt\fR: the optional maximum number of plies (half moves) before the game is terminated. .IP \(bu \fBrandomSeed\fR \fIInt\fR: optionally seed the pseudo-random number-generator to produce a repeatable game. See "\fB--randomSeed\fR" in \fBsection-1\fR of the man-pages. .SS Evaluation-options Each field governs automatic move-evaluation: .IP \(bu \fBincrementalEvaluation\fR \fIBool\fR, defaulting to "\fBTrue\fR". Whether to incrementally generate position-hashes & evaluate the piece-square value, from the previous values; otherwise these quantities are evaluated from scratch. This option improves space/time performance marginally, but doesn't affect the result. .IP \(bu \fBrankValues\fR: defines the value within the closed unit-interval "\fB[0, 1]\fR", of each type of piece, defaulting (ref. <\fBhttps://www.chessprogramming.org/Point_Value\fR>) to: .TS lb lb l l lb l . Piece Value ===== ===== Pawn 0.1 Rook 0.5 Knight 0.3 Bishop 0.3 Queen 0.9 King \fIMoot, since it can't be taken.\fR .TE .IP \(bu \fBcriteriaWeights\fR: the weights in the closed unit-interval "\fB[0,1]\fR", each associated with a criterion used to evaluate a move; at the lower bound, the corresponding criterion is not even evaluated. The criteria to which these weights correspond, are: .TS lb lb lb lb l l l l lb l lb l . Criterion Metric Ref Notes ========= ====== === ===== material Quantifies the value of the pieces remaining per side. This is dependent on the value of each type of piece; see "\fBrankValues\fR". mobility The difference between the number of moves available per side. Actually the reciprocal is measured, to emphasis the reduction caused by checking one's opponent. pieceSquareValue Quantifies the position held by the pieces per side. This metric includes aspects of both "\fBmaterial\fR" & "\fBmobility\fR". The value can be made linearly dependent on progress through the game. castlingPotential Whether each player has been permanently prevented from castling. Reflects the disadvantage of moving one's King, thus preventing subsequent castling. defence The difference between the number of pieces defending one's own, per side. There's neither any penalty for gaps in this defence nor account made of the value of the defended piece; it's just the total number of defenders. doubledPawns The difference between the total number of doubled Pawns per side. Reflects the reduced mobility of such Pawns. isolatedPawns The difference between the total number of isolated Pawns per side. Reflects the lack of defence from adjacent Pawns. passedPawns The difference between the total number of passed Pawns per side. Reflects improved promotion-prospects. .TE .IP Other criteria could be measured, but orthogonality is problematic. One could reasonably argue that most of these criteria are ultimately reflected in "\fBmaterial\fR", but often they quantify some strategic advantage which manifests further into the future than it is feasible to predict the likely exchange of pieces. .br N.B.: "\fBdefence\fR" & the three Pawn-related criteria typically can't justify their existence; even if one ignores the time required to calculate them, their value is dubious. This is the nub of the esoteric choice of whether to accurately quantify each board, or to accept a vague quantification in order to explore deeper in the same time. .IP \(bu \fBpieceSquareTables\fR: defines the value within the closed unit-interval "\fB[0, 1]\fR", of each type of piece occupying every square. .br .TS lb lb lb lb l l l l lb li lb l . Attribute Type Default Meaning ========= ==== ======= ======= normalise Bool False configured values may be automatically normalised into the closed unit-interval. CAVEAT: this option restricts one to validation of the XML-configuration by DTD, since the RelaxNG-specification checks that the specified values are already in the closed unit-interval (use \fBrunhaskell Setup configure -f -hxtrelaxng\fR or \fBstack install --flag='bishbosh:-hxtrelaxng'\fR). CAVEAT: normalisation is performed independently on the tables used to represent the opening-game & end-game, which may result in the application of a different transformation to each table. reflectOnY Bool True values are optionally configured for just the left-hand side of the board, & are then used to generate by reflection, the right-hand side. .TE .IP N.B.: the values defined for a Pawn occupying any square in the first or last rank, are irrelevant. .br Values are defined for just the White pieces, which are then used to generate by reflection, those for the Black pieces. .br For each type of piece, the values are defined in a SAN-coordinate-order list, rastering over the board from left to right, bottom to top; "\fIa1 b1 c1 d1 a2 b2 c3 ... c7 d8\fR". .br An alternative table may be provided for use during the end-game, to account for the different criteria relevant to that phase of the game. Under such circumstances, the two piece-square tables for that type of piece will be interpolated between, according to the number of pieces remaining (which is used as a proxy for progress towards the end-game). The packaged configuration-files define modified tables for both Pawn & King. .SS Search-options .IP \(bu \fBsortOnStandardOpeningMoveFrequency\fR: whether to sort the moves available from any position, using the frequency with which they occur in referenced standard openings. .IP \(bu \fBcaptureMoveSortAlgorithm\fR: the optional algorithm by which to partition & sort capture-moves for preferential evaluation when searching for the optimum amongst available moves. If unspecified, the order of capture-moves will remain unaltered both wrt each other & wrt other moves. .br .TS lb lb l l lb l . Value Meaning ===== ======= MVVLVA moves are advanced depending on the value of rank of the piece they capture, but where this is equal, those which achieve this using a less valuable piece are preferred; <\fBhttps://www.chessprogramming.org/MVV-LVA\fR>. This is highly effective. SEE moves are advanced depending on the net material gain resulting from any battle at the destination; <\fBhttps://www.chessprogramming.org/Static_Exchange_Evaluation\fR>. This is not currently competitive. .TE .IP Neither of these sort-algorithms affects the relative order of non-capture moves; cf. \fBsortOnStandardOpeningMoveFrequency\fR. This is performed after \fBsortOnStandardOpeningMoveFrequency\fR. .IP \(bu \fBminimumHammingDistance\fR \fIInt\fR: the optional positive lower bound on the Hamming-distance between any of the random numbers used to generate Zobrist hashes from positions; <\fBhttps://www.chessprogramming.org/Zobrist_Hashing\fR>. .br CAVEAT: linear independence of the bit-vectors is a better measure than Hamming-distance, of the quality of the selected random numbers. .IP \(bu \fBretireKillerMovesAfter\fR \fIInt\fR: the optional non-negative number of full moves (one by each player) after which killer-moves are retired; <\fBhttps://www.chessprogramming.org/Killer_Move\fR>. If unspecified, killer-moves won't even be recorded. .br N.B.: this is highly effective up to about \fB3\fR, beyond which returns diminish. .br Killer-moves are used to dynamically sort the moves available from a position, based on whether similar moves previously triggered beta-cutoff; <\fBhttps://www.chessprogramming.org/Beta-Cutoff\fR>. .IP \(bu \fBtrapRepeatedPositions\fR: whether to short-circuit the fitness-evaluation of \fIposition\fRs which have been visited before in the current game; <\fBhttps://www.chessprogramming.org/Repetitions\fR>. These situations result from loops of consecutive reversible moves, in the move-tree which defines the game of chess. The fitness of such \fIposition\fRs can be derived by induction, since were one to search from this \fIposition\fR, one would ultimately arrive back another time, so the fitness of this future \fIposition\fR equals the current fitness. .br N.B.: this doesn't typically improve performance in either space or time. .IP \(bu \fBusePondering\fR: whether an automated player should plan their next move, based on a prediction of the opponent's response, & thus make use their opponent's thinking-time; <\fBhttps://www.chessprogramming.org/Pondering\fR>. .IP \(bu \fBtranspositions\fR: these can be used to reorder the evaluation of moves, based on the results previously found for identical \fIposition\fRs in sibling games reached by an alternative sequence of arbitrary moves; <\fBhttps://www.chessprogramming.org/Transposition\fR>. .TS lb lb lb l l l lb li l . Attribute Type Meaning ========= ==== ======= retireTranspositionsAfter Int the non-negative number of full moves (one by each player) after which transpositions are retired. N.B.: this is highly effective at about \fB1\fR, beyond which returns diminish. minimumTranspositionSearchDepth Int the search-depth beneath which transpositions are not recorded. When the remaining search-depth is low, the potential gain from finding a recorded transposition of the current position, doesn't justify the effort. N.B.: this is most effective at about \fB2\fR. .TE .IP \(bu .B standardOpeningOptions .TS lb lb lb lb l l l l lb li lb l . Attribute Type Default Meaning ========= ==== ======= ======= maximumPliesSinceMatch Int the maximum number of plies since the last match with a prerecorded game, before abandoning further attempts; defaulting to \fIunlimited\fR. preferVictories Bool True whether from all matching positions extracted from the PGN-database, to prefer moves which result in a greater probability of victory, for the player who has the next move. tryToMatchMoves Bool True whether to attempt to exactly match the moves already made, with a standard opening; i.e. without matching transpositions. tryToMatchViaJoiningMove Bool True whether to attempt to join the current position (irrespective of the means by which it was achieved) to a standard opening that's only one move away. tryToMatchColourFlippedPosition Bool True whether to attempt to match a colour-flipped (<\fBhttps://www.chessprogramming.org/Color_Flipping\fR>) version of the current position with a standard opening. .TE .IP \(bu \fBsearchDepth\fR \fIInt\fR, defaulting to "\fB4\fR" (minimum "\fB1\fR"): the number of plies (half moves) to search ahead, when selecting the next move. This is defined for each of zero, one or two logical colours, corresponding to the players; it is the absence of any specification, from which the application infers manual move-selection. This value can be changed dynamically, see "\fBset searchDepth\fR" in \fBsection-1\fR of the man-pages. .br CAVEAT: the space & time complexity of the application are exponentially related to this quantity. .SS IO-options The application defines a set of "\fBioOptions\fR", in which one can define: .IP \(bu \fBmaximumPGNNames\fR \fIInt\fR: the optional maximum number of names, with which to annotate moves matching games from the configured PGN-databases. .IP \(bu \fBpgnOptions\fR: these options allow one to reference PGN-databases, which the application can leverage during move-selection; <\fBhttps://en.wikipedia.org/wiki/Portable_Game_Notation\fR>. .TS lb lb lb lb l l l l lb l lb l . Attribute Type Default Meaning ========= ==== ======= ======= databaseFilePath \fIFile-path\fR The path in the local file-system, to a PGN-database. decompressor \fIString\fR The optional name of an executable (available in the OS) used to decompress (to \fIstdout\fR) the specified file; the file's suffix isn't considered significant. minimumPlies \fIInt\fR 1 The minimum number of half moves, for an archived game to be considered valuable. maximumGames \fIInt\fR The optional maximum number of games to read from the database. isStrictlySequential (\fBTrue\fR|\fBFalse\fR) True Whether the recorded move-numbers are accurate. validateMoves (\fBTrue\fR|\fBFalse\fR) False Whether to validate all the moves. In the absence of validation, PGN-databases can be read faster, but the consequence of reading invalid moves is unpredictable. This option is required to read games which continued after a draw can be inferred. textEncoding (\fBISO8859-1(checked)\fR|\fButf8\fR|\fButf16\fR|\fButf32\fR) utf8 Defines the conversion-scheme between byte-sequences & Unicode characters. identificationTags String The PGN-field(s) from which to construct a composite identifier for a game. .TE .IP \(bu \fBpersistence\fR: these options govern how the application persists its state, so that a game may span multiple sessions. .TS lb lb lb lb l l l l lb li lb l . Attribute Type Default Meaning ========= ==== ======= ======= filePath File-path The local file in which game-state will be persisted. automatic Bool True Whether the game-state is automatically saved. .TE .P "\fBioOptions\fR" has a sub-section "\fBuiOptions\fR", which defines the user-interface. .IP \(bu \fBmoveNotation\fR (\fBICCFNumeric\fR|\fBPureCoordinate\fR|\fBSmith\fR), defaulting to "\fBSmith\fR"; <\fBhttps://en.wikipedia.org/wiki/Chess_notation\fR>. The expected syntax used to define a move. This application also understands \fBStandard Algebraic\fR notation, but it is only used to read the PGN-databases used to define standard openings. .IP \(bu \fBprintMoveTree\fR \fIInt\fR. Print the tree of all possible moves in the configured notation, truncated to the specified depth. The forest of moves available at each node, is sequentially sorted according to; \fBsortOnStandardOpeningMoveFrequency\fR, \fBcaptureMoveSortAlgorithm\fR; since the sort-algorithm is stable, the relative order of moves which compare equal, remains unchanged. The fitness of each move, from the perspective of the player of the move, is also printed to the configured number of decimal places; see \fBnDecimalDigits\fR. See "\fB--printMoveTree\fR" in \fBsection-1\fR of the man-pages. .IP \(bu \fBnDecimalDigits\fR \fIInt\fR, defaulting to "\fB3\fR". Defines the precision with which fractional ancillary data is displayed. .IP \(bu \fBverbosity\fR (\fBSilent\fR|\fBNormal\fR|\fBVerbose\fR|\fBDeafening\fR), defaulting to "\fBNormal\fR": defines the quantity of ancillary output required. See "\fB--verbosity\fR" in \fBsection-1\fR on the man-pages. .IP \(bu \fBboardMagnification\fR: the size-multiplier used when rendering the board. .TS lb lb lb l l l lb li l . Attribute Type Meaning ========= ==== ======= nColumns Int The horizontal magnification of the board-image. .TE .IP \(bu \fBcolourScheme\fR: defines the physical colour of each component of the display. .TS lb lb l l lb l . Attribute Options ========= ======= darkPieceColour (\fBBlack\fR|\fBRed\fR|\fBGreen\fR|\fBBlue\fR|\fBMagenta\fR|\fBCyan\fR) lightPieceColour (\fBRed\fR|\fBGreen\fR|\fBYellow\fR|\fBMagenta\fR|\fBCyan\fR|\fBWhite\fR) darkSquareColour (\fBBlack\fR|\fBRed\fR|\fBGreen\fR|\fBBlue\fR|\fBMagenta\fR|\fBCyan\fR) lightSquareColour (\fBRed\fR|\fBGreen\fR|\fBYellow\fR|\fBMagenta\fR|\fBCyan\fR|\fBWhite\fR) .TE .IP \(bu \fBdepictFigurine\fR: specifies whether to depict pieces as Unicode figurines, or merely ASCII letters. This will require a terminal configured to render Unicode. .SH FILES .TS lb lb l l lb l . File-name Contents ========= ======== config/bishbosh.dtd A basic formal description of the XML-format for the configuration-file. Also defines \fBExternal Entities\fR referencing the XML files described below. config/bishbosh.rng A more precise, but slower, \fBRELAX NG\fR definition of the XML-format for the configuration-file. config/*.xml These files are defined as XML \fBExternal Entities\fR (<\fBhttps://www.w3resource.com/xml/external-entities.php\fR>) in the DTD, thus permitting them to be referenced in the configuration specified on the command. config/{CECP,Raw}/*.xml Sample configuration-files. man/man1/bishbosh.1 Section-1 of the man-pages for this product, describing the command-line. pgn/*.pgn Standard openings & archived games, described in <\fBhttps://en.wikipedia.org/wiki/Portable_Game_Notation\fR>. .TE .SH AUTHOR Written by Dr. Alistair Ward. .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>.