Struct Tensor 

pub struct Tensor { /* private fields */ }

Representation for a multidimensional array of numbers.

Tensors are used as data inputs to ML operations and are the basic datatype for the tensor-forge library.

Examples

let shape = vec![4, 4];
let data: Vec<f64> = (0..16).map(|x| x as f64).collect();
let tensor = Tensor::from_vec(shape, data);
assert!(tensor.is_ok());

Data will be stored in a contiguous array of IEEE 754 double-precision floating-point.

Implementations

impl Tensor

pub fn zeros(shape: impl Into<Vec<usize>>) -> Result<Tensor, TensorError>

Constructs a zero-filled Tensor of a given shape.

Use Tensor::from_vec to construct a tensor with data, or fill the tensor after a call to Tensor::data_mut.

Errors

• TensorError::InvalidShape if shape contains a zeroed dimension.
• TensorError::ShapeMismatch if shape contains a zeroed dimension.

Examples

let shape = vec![4, 4];
let tensor = Tensor::zeros(shape);
assert_eq!(tensor.unwrap().data(), [0_f64; 4 * 4]);

Data will be stored in a contiguous array of IEEE 754 double-precision floating-point.

pub fn from_vec( shape: impl Into<Vec<usize>>, data: Vec<f64>, ) -> Result<Tensor, TensorError>

Constructs a Tensor of the given dimensions in shape from the input data.

Errors

• TensorError::InvalidShape if shape contains a zeroed dimension.
• TensorError::ShapeMismatch if the data cannot fit into the tensor’s dimension.

Examples

// Example (toy) data
let data: Vec<f64> = (0..16).map(|x| x as f64).collect();
let shape = vec![4, 4];

let tensor = Tensor::from_vec(shape, data);
assert!(tensor.is_ok());

Tensor data can fit into multiple valid shapes. For example, the above data with 16 total elements can fit into an 8x2, 2x8, 1x16, or 16x1 tensor.

// Example (toy) data from above
let data: Vec<f64> = (0..16).map(|x| x as f64).collect();
let shape = vec![16, 1];

let tensor = Tensor::from_vec(shape, data);
assert!(tensor.is_ok());

Examples found in repository

examples/custom_kernel.rs (line 117)

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 88)

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 63)

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 124)

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 shape(&self) -> &[usize]

Returns the shape of this tensor.

Examples

let shape = vec![4, 4];
let tensor = Tensor::zeros(shape);
assert_eq!(tensor.unwrap().shape(), vec![4, 4]);

Examples found in repository

examples/custom_kernel.rs (line 64)

    fn compute(&self, inputs: &[&Tensor], output: &mut Tensor) -> Result<(), KernelError> {
        // Validate arity.
        //
        // The Add operation expects exactly two input tensors.
        if inputs.len() != 2 {
            return Err(KernelError::InvalidArguments);
        }

        // Validate shape agreement.
        //
        // Graph construction should already guarantee this for well-formed Add nodes,
        // but kernels may still validate assumptions defensively.
        let left = inputs[0];
        let right = inputs[1];

        if left.shape() != right.shape() || left.shape() != output.shape() {
            return Err(KernelError::InvalidArguments);
        }

        let left_data = left.data();
        let right_data = right.data();
        let output_data = output.data_mut();
        for i in 0..output_data.len() {
            output_data[i] = left_data[i] + right_data[i];
        }
        Ok(())
    }

pub fn numel(&self) -> usize

Returns the total number of elements in this tensor.

Examples

let shape = vec![4, 4];
let tensor = Tensor::zeros(shape);
assert_eq!(tensor.unwrap().numel(), 16);  // 4x4 = 16 elements

pub fn data(&self) -> &[f64]

Returns an immutable reference to the data in this tensor.

Examples

let shape = vec![4, 4];
let tensor = Tensor::zeros(shape);
assert_eq!(tensor.unwrap().data(), vec![0_f64; 4 * 4]);

Examples found in repository

examples/custom_kernel.rs (line 68)

    fn compute(&self, inputs: &[&Tensor], output: &mut Tensor) -> Result<(), KernelError> {
        // Validate arity.
        //
        // The Add operation expects exactly two input tensors.
        if inputs.len() != 2 {
            return Err(KernelError::InvalidArguments);
        }

        // Validate shape agreement.
        //
        // Graph construction should already guarantee this for well-formed Add nodes,
        // but kernels may still validate assumptions defensively.
        let left = inputs[0];
        let right = inputs[1];

        if left.shape() != right.shape() || left.shape() != output.shape() {
            return Err(KernelError::InvalidArguments);
        }

        let left_data = left.data();
        let right_data = right.data();
        let output_data = output.data_mut();
        for i in 0..output_data.len() {
            output_data[i] = left_data[i] + right_data[i];
        }
        Ok(())
    }

pub fn data_mut(&mut self) -> &mut [f64]

Returns a mutable reference to the data in this tensor.

Examples

let shape = vec![4, 4];
let mut tensor = Tensor::zeros(shape);
assert_eq!(tensor.unwrap().data_mut(), vec![0_f64; 4 * 4]);

Examples found in repository

examples/custom_kernel.rs (line 70)

    fn compute(&self, inputs: &[&Tensor], output: &mut Tensor) -> Result<(), KernelError> {
        // Validate arity.
        //
        // The Add operation expects exactly two input tensors.
        if inputs.len() != 2 {
            return Err(KernelError::InvalidArguments);
        }

        // Validate shape agreement.
        //
        // Graph construction should already guarantee this for well-formed Add nodes,
        // but kernels may still validate assumptions defensively.
        let left = inputs[0];
        let right = inputs[1];

        if left.shape() != right.shape() || left.shape() != output.shape() {
            return Err(KernelError::InvalidArguments);
        }

        let left_data = left.data();
        let right_data = right.data();
        let output_data = output.data_mut();
        for i in 0..output_data.len() {
            output_data[i] = left_data[i] + right_data[i];
        }
        Ok(())
    }

Trait Implementations

impl Debug for Tensor

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

Formats the value using the given formatter.