View source for Intersite Games/Tournaments Layout

[[Category:Scheduling]]
== Introduction ==
'''Intersite Games''', '''Intersite Game Days''' or '''Tournaments''' are when multiple USYVL sites come together to play a tournament.

The tournament layout is one or more pools per division.  If there is only a single team in a pool, the team is moved into one of the pools in the next division up.  In the event that the highest level division has only a single team, then they are moved into a pool in the next division down.  This does not happen as often as it does in the [[Intrasite Games/Game Days Layout]] scenario, but does happen occasionally.

These '''Intersite Game Days'' 

== Concepts ==
Because of the irregularity of teams distribution among the divisions, there are often no "perfect" solutions.

Ideally every match would consist of teams from different sites.  But because the number of teams in each division of each site is so irregular, there is often no way to accomplish that.  The two situations that come up are:
* '''Collisions''' - There are not enough teams from other sites to always play another site, so a team ends up playing a team from there own '''Site''' or '''Program'''
* '''Duplications''' - There are not enough teams in the pool to play a unique match for each of the 4 games.  So a given team may play the same team more than once in the pool.
** Worst case is a pool of only two teams, so all 4 games will be duplicated.
** Note: You can end up with Collisions AND Duplications.
*** Worst case: only two teams in the pool, and both from the same site.

NOTE: Site Clinicians have widely ranging feelings about whether '''Collisions''' or '''Duplications''' are better solutions.
This falls mainly (but not always) along the lines of site/program size.  Larger sites are typically more forgiving of '''Collisions''' because not all of their teams in a division will have played all the other teams.
Smaller sites are typically more forgiving of '''duplications''' because their division teams have likely played each other several time on Intrasite Game Days.

== Pool Creation ==
When deciding how many pools to create for a division, there are a couple situations that arise.
* In general:
**An even number of teams in a pool is preferred to maximize the time that each team plays.
*** So if you have 10 teams, you may want to make a pool of 4 teams and a pool of 6 teams.
** Having an odd number of teams necessitates that one or more teams have a BYE during each round of pool play.
* Occasionally, under specific circumstances, having an odd number of teams is desired.  
** This typically happens when:
***  USYVL has some sort of a special event.  In this case, it is sometimes good to have teams with BYEs to be able to do some activity or get autographs from a visitor as part of the event.
*** The field cannot support the maximum number of courts required.
** So in the 10 teams in a division example above, we would instead create two 5 team pools with two courts each (4 courts total instead of the 5 courts if the pools were optimized).
** In our 10 team example: If the field only supported 3 courts (for this division), the solution might be to put all 10 teams in one pool and have 4 teams with BYEs each round.

Regardless of how good the Pool Creation Algoritm is, there is almost always a situation/solution that cannot be anticipated.  In this case, there needs to be a way for USYVL personnel to rework the pools (shifting teams, courts etc...).

The pool creation should be predictable and reproducable.  This is important because a new pass at generating a layout shouldn't change the layout if the inputs have not changed.
Randomization was used at one point and was found to be sorely lacking.


== Assigning Teams into Pools ==
A '''tournament number''' is established based on number of times the hosting site has hosted (usually 1-4)

Teams are dropped into a division queue - pretty sure that there is a separate queue for each site in a division

Rolling Queue - Pretty sure site order is derived from order they are listed in title (ie: host first and then visitors based on order encountered from input).
The teams list for each site (in each division) is "rolled" by '''tournament number''' * ('''site number index''' + 1).  
This rolling of team lists should provide different team matches even for completely duplicated tournaments (same host and same visitors).

Do actual assignment (usyvlTourn::assignTeamsToPoolsFromDivisionQueues($division)).  Have to look at code a bit longer to figure out algorithm for actually distributing teams from division->sites->teams into the pool.  Using various popping, pushing, rolling, so its a bit confusing.  This was designed to distribute teams as evenly as possible from various sites into a given pool.
With the advent of the Pool Layout DB, we actually want teams ordered by the site frequency, so it will match one of our ordered hashes in the pool layout db.
This assignment should be a simpler numerical task now.  Will try to think about the best approach for that.

If the Pool Layout DB is used (which it is as of 2018), then some of the above work is undone by usyvlPool::unShufflePool() which I am pretty sure just sorts teams by the site frequency in the pool, so that teams from the site with the highest number of teams (in the pool) are listed before teams from a site with lower count in the pool.

== Pool Solutions ==
Initial passes at assigning teams to pools were problematic.  Because the number of teams is so irregular, there are OFTEN cases where there is no solution which does not involve '''Duplications''' or '''Collisions''' (as mentioned above).  Played with combinatorics.  Worked in some cases, but as the number of teams in a pool increased, the solution time increased exponentially.

The [[Static-Hashed-Tournament_Scheduling_Algorithm]] was devised (in 2012?) with the idea that if somebody designed a pool layout that worked for a given situation then the same pool layout could be reused the next time that same situation came up.  The key was to figure out a way to succinctly describe a given situation.  We did this exclusively for 4 game pools, but, some modifications would have it work for other numbers of games (and I have toyed with making that change in case USYVL decides to change the number of games per pool).  By looking at the number of teams from each site in a sorted order, the number of variations becomes much more reasonable.  We found that the number of new solutions that had to be designed each season dropped off very quickly.

This setup required the development of an interactive editor that can save a given solution, but that was needed for other reasons as well.

2018-10-04 Note: considering modifying the notation to include number of games AND number of courts, that should cover all the situations that might come up with USYVL.  The number of teams can be derived from the remaining fields.

For example:
 5-2-4-3
 5 represents the number of games in the solution
 2 represents the number of courts in the solution
 4-3 represents the (sorted) number of teams from each of two sites (4 teams from site A, 3 teams from site B)

With only two courts in the pool, the solution would have to have 3 teams with a BYE each round.

In contrast, the current notation would just be the number of teams:
 4-3

The 4 games is assumed and the numnber of courts (3) would be derived from the overall number of teams (7), leaving one team with a BYE each game.

This could also be handled in the solution db by just having a column for those extra values.  So still toying with how something like that should be implemented.  Having the info encoded into a single string makes the lookup incredibly simple and would lend itself to other storage mechanisms.

== Code Implementation ==
In file inc/usyvlTourn.php:
* usyvlTourn::initTournamentPools() - Pool Creation
** decisions: optimize team counts in each pool (even or odd)
** inter division merges (automated), 
* usyvlTourn::rAssign() - Assign Teams to Pool - Called by assignTeams which is now only a wrapper
** loadDivisionQueues()
** rollDivisionQueues()
** assignTeamsToPoolsFromDivisionQueues()