PGN-Engine-Analyzer - analysis of PGN files annotated by engines

external link:


Stockfish
development versions

the latest versions of Stockfish

internal links:


Evaluation-Relevance-Reduction

move and position evaluations including engine WDL analyses and interactive form

modification of TCEC-PGN-files

in Notepad++ for Aquarium und Scid vs. PC

keyboard layout for chess annotation

with special symbols in Windows programs via AutoHotkey script

article links:


article start

highlights

contents of the programme package

overview

automatic variation entry in PGN file via engine

processing and analysis of the PGN engine variations and annotations

insertion of game move comments into the PGN file

insertion of variation move comments into the PGN file

ASCII/Unicode characters in PGN files

position evaluation symbols

move evaluation symbols

move-square colours

move arrows

excursus: move-square colours and coloured move styles in Aquarium especially for users of the Aquarium GUI

removal of irrelevant game move variations

reduction of variation moves

printing Scid vs. PC PGN files via LibreOffice Writer

replacement of NAG values and annotation modules

replacement of NAG values

replacement of engine related modules

replacement of mate announcements

replacement of chess piece text modules

clipboard mode

HTML mode

mate announcements

evaluation relevance reduction

programme selection for PGN files

parameters and checkboxes

GUI background colour

PGN-Engine-Analyzer programming


PGN-Engine-Analyzer - download:


zip-Icon

programme PGN-Engine-Analyzer
24th development version from 12th November 2024
ZIP file [6.4 MB]: PGN_Engine_Analyzer.zip
in the PGN-Engine-Analyzer GUI click on the button 'English'



Preliminary note:
This article was written in the original in German. The English translation comes from the author too. A sufficient quality of the translation cannot be guaranteed.

24th development version from 12th November 2024



PGN-Engine-Analyzer -
a Windows programme that the world doesn't need,
at most some adventurous users
of chess engines and PGN files


1) Highlights:



2) Contents of the programme package:



3) Overview:

In order to obtain all analyses from a pure PGN file with one or various games without variations and comments via PGN-Engine-Analyzer, a chess engine must analyse the PGN file in a first step and a new PGN file with these analyses must be created. This is done in the PGN-Engine-Analyzer start GUI in the upper left area under the heading 'automatic variation entry in PGN file via engine'. Attention: Before the first start, the engine must be installed correctly. For more details, see the following chapter.

In the second step, PGN-Engine-Analyzer can then unfold its actual capabilities by evaluating this new file and then creating either a new extensively commented PGN file, an HTML file for viewing in the browser or a spreadsheet for viewing in LibreOffice Calc. Of course, all 3 alternatives can also be done simultaneously. For this purpose serve in the PGN-Engine-Analyzer GUI the parameters on the right-hand side under the headline 'modification of the PGN variations file via analysis elements' for the new PGN file and on the lower right-hand side the checkboxes 'data → HTML' for the HTML file and 'data → clipboard' for the spreadsheet. All setting options and information offers on the left side of the GUI under the heading 'PGN variations analysis: parameters - information' concern all 3 analysis options.


4) Automatic variation entry in PGN file via engine:

Not all PGN files are structurally identical and can be correctly interpreted by PGN-Engine-Analyzer. If the program handles a PGN file incorrectly, it is therefore recommended that you first open the file in Scid vs. PC and then export it using the following options:

Space after Move Numbers: Yes
Export comments: No
Strip square/arrow mark codes from comments: Yes
Export Scid Flags: No
Indent comments: No
Export variations: No
Indent variations: No
Insert newlines every 80 chars: No
Column style (one move per line): No
Symbolic annotation style: ! +=
Convert null moves to comments: No
Character encoding: Utf-8.

Before pressing the 'start' button for the first time, the 'user options' should be called up and the engine to be used, which is able to handle the UCI protocol, should be selected there via 'engine programme path definition'.

After selecting various options and 'save', the 'UCI engine options' should be called up. This establishes contact with the engine and checks its ID. When first called, the original settings of the contacted engine are to be adopted. It also retrieves the engine options and lists them in the GUI. The engine default settings can then be modified in the 'user entry' column.

All user and engine options are stored by PGN-Engine-Analyzer. They can also individually be saved under a special file name via 'parameters: ... save' in the PGN-Engine-Analyzer GUI at the bottom left.

With the 'UCI engine options', there is a trick to keep in mind: Saved options contain an engine ID that presumably does not apply to new engine versions. So it is not enough for the user to save new engine versions under the old engine path and name in the Windows directory so as not to have to keep changing the default settings. Rather, he must still call up the 'UCI engine options'. PGN-Engine-Analyzer will then ask if the default engine settings should be used. If this is answered in the negative, however, it must be carefully checked whether the old user settings are still correct. In particular, it may be necessary that an NNUE name no longer applies. With Stockfish, it will then be sufficient to simply empty the user field in question, because the NNUE network integrated into the engine will then be activated automatically.

The 'user options' GUI essentially consists of the two parameter groups for regular and null move variations.

The latter pass the right of move to the opposite side. They matter in the analysis in order to become aware of the opponent's threats in the case of inaction and to derive position optimisations from them. They are processed by PGN-Engine-Analyzer in the course of move annotation for analysis PGN files, but not in the context of the creation of move evaluation symbols for game and regular variation moves, HTML files and clipboard data

The parameters are largely self-explanatory.

The 'analysis from/to move no.' input fields can contain multiple move entries, even in the wrong order. Example: '12-16 3'. Moves 3 and then 12 to 16 are analysed here. If the "end of game" option was also selected, all moves from 12 to the end of the game would be analysed in addition to move 3.

In the engine analysis stop variants, "depth modification with pieces value reduction" is an option that is not offered by engines and is an innovation of PGN-Engine-Analyzer. The depth of analysis increases or decreases as the material value of all pieces on the board decreases between the starting position and the king-king position.

After selecting a depth option, you should later check whether the engine has actually adhered to the entered depth number or deviated from it. This can happen.

