About tsh

... and its documentation.

Updated Fri Oct 14 15:18:12 EDT 2005 for tsh 3.000.

tsh is a Perl script for managing Scrabble tournaments, first written in 1999, continuously maintained since then and freely distributed for noncommercial use by John Chew <jjchew@math.utoronto.ca>. This document and tsh are copyright © 2005 by John J. Chew, III.

tsh is a program that deals with the logistics of running a tournament. With it, you can automatically or manually pair players, enter results, print standings, debug scorecard errors, estimate new player ratings and prepare data submissions for official ratings systems. tsh has been used at dozens of tournaments, producing high-quality pairings and reports with an estimated maximum operator:player ratio of 1:250.

If this is your first time using tsh, or if you have not yet used version 3.000 or later, you must read the Introduction. You may then continue with other sections listed at the top of this page. All users should at least skim the section on commands. Data entry staff should read the sections on data entry, generating generating reports and troubleshooting. At least one person at each tournament should have browsed all sections of the manual before the tournament begins, including those on installation, configuration and pairing theory. If you want to print a copy for your reference during the tournament, the entire reference manual is also available in one file.

Before each tournament, you should update your copy of tsh and read the news of what has changed in recent versions, and follow the links there to changes in the other manual sections.

Free telephone support is available by prior arrangement. If you are planning to use tsh at a tournament, please contact John Chew at least a few weeks in advance for help in setting up configuration files, and to discuss your support needs.

System Requirements

tsh is written in Perl, the multiplatform scripting language. Every released version is tested with OS/X and should therefore also run on common versions of Unix. tsh versions are tested a few times a year with Windows XP, and whenever a user requests it. If you are using an operating system not mentioned here, please allow a few extra weeks for any software changes that may be needed to bring the current version of tsh into compatibility with it.

Disk space and memory requirements are minimal, a fairly small number of megabytes each. One computer is recommended for every 250 or so players, and one networked printer per tournament, though having more of each will reduce data entry and report printing time and improve redundancy.

If an Internet connection is available at the event site, tsh can be used to automatically update web coverage of the tournament, and last-minute patches to the program itself can be automatically downloaded. If not, tsh can run without these features.

 

Troubleshooting tsh

What to do when things go wrong with tsh.

Updated Sat Jan 21 09:13:37 EST 2006 for tsh 3.050.

Installation

It's possible that some OS/X browsers may download a non-executable version of this file. If so, please contact me for instructions. If you can't reach me, move your tsh folder to your home directory, open a “Terminal” window, enter the command “cd tsh-nnnn” replacing “nnnn” with the version number that you downloaded, and finally enter the command “chmod a+x osx*” to mark the command executable.

Correcting Tournament Data

You can delete bad pairings using the “UnPairRound” command, edit scores using the “EditScore” command and delete bad scores using the “DELETEscore” command. See the command reference for the syntax of those commands.

If you have made a serious error, you can manually revert to an earlier version of any tournament data (“.t”) file. tsh journals a copy of the tournament data file into a subdirectory or folder named "old" after each major change. Quit out of tsh, then look for the last good data file (either by checking the timestamps or inspecting the contents of the files), rename the bad “.t” file to “.t.bad” and put a copy of the journalled “.t.lotsofnumbers” file in its place as a new “.t” file.

You can also edit “.t” files using a text editor. If you do so, first quit from tsh, because tsh keeps an internal copy of its data that will overwrite any changes you make when tsh next updates its files.

Crashes

If you are testing a new tsh feature, it’s possible that a program bug may put tsh into an infinite loop or dump core. In the former case, when tsh doesn’t give you a prompt, you’ll have to interrupt tsh and restart it. In OS/X and Unix, you interrupt terminal processes by pressing Control-C.

Some early versions of some pairings commands took a very long time to run. It’s possible that some bugs remain undiscovered. If you find that generating pairings in one particular situation takes excessively long (more than a few seconds), you may interrupt tsh, restart it, and then manually enter a faster pairing command. Allowing an extra repeat should in most cases substantially speed up the pairings calculations, or you can use the “PAIR” command to manually pair key players and then a regular command to pair the rest. In any case, in the unlikely event that this happens to you, please e-mail John a copy of the “.t” file involved.

As mentioned above, tsh journals its data after each major command, so if you are unsure about the condition of its files after a crash, revert to the last versions that were saved before the crash.

Errors and Informational Messages

If you aren't sure what an error message means, look to see if it has a code in [square brackets] at its end. If so, use the “HUH” command to ask for an explanation. If not, contact John and ask him to add an explanation.

If All Else Fails...

My phone number is (416) 876-7675. If you arrange with me beforehand, I’ll make sure that I’m easily reachable at that number during your tournament. If you didn’t prearrange my availability and you’re reading this because something has just gone unexpectedly wrong during a tournament, please try calling me anyway.

 

Introduction to tsh

How to get started with tsh.

Updated Tue Oct 25 16:25:20 EDT 2005 for tsh 3.020.

Overview

tsh is a program for managing a Scrabble tournament. Preferably long before the tournament begins, you need to decide the basics of how the tournament will run: how many players will play in how many separately paired divisions, how many rounds they will play, when any breaks will be, how the pairings will be determined and what prizes will be awarded. All of this information goes into an event configuration file.

As players register for your tournament, you should enter their names and pretournament ratings (if any) into the appropriate division’s data file. When you have a reasonable number, you can start running mock tournaments to make sure that you are familiar with the software and that the pairing system you have chosen works the way you want it to.

The event configuration files and the division data files belong in an event subfolder (subdirectory) of your tsh folder. You can and should use the “update” command to update your tsh folder whenever you have an Internet connection; it will not overwrite data in your event subfolders.

When all players are present or accounted for, you ask tsh for the pairings for the first round. tsh will display them on your screen and save a copy of the pairings to a printable web page. tsh saves a copy of most useful information that you’ve asked for in web pages. You may use this just for printing, or you may specify a public location for those files so that players and spectators can view the information directly.

As games finish, players submit their scores to you. You enter them into tsh, correct them if necessary, and at the appropriate time ask for the next round’s pairings. This goes on until the end of your tournament.

If you have prizes that can be automatically calculated (anything based on game scores, rather than individual plays or words), tsh will calculate them for you. If you are submitting your data for ratings purposes, tsh will prepare the data in the appropriate format.

Running tsh

This section, dealing with how to actually run tsh once you have it set up on your computer, is likely to be mostly unnecessary for most users and mystifying for many others, and is therefore addressed to those few who lie between.

Once you have installed and configured tsh, you’re ready to run tsh. Now tsh is a Perl script that runs under many different operating systems, and each operating system has a different way of starting programs. Broadly speaking, we can divide them into graphical methods and command-line methods. With the graphical methods, you need to find the icon appropriate for your operating system and (typically) double-click on it with your mouse to launch tsh, which will behave as though it was run from the command line with no “arguments”.

From the command line, you should in general enter some sort of incantation necessary to persuade your operating system to run tsh, followed by an optional “argument” giving the name of the subdirectory (folder) that contains the files for the event with which you want to work. If you do not specify an event, tsh will look first for the most recently updated configuration file it can find, or if none are available the oldstyle “tsh.config” file. Here's what to do for some popular operating systems.

Operating System Instructions
(Mac) OS/X Either open a Finder window to your tsh folder and double-click on the ‘osx-tsh.command’ icon, or follow the generic Unix command-line instructions. If you get a message saying that the file is not executable, see Troubleshooting.
Classic MacOS I have not supported Classic MacOS since 2003. If you need to use tsh with MacOS 9 or earlier, please contact me and I’ll fix a number of compatibility issues and create a double-clickable icon for launching tsh.
Any Unix (including Linux) Open a shell (terminal) window, cd to your tsh directory and enter “./tsh.pl” (or just “tsh.pl” if your path permits) followed optionally by a space and the name of the subdirectory with your event files. For example: “./tsh.pl toronto-2005”.
Windows Open a window to your tsh folder, then double-click on the “tsh” icon (if you have a properly installed version of Perl and a modern version of Windows) or “dos-run.bat” icon (otherwise).
DOS Type “perl tsh.pl”. If you want to override tsh’s choice of event directory, enter it on the same line: “perl tsh.pl myevent”. (To get a DOS command window under Windows, Choose “Run Command” from the Windows Start menu, then enter “command”.)
Other Check the “perlrun(1)” manual page concerning how to run Perl programs. Contact John Chew to have specific instructions added to this document.

