{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Toeplitz matrix is embedded in a circulant matrix and the FFT is used to efficiently calculate the matrix-matrix product." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Because the computation is based on the FFT, integer inputs will result in floating point outputs. This is unlike NumPy's " }, { "__type": "CrossRef", "__tag": 4002, "value": "matmul", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy._lib.array_api_compat.common._aliases:matmul" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", which preserves the data type of the input." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This is partly based on the implementation that can be found in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", licensed under the MIT license. More information about the method can be found in reference " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ". References " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": " have more reference implementations in Python." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.6.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": "T @ x", "annotation": "(M,) or (M, K) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The result of the matrix multiplication " }, { "__type": "InlineCode", "__tag": 4051, "value": "T @ x" }, { "__type": "Text", "__tag": 4046, "value": ". Shape of return matches shape of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Efficient Toeplitz Matrix-Matrix Multiplication using FFT" } ] } ], "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": "c_or_cr", "annotation": "array_like or tuple of (array_like, array_like)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The vector " }, { "__type": "InlineCode", "__tag": 4051, "value": "c" }, { "__type": "Text", "__tag": 4046, "value": ", or a tuple of arrays (" }, { "__type": "InlineCode", "__tag": 4051, "value": "c" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "r" }, { "__type": "Text", "__tag": 4046, "value": "). If not supplied, " }, { "__type": "InlineCode", "__tag": 4051, "value": "r = conjugate(c)" }, { "__type": "Text", "__tag": 4046, "value": " is assumed; in this case, if c[0] is real, the Toeplitz matrix is Hermitian. r[0] is ignored; the first row of the Toeplitz matrix is " }, { "__type": "InlineCode", "__tag": 4051, "value": "[c[0], r[1:]]" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "(M,) or (M, K) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Matrix with which to multiply." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "check_finite", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to check that the input matrices contain only finite numbers. Disabling may give a performance gain, but may result in problems (result entirely NaNs) if the inputs do contain infinities or NaNs." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "workers", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To pass to scipy.fft.fft and ifft. Maximum number of workers to use for parallel computation. If negative, the value wraps around from " }, { "__type": "InlineCode", "__tag": 4051, "value": "os.cpu_count()" }, { "__type": "Text", "__tag": 4046, "value": ". See scipy.fft.fft for more details." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function returns the matrix multiplication between a Toeplitz matrix and a dense matrix." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Toeplitz matrix has constant diagonals, with c as its first column and r as its first row. If r is not given, " }, { "__type": "InlineCode", "__tag": 4051, "value": "r == conjugate(c)" }, { "__type": "Text", "__tag": 4046, "value": " is assumed." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The documentation is written assuming array arguments are of specified \"core\" shapes. However, 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/_basic.py", "item_line": 2259, "item_type": "function", "aliases": [ "scipy.linalg.matmul_toeplitz" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Multiply the Toeplitz matrix T with matrix x::\n\n [ 1 -1 -2 -3] [1 10]\n T = [ 3 1 -1 -2] x = [2 11]\n [ 6 3 1 -1] [2 11]\n [10 6 3 1] [5 19]\n\nTo specify the Toeplitz matrix, only the first column and the first\nrow are needed.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nc = np.array([1, 3, 6, 10]) # First column of T\nr = np.array([1, -1, -2, -3]) # First row of T\nx = np.array([[1, 10], [2, 11], [2, 11], [5, 19]])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.linalg import toeplitz, matmul_toeplitz\nmatmul_toeplitz((c, r), x)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCheck the result by creating the full Toeplitz matrix and\nmultiplying it by ``x``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "toeplitz(c, r) @ x\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe full matrix is never formed explicitly, so this routine\nis suitable for very large Toeplitz matrices.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "n = 1000000\nmatmul_toeplitz([1] + [0]*(n-1), np.ones(n))\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "solve_toeplitz", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._basic:solve_toeplitz" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Solve a Toeplitz system using Levinson Recursion" } ] } ], "type": null }, { "__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": "c_or_cr", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "check_finite", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "workers", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "matmul_toeplitz" }, "references": [ ".. [1] Jacob R Gardner, Geoff Pleiss, David Bindel, Kilian", " Q Weinberger, Andrew Gordon Wilson, \"GPyTorch: Blackbox Matrix-Matrix", " Gaussian Process Inference with GPU Acceleration\" with contributions", " from Max Balandat and Ruihan Wu. Available online:", " https://github.com/cornellius-gp/gpytorch", "", ".. [2] J. Demmel, P. Koev, and X. Li, \"A Brief Survey of Direct Linear", " Solvers\". In Z. Bai, J. Demmel, J. Dongarra, A. Ruhe, and H. van der", " Vorst, editors. Templates for the Solution of Algebraic Eigenvalue", " Problems: A Practical Guide. SIAM, Philadelphia, 2000. Available at:", " http://www.netlib.org/utk/people/JackDongarra/etemplates/node384.html", "", ".. [3] R. Scheibler, E. Bezzam, I. Dokmanic, Pyroomacoustics: A Python", " package for audio room simulations and array processing algorithms,", " Proc. IEEE ICASSP, Calgary, CA, 2018.", " https://github.com/LCAV/pyroomacoustics/blob/pypi-release/", " pyroomacoustics/adaptive/util.py", "", ".. [4] Marano S, Edwards B, Ferrari G and Fah D (2017), \"Fitting", " Earthquake Spectra: Colored Noise and Incomplete Data\", Bulletin of", " the Seismological Society of America., January, 2017. Vol. 107(1),", " pp. 276-291." ], "qa": "scipy.linalg._basic:matmul_toeplitz", "arbitrary": [], "local_refs": [ "T @ x", "c_or_cr", "check_finite", "workers", "x" ] }