rom.ecsw.bilinear_form_hyperrom_ecsw

Purpose: Implements ECSW-based hyperreduction for finite element bilinear forms, enabling fast reduced-order stiffness matrix assembly by combining Energy-Conserving Sampling and Weighting (ECSW) with intelligent element clustering. Achieves substantial computational savings while preserving the energy conservation properties of the full-order operator—making it particularly suited for structural dynamics, wave propagation, and long-time integration scenarios.

Summary: Provides the BilinearFormHYPERROM_ecsw class, which assembles the hyperreduced bilinear form by clustering active elements by their free DOF count for vectorized processing, extracting local stiffness submatrices using advanced NumPy indexing, applying ECSW weights to preserve physical structure, and accumulating contributions into the final ( r r ) reduced stiffness matrix via vectorized Einstein summation. This approach is especially effective when element distributions are relatively uniform, energy conservation is critical, and real-time ROM evaluation is required.

Author: Suparno Bhattacharyya

Classes

Name	Description
BilinearFormHYPERROM_ecsw	ECSW-based hyperreduced bilinear form with element clustering for efficient assembly.

BilinearFormHYPERROM_ecsw

rom.ecsw.bilinear_form_hyperrom_ecsw.BilinearFormHYPERROM_ecsw(
    form,
    elem_weight,
    ubasis,
    lob,
    rob,
    vbasis=None,
    free_dofs=None,
    mean=None,
    nthreads=0,
    dtype=np.float64,
)

Summary: Implements a hyperreduction strategy that combines ECSW with element clustering to achieve computationally efficient and physically consistent reduced stiffness matrix assembly. The approach introduces several key innovations:

Element clustering by free DOF count for vectorized batch operations, eliminating expensive Python loops over individual elements.
Energy-conserving weighted assembly that preserves physical properties such as symmetry and stability throughout the reduction.
Efficient submatrix extraction using advanced NumPy indexing to pull free-DOF blocks from local element matrices.
Vectorized Einstein summation for parallel contraction of entire element clusters onto the reduced basis.

This hyperreduction strategy is most effective for problems where energy conservation is critical, element DOF distributions are relatively uniform, computational stability is paramount for long-time integration, and real-time performance is required for control or optimization workflows.

Parameters

Name	Type	Description	Default
form	callable	Full-order bilinear form function to be hyperreduced; should accept test and trial basis functions and return element-wise stiffness contributions.	required
elem_weight	scalar or array_like, shape (n_elements,)	ECSW weights determining each element’s contribution to the reduced assembly; either a scalar applied uniformly or per-element weights from ECSW analysis.	required
ubasis	Basis	Trial-space FE basis containing full DOF count, element connectivity, and quadrature information for the original mesh.	required
lob	ndarray, shape (n_free, r) or (n_full, r)	Left (test) reduced basis matrix; shape depends on whether `free_dofs` is provided—if so, the basis is defined only on free DOFs.	required
rob	ndarray, shape (n_free, r) or (n_full, r)	Right (trial) reduced basis matrix with the same shape requirements as `lob`; projects full-order solutions to the (r)-dimensional reduced space.	required
vbasis	Basis or None	Test-space FE basis; defaults to `ubasis` for standard Galerkin formulations.	`None`
free_dofs	ndarray of int or None	Indices of global DOFs that are free (non-Dirichlet); if provided, all reduced bases and operations are restricted to these DOFs.	`None`
mean	ndarray or None	Mean snapshot vector for solution centering; required if snapshot data was mean-subtracted during reduced basis construction.	`None`
nthreads	int	Number of threads for parallel element matrix extraction; `0` uses serial execution.	`0`
dtype	numpy.dtype	Numeric precision for all computations and storage arrays.	`np.float64`

Attributes

Name	Type	Description
lob	ndarray	Left reduced basis matrix, possibly restricted to free DOFs.
rob	ndarray	Right reduced basis matrix, possibly restricted to free DOFs.
free_dofs	ndarray or None	Indices of free DOFs when Dirichlet boundary conditions are present.
mean	ndarray or None	Mean snapshot vector for solution centering and reconstruction.
r	int	Reduced dimension (number of reduced basis vectors).
mapping	ndarray of int	Mapping from full DOF indices to reduced free-DOF indices; Dirichlet-constrained DOFs are mapped to `-1`.
cluster_idx	list of ndarray	Element indices grouped by number of free DOFs per element; each entry contains indices of elements sharing the same free DOF count.
order_cluster	list of ndarray	Local DOF ordering within each cluster for efficient submatrix extraction; shape `(cluster_size, n_free_dofs_in_cluster)`.
w_cluster	list of ndarray	ECSW weights corresponding to elements in each cluster.
R_test_free	list of ndarray	Test basis matrices restricted to free DOFs for each cluster; shape `(cluster_size, n_free_dofs, r)`.
R_trial_free	list of ndarray	Trial basis matrices restricted to free DOFs for each cluster; shape `(cluster_size, n_free_dofs, r)`.
unique_freedom	ndarray of int	Unique counts of free DOFs per element, determining the number of distinct clusters.
weight	ndarray	Full array of ECSW element weights.
nonzero_elements	ndarray	Indices of elements with nonzero ECSW weights.
ubasis_rom	Basis	Trial basis restricted to nonzero-weight elements.
vbasis_rom	Basis	Test basis restricted to nonzero-weight elements.
element_dofs	ndarray	Element-to-DOF connectivity for the restricted mesh.
free_indices	ndarray	Free DOF indices for each element.
mask	ndarray of bool	Boolean mask indicating which DOFs are free within each element’s local DOF set.
n_freedom	ndarray of int	Number of free DOFs per element.

