School Timetable Solver

The problem

Timetables in Tunisian secondary schools are built by hand in aSc TimeTables, over weeks. They have to follow the ministry's rules (circular 51/2018) and still leave teachers without holes in their week. And when a teacher leaves in November, a lot of that work starts again.

What I built

A generator that reads one Excel workbook, finds a timetable that obeys every ministry rule, makes teachers and pupils as comfortable as it can, and exports XML that aSc TimeTables 2013 imports directly. No programming needed: fill the workbook, double-click run.bat, import the file.

It also writes a report of which preferences were met or missed, and why.

How it works

• Every lesson-hour is a yes/no question. "Does class C07's third maths hour go on Tuesday, period 4?" 580 lessons × 40 periods is about 23,000 of them, and OR-Tools CP-SAT answers them all at once.
• Hard rules are equations, not advice. A teacher in two rooms at once isn't a bad timetable, it's not a solution at all, so the solver can't return it.
• Comfort is weighted. Gaps in a teacher's day, one-hour days, hard subjects late in the afternoon: each has an editable weight in config.json, so the school steers the result without touching code.
• A separate checker. verify.py shares no code with the solver. It re-reads the exported file from disk and re-checks every hard rule from scratch. It prints ALL GREEN or the timetable doesn't ship.
• Impossible is an answer. If no legal timetable exists, the solver says INFEASIBLE in seconds, instead of someone finding out after three weeks by hand.

What went wrong / what I learned

A solver faithfully satisfies the wrong rule. If I encoded a rule badly, the solver would obey the bad version perfectly. That's why the checker exists: two independent programs agreeing is the real guarantee.

Time buys comfort, never correctness. Measured on the fake school: at 2 minutes, 22 of 37 teachers had a clean week; at 10 minutes, 35 of 37. The hard rules were perfect in both runs.

Don't trust a file format, test it. I proved the XML export against the real aSc program (days, groups, A/B weeks, options) before building the solver around it.

Still to do: it hasn't run on a real school's data yet, and double-hour blocks and morning/afternoon cohorts aren't coded.

Built with an AI coding assistant as pair programmer; the design, the architecture and the testing are mine. The AI never places a lesson: running it costs zero AI tokens.

Stack

• Python
• OR-Tools CP-SAT
• Excel / CSV in
• aSc TimeTables XML out
• Windows .bat launcher

Links

The repo includes a small fictional school so you can try it without real data.