similarposition

The similarposition filter looks for positions that are "similar" to the current position within some other pgn file.

The basic syntax of the similarposition filter is:

    similarposition filename

where filename is the name of a pgn file. The filename must be a quoted string literal. For example,

  similarposition "x.pgn"

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.

The similarposition filter supports optional parameters nosort and notransform, which are discussed below.

Semantics

The filter

  similarposition "x.pgn"

is true if there is some position X in the mainline of a game in the file x.pgn that is similar to the current position.

Similar positions

Two positions are similar if they have the same side to move and either

1. Both board positions are pawnless, and one can be reached from the other by rotations and reflections of the board; or
2. 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.

notransform

If the notransform parameter is between the similarposition and the filename, then similarity of positions considers only identical board positions:

      similarposition notransform "y.pgn"

sort

By 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 nosort parameter:

      similarposition nosort "z.pgn"

-similarposition

The -similarposition commandline option should be followed by the unquoted name of a submissions file. This prefaces (as if by the -cql command line option) the body of the CQL file with the corresponding similarposition filter:

      cql -similarposition foo.pgn -input hhdbvi.pgn

(recall that -input hhdbvi.pgn can be replaced by -vi if the file hhdbvi.pgn is in the current directory).

The parameters nosort and notransform can also be used on the command line:

      cql -similarposition nosort foo.pgn -input hhdbvi.pgn

Using similarposition

The 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.

The 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 ◭≥5 filter 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 similarposition will not be invoked on such positions.