Restructure draw code to keep track of details like brackets, one-up-one-downs, etc.

[czlee]

Follows from #60.

The draw algorithms currently use a number of functions that pass around lists of tuples [(team1, team2), (team3, team4), ...]. While fit for the purpose of creating a draw, it's not very good at tracking flags and brackets and similar information. It would be nicer to have a draw generation architecture that can remember when it performs actions like swapping or balancing affs, so that that information can be displayed to a curious (or untrusting) user, and that is generally more extensible so it's easy to generate break rounds and so on. For example, draw algorithm classes might:

• Keep track of (relatively) custom "flags", like one-up-one-down and for what reason
• Keep track of brackets (though not all draws have brackets)
• Specify whether or not they require previous round(s)
• Specify whether or not the previous round must be an elimination round
• Have mechanisms for (relatively) custom options, like turning on or off intermediate bubbles

By "(relatively) custom", I meant that options and flags shouldn't be constrained by the architecture - they should be stored in an .options or .flags attribute or something.

This is probably a major job, and is probably not too high priority, since the current code does get the draw done fine (when it's not polluted by unconfirmed ballots). But it'd also be really nice to have in place for the unit tests in #71, and certainly it would give a lot more peace of mind at Australs.

[czlee]

Thinking out loud:

General principles:

• Place only as many restrictions as are strictly necessary for it to be technically feasible.
• No dependence on tournament configurations or any of the models. Keep this class strictly an algorithm cruncher. Use duck typing to draw information about teams.

Types of draws

Random

• Can be generated at any time.
• Parameters
  • A list of all teams.
• Options
  • Avoid history
  • Avoid same institution
• Procedure
  1. Generate a random draw.
  2. Avoid conflicts if necessary.
  3. Decide which teams aff and neg.

Manual

• Can be generated at any time.
• Probably easiest to implement via text file import, probably not part of these classes.

Power-paired

• Must have at least one round before it.
• Parameters
  • The standings on which to generate the pairings.
  • Note: Not "the previous round". It's easier for the caller to pass in the standings, to delineate roles clearly and maximize flexibility. The form of the standings will need to be specified, but presumably it's a fully-ranked list of teams each with a points attribute. We use points to generate brackets. We don't care about how the subranks were derived.
• Options
  • Odd bracket resolution (pull-up from top, pull-up from bottom, intermediate bubble, random)
  • Matching type (fold, slide, random)
  • Conflict avoidance method (one-up-one-down)
  • Avoid history
  • Avoid same institution
• Procedure
  1. Divide into brackets (includes odd bracket resolution)
  2. Do the matches for each bracket. (The function should just take a single bracket.)
  3. Avoid conflicts if necessary.
  4. Decide which teams aff and neg.

Break round

• Must have at least one round before it.
• Parameters
  • If the first break round: the standings on which to generate the pairings.
  • If the first break round: the size of the break.
  • If a second or later break round: the previous round (Don't just assume it's the last round, major international tournaments run separate breaks for ESL/EFL teams.)
• Procedure
  1. Extract the top n teams
  2. Determine how many compete in this round (if it's, e.g., a pre-octos)
  3. Pair the teams.
• Affs and negs need to be manually driven?

Interface in

All teams and standings lists are any iterable of objects with the attributes listed below. For draw types where teams are ordered, lists are assumed to be ordered from first to last. No other assumptions are made about the objects. It is illegal for a higher-ranked team to have fewer points than a lower-ranked team.

The attributes that teams must implement are:

• points, the number of wins a team is on.
• If side balancing is enabled, aff_count. If side balancing is turned off, the order in which teams of a single pairing are presented is random.
• If avoiding institution conflicts is enabled, same_institution, a function taking one argument that returns True if and only if the team and the team provided are from the same institution, and seen_institution, a function taking no arguments returning an integer count of how many times (prior to this round) they have seen their own institution.
• If avoiding history conflicts is enabled, seen, a function taking one argument, another team, and returning an integer count of how many times (prior to this round) they have seen their own team.

Options for power-pairing rounds (other than history/institution limits) can be a string or a function. If it's a string, it refers to one of the built-in methods. If it's a function, the algorithm uses that function (and it must conform to the same specifications). Can be specified as keyword arguments to the constructor, but don't have to be. Defaults are those used at Australs.

The history and institution limits are always integers.

Interface out

The draw will be communicated as a list of Debate objects. Debate objects are not the same as the Debate Django model (the name might cause some confusion). Each Debate object has the following attributes:

• teams, the list of teams in the debate
• aff_team, which will be the first object in the list of teams
• neg_team, which will be the second object in the list of teams
• bracket, a number, not necessarily an integer (could have intermediate bubbles). Will be returned as an integer if it can be, but may be a float.
  • For break rounds, this is always 1.
• room_rank, an integer. A strict order of rooms.
  • For break rounds, this should be the rank of the higher team, or in a second or later break round, the room rank of the higher team in the previous round.
• flags, a list of constants.
  • Swapped to avoid a history conflict
  • Swapped to avoid an institution conflict
  • A team was pulled up
  • Unavoidable history conflict
  • Unavoidable institution conflict

There is no guarantee that all teams are included (in fact, for break rounds, they certainly won't).

[czlee]

This is basically done, but I didn't implement break rounds because they're hard. Hopefully what's there now is a good framework for doing so though.