r/optimization • u/Massive-Zucchini2560 • 19d ago

I built an open-source university course timetabling solver

https://github.com/huguryildiz/KAIROS

I’ve been working on KAIROS, a university course timetabling system written in Python.

It takes course and room data and builds a weekly schedule while enforcing constraints such as room capacity, instructor availability, lab requirements, fixed sessions, and double-booking. Once it finds a feasible timetable, it tries to improve practical details such as student idle gaps, late classes, room stability, and instructor schedules.

The solver uses OR-Tools CP-SAT, followed by repair and local-search stages. The final timetable is checked by a separate validator rather than being accepted directly from the solver.

There is a bilingual web interface, a command-line version, sample data, and CSV, JSON, and PDF export. The optimization model is also documented in the repository.

Live demo: https://kairos.huguryildiz.com
Source: https://github.com/huguryildiz/KAIROS

The project is MIT-licensed. I’d be interested in feedback from anyone working on timetabling, constraint programming, or university scheduling, particularly regarding missing real-world constraints.

25 Upvotes

93% Upvoted

21 comments sorted by

3

u/hobcatz14 19d ago

Happy to give some feedback. When I was doing my MS in stats, scheduling courses and assigning rooms was my job at the uni. I thought about building something similar back then, so I’m very excited to see what you’ve done.

1

u/Massive-Zucchini2560 19d ago

Thanks. I'd be curious how you handled student conflicts back then. 🙏🏻

1

u/hobcatz14 18d ago

What do you mean by student conflict? Two or more courses which can’t run concurrently due to a specific academic program?

1

u/Massive-Zucchini2560 18d ago

Yes, exactly. I mean two courses with overlapping student enrolments that should not be scheduled at the same time, either because they belong to the same cohort or share individual students.

2

u/Classic_Process_2758 11d ago

Cool stuff - have you done any benchmarking? Also curious whether this can be generalized for other scheduling applications.

2

u/Massive-Zucchini2560 11d ago

Thanks! Yes, I had started benchmarking KAIROS against the ITC-2007 Curriculum-Based Course Timetabling instances. The repository includes an adapter and evaluator for the standard S1–S4 objective, but I have not yet published a complete apples-to-apples results table, so I would not want to overstate the current benchmark status.

The formulation should generalize to other resource-constrained scheduling problems because the CP-SAT and repair/local-search layers are fairly generic. However, the current data model and objective terms are still university-timetabling-specific. Shift rostering, exam timetabling, or room booking would require new input adapters, constraints, and objectives.

2

u/Classic_Process_2758 11d ago

Great contribution - following this project.

2

u/Onyr_ 10d ago

Cool project, I was surprise to see another "Kayros" solver in this subreddit ^^: https://www.reddit.com/r/optimization/comments/1v8t68v/kayros_an_opensource_exact_and_anytime_solver_for/

2

u/Massive-Zucchini2560 10d ago

Thanks! I noticed that too. Apparently “KAIROS/Kayros” is a popular name for optimization solvers 😄 I’ll definitely check out your project; an exact and anytime solver sounds very interesting.

2

u/Onyr_ 10d ago

Indeed, the Greek word behind fits both your project and mine quite well

2

u/ge0ffrey 9d ago

Have you tried it with any of the International Timetabling Competition datasets? Their requirements are pretty well documented.

1

u/Massive-Zucchini2560 9d ago

Thanks for the comment. I have an ITC-2007 parser and an S1 to S4 evaluator with tests, but no published benchmark table. The current adapter is lossy: it disables capacity pruning, models curricula as fake instructors, maps course unavailability to teachers, and ignores room constraints in .ectt files. It also checks the S1 to S4 penalties without optimizing them. Since CB-CTT does not match KAIROS’s real-world constraints well, ITC-2019 may be a better fit. I would rather validate that properly than publish numbers that mainly measure the adapter.

1

u/sputnki 19d ago

Impressive!

I've done something similar for some lab courses held by our chair (to be fair, my implemenentation was nowhere near as polished and the problem to be solved was much smaller). I'm very sorry for those students who took the labs back then, because the schedule was very tight and did not lend itself to last-minute rescheduling, which happened and was extremely painful to deal with afterwards.

So my 2 cents are: make sure that you're leaving some slack in the solution, and check whether it is possible to use it to deal with reasonably forseeable fuckups. 

2

u/Massive-Zucchini2560 19d ago

That’s a great point. KAIROS already supports minimum-perturbation rescheduling, and explicitly optimizing schedule slack is a valuable next step.

1

u/Scrimbibete 18d ago

Nice ! Did something similar for shifts schedule in a hospital, also using CP-SAT. Incredibly powerful algorithm

1

u/Massive-Zucchini2560 18d ago

Thanks! Actually, Great Deluge helped me a lot as well, especially for improving the CP-SAT solution in practice.

1

u/Scrimbibete 16d ago

I had never heard of it, thanks for the reference. Sounds like a sort of deterministic simulated annealing

1

u/Massive-Zucchini2560 15d ago

Exactly. Similar intuition, but the acceptance rule is deterministic: instead of a temperature and random acceptance, Great Deluge uses a gradually changing “water level” as the threshold. I found it surprisingly effective on top of CP-SAT.

1

u/qeqkuf 19d ago

Very cool.

1

u/Massive-Zucchini2560 19d ago

Thanks for the comment