romtools.vector_space#

This module defines the API to work with a vector subspace. A vector subspace is foundational to reduced-order models. In a ROM, a high-dimensional state is restricted to live within a low-dimensional vector space, known as a trial space. Mathematically, given a “FOM” vector \(\mathbf{u} \in \mathbb{R}^{N_{\mathrm{vars}} N_{\mathrm{x}}}\), we can write

\[\mathbf{u} \approx \tilde{\mathbf{u}} \in \mathcal{V} + \mathbf{u}_{\mathrm{shift}}\]

where

  • \(\mathcal{V}\) with \(\text{dim}(\mathcal{V}) = K \le N_{\mathrm{vars}} N_{\mathrm{x}}\) is the trial space

  • \(N_{\mathrm{vars}}\) is the number of PDE variables (e.g., 5 for the compressible Navier-Stokes equations in 3D)

  • \(N_{\mathrm{x}}\) is the number of spatial DOFs

Formally, we can describe this low-dimensional representation with a basis and an affine offset,

\[\tilde{\mathbf{u}} = \boldsymbol \Phi \hat{\mathbf{u}} + \mathbf{u}_{\mathrm{shift}}\]

where \(\boldsymbol \Phi \in \mathbb{R}^{ N_{\mathrm{vars}} N_{\mathrm{x}} \times K}\) is the basis matrix (\(K\) is the number of basis), \(\hat{\mathbf{u}} \in \mathbb{R}^{K}\) are the reduced, or generalized coordinates, \(\mathbf{u}_{\mathrm{shift}} \in \mathbb{R}^{ N_{\mathrm{vars}} N_{\mathrm{x}}}\) is the shift vector (or affine offset), and, by definition, \(\mathcal{V} \equiv \mathrm{range}(\boldsymbol \Phi)\).

The VectorSpace abstract class defined below encapsulates the information of an affine vector space, \(\mathcal{V}\), by virtue of providing access to a basis matrix, a shift vector, and the dimensionality of the vector space, while decoupling this representation from how it is computed.

Tensor representation#

Our representation of the basis and the affine offset for a vector space is based on tensors

\[\mathcal{\Phi} \in \mathbb{R}^{ N_{\mathrm{vars}} \times N_{\mathrm{x}} \times K}\]
\[\mathcal{u}_{\mathrm{shift}} \in \mathbb{R}^{ N_{\mathrm{vars}} \times N_{\mathrm{x}}}\]

Internally, we remark that all tensors are reshaped into 2D matrices, e.g., when performing SVD.

Content#

We currently provide the following concrete classes:

  • DictionaryVectorSpace: construct a vector space from a matrix without truncation.

  • VectorSpaceFromPOD: construct a vector subspace computed via SVD.

which derive from the abstract class VectorSpace.

API#

Classes

DictionaryVectorSpace(snapshots[, shifter, ...])

Reduced basis vector space (no truncation).

VectorSpace(*args, **kwargs)

Abstract base class for vector space implementations.

VectorSpaceFromPOD(snapshots[, truncater, ...])

POD vector space (constructed via SVD).
class romtools.vector_space.DictionaryVectorSpace(snapshots, shifter=None, orthogonalizer=<romtools.vector_space.utils.orthogonalizer.NoOpOrthogonalizer object>)[source]#

Bases: object

Reduced basis vector space (no truncation).

This class conforms to VectorSpace protocol.

Given a snapshot matrix \(\mathbf{S}\), we set the basis to be

\[\boldsymbol \Phi = \mathrm{orthogonalize}(\mathbf{S} - \mathbf{u}_{\mathrm{shift}})\]

where the orthogonalization and shifts are defined by their respective classes

Parameters:
get_basis()[source]#

Concrete implementation of VectorSpace.get_basis()

Return type:

ndarray

get_shift_vector()[source]#

Concrete implementation of VectorSpace.get_shift_vector()

Return type:

ndarray

class romtools.vector_space.VectorSpace(*args, **kwargs)[source]#

Bases: Protocol

Abstract base class for vector space implementations.

Methods:

extents()[source]#

Retrieves the dimension of the vector space

Returns:

A Tuple with the the dimensions of the vector space (n_var,nx,K).

Return type:

Tuple[int, int, int]

get_basis()[source]#

Retrieves the basis vectors of the vector space.

Returns:

The basis of the vector space in tensor form.

Return type:

np.ndarray

get_shift_vector()[source]#

Retrieves the shift vector of the vector space.

Returns:

The shift vector in tensorm form.

Return type:

np.ndarray

class romtools.vector_space.VectorSpaceFromPOD(snapshots, truncater=<romtools.vector_space.utils.truncater.NoOpTruncater object>, shifter=None, orthogonalizer=<romtools.vector_space.utils.orthogonalizer.NoOpOrthogonalizer object>, scaler=<romtools.vector_space.utils.scaler.NoOpScaler object>, svdFnc=None)[source]#

Bases: object

POD vector space (constructed via SVD).

This class conforms to VectorSpace protocol.

Given a snapshot matrix \(\mathbf{S}\), we compute the basis \(\boldsymbol \Phi\) as

\[\boldsymbol U = \mathrm{SVD}(\mathrm{prescale}(\mathbf{S} - \mathbf{u}_{\mathrm{shift}}))\]
\[\boldsymbol \Phi = \mathrm{orthogonalize}(\mathrm{postscale}(\mathrm{truncate}( \boldsymbol U )))\]

where \(\boldsymbol U\) are the left singular vectors and the orthogonalization, truncation, scaling, and shifts are defined by their respective classes.

For truncation, we enable truncation based on a fixed dimension or the decay of singular values; please refer to the documentation for the truncater.

Parameters:
get_basis()[source]#

Concrete implementation of VectorSpace.get_basis()

Return type:

ndarray

get_shift_vector()[source]#

Concrete implementation of VectorSpace.get_shift_vector()

Return type:

ndarray

get_singular_values()[source]#

Returns array of singular values

Return type:

ndarray

Modules

utils

There are a number of ways to construct a vector space, including affine offsets, scaling, etc.