Symbolic Tensor API

Detailed reference for the symbolic tensor operations API endpoint, including request formats, operations, and examples.

Endpoint Overview

The Symbolic Tensor API endpoint accepts requests to perform tensor calculations symbolically. Under the hood, it utilizes SymPy to manipulate tensor expressions. You can submit operations with symbolic tensor components (variables or symbolic expressions) and receive exact analytical results.

POST /api/tensors/symbolic/

All requests and responses use JSON format. The symbolic API is designed for operations where you need exact mathematical expressions rather than numerical approximations.

Request Format

The JSON request to the symbolic endpoint should describe the tensor operation in a structured way. The core fields in the request are:

Required Fields

operation (string): The type of tensor operation to perform (e.g., "add", "multiply", "contract", 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 or null): The symbolic components of the tensor, represented as strings or null for fully symbolic

Optional Fields

options (object): Additional parameters for specific operations (e.g., indices for contraction)

Supported Operations

The Symbolic Tensor API supports a variety of operations for tensor manipulation. Here are the primary operations:

add

Add two tensors of the same shape element-wise.

{ "operation": "add", "operands": [ { "name": "A", "shape": [2, 2], "values": [["a", "b"], ["c", "d"]] }, { "name": "B", "shape": [2, 2], "values": [["w", "x"], ["y", "z"]] } ] }

multiply

Multiply tensors using standard tensor multiplication rules.

{ "operation": "multiply", "operands": [ { "name": "A", "shape": [2, 3], "values": [["a", "b", "c"], ["d", "e", "f"]] }, { "name": "B", "shape": [3, 2], "values": [["u", "v"], ["w", "x"], ["y", "z"]] } ] }

contract

Contract (sum over) specified indices of a tensor.

{ "operation": "contract", "tensor": { "name": "T", "shape": [3, 3], "values": [["a", "b", "c"], ["d", "e", "f"], ["g", "h", "i"]] }, "indices": [0, 1] }

substitute

Replace symbolic variables with other expressions or values.

{ "operation": "substitute", "tensor": { "name": "A", "shape": [2, 2], "values": [["a", "b"], ["c", "d"]] }, "substitutions": { "a": "sin(x)", "b": 5, "c": "y^2", "d": "z + w" } }

differentiate

Compute symbolic derivatives of tensor expressions.

{ "operation": "differentiate", "tensor": { "name": "F", "shape": [2, 2], "values": [["x^2", "sin(x)"], ["cos(y)", "y^3"]] }, "with_respect_to": "x" }

simplify

Simplify complex tensor expressions using algebraic rules.

{ "operation": "simplify", "tensor": { "name": "E", "shape": [2, 1], "values": [["sin(x)^2 + cos(x)^2"], ["a*(b+c) - a*b - a*c"]] } }

Response Format

The response from the symbolic 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 symbolic values
operation: Echo of the operation that was performed
message (optional): Human-readable message about the operation
error (optional): Present only if an error occurred, with an explanation

Example Response

200 OK { "operation": "add", "result": { "shape": [2, 2], "values": [[ "a + w", "b + x" ], [ "c + y", "d + z" ]] } }

Error Handling

The API will perform validation on requests and return appropriate error responses when something goes wrong. Common error scenarios include:

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": "Shape mismatch for operation 'multiply': operands shapes [2,3] and [4,2] are incompatible." }

Parsing Errors

Returned when symbolic expressions cannot be parsed correctly:

{ "error": "Failed to parse symbolic values: invalid syntax in 'a++b'." }

500 Internal Server Error

Returned when something unexpected goes wrong on the server. These errors should be reported to the iTensor team.

Example Use Cases

Verifying Mathematical Identities

Use the symbolic API to verify tensor identities by manipulating and simplifying complex expressions.

Deriving Formulas

Derive exact formulas for physics, engineering, or mathematical applications without numerical approximations.

Generating Computational Code

Generate symbolic expressions that can later be converted to optimized numerical code for specific applications.