IITM Slotbook (v2: UniTime wrapper)
A Java application that assigns IITM Electrical Engineering courses to institutional slots and produces evidence-backed explanations for every assignment. Version 2 hands the optimisation to UniTime's course timetabling engine, cpsolver, and keeps the v1 CP-SAT model as an exact reference solver.
Documentation: docs_v2 describes this version; docs_v1 keeps the original CP-SAT version.
What changed from v1
| v1 | v2 |
|---|
| Default solver | OR-Tools CP-SAT | UniTime cpsolver (--solver cpsat still available) |
| Time model | Slot labels, never overlapping | Real IITM meeting times from the official grid; overlaps computed to 5 minutes |
Labs (additional_slot) | Displayed only | Fixed lab meetings that block instructors, conflicts and students |
| Rooms | Displayed only | Hard rule: one course per room at a time |
| Validation | 9 checks | 18 checks, including duplicate or negative preferences and lab clashes |
| Tests | 41 | 52, comparing both solvers on every scenario |
How UniTime compares (from the tests)
Every generated test scenario is solved by both UniTime and the exact CP-SAT solver:
- UniTime matched CP-SAT's proven best in 10 of the 13 scenarios CP-SAT fully solved. The other three were higher by 1, 8 and 4 points. The worst, 15%, is the scenario where 7 instructors share all 18 courses.
- On the 300-student scenario it did better than CP-SAT, 259 vs 261, because CP-SAT ran out of time.
- It found the exact best on all 10 small problems that can be checked exhaustively.
The full table is in the test plan.
Scope
The demonstrator uses an anonymized/mock subset inspired by the January–May 2025 EE slotbook. Course metadata resembles the supplied administrative sheet; student selections, instructor preferences, conflict weights and availability restrictions are synthetic test fixtures. Slot times follow the official grid at https://www.iitm.ac.in/timetable.
The system supports:
- CSV input and validation
- hard course, instructor, room, lab, fixed-slot and allowed-slot constraints
- soft instructor, historical-stability and student-conflict objectives
- UniTime search (construction with conflict-based statistics, hill climbing, great deluge) or exact CP-SAT
- deterministic assignment explanations with rejected alternatives
- JavaFX table view with solver selection, and CSV export
- feasible and deliberately infeasible demonstration datasets
See MANUAL.md for usage and ARCHITECTURE.md for the module flow.
Preference collection portal
The portal/ directory contains a Vercel-ready web application that collects student course rankings and instructor slot penalties in Google Sheets, exports the exact CSV contracts used by this application, optionally invokes a deployed solver API, and publishes the generated slotbook with explanations.
cd portal
npm test
npm run check
The demonstration portal intentionally has no student or instructor authentication. Its admin operations use server-side secrets, and its documentation explains the Google Apps Script and Vercel setup.
Quick start
Requirements: JDK 17+ and Maven 3.9+.
mvn clean test
mvn exec:java -Dexec.args="--input data/feasible --output output/demo"
mvn exec:java -Dexec.args="--input data/feasible --output output/demo --solver cpsat"
mvn javafx:run
For the mid-evaluation showcase, use the deliberately compact scenario in data/demo-showcase:
mvn exec:java -Dexec.args="--input data/demo-showcase --output output/demo-showcase --time-limit 10"
It contains 11 courses, 36 anonymous students and 144 ranked preferences. UniTime reaches objective 9, matching the CP-SAT proven optimum. The checked-in generated result shows one unavoidable low-weight elective overlap while satisfying the fixed-slot, laboratory, protected-pair and room constraints.
Engineering evidence
- Prompt log: CoSTAR prompts, negative prompts, reviews, debugging evidence and acceptance checks.
- Prompt review checklist: the gate applied before accepting AI-generated changes.
- Manual: name, synopsis, options, inputs, outputs, examples and limitations.
- About: the problem, what "explainable" means and data provenance.
- Code walkthrough: the UniTime mapping, the time encoding and the objective equivalence.
- Test plan: automated coverage, solver comparison and manual UI checks.
- Verification record: the results recorded for this version.
- Debugging practice: reproduce-observe-hypothesize-isolate-correct-test-regress-document.
- Two-minute script: presentation-ready system explanation.
- Live-modification practice: small evaluator-style changes and the files they exercise.
- Principles and practices: prompt engineering, debugging, version control and testing.
GitHub Actions runs the complete Maven test suite on every push and pull request.
Licensing
cpsolver is distributed under the GNU Lesser General Public License v3. This project uses it unmodified as a Maven library dependency.