If you get a message complaining that the configuration file can’t be found, make sure that your ‘.t’ files and ‘config.tsh’ file are together in one subdirectory, of the main tsh directory.

When you successfully start tsh, you should see a sequence of messages something like the following.

Welcome to tsh version 3.000 [iwelcome]
Loading configuration file. [iloadcfg]
Loading division A. [iloaddiv]
Loading division B. [iloaddiv]
Loading division C. [iloaddiv]
Loading division D. [iloaddiv]
Loading division E. [iloaddiv]
tsh>

The “tsh>” is your main prompt. If you have a system which supports it, the prompt will be in a distinctive colour. When you see it, you can type a command. After you type your command, don’t forget to press the return key.

 

tsh Commands

The basics of how to operate tsh.

Updated Thu Mar 16 10:26:49 EST 2006 for tsh 3.050.

How to Enter Commands

tsh is a command shell. If you’re familiar with using shells such as any Unix shell, OS/X Terminal or even DOS, you can probably skip this paragraph. A command shell is a no-frills way of interacting with a computer. In a large window, the computer displays a prompt, inviting you to type in a command that the computer understands. When you do so and then press the “return” key (analogous to hitting your clock in Scrabble), the computer takes some action based on what you’ve entered, then prompts you for your next command. Sometimes your command is modal, causing the computer to prompt for and expect a different set of commands until the mode is complete.

Pay attention to the changing prompts, which indicate what information tsh needs. Don’t forget to press the “return” key to confirm each command.

The Most Important Commands

The most important commands to remember are “quit”, “help” and “huh”.

Quit

The “quit” command makes tsh stop running.

HELP

If you’re not sure how to use a command, then try typing “help the-name-of-the-command”. Many commands are documented in this way, and soon all of them will be. Here’s an example, showing what one version of tsh shows when you enter “help help:

Usage: help topic

Use this command to view built-in documentation.  For fuller details, please
consult the HTML reference manual.  Enter 'help index' to see a list of
available commands, and 'help' followed by a command name to find out more
about that command. 

The first line tells you that when you use the “help” command you are expected to enter a topic after the word “help” so that tsh will know what you are asking for help about. Most commands require some supplementary information (called arguments) such as a division name, round number or player number.

HUH

If you’re not sure what a message means, and it has a code in [square brackets] after it, enter “huh the-message-code”. Again, messages are documented in this way, and soon all of them will be. If you enter “huh” on its own, the last message you saw will be explained. To take a mostly random example, if you saw the message “If you are sure you want to pair Round 12 based on Round 10, please specify config session_breaks. [eacpnsb]” you might want to know more and enter “huh eacpnsb”. You would then see the message:

[eacpnsb] It looks like you are relying on the default Chew pairing system, but
the program is not sure whether you wanted to compute pairings for the upcoming
round based on the first or second preceding round.  You can resolve the
ambiguity by setting a value for the configuration variable 'session_breaks' in
your configuration file. 

This tries to explain the original, brief message. If neither the detailed explanation nor the related documentation is clear to you, please ask John to provide further clarification.

tsh Command Reference

All currently available tsh commands are listed below in tables for reference, grouped by function. Most users will not use most of these commands. Each command has a name which verbosely describes its purpose, but which can be abbreviated to the portion shown in capital letters as shown in its example. Most commands must be followed (on the same line, before pressing “return”) by one or more arguments. These arguments are represented in examples by names, which must be replaced by actual values. If you don’t enter correct arguments, tsh will tell you what the correct ones should be, and where it stopped understanding what you were typing. Within modal commands, the syntax of what you are supposed to type varies, but is usually shown in the prompt.

To take one case, the example for the “RoundStandings” command, which displays standings in a division as of a specified round, reads rs r d. This means that “RoundStandings” can be abbreviated to its capitalised letters “rs”, and that it must be followed by a round number and a division name. You would enter “rs 5 b” and press the “return” key to ask for Division B standings as of Round 5. If you have only one division in your tournament, you may omit division names as arguments to commands. In the preceding example, you would just enter “rs 5”.

Data Entry Commands

The following commands are used for entering tournament results, as well as checking and correcting them:

CommandExampleDescription
Addscorea r dBegin entering new game scores for round r, division d. This command is modal, and keeps prompting for scores until you press “return” on a line without scores.
DELETEscoredelete p1 s1 p2 s2 r dDelete the previously entered scores s1 for player p1 and s2 for player p2 in round r division d. This syntax is intentionally verbose to discourage the use of this command.
EditScorees d p rBegin editing previously entered game scores, starting with player p in round r, division d. This command is modal and fully documented in the data entry section.
MISSINGmissing rList all players whose round r scores have not yet been entered.
showScoreCardsc d pShow the correct scorecard for player p in division d, for checking.

Report Generation Commands

The following commands generate reports based on tournament results:

CommandExampleDescription
ABSPgridabsp dShows a results grid suitable for submission for ABSP ratings.
AUPAIRaupair dCreates a .TOU file named for the division, containing ratings input information in AUPAIR.EXE format.
RATingsrat dShow current division standings (with ratings estimates) for division d.
ResultsByRoundrbr r1-r2 dRank players in division d based only on rounds r1 through r2, typically to compute “best results, day n” prizes.
ROTOroto rList rotisserie standings as of round r.
RoundStandingsrs r dShow standings for division d as of round r.
ShowPairingssp r dShow pairings for round r, division d.
STandingsst dShow current standings for division d.
showWallChartwc dShow correct wall chart for division d, to check against the physical chart.
UPSETsupset dShow ratings upsets for division d.

Pairing Commands

The following commands are used mainly for manually pairing rounds. You will need to know about them if you are configuring tsh before a tournament, or if you encounter an unexpected pairing situation and want to override automatic pairings. See the section on pairing theory for more detailed information about pairing systems.

CommandExampleDescription
CAMbridgePaircamp dSet up seven-round pairings as used in Cambridge ON for division d.
ChewPaircp sr dSet up Chew Pairings in division d based on round sr standings.
FactorPairfp rd rpt sr dPair players permitting rpt repeats based on sr standings in division d, optimally matching players whose ranks differ by rd.
InitFontesif nr dSet up fixed pairings for nr rounds (typically 3) in division d to give later Fontes pairings a place to start. Players are randomly chosen from quartiles and paired in round-robin quads.
KOTHkoth rpt sr dAdd king-of-the-hill pairings allowing rpt repeats (0 for none, 1 for simple repeats, 2 for threepeats), based on round sr standings in division d.
NewSwissns rpt sr dAdd a round of Swiss pairings. See KOTH above for descriptions of arguments.
PAIRpair p1 p2 r dManually pair players p1 and p2 in round r, division d. Use “0” as the player number of the opponent of a player with no opponent.
Pair1324p1324 rpt sr dPair 1–3, 2–4, 5–7, 6–8, and so on, i.e., factored pairings with factor two. See KOTH above for descriptions of arguments.
PairManypm r dBegin manually pairing a large number of players in round r, division d. This command is modal.
RandomPairrp rpt sr dAdd a round of random pairings to a division.
RoundRobinrr dAdd a full round robin to a division.
UnPairRoundupr r dDelete all round r pairings from division d. Only the last round’s pairings may be deleted, and only if no scores have been entered. Use DELETEscore to delete scores, or edit the “.t” files directly.

The following pairing commands are deprecated, but are listed in case there is anyone who is still using them. All of these commands have been replaced by NewSwiss, which produces much better quality Swiss pairings.

CommandExampleDescription
BYEbye p s r dDeprecated: use PAIR and Addscore instead.
PrePreSwissppsw rpt p1 p2 dDeprecated: use NewSwiss instead.
PRESWissppsw rpt p1 p2 dDeprecated: use NewSwiss instead.
SWisssw rpt sr dDeprecated: use NewSwiss instead.

Miscellaneous Commands

And here all the commands which don’t fit into one of the above categories:

