similarpositionfilter looks for positions that are "similar" to the current position within some other pgn file.
The basic syntax of the
similarposition filter is:
where filename is the name of a pgn file. The filename must be a quoted string literal. For example,
The pgn file named by filename is called the submissions database or just the submissions. By contrast, the file that is the input to the
cql program itself (specified in the
input parameter in the CQL header) is called the repository.
similarposition filter supports optional parameters
notransform, which are discussed below.
similarposition "x.pgn"is true if there is some position X in the mainline of a game in the file
x.pgnthat is similar to the current position.
Similar positionsTwo positions are similar if they have the same side to move and either
- Both board positions are pawnless, and one can be reached from the other by rotations and reflections of the board; or
- Both board positions have pawns, and one can be reached from the other by an optional reflection about the vertical bisector of the board followed by a horizontal shift (which can be the identity).
We say a position can be reached by a transform applied to some other position if the positions are identical after the application of the transform. Note that positions with identical board positions and the same side to move are always similar. En passant and castling privileges are not considered in comparing positions.
notransformparameter is between the
similarpositionand the filename, then similarity of positions considers only identical board positions:
similarposition notransform "y.pgn"
sortBy default, the output games (that is, the matching games in the repository) are sorted in increasing order by the game number within the submissions file that contained a position that matched some position in the game in the repository. To disable this sorting, use the
similarposition nosort "z.pgn"
-similarpositioncommandline option should be followed by the unquoted name of a submissions file. This prefaces (as if by the
-cqlcommand line option) the body of the CQL file with the corresponding
cql -similarposition "foo.pgn" -input hhdbvi.pgn
-input hhdbvi.pgn can be replaced by
-vi if the file
hhdbvi.pgn is in the current directory).
notransform can also be used on the command line:
cql -similarposition nosort "foo.pgn" -input hhdbvi.pgn
similarposition filter is intended to assist endgame composition tournament judges in determining predecessors of a particular file of studies. It is only a starting point: more precise checking requires a custom CQL filter for each submission. The
similarposition filter will frequently miss significant predecessors or signal games that are not actually predecessors; thus, the output must be manually checked.
similarposition can also be used to determine if a position from a file of full games appeared in the Heijden database of studies. There, one might want to require at least pieces in the positions in the positions considered so as to avoid trivial matches:
◭≥5 similarposition "master-level-games.pgn"The
◭≥5filter is evaluated at the current position (of the Heijden database). Positions with fewer than 5 pieces will fail to match at that point, so that
similarpositionwill not be invoked on such positions.