romtools.vector_space.utils.scaler#

Notes

The scaler class is used to performed scaled POD. Scaling is applied to tensors of shape \(\mathbb{R}^{ N_{\mathrm{vars}} \times N_{\mathrm{x}} \times N_s}\). These tensors are then reshaped into matrices when performing SVD.

Theory#

What is scaled POD, and why would I do it?

Standard POD computes a basis that minimizes the projection error in a standard Euclidean \(\ell^2\) inner product, i.e., for a snapshot matrix \(\mathbf{S} \in \mathbb{R}^{ N_{\mathrm{vars}} N_{\mathrm{x}} \times N_s}\), POD computes the basis by solving the minimization problem (assuming no affine offset)

\[\boldsymbol \Phi = \underset{ \boldsymbol \Phi_{\ast} \in \mathbb{R}^{ N_{\mathrm{vars}} N_{\mathrm{x}} \times K} | \boldsymbol \Phi_{\ast}^T \boldsymbol \Phi_{\ast} = \mathbf{I}}{ \mathrm{arg \; min} } \| \Phi_{\ast} \Phi_{\ast}^T \mathbf{S} - \mathbf{S} \|_2.\]

In this minimization problem, errors are measured in a standard \(\ell^2\) norm. For most practical applications, where our snapshot matrix involves variables of different scales, this norm does not make sense (both intuitively, and on dimensional grounds). As a practical example, consider fluid dynamics where the total energy is orders of magnitude larger than the density.

One of the most common approaches for mitigating this issue is to perform scaled POD. In scaled POD, we solve a minimization problem on a scaled snapshot matrix. Defining \(\mathbf{S}_{\ast} = \mathbf{W}^{-1} \mathbf{S}\), where \(\mathbf{W}\) is a weighting matrix (e.g., a diagonal matrix containing the max absolute value of each state variable), we compute the basis as the solution to the minimization problem

\[\boldsymbol \Phi = \mathbf{W} \underset{ \boldsymbol \Phi_{\ast} \in \mathbb{R}^{N_{\mathrm{vars}} N_{\mathrm{x}} \times K} |\boldsymbol \Phi_{\ast}^T \boldsymbol \Phi_{\ast} = \mathbf{I}}{ \mathrm{arg \; min} } \| \Phi_{\ast} \Phi_{\ast}^T \mathbf{S}_{\ast} - \mathbf{S}_{\ast} \|_2.\]

The Scaler encapsulates this information.

API#

Classes

`NoOpScaler`()	No op implementation
`ScalarScaler`([factor])	Applies a scalar scale factor
`Scaler`(args, *kwargs)	Interface for the Scaler class.
`StreamingScaler`(args, *kwargs)	Scaler interface required by streaming POD vector spaces.
`VariableAndVectorScaler`(scaling_vector, ...)	Concrete implementation designed to scale snapshot matrices involving multiple state variables by both the variable magnitudes and an additional vector.
`VariableScaler`(scaling_type)	Concrete implementation designed for snapshot matrices involving multiple state variables.
`VectorScaler`(scaling_vector)	Concrete implementation designed to scale snapshot matrices by a vector.

class romtools.vector_space.utils.scaler.NoOpScaler[source]#

Bases: object

No op implementation

This class conforms to the Scaler protocol.

post_scale(data_tensor)[source]#: Does not alter the input data matrix.

pre_scale(data_tensor)[source]#

Does not alter the input data matrix.

Parameters:: data_tensor (ndarray)

class romtools.vector_space.utils.scaler.ScalarScaler(factor=1.0)[source]#

Bases: object

Applies a scalar scale factor

This class conforms to the Scaler protocol.

Parameters:: factor (float)

post_scale(data_tensor)[source]#

Scales the input data matrix in place using the input factor.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: ndarray

pre_scale(data_tensor)[source]#

Scales the input data matrix in place using the reciprocal of the input factor.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: ndarray

class romtools.vector_space.utils.scaler.Scaler(*args, **kwargs)[source]#

Bases: Protocol

Interface for the Scaler class.

post_scale(data_tensor)[source]#

Scales the left singular vectors in place after performing SVD

Parameters:: data_tensor (ndarray)
Return type:: None