CommandExampleDescription
DEBUGdebug code levelTurns debugging for sections labelled with code on if level is 1 or off if 0. Examine the tsh source code to find applicable codes.
EVALeval codeEvaluate arbitary perl code. Use only if you know what you’re doing.
HELPhelp topicDisplays builtin documentation. topic is typically a command name.
HUHhuh codeGive a detailed explanation of a diagnostic message that included a [code].
Lookl wordLook up word in dictionary. Optional, not yet part of the main distribution.
QuitqQuit tsh.
RANDomscoresrand d...Give each player in division d a random score, to help simulate a tournament’s pairing system. Entering more than one division acts on each division, entering a division name more than once adds more than one round’s worth of random data.

Plug-In Commands

There may also be external (plug-in) commands installed in your particular copy of tsh. These will be in a directory called ‘bin’, and listed in a configuration file there called ‘tshxcfg.txt’. They have been tested with OS/X (and should therefore work with most other flavours of Unix) and Windows XP, but may not work with more primitive operating systems. If not, you may still be able to use externals by running them separately from the command line. The following externals are part of the default distribution.

CommandExampleDescription
high-losshigh-loss divList top ten high losing scores in a division.
high-loss-roundhigh-loss-round divList highest losing score in each round in a division.
high-winhigh-win divList top ten high winning scores in a division.
high-win-roundhigh-win-round divList highest winning score in each round in a division.
low-losslow-loss divList bottom ten low losing scores in a division.
low-winlow-win divList bottom ten low winning scores in a division.
maketmmaketm divMake a TourneyMan data file for a division.
nsscnssc divList School Championship prizes for a division.
show12show12 divList firsts and seconds for all players in a division.
tufflucktuffluck divList players according to the total of their six closest losses, for the NSA’s “Tuff Luck” prize.
updateupdateUpdate tsh software using a web connection.

There are also a number of standalone utilities found in the “util/” directory, which are currently provided on an as-is basis.

 

Data Entry with tsh

How to enter tournament results using tsh.

Updated Fri Oct 14 16:32:54 EDT 2005 for tsh 3.000.

Entering Results

At the end of the round, have players or runners bring their scoreslips to you. Sort them by division, and then for each division do the following. Enter the command (e.g.) “a 3 d” to add Round 3 scores for Division D. At the sub-prompt (which will look something like "[D3]:pn1 ps1 pn2 ps2? (9 scores left)") enter the numbers as they appear on the score slip: player 1’s number, player 1’s score, player 2’s number, player 2’s score. Put spaces between the numbers, press return at the end. If your entry is accepted, it will be repeated back to you with the player’s names and new cumes displayed, and you’ll get another prompt. If the player numbers don’t match, you’ll be told so. If the cumes don’t match what the players wrote on the result slip, then sometime before the next round ends get their scorecards and correct the discrepancy.

If you want to enter a bye, just enter one player number and one score (usually 50, or -50 for a forfeit). If you want to switch to entering results for a different division, enter the name of the division by itself. If you want to correct a mistake in the scores that you just entered, enter “es” (see below). If you want to see which results are still missing, enter “missing” or just “m”. Whenever you want to save what you’ve entered, press the return key without entering any scores to return to the “tsh> ” prompt. You will also be returned to the “tsh> ” prompt if you enter something that tsh does not understand. tsh will by default save your data every ten entries: to adjust this change the value of “config save_interval”.

If you have tsh set to track but not assign who went first or second in each game, you must enter game scores in player order, with the number and score of the player who went first appearing first on the line. If tsh knows who was supposed to go first (because that player had had fewer firsts than his/her opponent), then it will complain that the players determined who went first incorrectly. If it doesn’t know, it will assume that you have entered them correctly and update its information about who went first. You can use the “EditScores” command to edit whom tsh thinks went first or should go first.

When you’re close to having all the scores in for a round, entering “missing 6” (e.g.) will list all the results you’re still missing for round 6. You can then ask a runner or word judge to politely ask the players to pause their post mortem long enough to fill out their paperwork. As noted above, you can also just enter “m” in AddScores mode.

Checking and Correcting Results

If you make a mistake entering the score for division B player 4 in round 3, enter “es b 4 3” (or “editscore b 4 3”) at the “tsh> ” prompt. You’ll get a mockup of the player’s scorecard as it currently reads, a sub-prompt that gives you that player’s score that round and their opponent’s score that round, and you can reenter both (separated by a space, or just one score if a bye), choose a different division, round or player if you made more than one mistake, or enter “first” or “second” if you have tsh set to track firsts and seconds but have misentered one player’s information.

You can also use the “editscore” command to make corrections to player pretournament ratings. If you have not entered any scores yet, you may ask to edit the scores for the fictitious “Round 0” in order to change ratings.

If you catch your mistake while you’re still in “Addscore” mode, you can just enter “es” (without any additional arguments) at the “Addscore” prompt. You’ll go temporarily into “EditScore” mode, looking at the data that you just entered. When you exit “EditScore” mode, you will return to “Addscore” mode.

You may wish to check what you have entered against player scorecards or against the tournament wall charts. See the section on generating reports for information on how to do this.

If you have a serious problem, you may need to edit the tournament data files directly. Pay particular attention to the information in the preceding link about how to find copies of older, journalled versions of data files. For example, if you find after entering half of the results for a round that the other half of the players used a different round’s pairings to find their opponents, you will have some careful typing to do to fix the files. (Not that this has ever happened to the author, though he has lain awake at night worrying about similar scenarios.)

As soon as you have finished entering and checking results for a round, you should prepare and print all necessary reports for the next round.

 

Generating Reports with tsh

How to list standings, pairings and more using tsh.

Updated Thu Mar 16 10:24:18 EST 2006 for tsh 3.050.

tsh has a number of commands for listing information about what’s going on in your tournament. All of this information is listed on your screen when you ask for it. Most of it is also saved as a printable HTML file in your event directory, and optionally as a printable text file and as an online HTML file in an automatically indexed web directory.

config no_text_files” controls whether or not text files are created, and option “html_directory” controls whether and where online HTML files are created. To adjust the formatting of the HTML file, edit the “tsh.css” stylesheet file.

Pairings

Before each round begins, you need to print up pairings, showing who is playing whom where. If you are using Fontes Swiss pairings, these pairings will typically be available sometime in the middle of the preceding round, as soon as you have finished entering and checking the second preceding round’s results. You should post them as quickly as possible, so that anyone who finishes their game early will know right away who their next opponent is.

If you are using automatic or default pairings (and you should be), there may be a slight delay when you first display the pairings for a round, as tsh computes them. It is also possible that tsh might tell you that it can’t yet compute the pairings for a round, because all of the results it needs have not yet been entered. If you are not using automatic pairings, then see the section on manual pairings before displaying pairings.

You show pairings using the “ShowPairings round division” command. To list pairings (e.g.) for round 5, division C, enter the command “sp 5 c”. (If you have only one division, you may omit it, so you’d enter “sp 5”.) As noted at the beginning of this section, this will display on your screen who is playing whom where, create two printable HTML files called “C-pairings.html” and “C-alpha-pairings.html” and optionally create a text file called “C-pairings.doc” and an online HTML file on a web server. You can then either open the text file with a word processor, format it if necessary and print it, or open the HTML file with a web browser and print it directly. If you have enabled the “track_firsts” configuration option, games where tsh knows either who should go first or if a draw is required say so.

If you are using OS/X, you can open the documents from a second Terminal window using the “open” command. You can also print them directly to your default printer using the “lpr” command, though CSS formatting may not apply.

If you are using Windows, be sure to close whichever files you opened, or else tsh will not be able to update them again. Remember too that the files in your event directory contain whichever pairings you last asked for, so if you go back and look at round 3 pairings to check something, that’s what will be in the files, and it probably won’t be what the players want to see printed. The files in your web server directory (if specified) record information for each round separately, and keep track of the last displayed version of the pairings for each round.

Standings and Ratings Estimates

The “RATings division” command shows current standings with estimates of new (Elo/NSA or ABSP depending on the value of “config rating_system”) player ratings. “rat a” will tell you what Division A ratings would be if the tournament ended right now. You should use this command when all the scores are in for a round, and print its report. For NSA events, the rat” command does not yet split-rate 3-part tournaments or 1/3-rate local club tournaments, but it will do so as soon as someone asks me to implement these features. Files are created as with pairings.

