cumulative_energy()

cumulative_energy(singular_values, threshold: float = 0.9999, plot: bool = True, right=None, ax=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)).

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

Returns

ranksint or list(int)

Number of singular values required to capture the specified energy.