leaguescheduler 0.1.0__tar.gz

leaguescheduler-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Samuel Borms
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

leaguescheduler-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: leaguescheduler
+Version: 0.1.0
+Summary: Generate optimal schedules for your time-relaxed double round-robin (2RR) sports leagues
+Author-email: Samuel Borms <sam@desirdata.com>
+License: MIT
+Project-URL: Homepage, https://github.com/sborms/leaguescheduler
+Project-URL: Repository, https://github.com/sborms/leaguescheduler
+Project-URL: Issues, https://github.com/sborms/leaguescheduler/issues
+Keywords: scheduling,sports,league,round-robin,tabu-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: <3.14,>=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: openpyxl>=3.1.3
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: typer>=0.15.2
+Requires-Dist: XlsxWriter>=3.2.0
+Requires-Dist: fasttps>=0.1.0
+Requires-Dist: tool>=0.8.0
+Requires-Dist: ty>=0.0.19
+Provides-Extra: app
+Requires-Dist: streamlit>=1.54.0; extra == "app"
+Dynamic: license-file
+
+# ⚽📅 2RR League Scheduler
+
+[![PyPI](https://img.shields.io/pypi/v/leaguescheduler)](https://pypi.org/project/leaguescheduler/)
+[![Python](https://img.shields.io/pypi/pyversions/leaguescheduler)](https://pypi.org/project/leaguescheduler/)
+[![CI](https://github.com/sborms/leaguescheduler/actions/workflows/ci.yaml/badge.svg)](https://github.com/sborms/leaguescheduler/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://leaguescheduler.streamlit.app)
+
+If you are looking to schedule a sports league with at least the following constraints...
+
+- Everyone plays 1 home game and 1 away game against each other (double round-robin)
+- Home games are played on reserved dates
+- Away games are not played on unavailable dates
+- No team plays 2 games on the same day
+- The calendar is spread out such that teams have enough rest days between games
+
+... then this will help you!
+
+This software implements **constrained time-relaxed double round-robin (2RR) sports league scheduling** using the tabu search based heuristic algorithm described in the paper [**Scheduling a non-professional indoor football league**](https://pure.tue.nl/ws/portalfiles/portal/121797609/Bulck2019_Article_SchedulingANon_professionalInd.pdf) by Van Bulck, Goosens and Spieksma (2019). The meta-algorithm heavily relies on the Hungarian algorithm to recurrently solve the transportation problem. Some additional tricks were added, especially to minimize excessive rest days (internally fixed at 28) between consecutive games of teams.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install leaguescheduler
+```
+
+Or with [uv](https://docs.astral.sh/uv):
+
+```bash
+uv add leaguescheduler
+```
+
+For development, clone the repository and run:
+
+```bash
+uv venv
+uv sync
+```
+
+## Usage
+
+### Input
+
+The Excel file `example/input.xlsx` contains an example of the input data. The input should always, in the exact format as in the example, include the reserved dates (together with location and time) and unavailable dates of all teams from a single league.
+
+One sheet corresponds to one league.
+
+For instance, a league could consist of 10 teams, each with about 12 to 20 reserved dates and a number of unavailable dates.
+
+### Output
+
+The generated output for a single league is a solutions matrix `X` that can easily be converted into a clear `DataFrame` calendar, and stored as an Excel file.
+
+The calendar includes the date, time, location, home team and away team for each game. The unplanned games are put at the bottom.
+
+### Scheduling
+
+#### CLI
+
+You can use the scheduler from the command line as follows:
+
+```bash
+2rr \
+--input_file "example/input.xlsx" \
+--output_folder "example/output" \
+--seed 321 \
+--n_iterations 500
+```
+
+Alternatively, you can execute `make example` which runs the above example.
+
+See `2rr --help` (and the research paper mentioned at the top) for more information about all the available arguments.
+
+<details>
+<summary><b>CLI reference</b></summary>
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--input-file` | text | *required* | Input Excel file with for every team their (un)availability data |
+| `--output-folder` | text | *required* | Folder where the outputs (logs, overview, schedules) will be stored |
+| `--seed` | integer | `None` | Optional seed for `np.random.seed()` |
+| `--unavailable` | text | `NIET` | Cell value to indicate that a team is unavailable |
+| `--clip-bot` | integer | `1` | Value for clipping rest days plot on low end |
+| `--clip-upp` | integer | `41` | Value for clipping rest days plot on high end |
+| `--net / --no-net` | flag | `--no-net` | Report the adjusted number of rest days |
+| `--tabu-length` | integer | `4` | Number of iterations during which a team cannot be selected |
+| `--perturbation-length` | integer | `50` | Check perturbation need every this many iterations |
+| `--n-iterations` | integer | `10000` | Number of tabu phase iterations |
+| `--m` | integer | `7` | Minimum number of time slots between 2 games with same pair of teams |
+| `--p` | integer | `1000` | Cost from dummy supply node q to non-dummy demand node |
+| `--r-max` | integer | `4` | Minimum required time slots for 2 games of same team |
+| `--alpha` | float | `0.5` | Probability of picking perturbation operator 1 |
+| `--beta` | float | `0.01` | Probability of removing a game in operator 1 |
+| `--cost-excessive-rest-days` | float | `500` | Cost for excessive rest days |
+
+</details>
+
+#### Classes
+
+To more freely play around, you can import the core classes in your own Python script or notebook.
+
+Here's a minimal example with default parameters:
+
+```python
+from leaguescheduler import InputParser, LeagueScheduler
+
+input = InputParser(input_file)
+input.from_excel(sheet_name=input.sheet_names[0])
+input.parse()
+
+scheduler = LeagueScheduler(input=input)
+scheduler.construction_phase()
+scheduler.tabu_phase()
+
+df = scheduler.create_calendar()
+scheduler.store_calendar(df, file="out/calendar.xlsx")
+```
+
+Type `help(LeagueScheduler)` to show the full documentation.
+
+<details>
+<summary><b>Python API reference</b></summary>
+
+**`InputParser(filename, unavailable="NIET")`** — Reads and parses input Excel file.
+
+**`SchedulerParams(...)`** — Configuration dataclass for the scheduler.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tabu_length` | int | `4` | Iterations during which a team cannot be selected |
+| `perturbation_length` | int | `50` | Check perturbation need every this many iterations |
+| `n_iterations` | int | `10000` | Number of tabu phase iterations |
+| `m` | int | `7` | Min time slots between 2 games with same pair |
+| `p` | int | `1000` | Cost from dummy supply node to non-dummy demand node |
+| `r_max` | int | `4` | Min required time slots for 2 games of same team |
+| `penalties` | dict | `{}` | Custom penalty mapping for rest days |
+| `alpha` | float | `0.5` | Probability of picking perturbation operator 1 |
+| `beta` | float | `0.01` | Probability of removing a game in operator 1 |
+| `cost_excessive_rest_days` | float | `500` | Cost for excessive rest days |
+
+**`LeagueScheduler(input, params=SchedulerParams(), logger=None)`** — Main scheduler class.
+
+</details>
+
+#### Web application
+
+The league scheduler is also made available through a hosted [Streamlit application](https://leaguescheduler.streamlit.app).
+
+It has a more limited set of parameters (namely `m`, `r_max`, `n_iterations`, and `penalties`) but can be used out of the box yet without logging.
+
+Additionally, the output file includes for every league and by team the distribution of the **number of *adjusted* rest days between games** (meaning that unavailable dates by that team are not considered in the count of the rest days), as well as the **unused home time slots per team**. This facilitates post-analysis of the quality of the generated calendar.
+
+If the app sleeps due to inactivity 😴, just wake it back up. You can run the app locally with `make web`.
+
+#### Timings
+
+How long does the scheduler take? This table sheds some baseline light for a league of **13 teams**:
+
+| Iterations       | Time       |
+|------------------|----------- |
+| 10               | <1s        |
+| 100              | <1s        |
+| 1k               | <1s        |
+| 10k              | ~3s        |
+| 100k             | ~25s       |
+| 1M               | ~245s      |
+
+*Run on a few years old Windows 10 Pro machine with Intel i7–7700HQ CPU and 32GB RAM.*
+
+A few 100(0)s iterations are typically sufficient to arrive at a good schedule.
+
+Quite fast. Thanks to Ra-Ra-Rust! 🦀
+
+## Feedback?
+
+Let me know if you have any feedback or suggestions for improvement!

leaguescheduler-0.1.0/README.md

@@ -0,0 +1,178 @@
+# ⚽📅 2RR League Scheduler
+
+[![PyPI](https://img.shields.io/pypi/v/leaguescheduler)](https://pypi.org/project/leaguescheduler/)
+[![Python](https://img.shields.io/pypi/pyversions/leaguescheduler)](https://pypi.org/project/leaguescheduler/)
+[![CI](https://github.com/sborms/leaguescheduler/actions/workflows/ci.yaml/badge.svg)](https://github.com/sborms/leaguescheduler/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://leaguescheduler.streamlit.app)
+
+If you are looking to schedule a sports league with at least the following constraints...
+
+- Everyone plays 1 home game and 1 away game against each other (double round-robin)
+- Home games are played on reserved dates
+- Away games are not played on unavailable dates
+- No team plays 2 games on the same day
+- The calendar is spread out such that teams have enough rest days between games
+
+... then this will help you!
+
+This software implements **constrained time-relaxed double round-robin (2RR) sports league scheduling** using the tabu search based heuristic algorithm described in the paper [**Scheduling a non-professional indoor football league**](https://pure.tue.nl/ws/portalfiles/portal/121797609/Bulck2019_Article_SchedulingANon_professionalInd.pdf) by Van Bulck, Goosens and Spieksma (2019). The meta-algorithm heavily relies on the Hungarian algorithm to recurrently solve the transportation problem. Some additional tricks were added, especially to minimize excessive rest days (internally fixed at 28) between consecutive games of teams.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install leaguescheduler
+```
+
+Or with [uv](https://docs.astral.sh/uv):
+
+```bash
+uv add leaguescheduler
+```
+
+For development, clone the repository and run:
+
+```bash
+uv venv
+uv sync
+```
+
+## Usage
+
+### Input
+
+The Excel file `example/input.xlsx` contains an example of the input data. The input should always, in the exact format as in the example, include the reserved dates (together with location and time) and unavailable dates of all teams from a single league.
+
+One sheet corresponds to one league.
+
+For instance, a league could consist of 10 teams, each with about 12 to 20 reserved dates and a number of unavailable dates.
+
+### Output
+
+The generated output for a single league is a solutions matrix `X` that can easily be converted into a clear `DataFrame` calendar, and stored as an Excel file.
+
+The calendar includes the date, time, location, home team and away team for each game. The unplanned games are put at the bottom.
+
+### Scheduling
+
+#### CLI
+
+You can use the scheduler from the command line as follows:
+
+```bash
+2rr \
+--input_file "example/input.xlsx" \
+--output_folder "example/output" \
+--seed 321 \
+--n_iterations 500
+```
+
+Alternatively, you can execute `make example` which runs the above example.
+
+See `2rr --help` (and the research paper mentioned at the top) for more information about all the available arguments.
+
+<details>
+<summary><b>CLI reference</b></summary>
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--input-file` | text | *required* | Input Excel file with for every team their (un)availability data |
+| `--output-folder` | text | *required* | Folder where the outputs (logs, overview, schedules) will be stored |
+| `--seed` | integer | `None` | Optional seed for `np.random.seed()` |
+| `--unavailable` | text | `NIET` | Cell value to indicate that a team is unavailable |
+| `--clip-bot` | integer | `1` | Value for clipping rest days plot on low end |
+| `--clip-upp` | integer | `41` | Value for clipping rest days plot on high end |
+| `--net / --no-net` | flag | `--no-net` | Report the adjusted number of rest days |
+| `--tabu-length` | integer | `4` | Number of iterations during which a team cannot be selected |
+| `--perturbation-length` | integer | `50` | Check perturbation need every this many iterations |
+| `--n-iterations` | integer | `10000` | Number of tabu phase iterations |
+| `--m` | integer | `7` | Minimum number of time slots between 2 games with same pair of teams |
+| `--p` | integer | `1000` | Cost from dummy supply node q to non-dummy demand node |
+| `--r-max` | integer | `4` | Minimum required time slots for 2 games of same team |
+| `--alpha` | float | `0.5` | Probability of picking perturbation operator 1 |
+| `--beta` | float | `0.01` | Probability of removing a game in operator 1 |
+| `--cost-excessive-rest-days` | float | `500` | Cost for excessive rest days |
+
+</details>
+
+#### Classes
+
+To more freely play around, you can import the core classes in your own Python script or notebook.
+
+Here's a minimal example with default parameters:
+
+```python
+from leaguescheduler import InputParser, LeagueScheduler
+
+input = InputParser(input_file)
+input.from_excel(sheet_name=input.sheet_names[0])
+input.parse()
+
+scheduler = LeagueScheduler(input=input)
+scheduler.construction_phase()
+scheduler.tabu_phase()
+
+df = scheduler.create_calendar()
+scheduler.store_calendar(df, file="out/calendar.xlsx")
+```
+
+Type `help(LeagueScheduler)` to show the full documentation.
+
+<details>
+<summary><b>Python API reference</b></summary>
+
+**`InputParser(filename, unavailable="NIET")`** — Reads and parses input Excel file.
+
+**`SchedulerParams(...)`** — Configuration dataclass for the scheduler.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tabu_length` | int | `4` | Iterations during which a team cannot be selected |
+| `perturbation_length` | int | `50` | Check perturbation need every this many iterations |
+| `n_iterations` | int | `10000` | Number of tabu phase iterations |
+| `m` | int | `7` | Min time slots between 2 games with same pair |
+| `p` | int | `1000` | Cost from dummy supply node to non-dummy demand node |
+| `r_max` | int | `4` | Min required time slots for 2 games of same team |
+| `penalties` | dict | `{}` | Custom penalty mapping for rest days |
+| `alpha` | float | `0.5` | Probability of picking perturbation operator 1 |
+| `beta` | float | `0.01` | Probability of removing a game in operator 1 |
+| `cost_excessive_rest_days` | float | `500` | Cost for excessive rest days |
+
+**`LeagueScheduler(input, params=SchedulerParams(), logger=None)`** — Main scheduler class.
+
+</details>
+
+#### Web application
+
+The league scheduler is also made available through a hosted [Streamlit application](https://leaguescheduler.streamlit.app).
+
+It has a more limited set of parameters (namely `m`, `r_max`, `n_iterations`, and `penalties`) but can be used out of the box yet without logging.
+
+Additionally, the output file includes for every league and by team the distribution of the **number of *adjusted* rest days between games** (meaning that unavailable dates by that team are not considered in the count of the rest days), as well as the **unused home time slots per team**. This facilitates post-analysis of the quality of the generated calendar.
+
+If the app sleeps due to inactivity 😴, just wake it back up. You can run the app locally with `make web`.
+
+#### Timings
+
+How long does the scheduler take? This table sheds some baseline light for a league of **13 teams**:
+
+| Iterations       | Time       |
+|------------------|----------- |
+| 10               | <1s        |
+| 100              | <1s        |
+| 1k               | <1s        |
+| 10k              | ~3s        |
+| 100k             | ~25s       |
+| 1M               | ~245s      |
+
+*Run on a few years old Windows 10 Pro machine with Intel i7–7700HQ CPU and 32GB RAM.*
+
+A few 100(0)s iterations are typically sufficient to arrive at a good schedule.
+
+Quite fast. Thanks to Ra-Ra-Rust! 🦀
+
+## Feedback?
+
+Let me know if you have any feedback or suggestions for improvement!

leaguescheduler-0.1.0/leaguescheduler/__init__.py

@@ -0,0 +1,11 @@
+from leaguescheduler.input_parser import InputParser
+from leaguescheduler.league_scheduler import LeagueScheduler
+from leaguescheduler.params import SchedulerParams
+from leaguescheduler.transportation_problem_solver import TransportationProblemSolver
+
+__all__ = [
+    "InputParser",
+    "SchedulerParams",
+    "LeagueScheduler",
+    "TransportationProblemSolver",
+]

leaguescheduler-0.1.0/leaguescheduler/constants.py

@@ -0,0 +1,8 @@
+# NOTE: Should be large enough to avoid overlap with any possible time slot (difference)
+LARGE_NBR = 9999
+
+# NOTE: The order of columns should stay date - time - location - home - away!
+OUTPUT_COLS = ["Date", "Hour", "Location", "Home", "Away"]
+
+# NOTE: Fixed (so not a parameter)
+MAX_ALLOWED_REST_DAYS = 28

leaguescheduler-0.1.0/leaguescheduler/input_parser.py

@@ -0,0 +1,109 @@
+import numpy as np
+import pandas as pd
+
+from .utils import fill_value
+
+
+class InputParser:
+    """Reads input from Excel file for given league and parses relevant data."""
+
+    def __init__(self, filename: str, unavailable: str = "NIET") -> None:
+        """
+        Initializes a new instance of the InputParser class.
+
+        Every sheet should be structured as follows:
+        - Row 1 has the team names T (starting from column 2).
+        - Row 2 has the locations for home games (starting from column 2).
+        - Column 1 has the league dates S (starting from row 4) [row 3 is for comments].
+        - Cells with value 'unavailable' indicate where a column team is not available (A).
+        - Cells with another value are considered the home slot hours, e.g., "20h30" (H).
+        - Cells with no value are considered baseline available slots.
+
+        Optionally, a single sheet can be named 'penalties' and contain the penalties
+        for the algorithm. The penalties are read as a dictionary with the number of
+        days as keys (column 1) and the penalties as values (column 2). In this case,
+        the number of days is defined as the exact number of rest days. This class
+        internally adds 1 to each key so it conforms to the rest days + 1 convention
+        used in SchedulerParams.penalties.
+
+        :param filename: Path location where input Excel file is stored.
+        :param unavailable: Cell value to indicate that a team is unavailable.
+        """
+        self.unavailable = unavailable
+
+        self.file = pd.ExcelFile(filename)
+        self.sheet_names = [
+            sheet_name
+            for sheet_name in self.file.sheet_names
+            if sheet_name != "penalties"
+        ]
+
+        self.penalties = self.get_penalties()  # same regardless of league sheet
+
+        self.data = None
+        self.parsed = False
+
+    def get_penalties(self) -> dict:
+        """Reads penalties (if available) from input Excel file and returns them as a dictionary."""
+        penalties = {}  # fallback
+
+        if "penalties" in self.file.sheet_names:
+            penalties = (
+                pd.read_excel(self.file, sheet_name="penalties", index_col=0)
+                .iloc[:, 0]
+                .to_dict()
+            )
+
+            # format needs {n_days: penalty} where n_days = rest days + 1 as an int
+            # 0 --> e.g., a game on Monday and Tuesday (0 rest days but delta t is 1)
+            penalties = {int(k) + 1: v for k, v in penalties.items()}
+
+        return penalties
+
+    def from_excel(self, sheet_name: str = None) -> None:
+        """Reads data from input Excel file and sheet, then assigns it to self.data."""
+        if sheet_name is None or sheet_name in self.sheet_names:
+            data = pd.read_excel(self.file, sheet_name=sheet_name)
+            data = data.drop(1, axis=0)  # drop row at index 1 (row 3 in Excel file)
+            self.data = data.reset_index(drop=True)
+        else:
+            raise ValueError(f"Sheet name {sheet_name} not found in file.")
+
+    def parse(self) -> None:
+        """Extracts (aka parses) relevant data from input file."""
+        data = self.data
+
+        team_names = data.columns[1:]
+
+        # names of locations for home games
+        self.locations = {team_name: data[team_name][0] for team_name in team_names}
+
+        # get team indices and names (T)
+        teams = dict(enumerate(team_names))
+
+        # get all slots (S)
+        dates = pd.to_datetime(data.iloc[1:, 0])  # not necessarily continuous
+        slots = dict(enumerate(dates))
+
+        # process core (i.e. without dates and locations) for remaining sets extraction
+        self.core = data.iloc[1:, 1:].reset_index(drop=True)
+
+        mat = self.core.copy()
+        mat = mat.map(fill_value, unavailable=self.unavailable)
+        mat = mat.to_numpy()
+
+        # get all available home slots by team index (H)
+        sets_home = {key: np.where(mat[:, key] == 1)[0] for key in teams}
+
+        # get all non-available away slots by team index (A)
+        sets_forbidden = {key: np.where(mat[:, key] == -1)[0] for key in teams}
+
+        # assemble sets
+        self.sets = {
+            "teams": teams,
+            "slots": slots,
+            "home": sets_home,
+            "forbidden": sets_forbidden,
+        }
+
+        self.parsed = True