Skip to main content

SS Hankel

CI Status Documentation Status

Test coverage percentage uv Ruff prek

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

Metadata

Release files for ss-hankel 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ss-hankel 1.1.1
File Size Uploaded Provenance Actions
ss_hankel-1.1.1.tar.gz 14.4 kB With provenance Details for ss_hankel-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ss-hankel 1.1.1
File Interpreter ABI Platform Actions
ss_hankel-1.1.1-py3-none-any.whl Python 3 none any Details for ss_hankel-1.1.1-py3-none-any.whl

Total release size: 27.0 kB

Release files / ss_hankel-1.1.1.tar.gz

Download URL ss_hankel-1.1.1.tar.gz
Size 14.4 kB
Tags Source
SHA-256 checksum
How to use checksums
aeeae2c8094d8cdf269f3dc50e2367c2dce18ddb3cd0f16009a1ef89b25e8fcb
BLAKE2b-256 checksum
How to use checksums
e861f942e2cab56e8d67e058b82ceae5522a0effc1bc74d9a3bda9de49db7372
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / ss_hankel-1.1.1-py3-none-any.whl

Download URL ss_hankel-1.1.1-py3-none-any.whl
Size 12.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7db69836cd0f91569b576bd1a9d920ae5a6cfe2a0c907dbdfd202fdaf0e2a6f
BLAKE2b-256 checksum
How to use checksums
285d2438dab24bba71f377631447842d4585ac8a847fb9bd71cbdf3dd1139510
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for ss-hankel 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ss_hankel-1.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page