SCALE-Sim models a systolic array cycle by cycle before you build it

The input is a hardware config and a layer topology, and everything else is derived

SCALE-Sim is a simulator for systolic array based accelerators, supporting Deep Neural Network layers such as convolution, fully connected, and any layer that uses GEMMs, which includes attention. The mechanism is a two-file input model. The configuration file specifies the architecture and the run parameters, and the topology file is a CSV describing the layers of the workload topology. The config file has three sections, and the documentation describes what each one decides. The general section specifies the run name, which is user specific. The architecture_presets section describes the parameter of the systolic array hardware to simulate. The run_preset section specifies whether the simulator should run with user specified bandwidth or should calculate the optimal bandwidth for stall free execution, and it also allows specifying a `TimeLinearModel` parameter such as `TPUv4`, `TPUv5e` or `TPUv6e` to convert compute cycles into time estimates using hardware specific linear models. So the architecture is declared, the workload is declared, and the cycle count falls out of the arithmetic of how data moves through the array.

Convolution is the default input shape, and M, N, K needs a switch

The topology file format has a default and an alternative, and picking the wrong one produces a confusing result rather than an error. Layers are typically described as convolution layer parameters, and for other layer types SCALE-Sim also accepts the workload description in M, N, K format of the equivalent GEMM operation. The documentation is explicit that the tool expects the inputs in the convolution format by default, and that when using the M, N, K format for input you must specify it with the `-i gemm` switch, as in the example `python3 <scale sim repo root>/scalesim/scale.py -c <path_to_config_file> -t <path_to_mnk_topology_file> -i gemm`.

This matters because a convolutional layer and the GEMM it decomposes into are not interchangeable descriptions of the same workload. The im2col transformation that convolution becomes has a memory cost of its own, and the simulator models convolution as an im2col operation, so feeding it a raw GEMM description and reading the result as a convolution estimate will mislead you about the data movement. The two example files in the documentation, one showing convolution parameters and one showing the M, N, K form, are the reference for both shapes.

The run is a module invocation with a config, a topology and an output directory

Running the simulator is one command against the installed package, with three path arguments. After installing SCALE-Sim it can be run by using `scalesim.scale` and providing the paths to the architecture configuration and the topology descriptor csv file:

The invocation is `python3 -m scalesim.scale -c <path_to_config_file> -t <path_to_topology_file> -p <path_to_output_log_dir>`, and the output directory argument is the one people tend to forget, because the simulator also writes to a default location, and the documentation explains that the simulator generates read write traces and summary logs at `<run_dir>/../scalesim_outputs/`, with a custom location possible using the `-p` switch when using the `scalesim.py` file. If you would rather run directly from the source than through the installed package, the documentation gives the alternative, which sets the Python path to the repository root and invokes the script directly with the same config and topology arguments: `PYTHONPATH=$PYTHONPATH:<scale_sim_repo_root> python3 <scale_sim_repo_root>/scalesim/scale.py -c <path_to_config_file> -t <path_to_topology_file>`.

There is a third path for the first run from sources, when the dependencies are not yet installed, which installs them from the requirements file in the repository root.

Installation is a pip install from the folder, editable if you will hack on it

The installation story is short because the simulator is pure Python and installs from source. The documentation says that getting started is simple and that SCALE-Sim is completely written in Python and could be installed from source, and gives the command to install it in your environment as `pip3 install <path-to-scalesim-v3-folder>`. Developers who intend to modify the simulator during their usage are told to install it with the `-e` flag, which creates a symbolic link instead of replicating the package in the environment, so that modifications to the code are synchronised simultaneously. That distinction is the whole reason to choose one over the other, and the runtime dependencies are the ones listed in the requirements file:

`pip3 install -r <scale_sim_repo_root>/requirements.txt`

The declared dependencies in the package setup are numpy, configparser, absl-py, tqdm, pandas, setuptools, matplotlib, cython and numba, and the package is published under the name `scalesim` at version 3.0.0 with an MIT licence. The Makefile offers the same thing inside a virtual environment, and its recipe is the part to copy if you want an isolated environment:

	test -d ${venvdir} || python3 -m venv ${venvdir}
	${venvdir}/bin/pip install  --upgrade pip
	${venvdir}/bin/pip install setuptools wheel
	${venvdir}/bin/pip install  -Ur requirements.txt

The `venvdir` variable is set to `venv` at the top of the Makefile, and the same recipe touches the activate script and writes a `source_me.sh` that sources it. A `clean` target removes the caches, the build and the distribution directories.

Four summary reports separate compute, bandwidth, access counts and time

