{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function does not check the input array for being Hermitian/symmetric in order to allow for representing arrays with only their upper/lower triangular parts. Also, note that even though not taken into account, finiteness check applies to the whole array and unaffected by \"lower\" keyword." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function uses LAPACK drivers for computations in all possible keyword combinations, prefixed with " }, { "__type": "InlineCode", "__tag": 4051, "value": "sy" }, { "__type": "Text", "__tag": 4046, "value": " if arrays are real and " }, { "__type": "InlineCode", "__tag": 4051, "value": "he" }, { "__type": "Text", "__tag": 4046, "value": " if complex, e.g., a float array with \"evr\" driver is solved via \"syevr\", complex arrays with \"gvx\" driver problem is solved via \"hegvx\" etc." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As a brief summary, the slowest and the most robust driver is the classical " }, { "__type": "InlineCode", "__tag": 4051, "value": "ev" }, { "__type": "Text", "__tag": 4046, "value": " which uses symmetric QR. " }, { "__type": "InlineCode", "__tag": 4051, "value": "evr" }, { "__type": "Text", "__tag": 4046, "value": " is seen as the optimal choice for the most general cases. However, there are certain occasions that " }, { "__type": "InlineCode", "__tag": 4051, "value": "evd" }, { "__type": "Text", "__tag": 4046, "value": " computes faster at the expense of more memory usage. " }, { "__type": "InlineCode", "__tag": 4051, "value": "evx" }, { "__type": "Text", "__tag": 4046, "value": ", while still being faster than " }, { "__type": "InlineCode", "__tag": 4051, "value": "ev" }, { "__type": "Text", "__tag": 4046, "value": ", often performs worse than the rest except when very few eigenvalues are requested for large arrays though there is still no performance guarantee." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Note that the underlying LAPACK algorithms are different depending on whether " }, { "__type": "ParamRef", "__tag": 4071, "name": "eigvals_only" }, { "__type": "Text", "__tag": 4046, "value": " is True or False --- thus the eigenvalues may differ depending on whether eigenvectors are requested or not. The difference is generally of the order of machine epsilon times the largest eigenvalue, so is likely only visible for zero or nearly zero eigenvalues." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the generalized problem, normalization with respect to the given type argument " } ] }, { "__type": "Code", "__tag": 4050, "value": "type 1 and 3 : v.conj().T @ a @ v = w\ntype 2 : inv(v).conj().T @ a @ inv(v) = w\n\ntype 1 or 2 : v.conj().T @ b @ v = I\ntype 3 : v.conj().T @ inv(b) @ v = I", "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "LinAlgError", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If eigenvalue computation does not converge, an error occurred, or b matrix is not definite positive. Note that if input matrices are not symmetric or Hermitian, no error will be reported but results will be wrong." } ] } ] } ] } ], "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": "w", "annotation": "(N,) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The N (N<=M) selected eigenvalues, in ascending order, each repeated according to its multiplicity." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "v", "annotation": "(M, N) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The normalized eigenvector corresponding to the eigenvalue " }, { "__type": "InlineCode", "__tag": 4051, "value": "w[i]" }, { "__type": "Text", "__tag": 4046, "value": " is the column " }, { "__type": "InlineCode", "__tag": 4051, "value": "v[:,i]" }, { "__type": "Text", "__tag": 4046, "value": ". Only returned if " }, { "__type": "InlineCode", "__tag": 4051, "value": "eigvals_only=False" }, { "__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 a standard or generalized eigenvalue problem for a complex Hermitian or real symmetric matrix." } ] } ], "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, M) array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A complex Hermitian or real symmetric matrix whose eigenvalues and eigenvectors will be computed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "b", "annotation": "(M, M) array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A complex Hermitian or real symmetric definite positive matrix in. If omitted, identity matrix is assumed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "lower", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether the pertinent array data is taken from the lower or upper triangle of " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " and, if applicable, " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": ". (Default: lower)" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "eigvals_only", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to calculate only eigenvalues and no eigenvectors. (Default: both are calculated)" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "subset_by_index", "annotation": "iterable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, this two-element iterable defines the start and the end indices of the desired eigenvalues (ascending order and 0-indexed). To return only the second smallest to fifth smallest eigenvalues, " }, { "__type": "InlineCode", "__tag": 4051, "value": "[1, 4]" }, { "__type": "Text", "__tag": 4046, "value": " is used. " }, { "__type": "InlineCode", "__tag": 4051, "value": "[n-3, n-1]" }, { "__type": "Text", "__tag": 4046, "value": " returns the largest three. Only available with \"evr\", \"evx\", and \"gvx\" drivers. The entries are directly converted to integers via " }, { "__type": "InlineCode", "__tag": 4051, "value": "int()" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "subset_by_value", "annotation": "iterable, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, this two-element iterable defines the half-open interval " }, { "__type": "InlineCode", "__tag": 4051, "value": "(a, b]" }, { "__type": "Text", "__tag": 4046, "value": " that, if any, only the eigenvalues between these values are returned. Only available with \"evr\", \"evx\", and \"gvx\" drivers. Use " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.inf" }, { "__type": "Text", "__tag": 4046, "value": " for the unconstrained ends." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "driver", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defines which LAPACK driver should be used. Valid options are \"ev\", \"evd\", \"evr\", \"evx\" for standard problems and \"gv\", \"gvd\", \"gvx\" for generalized (where b is not None) problems. See the Notes section. The default for standard problems is \"evr\". For generalized problems, \"gvd\" is used for full set, and \"gvx\" for subset requested cases." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "type", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For the generalized problems, this keyword specifies the problem type to be solved for " }, { "__type": "InlineCode", "__tag": 4051, "value": "w" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "v" }, { "__type": "Text", "__tag": 4046, "value": " (only takes 1, 2, 3 as possible inputs) " } ] }, { "__type": "Code", "__tag": 4050, "value": "1 => a @ v = w @ b @ v\n2 => a @ b @ v = w @ v\n3 => b @ a @ v = w @ v", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This keyword is ignored for standard problems." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "overwrite_a", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to overwrite data in " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " (may improve 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": "Whether to overwrite data in " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " (may improve 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." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Find eigenvalues array " }, { "__type": "InlineCode", "__tag": 4051, "value": "w" }, { "__type": "Text", "__tag": 4046, "value": " and optionally eigenvectors array " }, { "__type": "InlineCode", "__tag": 4051, "value": "v" }, { "__type": "Text", "__tag": 4046, "value": " of array " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " is positive definite such that for every eigenvalue λ (i-th entry of w) and its eigenvector " }, { "__type": "InlineCode", "__tag": 4051, "value": "vi" }, { "__type": "Text", "__tag": 4046, "value": " (i-th column of " }, { "__type": "InlineCode", "__tag": 4051, "value": "v" }, { "__type": "Text", "__tag": 4046, "value": ") satisfies " } ] }, { "__type": "Code", "__tag": 4050, "value": " a @ vi = λ * b @ vi\nvi.conj().T @ a @ vi = λ\nvi.conj().T @ b @ vi = 1", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the standard problem, " }, { "__type": "InlineCode", "__tag": 4051, "value": "b" }, { "__type": "Text", "__tag": 4046, "value": " is assumed to be the identity matrix." } ] }, { "__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/_decomp.py", "item_line": 284, "item_type": "function", "aliases": [ "scipy.linalg.eigh" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.linalg import eigh\nA = np.array([[6, 3, 1, 5], [3, 0, 5, 1], [1, 5, 6, 2], [5, 1, 2, 2]])\nw, v = eigh(A)\nnp.allclose(A @ v - v @ np.diag(w), np.zeros((4, 4)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nRequest only the eigenvalues\n\n" }, { "__type": "Code", "__tag": 4050, "value": "w = eigh(A, eigvals_only=True)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nRequest eigenvalues that are less than 10.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "A = np.array([[34, -4, -10, -7, 2],\n [-4, 7, 2, 12, 0],\n [-10, 2, 44, 2, -19],\n [-7, 12, 2, 79, -34],\n [2, 0, -19, -34, 29]])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "eigh(A, eigvals_only=True, subset_by_value=[-np.inf, 10])\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nRequest the second smallest eigenvalue and its eigenvector\n\n" }, { "__type": "Code", "__tag": 4050, "value": "w, v = eigh(A, subset_by_index=[1, 1])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "w\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "v.shape # only a single column is returned\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "eig", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._decomp:eig" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "eigenvalues and right eigenvectors for non-symmetric arrays" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "eigh_tridiagonal", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._decomp:eigh_tridiagonal" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "eigenvalues and right eigenvectors for symmetric/Hermitian tridiagonal matrices" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "eigvalsh", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._decomp:eigvalsh" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "eigenvalues of symmetric or Hermitian arrays" } ] } ], "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": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "lower", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "eigvals_only", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "overwrite_a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "overwrite_b", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "type", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "1" }, { "__type": "SigParam", "__tag": 4030, "name": "check_finite", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "subset_by_index", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "subset_by_value", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "driver", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "eigh" }, "references": null, "qa": "scipy.linalg._decomp:eigh", "arbitrary": [], "local_refs": [ "a", "b", "check_finite", "driver", "eigvals_only", "lower", "overwrite_a", "overwrite_b", "subset_by_index", "subset_by_value", "type", "v", "w" ] }