romtools.vector_space.utils.scaler

  1#
  2# ************************************************************************
  3#
  4#                         ROM Tools and Workflows
  5# Copyright 2019 National Technology & Engineering Solutions of Sandia,LLC
  6#                              (NTESS)
  7#
  8# Under the terms of Contract DE-NA0003525 with NTESS, the
  9# U.S. Government retains certain rights in this software.
 10#
 11# ROM Tools and Workflows is licensed under BSD-3-Clause terms of use:
 12#
 13# Redistribution and use in source and binary forms, with or without
 14# modification, are permitted provided that the following conditions
 15# are met:
 16#
 17# 1. Redistributions of source code must retain the above copyright
 18# notice, this list of conditions and the following disclaimer.
 19#
 20# 2. Redistributions in binary form must reproduce the above copyright
 21# notice, this list of conditions and the following disclaimer in the
 22# documentation and/or other materials provided with the distribution.
 23#
 24# 3. Neither the name of the copyright holder nor the names of its
 25# contributors may be used to endorse or promote products derived
 26# from this software without specific prior written permission.
 27#
 28# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 29# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 30# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 31# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 32# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 33# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 34# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 35# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 36# HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 37# STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
 38# IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 39# POSSIBILITY OF SUCH DAMAGE.
 40#
 41# Questions? Contact Eric Parish (ejparis@sandia.gov)
 42#
 43# ************************************************************************
 44#
 45
 46'''
 47---
 48##**Notes**
 49The scaler class is used to performed scaled POD.
 50Scaling is applied to tensors of shape $\mathbb{R}^{ N_{\\mathrm{vars}} \\times N_{\\mathrm{x}} \\times N_s}$.
 51These tensors are then reshaped into matrices when performing SVD.
 52
 53___
 54##**Theory**
 55
 56*What is scaled POD, and why would I do it?*
 57
 58Standard POD computes a basis that minimizes the projection error in a standard Euclidean $\\ell^2$ inner product,
 59i.e., for a snapshot matrix $\\mathbf{S} \\in \\mathbb{R}^{  N_{\\mathrm{vars}} N_{\\mathrm{x}} \\times N_s}$,
 60POD computes the basis by solving the minimization problem (assuming no affine offset)
 61$$ \\boldsymbol \\Phi = \\underset{ \\boldsymbol \\Phi_{\\*} \\in \\mathbb{R}^{ N_{\\mathrm{vars}} N_{\\mathrm{x}}
 62\\times K} | \\boldsymbol \\Phi_{\\*}^T \\boldsymbol \\Phi_{\\*} = \\mathbf{I}}{ \\mathrm{arg \\; min} } \\| \\Phi_{\\*}
 63\\Phi_{\\*}^T \\mathbf{S} - \\mathbf{S} \\|_2.$$
 64In this minimization problem, errors are measured in a standard $\\ell^2$ norm.
 65For most practical applications, where our snapshot matrix involves variables of different scales,
 66this norm does not make sense (both intuitively, and on dimensional grounds).
 67As a practical example, consider fluid dynamics where the total energy is orders of magnitude larger than the density.
 68
 69One of the most common approaches for mitigating this issue is to perform scaled POD.
 70In scaled POD, we solve a minimization problem on a scaled snapshot matrix.
 71Defining $\\mathbf{S}_{\\*} = \\mathbf{W}^{-1} \\mathbf{S}$, where $\\mathbf{W}$ is a weighting matrix
 72(e.g., a diagonal matrix containing the max absolute value of each state variable),
 73we compute the basis as the solution to the minimization problem
 74$$ \\boldsymbol \\Phi = \\mathbf{W} \\underset{ \\boldsymbol \\Phi_{\\*} \\in \\mathbb{R}^{N_{\\mathrm{vars}} N_{\\mathrm{x}}
 75\\times K} |\\boldsymbol \\Phi_{\\*}^T \\boldsymbol \\Phi_{\\*} = \\mathbf{I}}{ \\mathrm{arg \\; min} } \\| \\Phi_{\\*}
 76\\Phi_{\\*}^T \\mathbf{S}_{\\*} - \\mathbf{S}_{\\*} \\|_2.$$
 77
 78The Scaler encapsulates this information.
 79
 80___
 81##**API**
 82'''
 83
 84from typing import Protocol
 85import numpy as np
 86import romtools.linalg.linalg as la
 87
 88
 89class Scaler(Protocol):
 90    '''
 91    Interface for the Scaler class.
 92    '''
 93
 94    def pre_scale(self, data_tensor: np.ndarray) -> None:
 95        '''
 96        Scales the snapshot matrix in place before performing SVD
 97        '''
 98        ...
 99