The output is the point of the tool, and it is split into four reports so that you can tell apart the different kinds of cost. COMPUTE_REPORT.csv holds layer wise logs for compute cycles, stalls and utilization percentages. BANDWIDTH_REPORT.csv holds layer wise information about average and maximum bandwidths for each operand when accessing SRAM and DRAM. DETAILED_ACCESS_REPORT.csv holds layer wise information about the number of accesses and access cycles for each operand for SRAM and DRAM. TIME_REPORT.csv holds layer wise time estimates in microseconds, calculated using the configured linear model, whether that is TPUv4, TPUv5e or TPUv6e, based on compute cycles and spatiotemporal dimensions. In addition, cycle accurate SRAM and DRAM access logs are dumped at `<outputs_dir>/<run_name>/`. The separation matters for interpretation. A stall cycle and a bandwidth ceiling are different bottlenecks, and a report that merged them would tell you that the design is slow without telling you which resource to change.

Two fidelity modes decide whether the bandwidth is your assumption or the answer

The multi-fidelity feature is the one to understand before you interpret a number. SCALE-Sim v2 lists a bandwidth calculation mode, called CALC, and a stall cycle calculation and use user bandwidth mode, called USER. The distinction is whether the bandwidth in your config is an input the simulator honours or an output the simulator derives. In USER mode you tell the tool what bandwidth the memory system will deliver, and the simulator computes the stall cycles that result from not meeting it. In CALC mode the simulator works out the bandwidth that would be needed for stall free execution, which is a statement about what your design would have to achieve rather than about what it does. The v2 feature list also includes analytical compute cycles validated by RTL simulation, and separate double buffered memory modelling for the input, filter and output matrices, which is what lets the bandwidth numbers differ per operand rather than being one system-wide figure.

Sparsity, memory models and multi-core arrived in v3, and the docs lag

The version history is where you learn what the current simulator can and cannot do. v3 adds five things over v2. Sparsity support is layer-wise and row-wise sparsity support for efficient neural network execution, and the repository carries a separate README_Sparsity.md for it. Ramulator integration gives a detailed memory model for evaluating DRAM performance, with a README_ramulator.md, a run_ramulator.sh script and a run_ramulator_mnk.sh, plus shell scripts for generating the ramulator stall and memory bandwidth plots. Accelergy integration provides energy and power estimation capabilities. Layout support covers advanced memory layout configurations, and there is a `layouts/` directory at the root. Multi-core support models accelerators with multiple tensor cores, which the documentation says addresses the limitations of the predecessor, v2, which could only model single-core systolic arrays. The honest caveat is that the documentation in the visible part of this repository is incomplete: the detailed config file documentation is marked as TBD, and the sections on the TimescaleDB and Postgres output, the Prometheus configuration and the multi-core workflow are cut off, so the practical steps for several of these features have to be taken from the linked documentation rather than from the project page.

Where a cycle-accurate array model stops being enough

The boundary of the tool is the array. SCALE-Sim models the dataflow inside a systolic array, and the reported numbers are about the array, its memory traffic and its stalls. It does not model the rest of a chip: the instruction pipeline, the host interconnect, the clock and power tree, the memory controller beyond what the Ramulator integration covers, or the cost of the logic that decides what the array does. That is not a defect, it is the scope that makes the cycle counts meaningful, but it means a design decision made on SCALE-Sim output is a decision about the array. The other limit is the fidelity of the memory model itself, since the bandwidth you feed in USER mode or that the simulator derives in CALC mode is a parameter of an idealised system, and the real number depends on the memory system you will actually build, which is exactly what the Ramulator integration exists to help with. The alternative to weigh against is a full-system simulator such as gem5 or an RTL simulation flow, which will tell you about the parts SCALE-Sim ignores and will take far longer to run. For exploring dataflow shapes across many layer configurations, a fast analytical cycle model is the right instrument; for deciding whether the whole chip meets its clock target, it is not.

Editorial conclusion

SCALE-Sim is worth using when you are deciding between dataflow shapes for a matrix accelerator, because it answers the question a spreadsheet cannot, namely how many cycles a given tiling and bandwidth assumption actually costs, and because the per-layer reports let you see which layer is the bottleneck rather than only the total. It is a poor fit if you need a full chip model, since the simulator stops at the array boundary and does not model the surrounding logic, and a poor fit if you need energy numbers, since the Accelergy integration is listed as a v3 feature whose usage is not described in the visible documentation. Before you run it, decide whether your workload should be given as convolution parameters or in M, N, K form, because the default input format is convolution and the M, N, K form needs the `-i gemm` switch, and note that the last push to the repository was on 2026-06-28 with the most recent release v3.0.0 from 2025-08-13.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. scalesim-project/SCALE-Sim on GitHub