Welcome to SS Hankel documentation!

Installation & Usage

Project Info

API Reference

SS Hankel

CI Status Documentation Status Test coverage percentage

uv Ruff pre-commit

PyPI Version Supported Python versions License

Documentation: https://ss-hankel.readthedocs.io

Source Code: https://github.com/34j/ss-hankel

Derivative-free method to find zeros of analytic (holomorphic) functions / solve nonlinear (polynomial / generalized) eigenvalue problems using contour integration. (Block SS-Hankel method, Block Sakurai Sugiura method)

Installation

Install this via pip (or your favourite package manager):

pip install ss-hankel

Usage

Below is a simple example of solving the following nonlinear eigenvalue problem from NEP-PACK Tutorial.

$$ f(x) = \begin{pmatrix} 3+e^{0.5x} & 2+2x+e^{0.5x} \ 3+e^{0.5x} & -1+x+e^{0.5x} \end{pmatrix} , \quad f(x) v = 0 $$

from typing import Any

import numpy as np
from numpy.typing import NDArray

from ss_hankel import score, ss_h_circle


def f(x: NDArray[Any]) -> NDArray[Any]: # deriative is not needed!
    return np.stack(
        [
            np.stack([3 + np.exp(0.5 * x), 2 + 2 * x + np.exp(0.5 * x)], axis=-1),
            np.stack([3 + np.exp(0.5 * x), -1 + x + np.exp(0.5 * x)], axis=-1),
        ],
        axis=-2,
    )


eig = ss_h_circle(
    f,
    num_vectors=2,
    max_order=8,
    circle_n_points=128, # number of integration points
    circle_radius=3, # radius of the contour
    circle_center=0, # center of the contour
)
print(f"Eigenvalues: {eig.eigval}") # eigenvalues inside the contour
print(f"Eigenvectors: {eig.eigvec}") # corresponding eigenvectors
print(f"|f(λ)v|/|f(λ)||v|: {score(f(eig.eigval), eig.eigvec)}")

Eigenvalues: [-3.+3.19507247e-15j]
Eigenvectors: [[-0.45042759-0.61296714j]
 [-0.38438888-0.52309795j]]
|f(λ)v|/|f(λ)||v|: [1.37836544e-15]

  • Batch calculation (function and/or contour) is supported.

    • Steps until SVD are batched. Function evaluations are batched (called only once).

    • Only the final step (solving small generalized eigenvalue problem) is not batched because the size of the eigenvalue problem (the number of eigenvalues in the contour) might be different and moreover scipy.linalg.eig does not support batch calculation.

  • Since random matrices U,V are used in the algorithm, the results may vary slightly on each run. np.random.Generator can be passed to control the randomness.

  • To get zeros of an analytic function, set lambda x: f(x)[..., None, None] as an argument. The SS-Hankel method for 1x1 matrix is completely equivalent to the Kravanja (1999)’s derivative-free root-finding method.

  • The default parameters are set to be impractically small. Consider increasing circle_n_points and max_order based on the problem and num_vectors based on the matrix size.

  • The number of eigenvalues (zeros) inside the contour is estimated by evaluating the numerical rank of the Hankel matrix. By default the singular values below the largest gap between singular values are considered meaningless, as propsed in Xiao (2016), but the behaviour can be controlled by manually setting rtol. atol (default: 1e-6) is useful in the case when no eigenvalues are inside the contour.

CLI Usage

> ss-hankel "{{3+Exp[x/2],2+2x+Exp[x/2]},{3+Exp[x/2],-1+x+Exp[x/2]}}" --circle-radius 4
eigenvalues:
[-3.-2.29788612e-15j]
eigenvectors (columns):
[[0.35283836-0.67388339j]
 [0.30110753-0.57508306j]]
|F(λ)v|/|F(λ)||v|:
[9.82824873e-16]
singular_values:
[1.36659229e-01 5.51578001e-17 3.11252713e-17 2.25070948e-17
 1.05446714e-17 9.42202841e-18 6.28427578e-18 2.84988862e-18]

References

Alternatives

Zeros of analytic functions

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits

Copier

This package was created with Copier and the browniebroke/pypackage-template project template.