{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function implements a Newton-Krylov solver. The basic idea is to compute the inverse of the Jacobian with an iterative Krylov method. These methods require only evaluating the Jacobian-vector products, which are conveniently approximated by a finite difference:" } ] }, { "__type": "Math", "__tag": 4058, "value": "J v \\approx (f(x + \\omega*v/|v|) - f(x)) / \\omega" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Due to the use of iterative matrix inverses, these methods can deal with large nonlinear problems." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "SciPy's " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " module offers a selection of Krylov solvers to choose from. The default here is " }, { "__type": "CrossRef", "__tag": 4002, "value": "lgmres", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lgmres:lgmres" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", which is a variant of restarted GMRES iteration that reuses some of the information obtained in the previous Newton steps to invert Jacobians in subsequent steps." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For a review on Newton-Krylov methods, see for example " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", and for the LGMRES sparse inverse method, see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find a root of a function, using Krylov approximation for inverse Jacobian." } ] } ], "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": "%(params_basic)s", "annotation": "", "desc": [] }, { "__type": "DocParam", "__tag": 4016, "name": "rdiff", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Relative step size to use in numerical differentiation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "method", "annotation": "str or callable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Krylov method to use to approximate the Jacobian. Can be a string, or a function implementing the same interface as the iterative solvers in " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". If a string, needs to be one of: " }, { "__type": "InlineCode", "__tag": 4051, "value": "'lgmres'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gmres'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'bicgstab'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'cgs'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'minres'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'tfqmr'" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The default is " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg.lgmres", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.sparse.linalg._isolve.lgmres:lgmres" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "inner_maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Parameter to pass to the \"inner\" Krylov solver: maximum number of iterations. Iteration will stop after maxiter steps even if the specified tolerance has not been achieved." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "inner_M", "annotation": "LinearOperator or InverseJacobian", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Preconditioner for the inner Krylov iteration. Note that you can use also inverse Jacobians as (adaptive) preconditioners. For example," } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> from scipy.optimize import BroydenFirst, KrylovJacobian\n>>> from scipy.optimize import InverseJacobian\n>>> jac = BroydenFirst()\n>>> kjac = KrylovJacobian(inner_M=InverseJacobian(jac))", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the preconditioner has a method named 'update', it will be called as " }, { "__type": "InlineCode", "__tag": 4051, "value": "update(x, f)" }, { "__type": "Text", "__tag": 4046, "value": " after each nonlinear step, with " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " giving the current point, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": " the current function value." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "outer_k", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Size of the subspace kept across LGMRES nonlinear iterations. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg.lgmres", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.sparse.linalg._isolve.lgmres:lgmres" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "inner_kwargs", "annotation": "kwargs", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Keyword parameters for the \"inner\" Krylov solver (defined with " }, { "__type": "ParamRef", "__tag": 4071, "name": "method" }, { "__type": "Text", "__tag": 4046, "value": "). Parameter names must start with the " }, { "__type": "InlineRole", "__tag": 4003, "value": "inner_", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " prefix which will be stripped before passing on the inner method. See, e.g., " }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg.gmres", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.sparse.linalg._isolve.iterative:gmres" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "%(params_extra)s", "annotation": "", "desc": [] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This method is suitable for solving large-scale problems." } ] } ], "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/optimize/_nonlin.py", "item_line": 1366, "item_type": "class", "aliases": [ "scipy.optimize.KrylovJacobian" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following functions define a system of nonlinear equations\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def fun(x):\n return [x[0] + 0.5 * x[1] - 1.0,\n 0.5 * (x[1] - x[0]) ** 2]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nA solution can be obtained as follows.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy import optimize\nsol = optimize.newton_krylov(fun, [0, 0])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "sol\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "root", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._root:root" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Interface to root finding algorithms for multivariate functions. See " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='krylov'" }, { "__type": "Text", "__tag": 4046, "value": " in particular." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg.gmres", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.iterative:gmres" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.linalg.lgmres", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lgmres:lgmres" }, "kind": "module" }, "descriptions": [], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "rdiff", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "method", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "lgmres" }, { "__type": "SigParam", "__tag": 4030, "name": "inner_maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "20" }, { "__type": "SigParam", "__tag": 4030, "name": "inner_M", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "outer_k", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "10" }, { "__type": "SigParam", "__tag": 4030, "name": "kw", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "KrylovJacobian" }, "references": [ ".. [1] C. T. Kelley, Solving Nonlinear Equations with Newton's Method,", " SIAM, pp.57-83, 2003.", " :doi:`10.1137/1.9780898718898.ch3`", ".. [2] D.A. Knoll and D.E. Keyes, J. Comp. Phys. 193, 357 (2004).", " :doi:`10.1016/j.jcp.2003.08.010`", ".. [3] A.H. Baker and E.R. Jessup and T. Manteuffel,", " SIAM J. Matrix Anal. Appl. 26, 962 (2005).", " :doi:`10.1137/S0895479803422014`" ], "qa": "scipy.optimize._nonlin:KrylovJacobian", "arbitrary": [], "local_refs": [ "%(params_basic)s", "%(params_extra)s", "inner_M", "inner_kwargs", "inner_maxiter", "method", "outer_k", "rdiff" ] }