{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a 1-D vector " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": " with length " }, { "__type": "InlineRole", "__tag": 4003, "value": "m", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", and an array " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " with shape " }, { "__type": "InlineCode", "__tag": 4051, "value": "(m, ...)" }, { "__type": "Text", "__tag": 4046, "value": "," } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "solve_circulant(c, b)" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "returns the same result as" } ] }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "solve(circulant(c), b)" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineRole", "__tag": 4003, "value": "solve", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "CrossRef", "__tag": 4002, "value": "circulant", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._special_matrices:circulant" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " are from " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.linalg", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.16.0" } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "LinAlgError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the circulant matrix associated with " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": " is near singular." } ] } ] } ] } ], "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": "x", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Solution to the system " }, { "__type": "InlineCode", "__tag": 4051, "value": "C x = b" }, { "__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": "Solve the equation " }, { "__type": "InlineCode", "__tag": 4051, "value": "C @ x = b" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "C" }, { "__type": "Text", "__tag": 4046, "value": " is a circulant matrix defined by " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The coefficients of the circulant matrix." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "b", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Right-hand side matrix in " }, { "__type": "InlineCode", "__tag": 4051, "value": "a x = b" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "singular", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This argument controls how a near singular circulant matrix is handled. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "singular" }, { "__type": "Text", "__tag": 4046, "value": " is \"raise\" and the circulant matrix is near singular, a " }, { "__type": "InlineRole", "__tag": 4003, "value": "LinAlgError", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is raised. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "singular" }, { "__type": "Text", "__tag": 4046, "value": " is \"lstsq\", the least squares solution is returned. Default is \"raise\"." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If any eigenvalue of the circulant matrix has an absolute value that is less than or equal to " }, { "__type": "ParamRef", "__tag": 4071, "name": "tol" }, { "__type": "Text", "__tag": 4046, "value": ", the matrix is considered to be near singular. If not given, " }, { "__type": "ParamRef", "__tag": 4071, "name": "tol" }, { "__type": "Text", "__tag": 4046, "value": " is set to " } ] }, { "__type": "Code", "__tag": 4050, "value": "tol = abs_eigs.max() * abs_eigs.size * np.finfo(np.float64).eps", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineRole", "__tag": 4003, "value": "abs_eigs", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the array of absolute values of the eigenvalues of the circulant matrix." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "caxis", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": " has dimension greater than 1, it is viewed as a collection of circulant vectors. In this case, " }, { "__type": "ParamRef", "__tag": 4071, "name": "caxis" }, { "__type": "Text", "__tag": 4046, "value": " is the axis of " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": " that holds the vectors of circulant coefficients." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "baxis", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " has dimension greater than 1, it is viewed as a collection of vectors. In this case, " }, { "__type": "ParamRef", "__tag": 4071, "name": "baxis" }, { "__type": "Text", "__tag": 4046, "value": " is the axis of " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " that holds the right-hand side vectors." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "outaxis", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " are multidimensional, the value returned by " }, { "__type": "CrossRef", "__tag": 4002, "value": "solve_circulant", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._basic:solve_circulant" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " is multidimensional. In this case, " }, { "__type": "ParamRef", "__tag": 4071, "name": "outaxis" }, { "__type": "Text", "__tag": 4046, "value": " is the axis of the result that holds the solution vectors." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "C", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the circulant matrix associated with the vector " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The system is solved by doing division in Fourier space. The calculation is " } ] }, { "__type": "Code", "__tag": 4050, "value": "x = ifft(fft(b) / fft(c))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "CrossRef", "__tag": 4002, "value": "fft", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.fft" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "ifft", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are the fast Fourier transform and its inverse, respectively. For a large vector " }, { "__type": "ParamRef", "__tag": 4071, "name": "c" }, { "__type": "Text", "__tag": 4046, "value": ", this is " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "much" } ] }, { "__type": "Text", "__tag": 4046, "value": " faster than solving the system with the full circulant matrix." } ] } ], "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": 1148, "item_type": "function", "aliases": [ "scipy.linalg.solve_circulant" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.linalg import solve_circulant, solve, circulant, lstsq\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "c = np.array([2, 2, 4])\nb = np.array([1, 2, 3])\nsolve_circulant(c, b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCompare that result to solving the system with `scipy.linalg.solve`:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "solve(circulant(c), b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nA singular example:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "c = np.array([1, 1, 0, 0])\nb = np.array([1, 2, 3, 4])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCalling ``solve_circulant(c, b)`` will raise a `LinAlgError`. For the\nleast square solution, use the option ``singular='lstsq'``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "solve_circulant(c, b, singular='lstsq')\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nCompare to `scipy.linalg.lstsq`:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x, resid, rnk, s = lstsq(circulant(c), b)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "x\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nA broadcasting example:\n\nSuppose we have the vectors of two circulant matrices stored in an array\nwith shape (2, 5), and three `b` vectors stored in an array with shape\n(3, 5). For example,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "c = np.array([[1.5, 2, 3, 0, 0], [1, 1, 4, 3, 2]])\nb = np.arange(15).reshape(-1, 5)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe want to solve all combinations of circulant matrices and `b` vectors,\nwith the result stored in an array with shape (2, 3, 5). When we\ndisregard the axes of `c` and `b` that hold the vectors of coefficients,\nthe shapes of the collections are (2,) and (3,), respectively, which are\nnot compatible for broadcasting. To have a broadcast result with shape\n(2, 3), we add a trivial dimension to `c`: ``c[:, np.newaxis, :]`` has\nshape (2, 1, 5). The last dimension holds the coefficients of the\ncirculant matrices, so when we call `solve_circulant`, we can use the\ndefault ``caxis=-1``. The coefficients of the `b` vectors are in the last\ndimension of the array `b`, so we use ``baxis=-1``. If we use the\ndefault `outaxis`, the result will have shape (5, 2, 3), so we'll use\n``outaxis=-1`` to put the solution vectors in the last dimension.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = solve_circulant(c[:, np.newaxis, :], b, baxis=-1, outaxis=-1)\nx.shape\nnp.set_printoptions(precision=3) # For compact output of numbers.\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "x\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nCheck by solving one pair of `c` and `b` vectors (cf. ``x[1, 1, :]``):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "solve_circulant(c[1], b[1, :])\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "circulant", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._special_matrices:circulant" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "circulant matrix" } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "c", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "singular", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "raise" }, { "__type": "SigParam", "__tag": 4030, "name": "tol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "caxis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "-1" }, { "__type": "SigParam", "__tag": 4030, "name": "baxis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "outaxis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "solve_circulant" }, "references": null, "qa": "scipy.linalg._basic:solve_circulant", "arbitrary": [], "local_refs": [ "b", "baxis", "c", "caxis", "outaxis", "singular", "tol", "x" ] }