romtools.hyper_reduction.deim#

Implementation of DEIM technique for hyper-reduction

Functions

`deim_get_approximation_matrix`(...)	Given a function basis \(\mathbf{U}\) and sample indices defining \(\mathbf{P}\), we compute
`deim_get_indices`(U[, comm])	Implementation of the discrete empirical method as described in Algorithm 1 of S.
`deim_get_test_basis`(test_basis, ...[, comm])	Given a test basis \(\mathbf{\Phi}\), a function basis \(\mathbf{U}\), and sample indices defining \(\mathbf{P}\), we compute
`multi_state_deim_get_indices`(U[, comm])	Version of DEIM for multi-state systems.
`multi_state_deim_get_test_basis`(test_basis, ...)	For multistate systems. Constructs an independent DEIM basis for each state variable using uniform sample indices :param test_basis: \((n_{var}, m, k)\) array, where \(n_{var}\) is the number of state variables, \(m\) is the number of DOFs and \(k\) is the number of basis functions. Test basis in projection scheme :param function_basis: \((n_{var}, m, n)\) array, where \(n_{var}\) is the number of state variables, \(m\) is the number of DOFs and \(n\) is the number of basis functions. Basis for function to be approximated. :param sample_indices: \((n_s, )\) array, where \(n_s\) is the number of sample points. Sampling points.
`qdeim_get_indices`(function_basis)	Select interpolation indices using QDEIM for a matrix-form basis.

Classes

`DEIM`(function_basis[, sample_indices, ...])	Serial discrete empirical interpolation operator.
`QDEIM`(function_basis[, sample_indices, ...])	Tensor-native DEIM operator using pivoted-QR point selection.

class romtools.hyper_reduction.deim.DEIM(function_basis, sample_indices=None, rcond=None, sample_all_states=True, basis_mode='per_state')[source]#

Bases: object

Serial discrete empirical interpolation operator.

The public class API follows the romtools tensor convention. Function snapshots have shape (n_vars, n_dofs, n_snapshots) and tensor-form function bases have shape (n_vars, n_dofs, n_basis).

basis_mode="per_state" is the default. A separate POD/function basis and DEIM sampling problem is constructed for each state variable. The state-specific sample sets are unioned into a common spatial sample mesh, and every state is sampled on that mesh. This avoids mixing quantities with different physical units in a single POD/SVD and allows the states to have different basis dimensions when constructed from snapshots.

basis_mode="global" retains the coupled formulation in which the first two tensor axes are collapsed in explicit C order and a single global basis is used. Global mode can exploit cross-state correlations but requires the state variables to be consistently nondimensionalized or weighted.

Notes

Function snapshots are snapshots of the quantity being approximated, such as a nonlinear term or residual. They are not necessarily the state snapshots used to construct a ROM trial basis.

property basis_mode#: Return "per_state" or "global".

property basis_sizes#: Return the number of function-basis vectors associated with each state.

classmethod from_basis(function_basis, sample_indices=None, rcond=None, sample_all_states=True, basis_mode='per_state')[source]#

Construct a serial DEIM operator from a tensor-form function basis.

Parameters:

function_basis – (n_vars, n_dofs, n_basis) function basis. In per_state mode, each state slice is treated as an independent basis. The tensor form therefore requires a common basis dimension across states when bases are supplied directly.
sample_indices – Optional rank-1 integer array. In per_state mode and in shared-sample global mode these are spatial indices. With basis_mode="global" and sample_all_states=False these are flattened state-DOF indices in C order.
rcond – Relative cutoff passed to numpy.linalg.pinv().
sample_all_states – If True (default), sample every state at each selected spatial point. False is supported only in global mode.
basis_mode – "per_state" (default) constructs independent DEIM operators for each state and unions their sample points. "global" constructs one coupled operator.

Returns:

Constructed interpolation operator.

Return type:

DEIM

classmethod from_snapshots(function_snapshots, truncater=None, sample_indices=None, rcond=None, sample_all_states=True, basis_mode='per_state')[source]#

