The :relation keyword

The :relation keyword occurs in a position list. It takes one parameter, a relation specifier.

A relation specifier is a list denoting parameters to the relation keyword.

For example, the following position list,

 (position
   :relation (:missingpiececount A 1 100))

searches for games in which two positions are the same except that the later one is missing one or more white pieces.

The operation of the :relation tag is as follows.

A position list with a relation tag matches a position P1 if and only if at some later point in the current game there is a position P2 such that the relationship between P1 and P2 matches the parameters defined in the relation specifier.

The meaning of each keyword inside a relation specifier is as follows.

:pattern

The :pattern keyword signifies that all piece designators that occur at the top level of the position list that encloses the current relation list define the allowable squares.

Only allowable squares are considered in the comparisons. By default all squares are allowable.

:originaldifferentcount

This parameter takes a range specifier. It matches if the number of allowable squares that are different between P1 and P2 lies within the range specifier.

:originalsamecount

This parameter takes a range specifier. It matches if the number of nonempty allowable squares that are the same between P1 and P2 lies within the range specifier.

:shift

Allow P2 to be shifted before the comparison. However, in no case is P2 allowed to have a different piece on a square than P1 after the transform is applied.

:flip

Allow P2 to be flipped before the comparison. However, in no case is P2 allowed to have a different piece on a square than P1 after the transform is applied.

:samesidetomove

P2 must have the same side to move as P1. This is the default.

:changesidetomove

P2 must have a different side to move as does P1.

:ignoresidetomove

Side to move information is ignored.

:missingpiececount

This keyword takes the same parameters as does the :piececount keyword in a position list: a pieced designator followed by a range.

A missing piece is a piece that occurs in P1 on a square that is empty on P2. P2 matches if the number of these missing pieces lies within the range specifier.

Unlike the case of the :piececount keyowrd, at most one :missingpiececount specifier can occur.

No shift or flip transformation specifiers in the containing position list affect the piece designator in this keyword.

The default piece designator for :missingpiececount is U and the default range is 0 .

That is, by default there can be no missing pieces.

:newpiececount

This keyword takes the same parameters as does the :piececount keyword in a position list: a pieced designator followed by a range.

A new piece is a piece that occurs in P2 on a square that is empty on P1. P2 matches if the number of these new pieces lies within the range specifier.

Unlike the case of the :piececount keyword, at most one :newpiececount specifier can occur.

No shift or flip transformation specifiers in the containing position list affect the piece designator in this keyword.

The default piece designator for :newpiececount is U and the default range is 0 .

That is, by default there can be no new pieces.

:variations

Search for P2 within variations and in the main line. By default, P2 must be in the main line.

:variationsonly

Search for P2 only within variations.

Relation list examples

To search games in which the same position occurs with white and black to move - for example, this is useful in looking for mutual zugzwangs, use

(position :relation (:changesidetomove))

The following position list searches for studies in which the configuration

Ke6 be7 be4 nd5

occurs shifted or flipped, but in which no pieces from the original position are on the same square as the pattern:

  (position
  Ke6 be7 be4 nd5
  :shift
  :flip
   :markall
  :relation (:pattern
	     :shift
	     :flip
	     :originalsamecount 0
	     :samesidetomove
	     :variations
	     )
  )

If one modified the :originalsamecount parameter to, say, 0 3 from its current value of 1, then the pattern in the second position would be allowed to overlap with at most three squares of the pattern in the original position.