Configuring tsh

How to set up tsh for your particular tournament.

Updated 2020-01-11T11:00:00+05 for tsh 3.340.

After you’ve installed tsh, you need to set up a subfolder (directory) of your tsh folder containing a configuration file (“config.tsh”, formerly known as “tsh.config”) describing your tournament, and one (“.t”) data file for each division. You can run as many tournaments as you like with one installation of tsh, but each one should have its own folder.

About The “config.tsh” file

When you ask me to create your files, please e-mail me the following information: your name; your event’s name; the number of rounds in your event; the number of divisions in your event; the names, divisions and ratings of the players you expect will play, or at least an estimate as to the numbers of players in each division; the number of places to which prizes will be paid; the numbers of rounds after which breaks (for meals, snacks, or the end of a day) will be held; the pairing system you will use (I recommend Chew pairings); whether or not some number of finalists will advance to a separate final event; your game result sheet style: scores, spread or both; your board numbering style: by board or by table (which may have more than one board) or none; your board numbering sequence: restart at one in each division, or number continuously; whether you want to display player photos in scoreboards and pairings reports; whether you assign firsts (starts) and seconds (replies) or have the players determine them; whether you want to keep track of firsts/seconds (starts/replies); how many points of spread you customarily assign for a forfeit/bye: 50 or 75.

You need to have a text file called “config.tsh” in your tournament folder/directory. You can ask me (John Chew, poslfit@gmail.com) to create one for you if you give me a few weeks’ notice. There are also a few sample tournaments that come with the tsh distribution, and you can try modifying one of their configuration files to make your own.

Your configuration file consists of a sequence of lines. The order of the lines sometimes matters: you may run into trouble if you try to specify the properties of a division before you declare its existence. The first word on a line determines its type, of which there are currently eight:

• comment
• division declaration
• class declaration
• configuration option
• automatic pairing instructions
• prize declaration
• encoding directive
• Perl command

Note that the lines that appear in a configuration file are not regular tsh commands. Here is a very short sample “config.tsh” file.

# This is a comment because it starts with a '#'.
# The next line that you will store the data for Division a in file a.t.
division a a.t
# The next line says that the division has 3 prize classes
classes a 3
# The next line says that you want to keep track of 1sts/2nds (starts/replies)
config track_firsts = 1
# The next line says that Division A will play a simple round robin
autopair a 0 1 rr a
# The next line says that 1st place in Division A wins $25,000.
prize rank 1 A $25000
# The next line demonstrates the 'perl' command
perl print "Hello, world\n";

There's also an experimental configuration directive called ‘begin”, which gives a command that should be run whenever you begin working with the tournament.

The following subsections discuss each type of line in detail.

Comments

Comments begin with a ‘#’.

You may add as many comments as you like to your configuration file, and it’s a good idea to be verbose so that the next person who runs your tournament for you will know what you were thinking.

Division Declarations

Your configuration file must contain at least one division declaration, beginning with the word ‘division’, then followed by a space, a case-insensitive division name, another space, and a filename. Division declarations must come before any other reference to a division in a configuration line. Filenames may or may not be case-sensitive depending on your operating system. You may have as many divisions as you like, but each one has to have its own division name and file name. All divisions should play the same number of rounds at roughly the same schedule; if not, you should set up separate directories and configuration files for differently scheduled divisions, and run separate copies of tsh.

In a multi-division event, you should keep the division name short, as it will appear beside player numbers and you will need to type it to specify divisions. If you want a longer version of the name for display purposes, use the “config division_label” configuration option.

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. Except: if you give your only division a name that could also be a player number, some commands may get confused if you don't type the division name, so use alphabetical division names where possible. If you have more than one division, you should keep your division names short as you will be typing them frequently.

Class Declarations

Your configuration file may contain one or more class declarations, beginning with the word ‘classes’, then followed by a space, a case-insensitive division name, another space, and an integer greater than 1. Classes are typically used to award prizes to deserving lower-ranked players in a division.

If you specify how many classes a division has, then players will be assigned to equal-sized classes according to their pretournament ranking. Classes are named ‘A’, ‘B’, ‘C’... and are listed in the ratings and standings reports. This assignment takes place each time you run tsh: if you change player ratings, it may change player classes.

You can instead manually assign players to classes in the “.t” file using the “class” extension field, which you might want to do if labelling players in a particular group for use with the gibson_class configuration option to restrict opponents of Gibsonized players to members of one class. In this case, you would append to the end of each line in the “.t” file a semicolon, then the keyword “class”, then a space, then the name of the class.

Configuration Options

