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.

  • VectorSpaceFromStreamingPOD: construct a POD vector space from snapshot blocks.

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).

VectorSpaceFromStreamingPOD(snapshot_loader, ...)

POD vector space constructed from snapshot blocks loaded on demand.
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 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 tensor 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

class romtools.vector_space.VectorSpaceFromStreamingPOD(snapshot_loader, block_size, n_snapshots, max_basis_dimension, 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, comm=None)[source]#

Bases: object

POD vector space constructed from snapshot blocks loaded on demand.

This class conforms to the VectorSpace protocol. Snapshot data is loaded twice by the streaming POD algorithm, and only one block is held at a time. Data-derived shifters and scalers perform initialization before those two passes. The randomized algorithm first computes up to max_basis_dimension candidate modes, after which the supplied truncater selects the retained basis. Energy truncation is measured against the complete shifted and pre-scaled snapshot matrix.

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 the approximate singular values of the candidate basis.

Return type:

ndarray

Modules

utils

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