MultiPV analysis directly from PicoChess UI

[Andrea Gatti]

Hi all,

I would like to describe a limitation I am currently experiencing when using PicoChess for position analysis, and suggest a possible improvement.

My Raspberry Pi is installed inside an all-in-one enclosure which includes a display, speakers, LCD, fan, etc. In other words, my PicoChess setup is not headless, and I interact directly with the Raspberry Pi itself. I never use an additional tablet or smartphone to operate PicoChess.

When I want to analyse a position, I use:

Analysis → Pico → Show

This correctly displays the principal variation currently being analysed by the active engine.

The problem is that, when analysing a chess position, in pretty much all cases it is much more useful to see multiple candidate lines, rather than just one principal variation. At the moment, however, there seems to be no way from the PicoChess UI to temporarily force the currently active engine to analyse more than one PV.

I know that a workaround already exists for users accessing PicoChess from a tablet or smartphone.

By connecting to the PicoChess webserver through Chrome and activating the Watcher, a second engine can be loaded in the Chrome instance. As I understand it, this engine runs on the client side rather than on the Raspberry Pi, therefore avoiding additional load on the Pi itself.

The Watcher interface also provides buttons allowing the user to select multiple PVs, and PicoChess even allows the user to choose which engine should be used by the Chrome instance.

This is a very good solution for people running a headless PicoChess setup or for users who normally interact with PicoChess through another device.

However, it does not really solve the problem for users like me who operate PicoChess directly from an enclosure and do not normally connect an additional device.

Would it therefore be possible to add a similar capability directly to the PicoChess interface?

Ideally, while in analysis mode, there could be a way to temporarily set MultiPV for the currently active engine — for example 2, 3, 4 or more lines — without permanently modifying the engine configuration.

This would make the built-in analysis function considerably more useful, because analysing only one PV often gives a rather incomplete picture of a position.

I hope this use case and possible enhancement can be taken into consideration.

Many thanks for your work on PicoChess.

Best regards,
Andrea

[Johan Sjöblom]

Well described.

Yes, the "web show" is restricted to 1 multipv on localhost. It has been traditionally like this, and its to save CPU just like you noted. And the web show is of course the browser based stockfish, not the compiled selected engine stockfish.

Ideally I would also like to get multipv from both tutor and the chosen engine, especially chosen engine in analysis mode.

The tutor is already multipv (as you probably saw in the turbo button discussion). It would only need a "send to client and show it" mechanism.  The selected engine would probably not consume so much more cpu with multipv = 3, it would just take longer to reach a certain depth. Not sure yet how difficult this is to do, but I have been thinking in the same lines as I would also like to use Picochess for learning and analysing purposes. It would for sure be easier if we first try it only on analysis mode.

// Johan

[Andrea Gatti]

Hi,

Yes I'm on the same idea. In principle it shouldn't be too difficult. You need to add the [+] and [-] buttons that you've already added to other tabs, like the web show, and depending on it, send and UCI command to analyse in multi PV. For example, for Stockfish that would be "setoption name MultiPV value 3" followed by the FEN and "go infinite".

At least this would be for the Analysis mode I think.

[Johan Sjöblom]

Despite the idea being simple it can be challenging to implement. The reason is that there are 2 complex state machines between the web client and the uci communication. The state machine closest to the engine determines which engine to ask for analysis or a move and when to start or stop the analysis. It keeps the picotutor 2 engines and the selected engine in sync with the main state machine in picochess. That took me a year to design. And yes the main state machine is more like an event handler. It listens to everything that happens on the DGT eboard, the web client board, or the web menu, or the clock menu, and it also checks for new engine analysis information using a timer. That is mainly designed by Dirk and the developers before me, but I have made several changes to it.

But lets see, I opened an issue for this so that I can create test code in a separate feature branch: https://github.com/JohanSjoblom/picochess/issues/444

[Andrea Gatti]

Johan, many thanks for picking this up as well so quickly. I feel that we've all done great things over the last couple weeks, you, Dirk, Randy, all the others and me, introducing enhancements and fixes. Of course I'm only testing, so my part is easy :-))

[Johan Sjöblom]

Yes, we are being creative. I do have an idea on how to show 3 lines from the selected engine… I dont know when I have time to fix it, but one of these days it might happen…

[Johan Sjöblom]

With Dirk we made a quite complex feature that I think you would enjoy testing.

It was a long issue discussion and it took a long time to find a solution design,  but here is one conclusion summary:

https://github.com/JohanSjoblom/picochess/issues/432#issuecomment-5030534075

You can pause a game or an analysis and do any temporary thing while you are in analysis mode and then return to that previous checkpoint position and continue.

A similar thing can be done if you do not have any eboard, if you only have a web client. Its the explore button that allows you to do temporary explore on the web client. When you want to return, just click explore off, or sync button. If you have an eboard connected the explore is turned on by default.

