rom.ecsw.hyperreduce

Purpose: Implements the end-to-end hyper-reduction pipeline for ECSW-based reduced-order modeling, combining optional randomized SVD preprocessing with a bounded Non-Negative Least Squares (NNLS) solve to compute positive cubature weights from a quantity-of-interest (QoI) matrix. Serves as the primary high-level entry point for deriving ECSW element weights from snapshot data.

Summary: Provides the hyperreduce function, which accepts a QoI matrix, optionally compresses it via randomized SVD, constructs per-entry bounded constraints around the projected right-hand side, solves the resulting bounded NNLS problem using NNLSSolver, and returns the hyperreduction weight vector alongside a solver convergence flag. Optional diagnostic plots of singular value decay and NNLS coefficient distributions are available for result inspection.

The broader ecsw.hyperreduce package includes:

  • Randomized SVD preprocessing routines for fast dimensionality reduction
  • Bounded NNLS solve integration via custom_nnls
  • Plotting helpers for diagnostic visualization of reduction errors and singular value spectra

Author: Suparno Bhattacharyya

Functions

Name Description
hyperreduce Perform hyper-reduction via randomized SVD followed by a bounded NNLS solve.

hyperreduce

rom.ecsw.hyperreduce.hyperreduce(
    qoi,
    n_components=500,
    verbosity=2,
    plot=True,
    const_tol=1e-10,
    zero_tol=1e-14,
    svd=False,
)

Summary: Executes the complete hyper-reduction pipeline on a quantity-of-interest matrix. The pipeline proceeds through four stages:

  1. (Optional) Randomized SVD: If svd=True, applies scikit-learn’s randomized_svd with oversampling and power iterations to compress qoi to n_components dimensions, reducing the problem size before the NNLS solve.
  2. Constraint Construction: Builds per-entry lower and upper bounds around the projected right-hand side vector ( _q ):

[ b_{} = q - , b{} = _q + ]

where ( _q = V_q^{} ) is the projected right-hand side vector.

  1. Bounded NNLS Solve: Calls NNLSSolver to find the non-negative weight vector ( ) satisfying the bounded constraints within the specified tolerances.
  2. (Optional) Diagnostics: If plot=True, displays plots of the singular value decay spectrum and the NNLS solution coefficient distribution for result inspection.

The hyper-reduced approximation error is computed internally as:

[ = ]

and printed to console for diagnostic purposes.

Parameters

Name Type Description Default
qoi array_like, shape (n_samples, n_features) Quantity-of-interest matrix on which hyper-reduction is performed; rows correspond to samples and columns to features (e.g., element contributions). required
n_components int Number of SVD components to retain when svd=True; must not exceed ((,, )). 500
verbosity int Verbosity level forwarded to NNLSSolver; higher values yield more detailed per-iteration diagnostic output. 2
plot bool If True, displays plots of singular value decay and NNLS solution coefficients for diagnostic inspection. True
const_tol float Half-gap tolerance defining the bounded constraints around the projected right-hand side vector; smaller values enforce tighter constraint satisfaction. 1e-10
zero_tol float Threshold below which NNLS solution coefficients are treated as zero and excluded from the active weight set. 1e-14
svd bool If True, applies randomized SVD preprocessing to qoi before the NNLS solve; if False, solves directly on the original data. False

Returns

Name Type Description
x ndarray, shape (n_features,) or (n_components,) Non-negative hyperreduction weight coefficients from the bounded NNLS solve; shape depends on whether SVD preprocessing was applied.
flag int Exit status from NNLSSolver: 0 = converged successfully; 1 = reached maximum iterations; 2 = stalled; 3 = failed.

Raises

Type Condition
ValueError Raised if n_components exceeds ((,, )) when svd=True.

Notes

  • The randomized SVD step (when enabled) uses oversampling and power iterations for improved numerical stability and accuracy on large matrices.
  • Bounds are constructed symmetrically around the projected right-hand side; const_tol directly controls the feasibility tolerance of the NNLS solution.
  • The diagnostic error printed to console reflects how well the selected weights reproduce the full integration across all QoI samples.

Example

>>> import numpy as np
>>> from hyperreduce_module import hyperreduce
>>> data = np.random.rand(100, 200)
>>> x, flag = hyperreduce(data, n_components=50, svd=True, plot=False)
>>> print("Exit flag:", flag)
>>> print("Active basis vectors:", np.sum(x > 0))