Struct Graph 

pub struct Graph { /* private fields */ }

A minimal compute-graph container for an ML runtime intermediate representation (IR).

A Graph owns a set of Nodes indexed by NodeId. Each node encodes:

• an operation kind (OpKind),
• a list of input dependencies (by NodeId), and
• the inferred output tensor shape.

This type currently supports constructing a graph via:

• Graph::input_node for source nodes, and
• op constructors like Graph::add, Graph::matmul, and Graph::relu.

Output nodes must be designated explicitly via Graph::set_output_node.

Examples

let mut g = Graph::new();
let x = g.input_node(vec![2, 3]);
let y = g.relu(x).unwrap();
g.set_output_node(y).unwrap();
assert_eq!(g.outputs().len(), 1);

Implementations

impl Graph

pub fn new() -> Self

Creates an empty graph with no nodes, inputs, or outputs.

Examples

let g = Graph::new();
assert_eq!(g.num_nodes(), 0);
assert!(g.inputs().is_empty());
assert!(g.outputs().is_empty());

Examples found in repository

examples/custom_kernel.rs (line 84)

fn main() {
    // Build a tiny graph:
    //
    //   out = add(a, b)
    //
    // The graph describes *what* should be computed, not how.
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create a custom registry.
    //
    // Start from an empty registry and explicitly register only the kernel(s)
    // needed by this graph.
    let mut registry = KernelRegistry::new();

    // Register our custom Add kernel.
    //
    // `register(...)` returns the previous mapping if one existed.
    let old = registry.register(OpKind::Add, Box::new(CustomAddKernel));
    assert!(
        old.is_none(),
        "First Add registration should not replace an existing kernel"
    );

    // Construct the executor with the custom registry.
    let exec = Executor::new(registry);

    // Bind runtime inputs.
    //
    // These are ordinary tensors supplied for the graph input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Execute the graph.
    //
    // During execution:
    // - the executor validates input bindings,
    // - walks the graph in topological order,
    // - sees an `OpKind::Add` node,
    // - looks up `OpKind::Add` in the registry,
    // - dispatches to `CustomAddKernel::compute(...)`.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/branching_graph.rs (line 47)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/addition_graph.rs (line 38)

fn main() {
    // Build the graph:
    //
    //   a ----\
    //          add ---> out
    //   b ----/
    //
    // Here `a` and `b` are graph input nodes. They do not yet have runtime values;
    // they only declare that the graph expects tensors of shape [2, 2].
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);

    // Add an operation node.
    //
    // `graph.add(a, b)` does not perform arithmetic immediately. It adds a new node to
    // the graph describing a future Add operation whose inputs are `a` and `b`.
    //
    // Shape validation happens here at graph-construction time. Since both inputs are
    // [2, 2], the resulting Add node is also [2, 2].
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    // Mark the node as an output. The executor will return a tensor for every node
    // designated as a graph output.
    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create runtime tensors for the graph input nodes.
    //
    // These must match the shapes declared by the corresponding input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Construct an executor with the default kernel registry.
    //
    // The registry determines which kernel implementation is used for each `OpKind`.
    // In this example, the default registry is expected to contain an Add kernel.
    let exec = Executor::new(KernelRegistry::default());

    // Execute the graph.
    //
    // The bindings are `(NodeId, Tensor)` pairs. Each input node in the graph must be
    // bound exactly once at runtime.
    //
    // Internally, the executor:
    // 1. validates the bindings,
    // 2. topologically orders the graph,
    // 3. executes non-input nodes using registered kernels,
    // 4. returns tensors for all declared output nodes.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/feedforward_neural_net.rs (line 47)

fn main() {
    let mut graph = Graph::new();

    let input_width = 3;
    let hidden_widths = [2, 2];
    let output_width = 2;
    let shape = vec![1, 4];

    // Create the input layer.
    //
    // Each input node declares that execution must provide a [1, 4] tensor for it.
    let mut current_layer: Vec<NodeId> = (0..input_width)
        .map(|_| graph.input_node(shape.clone()))
        .collect();

    let input_ids = current_layer.clone();

    // Build hidden layers iteratively.
    //
    // This loop is only in graph construction. The resulting graph is still a
    // feedforward DAG with no cycles.
    for &layer_width in &hidden_widths {
        let mut next_layer = Vec::with_capacity(layer_width);

        for _ in 0..layer_width {
            // Start accumulation with the first node of the current layer.
            let mut acc = current_layer[0];

            // Repeatedly add the remaining nodes from the current layer.
            //
            // Each `graph.add(...)` creates a new intermediate node.
            for &node in &current_layer[1..] {
                acc = graph
                    .add(acc, node)
                    .expect("Adding nodes in a layer should succeed");
            }

            // Apply a nonlinearity at the end of the layer computation.
            let out = graph
                .relu(acc)
                .expect("Applying ReLU after accumulation should succeed");

            next_layer.push(out);
        }

        current_layer = next_layer;
    }

    // Build the output layer the same way.
    let mut output_ids = Vec::with_capacity(output_width);

    for _ in 0..output_width {
        let mut acc = current_layer[0];

        for &node in &current_layer[1..] {
            acc = graph
                .add(acc, node)
                .expect("Adding nodes in the output layer should succeed");
        }

        let out = graph
            .relu(acc)
            .expect("Applying ReLU in the output layer should succeed");

        graph
            .set_output_node(out)
            .expect("Setting output node should succeed");

        output_ids.push(out);
    }

    // Bind concrete input tensors.
    //
    // As in the smaller examples, bindings are keyed by input-node `NodeId`.
    // The graph can be re-used with different runtime values.
    let bindings = vec![
        (
            input_ids[0],
            Tensor::from_vec(vec![1, 4], vec![1.0, -2.0, 3.0, -4.0])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[1],
            Tensor::from_vec(vec![1, 4], vec![0.5, 1.5, -2.5, 3.5])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[2],
            Tensor::from_vec(vec![1, 4], vec![10.0, -20.0, 30.0, -40.0])
                .expect("Tensor construction should succeed"),
        ),
    ];

    let exec = Executor::new(KernelRegistry::default());
    let outputs = exec
        .execute(&graph, bindings)
        .expect("Execution should succeed");

    for out in output_ids {
        let tensor = outputs
            .get(&out)
            .expect("Declared output should be present in executor results");

        println!("Computed output for node {:?}: {:?}", out, tensor);
    }
}

pub fn input_node(&mut self, shape: Vec<usize>) -> NodeId

Creates a new input node with the given tensor shape and returns its NodeId.

Input nodes have no dependencies and an output shape equal to shape.

Panics

Panics if a node ID collision is detected (an invariant violation indicating too many nodes have been allocated or ID generation is broken).

Examples

let mut g = Graph::new();
let x = g.input_node(vec![2, 3]);
assert!(g.node(x).is_ok());
assert_eq!(g.num_nodes(), 1);

Examples found in repository

examples/custom_kernel.rs (line 86)

fn main() {
    // Build a tiny graph:
    //
    //   out = add(a, b)
    //
    // The graph describes *what* should be computed, not how.
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create a custom registry.
    //
    // Start from an empty registry and explicitly register only the kernel(s)
    // needed by this graph.
    let mut registry = KernelRegistry::new();

    // Register our custom Add kernel.
    //
    // `register(...)` returns the previous mapping if one existed.
    let old = registry.register(OpKind::Add, Box::new(CustomAddKernel));
    assert!(
        old.is_none(),
        "First Add registration should not replace an existing kernel"
    );

    // Construct the executor with the custom registry.
    let exec = Executor::new(registry);

    // Bind runtime inputs.
    //
    // These are ordinary tensors supplied for the graph input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Execute the graph.
    //
    // During execution:
    // - the executor validates input bindings,
    // - walks the graph in topological order,
    // - sees an `OpKind::Add` node,
    // - looks up `OpKind::Add` in the registry,
    // - dispatches to `CustomAddKernel::compute(...)`.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/branching_graph.rs (line 55)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/addition_graph.rs (line 40)

fn main() {
    // Build the graph:
    //
    //   a ----\
    //          add ---> out
    //   b ----/
    //
    // Here `a` and `b` are graph input nodes. They do not yet have runtime values;
    // they only declare that the graph expects tensors of shape [2, 2].
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);

    // Add an operation node.
    //
    // `graph.add(a, b)` does not perform arithmetic immediately. It adds a new node to
    // the graph describing a future Add operation whose inputs are `a` and `b`.
    //
    // Shape validation happens here at graph-construction time. Since both inputs are
    // [2, 2], the resulting Add node is also [2, 2].
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    // Mark the node as an output. The executor will return a tensor for every node
    // designated as a graph output.
    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create runtime tensors for the graph input nodes.
    //
    // These must match the shapes declared by the corresponding input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Construct an executor with the default kernel registry.
    //
    // The registry determines which kernel implementation is used for each `OpKind`.
    // In this example, the default registry is expected to contain an Add kernel.
    let exec = Executor::new(KernelRegistry::default());

    // Execute the graph.
    //
    // The bindings are `(NodeId, Tensor)` pairs. Each input node in the graph must be
    // bound exactly once at runtime.
    //
    // Internally, the executor:
    // 1. validates the bindings,
    // 2. topologically orders the graph,
    // 3. executes non-input nodes using registered kernels,
    // 4. returns tensors for all declared output nodes.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/feedforward_neural_net.rs (line 58)

fn main() {
    let mut graph = Graph::new();

    let input_width = 3;
    let hidden_widths = [2, 2];
    let output_width = 2;
    let shape = vec![1, 4];

    // Create the input layer.
    //
    // Each input node declares that execution must provide a [1, 4] tensor for it.
    let mut current_layer: Vec<NodeId> = (0..input_width)
        .map(|_| graph.input_node(shape.clone()))
        .collect();

    let input_ids = current_layer.clone();

    // Build hidden layers iteratively.
    //
    // This loop is only in graph construction. The resulting graph is still a
    // feedforward DAG with no cycles.
    for &layer_width in &hidden_widths {
        let mut next_layer = Vec::with_capacity(layer_width);

        for _ in 0..layer_width {
            // Start accumulation with the first node of the current layer.
            let mut acc = current_layer[0];

            // Repeatedly add the remaining nodes from the current layer.
            //
            // Each `graph.add(...)` creates a new intermediate node.
            for &node in &current_layer[1..] {
                acc = graph
                    .add(acc, node)
                    .expect("Adding nodes in a layer should succeed");
            }

            // Apply a nonlinearity at the end of the layer computation.
            let out = graph
                .relu(acc)
                .expect("Applying ReLU after accumulation should succeed");

            next_layer.push(out);
        }

        current_layer = next_layer;
    }

    // Build the output layer the same way.
    let mut output_ids = Vec::with_capacity(output_width);

    for _ in 0..output_width {
        let mut acc = current_layer[0];

        for &node in &current_layer[1..] {
            acc = graph
                .add(acc, node)
                .expect("Adding nodes in the output layer should succeed");
        }

        let out = graph
            .relu(acc)
            .expect("Applying ReLU in the output layer should succeed");

        graph
            .set_output_node(out)
            .expect("Setting output node should succeed");

        output_ids.push(out);
    }

    // Bind concrete input tensors.
    //
    // As in the smaller examples, bindings are keyed by input-node `NodeId`.
    // The graph can be re-used with different runtime values.
    let bindings = vec![
        (
            input_ids[0],
            Tensor::from_vec(vec![1, 4], vec![1.0, -2.0, 3.0, -4.0])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[1],
            Tensor::from_vec(vec![1, 4], vec![0.5, 1.5, -2.5, 3.5])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[2],
            Tensor::from_vec(vec![1, 4], vec![10.0, -20.0, 30.0, -40.0])
                .expect("Tensor construction should succeed"),
        ),
    ];

    let exec = Executor::new(KernelRegistry::default());
    let outputs = exec
        .execute(&graph, bindings)
        .expect("Execution should succeed");

    for out in output_ids {
        let tensor = outputs
            .get(&out)
            .expect("Declared output should be present in executor results");

        println!("Computed output for node {:?}: {:?}", out, tensor);
    }
}

pub fn matmul( &mut self, left: NodeId, right: NodeId, ) -> Result<NodeId, GraphError>

Adds a matrix multiplication node left × right.

Shape rule (2-D):

• left.shape = [m, k]
• right.shape = [k, n]
• output shape is [m, n]

Errors

Returns GraphError::InvalidNodeId if either left or right does not exist in this graph.

Returns GraphError::ShapeMismatch if the inner dimensions do not match.

Examples

let mut g = Graph::new();
let a = g.input_node(vec![2, 3]);
let b = g.input_node(vec![3, 4]);

let c = g.matmul(a, b).unwrap();
assert!(g.node(c).is_ok());
assert_eq!(g.num_nodes(), 3);

// Mismatched inner dimension: [2,3] x [2,4] is invalid
let bad = g.input_node(vec![2, 4]);
assert!(matches!(g.matmul(a, bad).unwrap_err(), GraphError::ShapeMismatch));

Examples found in repository

examples/branching_graph.rs (line 72)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

pub fn add(&mut self, left: NodeId, right: NodeId) -> Result<NodeId, GraphError>

Adds an elementwise addition node left + right.

Shape rule:

• shape(left) == shape(right)

Errors

Returns GraphError::InvalidNodeId if either input does not exist in this graph.

Returns GraphError::ShapeMismatch if the shapes differ.

Examples

let mut g = Graph::new();
let a = g.input_node(vec![2, 3]);
let b = g.input_node(vec![2, 3]);

let c = g.add(a, b).unwrap();
assert!(g.node(c).is_ok());

let d = g.input_node(vec![2, 4]);
assert!(matches!(g.add(a, d).unwrap_err(), GraphError::ShapeMismatch));

Examples found in repository

examples/custom_kernel.rs (line 89)

fn main() {
    // Build a tiny graph:
    //
    //   out = add(a, b)
    //
    // The graph describes *what* should be computed, not how.
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create a custom registry.
    //
    // Start from an empty registry and explicitly register only the kernel(s)
    // needed by this graph.
    let mut registry = KernelRegistry::new();

    // Register our custom Add kernel.
    //
    // `register(...)` returns the previous mapping if one existed.
    let old = registry.register(OpKind::Add, Box::new(CustomAddKernel));
    assert!(
        old.is_none(),
        "First Add registration should not replace an existing kernel"
    );

    // Construct the executor with the custom registry.
    let exec = Executor::new(registry);

    // Bind runtime inputs.
    //
    // These are ordinary tensors supplied for the graph input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Execute the graph.
    //
    // During execution:
    // - the executor validates input bindings,
    // - walks the graph in topological order,
    // - sees an `OpKind::Add` node,
    // - looks up `OpKind::Add` in the registry,
    // - dispatches to `CustomAddKernel::compute(...)`.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/branching_graph.rs (line 77)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/addition_graph.rs (line 51)

fn main() {
    // Build the graph:
    //
    //   a ----\
    //          add ---> out
    //   b ----/
    //
    // Here `a` and `b` are graph input nodes. They do not yet have runtime values;
    // they only declare that the graph expects tensors of shape [2, 2].
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);

    // Add an operation node.
    //
    // `graph.add(a, b)` does not perform arithmetic immediately. It adds a new node to
    // the graph describing a future Add operation whose inputs are `a` and `b`.
    //
    // Shape validation happens here at graph-construction time. Since both inputs are
    // [2, 2], the resulting Add node is also [2, 2].
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    // Mark the node as an output. The executor will return a tensor for every node
    // designated as a graph output.
    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create runtime tensors for the graph input nodes.
    //
    // These must match the shapes declared by the corresponding input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Construct an executor with the default kernel registry.
    //
    // The registry determines which kernel implementation is used for each `OpKind`.
    // In this example, the default registry is expected to contain an Add kernel.
    let exec = Executor::new(KernelRegistry::default());

    // Execute the graph.
    //
    // The bindings are `(NodeId, Tensor)` pairs. Each input node in the graph must be
    // bound exactly once at runtime.
    //
    // Internally, the executor:
    // 1. validates the bindings,
    // 2. topologically orders the graph,
    // 3. executes non-input nodes using registered kernels,
    // 4. returns tensors for all declared output nodes.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/feedforward_neural_net.rs (line 79)

fn main() {
    let mut graph = Graph::new();

    let input_width = 3;
    let hidden_widths = [2, 2];
    let output_width = 2;
    let shape = vec![1, 4];

    // Create the input layer.
    //
    // Each input node declares that execution must provide a [1, 4] tensor for it.
    let mut current_layer: Vec<NodeId> = (0..input_width)
        .map(|_| graph.input_node(shape.clone()))
        .collect();

    let input_ids = current_layer.clone();

    // Build hidden layers iteratively.
    //
    // This loop is only in graph construction. The resulting graph is still a
    // feedforward DAG with no cycles.
    for &layer_width in &hidden_widths {
        let mut next_layer = Vec::with_capacity(layer_width);

        for _ in 0..layer_width {
            // Start accumulation with the first node of the current layer.
            let mut acc = current_layer[0];

            // Repeatedly add the remaining nodes from the current layer.
            //
            // Each `graph.add(...)` creates a new intermediate node.
            for &node in &current_layer[1..] {
                acc = graph
                    .add(acc, node)
                    .expect("Adding nodes in a layer should succeed");
            }

            // Apply a nonlinearity at the end of the layer computation.
            let out = graph
                .relu(acc)
                .expect("Applying ReLU after accumulation should succeed");

            next_layer.push(out);
        }

        current_layer = next_layer;
    }

    // Build the output layer the same way.
    let mut output_ids = Vec::with_capacity(output_width);

    for _ in 0..output_width {
        let mut acc = current_layer[0];

        for &node in &current_layer[1..] {
            acc = graph
                .add(acc, node)
                .expect("Adding nodes in the output layer should succeed");
        }

        let out = graph
            .relu(acc)
            .expect("Applying ReLU in the output layer should succeed");

        graph
            .set_output_node(out)
            .expect("Setting output node should succeed");

        output_ids.push(out);
    }

    // Bind concrete input tensors.
    //
    // As in the smaller examples, bindings are keyed by input-node `NodeId`.
    // The graph can be re-used with different runtime values.
    let bindings = vec![
        (
            input_ids[0],
            Tensor::from_vec(vec![1, 4], vec![1.0, -2.0, 3.0, -4.0])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[1],
            Tensor::from_vec(vec![1, 4], vec![0.5, 1.5, -2.5, 3.5])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[2],
            Tensor::from_vec(vec![1, 4], vec![10.0, -20.0, 30.0, -40.0])
                .expect("Tensor construction should succeed"),
        ),
    ];

    let exec = Executor::new(KernelRegistry::default());
    let outputs = exec
        .execute(&graph, bindings)
        .expect("Execution should succeed");

    for out in output_ids {
        let tensor = outputs
            .get(&out)
            .expect("Declared output should be present in executor results");

        println!("Computed output for node {:?}: {:?}", out, tensor);
    }
}

pub fn relu(&mut self, input: NodeId) -> Result<NodeId, GraphError>

Adds a ReLU node relu(input).

ReLU preserves shape: shape(output) == shape(input).

Errors

Returns GraphError::InvalidNodeId if input does not exist in this graph.

Examples

let mut g = Graph::new();
let x = g.input_node(vec![2, 3]);

let y = g.relu(x).unwrap();
assert!(g.node(y).is_ok());

// Using a NodeId from another graph is invalid
let mut other = Graph::new();
let foreign = other.input_node(vec![2, 3]);
assert!(matches!(g.relu(foreign).unwrap_err(), GraphError::InvalidNodeId));

Examples found in repository

examples/branching_graph.rs (line 62)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/feedforward_neural_net.rs (line 85)

fn main() {
    let mut graph = Graph::new();

    let input_width = 3;
    let hidden_widths = [2, 2];
    let output_width = 2;
    let shape = vec![1, 4];

    // Create the input layer.
    //
    // Each input node declares that execution must provide a [1, 4] tensor for it.
    let mut current_layer: Vec<NodeId> = (0..input_width)
        .map(|_| graph.input_node(shape.clone()))
        .collect();

    let input_ids = current_layer.clone();

    // Build hidden layers iteratively.
    //
    // This loop is only in graph construction. The resulting graph is still a
    // feedforward DAG with no cycles.
    for &layer_width in &hidden_widths {
        let mut next_layer = Vec::with_capacity(layer_width);

        for _ in 0..layer_width {
            // Start accumulation with the first node of the current layer.
            let mut acc = current_layer[0];

            // Repeatedly add the remaining nodes from the current layer.
            //
            // Each `graph.add(...)` creates a new intermediate node.
            for &node in &current_layer[1..] {
                acc = graph
                    .add(acc, node)
                    .expect("Adding nodes in a layer should succeed");
            }

            // Apply a nonlinearity at the end of the layer computation.
            let out = graph
                .relu(acc)
                .expect("Applying ReLU after accumulation should succeed");

            next_layer.push(out);
        }

        current_layer = next_layer;
    }

    // Build the output layer the same way.
    let mut output_ids = Vec::with_capacity(output_width);

    for _ in 0..output_width {
        let mut acc = current_layer[0];

        for &node in &current_layer[1..] {
            acc = graph
                .add(acc, node)
                .expect("Adding nodes in the output layer should succeed");
        }

        let out = graph
            .relu(acc)
            .expect("Applying ReLU in the output layer should succeed");

        graph
            .set_output_node(out)
            .expect("Setting output node should succeed");

        output_ids.push(out);
    }

    // Bind concrete input tensors.
    //
    // As in the smaller examples, bindings are keyed by input-node `NodeId`.
    // The graph can be re-used with different runtime values.
    let bindings = vec![
        (
            input_ids[0],
            Tensor::from_vec(vec![1, 4], vec![1.0, -2.0, 3.0, -4.0])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[1],
            Tensor::from_vec(vec![1, 4], vec![0.5, 1.5, -2.5, 3.5])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[2],
            Tensor::from_vec(vec![1, 4], vec![10.0, -20.0, 30.0, -40.0])
                .expect("Tensor construction should succeed"),
        ),
    ];

    let exec = Executor::new(KernelRegistry::default());
    let outputs = exec
        .execute(&graph, bindings)
        .expect("Execution should succeed");

    for out in output_ids {
        let tensor = outputs
            .get(&out)
            .expect("Declared output should be present in executor results");

        println!("Computed output for node {:?}: {:?}", out, tensor);
    }
}

pub fn set_output_node(&mut self, node: NodeId) -> Result<(), GraphError>

Marks node as an output node.

Graphs must have at least one output node to be meaningful for execution, and may have multiple outputs. This method does not create a new node or execute anything; it only records the provided node ID as an output.

Errors

Returns GraphError::InvalidNodeId if node does not exist in this graph.

Examples

let mut g = Graph::new();
let x = g.input_node(vec![2, 3]);
let y = g.relu(x).expect("No error should occur in the construction of this ReLU");

assert!(g.outputs().is_empty());
g.set_output_node(y).expect("We are passing a valid output node");
assert_eq!(g.outputs().contains(&y), true);
assert_eq!(g.outputs().len(), 1);

// A NodeId from another graph is invalid
let mut other = Graph::new();
let foreign = other.input_node(vec![2, 3]);
assert!(matches!(g.set_output_node(foreign).unwrap_err(), GraphError::InvalidNodeId));

Examples found in repository

examples/custom_kernel.rs (line 93)

fn main() {
    // Build a tiny graph:
    //
    //   out = add(a, b)
    //
    // The graph describes *what* should be computed, not how.
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create a custom registry.
    //
    // Start from an empty registry and explicitly register only the kernel(s)
    // needed by this graph.
    let mut registry = KernelRegistry::new();

    // Register our custom Add kernel.
    //
    // `register(...)` returns the previous mapping if one existed.
    let old = registry.register(OpKind::Add, Box::new(CustomAddKernel));
    assert!(
        old.is_none(),
        "First Add registration should not replace an existing kernel"
    );

    // Construct the executor with the custom registry.
    let exec = Executor::new(registry);

    // Bind runtime inputs.
    //
    // These are ordinary tensors supplied for the graph input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Execute the graph.
    //
    // During execution:
    // - the executor validates input bindings,
    // - walks the graph in topological order,
    // - sees an `OpKind::Add` node,
    // - looks up `OpKind::Add` in the registry,
    // - dispatches to `CustomAddKernel::compute(...)`.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/branching_graph.rs (line 81)

fn main() {
    let mut graph = Graph::new();

    // Declare graph inputs.
    //
    // The shapes here establish the legal runtime tensor shapes:
    //   a: [2, 3]
    //   b: [3, 2]
    //   c: [2, 2]
    let a = graph.input_node(vec![2, 3]);
    let b = graph.input_node(vec![3, 2]);
    let c = graph.input_node(vec![2, 2]);

    // Build intermediate operations.
    //
    // `relu(a)` preserves shape [2, 3].
    let ra = graph.relu(a).expect("Valid ReLU operation should succeed");

    // `relu(b)` preserves shape [3, 2].
    let rb = graph.relu(b).expect("Valid ReLU operation should succeed");

    // `matmul(ra, rb)` combines [2, 3] x [3, 2] -> [2, 2].
    //
    // This is a good example of graph-level validation preventing malformed graphs
    // before execution ever begins.
    let mm = graph
        .matmul(ra, rb)
        .expect("Valid matmul operation should succeed");

    // `add(mm, c)` adds two [2, 2] tensors and also yields [2, 2].
    let out = graph
        .add(mm, c)
        .expect("Valid add operation should succeed");

    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Bind concrete runtime values.
    //
    // These values are only examples; the graph structure is independent of them.
    // The same graph can be executed many times with different input tensors.
    let a_tensor = Tensor::from_vec(vec![2, 3], vec![-1.0, 2.0, -3.0, 4.0, -5.0, 6.0])
        .expect("Tensor construction should succeed");

    let b_tensor = Tensor::from_vec(vec![3, 2], vec![-7.0, 8.0, 9.0, -10.0, 11.0, 12.0])
        .expect("Tensor construction should succeed");

    let c_tensor = Tensor::from_vec(vec![2, 2], vec![0.5, 1.5, 2.5, 3.5])
        .expect("Tensor construction should succeed");

    let exec = Executor::new(KernelRegistry::default());

    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor), (c, c_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/addition_graph.rs (line 57)

fn main() {
    // Build the graph:
    //
    //   a ----\
    //          add ---> out
    //   b ----/
    //
    // Here `a` and `b` are graph input nodes. They do not yet have runtime values;
    // they only declare that the graph expects tensors of shape [2, 2].
    let mut graph = Graph::new();

    let a = graph.input_node(vec![2, 2]);
    let b = graph.input_node(vec![2, 2]);

    // Add an operation node.
    //
    // `graph.add(a, b)` does not perform arithmetic immediately. It adds a new node to
    // the graph describing a future Add operation whose inputs are `a` and `b`.
    //
    // Shape validation happens here at graph-construction time. Since both inputs are
    // [2, 2], the resulting Add node is also [2, 2].
    let out = graph
        .add(a, b)
        .expect("Adding valid input nodes should succeed");

    // Mark the node as an output. The executor will return a tensor for every node
    // designated as a graph output.
    graph
        .set_output_node(out)
        .expect("Setting output node should succeed");

    // Create runtime tensors for the graph input nodes.
    //
    // These must match the shapes declared by the corresponding input nodes.
    let a_tensor = Tensor::from_vec(vec![2, 2], vec![1.0, 2.0, 3.0, 4.0])
        .expect("Tensor construction should succeed");
    let b_tensor = Tensor::from_vec(vec![2, 2], vec![10.0, 20.0, 30.0, 40.0])
        .expect("Tensor construction should succeed");

    // Construct an executor with the default kernel registry.
    //
    // The registry determines which kernel implementation is used for each `OpKind`.
    // In this example, the default registry is expected to contain an Add kernel.
    let exec = Executor::new(KernelRegistry::default());

    // Execute the graph.
    //
    // The bindings are `(NodeId, Tensor)` pairs. Each input node in the graph must be
    // bound exactly once at runtime.
    //
    // Internally, the executor:
    // 1. validates the bindings,
    // 2. topologically orders the graph,
    // 3. executes non-input nodes using registered kernels,
    // 4. returns tensors for all declared output nodes.
    let outputs = exec
        .execute(&graph, vec![(a, a_tensor), (b, b_tensor)])
        .expect("Execution should succeed");

    let result = outputs
        .get(&out)
        .expect("Declared output should be present in executor results");

    println!("Computed output for node {:?}: {:?}", out, result);
}

examples/feedforward_neural_net.rs (line 111)

fn main() {
    let mut graph = Graph::new();

    let input_width = 3;
    let hidden_widths = [2, 2];
    let output_width = 2;
    let shape = vec![1, 4];

    // Create the input layer.
    //
    // Each input node declares that execution must provide a [1, 4] tensor for it.
    let mut current_layer: Vec<NodeId> = (0..input_width)
        .map(|_| graph.input_node(shape.clone()))
        .collect();

    let input_ids = current_layer.clone();

    // Build hidden layers iteratively.
    //
    // This loop is only in graph construction. The resulting graph is still a
    // feedforward DAG with no cycles.
    for &layer_width in &hidden_widths {
        let mut next_layer = Vec::with_capacity(layer_width);

        for _ in 0..layer_width {
            // Start accumulation with the first node of the current layer.
            let mut acc = current_layer[0];

            // Repeatedly add the remaining nodes from the current layer.
            //
            // Each `graph.add(...)` creates a new intermediate node.
            for &node in &current_layer[1..] {
                acc = graph
                    .add(acc, node)
                    .expect("Adding nodes in a layer should succeed");
            }

            // Apply a nonlinearity at the end of the layer computation.
            let out = graph
                .relu(acc)
                .expect("Applying ReLU after accumulation should succeed");

            next_layer.push(out);
        }

        current_layer = next_layer;
    }

    // Build the output layer the same way.
    let mut output_ids = Vec::with_capacity(output_width);

    for _ in 0..output_width {
        let mut acc = current_layer[0];

        for &node in &current_layer[1..] {
            acc = graph
                .add(acc, node)
                .expect("Adding nodes in the output layer should succeed");
        }

        let out = graph
            .relu(acc)
            .expect("Applying ReLU in the output layer should succeed");

        graph
            .set_output_node(out)
            .expect("Setting output node should succeed");

        output_ids.push(out);
    }

    // Bind concrete input tensors.
    //
    // As in the smaller examples, bindings are keyed by input-node `NodeId`.
    // The graph can be re-used with different runtime values.
    let bindings = vec![
        (
            input_ids[0],
            Tensor::from_vec(vec![1, 4], vec![1.0, -2.0, 3.0, -4.0])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[1],
            Tensor::from_vec(vec![1, 4], vec![0.5, 1.5, -2.5, 3.5])
                .expect("Tensor construction should succeed"),
        ),
        (
            input_ids[2],
            Tensor::from_vec(vec![1, 4], vec![10.0, -20.0, 30.0, -40.0])
                .expect("Tensor construction should succeed"),
        ),
    ];

    let exec = Executor::new(KernelRegistry::default());
    let outputs = exec
        .execute(&graph, bindings)
        .expect("Execution should succeed");

    for out in output_ids {
        let tensor = outputs
            .get(&out)
            .expect("Declared output should be present in executor results");

        println!("Computed output for node {:?}: {:?}", out, tensor);
    }
}

pub fn node(&self, id: NodeId) -> Result<&Node, GraphError>

Returns a shared reference to the node with the given NodeId.

Errors

Returns GraphError::InvalidNodeId if the node is not present in this graph.

Examples

let mut g = Graph::new();
let x = g.input_node(vec![1, 1]);
assert!(g.node(x).is_ok());

// A NodeId from another graph is invalid
let mut other = Graph::new();
let foreign = other.input_node(vec![1, 1]);
assert!(matches!(g.node(foreign).unwrap_err(), GraphError::InvalidNodeId));

pub fn num_nodes(&self) -> usize

Returns the total number of nodes stored in this graph.

Examples

let mut g = Graph::new();
assert_eq!(g.num_nodes(), 0);
let x = g.input_node(vec![2, 3]);
let y = g.relu(x).unwrap();
assert_eq!(g.num_nodes(), 2);

pub fn nodes(&self) -> impl Iterator<Item = &Node>

Returns the list of nodes.

Every inserted node is appended to this list (including op nodes created by Graph::add, Graph::matmul, and Graph::relu).

Examples

let mut g = Graph::new();
let a = g.input_node(vec![2, 3]);
let b = g.input_node(vec![2, 3]);
let c = g.add(a, b).unwrap();

// Includes both inputs and the derived node.
for node in g.nodes() {
    assert!([a, b, c].contains(&node.id));
}

pub fn inputs(&self) -> &[NodeId]

Returns the list of nodes recorded as inputs.

Examples

let mut g = Graph::new();
let a = g.input_node(vec![2, 3]);
let b = g.input_node(vec![2, 3]);
let c = g.add(a, b).unwrap();

// Only includes both inputs.
assert_eq!(g.inputs(), &[a, b]);

pub fn outputs(&self) -> &HashSet<NodeId>

Returns the list of nodes marked as outputs via Graph::set_output_node.

Examples

let mut g = Graph::new();
let x = g.input_node(vec![2, 3]);
let y = g.relu(x).expect("No error should occur in the construction of this ReLU");

assert!(g.outputs().is_empty());
g.set_output_node(y).expect("We are passing a valid output node");
assert!(g.outputs().contains(&y));
assert_eq!(g.outputs().len(), 1);

pub fn topo_sort(&self) -> Result<Vec<NodeId>, GraphError>

Computes a deterministic topological execution order (Kahn’s Algorithm) of all nodes in the graph.

Topological ordering guarantees that every node appears after all of its dependencies. This ordering is required for correct execution of the compute graph, since kernels must not execute before their input tensors are available.

The returned order includes every node in the graph exactly once.

Determinism

Determinism is guaranteed by enforcing a stable tie-breaking rule when multiple nodes are ready for execution. Nodes with zero remaining dependencies are processed in ascending NodeId order.

This ensures:

• Reproducible execution across runs
• Independence from hash seed randomization
• Stable ordering suitable for debugging and testing

Returns

A vector of NodeId representing the execution order.

The order satisfies the invariant:

For every node N:
    all inputs(N) appear before N in the returned vector

Errors

Returns GraphError::CycleDetected if the graph contains a cycle. Assuming normal API use, Graph methods will not allow cycle creation to ever occur.

Cycles violate compute graph semantics because no valid execution order exists.

Complexity

Time complexity: O(V + E) Space complexity: O(V + E)

where:

• V = number of nodes
• E = number of edges (dependencies)

Examples

let mut g = Graph::new();

let a = g.input_node(vec![2, 3]);
let b = g.relu(a).unwrap();
let c = g.relu(b).unwrap();

let order = g.topo_sort().unwrap();

let pos = |id| order.iter().position(|&x| x == id).unwrap();

assert!(pos(a) < pos(b));
assert!(pos(b) < pos(c));

Trait Implementations

impl Default for Graph

fn default() -> Self

Returns the “default value” for a type.