Ramulator 2.1: cycle-level DRAM simulation with generated Python bindings

A simulator for memory system research, not for running programs

Ramulator 2.1 exists to answer questions you cannot answer on real hardware without a fab. The project describes itself as a modern, modular, extensible and fast cycle-accurate DRAM simulator, built to support agile implementation and evaluation of new memory system designs, with new DRAM standards and emerging RowHammer mitigation techniques given as examples. The audience is therefore specific: people working on memory controllers, DRAM standards, and memory side channel defences, mostly in academic and industrial research groups. It is the successor of Ramulator 1.0 and a major overhaul of Ramulator 2.0, the latter described in an IEEE Computer Architecture Letters paper whose preprint is linked as the project homepage. Ramulator 2.1 can run standalone against memory traces, or be linked into another simulator as a DRAM and memory controller library, which is the mode that matters if you want to study interactions with a processor model. The licence is MIT, and there are no GitHub releases, so you work with the source tree.

The C++ core with Python wrappers generated from it

The architectural bet of this version is that the simulation logic lives in C++ and the configuration layer is Python, with the binding between them generated rather than written by hand. The user guide states that the C++ codebase ships with automatically generated Python wrappers, so users can focus on the modelling and simulation code without maintaining boilerplate. The build makes that visible: the default CMake invocation builds the shared library, builds the Python extension module under python/ramulator/, and runs the code generator so that all generated code stays in sync with the source. The repository layout follows the same split, with src/ holding the C++ implementation, python/ holding the wrappers, examples/ holding ready to run configurations and traces, tests/ holding the test and validation workflows, resources/gem5_wrappers/ holding the reference integration code, and visualizer/ holding a browser based trace visualizer built on Nuxt and WebGL. The Python package itself is minimal in metadata, version 2.1.0, requiring Python 3.10 or newer with pyyaml as the only runtime dependency.

Standards coverage from DDR3 through HBM4

The list of modelled standards is the reason to pick this simulator over writing your own timing model. Ramulator 2.1 provides device and memory controller models for DDR3, DDR4 and DDR5, for GDDR6 and GDDR7, for LPDDR5 and LPDDR6, and for HBM1, HBM2, HBM3 and HBM4. The differences the guide lists between 2.1 and 2.0 are aggregated bug fixes, wider support for newer DRAM and controller features, a wider set of test and validation workflows, notable work on ease of use, configuration and extension, and general code quality changes. That last pair of words matters less for a paper than the first two, since a controller idea about a newly published standard is only interesting if the simulator models that standard accurately. The user guide also asks that anyone using Ramulator 2.1 or 2.0 in published work cite the two accompanying papers, one for the 2.1 tutorial and one for the 2.0 journal article.

The container is the recommended setup path

The guide is direct about dependencies: it recommends using the container to avoid dependency issues, and the repository is configured so it can be opened as a one click Dev Container with everything already installed. The easiest route is a GitHub Codespace, and Visual Studio Code is said to prompt you to reopen the repository in a Dev Container after the first clone. For a local setup the compose file builds from the Dockerfile in .devcontainer and mounts the repository at /workspace, activating a virtual environment called ramulator2-venv in the container shell. It also grants SYS_PTRACE and sets seccomp to unconfined, which the compose file shows explicitly. A separate service in the same file, gated behind a profile, runs the visualizer, and the port it publishes is configurable through an environment variable that defaults to 3000.

docker compose up -d --build --wait
docker compose exec ramulator2 bash

The wait flag matters here, because the service has a healthcheck that watches for a ready marker file that the post-create script touches.

Building by hand when you need your own toolchain

If you are configuring the environment yourself, the guide lists the requirements plainly: a C++20 compiler such as g++-12 or clang++-15, CMake 3.14 or newer, and Python 3.10 or newer if you want the bindings, the CLI or the tests. Several dependencies are fetched by CMake itself rather than installed by hand, among them yaml-cpp for YAML configuration parsing, fmt for C++ print formatting, nanobind for the Python bindings when RAMULATOR_PYTHON_BINDINGS is on, and argparse, which is vendored in ext/. The Python side adds pytest, matplotlib for latency and throughput plotting, and ruff as the linter and formatter, installed from requirements-dev.txt, with setuptools 64 or newer pulled in automatically by the editable install. The plain build sequence is short:

