Skip to content

README.md

Latest commit

 

History

History
76 lines (56 loc) · 4.25 KB

README.md

File metadata and controls

76 lines (56 loc) · 4.25 KB
title Genetic Algorithm Timetable Generator
emoji 🗓️
colorFrom blue
colorTo indigo
sdk docker
pinned false
app_port 7860

Timetable Generator

This repository contains a Python-based timetable generation system for educational institutes. It leverages a Genetic Algorithm to produce optimized schedules without resource conflicts.

The system features both a desktop GUI built with tkinter and a modern web-based UI built with Gradio, backed by a FastAPI server. It is fully containerized and deployable to cloud platforms like Hugging Face Spaces.

🚀 Features

  • Genetic Algorithm Optimization: Uses evolutionary techniques to resolve complex scheduling constraints.
  • Web UI & API (Gradio + FastAPI): Interactive web interface for managing courses, tracking progress, and downloading schedules.
  • Desktop GUI (Tkinter): Rich desktop application with frame-based navigation, real-time console redirection, and custom styling.
  • Database Integration: SQLite backend for managing courses, teachers, branches, and class frequency requirements.
  • Data Visualization & Export: View generated timetables in a grid format and export directly to Excel with professional formatting.

🧬 Algorithm & Core Data Structures

The application relies on highly optimized data structures to evaluate fitness and resolve scheduling conflicts rapidly.

Advanced Conflict Detection

  • Sets for O(1) Lookups: Set data structures are extensively used to track unique elements and detect double-booking conflicts (teachers, rooms, branches) instantly. This $O(1)$ lookup time is critical for the fitness function, which must evaluate thousands of potential timetables during generation.

Constraint Resolution Engine

  • Max Heap Implementation: A priority queue (implemented via Python's heapq) is used to optimize constraint resolution (fix_overassigned_classes and fix_class_assignments). By processing the most severe constraint violations first, the algorithm makes impactful changes early, leading to much faster convergence.
    • Theoretical impact: Reduces constraint resolution time complexity from $O(m \times n)$ to $O(n \log n + m \log n)$ for $n$ classes and $m$ constraints.

Genetic Operators

  • Tournament Selection: Efficient random sampling to select optimal parent schedules.
  • Crossover & Mutation: Schedule slots are intelligently combined and mutated to explore the solution space effectively while maintaining valid ClassSlot objects.

🖥️ Desktop & Web Interfaces

Web Application (Cloud Ready)

The project includes a frontend.py Gradio application and an app.py FastAPI server. These allow you to generate and view schedules from any browser, making it ideal for cloud deployment.

Tkinter Desktop GUI (modern_timetable_gui.py)

The desktop interface provides a native experience featuring:

  • Visual Design: A modern, card-based layout with consistent typography and color-coded feedback.
  • Console Output Redirection: System logs and algorithm progress are streamed directly to a scrollable widget within the application using a custom StdoutRedirector.
  • Workflow Optimization: Dedicated notebook tabs guide users logically through database setup, relationship configuration, class requirement specification, and timetable generation.

🐳 Docker Support & Deployment

A Dockerfile is provided for fully containerized execution. The setup uses a shell script (run.sh) to concurrently launch the FastAPI backend internally (port 8000) and expose the Gradio frontend externally (port 7860).

Building the Image

docker build -t timetable-generator:latest .

Running the Container

docker run --rm -it -p 7860:7860 -v "$PWD":/app timetable-generator:latest
  • The -v "$PWD":/app flag mounts the current directory so that the SQLite database (timetable.db) persists on your host machine.
  • Access the web interface at http://localhost:7860.

📦 Requirements

All external dependencies are listed in requirements.txt:

  • fastapi & uvicorn (Backend API)
  • gradio (Web Interface)
  • requests (API Communication)
  • pandas & openpyxl (Data Handling & Excel Export)
  • tabulate (CLI Formatting)

All other modules rely solely on the Python standard library.