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

> Easily generate miss ratio curves with libCacheSim's MRC profiler. This script automates simulations across cache sizes and plots request and byte miss ratios. Get insights into your cache performance.

- Repository: [Juncheng Yang/libcachesim](https://github.com/1a1a11a/libcachesim)
- Tags: how-to-guide
- Published: 2026-02-23

---

**libCacheSim provides a dedicated MRC profiler accessible via [`scripts/profile_mrc.py`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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:

```bash
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`](https://github.com/1a1a11a/libcachesim/blob/main/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:

```python
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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/scripts/profile_mrc.py) script provides both CLI and programmatic interfaces for MRC generation.
- [`setup_utils.py`](https://github.com/1a1a11a/libcachesim/blob/main/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`](https://github.com/1a1a11a/libcachesim/blob/main/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.