Timetable Engine
Constraint-based timetabling system for Manchester University
Welcome to the Timetable Engine
This system helps you generate timetables for Manchester University using constraint-based optimization.
Use the numbered tabs above to prepare your data, configure the solver, generate a timetable, and export results. Most users start with the Workbook Editor or Data Upload tab.
This system supports multiple simultaneous users. Each user gets an isolated workspace with separate data files and solutions. Sessions expire after 6 hours of inactivity.
v2.4 · July 2026
1 Workbook Editor
Edit your timetable workbook in a spreadsheet-style grid (sections, instructors, rooms, timeslots, buildings, patterns, cohorts, weights, and more).
Getting started
Start by editing your Excel workbook (.xlsx) in the grid below (or download a blank/example workbook), then apply it to your session for solving.
Important: The editor works from a saved draft in your browser. Uploading an Excel workbook (.xlsx) on the Data Upload tab does not automatically replace what’s currently in your editor draft unless you upload/open it from the editor.
Start here
If you already have an Excel workbook (.xlsx), open the editor and use Upload workbook (.xlsx) inside the editor to load it into your draft.
How saving works
Draft (this browser): The editor keeps a saved draft in your browser so you can safely iterate without changing the server session until you’re ready.
Server session: Nothing is used for solving until you click Apply to session for Solve, which sends your current draft to the server session.
Important: Uploading an Excel workbook (.xlsx) on the Data Upload tab does not automatically replace what’s currently in your editor draft.
2 Data Upload
Choose a route
Upload a single Excel workbook (.xlsx) (recommended) or use the CSV/YAML multi-file route.
- Excel workbook (.xlsx) (recommended) — one file with multiple sheets; upload below.
- Workbook Editor — edit your Excel workbook (.xlsx) in the browser (grid + dropdowns); your draft is saved in this browser, then Apply to session for Solve pushes it to the server. (Use the Workbook Editor tab to download or edit drafts.)
- CSV / YAML — classic multi-file upload (Option 2 below).
Option 1: Single Excel workbook (.xlsx) (RECOMMENDED)
Upload one Excel workbook (.xlsx) with multiple sheets (same structure as the downloadable blank/example workbooks).
Note: There is no separate “Validate Data” button here—after a successful upload, validation runs automatically (same checks as the CSV flow). Messages appear below.
Required sheets: sections, instructors, rooms, timeslots, config, patterns, weights
Optional sheets: buildings, cohorts, section_groups
Need a starter Excel workbook? Go to the Workbook Editor tab to download blank/example workbooks and edit your saved draft.
Workbook Editor: Full-screen editor for all sheets. Your work is saved in this browser. Upload an Excel workbook (.xlsx), download an Excel workbook (.xlsx), then Apply to session for Solve (optional backup download first) — you’ll be taken to the Solve tab to generate the timetable.
Option 2: Multiple CSV Files & config
Supported formats: CSV and YAML.
For the CSV route, the system uses the following file formats:
- sections.csv — Course sections with requirements and constraints
- instructors.csv — Instructor information and availability
- rooms.csv — Room capacities and features
- timeslots.csv — Available time slots and patterns
- buildings.csv — Building locations for walking time calculations
- cohorts.csv — Student cohorts and requirements
- section_groups.csv — Section grouping constraints
- config.yaml — System configuration and weights
Required: sections.csv, instructors.csv, rooms.csv, timeslots.csv, config.yaml · Optional: section_groups.csv, buildings.csv, cohorts.csv
3 Configure
Configure constraint weights and solver parameters to customize the optimization process.
Constraint preferences
Set up your constraint preferences and weights. The system supports both hard constraints (must be satisfied) and soft constraints (preferences with penalties).
Recommendation: Most users should keep the default constraint weights. Only change weights if you have a specific outcome you’re trying to push (e.g., reduce student conflicts at the cost of more instructor gaps).
Constraint Weights
Recommended: Use the default weights. Adjust only when you’re iterating on a specific trade-off.
Solver Parameters
Time Patterns
Time patterns are typically defined in your Excel workbook (.xlsx) (the patterns sheet, or via the Workbook Editor). The server stores the active session settings in config.yaml, and the patterns currently loaded for this session are displayed below:
4 Solve
Run the optimization solver to find the best timetable that satisfies all constraints while minimizing penalties.
Data Validation
Configuration
Solve
5 Results
Review your generated timetable and export results.
Your timetable
Examine the generated timetable, view the weekly schedule grid, and export results as Excel workbook (.xlsx), CSV, or PDF.
Help & Documentation
Release v2.4 · July 2026
Sections below follow the numbered tabs at the top of the page (Workbook Editor through Results). Use the left blue bar to tell help topics apart from the circled tab numbers in the navigation bar.
Getting started
Typical workflow:
- Workbook Editor — edit your data in the browser, or use Data Upload to load an Excel workbook or CSV files
- Configure — adjust weights and solver settings (defaults are fine for most users)
- Solve — run the optimizer (Cancel Solve stops a long run)
- Results — review the schedule and export Excel, CSV, or PDF
Sessions: Each browser gets an isolated workspace. Sessions expire after 6 hours of inactivity.
Workbook Editor
What it is: A full-screen, in-browser editor for the same multi-sheet Excel workbook (.xlsx) you use outside the app (sections, instructors, rooms, timeslots, patterns, weights, and more). Edit in a spreadsheet-style grid with dropdowns and validation.
Local draft: The grid is saved automatically in this browser (localStorage). Clearing site data removes it—use Download workbook (.xlsx) for a backup.
Upload workbook (.xlsx): Use the editor’s own upload button to load a file from your computer into the grid.
Important: Uploading an Excel workbook (.xlsx) on the Data Upload tab does not automatically replace what’s currently in your editor draft. To load a file into the editor, upload from within the Workbook Editor.
Apply to session for Solve: Offers an optional backup download, then sends the grid to the server and opens the Solve tab. Fix validation errors first if the server rejects the apply.
Validation: Errors and warnings appear while you edit.
Where to open it: Go to the Workbook Editor tab and click Open Workbook Editor. Download Blank or Example workbooks from the same page.
Data Upload
Option 1: Excel workbook (.xlsx) — recommended
Upload one Excel workbook (.xlsx) containing all your data in separate sheets.
- Download the Blank Workbook or Example Workbook from the Workbook Editor tab
- Fill in each sheet:
- Required sheets: sections, instructors, rooms, timeslots, config, patterns, weights
- Optional sheets: buildings, cohorts, section_groups
- Save your workbook and upload with 1st Choose Excel workbook on the Data Upload tab
Validation: Runs automatically after a successful upload.
Option 2: CSV / YAML files
- 1st Choose Files — select CSV/YAML files
- 2nd Upload Files — send them to your session
- 3rd Validate Data — run validation before solving
Required files: sections.csv, instructors.csv, rooms.csv, timeslots.csv, config.yaml
Optional files: buildings.csv, cohorts.csv, section_groups.csv
Pattern rule: Each section’s duration_minutes must match its allowed_patterns entry (e.g. MWF50 → 50 minutes, TR75 → 75 minutes).
Sections CSV format
Instructors CSV format
Rooms CSV format
Timeslots CSV format
Section groups CSV format
Cohorts CSV format
Configure
Set constraint weights, solver time limit, random seed, and review loaded time patterns. Defaults are recommended unless you are tuning a specific trade-off.
Hard constraints (must be satisfied)
Section assignment: Each section must be assigned exactly once
Room exclusivity: No two sections can use the same room during overlapping clock time
Instructor exclusivity: No instructor can teach two overlapping sections
Room capacity: Room capacity must meet section requirements
Room features: Room must have all required features
Pinned assignments: Pinned timeslots or rooms must be honored (impossible pins make the problem infeasible)
Soft constraints (preferences with penalties)
Student conflicts: Minimize overlapping required sections for cohorts
Instructor gaps: Minimize idle time between classes
Late slots: Avoid late time slots for instructors who prefer not to teach late
Walking time: Minimize walking distance between consecutive classes
Fairness: Distribute undesirable slots fairly among instructors
Spread / cluster: Balance how instructor classes are spread or clustered across the week
Solve
Start the optimizer after your data is loaded and validated. The Solve page shows Data Validation and Configuration status before you run.
Long runs can be stopped with Cancel Solve. Set the solver time limit on the Configure tab for larger problems.
Tip: The solver finds the best timetable that satisfies hard constraints while minimizing soft-constraint penalties. Complex problems may take several minutes.
Results
View assignment metrics and a weekly calendar-style schedule grid.
When the solver reports INFEASIBLE, the Results view includes a diagnostic conflict analysis with suggested fixes.
Export:
- Excel workbook (.xlsx) — assignment table
- CSV — assignment table
- PDF — rendered weekly schedule grid
Troubleshooting
Common issues
INFEASIBLE: Open the Results tab and read the diagnostic panel.
No valid assignments for a section: Check room capacity, features, instructor availability, and allowed_patterns vs timeslot lengths.
Duration / pattern mismatch: TR75 needs duration_minutes=75; MWF50 needs 50 minutes on MWF slots.
Impossible pin: A pin that cannot be satisfied makes the model infeasible.
Poor quality solution: Adjust weights on the Configure tab.
Editor vs upload confusion: Data Upload does not replace your Workbook Editor draft.
Performance tips
Start with simpler data and add constraints gradually
Use pinned assignments only when the pin is definitely achievable
API reference
For programmatic access, all routes are under the /timetable prefix. Your session cookie is required for most endpoints.
About the Timetable Engine
Software information
Version: 2.4
Date: July 2026
Developers: Jeff Osborne and Cursor AI
Location: Manchester University, North Manchester, Indiana, USA
Algorithm & design
CP-SAT Solver: Google's OR-Tools Constraint Programming SAT solver for optimal solutions
Multi-Objective Optimization: Balances multiple competing constraints and preferences
Hard Constraints: Must be satisfied (instructor conflicts, room capacity, time overlaps)
Soft Constraints: Optimized with penalty weights (preferences, gaps, late slots)
Integer Linear Programming: Converts scheduling problems into mathematical optimization
Key features
Excel workbook (.xlsx): Upload all timetable data in one file with multiple sheets (recommended)
Workbook Editor: Edit the full multi-sheet workbook in the browser; your draft is saved locally in this browser until you apply it to the server
CSV / YAML upload: Alternative multi-file route for sections, instructors, rooms, timeslots, and config
Blank & example workbooks: Download starter workbooks from the Workbook Editor tab
Data validation: Checks your data before solving (automatic after Excel upload; explicit step for CSV)
Configure tab: Adjust constraint weights, solver time limit, random seed, and view loaded time patterns
Multi-user sessions: Each browser session gets an isolated workspace with separate uploads and solutions
Session timeout: Sessions expire after 6 hours of inactivity
Solve cancellation: Long-running solves can be cancelled from the Solve tab
Infeasibility diagnostics: When no valid timetable exists, the Results view explains likely conflicts and data issues
Weekly schedule view: Visual calendar-style grid of the solved timetable
Export results: Excel workbook (.xlsx), CSV, and PDF (schedule grid) from the Results tab
Help tab: Step-by-step guidance and CSV column format reference
Technical stack
Backend: Python 3.12 with FastAPI
Solver: Google OR-Tools CP-SAT
Frontend: HTML5, CSS3, JavaScript (ES6+)
Excel I/O: openpyxl for workbook read/write
PDF export: Playwright (server-side rendering)
Session storage: Per-session directories under uploads/; solutions kept in memory for the active session
Server: Uvicorn on loopback, with Apache reverse proxy
Contact & support
For questions, bug reports, or feature requests, please contact Jeff Osborne.
Email: jposborne@manchester.edu