AquaPGN - manipulation of PGN files generated by Aquarium

external link:


Stockfish
development versions

the latest versions of Stockfish

internal links:


evaluation relevance reduction

move and position evaluations together with NAG and Informator symbols

Keyboard layout for chess annotation

Preliminary remark:

Anyone interested in having engine variations or evaluations analysed in the sense of chapter 11) et sec. and then presented either in Aquarium via a PGN file to be loaded or in an HTML file or spreadsheet should consider using ScpcPGN in cooperation with Scid vs. PC.

Reasons:


However, 3 disadvantages of creating variations via Scid vs. PC should not be concealed:



AquaPGN - download:


zip-Icon

program AquaPGN - development version 12th August 2020
ZIP file [1.88 MB]: AquaPGN.zip
in the AquaPGN 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.

AquaPGN - a program that the world doesn't need, at most some users of the Chess GUI Aquarium


Last update from 12th August 2020:
Revision and clarification of the evaluation relevance reduction according to the specifications in this article. In particular, 2 additional parameters ('evaluation at 0.75-plus-game-result-probability' and '0.75-plus-game-result-probability') have been added. The previous 'win draw balance' has not been renamed without reason to 'evaluation at 0.75-game-result-probability'.
The AquaPGN GUI has been redesigned: Everything concerning parameters and information can be found on the left side, everything concerning 'modification of PGN file' on the right.
The information windows have been revised.
AquaPGN_X64.exe and AquaPGN_X86.exe are again included in the download ZIP file, the download link has changed.
Bug fixing and optimization.

Update from 8 Mai 2020:

AquaPGN_X64.exe (the executable program for Windows 64bit systems) and AquaPGN_X86.exe (the executable program for Windows 32bit systems) have been removed due to false positive virus messages, so that now an AutoIt version 3 must be downloaded to start the script AquaPGN either by double-clicking or alternatively by AutoIt3.exe or AutoIt3_x64.exe. This should not cause any loss of speed;
improved AquaPGN.html file;
some minor bug fixes.

Update from 1 April 2020:

The display of player data, PGN tags / evaluation settings, probabilistic game results by chart, engine-evaluated moves as well as statistics based on the eanalyzed engine evaluations during the program flow has been replaced by the generation of a HTML file that can be loaded in the browser and contains all this information;
three further text modules are offered, which support the presentation of the evaluation chart in Aquarium and the evaluation and time chart in Scid vs. PC;
bug fixes.

Update from 6.10.2018: Bug fixes.

Update from 29.9.2018: Bug fixes especially for English texts.

Update from 26.9.2018:

Move annotation in PGN file with colored moves;
switching to English program texts;
revision of the monitor mode and the tables in AquaPGN.ods for LibreOffice with further statistical evaluations;
correct handling of engine evaluation gaps in PGN files;
improved adaptation to other chess GUIs except Aquarium;
various bug fixes.

Update from 14.6.2018:

In monitor mode, the PGN tags (name, event, date, Elo values etc. - if available) of the PGN file, various game evaluations and diagrams with the probabilistic game results for each individual game are now also displayed;
for the move annotations further text modules are offered with an optimum rate for the respective move as well as an average optimum rate;
the data table in AquaPGN.ods for LibreOffice now contains not only the optimum rate together with the diagram and the average optimum rate, but also the PGN tags and the game evaluations;
adaptation to the chess GUI Arena.

Update from 25.3.2018:

Monitor mode, in which the data of the PGN tag pair section and all moves with engine position evaluations including analyses are displayed on the screen in multiple colors (see 12f));
revision of the annotator evaluations with 6 different text modules;
revision of tables and diagrams in AquaPGN.ods for LibreOffice;
adaptation to the chess GUI Kvetka.

Update from 15.1.2018:

Revision of the move evaluation symbols in accordance with the evaluation relevance reduction with various setting options and informations on this;
elimination of the definition of move evaluation symbols by 3 formula option;
position evaluation symbols with various setting options and informations on this;
probabilistic game results;
insertion of move evaluation symbols, position evaluation symbols and probabilistic game results into the clipboard for use in a spreadsheet program such as LibreOffice Calc;
insertion of a diagram with the probabilistic game results for white and black as a further LibreOffice Calc diagram;
complete analysis of the move evaluation symbols together with limit values, position evaluation symbols and probabilistic game results for 1 or 2 (then also the relevant evaluation difference) engine evaluations;
adaptation to the chess GUIs Lucas Chess, Scid vs. PC and Shredder Classic 4.

