CECP ('WB protocol') specs

[Ferdy]

The bit about GUI defaults and commandline options is out of place in a document describing a protocol.

Why not? protocol is about GUI (at least Winboard GUI) and engines. It does not hurt describing like that if the purpose is to make it more understandable.

It's out of place because the protocol description isn't the right place to discuss implementation details and idiosyncrasies of a particular GUI (even if it is X/WinBoard, which is arguably the reference implementation):

Note that by default the GUI is set to play variant normal or FIDE chess.

So a GUI specifically designed for playing Shogi is non-compliant because it's not set to play "variant normal" by default? Of course not, but that's what the text implies.

That is why it is in the note it is intended for winboard.

[hgm]

What it boils down to is that the GUI is allowed to assume anything if there was no explicit variants feature. It is up to the GUI designer whether he assumes engines play "normal" or "xiangqi" by default,or whether he wants to allow the user to configure this or not. So the text could be:

Not listing "normal" amongst the variants implies the engine will not be able to play orthodox Chess. It is up to the GUI to decide what it can order the engine to play if they did not receive any variants feature at all.

This would formally allow GUIs to send 'variant' commands to v1 engines, presumably instigated to do this by a user that knows what variants the engine can play from the latter's README file.

[kbhearn]

contentwise it's starting to look pretty decent. it definitely needs a table of contents though so people who are looking for information that's in the appendix don't have to scan the whole document to figure out where it is :)

the dark-red highlight of black text is very hard to read in the features table. a different color scheme would be nice there

[hgm]

It seemed more efficient waiting with making an index until the document itself was finished. I can of course also put hyper-text links in it where commands refer to each other, or from the features table to the discussion of the corresponding command. The document should not lose too much of its accessibility on printing, however.

