romtools.vector_space.utils.truncater#

Constructing a basis via POD typically entails computing the SVD of a snapshot matrix,

\[\mathbf{U} ,\mathbf{\Sigma} = \mathrm{svd}(\mathbf{S})\]

and then selecting the first \(K\) left singular vectors (i.e., the first \(K\) columns of \(\mathbf{U}\)). Typically, \(K\) is determined through the decay of the singular values.

The truncater class is designed to truncate a basis. We provide concrete implementations that truncate based on a specified number of basis vectors and the decay of the singular values

Classes

BasisSizeTruncater(basis_dimension)

Truncates to a specified number of singular vectors, as specified in the constructor

EnergyBasedTruncater(threshold)

Truncates based on the decay of singular values, i.e., will define \(K\) to be the number of singular values such that the cumulative energy retained meets or exceeds a threshold.

LeftSingularVectorTruncater(*args, **kwargs)

Interface for the Truncater class.

NoOpTruncater()

No op implementation
class romtools.vector_space.utils.truncater.BasisSizeTruncater(basis_dimension)[source]#

Bases: object

Truncates to a specified number of singular vectors, as specified in the constructor

This class conforms to the LeftSingularVectorTruncater protocol.

Parameters:

basis_dimension (int)

get_energy()[source]#
Returns:

The energy criteria corresponding to the truncated basis

Return type:

float

truncate(basis, singular_values, total_energy=None)[source]#

Truncate the basis based on the specified dimension.

Parameters:

  • basis (np.ndarray) – The original basis matrix.

  • singular_values (np.ndarray) – The array of singular values associated with the basis matrix.

  • total_energy (float) – Optional squared Frobenius norm of the full snapshot matrix.

Returns:

The truncated basis matrix with the specified dimension.

Return type:

np.ndarray

class romtools.vector_space.utils.truncater.EnergyBasedTruncater(threshold)[source]#

Bases: object

Truncates based on the decay of singular values, i.e., will define \(K\) to be the number of singular values such that the cumulative energy retained meets or exceeds a threshold.

This class conforms to the LeftSingularVectorTruncater protocol.

Parameters:

threshold (float)

get_energy()[source]#
Returns:

The energy criteria corresponding to the truncated basis

Return type:

float

truncate(basis, singular_values, total_energy=None)[source]#

Truncate the basis based on the energy threshold.

Parameters:

  • basis (np.ndarray) – The original basis matrix.

  • singular_values (np.ndarray) – The array of singular values associated with the basis matrix.

  • total_energy (float) – Optional squared Frobenius norm of the full snapshot matrix. If omitted, the supplied singular values are treated as the complete spectrum.

Returns:

The truncated basis matrix based on the energy threshold.

Return type:

np.ndarray

class romtools.vector_space.utils.truncater.LeftSingularVectorTruncater(*args, **kwargs)[source]#

Bases: Protocol

Interface for the Truncater class.

truncate(basis, singular_values, total_energy=None)[source]#

Truncate left singular vectors.

total_energy is the squared Frobenius norm of the full snapshot matrix when it is available. This permits energy-based truncation when singular_values contains only a leading portion of the spectrum.

Parameters:

  • basis (ndarray)

  • singular_values (ndarray)

  • total_energy (float | None)

Return type:

ndarray

class romtools.vector_space.utils.truncater.NoOpTruncater[source]#

Bases: object

No op implementation

This class conforms to the LeftSingularVectorTruncater protocol.