
SWISS PERFECT PROJECT
---------------------

Ratings (Elo) Module,  March 1996
=======================================

CONTENTS:

1. Introduction
2. Licence
3. File List
4. Usage
5. Test Data Format


1. INTRODUCTION
---------------

This is the first release of the Swiss Perfect 3 Ratings
Module.  The release consists of the source code and
DOS executable which allows testing of the module.

The source code has been compiled successfully on DOS (Turbo C++),
Linux (gcc) and SCO Unix (gcc).

2. LICENCE
----------

This software is distributed under the Swiss Perfect Public
Licence (GNU-like public licence).
Please read copying.txt for details.

2. FILE LIST
------------

Swiss Perfect files:
   sp3rtg.cpp    - ratings module
   trn_data.cpp  - test data reader
   sp3util.cpp   - C utilities
   sp3rtg.h      - header file for sp3rtg.c
   l_types.h     - Swiss Perfect types
   sp3sctyp.h    - Swiss Perfect score/result types.

Test harness:
   sprtg.cpp     - test program code

Executable
   sprtg.exe     - DOS executable of the test program

Test data
   test.rtg      - test data file

   makefile      - makefile for gcc (Linux)



3. USAGE
--------

Usage: sprtg -f filename

filename - name of a file with test data

Try:
    sprtg -f test.rtg

to use the test file included in this bundle.

Note: test.rtg contains a few tests which will be executed
      without a pause so to see the results of the test
      type: sprtg -f test.rtg | more 
      or    sprtg -f test.rtg > test.log
      and then examine test.log


4. TEST DATA FORMAT
-------------------

A data file may contain a number of tests (sections).

A test begins with a line containing the keyword Test in square
brackets ie. [Test].

Each line in a section is a comment line, a data line or
a configuration line.  Empty lines are ignored.

Comment Lines
-------------
Comment lines begin with a '*' or a '#" and are ignored.

Configuration Lines
-------------------
Configuration lines begin wit a '!' and contain one or more
entries in the following form:  ParamName=Value.
Note: spaces are allowed on neither side of "=".

Currently supported configuration parameters:

TrnType    - possible values: RoundRobin or Swiss.  Defines
             tournament type.

MultiGames - specifies how many games players play against each
             other.  Default is 1.

LowThresh  - minimum rating in the system
             (currently 2000 in the Elo system)

MaxDiffUp  - if an opponent's rating is greater than the player's
             own rating by MaxDiffUp value or more it is adjusted to
             be greater by MaxDiffUp.

MaxDiffDn  - if an opponent's rating is less than the player's
             own rating by MaxDiffDn value or more it is adjusted to
             be less by MaxDiffDn.

Configuration parameters are valid from the place they are defined
until they are overridden.  For example parameters defined at the
top of the file are valid for all the tests in the file unless
overridden before the end of file.


Data Lines
----------
A data line begins with a player number followed by the player's
rating and results.
Results can be specified in two different forms either as a 
total score or results of single games.

The first format allows quick testing or using this module in
simple ratings calculators while the second one will be used by
applications like Swiss Perfect and more sophisticated rating
calculators.


Format 1
--------
Example:
   1  R=2600   Rav=2350     Res=4.5/5

where:
  1     - start number
  2600  - player's own rating
  2350  - average opponents' rating
  4.5/5 - total score (4.5 points out of 5 games)

Note: for round-robin tournaments do not give Rav.  The module
      will calculate it from other players' ratings.


Format 2
--------
Example:
   10 R=2300  0:1  1:2  0:3  0:4  1:5  0:6  0:7  0.5:8  0.5:9

where:
  10   - start number
  2300 - player's own rating

The remainder of the line contains results of single games.
For example 0.5:8 means a draw with number 8.

NOTE:  Only one format can be used in a given test.
       Different tests in one data file can use different formats.


------
Author: Robert Rozycki
email : rozycki@perth.dialix.oz.au