In fact I used only 50% saturated red (#FF8080), but apparently displays differ a lot, so I will change it to #FFC0C0 (and what is now #FFC0C0 to #FFE0E0).

[Evert]

What it boils down to is that the GUI is allowed to assume anything if there was no explicit variants feature. It is up to the GUI designer whether he assumes engines play "normal" or "xiangqi" by default,or whether he wants to allow the user to configure this or not. So the text could be:

Not listing "normal" amongst the variants implies the engine will not be able to play orthodox Chess. It is up to the GUI to decide what it can order the engine to play if they did not receive any variants feature at all.

This would formally allow GUIs to send 'variant' commands to v1 engines, presumably instigated to do this by a user that knows what variants the engine can play from the latter's README file.

But even if a GUI assumes that engines play Xiangqi, it must still send "new/variant xiangqi" to be compliant because the "new" command explicitly sets the current variant to "normal" (or at least I think it did in the original specification document), right?
I ask because 't is up to the GUI designer whether he assumes engines play "normal" or "xiangqi" by default' sounds like the default variant that is set after receiving "new" is undefined by the specification.

As an aside, the way I would prefer things to work is

• The engine starts out in variant "normal"
• "variant X" switches the current variant to X (effective immediately, but generally only makes sense at the start of a game)
• "new" starts a new game in whatever the current variant is.
• To switch back to "normal", the GUI would send "variant normal".

I guess that will break things that depend on the current scheme though...

[hgm]

But even if a GUI assumes that engines play Xiangqi, it must still send "new/variant xiangqi" to be compliant because the "new" command explicitly sets the current variant to "normal" (or at least I think it did in the original specification document), right?

Right.

I ask because 't is up to the GUI designer whether he assumes engines play "normal" or "xiangqi" by default' sounds like the default variant that is set after receiving "new" is undefined by the specification.

OK, then that should be formulated clearer. 'By default' here was intended to mean in absence of a "feature variants" command, not in absence of a "variant" command.

As an aside, the way I would prefer things to work is

• The engine starts out in variant "normal"
• "variant X" switches the current variant to X (effective immediately, but generally only makes sense at the start of a game)
• "new" starts a new game in whatever the current variant is.
• To switch back to "normal", the GUI would send "variant normal".

I guess that will break things that depend on the current scheme though...

Indeed, that would not be compliant with the existing spec. I am not against explicitly repeating parameters at the start of every game, though. It would have been better if the variant had been an (optional) argument to "new". That would at the same time solve the problem that specifying a new variant is meaningless during a game.

[Evert]

Indeed, that would not be compliant with the existing spec. I am not against explicitly repeating parameters at the start of every game, though. It would have been better if the variant had been an (optional) argument to "new". That would at the same time solve the problem that specifying a new variant is meaningless during a game.

SjaakII actually starts a new game when it receives a "variant" command and treats "new" as a synonym for "variant normal" (in xboard mode, otherwise it just treats it as I described earlier: start a new game for the current variant).

Actually, that reminds me: the existing documentation states a plethora of things that are ok to send during analysis mode. Would it be possible (given what is current practice in different UIs, which I don't know but could presumably be found out by asking the authors) to limit the list to what would actually be sent during analysis mode (I think setboard and new are theoretically possible but never done in practice?) and deprecate the rest? It would really make things simpler/less daunting.

[hgm]

The original specs gave a restrictive summary of what could be sent: exit, new, usermove, undo, '.', setboard/edit, bk, hint. The latter three were added in v2 (it beats me why...). As basically anything you could want to do in analyze mode would force starting of a new search anyway, not much would have been lost if only the 'exit' command was allowed, and you would always leave analyze mode before giving a command, and then just re-enter it. (It would need a bit different rules for expiration of the effect of in/exclude commands, though.) But that means that implementations can treat any command this way: just abort the search, execute the command, and start a new analysis search. And that sort of removes the necessity to outlaw any command.

I hate over-specification of what you can and cannot do. It is pretty obvious from the function of some commands that they are meaningless in some modes. Like offering draws in force mode, or sending 'move now' when it is not the engine's turn. Should the specs therefore explicitly forbid it? My take on this has always been that you should only forbid things that would cause problems. In that approach there really should not be any limitation at all of what the engine could receive in analyze mode. I could say:

It is recommended an engine would process any command in analyze mode as it normally would, except that the engine should stay in analyze mode. And that GUIs should not send commands other than exit, (user)move, undo, in/exclude and multi-PV related option settings.

That reminds me that I am increasingly unhappy that Multi-PV is just an engine-defined option. Originally I imagined that the GUI needed not be aware of any multi-PV stuff, and that this was just between engine and user: the user could set it therough the Engine Settings dialog, and the Engine Output window would simply display whatever the engine sent as a result of that. This, however, proved very cumbersome and user unfriendly. During analysis one needs to be able to change the multi-PV setting with only a single mouse click, and I added the header in the Engine-output panes for that.

But that broke the assumption that the GUI did not have to be aware of that. So that XBoard now has to check for the existence of an engine-defined option, and manipulate it. The problem is compounded by the fact that I am not happy at all with the UCI type of multi-PV option that fixes the number of PVs, and that my own engines all use a score-window-based multi-PV approach. For which XBoard now has no support at all.

It might therefore be better to elevate multi-PV as a standard feature after all, which promises the support of dedicated commands to manipulate the number of PVs and the multi-PV margin. I am not sure how this can be best implemented, though. Perhaps there should be one command "multipv NUMBER MARGIN" that sets both a limit to the number of PVs and the score difference with the best. And a multipv=N feature that would tell how the GUI should use that command, in particular if clicks of the user on the Engine-Output header should be translated to a change in NUMBER or a change in MARGIN.

[Evert]

The original specs gave a restrictive summary of what could be sent: exit, new, usermove, undo, '.', setboard/edit, bk, hint. The latter three were added in v2 (it beats me why...). As basically anything you could want to do in analyze mode would force starting of a new search anyway, not much would have been lost if only the 'exit' command was allowed, and you would always leave analyze mode before giving a command, and then just re-enter it. (It would need a bit different rules for expiration of the effect of in/exclude commands, though.) But that means that implementations can treat any command this way: just abort the search, execute the command, and start a new analysis search. And that sort of removes the necessity to outlaw any command.

Hmm... yes, I suppose that's true. If I can assume that the GUI will never send stuff that needlessly aborts the analysis, then that may indeed be the best way to handle it.

I guess it would be useful if it were possible to think of engine state more or less as follows:

Code: Select all

FORCE (idly waiting for input)
 - any commands can be sent
PONDER (waiting for input while searching in the background)
 - any commands can be sent
THINKING
 - time management/move now/game termination conditions can be sent
ANALYSIS MODE
 - "exit" may be sent

Right now I have a general input loop that tries to handle all commands in all circumstances, which is perhaps not so useful.

I hate over-specification of what you can and cannot do. It is pretty obvious from the function of some commands that they are meaningless in some modes. Like offering draws in force mode, or sending 'move now' when it is not the engine's turn. Should the specs therefore explicitly forbid it? My take on this has always been that you should only forbid things that would cause problems.

I agree with this particular example as being an obviously meaningless case, but there is an argument to be made for the inverse position: by explicitly defining how to behave you remove all ambiguity and it is potentially less confusing.

Is an engine that responds to a draw offer in force mode in violation of the protocol if it does some sort of (static?) analysis before responding by accepting the draw in violation of the protocol?

It is recommended an engine would process any command in analyze mode as it normally would, except that the engine should stay in analyze mode. And that GUIs should not send commands other than exit, (user)move, undo, in/exclude and multi-PV related option settings.

Well, if the GUI is guaranteed to not send anything other than exit/move/include/exclude/multi-PV options then the engine is free to not be able to handle anything else, which is potentially simpler to implement.

That reminds me that I am increasingly unhappy that Multi-PV is just an engine-defined option. Originally I imagined that the GUI needed not be aware of any multi-PV stuff, and that this was just between engine and user: the user could set it therough the Engine Settings dialog, and the Engine Output window would simply display whatever the engine sent as a result of that. This, however, proved very cumbersome and user unfriendly. During analysis one needs to be able to change the multi-PV setting with only a single mouse click, and I added the header in the Engine-output panes for that.

But that broke the assumption that the GUI did not have to be aware of that. So that XBoard now has to check for the existence of an engine-defined option, and manipulate it. The problem is compounded by the fact that I am not happy at all with the UCI type of multi-PV option that fixes the number of PVs, and that my own engines all use a score-window-based multi-PV approach. For which XBoard now has no support at all.

It might therefore be better to elevate multi-PV as a standard feature after all, which promises the support of dedicated commands to manipulate the number of PVs and the multi-PV margin. I am not sure how this can be best implemented, though. Perhaps there should be one command "multipv NUMBER MARGIN" that sets both a limit to the number of PVs and the score difference with the best. And a multipv=N feature that would tell how the GUI should use that command, in particular if clicks of the user on the Engine-Output header should be translated to a change in NUMBER or a change in MARGIN.

This might be a good idea. I've never really looked at multi-pv, but it's on my list of things I'd vaguely like to add at some point in the future.

[hgm]

Hmm... yes, I suppose that's true. If I can assume that the GUI will never send stuff that needlessly aborts the analysis, then that may indeed be the best way to handle it.

The most annoying command in this respect is '.' for the periodic updates, which must absolutely not abort the search, or you would get nowhere. Fortunately XBoard stops sending it if there is no reply. As far as I could see most commands that make sense sort of force you to start a new search. (Things like switching ponder on or off during analysis, or setting another TC for future games, make very little sense.) An exception could be exclusion of a move that has not been searched yet in the current iteration. There you could simply disable the move and cntinue the search.

I guess it would be useful if it were possible to think of engine state more or less as follows:

Code: Select all

FORCE (idly waiting for input)
 - any commands can be sent
PONDER (waiting for input while searching in the background)
 - any commands can be sent
THINKING
 - time management/move now/game termination conditions can be sent
ANALYSIS MODE
 - "exit" may be sent

Right now I have a general input loop that tries to handle all commands in all circumstances, which is perhaps not so useful.

In the example driver I call that aspect of the state the 'activity' (and use IDLE instead of FORCE). I distinguish commands there that can (1) always be handled during search (setting or clearing a flag), (2) must abort the search to be performed in the main loop , and (3) must be ignored until the search finishes, and be processed in the main loop then. Whether a command falls in class (2) or (3) depends on the current activity.

I agree with this particular example as being an obviously meaningless case, but there is an argument to be made for the inverse position: by explicitly defining how to behave you remove all ambiguity and it is potentially less confusing.

Perhaps. But there are race conditions, and 'move now' can cross spontaneous expiration of THINKING, (and thus the start of PONDER), so that receiving move-now during ponder search would occasionally happen without it being anyone's fault. So I think it is safer, and perhaps even simpler, to be prepared to process everything always. The main issue is whether searches should be aborted or not.

Is an engine that responds to a draw offer in force mode in violation of the protocol if it does some sort of (static?) analysis before responding by accepting the draw in violation of the protocol?

My feeling is that it is. Accepting a draw to me is at the same level as playing a move. A static analysis could also detect an only-move situation, (some engines generate the table of legal moves in advance), and playing it in force mode would be a bad violation. We recently stumbled on a case where an engine (actually I think it was Polyglot) claimed a 50-move draw in force mode. I think it should not do that, and either Polyglot has to be fixed to not do that, or XBoard to ignore such claims from engines that are in force mode. Mates and no mating material is one thing, but draw claims are a player decision.

Well, if the GUI is guaranteed to not send anything other than exit/move/include/exclude/multi-PV options then the engine is free to not be able to handle anything else, which is potentially simpler to implement.

But it is the latter I doubt. If all the other commands require you to abort the search, so you can process the command in the main loop, and then start a new search after it, I don't see any simplification from limiting the set of commands.

This might be a good idea. I've never really looked at multi-pv, but it's on my list of things I'd vaguely like to add at some point in the future.

Multi-PV based on a margin is extremely simple to implement: in the root, just do not raise alpha to bestScore, but to bestScore-margin.