{"record":{"id":"0c1109bc1be5db59","repo":"jax-ml/jax","slug":"correlate2d-only-supports-2-dimensional-inputs","errorCode":null,"errorMessage":"correlate2d() only supports 2-dimensional inputs.","messagePattern":"correlate2d\\(\\) only supports 2-dimensional inputs\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/scipy/signal.py","lineNumber":456,"sourceCode":"    Specifying ``mode = 'same'`` returns a centered 2D correlation of the same\n    size as the first input:\n\n    >>> jax.scipy.signal.correlate2d(x, y, mode='same')\n    Array([[15., 24.,  7.],\n           [28., 14.,  9.],\n           [ 7.,  7.,  2.]], dtype=float32)\n\n    Specifying ``mode = 'valid'`` returns only the portion of 2D correlation\n    where the two arrays fully overlap:\n\n    >>> jax.scipy.signal.correlate2d(x, y, mode='valid')\n    Array([[15., 24.],\n           [28., 14.]], dtype=float32)\n  \"\"\"\n  if boundary != 'fill' or fillvalue != 0:\n    raise NotImplementedError(\"correlate2d() only supports boundary='fill', fillvalue=0\")\n  if np.ndim(in1) != 2 or np.ndim(in2) != 2:\n    raise ValueError(\"correlate2d() only supports 2-dimensional inputs.\")\n\n  swap = all(s1 <= s2 for s1, s2 in zip(in1.shape, in2.shape))\n  same_shape =  all(s1 == s2 for s1, s2 in zip(in1.shape, in2.shape))\n\n  if mode == \"same\":\n    in1, in2 = jnp.flip(in1), in2.conj()\n    result = jnp.flip(_convolve_nd(in1, in2, mode, precision=precision))\n  elif mode == \"valid\":\n    if swap and not same_shape:\n      in1, in2 = jnp.flip(in2), in1.conj()\n      result = _convolve_nd(in1, in2, mode, precision=precision)\n    else:\n      in1, in2 = jnp.flip(in1), in2.conj()\n      result = jnp.flip(_convolve_nd(in1, in2, mode, precision=precision))\n  else:\n    if swap:\n      in1, in2 = jnp.flip(in2), in1.conj()\n      result = _convolve_nd(in1, in2, mode, precision=precision).conj()","sourceCodeStart":438,"sourceCodeEnd":474,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/scipy/signal.py#L438-L474","documentation":"correlate2d validates that both inputs are exactly 2-D before delegating to the N-D machinery; arrays of any other rank are rejected with this ValueError, mirroring the SciPy 2-D-only API.","triggerScenarios":"Passing (N,H,W) batched feature maps, 1-D signals, or scalar templates to jax.scipy.signal.correlate2d.","commonSituations":"Template matching inside batched neural-net code without vmap; accidentally passing a list-of-lists-of-lists that becomes 3-D.","solutions":["Use jax.scipy.signal.correlate (N-D) for non-2-D inputs","vmap over the batch dimension or index a single image","Check np.ndim(in1) == np.ndim(in2) == 2 before calling"],"exampleFix":"// before\nr = jax.scipy.signal.correlate2d(imgs, tpl)  # imgs: (B,H,W)\n// after\nr = jax.vmap(lambda im: jax.scipy.signal.correlate2d(im, tpl))(imgs)","handlingStrategy":"validation","validationCode":"assert np.ndim(in1) == 2 and np.ndim(in2) == 2","typeGuard":"def is_2d(a) -> bool:\n    return jnp.asarray(a).ndim == 2","tryCatchPattern":null,"preventionTips":["vmap(lambda im: correlate2d(im, tpl)) for batches","Prefer correlate() for arbitrary-rank inputs"],"tags":["jax","scipy","correlation","rank-mismatch","shape-validation"],"backgroundTag":"wrong-dimensionality-input","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}