Skip to content

Commit 05dfda1

Browse files
committed
ENH: support the dot family for new-style user DTypes
The dot family (dot/inner/vdot/tensordot/multi_dot/correlate/convolve) routes through the legacy ``dotfunc`` ArrFuncs slot, which new-style (non-legacy) user DTypes cannot provide. Such DTypes therefore hit a hard error even when they implement the ``matmul`` and ``multiply`` gufuncs. When ``dotfunc == NULL``, fall back to ``matmul``/``multiply`` via small private helpers in ``numpy._core.numeric``: * ``PyArray_MatrixProduct2`` -> ``_dot_fallback`` (covers dot, inner, tensordot and multi_dot, which all delegate to it) * ``array_vdot`` -> ``_vdot_fallback`` * ``_pyarray_correlate`` -> ``_correlate_fallback`` (covers correlate and convolve) The fallbacks are strict drop-ins for the legacy behaviour: identical value, shape, scalar-vs-array return, ``out=`` contract and error messages. They are purely additive -- they fire only where the dot family currently errors, so the legacy fast path is untouched. Closes numpygh-30793
1 parent f8c34f2 commit 05dfda1

4 files changed

Lines changed: 227 additions & 3 deletions

File tree

‎numpy/_core/numeric.py‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1219,6 +1219,96 @@ def tensordot(a, b, axes=2):
12191219
return res.reshape(olda + oldb)
12201220

12211221

1222+
def _dot_result_shape(a, b):
1223+
if a.ndim == 0 or b.ndim == 0:
1224+
return np.broadcast_shapes(a.shape, b.shape)
1225+
if b.ndim == 1:
1226+
return a.shape[:-1]
1227+
return a.shape[:-1] + b.shape[:-2] + b.shape[-1:]
1228+
1229+
1230+
def _dot_check_out(out, shape, dtype):
1231+
if out.shape != tuple(shape):
1232+
raise ValueError("output array has wrong dimensions")
1233+
if out.dtype != dtype or not out.flags["C_CONTIGUOUS"]:
1234+
raise ValueError(
1235+
"output array is not acceptable (must have the right datatype, "
1236+
"number of dimensions, and be a C-Array)"
1237+
)
1238+
1239+
1240+
def _dot_contract(a, b, axis_a, axis_b):
1241+
notin_a = [k for k in range(a.ndim) if k != axis_a]
1242+
notin_b = [k for k in range(b.ndim) if k != axis_b]
1243+
n = a.shape[axis_a]
1244+
m = math.prod(a.shape[ax] for ax in notin_a)
1245+
p = math.prod(b.shape[ax] for ax in notin_b)
1246+
at = ascontiguousarray(a.transpose(notin_a + [axis_a]).reshape(m, n))
1247+
bt = ascontiguousarray(b.transpose([axis_b] + notin_b).reshape(n, p))
1248+
res = np.matmul(at, bt)
1249+
return res.reshape([a.shape[ax] for ax in notin_a]
1250+
+ [b.shape[ax] for ax in notin_b])
1251+
1252+
1253+
def _dot_fallback(a, b, out=None):
1254+
"""``dot`` via ``matmul``/``multiply`` for dtypes without a legacy dotfunc."""
1255+
a = np.asarray(a)
1256+
b = np.asarray(b)
1257+
res_dtype = np.result_type(a.dtype, b.dtype)
1258+
res_shape = _dot_result_shape(a, b)
1259+
if out is not None:
1260+
_dot_check_out(out, res_shape, res_dtype)
1261+
if a.ndim == 0 or b.ndim == 0:
1262+
# 0-D: scalar multiply
1263+
res = np.multiply(a, b)
1264+
elif a.shape[-1] == 0 or 0 in res_shape:
1265+
# empty contraction or empty result: all-zeros, no matmul
1266+
res = np.zeros(res_shape, dtype=res_dtype)
1267+
elif a.ndim == 1 and b.ndim == 1:
1268+
# 1-D x 1-D: inner product
1269+
res = np.matmul(ascontiguousarray(a), ascontiguousarray(b))
1270+
elif b.ndim == 1:
1271+
# N-D x 1-D: over last axis of a
1272+
res = _dot_contract(a, b, a.ndim - 1, 0)
1273+
else:
1274+
# N-D x M-D: last of a, 2nd-last of b
1275+
res = _dot_contract(a, b, a.ndim - 1, b.ndim - 2)
1276+
if out is not None:
1277+
out[...] = res
1278+
return out
1279+
return res
1280+
1281+
1282+
def _vdot_fallback(a, b):
1283+
a = np.asarray(a).ravel()
1284+
b = np.asarray(b).ravel()
1285+
if a.dtype.kind == "c":
1286+
a = np.conjugate(a)
1287+
return np.matmul(a, b)
1288+
1289+
1290+
def _correlate_fallback(a, v, mode):
1291+
"""Forward correlation via ``matmul`` for dtypes without a legacy dotfunc.
1292+
1293+
``_pyarray_correlate`` already handles empty checks, complex conjugation
1294+
and the ``len(a) < len(v)`` swap/reverse, so ``a`` is the longer operand.
1295+
"""
1296+
a = ascontiguousarray(np.asarray(a).ravel())
1297+
v = ascontiguousarray(np.asarray(v).ravel())
1298+
res_dtype = np.result_type(a.dtype, v.dtype)
1299+
n1, n2 = a.size, v.size
1300+
pad = zeros(n2 - 1, dtype=res_dtype)
1301+
apad = concatenate([pad, a, pad])
1302+
win = apad[arange(n1 + n2 - 1)[:, None] + arange(n2)]
1303+
full = np.matmul(win, v)
1304+
if mode == 0:
1305+
return ascontiguousarray(full[n2 - 1:n1]) # valid
1306+
if mode == 1:
1307+
s = (n2 - 1) // 2
1308+
return ascontiguousarray(full[s:s + n1]) # same
1309+
return full # full
1310+
1311+
12221312
def _roll_dispatcher(a, shift, axis=None):
12231313
return (a,)
12241314

