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.
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
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
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.
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.
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
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.
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
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
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 $$$
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.
- Problemesis: Usual conditions and Other conditions
- StrateGems: Fairy definitions
- Chess Problem Database Server: Keywords
- Wikipedia: List of chess variants
- Retro Corner: Fairy Rules and Miscellaneous Fairy Rules
- Kobulchess: Fairy pieces and conditions
- Julia's Fairies: Frequently used fairy pieces and conditions
- Phénix: Définitions féeriques (in French)
- Jacques Dupin's Echekk: Conditions féeriques et genres Circé (in French)
- Die Schwalbe: Märchenschachlexikon (in German)
- British Chess Problem Society: Fairy Glossary
- Variantim: Fairy definitions
- David Pritchard: The Classified Encyclopedia of Chess Variants
- G. P. Jelliss: Simple Chess Variants
Chess960, Chigorin, Almost, Knightmate, CavalierMajeur, Berolina
These conditions modify the initial position. They also sometimes modify the set of allowed promotions.
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.)
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.
Each player can move pieces from either player (Jed Stone, 1982).
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.
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".
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).
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:
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:
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.
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:
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.
|GrowingMen / ShrinkingMen||Yes||No||Yes|
|FreeForAll / AllIn||Yes||No||No|
|Multicapture / Unicapture||Yes||No||Yes|
(1) Available but severely buggy.
About the solver
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
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.
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.
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.
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
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:
- In Masand, provisional checks are not notated mid-move by Popeye.
- The symbol "#" cannot appear mid-move in a problem published on Julia's Fairies (which is using Py2Web).
- 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.