Program: gafs - Chess Endgames
Version: 1.42 - December 2006
Author: Guido Antonelli - Email:rigel_g@iol.it


The program gafs (Guido Antonelli Finali di Scacchi) runs the main functions
concerning chess endings. As these functions are numerous and complex, gafs
requires that the first option in the command line, that follows the name of
the program, determines the type of the requested function, the meaning of
the subsequent options and the format of the other parameters.
The options following the first can be put in any order.



USER MANUAL

Menu of the first valid options:

  -b       - bitbases generation from tablebases
  -e       - chess endgame manual execution
  -g       - chess endgames tablebases generation
  -i       - single position analysis
  -l       - listing of positions by single result (white or black moves)
  -m       - memory needs evaluation for tablebases generation
  -t       - listing of positions by combined results (white and black moves)
  -v       - tablebases verifying

Details of each option are obtained typing gafs followed by the option.

Example: gafs -g   (gives information about tablebases generation)

NOTE

This menu is obtained by typing: gafs



Menu of valid options for command line: gafs -b ...:

  -a <dir> - indicates directory (and path) of the bitbases to be generated,
             if different from current directory
  -d <dir> - indicates directory (and path) of the tablebases to be utilized,
             if different from current directory
  -l <lin> - language used for messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -r       - forces recalculation of an already existing endgame
  -R       - generates the bitbases of the endgame <nomtab> and of all the end-
             ings obtained from <nomtab> by capture and/or promotion
 <nomtab>  - name of the endgame to be generated

