API Reference

iTensor exposes a RESTful API that allows programmatic access to its tensor computation engine. The API is organized around a few core endpoints under a common base path (e.g., /api/tensors/).

Currently, the primary endpoints are for symbolic tensor operations and numerical tensor operations. Both endpoints expect HTTP POST requests with a JSON payload describing the operation, and they return results in JSON format.

All endpoints are part of a versioned API (for instance, assuming base URL http://<server>/api/).

This endpoint accepts requests to perform tensor calculations symbolically. Under the hood, it utilizes SymPy to manipulate tensor expressions. The user can submit an operation with symbolic tensor components (for example, unspecified or symbolic values, denoted by variables) and receive an exact analytical result if possible.

Request Format

The JSON request to the symbolic endpoint should describe the tensor operation in a structured way. The exact schema may evolve, but the core fields are:

• operation (string): The type of tensor operation to perform. Examples might include "add" (for tensor addition), "multiply" (for tensor multiplication), "contract" (for index contraction), etc. iTensor may support a fixed set of operations in its initial version.
• operands (array): A list of operands (tensors) involved in the operation. Each operand can be an object defining a tensor. For symbolic calculations, operands can have unspecified values:
  • name (string, optional): A label or variable name for the tensor (e.g., "A", "B"). If provided, the result might be expressed in terms of these names.
  • shape (array of integers): The dimensions of the tensor (e.g., [2, 2] for a 2x2 matrix, or [3] for a length-3 vector). This is required so the system knows the structure.
  • values (nested array or null): The components of the tensor. For symbolic, this can be omitted or set to null/None to indicate a fully symbolic tensor (all elements are symbolic). Alternatively, you can provide some or all elements as strings representing symbolic expressions (e.g., "[ [ 'a', 'b'], [ 'c', 'd'] ]" for a 2x2 symbolic matrix with elements a, b, c, d). If values are provided as strings, the backend will parse them into SymPy symbols/expressions.
• options (object, optional): Additional options for the operation. For example, if the operation is "contract" or a tensor index manipulation, this might specify which indices to contract or other parameters. Another example: for differentiation, an option might specify the variable to differentiate with respect to.

Example Request (Symbolic Addition)

In this example, two 2x2 matrices A and B are added. All entries are symbolic (represented by strings like "a11" which the backend interprets as a symbol). The "operation": "add" tells the API to perform element-wise matrix addition.

Response Format

The response will be a JSON object containing the result of the symbolic operation. Common fields in the response include:

• result: The resulting tensor, usually represented in a similar structure to the input operands. This could be an object with a shape and values. The values will contain expressions (as strings) for each component of the resulting tensor.
• operation: Echoes the operation that was performed (for confirmation).
• operands: Sometimes the API may echo back a simplified form of the operands or references to them (e.g., using the provided name).
• message (optional): A human-readable message, e.g., "Addition performed successfully", or any warnings.
• error (optional): Present only if an error occurred (then result might be absent). This could be an error message string explaining what went wrong.

Example Response (Symbolic Addition)

For the addition example above, each element of the result is the sum of corresponding symbolic elements from A and B. The result is still symbolic. Note that the symbols are returned as strings like "a11 + b11" – the client (or user) can interpret or display these as needed. If the operation were more complex (e.g., matrix multiplication), the expressions could involve summations of products (following the algebraic rules).

This endpoint is for performing tensor operations with concrete numeric data. It uses NumPy (and possibly other numeric libraries) to compute results efficiently. Users should use this endpoint when they have actual numbers and want the computation done (for example, adding two large matrices, or computing a tensor contraction result).

The API design for the numerical endpoint is similar to the symbolic one, but all values should be numeric (integers or floats) rather than symbolic strings. It may support the same set of operations (add, multiply, etc.), but focuses on returning numerical results.

Request Format

• operation (string): The operation to perform (e.g., "add", "multiply", "dot" for dot product, etc.).
• operands (array): List of tensor operands involved in the operation. Each operand in this context should have:
  • shape (array of ints): The dimensions of the tensor.
  • values (nested arrays): The actual numeric data for the tensor. The structure of nested arrays should match the shape. For example, a 2x2 matrix would be an array of 2 arrays each of length 2: [[1,2],[3,4]].
  • dtype (string, optional): The data type of the numbers (such as "float64" or "int32"). If not provided, the backend will infer or default to float.
  • name (string, optional): A label for the tensor (not needed for computation, but could be useful in logs or debugging).
• options (object, optional): Additional parameters for the operation if needed. For example, an epsilon for numerical tolerance (if doing approximate comparisons), or specifying whether to do element-wise vs matrix multiplication (though that might also be encoded in different operation names).

Example Request (Numerical Multiplication)

This requests a multiplication of a 2x3 matrix by a 3x2 matrix. The first operand is a 2x3 matrix, second is 3x2. The "operation": "multiply" here implies a matrix multiplication (the API will likely interpret "multiply" for matrices as the dot product along the matching dimension, or possibly it might have distinct operations like "matmul" – the exact semantics will be defined by iTensor's API documentation). In this example, the multiplication is valid because the inner dimensions (3) match.

Response Format

The response for numerical operations will contain the computed numeric result:

• result: The resulting tensor, typically given with its shape and values. All values will be numbers (or perhaps scientific notation strings if very large, but generally as JSON numbers).
• operation: Echo of the operation performed.
• elapsed_time (optional): Some APIs include performance info. iTensor might include how long the computation took, especially if it's a heavy operation, to give the user an idea of performance.
• error (optional): Present if the operation failed (see error handling).

Example Response (Numerical Multiplication)

This result corresponds to multiplying the 2x3 and 3x2 matrices from the request example. The resulting 2x2 matrix has values calculated by the standard matrix multiplication formula (dot products of rows and columns): for instance, 58 = 1*7 + 2*9 + 3*11, and so on.

Both API endpoints perform validation on the request. If something is wrong, they will return an error response (usually with an HTTP 400 status code for client errors). Common error scenarios include:

• Missing or Invalid Fields: If required fields like operation or operands are missing, or if operands is not a list, the API returns a 400 Bad Request with an error message like{"error": "Invalid request format: 'operands' field is required."}.
• Unsupported Operation: If operation is not one of the supported types (say someone put "divide" but the API doesn't handle that yet), you may get{"error": "Unsupported operation 'divide'.", "supported_operations": ["add","multiply",...]}.
• Shape Mismatch or Invalid Tensor Data: If the provided tensors are not compatible for the operation (e.g., adding tensors of different shapes, or multiplying matrices with incompatible dimensions), the API returns a 400 with a message like{"error": "Shape mismatch for operation 'multiply': operands shapes [2,3] and [4,2] are incompatible."}.
• Parsing Errors: For symbolic operations, if any of the symbolic values cannot be parsed into valid SymPy expressions, the API might return an error. For example, an entry like "a++b" (invalid syntax) could yield{"error": "Failed to parse symbolic values: invalid syntax in 'a++b'."}.
• Server Errors: If something goes wrong on the server (uncaught exception, etc.), a 500 Internal Server Error is returned. In debug mode, Django might include a stack trace (but in production, it will be a generic error).

In all error cases, the response will contain an error field with a descriptive message. The client should check for the presence of this field or the HTTP status code to handle errors gracefully.

Symbolic API Use Cases

• Symbolic Formula Derivation: A user can use this endpoint to derive formulas. For instance, provide two generic 3x3 matrices and an operation "multiply" to get the symbolic product matrix (useful for textbooks or derivation).
• Verification of Identities: The symbolic engine can help verify tensor identities by simplifying expressions. One could send a complicated tensor algebra expression and see if the result simplifies to a known simpler form (though note: this requires the API to implement simplification routines or it might just output the expanded form).
• Differentiation: A planned feature might be to include operations like "differentiate" where the payload includes a tensor expression and a variable to differentiate with respect to, and the result would be a symbolic derivative.

Numerical API Use Cases

• Basic Linear Algebra: Adding, subtracting, or multiplying matrices/vectors. For example, use "operation": "add" to add two same-shaped tensors,"operation": "multiply" to do matrix multiplication as in the example, or perhaps "operation": "dot" to do dot product of two vectors.
• Tensor Contraction: If supported, a user might send a higher-rank tensor and request contraction along certain indices (the API might have an operation like "contract" or use "options" to specify indices). The result would be a reduced-rank tensor after summing over the contracted index.
• Element-wise Operations: If the API distinguishes between element-wise operations and matrix operations, a user could explicitly request element-wise multiplication, division, etc. This would be useful for operations like Hadamard products (element-wise multiplication) or applying functions element-wise to tensors.