Another innovation are the percentage analysis-test completion intervals. Essentially, it is a question of how frequently the running engine outputs should be examined during the analysis to see whether the analysis has been completed. This is because such examinations cost processor power.
An example to illustrate this: Even a fixed analysis time does not prevent an engine from outputting a final variation in an extremely short time and without waiting for the specified duration to expire, if only one move is possible. In such a case, should we wait until the regular expiry of the fixed analysis time before registering this variation? If, for example, the number '10' should have been entered in the parameter '1st analysis termination test interval from 0% until', the (only) variation will probably already be registered after 10% of the fixed analysis time and a subsequent engine analysis can be initiated. Whether the parameter '10' would make sense in this example depends on the absolute duration of the fixed analysis time. The greater this is, the lower this percentage could be selected. After all, 10% of 100 milliseconds is short, while 10% of 100 seconds is too generous.
The analysis termination test intervals of the individual parameters can be determined with the tool in the folder 'Intervall Funktion'-'English'.
With a fixed analysis duration the full extent of the intervals with 100% is equivalent to this duration, and with all other analysis stop variations to the average analysis times per turn used in the game so far.
The last interval is prolonged beyond the 100% limit.

If a '0' is entered under 'number of variations per move' – regardless of regular or null move variations – these types of variations are not inserted into the game. Theoretically, therefore, an entire game could be plastered with null move variations alone, in order to recognise only threatening moves.
If only a '1' is entered for regular variants, i.e. if only one engine variation is desired per move (single variation mode), the analysis function is considerably restricted, because PGN-Engine-Analyzer can then no longer judge whether and to what extent a game move variation is better than a second-best variation. Positive move evaluation symbols are then eliminated.

Care should also be taken when choosing the colour(s) to the right of 'analysis for'. If one chooses a colour instead of 'both sides’, the analysis function of PGN-Engine-Analyzer is also limited, because then it is not possible to fall back on the evaluation of the best variation of the following move and in case of a missing game move variation for the current move, its evaluation cannot be determined exactly.

If a Chess960 game is to be analysed, there must be a tag [Variant "Chess960"] somewhere in the PGN game header and, of course, a tag with the FEN starting position. This FEN position alone is not sufficient, because although this starting position is then adopted at the start of the game, the programme cannot know that it is Chess960 and consequently will not apply the Chess960 castling rules.

If the checkbox 'information about the ongoing engine analysis' has been selected, some results for the respective moves and selected user option parameters are displayed during the engine work.

In the line with the time abbreviations e, a, w and l, these letters stand for:
e: time spent by the engine;
a: average time spent by the engine;
w: time used by PGN-Engine-Analyzer while waiting for the engine analysis to complete, which should effectively be a little higher because the previous execution of programme code also takes some time during the engine analysis;
l: loss time = w - e, if it is > 0, which is the case for fixed analysis time if the analysis termination test intervals exceed 100%.
w and l can display incorrect values if the system is heavily utilised by the engine and the computing resources for the PGN engine analyser are too low.

For Stockfish the hash load specified by the engine should not exceed 30 or 40% in order to achieve an economic ratio of analysis performance per time duration („Impact of hash on playing strength“). The hash size is set in the 'UCI engine options'.

The sign '»' in front of 'regular variations' or in front of 'null move variations' indicates for which type of variations results were last entered into the GUI.

The way the chessboard is displayed depends on whether the fonts
Chess Alpha 2 (responsible for displaying the pieces and board squares) and
Chess Merida Unicode (responsible for displaying the outer chessboard)
are installed in Windows.

The 'engine priority' determines the amount of computing resources that the computer makes available to the engine. If not all computer threads are selected in the engine options, the priority can probably be set to a maximum of '5'. Otherwise, it should remain in the below-average range in order to be able to work reasonably with Windows and possibly other programmes.

In the text input field to the right of 'engine name', the 'Annotator' tag to be included in the PGN game header is specified. If PGN-Engine-Analyzer finds the module '#Original#' there, it replaces it with the original engine ID. Other information in this text field can include information about engine options, such as the number of threads or the use of Syzygy tablebases.

If 'auto end' has been selected, Windows will shut down automatically after the engine variations have been added to the PGN file and this new file has been saved automatically. The way in which the system is shut down is determined by entering a parameter in the field next to it.
The parameter is a combination of the following values:
0 = logoff
1 = shutdown
2 = reboot
4 = force
8 = power dow
n 16 = force if hung
32 = standby
64 = hibernate.
Several values must be linked bit by bit with the OR operator. Standby and hibernate are ignored if other values are used.

During the analysis by the chess engine you can switch to another window or programme. And in the case of pressing the Esc key, the variation entry is terminated before the next half-move.


5) Processing and analysis of the PGN engine variations and annotations:

The evaluation of a PGN file, which has been provided with variations and comments by an engine, is characteristic for PGN-Engine-Analyzer and is triggered by clicking on 'start PGN variations file evaluation' at the bottom left of the PGN-Engine-Analyzer GUI.

If the checkbox 'continuous information in variation analysis' has been selected beforehand, some results for the respective moves are displayed very quickly during the evaluation.

The engine output is evaluated by PGN-Engine-Analyzer and the analysis results optionally
Of course, the analysis results are assigned to those moves for which engine outputs are available. However, they are also assigned to moves for which this is not the case, provided that these moves have successor moves that were in turn supplied with such information by the engine. However, such analysis results are limited to search depth, evaluation, WDL values, position evaluation symbol and probabilistic game result. Therefore, if engine outputs are only available for one colour, the moves of the other colour can only be analysed to a limited extent.

6) Insertion of game move comments into the PGN file:

PGN-Engine-Analyzer inserts comments into a new PGN file to be created after those game moves for which an engine provides it with data in a PGN variation file. To this, it replaces the text modules utilized by the user in the five-digit format #.....# in the PGN-Engine-Analyzer GUI in the text input field under the heading 'insertion of game move comments', if this option is selected. But the text definition in the supplied 'PGN_Engine_Analyzer.par' file using any editor in line 18 is much more convenient. Of course, PGN-Engine-Analyzer adopts the user-selectable explanatory texts between the modules.

If the English language was selected in the PGN-Engine-Analyzer GUI, English text modules must also be used, otherwise they will not be replaced.