pre_scale(data_tensor)[source]#

Scales the snapshot matrix in place before performing SVD

Parameters:: data_tensor (ndarray)
Return type:: None

class romtools.vector_space.utils.scaler.StreamingScaler(*args, **kwargs)[source]#

Bases: Scaler, Protocol

Scaler interface required by streaming POD vector spaces.

initialize_scalings_from_loader(snapshot_loader, block_size, n_snapshots, comm=None)[source]#

Initialize scaling data from snapshot blocks.

This method is only required for streaming POD. Fixed scalers may implement it as a no-op.

Parameters:

snapshot_loader (SnapshotLoader)
block_size (int)
n_snapshots (int)

Return type:

None

class romtools.vector_space.utils.scaler.VariableAndVectorScaler(scaling_vector, scaling_type)[source]#

Bases: object

Concrete implementation designed to scale snapshot matrices involving multiple state variables by both the variable magnitudes and an additional vector. This is particularly useful when wishing to perform POD for, e.g., a finite volume method where we want to scale by the cell volumes as well as the variable magnitudes. This implementation combines the VectorScaler and VariableScaler classes.

This class conforms to the Scaler protocol.

post_scale(data_tensor)[source]#

Scales the input data matrix in place after processing, first using the VectorScaler and then the VariableScaler.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None

pre_scale(data_tensor)[source]#

Scales the input data matrix in place before processing, first using the VariableScaler and then the VectorScaler.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None

class romtools.vector_space.utils.scaler.VariableScaler(scaling_type)[source]#

Bases: object

Concrete implementation designed for snapshot matrices involving multiple state variables.

This class is designed to scale a data matrix comprising multiple states (e.g., for the Navier–Stokes, rho, rho u, rhoE)

The available scaling options are:

"max_abs": for state variable \(u_i\), compute \(s_i = \max\left(\lvert S_i \rvert\right)\).
"mean_abs": for state variable \(u_i\), compute \(s_i = \operatorname{mean}\left(\lvert S_i \rvert\right)\).
"variance": for state variable \(u_i\), compute \(s_i = \operatorname{std}\left(S_i\right)\).

Here, \(S_i\) denotes the snapshot matrix for state variable \(u_i\).

This class conforms to the Scaler protocol.

initialize_scalings(data_tensor)[source]#

Initializes the scaling factors for each state variable based on the specified method.

Parameters:: data_tensor (np.ndarray) – The input data matrix.
Return type:: None

initialize_scalings_from_loader(snapshot_loader, block_size, n_snapshots, comm=None)[source]#

Initialize variable scales from all snapshot blocks.

This method is only required for streaming POD.

Parameters:

snapshot_loader (SnapshotLoader)
block_size (int)
n_snapshots (int)

Return type:

None

post_scale(data_tensor)[source]#

Scales the input data matrix in place using the scaling vector.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None

pre_scale(data_tensor)[source]#

Scales the input data matrix in place before processing, taking into account the previously initialized scaling factors.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None

class romtools.vector_space.utils.scaler.VectorScaler(scaling_vector)[source]#

Bases: object

Concrete implementation designed to scale snapshot matrices by a vector. For a snapshot tensor \(\mathbf{S} \in \mathbb{R}^{N_{\mathrm{u}} \times N \times K}\), the VectorScaler accepts in a scaling vector \(\mathbf{v} \in \mathbb{R}^{N}\), and scales by

\[\mathbf{S}^* = \mathrm{diag}(\mathbf{v})^{-1} \mathbf{S}\]

before performing POD (i.e., POD is performed on \(\mathbf{S}^*\)). After POD is performed, the bases are post-scaled by

\[\boldsymbol \Phi = \mathrm{diag}(\mathbf{v}) \mathbf{U}\]

Note that scaling can cause bases to not be orthonormal; we do not recommend using scalers with the NoOpOrthogonalizer.

This class conforms to the Scaler protocol.

post_scale(data_tensor)[source]#

Scales the input data matrix in place using the scaling vector.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None

pre_scale(data_tensor)[source]#

Scales the input data matrix in place using the inverse of the scaling vector.

Parameters:: data_tensor (np.ndarray) – The input data matrix to be scaled.
Return type:: None