# mlnetwork/rostam architecture

> Architecture diagram of the GitHub repository mlnetwork/rostam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mlnetwork/rostam
- Repository: https://github.com/mlnetwork/rostam

## Overview

##### Project type and purpose
- From the file tree and README, “rostam” is a command-line driven simulation framework for multi-GPU training jobs over different interconnect topologies (electrical, ring, fullmesh, optical/OCS).
- It ingests pre-profiled model execution graphs, performs operator placement (optionally via Gurobi-powered ILP), schedules operations across devices, and simulates communication over a chosen network topology to produce performance metrics.

##### File structure
– Top-level “src” directory splits into cohesive modules:
- compute: GPU device abstraction
- executor: loads graph profiles, drives session execution, tracks op scheduling
- graph_def: protobuf definitions for input profiles
- interconnect: implementations of various network topologies and packet/transport logic
- placement: operator partitioning and device-mapping strategies (DP, MP, base, ILP via Gurobi)
- sipml: command-line frontends (sipml-elect, sipml-ring, etc.)
- utils: shared utilities (config parsing, matrix math, exit codes)
- scripts: profile-generation Python scripts for ResNet, Transformer, etc.
– Build artifacts: autotools files (configure.ac, Makefile.am), autogen.sh.

##### README for additional insights
– The framework supports optional Gurobi for ILP-based placement; falls back to presets if unavailable.
– Input profiles are protobuf files plus iteration-level stats.
– CLI tools expose flags for number of GPUs, bandwidth, topology, solver method, input profile path.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% User / Profiling Scripts
  subgraph "User / Profiling Scripts"
    Scripts_ImageNet["imagenet_profiler.py"]:::script
    Scripts_Transformer["transformer_profiler.py"]:::script
    Scripts_Run["run.sh"]:::script
  end

  %% CLI Frontend
  subgraph "CLI Frontend (src/sipml)" 
    CLI_Elect["sipml-elect.cc"]:::cppModule
    CLI_Ring["sipml-ring.cc"]:::cppModule
    CLI_Fullmesh["sipml-fullmesh.cc"]:::cppModule
    CLI_OCS["sipml-ocs.cc"]:::cppModule
  end

  %% GraphDef Parser
  subgraph "GraphDef Parser (src/graph_def)"
    Parser_PbCC["graph_profile.pb.cc"]:::cppModule
    Parser_PbH["graph_profile.pb.h"]:::cppModule
  end

  %% Executor
  subgraph "Executor (src/executor)"
    Exec_GraphCC["graph.cc"]:::cppModule
    Exec_GraphHH["graph.hh"]:::cppModule
    Exec_OpCC["op.cc"]:::cppModule
    Exec_OpHH["op.hh"]:::cppModule
    Exec_SessCC["session.cc"]:::cppModule
    Exec_SessHH["session.hh"]:::cppModule
    Exec_Proto["graph_profile.proto"]:::cppModule
  end

  %% Placement Engine
  subgraph "Placement Engine (src/placement)"
    Place_BaseCC["base_placement.cc"]:::cppModule
    Place_BaseHH["base_placement.hh"]:::cppModule
    Place_DPCC["dp.cc"]:::cppModule
    Place_DPHH["dp.hh"]:::cppModule
    Place_MPCC["mp.cc"]:::cppModule
    Place_MPHH["mp.hh"]:::cppModule
    Place_OpPartCC["op_partitioner.cc"]:::cppModule
    Place_OpPartHH["op_partitioner.hh"]:::cppModule
    Place_StrategyCC["strategy.cc"]:::cppModule
    Place_StrategyHH["strategy.hh"]:::cppModule
  end

  %% Compute Engine
  subgraph "Compute Engine (src/compute)"
    Compute_Device["device.hh"]:::cppModule
    Compute_GPUCC["gpu.cc"]:::cppModule
    Compute_GPUHH["gpu.hh"]:::cppModule
  end

  %% Interconnect Simulator
  subgraph "Interconnect Simulator (src/interconnect)"
    IC_BaseCC["base_interconnect.cc"]:::cppModule
    IC_BaseHH["base_interconnect.hh"]:::cppModule
    IC_ElectCC["electrical_switch.cc"]:::cppModule
    IC_ElectHH["electrical_switch.hh"]:::cppModule
    IC_FullCC["fullmesh.cc"]:::cppModule
    IC_FullHH["fullmesh.hh"]:::cppModule
    IC_RingCC["ring.cc"]:::cppModule
    IC_RingHH["ring.hh"]:::cppModule
    IC_OCSCC["ocs.cc"]:::cppModule
    IC_OCSHH["ocs.hh"]:::cppModule
    IC_MordiaCC["mordia.cc"]:::cppModule
    IC_MordiaHH["mordia.hh"]:::cppModule
    IC_Packet["packet.hh"]:::cppModule
    IC_TransportCC["transport.cc"]:::cppModule
    IC_TransportHH["transport.hh"]:::cppModule
    IC_TMCC["tm_estimator.cc"]:::cppModule
    IC_TMHH["tm_estimator.hh"]:::cppModule
  end

  %% Utils & Config
  subgraph "Utils & Config (src/utils)"
    Utils_Utils["utils.hh"]:::cppModule
    Utils_Config["sim_config.hh"]:::cppModule
    Utils_Matrix["matrix.hh"]:::cppModule
    Utils_Exit["exit_status.hh"]:::cppModule
  end

  %% External Solver
  External_Gurobi["Gurobi Solver"]:::external

  %% Output Metrics
  Output["Performance Metrics / Logs"]:::output

  %% Relationships
  Scripts_ImageNet -->|generates profile| CLI_Elect
  Scripts_Transformer -->|generates profile| CLI_Ring
  Scripts_Run -->|invokes| CLI_Fullmesh

  CLI_Elect -->|loads profile| Parser_PbCC
  CLI_Ring -->|loads profile| Parser_PbCC
  CLI_Fullmesh -->|loads profile| Parser_PbCC
  CLI_OCS -->|loads profile| Parser_PbCC

  Parser_PbCC -->|deserializes pb| Exec_GraphCC

  Exec_GraphCC -->|"constructs DAG"| Place_BaseCC
  Exec_GraphCC -->|schedules ops| Compute_Device
  Exec_GraphCC -->|schedules ops| IC_BaseCC

  Place_BaseCC -->|uses strategy| Place_DPCC
  Place_BaseCC -->|uses strategy| Place_MPCC
  Place_BaseCC -->|optional ILP| External_Gurobi

  Compute_Device -->|compute time| Output
  IC_BaseCC -->|packet streams| Output

  Exec_GraphCC -->|produces metrics| Output
  Output -->|reports| Scripts_Run

  %% Dependencies on Utils
  Utils_Utils -.-> CLI_Elect
  Utils_Config -.-> Exec_GraphCC
  Utils_Matrix -.-> Compute_Device
  Utils_Exit -.-> Scripts_Run

  %% Click Events
  click Scripts_ImageNet "https://github.com/mlnetwork/rostam/blob/master/src/scripts/imagenet_profiler.py"
  click Scripts_Transformer "https://github.com/mlnetwork/rostam/blob/master/src/scripts/transformer_profiler.py"
  click Scripts_Run "https://github.com/mlnetwork/rostam/blob/master/src/scripts/run.sh"
  click CLI_Elect "https://github.com/mlnetwork/rostam/blob/master/src/sipml/sipml-elect.cc"
  click CLI_Ring "https://github.com/mlnetwork/rostam/blob/master/src/sipml/sipml-ring.cc"
  click CLI_Fullmesh "https://github.com/mlnetwork/rostam/blob/master/src/sipml/sipml-fullmesh.cc"
  click CLI_OCS "https://github.com/mlnetwork/rostam/blob/master/src/sipml/sipml-ocs.cc"
  click Parser_PbCC "https://github.com/mlnetwork/rostam/blob/master/src/graph_def/graph_profile.pb.cc"
  click Parser_PbH "https://github.com/mlnetwork/rostam/blob/master/src/graph_def/graph_profile.pb.h"
  click Exec_GraphCC "https://github.com/mlnetwork/rostam/blob/master/src/executor/graph.cc"
  click Exec_GraphHH "https://github.com/mlnetwork/rostam/blob/master/src/executor/graph.hh"
  click Exec_OpCC "https://github.com/mlnetwork/rostam/blob/master/src/executor/op.cc"
  click Exec_OpHH "https://github.com/mlnetwork/rostam/blob/master/src/executor/op.hh"
  click Exec_SessCC "https://github.com/mlnetwork/rostam/blob/master/src/executor/session.cc"
  click Exec_SessHH "https://github.com/mlnetwork/rostam/blob/master/src/executor/session.hh"
  click Exec_Proto "https://github.com/mlnetwork/rostam/blob/master/src/executor/graph_profile.proto"
  click Place_BaseCC "https://github.com/mlnetwork/rostam/blob/master/src/placement/base_placement.cc"
  click Place_BaseHH "https://github.com/mlnetwork/rostam/blob/master/src/placement/base_placement.hh"
  click Place_DPCC "https://github.com/mlnetwork/rostam/blob/master/src/placement/dp.cc"
  click Place_DPHH "https://github.com/mlnetwork/rostam/blob/master/src/placement/dp.hh"
  click Place_MPCC "https://github.com/mlnetwork/rostam/blob/master/src/placement/mp.cc"
  click Place_MPHH "https://github.com/mlnetwork/rostam/blob/master/src/placement/mp.hh"
  click Place_OpPartCC "https://github.com/mlnetwork/rostam/blob/master/src/placement/op_partitioner.cc"
  click Place_OpPartHH "https://github.com/mlnetwork/rostam/blob/master/src/placement/op_partitioner.hh"
  click Place_StrategyCC "https://github.com/mlnetwork/rostam/blob/master/src/placement/strategy.cc"
  click Place_StrategyHH "https://github.com/mlnetwork/rostam/blob/master/src/placement/strategy.hh"
  click Compute_Device "https://github.com/mlnetwork/rostam/blob/master/src/compute/device.hh"
  click Compute_GPUCC "https://github.com/mlnetwork/rostam/blob/master/src/compute/gpu.cc"
  click Compute_GPUHH "https://github.com/mlnetwork/rostam/blob/master/src/compute/gpu.hh"
  click IC_BaseCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/base_interconnect.cc"
  click IC_BaseHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/base_interconnect.hh"
  click IC_ElectCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/electrical_switch.cc"
  click IC_ElectHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/electrical_switch.hh"
  click IC_FullCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/fullmesh.cc"
  click IC_FullHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/fullmesh.hh"
  click IC_RingCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/ring.cc"
  click IC_RingHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/ring.hh"
  click IC_OCSCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/ocs.cc"
  click IC_OCSHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/ocs.hh"
  click IC_MordiaCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/mordia.cc"
  click IC_MordiaHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/mordia.hh"
  click IC_Packet "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/packet.hh"
  click IC_TransportCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/transport.cc"
  click IC_TransportHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/transport.hh"
  click IC_TMCC "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/tm_estimator.cc"
  click IC_TMHH "https://github.com/mlnetwork/rostam/blob/master/src/interconnect/tm_estimator.hh"
  click Utils_Utils "https://github.com/mlnetwork/rostam/blob/master/src/utils/utils.hh"
  click Utils_Config "https://github.com/mlnetwork/rostam/blob/master/src/utils/sim_config.hh"
  click Utils_Matrix "https://github.com/mlnetwork/rostam/blob/master/src/utils/matrix.hh"
  click Utils_Exit "https://github.com/mlnetwork/rostam/blob/master/src/utils/exit_status.hh"

  %% Styles
  classDef cppModule fill:#ADD8E6,stroke:#333,stroke-width:1px
  classDef script fill:#98FB98,stroke:#333,stroke-width:1px
  classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
  classDef output fill:#FFFACD,stroke:#333,stroke-width:1px
```