Construct a serial DEIM operator from tensor-form function snapshots.

Parameters:

function_snapshots – (n_vars, n_dofs, n_snapshots) snapshots of the function to be approximated.
truncater – Optional implementation of the LeftSingularVectorTruncater protocol. In per_state mode the truncater is applied independently to each state’s SVD, so energy-based truncation may produce different basis dimensions for different states. If omitted, all available modes are retained.
sample_indices – Optional rank-1 integer array. In per_state mode and in shared-sample global mode these are spatial indices. With basis_mode="global" and sample_all_states=False these are flattened state-DOF indices in C order.
rcond – Relative cutoff passed to numpy.linalg.pinv().
sample_all_states – If True (default), sample every state at each selected spatial point. False is supported only in global mode.
basis_mode – "per_state" (default) performs a separate POD and DEIM selection for each state before taking the union of sample points. "global" performs one POD on the C-order flattened multistate snapshots.

Returns:

Constructed interpolation operator.

Return type:

DEIM

property function_basis#

Return a copy of the function basis or per-state function bases.

In global mode this is a rank-3 romtools tensor. In per_state mode this is a tuple of rank-2 arrays because the state-specific basis dimensions may differ.

project_test_basis(test_basis)[source]#

Construct the sampled test basis used for hyper-reduction.

test_basis must have romtools tensor shape (n_vars, n_dofs, n_test_basis). With shared-state sampling the result has shape (n_vars, n_sample_points, n_test_basis). With independent flattened sampling it has shape (n_samples, n_test_basis).

reconstruct(sampled_values)[source]#

Reconstruct full-order tensor values from sampled values.

With shared-state sampling, sampled_values must have shape (n_vars, n_sample_points) or (n_vars, n_sample_points, n_snapshots). The return value has shape (n_vars, n_dofs) or (n_vars, n_dofs, n_snapshots).

In global mode with sample_all_states=False, sampled values have shape (n_samples,) or (n_samples, n_snapshots) because the samples are arbitrary flattened state-DOF entries. The reconstructed result is still returned in romtools tensor form.

reconstruction_matrix()[source]#

Return the flattened DEIM reconstruction matrix.

The row and column ordering follows the romtools C-order state-major convention. In per_state mode this is a block-diagonal matrix whose blocks are U_i @ pinv(U_i[sample_indices, :]). The common union sample mesh therefore acts as an oversampled DEIM system for each state.

property sample_all_states#: Whether all states are sampled at every selected spatial point.

property sample_indices#

Return the sample indices.

These are spatial indices in per_state mode and whenever sample_all_states=True. They are flattened C-order state-DOF indices only for global mode with sample_all_states=False.

property state_sample_indices#

Return the pre-union DEIM/QDEIM sample points for each state.

This is a tuple in automatically sampled per_state mode and None for a global basis or when a sample mesh was supplied by the user.

class romtools.hyper_reduction.deim.QDEIM(function_basis, sample_indices=None, rcond=None, sample_all_states=True, basis_mode='per_state')[source]#

Bases: DEIM

Tensor-native DEIM operator using pivoted-QR point selection.

Basis construction, tensor handling, and shared-state sampling are inherited from DEIM; only the DEIM selection performed on each applicable basis differs.

romtools.hyper_reduction.deim.deim_get_approximation_matrix(function_basis, sample_indices)[source]#

Given a function basis \(\mathbf{U}\) and sample indices defining \(\mathbf{P}\), we compute

\[\mathbf{U} \mathrm{pinv}( \mathbf{P}^T \mathbf{U})\]

which comprises the matrix needed for the DEIM approximation to \(\mathbf{f}\)

Parameters:

function_basis – \((m, n)\) array, where \(m\) is the number of DOFs and \(n\) the number of basis functions. Basis for function to be approximated.
sample_indices – \((n_s, )\) array, where \(n_s\) is the number of sample points. Sampling points.

Returns:

\((n, n_s)\) array. DEIM approximation basis

Return type:

deim_matrix

romtools.hyper_reduction.deim.deim_get_indices(U, comm=None)[source]#