Update from 10.3.2017:

Complete revision of the move annotation; data about annotated moves are written to the clipboard and can be further processed in a spreadsheet program, e.g. for diagrams; evaluation relevance reduction: for more information, see...

What can AquaPGN do?

The editing of PGN files generated with Aquarium (© 2008-2018 Convekta Ltd.). It is initiated by clicking the Start button in the AquaPGN GUI. In detail (for the impatient: the best comes from paragraph 11)):

1) Removal of inline commands::

It eliminates inline commands from aquarium PGN files which are introduced with the character string '{[%t' and continued with a 4-digit element:


2) Replacement of NAG text modules:

It replaces NAG text modules that are introduced with the '$' sign and are supplied in a separate *.nag file. The text modules contained in this file only partly correspond to the official standard (if there is one at all) and should only be understood as a suggestion. Special characters that appear in fonts after the character with the number 255 (decimal) should only be used if they are supported by the font AqChessUnicode.

Another hint on the edge: If the inclined reader seeks to use Unicode chess special characters, for example position evaluation symbols, but should not get hold of them, the following link to the AqChessUnicode font might be helpful. By the way, this font is also included with the chess GUI Aquarium.

3) Replacement of chess piece text modules:

If in an annotation after a space character a 'w' for 'white' or an 's' for 'black' is entered followed by a 'K', 'Q', 'R', 'B', 'N' or 'P' for the pieces in question or 'C' for 'castling', are these text modules replaced by the piece names concerned. Examples: 'the wKside', 'the 2 bRs'.
Note that there is no need for a preceding '$' sign like in NAG expressions.

4) Replacement of mate announcements:

In annotations it turns from an

5) Insertion of null moves by annotation:

Aquarium finds it difficult to insert null moves via 'Z0', this is only possible at the end of a move sequence. AquaPGN provides a remedy. 2 cases of the insertion of null move variations by annotation are to be distinguished:

Insertion of a variation with repetition of the previous, i.e. 'commented' move with subsequent null move in the sense of 'with the idea ...' (cf. NAG text module $140) or 'with the threat ...': '\(\+--.*?\)' - to speak with a regular expression. You start with '(+--' and then continue with either a move without a move number (e.g. '(+--e4)') or a move sequence (e.g. '(+--e4 Nc6 d4)') or leave it ('(+--)'). So at the end there is the ')'. The two '--' represent the null move.

Insertion of a variant without repetition of the previous, i.e. 'commented' move with a null move, which represents the 'commented' move, in the sense of 'directed against ...' (cf. NAG text module $141): '\(--.*?\)' - to speak now one last time with a regular expression. You start with '(--' and then either continue with a move or a sequence of moves or leave it at that. At the end there is the ')' again.

Just as a quick reminder:
'with the idea ...'. → '+--', 'directed against ...' → '--'.

It is possible to put the whole thing into a move annotation (or even combine it with a NAG text module), e.g. 'with the idea(+--Bf4)' or '$140(+--Bf4)' or 'directed against(--Bf4)' or '$141(--Bf4)'.

6) Regrouping of annotations before moves:

AquaPGN places these annotations where they belong, namely in front of the moves, and by the way deletes the '{[%t bLon...}' element.

7) Regrouping of end of game annotations:

AquaPGN places such annotations again where they belong, namely at the end of the game, and by the way deletes the '{[%t Long...}' element.

8) Removal of line breaks '^13 ^10':

Aquarium uses the character strings '^13 ^10' to form paragraphs in annotations. Unfortunately, the program pgn4web does not eliminate these strings, not to mention their correct conversion into paragraphs. They therefore insult the eye of the beholder in this unchanged cryptic form. AquaPGN makes short work of this and eliminates these strings once and for all.

9) Conversion of the character representation of null moves:

AquaPGN converts null moves represented in aquarium PGN files by 'Z0' into '--', a format which is used among others by the very recommendable and free chess database program Scid vs. PC, by the very recommendable and free Internet PGN viewer pgn4web and apparently by the less recommendable, because not so free Chessbase.

