rom.ecm.train_ecm

Purpose: Provides high-level training routines for the Empirical Cubature Method (ECM) within the scikit-rom framework. These functions wrap the lower-level EmpiricalCubatureMethod class into streamlined workflows for constructing the Gauss-point selection and weight arrays needed for online ECM-based hyperreduced assembly.

Summary: Contains two functions: ECM, which performs the core ECM training given a preassembled residual snapshot matrix, and ECM_from_skrom, which provides a fully end-to-end wrapper integrating residual collection, ECM training, and output packaging into a single call compatible with the scikit-rom notebook structure.

Functions

Name	Description
ECM	Core ECM training routine adapted to the scikit-rom data layout.
ECM_from_skrom	End-to-end ECM training wrapper for the scikit-rom notebook structure.

ECM

rom.ecm.train_ecm.ECM(
    q_mus_ecm,
    n_elements,
    n_gauss_points,
    tol=1e-05,
    n_components=None,
    plot=False,
    constrain_sum_of_weights=False,
    dtype=np.float64,
    svd_rank=None,
)

Summary: Performs ECM training adapted to the scikit-rom data layout. Takes the residual snapshot matrix q_mus_ecm returned by collect_residuals_ecm, computes its SVD to determine the empirical basis, runs the EmpiricalCubatureMethod selection algorithm to identify the optimal Gauss-point subset and weights, and returns the results in both raw index-weight form and as a dense per-element, per-Gauss-point multiplier array ready for online assembly.

Parameters

Name	Type	Description	Default
q_mus_ecm	ndarray, shape (n_snapshots × r, n_elements × n_gauss_points)	Residual snapshot matrix returned by `collect_residuals_ecm`; each column corresponds to one element–Gauss-point contribution.	required
n_elements	int	Number of elements in the mesh.	required
n_gauss_points	int	Number of Gauss points per element.	required
tol	float	Singular value cutoff used to determine the ECM empirical basis size; smaller values retain more modes.	`1e-05`
n_components	int or None	If provided, overrides `tol` and uses exactly this many left singular vectors for the ECM basis.	`None`
plot	bool	If `True`, plots the singular value spectrum for diagnostic inspection.	`False`
constrain_sum_of_weights	bool	Passed directly to `EmpiricalCubatureMethod.SetUp`; if `True`, constrains the sum of selected weights to match the original integration sum.	`False`
dtype	numpy.dtype	Floating-point data type for all computations and output arrays.	`np.float64`
svd_rank	int or None	If provided, truncates the SVD to this rank before ECM basis selection.	`None`

Returns

Name	Type	Description
W	ndarray, shape (n_selected,)	ECM weights for the selected flat Gauss-point indices.
Z	ndarray, shape (n_selected,)	Selected flat indices in the range `[0, n_elements × n_gauss_points)` identifying the chosen Gauss points.
S	ndarray	Singular values of `q_mus_ecm.T`, useful for inspecting the decay rate and validating the basis size choice.
gauss_weight_ecm	ndarray, shape (n_elements, n_gauss_points)	Dense ECM multiplier array in per-element, per-Gauss-point layout, ready for direct use in online scikit-rom assembly routines.

ECM_from_skrom

rom.ecm.train_ecm.ECM_from_skrom(
    NLS_train_ms,
    NLS_train_mean,
    V_sel,
    reconstruct_solution,
    Residual,
    training_params,
    assemble_kwargs,
    basis,
    *,
    extra_kwargs=None,
    hyper_basis=None,
    tol=1e-05,
    n_components=None,
    plot=False,
    constrain_sum_of_weights=False,
    dtype=np.float64,
    svd_rank=None,
)

Summary: Provides a fully end-to-end ECM training workflow designed for the scikit-rom notebook structure. Handles residual collection over the training parameter set, constructs the snapshot matrix q_mus_ecm, invokes the ECM training routine, and packages all outputs into a single result dictionary. This wrapper eliminates manual intermediate steps between snapshot collection and ECM weight production, making it the recommended entry point for ECM offline training in scikit-rom workflows.

Returns

Name	Type	Description
result	dict	Dictionary containing all ECM training outputs with the following keys: `q_mus_ecm` (residual snapshot matrix), `W` (selected ECM weights), `Z` (selected flat Gauss-point indices), `S` (singular values), and `gauss_weight_ecm` (dense per-element, per-Gauss-point multiplier array).