residual_energy()

residual_energy(singular_values, threshold: float = 1e-06, plot: bool = True, right=None, ax=None, **kwargs)

Compute the number of singular values needed such that the residual energy drops beneath a given threshold.

The residual energy of \(r\) singular values is defined by

\[\epsilon_r = \sum_{i=r+1}^k\sigma_i^2 \bigg/ \sum_{j=1}^k\sigma_j^2 = 1 - \left( \sum_{i=1}^r\sigma_i^2 \bigg/ \sum_{j=1}^k\sigma_j^2 \right)\]

This function determines the smallest \(r\) such that \(\epsilon_r \le\) threshold.

Parameters

singular_values(n,) ndarray

Singular values of a snapshot matrix, e.g., scipy.linalg.svdvals(states).

thresholdfloat or list[floats]

Energy residual threshold(s). Default is 10^-6.

plotbool

If True, plot the residual energy and the threshold(s) against the singular value index.

rightint or None

Maximum singular value index to plot (plt.xlim(right=right)).

axplt.Axes or None

Axes to plot the results on if plot=True. If not given, a new single-axes figure is created.

kwargsdict

Options to pass to plt.semilogy()

Returns

ranksint or list[int]

Number of singular values required to shrink the residual energy below the specified threshold.