ss_hankel package¶

exception ss_hankel.EigvalsOutsidePathWarning[source]¶: Bases: RuntimeWarning

exception ss_hankel.MaxOrderTooSmallWarning[source]¶: Bases: RuntimeWarning

class ss_hankel.SSHCircleResult(*, eigval: ndarray[Any, dtype[Any]], eigvec: ndarray[Any, dtype[Any]], s: ndarray[Any, dtype[Any]], s_valid: ndarray[Any, dtype[bool]], n: int, circle_center: ndarray[Any, dtype[Any]], circle_radius: ndarray[Any, dtype[Any]])[source]¶

Bases: object

circle_center: ndarray[Any, dtype[Any]]¶: The center of the circle of shape […].

circle_radius: ndarray[Any, dtype[Any]]¶: The radius of the circle of shape […].

eigval: ndarray[Any, dtype[Any]]¶: The eigenvalues, an array of shape […] of (array of shape [neigval] if max_neigval >= neigval, else None)

eigvec: ndarray[Any, dtype[Any]]¶: The eigenvectors, an array of shape […] of (array of shape [n, neigval] if max_neigval >= neigval, else None)

n: int¶: The size of the matrix.

s: ndarray[Any, dtype[Any]]¶: Array of shape […, K * L]

s_valid: ndarray[Any, dtype[bool]]¶: Boolearn array of shape […, K * L]

class ss_hankel.SSHKwargs[source]¶

Bases: TypedDict

atol: NotRequired[float]¶: The absolute threshold to treat eigenvalues as zero, by default 1e-6

circle_center: NotRequired[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]¶: The center of the circle of shape […], by default 0

circle_n_points: NotRequired[int]¶: Number of integration points on the circle, by default 16

circle_radius: NotRequired[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes]]¶: The radius of the circle of shape […], by default 1

max_neigval: NotRequired[int | None]¶: The maximum number of eigenvalues to proceed calculation, by default None

max_order: NotRequired[int | None]¶: Maximum order of the moments μ_k and s_k, by default None.

num_vectors: NotRequired[int | None]¶: Number of linearly independent vectors (L), by default None.

rng: NotRequired[Generator | None]¶: The random number generator, by default None

rtol: NotRequired[float | Literal['auto']]¶: The relative threshold to treat eigenvalues as zero, by default “auto” If “auto”, the threshold is determined by searching the largest gap of singular values

ss_hankel.score(feigval: ndarray[Any, dtype[Any]], eigvec: ndarray[Any, dtype[Any]], /, ord: Any = None) → ndarray[Any, dtype[Any]][source]¶

Compute the accuracy of the solution of the eigenvalue problem.

|F(λ)v|/|F(λ)||v|

Parameters:

feigval (NDArray[Any]) – The function evaluated at the eigenvalues (…, n_eig, n, n).
eigvec (NDArray[Any]) – The eigenvectors of shape (…, n, n_eig).
ord (Any, optional) – Order of the norm to be passed to np.linalg.norm, by default None

Returns:

The score of the solution.

Return type:

NDArray[Any]

Sakurai-Sugiura method for the circle.

Parameters:

f (Callable[[np.ndarray], np.ndarray]) – An analytic function (F(z)). Array of shape [circle_n_points] will be passed and should return [circle_n_points, …, n, n] array.
num_vectors (int, optional) – Number of linearly independent vectors (L), by default None.
max_order (int, optional) – Maximum order of the moments μ_k and s_k, by default None. The size of hankel matrix is num_vectors * max_order.
circle_n_points (int, optional) – Number of integration points on the circle, by default 16
circle_center (complex, optional) – The center of the circle of shape […], by default 0
circle_radius (float, optional) – The radius of the circle of shape […], by default 1
rtol (float, optional) – The relative threshold to treat eigenvalues as zero, by default “auto” If “auto”, the threshold is determined by searching the largest gap of singular values
atol (float, optional) – The absolute threshold to treat eigenvalues as zero, by default 1e-6
max_neigval (int | None, optional) – The maximum number of eigenvalues to proceed calculation, by default None
rng (np.random.Generator | None, optional) – The random number generator, by default None

Returns:

The eigenvalues and eigenvectors.

Return type:

SakuraiSugiuraCircleResult

Warning

MaxOrderTooSmallWarning: The maximum order is too small against the number of eigenvalues.
EigvalsOutsidePathWarning: Some eigenvalues are outside the path.
NEigvalExceedMaxWarning: The number of eigenvalues is larger than max_neigval.

References

Asakura, J., Sakurai, T., Tadano, H., Ikegami, T., & Kimura, K. (2009). A numerical method for nonlinear eigenvalue problems using contour integrals. JSIAM Letters, 1, 52–55. https://doi.org/10.14495/jsiaml.1.52

Kravanja, P., & Van Barel, M. (1999). A Derivative-Free Algorithm for Computing Zeros of Analytic Functions. Computing (Vienna/New York), 63, 69–91. https://doi.org/10.1007/s006070050051

Xiao, J., Meng, S., Zhang, C., & Zheng, C. (2016). Resolvent sampling based Rayleigh-Ritz method for large-scale nonlinear eigenvalue problems. Computer Methods in Applied Mechanics and Engineering, 310, 33–57. https://doi.org/10.1016/j.cma.2016.06.018

Submodules¶

ss_hankel.cli module¶

ss_hankel.cli.main(expr: str, /, *, num_vectors: int | None = None, max_order: int | None = 8, circle_n_points: int = 256, circle_center: complex = 0, circle_radius: float = 1, rtol: float | Literal['auto'] = 'auto', atol: float = 1e-06, seed: int | None = None) → None[source]¶

Compute the eigenvalues and eigenvectors of a matrix-valued function.

Some default parameters (circle_n_points, max_order) are set larger than the default in the Python API for convenience.

Parameters:

expr (str) – The matrix-valued function in Mathematica format.
num_vectors (int, optional) – Number of linearly independent vectors (L), by default None.
max_order (int, optional) – Maximum order of the moments μ_k and s_k, by default 8. The size of hankel matrix is num_vectors * max_order.
circle_n_points (int, optional) – Number of integration points on the circle, by default 256
circle_center (complex, optional) – The center of the circle, by default 0
circle_radius (float, optional) – The radius of the circle, by default 1
rtol (float, optional) – The relative threshold to treat eigenvalues as zero, by default “auto” If “auto”, the threshold is determined by searching the largest gap of singular values
atol (float, optional) – The absolute threshold to treat eigenvalues as zero, by default 1e-6
seed (int, optional) – The seed for the random number generator, by default None. If None, the random number generator is not seeded.

ss_hankel.testing module¶

ss_hankel.testing.asakura_example_1(z: ndarray[Any, dtype[Any]]) → ndarray[Any, dtype[Any]][source]¶

Example 1 from Asakura 2009.

Parameters:: z (NDArray[Any]) – The input array of shape (…).
Returns:: Matrix of shape (…, 3, 3).
Return type:: NDArray[Any]

ss_hankel.testing.asakura_example_1_eigvals() → ndarray[Any, dtype[Any]][source]¶

The eigenvalues of example 1 from Asakura 2009.

Returns:: Eigenvalues of shape (6,).
Return type:: NDArray[Any]