Tensor Operations¶
Creation¶
zeros¶
1 | |
Create a tensor with zeros.
Parameters:
tensor_type(Value): The type of the tensor.dynamic_shape(Value | None): The dynamic shape of the tensor. If none, tensor type is assumed to have complete shape.
ones¶
1 | |
Create a tensor filled with ones.
Parameters:
tensor_type(Value): The type of the tensor.dynamic_shape(Optional[Value]): The dynamic shape of the tensor. If none, tensor type is assumed to have complete shape.
full¶
1 | |
Create a tensor filled with a scalar value.
Parameters:
tensor_type(Value): The type of the tensor.fill_value(Value): The scalar value to fill. Must have the same dtype as the tensor element type. Usearith.castto convert if needed.dynamic_shape(Optional[Value]): The dynamic shape of the tensor. If none, tensor type is assumed to have complete shape. Default:None.
full_like¶
1 | |
Create a tensor filled with a scalar value, using the input tensor's shape.
Parameters:
tensor(Value): The reference tensor whose shape and placement are used.fill_value(Value): The scalar value to fill. Must have the same dtype as the tensor's element type. Usearith.castto convert if needed.
Movement¶
copy¶
1 | |
Copy the values from the source value to target, preserving the lifetime of source value.
Note:
This operation will verify if copy from assigned device of value to device is possible according to the compute model.
Parameters:
value(Value): The value to copytarget(Value): The device to copy to. If None, the value is copied to the default device
Returns:
result(Value): The copied value.
Example:
1 2 3 4 5 6 7 | |
memcpy¶
1 | |
Copy the values from the source value to host, preserving the lifetime of source value.
Note:
This operation will verify if copy operation from value to dst is possible according to the compute model.
Parameters:
dst(Value): The device to copy to.src(Value): The value to copy.
Returns:
result(Value): The copied value.
Example:
1 2 3 4 5 6 | |
move¶
1 | |
Move values from the source value to target, invalidating the lifetime of source value.
Move operation removes the lifetime of the source value, and transfers it to the returned value.
Key Characteristics:
- Ownership transfer - Source tensor becomes invalid after move
- Zero-copy optimization - When possible, avoids actual data copying
- Compile-time validation - Compiler verifies move validity using compute model
- Memory efficiency - Prevents accidental use of moved tensor
Note:
This operation will verify if move from assigned device of value to target_device is possible according to the compute model.
Parameters:
value(Value): The value to move. Must be an interpreted value at invocation time.target_device(Value): Device or memory to move to (as an interpreted value representing anExecutororMemory).
Returns:
result(Value): The moved value whose lifetime replaces the source value's lifetime.
Example:
1 2 3 4 5 6 | |
Warning:
Moving a tensor to a different device will invalidate the lifetime of the source tensor. Therefore, the source tensor cannot be used after the move operation. And trying to use the source tensor will cause a compiler error.
1 2 3 4 | |
request_load¶
1 | |
Request a copy of the values from the source value to target, preserving the lifetime of source value.
Returns a handle, which is ID of the request, which will be consumed by receive operation.
Key Features:
- Asynchronous operation - Data loading happens in the background
- Handle-based access - Use
legato.tensor.receiveto consume the handle and access data - Automatic cleanup - Compiler warns and automatically deletes unused handles (when statically analyzable)
- Memory efficiency - Enables overlapping of computation and data movement
Parameters:
tensor(Value): The compiled value to request a copy of.devices(Value): Target device(s) to load to. Accepts a single device or a list of devices. Each device is an interpretedExecutororMemoryvalue.target_name(Value): Target name to receive the tensor. (interpreted value)
Note:
Bertha uses static receive slots; do not forward this SSA handle to receive_type on Bertha. Match explicit target names on load and receive.
Returns:
result(Value): A handle (request ID) to be consumed byreceive.
Example:
1 2 3 4 5 6 7 8 9 | |
Receive¶
receive¶
1 | |
Receive the values from the source value to target, consuming the handle.
The handle is returned by request_copy or request_move operation.
Key Features:
- Handle consumption - The handle is consumed and cannot be used again
- Context requirement - Must be called within the appropriate compute context
- Synchronous operation - Blocks until data is available
- Type safety - Compiler ensures handle validity and type consistency
Note:
Handle consumption will not work on Bertha, since it does not have hardware support for handle consumption.
Parameters:
tensor(Value): Target tensor to receive. (compiled value)handle(Value): Request handle returned byrequest_load. (compiled or interpreted value)target_name(Value): Target name to receive the tensor. (interpreted value)
Returns:
result(Value): The received value materialized with the requested type.
Example:
1 2 3 4 5 6 7 8 9 | |
receive_type¶
1 | |
Receive the values from the source value to target, consuming the handle.
The handle is returned by request_copy or request_move operation.
Parameters:
tensor_type(Value): Target tensor type to receive. (compiled value)handle(Value): Request handle returned byrequest_load. (compiled value)dynamic_shape(Value): Dynamic shape of the tensor. (compiled value)target_name(Value): Target name to receive the tensor. (interpreted value)
Returns:
result(Value): The received value materialized with the requested type.
View and Shape¶
view¶
1 | |
Creates view of the value. This will borrow lifetime from the original value.
Returned value will share the same memory with the original value. This operation is no-op from the hardware, but provides a simplified interface for indexing tensors.
Example:
1 2 3 4 5 | |
Parameters:
value(Value): The compiled value (tensor) to view.indices(Value): Compiled tuple of index, or range representing the view. Length of the tuple must match the rank of the input tensor. Dimensions with index is collapsed. Therefore, tuple must contain at least single range entry.
Returns:
result(Value): A view value that aliases the storage ofvalue.
Example:
1 2 3 4 5 6 7 | |
reshape¶
1 | |
Reshape the value to the new shape.
This operation is no-op from the hardware, but compiler can use this to retag a tensor with a new shape/rank after target-specific validation.
Parameters:
value(Value): The compiled value to reshape.shape(Value): New shape, using the same syntax as tensor type shapes. A scalar dimension is interpreted as(logical, physical) == (d, d). A tuple dimension is interpreted as(logical, physical). Use-1for a dynamic logical dimension.dynamic_shape(Value | None): Optional tuple of runtime values for dynamic logical dimensions inshape. Default:None.
Returns:
result(Value): The reshaped value with the specified shape.
Example:
1 2 3 4 5 6 | |
Shape constraints
Total number of physical elements of the reshaped tensor must match the input tensors' total number of physical elements. Moreover, whether new logical shape covers valid data range is not verified by this operation. It is programmer's responsibility to check whether logical shape is given correctly.
Masking¶
The following are frontend APIs. Standalone full, full_like, zeros, and
ones fills are not general EVT0 binary operations; a supported fusion may
consume a restricted form. See Tensor memory patterns
for explicit frontend-only examples and Math backend support.
A standalone fill that survives to EVT0 assignment reports headline LE0121
with recorded reason LE2104. For an example of inspecting compiler diagnostics,
see Compile diagnostics.
where¶
1 | |
Select values element-wise based on a boolean condition.
Parameters:
condition(Value): Boolean tensor or scalar condition.true_value(Value): Values selected where condition is true. Must have exactly the same type asfalse_value.false_value(Value): Values selected where condition is false. Must have exactly the same type astrue_value. Uselegato.tensor.full_liketo materialize scalar fallback values for tensor branches.
Shape constraints
condition, true_value, and false_value must all have exactly the
same shape. condition must be boolean, and true_value /
false_value must have exactly the same dtype. Broadcasting is not
supported. Use legato.tensor.full_like to expand a scalar fallback
value to the required tensor shape before passing it to where.
tril¶
1 | |
Return the lower triangular part of a tensor.
Parameters:
tensor(Value): The input tensor (rank >= 2).diagonal(Value): The diagonal offset. 0 means the main diagonal.
Rank requirement
The input tensor must have rank >= 2. The operation extracts the lower triangular part of the last two dimensions.
Introspection¶
get_rank¶
1 | |
Get the rank of the value.
Parameters:
value(Value): The compiled value to get the rank of.
Returns:
result(Value): The rank of the value.
get_dimension¶
1 | |
Get the dimension of the value at the given index.
Parameters:
value(Value): The compiled value to get the dimension of.index(Value): The index of the dimension to get. (index or integer value)
Returns:
result(Value): The dimension of the value at the given index.
Load and receive operations use explicit target names. Current call forms are:
1 2 3 | |
Use legato.tensor.receive when an existing tensor value describes the received
type and shape. Use legato.tensor.receive_type when you only have a type and
optional dynamic shape; it materializes a tensor of that type using the handle.
Example:
1 2 3 4 5 | |
Borrowing a tuple element¶
1 | |
borrow_tuple_element selects a tensor member from a tuple without copying its
storage. The index must be a compile-time, nonnegative integer within the tuple. The
result aliases the selected member and keeps the producer storage alive while the
borrowed result is live.
Because the two values share storage, writing through the borrowed tensor also changes the original tuple member. Use this operation for read-only consumers unless write-through aliasing is intentional. Ordinary tuple indexing and destructuring keep their ownership-producing behavior and may copy a tensor member.
Use borrowing when a tuple-producing operation and its consumers are known to share the same storage lifetime, such as extracting a read-only result from a fused operation. Use ordinary indexing when the consumer needs independent storage.
Notes:
- Handles are consumed in the appropriate context and target buffer.
receive_typeaccepts a tensor type plus an optional dynamic shape tuple of index/integer/range values. Use an empty tuple orNonefor fully static shapes.