relation square parameters

A square parameter is a type of relation parameter that directly compares the pieces on the squares in two positions. Which squares are compared, and the criteria for a match, is specified by different parts of the square parameter.

To recap: When a relation filter is evaluated at a particular position, that position is called the source or source position. Every other position in the game successively becomes the target or target position. For the relation filter to match at a target, each of its relation parameters must also match that target.

A square parameter compares source and target positions, counts the matches and mismatches, and checks that these counts lie within specified ranges.

The syntax of a square parameter is 

squareparameter:=
  (
    sourcesquares set1
    targetsquares set2
    match range1
    mismatch range2
  )
Here, set1 and set2 are each set filters. Likewise, range1 and range2 are ranges.

Each of the lines above beginning with sourcesquares, targetsquares, match, and mismatch are optional. When they are missing, defaults are provide. Their defaults are as follows:

  • If sourcesquares set1 is missing, it is taken to be sourcesquares any
  • If targetsquares set2 is missing, it is taken to be targetsquares any
  • If match range1 is missing it is taken to be match 0 64.
  • If mismatch range2 is missing it is taken to be mismatch 0 64
In other words, if you did not specify part of a square parameter, CQL implicitly will provide the missing parts from the following table:

Missing part default value
sourcesquares sourcesquares any
targetsquares targetsquares any
match match 0 64
mismatch mismatch 0 64

To determine whether a target position matches its source position according to a square parameter, CQL does the following (assuming the square parameter is as above):

  1. Evaluate the sourcesquares set filter set1 at the source position to get a set of squares called the sourcesquares square set.

    Note that the current position is actually equal to target when the square parameter is assessed. Therefore, the sourcesquares square set might be completely different from the set of squares associated with the set filter set1 at the current position.

  2. Evaluate the targetsquares set filter set2 at the target position (which is the current position) to get a set of squares called the targetsquares square set
  3. Take the intersection of the sourcesquares square set and the targetsquares square set to get a new set of squares called the comparison set
  4. For each square in the comparison set, compare the contents of that square in the source position and in the target position. If the contents are equal, then they match. Otherwise, they mismatch.
  5. Compute the total number of matches and of mismatches of squares in the comparison set. Thus, the sum of the number of mismatches and the number matches must equal the number of squares in the comparison set.
  6. Check that the numbers of matches lies within the match range range1. If it does not, the square parameter does not match the target.
  7. Check that the number of mismatches lies within the mismatch range range2. If it does not, the square parameter does not match the target.
  8. If the numbers of matches and mismatches each lie with their corresponding ranges, the square parameter matches the target.

Examples of square parameters

Using square parameters can sometimes be confusing because the set filters set1 and set2 are evaluated at different positions, namely the source and the target. Then these have to be intersected, which adds another layer of complexity to the process. This section goes over some examples that will help describe some techniques for using square parameters.

A single square parameter using a square variable

Below is the relation filter from the knight-pawn-fork-relation.cql: 
relation
 wtm
 variation
 A on $forkingsquare
 (sourcesquares not $forkingsquare mismatch 0)
This sample is part of a CQL file that looks for games in which there is a mainline source where White moves a knight to a square to fork the black King and a black Pawn on the second rank. In the variation, an identical position occurs except that now a white piece is on the knight's destination. The knight's destination square here had been bound to a square named $forkingsquare .

