MU Spartans LogoTimetable Engine

Constraint-based timetabling system for Manchester University

Welcome to the Timetable Engine

This system helps you generate optimal timetables for Manchester University using constraint-based optimization.

👥

Multi-User System

This system supports multiple simultaneous users. Each user gets their own isolated workspace with separate data files and solutions.

💡 Your session and data are automatically managed. Sessions expire after 24 hours of inactivity.

1🧩 Workbook Editor

v2.3 · April 2026 — Start by editing your Excel workbook (.xlsx) in the Workbook Editor (grid + dropdowns), 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.

2📁 Data Upload

Upload a single Excel workbook (.xlsx) (recommended) or use the CSV/YAML multi-file route.

3⚙️ Configure

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).

4🧮 Solve

Run the optimization solver to find the best timetable that satisfies all constraints while minimizing penalties.

5📊 Results

Examine the generated timetable, view reports, and export results in various formats (CSV, HTML, ICS calendar).

Manchester University Logo

🧩 Workbook Editor

Edit your timetable workbook in a spreadsheet-style grid (sections, instructors, rooms, timeslots, buildings, patterns, cohorts, weights, and more).

1How 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.

2Start 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.

📁 Data Upload

Release v2.3 · April 2026

Load your timetable data in one of these ways:

📊 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

No Excel workbook selected

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

No files selected

⚙️ Configuration

Configure constraint weights and solver parameters to customize the optimization process.

Suggested default: Keep the constraint weights as-is unless you have a specific scheduling issue you’re trying to correct.

1Constraint Weights

Recommended: Use the default weights. Adjust only when you’re iterating on a specific trade-off.

Penalty weight for student/cohort conflicts
Penalty weight for instructor daily gaps
Penalty weight for late slot assignments
Penalty weight for walking time between classes
Penalty weight for unequal instructor workload distribution
Penalty weight for instructor classes spread across days
Penalty weight for instructor classes clustered together

2Solver Parameters

Timeslots after this minute are considered "late" (e.g., 990 = 4:30 PM)
Maximum time to spend solving
Seed for reproducible results
Number of parallel workers for solving

3Time 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:

Debug Info: Loading...

🧮 Generate Timetable

Run the optimization solver to generate your timetable.

1Data Validation

Please upload and validate data first

2Configuration

Using default configuration

3Solve

💡 Tip: The solver will try to find the best timetable that satisfies all hard constraints while minimizing soft constraint violations. This may take a few minutes for complex problems.

📊 Results

Review your generated timetable and export results.

No results yet. Please generate a timetable first.

❓ Help & Documentation

1Getting Started

Follow these steps to generate your first timetable:

  1. Upload your data using the Data Upload tab
    • RECOMMENDED: Single Excel workbook (.xlsx) with multiple sheets
    • Alternative: Multiple CSV files (original method)
  2. Optionally use the Workbook Editor to edit your workbook in the browser (see Help → Workbook Editor)
  3. Go to Configure (recommended: keep the default constraint weights)
  4. Run the solver in the Solve tab
  5. Review and export results in the Results tab

2Excel workbook (.xlsx) upload (RECOMMENDED)

Easy method: Upload one Excel workbook (.xlsx) containing all your data in separate sheets.

How to Use:

  1. Download the Blank Workbook or Example Workbook from the Workbook Editor tab
  2. Fill in each sheet with your data:
    • Required sheets: sections, instructors, rooms, timeslots, config
    • Optional sheets: patterns, weights, buildings, cohorts, section_groups
  3. Save your Excel workbook (.xlsx)
  4. Upload it using the Choose Excel workbook button on the Data Upload tab

Benefits: All data in one file, easier to manage, patterns and weights included, less prone to errors.

3Workbook 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): Loads an Excel workbook (.xlsx) from your computer into the editor (same upload as the Data tab).

Apply to session for Solve: Asks if you want to download an Excel workbook (.xlsx) backup, then sends the grid to the server and opens the Solve tab to run the solver. 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.

4CSV Format Guide (Alternative Method)

You can also upload individual CSV files if you prefer the original method.

Sections CSV Format

section_id,course_code,title,instructor_id,expected_enrollment,duration_minutes,allowed_patterns,must_share_time_with,must_not_overlap_with,required_features,min_room_capacity,pinned_timeslot_id,pinned_room_id,cohorts,weight_student_conflict CHEM-105-A,CHEM-105,Introduction to Inorganic Chemistry,Salupo-Bryant,40,50,MWF50,,,,,,,,2 CHEM-105R-A,CHEM-105,Introduction to Inorganic Chemistry Recitation,Salupo-Bryant,40,50,W75|F75,,,,,,,,2 CHEM-105L-A,CHEM-105L,Introduction to Inorganic Chemistry Lab,DavisM,16,110,T110|R110,,,LAB,,,,,2