Warning:

The 4 last mentioned corrections are marked in the AquaPGN GUI with blue color, because they lead to irritations when viewing such changed PGN files in Aquarium. If the null moves are changed, Aquarium will even fail to display the PGN file after the first null move occurs. They should therefore only be applied for files that are used outside Aquarium.

10) Replacement of annotator evaluations:

AquaPGN replaces user evaluations ('{[%t Val] ...}') in such a way that the cryptic characters found in PGN files, which are only readable as numbers inside Aquarium, are replaced by comprehensible values in number format (see the discussion at the Rybka forum). AquaPGN can convert a total of 6 different text modules, which can be used in the GUI line next to the actual text:

#KBwt# - the evaluation as it is also and only visible in Aquarium;
#KBwtvb# - an evaluation range ('evaluation from' - 'evaluation to') from the mean value between previous and current value to the mean value between current and subsequent value, e.g. '-0.02 – 0.02' instead of '0.00'; reason: no intermediate values can be entered in Aquarium;
#SbsA# - position evaluation symbol in ASCII;
#SbsU# - position evaluation symbol in Unicode - could lead to illegible characters in some chess programs;
#pPrW# - probabilistic game result from 0% to 100% regardless of the move color always from the point of view of white;
#pPrS# - probabilistic game result from 0% to 100% for white and (in each case with the same evaluation) from 100% to 0% for black (recommended!).

So you could misuse this AquaPGN function to automatically annotate a game with position evaluation symbols and probabilistic game results by not first laboriously determining them and then writing them down in the annotation, but simply using the annotation evaluation and letting the rest AquaPGN do the job.

The conversion of the #pPrS# components is faced with the difficult task of determining technically whether it is a white or black move, even if there is no move number with 1 or 3 points before the actual move. If this does not work properly in individual cases (oh shame!), the #pPrW# text module would have to be used.

11) Processing and analysis of engine variations and evaluations:

AquaPGN uses engine variations and evaluations which are inserted into the annotation by Aquarium while the engine analysis is running [via the 'Insert' key (single-variation mode) or by selecting the 'Analysis'-'Insert' menu group or with the mouse after right-clicking in the analysis window by clicking on 'Insert variation' (single-variation mode) or 'Insert all lines' (multi-variation mode)]. These engine evaluations can optionally be used for automatic annotation of moves with various data or with the move evaluation symbols '!!', '!', '!?', '?!', '?' and '??', modified, regrouped or deleted. And the variations can be reduced to a definable number of moves for a better overview.

Problems with the engine variations or evaluations of Aquarium:

The position evaluations including information about number of nodes, analysis depth and time, engine name and antecessor move (previous move) can be found at the end of the variation instead of at its beginning. To make matters worse, the variations of a game move (including their evaluation!) do not have to join it at all, they can also appear in any later game move where they are out of place. Therefore AquaPGN can regroup these evaluations and other data at the beginning of the variation after the correct move. The data at the end of the variation can be left, changed or deleted.

These original data are - according to taste - partly superfluous (the analysis time even appears twice) and divided into 'Evaluation' and 'Long after' annotations, even with different emphasis. AquaPGN turns this into uniform annotations.

The relevant text modules apart from the actual individually selectable text for the start and end of variation are as follows:


The variation annotations can be defined in the AquaPGN GUI in the text fields under 'relocation of evaluations to variation start with change:' as well as 'retention of evaluations at end of variation with change:'. But the definition of the two texts in the supplied *.par files using any editor in line 41 for the start of the variation and line 42 for the end of the variation is much more convenient.

Tip at the margin: In the text outside the actual text modules, you should avoid the normal '-' character under certain circumstances and replace it with the Unicode character '‑' (protected or non-breaking hyphen: hexadecimal 2011 or hexadecimal UTF-8 bytes E2 80 91 or decimal 8209). You should also use the fixed, non-breaking space character ' ' (hexadecimal A0 or decimal 160) in suitable places. Otherwise Aquarium will mercilessly break such text in the annotation on the right side. 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 '_'.

The variations are sometimes incredibly long. AquaPGN can therefore shorten the variations to a maximum number of variation moves, without, however, interfering with other variations that join or latch into the variations to be shortened.