You can show standings from earlier rounds using the “roundstandings round division” command. Entering “rs 4 d” will give you the standings as of round 4 for division D. This command does not generate printing files, as it is used mostly to quickly check past pairings, and because you will typically already have printed copies of the standings for previous rounds as well as web files from previous reports of ratings estimates.

The now deprecated “STandings division” command does what the “RATings” command does, but without the ratings estimates, and is kept largely for use at nonrated events. Entering “st c” will give you the current standings for Division C. Files are created as with pairings.

The “tourney.pl” program can be used to produce detailed tournament reports which combine standings, estimated NSA ratings and scores of all games. In Unix, enter “tourney.pl a.t > a.txt” or “tourney.pl -d 10 a.t > a.txt” (to split-rate after 10) to create a file called “a.txt” containing a report based on the data in “a.t”.

Ratings Data Submission

tsh creates ratings data files in three different formats, depending on which rating system you will be submitting your data to.

NSA Ratings

The NSA web site accepts tsh’s own “.t” files for ratings data submission, and Joe Edley prefers that one data file be submitted per tournament rather than one data file per division. There is a stopgap script that can be used at the shell prompt (in Unix) to create a combined submission file for a multidivisional tournament: “util/concat-t folder/*.t”, which creates a file called “all.t” from all “.t” files in the folder named “folder”. In the not too distant future, tsh will be better integrated with the NSA rating data submission system.

ABSP Ratings

The “ABSPgrid” command generates a ratings grid for submission to the ABSP. The grid is a text file which is displayed on the screen and saved to a file.

AUPAIR Ratings

The “AUPAIR” command generates a “.TOU” file in the format used by the “AUPAIR.EXE” program. The file is not displayed on the screen. “AUPAIR.EXE” is used by Bob Jackman and his International SOWPODS Rating System, and by many countries in southeast Asia.

Prizes

You can show standings based on a range of rounds using the “ResultsByRound firstround-lastround division” command. Entering “rbr 1-7 b” will give you the standings based on the first seven rounds for Division B. Files are created as with pairings. This command is typically used to compute "best result day n" prizes.

There are external commands for computing high and low win and loss. For example, “high-win a” lists the top twenty game scores in division A, the rounds in which they took place, the losing score and the names of the players involved.

There is an external command for computing the NSA’s “Tuff Luck” prize based on the lowest total of six losing spreads: “tuffluck a” lists the “Tuff Luck” standings for Division A.

If you run a rotisserie pool, you can use the rotofile configuration option to specify the location of a text file giving the structure of that pool, then use the “ROTO” command to display current standings. Each team is represented by a list of names, followed by a blank line. The team owner’s name is preceded by the word “owner” and a space, each team member’s name is preceded by the word “player” and a space.

TheUPSETs” command lists the top twenty ratings upsets: games in which a significant ratings underdog managed to win.

Checking Scorecards and Wall Charts

tsh includes commands for producing electronic versions of player scorecards and tournament wall charts. These were originally intended to allow you to check these documents and correct your data. As of 2005, the only official version of the tournament results is deemed to be the data that you entered from the result slips, so these commands should be used only to point out and explain errors in the printed documents, or to replace a lost scorecard at a player’s request.

You can show a scorecard using the “ShowscoreCard division player” command. Entering “sc j 5” will give you the scorecard for player J5. A file called “J-scorecard.html” will be created, which can be printed and given to a player who has lost their original scorecard. Scorecards are also displayed whenever you use the “EditScores” command. When a score has been added to a scorecard within the last two hours, the age of that modification in minutes is shown at the top of the card. This is to help determine whether an absent player may be away taking a break from a game that ran unusually late.

You can show a wallchart using the “showWallChart division” command. Entering “wc g” will give you the wall chart for division G. Typing a round number before the division name will start the wall chart at that round, in case your wall chart would otherwise be too wide to print nicely. Files are created as with pairings.

 

Installing tsh

How to obtain and install what you need to run tsh.

Updated Sat Feb 11 21:33:16 EST 2006 for tsh 3.050.

What You Need

You need a copy of Perl, a text editor to edit configuration files, master sheets from which to print score slips and other forms, and the ZIP archive of the complete tsh distribution.

Perl

First, you should make sure that you have a recent version of the freely available Perl interpreter installed on your machine. Perl runs under several operating systems, including but not limited to Unix, MacOS, VMS and Windows. If you don’t have a copy installed on your machine, you can download one from www.perl.com. Pre-OS/X Macintosh users can download a pre-compiled application from www.macperl.com (but be warned that the current version is not guaranteed to be Classic MacOS compatible — contact me for details); OS/X and many other versions of Unix come with Perl. Windows users can find a good Perl interpreter at ActiveState (look for ActivePerl, go to the free download section and download and run the Windows MSI installer).

Text Editor

You will also need a text editor. You will use it to set up config.tsh, your settings file. You may also use it to edit tournament (".t") files if you find you need to do something in the heat of a tournament that I didn’t expect you to need. If you’re a Unix user, you know which editor is the One True Editor and don’t need to be told. (It’s vim, of course.) If you’re a Classic MacOS user, SimpleText will do in a pinch, but BBEdit is much better. Mac OS/X users can use vim, vi, pico, or TextEdit, but they should be careful not to use a Classic mode editor like BBEdit unless they are careful to specify Unix line breaks. Windows users can use Notepad.

Forms

Score slips should be prepared to work best with tsh’s workflow. They should contain the following information in the following layout:

1st player (start): 1ST-NUMBER 1ST-SCORE 1ST-NAME 1ST-INITIALS
2nd player (reply): 2ND-NUMBER 2ND-SCORE 2ND-NAME 2ND-INITIALS

The fields may be rearranged to some extent to suit layout constraints, but the important thing is that the numeric information that needs to be entered into tsh appears in the “1st-player-number, 1st-score, 2nd-player-number, 2nd-score” order in which it will be needed.

If you use a self-posting wall chart, it should be set up so that the player names read down the left side and the round numbers across the top.

I have master sheets for stickers and score slips available for download in PDF format.

tsh.zip

All of the files you need to use tsh, except for configuration files specific to your event, can be downloaded in one zip archive. When you have downloaded and expanded the archive, you then need to set up those configuration files.

Updating tsh

tsh is a work in progress: it’s updated several times per year to include helpful suggestions from its users. Older versions are available for download from the tsh web site but are not supported. You should be sure to upgrade to the current version when you get ready to run a tournament.

If you have a copy of tsh 2.975 or later and a modern operating system (such as OS/X or some other kind of Unix, or even Windows XP), you can update your copy of tsh by simply entering the “update” command at the “tsh>” prompt. Your machine must be connected to the Internet when you enter the command for this to work. If you lose your connection during an update, just enter “update” again when your connection is restored.

The “update” command gives you the newest possible version of each file, which may be newer than the currently posted official ZIP archive.

If you can't run tsh to use the “update” command, try running the “get-tsh.pl” script in your tsh folder.

If you have an older version of tsh, download the current ZIP archive, and don't forget to copy over your event files to the newly created folder.

 

Configuring tsh

How to set up tsh for your particular tournament.

Updated Mon Jan 16 11:15:51 EST 2006 for tsh 3.040.

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

You need to have a text file called “config.tsh” 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. 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 has four types of lines in it: comments, division declarations, configuration options and automatic pairing instructions. Each is identified by the first word on the line, as shown in the following example of a simple tournament’s configuration 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 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

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.

Your configuration file must contain at least one division declaration. Division names are case-insensitive. 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.

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, some older commands may give you cryptic error messages. If you have more than one division, you should keep your division names short as you will be typing them frequently.

Automatic pairing instructions and configuration options are discussed in detail below.

Configuration Options

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.
colourcolour = 'no'Enables use of ANSI colour escape sequences to highlight text in the tsh session.
colour = 'yes'
event_nameevent_name = "Toronto 2005"Used to identify the event, particularly when exporting to AUPAIR.
external_pathexternal_path = ['./bin','../bin']Used to specify where external commands can be found. Default value is ['./bin'].
gibsongibson = 1Enable automatic detection of Gibson situations. When using default or Chew pairings, tsh always looks for possible Gibson situations. When using automatic pairings, tsh does or does not check depending on the value of this option.
gibson_groupsgibson{'A'} = [[1,2]]Indicates when using Chew pairings Gibsonization detection that the bracketed ranks are to be considered equivalent for Gibsonization purposes. In this example, where the top two players go to the finals, a player should be Gibsonized if they have clinched a place in the top two, even if they haven’t clinched first place. If you also wanted to have ranks three through five be considered equivalent to each other, the right hand side ought to be “[[1,2],[3,4,5]]”.
html_directoryhtml_directory = '/Library/WebServer/Documents/myevent/tsh/'Override the default “./html/” as a place to keep round-by-round “.html” reports. Must end with a “/” or other locally appropriate path separator. The example given places reports on the local machine’s public web server under OS/X.
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.
initial_exagonyinitial_exagony = 1If used, prevents players from the same team from facing each other in first-round random pairings. See also the “team” extension field.
manual_pairingsmanual_pairings = 1Use neither auto-pairings even if configured, nor Chew pairings in the absence of auto-pairings.
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.
max_roundsmax_rounds = 12Specify the last round in the tournament. Used in Gibson detection, and to check for illegal round numbers in commands.
name_formatname_format = "%-22s"Specify sprintf(3) formatting of player names.
no_text_filesno_text_files = 1Do not create text versions of reports. Useful if you only want HTML files, and don’t want your directories cluttered with text files.
player_number_formatplayer_number_format = "#%s"Specify sprintf(3) formatting of player numbers. By default, a "#' is prepended to the number for clarity if there is only one division.
prize_bandsprize_bands{'A'} = [2,10]Used in Chew pairings to specify which final ranks are to be considered equivalent for pairings purposes. In the example, ranks 1 and 2 are equivalent (presumably allowing entry to a two-player final round) as are ranks 3-10 (presumably awarding players cash prizes). If this option is omitted when required, a warning is displayed and a value of [1] is assumed: finishing first is important and nothing else matters. Note that with a value of [1], Gibsonization is effectively disabled, because the “highest ranked player out of contention for prize money” that the Gibsonized player ought to play ends up being the second-ranked player.
rating_systemrating_system = 'absp'If set to 'absp', computes ABSP ratings instead of NSA ratings in the “RATings” command. Also affects the way pretournament ratings are used to influence the scores generated by the “RANDomscores” command.
reservedreserved{'P'}[13] = 4Permanently assigns player P13 to board 4. Typically used when you have a player with special needs.
rotofilerotofile = 'roto.txt'Specify the name of a rotisserie pool file to be used in producing rotisserie pool reports.
save_intervalsave_interval = 10Specifies how often results should be saved to disk in “Addscore”. Defaults to every ten new entries.
session_breakssession_breaks = [3,6,8,11,12]Specifies after which rounds there is enough time in the schedule to wait for all results to come in before computing pairings. Used when the “ChewPair” is automatically invoked.
show_teamsshow_teams = 1Show team names with player names.
split1split1 = 9Specifies after which round a long tournament should be split-rated when using Elo ratings.
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 give 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. If this option is set and assign_firsts is not set, tsh will use the order in which scores are entered to determine who played first, and complain if the wrong player did. If this option is set and you use Chew Pairings, the pairing algorithm will have a weak preference for pairing players due to go first with players due to go second.

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 to use this command.

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 three ways of telling tsh what kind of pairings to use: default, automatic 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. The following configuration options can be set to control how these default pairings work. See the detailed description of configuration options for their syntax.

OptionEffect
autopair If set, prevents default pairings from being used.
manual_pairings If set, prevents default pairings from being used.
max_rounds Required by the Chew pairing algorithm.
prize_bands Should be set to indicate which final ranks are equivalent preceding round’s scores during sessions. If you do not set it, you will be warned that you have not set it each time pairings are calculated.
session_breaks If set, pairings may be calculated based Fontes-style on the second preceding round’s scores during sessions. If not set, pairings will only be calculated once the immediately preceding round’s scores have all been entered.

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 next section, you might still need to resort to manual pairings even when you have planned on using automatic pairings.

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 may also have to use manual pairings if you use one of the older automatic pairing systems that detect Gibson situations but do not automatically assign Gibson pairings. In such cases you typically manually assign the pairing just for the Gibsonized player, and then try automatic pairings on the rest of the field.

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.

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.

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 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:

KeywordData
board Lists at which board the player played in each round. This is typically set by the “ShowPairings” command the first time pairings for the round are shown, and not changed thereafter.
cume Is present if the player’s cume must be set to a given value. It should be used with extreme caution, as it will override the regular calculation of cume in all rounds. This feature is not yet fully implemented.
cumeadj Is present if the player’s cume must be adjusted, typically to compensate for a misadjudication. It should be followed by one or two values, the first the amount of the adjustment, the second the round in which the adjustment should first be applied. This feature is not yet fully implemented.
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.
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, rounds where the player is paired but has to randomly determine whether or not s/he goes first are marked 3, rounds where tsh is not sure who will go first or even whether a random determination will be required are marked 4.
team Names the player’s team, for use when “config initial_exagony” is enabled. The value is a case-sensitive single-word code with no spaces.

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.

The “util/” folder contains an unsupported script currently called “simwsc” which has hardcoded values in it to perform a full-tournament simulation for pairings testing purposes.

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.

 

Pairing Theory and tsh

Some background on how pairing systems work.

Updated Mon Jan 16 14:53:00 EST 2006 for tsh 3.050.

This section discusses the theory behind scheduling pairings for tournaments and the details of the pairing systems implemented in tsh. See elsewhere the table of tsh’s pairing commands, and the discussion of how and when to use them.

Goals

The following are desirable properties of a pairing system. It is impossible to satisfy all of these properties simultaneously.

PropertyDescription
“Aristomachy” Top players should be paired with each other, especially toward the end of the tournament. King-of-the-Hill pairings do this best, Round Robin pairings do this worst.
Division Sizing Some pairing systems (notably round robin) require specific numbers of players. The number of players is usually not under the director’s control, though often their assignment to divisions is. A small number of large divisions permits smaller number of larger prizes but requires players to face opponents of more widely ranging ratings.
“Exagony” Players travelling together to a tournament do not like to play each other, as many players travel to vary their opponents. At the World Championships, unnecessarily pairing together players from the same country may make it difficult for them to earn an additional place at the next WSC.
Fairness The final ranking of players by the customary win-loss record and cumulative spread should be equivalent to a ranking according to their level of performance in the tournament. Three possible ways of measuring the latter are to average the final rankings of the opponents of each player (Average Opponent Ranking or AOR, to add the number of wins and spread of the opponents of each players (Sum of Opponent Scores, SOS or Buchholz), and uninitialised iterated performance ratings (IPR, the ratings that players would have if they had all arrived at the tournament unrated).
Implementability A good human director can pair 50–100 players by hand if a dynamic pairing system is not too computationally demanding. Computers can currently do brute-force exhaustive searches for optimal pairings up to groups of about 16 (for which there are 2,027,025 possible pairings), use smarter algorithms for very difficult pairing situations involving twice as many players, and can easily apply complex rules to larger groups to find pairings which match well-designed criteria.
Incentivization A player should not be placed in a position where tieing or losing is strategically preferably to winning. For example, a player who has clinched a place in a two-player final should not be paired with a possibly weak player whose victory would send him to the finals.
Inclusivity A player should not needlessly be excluded from contention for a prize by being paired with someone who is out of contention. For example, if with one round left to play the top three players have N, N and N–1 wins and the top two have a 500-point spread advantage over #3, then #3 needs to play #1 or #2 in order to have any reasonable chance of finishing first.
“Monagony” Players should play each other as few times as possible. Repeat pairings can prevent other players from catching up to the repeaters, and do not accurately measure the repeating players’ ability to defeat a wider field. Players also do not in general like playing each other in consecutive rounds.
Monotony A lower-ranked player should not be paired so as to make it more likely that he will become the overall winner than that a higher-ranked player will.
Suspense The outcome of the tournament should be determined as late as possible.

Gibsonization

David Gibson, the all-time top money winner in the history of Scrabble, has made a habit of clinching victory in major events without waiting for the final round. Because of this, players are said to be “Gibsonized” when after clinching, they are paired with lower-ranked players to avoid affecting the ranking of runners-up. tsh has two mechanisms for detecting Gibson situations.

With “config gibson” enabled, tsh will check for Gibson situations based on wins (but not spread) anytime it computes regular pairings. If it detects one (or two), it will stop and ask you to manually pair the Gibson player before continuing. This is because it is not easy to determine according to standard rules who should be the Gibson’s opponent, that is who is the highest-ranked player who is unlikely to be in contention for any sort of place prize.

The Chew pairing system, because it requires information about the tournament’s prize structure, will automatically detect and assign Gibson pairings. Gibson situations are detected based on wins and generalised NSA spread thresholds (a player may hope to win one game by 250 points, two games by an average of 200 points, and more games by an average of 150 points each). You may use “config gibson_groups” to specify for example that a player should be Gibsonized for clinching one of the top two places even if s/he has not clinched first place. If all players are still in contention for some sort of prize, it will pair the Gibson with the lowest ranked player who has played the Gibson least often. If some players are out of contention for any prize, it will pair the Gibson with the highest ranked such player who has played the Gibson least often. If there is more than one Gibson, as many of them are possible (all of them if the total number is even) are paired with each other KOTH minimizing rematches and consecutive rematches.

It is important to note that if you are using Fontes pairings, a Gibson situation may develop in round n, paired based on round n–2, as a result of games played in round n–1. tsh does not currently check for this situation, and in practice the players involved might already even have started playing round n before anyone notices what has happened. If you do find yourself in this situation, try to manually repair the top few boards, if they have not already started their games.

Pairing Systems

tsh currently supports the following pairing systems, in order of increasing sophistication. If you have a need for a different pairing system, please contact John Chew at least two months in advance of your tournament. There is also a partial implementation of the NSC factored pairing system, but it is not yet ready for tournament use.

Random Pairings

Random pairings match players based on a statistical hashing function of their name and player number. They are random in that who plays whom will not appear to follow any pattern, but only pseudorandom in the sense that if you do not change the names and order of your players the pairings will always be generated the same way.

You might want to use random pairings when assigning first-round pairings for a group of players who do not have a reliable past tournament record.

The general command for random pairings in tsh is “randompair repeats based-on-round division”. For example, to ask for random pairings with no repeats allowed, based on standings in round 7 for division D, use the command “rp 0 7 d”. This example is somewhat contrived though, as after the first round it would be foolish to use random pairings rather than some sort of standings-based pairings.

See also the “config initial_exagony” configuration variable for avoiding pairing players from the same team in the first round. If you use this variable and do not assign players to teams, pairings will fail because everyone will appear to belong to the same unnamed team.

As it does with other pairing commands, tsh will try to minimize repeats and avoid successive repeats where possible, though in the first round this is irrelevant.

Manual Pairings

Sometimes, you can’t use a computer to do all your pairings. For theatrical purposes you might have the first round’s pairings be done by a physical draw. You might need to tweak computer pairings because someone has taken ill after you’ve computed your pairings and some people have started to play. You might want to manually pair a few players and allow the rest to be automatically paired. Or something really weird and unexpected might have happened.

tsh provides two commands for manual pairings. If you’re just doing a few, then use “PAIR p1 p2 round division”. For example, “pair 1 2 5 a” pairs players 1 and 2 in round 5 in Division A. To assign a player a bye, pair them against the fictitious player 0.

If you need to do a lot of pairings, use the “PairMany round division” command. For example, “pm 3 b” lets you enter pairings for round 3, division B and prompts you to enter pairs of player numbers, one pair per line. If you enter a division name by itself, you will switch to entering pairings for that division. If you enter a round number preceded by an R and a space, e.g. “r 5” you will switch to entering pairings for that round. If you enter anything else, you will return to the main prompt.

You cannot assign pairings for a round until all previous pairings for both players have been assigned, and tsh will stop you if you try. You can reassign pairings for players who have already recorded scores, but should do so only with extreme caution, and you will likely need to use the “EditScores” or “DELETEscore” command. Use the “ShowPairings” command to check your pairings after any manual changes, to make sure that all players are paired and none are multiply paired (tsh will warn you of either situation).

If you want to pair partially manually and partially automatically, remember that tsh invokes its automatic and default pairing mechanisms when you use the “ShowPairings” command. Specify any manual pairings before using that command. If you forget and do a “ShowPairings” first, then use the “UnPairRound” command to unpair all of the last round’s pairings from a division.

King-of-the-Hill Pairings

In King-of-the-Hill (KOTH) pairings, the top two players are paired with each other, then the next two, and so on.

KOTH pairings are often used in the final round(s) of a tournament to ensure that contenders face each other, often with an extra repeat permitted so that contenders face each other again even when they have already played each other.

The general command for KOTH pairings in tsh is “koth repeats based-on-round division”. For example, to ask for KOTH with one repeat allowed, based on standings in round 11 for division B, use the command “koth 1 11 b”.

If the players who are supposed to play each other have already played each other too often, tsh will look for the nearest available player, breaking ties to avoid consecutive repeats, match starts with replies and minimize repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

Factored Pairings

Factored Pairings (FP) are the same as KOTH except that the optimum rank separation of players is some fixed number (the factor) greater than the value of one used in KOTH.

A version of FP is used in the (US) NSC in preliminary rounds, with factors gradually decreasing from 20 to 2, to artificially control the rate at which the contender pool shrinks. (At the NSC, pairing is done in groups of four to eight players, three or four rounds at a time.)

The general command for FP in tsh is “FactorPair distance repeats based-on-round division”. For example, to ask for FP(2) with no repeats allowed, based on standings in round 14 for division C, use the command “fp 2 0 14 c”. The “Pair1324” command is a synonym for “fp 2”.

If the players who are supposed to play each other have already played each other too often, tsh will look for the nearest available player(s) to the optimum opponent(s), breaking ties to avoid consecutive repeats, match starts with replies and minimize repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

Round Robin Pairings

In Round Robin (RR) pairings, every player plays every other player once.

RR pairings are used when the number of players is no more than one more than the number of rounds scheduled. If the number of players is a little less than that number, than the remaining rounds are often paired KOTH. While RR pairings are fair and give each player the widest possible field of opponents, if the skill levels of the players vary greatly then it may be more fair to use a more flexible system that will allow the top contenders to play each other more than once. It is also difficult but not always impossible to schedule an RR so that contenders face each other in the final round.

The general command for RR pairings in tsh is “rr division”. For example, to ask for a set of RR pairings to be added to division A, use the command “rr a”.

There is also a specialized command for doing partial round robin pairings for use at Cambridge ON. Use the “camp division” command to add fixed pairings for a seven-round tournament with any number of players.

Swiss Pairings

In Swiss pairings, players are divided into “win groups” according to how many wins they have scored. The top half of each win group plays the bottom half, in order.

Several different systems of Swiss pairings are popular in Chess, where Swiss pairings originated. Swiss pairings work well for divisions where the number of players is large and the number of rounds is small.

Regular Swiss pairings cause delays in tournaments because the pairings for the next round cannot be computed until all the results are in for the previous round. Fontes (or Portland) Swiss pairings trade off some pairings accuracy for speed by computing pairings based on the second previous round’s results. As a compromise, some directors use regular Swiss pairings immediately after session breaks and Fontes Swiss pairings at other times.

The general command for Swiss pairings in tsh is “ns repeats based-on-round division”. For example, to ask for Swiss pairings with two repeats allowed, based on standings in round 17 for division C, use the command “koth 2 17 c”.

If you ask for Swiss pairings based on round 0, tsh will rank players by pretournament rankings, breaking ties randomly. This effectively pairs the top half of the field against the bottom, which may be something you want to do even if you aren’t pairing the rest of the tournament Swiss.

There is a special command for starting a Fontes Swiss tournament. Because you will need at least two rounds of scores before you can pair Fontes Swiss, the “InitFontes number-of-rounds division” command divides players into groups of four and schedules them to play in round robins. This takes three rounds (3 is the recommended value for number-of-rounds) and provides a fair start to the Swiss system, as well as giving you three hours to get used to doing data entry before you need to worry about pairings. If the number of players is not divisible by four, there may be a group of six players who play a partial round robin. The players in each group are chosen randomly, one from each quartile (or sextile).

Early in the tournament, you should use 0 repeats. At some point in a long tournament, you should start increasing the number of repeats or else the top players will begin much lower-ranked players because they have already all played each other. You can try simulating the outcome of the tournament to get a feel for when this is likely to happen, use your intuition based on past similar tournaments, or keep an eye on who the top-ranked player is playing each round and decide for example once they are paired with someone out of the top ten. Most Swiss tournaments end with one or two rounds of KOTH to ensure that contenders play each other often enough.

tsh chooses an opponent within the win group who (in decreasing order of importance): minimizes repeats, is not the previous round’s opponent, is due to play first if the current player is due to play second (and vice versa, but in either case only if “config track_firsts” is active), and is as close as possible to half a win group away in ranking. For the sake of computational efficiency, tsh looks for opponents first for those players who have the fewest candidate opponents (with ties broken by current ranking). If a win group is odd, the top player in the next group is promoted to join it. If a win group cannot be paired, two more players are promoted. If the entire division cannot be paired in one big group, an error message is displayed, and you should increase the number of allowed repeats. If the number of players is odd, tsh will assign a bye to the lowest-ranked player who has had the fewest byes.

Chew Pairings

Chew pairings draw on Swiss pairings and the two-victor “Basic Approach” pairing system developed for the 2003 CNSC and refined at the 2004 NSC, 2005 CNSC and 2005 NSC. Tournament simulations determine which players are still in contention; the minimum number of repeats required to pair those players is computed; the contenders are split into leaders and nonleaders so as to minimize the number of leaders while not increasing the required number of repeats. Beginning at the top, each leader is paired with the lowest-ranked other leader who can catch up to him/her; the nonleaders are paired Swiss.

Chew (or similar) pairings should be used in tournaments where after a number of preliminary rounds two or more top players are selected to compete in final rounds. They are also sufficiently flexible that they may be used in any sort of tournament, and are therefore used as tsh’s default pairing algorithm. As with Swiss pairings, they may be computed based on the immediately preceding round’s standings or those of the second preceding round, depending on event scheduling.

The general command for Chew pairings in tsh is “cp based-on-round division”. For example, to ask for Chew pairings based on round 5 in division D, use the command “cp 5 d”. As explained in the discussion on default pairings, if you do not specify any pairing system, manual or automatic, tsh will use Chew pairings. You must specify “config max_rounds” and should specify “config prize_bands” and “config gibson_groups” when using Chew pairings.

Here is the Chew pairing algorithm in greater detail.

 

What’s New in tsh

A chronological list of changes to tsh.

Updated Sat Apr 8 19:51:17 EDT 2006 for tsh 3.050.

Changes are made to tsh for just about every tournament at which it is used. This means two things: firstly, you should be sure to update to the most recent version before your tournament; and secondly, if there’s a feature that you’d like added please be sure to mention it, preferably with about a month’s lead time.

VersionEventChanges
3.050Dallas Open 2006
  • If you are using xterm terminal emulation and have specified the “event_name” configuration option, tsh will identify itself in your window title bar.
  • ShowscoreCard” formats correctly even when first and seconds are not assigned.
  • Under some circumstances, the downloaded executable files would not be executable for OS/X users. I think I've fixed the problem, and documented how to fix it locally if it recurs.
  • At Kath Mullholand's request, the “high-win” external command (and the other three similar ones) now display a header that identifies the division.
  • Quality of pairings is slightly improved by disabling a speed optimization that tries to pair first those players with a smaller number of candidate opponents, when the number of players to be paired in a group is no more than twelve.
  • At Mary Rhoades' request, the “ShowPairings” command now also generates alphabetical pairings listings in addition to the old rank-based listings.
  • The “AddScore” no longer accepts scores outside the range [-150,1500].
  • Added UPSETs command to list top ratings upset games.
  • The munge-scores.pl utility, used by several external and utility commands, now reports player numbers, so those external commands will report them too.
3.040Oshawa 2006
  • Colour prompts for Windows users disabled by default, still optionally selectable. Windows colour is apparently broken in the most recent ActivePerl distribution.
  • If an html_directory needs to be created, lib/tsh.css is copied into it.
  • Fixed an obscure bug in “ChewPair” that made it occasionally crash.
  • Utility command “util/truncate_t” is tolerant of blank lines.
  • Added top-level script “get-tsh.pl”, built using “update” external command, to act as a standalone download tool for tsh. That is, you can if you want to download just this one script, run it and it will fetch everything else for you. Useful if you have a mostly complete installation but have somehow managed to wreck either your “tsh.pl” or part of the software update mechanism.
  • The “update” external command was saying that some files had been updated even when no files had been updated. That bug is fixed.
3.030WSC 2005
  • Support for scoreless byes.
  • Fixed a bug that caused starts/replies to be instable.
  • Fixed “ChewPair” command and pairing system: Gibson spread threshold now based on some historical data, leaders paired against lower-ranked contenders.
  • Addscore” won't let you switch to a division whose results have all been entered.
  • AUPAIR command supports byes.
  • Added “player_number_format” configuration option.
  • Added “show_teams” configuration option.
  • RATings” command shows next opponent if paired. (Suggested by David Acton.)
  • 0-point bye counts as a loss, not a tie.
  • Fixed a bug where pairings display would stop if a table was unoccupied.
  • Fixed a bug in bin/munge-scores that led to games with byes appearing in high/low win/loss lists.
  • MISSing” command lists players in current standing order.
  • Tweaked code for reserved table assignments, think there might still be a problem.
  • For a few versions, you had to specify the max_rounds configuration option to make pairings commands work. This should no longer be necessary, though it is still recommended.
3.020Kingston 2005
("Now... with tint control!")
  • All remaining commands converted to using newer parsing code.
  • LOOK” command checks for dictionary at runtime.
  • UnPairRound” command does not affect inactive players, minor bugs fixed.
  • EditScores” command deletes future byes when a player is (re)activated.
  • RANDomscores” command sets spread to 50 points for scheduled byes.
  • Fixed a bug where if you asked for pairings too far in advance, inactive player records would still have byes added.
  • Colour prompts for Windows users too.
  • MISSing” command ignores inactive players, displays board numbers when known.
  • ShowscoreCard” shows board numbers.
  • UPDATE” command will delete read-only files (like src/TSH/blib/lib/TSH/Pair.pm) to make way for their replacements.
  • Addscore” prevents entry of Rd. N+1 results when Rd. N is incomplete even when switching divisions.
  • Several commands explicitly report when pairings have failed.
  • Added “RandomPair” command.
  • Added “etc team” extension field.
  • Added “config initial_exagony” configuration parameter.
3.010Kingston 2005
  • Added “ON” and “OFF” subcommands to“EditScore” to permit enabling and disabling a player.
  • ShowscoreCard” detects truncated .t files.
  • ShowscoreCard” reports nonstandard spreads for inactive players.
  • Removed a bug that caused multiple byes to be appended each round to inactive players.
  • Removed two bugs introduced in 3.000 that caused odd divisions to severely misbehave.
  • Removed bug introduced in 3.000 that caused round robins to fail sometimes.
  • UnPairRound command will delete scored byes if they are the only scores in round.
  • RANDomscores command deals more appropriately with partially scored rounds, completing them rather than adding one score to each player regardless of number of scores recorded.
  • Deprecated PartialSWiss command finally deleted.
  • First sample folder cleaned up.
  • RoundRobin command works with inactive players.
  • In many places, the division name is now not displayed if the tournament has only one division.
  • PAIRPairMany> commands allows either player number to be zero for a bye.
  • PAIR, PairMany commands unpairs opponents of repaired players, assigning 50-point byes if necessary.
  • KOTH, Pair1324 commands works with inactive players, uses consecutive repeat avoidance, matching starts and replies, minimizing repeats as secondary criteria.
  • FactorPair” command released.
3.000MWMST 2005
  • Finished implementing “ChewPair” command and pairing system, which is now the default if pairings are asked for and no other system was specified.
  • Added HUH” command for explaining error messages.
  • Rewrote HELP” command to give detailed help about individual commands.
  • Added AUPAIR command for exporting to that ratings file format.
  • Many commands rewritten to conform to new internal code standards to support faster software updates and smaller runtime memory usage.
  • Fixed a bug in “ShowPairings” which had caused it to omit boards where more than two players had erroneously been scheduled to play.
  • Added DEBUG command for selectively toggling debugging on and off.
  • SWiss” command is now just an alias for “NewSwiss”.
  • Added “config external_path” to allow user plug-in directories.
2.980NSC 2005
  • ResultsByRound” command creates printable HTML files.
  • Added very experimental versions of “FactorPair1” and “FactorPair” commands.
  • Added “config prize_bands” to expand support for Chew pairings.
  • Added “config save_interval” to auto-save when entering a large number of scores.
  • Added “config rating_system” to allow computation of ABSP tournament ratings in “rat” command.
  • Added “maketm” external command to generate TourneyMan data files.
  • Added “high-loss-round” external command to list high losses in each round.
  • Added “high-win-round” external command to list high wins in each round.
  • Added “util/parsetm” utility to import TourneyMan data files.
  • roto” allows any number of players per team.
  • showWallChart” syntax does not require “-f” before round number anymore.
  • External command “show12” shows counts of firsts and seconds for each player.
  • The board at which each game was played is recorded (in “etc board”) and will not change once assigned.
2.975ABSP compatibility
  • Added “ABSPgrid” command.
  • Added “config colour”.
  • Made external commands work with Windows XP.
  • Reorganized search algorithm for configuration files. It’s now (1) files or directories specified on the command line, (2) the most recently changed among */config.tsh and */tsh.config, or (3) tsh.config. The intent is that users should have one tsh directory with a subdirectory for each event.
  • Added “update” external command, which downloads updates to the distribution.
