last update August 2018, version 7.4.2

program balans and related programs

The input of the programs takes place through commands in a console window
In MSWindows this may be a CMD window
in Linux or MinGW a terminal window.

For a description of programs balans, vernum and score2 see

http://www.pjms.nl/BALANS/balance.html

Starting with version 7.0 program balans takes the optimalisation beyond the 2-pair interactions that determine the quality factor Qf, by also considering the "vacancy quality". In the following we call Qf1 the quality factor when one pair is absent. Qf1av and Qf1max are the average value and the maximum of Qf1. For a discussion see

vacancy_quality.html

program balans.

To run balans, go to the directory where program balans.exe is located.
Then type the command:
balans [options] movement-file
example: balans -s 1000 nbb14.7.txt

Movement files

"movement-file" in the above is the file containing the movement, a text file with layout as may be seen in the examples. Movement files that confirm to this standard will be processed without problem. Some extensions to the standard are allowed
For a detailed description of the movement files, click here.

[options] stands for a number of possible options.
Possibilities (in the following n is a positive number):

 -c   : check the movement, no optimalisation
 -s n : use n iterations for the optimalisation
 -f n : keep first n positions fixed
 -r n : keep round n fixed
 -t n : keep table n fixed
 -i n : keep pair n fixed
 -j n : keep board group n fixed (n=number or capital letter)
 -R n : keep all rounds fixed except round n
 -D n : keep all tables fixed except table n
 -I n : keep all pairs fixed except pair n (and its direct opponents)
 -J n : keep all boards fixed except board group n (n=number or capital letter)
 -a fixerfile: supply r * t fixers 0=free, 1=fixed
 -v n : pair n is absent
 -z   : randomize compass directions before optimalisation
 -L   : indicate board sets by capital letters
 -p   : renumber pairs, give permutation on command line
 -m <filename> : export the updated movement to file <filename>
          (see also default filename)
 -Q   : quiet mode. Prints only balance characteristics
 -P n1-n2 (e.g. -P 4-8): preferred range of absent pair nr.
 -W w1:w2 (e.g. -W 0:1): relative weight of Qf1max and Qf1av
 -k 0 : don't optimize d4 / -k 1: optimize d4
 -S n:c1:c2 (e.g. -S 1:750:7.5): algorithm + optional temperature interval
 -T n : maximum time in seconds
 -h   : give a short description of the options

keeping tables fixed, -f -r -t -i -j -R -D -I -J -a fixerfile

There are several options to keep certain tables fixed in certain rounds.

-r -t -i and -j may be used several times to keep several subsets fixed simultaneously.
-R -D -I and -J may be used several times to release several subsets simultaneously. Example '-D1 -D3': keep all tables fixed except tables 1 and 3.

Option -f only works on the first n positions.

Option -a <filename> is the most general way to keep tables fixed. For an example of a fixerfile see file fixers.txt. This file may be used for a command such as:

 balans -a fixers.txt mitchell14.7.txt
The fixerfile may contain extra spaces and new lines.

Options -f -r -t -i -j overrule the data of the fixerfile.

remarks about keeping tables fixed.

If you switch all tables with the same board group the balance of a movement does not change. Therefore for every board group, you can keep one arbitrary table fixed without loss of generality. Many movements are organized in such a way that table 1, or round 1, or the first few tables of round 1, contain all different boards. Thus, in such cases the options -t, or -r, or -f may be used to fix those tables and still maintain generality
E.g. for an incomplete Mitchell with 16 pairs and 6 rounds:
balans -f6 -s1000 16p6rshortmitchell1.asc
However it is not always a good idea to do so. For large/difficult movements such fixing will make life harder for balans, producing slightly worse Qf on average. Instead don't fix anything during very long optimisation runs (and use option -S too). When the quality is satisfactory, or no more optimisation time available, you may then beautify the result using option -J of vernum to revert the movement to the same form as if you had fixed the first round or table initially.
Fixing more than one round/table, on the other hand, will usually make life easier for balans. But then you have to be careful that the extensive fixing doesn't completely exclude the optimal solution.

number of iterations, option -s

If you don't use option -s the program takes a default value, currently 2000. For small movements, say up to 20 pairs, this is usually sufficient, but if you want to be very sure it is advisable to take a larger number. For large/difficult movements consider option -S too (-S1...).

maximum time, option -T

specify the maximum time to be used, in seconds.
The first reached limit of either number of iterations or time causes balans to terminate and output results.

preferred range of absent pair nr, option -P nfirst-nlast

