API Reference

API Reference#

diffaaable.aaa(Z, F, tol=1e-13, mmax=100, return_errors=False)[source]#

This is a wrapped version of aaa as provided by baryrat, providing a custom jvp to enable differentiability.

For detailed information on the usage of aaa please refer to the original documentation:

Compute a rational approximation of `F` over the points `Z` using the
AAA algorithm.

Arguments:
    Z (array): the sampling points of the function. Unlike for interpolation
        algorithms, where a small number of nodes is preferred, since the
        AAA algorithm chooses its support points adaptively, it is better
        to provide a finer mesh over the support.
    F: the function to be approximated; can be given as a function or as an
        array of function values over ``Z``.
    tol: the approximation tolerance
    mmax: the maximum number of iterations/degree of the resulting approximant
    return_errors: if `True`, also return the history of the errors over
        all iterations

Returns:
    BarycentricRational: an object which can be called to evaluate the
    rational function, and can be queried for the poles, residues, and
    zeros of the function.

For more information, see the paper

  | The AAA Algorithm for Rational Approximation
  | Yuji Nakatsukasa, Olivier Sete, and Lloyd N. Trefethen
  | SIAM Journal on Scientific Computing 2018 40:3, A1494-A1522
  | https://doi.org/10.1137/16M1106122

as well as the Chebfun package <http://www.chebfun.org>. This code is an
almost direct port of the Chebfun implementation of aaa to Python.

Attention

Returns nodes, values, weights and poles, in contrast to the baryrat implementation that returns the BarycentricRational ready to be evaluated. This is done to facilitate differentiability.

Parameters:

  • z_k (array (M,)) – the sampling points of the function. Unlike for interpolation algorithms, where a small number of nodes is preferred, since the AAA algorithm chooses its support points adaptively, it is better to provide a finer mesh over the support.

  • f_k (array (M,)) – the function to be approximated; can be given as a callable function or as an array of function values over z_k.

  • tol (float) – the approximation tolerance

  • mmax (int) – the maximum number of iterations/degree of the resulting approximant

Returns:

  • z_j (array (m,)) – nodes of the barycentric approximant

  • f_j (array (m,)) – values of the barycentric approximant

  • w_j (array (m,)) – weights of the barycentric approximant

  • z_n (array (m-1,)) – poles of the barycentric approximant (for convenience)

diffaaable - JAX-differentiable AAA algorithm

diffaaable.lorentz_aaa(z_k, f_k, tol=1e-09, mmax=100, return_errors=False)[source]#
diffaaable.poles(z_j, w_j)[source]#

The poles of a barycentric rational with given nodes and weights. Poles lifted by zeros of the nominator are included. Thus the values \(f_j\) do not contribute and don’t need to be provided The implementation was modified from baryrat to support JAX AD.

Parameters:

  • z_j (array (m,)) – nodes of the barycentric rational

  • w_j (array (m,)) – weights of the barycentric rational

Returns:

z_n – poles of the barycentric rational (more strictly zeros of the denominator)

Return type:

array (m-1,)

diffaaable.residues(z_j, f_j, w_j, z_n)[source]#

Residues for given poles via formula for simple poles of quotients of analytic functions. The implementation was modified from baryrat to support JAX AD.

Parameters:

  • z_j (array (m,)) – nodes of the barycentric rational

  • w_j (array (m,)) – weights of the barycentric rational

  • z_n (array (n,)) – poles of interest of the barycentric rational (n<=m-1)

Returns:

r_n – residues of poles z_n

Return type:

array (n,)

diffaaable.selective_subdivision_aaa(f, domain, N=36, max_poles=400, cutoff=None, tol_aaa=1e-09, tol_pol=1e-05, suggestions=None, on_rim=False, Dmax=30, use_adaptive=True, evolutions_adaptive=5, radius_adaptive=0.0001, z_k=None, f_k=None, divide_horizontal=True, debug_plot_domains=False)[source]#

When the number of poles that need to be located is large it can be beneficial to subdivide the search domain. This function implements a recursive subdivision of the domain, that automatically terminates once the poles are found to a satisfactory degree.