The following text modules are available – in case of duplicity, the first module starting with ‘#W-’ represents a WDL ERR value and the second a user ERR value (cf. chapter 20)):

only in game move comments:



in game and variation move comments:



7) Insertion of variation move comments into the PGN file:

PGN-Engine-Analyzer can also modify and extend the variation move comments coming from an engine. To this, it replaces the text modules utilized by the user in the format #.....# in the PGN-Engine-Analyzer GUI in the text input field under the heading 'modification of engine comments at variation start', if this option is selected. But the text definition in the supplied '*.par' files using any editor in line 17 is much more convenient. Of course, PGN-Engine-Analyzer adopts again the user-selectable explanatory texts between the modules.

Not all of the text modules listed in chapter 6) above make sense here. Only the text modules listed there under the heading 'in game and variation move comments' can be used for variations.

Furthermore, the following can only be used for variation move comments:

#var-n#
number of the variation in the ranking of all regular variations of the respective game move given by the engine; recommended if the checkbox 'removal of irrelevant game move variations' is selected in the PGN-Engine-Analyzer GUI; null move variations are marked with 'N'; if 'insertion of game move comments' has been selected, game move variations are not commented in order to avoid double annotations.


8) ASCII/Unicode characters in PGN files:

Scid vs. PC and Aquarium know how to handle Unicode characters in PGN files. However nitial tests with Arena, Kvetka and Shredder Classic 4 were negative. If one of these last mentioned programmes should be selected as output programme in the PGN-Engine-Analyzer GUI, PGN-Engine-Analyzer will therefore try to convert some used Unicode characters into ASCII characters. At present, this still has plenty of experimental character.

The AqChessUnicode font has chess Unicode characters, especially the chess figurines. If AqChessUnicode is not available, the following download link may be helpful: AqChessUnicode font. This font is also included in the chess GUI Aquarium.

For the explanation of suitable text modules in the '*.par' files '∑' (sum) and 'ø' (average) characters could be used. They can be found under hexadecimal 2211 or decimal 8721 and hexadecimal F8 or decimal 248.

In the text outside the actual text modules, you should use the fixed, non-breaking space character (hexadecimal A0 or decimal 160) in suitable places. Otherwise the chess programs could mercilessly break such text in the annotation on the right side.

If there is a selection of Aquarium according to chapter 21), the normal hyphen should be avoided under certain circumstances and replaced by the protected or non-breaking hyphen (hexadecimal 2011 or decimal 8209). However, if you intend to load the PGN files into Arena, Kvetka or Shredder Classic 4, you should refrain from the non-breaking hyphen due to lack of Unicode character recognition in these programs (as well as from the fixed space character, by the way); you could then use the underscore '_'.


9) Position evaluation symbols:

These are inserted by PGN-Engine-Analyzer automatically in the course of the annotation optionally with the following text modules:


In ASCII mode they are output as follows:


In 1-character-mode, instead of +/=, -/=, +/- and -/+, the following special characters common in chess annotations are output as single character in each case:
⩲, ⩱, ±, ∓.

Only '±' is an ASCII character, the other 3 are Unicode characters. Scid vs. PC and Aquarium will display these 3 special characters correctly if a suitable Unicode font such as AqChessUnicode or Cambria is used. The clipboard output (see chapter 17) also automatically falls back on these special characters, so the installation of such a font is necessary for their correct display.

Information about the position evaluation symbols in the context of user ERR is provided on the left side in the PGN-Engine-Analyzer GUI after clicking the 'info' button under the headline 'position evaluation symbols ...' and 'scheme:'. The user ERR position evaluation symbols inserted by PGN-Engine-Analyzer depend on the adjusted parameters of the evaluation relevance reduction and the position evaluation scheme selected in the PGN-Engine-Analyzer GUI.

In the window after clicking on the button 'complete analysis for one or two special engine evaluations' of course the result of the parameter evaluations for the entered values with regard to the position evaluation symbols can be shown.


10) Move evaluation symbols:

These are inserted by PGN-Engine-Analyzer in the notation behind game and variation moves, provided that the checkbox 'insertion of move evaluation symbols !! / ! / !? / ?! / ? / ??' on the right side of the GUI is selected. They are determined
in the case of optimal game and variation moves by evaluation comparison with the second-best variation move (if available): !! / ! / !?;
in the case of suboptimal game and variation moves by evaluation comparison with the best variation move: ?! / ? / ??.
Without multi-variation mode due to lack of comparison possibilities no positive move evaluation symbols!

Their meaning is:


Limited information about the move evaluation symbols in the context of user ERR for an initial evaluation of 0.00 is provided after clicking the 'information' button under the headline 'move evaluation symbols !! / ! / !? / ?! / ? / ??:' on the left side in the PGN-Engine-Analyzer GUI. The user ERR move evaluation symbols inserted by PGN-Engine-Analyzer depend on the adjusted parameters of the evaluation relevance reduction and the move evaluation scheme selected in the PGN-Engine-Analyzer GUI.

After clicking the button '!! / ! / !? / ?! / ? / ?? - matrix for 2 engine evaluations from +10 to -10' the relevant evaluation differences and move evaluation symbols each according to WDL ERR / user ERR for a variety of engine evaluation pairs are displayed. If you are looking for results for White, select an evaluation from the column on the left margin and a comparative evaluation from the row on the top margin. The intersection field contains the result. The opposite procedure is followed for Black. The diagonal cells from top left to bottom right naturally contain relevant evaluation differences of 0.00, since the two evaluations are identical. Above this diagonal, the values are positive, below negative. The colors used should be self-explanatory.

And if you want information about special evaluations, for example because you have variation evaluations during a manual annotation, but you are not sure which move or position evaluation symbol you should assign, you can click on the button 'complete analysis for one or two special engine evaluations' to see the result of the parameter analysis.