The endgame's name is formed by a sequence of smallcase characters indicating
the men IN ITALIAN NOTATION in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
    (King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
The bitbases contain 2 bits (win, draw, loss, illegal position) per each posi-
tion of the men and use the following names:
    <nomtab>.tcb  = <nomtab> endgame with white moving
    <nomtab>.tcn  = <nomtab> endgame with black moving
    <nomtab>.tcf  = statistics (ASCII) of <nomtab> endgame
The bitbases of a specified endgame are produced only if the correspondent
tablebases have been previously generated.
This holds also in the case in which option -R is used.
Cpu time and RAM memory are minimal, because the generation of bitbases
requests only read/write operations onto the disk, and this is done by
reading blocks of only some Mbytes time by time.

Esempio: gafs -b -d tab8bit -a tab2bit -R rprp
         (starting from the tablebases existing in ./tab8bit, the commans
          produces in the directory ./tab2bit the tablebase rprp and all
          those obtainable from rprp by capture and/or promotion).



Menu of valid options for command line: gafs -e ...:

  -b       - white moves first (default)
  -d <dir> - indicates directory (and path) of the tablebases necessary to
             the endgame, if different from current directory
  -l <lin> - language used for men symbols and messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -n       - black moves first
  -p<c>    - indicates the presence of a possible en passant capture in <c>
             file
 <pcr>     - man + file + rank

Men with their positions must be given in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
and indicated by the their alphabet letter in the selected <lin>.

Examples: gafs -e -d tables rd4 dh8 rg2 tg1
        (it plays manually with Italian notation the endgame K+Q against K+R
         with white moving and tablebases stored in the directory ./tables).

        gafs -e -d tables -l en -pc -n kc2 pc4 ke5 pd4
        (it plays manually with English notation the endgame K+P against K+P
         with black moving, a white Pawn in file c that can be captured en
         passant and tablebases stored in the directory ./tables).


Internal submenu for manual playing:

   ? / a[iuto]  = this menu
   f[ine]   = program end
   l[ista]  = list legal moves and their results
   m[ostra] = show the square on the screen
     -<n>   = go back <n> plies (n > 0)
   s[alva] [file] = save on file the moves sequence (default: show the sequence
              on the screen)
   <mossa>  = move to be executed in numerical notation
              Examples in English notation:  Kc4-d4  Ra1-a8+  Pc7-c8D+  Qa2xa4
Legenda:
    v <n>   = win in <n> moves
    p       = draw
    s <n>   = loss in <n> moves



Menu of valid options for command line: gafs -g ...:

  -1       - uses the direct move algorith (slow but stable)
  -2       - uses the mixed move algorithm (default, intermediate for speed and
             stability)
  -3       - uses the backward move algorithm (faster but less stable)
  -d <dir> - indicates directory (and path) of the tablebases existent or to be
             generated, if different from current directory.
  -i <nnn> - indicates the number of seconds of elapsed time between two subse-
             quent disk backup of the tablebases
  -l <lin> - language used for messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -m <mmm> - indicates the memory in Mbyte given to the program
  -r       - forces recalculation of an existing tablebase.
  -v       - verifies positions legality by backmove
 <nomtab>  - name of the endgame to generate

Endgame's name is formed by the sequence of smallcase characters indicating the
men IN ITALIAN NOTATION in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
(King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
Standard tablebases contain 1 byte per position, to which 1 or more carry bits
per position are added at the end of the file.
Standard tablebases have the following names:
    <nomtab>.tbb  = <nomtab> endgame with white moving
    <nomtab>.tbn  = <nomtab> endgame with black moving
    <nomtab>.stf  = statistics (ASCII) of <nomtab> endgame
The options -1, -2 and -3 are mutually exclusive.
Option -i <nnn> refers to tablebases intermediate backup during calculations;
this permits to continue the computation if for any reason the generation has
been interrupted. Default and at the same time minimum value is -i 3600.
To continue the calculation it is sufficient to repeat the generation command,
because the program checks the presence of some specific auxiliary files esta-
blishing automatically the present situation of the calculation. 
Option -m IS MANDATORY. It is strongly advisable to use only PHYSICAL MEMORY
(details follow).
Option -v makes more strict the positions legality checking; this increases
computation time, but subsequent tablebase generation is a little faster.
For technical reasons the option -v cannot be used together with the backward
move algorithm.

Examples: gafs -g -d tables -i 7200 -m 210 rtard
          (generates in the directory ./tables the tablebases of K+R+B against
           K+Q and all the tablebases obtained by capture and/or promotions, if
           not yet present, saving the result at the end of the current cycle
           every 7200 seconds, i.e. two hours, of elapsed time from starting or
           from previous backup; assigned memory is 210 Mb)

          gafs -g -d tables -i 7200 -m 210 rtard
          (this command is identical to the previous command: but, if the compu-
           tation has been interrupted after at least one backup, this command
           causes a restart of the computation from the last backup).

NOTES

The generation of a standard tablebase (8 or more bits per position) is done
only if the tablebase has not been previously produced, except that recalcula-
tion has been forced with option -r. In any case all the tablebases obtained
by capture and/or promotion are automatically generated, if not previously
existent, and this process is applied recursively.
During the calculation of the tablebases, depending also on the available RAM
memory and on the algorithm used, many auxiliary files of type <nomtab>.???
must be present, which will be deleted at the end of run.
DO NOT EVER CHANGE THESE FILES.
If the computation of a tablebases has been interrupted, restart command must
refer only to the tablebases not terminated, in the case that at least one
backup has been made.



Menu of valid options for command line: gafs -i ...:

  -d <dir> - indicates directory (and path) of the tablebases necessary to
             the ending, if different from current directory
  -l <lin> - language used for men symbols and messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
 <pcr>     - man + file + rank

Men with their positions must be given in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
and indicated by the their alphabet letter in the selected <lin>.

Examples: gafs -i -d tables -l en Kd4 Qh8 Kg2 Rg1
         (shows the best results and results obtained for each legal move in
          such a position when white and black moves; if pawns are present,
          results are also given for legal en passant captures; tablebases
          are looked for in the directory ./tables).



Menu of valid options for command line: gafs -l ...:

  -c       - produces the list without numerations, men symbols and separators
  -d <dir> - indicates directory (and path) of the tablebases necessary to
             the endgame, if different from current directory
  -f       - produces the output in FEN format (see the comment note)
  -l <lin> - language used for men symbols and messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -<rs>    - result used as selection key
 <nomtab>.<suf> - name of tablebase to be searched with suffix (suffix
                  specifies the player who moves)
 <uscita>  - ASCII output file (default = screen)

Legal values for <rs>:

  -p       - all draws
  -p0      - stalemates
  -s       - losses
  -s<n>    - loss in n moves (n >= 0)
  -t       - all legal positions
  -T       - all legal and illegal positions
  -v       - win
  -v<n>    - win in n moves (n >= 1)

Option -f generates an output in standard FEN format, but in combination with
option -c produces an output in a modified and more compact FEN format where
the following items are removed:

     - the digits '8' present in the string
     - the number of void squares at the end of each rank
     - the ranks following the last man on the chessboard.

Option -l <lin> produces the result with men symbols in the selected language.
Option -t and -T are incompatible with other options, except directory and/or
language options.
The tablebase name is formed by the sequence of smallcase characters indicating
the men in Italian notation in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
(King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
followed by point and suffix.
The suffix <suf> is tbb when white moves and tbn when black moves.
The tablebase name must precede the output file, if any.

Example: gafs -l -d tables -v9 rdr.tbb kqk.txt
         (writes on file kqk.txt the list of all the positions of K+Q against K
          endgame when white moves and wins in 9 moves; the related tablebase is
          looked for in the directory ./tables)

NOTE

Files generated whit this command for 5 or more men endgames could have dimen-
sions of Gbytes order, if limiting criteria are not set.
Option -c is foreseen in order to reduce the file dimensions for very large
lists. 



Menu of valid options for command line: gafs -m ...:

  -1       - evaluates the RAM with the direct move algorith
  -2       - evaluates the RAM with the mixed move algorithm
  -3       - evaluates the RAM with the backward move algorithm (default)
  -b       - evaluates the RAM memory necessary using a block subdivision during
             computation
  -l <lin> - language used for messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -p       - evaluates the number of legal positions
  -v       - verifies positions legality by backmove
 <nomtab>  - name of the endgame to which the command is applied

Endgame's name is formed by the sequence of smallcase characters indicating the
men IN ITALIAN NOTATION in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
(King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
The options -1, -2 and -3 are mutually exclusive and operate only if associated
with the option -b.
Option -v, combined with option -p, makes more restrictive the legality check,
but increases calculation time noticeably.

Examples: gafs -m -p -v rprp
          (gives the dimension of the RAM and disk memory, requested for the
           calculation of the rprp endgame without subdivision in blocks, if
           such endgame will be solved by the backward move algorithm; moreover
           it computes the number of legal positions checked by the possibili-
           ties of a backmove)

          gafs -m -2 -b rttrta
          (gives the dimension of the requested RAM and disk memory, using a
           subdivision in blocks of the tablebases, if the endgame rttrta will
           be solved by the mixed move algorithm)


NOTE

This command is operative with endgames up to 8 men, assuming conventionally one
byte per position.



Menu of valid options for command line: gafs -t ...:

  -c       - produces the list without numerations, men symbols and separators
  -d <dir> - indicates directory (and path) of the tablebases necessary to
             the endgame, if different from current directory
  -f       - produces the output in FEN format (see the comment note)
  -l <lin> - language used for men symbols and messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -<rb>    - result when white moves (used as selection key)
  -<rn>    - result when black moves (used as selection key)
 <nomtab>  - name of the endgame to be searched
 <uscita>  - output file (default = screen)

Admitted values for <rb> and <rn>:

  -p       - all draws
  -p0      - stalemates
  -s       - losses
   s<n>    - loss in n (0 <= n < 127) moves
   v       - win
   v<n>    - win in n (0 < n < 128) moves

Option -f generates an output in standard FEN format, but in combination with
option -c produces an output in a modified and more compact FEN format where
the following items are removed:

     - the digits '8' present in the string
     - the number of void squares at the end of each rank
     - the ranks following the last man on the chessboard.

Option -l <lin> produces the result with men symbols in the selected language.
In the command line the two results -<rb> and -<rn> must be always given and
-<rb> must precede -<rn>.
Endgame's name is formed by the sequence of smallcase characters indicating the
men in Italian notation in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
(King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
The tablebase name must precede the output file, if any.

Example: gafs -t -d tables -v5 -v7 rdrd kqkq.txt
         (writes on file kqkq.txt the list of all the positions of K+Q against
          K+Q endgame, whose results are respectively win in 5 moves when white
          moves and win in 7 moves when black moves; the related tablebases are
          looked for in the directory ./tables)

NOTE

Files generated with this command for 5 or more men endgames could have dimens-
ions of Gbytes order, if limiting criteria are not set.
Option -c is foreseen in order to reduce the file dimensions for very large
lists. 



Menu of valid options for command line: gafs -v ...:

  -d <dir> - indicates directory (and path) of the tablebases to verify, if
             different from current directory
  -l <lin> - language used for messages.
             Possible choices for <lin>:
             it (default), cz, dk, nl, en (English), ee, fi, fr, de, hu
             is, no, pl, pt, ro, es, se
  -m <mmm> - indicates the memory in Mbyte given to the program
  -R       - verifies the correctness of the tablebases for the specified
             endgame and of the tablebases of all endgames obtained recursively
             by capture and/or promotion
  -s       - rewrites the statistics of the endgame on the screen and onto the
             file <nomtab>.stv in the specified directory
  -x       - in case of errors makes the corrections on the (binary) tablebases
 <nomtab>  - name of the endgame to check

Endgame's name is formed by the sequence of smallcase characters indicating the
men IN ITALIAN NOTATION in the following order:
    white King   white Pieces/Pawns   black King   black Pieces/Pawns
(King = r, Queen = d, Rook = t, Bishop = a, Knight = c, Pawn = p)
Option -m IS MANDATORY. It is convenient to use only PHYSICAL MEMORY (details
follow).
Option -s rewrites the statistical file at the end of the cheking, because such
file, written normally in the phase of generation (in ASCII format and with suf-
fix .stf), is sometimes wrong when the tablebase computation has been interrupt-
ed and restarted one or more times. If the verification time is foreseen as par-
ticularly long, the use of option -s is strongly advisable.
Option -x has only a debugging scope, because it permits the execution of direct
corrections of the tablebases on the basis of the checking procedure; sometimes,
but not always, this option, if used repeatedly, can eliminate all the errors
and can be useful for finding the programming error.
Options -s and -x are incompatible.

Example: gafs -v -d tables -m 210 -R rtard
         (verifies the correctness of the 2 tablebases of the endgame K+R+B 
          against K+Q and of all the derived tablebases; the related tablebases
          are looked for in the directory ./tables).

NOTE

The procedure is not mathematically unfailing because it is checked only the
consistency between the results for all legal positions.



IMPORTANT NOTE

- In running gafs it is strongly recommended of using always only the PHYSICAL
  MEMORY, that must be declared when the commands gafs -g for generation or
  gafs -v for checking are given, keeping into account that the program REQUESTS
  but DOES NOT CHECK the amount of memory allocated to the program by the user.
  When the declared RAM is not sufficient to contain all the necessary tablebases
  the program divides the tablebases in blocks automatically and uses the disk
  memory for reading and writing the blocks, simulating in such way a virtual
  memory under the control of the program itself.
  As a consequence assigning to the memory a value greater of the actual must be
  avoided and can have dangerous unexpected consequences.
  With the subdivision in blocks, the use of the magnetic disk increases very
  much in any case and this can represent a risk for the disk itself.
  Analyzing the three available algorithms (options -1, -2 and -3), the CPU
  time get smaller dramatically from the first to the third method, but with
  the subdivision in blocks the use of the disk increases strongly in the pro-
  portion of the numbers 1, 2, 10. 
  Therefore from first experiences with 6 men endgames the second method can
  represent the best solution, also keeping into account that the third method
  has still some unresolved problems.
  Nevertheless such algorithm has been chosen as default, because if the RAM
  is sufficient and no subdivion in blocks is necessary, it appears as the 
  fastest algorithm. 



LIABILITY

  IN ANY CASE GUIDO ANTONELLI SHALL NOT BE LIABLE FOR POSSIBLE DAMAGES ARISING
  FROM THE USE OF THE PROGRAM IN GENERAL AND, SPECIFICALLY, IN RELATION TO THE
  ABOVE EXPLAINED PROBLEM.



OTHER NOTES

- The program contains an internal check that reveals possible modifications in
  the binary code. For this reason the program starts rereading the exe file and
  checks a parity code. Under Unix/Linux the program must be stored in the
  current directory because the complete path is not transmitted to the program
  as command line parameter.

- The program has been accurately checked to avoid any damage to the user's
  files and in general to the computing system; nevertheless it is a good rule
  to run it in a context protected by the operating system itself. 

- For what I know, the program operates correctly in the generation of the ta-
  blebases when the total number of men is <= 5 and the program run on a pro-
  cessor with 2 Gb RAM (my computer). I checked the program successfully also
  with some simple 6 men endgames. The algorithm used in this case was the se-
  cond (option -2), which minimizes the total computation time, sum of CPU and
  I/O time. As it is statistically certain that the program contains errors,
  it can happen that the generation of particular endgames will be unseccessful
  also after days, weeks or longer periods of computation time with the conse-
  quences of the loss of all the work done until that moment.

- Men could be indicated in the following languages:

   it = Italian        cz = Czech          dk = Danish         nl = Dutch
   en = English        ee = Esthonian      fi = Finnish        fr = French
   de = German         hu = Hungarian      is = Icelandic      no = Norwegian
   pl = Polish         pt = Portuguese     ro = Roumanian      es = Spanish
   se = Swedish.

  but at present it is possible to use only Italian and English.



FUTURE DEVELOPMENTS

The program is almost completely realized in accordance with my present ideas
and therefore the developments should concern:

- Corrections of possible errors.

- Optimization of the code to speed up the calculations. 

- Checking of the program when the number of moves is greater than 126 (and
  successively 252). This has been done successfully for the only rpprp case. 

- Writing a program for generating bitbases directly.

- Finding ...some new idea!



THANKS

Thanks in advance to people who will give me hints and point out possible errors. 
If you have any questions, comments, etc., please feel free to contact me at the
above mentioned address.


Have a good time!

Guido