And Aquarium has the stupid habit of displaying variations at the end of the game unwanted for the user as game moves (not variation moves). AquaPGN can also (hopefully) correct this with the function 'engine moves at the end of the game --> variation'. However, this requires that AquaPGN can correctly identify the end of the game. Whether this is successful depends on the honourable user. Obviously (subject to further tests) Aquarium creates such ghostly game moves at the end of the game, if a variation is inserted, which in its course contains the end of the game including the (so far) last game move, but beyond that also subsequent moves. And all the more if the user or representative for him AquaPGN inserts after the last move one or more new engine evaluations, because then of course another game move is needed, with which these evaluations are linked. So in case of using the program function 'engine moves at the end of the game --> variation' to avoid worries, before the beginning of the automatic game analysis or before inserting the last engine evaluation(s) the cursor in the notation window must be before (!) the last move of the game. Thus an analysis of this last move is performed at the beginning of the analysis. However, if it is at the end of the last game move, at least the first newly calculated variation move is added as the last game move. The function 'engine moves at the end of the game --> variation' will not touch this new game move, but only integrate the following moves into a variation.

If there are error messages when using the function 'engine moves at the end of the game --> variation', if you like it or not, the program must be started again without this function.

12) Automatic annotation:

The last point of criticism is the insufficient representation of the evaluations by Aquarium. Immediately after game and variation moves (the first moves of engine variations in each case) their evaluations and the conclusions therefrom should be clearly recognizable. The same applies to the differences between variation evaluations in multi-variation mode. Therefore the program offers in its GUI an annotation by move evaluation symbols ('!!', '!', '!?', '?!', '?' and '??') as well as move coloring and an extensive detail annotation.

For many of the features discussed below, especially the annotating by move evaluation symbols, the move colouring, the relevant rating differences, the position evaluation symbols, the optimum rates, the probabilistic game results etc., the probably worldwide unique evaluation relevance reduction was the inspiration, about which you can find out more here. It relativizes engine evaluations and reduces engine evaluation differences to relevant evaluation differences by means of an integral function. 0.00-evaluations are taken into account 100%, evaluations of a special value to be entered in the AquaPGN GUI under 'evaluation relevance reduction' - 'evaluation at 0.75-game-result-probability' 50% and extreme positive or negative evaluations with almost 0%. In addition, an 'evaluation at 0.75-plus-game-result-probability', which must not be lower than the previously mentioned evaluation, and a '0.75-plus-game-result-probability', which must not be lower than 0.75, must be entered in the AquaPGN GUI.

If there are only variations in single-variation mode, these annotation functions work only very limited: Only in the course of the game moves a blunder check is possible, so the evaluation of the variation originating from the engine (which is as the only one of course also the best) at the place of a game move can be compared with that of the following game move and in case of a decrease in evaluation, which is then owed to the previous (and not identical with the best variation move) game move, this game move be condemned by '?!', '?' and '??' and provided with an additional detailed annotation (see below).

12a) Move evaluation symbols:

'!!'  - extremely advantageous move (cf. NAG $3 in the *.nag file);
'!'  - clearly advantageous move (cf. NAG $1 in the *.nag file);
'!?'  - slightly advantageous move (cf. NAG $5 in the *.nag file);
'?!'  - questionable move (cf. NAG $6 in the *.nag file);
'?'  - weak move (cf. NAG $2 in the *.nag file);
'??'  - miserable move (cf. NAG $4 in the *.nag file).

This kind of automatic annotation by AquaPGN is solely based on the evaluations of a chess engine, which is not a chess columnist, but a number cruncher and therefore has no understanding for artistic figure acrobatics. The motto is: The truth lies in the hundredth of a pawn's unit evaluation!

For the annotation by '!!', '!', '!', '!?', '?!', '?' and '??' the probably worldwide unique evaluation relevance reduction is used, about which you can find out more here. It reduces engine evaluation differences to relevant evaluation differences using an integral function. 0.00 evaluations are considered 100%, evaluations of a special value to be entered in the AquaPGN GUI under 'evaluation relevance reduction - win draw balance' (recommendation: 0.62) at 50% and extreme positive or negative evaluations almost 0%.

On the left side of the GUI can be chosen one of 2 different schemes under 'move evaluation symbols (!! / ! / !? / ?! / ? / ??)'. The 'information' button on the right provides information about the selected scheme plus parameters.