The argument consists of two parts, separated by a '-' or a ':'.
examples: -P 4-8, -P8
When nlast=nfirst the last part may be omitted: -P8 is equivalent to -P8-8.
The program selects the maximal Qf1 within this range, when there is a choice between equivalent movements.
Default is: consider all pairs.

relative weight of Qf1max and Qf1av, option -W w1:w2

The argument consists of two parts, separated by a ':'.
examples: -W 1:5 , -W0
If the w2 part is not given w2=1.0.
The numbers w1 and w2 are the relative weights to be attached to the vacancy quality parameters Qf1max and Qf1av.
The weighting function is Fw = w1 * Qf1max + w2 * P * Qf1av
where P is the number of pairs in the movement.
Normally the default value is w1 = 2.0, w2 = 1.0
However, when option -v is selected, or when P is odd, the default is w1 = 0, w2 = 1.
In this equation Qf1max is the maximum within the range given with option -P, but Qf1av is always evaluated over all pairs.
w1 and w2 may be given in the customary floating point notation optionally including sign, integer part, decimal point, fraction, exponent, e.g. +1.0e-2

Special values of w1, w2
w1w2 
0≠ 0 optimize Qf1av only
≠ 0 0 optimize Qf1max only
00 don't optimize Qf1max or Qf1av
 absentw2 = 1.0

optimize d4, options -k0 / -k1

When this option is enabled, and more than one solution is found with the same current optimal properties, the program takes the one with the smallest d4 (= 4th moment of the distribution of scorenumbers).
-k0 : turn d4 optimalisation off.
-k1 : turn d4 optimalisation on (default).

option -v

Option -v may be given only once per command. If the number given with -v is larger than the number of pairs for which the movement was made, the highest pair number is omitted.

The normal output of balans contains already the Quality factors Qf1(p) for all choices of absent pair p. With w2=0 combined with the option -P one can search for the optimum balance for any choice of absent pair(s), but this is in combination with maximum Qf for the full movement. Option -v should be used if you are not interested in the full movement, but only in the balance of a movement with one absent pair.

slow algorithm tuning, option -S n:c1:c2

The argument consists of up to three parts, separated by a ':'.
examples: -S1, -S1:150, -S1:110:22, -S 0:5:80
The algorithm number n is mandatory. The interpretation of the optional numbers c1 and c2 depends on n. Currently only two algorithms are defined, 0 and 1.

-S0 selects the default fast algorithm, taking c1:c2 (default 1:2000) as the start and peak temperatures. So not specifying -S at all is equivalent to -S0:1:2000. The higher the temperature (T), the greater the likelihood that we temporarily accept an arrow switch that increases the sum of squares (= decreases Qf). Such an increase may be needed in order to find an even lower value later on. T=1 is so low that essentially only immediate improvements are accepted. By default we start there. Later on, when T reaches the peak value 2000, the search will move around much more freely, closer to a random walk. With -S0 the temperature goes quickly up and down, up and down, with only approximately 100 iterations from peak to peak.

-S1 selects slow exponential cooling (or heating) from temperature c1 to temperature c2. This algorithm should not be used for movements where the default -S0 easily finds the optimal Qf and spends the rest of the time optimising Qf1max/Qf1av/d4. -S0 is best for those. -S1 is targeted at cases where the best Qf is hard to find.
The default for c1:c2 is currently very crudely set to P:P/4 where P is the number of pairs in the movement. So for a 56 pair movement specifying -S1 is the same as -S1:56 and -S1:56:14.

The default -S0 algorithm is always recommended for at least one or a few short runs before -S1 is tried out for a few short runs too, perhaps 10000 iterations each. That makes it easier to guess a more useful temperature interval than the default one for longer -S1 runs. For the 100 pair 99 round endless Howell the default interval 100:25 seems to be perfect. But for many other large and/or difficult movements the default end temperature is too low, catching the search in a local optimum too early on and just wasting CPU without being able to escape after that. On rare occasions the default start temperature is too low too. If the -S0 trial runs found new optima at high T, consider starting the -S1 runs at high T too. After a moderately long -S1 run, a further minor improvement can often be quickly obtained by a short reheating from below to above the temperature where the present solution was found. Fast improvements happen much less frequently when a solution found by -S0 is fed into balans. That's because the -S0 algorithm already includes such retries with reheating automatically, searching very intensely several times near non-transient new optima. A short -S0 run may also be used to harden the output of a long -S1 run. If you aim for more than minor improvements, it's probably better to spend most of the time on -S1 cooling in a rather narrow interval around the T where the previous result of a semi-long -S1 run was found - before the final short -S1 or -S0 hardening. The main problem here is that exponential cooling spends too much time at some temperatures and too little at others. Manually chaining -S1 runs with varying intervals is a work-around for that. In a future version we expect to provide more intelligent adaptive cooling, e.g. at constant thermodynamic speed.