Implementation of the discrete empirical method as described in Algorithm 1 of S. Chaturantabut and D. C. Sorensen, “Discrete Empirical Interpolation for nonlinear model reduction,” doi: 10.1109/CDC.2009.5400045.

Parameters:

U – \(\mathbf{U} \in \mathbb{R}^{m \times n}\), where \(m\) is the number of DOFs and \(n\) is the number of samples. Function basis in matrix format.
comm – Optional communicator object. If none, algorithm assumes shared-memory data.

Returns:

\(\mathrm{indices} \in \mathbb{I}^{n}\): sample mesh indices.

Otherwise:

Sample mesh local indices and the corresponding owing ranks.

Return type:

If comm == None

romtools.hyper_reduction.deim.deim_get_test_basis(test_basis, function_basis, sample_indices, comm=None)[source]#

Given a test basis \(\mathbf{\Phi}\), a function basis \(\mathbf{U}\), and sample indices defining \(\mathbf{P}\), we compute

\[[ \mathbf{\Phi}^T \mathbf{U} \mathrm{pinv}( \mathbf{P}^T \mathbf{U}) ]^T\]

which comprises the “test basis” for the DEIM approximation for \(\mathbf{\Phi}^T \mathbf{f}\)

Parameters:

test_basis – \((m, k)\) array, where \(m\) is the number of DOFs and \(k\) is the number of basis functions. Test basis in projection scheme
function_basis – \((m, n)\) array, where \(m\) is the number of DOFs and \(n\) is the number of basis functions. Basis for function to be approximated.
sample_indices – \((n_s, )\) array, where \(n_s\) is the number of sample points. Sampling points.
comm – Optional communicator object. If none, algorithm assumes shared-memory data.

Returns:

\((n_s, k)\) array, where: \(n_s\) is the number of sample points and \(k\) the number of basis functions. DEIM test basis matrix.

Return type:

deim_test_basis

romtools.hyper_reduction.deim.multi_state_deim_get_indices(U, comm=None)[source]#

Version of DEIM for multi-state systems.

We perform DEIM on each state variable, and then return the union of all indices. Repeated indices are removed.

Parameters:

U – \(\mathbf{U} \in \mathbb{R}^{l \times m \times n}\), where \(l\) is the number of variables, \(m\) is the number of DOFs and \(n\) the number of samples. Multi-dimensional function basis in tensor format.

Returns:

\(\mathrm{indices} \in \mathbb{I}^{n}\): sample mesh indices.

Otherwise:

Sample mesh local indices and the corresponding owing ranks.

Return type:

If comm == None

romtools.hyper_reduction.deim.multi_state_deim_get_test_basis(test_basis, function_basis, sample_indices)[source]#

For multistate systems. Constructs an independent DEIM basis for each state variable using uniform sample indices :param test_basis: \((n_{var}, m, k)\) array, where

\(n_{var}\) is the number of state variables, \(m\) is the number of DOFs and \(k\) is the number of basis functions. Test basis in projection scheme

Parameters:

function_basis – \((n_{var}, m, n)\) array, where \(n_{var}\) is the number of state variables, \(m\) is the number of DOFs and \(n\) is the number of basis functions. Basis for function to be approximated.
sample_indices – \((n_s, )\) array, where \(n_s\) is the number of sample points. Sampling points.

Returns:

\((n_{var}, n_s, k)\) array, where: \(n_{var}\) is the number of state variables, \(n_s\) is the number of sample points, and \(k\) the number of basis functions. DEIM test basis matrix.

Return type:

deim_test_basis

romtools.hyper_reduction.deim.qdeim_get_indices(function_basis)[source]#

Select interpolation indices using QDEIM for a matrix-form basis.

QDEIM applies a column-pivoted QR factorization to the transpose of the function basis. The first n_basis pivot indices define the interpolation points.

Parameters:: function_basis – (n_dofs, n_basis) function basis.
Returns:: Rank-1 integer array of interpolation indices.
Return type:: numpy.ndarray