There are a large number of configuration options that you can set using lines beginning with the “config” keyword. All configuration options are at least theoretically optional, because they either have reasonable default values (which may depend on your configuration realm, or not required by all commands (a notable counterexample is the “max_rounds” option, which tells tsh how many rounds long your tournament is, and which is therefore required for the proper functioning of several pairing commands.

Here are all currently available configuration options:

Configuration Realms

Because tsh is used in many different countries with many different Scrabble traditions (and it’s even sometimes used for non-Scrabble events), tsh has a quick way of specifying common default values for configuration options that vary from country to country: the “realm” configuration option. The following table shows which default values are set according to the value of this option.

Configuring 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 one or more of the pairing systems described in that section for your tournament before reading further.

There are four ways of telling tsh what kind of pairings to use: default, automatic, custom and manual pairings.

Default Pairings

With default pairings the only thing you need to tell tsh is how many rounds your tournament is:

# The following config.tsh line says that this tournament has 12 rounds.
config max_rounds = 12

After you enter the results for each round, ask tsh for the next round’s pairings using the “ShowPairings” command and it will compute Chew pairings. (If the number of rounds is large compared to the number of players, one or more round robins will be scheduled first.) The following configuration options can be set to control how these default pairings work. See the detailed description of configuration options for their syntax.

Automatic Pairings

If you prefer to have more control over your tournament’s pairings, or have advertised the use of a specific system that is not the tsh default, you should use automatic pairings. This involves pre-entering all the pairings commands that you expect to use into the configuration file, where they will be automatically triggered when the time is right.

Each auto-pairing configuration 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.

For example, you can tell tsh that the first seven rounds of your two-division event is a round-robin, and the eighth round is a king-of-the-hill (KOTH):

# When Div. A has no scores and needs Rd. 1 pairings: RoundRobin A
autopair a 0 1 rr a
# When Div. B has no scores and needs Rd. 1 pairings: RoundRobin B
autopair b 0 1 rr b
# When Div. A has Rd. 7 scores and needs Rd. 8 pairings: 
# KOTH with one repeat allowed based on Rd. 7 standings, Division A
autopair a 7 8 koth 1 7 a
# When Div. B has Rd. 7 scores and needs Rd. 8 pairings: 
# KOTH with one repeat allowed based on Rd. 7 standings, Division B
autopair b 7 8 koth 1 7 b

When you ask for the first round’s pairings tsh will compute the round-robin, then later on when you have entered scores for the first seven rounds you can ask tsh for the eight round’s pairings and it will compute the KOTH. If you ask for Round 8 pairings before all results are in for Round 7, tsh will remind you that it can’t compute them yet.

Here’s a slightly more complicated example, for a six-round two-division tournament where the first three rounds are paired using the “InitFontes” command, the next two are paired Swiss based on Round 3 standings but with no repeats, and the last is a KOTH based on Round 5 standings with repeats permitted:

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 1 5 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 5 b

As explained in the section on manual pairings, you might still need to resort to manual pairings even when you have planned on using automatic pairings.

Custom Pairings

Some directors have developed regionally popular idiosyncratic pairing systems. For example, you might have a few rounds paired according to a fixed schedule, a few rounds of Swiss, and a few rounds of KOTH. You can select one of these by specifying a value for the “pairing_system” configuration option. The “ShowPairings” command will then generate pairings appropriate to the specified custom pairing system.

To add a new custom pairing system to tsh, please submit your request at least 1-2 months before its first planned use.

Manual Pairings

You should use manual pairings if you do not know in advance exactly how you will be pairing the tournament, such as when you haven’t decided when to start allowing repeats.

You might also find during your tournament that the automatic system you specified is impossible. For example, you might have asked for a round-robin followed by a KOTH with no repeats. You can quit tsh, edit the automatic pairing instructions and then try again, but if you’re under time pressure you’ll likely prefer to just enter the pairings commands directly and manually.

Prize Declarations

The “PRiZes” command lists all the prizes you are awarding, and if it can be automatically determined, who won them. If you want to use this command, you need to list your prizes in your configuration file using the “prize” instruction. You need one instruction in the file for each prize you are awarding. For example, if you are awarding a high game prize in each of four divisions, it will take four instructions to describe them. Unlike with most other lines in your configuration file, the order in which you enter prize instructions is important, as that is the order in which they will appear in the subsequent report.

Here are some examples of actual prize instructions from recent events:

prize note Place Prizes
prize rank 1 1 $25000
prize rank 2 1 $10000
prize separator
prize note Miscellaneous Automatically Calculated Prizes
prize tuffluck 1 1 $50
prize rank 1 1 $200 groupname='55+ Senior' members=[2,5,6,21,22,23,28,30,42,46,51,52,53,68,69,72,74,78,82,85,91,101,102]
prize brlh 1 1 $200 first=15 last=21 prizename='Division 1 Best Record Day 3 Lower Half'
prize highroundwin 1 1 $20 round=1
prize highroundloss 1 1 $20 round=28
prize lowwin 1 1 $20
prize separator
prize note Signup Prizes
prize signup 'Division 1 Biggest Comeback' 1 $75
# the following line awards a trophy to the top ranked player in division 4 class N
prize rank 1 4 Trophy groupname='Newcomers' class=N prizename="Newcomers Trophy"

Each line has several items, separated by one or more spaces. If an item has a space in it, such as “'Division 1 Biggest Comeback'”, enclose it in matching single or double quotes.

1. The first item has to be the word “prize”, to identify the line as a prize declaration.
2. The second item is the prize type: a complete list can be found below.
3. The third item is the prize subtype: usually the rank a player has to attain in the category determined by the prize type in order to win the prize. In the example above, first place wins $25,000 and second place wins $10,000. Negative ranks count from the bottom of the field.
4. The fourth item is the name of the division to which the player must belong in order to qualify for the prize. In the example above, all prizes are in Division 1.
5. The fifth item is the amount of the prize. This may be a cash value, or a description of merchandise.

In addition to these five items, you may have extra items consisting of an item label, an equals sign, and an item value. A complete list of these can also be found below.

Here is a list of all currently defined prize types. If you want to compute a prize that is not listed below, please ask and it will be added.

Here is a table of extra items that may be added to any prize declaration to refine the way prizes are awarded. Each must be followed by an “=” and a value. There must not be spaces before or after the “=”. If the value includes spaces, the entire value must be enclosed in “'”.

Encoding Directives

If you need to have text in your configuration file that is not in the ISO 8859-1 (Latin) character encoding, use the “encoding” directive to specify an alternate encoding. The new encoding should be named in the directive following white space, and takes effect immediately. If you have no idea what this is about, be thankful.

Raw Perl Commands

Experienced thrill-seekers may also add lines to the “config.tsh” 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 for using this feature.

The “.t” Files

A “.t” file contains all the information for a division, and must be in the same subdirectory as your “config.tsh” file. 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.

There is an experimental script for importing data from TourneyMan files. It’s called “parsetm”, is found in the “util/” directory and can be invoked from the command-line to turn one “.ltm” file at a time into a “.t” file. It has been thoroughly tested on the version of TourneyMan to be used at the 2005 US NSC.

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

Chew, John   1850 400 450 350; 10 4 3; p12 1 2 2; board 1 1 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. He went first in round 1 and second in rounds 2 and 3. He played at board #1 in rounds 1 and 2, and at board #3 in round 3. Anywhere where there is a space on the line, tsh will tolerate as many spaces as you like, but please do not use tabs. Of course, adding spaces within a player’s name will make many reports look odd.

Scores and opponent numbers may have the special value “00”, indicating that the value has not yet been assigned. This should not be confused with the “0” that indicates a bye.

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.

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

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

Player names may include any characters other than semicolons, and must not end in a digit. If you will be submitting your tournament results to a rating system, then you should spell your player names exactly the way that they appear in official rating lists. 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. Player names should be entered as shown above, with the surname (last name) first followed by a comma. If you do not do so, a few commands which need to know how to split names into given names (first names) and surnames will not function.

Not all files contain the same information for players. Some information only appears if some optional features are enabled. Each set of optional data is preceded by a semicolon and an identifying keyword. At present, the following extensions are in use:

If you have an Internet connection, you can update the tournament ratings in your player data files at any time using first the “UPDATERATINGS” command and then the “USERATINGS” command. This command is not available for all realms. If it doesn't work in yours, please ask for rating support to be added.

“.tsh” Archive Files

The “BUGreport” and “SUBMIT” commands generates (and depending on configuration may upload) an archive file which concatenates the configuration file with copies of each division data file wrapped between marker lines. Here’s a very simple example.

config event_name = "Sample Event"
config max_rounds = 2
division A a.t
division B b.t
#begin_file name=a.t
Chew, John    1800 2 2 ; 400 350
Chew, Kristen 1400 1 1 ; 350 400
#end_file name=a.t
#begin_file name=b.t
Chew, Jamie 1000 2 2 ; 400 350
Chew, Liam   500 1 1 ; 350 400
#end_file name=b.t

You may use this as an archive format for past events. tsh will accept an archive name as a command-line argument, but treats its data as read-only.

User Profile

If you find yourself running a lot of similarly configured events and want to save the common configuration instructions in one place, you can do so in your user profile using the “PROFILE” command. This command lets you manipulate a file called “lib/profile.tsh” that is currently identical in format to your “config.tsh” files, but is not intended to be edited directly.

A good value to store in your profile is configuration realm.

Dry Run

Once you have everything set up, preferably a few days before your tournament, you should try a dry run of your event. The easiest way to do this is to use the “DRYrun” command, which runs an entire tournament for one division on random data using the pairings you configured. After you’ve looked at all the reports it has generated, use the “RESETEVERYTHING” command to delete all the test data.

If you want finer control over the dry run, you can do what it does manually using the “ShowPairings” and “RANDomscores” commands.

There are also a number of unsupported scripts in the “util/” folder which do further analysis on dry runs, for the purposes of compiling statistics on pairing systems and predicting event winners.

Backups and Redundancy

Now is a good time to think about what to do if disaster strikes. You should always bring an extra computer, extra printer 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.