{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A preconditioner, P, is chosen such that P is close to A but easy to solve for. The preconditioner parameter required by this routine is " }, { "__type": "InlineCode", "__tag": 4051, "value": "M = P^-1" }, { "__type": "Text", "__tag": 4046, "value": ". The inverse should preferably not be calculated explicitly. Rather, use the following template to produce M " } ] }, { "__type": "Code", "__tag": 4050, "value": "# Construct a linear operator that computes P^-1 @ x.\nimport scipy.sparse.linalg as spla\nM_x = lambda x: spla.spsolve(P, x)\nM = spla.LinearOperator((n, n), M_x)", "execution_status": null } ], "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": "x", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The converged solution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "info", "annotation": "int", "desc": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Provides convergence information:" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "0successful exit >0 : convergence to tolerance not achieved, number of iterations" } ] } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Solve " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ax = b" }, { "__type": "Text", "__tag": 4046, "value": " with the Generalized Minimal RESidual method." } ] } ], "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": "{sparse array, ndarray, LinearOperator}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The real or complex N-by-N matrix of the linear system. Alternatively, " }, { "__type": "ParamRef", "__tag": 4071, "name": "A" }, { "__type": "Text", "__tag": 4046, "value": " can be a linear operator which can produce " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ax" }, { "__type": "Text", "__tag": 4046, "value": " using, e.g., " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy.sparse.linalg.LinearOperator" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "b", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Right hand side of the linear system. Has shape (N,) or (N,1)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x0", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Starting guess for the solution (a vector of zeros by default)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "atol, rtol", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameters for the convergence test. For convergence, " }, { "__type": "InlineCode", "__tag": 4051, "value": "norm(b - A @ x) <= max(rtol*norm(b), atol)" }, { "__type": "Text", "__tag": 4046, "value": " should be satisfied. The default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "atol=0." }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "rtol=1e-5" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "restart", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of iterations between restarts. Larger values increase iteration cost, but may be necessary for convergence. If omitted, " }, { "__type": "InlineCode", "__tag": 4051, "value": "min(20, n)" }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of iterations (restart cycles). Iteration will stop after maxiter steps even if the specified tolerance has not been achieved. See " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback_type" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "M", "annotation": "{sparse array, ndarray, LinearOperator}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Inverse of the preconditioner of " }, { "__type": "ParamRef", "__tag": 4071, "name": "A" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "ParamRef", "__tag": 4071, "name": "M" }, { "__type": "Text", "__tag": 4046, "value": " should approximate the inverse of " }, { "__type": "ParamRef", "__tag": 4071, "name": "A" }, { "__type": "Text", "__tag": 4046, "value": " and be easy to solve for (see Notes). Effective preconditioning dramatically improves the rate of convergence, which implies that fewer iterations are needed to reach a given error tolerance. By default, no preconditioner is used. In this implementation, left preconditioning is used, and the preconditioned residual is minimized. However, the final convergence is tested with respect to the " }, { "__type": "InlineCode", "__tag": 4051, "value": "b - A @ x" }, { "__type": "Text", "__tag": 4046, "value": " residual." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "callback", "annotation": "function", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "User-supplied function to call after each iteration. It is called as " }, { "__type": "InlineCode", "__tag": 4051, "value": "callback(args)" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "args" }, { "__type": "Text", "__tag": 4046, "value": " are selected by " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback_type" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "callback_type", "annotation": "{'x', 'pr_norm', 'legacy'}, optional", "desc": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Callback function argument requested:" } ] }, "dd": [ { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ": current iterate (ndarray), called on every restart" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "pr_norm" }, { "__type": "Text", "__tag": 4046, "value": ": relative (preconditioned) residual norm (float), called on every inner iteration" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "legacy" }, { "__type": "Text", "__tag": 4046, "value": " (default): same as " }, { "__type": "InlineCode", "__tag": 4051, "value": "pr_norm" }, { "__type": "Text", "__tag": 4046, "value": ", but also changes the meaning of " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxiter" }, { "__type": "Text", "__tag": 4046, "value": " to count inner iterations instead of restart cycles." } ] } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This keyword has no effect if " }, { "__type": "ParamRef", "__tag": 4071, "name": "callback" }, { "__type": "Text", "__tag": 4046, "value": " is not set." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "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/sparse/linalg/_isolve/iterative.py", "item_line": 587, "item_type": "function", "aliases": [ "scipy.sparse.linalg.gmres" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.sparse import csc_array\nfrom scipy.sparse.linalg import gmres\nA = csc_array([[3, 2, 0], [1, -1, 0], [0, 5, 1]], dtype=float)\nb = np.array([2, 4, -1], dtype=float)\nx, exitCode = gmres(A, b, atol=1e-5)\nprint(exitCode) # 0 indicates successful convergence\nnp.allclose(A.dot(x), b)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "LinearOperator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._interface:LinearOperator" }, "kind": "module" }, "descriptions": [], "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": "b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "x0", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "rtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "1e-05" }, { "__type": "SigParam", "__tag": 4030, "name": "atol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "0.0" }, { "__type": "SigParam", "__tag": 4030, "name": "restart", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "M", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "callback", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "callback_type", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "gmres" }, "references": null, "qa": "scipy.sparse.linalg._isolve.iterative:gmres", "arbitrary": [], "local_refs": [ "A", "M", "atol", "b", "callback", "callback_type", "info", "maxiter", "restart", "rtol", "x", "x0" ] }