After clicking the button '!! / ! / !? / ?! / ? / ?? - matrix for 2 engine evaluations from +10 to -10' the relevant evaluation differences and move evaluation symbols for a variety of engine evaluation pairs are displayed. In the column on the left margin the better and in the row on the top margin the worse evaluations are listed. 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 from the point of view of White are listed, below those from the point of view of Black. 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 evaluation symbol you want to assign, you can click on the button 'complete analysis for one or two special engine evaluations' to see the result of the formula analysis.

Example for the case of an 'evaluation at 0.75-game-result-probability' of 1.50, an 'evaluation at 0.75-plus-game-result-probability' of 3.00, a '0.75-plus-game-result-probability' of 0.875 each in the AquaPGN GUI and – after clicking on the button 'complete analysis for one or two special engine evaluations' – entering '1' as a better evaluation for one move and then '0' for the worse move:
The move evaluation symbol for the better move is '!?' for both schemes, for the worse '?!'.
The move evaluation symbol thresholds for the better evaluation reveal that neither of the two schemes allows a '!!' for a better alternative move in relation to the move with the evaluation 1.00 and that a '!' can only be granted if the alternative move evaluation is at least 3.45 or 4.42. For all other move evaluation symbols, especially the negative ones, however, there are thresholds so that they can be distributed if the alternative move is only good or bad enough to reach or exceed the respective threshold.

Trial by example: Test the evaluation pair '3.44' and '1' with the button 'complete analysis for one or two special engine evaluations' and you will find the move evaluation symbols '!?' and '?!'. So far correct, because the value ‘3.45’ was undercut. New attempt: this time '3.45' and '1' - voila: '!' and '?' in the scheme with 7 sectors. And for the evaluation pair '4.42' and '1' both schemes agree again.

If you should only wish the move evaluation symbols during the automatic annotation and disdain the other annotation together with variations in order to simply get a quick overview of successful (only in multi-variation mode!) and failed game moves, the functions on the right side in the AquaPGN GUI 'move evaluation symbols (!! / ! / !? / ?! / ? / ? / ??)' as well as 'removal of engine variations and evaluations' would have to be selected and 'detailed commentary' deselected. Then only the game moves are provided with move evaluation symbols, the variations are eliminated.

12b) Detailed commentary:

This is always done immediately after the relevant game move or 1st variation move and if necessary (in multi-variation mode) after the other variation moves. In addition to the individually selectable explanatory text, it uses the following text modules, many of which are identical to those already explained under number 11):


In addition with the game move the following data:


The two detailed annotations for game and variation moves can be defined in the AquaPGN GUI in the text field next to 'detailed commentary:'. For space reasons, however, there exists only one line that contains both texts, with the triple character '***' representing the separator. However, it is much more comfortable to define the two texts in the *.par files by any editor in line 28 for game move and in line 29 for variation move comments.

Reference is expressly made here to the 'Tip at the margin' under number 11) about the use of special characters in the text outside the actual text modules.

Nota bene: The recommendable '∑' (sum) and 'ø' (average) characters available in the *.par files supplied with the program package can be found under hexadecimal 2211 or decimal 8721 and hexadecimal F8 or decimal 248.

It is advisable to provide each move with at least one engine evaluation. However, if this is not opportune, AquaPGN at least helps itself with a little trick: In an evaluation gap AquaPGN constructs a - let's call it - phantom evaluation for the game move before the first move following the gap, the source of which is the optimal evaluation of the following game move.

12c) Position evaluation symbols:

These are inserted automatically in the course of the detailed annotation optionally with the following text modules:

#SbsA# - position evaluation symbol in ASCII;
#SbsU# - position evaluation symbol in Unicode.

In ASCII mode they are output as follows:

'=' - balance / draw / minimal advantage for White or Black (see NAG $10 to $13 in the *.nag file); '+/=' - White has a slight advantage (see NAG $14 in the *.nag file);
'-/=' - Black has slight advantage (see NAG $15 in the *.nag file);
'+/-' - White has moderate advantage (see NAG $16 in the *.nag file);
'-/+' - Black has moderate advantage (see NAG $17 in the *.nag file);
'+-' - White has a clear advantage (see NAG $18 in the *.nag file);
'-+' - Black has a clear advantage (see NAG $18 in the *.nag file);
'++-' - White has an extreme advantage (see NAG $19 in the *.nag file);
'--+' - Black has an extreme advantage (see NAG $20 in the *.nag file).

