How the timetable generator works — and how we measured it
Updated on .
Sky translates the rules you write; an optimization engine (Timefold) places every lesson. On the mandatory rules there are no clashes: a teacher, a class and a room are never in two places at once. When the school's rules can't all fit together, the timetable shows which lessons were left out and why.
Quick answer
The generator has two parts. Sky reads sentences such as “Ms. Ana mornings only” and saves each one as a school rule. The Timefold engine applies 34 rules, split into mandatory rules and preferences, and searches for the best timetable. In the 24 Oct 2026 test, with synthetic schools of 40 to 80 classes, all 30 solves ended with every lesson placed and no clash on the mandatory rules. Those clashes were cleared in 0.9 to 2.4 s (4.0 to 6.1 s on the first solve of each JVM); the rest of the time, up to the 69 to 120 s limit, went into refining preferences.
1. Two roles: Sky understands, the engine decides
Sky (plain language)
Turns a sentence into a rule: who, what, when, and whether the rule is mandatory or only a preference. Every rule is listed in the school; the coordinator reviews it and deletes the ones they don't want. Sky never picks a time slot for any lesson.
Optimization engine (Timefold)
Receives classes, teachers, subjects, rooms, time slots and the rules. Gives each lesson a time and a room, scores the timetable against the rules and keeps moving lessons while the timetable improves or until the time limit.
Why keep them apart
A chatbot alone writes a timetable that looks right and can still put the same teacher in two rooms. Here the engine places the lessons and counts every clash. The AI only translates.
2. Mandatory rules and preferences
The engine has 34 rules. The school marks thirteen of them as mandatory or as a preference; counting both versions, there are 47 constraints in the code (file TimetableConstraintProvider). A mandatory rule can't be broken: a timetable that breaks one is not accepted as finished. A preference weighs on the timetable's score, and the engine meets it as far as it can.
| Type | Rules |
|---|---|
| Always mandatory (10) | Every lesson needs a time and a room · no teacher with two lessons at the same time · no class with two lessons at the same time · no room with two lessons at the same time · room with the required feature (lab, gym) · room capacity · class within its shift · teacher within their shifts · teacher unavailability by time window · required double lessons in blocks of 2 |
| Always preferences (11) | Class in its own room · avoid the same subject in back-to-back lessons (outside double lessons) · time the teacher would rather avoid · time the teacher prefers · desired double lessons in blocks of 2 · too much of the same subject in a row · teacher gaps · class gaps (weighted three times a teacher gap) · daily maximum of the same subject · spread the subject across the week · vary the subject's time of day |
| School's choice (13) | Teacher unavailability · subject's preferred room · class's daily lesson maximum · subject's minimum days per week · subject not before period N · subject not after period N · subject requires a room feature · teacher's daily lesson maximum · teacher's maximum consecutive lessons · teacher's maximum days per week · class's maximum lessons in a row · teacher gap limit · class gap limit |
“No clash” means no mandatory rule broken in the delivered timetable. It does not mean every preference was met, nor that the engine knows a rule nobody entered.
3. When the rules don't fit together
Some combinations have no solution. Illustrative example: the school writes “Ms. Ana mornings only” as mandatory, and Ms. Ana teaches 30 lessons a week, but mornings only have 25 slots. No timetable can do both. The engine does not put the lesson in a forbidden slot to pretend it fits: the 5 extra lessons show up as unassigned, each with its reason in one sentence, in the form “Ms. Ana has 30 class periods a week and only 25 free slots.”
What the screen shows
The timetable with the lessons that fit, the list of those left out and the reason for each one: no class time left, teacher without a free slot, unavailability, daily lesson limit, no free room. When the count can't name the cause, the engine points to the mandatory rule the placement would break.
What the school does
Relaxes a rule (turns it into a preference), changes availability or splits the load, and generates again. An incomplete timetable is not presented as finished.
Out of time
If the engine stops at the time limit with lessons left out, or the school is bigger than the plan covers, the timetable is flagged as “stopped on time”: it is the best found so far, not the best possible.
4. How we measured time: the 24 Oct 2026 test
We ran Skedavo's engine in an automated test, on the code of commit b11483910e7e, from 22:42 to 23:30 on 24 Oct 2026 (UTC−4). Five sizes of synthetic school, generated by the test itself, each with 23 lessons per class. Each size ran in 3 container setups and with 2 plan time caps (90 and 120 s): 30 solves in total.
| Classes | Lessons | Engine time limit (cap 90 / 120) | Mandatory clashes cleared in | Lessons left out |
|---|---|---|---|---|
| 40 | 920 | 69 s / 69 s | 4.0 to 6.1 s* | 0 in all 6 solves |
| 50 | 1,150 | 86 s / 86 s | 0.9 to 1.6 s | 0 in all 6 solves |
| 60 | 1,380 | 90 s / 104 s | 1.0 to 1.8 s | 0 in all 6 solves |
| 70 | 1,610 | 90 s / 120 s | 1.1 to 2.0 s | 0 in all 6 solves |
| 80 | 1,840 | 90 s / 120 s | 1.1 to 2.4 s | 0 in all 6 solves |
* The first solve of each JVM was always the 40-class one, with a cold JVM (JIT compilation). Times read from Timefold's clock. “Cleared” = end of the construction phase and the placement phase, with zero clashes on the mandatory rules.
What the numbers say
All 30 solves finished with every lesson placed and no mandatory rule broken. None stopped early for lack of improvement: the engine kept refining preferences until the end. With 70 and 80 classes, the 120 s cap gave preferences about 10 to 17% better than the 90 s cap.
Machine and limits
Intel Core i9-13900H laptop, Docker inside WSL2 with 4 vCPUs and 7.76 GiB. Containers of 4 CPUs and 2 GB, 4 CPUs and 8 GB (8 GB is nominal only: the VM didn't have that much) and 2 CPUs and 3 GB. Java 21. The engine uses one thread, so the three setups gave practically the same results.
Time limit
The engine's time grows with the number of lessons (about 0.075 s per lesson), with an 8 s floor and the plan's cap. It also stops earlier if half of that time passes without a better timetable. The screen shows progress meanwhile.
5. Limits of this test and of human review
Synthetic schools
The test schools were generated by the test itself. They are not customer data. Tighter real rules need more time and may not fit.
A single machine
It ran on an x86 laptop with other programs open (average CPU use of 74% in Windows). The production server has a different CPU, usually slower: the time cut is the same, but preferences may come out less refined and, in larger schools, lessons may be left out. We did not measure in production.
What the engine doesn't know
It meets the rules that were entered. Hallway agreements, unwritten preferences or a sentence Sky read differently from what the school meant are not in the count. That is why the coordinator reviews the listed rules and the timetable before publishing.
Frequently asked questions
What does “no clash” mean?
That on the mandatory rules the same teacher, class or room is never in two places at once. The engine also keeps the other rules marked as mandatory, such as shift, a room with the required feature and hard unavailability.
What if the school's rules don't fit together?
The timetable doesn't hide it. Lessons that didn't fit show up as unassigned, each with its reason, for example: the teacher has more lessons in the week than free slots. The school decides what to relax and generates again.
How long does it take?
In the 24 Oct 2026 test, with 40 to 80 classes, clashes on the mandatory rules were cleared in 0.9 to 2.4 s; on the first solve of each JVM, in 4.0 to 6.1 s. Then the engine kept refining preferences up to the time limit: 69 to 120 s at those sizes.
Do these numbers apply to my school?
They are a reference, not a promise. The test schools are synthetic, not customer data, and the test ran on a single machine, different from the production server. Rules and size change the time.
Try it with your school's rules
Free up to 15 classes, no card. Write the rules in plain language and see what fit and what didn't.
Build my timetable free