# consecutivemoves

The `consecutivemoves` filter takes two position variables in parentheses as arguments, optionally preceded by a range:
```  consecutivemoves (x y)
consecutivemoves 5 1000 (x y)```

Suppose the arguments to the `consecutivemoves` filter are the position variables `x` and `y` .

The `consecutivemoves` filter first finds the latest common ancestor `L` of the positions represented by `x` and `y`.

Let `S` be the sequence of moves from `L` to `x` . Let `T` be the sequence of moves from `L` to `y`.

`S` and `T` are the exact moves, in order, played to reach `x` from `L` and to reach `y` from `L` respectively.

Thus, the length of `S` is equal to the ply value of `x` minus the ply value of `L`. Similarly the length of `T` is the ply value of `y` minus the ply value of `L` .

The filter `consecutivemoves(x y)` gives the length of the longest sequence of consecutives moves in `S` that is identical to a sequence of consecutive moves in `T` .

If a range is specified, the `consecutivemoves` filter only matches if that length lies with the range. If either of its argument filters do not match, then neither does the `consecutivemoves` filter.

The `consecutivemoves` filter adds comments to the longest pair of subsequences of consecutive moves that it located (unless the `quiet` or `silent` was specified in the CQL header). These comments indicate which move in one subsequence matched which move in the other subsequence.

The `consecutivemoves` filter is used in locating so-called "logical" studies, where one key move (the move in the LCA position) has a small difference that only becomes apparent much later.

If the parameter `quiet` is included, the `consecutivemoves` filter does not output any comments. (The filter also does not output comments if the quiet is specified in the CQL header):

`    consecutivemoves quiet 15 100 (source target)`

# Examples

The `consecutivemoves` filter is used in zugzwang2.cql and movedblackpieceecho.cql . In zugzwang2.cql, the `consecutivemoves` filters is used to find a zugzwang position where the positions differing only in side to move are reached by a series of identical moves.

In the following position from a Didukh study, White can play either `2. Kf3!` or `2. Kf2`:

Didukh 2011, mainline after Black's 1...Nf5
(found from CQL file: zugzwang2.cql)

If White plays `2. Kf3` the position leads to the following position, which is winning for White:

Didukh 2011, mainline after 10. Kf2

If on the other hand, white plays `2. Kf2`, then Black reaches the following the position, which is identical to the position above except that it is white to move instead of black to move:

Didukh 2011, variation after 9...Bb7

The sequences of moves to reach the two positions above are the same for 15 consecutive individual moves. For example, from the PGN output for the Didukh study, we see that if White were to play `2. Kf2` then Black would respond `2...Ne7`.

Note the comments of the form: `target-move` or `source-move`. The comments were generated as a consequence of the filter:

`    consecutivemoves (source target)>= 5`

in the CQL file zugzwang2.cql. It was called when the `source` was set to the mainline black-to-move position (diagrammed above) after `10. Kf2`, and `target` was set to the variation white-to-move position (diagrammed above) after `9...Bb7`.

The comment `target-move[1]` means that this is the first (because of the `[1]`) move of the sequence of moves leading to `target` . There is a corresponding sequence of moves leading to `source`, and the first move of that sequence, which is `2...Ne7` in the mainline, is annotated `source-move[1]`. Both these moves are the same: `...Ne7`.

Reading down the moves in the variation and mainline, one can see the correspondence of identical moves between the variation and the mainline.