Example for the case of an 'evaluation at 0.75-game-result-probability' of 1.00, an 'evaluation at 0.75-plus-game-result-probability' of 1.195, a '0.75-plus-game-result-probability' of 0.875 each in the PGN-Engine-Analyzer GUI and – after clicking on the button 'complete analysis for one or two special engine evaluations' – entering 1 as a better evaluation, 0 for the worse one and finally 50 for the WDL half moves:
In both schemes, the move evaluation symbol for the better evaluation is '!?', for the worse '?!'.
For 3 out of a total of 4 user and WDL schemes, the move evaluation symbol for the better evaluation is '!!', for the worse '??' and only for the 8-sector user scheme '!' or '?'.
The move evaluation symbol thresholds for the better evaluation reveal that none of the 4 schemes allows a '!!' or '!' for a better alternative move in relation to the move with the evaluation of 1.00 and depending on the scheme either never or only with an alternative move evaluation of at least 1.57 or 2.92 a '!?' can be granted. For the negative move evaluation symbols, on the other hand, there are thresholds throughout so that they can be granted if the alternative move is only bad enough to reach or exceed the respective threshold.

Trial by example: Test the evaluation pair 1.56 and 1 with the button 'complete analysis for one or two special engine evaluations' and you will find the user-BRR move evaluation symbol '–' in each case. So far correct, because the value 1.57 was undercut. New attempt: this time 1.57 and 1 - voila: '!?' and '?!' in the scheme with 7 sectors. And for the evaluation pair 2.93 and 1 both user-BRR schemes agree again.

This does not work with the WDL-BRR, because with each new evaluation, new integral equations are also formed, which prevent comparability with previous results.

Move evaluation symbols without further annotations allow a quick overview of the move quality in the course of a game. To do this, select only the 'insertion of move evaluation symbols ...' in the right-hand area of the PGN-Engine-Analyzer GUI, possibly also the 'move-square colours ...' for Scid vs. PC and Aquarium and – if you attach importance to the evaluation diagram – the 'insertion of game move comments' with a single text module: #e-c-e#. The evaluation inserted for this by PGN-Engine-Analyzer can remain invisible in Scid vs. PC, but (probably?) not in Aquarium. In contrast to Scid vs. PC, Aquarium compensates for this with a sea of colours.

In both programmes, the variation move comments not touched by PGN-Engine-Analyzer in this constellation can be clicked away, so that only the game moves with the move evaluation symbols, possibly with the colours and possibly with the evaluations in Aquarium remain.

If you want to switch comfortably between different selection constellations or text modules for the comments, the choice and storage of 'parameters' with the 'load' and 'save' buttons on the bottom left in the PGN-Engine-Analyzer-GUI is recommended.


11a) Move-square colours for Scid vs. PC and Aquarium:

PGN-Engine-Analyzer colours the chessboard square on which a piece has settled during a move, provided that the checkbox 'move-square colours for !! / ! / !? / ?! / ? / ??' on the right of the PGN-Engine-Analyzer GUI has been selected. The colour selection is made according to the user specifications in the 6 colour code lines under the mentioned checkbox. To determine the colour codes, the HTML Color Picker is recommended.

In Scid vs. PC nothing has to be changed for the colouring of the move-squares. Of course, it is only visible when a game or variation move is selected and involves an evaluation win or loss that corresponds to one of the 6 move evaluation symbols. The move colour codes are invisible in the annotation of Scid vs. PC if 'PGN – Options – Hide Square/Arrow Codes' is checked, but not in the comment editor.

If one should get the idea to take over the move-square colours used by PGN-Engine-Analyzer for markings in the comment editor of Scid vs. PC or to simply use other colours there, one would first be fighting a losing battle. As far as can be seen, Scid vs. PC does not allow changing the colour palette in the comment editor, especially not via the menu Options – Colors. However, if you dare to manipulate Scid vs. PC quasi in the machine room, you might be helped:

Load the file .../bin/scid.gui in the program directory of Scid vs. PC into an editor and search for the line
'variable  colorList {}  markTypeList {}'.
The line 125666 in version 4.25 that follows reads, for example:
'set colorList {cornsilk2 wheat2 burlyWood3 grey50 gray10 rosyBrown mediumPurple1 royalBlue3 skyBlue cadetBlue2 paleGreen2 yellow3 darkOrange1 indianRed3}'.
The colour codes in this line need to be changed, for example as follows:
'set colorList {#00FF84 #80FFC1 #B3FFDA #FFB3FF #FF80FF #FF4DFF blue #00CC69 #CC00CC white black yellow3 darkOrange1 indianRed3}'.

The colour codes preceded by a '#' and immediately followed by a 6-digit HEX number can be changed as desired. After finishing Scid vs. PC, the scid.gui file must be saved. After restarting Scid vs. PC, the new colour palette should be available.


11b) Move arrows for Scid vs. PC and Aquarium:

If this feature is selected, codes for Scid vs. PC or Aquarium are integrated into the PGN files to display move arrows on the chessboard.

For Scid vs. PC, the colours of the move arrows have the following meaning:
blue: the last move made;
green: the best subsequent variation move; if there is no yellow move arrow, this is also the subsequent game move;
white: either the second-best subsequent variation move or - if there are no other arrows apart from the blue one - the subsequent game move for which no evaluation information is available;
grey: the third best subsequent variation move;
black: the fourth best or a worse subsequent variation move;
yellow: the following move, which is not identical to the 1st move of the 1st variation; if it is a variation move, the yellow arrow replaces the relevant white, grey or black arrow;
red: the best answering move if the side now having the move would suspend its move, which regularly indicates a threatening move;
orange: the next move in the game whose evaluation is worse than that of a null move (red arrow);
violet: the second best or a worse reply move if the side now having the move would suspend its move.

As Aquarium only offers 4 different colours, the move arrows are limited to the following colour palette:
blue: the last move made;
green: the best subsequent variation move; if there is no yellow move arrow, this is also the subsequent game move;
yellow: the following move, which is not identical to the 1st move of the 1st variation; if it is a variation move, the yellow arrow replaces the relevant white, grey or black arrow;
red: the best answering move if the side now having the move would suspend its move, which regularly indicates a threatening move.

To avoid a collision of the draw arrows generated by PGN-Engine-Analyzer with the GUI's own draw arrows in Scid vs. PC and Aquarium, it is recommended to select the following setting:
in Scid vs. PC in the PGN window PGN - Options - Hide Square/Arrow Codes yes; in Aquarium click on the fish symbol - Options - Display Options – Board cursor no.

