RING-5 Documentation

Welcome to the RING-5 documentation! This wiki provides comprehensive guides for using and developing with RING-5, a modern Python-based analysis and visualization tool for gem5 simulator output.

Getting Started

Quick Start Guide - Get up and running in 5 minutes
Installation - Detailed installation instructions
First Analysis - Your first gem5 analysis walkthrough

User Guides

Web Interface Guide - Using the Streamlit dashboard
Parsing gem5 Stats - Complete parsing workflow
Data Transformations - Using shapers and pipelines
Creating Plots - Visualization guide
LaTeX Export Guide - Publication-quality export (NEW!)
Portfolio Management - Saving and sharing analyses

Plot Types

Bar Charts - Single and grouped bar charts
Line Plots - Time-series and trend analysis
Scatter Plots - Correlation and distribution
Histogram Plots - Distribution visualization
Grouped Stacked Bars - Complex comparisons

Developer Guides

Architecture Overview - System design and patterns
Development Setup - Setting up your dev environment
Adding New Plot Types - Extending visualization
Adding New Shapers - Custom data transformations
Testing Guide - Writing and running tests
AI Agent Setup - Using AI assistants for development

API Reference

Parsing API - Parse service and scanner
Plotting API - Plot factory and renderers
Shaper API - Data transformation interface
Backend Facade - Main API entry point

Advanced Topics

Pattern Aggregation - Handling repeated variables
Async Parsing - Parallel processing internals
Type System - gem5 variable types
Performance Optimization - Tips for large datasets
Debugging - Troubleshooting common issues

Contributing

Contributing Guide - How to contribute
Code Style - Conventions and standards
Pull Request Process - Submitting changes
Release Process - Version management

Quick Links

I want to…	Go to
Install RING-5	Installation
Parse gem5 stats	Parsing Guide
Create a plot	Creating Plots
Transform data	Data Transformations
Add a feature	Development Setup
Report a bug	GitHub Issues
Understand the architecture	Architecture Overview
Use with AI assistants	AI Agent Setup

What is RING-5?

RING-5 is Reproducible Instrumentation for Numerical Graphics for gem5. It provides:

Interactive Web UI - No-code analysis with Streamlit
High-Performance Parsing - Async parallel processing
Flexible Transformations - Pipeline-based data processing
Publication-Quality Plots - Interactive Plotly visualizations
Portfolio Management - Save and restore complete analyses

Key Features

Async-First Architecture - Efficient parallel processing
Strongly Typed - mypy strict mode, type hints everywhere
Test-Driven - 653+ tests, 77% coverage
Layered Design - Clean separation: Data → Domain → Presentation
Extensible - Factory patterns for plots and transformations

Documentation Format

This documentation follows these conventions:

Code examples are complete and runnable
Type hints are shown in Python code
Commands are prefixed with $ for terminal
File paths use Unix conventions (/path/to/file)
Links connect related topics

Learning Path

For Users

Start with Quick Start Guide
Follow First Analysis tutorial
Explore Web Interface Guide
Learn Data Transformations
Master Creating Plots

For Developers

For Researchers

Review Parsing Guide for gem5 specifics
Explore Pattern Aggregation
Learn Performance Optimization
Check Publication Tips

Getting Help

Documentation Issues: Open a docs issue
Bug Reports: Open a bug issue
Feature Requests: Open a feature issue
Questions: Check existing Discussions

License

RING-5 is released under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for details.

Acknowledgments

RING-5 builds upon the gem5 simulator community’s work and is designed for researchers in computer architecture (ISCA, MICRO, ASPLOS conferences).

Version: 1.0.0 Last Updated: February 2026 Maintained By: Contributors