— johan

[Andrea Gatti]

Oh wow, this is food for my testing. This evening is going to be interesting.
Stay tuned.

Thanks

[Andrea Gatti]

Hello Johan, Dirk,

yesterday I spent the evening using PicoChess for my analysis on the DGT and making use of the explore function, to continue an analysis branch on the Pi while I had the position fixed on the DGT.

I must say that this is extremely useful and interesting. You basically have multiple analysis on different lines at the same time. A very efficient way to perform analysis. I also made use of the remote_engine while analysing, so I've been able to push PicoChess to its maximum potential.

Everything was smooth, no issues at all.

Thanks to you and Dirk for putting together this great feature!

AG

[Dirk]

Yes Andrea, 

Isn‘t that a great feature!? I really like this and I am glad that we came up with this practical approach after a long discussion and that Johan could implement this feature. It is one of the features that makes PicoChess so unique and special in my opinion.

Dirk

[Johan Sjöblom]

Wow, really nice that it works. It took some effort to get it right. It is intended for learning. I was thinking that if you have a game you want to study you start with one of the "enter moves" modes where tutor analyses if tutor is ON, and otherwise the selected engine analyses. When you reach an interesting point you switch to analyses mode, and do whatever exploration, and then return back to the previous position. I think analysing with physical pieces on a DGT board is a better learning experience than to analyse on a web interface, as you also use your muscle memory. But of course that may be just because of my age that I think its better learning ;-)

And while you are on the eboard analysing you can always use the web client to explore any sideline and let the web stockfish analyser run. Next time you make a move on the DGT board the web client will re-sync. At least that was the intended design. So the web client is an extra exploration board where you can test sidelines withut interrupting the current position analysis going on at the DGT board and in the picochess backend. (and you can have several web clients open at the same time)

It might be quite difficult to write a manual for this, but if you manage to describe how to use this we will definitely include it (as I will also include your description on the remote tutor)

-- Johan

[Andrea Gatti]

Hi,

yes that is one use case. My specific one is to use this feature while I study Chess Books.

1- Prepare the specific position on the DGT

2- Scan and import the position in PicoChess

3- Put PicoChess in Analysis mode and use an engine - local or remote

4- Make sure Explorer is on

5- Follow the lines on the book moving the pieces on the DGT until you don't understand why the book is not speaking about your fantastic line, by which you deserve the world champion title...

6- Begin exploring your own line on PicoChess while leaving the pieces untouched on the DGT

7- Realize that you line was an awful blunder

8- Resync PicoChess with DGT at the point that you left before, and continue studying. You better study.

Does it make sense as a use case?

If yes, I can try and pull something together in the same form of the Manual for the remote engines and tutor.

[Johan Sjöblom]

Yes it makes sense. And a manual would be really valuable. 

You basically use the web client as a free exploration board that does not disturb the picochess backend or the DGT physical board position.

I realized already in your earlier posts that we are missing one feature detail:

- If you are already in analysis mode:

- then you cannot set a checkpoint on the current position. At the moment the solution design is that it sets a checkpoint when you enter analysis mode.

- if you could store a checkpoint while in analysis mode, you could also do the exploration on the physical DGT board (step 6 on the DGT board instead of on the web client)

- Then you would be able to return to that checkpoint when you want
Not sure how to design an easy to understand menu choice to do this. But technically we can store a checkpoint, and ask it to be returned. At the moment that is what the system does when you enter or leave the analysis mode.

-- Johan

[Andrea Gatti]

Right. My use case in fact is slightly different from yours, because I'm already in analysis mode.

But this is not an issue, and I don't think we need to modify anything:

a) If you're playing - like in your example - the checkpoint is necessary and because you switch to analysis, and then go back to playing.

b) If you're already analysing like I do, I don't need it - the checkpoint is basically the piece position on the DGT which I don't touch

I could document both use cases in the manual.

OK?

[Andrea Gatti]

...additional points to my previous reply:

I just realized that we may have 2 other use cases:

c) Replay of saved PGN file without a DGT board

d) Replay of a saved PGN file with DGT connected and therefore moving the pieces according to the PGN

I'm not sure what would happen in those 2 other cases, and if anybody knows or has tried.. maybe we'll need to document all four cases?

(ps: we're making it so full-featured that we'll probably need to call it PicoChess Pro one day LOL)

[Johan Sjöblom]

I have earlier implemented a PGN replay mode. You can start it with or without ”waiting for tutor”. If you chose tutor it will wait until depth has reached at least 15 before auto-making the next move. That guarantees the quality of the tutor analysis and announcements like ! Or ? For every move, but is a little bit slower.

You can chose replay when yor game has finished, or upload an existing pgn from your phone. Maybe I need to add more ways to start replay.

The PGN replay mode works both with and without DGT eboard ( c and d)