2.960Albany NY
  • Added “tuffluck” external command.
  • Partly functional version of “ChewPair” command added.
  • ScoreCard command generates HTML version that can be printed as replacement for lost scorecard.
  • WallChart command generates HTML version.
  • Round-by-round HTML files are automatically indexed.
  • New RATING subcommand in EditScores.
  • Contextual help in EditScores.
  • EditScores can be used before any results are entered.
  • Initial .t files may omit trailing semicolon.
2.950Toronto LCT
  • Addscore prevents entry of Rd. N+1 results when Rd. N is incomplete.
  • New external command “show12” displays table of firsts/seconds.
  • First/second forecasts/assignments are now more accurate.
2.940Stamford CT
  • Optional specification of configuration file on command line.
  • NewSwiss tries to minimize repeat pairings.
2.930CNSC 2005
  • Addscore reports how many scores remain unentered.
  • Two-part tournaments are correctly split-rated.
2.920Thunder Bay ON 2005
  • Added some more three-word names to tourney.pl.
2.910BAT 2005
  • Added config gibson.
  • Added config max_rounds.
  • The timestamp of the most recent score entered for each player is now recorded.
  • Added ROTO command.
  • Code for reserved table assignments is working again.
  • Forecasts of firsts and seconds are purged before new forecasts are generated, which addresses a potential problem with corrupt stale data when players have systematically misreported firsts and seconds.
  • Added config no_text_files.
  • Added config html_directory.
  • Autopair supports PAIR1324.
  • Fixed a bug that prevented calculation of the ratings of unrated players.
