cumulative_energy()

cumulative_energy(singular_values, threshold: float = 0.9999, plot: bool = True, right: int = None, ax: Axes = None, **kwargs)

Compute the number of singular values needed to surpass a given cumulative energy threshold.

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

\[\kappa_r = \sum_{i=1}^r\sigma_i^2 \bigg/ \sum_{j=1}^k\sigma_j^2.\]

This function determines the smalled \(r\) such that \(\kappa_r \ge\) threshold.

Parameters:

singular_values(n,) ndarray

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

thresholdfloat or list[float]

Energy capture threshold(s). Default is 99.99%.

plotbool

If True, plot the cumulative energy and the capture threshold(s) against the singular value index (linear scale).

rightint or None

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

axmatplotlib.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 matplotlib.pyplot.plot().

Returns:

ranksint or list[int]

Number of singular values required to capture the specified energy.