{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [], "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": "Error raised under three conditions:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": true, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The algorithm failed due to a failure of the QR algorithm to compute all eigenvalues." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If eigenvalue sorting was requested, the eigenvalues could not be reordered due to a failure to separate eigenvalues, usually because of poor conditioning." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If eigenvalue sorting was requested, roundoff errors caused the leading eigenvalues to no longer satisfy the sorting condition." } ] } ] } ] } ] } ] } ], "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": "T", "annotation": "(M, M) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Schur form of A. It is real-valued for the real Schur decomposition." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "Z", "annotation": "(M, M) ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A unitary Schur transformation matrix for A. It is real-valued for the real Schur decomposition." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "sdim", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If and only if sorting was requested, a third return value will contain the number of eigenvalues satisfying the sort condition. Note that complex conjugate pairs for which the condition is true for either eigenvalue count as 2." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute Schur decomposition of a 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": "Matrix to decompose" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "output", "annotation": "{'real', 'complex'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When the dtype of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is real, this specifies whether to compute the real or complex Schur decomposition. When the dtype of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is complex, this argument is ignored, and the complex Schur decomposition is computed." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "lwork", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Work array size. If None or -1, it is automatically computed." } ] } ] }, { "__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 a (may improve performance)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "sort", "annotation": "{None, callable, 'lhp', 'rhp', 'iuc', 'ouc'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specifies whether the upper eigenvalues should be sorted. A callable may be passed that, given an eigenvalue, returns a boolean denoting whether the eigenvalue should be sorted to the top-left (True)." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "output='complex'" }, { "__type": "Text", "__tag": 4046, "value": " OR the dtype of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is complex, the callable should have one argument: the eigenvalue expressed as a complex number." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "output='real'" }, { "__type": "Text", "__tag": 4046, "value": " AND the dtype of " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": " is real, the callable should have two arguments: the real and imaginary parts of the eigenvalue, respectively." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternatively, string parameters may be used " } ] }, { "__type": "Code", "__tag": 4050, "value": "'lhp' Left-hand plane (real(eigenvalue) < 0.0)\n'rhp' Right-hand plane (real(eigenvalue) >= 0.0)\n'iuc' Inside the unit circle (abs(eigenvalue) <= 1.0)\n'ouc' Outside the unit circle (abs(eigenvalue) > 1.0)", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Defaults to None (no sorting)." } ] } ] }, { "__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 matrix contains 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": "The Schur decomposition is " } ] }, { "__type": "Code", "__tag": 4050, "value": "A = Z T Z^H", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where Z is unitary and T is either upper-triangular, or for real Schur decomposition (output='real'), quasi-upper triangular. In the quasi-triangular form, 2x2 blocks describing complex-valued eigenvalue pairs may extrude from the diagonal." } ] }, { "__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_schur.py", "item_line": 17, "item_type": "function", "aliases": [ "scipy.linalg.schur" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.linalg import schur, eigvals\nA = np.array([[0, 2, 2], [0, 1, 2], [1, 0, 1]])\nT, Z = schur(A)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "T\nZ\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "T2, Z2 = schur(A, output='complex')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "T2\neigvals(T2)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nA custom eigenvalue-sorting condition that sorts by positive imaginary part\nis satisfied by only one eigenvalue.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "_, _, sdim = schur(A, output='complex', sort=lambda x: x.imag > 1e-15)\nsdim\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWhen ``output='real'`` and the array `a` is real, the `sort` callable must accept\nthe real and imaginary parts as separate arguments. Note that now the complex\neigenvalues ``-0.32948354+0.80225456j`` and ``-0.32948354-0.80225456j`` will be\ntreated as a complex conjugate pair, and according to the `sdim` documentation,\ncomplex conjugate pairs for which the condition is True for *either* eigenvalue\nincrease `sdim` by *two*.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "_, _, sdim = schur(A, output='real', sort=lambda x, y: y > 1e-15)\nsdim\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "rsf2csf", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.linalg._decomp_schur:rsf2csf" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Convert real Schur form to complex Schur form" } ] } ], "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": "output", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "real" }, { "__type": "SigParam", "__tag": 4030, "name": "lwork", "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": "sort", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "check_finite", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "schur" }, "references": null, "qa": "scipy.linalg._decomp_schur:schur", "arbitrary": [], "local_refs": [ "T", "Z", "a", "check_finite", "lwork", "output", "overwrite_a", "sdim", "sort" ] }