{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The code " } ] }, { "__type": "Code", "__tag": 4050, "value": "A = convolution_matrix(a, n, mode)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "creates a Toeplitz matrix " }, { "__type": "CrossRef", "__tag": 4002, "value": "A", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "A" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " such that " }, { "__type": "InlineCode", "__tag": 4051, "value": "A @ v" }, { "__type": "Text", "__tag": 4046, "value": " is equivalent to using " }, { "__type": "InlineCode", "__tag": 4051, "value": "convolve(a, v, mode)" }, { "__type": "Text", "__tag": 4046, "value": ". The returned array always has " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " columns. The number of rows depends on the specified " }, { "__type": "ParamRef", "__tag": 4071, "name": "mode" }, { "__type": "Text", "__tag": 4046, "value": ", as explained above." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the default 'full' mode, the entries of " }, { "__type": "CrossRef", "__tag": 4002, "value": "A", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "A" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " are given by " } ] }, { "__type": "Code", "__tag": 4050, "value": "A[i, j] == (a[i-j] if (0 <= (i-j) < m) else 0)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineCode", "__tag": 4051, "value": "m = len(a)" }, { "__type": "Text", "__tag": 4046, "value": ". Suppose, for example, the input array is " }, { "__type": "InlineCode", "__tag": 4051, "value": "[x, y, z]" }, { "__type": "Text", "__tag": 4046, "value": ". The convolution matrix has the form " } ] }, { "__type": "Code", "__tag": 4050, "value": "[x, 0, 0, ..., 0, 0]\n[y, x, 0, ..., 0, 0]\n[z, y, x, ..., 0, 0]\n...\n[0, 0, 0, ..., x, 0]\n[0, 0, 0, ..., y, x]\n[0, 0, 0, ..., z, y]\n[0, 0, 0, ..., 0, z]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In 'valid' mode, the entries of " }, { "__type": "CrossRef", "__tag": 4002, "value": "A", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "A" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " are given by " } ] }, { "__type": "Code", "__tag": 4050, "value": "A[i, j] == (a[i-j+m-1] if (0 <= (i-j+m-1) < m) else 0)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This corresponds to a matrix whose rows are the subset of those from the 'full' case where all the coefficients in " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " are contained in the row. For input " }, { "__type": "InlineCode", "__tag": 4051, "value": "[x, y, z]" }, { "__type": "Text", "__tag": 4046, "value": ", this array looks like " } ] }, { "__type": "Code", "__tag": 4050, "value": "[z, y, x, 0, 0, ..., 0, 0, 0]\n[0, z, y, x, 0, ..., 0, 0, 0]\n[0, 0, z, y, x, ..., 0, 0, 0]\n...\n[0, 0, 0, 0, 0, ..., x, 0, 0]\n[0, 0, 0, 0, 0, ..., y, x, 0]\n[0, 0, 0, 0, 0, ..., z, y, x]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the 'same' mode, the entries of " }, { "__type": "CrossRef", "__tag": 4002, "value": "A", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "A" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " are given by " } ] }, { "__type": "Code", "__tag": 4050, "value": "d = (m - 1) // 2\nA[i, j] == (a[i-j+d] if (0 <= (i-j+d) < m) else 0)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The typical application of the 'same' mode is when one has a signal of length " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " (with " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": " greater than " }, { "__type": "InlineCode", "__tag": 4051, "value": "len(a)" }, { "__type": "Text", "__tag": 4046, "value": "), and the desired output is a filtered signal that is still of length " }, { "__type": "ParamRef", "__tag": 4071, "name": "n" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For input " }, { "__type": "InlineCode", "__tag": 4051, "value": "[x, y, z]" }, { "__type": "Text", "__tag": 4046, "value": ", this array looks like " } ] }, { "__type": "Code", "__tag": 4050, "value": "[y, x, 0, 0, ..., 0, 0, 0]\n[z, y, x, 0, ..., 0, 0, 0]\n[0, z, y, x, ..., 0, 0, 0]\n[0, 0, z, y, ..., 0, 0, 0]\n...\n[0, 0, 0, 0, ..., y, x, 0]\n[0, 0, 0, 0, ..., z, y, x]\n[0, 0, 0, 0, ..., 0, z, y]", "execution_status": null }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.5.0" } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "A", "annotation": "(..., k, n) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The convolution matrix whose row count " }, { "__type": "InlineRole", "__tag": 4003, "value": "k", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " depends on " }, { "__type": "ParamRef", "__tag": 4071, "name": "mode" }, { "__type": "Text", "__tag": 4046, "value": ": " } ] }, { "__type": "Code", "__tag": 4050, "value": "======= =========================\n mode k\n======= =========================\n'full' m + n -1\n'same' max(m, n)\n'valid' max(m, n) - min(m, n) + 1\n======= =========================", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For batch input, each slice of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(k, n)" }, { "__type": "Text", "__tag": 4046, "value": " along the last two dimensions of the output corresponds with a slice of shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(m,)" }, { "__type": "Text", "__tag": 4046, "value": " along the last dimension of the input." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a convolution matrix." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "a", "annotation": "(..., m) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The 1-D array to convolve. N-dimensional arrays are treated as a batch: each slice along the last axis is a 1-D array to convolve." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "n", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The number of columns in the resulting matrix. It gives the length of the input to be convolved with " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": ". This is analogous to the length of " }, { "__type": "InlineRole", "__tag": 4003, "value": "v", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.convolve(a, v)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mode", "annotation": "str", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is analogous to " }, { "__type": "ParamRef", "__tag": 4071, "name": "mode" }, { "__type": "Text", "__tag": 4046, "value": " in " }, { "__type": "InlineCode", "__tag": 4051, "value": "numpy.convolve(v, a, mode)" }, { "__type": "Text", "__tag": 4046, "value": ". It must be one of ('full', 'valid', 'same'). See below for how " }, { "__type": "ParamRef", "__tag": 4071, "name": "mode" }, { "__type": "Text", "__tag": 4046, "value": " determines the shape of the result." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Constructs the Toeplitz matrix representing one-dimensional convolution " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ". See the notes below for details." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array argument(s) of this function may have additional \"batch\" dimensions prepended to the core shape. In this case, the array is treated as a batch of lower-dimensional slices; see " }, { "__type": "InlineRole", "__tag": 4003, "value": "linalg_batch", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/linalg/_special_matrices.py", "item_line": 1121, "item_type": "function", "aliases": [ "scipy.linalg.convolution_matrix" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.linalg import convolution_matrix\nA = convolution_matrix([-1, 4, -2], 5, mode='same')\nA\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCompare multiplication by `A` with the use of `numpy.convolve`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([1, 2, 0, -3, 0.5])\nA @ x\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nVerify that ``A @ x`` produced the same result as applying the\nconvolution function.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.convolve([-1, 4, -2], x, mode='same')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFor comparison to the case ``mode='same'`` shown above, here are the\nmatrices produced by ``mode='full'`` and ``mode='valid'`` for the\nsame coefficients and size.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "convolution_matrix([-1, 4, -2], 5, mode='full')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "convolution_matrix([-1, 4, -2], 5, mode='valid')\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "toeplitz", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._special_matrices:toeplitz" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Toeplitz matrix" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "n", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "mode", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "full" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "convolution_matrix" }, "references": [ ".. [1] \"Convolution\", https://en.wikipedia.org/wiki/Convolution" ], "qa": "scipy.linalg._special_matrices:convolution_matrix", "arbitrary": [], "local_refs": [ "A", "a", "mode", "n" ] }