Methods

Name	Description
assemble_weighted_ecsw	Assemble the globally weighted reduced stiffness matrix using ECSW element clustering.
extract_element_matrices_rom	Extract local element stiffness matrices for the hyperreduced mesh.

assemble_weighted_ecsw

rom.ecsw.bilinear_form_hyperrom_ecsw.BilinearFormHYPERROM_ecsw.assemble_weighted_ecsw(**kwargs)

Summary: Orchestrates the complete ECSW hyperreduction assembly to produce the final reduced stiffness matrix ( K_r ^{r r} ). Executes the following five stages:

Element Matrix Extraction: Calls element extraction routines to compute local stiffness matrices for all active elements, leveraging parallel processing when available.
Cluster-Based Processing: Processes elements in clusters grouped by their free DOF count, enabling highly efficient vectorized operations over entire element groups.
Submatrix Extraction: For each cluster, extracts free-DOF submatrices from local element matrices using advanced NumPy indexing.
ECSW Weighting: Applies energy-conserving element weights to preserve physical properties during reduction.
Vectorized Contraction: Uses Einstein summation to perform parallel contractions over entire clusters:

[ K_r = {e} R{}[e]^(w[e] K_{}[e]) R_{}[e] ]

The final result preserves the mathematical structure of the full-order operator while achieving substantial computational savings through intelligent clustering and vectorization.

Parameters

Name	Type	Description	Default
**kwargs	dict	Additional keyword arguments forwarded to element extraction routines, such as material parameters or quadrature settings.	`{}`

Returns

Name	Type	Description
K_reduced	ndarray, shape (r, r)	Assembled reduced-order stiffness matrix ready for use in ROM linear solves; preserves the energy conservation properties of the full-order operator.

extract_element_matrices_rom

rom.ecsw.bilinear_form_hyperrom_ecsw.BilinearFormHYPERROM_ecsw.extract_element_matrices_rom(
    ubasis,
    vbasis=None,
    elem_indices=None,
    **kwargs,
)

Summary: Evaluates the bilinear form element by element over the hyperreduced mesh and returns local stiffness matrices for all active elements. Integration is restricted to the ECSW-selected element subset, dramatically reducing computational cost relative to full-mesh evaluation. Supports both serial and parallel execution modes. For each element ( e ), the local stiffness matrix entry is:

[ K_e[i,j] = _{_e} _i() (_j()) , d ]

where ( _i, _j ) are local basis functions and integration uses the quadrature rules embedded in the finite element basis.

Parameters

Name	Type	Description	Default
ubasis	Basis	Trial-space FE basis containing mesh connectivity, quadrature points, and basis function evaluations.	required
vbasis	Basis or None	Test-space FE basis; defaults to `ubasis` for standard Galerkin formulations.	`None`
elem_indices	array_like of int or None	Specific element indices to process; defaults to all elements in the hyperreduced mesh.	`None`
**kwargs	dict	Additional keyword arguments forwarded to the bilinear form evaluation, such as material parameters or other problem-specific data.	`{}`

Returns

Name	Type	Description
element_matrices	ndarray, shape (n_elements, n_local_dofs, n_local_dofs)	Stack of local element stiffness matrices; `element_matrices[e]` is the `n_local_dofs × n_local_dofs` stiffness matrix for element ( e ).

Raises

Type	Condition
ValueError	Raised if trial and test bases have incompatible quadrature point counts, indicating a mismatch in integration rules.

Functions

Name	Description
with_elements	Return a restricted basis on a specified subset of element indices.

with_elements

rom.ecsw.bilinear_form_hyperrom_ecsw.with_elements(self, elements=None)

Summary: Returns a new FacetBasis instance restricted to the specified subset of element indices. Used internally to construct the hyperreduced basis objects ubasis_rom and vbasis_rom covering only the active (nonzero-weight) elements, and is also available for external use when restricting any compatible basis to an element subset.

Parameters

Name	Type	Description	Default
elements	array_like of int or None	Subset of element indices to retain in the restricted basis; if `None`, the full basis is returned unchanged.	`None`

Returns

Name	Type	Description
restricted_basis	FacetBasis	New `FacetBasis` instance covering only the specified elements, with mesh connectivity and quadrature data adjusted accordingly.