# nvlabs/alpasim architecture

> Architecture diagram of the GitHub repository nvlabs/alpasim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvlabs/alpasim
- Repository: https://github.com/nvlabs/alpasim

## Overview

AlpaSim is a modular autonomous-driving research simulator. A researcher configures a run, the runtime schedules closed-loop rollouts, and policy, traffic, physics, controller, and sensor-rendering services provide successive simulation results for evaluation. The graph also preserves configuration/deployment, plugin extensibility, and log replay as distinct capabilities. README descriptions and the file tree support the broad service map; sampled excerpts confirm portions of runtime orchestration, controller invocation, and evaluation aggregation, but not every service call, so uncertain wiring is omitted.

Main entry points: [`src/runtime/alpasim_runtime/event_loop.py`](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/event_loop.py) (Event loop), [`src/runtime/alpasim_runtime/worker/main.py`](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/worker/main.py) (Rollout worker), [`src/runtime/alpasim_runtime/services/renderer.py`](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/services/renderer.py) (Sensor rendering), [`src/eval/src/eval/runtime_evaluator.py`](https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/runtime_evaluator.py) (Runtime evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Run setup"]
  node_wizard["Configuration and deployment<br/>[wizard.py]"]
  node_plugins["Plugin registry<br/>[plugins.py]"]
  node_grpc["Service contracts<br/>[runtime.proto]"]
end

subgraph group_runtime["Simulation runtime"]
  node_daemon["Runtime daemon<br/>[engine.py]"]
  node_scheduler["Rollout scheduler<br/>[scheduler.py]"]
  node_worker["Rollout worker<br/>[main.py]"]
  node_eventloop["Event loop<br/>[event_loop.py]"]
  node_scene["Scene loading<br/>[scene_loader.py]"]
end

subgraph group_services["Simulation services"]
  node_policy["Driving policies<br/>[main.py]"]
  node_traffic["Traffic simulation<br/>[servicer.py]"]
  node_physics["Vehicle physics<br/>[server.py]"]
  node_controller["Controller and vehicle<br/>[system_manager.py]"]
  node_renderer["Sensor rendering<br/>[renderer.py]"]
end

subgraph group_results["Evaluation and replay"]
  node_eval["Runtime evaluation"]
  node_scorers["Metric scorers<br/>[base.py]"]
  node_aggregate["Result aggregation<br/>[main.py]"]
  node_replay["Log replay<br/>[asl_reader.py]"]
  node_asl[("Simulation logs<br/>[artifact.py]")]
end

node_researcher(("Researcher"))
node_nurec["NuRec renderer"]
node_videomodel["Video-model renderer"]

node_researcher -->|"configures"| node_wizard
node_wizard -->|"starts run"| node_daemon
node_plugins -->|"registers models"| node_policy
node_daemon -->|"submits rollouts"| node_scheduler
node_scheduler -->|"dispatches jobs"| node_worker
node_worker -->|"loads scene"| node_scene
node_worker -->|"runs rollout"| node_eventloop
node_eventloop -->|"requests trajectory"| node_policy
node_eventloop -->|"requests traffic"| node_traffic
node_eventloop -->|"requests physics"| node_physics
node_eventloop -->|"requests control"| node_controller
node_eventloop -->|"requests sensors"| node_renderer
node_renderer -.->|"renders with"| node_nurec
node_renderer -.->|"renders with"| node_videomodel
node_worker -->|"evaluates rollout"| node_eval
node_eval -->|"computes metrics"| node_scorers
node_eval -->|"writes artifacts"| node_asl
node_aggregate -->|"reads logs"| node_asl
node_researcher -->|"reviews results"| node_aggregate
node_replay -->|"reads recordings"| node_asl
node_grpc -->|"defines API"| node_daemon

click node_wizard "https://github.com/nvlabs/alpasim/blob/main/src/wizard/alpasim_wizard/wizard.py"
click node_plugins "https://github.com/nvlabs/alpasim/blob/main/src/plugins/alpasim_plugins/plugins.py"
click node_grpc "https://github.com/nvlabs/alpasim/blob/main/src/grpc/alpasim_grpc/v0/runtime.proto"
click node_daemon "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/daemon/engine.py"
click node_scheduler "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/daemon/scheduler.py"
click node_worker "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/worker/main.py"
click node_eventloop "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/event_loop.py"
click node_scene "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/scene_loader.py"
click node_policy "https://github.com/nvlabs/alpasim/blob/main/src/driver/src/alpasim_driver/main.py"
click node_traffic "https://github.com/nvlabs/alpasim/blob/main/src/trafficsim/alpasim_trafficsim/grpc/servicer.py"
click node_physics "https://github.com/nvlabs/alpasim/blob/main/src/physics/alpasim_physics/server.py"
click node_controller "https://github.com/nvlabs/alpasim/blob/main/src/controller/alpasim_controller/system_manager.py"
click node_renderer "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/services/renderer.py"
click node_eval "https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/runtime_evaluator.py"
click node_scorers "https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/scorers/base.py"
click node_aggregate "https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/aggregation/main.py"
click node_replay "https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/replay_services/asl_reader.py"
click node_asl "https://github.com/nvlabs/alpasim/blob/main/src/utils/alpasim_utils/artifact.py"

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_wizard,node_plugins,node_grpc toneBlue
class node_daemon,node_scheduler,node_worker,node_eventloop,node_scene toneAmber
class node_policy,node_traffic,node_physics,node_controller,node_renderer toneMint
class node_eval,node_scorers,node_aggregate,node_replay,node_asl toneRose
class node_researcher,node_nurec,node_videomodel toneIndigo
```

## Components

### Run setup

- [Configuration and deployment](https://github.com/nvlabs/alpasim/blob/main/src/wizard/alpasim_wizard/wizard.py): `src/wizard/alpasim_wizard/wizard.py`
- [Plugin registry](https://github.com/nvlabs/alpasim/blob/main/src/plugins/alpasim_plugins/plugins.py): `src/plugins/alpasim_plugins/plugins.py`
- [Service contracts](https://github.com/nvlabs/alpasim/blob/main/src/grpc/alpasim_grpc/v0/runtime.proto): `src/grpc/alpasim_grpc/v0/runtime.proto`

### Simulation runtime

- [Runtime daemon](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/daemon/engine.py): `src/runtime/alpasim_runtime/daemon/engine.py`
- [Rollout scheduler](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/daemon/scheduler.py): `src/runtime/alpasim_runtime/daemon/scheduler.py`
- [Rollout worker](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/worker/main.py): `src/runtime/alpasim_runtime/worker/main.py`
- [Event loop](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/event_loop.py): `src/runtime/alpasim_runtime/event_loop.py`
- [Scene loading](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/scene_loader.py): `src/runtime/alpasim_runtime/scene_loader.py`

### Simulation services

- [Driving policies](https://github.com/nvlabs/alpasim/blob/main/src/driver/src/alpasim_driver/main.py): `src/driver/src/alpasim_driver/main.py`
- [Traffic simulation](https://github.com/nvlabs/alpasim/blob/main/src/trafficsim/alpasim_trafficsim/grpc/servicer.py): `src/trafficsim/alpasim_trafficsim/grpc/servicer.py`
- [Vehicle physics](https://github.com/nvlabs/alpasim/blob/main/src/physics/alpasim_physics/server.py): `src/physics/alpasim_physics/server.py`
- [Controller and vehicle](https://github.com/nvlabs/alpasim/blob/main/src/controller/alpasim_controller/system_manager.py): `src/controller/alpasim_controller/system_manager.py`
- [Sensor rendering](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/services/renderer.py): `src/runtime/alpasim_runtime/services/renderer.py`

### Evaluation and replay

- [Runtime evaluation](https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/runtime_evaluator.py): `src/eval/src/eval/runtime_evaluator.py`
- [Metric scorers](https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/scorers/base.py): `src/eval/src/eval/scorers/base.py`
- [Result aggregation](https://github.com/nvlabs/alpasim/blob/main/src/eval/src/eval/aggregation/main.py): `src/eval/src/eval/aggregation/main.py`
- [Log replay](https://github.com/nvlabs/alpasim/blob/main/src/runtime/alpasim_runtime/replay_services/asl_reader.py): `src/runtime/alpasim_runtime/replay_services/asl_reader.py`
- [Simulation logs](https://github.com/nvlabs/alpasim/blob/main/src/utils/alpasim_utils/artifact.py): `src/utils/alpasim_utils/artifact.py`

### Other components

- **Researcher**
- **NuRec renderer**
- **Video-model renderer**

## Connections

- Researcher → Configuration and deployment: configures
- Configuration and deployment → Runtime daemon: starts run
- Plugin registry → Driving policies: registers models
- Runtime daemon → Rollout scheduler: submits rollouts
- Rollout scheduler → Rollout worker: dispatches jobs
- Rollout worker → Scene loading: loads scene
- Rollout worker → Event loop: runs rollout
- Event loop → Driving policies: requests trajectory
- Event loop → Traffic simulation: requests traffic
- Event loop → Vehicle physics: requests physics
- Event loop → Controller and vehicle: requests control
- Event loop → Sensor rendering: requests sensors
- Sensor rendering → NuRec renderer: renders with
- Sensor rendering → Video-model renderer: renders with
- Rollout worker → Runtime evaluation: evaluates rollout
- Runtime evaluation → Metric scorers: computes metrics
- Runtime evaluation → Simulation logs: writes artifacts
- Result aggregation → Simulation logs: reads logs
- Researcher → Result aggregation: reviews results
- Log replay → Simulation logs: reads recordings
- Service contracts → Runtime daemon: defines API