If Aquarium has been selected as the PGN output program, PGN-Engine-Analyzer also creates coloured move styles for the moves according to the move evaluation symbols. For more details, see chapter 12).


12) Excursus: move-square colours and coloured move styles especially for users of Aquarium:

Aquarium is cheap and sophisticated, hence perhaps the most interesting alternative to Scid vs. PC as a programme for displaying the PGN files created by PGN-Engine-Analyzer. Therefore this digression.

Move-square colours from PGN-Engine-Analyzer are also displayed in Aquarium, but limited to the two colours red and green, as this programme only offers only 4 colours for square marks at all.

On the other hand, Aquarium shines in the colouring of moves in the notation. To this it uses all the colours that can be set in the PGN-Engine-Analyzer GUI on the right under 'colour codes of thes move assessments:' and are used for the colouring of the move-squares in Scid vs. PC.

This feature, which is unfortunately not available in Scid vs. PC, takes advantage of the Aquarium comment styles that are normally used during manual annotation using the Aquarium 'Comments' tab and click on the left 'Annotate' button and following click on 'Styles'. The move colours used by PGN-Engine-Analyzer correspond to the 6 move qualities discussed in chapter 10) ("Move evaluation symbols"), whereby such moves do not necessarily have to be provided with a move evaluation symbol in the annotation in order to be able to be colour formatted.

These styles are defined in Aquarium by selecting the tab 'Comments' and click on the arrow symbol under the left button 'Annotate' or simply by using the key combination Shift-S and following click on 'Edit styles'. You will then find yourself in the GUI 'Edit special styles...'. The list there under 'Style name' already contains style categories called
'Good move' (in PGN-Engine-Analyzer synonymous with 'impressive move' - '!'),
'Interesting move' (in PGN-Engine-Analyzer synonymous with 'attractive move' - '!?'),
'Dubious move' (in PGN-Engine-Analyzer synonymous with 'questionable move' - '?!'),
'Bad move' (in PGN-Engine-Analyzer synonymous with 'weak move' - '?').

PGN-Engine-Analyzer uses these as well as the two following style categories:
'Special Style 22' for brilliant moves ('!!'),
'Special style 23' for miserable moves ("??").

The detailed definition of these 6 styles in Aquarium is in principle up to the user. Nevertheless some tips should be mentioned here:

Mouse click on the button 'Edit styles...'.
Selection of a style to be edited in the 'Style name' list, whereby only the 6 styles between 'Good move' and 'Special style 23' are relevant here.
In the 'Substyle' list, 'Move' must be selected.
In the upper right corner the 'Priority' is shown which should not be changed because PGN-Engine-Analyzer uses it.
With selection of the 4 check boxes 'Override global' you can select font, font size, text color and background color, furthermore you can manipulate the font style. At least one of these checkboxes should be selected or at least the font style be changed, otherwise the selected style would not differ from the general style.

The selected styles should contrast clearly the general styles for avoiding confusion. These are set in the Aquarium GUI after clicking on the fish symbol in the upper left corner under 'Options' - 'Display Options' - 'Notation styles...'. The cryptic categories there have the following meaning:
'Main line': game moves;
'Main branch': variation moves;
'Simple branch': subvariation moves;
'Text comment': user annotations;
'Complex branch': first move of a variation - since PGN-Engine-Analyzer marks these moves with move styles, if they are to be praised as good or denounced or bad moves, a clever distinctive style choice should be made here.

Again: all mentioned 6 + 5 = 11 styles should be able to be differentiated (color-wise) reasonably.


13) Removal of irrelevant game move variations:

A game move variation is a variation whose 1st move is identical to the game move. It is irrelevant if the subsequent game move contains an engine-commented variation (which automatically comments on the previous move) and the depth of the engine evaluation of the game move variation (game move depth) is less than or equal to the depth of the engine evaluation in the variation of the subsequent move (subsequent move depth). This is because in this case the subsequent move depth in the variation evaluation extends further than the game move depth, making the game move variation superfluous.

By selecting the checkbox 'removal of irrelevant game move variations', PGN-Engine-Analyzer will remove them completely from the annotation, which serves for clarity. They still exist program-internally and can even play a role in the annotation, for example in the text module #va-no#.


14) Reduction of variation moves:

The variations delivered by Scid vs. PC are sometimes incredibly long. PGN-Engine-Analyzer can therefore reduce the variations to a maximum number of variation moves by selecting the checkbox 'reduction of variation half moves to maximum' and entering the number of variation moves in the text field. This goes hand in hand with the idea that the significance of the engine evaluation evaporates as the number of variation moves increases.

This programme function is actually obsolete, since the variations can already be reduced during their insertion into the PGN file by the engine by entering the 'maximum number of variation half-moves' in the user options. If this should have been forgotten, it can still be improved here.

Even if PGN-Engine-Analyzer removes the last variation move with a hash sign as mate indication, PGN-Engine-Analyzer still recognises mate and corrects the evaluation at the start of the variation accordingly.


15) Printing Scid vs. PC PGN files via LibreOffice Writer:

printing of PGN files generated in Scid vs. PC via export in any editor is unconvincing. A two-column set allows smoother reading of a more compact text. Accordingly, an empty text document with normal page size could be created or loaded in LibreOffice Writer and transformed into a two-column text document via Format - Page - Columns: 2. Then the PGN file must be integrated into the text document via Insert - Insert text from file. If text modules with hyphens are separated unnecessarily despite hyphenation being switched off, the replace function could be helpful, whereby the normal hyphen is to be replaced with the non-breaking hyphen (DEC 8209 – HEX 2011 – for example available in the font Cambria).

When exporting the PGN file in Scid vs. PC, the following options would be useful:

Space after Move Numbers: Yes
Export comments: Yes
Strip square/arrow mark codes from comments: Yes
Export Scid Flags: Yes
Indent comments: Yes
Export variations: Yes
Indent variations: Yes
Insert newlines every 80 chars: No
Column style (one move per line): No
Symbolic annotation style: ! +=
Convert null moves to comments: No
Character encoding: Utf-8.