In Unicode mode, instead of '+/=', '-/=', '+/-' and '-/+', the Unicode special characters usual in annotations are output as single characters, which are displayed correctly in Aquarium, since the font AqChessUnicode.ttf is used there. Also the clipboard output automatically falls back on these special characters, so for their correct display the installation of this font is necessary.

Information about the position evaluation symbols is provided in the AquaPGN GUI after clicking the 'info' button under the lines 'position evaluation symbols ...' and 'scheme:'. The results again depend on the adjusted parameters of the evaluation relevance reduction and the position evaluation scheme selected in the AquaPGN 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; in the example of the entry of a evaluation pair of '1' and '0' under point 12a) the position evaluation symbols are '±' for the schemes with 9 sectors and '⩲' for the schemes with 7 sectors.

12d) Probabilistic game results:

These are also inserted automatically in the course of the detailed annotation optionally with the following text modules:

#pPrW# - probabilistic game result from 0% to 100% regardless of the move color always from the point of view of White;
#pPrS# - probabilistic game result from 0% to 100% for White and (with the same evaluation) from 100% to 0% for Black (recommended!).

In clipboard mode, only the 2nd variant is used. These values are then used for the 'Dia-p-Pr' diagram in the AquaPGN.ods file.

In the example of entering an evaluation pair of '1' and '0' shown under point 12a), after pressing the button 'complete analysis for one or two special engine evaluations', the probabilistic game result in the case of an evaluation of 1.00 is displayed as 67% (the evaluation is between 0 and 1.50, so the presumed game result must be between 50% and 75%); the evaluation 0.00 of course leads to the display of '50%'.

12e) Clipboard mode:

The checkbox 'evaluation data --> clipboard' allows the transposition of a lot of data of a PGN file (so possibly even of several games) as well as additionally calculated data, as described above in connection with the text modules, into the clipboard. From there they can be transferred to other programs via Ctrl-v. In particular, a spreadsheet program that evaluates these data for diagrams may be appropriate. Such a worksheet called AquaPGN.ods, which was created with LibreOffice, version 5.4, as an ods file, can be found in the program package.

To enter the clipboard data there,
immediately after finishing AquaPGN (i.e. after filling the clipboard) select the 1st table 'Daten',
if necessary, delete all rows in the data sheet from the yellow-colored cell A5,
select the yellow cell A5 and then enter Ctrl-v.

You could choose in the dialogue that thereupon appears:
Character Set: Unicode;
From row: 1;
Separated by;
Tab;
Return/Enter;
voila.

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 diagrams in the 6 diagram tables are even created automatically using the clipboard data to be inserted in the 1st table, without the need to rely on a macro. This automatic works either only for the first game of the PGN file or for a move range to be selected by the user (see table 'Dia-Daten', line 1). The diagram tables are therefore intelligent enough to recognize with which data series the first game ends. If the diagrams should become confusing due to high numerical values, the diagram representation can be restricted to a special area by selecting a move area with lower numerical values.

In the 'Konsistenz' spreadsheet it is checked whether various clipboard data supplied by AquaPGN really correspond to the intended logic of the program code. The data taken over from AquaPGN (green) and calculated in the table (yellow) are located in adjacent columns. Should there a contradiction arise, the calculated yellow cells 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 'Konsistenz' is not very helpful for the normal user, but it consumes a lot of storage space. It can be deleted in case of dissatisfaction.

If only clipboard mode is selected in the AquaPGN GUI, possibly in conjunction with monitor mode (digit 12f), no modified PGN file will be saved.

12f) HTML file mode:

The checkbox 'evaluation data --> monitor' causes the output of the clipboard data mentioned under number 12e) on the screen plus 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 can be found in Aquarium's opened PGN file or for which AquaPGN has exceptionally constructed phantom evaluations.

The 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 using the up and down red-colored 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. All colors can be defined with 6-digit hexadecimal digits (0-9, A-F, a-f) in the supplied sample file AquaPGN.html in the ‘HTML’ folder, which has to be modified during program operation after opening and then saved again under a new name.

