A tool to generate a CSV export of the best tournament schedule for the specified number of teams and fields, under the constraint that every team must play the same amount of games on some fields (all fields by default).
Can be used either as a command-line tool or as a regular Python module.
# Installation
## Through PyPI
```bash
$ pip install tournament-scheduler
```
## Manually
```bash
$ git clone https://github.com/fdebellabre/tournament-scheduler && cd tournament-scheduler
$ pip install .
```
# Usage
## From the command line
Either specify the team names
```bash
$ scheduler --nfield 6 Paris Bordeaux Lille Lyon Marseille Nantes Toulouse
```
Or specify the number of teams
```bash
$ scheduler --nteams 7 --nfield 6
```
## From within Python
```python
import scheduler
import numpy as np
import pandas as pd
nteams = 10
nfields = 3
bestfields = 1
teams = ['Team ' + str(z+1) for z in range(nteams)]
games = scheduler.get_best_schedule(teams,nfields,bestfields)
# Field distribution quality
scheduler.get_aggregate_data(games)
# Schedule quality
np.array(scheduler.get_gap_info(games)) # gaps between games (rows are teams)
# Save the schedule to csv
schedule = scheduler.pivot_schedule(games)
schedule.to_csv('schedule.csv')
```
# Procedure
The goal of this program is to optimize a schedule for a group tournament with those characteristics:
- any two teams must meet once
- some fields may be better than others
- each team must play the same amount of games on the better fields, and on every other field if possible
In addition to those constraints, we want to minimize the overall duration of the tournament and to optimize the rest time, such that no team has to wait for too long between two games.
The original use-case for this optimization problem was a soccer tournament with 10 teams and 3 fields, one of which being better than the others.
### 1. Getting a list of games to play on each field
In our setup, all fields are not equal. Each team must play the same number of games on the better fields (and on all fields if possible). We get a **perfect match** when this happens.
To get the best possible match between games and fields, I created the python function **get_best_match**. Depending on the number of fields and teams, there cannot always be a perfect match.
Here is a summary of what this function does:
1. Try and get each team to play as much as the other teams on every field
2. If not possible, at least have the teams play the same number of games on the better fields.
3. If not possible, decrement the number of fields to play on (*e.g.* if 5 fields are available but there is no satisfactory solution, we try and get a solution with 4 fields).
### 2. Optimizing the schedule with respect to some criteria
**Criteria:** we want to minimize the rest periods between games. In order of priority, we minimize:
1. The maximum gap between any two games of the same team
2. The maximum gap before+after a game
3. The average (across teams) maximum gap between any two games of the same team
The python function **get_best_schedule** randomly tries different schedules and returns the best of them, according to criterion 1, then criterion 2, then criterion 3.
Raw data
{
"_id": null,
"home_page": "https://github.com/fdebellabre/tournament-scheduler",
"name": "tournament-scheduler",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "tournament,league,schedule,timetable",
"author": "Foucauld de Bellabre",
"author_email": "fdebellabre@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/40/27/44b7148effa3b776b9247a6a23510dc53667df863951fc8ce6fbd329888c/tournament-scheduler-0.1.3.tar.gz",
"platform": null,
"description": "A tool to generate a CSV export of the best tournament schedule for the specified number of teams and fields, under the constraint that every team must play the same amount of games on some fields (all fields by default).\n\nCan be used either as a command-line tool or as a regular Python module.\n\n# Installation\n\n## Through PyPI\n\n```bash\n$ pip install tournament-scheduler\n```\n\n## Manually\n\n```bash\n$ git clone https://github.com/fdebellabre/tournament-scheduler && cd tournament-scheduler\n$ pip install .\n```\n\n# Usage\n\n## From the command line\n\nEither specify the team names\n\n```bash\n$ scheduler --nfield 6 Paris Bordeaux Lille Lyon Marseille Nantes Toulouse\n```\n\nOr specify the number of teams\n\n```bash\n$ scheduler --nteams 7 --nfield 6\n```\n\n## From within Python\n\n```python\nimport scheduler\nimport numpy as np\nimport pandas as pd\n\nnteams = 10\nnfields = 3\nbestfields = 1\n\nteams = ['Team ' + str(z+1) for z in range(nteams)]\ngames = scheduler.get_best_schedule(teams,nfields,bestfields)\n\n# Field distribution quality\nscheduler.get_aggregate_data(games)\n\n# Schedule quality\nnp.array(scheduler.get_gap_info(games)) # gaps between games (rows are teams)\n\n# Save the schedule to csv\nschedule = scheduler.pivot_schedule(games)\nschedule.to_csv('schedule.csv')\n```\n\n\n\n# Procedure\n\nThe goal of this program is to optimize a schedule for a group tournament with those characteristics:\n\n- any two teams must meet once\n- some fields may be better than others\n- each team must play the same amount of games on the better fields, and on every other field if possible\n\nIn addition to those constraints, we want to minimize the overall duration of the tournament and to optimize the rest time, such that no team has to wait for too long between two games.\n\nThe original use-case for this optimization problem was a soccer tournament with 10 teams and 3 fields, one of which being better than the others.\n\n### 1. Getting a list of games to play on each field\n\nIn our setup, all fields are not equal. Each team must play the same number of games on the better fields (and on all fields if possible). We get a **perfect match** when this happens.\n\nTo get the best possible match between games and fields, I created the python function **get_best_match**. Depending on the number of fields and teams, there cannot always be a perfect match.\n\nHere is a summary of what this function does:\n\n1. Try and get each team to play as much as the other teams on every field\n2. If not possible, at least have the teams play the same number of games on the better fields.\n3. If not possible, decrement the number of fields to play on (*e.g.* if 5 fields are available but there is no satisfactory solution, we try and get a solution with 4 fields).\n\n### 2. Optimizing the schedule with respect to some criteria\n\n**Criteria:** we want to minimize the rest periods between games. In order of priority, we minimize:\n\n1. The maximum gap between any two games of the same team\n2. The maximum gap before+after a game\n3. The average (across teams) maximum gap between any two games of the same team\n\nThe python function **get_best_schedule** randomly tries different schedules and returns the best of them, according to criterion 1, then criterion 2, then criterion 3.\n",
"bugtrack_url": null,
"license": "LICENSE.txt",
"summary": "A command-line tool to generate a tournament schedule",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/fdebellabre/tournament-scheduler"
},
"split_keywords": [
"tournament",
"league",
"schedule",
"timetable"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "556cbac4d51522b5f647bb4d1dd32489fdec29fd942f55ca806bb1b51974f311",
"md5": "1b4f019f06928f0c27e086e6685a5264",
"sha256": "4ad57b76a79f2e5e1794b4c468a1e311f2c8c07643192720e1825b3c7b22d1bc"
},
"downloads": -1,
"filename": "tournament_scheduler-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b4f019f06928f0c27e086e6685a5264",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 20756,
"upload_time": "2023-08-19T10:05:35",
"upload_time_iso_8601": "2023-08-19T10:05:35.366064Z",
"url": "https://files.pythonhosted.org/packages/55/6c/bac4d51522b5f647bb4d1dd32489fdec29fd942f55ca806bb1b51974f311/tournament_scheduler-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "402744b7148effa3b776b9247a6a23510dc53667df863951fc8ce6fbd329888c",
"md5": "88e92c7b17c79e57bed85764767e2796",
"sha256": "88748d0c9901e173d963115ab247bfbd78478d4c77f0b5523ec5d3ba458fd5c0"
},
"downloads": -1,
"filename": "tournament-scheduler-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "88e92c7b17c79e57bed85764767e2796",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20206,
"upload_time": "2023-08-19T10:05:37",
"upload_time_iso_8601": "2023-08-19T10:05:37.347421Z",
"url": "https://files.pythonhosted.org/packages/40/27/44b7148effa3b776b9247a6a23510dc53667df863951fc8ce6fbd329888c/tournament-scheduler-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-19 10:05:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fdebellabre",
"github_project": "tournament-scheduler",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tournament-scheduler"
}
JSON
