asc2.matmul_acc

asc2.matmul_acc(acc: LocalTensor, input: LocalTensor, other: LocalTensor, *, hf32: bool = False) → None

Computes the matrix multiplication of input and other and accumulates the result into acc.

This function performs in-place accumulation, adding the result of input @ other to the existing accumulator values. Use asc2.zeros_acc() to create an accumulator. For simple matrix multiplication without accumulation, use matmul() which returns a new tensor.

Rationale: Ascend’s Cube units operate on a dedicated L0C accumulator register where the accumulator and matmul destination are the same physical entity—the hardware accumulates in-place as part of the matmul operation itself. Unlike general-purpose memory (UB, L1), L0C is a specialized register file designed for this exact use case. This destination-passing style makes the hardware behavior explicit: you create an accumulator with zeros_acc, reuse it across multiple matmul operations, then read the final result. While other frameworks may use functional style (e.g. acc = matmul(acc, a, b)), that approach would either require implicit copies from L0C (defeating the purpose of the dedicated accumulator) or obscure the fact that accumulation happens in specialized hardware.

Parameters:

  • acc – Accumulator tensor (2D tensor in L0C), must be created with asc2.zeros_acc()

  • input – The left operand (2D tensor in L0A)

  • other – The right operand (2D tensor in L0B)

  • hf32 – Enable the rounding to HF32 for input tensors with float32 dtype

Raises:

  • TypeError – If acc, input, or other is not a LocalTensor

  • RuntimeError – If input tensors are not 2D, have incompatible shapes, unsupported dtype, or accumulator has wrong shape/dtype

Note

Input tensors must have either float16, bfloat16, or float32 data type and compatible shapes. Accumulator tensor type is always float32.

Examples

Accumulate multiple matrix multiplications (e.g., for K-tiled matmul):

acc = asc2.zeros_acc([64, 256], dtype=asc2.float32)
for k in range(k_tiles):
    a_k = asc2.copy(a_l1, [0, k * 32], [64, 32], asc2.TensorLocation.L0A)
    b_k = asc2.copy(b_l1, [k * 32, 0], [32, 256], asc2.TensorLocation.L0B)
    asc2.matmul_acc(acc, a_k, b_k)
asc2.copy_out(acc, c_gm, [0, 0])

Accumulate with bias initialization:

bias = asc2.copy(bias_l1, [0], [256], asc2.TensorLocation.BT)
acc = asc2.zeros_acc([64, 256], dtype=asc2.float32, bias=bias)
for k in range(k_tiles):
    a_k = asc2.copy(a_l1, [0, k * 32], [64, 32], asc2.TensorLocation.L0A)
    b_k = asc2.copy(b_l1, [k * 32, 0], [32, 256], asc2.TensorLocation.L0B)
    asc2.matmul_acc(acc, a_k, b_k)
asc2.copy_out(acc, c_gm, [0, 0])

Accumulate with HF32 mode (for float32 inputs):

acc = asc2.zeros_acc([32, 64], dtype=asc2.float32)
asc2.matmul_acc(acc, a_l0a, b_l0b, hf32=True)