‎numpy/_core/src/common/npy_import.h‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,10 @@ typedef struct npy_runtime_imports_struct {
2929
PyObject *_clip;
3030
PyObject *_commastring;
3131
PyObject *_convert_to_stringdtype_kwargs;
32+
PyObject *_correlate_fallback;
3233
PyObject *_default_array_repr;
3334
PyObject *_default_array_str;
35+
PyObject *_dot_fallback;
3436
PyObject *_dump;
3537
PyObject *_dumps;
3638
PyObject *_getfield_is_safe;
@@ -47,6 +49,7 @@ typedef struct npy_runtime_imports_struct {
4749
PyObject *_ufunc_inspect_signature_builder;
4850
PyObject *_usefields;
4951
PyObject *_var;
52+
PyObject *_vdot_fallback;
5053
PyObject *_view_is_safe;
5154
PyObject *_void_scalar_to_string;
5255
} npy_runtime_imports_struct;

‎numpy/_core/src/multiarray/multiarraymodule.c‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -996,6 +996,17 @@ PyArray_MatrixProduct2(PyObject *op1, PyObject *op2, PyArrayObject* out)
996996
}
997997
Py_SETREF(typec, NPY_DT_CALL_ensure_canonical(typec));
998998

999+
if (typec != NULL && PyDataType_GetArrFuncs(typec)->dotfunc == NULL) {
1000+
Py_DECREF(typec);
1001+
if (npy_cache_import_runtime("numpy._core.numeric", "_dot_fallback",
1002+
&npy_runtime_imports._dot_fallback) == -1) {
1003+
return NULL;
1004+
}
1005+
return PyObject_CallFunctionObjArgs(
1006+
npy_runtime_imports._dot_fallback, op1, op2,
1007+
out != NULL ? (PyObject *)out : Py_None, NULL);
1008+
}
1009+
9991010
Py_INCREF(typec);
10001011
ap1 = (PyArrayObject *)PyArray_FromAny(op1, typec, 0, 0,
10011012
NPY_ARRAY_ALIGNED, NULL);
@@ -1206,9 +1217,14 @@ _pyarray_correlate(PyArrayObject *ap1, PyArrayObject *ap2, PyArray_Descr *typec,
12061217
}
12071218
dot = PyDataType_GetArrFuncs(PyArray_DESCR(ret))->dotfunc;
12081219
if (dot == NULL) {
1209-
PyErr_SetString(PyExc_ValueError,
1210-
"function not available for this data type");
1211-
goto clean_ret;
1220+
Py_DECREF(ret);
1221+
if (npy_cache_import_runtime("numpy._core.numeric", "_correlate_fallback",
1222+
&npy_runtime_imports._correlate_fallback) == -1) {
1223+
return NULL;
1224+
}
1225+
return (PyArrayObject *)PyObject_CallFunction(
1226+
npy_runtime_imports._correlate_fallback, "OOi",
1227+
(PyObject *)ap1, (PyObject *)ap2, mode);
12121228
}
12131229

