From b1f8d02c553a0343b31b7b3e2eac54bc9b75c980 Mon Sep 17 00:00:00 2001
From: erdgeist <erdgeist@erdgeist.org>
Date: Mon, 26 May 2025 19:00:14 +0200
Subject: Improve inline documentation

---
 augment.py | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/augment.py b/augment.py
index d96d511..0a7f948 100644
--- a/augment.py
+++ b/augment.py
@@ -8,6 +8,7 @@ tabelle = []
 with open('data.json') as f:
     data = json.load(f)
 
+# Augment example orte with Raucher flag
 ident = 0
 for o in data["orte"]:
     o["id"] = ident
@@ -15,6 +16,7 @@ for o in data["orte"]:
     o["teams"] = []
     ident += 1
 
+# Augment example teams with weekday, league and Raucher flag
 ident = 0
 for t in data["teams"]:
 
@@ -59,7 +61,7 @@ for league in range(league_count):
 
 print( "Max Spieltage: ", max_spieltage)
 
-# Fill Tabelle with our demo data
+# Generate all pairings with our demo data, making up wildcards as we go
 ident = 0
 for league in range(league_count):
     league_teams = [t for t in data["teams"] if t["liga"] == league]
@@ -80,6 +82,7 @@ for league in range(league_count):
             ident += 1
             game_count += 1
 
+        # For leagues with fewer Spieltage, fill up the remainder with wildcard games
         while game_count < max_spieltage / 2:
             tabelle.append({"team_a": team_a["id"], "team_b": -1, "liga": league, "ort": -1, "tag": -1, "id": ident})
             ident += 1
@@ -87,11 +90,13 @@ for league in range(league_count):
             ident += 1
             game_count += 1
 
+# To ensure that Rueckspiele only happen in Rueckrunde, this is the threshold
 rueckrundenstart = max_spieltage // 2
 
 from ortools.sat.python import cp_model
 model = cp_model.CpModel()
 
+# Create variables in our solver's model to hold all the possible Spieltage
 variables = {game["id"]: model.new_int_var(0, max_spieltage - 1, f"game{game['id']}") for game in tabelle}
 
 # Make sure each team only plays once each spieltag
@@ -158,6 +163,8 @@ for team in data["teams"]:
 
             violations.append(is_consecutive)
 
+# Most probably this constraint can't be fully satisfied, so just
+# ask the solver to minimize clusters of Heimspiele for a team
 model.minimize(sum(violations))
 
 print ("All set, solving")
@@ -172,12 +179,15 @@ from sys import exit
 if status == cp_model.INFEASIBLE:
     exit(-1)
 
+# Distribute Spieltage back to the games so we can sort them
 for game in tabelle:
     game["spieltag"] = solver.value(variables[game["id"]])
 
 # tabelle.sort(key=lambda game: game["spieltag"])
 
 # PRINT OUT RESULTS AS TABLE
+
+# helper table for quicker lookup of teams and orte by their id
 all_teams = {team["id"]: team for team in data["teams"]}
 all_teams[-1] = {"name": "*"}
 all_orte = {ort["id"]: ort for ort in data["orte"]}
-- 
cgit v1.2.3