Parameters:

  • f (callable) – The function that the pole search is conducted on. It should accept batches of complex numbers and return a complex number per input.

  • domain (Domain) – The pole search is limited to this domain.

  • N (int) – The initial number of samples. If the number of samples drops below N the algorithm will add N new samples to the domain.

  • max_poles (int) – The maximum number of poles that are considered valid within one search. If this number is exceeded the domain will be subdivided.

  • cutoff (float) – A cutoff to avoid numerical instability due to large samples close to poles. See also diffaaable.adaptive.adaptive_aaa.

  • tol_aaa (float) – The tolerance for the AAA algorithm. See also diffaaable.core.aaa.

  • tol_pol (float) – The tolerance for the pole search. This is used to determine if a pole has moved significantly since the last domain subdivision.

  • suggestions (array) – A list of poles that are already known. This is used internally to recursively call selective_subdivision_aaa.

  • on_rim (bool) – If True, the initial samples are taken on the rim of the domain. Selecting the samples on the domain border is closely related to similar contour integral approaches. It is however generally recomended to sample within the domain (default: False).

  • Dmax (int) – The maximum number of subdivisions. If this number is exceeded the algorithm will stop and return the current poles. TODO: allow the user to specify that when reaching Dmax the algorithm should return no poles to avoid false poles.

  • use_adaptive (bool) – If True, the algorithm will use the adaptive AAA algorithm within the subdomains to locate the poles more accurately. The samples collected while searching the parent domain are passed to the respective subdomains to minimize computational cost. Using the adaptive aaa is generally recommended (default: True). If False, the algorithm will use the standard AAA algorithm.

  • evolutions_adaptive (int) – The number of evolutions for the adaptive AAA algorithm.

  • radius_adaptive (float) – The radius for the adaptive AAA algorithm. See also diffaaable.adaptive.adaptive_aaa.

  • z_k (array) – The samples that have already been collected. This is used internally to recursively call selective_subdivision_aaa. It can also be used by the user to pass samples that are already known.

  • f_k (array) – The function values of the samples that have already been collected. This is used internally to recursively call selective_subdivision_aaa. It can also be used by the user to pass samples that are already known.

  • divide_horizontal (bool) – If True, the next domain division will be horizontal. Used internally to alternate between horizontal and vertical divisions during recursion.

  • debug_plot_domains (bool) – If True, the algorithm will plot the domains that are being searched. This is useful for debugging and understanding the algorithm.

diffaaable.set_aaa(z_k, f_k, tol=1e-13, mmax=100, reortho_iterations=3, normalize=True)[source]#

Implementation of the vector valued AAA algorithm avoiding repeated large SVDs

Parameters:

  • z_k (complex) – M sample points

  • f_k (complex) – MxN array of the sampled vector (size N) at z_k

diffaaable.tensor_aaa(z_k, F_k, tol_aaa=1e-09, mmax_aaa=100, thres_numerical_zero=1e-13, norm_power=0)[source]#

Convenience alternative to the vector valued AAA algorithm (aaa.vectorial) accepting a tensor valued function F_k (so arbitrary dimensionality) instead of the single dimension that aaa.vectorial requires.

This function will first flatten the tensor valued function F_k and then apply the AAA algorithm to the flattened data. The result will be reshaped to the original tensor shape. The AAA algorithm will only be applied to the non-zero entries of the tensor. The entries very close to zero for all z_k will be replaced by zero.

Internally tensor_aaa uses a sped up version of the AAA algorithm. (see https://doi.org/10.1093/imanum/draa098) This can lead to numerical issues when reorthogonalization is sloppy. Further investigation needed.

Parameters:

  • z_k (complex) – M sample points

  • F_k (complex) – Mx… array of the sampled vector (arbitrary size) evaluated at z_k

  • tol_aaa (float) – tolerance for the AAA algorithm

  • mmax_aaa (int) – maximum number of support points for the AAA algorithm

  • thres_numerical_zero (float) – threshold for detecting numerical zeros. These will be replaced by symbolic zeros and not fitted.

  • norm_power (int) – The different tensor entries are normalized by their maximum absolute value to the power of norm_power. By default norm_power=0 the tensor entries are not normalized.

diffaaable.vectorial_aaa(z_k, f_k, tol=1e-13, mmax=100, return_errors=False)[source]#

Find a rational approximation to \(\mathbf f(z)\) over the points \(z_k\) using a modified AAA algorithm, as presented in [^4]. Importantly the weights and thus also the poles are shared between all entries of \(\mathbf f(z)\).

Parameters:

  • z_k (array (M,):) – M sample points

  • f_k (array (M, V):) – vector valued function values

  • tol (float) – the approximation tolerance

  • mmax (int) – the maximum number of iterations/degree of the resulting approximant

Returns:

Contents