AlgoLab

A desktop application built with Python and Pygame for visualizing data structures and algorithms.

Each operation is presented as a step-by-step, pausable, rewindable animation, with a live explanation of what is happening. AlgoLab was developed as an educational companion for a Data Structures and Algorithms course.

📸 Screenshots

Main Menu - Pick any of the nine topics to open its dedicated visualizer.

Stack - Push, pop, and peek animated step by step, with a live TOP pointer.

Queue - Enqueue and dequeue animated with FRONT and REAR pointers.

Linked List - Insert and delete operations, with HEAD and the algorithm's temporary PREVIOUS / CURRENT / NEW pointers shown as they move.

Binary Search Tree - Insert, search, delete, and traversals, rendered as a live tree diagram.

Heap - Min/Max heap operations shown as both a tree and its underlying array, side by side.

Graph - Build a custom directed/undirected, weighted/unweighted graph and run BFS, DFS, Dijkstra, or Bellman-Ford on it.

Sorting - Merge Sort visualized as an animated bar chart. Bubble, Selection, Insertion, Quick, and Heap Sort are also available on the same screen.

Sorting (race mode) - Race mode between Quick Sort and Merge Sort

Hash Table - Separate chaining collision resolution with a live load factor bar. Linear probing, quadratic probing, and double hashing are also supported.

Asymptotic Notation - Compare Big-O growth curves from O(1) to O(n^n) with an adjustable input size.

📚 Topics

• Asymptotic Notation: Complexity graphs with adjustable inputs
• Linked Lists: Insert, delete, search
• Stacks: Push, pop, peek
• Queues: Enqueue, dequeue, peek
• Binary Search Trees: Insert, search, delete, min/max, traversals
• Heaps: Min/Max heaps, insert, peek, extract, heapify
• Graphs: Directed/undirected, weighted/unweighted, BFS, DFS, Dijkstra, Bellman-Ford
• Sorting: Bubble Sort, Insertion Sort, Merge Sort, Quick Sort, Heap Sort
• Hash Tables & Sets: Chaining, probing, double hashing, Set/Map modes, configurable hash functions, collision counting

✨ Features

• Step-by-step, pausable, and rewindable simulations

• Adjustable animation speed

• Live explanations of operations

• Color-coded operations and legends

• Configurable data structure attributes

• Randomize button for every topic

• Per-topic Big-O reference table through the Info button on every topic screen

• Fullscreen, auto-scaled to the machine's native resolution

• Screenshot capture (F12), saved to assets/screenshots/

• Keyboard shortcuts:

  • P Pause/Resume
  • <- / -> Step backward/forward
  • Enter Run the primary action
  • F12 Take a screenshot
  • Esc Quit

⚙️ Getting Started

Requirements

• Python 3.10+
• Pygame

1. Clone the Repository

git clone https://github.com/AmirmasoudCS/AlgoLab.git
cd AlgoLab

2. Create a Virtual Environment

python -m venv .venv

3. Activate the Virtual Environment

Windows:

.venv\Scripts\activate

Linux / macOS:

source .venv/bin/activate

4. Install Dependencies

pip install -r requirements.txt

Run the Application

Run from the source:

python -m algolab.main

Build a standalone application:

AlgoLab can also be packaged as a standalone executable using PyInstaller.

pyinstaller AlgoLab.spec

The packaged application will be available in the dist/ directory.

🏗️ Architecture

Each topic follows the same structure:

model.py        # Data structure and state
operations.py   # Operations performed on the structure
simulation.py   # Step-by-step simulation

Simulations operate on a copy of the model's state and record each intermediate state as an immutable snapshot. The real model is only updated when the simulation completes.

This allows operations to be paused, replayed, rewound, and committed without modifying the actual data structure during the animation.

Randomize actions bypass the simulation layer and use the data structure's normal operations to produce an immediate state.

📁 Project Structure