Instructors CSV Format

instructor_id,name,unavailable_timeslot_ids,max_daily_minutes,max_days_per_week,preferred_buildings,avoid_late_slots Osborne,Jeff Osborne,,540,5,SCIC,FALSE DavisK,Kathy Davis,,540,5,SCIC,FALSE DavisM,Matt Davis,,540,5,SCIC,FALSE

Rooms CSV Format

room_id,building,capacity,features SCIC101,SCIC,40,PROJECTOR SCIC103,SCIC,40,PROJECTOR SCIC141,SCIC,40,PROJECTOR

Timeslots CSV Format

timeslot_id,day_pattern,start_min,end_min,label MWF_08:00_08:50,MWF,480,530,Monday/Wednesday/Friday 08:00-08:50 MWF_09:00_09:50,MWF,540,590,Monday/Wednesday/Friday 09:00-09:50 MWF_10:00_10:50,MWF,600,650,Monday/Wednesday/Friday 10:00-10:50

Section Groups CSV Format

group_id,name,members,type BIOL-CHEM-CORE_FY,Biol-Chem Fys,CHEM-111|CHEM-111L|MATH-121,cannot_overlap BIOL-CHEM-CORE_2Y,Biol-Chem 2nd Yrs,CHEM-311|CHEM-311L|CHEM-311R|PHYS-111|PHYS-111R|PHYS-111L,cannot_overlap

Cohorts CSV Format

cohort_id,name,required_section_groups BIOL-CHEM-FY,Biology-Chemistry FY,BIOL-CHEM-CORE_FY BIOL-CHEM-2YR,Biology-Chemistry 2nd Yr,BIOL-CHEM-CORE_2Y

5Constraint Types

Hard Constraints (Must be satisfied)

Section Assignment: Each section must be assigned exactly once

Room Exclusivity: No two sections can occupy the same room at the same time

Instructor Exclusivity: No instructor can teach two sections simultaneously

Room Capacity: Room capacity must meet section requirements

Room Features: Room must have all required features

Pinned Events: Sections with pinned timeslots/rooms must be fixed

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

6Troubleshooting

Common Issues

Infeasible Problem: Check for conflicting constraints or insufficient resources

No Valid Assignments: Verify room capacity and feature requirements

Poor Quality Solution: Adjust constraint weights to prioritize important factors

Performance Tips

Use appropriate time limits based on problem size

Start with simpler constraints and add complexity gradually

Use pinned assignments for critical sections

7API Reference

For programmatic access, use the REST API endpoints:

POST /solve - Start a new solve GET /solutions/{id} - Get solution details GET /solutions/{id}/view/{type} - Get HTML view GET /solutions - List all solutions

ℹ️ About the Timetable Engine

1Software Information

Version: 2.3 (Excel workbook + Workbook Editor)

Date: April 2026

Developers: Jeff Osborne and Cursor AI

Location: Manchester University, North Manchester, Indiana, USA

2Algorithm & 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

3Key Features

Excel workbook (.xlsx): Upload all data in a single Excel workbook (.xlsx) with multiple sheets

Workbook Editor: Edit the full multi-sheet workbook in the browser; draft stored locally, then apply to the server for solve

Multi-User Support: Up to 20 simultaneous users with isolated workspaces

Session Management: Automatic session tracking with 24-hour inactivity timeout

Real-time Optimization: Generates timetables in seconds to minutes

Flexible Constraints: Supports complex scheduling rules and preferences

Interactive Interface: Web-based GUI for easy data upload and result visualization

Multiple export formats: Excel workbook (.xlsx), CSV, and PDF for weekly schedules

Dataset Import/Export: Save and restore complete datasets as ZIP files

Solve Queue: Manages concurrent solver runs to optimize server resources

Scalable Architecture: Handles small to large-scale scheduling problems

Constraint Validation: Ensures data consistency before optimization

4Technical Stack

Backend: Python with FastAPI framework

Solver: Google OR-Tools CP-SAT

Frontend: HTML5, CSS3, JavaScript (ES6+)

Database: SQLite for solution persistence

Server: Uvicorn ASGI server with Apache reverse proxy

5Contact & Support

For questions, bug reports, or feature requests, please contact Jeff Osborne.

Email: jposborne@manchester.edu