Renumbering of the movement

option -L: translates the board groups to letters.
          If, for examples you have a movement that starts with
             8- 1 1    3- 6 4    2- 7 6    5- 4 7
          option -L will translate this to:
             8- 1 A    3- 6 D    2- 7 F    5- 4 G
          More possibilities to rearrange the board groups may be found 
          in program 'vernum', options -N and -n.

option -p: renumber the pairs. You must specify exactly the
          new order of pair numbers.
          The way this works is best illustrated with an example.
          Suppose we want to change the movement above such that in
          round 1 the order of pairs is 1 2 3 ...
          In other words we want to change
             8 1 3 6 2 7 5 4
          into:
             1 2 3 4 5 6 7 8
          Move the 1, together with the 2 below it, to position 1,
          etcetera, so we obtain the two rows
             1 2 3 4 5 6 7 8
             2 5 3 8 7 4 6 1
          The lower series is what you should specify in the 
          command, e.g.:
              balans -cLp howell4tafels.txt 2 5 3 8 7 4 6 1
          This will change the first line into the 
          "Universal Starting Position"
              1- 2 A    3- 4 B    5- 6 C    7- 8 D 

option -Q (= Quiet)

Output to the console (stdout) is suppressed. Only one line is output, with the results Qf, d4, etcetera. Of special interest when balans is called from a script or other program.

option -z (= randomize)

Before the optimalisation the NS and EW seatings are randomly switched.

executing the program

The program starts by presenting the original movement, and its balance parameters. Unless you specified -c it will then start to optimize. During optimization the program shows some information about the progress.

Finally the optimized movement is shown, as well as the scorematrix, a table of Qf1's, the sum of squares, standard deviation, Qf and a few other details.

The resulting movement is also written to a file as specified. Comments in this file give the most important characteristics of the movement.

Example:

 balans -r1 -t1 -P15 -s1000 mitchell16.asc
Starting from a standard 16-pair Relay Mitchell we want to obtain an optimized version in which round 1 and table 1 are kept fixed, and pair 15 is preferred as the absent one in case of a vacancy (because we then effectively avoid the board sharing between table 1 and 8). This leads to a movement with optimal balance, Qf=91.38 Qf1av=85.714, and fortunately also optimal balance if pair 15 is absent, Qf1(15)=Qf1max=87.50.
You may also use spaces between option and argument:
 balans -r 1 -t 1 -P 15 -s 1000 mitchell16.asc

If you want the console output in a file instead of the screen give the command::

 balans [options] movement-file > output-file
For another example see outputexample.html

Program vernum.

This is a version of balans in which all optimalisation possibilities have been removed and a few extra options are present to help in renumbering the pairs in a movement. Notice that options -R -D -I -J work differently from balans.

call:

  vernum [options] movement-file
[options] stands for a number of possible options.
Possibilities
 -Q   : Quiet mode, print the balance parameters only
 -h   : give a survey of the options
 -A   : output movement confirming to  Dutch standard
 -p   : renumber pairs (see above)
 -L   : translate board group numbers to letters (see above)
 -u   : renumber to "Universal Starting Position"
 -w   : Interchange NS, EW for all rounds and tables
 -z   : randomly choose NS, EW for all rounds and tables
 -f -r -t -i -j -a fixerfile: (see above)
        These options influence the effect of -w and -z
 -R <round> : Arrow switch of one round				
 -D <table> : Arrow switch of one table	in all rounds		
 -I <pair> : Arrow switch all tables where this pair plays
 -J <board> : Arrow switch all tables where this board group is played 
 -v n : calculation for the case pair n is absent
 -N   : Use numbers for the board groups in the output 
        (program takes default sequence)
 -n <lowest number>  : Use numbers for the board groups in the output
        but specify the sequence
 -m <filenaam> : output the resulting movement to file <filenaam>
                (see also default filename)
 -K <ntables> : sort the first <ntables> tables of every round according to boardset
                useful if you want to obtain a movement with stationary boards.
 -b <basis>   : output movement as a set of base movements
                to find the base movements in a compound movement such as
                used in scoring across the field.
 -o <offset>  : add <offset> to every odd pair number
 -e <offset>  : add <offset> to every even pair number
                for combining base movements to a larger movement.