📁 
├── 📁 assets
│   ├── 📁 screenshots
│   │   ├── 🖼️ asymptotic.png
│   │   ├── 🖼️ bst.png
│   │   ├── 🖼️ graph.png
│   │   ├── 🖼️ hash_chaing.png
│   │   ├── 🖼️ heap.png
│   │   ├── 🖼️ linked_list.png
│   │   ├── 🖼️ main_menu.png
│   │   ├── 🖼️ merge_sort.png
│   │   ├── 🖼️ queue.png
│   │   └── 🖼️ stack.png
│   ├── 📄 icon.ico
│   └── 🖼️ icon.png
├── 📁 config
│   └── ⚙️ config.toml
├── 📁 log
├── 📁 src
│   └── 📁 algolab
│       ├── 📁 core
│       │   ├── 🐍 __init__.py
│       │   ├── 🐍 application.py
│       │   └── 🐍 configuration.py
│       ├── 📁 simulation
│       │   ├── 🐍 __init__.py
│       │   ├── 🐍 events.py
│       │   ├── 🐍 history.py
│       │   ├── 🐍 simulator.py
│       │   └── 🐍 state.py
│       ├── 📁 topics
│       │   ├── 📁 asymptotic
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 complexity.py
│       │   │   ├── 🐍 model.py
│       │   │   └── 🐍 visualizer.py
│       │   ├── 📁 bst
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 graph
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 hash_table
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 heap
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 linked_list
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 queue
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 sorting
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   ├── 📁 stack
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 model.py
│       │   │   ├── 🐍 operations.py
│       │   │   └── 🐍 simulation.py
│       │   └── 🐍 __init__.py
│       ├── 📁 ui
│       │   ├── 📁 components
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 button.py
│       │   │   ├── 🐍 checkbox.py
│       │   │   ├── 🐍 info_panel.py
│       │   │   ├── 🐍 numeric_input.py
│       │   │   ├── 🐍 radio_button.py
│       │   │   └── 🐍 surface.py
│       │   ├── 📁 screens
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 asymptotic.py
│       │   │   ├── 🐍 bst.py
│       │   │   ├── 🐍 graph.py
│       │   │   ├── 🐍 hash_table.py
│       │   │   ├── 🐍 heap.py
│       │   │   ├── 🐍 linked_list.py
│       │   │   ├── 🐍 main_menu.py
│       │   │   ├── 🐍 queue.py
│       │   │   ├── 🐍 screen.py
│       │   │   ├── 🐍 screen_manager.py
│       │   │   ├── 🐍 sorting.py
│       │   │   └── 🐍 stack.py
│       │   ├── 🐍 __init__.py
│       │   └── 🐍 theme.py
│       ├── 📁 visualization
│       │   ├── 📁 graph
│       │   │   ├── 🐍 __init__.py
│       │   │   ├── 🐍 bounds.py
│       │   │   ├── 🐍 coordinate_system.py
│       │   │   ├── 🐍 curve.py
│       │   │   ├── 🐍 layout.py
│       │   │   ├── 🐍 renderer.py
│       │   │   └── 🐍 scaling.py
│       │   └── 🐍 __init__.py
│       ├── 🐍 __init__.py
│       └── 🐍 main.py
├── 📁 tests
│   ├── 📁 core
│   │   ├── 🐍 __init__.py
│   │   └── 🐍 test_configuration.py
│   ├── 📁 simulation
│   │   ├── 🐍 __init__.py
│   │   ├── 🐍 test_events.py
│   │   ├── 🐍 test_history.py
│   │   ├── 🐍 test_simulator.py
│   │   └── 🐍 test_state.py
│   ├── 📁 topics
│   │   ├── 📁 asymptotic
│   │   │   ├── 🐍 __init__.py
│   │   │   ├── 🐍 test_complexity.py
│   │   │   ├── 🐍 test_model.py
│   │   │   └── 🐍 test_visualizer.py
│   │   ├── 📁 bst
│   │   │   ├── 🐍 test_bst_model.py
│   │   │   ├── 🐍 test_bst_operations.py
│   │   │   └── 🐍 test_bst_simulation.py
│   │   ├── 📁 heap
│   │   │   ├── 🐍 test_heap_model.py
│   │   │   ├── 🐍 test_heap_operations.py
│   │   │   └── 🐍 test_heap_simulation.py
│   │   ├── 📁 linked_list
│   │   │   ├── 🐍 test_linked_list_model.py
│   │   │   ├── 🐍 test_operations.py
│   │   │   └── 🐍 test_simulation.py
│   │   ├── 📁 queue
│   │   │   ├── 🐍 test_queue_model.py
│   │   │   ├── 🐍 test_queue_operations.py
│   │   │   └── 🐍 test_queue_simulation.py
│   │   ├── 📁 stack
│   │   │   ├── 🐍 test_stack_model.py
│   │   │   ├── 🐍 test_stack_operations.py
│   │   │   └── 🐍 test_stack_simulation.py
│   │   └── 🐍 __init__.py
│   ├── 📁 ui
│   │   ├── 📁 compontets
│   │   │   ├── 🐍 checkbox.py
│   │   │   └── 🐍 radio_button.py
│   │   ├── 📁 screens
│   │   │   ├── 🐍 __init__.py
│   │   │   ├── 🐍 test_asymptotic.py
│   │   │   ├── 🐍 test_main_menu.py
│   │   │   ├── 🐍 test_screen.py
│   │   │   └── 🐍 test_screen_manager.py
│   │   └── 🐍 __init__.py
│   ├── 📁 visualization
│   │   ├── 📁 graph
│   │   │   ├── 🐍 __init__.py
│   │   │   ├── 🐍 test_bounds.py
│   │   │   ├── 🐍 test_coordinate_system.py
│   │   │   ├── 🐍 test_curve.py
│   │   │   ├── 🐍 test_layout.py
│   │   │   └── 🐍 test_scaling.py
│   │   └── 🐍 __init__.py
│   └── 🐍 __init__.py
├── 📄 AlgoLab.spec
├── ⚖️ LICENSE
├── ⚙️ pyproject.toml
├── 📘 README.md
├── 📝 requirements.txt
└── 🐍 smoke_test.py

Generated using Tree Printer

🧪 Testing

AlgoLab uses pytest for automated testing.

pytest

Tests cover the core logic, simulation system, data structure operations, UI components, and visualization utilities.

⚠️ Known Limitations

• BST Randomization can produce highly skewed trees depending on insertion order.
• Heap Type Switching rebuilds the heap when switching between Min and Max modes.
• Hash Tables do not automatically resize when an open-addressing table becomes full.
• Queue's dequeue is O(n) in this implementation (list.pop(0)), not the textbook O(1). A deque- or linked-list-backed queue would achieve O(1).

⚖️ License

This project is licensed under the MIT License.