16) Replacement of NAG values and annotation modules:

This function does not require engine-generated and annotated variations, but simply any PGN file with such text modules. It removes these modules from the entire PGN file and replaces them with new comments.

A selection of the checkbox 'replacement of NAG values and annotation modules' on the right of the PGN-Engine-Analyzer GUI automatically deselects all checkboxes for move annotation and HTML/clipboard.

a) Replacement of NAG values:

NAG text modules are replaced which are introduced with the "$" character and continued with a one to three-digit number up to a maximum of 215. The replacement modules are supplied in the file PGN_Engine_Analyzer_english.nag and are automatically loaded and used by PGN-Engine-Analyzer as soon as it encounters a NAG text module. The replacement modules were taken from the help in Scid vs. PC (Index – NAG annotation values).

b) Replacement of engine related modules:

#gxv → game move = x[st/nd/rd/th] variation (x from 1 to 9)
#sdp → search depth
#ela → evaluation
#egm → evaluation game move
#eom → evaluation optimal move
#pes → position evaluation symbol
#pgr → probabilistic game result
#aeg → absolute evaluation gain
#ael → absolute evaluation loss
#reg → relevant evaluation gain
#rel → relevant evaluation loss
#omr → optimum rate

c) Replacement of mate announcements:

#Mx → mate in x moves
#M1 → mate in one move

#+Mx → White mates in x moves
#+M1 → White mates in one move

#-Mx → Black mates in x moves
#-M1 → Black mates in one move

where x from 1 to 999.

d) Replacement of chess piece text modules:

Generally, the minimum 2-digit and maximum 3-digit input is:

[#][w/b][K/k/Q/q/R/r/B/b/N/n/P/p/C/O/o]

where
the '[...]' brackets are for illustration purposes only and must be omitted during input,
'/' stands for 'or' and must also be omitted during input and
[w/b] may be omitted.

Converted are:

w → white
b → black

K → king
k → ♔

Q → queen
q → ♕

R → Rook
r → ♖

B → Bishop
b → ♗

N → Knight
n → ♘

P → Pawn
p → ♙

C → Castling
O → O-O-O
o → O-O

Example:

attack on the #bKside → attack on the black kingside


17) Clipboard mode:

The checkbox "data → clipboard" in the PGN-Engine-Analyzer GUI makes it possible to transfer a variety of data and analyses from a PGN file with one or various games provided with variation annotations as well as quite a number of additionally calculated data, as described above in connection with the text modules for game and variation move commentary, to the clipboard. From there, they can be transferred to other programmes via Ctrl-V. In particular, a spreadsheet program that evaluates these data for diagrams may be appropriate. Such a spreadsheet document called PGN_Engine_Analyzer.ods, which was created as an ods file with LibreOffice, version 7.6.4.1, can be found in the programme package.

To enter the clipboard data in LibreOffice Calc,
immediately after the work was done by PGN-Engine-Analyzer and return to the PGN-Engine-Analyzer GUI (i.e. after filling the clipboard) select the 1st table 'data',
if necessary, delete all rows with data in the data sheet from row 4 up to the row that contains the entry '*' in the 'GM' column in the bottom cell, or – if the main macro (see below) was started at least once beforehand – start the macro set up specifically for this by clicking on the red 'clear data rows' button in the 2nd 'macro' table,
select the red cell A4 and
then enter Ctrl-V.

You could choose in the dialogue 'Text import' that thereupon appears:
Character Set: Unicode (UTF-16)
Language: English (USA)
From row: 1
Separated by
Tab
Return/Enter
Voila.

Under no circumstances should the option 'Detect special numbers' be selected.

If 'English' was selected as the language in PGN-Engine-Analyzer, the dot is used for decimal numbers in the clipboard. In this respect, it might be advisable to make sure in LibreOffice that under 'Tools – Options - Language Settings – Language' is entered:
Locale setting: English (USA)
Decimal separator key: Same as locale setting
Decimal separator key: [x] Same as locale setting.

Somewhat hidden to the right of the last data line of a game are found the game tags present in the PGN file as well as various evaluations.

Particular mention should be made in the case of the presence of Elo values of both players of the calculation of the expected values (between 0 and 1) as well as furthermore of the calculation of the new Elo values in the event of the presence of a meaningful game result. The calculation was thereby based on the formulas of Jeff Sonas, 'The Sonas Rating Formula – Better than Elo?'

The 2nd 'macro' table contains the 'macro start' button under a chessboard. Click on it to start a macro with 3 windows, provided that the macro has been authorised under Tools - Options - LibreOffice - Security - Macro Security - Medium/Low. The position and size of the windows can be set in cells H4 to M4 of the ‘macro data’ table. In particular, the window with the move list can be moved from the left to the right edge of the screen.

Clicking on a move cell in the move list table displays the chess position after this move on the board, as well as - if available - detailed information about this move to the right of the board and move arrows about the last move and the variations of the subsequent move. Such information is available if the move selected in the move list has a non-grey background. Green and red coloured backgrounds indicate clearly good or bad evaluations.

The colours of the move arrows have the following meaning:
blue: the last move made;
green: the best subsequent variation move; if there is no yellow move arrow, this is also the subsequent game move;
white: either the second-best subsequent variation move or - if there are no other arrows apart from the blue one - the subsequent game move for which no evaluation information is available;
grey: the third best subsequent variation move;
black: the fourth best or a worse subsequent variation move;
yellow: the following move, which is not identical to the 1st move of the 1st variation; if it is a variation move, the yellow arrow replaces the relevant white, grey or black arrow;
red: the best answering move if the side now having the move would suspend its move, which regularly indicates a threatening move;
orange: the next move in the game whose evaluation is worse than that of a null move (red arrow);
violet: the second best or a worse reply move if the side now having the move would suspend its move.

Only limited evaluation information is offered when variation moves are clicked on in the variation window. And no evaluation information is available for moves that only have a grey background colour in the move window.