The relation filter looks for targets that:

  1. have white to move and are in a variation (the wtm variation are the two target filters
  2. have a white piece on the square $forkingsquare (a square previously assigned to the Knight's destination
  3. the contents of every square in the source position is exactly the same as the corresponding square's contents in the target position, except for the $forkingsquare. Here, set1 the set filter for the sourcesquares, is not $forkingsquare which is all the squares except for that square.

square parameters that look for underpromotions

Another example comes from the CQL file underpromotion-relation.cql. This example looks for studies that arise from a White underpromotion. It does this by looking for positions that are identical except that a white piece is some [RNBQ] in the mainline and is a different [RNBQ] in the variation. There must be no differences in the position other than that changed White piece. This situation most commonly occurs as a result of an underpromotion in one of the lines, where the variation shows why the a pawn could not successfully promote to some particular piece.

The relevant relation filter has a target filter of variation forcing the target to be in the variation, and the two relation parameters: 

(sourcesquares [RNBQ] targetsquares [RNBQ] mismatch 1)
(mismatch 1)
Let us fix a particular source position and target position and examine in more details how these two relation parameters are evaluated.

In the first of these relation parameters, we observe that the default match range will be used. Therefore, the first relation parameter is actually equivalent to the square parameter: 

(sourcesquares [RNBQ] targetsquares [RNBQ] match 0 64 mismatch 1)
The sourcesquares square set here is all the squares in the source position on which there is a white rook, knight, bishop or queen. The targetsquares set is all the squares in the target position on which there is a white rook, knight, bishop or queen.

These two sets of squares are intersected to get a comparison set: the squares that are being compared in the source and target positions. Because of the mismatch 1, the square parameter matches if there is precisely one square in the comparison set that has different contents (that is, either the square is empty in both the source and target, or the same piece is in the source and target on that square) in the source and target positions.

Technically, because of the match 0 64 in the square parameter, CQL will also check that there are between 0 and 64 squares in the comparison sets that have the same contents. This check is trivially always true however.

This single changed square is the square that should hold the promoted piece: it represents (usually) a pawn that was promoted to one piece in the mainline and to a different piece in the variation.

The second square parameter of the relation parameters is (mismatch 1) This square parameter, due to the defaults, is equivalent to: 

(sourcesquares any targetsquares any match 0 64 mismatch 1)
This square parameter matches a target when there is precisely one square whose contents are different in the source and target positions.

Note that the previous square parameter verified that there was already one square with a different non-King non-Pawn white piece in the source and target. The effect of the (mismatch 1) square parameter is therefore to insure that that square is the only square that has different contents in the source and target.

square parameter to find a single changed black piece

Finally, we consider the square parameter used in the relation filter in moved-black-piece-relation.cql. This CQL file seeks a target in the variations that is the same as the source except that a single black piece has changed position. The relation filter that accomplishes this: 
 relation
   variation
    (tomove match)
    (sourcesquares a targetsquares _ mismatch 1)
    (sourcesquares _ targetsquares a mismatch 1)
    (mismatch 2)

For the above code
  • The relation filter is all the code.
  • The target filters is the single filter variation
  • There are four relation parameters:
    1. The tomove parameter, (tomove match). This relation parameter matches if source and target have the same side to move.
    2. The square parameter 
      (sourcesquares a targetsquares _ mismatch 1)
      This parameter matches if there is exactly one square with the property that there is a black piece on that square in the source, but the square is empty in the target.
    3. another square parameter 
      (sourcesquares _ targetsquares a mismatch 1)
      This parameter matches if there is exactly one square with the property that the square is empty in the source but has a black piece on it in the target.
    4. a third square parameter (mismatch 2). This parameter matches if there are precisely two squares each of which has different contents in the source and the target.
Now, consider the following two positions
mainline (source)variation (target)

Will the above two positions as source and target be matched by the above relation filter?

tomove match requires the same side to move in both source and target positions. Black is in check in both diagrams so we know the same side is to move.

What about: 

(sourcesquares a targetsquares _ mismatch 1)

There is exactly a single black piece in the source that is in the target position on an empty square. Only squares that both (1) have a black piece on them in the source and (2) have an empty square on them in the target are compared. Of these, there must be 1 mismatch. This mismatch corresponds to the square left empty by the single moved black piece. In our diagrams this is square c8.

Now we consider 

(sourcesquares _ targetsquares a mismatch 1)

The target matches the source according to this square parameter exactly when there is a single black piece in the target that is on a square that was empty in the source. The reasoning is as above, and this single mismatch corresponds to the new square of the moved black piece. In our diagrams this is square b7.

Finally, (mismatch 2) square parameter just makes sure there are no other differences between the positions. Since the two earlier square parameters each contributed a single mismatch, for a total of two mismatches, squares c8 and b7, there must be no other mismatches. Thus, the source and target do match the relation filter as we wanted.