Configuring tsh

How to set up tsh for your particular tournament.

Updated Sun Apr 10 10:25:18 EDT 2005 for tsh 2.900.

After you've installed tsh, you need to set up a configuration file ('tsh.config') describing your tournament, and one ('.t') data file for each division. If you are reinstalling tsh after setting up these files, don't forget to copy your configuration and data files from your old tsh folder to the new one.

Pairings

tsh has a number of pairings commands, each of which adds one or more rounds of who-plays-whom information to the player data (".t") files. Pairing information must be entered before scoring information: the score entry command will not accept scores for players whose opponents are not yet known to the program. You should be familiar with the contents of the section on pairing theory and have decided on a pairing system for your tournament before reading further.

Most of the time, pairings are configured to be generated automatically. As explained below, you can specify which pairing commands get automatically triggered at which rounds. For example, you can tell tsh that the first seven rounds of your event is a round-robin, and the eighth round is a king-of-the-hill (KOTH).

You still need to know what the pairings commands are and how they work, for two reasons. First, even with automatic pairings you'll be entering the commands once, into a configuration file before the event begins. Second, there may be unusual situations in which you need to override automatic pairings: Gibsonization, serious errors in your planned pairings, etc.

tsh supports several different pairing algorithms, and if it doesn't support the one you want, let me know and I'll add it.

First-Round Pairings

