asc2.copy_out

asc2.copy_out(src: LocalTensor, dst: GlobalTensor, offsets: Iterable[RuntimeInt], *, real_shape: Iterable[RuntimeInt] | None = None) → None
asc2.copy_out(src: RuntimeNumeric, dst: GlobalTensor, offsets: Iterable[RuntimeInt]) → None

Copy data from a local tensor or scalar value to a global tensor.

This function supports two modes of operation:

  1. Store a local tensor with offsets: Store a local tensor to the global tensor at the specified offsets.

  2. Store a scalar: Store a single value (or a local tensor with exactly one element) at the specified offsets.

Parameters:

  • src – The source value to store. Can be a local tensor, a scalar value, or a local tensor with one element. For 1D tensors, any shape is supported. For 2D+ tensors in UB, the last dimension must be aligned to 32 bytes (e.g., 8 elements for float32, 16 elements for float16).

  • dst – The destination global tensor.

  • offsets – The offsets into the global tensor for each dimension.

  • real_shape – Explicitly specify how many elements to store to the global tensor. The local tensor has its full shape, but only real_shape elements are written to the global tensor. Must match the rank of the local tensor and each dimension must not exceed the corresponding tensor dimension. Cannot be used for scalar stores.

Raises:

  • TypeError – If src is not a LocalTensor or numeric, or dst is not a GlobalTensor

  • ValueError – If real_shape is used with scalar stores

  • RuntimeError – If data alignment check fails, offsets rank mismatch, or real_shape exceeds tensor shape

Note

Local tensors from UB and L0C memory locations can be stored to global memory. Only 1D and 2D tensors are fully supported and stable; higher-dimensional support is experimental.

Examples

Copy a 1D tensor using explicit offsets:

out_gm = asc2.global_tensor(out_ptr, [1024])
src = asc2.copy_in(x_gm, [0], [128])
asc2.copy_out(src, out_gm, [256])

Copy a 2D tensor to a 2D global tensor:

out_gm = asc2.global_tensor(out_ptr, [64, 128])
src = asc2.copy_in(x_gm, [0, 0], [16, 32])
asc2.copy_out(src, out_gm, [8, 16])

Copy a scalar value:

out_gm = asc2.global_tensor(out_ptr, [1024])
asc2.copy_out(42.0, out_gm, [0])

Copy a 2D tensor with explicit real_shape (store fewer elements than tensor shape):

out_gm = asc2.global_tensor(out_ptr, [100, 100])
src = asc2.copy_in(x_gm, [0, 0], [16, 16])
asc2.copy_out(src, out_gm, [0, 0], real_shape=[12, 12])
# src has shape [16, 16], but only 12x12 elements stored to global tensor

Copy an accumulator tensor (from L0C) directly to global memory:

acc = asc2.zeros_acc([64, 128], dtype=asc2.float32)
asc2.matmul_acc(acc, a_l0a, b_l0b)
out_gm = asc2.global_tensor(out_ptr, [64, 128])
asc2.copy_out(acc, out_gm, [0, 0])