Struct ExecutionGraph 

pub struct ExecutionGraph { /* private fields */ }

Execution path graph for tracking brick → kernel → PTX relationships.

PAR-201: Captures the full execution hierarchy for profiling analysis.

Example

use trueno::brick::{ExecutionGraph, ExecutionNode, EdgeType};

let mut graph = ExecutionGraph::new();

// Add layer scope
let layer_id = graph.add_node(ExecutionNode::Layer { index: 0 });

// Add brick within layer
let brick_id = graph.add_node(ExecutionNode::Brick {
    id: BrickId::QkvProjection,
    timing_ns: 1000,
    elements: 4096,
});
graph.add_edge(layer_id, brick_id, EdgeType::Contains);

// Add kernel launched by brick
let kernel_id = graph.add_node(ExecutionNode::Kernel {
    name: "batched_q4k_gemv".into(),
    ptx_hash: 0x7a3b1c2d,
    grid: (32, 1, 1),
    block: (256, 1, 1),
    shared_mem: 4096,
});
graph.add_edge(brick_id, kernel_id, EdgeType::Launches);

// Export to trueno-graph for analysis
#[cfg(feature = "execution-graph")]
let csr = graph.to_csr();

Implementations

impl ExecutionGraph

pub fn critical_path(&self) -> (Vec<ExecutionNodeId>, u64)

Compute critical path through execution graph using longest-path algorithm.

Returns (critical_path_nodes, total_time_ns). The critical path represents the longest chain of dependencies that determines total execution time.

Reference: Graham et al. (1979) “Scheduling Algorithms for Multi-Processor Systems”

pub fn compute_slack(&self) -> HashMap<ExecutionNodeId, u64>

Compute slack for each node (how much it can be delayed without affecting total time).

Returns map from node ID to slack in nanoseconds. Nodes on critical path have slack = 0.

pub fn roofline_distance( &self, peak_tflops: f32, peak_bandwidth_gb_s: f32, ) -> HashMap<ExecutionNodeId, f32>

Compute roofline distance for kernel nodes.

Returns map from kernel node ID to distance from roofline (0.0 = optimal). Distance = 1.0 - min(achieved/peak_compute, achieved/peak_bandwidth).

Reference: Williams et al. (2009) “Roofline: An Insightful Visual Performance Model”

pub fn detect_ping_pong(&self) -> Vec<(ExecutionNodeId, ExecutionNodeId)>

Detect ping-pong memory transfer patterns (wasteful H2D followed by D2H).

Returns pairs of transfer node IDs that exhibit ping-pong behavior.

pub fn critical_path_summary(&self) -> String

Get critical path analysis summary as formatted string.

impl ExecutionGraph

pub fn new() -> Self

Create a new empty execution graph.

pub fn add_node(&mut self, node: ExecutionNode) -> ExecutionNodeId

Add a node to the graph, returning its ID.

pub fn add_edge( &mut self, src: ExecutionNodeId, dst: ExecutionNodeId, edge_type: EdgeType, )

Add an edge between two nodes.

pub fn add_weighted_edge( &mut self, src: ExecutionNodeId, dst: ExecutionNodeId, edge_type: EdgeType, weight: f32, )

Add an edge with a weight.

pub fn push_scope(&mut self, node: ExecutionNode) -> ExecutionNodeId

Push a scope for hierarchical recording. All subsequent nodes will be children of this scope.

pub fn pop_scope(&mut self) -> Option<ExecutionNodeId>

Pop the current scope.

pub fn current_scope(&self) -> Option<ExecutionNodeId>

Get the current scope (if any).

pub fn add_node_in_scope(&mut self, node: ExecutionNode) -> ExecutionNodeId

Add a node under the current scope.

pub fn record_kernel_launch( &mut self, name: &str, ptx_hash: u64, grid: (u32, u32, u32), block: (u32, u32, u32), shared_mem: u32, ) -> ExecutionNodeId

Record a kernel launch under the current scope.

pub fn record_kernel_launch_with_metrics( &mut self, name: &str, ptx_hash: u64, grid: (u32, u32, u32), block: (u32, u32, u32), shared_mem: u32, timing_ns: u64, arithmetic_intensity: f32, achieved_tflops: f32, ) -> ExecutionNodeId

Record a kernel launch with roofline metrics (Phase 9).

pub fn record_transfer( &mut self, src: &str, dst: &str, bytes: u64, direction: TransferDirection, timing_ns: Option<u64>, ) -> ExecutionNodeId

Record a memory transfer (Phase 9: data movement topology).

pub fn add_dependency(&mut self, from: ExecutionNodeId, to: ExecutionNodeId)

Add a dependency edge for critical path analysis (Phase 9).

pub fn node(&self, id: ExecutionNodeId) -> Option<&ExecutionNode>

Get a node by ID.

pub fn node_by_name( &self, name: &str, ) -> Option<(ExecutionNodeId, &ExecutionNode)>

Get a node by name.

pub fn nodes(&self) -> &[ExecutionNode]

Get all nodes.

pub fn edges(&self) -> &[ExecutionEdge]

Get all edges.

pub fn num_nodes(&self) -> usize

Number of nodes.

pub fn num_edges(&self) -> usize

Number of edges.

pub fn outgoing_edges( &self, node: ExecutionNodeId, ) -> impl Iterator<Item = &ExecutionEdge>

Get outgoing edges for a node.

pub fn incoming_edges( &self, node: ExecutionNodeId, ) -> impl Iterator<Item = &ExecutionEdge>

Get incoming edges for a node.

pub fn kernel_nodes( &self, ) -> impl Iterator<Item = (ExecutionNodeId, &ExecutionNode)>

Find all kernel nodes.

pub fn slowest_kernel(&self) -> Option<(ExecutionNodeId, &ExecutionNode, u64)>

Find the slowest kernel (by parent brick timing).

pub fn clear(&mut self)

Clear the graph.

pub fn is_scope_balanced(&self) -> bool

Check if scope stack is balanced (empty).

impl ExecutionGraph

pub fn to_dot(&self) -> String

Export to DOT format for Graphviz visualization.

pub fn to_csr(&self) -> CsrGraph

Export to trueno-graph CsrGraph format.

pub fn to_tree_node(&self) -> TreeNode

Convert to presentar-terminal TreeNode for TUI visualization.

PAR-201: Renders the execution graph as a collapsible tree in the terminal.

pub fn to_ascii_tree(&self) -> String

Render graph to ASCII tree string (headless mode for testing/automation).

PAR-201: Zero-dependency tree visualization for CI/CD, logging, and snapshot tests.

Trait Implementations

impl Debug for ExecutionGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ExecutionGraph

fn default() -> ExecutionGraph

Returns the “default value” for a type.