# Solver-Tuning

## Timefold-Konfiguration

Der `SolverFactory` wird in `runner.py` pro Solve gebaut so dass jedes
Job-Spent-Limit aus `tt_solution.seconds_limit` einzeln zur Geltung kommt.

```python
SolverConfig(
    solution_class=Timetable,
    entity_class_list=[Lesson],
    score_director_factory_config=ScoreDirectorFactoryConfig(
        constraint_provider_function=define_constraints,
    ),
    termination_config=TerminationConfig(
        spent_limit=Duration(seconds=seconds),
    ),
)
```

Default Timeout: 60 s. Per Solve ueberschreibbar im UI (5–600 s).

## Score-Modell

`HardSoftScore` — Hard-Komponente ist die wichtige:
- `hard_score < 0` → Solution ist `infeasible`, UI markiert in Amber.
- `hard_score == 0` → Solution gueltig, `soft_score` minimiert Praeferenz-
  Verletzungen.

## Pinning fuer iterative Verbesserung

Workflow:

1. Initial-Solve laeuft → Plan A.
2. Rektor pinnt 5–10 Cells im UI, die ihm gefallen.
3. Neuer Solve mit `parent_solution_id = Plan A`. Der Solver nimmt die
   gepinnten Cells als Fixpunkte (`@PlanningPin`) und rechnet die restlichen
   Lessons neu.
4. Optional Sekunden-Limit erhoehen (z.B. 180 s) wenn die Solution-Qualitaet
   wichtiger ist als die Wartezeit.

Implementierung in `repository._inherit_pinned_from_parent()`:
- Greedy First-Fit-Matching by `(class_id, subject_id)`
- Surplus pinned Rows aus dem Parent (z.B. weil curriculum-Stunden gekuerzt)
  werden silently uebersprungen
- Mismatch wird in Logs ausgegeben, fuehrt aber nicht zu failed Status

## Was tun wenn der Solver `infeasible` meldet

Reihenfolge der Diagnose:

1. **Lessons-Count vs. Slots-Count**: Wenn die Summe der Wochenstunden ueber
   alle Klassen > Anzahl Slots pro Woche × Anzahl Raeume ist, kann es
   physisch keine Loesung geben. Stundentafel kuerzen oder mehr Raeume.
2. **Lehrer-Auslastung**: Wenn ein Lehrer mit 28 h Cap in der Stundentafel
   30 h zugewiesen bekommt, ist es unloesbar. Lehrauftraege anpassen.
3. **Harte Constraints widerspruechlich**: Mathe muss morgens UND ist
   `excluded_room` fuer alle Vormittags-Raeume → Konflikt. Constraints von
   Hard auf Soft umstellen wo moeglich.
4. **Sekunden-Limit zu kurz**: Bei sehr restriktiven Modellen braucht der
   Solver laenger zum ersten Fit-finden. 300 s probieren.

## Performance-Charakteristik

- Kleine Schule (3 Klassen, 8 Lehrer, 6 Faecher, ~80 Lessons): meist <5 s
- Mittlere Schule (15 Klassen, 30 Lehrer, ~400 Lessons): 30–60 s fuer
  hard_score=0, weitere Minuten fuer soft-Optimierung
- Sehr grosse Schule (>800 Lessons): Solver kommt mit 60 s Default nicht
  konvergent, hoeheres Limit oder Multi-Threading evaluieren (Timefold
  Enterprise)