Cache Project Enhanced

Cache Project Enhanced is a command-line cache simulator that analyzes memory traces using either a direct-mapped cache or a set-associative cache with LRU replacement. It converts a simple class assignment into a more practical systems-analysis tool by generating readable reports, CSV exports, and validation-backed simulation results.

What Problem It Solves

Understanding cache behavior is essential in computer architecture, systems programming, and performance engineering. This project helps users inspect how different cache configurations respond to a stream of memory addresses and measure outcomes such as hits, misses, unaligned accesses, and replacement behavior.

Key Features

• Simulates direct-mapped and set-associative caches
• Applies LRU replacement for set-associative mode
• Detects unaligned memory accesses
• Produces both human-readable and CSV reports
• Validates cache configuration inputs
• Includes reusable Python module design instead of a one-file script
• Ships with sample memory traces and unit tests

Tech Stack

• Python 3.10+
• Standard library only
• argparse, csv, dataclasses, math, pathlib, unittest

Project Structure

.
├── data/
│   ├── cache.txt
│   ├── mem1.txt
│   ├── mem2a.txt
│   └── mem3.txt
├── docs/
│   └── project-evaluation.md
├── src/
│   └── cache_simulator.py
├── tests/
│   └── test_cache_simulator.py
├── .gitignore
├── README.md
├── pyproject.toml
└── requirements.txt

How To Run

Install dependencies:

pip install -r requirements.txt

Run a direct-mapped simulation:

python -m src.cache_simulator \
  --type d \
  --cache-size 64 \
  --block-size 16 \
  --memfile data/mem1.txt \
  --output reports/direct_report.txt \
  --csv-output reports/direct_report.csv

Run a set-associative simulation:

python -m src.cache_simulator \
  --type s \
  --cache-size 64 \
  --block-size 16 \
  --nway 2 \
  --memfile data/mem2a.txt \
  --output reports/set_assoc_report.txt \
  --csv-output reports/set_assoc_report.csv

Example Usage

Example console output:

Simulation complete.
Text report: .../reports/direct_report.txt
CSV report: .../reports/direct_report.csv
Hit rate: 75.00%

Why This Project Is Interesting

This project is interesting because it sits at the intersection of systems programming, data representation, and performance analysis. Instead of only producing HIT or MISS, the enhanced version makes the results easier to inspect, compare, and present. It also demonstrates clean refactoring: moving from a basic script into a structured, testable CLI tool.

Future Improvements

• Add visualization of hit and miss trends over time
• Support fully associative caches and FIFO replacement
• Add configurable address width and word size
• Export summary statistics as JSON
• Build a small web UI for interactive experimentation