Use of -n and -N

With -n a sequence is expected of all characters used for the board groups, in the order desired.

Example option -n

command:
vernum -n 7 schemafile.txt A B C D E F
changes 'A' into '7', 'B' into '8', etcetera.
Before:
10 6 6 6 0
 1  2 A    3  4 B    5  6 C    7  8 D    9 10 E    0  0 0
 4  7 A    6  9 B   10  8 C    2  5 D    0  0 0    1  3 F
 9  8 A   10  1 B    3  2 C    0  0 0    7  6 E    5  4 F
 6  3 A    8  5 B    0  0 0    1  9 D    4  2 E   10  7 F
 5 10 A    0  0 0    7  1 C    4  6 D    3  8 E    9  2 F
 0  0 0    7  2 B    9  4 C    3 10 D    5  1 E    6  8 F
After:
10  6  6  6 0 g
 1- 2  7   3- 4  8   5- 6  9   7- 8 10   9-10 11   0- 0  0  
 4- 7  7   6- 9  8  10- 8  9   2- 5 10   0- 0  0   1- 3 12  
 9- 8  7  10- 1  8   3- 2  9   0- 0  0   7- 6 11   5- 4 12  
 6- 3  7   8- 5  8   0- 0  0   1- 9 10   4- 2 11  10- 7 12  
 5-10  7   0- 0  0   7- 1  9   4- 6 10   3- 8 11   9- 2 12  
 0- 0  0   7- 2  8   9- 4  9   3-10 10   5- 1 11   6- 8 12  

Option -N is a simplified version of this. The sequence of letters is in the order in which they appear in the movement, and the numbers start with 1.

-n en -N may also be used if the board groups are already numbers. Then, for -n, specify on the command line the old numbers in the order desired. When, for example, you have a movement with board groups 11 .. 17, then

vernum -n 1 klad.txt 17 16 15 14 13 12 11
produces:
old:    17 16 15 14 13 12 11
new:     1  2  3  4  5  6  7 
If -p en -n are used simultaneously in one command supply first the pair numbers, then the board groups.

Option -u
Universal begin position. Take care! This option renumbers only the pairs, not the board groups. To get the board groups in sequence use option -N, possibly followed by a run with -L

Further options for the hobbyist

-K, -b, -o, -e ...
If these don't work as expected, please let me know. I'm always in for further suggestions.

Program score2

This program calculates the possible scores of a hypothetical match with 2 strong pairs in a field of average pairs. For a description of this model see the website.

call:

  score2 [options] movement-file

Options [n is an integer number]
 -T n : n = the score in percent of the strong pairs (normally 100)
 -e   : extensive output, all possible scores per pair for all possible
        choices for the 2 strong pairs.
 -d   : distribution of the scores (with sort of graph) on the screen.
 -x   : export distribution of scores to a file
 -1   : there is only 1 strong pair. For this option the options above are ignored.
 -h   : prints short survey of the options

The Bussemaker model

Simulations according to the Bussemaker model are also included in score2. The use of score2 for this model is described on a different page.

default file name

All three programs use the default file name _balans.txt. If you don't supply an option -m in balans or vernum the resulting movement is written to file _balans.txt. If you don't supply an input movement-file the program looks for file _balans.txt and uses it. This may be handy in subsequent calls. E.g., if you modify a movement using vernum and then you want to optimize it, all you have to do is type "balans".

Survey of options, programs balans, vernum and score2

Optionbalansvernumscore2
-h+++
-c+ignored 
-s iterations+ +
-r round++ 
-t table++ 
-f npos++ 
-i pair number++ 
-j board group++ 
-R round++ 
-I pair number++ 
-J board group++ 
-D table++ 
-v vacant pair nr++ 
-k 0 / -k 1+  
-P vfirst-vlast+  
-W w1:w2+  
-S n:c1:c2+  
-T time+  
-Q++ 
-m outputfile++ 
-a fixerfile++ 
-L++ 
-p++ 
-A + 
-u + 
-w + 
-n + 
-N + 
-K tables + 
-b base + 
-o offset + 
-e offset + 
-e  +
-d  +
-x  +
-T top  +
-1   (= score1)  +
-b  (Bussemaker)   +

Development environment

These programs are written in C, developed in the MinGW and Linux environments, and compiled with gcc or clang. The random numbers are generated by Mutsuo Saito and Makoto Matsumoto's SIMD-oriented Fast Mersenne Twister (SFMT) .