{"record":{"id":"49b31a817fdea524","repo":"jax-ml/jax","slug":"convolution-matrix-a-must-be-at-least-1-dimension","errorCode":null,"errorMessage":"convolution_matrix: a must be at least 1-dimensional, got a scalar.","messagePattern":"convolution_matrix: a must be at least 1-dimensional, got a scalar\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/scipy/linalg.py","lineNumber":2855,"sourceCode":"\n  See also:\n    :func:`jax.scipy.linalg.toeplitz`\n\n  Examples:\n    >>> jax.scipy.linalg.convolution_matrix(jnp.array([-1, 4, -2]), 5, mode='same')\n    Array([[ 4, -1,  0,  0,  0],\n           [-2,  4, -1,  0,  0],\n           [ 0, -2,  4, -1,  0],\n           [ 0,  0, -2,  4, -1],\n           [ 0,  0,  0, -2,  4]], dtype=int32)\n  \"\"\"\n  n = operator.index(n)\n  if n <= 0:\n    raise ValueError(f\"n must be a positive integer; got {n}.\")\n  check_arraylike(\"convolution_matrix\", a)\n  a_arr = jnp.asarray(a)\n  if a_arr.ndim == 0:\n    raise ValueError(\n        \"convolution_matrix: a must be at least 1-dimensional, got a scalar.\")\n  m = a_arr.shape[-1]\n  if m < 1:\n    raise ValueError(f\"len(a) must be at least 1; got shape {a_arr.shape}.\")\n  if mode not in ('full', 'valid', 'same'):\n    raise ValueError(\n        f\"mode must be one of 'full', 'valid', 'same'; got {mode!r}.\")\n  pad_widths = [(0, 0)] * (a_arr.ndim - 1) + [(0, n - 1)]\n  az = jnp.pad(a_arr, pad_widths)\n  raz = jnp.pad(jnp.flip(a_arr, axis=-1), pad_widths)\n  L = m + n - 1\n  if mode == 'same':\n    trim = min(n, m) - 1\n    tb = trim // 2\n    te = trim - tb\n  elif mode == 'valid':\n    tb = min(n, m) - 1\n    te = tb","sourceCodeStart":2837,"sourceCodeEnd":2873,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/scipy/linalg.py#L2837-L2873","documentation":"convolution_matrix requires the filter kernel a to be at least 1-D; a Python scalar or 0-d array fails the a_arr.ndim == 0 check. The matrix is built by vectorizing over the last axis of a, which a scalar lacks.","triggerScenarios":"Calling convolution_matrix(2.0, n) or convolution_matrix(jnp.asarray(3), n).","commonSituations":"Passing a single tap of a filter as a bare number; indexing that accidentally extractss a scalar (a[0] instead of a[0:1]).","solutions":["Wrap in a list/array: convolution_matrix([2.0], n)","Fix scalar-producing indexing: use a[i:i+1] instead of a[i]","Validate a.ndim >= 1 in caller code"],"exampleFix":"# before\nC = convolution_matrix(kernel[0], n)\n# after\nC = convolution_matrix(kernel[0:1], n)","handlingStrategy":"validation","validationCode":"a_arr = jnp.asarray(a)\nif a_arr.ndim == 0:\n    a_arr = a_arr.reshape(1)\nC = convolution_matrix(a_arr, n)","typeGuard":"def is_at_least_1d(x) -> bool:\n    return jnp.asarray(x).ndim >= 1","tryCatchPattern":"try:\n    convolution_matrix(a, n)\nexcept ValueError as e:\n    if 'at least 1-dimensional' in str(e):\n        a = jnp.atleast_1d(a); convolution_matrix(a, n)\n    else: raise","preventionTips":["Use slicing (a[i:i+1]) not indexing when extracting a single tap","Apply atleast_1d to filter kernels at API boundaries","Test single-tap filter edge cases explicitly"],"tags":["jax","convolution-matrix","input-validation","shape-error"],"backgroundTag":"expected-ndim-array","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}