— Johan

[Andrea Gatti]

Excellent. Will try and test all of these tomorrow. Thanks.

[Johan Sjöblom]

On a) and b) you mentioned. I can see that you understood the similarity between exploring on the web client and exploring on the physical board. Indeed, when you explore on the web client the backend picochess position and the DGT eboard physical pieces represent the "check point" that you go back to when you press sync or click the explore button off, or when a move is being made on the physical chess board. I think the later one here is the main use case, it always returns to the sync position if something in the anchored check point on the board changes.

When we go into analysis mode (from another mode obviously), a checkpoint is always stored in the picochess backend. After analysing you can return to that checkpoint and previous mode by clicking on the "analysis mode again", and you will get "set pieces" guidance and hear an "OK" sound when you have set the physical pieces back to how they were. If you came from mode normal you can continue your game, if you came from an enter move mode (hint on, eval score) you can continue to enter moves.

I guess we do not need the use case when you are already inside analysis mode, but if you entered analysis mode without any intention to go back to any specific chess position, we could have a "store and restore checkpoint" function to be used only when in analysis mode. But if its not a very important use case such user interface changes will only make things more complex and confuse the users. The current main use case is to come from normal play, just select analysis mode, do whatever you want on the physical board, and then click return from analysis mode, and the position will change back to the checkpoint and the mode will go back to whatever it was before analysis mode.

-- Johan

[Andrea Gatti]

I agree ajohan, we don't want to overcomplicate it.

[Andrea Gatti]

Hi Johan, Dirk,

I am now starting to write the manual section about using PicoChess as an analysis/study tool, including the checkpoint/explore functionality.

Before I document the procedures, I would like to verify a few UI details with you, because I want the steps to be exact and then perform one final round of testing myself.

My current understanding is the following.

When entering Analysis mode from another mode, PicoChess automatically stores a checkpoint containing the current position and the previous mode. The user can then freely explore on the physical DGT board. When the analysis is finished, PicoChess can return to that checkpoint, guide the user to restore the physical position and then resume the previous mode.

Could you please confirm the exact UI sequence for this?

In particular:

1. What is the exact menu/button sequence used to return from Analysis mode to the stored checkpoint?

2. When returning, does PicoChess always automatically:

   • restore the previous mode;

   • enter the “set pieces” guidance;

   • wait until the DGT position matches the stored checkpoint;

   • play the OK sound once the position is correct?

3. Does this mechanism work identically when Analysis mode was entered from:

   • Normal mode;

   • Enter Moves / Hint / Eval modes;

   • PGN Replay mode?

4. Regarding the Web Explore function: my understanding is that while Explore is ON, the web board can be used independently and the PicoChess backend + DGT position remain the synchronization point. The web board returns to that position when:

   • Explore is switched OFF;

   • Sync is pressed;

   • a move/change is made on the physical DGT board.

Is this correct?

5. Finally, if there is no DGT board connected, is the behaviour conceptually the same, with the PicoChess backend position acting as the reference/checkpoint for the web client?

I am asking these questions because I want the manual to describe the actual UI workflow, not only the underlying concept. Once you confirm this, I can reproduce the procedures and do a final test pass before writing the final version.

Thanks!
AG

[Randy Reade]

Big thanks to you, Andrea, for adding to the PicoChess documentation. It has not kept up with development over the years. Hopefully we can someday get a unified, updatable manual pulling together any relevant info from the original documentation, Dirk's numerous v3 posts explaining his improvements, Johan's recently drafted manual and your documents. This would be a huge contribution to the community.

Randy

[Johan Sjöblom]

Yes, a big thanks from me as well Andrea. This is very very useful. I was actually hoping I could ask the AI to combine all the manuals to one, and then when we are happy with the English UK version we would ask for a translation into Italian; Spanish, German etc and ask native speakers to check them. But I feel its a good idea to get a structure we are happy with in one language before we start translating.

Andrea, Your overall understanding is correct, with a few details. I asked my development AI to read the code, read my notes, and check the actual functionality and answer your questions :-)

To enter temporary physical-board Analysis:

1. Open the web menu using the ⚙ Menu button.
2. Select Mode.
3. Select Analysis.
4. Picochess changes to Analysis mode and automatically saves the position, complete move stack, previous mode, play side, game state, and clock values.
5. Analyse freely using the physical board.

To return:

1. Open ⚙ Menu.

2. Select Mode.

3. The normal Analysis tile is now replaced by:

   ↩ Return to previous mode

   For example, ↩ Return to Play or ↩ Return to Enter Moves · Hints.

4. Select that Return tile.

This return command currently exists in the web Mode menu. It is not a separate button on the ANALYSIS tab or a command in the physical DGT clock menu.

An ordinary mode change away from Analysis has a different meaning: it keeps the current analysed position and discards the checkpoint. It does not restore anything.

