A generalized university course timetable scheduling solver powered by constraint optimization.
A solved timetable in the desktop app. See the visual walkthrough for every screen.
ChronoSolve generates conflict-free timetables for educational institutions. Unlike rigid, institution-specific tools, it treats every scheduling detail; days, time slots, rooms, teacher preferences, etc; as configurable input rather than hardcoded assumptions.
Works for any level of education. Because days, slots, rooms, student groups, and constraints are all configuration (never hardcoded), the same solver schedules schools (K-12), pre-university and junior colleges, colleges, universities, and coaching or training centers. A "student group" is any cohort that attends classes together (a class, section, batch, or year), so any institution that schedules groups against teachers, rooms, and time slots is in scope.
The one case it does not model is fully individualized per-student timetables, where every student picks a unique combination of electives and needs a personal schedule. ChronoSolve schedules at the group level, which fits the vast majority of schools and university programs.
Core solver: Google OR-Tools CP-SAT - a production-grade constraint programming solver that finds optimal (or near-optimal) schedules while respecting hard constraints and maximizing soft preferences.
Hard constraints (must be satisfied):
- No teacher/student group/room clashes
- Required teaching hours per subject
- Teacher and group availability
- Consecutive hours for lab sessions
Soft constraints (optimized with configurable weights):
- Minimize student gaps between classes
- Respect teacher time preferences (morning slots, free days, leave early)
- Spread subjects across the week
- Balance teacher workload
| Component | Technology |
|---|---|
| Solver | Python 3.14+ · Google OR-Tools CP-SAT |
| Data models | Pydantic v2 |
| Input format | YAML / JSON |
| CLI | Typer |
| Desktop app | Tauri v2 · React · TypeScript · Tailwind CSS |
| Package manager | uv |
uv sync
# Print an example input to start from
uv run timetable template > my_school.yaml
# Validate without solving
uv run timetable validate my_school.yaml
# Solve and print per-group timetables (also: --format json|csv, -o out.json)
uv run timetable solve my_school.yaml --time-limit 60
# Score an existing schedule against the constraints
uv run timetable score my_school.yaml result.json
# Run the sidecar API server (prints PORT=<n> for the desktop app)
uv run python -m timetable_solver.serverLibrary usage:
from timetable_solver import load_problem, solve, score_schedule
problem = load_problem("my_school.yaml")
result = solve(problem, time_limit=60) # refine=True adds annealing
print(result.status, result.quality_score)Tests: uv run pytest tests/ --cov=src
A real-world example lives in examples/nmamit_cse_sem3.yaml (a 4-section CSE semester converted from a legacy generator), with matching CSVs under examples/import/ for the desktop app's import wizard.
With just installed, common workflows are one command (recipes wrap scripts/workflow.sh):
just check # every CI quality gate locally (ruff, pytest, eslint, vitest, clippy)
just solve # CLI smoke: template -> validate -> solve
just web # browser dev mode: sidecar + Vite wired together
just dev # full desktop app (Tauri)Prebuilt .dmg builds are attached to each GitHub release (Apple Silicon / aarch64). Releases are automated: merges to main accumulate into a "Release" pull request that, when merged, bumps the version, updates the changelog, and publishes a GitHub release with a freshly built .dmg attached - no manual tagging or publish step. To install:
- Download
ChronoSolve_<version>_aarch64.dmg, open it, and drag ChronoSolve into your Applications folder. - The build is not signed or notarized, so macOS Gatekeeper blocks the first launch. Clear it once, either way:
- Control-click (right-click) ChronoSolve in Applications, choose Open, then Open again in the dialog. macOS remembers the choice.
- Or in Terminal:
xattr -dr com.apple.quarantine /Applications/ChronoSolve.app
The first launch can take up to a minute while macOS validates the unsigned libraries bundled with the solver; later launches start in a few seconds. The app runs entirely on your machine - the solver is bundled in, nothing is uploaded.
Requires Node 20+, Rust (via rustup), and uv on PATH - the app spawns the solver sidecar with uv run and discovers its port automatically:
cd app
npm install
npm run tauri dev # opens the ChronoSolve window
npm run test # frontend unit tests (Vitest)Prefer pictures? The visual walkthrough has a screenshot of every screen.
The left sidebar follows the workflow top to bottom:
- Dashboard - your home base. Load the worked example, open a YAML/JSON file, or import CSV to get started. Shows live entity counts and a Data -> Constraints -> Schedule progress pipeline.
- Data - edit courses, instructors, student groups, and rooms as tables, or switch to the YAML view to edit the raw definition. Import entities from CSV with column auto-matching.
- Constraints - toggle the hard rules every timetable must satisfy and set how much each soft preference matters, with quick presets and a live impact preview. Author advanced rules (breaks, allowed slots, daily caps, sequencing, room policies) from plain-language templates.
- Scheduler - run the solver and watch it converge live (best result and solutions-found stream in); cancel any time. If no valid timetable exists, the clashing rules are listed with a one-click "Soften to preference" escape hatch, so a re-run can trade that rule off instead of failing.
- Timetable - view the generated schedule by class, teacher, or room (or a master overview) and filter by type/department/semester - then edit it directly: drag sessions to new slots, reassign rooms, and lock what must stay. Conflicts flag instantly and the quality score re-prices as you edit; apply your edits into the problem, undo/redo any step, or re-run the scheduler around your locks to rebuild everything else.
A ⌘K command palette and keyboard shortcuts drive every action, and the whole app supports light and dark themes. New here? On first launch a welcome card offers a quick guided tour or a self-guided look around, and you can reopen either later from the Help menu - replay the tour, or press ⌘/ to toggle ambient hints that label whatever is on screen.
ChronoSolve grew out of an earlier final-year engineering project I built with my team. That version produced working timetables, but under a deadline we never got to properly tackle the hard part: timetabling is an NP-hard constraint problem, and our solution fit our own college's case rather than the general one.
ChronoSolve is the rethink. Rather than hardcoding one institution's rules, it treats every detail - days, slots, rooms, student groups, and the constraints themselves - as configuration, and hands the optimization to a proven CP-SAT solver instead of a hand-rolled heuristic. The aim is a single tool that adapts to the widest range of schools, colleges, and universities, instead of being rebuilt for each new timetable.