Bug: ak.matmul 1D @ 1D Return Type Violates NumPy Semantics and Type Annotations

[ajpotts]

Bug: ak.matmul 1D @ 1D Return Type Violates NumPy Semantics and Type Annotations

Summary

ak.matmul correctly computes the numerical result for 1D @ 1D inputs, but returns a scalar while being annotated (and typeguard-enforced) as returning a pdarray. This causes runtime failures under typeguard and breaks NumPy-alignment test suites.

Expected Behavior (NumPy)

np.matmul(a, b)  # where a.shape == b.shape == (n,)
# returns a scalar (np.generic)

Actual Behavior (Arkouda)

ak.matmul(ak.array(a), ak.array(b))
# returns a scalar (e.g., np.int64)
# BUT function is annotated as returning pdarray

This triggers:

TypeError: type of the return value must be pdarray; got numpy.int64 instead

Impact

• NumPy alignment tests fail for 1D @ 1D
• Users cannot rely on typeguard-enabled builds
• Semantically correct behavior is masked as an error

Reproduction

import numpy as np
import arkouda as ak

a = np.arange(10)
b = np.arange(10)
ak.matmul(ak.array(a), ak.array(b))  # typeguard failure

Proposed Fix

Update the return type annotation of ak.matmul to reflect NumPy semantics:

• (n,) @ (n,) -> scalar
• Otherwise -> pdarray

Suggested typing:

from typing import Union
import numpy as np

def matmul(...) -> Union[pdarray, np.generic]:
    ...

Workaround (Tests)

Mark 1D@1D alignment tests as xfail until the annotation is fixed.