2.900BAT 2005
2.850NSSC 2005
  • Fixed a bug introduced to RoundStanding in 2.800 (?).
2.840NSSC 2005
  • Fixed a bug introduced in 2.800 (?) where missing pairs were displayed twice.
2.830NSSC 2005
  • Generated HTML is somewhat more legible and conformant.
2.820NSSC 2005
  • Corrected determination of firsts and seconds.
2.810NSSC 2005
  • Added external command (plug-in) interface
  • Partial support for active/inactive players
  • 'off' extension field in '.t' files
  • MISSING and ShowPairings show "draws" if players must draw
  • config name_format = "%-22s"
  • config max_name_length = 22
  • config assign_firsts = 0
  • showWallChart and showScoreCard adjust column with to widest team name.
2.800NSSC 2005
  • EditScore now displays the current scorecard before each prompt, rather than after changes.
  • You can now enter the word first or second at the EditScore prompt to specify that the player went first or second.
  • MISSING and ShowPairings display firsts and seconds if known.
  • config track_firsts = 1 enables tracking of who went first or second in each game. tsh will use NSA rules for determining firsts and seconds, and complain if scores are not entered in order of play if known.
  • Auto-pairing used to be available only when a division was completely unpaired. Now, you can still auto-pair even after entering a few manual pairings.
  • You can now write config variable = value instead of perl $config'variable = value in tsh.config.
  • Byes are automatically chosen and assigned by the NS, KOTHand Pair1324commands.
  • The BYE command is now deprecated. It is no longer documented, and will be deactivated soon. Use the PAIR and Addscore commands instead.
  • The ShowPairings command used to always list everyone and their opponent (if any). Now, if no players are paired, it says so rather than listing everyone as unpaired.
  • The PAIR command used to always echo back the names and standings of the players you just (manually) paired. Now it only does so if you changed an existing pairing.
  • The SWiss, PartialSWiss, PRESWiss and PrePreSWiss commands are now deprecated. They are no longer documented, and will be deactivated completely soon. Use NewSwiss instead.
  • You can now enter 'es' when in Addscore mode, to go into EditScore on the most recently entered (and presumably mistaken) score.
  • EditScore command sometimes didn’t correctly record changes when editing multiple divisions, does so now.
  • UnPairRound command used to sometimes give incorrect error messages, but no longer does so.
  • Pair1324 documentation used to say that below 4th place, pairings were KOTH. This is untrue (they continue 5-7, 6-8, etc.) and the documentation has been corrected.
  • All command parsers rewritten to give consistent response and more specific descriptions of syntax errors.
  • RoundStandings used to misreport results in the current round, if not all scores had been entered, now reports correctly.
  • Division name may now be specified in command lines, even when event only has one division.
  • Distribution now in ZIP format.
  • Documentation rewritten.
  • Randomization of player orderings is now much less random, so first-round table assignments stay stable unless roster is changed.
  • Some spurious warning messages deleted.
  • Support added for new generalized .t files.
  • ShowPairings now generates HTML.
  • Trailing commas in player names are suppressed.
