ASTRA-sim models the whole training stack, from scheduler to network

ASTRA-sim models the stack, not just the interconnect

Network simulators tend to be built for one layer: packets, links, maybe a routing algorithm. ASTRA-sim takes a wider slice. The README describes it as a distributed AI system simulator that models the end-to-end software and hardware stack of modern AI systems, and it names three things explicitly: workload scheduling, collective communication algorithms, and hardware architectures covering compute, memory and network.

That scope is the point. A large-model training job is sensitive to all three at once. A change to how a collective is laid out across ranks competes with the placement of compute and with memory pressure, and those effects interact in ways that a single-layer model hides. The project describes the result as end-to-end multi-fidelity simulation for aiding design and deployment of next-generation distributed AI systems.

The intended reader is a researcher or systems engineer who needs to reason about a configuration before renting the hardware. The README is short and does not enumerate the modelled mechanisms in detail, so the project's wiki and website carry the substance rather than the front page.

APIs are the seam where external components plug in

The architecture point in the README is the suite of APIs, described as enabling plug-and-play of external open or proprietary components for modelling different parts of the AI system. That is what separates ASTRA-sim from a monolithic trace analyser: the intent is that a component already written for a real system can be modelled inside the simulator, and that the modelled parts can be swapped.

The repository layout supports that reading. The top level splits into astra-sim/ for the simulator itself, extern/ for external code, inputs/ for inputs, examples/ for worked configurations, tests/ for tests, build/ and utils/ for the build and shared helpers, plus docs/ and a CMakeLists.txt at the root. A .gitmodules file sits alongside the extern/ directory, which is the usual arrangement for fetching external code as submodules rather than copying it in by hand, and a Dockerfile at the root defines a reproducible environment for the whole tree.

The practical consequence for a user is that this is a compiled C++ project with a Python 3.11 toolchain alongside it, not a Python library you import. The primary language is C++, and the build system is CMake.

Workload input is a Chakra execution trace

How a workload enters the simulator is the first practical question, and the README answers it in one sentence: ASTRA-sim accepts MLCommons Chakra Execution Traces as workload-layer inputs, with a pointer to the Chakra project for details.

That is a hard constraint worth stating plainly. If your training job emits a different trace format, something has to convert it, and the repository does not document a generic importer. Traces are also the honest representation of a real job, which means the fidelity of your simulation inherits the fidelity of whatever produced the trace.

The layered structure described in the overview diagram, with the workload layer on one side and compute, memory and network on the other, explains why the trace format matters so much. Once the workload layer is fixed, the remaining question is what happens underneath it, and that is where the plug-in APIs do their work. The README shows the layering as a visual summary and refers readers to the website for the full picture, so the API surface itself is documented outside the repository.

The shipped container pins Ubuntu 22.04, Python 3.11 and Abseil

The Dockerfile is the most concrete installation information the project provides, and it reads like a build recipe rather than a development image. It starts from Ubuntu 22.04, marks itself as using Ubuntu, and names two maintainers from Georgia Institute of Technology.

FROM ubuntu:22.04

System dependencies are installed in one pass, and the list is informative about what the simulator expects to find.

RUN apt -y install \
    coreutils wget vim git \
    gcc g++ clang-format \
    make cmake \
    libboost-dev libboost-program-options-dev \
    openmpi-bin openmpi-doc libopenmpi-dev \
    python3.11 python3-pip python3-venv \
    graphviz

Boost, OpenMPI and CMake are the C++ side, and the presence of openmpi packages hints that message passing is part of how the modelled system is represented. The Python side is a virtual environment on version 3.11, which the Dockerfile comments mark as required, with the project root added to the Python path and a set of analysis packages installed as STG dependencies.

RUN python3 -m venv /opt/venv/astra-sim
ENV PYTHONPATH="/app/astra-sim"
RUN pip3 install numpy sympy graphviz pandas

The image also compiles Abseil, pinned to the 20240722.0 release and labelled the latest LTS at the time of writing, because Protobuf is a dependency. Pinning a dated release is a reasonable choice for reproducibility, and it is also a maintenance obligation: a Protobuf or Abseil change upstream lands on you.

The examples directory maps the dimensions you can vary

The examples tree is the fastest way to understand what the simulator expects you to change. It is organised into workload/, network/, system/, remote_memory/ and run_scripts/, with a README of its own alongside them.

The folder names describe the axes of variation directly. Workload examples change how the job is shaped. Network examples change the interconnect model. System examples change the larger system composition, and remote_memory/ points at a distinct memory placement arrangement. The run_scripts/ directory holds the commands that tie a chosen combination together, which is what makes the examples executable rather than illustrative.

This is also where the multi-fidelity claim is visible in practice. Rather than one canonical configuration, you get a directory of variations that can be composed, and the scripts directory suggests the intended workflow is to pick a combination and run it.

The repository also carries a tests/ directory at the top level and an inputs/ directory, so the expected input files for a run are kept alongside the examples that consume them. A reader deciding whether ASTRA-sim fits their setup should start in examples/run_scripts/ rather than in the simulator source, because the scripts show the actual entry points and argument shapes that the rest of the tree supports.

Version 2.0 sits beside a preserved 1.0 branch

The README states that ASTRA-sim is currently at version 2.0 and that the previous version, ASTRA-sim 1.0, is available in a branch named ASTRA-sim-1.0. Keeping the old line in the same repository rather than in a tag or a separate archive makes comparison between the two architectures possible, and it means papers or experiments written against 1.0 can still be reproduced from a named branch.

There is a cost to that arrangement. The repository has no GitHub releases, so there is no tagged artifact, no release notes and no published changelog for 2.0 in this tree. The version number in use has to be taken from the README statement, and the detailed history of what changed between 1.0 and 2.0 is not recorded in the repository. The last push to the master branch was on 2026-09-19.

For support there is a user mailing list at [email protected], and the README asks people to fill in a form to join it. The project also asks for contributions through pull requests, which for a simulator of this size usually means adding a model, a workload trace or a hardware configuration.

Simulation trades real measurement for repeatable comparison

The alternative to ASTRA-sim is not another simulator so much as a different method: measure the system you actually intend to run. That approach produces ground truth for one configuration on one machine, at the cost of real time, real money and one configuration per experiment. ASTRA-sim inverts that trade, letting you compare many hardware and algorithm choices without occupying the hardware.

The trade is fidelity for turnaround, and the project's own framing of multi-fidelity simulation admits the seam. A model of a collective algorithm, a network topology or a memory hierarchy is a claim about behaviour, and if the model is wrong the comparison is wrong in the same direction for every configuration it touches. The plug-in API approach helps here, because a component can be swapped for a version that reproduces a real measured result, but that work falls on the user.

The narrow reading of who should not use it is straightforward. If you need numbers you can put in a paper about a specific physical cluster, or you want a working training job rather than a model of one, a simulator is the wrong instrument. The licence is MIT, which is permissive for both research and commercial use, so nothing in the licence pushes you toward one use over the other.

Editorial conclusion

ASTRA-sim fits a systems researcher who needs to compare scheduling, collective algorithms and hardware configurations before touching a real cluster, and it does not fit someone who needs measured results on physical hardware or a turnkey training job. Before adopting it, read the wiki rather than the README, pick the examples under examples/workload and examples/network that match your stack, and confirm your trace format is MLCommons Chakra, since that is the documented workload input.

Frequently asked questions

Official sources

1. astra-sim/astra-sim on GitHub
2. Issues
3. License: MIT
4. Project website
5. README