Added documentation

Author: sichinaga

pydmd/preprocessing/randomized.py

@@ -12,42 +12,46 @@
 from pydmd.utils import compute_rqb
 
 svd_rank_type = Union[int, float]
-seed_type = Union[None, int]
 
 def randomized_preprocessing(
     dmd: DMDBase,
     svd_rank: svd_rank_type,
     oversampling: int,
     power_iters: int,
     test_matrix: np.ndarray = None,
-    seed: seed_type = None,
+    seed: int = None,
 ):
     """
     Randomized QB pre-processing.
 
     :param dmd: DMD instance to be wrapped.
+    :param svd_rank: target rank of the input data.
+    :param oversampling: amount to oversample beyond the target rank.
+    :param power_iters: number of power iterations to perform.
+    :param test_matrix: optional custom random test matrix.
+    :param seed: optional random generator seed.
     """
     return PrePostProcessingDMD(
         dmd,
         partial(
-            _rand_preprocessing,
+            _pre,
             svd_rank=svd_rank,
             oversampling=oversampling,
             power_iters=power_iters,
             test_matrix=test_matrix,
             seed=seed,
         ),
-        _rand_postprocessing,
+        _post,
     )
 
-def _rand_preprocessing(
+def _pre(
     state: Dict,
     X: np.ndarray,
     svd_rank: svd_rank_type,
     oversampling: int,
     power_iters: int,
     test_matrix: np.ndarray,
-    seed: seed_type,
+    seed: int,
     **kwargs
 ):
     Q = compute_rqb(
@@ -58,5 +62,5 @@ def _rand_preprocessing(
     return (state["compression_matrix"].dot(X),) + tuple(kwargs.values())
 
 
-def _rand_postprocessing(state: Dict, X: np.ndarray) -> np.ndarray:
+def _post(state: Dict, X: np.ndarray) -> np.ndarray:
     return state["compression_matrix"].conj().T.dot(X)

pydmd/rdmd.py

@@ -10,7 +10,7 @@
 import numpy as np
 
 from .cdmd import CDMD
-from .utils import compute_rank, compute_rqb
+from .utils import compute_rqb
 
 
 class RDMD(CDMD):
@@ -24,13 +24,13 @@ class RDMD(CDMD):
     :param seed: Seed used to initialize the random generator when computing
         random test matrices.
     :type seed: int
-    :param oversampling: Number of additional samples (beyond the desired rank)
-        to use when computing the random test matrix. Note that values {5,10}
-        tend to be sufficient.
+    :param oversampling: Number of additional samples (beyond the target rank)
+        to use when computing the random test matrix. Note that values in the
+        range [5, 10] tend to be sufficient.
     :type oversampling: int
     :param power_iters: Number of power iterations to perform when executing
-        the Randomized QB Decomposition. Note that values {1,2} often lead to
-        considerable improvements.
+        the Randomized QB Decomposition. Note that as many as 1 to 2 power
+        iterations often lead to considerable improvements.
     :type power_iters: int
     """
 

pydmd/utils.py

@@ -201,6 +201,45 @@ def compute_rqb(
 ) -> NamedTuple(
     "RQB", [("Q", np.ndarray), ("B", np.ndarray), ("Omega", np.ndarray)]
 ):
+    """
+    Randomized QB Decomposition.
+
+    :param X: the matrix to decompose.
+    :type X: np.ndarray
+    :param svd_rank: the rank for the truncation; If 0, the method computes
+        the optimal rank and uses it for truncation; if positive interger,
+        the method uses the argument for the truncation; if float between 0
+        and 1, the rank is the number of the biggest singular values that
+        are needed to reach the 'energy' specified by `svd_rank`; if -1,
+        the method does not compute truncation. Use this parameter to
+        define the target rank of the input matrix.
+    :type svd_rank: int or float
+    :param oversampling: Number of additional samples (beyond the target rank)
+        to use when computing the random test matrix. Note that values in the
+        range [5, 10] tend to be sufficient.
+    :type oversampling: int
+    :param power_iters: Number of power iterations to perform when executing
+        the Randomized QB Decomposition. Note that as many as 1 to 2 power
+        iterations often lead to considerable improvements.
+    :type power_iters: int
+    :param Omega: The random test matrix that will be used when executing
+        the Randomized QB Decomposition. If not provided, the `svd_rank` and
+        `oversampling` parameters will be used to compute the random matrix.
+    :type Omega: numpy.ndarray
+    :param seed: Seed used to initialize the random generator when computing
+        random test matrices.
+    :type seed: int
+    :return: the orthonormal basis matrix, the transformed data matrix, and
+        the random test matrix.
+    :rtype: NamedTuple("RQB", [('Q', np.ndarray),
+                               ('B', np.ndarray),
+                               ('Omega', np.ndarray)])
+
+    References:
+    N. Benjamin Erichson, Lionel Mathelin, J. Nathan Kutz, Steven L. Brunton.
+    Randomized dynamic mode decomposition. SIAM Journal on Applied Dynamical
+    Systems, 18, 2019.
+    """
     if X.ndim != 2:
         raise ValueError("Please ensure that input data is a 2D array.")