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 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 black-to-play, 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, 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 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 unawarded 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

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

  • 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
    
  • 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
    

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.

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 these external links for missing definitions.

HTML

PDF

Chess960, Chigorin, Almost, Knightmate, CavalierMajeur, Berolina

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

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

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

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

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.

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. Below is an illustrative example.

  • By Paul Bissicks, S.N. Ravishankar, and Christopher M.B. Tylor, from The Problemist Supplement 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).

AllowTerminalAutoChecks

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

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.

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. There is only a difference with plain Checking Zigzag — the Stapff and Ultra variants of Jacobi correspond to WinChloe.

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:

WhiteMustCaptureBlackMustCapture
WhiteMustCheckBlackMustCheck
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.

  • Problem 8160 from Phénix 282 (2018) by Bernd Gräfrath 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
Multicapture / UnicaptureYesNoYes
#RYesNoNo
#CYesNoNo
KkYesNoNo
AntiParryYesNoNo
WhiteMustCapture AntiYesNoYes
WhiteMustCapture UltraYesNo(1)Yes
WhiteMustCheckYesNoYes
WhiteMustCheck AntiYesNoNo
WhiteAlphabetic AntiYesNoYes
Blackcap ZigzagYesNoYes
Checking ZigzagYesNoYes

(1) Available but severely buggy.

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
    

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
    

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
    

#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 detected 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.