Numerical Tensor API

Complete reference for the numerical tensor operations API endpoint, including request formats, operations, and performance considerations.

Endpoint Overview

The Numerical Tensor API endpoint is designed for performing tensor operations with concrete numeric data. It leverages NumPy for efficient computation of numerical results. This endpoint is ideal for when you need to perform calculations with actual numbers rather than symbolic expressions.

POST /api/tensors/numerical/

All requests and responses use JSON format. The numerical API focuses on high-performance computation and is suitable for data processing, scientific computing, and machine learning applications.

Request Format

The JSON request to the numerical endpoint follows a similar structure to the symbolic endpoint, but with concrete numeric values instead of symbolic expressions. The core fields are:

Required Fields

operation (string): The type of tensor operation to perform (e.g., "add", "multiply", "matmul", etc.)
operands (array): An array of tensor objects involved in the operation

Tensor Object Structure

name (string, optional): A label for the tensor (e.g., "A", "B")
shape (array of integers): The dimensions of the tensor (e.g., [2, 2] for a 2×2 matrix)
values (nested array): The actual numeric data for the tensor
dtype (string, optional): The data type of the numbers (e.g., "float64", "int32")

Optional Fields

options (object): Additional parameters for specific operations (e.g., axis for reduction operations)

Supported Operations

The Numerical Tensor API supports a wide range of operations for numeric tensor manipulation. Here are the key operations:

add

Add two tensors of the same shape element-wise.

{ "operation": "add", "operands": [ { "name": "A", "shape": [2, 2], "values": [[1.0, 2.0], [3.0, 4.0]] }, { "name": "B", "shape": [2, 2], "values": [[5.0, 6.0], [7.0, 8.0]] } ] }

matmul

Perform matrix multiplication between compatible tensors.

{ "operation": "matmul", "operands": [ { "name": "A", "shape": [2, 3], "values": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] }, { "name": "B", "shape": [3, 2], "values": [[7.0, 8.0], [9.0, 10.0], [11.0, 12.0]] } ] }

contract

Contract indices of tensors, generalizing matrix multiplication to higher dimensions.

{ "operation": "contract", "operands": [ { "name": "T1", "shape": [2, 3, 4] }, { "name": "T2", "shape": [4, 3, 5] } ], "subscripts": "ijk,kjl->il" }

sum

Sum elements along a specified axis.

{ "operation": "sum", "tensor": { "name": "A", "shape": [3, 3], "values": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0], [7.0, 8.0, 9.0]] }, "axis": 0 }

apply

Apply a function to each element of a tensor.

{ "operation": "apply", "function": "exp", "tensor": { "name": "A", "shape": [2, 2], "values": [[0.0, 1.0], [2.0, 3.0]] } }

reshape

Change the shape of a tensor without changing its data.

{ "operation": "reshape", "tensor": { "name": "A", "shape": [2, 3], "values": [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]] }, "new_shape": [3, 2] }

zeros / ones

Create tensors filled with zeros or ones.

{ "operation": "zeros", "tensor": { "name": "Z", "shape": [3, 3], "dtype": "float32" } }

random

Create tensors with random values.

{ "operation": "random", "tensor": { "name": "R", "shape": [4, 4], "distribution": "uniform", "range": [0, 1], "dtype": "float64" } }

Response Format

The response from the numerical API will be a JSON object containing the result of the operation. The typical fields in the response include:

result: The resulting tensor with its shape and numeric values
operation: Echo of the operation that was performed
elapsed_time (optional): Performance information about how long the computation took
error (optional): Present only if an error occurred, with an explanation

Example Response

200 OK { "operation": "matmul", "result": { "shape": [2, 2], "values": [[ 58, 64 ], [ 139, 154 ]] } }

Error Handling

The API will perform validation on requests and return appropriate error responses for various conditions:

400 Bad Request

Returned when the request is invalid or missing required fields:

{ "error": "Invalid request format: 'operands' field is required." }

Shape Mismatch

Returned when tensor shapes are incompatible for the requested operation:

{ "error": "Cannot multiply tensor of shape [2,3] with tensor of shape [4,2]." }

Data Type Issues

Returned when non-numeric data is found in values:

{ "error": "Expected numeric value, received string at position [1,2]." }

Computational Errors

Returned for operations that lead to mathematical errors:

{ "error": "Division by zero encountered in calculation." }

Performance Considerations

When using the Numerical Tensor API, consider these performance optimization strategies:

Data Types

Choose appropriate data types for your tensors. Lower precision types (e.g., float32) consume less memory and may compute faster than higher precision types (e.g., float64), but with reduced numerical precision.

Tensor Size

Be mindful of tensor sizes. Very large tensors may lead to slower computations or memory errors. Break large operations into smaller chunks when possible.

Operation Chaining

When possible, combine multiple operations into a single API call to reduce network overhead. Sequential operations that must be sent as separate requests will be slower.

In-place Operations

Use in-place operations when available to modify tensors directly rather than creating new ones. This can save memory and reduce overhead.

Integration with Symbolic API

The Numerical and Symbolic APIs can be used together for a powerful hybrid approach:

Derive expressions symbolically: Use the Symbolic API to create and simplify mathematical expressions with variables.
Substitute values: Convert symbolic expressions to numerical ones by evaluating them with specific values.
Compute numerically: Perform fast numerical computations on the resulting concrete tensors.

Example Workflow

// 1. Define a symbolic rotation matrix POST /api/tensors/symbolic/ { "operation": "create", "tensor": { "name": "R", "shape": [2, 2], "values": [["cos(theta)", "-sin(theta)"], ["sin(theta)", "cos(theta)"]] } } // 2. Evaluate with a specific angle value POST /api/tensors/numerical/ { "operation": "evaluate", "symbolic_tensor": "R", "values": { "theta": 0.5 }, "result_tensor": { "name": "R_numeric", "dtype": "float64" } } // 3. Apply the rotation to a point POST /api/tensors/numerical/ { "operation": "matmul", "operands": [ { "name": "R_numeric" }, { "name": "point", "shape": [2, 1], "values": [[1.0], [0.0]] } ] }