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
https://www.pjms.nl/BALANS/balance.html
New in version 8 of program balans is the use of multiprocessing. In order to take advantage of multi-core computers, the job is split up in several essentially independent optimisations that run in parallel. By default there are as many of these as there are cpu's available, but it is also possible to have less or even more copies. See option -s on how to specify the "ensemble size", i.e. the number of concurrent optimisations.
The optimisation algorithm has been improved, and some new options were added.
Since version 7 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
example: balans -s 1000 nbb14.7.txt
"movement-file" in the above is the file containing the movement.
Movement files that conform 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.
For the special cases of movement-file being a lone dash ('-') or absent, see Files.
[options] stands for a number of possible options.
Possibilities (in the following n is a positive number, or, in a few cases, 0):
-c : check the movement, no optimalisation
-s n:n1 : use n (super) iterations for the optimalisation
n1 is optional ensemble size, i.e. number of simultaneous optimisations.
-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 : randomise 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>
-m - : write the updated movement to console (stdout)
-V n : select amount of output. (-V0 silent, -V1 minimal, ..., see appendixQ).
-Q : quiet mode, print balance characteristics only, same as -V1
-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 (default -W 2:1)
-k 0 : don't optimise d4 / -k 1: optimise d4
-S n:c1:c2 (e.g. -S 2:400:0.01) algorithm + optional parameter(s), see appendixS
-T n : maximum time in seconds
-h : give a short description of the options and movement-file argument
-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.txtThe fixerfile may contain extra spaces and newlines.
Options -f -r -t -i -j overrule the data of the fixerfile.
balans -f6 -s1000 16p6rshortmitchell1.ascHowever 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.
A non-zero ensemble size of n means that |n| independent arrowswitching states are tracked more or less in parallel. If n is positive, all ensemble members start out in the same unswitched initial state. If n is negative, all but the first member start out in a randomised arrow switching state.
After each (super) iteration, the ensemble members are synchronised and their results compared to see if a new local optimum has been found.
If not specified, the ensemble size defaults to the number of threads. So on an Intel 4-core cpu with hyper-threading (2 threads per core) this is usually equivalent to using 8 ensemble members and 8 threads, 1 member per thread. However, if the environment variable OMP_NUM_THREADS is set to a positive integer value, then that number determines the number of threads and thus indirectly the default ensemble size.
| w1 | w2 | |
| 0 | ≠ 0 | optimise Qf1av only |
| ≠ 0 | 0 | optimise Qf1max only |
| 0 | 0 | don't optimise Qf1max or Qf1av |
| absent | w2 = 1.0 |
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.
option -L: translates the board groups to letters.
If, for example 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
1- 2 A 3- 4 D 5- 6 F 7- 8 G
More powerful options are present in program vernum
Finally the optimised 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.ascStarting from a standard 16-pair Relay Mitchell we want to obtain an optimised 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, assuming Universal Starting Position). 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.
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-fileFor another example see outputexample_en.html.
call:
vernum [options] [movement-file]As for balans, absent movement-file means read _balans.txt, while '-' means read standard input (see also Files).
[options] stands for a number of possible options.
Possibilities:
-Q and -V n : select amount of output (see appendixQ.html) -h : give a survey of the options -A : output movement conforming 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 program balans for details) 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 <filename> : output the resulting movement to file <filenaam> -m - : write the updated movement to console (stdout) -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.
vernum -n 7 schemafile.txt A B C D E Fchanges 'A' into '7', 'B' into '8', etcetera.
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 FAfter:
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 and -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 11produces:
old: 17 16 15 14 13 12 11 new: 1 2 3 4 5 6 7If -p and -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.
call:
score2 [options] [movement-file]
As usual, movement-file may be absent (read _balans.txt) or a dash ('-', read standard input)
Options (n is an integer number):
-Q and -V n : select amount of output (see appendixQ.html)
-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 the file hist.txt
-1 : there is only 1 strong pair. For this option the options above are ignored.
-b : Bussemaker model, see below
-h : prints short survey of the options
vernum -N -m- nbb14.7.txt | balans -r1 -Here vernum reads the input movement nbb14.7.txt, renumbers the board groups from A..G to 1..7 and writes the resulting output movement to the pipe (|). Balans reads from the pipe and writes the optimised movement to _balans.txt.
vernum -N -m- nbb14.7.txt | balans -r1 -m- - | score2 -
| Option | balans | vernum | score2 |
|---|---|---|---|
| -h | + | + | + |
| -c | + | ignored | |
| -s iterations:esize | + | + | |
| -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 | + | ||
| -V mode | + | + | + |
| -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) | + |