{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.11.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": "x", "annotation": "ndarray of float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Least-square solution returned." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "istop", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "istop gives the reason for stopping " } ] }, { "__type": "Code", "__tag": 4050, "value": "istop = 0 means x=0 is a solution. If x0 was given, then x=x0 is a\n solution.\n = 1 means x is an approximate solution to A@x = B,\n according to atol and btol.\n = 2 means x approximately solves the least-squares problem\n according to atol.\n = 3 means COND(A) seems to be greater than CONLIM.\n = 4 is the same as 1 with atol = btol = eps (machine\n precision)\n = 5 is the same as 2 with atol = eps.\n = 6 is the same as 3 with CONLIM = 1/eps.\n = 7 means ITN reached maxiter before the other stopping\n conditions were satisfied.", "execution_status": null } ] }, { "__type": "DocParam", "__tag": 4016, "name": "itn", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of iterations used." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normr", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "norm(b-Ax)" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normar", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "norm(A^H (b - Ax))" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "norma", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "norm(A)" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "conda", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Condition number of A." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normx", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "norm(x)" } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Iterative solver for least-squares problems." } ] } ], "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": "Matrix A in the linear system. Alternatively, " }, { "__type": "InlineCode", "__tag": 4051, "value": "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": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "A^H x" }, { "__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": "array_like, shape (m,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Vector " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " in the linear system." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "damp", "annotation": "float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Damping factor for regularized least-squares. " }, { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " solves the regularized least-squares problem " } ] }, { "__type": "Code", "__tag": 4050, "value": "min ||(b) - ( A )x||\n ||(0) (damp*I) ||_2", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where damp is a scalar. If damp is None or 0, the system is solved without regularization. Default is 0." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "atol, btol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Stopping tolerances. " }, { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol. Let " }, { "__type": "InlineCode", "__tag": 4051, "value": "r = b - Ax" }, { "__type": "Text", "__tag": 4046, "value": " be the residual vector for the current approximate solution " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ax = b" }, { "__type": "Text", "__tag": 4046, "value": " seems to be consistent, " }, { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " terminates when " }, { "__type": "InlineCode", "__tag": 4051, "value": "norm(r) <= atol * norm(A) * norm(x) + btol * norm(b)" }, { "__type": "Text", "__tag": 4046, "value": ". Otherwise, " }, { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " terminates when " }, { "__type": "InlineCode", "__tag": 4051, "value": "norm(A^H r) <= atol * norm(A) * norm(r)" }, { "__type": "Text", "__tag": 4046, "value": ". If both tolerances are 1.0e-6 (default), the final " }, { "__type": "InlineCode", "__tag": 4051, "value": "norm(r)" }, { "__type": "Text", "__tag": 4046, "value": " should be accurate to about 6 digits. (The final " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": " will usually have fewer correct digits, depending on " }, { "__type": "InlineCode", "__tag": 4051, "value": "cond(A)" }, { "__type": "Text", "__tag": 4046, "value": " and the size of LAMBDA.) If " }, { "__type": "ParamRef", "__tag": 4071, "name": "atol" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "ParamRef", "__tag": 4071, "name": "btol" }, { "__type": "Text", "__tag": 4046, "value": " is None, a default value of 1.0e-6 will be used. Ideally, they should be estimates of the relative error in the entries of " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " respectively. For example, if the entries of " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": " have 7 correct digits, set " }, { "__type": "InlineCode", "__tag": 4051, "value": "atol = 1e-7" }, { "__type": "Text", "__tag": 4046, "value": ". This prevents the algorithm from doing unnecessary work beyond the uncertainty of the input data." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "conlim", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " terminates if an estimate of " }, { "__type": "InlineCode", "__tag": 4051, "value": "cond(A)" }, { "__type": "Text", "__tag": 4046, "value": " exceeds " }, { "__type": "ParamRef", "__tag": 4071, "name": "conlim" }, { "__type": "Text", "__tag": 4046, "value": ". For compatible systems " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ax = b" }, { "__type": "Text", "__tag": 4046, "value": ", conlim could be as large as 1.0e+12 (say). For least-squares problems, " }, { "__type": "ParamRef", "__tag": 4071, "name": "conlim" }, { "__type": "Text", "__tag": 4046, "value": " should be less than 1.0e+8. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "conlim" }, { "__type": "Text", "__tag": 4046, "value": " is None, the default value is 1e+8. Maximum precision can be obtained by setting " }, { "__type": "InlineCode", "__tag": 4051, "value": "atol = btol = conlim = 0" }, { "__type": "Text", "__tag": 4046, "value": ", but the number of iterations may then be excessive. Default is 1e8." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "lsmr", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._isolve.lsmr:lsmr" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " terminates if the number of iterations reaches " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxiter" }, { "__type": "Text", "__tag": 4046, "value": ". The default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "maxiter = min(m, n)" }, { "__type": "Text", "__tag": 4046, "value": ". For ill-conditioned systems, a larger value of " }, { "__type": "ParamRef", "__tag": 4071, "name": "maxiter" }, { "__type": "Text", "__tag": 4046, "value": " may be needed. Default is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "show", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Print iterations logs if " }, { "__type": "InlineCode", "__tag": 4051, "value": "show=True" }, { "__type": "Text", "__tag": 4046, "value": ". Default is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "x0", "annotation": "array_like, shape (n,), optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Initial guess of " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": ", if None zeros are used. Default is None." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 1.0.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "lsmr solves the system of linear equations " }, { "__type": "InlineCode", "__tag": 4051, "value": "Ax = b" }, { "__type": "Text", "__tag": 4046, "value": ". If the system is inconsistent, it solves the least-squares problem " }, { "__type": "InlineCode", "__tag": 4051, "value": "min ||b - Ax||_2" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": " is a rectangular matrix of dimension m-by-n, where all cases are allowed: m = n, m > n, or m < n. " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " is a vector of length m. The matrix A may be dense or sparse (usually sparse)." } ] } ], "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/lsmr.py", "item_line": 29, "item_type": "function", "aliases": [ "scipy.sparse.linalg.lsmr" ], "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 lsmr\nA = csc_array([[1., 0.], [1., 1.], [0., 1.]], dtype=float)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe first example has the trivial solution ``[0, 0]``\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b = np.array([0., 0., 0.], dtype=float)\nx, istop, itn, normr = lsmr(A, b)[:4]\nistop\nx\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe stopping code ``istop=0`` returned indicates that a vector of zeros was\nfound as a solution. The returned solution `x` indeed contains\n``[0., 0.]``. The next example has a non-trivial solution:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b = np.array([1., 0., -1.], dtype=float)\nx, istop, itn, normr = lsmr(A, b)[:4]\nistop\nx\nitn\nnormr\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAs indicated by ``istop=1``, `lsmr` found a solution obeying the tolerance\nlimits. The given solution ``[1., -1.]`` obviously solves the equation. The\nremaining return values include information about the number of iterations\n(`itn=1`) and the remaining difference of left and right side of the solved\nequation.\nThe final example demonstrates the behavior in the case where there is no\nsolution for the equation:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b = np.array([1., 0.01, -1.], dtype=float)\nx, istop, itn, normr = lsmr(A, b)[:4]\nistop\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "x\nA.dot(x)-b\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "normr\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n`istop` indicates that the system is inconsistent and thus `x` is rather an\napproximate solution to the corresponding least-squares problem. `normr`\ncontains the minimal distance that was found." } ], "title": [], "level": 0, "target": null }, "see_also": [], "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": "damp", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.0" }, { "__type": "SigParam", "__tag": 4030, "name": "atol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1e-06" }, { "__type": "SigParam", "__tag": 4030, "name": "btol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "1e-06" }, { "__type": "SigParam", "__tag": 4030, "name": "conlim", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "100000000.0" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "show", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "x0", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "lsmr" }, "references": [ ".. [1] D. C.-L. Fong and M. A. Saunders,", " \"LSMR: An iterative algorithm for sparse least-squares problems\",", " SIAM J. Sci. Comput., vol. 33, pp. 2950-2971, 2011.", " :arxiv:`1006.0758`", ".. [2] LSMR Software, https://web.stanford.edu/group/SOL/software/lsmr/" ], "qa": "scipy.sparse.linalg._isolve.lsmr:lsmr", "arbitrary": [], "local_refs": [ "A", "atol", "b", "btol", "conda", "conlim", "damp", "istop", "itn", "maxiter", "norma", "normar", "normr", "normx", "show", "x", "x0" ] }