Before putting it on CPAN, I'd like some advice on a module that
pairs league members for roundrobin tournaments. I'm wondering
about the name and also about the API, as people say, eg Adam
Kennedy and Sam Tregar, that getting the API right at the start
is more important than the actual code.
The module uses a little of the math of combinatory designs. This
area of math is also useful in other sorts of tournament
scheduling, eg whist tournaments, so the name,
Games::Schedule::RoundRobin might be better, because these other
types of tournaments then could become sub-species of
Games::Schedule too.
On the other hand, the math of whist tournaments is considerably
less straight forward than that of roundrobin tournaments and
these other modules will probably never be produced. If I do
decide to go with Games::RoundRobin, I'm also wondering what else
could be a subcategory of Games::RoundRobin than
schedule-related functions, so perhaps just Games::RoundRobin is
adequate for my module.
Scoring, however, is perhaps another area that could have its own module.
There is an extensive C++ library, libtour that handles scoring
and more of the other features of tournaments. In the perl
community, there was discussion of roundrobin tournaments
in January 2005 on Mark Jason Dominus's Quiz of the Week list.
Here is the API. I'm wondering if I'm trying to support too many
representations of a league member, and if there are other ways
of reporting the pairings.
NAME
Games::RoundRobin::Schedule - RoundRobin Tournament Pairings
SYNOPSIS
$schedule = Games::RoundRobin::Schedule->new;
$pairings = $schedule->indexesInRound($m);
$round = $schedule->meeting($member1, $member2);
...
DESCRIPTION
Every member of a league of 2n players can be paired with every other
member in 2n-1 rounds.
If the league members are (Inf, 1 .. 2n-1), then in round i, i can be
paired with Inf, and a can meet b, where a+b = 2i (mod 2n-1).
METHODS
new
Games::RoundRobin::Schedule->new( v => 5, league => [’Ha’, ’Be’, ’He’])
Games::RoundRobin::Schedule->new( league => {A => $a, B => $b, C => $c})
where v (optional) is the number of league members, and league
(optional) is a list (or a hash) reference to the individual unique
league members. One of v, or league (which takes precedence) is neces-
sary, and if league is not given, the members are identified by the
numbers 0 .. n-1.
If the league is a list (or hash) of n objects, they should be
instances of a class that overloads both string quoting with a ’name’
method and arithmetical operations with an ’index’ method. The index
method, called on the n objects in order, should return the n numbers,
0 .. n-1, and in that order if they are presented as an array. If they
are presented as a hash, the hash is stored internally as an array and
the keys are discarded.
If the league is a list of strings or numbers, indexes are constructed
for the values on the basis of their positions in the list, and if a
hash of strings or numbers, on the basis of the lexicographic order of
their keys. Each string is expected to be unique.
If n is odd, a ’Bye’ member (a Games::League::Member object, if no
other) is added at the end and n increased by 1.
index
$schedule->index($member)
Returns $member’s index, the number which is used to pair it with other
members. The index is the position, 0..n-1, of the $member in the
league argument to the constructor (if an array) or the constructed
array (if a hash.)
If $member is not a member of the array, undef is returned.
member
$schedule->member($index)
$schedule->member($name)
Returns the member represented by $index, a number which ranges from
0..n-1, or $name, a string.
partners
$schedule->partners($index)
$schedule->partners($name)
Returns an array reference of all the partners of the $indexed or
$named member, in index order.
realPartners
$schedule->realPartners($index)
Returns an array reference of all the partners of the $indexed member,
excluding the ’Bye’ member, if present.
size
$schedule->size
Returns the number of members in the round robin. Sometimes this may
not be the same as the number of league members specified, because the
array of league members takes precedence if supplied, and a bye is
added if the number is odd.
rounds
$schedule->rounds
Returns the number of rounds in the round robin. This equals the number
of league members, minus 1.
indexesInRound
$schedule->indexesInRound($m)
Returns an array reference of the pairings in round $m. This method is
useful if you are using numbers to represent your league members. It is
not so useful if you are using strings or objects and you don’t know
their index numbers. Positions in the array represent members. The val-
ues represent their partners. Each member is thus represented twice.
namesInRound
$schedule->namesInRound($m)
Returns an hash reference of the pairings in round $m. This method is
useful if you are using strings or objects. Keys in the hash represent
league members. If the league members are objects, their names are used
as keys. The values are their partners. Each player is thus represented
twice.
meetings
$schedule->meetings($member1,[$member2,$member3,...])
Returns, as an array reference, the rounds (TODO and the venue) at
which $member1 meets $member2, $member3, ...
--
Dr Bean, Taiwan