The move quality colors preset in AquaPGN.html and modifiable by the user are:

#00FF84 (!!)
#80FFC1 (!)
#B3FFDA (!?)
#FFB3FF (?!)
#FF80FF (?)
#FF4DFF (??).

The same colors are also used by the 'Data' table in AquaPGN.ods. On the Internet, for example, you can find a convenient color selection with the prefix '#' under...

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

If only HTML file mode is selected in the AquaPGN GUI, possibly in conjunction with clipboard mode (number 12e), no modified PGN file will be saved.

12g) Formatted moves in the PGN file:

This feature 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 AquaPGN GUI holds a checkbox 'move styles' in the upper right corner, which can be used to assign special styles, especially colors, to good and bad moves in the generated PGN files. Affected are the 6 move qualities listed in section 12a), whereby these do not necessarily have to be provided with a move evaluation symbol in order to be able to be 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 AquaPGN synonymous with 'clearly advantageous move' - '!'),
'Interesting move' (in AquaPGN synonymous with 'slightly advantageous move' - '!?'),
'Dubious move' (in AquaPGN synonymous with 'questionable move' - '?!'),
'Bad move' (in AquaPGN synonymous with 'weak move' - '?').

AquaPGN uses these as well as the two following style categories:
'Special Style 22' for extremely advantageous 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 AquaPGN 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 AquaPGN marks these moves with move styles, if they are to be praised or denounced as good 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) Automatic game analysis by remote control of Aquarium:

Aquarium has in terms of information content very limited 'Game Analysis' and 'Find Blunders' analysis. If these should not appeal or if they are not successful as desired (see the discussion at Rybka-Forum), the game moves to be examined can be provided within Aquarium either in single- or multi-variation mode with engine evaluations and other interesting information (in order to then start the automatic annotation function of AquaPGN).

If this seems too tedious to you, take a look at the AquaPGN GUI section 'Aquarium game analysis'. This allows to automate the addition of engine evaluations to Aquarium by remotely controlling Aquarium from AquaPGN. If you should dare to do this, you should, in your own interest, carefully read and observe the notes on preparation that appear after starting this function. After all the author excludes any liability for any damage due to malfunctions of AquaPGN and in particular due to malfunctions of this special program feature (see the attached file 'COPYING'). Mystically speaking: After starting this program function, the user's computer is in the power of fate! A goodness proposal for jumpy souls: Modestly start the game analysis with only a few half moves and then check what’s all has crashed …

On the one hand, the 'analysis time per move in seconds' can be set, which, however, can be significantly extended by selecting the function 'variation insertion only after next variation calculation'. This opens up the possibility for Aquarium to complete the current variation calculation before it is inserted into the notation. However, this feature can fail to operate with mate evaluations. Stockfish, for example, can announce a mate at a maximum search depth of 'd127' and then call it a day. Then the insertion of the engine evaluation halts too. Therefore an emergency brake was built into AquaPGN: It is waited maximally the triple normal analysis time for a reaction of the engine. If nothing happens until then, the current evaluation is inserted into the notation.

When choosing the 'half moves from the end of the analysis area', it should be noted that the game moves are processed from back to front. So if the entered number of half moves is smaller than the number of all half moves in the game and the analysis started at the end of the game, opening moves remain unevaluated.

With the selection of the single- or multi-variation mode (with correct preparation of Aquarium) of course either only one variation or several variations per half turn are entered in the notation.

And due to some complications with an Aquarium program internal identification number of the notation window title bar, whose value is usually either 1 or 2, a selection list had to be inserted into the AquaPGN GUI with which an 'INSTANCE1' (value: 1), 'INSTANCE2' (value: 2) or 'INSTANCE3' (value: 3) can be selected in order to make the whole action successful. Unfortunately, it must be left to the user to determine the correct setting on his system.

For this you can use the tool Au3Info.exe, which is included in the downloadable program package of 'AutoIt'. It can also be downloaded individually from the Webseite. After the start the 'Finder Tool' must be dragged on the title bar with the text 'Notation' of the notation window of Aquarium. Under 'Basic Control Info' you can read the following:

Class TDockHeader Instance: x where the 'x' stands for the instance you are looking for. Attention: Experience shows that this instance number can change for unknown reasons (tab order?).

AquaPGN performs mouse clicks in the 'Analysis' window of Aquarium. The mouse pointer is centered in the window. A possible Windows taskbar on the left or upper side is considered by the program.

During the analysis by the chess engine you can switch to another window or program. If then Aquarium has to insert an engine evaluation, AquaPGN will hopefully automatically switch to Aquarium in the background and back to the previously used window or program after the work is done.

14) Miscellaneous in the AquaPGN GUI:

To the right of the button 'start' there is a selection list for the following 7 chess programs:

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

Some modifications are made to the new PGN file to be saved, if Arena, Kvetka, Lucas Chess, Scid vs. PC or Shredder Classic 4 are selected.

The settings for Aquarium and pgn4web are identical.

For Arena, Lucas Chess, Scid vs. PC and Shredder Classic 4 the parentheses around move evaluation symbols have to be removed.

Additionally, for Arena and Shredder Classic 4 have to be merged the adjacent comments to one annotation, otherwise only the first one will be shown.

Arena, Kvetka and Shredder Classic 4 cannot display Unicode characters as well as characters of the rear area of the ASCII table (e.g. the fixed space), thus also not correctly the information represented with the comment text modules #SbsU#, #Z-a-F# and #Z-z-F# (figurine representation) because of the Unicode characters used there. Alternative text modules are available. The same of course applies to user text modules that contain such characters. These can simply be replaced by self-created alternative text modules. Nevertheless AquaPGN tries to replace the Unicode characters used by the program with displayable ASCII characters, if one of the mentioned 3 alternative programs is selected.

All settings relevant for the AquaPGN GUI can be individually loaded and saved as parameters. What a click on 'left', 'select all', 'right', 'left', 'deselect all', 'right' causes, the user may find out for himself. By the way, not every click on any checkbox is rewarded with the expected reaction. Conversely, a checkbox is sometimes initialized even though it has not been touched at all. The program knows how to avoid counterproductive orders in some cases.

If the size of the program GUI exceeds the screen resolution, the latter does not have to be increased immediately. Starting with Windows 7, there should be a setting - switching off Aero Snap - which reduces the size of a window when attempting to move it beyond the edge of the screen. Hmmm. One would then at least have access to all areas of the reduced-size GUI, if one was able to recognize them in detail. Problem solution à la Microsoft. The tool 'AltDrag', which is freely available on the Internet, is already more convenient: With the 'Alt' key pressed, windows and thus also the program GUI can be moved with the mouse in any manner over the screen border without resizing, whereby the previous mouse click can take place at any window position.

You can switch to English program texts by clicking on the 'English' button at the bottom left of the AquaPGN GUI. If the name there is 'Deutsch', such a click would cause the selection of German as the official GUI language.

15) Final remarks:

AquaPGN was created with AutoIt3 (© 1999-2018 Jonathan Bennett & AutoIt Team).

The program package contains:


The latest version of AquaPGN has been tested with Aquarium 2019. The modified PGN files have been tested needless to say with Aquarium itself, a bit with Arena, Kvetka, Lucas Chess, Scid vs. PC, Shredder Classic 4 and with the Internet PGN viewer pgn4web (version 2.90), which is used for publishing commented games and studies on this website. Of course, PGN files can also be viewed offline with this program, if you choose the right browser (for example Firefox, but not the Russian Yandex).

No software is error-free, AquaPGN is certainly not. The program does complicated things, because even Aquarium is extremely complex, 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 AquaPGN with a new program version.

If the user lets PGN files annotate or engine evaluations change, lets write data to the clipboard or display them on the monitor, he will inevitably be confronted with the snail's pace of AquaPGN. With more than one game per PGN file, the program goes to its knees very quickly. AutoIt3 is an interpreter language and therefore sometimes painfully slow, but on the other hand it allows extremely imaginative applications without immense effort. It's a compromise!

Contact: mail@konrod.info


zip-Icon

program AquaPGN - development version 12th August 2020
ZIP file [1.88 MB]: AquaPGN.zip
in the AquaPGN GUI click on the button 'English'








 

Finito ♦ Aus die Maus ♦ Schicht im Schacht ♦ Klappe zu - Affe tot

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