If you are using fixed pairings, such as full or partial round robins, then the first round is no different from any other. Enter the command "rr a" to add a full round robin (to Division A). To set this up for automatic pairing, the configuration command would be "autopair a 0 1 rr a" ("automatically pair division A when round 0 results are complete and round 1 pairings are needed, using the command "rr a").

Note: Here and throughout the rest of this document, I will assume that you are running a multidivision tournament. If you have only one division in your tournament, you must leave out the division name from any commands you enter (but not right after the word "autopair". For example, with only division A, you'd enter "autopair a 0 1 rr".

If you are using Swiss pairings, it's a bit trickier. You need to start off the Swiss process with one or more fixed rounds based on pretournament ratings.

If you are using non-Fontes Swiss, or you have a very short tournament schedule (four rounds or fewer), then you should start by pairing the top half of the field against the bottom. That's what the Swiss command "ns 0 a" will do (for division A): it applies the Swiss algorithm with 0 (no) repeat pairings (which makes no difference, as players haven't faced any opponents yet). The "ns" command ranks players by their current standings, and since everyone is tied at 0 +0, it sorts them secondarily by their pretournament rating, and breaks further ties if necessary using a pseudorandom choice. To set this up for automatic pairing, the configuration command would be "autopair a 0 1 ns 0 a" ("automatically pair division A when round 0 results are complete and round 1 pairings are needed, using the command "ns 0 a").

If you are running a longer Fontes Swiss event, use the "if 3 a" command to add three fixed rounds (to division A, in this example). It takes one player at random from each quartile and schedules three-round four-player round robins. (Depending on the number of players, there may be six players left over who play a partial round robin.) It's a good way to make sure that everyone plays a good range of opponents before the Swiss pairings begin. It also gives you a good two-round shakedown period when if you fall behind with your data entry or your computer or your printer crashes, you don't have to worry because you have three rounds of pairings precomputed. To set this up for automatic pairing, the configuration command would be "autopair a 0 1 if 3 a" ("automatically pair division A when round 0 results are complete and round 1 pairings are needed, using the command "if 3 a").

Once you are sure that everyone has arrived, check to make sure that the pairings are the way you want them, by using the ShowPairings command. If you have to move people around from division to division after you have calculated pairings, use the "upr 1 a" command to remove pairings (in this case, for round 1, division A). If you have used the "if" command, you'll have to unpair first round 3, then round 2, and lastly round 1. Alternately, you can quit tsh and revert to a journalled backup data file.

If your pairing requirements for the first round can't be generated by an existing tsh command, and you can't reach me in time to implement them, you can use the "pm 1 a" command to interactively enter pairs of player numbers (in this case, for round 1, division A). You can also make minor tweaks using the "pair 2 15 1 a" command (in this case, to pair players 2 and 15 in round 1, division A).

Do the same for all divisions, then 'quit' if the tournament isn't going to start for awhile, or leave tsh running if it is.

Later Rounds

In later rounds, proceed the same as in the first round, using the "NS" (Swiss), "RR" (Round Robin), "KOTH" (King-of-the-Hill) or "PairMany" (manual) commands. If you run into an unusual situation, use the "PAIR" command to override pairings. If you want to use your automatically configured pairings except for a few overrides, be sure to use the "PAIR" command before the "ShowPair" command. If you accidentally use the "ShowPair" command first, use the "UnPairRound" command to undo its effects.

Byes

Byes are assigned automatically by tsh whenever pairings are computed in an odd division. The bye goes to the lowest-ranked among all the players who have the least number of byes so far.

To manually specify a bye, for example when a player does not show up for a game, enter (e.g.) "pair 0 12 7 b" to say that player #12 had a bye (opponent #0) in round 7, division B. If the bye is to be scored as a win, enter its score (using "a") as 50; for a forfeit loss, -50.

The 'tsh.config' file

You need to have a text file called 'tsh.config' in your tournament folder/directory. You can ask me (John Chew, jjchew@math.utoronto.ca) to create one for you if you give me a few weeks' notice. At a minimum, it should contain the line:

division a a.t

This line says that you will have a division called 'a' (or 'A', case doesn't matter), and that its data will be found in a file called 'a.t'. You can have as many divisions as you like, as long as they have different names:

division a a.t
division b b.t
division c c.t
division d d.t
division e e.t

If you have only one division in your tournament, it does not matter what you name it, and you won't ever have to type its name. If you do type its name, you will get cryptic error messages.

You should also specify how your tournament is paired. While you may need to override configuration settings and pair manually in some cases (we don't yet support automatic Gibsonization, for instance), using automatic pairings as described below will make your data entry person's life much easier.

Enter one line for each division and round that needs pairing. Here's a fairly simple example:

autopair a 0 1 if 3 a
autopair a 3 4 ns 0 3 a
autopair a 3 5 ns 0 3 a
autopair a 5 6 koth 0 a
autopair b 0 1 if 3 b
autopair b 3 4 ns 0 3 b
autopair b 3 5 ns 0 3 b
autopair b 5 6 koth 1 b

Each line consists of the command word 'autopair', a division name, the number of the round whose results must all be in before pairings can be calculated, the number of the round whose pairings will be calculated, and then a tsh command that generates the pairings. Don't worry about the details of that last command yet. (If you can't stop worrying, "if" means initialise Fontes Swiss pairings, "ns" means calculate new-style Swiss pairings, and "koth" means calculate King-of-the-Hill pairings.) In this example, rounds 1-3 are paired in a fixed schedule, rounds 4 and 5 are Swiss-paired based on round 3 standings, and round 6 is KOTH with repeats based on round 5 standings. You can read more about the theory of this in the section about pairings.

There are a number of configuration options that you can set using lines beginning with the "config" keyword. Perl hackers should note that "config whatever" results simply in the evaluation of "$config'whatever"; others should ignore this sentence. Here are all currently available configuration options:

OptionExampleDescription
assign_firstsassign_firsts = 1Have tsh randomly determine who goes first when players would otherwise have to draw.
autopair Set using the autopair instruction. It's not a good idea to mess with this directly.
backup_directorybackup_directory = './notold/'Override the default './old/' as a place to keep journalled '.t' files. Must end with a '/' or other locally appropriate path separator.
html_tophtml_top = '<p align=center><a href="event url"><img src="event logo"></a></p>'If defined, appears between the body and h1 tags at the top of each HTML page.
max_name_lengthmax_name_length = 22Specify minimum width of name fields, may get automatically increased by the presence of longer names in a ".t" file.
name_formatname_format = "%-22s"Specify sprintf(3) formatting of player names.
noboysnoboys = 1Disable David Boys' tweak to old Swiss pairings.
reservedreserved{'P'}[13] = 4Permanently assigns player P13 to table 4.
table_formattable_format = '%3s'sprintf(3) description of how table numbers are formatted.
tablestables{'A'} = [1,1,2,2,3,3,4,4,5,5]List which board is at which table. Division name must be capitalized. If you don't information for enough boards, you'll get cryptic error messages. You may use Perl expressions like 1..20 or map { $_, $_ } 1..20 to save typing.
track_firststrack_firsts = 1Make tsh care about who played first and second in each game.

Experienced thrill-seekers may also add lines to the 'tsh.config' file which begin with the keyword "perl". This is about as safe as using the tsh shell command "eval", and does the same thing: it evaluates its argument as a string. There is currently no good reason to use this command.

Once you have your 'tsh.config' file set up, you need to make each division (".t") file.

The ".t" Files

A '.t' file contains all the information for a division, and must also be in your main tsh folder. It's a text file that can be edited with a text editor if need be, and is usually created in the first place using a text editor. You may have received '.t' files for your tournament with your tsh distribution, but you should be familiar with the content of this section in case of no-shows and walk-ins.

A '.t' file should contain one line per player. The line should look something like this:

John Chew   1850 400 450 350; 10 4 3

In this example, a player named John Chew entered the tournament with a rating of 1850. In round 1, he played player #10 and scored 400 points. In round 2, he played player #4 and scored 450 points. In round 3, he played player #3 and scored 350 points. It doesn't matter how many spaces there are between the player's name and rating. Please use spaces though and not tabs.

Players must be listed in order of player number, beginning with player number 1. Note that this means that players must be numbered within each division starting at 1. Unless you feel strongly otherwise, you should number players beginning with the highest-rated. If you want to number players in two divisions in one numbering system without restarting from 1 at the top of the second division, you must call the two divisions one division for data entry purposes.

If you enable some optional features, you may find additional information at the end of some lines in your '.t' files. Each section of information is preceded by a semicolon, and consists of a keyword specifying the type of information followed by a series of data values separated by spaces.

When you first set up a tournament file, it will probably contain only player names and ratings. So your file will look something like:

John Chew          1850 ;
Sherrie Saint John 1300 ;
Kristen Chew       1200 ;

Player names may include any characters other than semicolons, and must not end in a digit. If you really have to have a player name that ends in a digit (it has happened), put a comma after the final digit and the comma will be silently omitted in reports.

Extended '.t' files may have additional data at the end of some or all lines. Each set of data is preceded by a semicolon and an identifying keyword. At present, the following extensions are in use:

p12 lists whether the player went first (1) or second (2) in each round. Rounds where the player went neither first nor second are marked 0, and rounds where the player is paired but it is not yet known whether they went first or second are marked 3.

off is present if the player is inactive for pairing purposes. It is followed by a single integer, indicating what spread ought to be awarded to them for each missed game. This feature is not yet fully implemented.

Dry Run

Once you have everything set up, preferably a few days before your tournament, you should try a dry run of your event. Save a backup copy of your ‘.t’ files. Enter one complete set of results for one division, then use the “RAND” command to quickly add additional random scores as necessary. Check to make sure that all of your pairings are generated in a reasonable manner, and in particular that you've chosen sensible times to allow repeat pairings. Try it a few times more with just the “RAND” command, then restore the original backups of your ‘.t’ files.

Backups and Redundancy

Now's probably a good time to think about what to do if disaster strikes. You should always bring an extra computer, extra computer and extra ink cartridges. If you are running a multidivision tournament and have extra staff, then you can use the extra equipment to split the data entry task across two installations of tsh, combining the two if some of your hardware fails.

tsh journals a copy of every ‘.t’ file after every change, which is useful for correcting errors, but not helpful if your hard disk crashes or your computer dies. Follow the standard rule for backups: make a copy of important files often enough that you don't mind having to type in any changes since your last backup. For ‘.t’ files, this should be somewhere between every round (to be safe) and every session (to live dangerously). Back up files to other computers, the net, and/or removable media.

If your computer fails and you do not have a spare computer, announce what has happened, gather scorecards and any qualified directors and do pairings by hand. Then write out "I will not run a tournament without a spare computer" enough times by hand that you learn your lesson.

If your printer fails or you run out of ink, in a small tournament you can probably write out or announce pairings aloud, especially if you just need to cover until you can find a replacement cartridge.