12141230
int needs_pyapi = PyDataType_FLAGCHK(PyArray_DESCR(ret), NPY_NEEDS_PYAPI);
@@ -2626,6 +2642,16 @@ array_vdot(PyObject *NPY_UNUSED(dummy), PyObject *const *args, Py_ssize_t len_ar
26262642
}
26272643
Py_SETREF(type, NPY_DT_CALL_ensure_canonical(type));
26282644

2645+
if (type != NULL && PyDataType_GetArrFuncs(type)->dotfunc == NULL) {
2646+
Py_DECREF(type);
2647+
if (npy_cache_import_runtime("numpy._core.numeric", "_vdot_fallback",
2648+
&npy_runtime_imports._vdot_fallback) == -1) {
2649+
return NULL;
2650+
}
2651+
return PyObject_CallFunctionObjArgs(
2652+
npy_runtime_imports._vdot_fallback, op1, op2, NULL);
2653+
}
2654+
26292655
Py_INCREF(type);
26302656
ap1 = (PyArrayObject *)PyArray_FromAny(op1, type, 0, 0, 0, NULL);
26312657
if (ap1 == NULL) {

‎numpy/_core/tests/test_multiarray.py‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8348,6 +8348,111 @@ def test_3d_tensor(self):
83488348
assert_equal(np.inner(b, a).transpose(2, 3, 0, 1), desired)
83498349

83508350

8351+
class TestDotFamilyFallback:
8352+
# The dot family (dot/inner/vdot/tensordot/correlate) historically requires
8353+
# a legacy ``dotfunc`` ArrFuncs slot, which new-style user DTypes cannot
8354+
# provide. For such DTypes numpy falls back to the ``matmul``/``multiply``
8355+
# gufuncs via the private helpers in ``numpy._core.numeric``. These tests
8356+
# exercise the helpers directly (against the legacy ``np.dot`` oracle) and,
8357+
# when available, end-to-end through a real new-style DType (quaddtype).
8358+
8359+
@pytest.mark.parametrize("sa,sb", [
8360+
((), ()), ((), (3, 4)), ((4, 3), ()), ((5,), (5,)), ((3,), (3, 4)),
8361+
((4, 3), (3,)), ((4, 3), (3, 5)), ((2, 3, 4), (4,)), ((4,), (2, 4, 5)),
8362+
((2, 3, 4), (6, 4, 5)), ((0, 3), (3, 4)), ((4, 0), (0, 5)),
8363+
])
8364+
def test_dot_fallback_matches_dot(self, sa, sb):
8365+
from numpy._core.numeric import _dot_fallback
8366+
rng = np.random.default_rng(1)
8367+
a = rng.integers(-4, 5, sa).astype(np.float64)
8368+
b = rng.integers(-4, 5, sb).astype(np.float64)
8369+
ref = np.dot(a, b)
8370+
got = _dot_fallback(a, b)
8371+
assert_array_equal(got, ref)
8372+
assert got.shape == np.shape(ref)
8373+
8374+
def test_dot_fallback_out(self):
8375+
from numpy._core.numeric import _dot_fallback
8376+
a = np.arange(12, dtype=np.float64).reshape(4, 3)
8377+
b = np.arange(15, dtype=np.float64).reshape(3, 5)
8378+
out = np.empty((4, 5), dtype=np.float64)
8379+
ret = _dot_fallback(a, b, out=out)
8380+
assert ret is out
8381+
assert_array_equal(out, np.dot(a, b))
8382+
# strict out= contract, mirroring legacy np.dot
8383+
assert_raises(ValueError, _dot_fallback, a, b, out=np.empty((4, 4)))
8384+
assert_raises(ValueError, _dot_fallback, a, b,
8385+
out=np.asfortranarray(np.empty((4, 5))))
8386+
8387+
def test_vdot_fallback_matches_vdot(self):
8388+
from numpy._core.numeric import _vdot_fallback
8389+
rng = np.random.default_rng(2)
8390+
a = rng.integers(-4, 5, (2, 3)).astype(np.float64)
8391+
b = rng.integers(-4, 5, (2, 3)).astype(np.float64)
8392+
assert_array_equal(_vdot_fallback(a, b), np.vdot(a, b))
8393+
ac = (a + 1j * b).astype(np.complex128)
8394+
bc = (b - 1j * a).astype(np.complex128)
8395+
assert_array_equal(_vdot_fallback(ac, bc), np.vdot(ac, bc))
8396+
8397+
@pytest.mark.parametrize("mode,code", [("valid", 0), ("same", 1), ("full", 2)])
8398+
@pytest.mark.parametrize("n2", [1, 2, 3, 4, 5])
8399+
def test_correlate_fallback_matches_correlate(self, mode, code, n2):
8400+
# the helper assumes len(a) >= len(v) (the C layer handles the swap),
8401+
# so test the forward correlation against the legacy oracle
8402+
from numpy._core.numeric import _correlate_fallback
8403+
a = np.arange(1, 9, dtype=np.float64)
8404+
v = (np.arange(1, n2 + 1, dtype=np.float64) * 0.5 + 1)
8405+
assert_array_equal(_correlate_fallback(a, v, code),
8406+
np.correlate(a, v, mode))
8407+
8408+
def test_quaddtype_dot_family(self):
8409+
numpy_quaddtype = pytest.importorskip("numpy_quaddtype")
8410+
QuadPrecDType = numpy_quaddtype.QuadPrecDType
8411+
QuadPrecision = numpy_quaddtype.QuadPrecision
8412+
qd = QuadPrecDType()
8413+
8414+
def q(arr):
8415+
arr = np.asarray(arr, dtype=np.float64)
8416+
out = np.empty(arr.shape, dtype=qd)
8417+
for idx in np.ndindex(arr.shape):
8418+
out[idx] = QuadPrecision(repr(float(arr[idx])))
8419+
return out
8420+
8421+
def f(arr):
8422+
arr = np.asarray(arr)
8423+
flat = np.array([float(v) for v in arr.ravel()])
8424+
return flat.reshape(arr.shape)
8425+
8426+
rng = np.random.default_rng(3)
8427+
a = rng.integers(-4, 5, (3,)).astype(np.float64)
8428+
b = rng.integers(-4, 5, (3,)).astype(np.float64)
8429+
A = rng.integers(-4, 5, (4, 3)).astype(np.float64)
8430+
B = rng.integers(-4, 5, (3, 5)).astype(np.float64)
8431+
C = rng.integers(-4, 5, (5, 2)).astype(np.float64)
8432+
8433+
# 1-D . 1-D returns a scalar, exactly like legacy np.dot
8434+
scalar = np.dot(q(a), q(b))
8435+
assert np.ndim(scalar) == 0
8436+
assert float(scalar) == np.dot(a, b)
8437+
8438+
assert_array_equal(f(np.dot(q(A), q(B))), np.dot(A, B))
8439+
assert_array_equal(f(np.inner(q(A), q(A))), np.inner(A, A))
8440+
assert float(np.vdot(q(a), q(b))) == np.vdot(a, b)
8441+
assert_array_equal(f(np.tensordot(q(A), q(B), axes=1)),
8442+
np.tensordot(A, B, axes=1))
8443+
assert_array_equal(f(np.linalg.multi_dot([q(A), q(B), q(C)])),
8444+
np.linalg.multi_dot([A, B, C]))
8445+
for mode in ("valid", "same", "full"):
8446+
assert_array_equal(f(np.correlate(q(a), q(b), mode)),
8447+
np.correlate(a, b, mode))
8448+
assert_array_equal(f(np.convolve(q(A.ravel()), q(b), mode)),
8449+
np.convolve(A.ravel(), b, mode))
8450+
8451+
# empty-input error messages come from the C layer, unchanged
8452+
with pytest.raises(ValueError, match="first array argument"):
8453+
np.correlate(q(np.empty(0)), q(a))
8454+
8455+
83518456
class TestChoose:
83528457
def _create_data(self):
83538458
x = 2 * np.ones((3,), dtype=int)

0 commit comments

Comments
 (0)