Entering Problems

Introduction

For now, Jacobi only supports entering problems in a text format similar to Popeye's. Eventually I plan to add a graphical editor, but the text format is still useful to make it possible to keep track of problems in a text file, or to easily exchange problems with others in a forum or by e-mail.

Most of the time, input in Popeye's format can be used as is. This is by design so that you can more easily test the same problem in both programs. Since Jacobi can only handle one problem at a time, it accepts but doesn't require BeginProblem and EndProblem if your input is in English.

To save time, you can type only the first few letters of a keyword (e.g. writing stip instead of stipulation) as long as it is not ambiguous. Popeye works the same way.

Forward stipulations

  • By default the initial position is the standard one, so the following will list every possible way to play Fool's mate.

    option FirstToMove white
stipulation h#2

  • In the example above we had to add "option FirstToMove white" to undo the convention that black plays first in a helpmate of integer length. (This option is different from Popeye's WhiteToPlay which would also remove 0.5 moves from the helpmate.) If you prefer, you can instead use Jacobi's elementary commands, play and test, which aren't loaded with a baggage of conventions:

    play help 2.0
test #

  • P0527811 by Christopher John Feather in 1975 is a h#2 problem. It would be entered as

    forsyth 1RrB2b1/8/4s3/2s3p1/2K2b2/1p1rk3/6BR/8
stipulation h#2

  • P1225028 by Milos Tomasevic and Radovan Tomasevic in 1992 is a ser-sx 126. It would be entered as

    forsyth 4bsq1/2p1K3/2k2r1b/5p1s/1P1P1p2/1PpP1Pp1/2P1rp2/1B6
stipulation ser-sx 126

Proof games

In the case of proof games, Jacobi is a bit picky and it requires the forsyth statement to appear immediately after the stipulation statement so it doesn't get confused with an initial position declaration. Technically the diagram is extra data attached to the dia stipulation, which is why I like to put it on the same line (but you can also insert a line break).

  • The example problem at the top of the welcome page is P1068521, entered as

    stipulation dia9.5 forsyth rsbq1bsr/pppk1ppp/2B5/4p3/8/3PSSr1/PPP2PPP/R1BQ1RK1
condition Circe RexInclusive

A-to-B stipulations

  • P1243719 part (1) by Andrew Buchanan and Richard Stanley in 2001 is an A-to-B in 5.5 moves. In Jacobi we could still use dia5.5 but to increase compatibility with Popeye we can also write a=>b5.5. The problem would be entered as

    forsyth 8/3pP1p1/6p1/5P2/2p2P1k/2p2p2/PpK2pP1/r7
stipulation a=>b5.5 forsyth 6k1/3pP1p1/6P1/5PP1/2p5/2p2p2/P4p2/rb1K4

    Popeye's default is white-to-play for ser-a=>b but black-to-play for a=>b, so to solve this problem in Popeye you must add option WhiteToPlay. Jacobi's default is white-to-play, and to change it you would add option FirstToMove black.

Language commands

Jacobi is lenient and will accept commands and conditions written in English, French, or German (French and German conditions accepted since v0.3.1).

This polyglot approach doesn't work for pieces because a position with only K and B is possible in English and German, but the meaning is different. Color names are also problematic because the color "b" is possible in English and French, but the meaning is different.

By default the language is English with S for knight. The following commands declare a different language.

  • DebutProbleme: French
  • AnfangProblem: German
  • EnglishN: English with N for knight

These affect the parsing of piece letters and color names following forsyth, pieces, constraints, the option FirstToMove, and the PG option Add.

Example:

  • P1000770 by Thierry Le Gleuher in 2000 is a PG 8.5 with the condition EinsteinChess. For fun, let's enter it using French notation. FinProbleme is accepted but not required.

    DebutProbleme
enonce dia8.5 forsyth tc2r2t/ppp1p1pp/3p4/5p2/8/8/PPPPPPPP/TCFDRCFT
condition EchecsEinstein

Advanced stipulations

Proof game options

Adding an unspecified number of pieces

  • P1305233 by Alexandre Leroux in 2015 is a PG 7.0 with the option AddPieces. Since we no longer care for compatibility with Popeye we can write PG instead of dia if we want (they are synonyms). It would be entered as

    stipulation PG 7.0 pieces white Ka5 Pa6 black Re4 AddPieces

  • P1068165 by Peter Fayers in 2005 is a PG 6.0 with the condition Kriegspiel which (in this case) means the PG option AddWhitePieces. It would be entered as

    stipulation PG 6.0 forsyth r6r/pppqkppp/2bp1s2/8/8/8/8/8 AddWhitePieces

Adding a specific number of pieces

  • P1189482 by François Gouze in 2010 is a PG 10.5 with the condition "Add one piece" which can be solved with option Add white X (available since v0.4.8). In Jacobi, X represents an unspecified piece. (To prove C+ one also has to solve with Add black X.) It would be entered as

    stipulation PG 10.5 forsyth 1s1q1b1r/p1pppp1p/6ps/8/3k3P/3PR1P1/PPP1PP2/RS1QK1S1 Add white X

  • It is possible to add more than one piece. The unrewarded T06 from TLG-50 by Allan Bell in 2010 requires adding a white king and a white pawn. It would be entered as

    stipulation PG 9.0 forsyth rsbqkbsr/pppppp1p/8/8/3R4/2S5/PPP3PP/2R2r2 Add white K P

    It is possible to repeat a piece and to specify pieces for each color, for example Add white P P black Q K.

Coloring Problems

  • P0000111 by Andrey Frolkin and Leonid Lyubashevsky is a PG 11.0 with the condition ColorThePieces. Jacobi is not very fast for this kind of problem, but here's the input:

    stipulation PG 11.0 forsyth RS1Q1BSR/1PP1PKPP/1PP5/5P2/7P/1PP3P1/1PP1PP2/1SBQK1S1 ColorThePieces

Chaining multiple stipulations

  • P0001674 by Vasile I. Tacu in 1991 is a PG 6.0 with undefined pieces, followed by a mate in 1. In a forsyth string, the letter X represents a white undefined piece, which is why we need to add the PG option ColorThePieces. The problem would be entered as

    stipulation PG 6.0 forsyth XXXXXXXX/XXXXX1XX/8/5X2/8/8/XXXXXXXX/XXXXXX1X ColorThePieces
stipulation #1

  • P1338763 by myself in 2017 is a PG 5.0 with the option AddPieces, followed by immediate checkmate. It would be entered as

    stipulation PG 5.0 pieces white Kf1 Sb6 AddPieces
test #

  • P0574859 by Franz Pachl and Markus Manhart in 1993 is a h##3.5. A double-mate requires putting oneself in check which is illegal in orthodox Chess, so in Jacobi this problem requires the fairy condition AllowTerminalAutoChecks (automatically added if you forget). This particular double-mate problem is of the variety that requires the previous move to be checkmate. Starting the problem with h#3.0 would start with the wrong player and mess with the move numbers. A clever way to enter it is

    forsyth 1b6/2B5/4p3/P3K1Rr/4P3/6p1/4R1P1/1S1ks3
stipulation h~2.5
stipulation #1
stipulation ##1
condition AllowTerminalAutoChecks

  • P1067987 by Mark Kirtley in 2004 is a synthetic game problem which requires the move "5... e1=S" in the middle of the game. It's a bit crazy, but it can be entered as

    play help 4.5
test dia pieces black Pe2 AddPieces
test not dia pieces black Se1 AddPieces
play help 0.5
test not dia pieces black Pe2 AddPieces
test dia pieces black Se1 AddPieces
stipulation hs#2

Reflex stipulations

The reflex stipulation "r" is the combination of the self stipulation "s" and a reflex condition with the same aim. The reflex condition is the combination of three rules:

  1. Each side must reach the aim if they're able to.
  2. The idle side in a series will wake up to reach the aim.
  3. Reaching the aim ends the move sequence.

Here is an example:

  • P1292590 part (b) by Raffi Ruppin in 1964 is a ser-r#4. It would be entered as

    forsyth k7/P4PPs/PP5r/1r6/2p1s3/5b2/8/2K5
stipulation ser-r#4

    This is shorthand for the following code, where the reflex condition has been pulled out:

    forsyth k7/P4PPs/PP5r/1r6/2p1s3/5b2/8/2K5
set test # reflex
stipulation ser-s#4

    The set test # command creates a persistent checkmate test for every subsequent move. The command must be followed by an option such as reflex to have any effect on the game. The option reflex is itself a shorthand for the three options prefer wake end which correspond to the three rules above.

Below are examples where "reflex" is used as a condition, applied to something other than a self stipulation.

  • P1318357 by Peter Rösler in 1992 is a h#6 with the condition Semireflex-check. It would be entered as

    pieces white Ka8 Pc2 black Kc8 Pd2g2h2 
set test + black reflex
stipulation h#6

    In the above problem, it turns out that the reflex condition can be replaced with BlackMustCheck, but this needs not hold in general. A reflex condition is stricter because the game ends when Black checks, while the game continues with BlackMustCheck.

  • JF-1257 by Nicolas Dupont in 2017 is a PG 17 with the condition Black reflex #. It would be entered as

    set test # black reflex
stipulation PG 17 forsyth rbq4r/pK1pp1sp/2s3bp/2p2pk1/8/5P2/PP1PP1PR/RSBQ1BS1

Series stipulations

The ser- stipulation ends with the other player on the move, so if you chain two ser- stipulations, then the first one will be a white series, and the second one will be a black series. If your goal is to split a long series into a chain of series for partial testing, then use ser-* to get a series that ends with the same player on the move. ("*" is a notation introduced by Nicolas Dupont to represent a pass move.)

Parry series

Parry series are described in an article (PDF) by the inventor Dan Meinking, and revisited in a follow-up article by Petko Petkov. A parry series is denoted pser- if the parry moves are defensive, and phser- if the parry moves are helping. Currently, Jacobi can only deal with phser-. Because of an historical accident, the notation "pser-h" is used in publications and in Popeye to represent "phser-h", making it impossible to have a notation for a defensive series followed by a help move. I haven't bothered to program this strange exception in Jacobi so one must enter phser-h (feel free to rename it to pser-h when publishing). In phser-*, the pass move "*" can become a parry. Below is a summary of the help stipulations we just discussed, which are useful for checking PGs.

StipulationNumber of plies including pass movesDescription
phser-oddThe series ends with a move by the series-side, even if that move gives check (the stipulation ends before the idle-side can respond).
phser-hevenLike phser-, but with an arbitrary move by the idle-side added at the end, even if there was no check.
phser-*evenThe series ends with the series-side on the move. This means that the last fullmove is either a non-checking move followed by a pass, or a check-and-parry, but not a checkmate by the series-side (since it cannot be parried).

Anti-parry series

The fairy condition AntiParry opens up the possibility of an anti-parry series aser- (the idle side responds to auto-checks, being forced to un-check). If the idle side should respond to both checks and auto-checks, then the stipulation is paser-. As before, Jacobi can only verify the help variants ahser- and pahser-. See the document Anti-Parry Series (PDF) and follow the links on top for examples.

It's worth noting that aser- in AntiParry is quite similar to pser- in Vogtlaender. The possible games are almost identical, with differences only due to the possibility in Vogtlaender of castling through an orthodox check even if the king doesn't land in check, and the possibility in Anti-Parry of delivering a check on the final move of the series. Aims need to be modified: the aim "dia" stays the same in Vogtlaender, the aim "+" becomes "!+", and the aim "=" becomes "s#", but not all aims can be transformed in this way.

Aims

Definitions

Most are well-known. Below is additional information.

Diagram (dia, a=>b, PG)

"dia" must be followed by "forsyth" or "pieces" — immediately in the case of "test dia", and right after the length in the case of "stipulation dia". In Jacobi, "dia", "a=>b", and "PG" are synonyms and are completely equivalent. The aim "dia" is special because dia and ser-hdia stipulations start with White by default, even though the corresponding helpmates (h# and ser-h#) start with Black.

Multiple checks (+, ++, +++, ...)

"+" will trigger on 1 check or more, "++" will trigger on 2 checks or more, and so on. To test for exactly 2 checks, do it this way:

test ++
test not +++

To test for mate by double check (or more), do

test #
test ++

Mate events ($, $$, $$$, ...)

In #R Chess, #C Chess and Kk Chess, a move may contain 1 or more mate events. The aim "$" will match both provisional mates and true mates, while "#" will match true mates only. A sequence of n "$" will trigger on n mates or more, similar to multiple checks. To test for exactly 2 mates, do:

test $$
test not $$$

Fairy conditions

Definitions

The list of conditions available in Jacobi can be found by opening the section "Conditions" on the solver page. The suffix "Chess" has been removed from names, but this is only for conciseness. In publications, it's probably best to add "Chess" to some of them, e.g. "Chameleon Chess", "Andernach Chess", etc.

This section is incomplete. Please refer to the following external links for missing definitions.

Fairy chess (problem rules)

Chess variants (game rules)

Priority should be given to Fairy chess links because the definitions of Chess variants may sometimes differ. For example, the fairy condition "Maximummer" applies to Black only, but as a chess variant it applies to both players. In the fairy condition "Monochromatic", checks obey the restriction, but as a chess variant it is sometimes specified that checks are orthodox.

Chess960, Chigorin, Almost, Knightmate, CavalierMajeur, Berolina

These conditions modify the initial position. They also sometimes modify the set of allowed promotions.

In Chess960 forward stipulations, Jacobi will attempt to maximize castling rights, but there is no deep retro-analysis. If there are kings and rooks on their initial ranks but White and Black don't correspond, then Jacobi will be confused and may pick the wrong castling rights.

In Knightmate, Jacobi interprets S as a royal knight and K as a non-royal king, so there is no need to manually specify a royal S.

NonRoyalKings

Kings can be captured and promotions to king are possible. NonRoyalKings was created to implement LosingChess, but maybe it's interesting on its own. Following Popeye, a non-royal king can castle. (If you disagree, then just ignore any castling solution found.)

LeseMajeste

Allows illegal starting positions where the player to move is already checking the opponent's king. Note that this is classified as a theme by PDB and not as a fairy condition. The player to move cannot capture the opponent's king, in accordance with Article 1.4.1 of the Laws of Chess (2018). Adding LeseMajeste makes Bicapture PGs possible.

Annan, BackToBack, FaceToFace

A piece moves like a specific nearby unit instead of as itself if such a nearby unit is present.

  • Annan: moves like the friendly unit one square behind.
  • BackToBack: moves like the enemy unit one square behind.
  • FaceToFace: moves like the enemy unit one square in front.

The en-passant rule comes from Popeye:

  1. Only pawns and Berolina pawns that act like the same type of pawn can be captured en-passant.
  2. Any piece can capture en-passant, as long as it acts like a pawn or a Berolina pawn or a pawned piece. (Currently Jacobi has no pawned piece, but Popeye has DR and SH.)

  • The test below illustrates these rules. En passant is only possible with the pieces on files a, b and c.

    pieces white Pb4e4h5 BPc4f4 Rb5c5e5f5 black Pa7d8e7g7 BPb7b8d7e8 Rg8
stip hep1.0
cond Annan

NormalPawn

Found in Popeye. Some conditions make it possible to bring pawns to their first rank. By default they cannot move, excepted with Circe Equipollents, Circe Parrain, and Einstein. NormalPawn allows pawns on their first rank to move (by one square) or capture.

FreeForAll

Each player can move pieces from either player (Jed Stone, 1982).

PromOnly

Found in Popeye. Normally the set of allowed promotions is determined by the fairy conditions and by any fairy piece appearing in the starting position. PromOnly lets you override this. To allow a pawn to move to the promotion rank but stay a pawn, use PromOnly P. Fairy pieces cannot be specified at the moment, sorry. For technical reasons, the PromOnly letters are English-S even if you use a language command.

In Jacobi, if PromOnly is set but no piece is given, then a pawn cannot move to its promotion rank (equivalent to Popeye's NoWhitePromotion + NoBlackPromotion). I don't think that this condition should be used because the natural meaning of "No promotions" is probably "PromOnly P" (assuming there are no Berolina pawns). This is the meaning in WinChloe. In Popeye's interpretation, it's not clear whether a pawn on its 7th rank gives check or not. Popeye is inconsistent about it (and Jacobi also).

WhiteOscillatingKings, BlackOscillatingKings

Royal pieces exchange places after each white/black move. TypeC (from Popeye) means that the player must be in check for the swap to occur.

#R, #C, Kk

These conditions make it possible to keep playing after mate. When mate occurs, an action is performed.

  • #R: the mating piece(s) are removed.
  • #C: the mating piece(s) change color.
  • Kk: the royal pieces exchange places.

By default, the mating move must be legal before the action. The option ReleasingCheck lets you anticipate the effect of the action to get rid of a self-check. The option has the most effect on Kk Chess.

If after the action is performed the opponent is still mate, then the action is repeated. If the action leads to self-check or to a second swap, then the last action is reverted and the game ends in "true mate".

NoImmediateRepetition

A move is illegal if it repeats the diagram from 2 plies ago. Created to implement AllIn = FreeForAll + NoImmediateRepetition, but maybe it has other uses. Note that the diagram (not the position) is compared.

  • Here's an illustrative example by Paul Bissicks, S.N. Ravi Shankar, and Chris Tylor, from The Problemist Supplement, September 2017 (W675590, part a).

    pieces white Kg6 Pc7 black Ka4 Pa3a5b3b4b5
stipulation h#2
condition AllInChess
condition GrowingMen

    The solution is 1.c8=B Bd7 2.Bxb5 Be8#. The follow-up move 3.Bb5 is illegal because it repeats the diagram, even though the bishop on b5 is not exactly the same (it grew from 2√2 to 3√2).

Isardam

Moves causing a Madrasi-like paralysis are illegal. This rule also applies to the capture of the king, unless TypeB.

Leffie

Moves causing an Eiffel-like paralysis are illegal. This rule also applies to the capture of the king, unless TypeB. (Paul Răican, Quartz 46).

AntiParry

When not in-check, the side on-move may put his own king in-check, provided that the move does not also check the opponent's king. The opponent must immediately remove this auto-check via a move (anti-parry) such that, after having been played, neither king is in-check. If such an anti-parry move does not exist, then the auto-check is forbidden. Castling through check is forbidden unless the moving side's king also lands in-check.

See the article on Anti-Parry Chess in StrateGems 59 (2012) if you have a copy (no online version).

AllowTerminalAutoChecks

Allows the last move to be self-check. Necessary in Jacobi for auto-check, auto-mate, and double-mate aims.

Duelist (= Single Combat)

Usually formulated as "players must keep playing the same piece if possible", but Popeye's definition is rather that players must play a move that starts from the arrival square of their last move if possible. This makes a difference when combining with other conditions: In Circe, if a duelist is captured and reborn, then it is no longer a duelist. In Andernach Chess, if a duelist is captured, then the recolored attacker becomes the duelist.

WhiteMustCapture, BlackMustCapture, WhiteMustCheck, BlackMustCheck

The player must capture/check if possible. If not possible, then any move can be played. Anti: must not. Ultra: If not possible, then the game ends and the position is mate/stalemate. SemiUltra: If not possible, then the game ends but the position is not considered mate/stalemate unless there are no legal moves at all. SemiUltra is a Jacobi invention to implement BlackCap, BlackChecks, and Dawson's Zigzag. In table form:

OptionEffectMate/Stalemate
(nothing)PriorityOrthodox
UltraObligatoryFairy
SemiUltraObligatoryOrthodox

BlackPassesIfStuck

This is a Jacobi invention to implement BlackCap and BlackChecks by combination with BlackMustCapture SemiUltra and BlackMustCheck SemiUltra, respectively. It might be useful in combination with other conditions where Black is likely to have no legal move.

AllIn

The side to move may make a normal legal move with a unit of either color, provided only that the move does not simply undo the previous move.

One tricky aspect of All-in Chess is the set of conditions under which it is possible to castle with the opponent's pieces. In the article More All-in Chess with Growing Men by Paul Bissicks from The Problemist Supplement, September 2017, the rules are laid out:

  1. The mover's king must obviously not be put in illegal self-check.
  2. Castling with the opponent's pieces to escape check is illegal.
  3. Castling by moving the opponent's rook across a square where it attacks the mover's king is illegal.

As of v0.5.2, Jacobi only implements rules 1 and 2.

Rule 3 is unusual because Popeye doesn't consider a castling rook to be visiting intermediate squares, otherwise the following tests would not return 1.O-O-O as a solution.

  • begin pieces white Ke1 Ra1 black Rb8 stip 00 1 cond ExtinctionChess end
  • begin pieces white Ke1 Ra1 black Sb3 stip 00 1 cond ProvocationChess end

Zigzag, ZigzagStapff, ZigzagUltra

White must not check nor capture. The three variants are implemented using the options SemiUltra, nothing, and Ultra, respectively. The result is this:

ConditionWhite restrictionMate/Stalemate
ZigzagObligatoryOrthodox
ZigzagStapffPriorityOrthodox
ZigzagUltraObligatoryFairy

Checking Zigzag

Checking Zigzag is the combination of BlackChecks (Black checks if he can, otherwise he passes) and Zigzag. You can write "condition Checking Zigzag" because Jacobi accepts "Checking" as a synonym of BlackChecks.

Jacobi follows the definition given in this Popeye feature request. In WinChloe, the white restriction in Checking Zigzag is slightly different, described in Quartz 45, and considered incorrect by the comment attached to P1106694. There is only a difference with plain Checking Zigzag — the Stapff and Ultra variants of Jacobi correspond to WinChloe.

Move length

Remember that the length of a move is "as the crow flies". It's tempting to want to define it as the path length, but this wouldn't work because some fairy pieces like the Rose or Ubi-Ubi can move to the same square using paths of different lengths. The same difficulty exists with the rook and queen in VerticalCylinder.

In VerticalCylinder, the length of a move is "as the crow flies" on a vertical cylinder. For example, the length of axh3 on a vertical cylinder is √2 (matching the path length in this case), and the length of Bc1-d8 on a vertical cylinder is √50 (not matching the path length of 7√2). Incidentally, the move animation in the Game editor is "as the crow flies", so it shows the length of a move. Vertical cylinder move length is demonstrated in this PG in 11.5 by Guy Sobrecases in 2006. 4...Re4+ is longer than 4...Rd4 "as the crow flies".

englishN
stipulation dia 11.5 forsyth 3qknnr/1uu1u1uu/8/6u1/Q1UUU3/8/bU1UN2U/RNB3K1
condition Berolina
condition VerticalCylinder
condition DoubleMaximummer

Castling requires special considerations. In GrowingMen and ShrinkingMen, the move lengths of the king and rook are applied separately to each piece. In Maximummer, the move lengths of the king and rook are added together.

The path of reborn pieces is not included in Maximummer, and doesn't affect GrowingMen either.

Application order

Some experimenting shows that when you mix two conditions in Popeye (say ChameleonChess and EinsteinChess), the order in which you list the conditions doesn't matter — instead the conditions are applied in a predetermined order. Jacobi does the same thing, and this is reinforced by the UI where conditions are checkboxes whose order cannot be changed. In the UI, the conditions are listed in rough order of application. For example (following Popeye), Monochromatic affects Madrasi paralysis and Madrasi paralysis affects the definition of observation of Patrol, so these three conditions are listed in the order Monochromatic, Madrasi, Patrol. The application order used by Jacobi attempts to match the order used by Popeye.

Move selection conditions

The move selection conditions are these:

Duelist
WhiteMustCaptureBlackMustCapture
WhiteMustCheckBlackMustCheck
WhiteFollowMyLeaderBlackFollowMyLeader
WhiteAlphabeticBlackAlphabetic
WhiteMaximummerBlackMaximummer

Popeye doesn't allow you to use them at the same time for the same side, but WinChloe does, so why not? For these conditions, the application order of Jacobi matches WinChloe's.

  • P1356701 by Bernd Gräfrath in 2018 is a PG 9.5 which makes use of the application order of move selection conditions:

    stipulation dia 9.5 forsyth rsbqkbsr/pppp3p/5p2/8/4p3/8/P1PPPPP1/2B1KBSR
condition BlackMustCapture
condition BlackMinimummer

The "Ultra" and "SemiUltra" options boost a condition's priority, so WhiteMustCheck Ultra (= WhiteUltraSchachZwang) is applied before WhiteMustCapture. This agrees with Popeye which lets you mix these two conditions.

Exclusive to Jacobi

The following conditions are of special interest because they're not in Popeye. This means that, for these conditions, Jacobi is useful not just for proof games but also for other help stipulations. A condition in quotes means that I haven't seen it in any lexicon, but the meaning is straightforward.

JacobiPopeyeWinChloe
Chess960YesNoNo
VerticalCylinderYesNoYes
GrowingMen / ShrinkingMenYesNoYes
Madrasi PawnExclusiveYesNoYes
AntiUltraPatrolYesNoYes
"AntiProvocation"YesNoNo
AntiFunctionaryYesNoYes
FreeForAll / AllInYesNoNo
BicaptureYesNoNo
CannibalYesNoNo
AdversePromotionsYesNoYes
Multicapture / UnicaptureYesNoYes
#RYesNoNo
#CYesNoNo
KkYesNoNo
"Isardam PawnExclusive"YesNoNo
LeffieYesNoYes
AntiParryYesNoNo
WhiteMustCapture AntiYesNoYes
WhiteMustCheckYesNoYes
WhiteMustCheck AntiYesNoNo
WhiteAlphabetic AntiYesNoYes
VerticalSymmetryCirceYesNoYes
Blackcap ZigzagYesNoYes
Checking ZigzagYesNoYes

Partial verification of problems

Constraints

Constraints (available since v0.5.3) let you narrow the search. They can be used to look for duals by forcing parts of your intended solution. They can also sometimes be used to completely verify a problem if you are really sure that the constraints must be obeyed by any solution, leading to a human-computer proof of correctness (HC+).

For each piece in the original diagram, it is possible to specify some or all of its moves. It is also possible to specify a minimum number of moves that the piece must make.

Let's start with an example.

  • About his 1st Prize from the Murfatlar 2018 preliminary award, Nicolas Dupont wrote:

    "The capture e3xe4 is impossible as square e3 is observed by the immovable Pf2. Hence the capture d2xd3 is mandatory, which implies that Sb1 Qd1 and Ke1 must have left their observation of square d2 (and then gone back home), and that Bc1 must have been home-captured (and then replaced by a Pronkin promotion)."

    Because of the tight move count, we can further deduce that Qd8 captured on c1 and then moved to d3. This leads to the following input.

    stipulation dia 18.5 pieces white Ke1 Qd1 Ra1h1 Bc1f1 Sb1g1 BPa2b2e2f2g2d3e4 black Kb5 Rg6h8 Bf4c8 Sd7g8 BPa3c5e5e6b7e7f7h7
condition Berolina
condition Lortap
constraints BPd2xd3 Sb1(2) Qd1(2) Ke1(6) BPh2-c1=B Qd8xc1-d3

    With this input, Jacobi finds a cook. An HC+ correction can be found in the WCCC 2018 Bulletin.

For more examples, see this article on Julia's Fairies.

Notation

The constraints notation is similar to the strategy notation displayed by Natch and Euclide. For example, in Qd8xc1 the queen doesn't have to go directly from d8 to c1 — it may play some intermediate non-capturing moves. Jacobi's constraints notation accepts more symbols to allow more flexibility. Below is a full description.

  1. The constraints for a given piece are written in one block without any intervening spaces. The notation starts with the piece type and its original square (the piece type is redundant information and is only used to detect errors).
  2. This is followed by zero or more move constraints for that particular piece.
    1. A move constraint starts with the type of move:
      "-" : a sequence of zero or more non-capturing moves.
      "x" : a sequence of zero or more non-capturing moves, followed by a capture.
      "~" : a sequence of zero or more moves.
      "*" : a sequence of zero or more moves, followed by a capture.
      ">" : exactly one move.
      "!" : exactly one castling move (king or rook).
    2. Capturing moves ("x" and "*") can be optionally followed by the origin square of the captured piece in brackets, for example x[c1].
    3. This is followed by the square that must be reached.
    4. If the piece type is different from last time, then the change needs to be specified. For example, if the piece changed to a bishop, then add "=B", or "=bB" if the color also changed. Although the promotion notation is being used, the piece change can have occurred earlier. You also don't need to catch every individual change with a contraint — Jacobi only needs to know the piece type each time you give a destination square.
  3. Move constraints are a bit like "achievements" that pieces must unlock one after the other. Every piece must have completed their last achievement when the problem length is reached or when the piece is captured or disappears. Progress can only go forward, excepted the last achievement which can be revoked if a piece plays an extra move that doesn't satisfy it, forcing the piece to attempt the achievement again. To allow a piece to potentially wander after its last capture and come back, write xc3-c3 instead of xc3. If instead you want the piece to be completely free after the last move constraint, then write "xc3-" to allow zero or more non-capturing move, or "xc3~" to allow zero or more arbitrary moves. A trailing "-" or "~" is a square-less move constraint that takes the last spot, therefore making the previous move constraint unrevokable.
  4. After all the move constraints of a piece have been given, it is possible to specify the minimum number of moves that the piece must make since the beginning in parentheses. For technical reasons, castling counts as zero moves for both the king and the rook. Since v0.5.4 you can also write (2..4) for a range, and (0..0) for a piece which doesn't move (though it can still castle or be moved by a fairy condition).

As a summary, you can write something like "Qd1xh1xb5-d2" if Qd1 captures exactly twice and ends on d2. Write "Qd1*h1*b5~d2" if there can be extra captures along the way. Write "Qd1*h1*b5~d2~" if Qd1 is allowed to play more moves after d2.

Castling is considered to move the rook too, so white O-O can be enforced with the constraints "Ke1!g1 Rh1!f1". Writing just "Ke1!g1" is slower because Jacobi could waste time exploring games where Rh1 moves before castling.

Although Jacobi is in general lenient about letter case, here piece types must be uppercase, and columns and colors must be lowercase, otherwise there is ambiguity between bP and BP (black pawn, or Berolina pawn?).

Fairy considerations

In Chess960 PGs, constraints on pieces other than pawns are obviously problematic. You can test a specific Chess960 initial position by solving an A-to-B problem.

In KobulKings and in Circe Clone RexInclusive, a king can become a different royal unit. For now, use non-royal notation (=B, not =rB), though this may change in the future.

Sentinels are not pieces from the original diagram and their path cannot be constrained, sorry.

To make it possible to match a suicidal move in Circe Assassin and in #R Chess, move constraints are tested midway during the application of fairy conditions, after KobulKings but before Circe. In particular, #C Chess recolorings and king swaps are not yet applied when a move constraint is being tested (but are applied by the time the next move constraint is tested).

When a piece is passively moved or transformed (like a Circe rebirth, or a Masand recoloring), the constraint system doesn't see it. For example, in Circe, if Qd1 is captured on d4, reborn on d1, and no longer moves, then the correct queen constraint is Qd1~d4 and not Qd1~d4-d1 since the queen didn't "move" to d1. A piece persists after rebirth so further moves can be constrained, for example Qd1~d4-e2 if the queen moves to e2 after rebirth.

Non-PGs

Constraints apply to forward stipulations too, but without any look-ahead analysis while searching for a solution. To add such an analysis, add a dummy PG stipulation at the end of the problem.

test dia forsyth 64 AddPieces

Eventually this will probably be added automatically, but for now I like to be able to experiment with and without.

Unique defenses

Some direct and self problems have solutions where White repeatedly forces Black to have exactly one legal move. Jacobi can look for solutions of this form because there is no branching of defense, so the problem behaves like a help game.

This is achieved with the stipulation u (for unique defense) introduced in Jacobi v0.5.5. In this stipulation, White starts, and legal moves by the second player must be unique. An integer length can be used to test self stipulations, and a fractional length can be used to test direct stipulations.

Doing this will not find solutions where Black has more than one legal move, so the test is only partial, equivalent to Popeye's option NonTrivial 0 1. Here are some examples.

  • P1104389 by Hermann Stapff in 1950 is a #9 with the condition Checking Zigzag type Stapff. In the solution, every black move is unique, so the problem can be partially checked using:

    forsyth 2K5/2pPpP2/3Pp1k1/8/5pbp/8/1p6/8
stipulation u#8.5
condition Checking ZigzagStapff

  • P1180459 by Thomas R. Dawson in 1913 is a s#25 with the condition Blackcap Zigzag. In the solution, every black move is unique, so the problem can be partially checked using:

    forsyth K1k1s3/5p2/2S5/b7/1ppppppp/7r/PPPPPPP1/8
stipulation u#25
condition Blackcap Zigzag

  • P1097744 by Thomas R. Dawson in 1917 is a s#8 with the condition Checking Zigzag. In the solution, every black move is unique except the last one, so the stipulation can be decomposed into u~7 and s#1, both accepted by Jacobi. The input is:

    pieces white Kd1 black Ke3 Sa3 Pb4
stipulation u~7
stipulation s#1
condition Checking Zigzag

  • P1104196 by Hans Hofmann in 1948 is a r#8 with the condition Checking Zigzag. In the solution, every black move is unique and the reflex is only used for the last move, so the problem can be partially checked using:

    pieces white Ke8 Pc2 black Kf6 Bb2
stipulation u~9
stipulation r#1
condition Checking Zigzag

  • P1333442 by Sergey Smotrov in 2017 is a s#17. In the solution, every black move is unique except move 15 where Black has 2 options. Since our goal is only a partial check, we can cheat and replace Black's 15th move with a help move. We also require White's 15th move to be check to limit Black's options. Making the last move a s#1 is a good habit because it can find more cooks at no cost. Doing this finds one invalid "help" solution and the two intended solutions. The input is:

    forsyth 3QS3/1k1B4/3R1p1r/p7/7s/2P1B3/1spK4/r2b4
stipulation u~14
stipulation h+0.5
stipulation h~0.5
stipulation u~1
stipulation s#1

Jacobi also offers puser-, auser- and pauser-, the unique-defense counterparts to phser-, ahser- and pahser-. Here's an example.

  • P1224929 by George P. Sphicas in 2009 is a pser-s#10. In the solution, every black move is unique, so the problem can be partially checked using:

    forsyth 1k6/1P4P1/3K1P2/8/8/8/8/7b
stipulation puser-s#10

About the solver

Defensive moves

Jacobi will accept a defensive move if the situation being defended against can be directly tested. So a s#1 is fine because Black is defending against checkmate, but a s#2 is not, because the first black move is defending against a s#1, which is not an instant verification.

This means that Jacobi can handle stipulations where the only defensive move is at the very end of the problem, but it can also handle some other cases too. The stipulation hsx5 followed by the stipulation hs#2 works, but it requires elaboration. Black's 5th move is defensive in the sense that Black will avoid capturing if he can, but Black's choice among possible capturing moves will be helpful.

PG demolition mode

The solver option "PG demolition mode" searches the most likely moves first and then progressively tries less likely moves in multiple passes. It should find a cook faster if there is one. On the other hand, if the problem is sound then it will take much longer to prove it, so you should not use the option if you expect the problem to be sound. Many people ask me how many passes it makes but there's no easy way to answer that. It is best to imagine that this mode takes infinite time, so you stop it when your patience runs out.

The option is for proof games only. If the problem doesn't have a proof game component ("dia" or equivalent), then there will be just one pass which will be identical to a search with the option off. If the solver is doing more than one pass then the option is working.

  • The option is famous for having been able to cook JF-1146 in less than 1 hour.

    stipulation dia16.5 forsyth r1Bs1rs1/ppP1k2p/7b/8/p7/3K1S1r/1P5P/3S2R1
condition Masand

Heuristic mode

The solver option "Heuristic mode" excludes moves that are locally dualistic. Because some moves are not analyzed, this mode cannot yield a C+ verdict. This mode imitates the shortcuts that human solvers use. For example, if plies A and B were just played, then the next ply C is rejected if playing C B A would have been legal and would lead to the same position as A B C. Heuristic mode has been programmed to catch other types of duals as well (all within a window of 3 plies), but it is not guaranteed to find them all. To get an idea of what it's doing, play around in the Game editor. Heuristic mode looks for solutions made purely of "green" moves.

The option tends to find a problem's intention more quickly, sometimes by a factor of more than 100, with a median speedup of maybe 3x for short proof games. I don't know if the option has other uses.

  • P1000395 by Thierry Le Gleuher in 1999 is a PG 20.5 with the condition Einstein. The intention can be found in less than a minute using Heuristic mode. As of v0.6.1, a full verification of the problem would probably take a few months.

    stip dia 20.5 forsyth P3k3/2ppppPp/pp2p1pp/1P6/ppPPP1p1/PP4p1/P1KPPPPP/1p1P4
condition Einstein

Hash table

For technical reasons, the hash table memory size can only be set once, before the first click on "Start". To change the hash table size again you have to reload the page.

A hash table size greater than 128M is useful for long-running problems (forward stipulation problems that take more than ~2 minutes, and proof games that take more than ~10 minutes).

The maximum possible value depends on your browser and browser version. Currently the maximum is 1014M in Firefox 64, and 2022M in Chrome 71.

Speed

The solver runs quickly in recent versions of Firefox and Chrome. One exception is Internet Explorer which is from 3x to 20x slower than the competition, even with IE 11. Its successor, Edge, is supposed to be faster.

As a way to test your performance, the first example (listing solutions to Fool's mate) should take about 0.2s on a reasonable machine.

If you get poor performance, you could consider installing a second browser (different from your favorite one) that you'd use only for running Jacobi.

Correctness

Jacobi uses a transposition table with hash keys of 86 bits, which gives a theoretically very tiny chance of missing a solution. Jacobi may also contain bugs, which is a more likely source of incorrect results. If you believe that Jacobi returned a wrong result for a problem, then please tell me by e-mail.

Keep in mind that fairy conditions are not always perfectly defined, especially in the way they interact when a problem uses more than one. My goal is to copy the behavior of the latest version of Popeye so that a problem that is C+ in Popeye will be C+ in Jacobi, and vice-versa. If you find a difference in behavior which is not a bug in Popeye, then tell me and I'll try to match what Popeye does.

Shorter solutions

Currently, Jacobi only searches for solutions of the exact specified length, as if each stipulation had the "exact-" prefix in Popeye. Solvers are divided on this issue, with Popeye and WinChloe reporting shorter solutions, but not Natch and Euclide. I plan to add a way to automatically search for shorter solutions, and maybe make it the default.

Crashes

Jacobi does a lot of internal consistency checks and it prefers to crash rather than give you wrong results. If Jacobi crashes and you don't think it should have, then please e-mail me the problem you were trying to solve and approximately how long it took before the crash, so I can try to reproduce it.

  • One known way to crash Jacobi is with a ChecklessChess loop, like this one taken from Popeye's BEISPIEL/exklohne.inp .

    anfang
auto Gerd Rinder
quel Seite 9, Die Schwalbe, X/1969
beme Ohneschach-Anomalie !
ford #1
bedi ohneschach
stei
weis kd7 td8h8 la1h1
schw ke5 nc3f3
ende

Game editor

The game editor is initialized when you click on the solver Start button (it shares the solver's chess engine). The game editor can then be used to view solutions or to play arbitrary legal moves. When you play arbitrary moves, the game editor obeys part of the problem description, but not everything. It will obey

  • the starting position
  • fairy conditions
  • series stipulations (i.e. the editor will automatically pass)
  • reflex conditions
  • unique defenses (stipulation "u")

but, for flexibility, it will not obey

  • the length of the problem
  • aims (such as # or dia)
  • constraints
  • the defensive component of stipulations (letter "s").

Play can continue beyond the problem length, extending what happened last (so a series mover will continue to be one).

Colored legal moves

Since v0.6.1, when you click on a piece, its legal moves are shown with colored dots with the following meaning:

  • green: no dual found
  • orange: dual by interchange with the previous move
  • red: dual by using a different path when a piece makes two consecutive moves
  • gray: (rare) the move will trigger a choice-menu containing moves that are not all of the same color.

This imitates the colors used by iNatch, but there are slight differences due to the different implementation.

Jacobi uses heuristics that may miss some duals (i.e. green moves are not guaranteed to be dual-free), but there should be no false-positive (i.e. orange and red moves are definitely dualistic).

Importing a game

The checkbox Editable game notation lets you edit or paste game notation. Unclick the checkbox to validate your changes. The notation language must be the same as the solver's Output language. If some part of what you entered is not understood, then the game will be truncated and the rest displayed in red, giving you a chance to fix the problem by clicking again on the checkbox.

Composing aid

The game editor can be used as a fairy PG composing aid:

  1. Create a minimal problem to describe what you want to achieve. If you want to compose a standard PG, then you only need to give conditions.
  2. Click on the solver's Start button to initialize the game editor.
  3. Play moves in the game editor.

The Current position section shows information that can help you create a problem input for testing. Before you click on a cook, you should copy your intention to Notepad or such so that you can copy it back to Jacobi later to use it as your starting point for your correction.

Tips

Berolina Chess

  • The 1st prize of Retros Problemaz 2007 by Paul Răican is a PG 21.0 with the condition BerolinaChess (available since v0.4.1) and DoubleMaximummer. Fairy pieces with 2-letter symbols can't be specified in forsyth, so we have to use the pieces notation. Alain Brobecker wrote a conversion tool Forsyth2Pieces which you may find useful.

    stipulation dia 21.0 pieces white Kf2 Se5 BPa2b4c4e4g2g3 black Ke8 Ra8h8 Bc8a3 Sb8f6 BPa7b7d5f5g7
condition Berolina
condition DoubleMaximummer

    In the language English-N, Berolina pawns are currently represented by the single letter U. This may change in the future when Jacobi can handle more than 26 pieces. For the moment, the following alternative input works:

    EnglishN
stipulation dia 21.0 forsyth rnb1k2r/uu4u1/5n2/3uNu2/1UU1U3/b5U1/U4KU1/8
condition Berolina
condition DoubleMaximummer

Retro-Growing Men

In Growing Men, no unit can make a shorter move than it made last time. In a forward stipulation problem, Jacobi assumes that every piece standing on the diagram has no "last time".

If retro-analysis is expected, then it means that the fairy condition was active since the initial position, and pieces standing on the diagram may have a non-minimal move length if it can be proven. Ideally this condition should be called Retro-Growing Men, similarly to the distinction between Volage and Retro-Volage.

Jacobi cannot solve Retro-Growing Men problems directly. For those, you need to perform the retro-analysis manually, and then add a preamble that enforces the deductions you've made. This makes use of the chained stipulation capabilities of Jacobi.

  • Here's an example by Paul Bissicks, S.N. Ravi Shankar, and Chris Tylor, from The Problemist Supplement, September 2017 (W675590, part c). Retro-analysis shows that bPb5 must have captured, so we create a preamble with an explicit capture. Here, the preamble is separated from the problem by a blank line (only for clarity).

    pieces white Kg6 Pc7 Rb5 black Ka4 Pa3a5b3b4c6b7
option InitialMoveNumber 0.5
stip dia 0.5

pieces white Kg6 Pc7 black Ka4 Pa3a5b3b4b5b7
stip h#2
cond AllInChess
cond GrowingMen

    If you remove the preamble, then Jacobi finds no solution because, with a fresh bPb5, the intention isn't mate: 1.c8=Q Qf8 2.Qxb4 Qh4+ (followed by 3.b4).

#R Chess and friends

  • Problem 2B part (a) by Chris Tylor from feenschach 212 (2015) has the condition #C Chess and the stipulation H(#/#)4. This stipulation means that two mates by White occur in a helpmate in 4 (where a mate can be provisional or true). Jacobi cannot test such a stipulation directly, but the possibilities are H#1/H#3, H#2/H#2, H#3/H#1, H##4, and H##2 (a shorter cook), and Jacobi can test these possibilities individually. Below is the input to test the first possibility. (Reminder: the Jacobi aim $ tests for at least one mate, provisional or true.)

    forsyth 4s3/4p2p/2pkpp2/8/1K2b1P1/6R1/7B/8
stipulation h$1
stipulation h$3
condition #C

    Theoretically, this could generate spurious solutions having more than two mates, some possibly by Black. The correct input is given below, but it's probably easiest to use the input above and to manually discard any forbidden solution.

    forsyth 4s3/4p2p/2pkpp2/8/1K2b1P1/6R1/7B/8
option FirstToMove black
play help 0.5 test not $
play help 0.5 test $ test not $$
play help 0.5 test not $
play help 0.5 test not $
play help 0.5 test not $
play help 0.5 test not $
play help 0.5 test not $
play help 0.5 test $ test not $$
condition #C

    Testing the possibility H#2/H#2 will find a cook, Chris Tylor is aware of it.

As you can see, provisional mates can be stipulated but they are not currently notated mid-move by Jacobi for the following technical and practical reasons:

  1. In Masand, provisional checks are not notated mid-move by Popeye.
  2. The symbol "#" cannot appear mid-move in a problem published on Julia's Fairies (which is using Py2Web).
  3. Possible confusion with the true mate aim "#" if the symbol "#" appears mid-move.

Feel free to manually insert the symbol "#" mid-move before publishing.

Solving in parts

Using features from the "Advanced stipulations" section, it is possible to split a proof game into 2 or more parts to be solved separately, possibly on different computers.

  • The example below shows one way to split the demonstration PG 9.5 into two parts.

    stipulation dia 0.5 pieces white Pe2f2g2h2 Sg1 AddPieces
stipulation dia 9.0 forsyth rsbq1bsr/pppk1ppp/2B5/4p3/8/3PSSr1/PPP2PPP/R1BQ1RK1
condition Circe RexInclusive

    stipulation dia 0.5 pieces white Pa2b2c2d2 Sb1 AddPieces
stipulation dia 9.0 forsyth rsbq1bsr/pppk1ppp/2B5/4p3/8/3PSSr1/PPP2PPP/R1BQ1RK1
condition Circe RexInclusive

    In the first part, the first line fixes the right-side pawns and knight for the first halfmove, so only 10 white moves will be tested (out of 20). The second test fixes the left-side pawns and knight.

This trick needs to be adjusted for some conditions: In CavalierMajeur, we need to fix N instead of S. In BerolinaChess, we need to fix BP instead of P. In AllInChess, there are 40 first moves, so maybe one part should fix Black, and the other part should fix White. Splitting Chess960, Bicapture, or Cannibal is a bit more difficult.

Manual intelligent mode

For problems with a mate or stalemate aim, Popeye, WinChloe, Alybadix and other programs offer an "intelligent mode" which first tries to find final positions and then attempts to reach them. Jacobi doesn't have an intelligent mode, but if there aren't too many possible final positions, then maybe they can all be manually tested. A final position can be specified by adding a "test dia" command at the end of the problem. Undefined pieces (letter X) and the PG option AddPieces help express just the mate/stalemate matrix.

  • P1291992 by George P. Sphicas in 2007 is a ser-h#24. As pointed out by Mario Richter in the PDB comments, the possible squares where the black king can be mated seem to be d5 and g3. This gives two problems to test (the first one represents the intention).

    pieces white Ka7 Bf6 Pa3e2f3f5 black Ke3 Pa2a4a5a6
stip ser-h#24
test dia pieces white Pe4f3f5 Bf6 black Kd5 Xc4c5c6d6 AddPieces

    pieces white Ka7 Bf6 Pa3e2f3f5 black Ke3 Pa2a4a5a6
stip ser-h#24
test dia pieces white Be5 Pe2f3 black Kg3 Xf2g2h3h4 AddPieces

Because of the risk of making errors, problems verified in this way should probably be labeled HC+ (human-computer checked) instead of C+.