{ "__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": [], "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": "r", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Residues corresponding to the poles. For repeated poles, the residues are ordered to correspond to ascending by power fractions." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "p", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Poles ordered by magnitude in ascending order." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "k", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Coefficients of the direct polynomial term." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute partial-fraction expansion of b(z) / a(z)." } ] } ], "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": "b", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Numerator polynomial coefficients." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "a", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Denominator polynomial coefficients." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The tolerance for two roots to be considered equal in terms of the distance between them. Default is 1e-3. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "unique_roots", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:unique_roots" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for further details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rtype", "annotation": "{'avg', 'min', 'max'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Method for computing a root to represent a group of identical roots. Default is 'avg'. See " }, { "__type": "CrossRef", "__tag": 4002, "value": "unique_roots", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:unique_roots" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for further details." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineRole", "__tag": 4003, "value": "M", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " is the degree of numerator " }, { "__type": "ParamRef", "__tag": 4071, "name": "b" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "N", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " the degree of denominator " }, { "__type": "ParamRef", "__tag": 4071, "name": "a" }, { "__type": "Text", "__tag": 4046, "value": ": " } ] }, { "__type": "Code", "__tag": 4050, "value": " b(z) b[0] + b[1] z**(-1) + ... + b[M] z**(-M)\nH(z) = ------ = ------------------------------------------\n a(z) a[0] + a[1] z**(-1) + ... + a[N] z**(-N)", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "then the partial-fraction expansion H(z) is defined as " } ] }, { "__type": "Code", "__tag": 4050, "value": " r[0] r[-1]\n= --------------- + ... + ---------------- + k[0] + k[1]z**(-1) ...\n (1-p[0]z**(-1)) (1-p[-1]z**(-1))", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If there are any repeated roots (closer than " }, { "__type": "ParamRef", "__tag": 4071, "name": "tol" }, { "__type": "Text", "__tag": 4046, "value": "), then the partial fraction expansion has terms like " } ] }, { "__type": "Code", "__tag": 4050, "value": " r[i] r[i+1] r[i+n-1]\n-------------- + ------------------ + ... + ------------------\n(1-p[i]z**(-1)) (1-p[i]z**(-1))**2 (1-p[i]z**(-1))**n", "execution_status": null, "out": "" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function is used for polynomials in negative powers of z, such as digital filters in DSP. For positive powers, use " }, { "__type": "CrossRef", "__tag": 4002, "value": "residue", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:residue" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See Notes of " }, { "__type": "CrossRef", "__tag": 4002, "value": "residue", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:residue" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for details about the algorithm." } ] } ], "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": "build-install/usr/lib/python3.14/site-packages/scipy/signal/_signaltools.py", "item_line": 3421, "item_type": "function", "aliases": [ "scipy.signal.residuez" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "The following example computes the partial-fraction\nexpansion of b(z) / a(z):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import signal\nb = np.array([1, 0.3])\na = np.array([1, -0.75, 0.125])\nr, p, k = signal.residuez(b, a)\nr\np\n", "execution_status": "success", "out": "array([0.25, 0.5 ])\n" }, { "__type": "Text", "__tag": 4046, "value": "\nThere is no direct term here, so `k` is empty:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "k\n", "execution_status": "success", "out": "array([], dtype=float64)\n" }, { "__type": "Text", "__tag": 4046, "value": "\nGet `b` and `a` back with `invresz`:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "signal.invresz(r, p, k)\n", "execution_status": "success", "out": "(array([1. , 0.3]), array([ 1. , -0.75 , 0.125]))\n" }, { "__type": "Text", "__tag": 4046, "value": "\nAn example where `k` is not empty:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b = np.array([2, -1, 0.1])\na = np.array([1, -0.5])\nr, p, k = signal.residuez(b, a)\nr, p\nk\n", "execution_status": "success", "out": "array([ 1.6, -0.2])\n" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "invresz", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:invresz" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "residue", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:residue" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "unique_roots", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:unique_roots" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__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": "a", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "tol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.001" }, { "__type": "SigParam", "__tag": 4030, "name": "rtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "avg" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "residuez" }, "references": null, "qa": "scipy.signal._signaltools:residuez", "arbitrary": [], "local_refs": [ "a", "b", "k", "p", "r", "rtype", "tol" ] }