How I build a university timetable generator

Matheus Garvão — Tue, 29 Apr 2025 14:17:03 +0000

Internship Project: Automatic Timetable Generation System for UniFil

At the beginning of 2023, my advisor challenged me to develop, as an internship project, an automatic timetable generation system for UniFil (https://unifil.br).

Context and Challenges

Unlike many universities, our institution must deal with several peculiarities:

Professors do not have a fixed workload during the day.
There is a list of around 200 courses.
The schedules are renewed every two months with new subjects.
We have a varied number of rooms—from computer labs and robotics rooms to common classrooms—each with its own restrictions and capacities.
Additional internal constraints significantly increase the complexity of the problem.

Initial Research

I started researching existing solutions and found the FET Timetable. However, its documentation and usability were not compatible with our scenario.

Then I discovered OptaPlanner—now known as Timefold Solver—which, with its detailed documentation, allowed me to build my own problem model and develop a customized interface.

First Implementation

Initially, I focused on modeling the problem without including the flexible courses and performed the first tests with default settings. Quickly, I identified that several constraints were implemented inadequately.

To better understand the errors:

I used the ScoreExplanation feature.
Saved debugging info in a JSON file.
Adjusted flaws and re-ran the system — but the timetable was still not fully functional.

Optimization Insight

By revisiting the documentation and studying the chapter on combinatorial optimization in Peter Norvig’s book “Artificial Intelligence”, I realized the need to improve the constraints.

Changes made:

Switched from lists to sets to optimize access time.
Inverted the association: instead of linking professors to courses, each course now holds the set of qualified professors.

Benchmarking and Migration

During benchmarking, I found OptaPlanner was outdated and migrated to Timefold Solver, which improved execution time.

I published my first articles on the topic:

Article 1
Article 2 – page 63

These detail the algorithm and benchmarking process.

Interface & Search Space Challenges

Even with improvements, challenges remained:

Lack of a user-friendly interface — data was entered via JSON.
The search space was extremely large: ~10^820 possibilities.
The generator overly focused on specific preferences.

Strategies to Overcome Challenges

I adopted two strategies:

Reduced the search space by excluding optional courses.
Ran two executions of Timefold:
- One ignoring “soft” constraints (e.g., Friday off, Monday preference).
- Then adjusted results to match those preferences.

Results

With these changes:

In ~6 hours, I generated a viable timetable.
After 5 more hours of tuning, it became production-ready.
A process that normally takes a month was reduced to <12 hours.

Lessons and Future Work

Biggest challenges:

Working with new technologies.
Finding creative solutions independently.

Thanks to the excellent documentation on Timefold, this became manageable.

Next steps:

Improve the system further.
Re-evaluate constraints.
Implement a hyper-heuristic layer on Timefold.

We are currently testing a choice function (developed by another student), which improved execution time by ~20%.

DEV Community: Matheus Garvão