# pankajn-git/neupims-project architecture

> Architecture diagram of the GitHub repository pankajn-git/neupims-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pankajn-git/neupims-project
- Repository: https://github.com/pankajn-git/neupims-project

## Overview

NeuPIMs is a configurable simulator for neural-network inference on NPU/PIM hardware. Its main workflow parses configuration, initializes operation and memory-address state, constructs a model, launches it in the simulator, and runs the simulation. The repository also includes DRAM and interconnect simulation components. The excerpts show the entry-point workflow, but not most simulator internals or how the integrated simulators are invoked, so those relationships are left unverified rather than presented as established calls.

Main entry points: [`NeuPIMs/src/main.cc`](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/main.cc) (Program entry), [`NeuPIMs/src/Simulator.h`](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Simulator.h) (Simulator), [`NeuPIMs/src/scheduler/Scheduler.cc`](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/scheduler/Scheduler.cc) (Scheduling), [`NeuPIMs/extern/NewtonSim/src/neupims_controller.cc`](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/neupims_controller.cc) (DRAM controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation runtime"]
  node_cli["CLI parsing"]
  node_entry["Program entry<br/>[main.cc]"]
  node_simulator["Simulator<br/>[Simulator.h]"]
  node_config["Shared configuration<br/>[Common.h]"]
  node_client["Request client<br/>[Client.cc]"]
  node_requestgen["Request generation<br/>[RequestGenerator.h]"]
end

subgraph group_model["Model execution"]
  node_model["Model definition<br/>[Model.cc]"]
  node_program["Model program<br/>[ModelProgram.cc]"]
  node_stage["Stage program<br/>[StageProgram.cc]"]
  node_scheduler["Scheduling<br/>[Scheduler.cc]"]
  node_operations["Inference operations<br/>[Operation.cc]"]
  node_tensor["Tensor representations<br/>[NPUTensor.cc]"]
end

subgraph group_memory["Memory simulation"]
  node_address["Address allocation<br/>[AddressAllocator.h]"]
  node_dram["DRAM controller"]
  node_dramstate["DRAM channel state<br/>[channel_state.h]"]
  node_dramqueue["PIM command queue"]
end

subgraph group_network["Interconnect simulation"]
  node_interconnect["Interconnect API<br/>[Interconnect.hpp]"]
  node_traffic["Traffic manager"]
  node_router["Input-queued router<br/>[iq_router.cpp]"]
  node_networkstats["Network statistics<br/>[stats.hpp]"]
end

node_user(("Simulation user"))

node_user -.->|"starts"| node_entry
node_entry -->|"parses options"| node_cli
node_entry -->|"sets configuration"| node_config
node_entry -->|"initializes operations"| node_operations
node_entry -->|"constructs and runs"| node_simulator
node_entry -->|"creates and launches"| node_model
node_entry -->|"initializes allocators"| node_address
node_client -->|"uses"| node_requestgen
node_scheduler -->|"uses model program"| node_model
node_scheduler -->|"uses"| node_program
node_scheduler -->|"uses"| node_stage
node_scheduler -->|"uses tensors"| node_tensor
node_simulator -.->|"coordinates requests"| node_client
node_simulator -.->|"dispatches work"| node_scheduler
node_simulator -.->|"uses DRAM model"| node_dram
node_simulator -.->|"uses network model"| node_interconnect
node_dram -->|"uses channel state"| node_dramstate
node_dram -->|"uses command queue"| node_dramqueue
node_interconnect -.->|"dispatches traffic"| node_traffic
node_traffic -.->|"routes flits"| node_router
node_traffic -.->|"records statistics"| node_networkstats

click node_cli "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/helper/CommandLineParser.h"
click node_entry "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/main.cc"
click node_simulator "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Simulator.h"
click node_config "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Common.h"
click node_client "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/client/Client.cc"
click node_requestgen "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/RequestGenerator.h"
click node_model "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Model.cc"
click node_program "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/ModelProgram.cc"
click node_stage "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/StageProgram.cc"
click node_scheduler "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/scheduler/Scheduler.cc"
click node_operations "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/operations/Operation.cc"
click node_tensor "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/tensor/NPUTensor.cc"
click node_address "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/allocator/AddressAllocator.h"
click node_dram "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/neupims_controller.cc"
click node_dramstate "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/channel_state.h"
click node_dramqueue "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/neupims_command_queue.cc"
click node_interconnect "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/include/booksim2/Interconnect.hpp"
click node_traffic "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/GNNTrafficManager.cpp"
click node_router "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/routers/iq_router.cpp"
click node_networkstats "https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/stats.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_entry,node_simulator,node_config,node_client,node_requestgen,node_user toneBlue
class node_model,node_program,node_stage,node_scheduler,node_operations,node_tensor toneAmber
class node_address,node_dram,node_dramstate,node_dramqueue toneMint
class node_interconnect,node_traffic,node_router,node_networkstats toneRose
```

## Components

### Simulation runtime

- [CLI parsing](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/helper/CommandLineParser.h): `NeuPIMs/src/helper/CommandLineParser.h`
- [Program entry](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/main.cc): `NeuPIMs/src/main.cc`
- [Simulator](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Simulator.h): `NeuPIMs/src/Simulator.h`
- [Shared configuration](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Common.h): `NeuPIMs/src/Common.h`
- [Request client](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/client/Client.cc): `NeuPIMs/src/client/Client.cc`
- [Request generation](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/RequestGenerator.h): `NeuPIMs/src/RequestGenerator.h`

### Model execution

- [Model definition](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/Model.cc): `NeuPIMs/src/Model.cc`
- [Model program](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/ModelProgram.cc): `NeuPIMs/src/ModelProgram.cc`
- [Stage program](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/StageProgram.cc): `NeuPIMs/src/StageProgram.cc`
- [Scheduling](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/scheduler/Scheduler.cc): `NeuPIMs/src/scheduler/Scheduler.cc`
- [Inference operations](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/operations/Operation.cc): `NeuPIMs/src/operations/Operation.cc`
- [Tensor representations](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/tensor/NPUTensor.cc): `NeuPIMs/src/tensor/NPUTensor.cc`

### Memory simulation

- [Address allocation](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/src/allocator/AddressAllocator.h): `NeuPIMs/src/allocator/AddressAllocator.h`
- [DRAM controller](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/neupims_controller.cc): `NeuPIMs/extern/NewtonSim/src/neupims_controller.cc`
- [DRAM channel state](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/channel_state.h): `NeuPIMs/extern/NewtonSim/src/channel_state.h`
- [PIM command queue](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/NewtonSim/src/neupims_command_queue.cc): `NeuPIMs/extern/NewtonSim/src/neupims_command_queue.cc`

### Interconnect simulation

- [Interconnect API](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/include/booksim2/Interconnect.hpp): `NeuPIMs/extern/booksim/include/booksim2/Interconnect.hpp`
- [Traffic manager](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/GNNTrafficManager.cpp): `NeuPIMs/extern/booksim/src/GNNTrafficManager.cpp`
- [Input-queued router](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/routers/iq_router.cpp): `NeuPIMs/extern/booksim/src/routers/iq_router.cpp`
- [Network statistics](https://github.com/pankajn-git/neupims-project/blob/main/NeuPIMs/extern/booksim/src/stats.hpp): `NeuPIMs/extern/booksim/src/stats.hpp`

### Other components

- **Simulation user**

## Connections

- Simulation user → Program entry: starts
- Program entry → CLI parsing: parses options (evidence: `NeuPIMs/src/main.cc`)
- Program entry → Shared configuration: sets configuration (evidence: `NeuPIMs/src/main.cc`)
- Program entry → Inference operations: initializes operations (evidence: `NeuPIMs/src/main.cc`)
- Program entry → Simulator: constructs and runs (evidence: `NeuPIMs/src/main.cc`)
- Program entry → Model definition: creates and launches (evidence: `NeuPIMs/src/main.cc`)
- Program entry → Address allocation: initializes allocators (evidence: `NeuPIMs/src/main.cc`)
- Request client → Request generation: uses
- Scheduling → Model definition: uses model program
- Scheduling → Model program: uses
- Scheduling → Stage program: uses
- Scheduling → Tensor representations: uses tensors (evidence: `NeuPIMs/src/scheduler/Scheduler.cc`)
- Simulator → Request client: coordinates requests
- Simulator → Scheduling: dispatches work
- Simulator → DRAM controller: uses DRAM model
- Simulator → Interconnect API: uses network model
- DRAM controller → DRAM channel state: uses channel state
- DRAM controller → PIM command queue: uses command queue
- Interconnect API → Traffic manager: dispatches traffic (evidence: `NeuPIMs/extern/booksim/src/GNNTrafficManager.cpp`)
- Traffic manager → Input-queued router: routes flits
- Traffic manager → Network statistics: records statistics