100    def post_scale(self, data_tensor: np.ndarray) -> None:
101        '''
102        Scales the left singular vectors in place after performing SVD
103        '''
104        ...
105
106
107class NoOpScaler:
108    '''
109    No op implementation
110
111    This class conforms to `Scaler` protocol.
112    '''
113
114    def __init__(self) -> None:
115        pass
116
117    def pre_scale(self, data_tensor: np.ndarray):
118        '''Does not alter the input data matrix.'''
119        pass
120
121    def post_scale(self, data_tensor):
122        '''Does not alter the input data matrix.'''
123        pass
124
125
126class VectorScaler:
127    '''
128    Concrete implementation designed to scale snapshot matrices by a vector.
129    For a snapshot tensor $\\mathbf{S} \\in \\mathbb{R}^{N_{\\mathrm{u}} \\times N \\times K}$, the VectorScaler
130    accepts in a scaling vector $\\mathbf{v} \\in \\mathbb{R}^{N}$, and scales by
131    $$\\mathbf{S}^* = \\mathrm{diag}(\\mathbf{v})^{-1} \\mathbf{S}$$
132    before performing POD (i.e., POD is performed on $\\mathbf{S}^*$). After POD is performed, the bases
133    are post-scaled by $$\\boldsymbol \\Phi = \\mathrm{diag}(\\mathbf{v}) \\mathbf{U}$$
134
135    **Note that scaling can cause bases to not be orthonormal; we do not
136    recommend using scalers with the NoOpOrthonormalizer**
137
138    This class conforms to `Scaler` protocol.
139    '''
140
141    def __init__(self, scaling_vector) -> None:
142        '''
143        Constructor for the VectorScaler.
144
145        Args:
146            scaling_vector: Array containing the scaling vector for each row
147                in the snapshot matrix.
148
149        This constructor initializes the VectorScaler with the specified
150        scaling vector.
151        '''
152        self.__scaling_vector_matrix = scaling_vector
153        self.__scaling_vector_matrix_inv = 1.0 / scaling_vector
154
155    def pre_scale(self, data_tensor: np.ndarray) -> None:
156        '''
157        Scales the input data matrix in place using the inverse of the scaling vector.
158
159        Args:
160            data_tensor (np.ndarray): The input data matrix to be scaled.
161        '''
162        data_tensor *= self.__scaling_vector_matrix_inv[None, :, None]
163
164    def post_scale(self, data_tensor: np.ndarray) -> None:
165        '''
166        Scales the input data matrix in place using the scaling vector.
167
168        Args:
169            data_tensor (np.ndarray): The input data matrix to be scaled.
170        '''
171        data_tensor *= self.__scaling_vector_matrix[None, :, None]
172
173
174class ScalarScaler:
175    '''
176    Applies a scalar scale factor
177
178    This class conforms to `Scaler` protocol.
179    '''
180
181    def __init__(self, factor: float = 1.0) -> None:
182        self._factor = factor
183
184    def pre_scale(self, data_tensor: np.ndarray) -> np.ndarray:
185        '''
186        Scales the input data matrix in place using the reciprocal of the input factor.
187
188        Args:
189            data_tensor (np.ndarray): The input data matrix to be scaled.
190        '''
191        data_tensor /= self._factor
192
193    def post_scale(self, data_tensor: np.ndarray) -> np.ndarray:
194        '''
195        Scales the input data matrix in place using the input factor.
196
197        Args:
198            data_tensor (np.ndarray): The input data matrix to be scaled.
199        '''
200        data_tensor *= self._factor
201
202
203class VariableScaler:
204    '''
205    Concrete implementation designed for snapshot matrices involving multiple
206    state variables.
207
208    This class is designed to scale a data matrix comprising multiple states
209    (e.g., for the Navier--Stokes, rho, rho u, rhoE)
210
211    This scaler will scale each variable based on
212      - max-abs scaling: for the $i$th state variable $u_i$, we will compute the scaling as
213        $s_i = \\mathrm{max}( \\mathrm{abs}( S_i ) )$, where $S_i$ denotes the snapshot matrix of the $i$th variable.
214      - mean abs: for the $i$th state variable $u_i$, we will compute the scaling as
215        $s_i = \\mathrm{mean}( \\mathrm{abs}( S_i ) )$, where $S_i$ denotes the snapshot matrix of the $i$th variable.
216      - variance: for the $i$th state variable $u_i$, we will compute the scaling as
217        $s_i = \\mathrm{std}( S_i ) $, where $S_i$ denotes the snapshot matrix of the $i$th variable.
218
219    This class conforms to `Scaler` protocol.
220    '''
221
222    def __init__(self, scaling_type) -> None:
223        '''
224        Constructor for the VariableScaler.
225
226        Args:
227            scaling_type (str): The scaling method to use ('max_abs',
228            'mean_abs', or 'variance').
229
230        This constructor initializes the VariableScaler with the specified
231        scaling type, variable ordering, and number of variables.
232        '''
233        self.__scaling_type = scaling_type
234        self.have_scales_been_initialized = False
235        self.var_scales_ = None
236
237    def initialize_scalings(self, data_tensor: np.ndarray) -> None:
238        '''
239        Initializes the scaling factors for each state variable based on the
240        specified method.
241
242        Args:
243            data_tensor (np.ndarray): The input data matrix.
244        '''
245        n_var = data_tensor.shape[0]
246        self.var_scales_ = np.ones(n_var)
247        for i in range(n_var):
248            ith_var = data_tensor[i]
249            if self.__scaling_type == "max_abs":
250                var_scale = la.max(abs(ith_var))
251            elif self.__scaling_type == "mean_abs":
252                var_scale = la.mean(abs(ith_var))
253            elif self.__scaling_type == "variance":
254                var_scale = la.std(ith_var)
255
256            # in case of a zero field (e.g., 2D)
257            if var_scale < 1e-10:
258                var_scale = 1.0
259            self.var_scales_[i] = var_scale
260        self.have_scales_been_initialized = True
261
262    # These are all inplace operations
263    def pre_scale(self, data_tensor: np.ndarray) -> None:
264        '''
265        Scales the input data matrix in place before processing, taking into account
266        the previously initialized scaling factors.
267
268        Args:
269            data_tensor (np.ndarray): The input data matrix to be scaled.
270        '''
271        n_var = data_tensor.shape[0]
272        if self.have_scales_been_initialized:
273            pass
274        else:
275            self.initialize_scalings(data_tensor)
276        # scale each field (variable scaling)
277        for i in range(n_var):
278            data_tensor[i] /= self.var_scales_[i]
279
280    def post_scale(self, data_tensor: np.ndarray) -> None:
281        '''
282        Scales the input data matrix in place using the scaling vector.
283
284        Args:
285            data_tensor (np.ndarray): The input data matrix to be scaled.
286        '''
287        assert self.have_scales_been_initialized, "Scales in VariableScaler have not been initialized"
288        # scale each field
289        n_var = data_tensor.shape[0]
290        for i in range(n_var):
291            data_tensor[i] *= self.var_scales_[i]
292
293class VariableAndVectorScaler:
294    '''
295    Concrete implementation designed to scale snapshot matrices involving
296    multiple state variables by both the variable magnitudes and an additional
297    vector.  This is particularly useful when wishing to perform POD for,
298    e.g., a finite volume method where we want to scale by the cell volumes as
299    well as the variable magnitudes. This implementation combines the
300    VectorScaler and VariableScaler classes.
301
302    This class conforms to `Scaler` protocol.
303    '''
304
305    def __init__(self, scaling_vector, scaling_type) -> None:
306        '''
307        Constructor for the VariableAndVectorScaler.
308
309        Args:
310            scaling_vector: Array containing the scaling vector for each row
311            in the snapshot matrix.
312            scaling_type: Scaling method ('max_abs',
313            'mean_abs', or 'variance') for variable magnitudes.
314
315        This constructor initializes the `VariableAndVectorScaler` with the
316        specified parameters.
317        '''
318        self.__my_variable_scaler = VariableScaler(scaling_type)
319        self.__my_vector_scaler = VectorScaler(scaling_vector)
320
321    def pre_scale(self, data_tensor: np.ndarray) -> None:
322        '''
323        Scales the input data matrix in place before processing, first using the
324        `VariableScaler` and then the `VectorScaler`.
325
326        Args:
327            data_tensor (np.ndarray): The input data matrix to be scaled.
328        '''
329        self.__my_variable_scaler.pre_scale(data_tensor)
330        self.__my_vector_scaler.pre_scale(data_tensor)
331
332    def post_scale(self, data_tensor: np.ndarray) -> None:
333        '''
334        Scales the input data matrix in place after processing, first using the
335        `VectorScaler` and then the `VariableScaler`.
336
337        Args:
338            data_tensor (np.ndarray): The input data matrix to be scaled.
339        '''
340        self.__my_vector_scaler.post_scale(data_tensor)
341        self.__my_variable_scaler.post_scale(data_tensor)