What happens during Return

Picochess performs these actions in this order:

1. Restores the logical checkpoint, including the exact position and move stack.
2. Stops analysis output while physical synchronization is pending.
3. Compares the physical DGT position with the checkpoint.
4. If they differ, announces Set pieces and waits for the physical board to match.
5. It may provide square-specific correction guidance while waiting.
6. Once the physical position matches, Picochess emits one Position OK / OK confirmation.
7. Picochess automatically returns to the mode saved in the checkpoint.

Two qualifications are important:

• If the physical board already matches the checkpoint, the Set pieces phase is skipped.
• The previous mode and clock values are restored, but the clock is deliberately left stopped. Returning to Play does not automatically restart the playing clock.

The code protects completion as a single transaction, so repeated board scans or duplicate Return requests should not produce multiple OK confirmations. Whether the confirmation is audibly spoken depends on the configured sound/voice setup; Picochess emits one Postion OK confirmation.

Modes from which Analysis can be entered

The checkpoint mechanism applies to every successful transition from another mode into Analysis.

• Play / Normal: Supported. It restores the game, play side, clocks and Play mode. The clock remains stopped.
• Enter Moves · Hints: Supported. It restores the move stack and returns to that mode.
• Enter Moves · Score: Supported in the same way.
• Other non-playing modes: The generic position and mode restoration applies.
• PGN Replay: Position, move stack and PGN Replay mode are restored. However, replay autoplay is stopped when leaving PGN Replay and is not part of the checkpoint. Therefore, describe this as returning to a paused PGN Replay, not automatically resuming autoplay.

PGN Replay is the case I would particularly include in your final manual test pass.

Web Explore

Your understanding is substantially correct. Web Explore is browser-local and independent of the backend checkpoint mechanism.

While Explore is ON:

• Legal web-board variations remain local to that browser.
• They do not change the Picochess backend, the DGT position, or another browser’s Explore variation.
• Web Stockfish can analyse the local variation.

The web board returns to the Picochess live position when:

• Explore is switched OFF;
• Sync is pressed;

• an accepted move or position update arrives from the physical DGT board.

A transient piece lift by itself is not necessarily a position update. The reset occurs when PicoChess accepts and publishes the changed DGT position or move.

One small UI distinction:

• Switching Explore OFF also synchronizes the diagram.
• Pressing Sync synchronizes the diagram and switches Explore OFF.
• A new DGT update resets the explored variation to the new live position but normally leaves Explore ON, ready to explore from that new anchor.

Without a DGT board

Both facilities still work, but they remain distinct:

• Web Explore: The Picochess backend position is normally the live reference. Explore creates a disposable browser-local variation; switching it OFF or pressing Sync returns to the backend position. Explore is not automatically enabled in a no-board setup because the web board is also the normal live move-entry surface.
• Analysis checkpoint: Entering Analysis still saves a backend checkpoint. Return restores it and automatically returns to the previous mode. Because there is no physical board to correct, synchronization completes immediately—there is no Set pieces phase.

The Web Explore anchor is of course not technically a checkpoint as you know, its just the backend picochess server and the DGT board. 

-- Johan

[Andrea Gatti]

Guys, many thanks for your kind words.

@Johan, I also use AI to pull together the final draft of the documentation, telling my AI friend what I have understood, sharing the tests that I do and sometimes sharing our posts if I'm unsure of my own understanding!

Regarding your notes, the PGN Replay is exactly one of the areas (use case c and d) where I got stuck and I was unsure about. The rest of the use cases are now pretty clear to me.

I'll now work on the new chapter of the users' manual, using the same format already used for the remote engines. At a given point, you're right, we'll need to ask AI to pull together the various sections and make a final, comprehensive document. But I feel we're still pretty far away from that stage.

I also would like in a second version, to add some pictures. We all know that pics are worth a thounsand words.

Thanks!

AG

[Johan Sjöblom]

I think the big question for the user being in the Analysis mode is how to return. Basically there are two ways out:

1. click the "return to previous mode" - This will send you back to the checkpoint and to the mode you had before you entered analysis.

2. click any other mode tile to "escape" the checkpoint and continue from where you happen to be on the eboard (or web client) at the moment. This is for when you do not want to go back to the checkpoint. Simply click the mode you want to go to instead of clicking on the "return to previous mode".

-- Johan

[Johan Sjöblom]

If you already combine the manuals we simply replace the existing manual in the repository with your new version. And yes, a picture is worth a million words...

At some point I also want to translate the new modernized menu... I need to make a separate translation mechanism for that. Its issue 436 https://github.com/JohanSjoblom/picochess/issues/436

And the other on my todo list is to get the new menu working equally to the clock menu, despite working on the modernized menu since March its still on my todo list :-) https://github.com/JohanSjoblom/picochess/issues/424

-- Johan