Last updated: 2026-09-07

Decode Planning

Compute Graph

Represent decode work as a dependency graph that can be topologically ordered.

Graph builders use this module to describe fused operations, dependencies, and dispatch metadata before any Vulkan command recording happens.

12 exports 21 methods src/compute/graph.zig

12 exports shown

enum

ExecDomain

pub const ExecDomain = enum

Where a graph node executes: GPU compute, GPU transfer, or CPU host.

src/compute/graph.zig:10

enum

BottleneckKind

pub const BottleneckKind = enum

Classification of the dominant performance bottleneck for a graph node.

src/compute/graph.zig:20

struct

HardwareInfo

pub const HardwareInfo = struct

Hardware parameters used by bottleneck and utilization heuristics.

src/compute/graph.zig:38

enum

OpType

pub const OpType = enum

Operation types that a compute graph node can represent.

Each variant maps to one GPU shader dispatch or fused kernel invocation during decode-time execution.

src/compute/graph.zig:53

struct

Node

pub const Node = struct

A single operation node in the compute dependency graph.

Each node carries dispatch metadata (workgroups, push constants) and dependency edges so the graph can be topologically sorted before recording.

src/compute/graph.zig:108

struct

Edge

pub const Edge = struct

Directed dependency edge between two graph nodes.

src/compute/graph.zig:157

struct

OpCount

pub const OpCount = struct

Count of nodes that share the same operation type.

src/compute/graph.zig:165

struct

CriticalPathNode

pub const CriticalPathNode = struct

Critical-path node annotated with its dependency depth.

src/compute/graph.zig:173

struct

NodeAnalysis

pub const NodeAnalysis = struct

Per-node structural metrics derived from the dependency graph.

src/compute/graph.zig:185

struct

Hotspot

pub const Hotspot = struct

A node ranked among the top contributors to estimated decode time.

src/compute/graph.zig:241

struct

GraphAnalysis

pub const GraphAnalysis = struct

Computed summary of the graph structure used by visualization and debugging tools.

src/compute/graph.zig:265

Methods

method

GraphAnalysis.deinit

pub fn deinit(self: *GraphAnalysis) void

Release the arrays allocated for the analysis result.

Parameters

self: Graph analysis to tear down in place.

src/compute/graph.zig:315

struct

Graph

pub const Graph = struct

Static compute graph for a transformer layer or full decode pass.

src/compute/graph.zig:408

Methods

method

Graph.init

pub fn init(allocator: std.mem.Allocator, name: []const u8) Graph

Initialize an empty graph with a human-readable name.

Parameters

allocator: Allocator used for node storage.
name: Debug name for logging and diagnostics.

Returns

A graph ready to accept nodes and dependencies.

src/compute/graph.zig:424

method

Graph.deinit

pub fn deinit(self: *Graph) void

Release all graph nodes owned by the graph.

Parameters

self: Graph to tear down in place.

src/compute/graph.zig:433

method

Graph.addNode

pub fn addNode(self: *Graph, op: OpType, name: []const u8) !u32

Append a node to the graph and assign it the next dense node ID.

Parameters

self: Graph to append to.
op: Operation kind represented by the new node.
name: Human-readable node label used in logs and diagnostics.

Returns

The node ID assigned to the appended node.

Notes

IDs are stable for the lifetime of the graph and match insertion order.

src/compute/graph.zig:445

method

Graph.setInputs

pub fn setInputs(self: *Graph, node_id: u32, inputs: []const u32) void

Set the input buffer table indices consumed by a node.

Parameters

self: Graph containing the node to update.
node_id: ID of the node whose inputs should be overwritten.
inputs: Buffer table indices consumed in shader binding order.

Notes

The slice is copied into the node's fixed-size input array.

src/compute/graph.zig:479

method

Graph.setOutput

pub fn setOutput(self: *Graph, node_id: u32, output: u32) void

Set the output buffer table index produced by a node.

Parameters

self: Graph containing the node to update.
node_id: ID of the node whose output should be overwritten.
output: Buffer table index produced by the node.

src/compute/graph.zig:491

method

Graph.setWorkgroups

pub fn setWorkgroups(self: *Graph, node_id: u32, x: u32, y: u32, z: u32) void

Set the workgroup dimensions that should be used when dispatching a node.

Parameters

self: Graph containing the node to update.
node_id: ID of the node whose dispatch dimensions should be overwritten.
x: Workgroup count in the X dimension.
y: Workgroup count in the Y dimension.
z: Workgroup count in the Z dimension.

