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.
A first GUI experience follows this path:
- Choose a Lab from Home or the sidebar.
- Select a preset or provide a trace.
- Load the experiment.
- Use Step or Run All.
- Inspect the available Evidence, Cache State, Statistics, and Timeline views.
This is the common learning workflow, not a promise that every Lab exposes the same controls or the same set of panels.
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.
- 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.
| 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.
The v3.0.0 release was verified with the following environment; these are
release verification facts, not minimum-version requirements.
| Item | Verified with |
|---|---|
| Operating system | Windows 10 / 11 |
| Python | 3.12 |
| PySide6 | 6.11.1 |
| Test runner | unittest |
| GUI validation | Qt offscreen smoke and real event-loop startup |
| 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 --guiAfter setup, the repository-relative helpers are also available:
.\scripts\run_gui.ps1
.\scripts\run_tests.ps1- Launch the application with
--guiorscripts/run_gui.ps1. - Select a Lab from Home or the sidebar.
- Choose a preset or enter a supported trace.
- Load the experiment to start from its defined initial state.
- Use Step for one access or Run All for the remaining accesses.
- Observe the Evidence, Cache State, Statistics, and Timeline views that the selected Lab provides.
Run one sequential experiment with an explicit cache configuration:
.\.venv\Scripts\python.exe -B .\src\main.py --trace sequential --count 16 --cache-size 1024 --block-size 16 --ways 2 --policy LRUCompare associativity on a conflict-oriented trace:
.\.venv\Scripts\python.exe -B .\src\main.py --trace conflict --count 32 --cache-size 1024 --block-size 16 --ways 2 --policy FIFO --compare waysExport the supported CSV and Markdown reports for a single experiment:
.\.venv\Scripts\python.exe -B .\src\main.py --trace sequential --count 16 --export-dir .\outputs\cli-exampleAll options above are provided by the current src/main.py CLI. Run with
--help for the complete argument reference.
- Use Address Explorer to follow
0, 4, 8, 0one 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.
| Version | Product stage | Stable verification baseline |
|---|---|---|
| V1.0 | Cache Simulator | 46 tests |
| V2.0 | Address Visualization | 89 tests |
| V3.0 | Educational Cache Platform | v3.0.0 verification baseline: 720 tests, Skip 0 |
main is the current V3.0 product line, and v3.0.0 is the current formal
release. archive/v2 preserves the V2 history as a historical branch; it is not
the current development branch and was not merged into main. See
VERSION_HISTORY.md for the repository references and
version boundaries.
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.
flowchart TD
Entry["src/main.py"] --> Shell["Platform Shell"]
Shell --> Registry["Lab Registry"]
Registry --> Widget["Independent Lab Widget"]
Widget --> Controller["Lab Controller"]
Controller --> State["Page State / View Models"]
Controller --> Core["GUI-free Core"]
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
- The
v3.0.0verification baseline contains 720unittesttests with no skips. - Windows GitHub Actions CI validates the release baseline with Python 3.12.
- Windows clean-copy installation and the documented 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.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
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.
- 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.
CacheVis-RV V3.0 is the current public release. The application exposes eight
available labs, with a v3.0.0 verification baseline of 720 automated tests and no skips. See
CHANGELOG.md and the
V3.0 release notes.
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.
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.