{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelsy'" }, { "__type": "Text", "__tag": 4046, "value": " is used as a driver, " }, { "__type": "CrossRef", "__tag": 4002, "value": "residues", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "residues" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " is set to a (0,)-shaped array and " }, { "__type": "CrossRef", "__tag": 4002, "value": "s", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "s" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " is always " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "LinAlgError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If computation does not converge." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "ValueError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When parameters are not compatible." } ] } ] } ] } ], "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": "(N,) or (N, K) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Least-squares solution." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "residues", "annotation": "(K,) ndarray or float", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Square of the 2-norm for each column in " }, { "__type": "InlineCode", "__tag": 4051, "value": "b - a x" }, { "__type": "Text", "__tag": 4046, "value": ", if " }, { "__type": "InlineCode", "__tag": 4051, "value": "M > N" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "rank(A) == n" }, { "__type": "Text", "__tag": 4046, "value": " (returns a scalar if " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " is 1-D). Otherwise a (0,)-shaped array is returned." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rank", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Effective rank of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "s", "annotation": "(min(M, N),) ndarray or None", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Singular values of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": ". The condition number of " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "s[0] / s[-1]" }, { "__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": "Compute least-squares solution to the equation " }, { "__type": "InlineCode", "__tag": 4051, "value": "a @ x = b" }, { "__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": "a", "annotation": "(M, N) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Left-hand side array" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "b", "annotation": "(M,) or (M, K) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Right hand side array" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "cond", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Cutoff for 'small' singular values; used to determine effective rank of a. Singular values smaller than " }, { "__type": "InlineCode", "__tag": 4051, "value": "cond * largest_singular_value" }, { "__type": "Text", "__tag": 4046, "value": " are considered zero." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "overwrite_a", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Discard data in " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " (may enhance performance). Default is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "overwrite_b", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Discard data in " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " (may enhance performance). Default is False." } ] } ] }, { "__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 (crashes, non-termination) if the inputs do contain infinities or NaNs." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "lapack_driver", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Which LAPACK driver is used to solve the least-squares problem. Options are " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelsd'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelsy'" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelss'" }, { "__type": "Text", "__tag": 4046, "value": ". Default (" }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelsd'" }, { "__type": "Text", "__tag": 4046, "value": ") is a good choice. However, " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelsy'" }, { "__type": "Text", "__tag": 4046, "value": " can be slightly faster on many problems. " }, { "__type": "InlineCode", "__tag": 4051, "value": "'gelss'" }, { "__type": "Text", "__tag": 4046, "value": " was used historically. It is generally slow but uses less memory." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.17.0" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute a vector x such that the 2-norm " }, { "__type": "InlineCode", "__tag": 4051, "value": "|b - A x|" }, { "__type": "Text", "__tag": 4046, "value": " is minimized." } ] }, { "__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. Note that calls with zero-size batches are unsupported and will raise a " }, { "__type": "InlineCode", "__tag": 4051, "value": "ValueError" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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": 1606, "item_type": "function", "aliases": [ "scipy.linalg.lstsq" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.linalg import lstsq\nimport matplotlib.pyplot as plt\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSuppose we have the following data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x = np.array([1, 2.5, 3.5, 4, 5, 7, 8.5])\ny = np.array([0.3, 1.1, 1.5, 2.0, 3.2, 6.6, 8.6])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe want to fit a quadratic polynomial of the form ``y = a + b*x**2``\nto this data. We first form the \"design matrix\" M, with a constant\ncolumn of 1s and a column containing ``x**2``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "M = x[:, np.newaxis]**[0, 2]\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "M\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWe want to find the least-squares solution to ``M.dot(p) = y``,\nwhere ``p`` is a vector with length 2 that holds the parameters\n``a`` and ``b``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "p, res, rnk, s = lstsq(M, y)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "p\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nPlot the data and the fitted curve.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(x, y, 'o', label='data')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "xx = np.linspace(0, 9, 101)\nyy = p[0] + p[1]*xx**2\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "plt.plot(xx, yy, label='least squares fit, $y = a + bx^2$')\nplt.xlabel('x')\nplt.ylabel('y')\nplt.legend(framealpha=1, shadow=True)\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.grid(alpha=0.25)\nplt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-06bee8f579531ece.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "scipy.optimize.nnls", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.optimize._nnls:nnls" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "linear least squares with non-negativity constraint" } ] } ], "type": "func" } ], "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": "cond", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "overwrite_a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "overwrite_b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "check_finite", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "lapack_driver", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "lstsq" }, "references": null, "qa": "scipy.linalg._basic:lstsq", "arbitrary": [], "local_refs": [ "a", "b", "check_finite", "cond", "lapack_driver", "overwrite_a", "overwrite_b", "rank", "residues", "s", "x" ] }