# darma-tasking/vt architecture

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

- Interactive diagram: https://gitdiagram.com/darma-tasking/vt
- Repository: https://github.com/darma-tasking/vt

## Overview

vt is a C++ active-messaging runtime for scientific applications, built on MPI. An application uses virtualized endpoints and messages; vt routes work independently of physical rank, manages distributed objects and collections, and can migrate work through automatic load balancing. The map includes communication, collectives, RDMA handles, and runtime coordination as major capabilities. Relationships are limited to README-documented behavior and sampled source references; several subsystems are represented by their exact enclosing directory because their implementation was not sampled.

Main entry points: [`src/vt/messaging/active.h`](https://github.com/darma-tasking/vt/blob/develop/src/vt/messaging/active.h) (Active messaging), [`src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc`](https://github.com/darma-tasking/vt/blob/develop/src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc) (Load balancing), [`src/vt/vrt/collection/migrate`](https://github.com/darma-tasking/vt/tree/develop/src/vt/vrt/collection/migrate) (Collection migration), [`src/vt/objgroup/manager.h`](https://github.com/darma-tasking/vt/blob/develop/src/vt/objgroup/manager.h) (Object groups)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime foundation"]
  node_context["Execution context<br/>[context.h]"]
  node_components["Runtime components<br/>[component_pack.h]"]
  node_scheduler["Task scheduler"]
end

subgraph group_messaging["Messaging and callbacks"]
  node_messages["Active messaging<br/>[active.h]"]
  node_handlers["Handler registry<br/>[handler.h]"]
  node_pipes["Callback pipes"]
end

subgraph group_virtual["Virtual entities"]
  node_objgroups["Object groups<br/>[manager.h]"]
  node_collections["Virtual collections<br/>[manager.impl.h]"]
  node_locations["Location management"]
  node_migration["Collection migration"]
end

subgraph group_coordination["Distributed coordination"]
  node_collectives["Collective operations"]
  node_groups["Distributed groups<br/>[group_manager.cc]"]
  node_rdma["RDMA handles<br/>[manager.h]"]
  node_phases["Phase tracking<br/>[phase_manager.cc]"]
end

subgraph group_balancing["Load balancing"]
  node_loadbalance["Load balancing<br/>[lb_manager.cc]"]
  node_lbdata["Load data"]
  node_replay["Workload replay<br/>[simulate_replay.cc]"]
end

node_app(("Scientific application"))
node_mpi(("MPI runtime"))

node_app -->|"sends work"| node_messages
node_mpi -->|"underlies transport"| node_messages
node_context -->|"uses rank context"| node_mpi
node_components -.->|"coordinates runtime"| node_context
node_messages -.->|"dispatches handlers"| node_handlers
node_messages -.->|"schedules work"| node_scheduler
node_pipes -->|"registers callbacks"| node_handlers
node_objgroups -->|"sends object messages"| node_messages
node_collections -.->|"routes virtual work"| node_locations
node_collections -->|"supports migration"| node_migration
node_locations -.->|"updates placement"| node_migration
node_collectives -.->|"operates across groups"| node_groups
node_objgroups -->|"creates handles"| node_rdma
node_phases -->|"hooks balancing"| node_loadbalance
node_loadbalance -->|"uses load data"| node_lbdata
node_loadbalance -->|"balances placement"| node_migration
node_replay -.->|"replays workloads"| node_loadbalance

click node_context "https://github.com/darma-tasking/vt/blob/develop/src/vt/context/context.h"
click node_components "https://github.com/darma-tasking/vt/blob/develop/src/vt/runtime/component/component_pack.h"
click node_scheduler "https://github.com/darma-tasking/vt/tree/develop/src/vt/scheduler"
click node_messages "https://github.com/darma-tasking/vt/blob/develop/src/vt/messaging/active.h"
click node_handlers "https://github.com/darma-tasking/vt/blob/develop/src/vt/handler/handler.h"
click node_pipes "https://github.com/darma-tasking/vt/tree/develop/src/vt/pipe"
click node_objgroups "https://github.com/darma-tasking/vt/blob/develop/src/vt/objgroup/manager.h"
click node_collections "https://github.com/darma-tasking/vt/blob/develop/src/vt/vrt/collection/manager.impl.h"
click node_locations "https://github.com/darma-tasking/vt/tree/develop/src/vt/topos/location"
click node_migration "https://github.com/darma-tasking/vt/tree/develop/src/vt/vrt/collection/migrate"
click node_collectives "https://github.com/darma-tasking/vt/tree/develop/src/vt/collective"
click node_groups "https://github.com/darma-tasking/vt/blob/develop/src/vt/group/group_manager.cc"
click node_rdma "https://github.com/darma-tasking/vt/blob/develop/src/vt/rdmahandle/manager.h"
click node_phases "https://github.com/darma-tasking/vt/blob/develop/src/vt/phase/phase_manager.cc"
click node_loadbalance "https://github.com/darma-tasking/vt/blob/develop/src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc"
click node_lbdata "https://github.com/darma-tasking/vt/tree/develop/src/vt/vrt/collection/balance"
click node_replay "https://github.com/darma-tasking/vt/blob/develop/tools/workload_replay/simulate_replay.cc"

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_context,node_components,node_scheduler toneBlue
class node_messages,node_handlers,node_pipes toneAmber
class node_objgroups,node_collections,node_locations,node_migration toneMint
class node_collectives,node_groups,node_rdma,node_phases toneRose
class node_loadbalance,node_lbdata,node_replay,node_app,node_mpi toneIndigo
```

## Components

### Runtime foundation

- [Execution context](https://github.com/darma-tasking/vt/blob/develop/src/vt/context/context.h): `src/vt/context/context.h`
- [Runtime components](https://github.com/darma-tasking/vt/blob/develop/src/vt/runtime/component/component_pack.h): `src/vt/runtime/component/component_pack.h`
- [Task scheduler](https://github.com/darma-tasking/vt/tree/develop/src/vt/scheduler): `src/vt/scheduler`

### Messaging and callbacks

- [Active messaging](https://github.com/darma-tasking/vt/blob/develop/src/vt/messaging/active.h): `src/vt/messaging/active.h`
- [Handler registry](https://github.com/darma-tasking/vt/blob/develop/src/vt/handler/handler.h): `src/vt/handler/handler.h`
- [Callback pipes](https://github.com/darma-tasking/vt/tree/develop/src/vt/pipe): `src/vt/pipe`

### Virtual entities

- [Object groups](https://github.com/darma-tasking/vt/blob/develop/src/vt/objgroup/manager.h): `src/vt/objgroup/manager.h`
- [Virtual collections](https://github.com/darma-tasking/vt/blob/develop/src/vt/vrt/collection/manager.impl.h): `src/vt/vrt/collection/manager.impl.h`
- [Location management](https://github.com/darma-tasking/vt/tree/develop/src/vt/topos/location): `src/vt/topos/location`
- [Collection migration](https://github.com/darma-tasking/vt/tree/develop/src/vt/vrt/collection/migrate): `src/vt/vrt/collection/migrate`

### Distributed coordination

- [Collective operations](https://github.com/darma-tasking/vt/tree/develop/src/vt/collective): `src/vt/collective`
- [Distributed groups](https://github.com/darma-tasking/vt/blob/develop/src/vt/group/group_manager.cc): `src/vt/group/group_manager.cc`
- [RDMA handles](https://github.com/darma-tasking/vt/blob/develop/src/vt/rdmahandle/manager.h): `src/vt/rdmahandle/manager.h`
- [Phase tracking](https://github.com/darma-tasking/vt/blob/develop/src/vt/phase/phase_manager.cc): `src/vt/phase/phase_manager.cc`

### Load balancing

- [Load balancing](https://github.com/darma-tasking/vt/blob/develop/src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc): `src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc`
- [Load data](https://github.com/darma-tasking/vt/tree/develop/src/vt/vrt/collection/balance): `src/vt/vrt/collection/balance`
- [Workload replay](https://github.com/darma-tasking/vt/blob/develop/tools/workload_replay/simulate_replay.cc): `tools/workload_replay/simulate_replay.cc`

### Other components

- **Scientific application**
- **MPI runtime**

## Connections

- Scientific application → Active messaging: sends work
- MPI runtime → Active messaging: underlies transport
- Execution context → MPI runtime: uses rank context (evidence: `src/vt/context/context.h`)
- Runtime components → Execution context: coordinates runtime (evidence: `src/vt/context/context.h`)
- Active messaging → Handler registry: dispatches handlers
- Active messaging → Task scheduler: schedules work
- Callback pipes → Handler registry: registers callbacks (evidence: `src/vt/pipe/pipe_manager_tl.impl.h`)
- Object groups → Active messaging: sends object messages (evidence: `src/vt/objgroup/manager.h`)
- Virtual collections → Location management: routes virtual work (evidence: `src/vt/vrt/collection/manager.impl.h`)
- Virtual collections → Collection migration: supports migration (evidence: `src/vt/vrt/collection/manager.impl.h`)
- Location management → Collection migration: updates placement
- Collective operations → Distributed groups: operates across groups (evidence: `src/vt/group/group_manager.cc`)
- Object groups → RDMA handles: creates handles
- Phase tracking → Load balancing: hooks balancing
- Load balancing → Load data: uses load data (evidence: `src/vt/vrt/collection/balance/lb_invoke/lb_manager.cc`)
- Load balancing → Collection migration: balances placement
- Workload replay → Load balancing: replays workloads
