From 04f4097fe3d3724860e346114517c85b808b6466 Mon Sep 17 00:00:00 2001
From: Eric Joshua Parish <ejparis@sandia.gov>
Date: Thu, 25 Jan 2024 19:33:45 -0600
Subject: [PATCH] updated header documentation for scaler

---
 romtools/trial_space_utils/scaler.py | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/romtools/trial_space_utils/scaler.py b/romtools/trial_space_utils/scaler.py
index 1cf4a193..2dcedab8 100644
--- a/romtools/trial_space_utils/scaler.py
+++ b/romtools/trial_space_utils/scaler.py
@@ -44,14 +44,19 @@
 #
 
 '''
-The scaler class is used to performed scaled POD.
+---
+##**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}$, POD computes the basis by solving the minimization problem
+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_{\\*} \\in \\mathbb{R}^{N \\times K} | \\boldsymbol
+$$ \\boldsymbol \\Phi = \\underset{ \\boldsymbol \\Phi_{\\*} \\in \\mathbb{R}^{ N_{\\mathrm{vars}} N_{\\mathrm{x}} \\times K} | \\boldsymbol
 \\Phi_{\\*}^T \\boldsymbol \\Phi_{\\*} = \\mathbf{I}}{ \\mathrm{arg \\; min} } \\| \\Phi_{\\*} \\Phi_{\\*}^T
 \\mathbf{S} - \\mathbf{S} \\|_2.$$
 In this minimization problem, errors are measured in a standard $\\ell^2$ norm.
@@ -64,11 +69,14 @@
 Defining $\\mathbf{S}_{\\*} = \\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_{\\*} \\in \\mathbb{R}^{N \\times K} |\\boldsymbol
+$$ \\boldsymbol \\Phi = \\mathbf{W} \\underset{ \\boldsymbol \\Phi_{\\*} \\in \\mathbb{R}^{N_{\\mathrm{vars}} N_{\\mathrm{x}} \\times K} |\\boldsymbol
 \\Phi_{\\*}^T \\boldsymbol \\Phi_{\\*} = \\mathbf{I}}{ \\mathrm{arg \\; min} } \\| \\Phi_{\\*} \\Phi_{\\*}^T
 \\mathbf{S}_{\\*} - \\mathbf{S}_{\\*} \\|_2.$$
 
-The Scaler encapsulates this information
+The Scaler encapsulates this information.
+
+___
+##**API**
 '''
 
 import abc
@@ -113,7 +121,7 @@ class VectorScaler(Scaler):
     '''
     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
+    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}$$