mkdir -p build
cd build
cmake ..
make -j
cd ..

If you only want the C++ library for your own simulator, the same sequence works with the bindings switched off:

cmake .. -DRAMULATOR_PYTHON_BINDINGS=OFF

Clang-format is listed as an optional tool, and the repository carries a .clang-format file and a ruff configuration that sets a line length of 100 with double quotes.

The first run and the editable Python install

Once the build is done, the guide points you at the example configuration as the sanity check, and the examples directory also holds a gem5 hello world script and a traces folder for input workloads. Running the example is expected to print example statistics, which is the signal that the whole chain, C++ library, generated bindings and Python configuration, is wired correctly.

python3 examples/example_config.py

To use the simulator from any directory rather than only from the repository root, the guide asks you to install the Python package in editable mode after building, so that both the module invocation and the import work anywhere:

pip install -e .

If that install fails, the documented fallback is to create and activate a virtual environment first and install again. The guide's own table of contents runs through your first run, writing configurations, validation and regression tests, gem5 integration, using Ramulator as a pure C++ library, extending Ramulator, an explanation of how it works internally, and the trace visualizer, so a reader can pick the chapter that matches the question in front of them.

Dropping the simulator into gem5, and the browser visualizer

The integration story is the one that sets Ramulator apart from a standalone trace replayer. The project provides gem5 wrappers that work as a drop in component for both SE and FS mode, tested against gem5 v25.1, with FS mode tested using a post-boot checkpoint. The reference wrapper code lives in resources/gem5_wrappers/, and examples/gem5_se_ramulator_hello_world.py is the starting point in the examples directory, which is what you would point a gem5 run at. On the analysis side, the visualizer is a browser based tool built on Nuxt and WebGL, and the compose file gives it a dev service on node:22 that runs npm install followed by nuxt dev with the host set to 0.0.0.0, backed by a named volume for node_modules so that rebuilds do not re-download packages.

  visualizer:
    profiles: [visualizer]
    build:
      context: ./visualizer
      dockerfile: Dockerfile

For iteration there is a visualizer-dev profile, and both services read the same RAMULATOR_VISUALIZER_PORT variable, so the port you publish locally is set in one place.

A public tree that lags the authors' internal version

The most important caveat is stated in the introduction rather than buried. This repository holds the public version of Ramulator 2.1, and the project says that improvements to the code framework, additional functionality and bug fixes will be synchronized from the internal version from time to time. So the tree you clone is a snapshot, and a paper written this quarter may be based on behaviour that arrives in the public repository later, with no release tags to tell you which version you have. That is the upgrade cost of working here: there is no versioned release stream to pin, only a moving main branch and a citation request in the guide. There are other boundaries worth stating. It is a cycle-level DRAM simulator, so it says nothing about your application code. It demands a C++20 toolchain, so a Python only environment is not enough. And the repository is a research codebase maintained alongside a private one, which is a different maintenance contract from a supported product.

Editorial conclusion

Adopt ramulator2 if you are a memory systems researcher or a student who needs a cycle-accurate DRAM and controller model to evaluate a design idea, and if you can work in C++20 with a CMake toolchain. Do not reach for it to model an application workload in production, and do not expect the public tree to match the authors' internal version on any given day, because the project states that internal improvements are synchronized from time to time. Verify first that the standard you need, DDR5, GDDR7, LPDDR6 or HBM4, has the controller behaviour you care about, since coverage of newer features evolves over time and there are no release tags to pin.

Frequently asked questions

Official sources

1. CMU-SAFARI/ramulator2 on GitHub
2. Issues
3. License: MIT
4. Project website
5. README