If a move cell is selected in the table of variations, the current board position is displayed and, to the right of it, evaluation information about the first move of the variation in question is shown, as well as by arrows the variation move that took place (blue) and the subsequent (green) variation move. An exception applies if you click on the 1st move or on one of the subsequent and colour-coded moves of a game move variation, provided that this move was actually made in the game and evaluation information is available for it. In this case, the program automatically jumps to this game move in the move list, with the result that the complete information is shown as if this game move had been selected in the move list.

Game and variation moves that were last clicked on are marked with a right-hand border.

To avoid unnecessarily restricting the tables in the 3 macro windows, it is recommended to switch off all bars in the View - Toolbars menu and possibly doing the same in the View - Headers menu.

The macro is only ended when the ‘macro end’ cell is selected in the 'macro' table and information about the end of the macro is then displayed to the right of it. However, as 3 windows are still open despite the end of the macro, 2 windows can be closed by pressing Ctrl-W twice.

Unfortunately, the macro runs rather slowly. This applies in particular to changes to the board position. A fast computer is an advantage. An alternative for constantly waiting and annoyed users is to use the move arrows, possibly also the move square colours, in PGN files for Scid vs. PC and Aquarium. In addition to the speed increase, this application also has the advantage that an engine can be started in the game positions.

The diagrams in the 7 diagram tables of PGN_Engine_Analyzer_english.ods are created automatically from the clipboard data inserted in the first table without the need to rely on a macro. This automatic function works either for all games in the range up to data line 1000, which can of course be extended, or for a range of moves from it to be selected by the user (see the green cells in table 'dia data', line 1). If the diagrams should become confusing due to high numerical values, the diagram representation can be restricted to the chosen move area by selecting lower numerical values in the 5 green cells in row 4 of the 'dia data' table.

In the 'consistency' spreadsheet it is checked whether various clipboard data supplied by PGN-Engine-Analyzer really correspond to the intended logic of the program code. The data taken over from PGN-Engine-Analyzer and calculated in the table (yellow) are located in adjacent columns. Should there a contradiction arise, the calculated yellow cell will be colored red. In LibreOffice Calc the cell references of the yellow cells can be clearly displayed via Tools - Detective - Trace Precedents / Dependants.

This spreadsheet 'consistency' is not very helpful for the normal user, but it consumes a lot of storage space or CPU performance. It can be deleted in case of dissatisfaction.

If only clipboard mode is selected in the PGN-Engine-Analyzer GUI, possibly in conjunction with HTML mode (chapter 18)), no modified PGN file will be saved.


18) HTML mode:

The checkbox 'data → HTML' in the PGN-Engine-Analyzer GUI causes the output of the clipboard data mentioned in chapter 17) to a HTML file inclusive PGN game header, PGN tags of the PGN file if available, various game evaluations as well as diagrams with the probabilistic game results for each single game. Only those game moves are listed for which engine evaluations entered by PGN-Engine-Analyzer can be found in the loaded PGN file or for which PGN-Engine-Analyzer has exceptionally formed phantom evaluations (see chapter 6), text module #eva-s#).

PGN-Engine-Analyzer uses the PGN_Engine_Analyzer.html file cited in chapter 2), which contains the necessary CSS instructions. PGN-Engine-Analyzer contributes the basic framework and the analysis data.

The newly formed HTML file must be saved in a folder that also contains the files
jquery.flot.js,
jquery.js,
jquery.flot.barlabels.js,
LICENSE.txt
located in the HTML folder. Otherwise, the charts are not displayed.

The file can be scrolled up and down using the pink-coloured arrow buttons.

The moves are color-coded in accordance with the move evaluation symbols. If there is none, it remains with the basic colors white or grey. In the supplied file PGN_Engine_Analyzer.html which is modified during the programme run and then has to e saved under a new name, the move evaluation colours are defined with 6-digit hexadecimal numbers (0-9, A-F, a-f) as follows:

.pos3 {background-color: #00E677;} (!!)
.pos2 {background-color: #4DFFA9;} (!)
.pos1 {background-color: #B3FFDA;} (!?)
.neg1 {background-color: #FFB3FF;} (?!)
.neg2 {background-color: #FF4DFF;} (?)
.neg3 {background-color: #E600E6;} (??)

These definitions as well as all other CSS instructions can be modified by the user.

Also in HTML mode the Elo evaluations mentioned above in the clipboard chapter 17) are displayed if the PGN file provides the corresponding data.

If only HTML mode is selected in the PGN-Engine-Analyzer GUI, possibly in conjunction with clipboard mode, no modified PGN file will be saved.


19) Mate announcements:

If engines detect a mate move sequence, they output a 'mate (-)x', but not a numerical evaluation. However, this is needed by PGN-Engine-Analyzer for its internal calculations. The 'x' represents the distance to mate in full moves, whereby the variation move that is commented on in this way is added numerically. PGN-Engine-Analyzer converts this expression into half moves and outputs an evaluation of ±300.00 ∓ number of half moves to mate without consideration of the current move – with white advantage without sign, with black with preceding minus sign. An immediate mate move is evaluated at (‑)300.00.

If the text module '# mate#' is used for the game or variation move comments, PGN-Engine-Analyzer uses a mate announcement in the form ' Mx' in favour of White or ' ‑Mx' in favour of Black, where 'x' stands for the distance to mate in full moves without consideration of the current move. If, as is usually the case, no mate is to be announced, the text module is removed. '# mate#' indicates that PGN-Engine-Analyzer automatically places a fixed space before this mate announcement. It is therefore advisable to insert the text module immediately after one of the 3 evaluation text modules, whereby '#evalu## mate#' is generally suitable, but '#e-c-e## mate#' is also appropriate for the game move comments in Aquarium. A blank space between both modules is omitted so that the removal of the # mate# module does not leave an unnecessary space.


20) Evaluation relevance reduction:

For many of the programme features discussed above, especially the annotating by move evaluation symbols, the move colouring, the position evaluation symbols, the relevant wins and losses, the optimum rates and the probabilistic game results, the possibly worldwide unique evaluation relevance reduction (ERR) was the inspiration. It relativizes engine evaluations and reduces absolute engine evaluation differences to relevant evaluation differences by means of integral functions.

0.00-evaluations are taken into account at 100%, extreme positive or negative evaluations at 0% (WDL ERR) or close to 0% (user ERR) and all other evaluations in the range between these extreme values.

The engine/calculation WDL ERR inspired by the engine Stockfish is based on win/draw/loss estimation quotas, which are written for each move into the game commentary by a suitable engine, such as Stockfish. However, Stockfish does not show these WDL values automatically, but only after clicking on the checkbox 'UCI_ShowWDL' in the engine options GUI.

More details on this topic can be found here.

For the PGN move annotation, either the WDL or user ERR text modules are available. For the HTML and spreadsheet files, the move evaluation symbols and move field colours, the ERR mode can be selected by choosing one of the 3 following alternatives at the bottom left of the PGN-Engine-Analyzer GUI:


The relevant parameters are to be entered on the left in the PGN-Engine-Analyzer GUI under the heading 'user evaluation relevance reduction':


Firstly the TCEC engine statistics may be helpful in answering the question of which 3 values make sense. Because not least the evaluation behaviour of an engine that was used for the game annotation could be decisive for the measurement of these parameters. In addition, the WDL ERR opens up a new source of information. In the generated HTML and spreadsheet files, average theoretical WDL evaluations for the probabilistic game results 0.75 as well as 0.75+ (to be entered by the user in the PGN-Engine-Analyzer GUI) can be found after each game, although they can differ considerably depending on the ratings occurring in the game.

A parameter that is decisive for the WDL-BRR can still be found in the PGN Engine Analyser GUI at the bottom right (unfortunately in a somewhat inappropriate place) with the designation 'WDL zero'. More precisely, this is the absolute value of the minimum evaluation at which the engine WDL predicts a one hundred percent win based on experience. When using the Stockfish engine, this value is likely to be around 2.35 empirically. From this evaluation onwards, positions for White are statistically considered 100% won and from the negative amount of this evaluation onwards 100% lost. Almost all WDL evaluations in the programme are based on this value and gain considerably in precision as a result. Again, the generated HTML and spreadsheet files contain 3 analyses of this value for each game, which may be helpful for entering the WDL zero value in the GUI. Why actually 'zero'? Because with this positive and negative evaluation, the mathematical WDL evaluation relevance functions have a zero.

PGN-Engine-Analyzer is thus a programme in which the parameters that are decisive for such essential chess assessments as move and position evaluation symbols, relevant wins and losses, optimum quotes and probabilistic game results are transparently available to the user for personal experiments.


21) Programme selection for PGN files:

On the right side of the PGN-Engine-Analyzer GUI under the headline 'PGN file → chess programme' there is a selection list for the following 7 chess programmes:

Aquarium,
Arena,
Kvetka,
Lucas Chess,
pgn4web,
Scid vs. PC,
Shredder Classic 4.

Some modifications are made to the new PGN file to be saved, depending on which programme was selected to load the file. Affected are


Lucas Chess displays PGN games including variations and annotations via Tools - PGN - Read PGN - Edit, if under Options - Configuration - Appearance - PGN table – Enable information panel by default is selected. Otherwise, you must also click on Config - View - PGN information. Lucas Chess can colour moves that are provided with move evaluation symbols, but the colors are set there under Options - Colors - General – PGN.

The 2 games in the PGN file 'games_engine_variations_analyses_WDL_Scid_vs_PC.pgn' can be viewed with the help of pgn4web on the Internet.


22) Parameters and checkboxes:

All settings relevant for the PGN-Engine-Analyzer GUI, including the selection of checkboxes, can be loaded and saved individually as parameters.

Not every click on any checkbox or in the list of chess programmes is rewarded with the expected reaction. In some cases, the programme knows how to avoid counterproductive orders and deselects checkboxes on the spot. This is a programme feature, not a bug.

If the button labelled 'English' at the bottom of the PGN-Engine-Analyzer GUI was clicked to switch to English-language programme texts, only the English-language text modules would be converted into data when creating an analysis PGN file, provided they were loaded with a suitable parameter file. Clicking on the button labelled 'German' would cause German to be selected as the GUI official language and loaded German-language text modules would again be given their due.


23) GUI background colour:

The input field to the right of 'background colour of all GUIs' on the left in the PGN-Engine-Analyzer GUI allows the choice of the GUI background colour with a colour code analogous to the 6 colour code lines already mentioned in chapter 11) on the right side of the GUI under the checkbox 'move-square colours for !! / ! / !? / ?! / ? / ??'.


24) PGN-Engine-Analyzer programming:

PGN-Engine-Analyzer was created with AutoIt3 v3.3.14.5. When making changes to the source code in the PGN_Engine_Analyzer.au3 file under other AutoIt versions, 'script breaking changes' should be considered.

The PGN files modified by PGN-Engine-Analyzer were tested with Scid vs. PC itself, of course, as well as with Aquarium, then a little with Arena, Kvetka, Lucas Chess, Shredder Classic 4, and with the internet PGN viewer pgn4web (versions 2.90 and 3.05).

If the user lets analyze several games in a PGN variations file with the aim of creating a new PGN analysis file, he will inevitably be confronted with the snail's pace of PGN-Engine-Analyzer. With more than one game per PGN file, the programme very quickly will be brought to its knees. AutoIt3 is an interpreter language and therefore sometimes painfully slow, but on the other hand it allows extremely imaginative applications without immense workload. It is a compromise!

No software is error-free, PGN-Engine-Analyzer is certainly not. The program does complicated things and as a lonely individual programmer you can't devote yourself to endless tests before publication. In this sense the error frustrated users are abused as involuntary beta testers and encouraged to make use of the following e-mail address in order to give the opportunity to eliminate the shameful missteps of PGN-Engine-Analyzer with a new program version.

Contact: mail@konrod.info


zip-Icon

programme PGN-Engine-Analyzer
24thdevelopment version from 12th November 2024
ZIP file [6.4 MB]: PGN_Engine_Analyzer.zip
in the PGN-Engine-Analyzer GUI click on the button 'English'








 

Ende Gelände ♦ Aus die Maus ♦ Schicht im Schacht ♦ Klappe zu - Affe tot

So long ♦ See You Later, Alligator - In A While, Crocodile ♦ Over And Out