rom.ecm.helpers

Purpose: Supplies utility routines for preparing, converting, and managing ECM (Empirical Cubature Method) weights so they are compatible with the ROM assembly classes in this package. Handles the conversion from various weight formats—sparse mappings, flat index-weight pairs, or dense arrays—into the standardized dense per-element, per-Gauss-point arrays expected by the ECM bilinear and linear form assemblers.

Summary: Provides four focused helper functions covering active element identification, dense weight array construction, flat-to-dense weight conversion with optional quadrature rescaling, and basis restriction to element subsets. These utilities form the bridge between ECM solver output (which may use absolute cubature weights or sparse representations) and the multiplicative-weight convention required by the ROM assemblers in this folder.

Conventions

The ECM bilinear and linear form assemblers in this package expect ECM weights as multiplicative factors applied to scikit-fem’s native per-Gauss-point contributions—that is, values that already incorporate basis.dx. If your ECM implementation or external software returns absolute cubature weights (i.e., weights representing stand-alone integration values rather than multipliers), use flat_to_element_gauss_weights with the base_quadrature_weights argument to rescale them into the correct multiplicative form before passing to any ROM assembler.

Functions

Name	Description
active_ecm_elements	Return indices of elements with at least one active (nonzero) Gauss-point weight.
dense_ecm_weights	Construct a dense ECM weight array of shape `(n_elements, n_gauss_points)` from various input formats.
flat_to_element_gauss_weights	Convert flat ECM index-weight pairs to a dense element × Gauss-point weight array, with optional quadrature rescaling.
with_elements	Restrict a FacetBasis or similar basis object to a specified subset of elements.

active_ecm_elements

rom.ecm.helpers.active_ecm_elements(weight_array, *, atol=0.0)

Summary: Scans the ECM weight array and returns the indices of all elements that have at least one Gauss-point weight whose absolute value exceeds atol. This provides a fast way to identify the active element subset used by ECM-based hyperreduction, enabling downstream assembly routines to restrict computation to only the contributing elements.

Parameters

Name	Type	Description	Default
weight_array	ndarray, shape (n_elements, n_gauss_points)	Dense ECM weight array to scan for active entries.	required
atol	float	Absolute tolerance below which a weight is considered zero and the corresponding Gauss point inactive.	`0.0`

Returns

Name	Type	Description
active_indices	ndarray of int	Indices of elements containing at least one Gauss-point weight with absolute value greater than `atol`.

dense_ecm_weights

rom.ecm.helpers.dense_ecm_weights(
    weight_data,
    n_elements,
    n_gauss_points,
    *,
    dtype=np.float64,
)

Summary: Constructs a dense weight array of shape (n_elements, n_gauss_points) suitable for direct use in ROM assembly routines. Accepts three input formats for weight_data, allowing seamless integration with different ECM solver output conventions:

A mapping from element index to a sequence of per-Gauss-point weights (sparse dictionary format).
A dense array of shape (n_elements, n_gauss_points) passed through directly.
A flat array of length n_elements × n_gauss_points reshaped into the required 2D layout.

Parameters

Name	Type	Description	Default
weight_data	Mapping[int, Sequence[float]] or array_like	ECM weight data in one of the three supported formats described above.	required
n_elements	int	Total number of elements in the mesh.	required
n_gauss_points	int	Number of Gauss points per element.	required
dtype	DTypeLike	Numeric data type for the returned array.	`np.float64`

Returns

Name	Type	Description
weights	ndarray, shape (n_elements, n_gauss_points)	Dense ECM weight array ready for use in ROM assembly.

flat_to_element_gauss_weights

rom.ecm.helpers.flat_to_element_gauss_weights(
    n_elements,
    n_gauss_points,
    selected_indices,
    selected_weights,
    *,
    base_quadrature_weights=None,
    dtype=np.float64,
)

Summary: Converts the flat index-weight pairs produced by an ECM solver into a dense (n_elements, n_gauss_points) weight array. The flat selected_indices array contains Gauss-point indices in the linearized element × quadrature-point space (as typically output by ECM algorithms), and selected_weights holds their corresponding ECM weights.

When base_quadrature_weights is provided, each ECM weight is divided by the corresponding reference quadrature weight at that Gauss point. This rescaling is required when the ECM solver returns absolute cubature weights rather than multipliers for basis.dx-scaled contributions. After rescaling, the resulting weights are consistent with the multiplicative convention expected by the ROM assemblers in this package:

[ w_{e,q}^{} = ]

Parameters

Name	Type	Description	Default
n_elements	int	Total number of elements in the mesh.	required
n_gauss_points	int	Number of Gauss points per element.	required
selected_indices	array_like	Flat indices of the ECM-selected Gauss points in the linearized (element × quadrature point) space.	required
selected_weights	array_like	ECM weights corresponding to each selected Gauss point.	required
base_quadrature_weights	array_like or None	Reference quadrature weights of length `n_gauss_points`; when provided, ECM weights are divided by these to convert from absolute cubature to multiplicative form.	`None`
dtype	DTypeLike	Numeric data type for the returned array.	`np.float64`

Returns

Name	Type	Description
weight_array	ndarray, shape (n_elements, n_gauss_points)	Dense ECM weight array in multiplicative form, ready for ROM assembly. Unselected Gauss points receive a weight of zero.

with_elements

rom.ecm.helpers.with_elements(self, elements=None)

Summary: Returns a modified version of a FacetBasis (or compatible basis object) that is restricted to a specified subset of mesh elements. This is particularly useful for constructing the hyperreduced basis object used during ECM assembly, where only the active elements contribute and full-mesh basis operations would be wasteful.

Parameters

Name	Type	Description	Default
self	Basis	The basis object to restrict (FacetBasis or compatible type).	required
elements	array_like of int or None	Indices of the elements to retain; if `None`, the full basis is returned unchanged.	`None`

Returns

Name	Type	Description
restricted_basis	Basis	A basis object covering only the specified element subset, with mesh connectivity and quadrature data adjusted accordingly.

Notes

Use these helpers in the following order for a typical ECM weight preparation workflow:

Run your ECM solver to obtain flat selected_indices and selected_weights.
Call flat_to_element_gauss_weights (with base_quadrature_weights if using absolute cubature weights) to produce the dense weight array.
Pass the result to active_ecm_elements to identify the contributing elements.
Use with_elements to restrict your FE basis to those active elements before passing to BilinearFormHYPERROM_ecm or the linear form equivalent.