2.740Newsday SSC
  • PairMany debugged.
2.730Newsday SSC
  • ShowPairings catches and shows more pairing errors.
2.720Newsday SSC
  • PairMany added.
2.710Newsday SSC
  • Player names may include nonterminal numerals.
2.700Newsday SSC
  • HTML output from standings command.
2.600Oshawa 2005
  • RoundRobin command added.
  • RATings command added.
2.500MWMST 2004
  • Trying to autopair a round twice doesn’t crash tsh.pl.
2.400Albany 2004
  • Fixed wc -f #.
  • Autopair works at start of tournament.
  • MISSING lists divisions in alphabetical order.
  • 'm' synonym for 'missing' in score entry mode.
2.300BAT 2004
  • Autopair added.
  • EditScore emits updated scorecard.
2.210Montreal QC 2004-03 LCT
  • Suppressed a spurious error message.
2.200Cambridge ON 2004
  • "Cambridge pairings" added.
2.100CNSC 2003
  • Addscore gives updated cumes as a check.
2.000MWMST 2003
  • MISSING lists missing data in score entry mode.
  • Teed log files have '.doc' extension, no embedded spaces.
1.900CWSCQT 2003
  • Added ShowPairings -p as kludge to work with make-rr.pl.
1.800Albany 2003
  • ScoreCard shows opp ratings.
  • UnPairRound reports on problem players.
  • Table numbers can be arbitrary strings .
  • Entering a division name changes divisions in score entry mode.
  • ShowWallChart -f r lists beginning with round r only.
1.700Boston 2003
  • EditScore added.
  • NewSwiss code added, first manually paired player can be 0 for an unscored bye pairing.
1.600Boston 2001
  • InitFontes works for any number of players, not just 4n and 4n+2.
1.500Toronto 2001
  • Various changes.
1.400Boston 2001
  • Various changes.
1.300Danbury 2001
  • Various changes.
1.2002000 CNSC
  • Various changes.
1.1031999 MWMST
  • First production use
1.000None
  • First release