How to Generate Miss Ratio Curves Using the MRC Profiler in libCacheSim

libCacheSim provides a dedicated MRC profiler accessible via scripts/profile_mrc.py that automatically builds the mrcProfiler binary, executes cache simulations across multiple cache sizes, and plots both request and byte miss-ratio curves.

Generating miss ratio curves (MRCs) is essential for understanding cache behavior and determining optimal cache sizes. The libCacheSim repository ships with a complete Python-based workflow that handles binary compilation, execution, and visualization without requiring manual intervention.

Understanding the MRC Profiler Workflow

The MRC profiler operates through three distinct stages managed by scripts/profile_mrc.py. Each stage interacts with specific utility modules to ensure accurate data collection and presentation.

Binary Preparation via setup_utils.py

Before any profiling can occur, the system must compile the mrcProfiler executable. The scripts/utils/setup_utils.py module handles this automatically by checking for the binary in _build/bin and triggering a build if it is missing. The absolute path to the compiled binary is exposed as the constant MRCPROFILER_PATH, which subsequent functions use to invoke the profiler.

Execution and Output Parsing

The function run_mrcprofiler_size() in profile_mrc.py launches the binary with parameters specifying the trace file, cache algorithms, and a comma-separated list of cache sizes. The binary outputs tab-separated lines following this format:

<hit-ratio>	<cache-size>B	<request-miss-ratio>	<byte-miss-ratio>

The helper _parse_mrcprofiler_output() applies a regular expression to capture these fields, returning a dictionary that maps each algorithm to a list of tuples containing (cache_size, miss_ratio, byte_miss_ratio).

Visualization with plot_mrc_size

Once data is parsed, plot_mrc_size() generates publication-ready plots. This function optionally converts raw byte sizes to human-readable units (KB, MB, GB) using find_unit_of_cache_size from str_utils.py. By default, it produces two PDF files: one for request miss ratio (*_profiled_rmr.pdf) and one for byte miss ratio (*_profiled_bmr.pdf), with the cache size axis displayed on a logarithmic scale.

Command-Line Usage for Generating Miss Ratio Curves

The simplest way to generate MRCs is through the command-line interface provided by profile_mrc.py. This method handles the entire workflow from compilation to final plot generation.

The following example generates curves for the LRU algorithm using the SHARDS sampling profiler on a CSV trace:

python3 scripts/profile_mrc.py \
    --tracepath data/twitter_cluster52.csv \
    --trace-format csv \
    --trace-format-params "time-col=1,obj-id-col=2,obj-size-col=3,delimiter=,,obj-id-is-num=1" \
    --algos LRU \
    --profiler SHARDS \
    --profiler-params FIX_RATE,0.01,42 \
    --sizes 0.001,0.005,0.01,0.02,0.05,0.10,0.20,0.40 \
    --name twitter_mrc

This invocation automatically builds the mrcProfiler binary if necessary, executes the simulation across the specified cache size fractions, and outputs twitter_mrc_profiled_rmr.pdf and twitter_mrc_profiled_bmr.pdf in the current directory.

Programmatic Python API for MRC Generation

For integration into larger analysis pipelines, the functions within profile_mrc.py can be imported and called directly from Python. This approach provides greater flexibility for batch processing and custom visualization.

The following example demonstrates how to run the profiler and generate plots programmatically:

from scripts.profile_mrc import run_mrcprofiler_size, plot_mrc_size

# 1️⃣ Run the profiler (binary is located via MRCPROFILER_PATH)

dataname, mrc = run_mrcprofiler_size(
    datapath="data/twitter_cluster52.csv",
    algos="LRU,LFU",
    cache_sizes="0.001,0.005,0.01,0.02,0.05,0.10,0.20,0.40",
    profiler="SHARDS",
    profiler_params="FIX_RATE,0.01,42",
    ignore_obj_size=True,
    trace_format="csv",
    trace_format_params="time-col=1,obj-id-col=2,obj-size-col=3,delimiter=,,obj-id-is-num=1",
)

# 2️⃣ Plot request miss ratios (log-scaled cache size)

plot_mrc_size(
    mrc_dict=mrc,
    cache_size_has_unit=True,
    use_byte_miss_ratio=False,
    name=f"{dataname}_request_mrc",
)

# 3️⃣ Plot byte miss ratios

plot_mrc_size(
    mrc_dict=mrc,
    cache_size_has_unit=True,
    use_byte_miss_ratio=True,
    name=f"{dataname}_byte_mrc",
)

This script produces the same PDF outputs as the command-line version but allows for dynamic algorithm selection and integration with data science workflows.

Key Source Files and Their Roles

The MRC profiling system is distributed across several utility modules within the scripts/ directory. Understanding these components helps with debugging and extending the functionality.

• scripts/profile_mrc.py – Main driver that orchestrates argument parsing, binary execution, and result plotting. Contains run_mrcprofiler_size() and plot_mrc_size().

• scripts/utils/setup_utils.py – Handles build system integration, defines MRCPROFILER_PATH, and compiles the mrcProfiler binary on first use.

• scripts/utils/trace_utils.py – Provides helper functions to extract human-readable trace names from file paths, used for labeling plot titles.

• scripts/utils/str_utils.py – Implements find_unit_of_cache_size() to convert byte values to KB, MB, or GB for axis labeling.

• scripts/utils/plot_utils.py – Defines global Matplotlib styling, color palettes, and marker styles used across all visualization functions.

Summary

Generating miss ratio curves in libCacheSim requires understanding the interaction between the Python scripting layer and the compiled mrcProfiler binary. Key takeaways include:

• The scripts/profile_mrc.py script provides both CLI and programmatic interfaces for MRC generation.
• setup_utils.py automatically handles binary compilation and exposes the path via MRCPROFILER_PATH.
• The profiler outputs tab-separated data containing hit ratios, cache sizes, and both request and byte miss ratios.
• plot_mrc_size() generates dual PDF outputs for request miss ratio and byte miss ratio with logarithmic size axes.

Frequently Asked Questions

What is the difference between request miss ratio and byte miss ratio in libCacheSim MRC output?

Request miss ratio measures the proportion of individual requests that result in cache misses, while byte miss ratio measures the proportion of total bytes transferred that were missed. The mrcProfiler binary outputs both metrics in separate columns, and plot_mrc_size() generates distinct PDF files (*_profiled_rmr.pdf for request miss ratio and *_profiled_bmr.pdf for byte miss ratio) to visualize these differences.

How does the SHARDS profiler parameter FIX_RATE affect MRC generation accuracy?

The FIX_RATE parameter in SHARDS (Simple Hash-based Adaptive Randomized Data Structure) controls the sampling rate used to estimate the miss ratio curve. A value of 0.01 (as shown in the examples) means the profiler samples approximately 1% of the trace, significantly speeding up computation while maintaining statistical accuracy. The third parameter (42 in the examples) specifies the random seed for reproducible results.

Can I use the MRC profiler with custom trace formats beyond CSV?

Yes, the run_mrcprofiler_size() function accepts a trace_format parameter that supports multiple formats including csv, binary, and other formats supported by libCacheSim. The trace_format_params argument allows you to specify format-specific options such as column indices for time, object ID, and object size, or delimiter characters for CSV files, ensuring compatibility with custom trace structures.

Where does libCacheSim store the compiled mrcProfiler binary?

The compiled binary is stored in _build/bin/mrcProfiler relative to the repository root. The scripts/utils/setup_utils.py module defines the constant MRCPROFILER_PATH to reference this location and automatically triggers the build process via the setup utilities if the binary is not present when first running the profiler.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}