CacheVis-RV

An interactive desktop platform for learning cache mapping, miss behavior, locality, replacement policies, AMAT, and write policies.

Built with Python and PySide6 for computer architecture education and visual experimentation.

中文说明

Why CacheVis-RV

Cache behavior is easier to understand when addresses, cache lines, evidence, and performance consequences are visible together. CacheVis-RV turns abstract rules into guided, repeatable experiments while keeping the underlying models deterministic and testable.

What you can learn

• How tag, index, and offset bits map an address into a cache.
• Why misses are compulsory, conflict, or capacity misses under the strict 3C model.
• How temporal and spatial locality change cache behavior.
• Where LRU, FIFO, and deterministic Random replacement decisions diverge.
• Why hit rate alone does not determine AMAT or total memory cost.
• How write-through/write-back and allocation choices affect dirty state and traffic.

Eight labs

Group	Lab	Focus
Learn	Address Explorer	Address splitting, mapping, cache contents, and timeline
Learn	Miss Type Lab	Compulsory, conflict, and capacity evidence
Learn	Locality Lab	Temporal/spatial locality and block reuse
Learn	Policy Lab	LRU, FIFO, and deterministic Random comparison
Learn	Performance Lab	AMAT, timing assumptions, sweeps, and trade-offs
Learn	Write Policy Lab	Write propagation, allocation, dirty eviction, and traffic
Classic Tools	Single Experiment	Configurable trace simulation and report export
Classic Tools	Compare Experiment	Side-by-side cache parameter comparison

All eight labs are available. Pages are created lazily and cached so navigation preserves an experiment's state.

Visual tour

Miss Type Lab — strict 3C evidence

Policy Lab — LRU, FIFO, and Random side by side

Performance Lab — hit rate is not AMAT

Write Policy Lab — four synchronized policy lanes

Quick start

Officially verified on Windows 10 and Windows 11. Other platforms have not yet completed formal verification.

git clone https://github.com/Yucheng-art/CacheVis-RV.git
cd CacheVis-RV
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -B .\src\main.py --gui

After setup, the repository-relative helpers are also available:

.\scripts\run_gui.ps1
.\scripts\run_tests.ps1

Example experiments

• Use Address Explorer to follow 0, 4, 8, 0 one step at a time.
• Run the three Miss Type presets and inspect the actual-cache/reference-cache evidence.
• Contrast row-major and column-major matrix access in Locality Lab.
• Find the first divergence among LRU, FIFO, and Random in Policy Lab.
• Run Hit Rate Is Not AMAT and compare timing assumptions in Performance Lab.
• Compare all four write-policy lanes, then separate runtime traffic from final dirty drain.

Architecture

The platform shell owns navigation and lazy page creation. Each teaching lab has its own controller, immutable page state/view models, and PySide6 widget tree. Shared cache behavior lives in a GUI-free core package. Compatibility facades keep the established flat imports working for existing callers.

src/main.py
└── cachevis_rv/
    ├── core/          cache configuration, lines, simulator, policies, statistics
    ├── experiments/   reusable runners, parsing, reporting, and services
    ├── gui/           platform shell, registry, Home, sidebar, and theme
    └── labs/          one independent package per lab

Verification

• 720 unittest tests pass with no skips.
• Windows clean-environment installation and Quick Start are verified.
• Qt offscreen creation/navigation smoke tests pass.
• The real GUI entry reaches the Qt event loop without a traceback.
• Core, controller, view-model, registry, parser, invariants, and platform boundaries are tested.

Run the same suite locally:

.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v

Project structure

.github/             Windows CI and issue forms
docs/                architecture, milestone notes, checklists, and screenshots
scripts/             repository-relative PowerShell launchers
src/                 application, core, experiments, GUI, and lab packages
tests/               unittest regression and boundary tests

Supported scope

CacheVis-RV is an educational, deterministic cache-learning platform. It covers address mapping, 3C miss classification, locality evidence, replacement-policy comparison, analytical performance modeling, and write-policy traffic under the explicit assumptions displayed by each lab.

Current limitations

• It is not a cycle-accurate or RTL simulator.
• It is not a complete memory-hierarchy or industrial performance model.
• The write-policy model does not simulate store buffers, write combining, coherence, memory consistency, energy, or pipeline CPI.
• EXE packaging and formal validation outside Windows 10/11 are not provided.
• Results apply to the selected configuration, trace, and stated assumptions; they do not establish a universally optimal policy.

Project status

CacheVis-RV V3.0 is the current public release. The application exposes eight available labs, and the v3.0.0 release is verified by 720 automated tests. See CHANGELOG.md and the showcase release notes.

Copyright and usage

Copyright © 2026 Yucheng Xu. All rights reserved. The code is source-available for portfolio review, educational evaluation, and demonstration. No standard open-source license is granted. See COPYRIGHT.md and THIRD_PARTY_NOTICES.md.

Author / portfolio note

Designed and implemented by Yucheng Xu as a computer architecture education and software-engineering portfolio project. Responsible security reports should follow SECURITY.md and must not include secrets or personal data.