src/compute/graph.zig:501

method

Graph.setLayerIndex

pub fn setLayerIndex(self: *Graph, node_id: u32, layer_index: ?u32) void

Assign a transformer layer index to a node for per-layer diagnostics.

src/compute/graph.zig:506

method

Graph.setExecDomain

pub fn setExecDomain(self: *Graph, node_id: u32, domain: ExecDomain) void

Override the execution domain for a node (defaults to `gpu_compute`).

src/compute/graph.zig:511

method

Graph.setThreadsPerWorkgroup

pub fn setThreadsPerWorkgroup(self: *Graph, node_id: u32, threads_per_workgroup: u32) void

Set the number of threads per workgroup for occupancy estimates.

src/compute/graph.zig:516

method

Graph.setCostEstimate

pub fn setCostEstimate(self: *Graph, node_id: u32, read_bytes: u64, write_bytes: u64, weight_bytes: u64, flops: u64) void

Attach byte-traffic and FLOP cost estimates used by the bottleneck heuristics.

Parameters

self: Graph containing the node to update.
node_id: ID of the node whose cost estimates should be overwritten.
read_bytes: Estimated activation bytes read per dispatch.
write_bytes: Estimated bytes written per dispatch.
weight_bytes: Estimated weight/tensor payload bytes streamed per dispatch.
flops: Approximate floating-point operations performed per dispatch.

src/compute/graph.zig:527

method

Graph.setHostSync

pub fn setHostSync(self: *Graph, node_id: u32, requires_host_sync: bool) void

Mark whether a node requires host-visible synchronization or readback.

src/compute/graph.zig:536

method

Graph.setNote

pub fn setNote(self: *Graph, node_id: u32, note: ?[]const u8) void

Attach an optional static diagnostic note to a node.

src/compute/graph.zig:541

method

Graph.setAssumedDecodeSeqLen

pub fn setAssumedDecodeSeqLen(self: *Graph, assumed_decode_seq_len: u32) void

Record the sequence length assumed when building decode-time cost estimates.

src/compute/graph.zig:546

method

Graph.setHardwareContext

pub fn setHardwareContext(self: *Graph, hardware: HardwareInfo) void

Provide hardware parameters used by occupancy and bandwidth heuristics.

src/compute/graph.zig:551

method

Graph.addDependency

pub fn addDependency(self: *Graph, node_id: u32, depends_on: u32) void

Declare that one node must execute after another.

Parameters

self: Graph containing both nodes.
node_id: Node that depends on `depends_on`.
depends_on: Node that must run first.

Notes

Cycles are not rejected here; `topologicalOrder()` detects them later.

src/compute/graph.zig:560

method

Graph.topologicalOrder

pub fn topologicalOrder(self: *const Graph, allocator: std.mem.Allocator) ![]u32

Compute a valid execution order for the current dependency graph.

Parameters

self: Graph to sort.
allocator: Allocator used for temporary in-degree tracking and the returned order slice.

Returns

Node IDs in a valid execution order, or `error.CyclicDependency` when the graph contains a cycle.

src/compute/graph.zig:570

method

Graph.nodeCount

pub fn nodeCount(self: *const Graph) usize

Return the number of nodes currently stored in the graph.

Parameters

self: Graph to inspect.

Returns

The number of appended nodes.

src/compute/graph.zig:625

method

Graph.analyze

pub fn analyze(self: *const Graph, allocator: std.mem.Allocator) !GraphAnalysis

Analyze dependency structure for visualization and optimization work.

Parameters

self: Graph to inspect.
allocator: Allocator used for the returned analysis arrays.

Returns

A GraphAnalysis containing op counts, edges, node depths, and the longest dependency chain.

src/compute/graph.zig:633

method

Graph.writeJsonReport

pub fn writeJsonReport(self: *const Graph, writer: *std.Io.Writer, allocator: std.mem.Allocator) !void

Serialize a graph-analysis JSON payload suitable for custom viewers and scripts.

Parameters

self: Graph to inspect and serialize.
writer: Destination writer for the JSON payload.
allocator: Allocator used for temporary analysis storage.

src/compute/graph.zig:944

method

Graph.writeDot

pub fn writeDot(self: *const Graph, writer: *std.Io.Writer, allocator: std.mem.Allocator) !void

Serialize the graph as Graphviz DOT for quick local rendering.

Parameters

self: Graph to inspect and serialize.
writer: Destination writer for the DOT payload.
allocator: Allocator used for temporary analysis storage.

src/compute/graph.zig:979