PageInvaders

PageInvaders is a desktop virtual-memory simulator for Operating Systems classes. Page requests move through a TLB, page table, loader, and physical frames while the app shows page hits, faults, dirty evictions, EMAT, fault rate, and thrashing.

The app is intentionally small: Python, pygame, and SQLite from the standard library. There is no web server and no network dependency.

Project Files

File	Purpose
main.py	pygame UI, menu, animation, controls, report overlay, and save action.
engine.py	Headless simulation model: TLB, page table, frames, metrics, scenarios, and FIFO/LRU/OPT replacement strategies.
db.py	SQLite persistence for saved run reports.
requirements.txt	Runtime dependency list.

Generated folders such as build/, dist/, __pycache__/, debug screenshots, and saved reports.db files are not part of the source tree.

Run From Source

python -m pip install -r requirements.txt
python main.py

Build The Executable

python -m pip install "pyinstaller>=6.0"
pyinstaller pageinvaders.spec

The executable is created at dist/PageInvaders.exe. The first saved report creates a reports.db file next to the executable. When running from source, reports.db is created next to db.py.

Controls

Action	Control
Play or pause	On-screen button or Space
Step while paused	On-screen button or Right Arrow
Reset current run	On-screen button
Change speed	Speed button
Toggle TLB	TLB button
Compare algorithms	Run all 3
Open report	Report button after a run completes
Return to menu	Menu button or Esc

Simulation Model

engine.py keeps the simulation independent from pygame. The UI creates an Engine, subscribes to access events through EventBus, and renders the latest model state.

Each access follows this flow:

1. Check the TLB if it is enabled.
2. Read the page-table entry.
3. Serve resident pages as hits.
4. On a fault, use a free frame or ask the active replacement strategy for a victim.
5. Update dirty/reference bits, counters, EMAT, rolling fault rate, and thrashing state.
6. Publish one event for the UI animation and narration.

Replacement strategies:

Algorithm	Victim rule
FIFO	Oldest load_time
LRU	Oldest last_used
OPT	Resident page used furthest in the future

Scenarios

The menu includes built-in teaching scenarios:

Scenario	Purpose
Belady's Anomaly	Shows FIFO faults can increase with more frames.
Textbook Classic	Uses a standard reference string for algorithm comparison.
Thrashing	Tiny physical memory with wide random access.
Locality of Reference	Demonstrates why LRU works well on localized traces.

Saved Reports

The report overlay can save a completed run to SQLite. db.py stores one row in runs and the per-step details in steps. You can inspect the database with any SQLite browser.

Configuration Defaults

Setting	Default
Algorithm	LRU
Pattern	LOCALIZED
Frames	4
Virtual pages	16
Reference length	50
Write probability	0.20
Locality	0.85
TLB	Enabled