{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "At iteration " }, { "__type": "InlineMath", "__tag": 4057, "value": "m" }, { "__type": "Text", "__tag": 4046, "value": " (at which point there are " }, { "__type": "InlineMath", "__tag": 4057, "value": "m" }, { "__type": "Text", "__tag": 4046, "value": " terms in the both the numerator and denominator of the approximation), the rational approximation in the AAA algorithm takes the barycentric form" } ] }, { "__type": "Math", "__tag": 4058, "value": "r(z) = n(z)/d(z) =\n\\frac{\\sum_{j=1}^m\\ w_j f_j / (z - z_j)}{\\sum_{j=1}^m w_j / (z - z_j)}," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "z_1,\\dots,z_m" }, { "__type": "Text", "__tag": 4046, "value": " are real or complex support points selected from " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineMath", "__tag": 4057, "value": "f_1,\\dots,f_m" }, { "__type": "Text", "__tag": 4046, "value": " are the corresponding real or complex data values from " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineMath", "__tag": 4057, "value": "w_1,\\dots,w_m" }, { "__type": "Text", "__tag": 4046, "value": " are real or complex weights." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Each iteration of the algorithm has two parts: the greedy selection the next support point and the computation of the weights. The first part of each iteration is to select the next support point to be added " }, { "__type": "InlineMath", "__tag": 4057, "value": "z_{m+1}" }, { "__type": "Text", "__tag": 4046, "value": " from the remaining unselected " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": ", such that the nonlinear residual " }, { "__type": "InlineMath", "__tag": 4057, "value": "|f(z_{m+1}) - n(z_{m+1})/d(z_{m+1})|" }, { "__type": "Text", "__tag": 4046, "value": " is maximised. The algorithm terminates when this maximum is less than " }, { "__type": "InlineCode", "__tag": 4051, "value": "rtol * np.linalg.norm(f, ord=np.inf)" }, { "__type": "Text", "__tag": 4046, "value": ". This means the interpolation property is only satisfied up to a tolerance, except at the support points where approximation exactly interpolates the supplied data." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the second part of each iteration, the weights " }, { "__type": "InlineMath", "__tag": 4057, "value": "w_j" }, { "__type": "Text", "__tag": 4046, "value": " are selected to solve the least-squares problem" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\text{minimise}_{w_j}|fd - n| \\quad \\text{subject to} \\quad\n\\sum_{j=1}^{m+1} w_j = 1," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "over the unselected elements of " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "One of the challenges with working with rational approximations is the presence of Froissart doublets, which are either poles with vanishingly small residues or pole-zero pairs that are close enough together to nearly cancel, see " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ". The greedy nature of the AAA algorithm means Froissart doublets are rare. However, if " }, { "__type": "ParamRef", "__tag": 4071, "name": "rtol" }, { "__type": "Text", "__tag": 4046, "value": " is set too tight then the approximation will stagnate and many Froissart doublets will appear. Froissart doublets can usually be removed by removing support points and then resolving the least squares problem. The support point " }, { "__type": "InlineMath", "__tag": 4057, "value": "z_j" }, { "__type": "Text", "__tag": 4046, "value": ", which is the closest support point to the pole " }, { "__type": "InlineMath", "__tag": 4057, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " with residue " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\alpha" }, { "__type": "Text", "__tag": 4046, "value": ", is removed if the following is satisfied" } ] }, { "__type": "Math", "__tag": 4058, "value": "|\\alpha| / |z_j - a| < \\verb|clean_up_tol| \\cdot \\tilde{f}," }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\tilde{f}" }, { "__type": "Text", "__tag": 4046, "value": " is the geometric mean of " }, { "__type": "CrossRef", "__tag": 4002, "value": "support_values", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "support_values" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "", "annotation": "RuntimeWarning", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rtol" }, { "__type": "Text", "__tag": 4046, "value": " is not achieved in " }, { "__type": "ParamRef", "__tag": 4071, "name": "max_terms" }, { "__type": "Text", "__tag": 4046, "value": " iterations." } ] } ] } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "AAA real or complex rational approximation." } ] } ], "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": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "support_points", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Support points of the approximation. These are a subset of the provided " }, { "__type": "ParamRef", "__tag": 4071, "name": "x" }, { "__type": "Text", "__tag": 4046, "value": " at which the approximation strictly interpolates " }, { "__type": "ParamRef", "__tag": 4071, "name": "y" }, { "__type": "Text", "__tag": 4046, "value": ". See notes for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "support_values", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Value of the approximation at the " }, { "__type": "CrossRef", "__tag": 4002, "value": "support_points", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "support_points" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "weights", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Weights of the barycentric approximation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "errors", "annotation": "array", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Error " }, { "__type": "InlineMath", "__tag": 4057, "value": "|f(z) - r(z)|_\\infty" }, { "__type": "Text", "__tag": 4046, "value": " over " }, { "__type": "InlineRole", "__tag": 4003, "value": "points", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " in the successive iterations of AAA." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "x", "annotation": "1D array_like, shape (n,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "1-D array containing values of the independent variable. Values may be real or complex but must be finite." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "y", "annotation": "1D array_like, shape (n,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Function values " }, { "__type": "InlineCode", "__tag": 4051, "value": "f(x)" }, { "__type": "Text", "__tag": 4046, "value": ". Infinite and NaN values of " }, { "__type": "InlineRole", "__tag": 4003, "value": "values", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and corresponding values of " }, { "__type": "InlineRole", "__tag": 4003, "value": "points", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " will be discarded." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rtol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Relative tolerance, defaults to " }, { "__type": "InlineCode", "__tag": 4051, "value": "eps**0.75" }, { "__type": "Text", "__tag": 4046, "value": ". If a small subset of the entries in " }, { "__type": "InlineRole", "__tag": 4003, "value": "values", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are much larger than the rest the default tolerance may be too loose. If the tolerance is too tight then the approximation may contain Froissart doublets or the algorithm may fail to converge entirely." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "max_terms", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of terms in the barycentric representation, defaults to " }, { "__type": "InlineCode", "__tag": 4051, "value": "100" }, { "__type": "Text", "__tag": 4046, "value": ". Must be greater than or equal to one." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "clean_up", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Automatic removal of Froissart doublets, defaults to " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ". See notes for more details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "clean_up_tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Poles with residues less than this number times the geometric mean of " }, { "__type": "InlineRole", "__tag": 4003, "value": "values", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " times the minimum distance to " }, { "__type": "InlineRole", "__tag": 4003, "value": "points", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are deemed spurious by the cleanup procedure, defaults to 1e-13. See notes for more details." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As described in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": ", the AAA algorithm is a greedy algorithm for approximation by rational functions on a real or complex set of points. The rational approximation is represented in a barycentric form from which the roots (zeros), poles, and residues can be computed." } ] } ], "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/interpolate/_bary_rational.py", "item_line": 213, "item_type": "class", "aliases": [ "scipy.interpolate.AAA" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Here we reproduce a number of the numerical examples from [1]_ as a demonstration\nof the functionality offered by this method.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport matplotlib.pyplot as plt\nfrom scipy.interpolate import AAA\nimport warnings\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFor the first example we approximate the gamma function on ``[-3.5, 4.5]`` by\nextrapolating from 100 samples in ``[-1.5, 1.5]``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.special import gamma\nsample_points = np.linspace(-1.5, 1.5, num=100)\nr = AAA(sample_points, gamma(sample_points))\nz = np.linspace(-3.5, 4.5, num=1000)\nfig, ax = plt.subplots()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.plot(z, gamma(z), label=\"Gamma\")\nax.plot(sample_points, gamma(sample_points), label=\"Sample points\")\nax.plot(z, r(z).real, '--', label=\"AAA approximation\")\nax.set(xlabel=\"z\", ylabel=\"r(z)\", ylim=[-8, 8], xlim=[-3.5, 4.5])\nax.legend()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-89ecabd95958b735.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nWe can also view the poles of the rational approximation and their residues:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "order = np.argsort(r.poles())\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "r.poles()[order]\nr.residues()[order]\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFor the second example, we call `AAA` with a spiral of 1000 points that wind 7.5\ntimes around the origin in the complex plane.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "z = np.exp(np.linspace(-0.5, 0.5 + 15j*np.pi, 1000))\nr = AAA(z, np.tan(np.pi*z/2), rtol=1e-13)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe see that AAA takes 12 steps to converge with the following errors:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "r.errors.size\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "r.errors\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nWe can also plot the computed poles:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fig, ax = plt.subplots()\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "ax.plot(z.real, z.imag, '.', markersize=2, label=\"Sample points\")\nax.plot(r.poles().real, r.poles().imag, '.', markersize=5,\n label=\"Computed poles\")\nax.set(xlim=[-3.5, 3.5], ylim=[-3.5, 3.5], aspect=\"equal\")\nax.legend()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-19596e51b8669332.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nWe now demonstrate the removal of Froissart doublets using the `clean_up` method\nusing an example from [1]_. Here we approximate the function\n:math:`f(z)=\\log(2 + z^4)/(1 + 16z^4)` by sampling it at 1000 roots of unity. The\nalgorithm is run with ``rtol=0`` and ``clean_up=False`` to deliberately cause\nFroissart doublets to appear.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "z = np.exp(1j*2*np.pi*np.linspace(0,1, num=1000))\ndef f(z):\n return np.log(2 + z**4)/(1 - 16*z**4)\nwith warnings.catch_warnings(): # filter convergence warning due to rtol=0\n warnings.simplefilter('ignore', RuntimeWarning)\n r = AAA(z, f(z), rtol=0, max_terms=50, clean_up=False)\nmask = np.abs(r.residues()) < 1e-13\nfig, axs = plt.subplots(ncols=2)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "axs[0].plot(r.poles().real[~mask], r.poles().imag[~mask], '.')\naxs[0].plot(r.poles().real[mask], r.poles().imag[mask], 'r.')\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nNow we call the `clean_up` method to remove Froissart doublets.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "with warnings.catch_warnings():\n warnings.simplefilter('ignore', RuntimeWarning)\n r.clean_up()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "mask = np.abs(r.residues()) < 1e-13\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "axs[1].plot(r.poles().real[~mask], r.poles().imag[~mask], '.')\naxs[1].plot(r.poles().real[mask], r.poles().imag[mask], 'r.')\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-eb861074bfdb7cf2.png" } }, { "__type": "Text", "__tag": 4046, "value": "\nThe left image shows the poles prior of the approximation ``clean_up=False`` with\npoles with residue less than ``10^-13`` in absolute value shown in red. The right\nimage then shows the poles after the `clean_up` method has been called." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "FloaterHormannInterpolator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.interpolate._bary_rational:FloaterHormannInterpolator" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Floater-Hormann barycentric rational interpolation." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "pade", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.interpolate._pade:pade" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Padé approximation." } ] } ], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "x", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "y", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "rtol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "max_terms", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "100" }, { "__type": "SigParam", "__tag": 4030, "name": "clean_up", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "clean_up_tol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "1e-13" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "AAA" }, "references": [ ".. [1] Y. Nakatsukasa, O. Sete, and L. N. Trefethen, \"The AAA algorithm for", " rational approximation\", SIAM J. Sci. Comp. 40 (2018), A1494-A1522.", " :doi:`10.1137/16M1106122`", ".. [2] J. Gilewicz and M. Pindor, Pade approximants and noise: rational functions,", " J. Comp. Appl. Math. 105 (1999), pp. 285-297.", " :doi:`10.1016/S0377-0427(02)00674-X`" ], "qa": "scipy.interpolate._bary_rational:AAA", "arbitrary": [], "local_refs": [ "clean_up", "clean_up_tol", "errors", "max_terms", "rtol", "support_points", "support_values", "weights", "x", "y" ] }