Clustering refactor, codacy compliance, doc updates

- Clustering now refactored into a protected _cluster method which does
  the actual clustering and then a clustering method and a
hyperparameter sweep.
- Added new private variable for the `svd_rank_preallocate`
- Edited lines too long.
- Completed many missing doc strings
- Simplified some omega handling logic.
- Tutorials use updated API, adjusted some documentation, added to
  README, edited titles to be more useful.

Author: klapo

pydmd/costs.py

@@ -16,7 +16,10 @@ def overlapping_oscillators():
     """
 
     def rhs_FNM(t, x, tau, a, b, Iext):
-        # FitzHugh-Nagumo Model
+        """FitzHugh-Nagumo Model
+
+        See costs-tutorial_toy-data for details.
+        """
         v = x[0]
         w = x[1]
         vdot = v - (v**3) / 3 - w + Iext
@@ -26,7 +29,10 @@ def rhs_FNM(t, x, tau, a, b, Iext):
         return dx
 
     def rhs_UFD(t, y, eta, epsilon, tau):
-        # Unforced Duffing Oscillator
+        """Unforced Duffing Oscillator
+
+        See costs-tutorial_toy-data for details.
+        """
         p = y[0]
         q = y[1]
         pdot = q
@@ -121,7 +127,7 @@ def rhs_UFD(t, y, eta, epsilon, tau):
 )
 mrd.fit(data, np.atleast_2d(time), window, step, verbose=False)
 # Force the clustering to use two components due to the nature of the toy data.
-_ = mrd.cluster_omega(n_components=2, transform_method=transform_method)
+mrd.cluster_omega(n_components=2, transform_method=transform_method)
 
 
 def test_construction():
@@ -148,6 +154,7 @@ def test_construction():
 
 
 def test_bad_construction():
+    """Test bad fit and construction keywords and parameters."""
     mrd_alternative = COSTS()
     with raises(ValueError):
         mrd_alternative.fit(
@@ -156,6 +163,7 @@ def test_bad_construction():
 
 
 def test_window_construction():
+    """Determine that the correct number of windows were found."""
     assert mrd.build_windows(data, window, step, integer_windows=True) == 61
 
 
@@ -244,15 +252,16 @@ def test_omega_transforms():
 
 
 def test_to_xarray():
-    """ """
+    """Tests the round trip conversion to and from xarray."""
     ds = mrd.to_xarray()
     mrd_convert = mrd.from_xarray(ds)
 
     assert np.allclose(mrd.omega_array, mrd_convert.omega_array)
     assert np.allclose(mrd.modes_array, mrd_convert.modes_array)
     assert np.allclose(mrd.cluster_centroids, mrd_convert.cluster_centroids)
 
-    # The round trip of the pydmd_kwargs is sensitive to python and numpy version.
+    # The round trip of the pydmd_kwargs is sensitive to python and numpy
+    # version.
     assert np.allclose(
         mrd._pydmd_kwargs["proj_basis"], mrd_convert._pydmd_kwargs["proj_basis"]
     )
@@ -262,6 +271,7 @@ def test_to_xarray():
 
 
 def test_plotters():
+    """Determine no errors are triggered when plotting."""
     mrd.plot_reconstructions(data)
     mrd.plot_scale_separation(data)
     mrd.plot_error(data)

pydmd/mrcosts.py

@@ -9,10 +9,23 @@
 
 
 def build_multiscale_process():
-    """ """
+    """
+    Simulates a system with two oscillators with occasionally overlapping
+    frequencies (adapted from Dylewsky et al., 2019) with a transient
+    coherent wave packet constructive interfering with the system.
+
+    Oscillator #1: FitzHugh-Nagumo Model
+    Oscillator #2: Unforced Duffing Oscillator
+
+    Data are sub-selected to reduce the computational load from minutes to
+    10s of seconds. See costs-tutorial_toy-data for details.
+    """
 
     def rhs_FNM(t, x, tau, a, b, Iext):
-        # FitzHugh-Nagumo Model
+        """FitzHugh-Nagumo Model
+
+        See costs-tutorial_toy-data for details.
+        """
         v = x[0]
         w = x[1]
         vdot = v - (v**3) / 3 - w + Iext
@@ -22,7 +35,10 @@ def rhs_FNM(t, x, tau, a, b, Iext):
         return dx
 
     def rhs_UFD(t, y, eta, epsilon, tau):
-        # Unforced Duffing Oscillator
+        """Unforced Duffing Oscillator
+
+        See costs-tutorial_toy-data for details.
+        """
         p = y[0]
         q = y[1]
         pdot = q
@@ -269,7 +285,10 @@ def test_omega_transforms():
 
 
 def test_netcdf():
-    """ """
+    """
+    Test the round trip conversion of the mrCOSTS object to file in
+    netcdf format and back to mrCOSTS.
+    """
     mrc.to_netcdf("tests")
     file_list = glob.glob("*tests*.nc")
     mrc_from_file = mrCOSTS()
@@ -283,6 +302,10 @@ def test_netcdf():
 
 
 def test_plot_local_reconstructions():
+    """
+    Test that the local reconstruction plot works and raises the appropriate
+    errors when trying to plot the first decomposition level without data.
+    """
     mrc.plot_local_reconstructions(0, data=data)
 
     with raises(ValueError):
@@ -293,6 +316,10 @@ def test_plot_local_reconstructions():
 
 
 def test_plot_local_error():
+    """
+    Test that the local error plot works and raises the appropriate
+    errors when trying to plot the first decomposition level without data.
+    """
     mrc.plot_local_error(0, data=data)
 
     with raises(ValueError):
@@ -303,6 +330,10 @@ def test_plot_local_error():
 
 
 def test_plot_local_scale_separation():
+    """
+    Test that the local scale separation plot works and raises the appropriate
+    errors when trying to plot the first decomposition level without data.
+    """
     _ = mrc.plot_local_scale_separation(0, data=data)
 
     with raises(ValueError):
@@ -313,6 +344,11 @@ def test_plot_local_scale_separation():
 
 
 def test_plot_local_time_series():
+    """
+    Test that the local time series of a point plot works and raises the
+    appropriate errors when trying to plot the first decomposition level
+    without data.
+    """
     _ = mrc.plot_local_time_series(0, 0, data=data)
 
     with raises(ValueError):
@@ -323,6 +359,7 @@ def test_plot_local_time_series():
 
 
 def tear_down():
+    """Remove the files generated in `test_netcdf`"""
     file_list = glob.glob("*tests*.nc")
     for f in file_list:
         os.remove(f)

tests/test_costs.py

@@ -4,27 +4,29 @@ In this folder we collect several useful tutorials in order to understand the pr
 An additional PDF tutorial ([DSWeb contest winner](https://dsweb.siam.org/The-Magazine/All-Issues/dsweb-2019-contest-tutorials-on-dynamical-systems-software)) is available [here](tutorial_dsweb.pdf).
 
 
-| Name                                                                                                                                                                                      | Description                                                        | PyDMD used classes    |
-|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------|-----------------------|
-| Tutorial1 [[.ipynb](tutorial1/tutorial-1-dmd.ipynb), [.py](tutorial1/tutorial-1-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial1dmd.html)]                        | Analyzing real, simple data sets with PyDMD                                        | `pydmd.DMD`, `pydmd.BOPDMD`           |
-| Tutorial2 [[.ipynb](tutorial2/tutorial-2-adv-dmd.ipynb), [.py](tutorial2/tutorial-2-adv-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial2advdmd.html)]             | advanced features of standard DMD                                  | `pydmd.DMD`           |
-| Tutorial3 [[.ipynb](tutorial3/tutorial-3-mrdmd.ipynb), [.py](tutorial3/tutorial-3-mrdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial3mrdmd.html)]                  | multi-resolution DMD for transient phenomena                       | `pydmd.MrDMD`         |
-| Tutorial4 [[.ipynb](tutorial4/tutorial-4-cdmd.ipynb), [.py](tutorial4/tutorial-4-cdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial4cdmd.html)]                     | compress DMD for computation speedup                               | `pydmd.CDMD`          |
-| Tutorial5 [[.ipynb](tutorial5/tutorial-5-fbdmd.ipynb), [.py](tutorial5/tutorial-5-fbdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial5fbdmd.html)]                  | forward-backward DMD for CFD model analysis                        | `pydmd.FbDMD`         |
-| Tutorial6 [[.ipynb](tutorial6/tutorial-6-hodmd.ipynb), [.py](tutorial6/tutorial-6-hodmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial6hodmd.html)]                  | higher-order DMD applied to scalar time-series                     | `pydmd.HODMD`         |
-| Tutorial7 [[.ipynb](tutorial7/tutorial-7-dmdc.ipynb), [.py](tutorial7/tutorial-7-dmdc.py), [.html](http://pydmd.github.io/PyDMD/tutorial7dmdc.html)]                     | DMD with control                                                   | `pydmd.DMDC`          |
-| Tutorial8 [[.ipynb](tutorial8/tutorial-8-comparisons.ipynb), [.py](tutorial8/tutorial-8-comparisons.py), [.html](http://pydmd.github.io/PyDMD/tutorial8comparison.html)] | comparison between DMD and optimal closed-form DMD                 | `pydmd.OptDMD`        |
-| Tutorial9 [[.ipynb](tutorial9/tutorial-9-spdmd.ipynb), [.py](tutorial9/tutorial-9-spdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial9spdmd.html)]                  | sparsity-promoting DMD                                             | `pydmd.SpDMD`         |
-| Tutorial10 [[.ipynb](tutorial10/tutorial-10-paramdmd.ipynb), [.py](tutorial10/tutorial-10-paramdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial10paramdmd.html)]   | parametric DMD                                                     | `pydmd.ParametricDMD` |
-| Tutorial11 [[.ipynb](tutorial10/tutorial-11-regularization.ipynb), [.py](tutorial11/tutorial-11-regularization.py), [.html](http://pydmd.github.io/PyDMD/tutorial11regularization.html)]   | Tikhonov regularization                                      | `pydmd.DMDBase` |
-| Tutorial12 [[.ipynb](tutorial12/tutorial-12-cdmd.ipynb), [.py](tutorial12/tutorial-12-cdmd.py)]                                                                                 | cDMD for background modeling                                       | `pydmd.CDMD`          |
-| Tutorial13 [[.ipynb](tutorial13/tutorial-13-subspacedmd.ipynb), [.py](tutorial13/tutorial-13-subspacedmd.py)]                                                                   | SubspaceDMD for locating eigenvalues of stochastic systems         | `pydmd.SubspaceDMD`   |
-| Tutorial14 [[.ipynb](tutorial14/tutorial-14-bop-dmd.ipynb), [.py](tutorial14/tutorial-14-bop-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial14-bop-dmd.html)]     | Comparison between Bagging-/ Optimized DMD and exact DMD | `pydmd.BOPDMD`        |
-| Tutorial15 [[.ipynb](tutorial15/tutorial-15-pidmd.ipynb), [.py](tutorial15/tutorial-15-pidmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial15-pidmd.html)]     | Physics-informed DMD for manifold enforcement | `pydmd.PiDMD`        |
-| Tutorial16 [[.ipynb](tutorial16/tutorial-16-rdmd.ipynb), [.py](tutorial16/tutorial-16-rdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial16-rdmd.html)]     | Randomized DMD for greater computation speedup | `pydmd.RDMD`        |
-| Tutorial17 [[.ipynb](tutorial17/tutorial-17-edmd.ipynb), [.py](tutorial17/tutorial-17-edmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial17-edmd.html)]     | Extended DMD for nonlinear eigenfunction discovery | `pydmd.EDMD`        |
-| Tutorial18 [[.ipynb](tutorial18/tutorial-18-lando.ipynb), [.py](tutorial18/tutorial-18-lando.py), [.html](http://pydmd.github.io/PyDMD/tutorial18-lando.html)]     | LANDO for nonlinear system modeling | `pydmd.LANDO`        |
-| Tutorial19 [[.ipynb](tutorial19/tutorial-19-havok.ipynb), [.py](tutorial19/tutorial-19-havok.py), [.html](http://pydmd.github.io/PyDMD/tutorial19-havok.html)]     | HAVOK for modeling chaos with partial measurements | `pydmd.HAVOK`        |
+| Name                                                                                                                                                                                                    | Description                                                     | PyDMD used classes          |
+|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------|-----------------------------|
+| Tutorial1 [[.ipynb](tutorial1/tutorial-1-dmd.ipynb), [.py](tutorial1/tutorial-1-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial1dmd.html)]                                        | Analyzing real, simple data sets with PyDMD                     | `pydmd.DMD`, `pydmd.BOPDMD` |
+| Tutorial2 [[.ipynb](tutorial2/tutorial-2-adv-dmd.ipynb), [.py](tutorial2/tutorial-2-adv-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial2advdmd.html)]                             | advanced features of standard DMD                               | `pydmd.DMD`                 |
+| Tutorial3 [[.ipynb](tutorial3/tutorial-3-mrdmd.ipynb), [.py](tutorial3/tutorial-3-mrdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial3mrdmd.html)]                                  | multi-resolution DMD for transient phenomena                    | `pydmd.MrDMD`               |
+| Tutorial4 [[.ipynb](tutorial4/tutorial-4-cdmd.ipynb), [.py](tutorial4/tutorial-4-cdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial4cdmd.html)]                                     | compress DMD for computation speedup                            | `pydmd.CDMD`                |
+| Tutorial5 [[.ipynb](tutorial5/tutorial-5-fbdmd.ipynb), [.py](tutorial5/tutorial-5-fbdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial5fbdmd.html)]                                  | forward-backward DMD for CFD model analysis                     | `pydmd.FbDMD`               |
+| Tutorial6 [[.ipynb](tutorial6/tutorial-6-hodmd.ipynb), [.py](tutorial6/tutorial-6-hodmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial6hodmd.html)]                                  | higher-order DMD applied to scalar time-series                  | `pydmd.HODMD`               |
+| Tutorial7 [[.ipynb](tutorial7/tutorial-7-dmdc.ipynb), [.py](tutorial7/tutorial-7-dmdc.py), [.html](http://pydmd.github.io/PyDMD/tutorial7dmdc.html)]                                     | DMD with control                                                | `pydmd.DMDC`                |
+| Tutorial8 [[.ipynb](tutorial8/tutorial-8-comparisons.ipynb), [.py](tutorial8/tutorial-8-comparisons.py), [.html](http://pydmd.github.io/PyDMD/tutorial8comparison.html)]                 | comparison between DMD and optimal closed-form DMD              | `pydmd.OptDMD`              |
+| Tutorial9 [[.ipynb](tutorial9/tutorial-9-spdmd.ipynb), [.py](tutorial9/tutorial-9-spdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial9spdmd.html)]                                  | sparsity-promoting DMD                                          | `pydmd.SpDMD`               |
+| Tutorial10 [[.ipynb](tutorial10/tutorial-10-paramdmd.ipynb), [.py](tutorial10/tutorial-10-paramdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial10paramdmd.html)]                   | parametric DMD                                                  | `pydmd.ParametricDMD`       |
+| Tutorial11 [[.ipynb](tutorial10/tutorial-11-regularization.ipynb), [.py](tutorial11/tutorial-11-regularization.py), [.html](http://pydmd.github.io/PyDMD/tutorial11regularization.html)] | Tikhonov regularization                                         | `pydmd.DMDBase`             |
+| Tutorial12 [[.ipynb](tutorial12/tutorial-12-cdmd.ipynb), [.py](tutorial12/tutorial-12-cdmd.py)]                                                                                               | cDMD for background modeling                                    | `pydmd.CDMD`                |
+| Tutorial13 [[.ipynb](tutorial13/tutorial-13-subspacedmd.ipynb), [.py](tutorial13/tutorial-13-subspacedmd.py)]                                                                                 | SubspaceDMD for locating eigenvalues of stochastic systems      | `pydmd.SubspaceDMD`         |
+| Tutorial14 [[.ipynb](tutorial14/tutorial-14-bop-dmd.ipynb), [.py](tutorial14/tutorial-14-bop-dmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial14-bop-dmd.html)]                     | Comparison between Bagging-/ Optimized DMD and exact DMD        | `pydmd.BOPDMD`              |
+| Tutorial15 [[.ipynb](tutorial15/tutorial-15-pidmd.ipynb), [.py](tutorial15/tutorial-15-pidmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial15-pidmd.html)]                           | Physics-informed DMD for manifold enforcement                   | `pydmd.PiDMD`               |
+| Tutorial16 [[.ipynb](tutorial16/tutorial-16-rdmd.ipynb), [.py](tutorial16/tutorial-16-rdmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial16-rdmd.html)]                              | Randomized DMD for greater computation speedup                  | `pydmd.RDMD`                |
+| Tutorial17 [[.ipynb](tutorial17/tutorial-17-edmd.ipynb), [.py](tutorial17/tutorial-17-edmd.py), [.html](http://pydmd.github.io/PyDMD/tutorial17-edmd.html)]                              | Extended DMD for nonlinear eigenfunction discovery              | `pydmd.EDMD`                |
+| Tutorial18 [[.ipynb](tutorial18/tutorial-18-lando.ipynb), [.py](tutorial18/tutorial-18-lando.py), [.html](http://pydmd.github.io/PyDMD/tutorial18-lando.html)]                           | LANDO for nonlinear system modeling                             | `pydmd.LANDO`               |
+| Tutorial19 [[.ipynb](tutorial19/tutorial-19-havok.ipynb), [.py](tutorial19/tutorial-19-havok.py), [.html](http://pydmd.github.io/PyDMD/tutorial19-havok.html)]                           | HAVOK for modeling chaos with partial measurements              | `pydmd.HAVOK`               |
+| Tutorial20a&#160;[[.ipynb](tutorial20/costs-tutorial_toy-data.ipynb)]     <br/><br/><br/><br/>                                                                                                          | COSTS for decomposing toy data                                  | `pydmd.COSTS`             |
+| Tutorial20b&#160;[[.ipynb](tutorial20/costs-tutorial_real-data.ipynb)]     <br/><br/><br/>                                                                                                              | mrCOSTS for decomposing multi-scale physics of real, noisy data | `pydmd.mrCOSTS`             |
 
 
 

tests/test_mrcosts.py

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Multi-resolution Coherent Scale separation (mrCOSTS) using PyDMD\n",
+    "# Tutorial 20b: Multi-resolution Coherent Scale separation (mrCOSTS) using real data\n",
     "\n",
     "This tutorial focuses on the real-world application the mrCOSTS object for multi-resolution coherent scale separation. In the toy-data example, the data include perfect oscillators as well as data engineered to be separable. Real world data is not so amiable. We provide this example with real data to illustrate how to use the mrCOSTS method on noisy, messy data. \n",
     "\n",