DMDBase#

class datafold.dynfold.DMDBase(sys_type, sys_mode, is_controlled=False, is_control_affine=False, is_time_invariant=True)[source]#

Bases: BaseEstimator, LinearDynamicalSystem, TSCPredictMixin

Abstract base class for variations of the Dynamic Mode Decomposition (DMD).

A DMD model decomposes a linearly identified dynamical system matrix – obtained from example time series data – into intrinsic spatial-temporal components. Specifically, this corresponds to an eigendecomposition of the system matrix. Due to its connection to non-linear dynamical systems with the Koopman operator (see e.g. introduction in Tu et al. [2014]), the DMD variants (in the subclasses) use the terminology of this.

A DMD model approximates the Koopman operator with a matrix K, which defines a linear dynamical system

K^n x_0 &= x_n

with x_n being the (column) state vectors of the system at timestep n. Note, that the state vectors x, when used in conjunction with the EDMD() model are not the original observations of a system, but states from a functional coordinate basis that seeks to linearize the dynamics (see reference for details).

A DMDBase subclass can either provide the matrix K, the generator U of K

U = \frac{K-I}{\Delta t}

or the spectrum of either K or U. The spectrum of the Koopman matrix (or similar its generator) is obtained by solving the eigenproblem of the matrix

K \Psi_r = \Psi_r \Lambda

where \Psi_r are the right eigenvectors and \Lambda a matrix with the eigenvalues on the diagonal. The spectral components enable further system analysis (e.g. stability, mode analysis) and lead also to an inexpensive system representation with powers of a diagonal matrix instead of a full matrix:

x_n &= K^n x_0 \\
&= K^n \Psi_r b_0  \\
&= \Psi_r \Lambda^n b_0

The DMD modes \Psi_r - or eigenvectors - remain constant and the vector b_0 can be understood as a “spectrally adapted initial state”, which is obtained from x_0 and the eigenvectors.

All subclasses of DMDBase are also subclasses of LinearDynamicalSystem and must therefore set up and specify the system (see setup_sys_spectral() and setup_sys_matrix()).

References

Schmid [2010] - DMD method in the original sense Rowley et al. [2009] - connects the DMD method to Koopman operator theory Tu et al. [2014] - generalizes the DMD to temporal snapshot pairs Williams et al. [2015] - generalizes the approximation to a lifted space Kutz et al. [2016] - an introductory book for DMD and its connection to Koopman theory

Attributes Summary

dmd_modes

Methods Summary

fit(X, *, U[, P, y])

Abstract method to train DMD model.

fit_predict(X, *[, U, y])

Fit model and reconstruct the time series data.

get_feature_names_out([input_features])

predict(X, *[, U, time_values])

Predict time series data for each initial condition and time values.

reconstruct(X, *[, U, qois])

Reconstruct time series collection.

score(X, *[, U, y, sample_weight])

Score model by reconstructing time series data.

Attributes Documentation

dmd_modes#

Methods Documentation

abstract fit(X, *, U, P=None, y=None, **fit_params)[source]#

Abstract method to train DMD model.

Parameters:
  • X (TSCDataFrame) – Training time series data.

  • U (Optional[TSCDataFrame]) – Control input (set to None by default if the subclass does not support control input).

  • P

    ignored

    reserved for parameter input

  • y

    ignored
    TODO for future devevelopment: This parameter is reserved to specify an

    extra map. Currently, this is already implemented for EDMD.

Return type:

DMDBase

fit_predict(X, *, U=None, y=None, **fit_params)[source]#

Fit model and reconstruct the time series data.

Parameters:
  • X (TSCDataFrame) – Training time series data.

  • y – ignored

Returns:

same shape as input X

Return type:

TSCDataFrame

get_feature_names_out(input_features=None)[source]#
predict(X, *, U=None, time_values=None, **predict_params)[source]#

Predict time series data for each initial condition and time values.

Parameters:
  • X (TSCDataFrame, numpy.ndarray) – Initial conditions of shape (n_initial_condition, n_features).

  • time_values (Optional[ndarray]) – Time values to evaluate the model at. If not provided, then the time at the initial condition plus dt_ is set (i.e. predict a single step).

Keyword Arguments:
  • post_map (Union[numpy.ndarray, scipy.sparse.spmatrix]) – A matrix that is combined with the right eigenvectors. post_map @ eigenvectors_right_. If set, then also the input feature_columns is required. It cannot be set with ‘modes’ at the same time and requires “sys_type=spectral”.

  • modes (Union[numpy.ndarray]) – A matrix that sets the DMD modes directly. This must not be given at the same time with post_map. If set, then also the input feature_columns is required. It cannot be set with ‘modes’ at the same time and requires “sys_type=spectral”.

  • feature_columns (pandas.Index) – If post_map is given with a changed state length, then new feature names must be provided.

Returns:

The computed time series predictions, where each time series has shape (n_time_values, n_features).

Return type:

TSCDataFrame

reconstruct(X, *, U=None, qois=None)[source]#

Reconstruct time series collection.

Extract the same initial states from the time series in the collection and predict the other states with the model at the same time values.

Parameters:
Returns:

same shape as input X

Return type:

TSCDataFrame

score(X, *, U=None, y=None, sample_weight=None)[source]#

Score model by reconstructing time series data.

The default metric (see TSCMetric used is mode=”feature”, “metric=rmse” and “min-max” scaling.

Parameters:
  • X (TSCDataFrame) – Time series data to reconstruct with (n_samples, n_features).

  • U (Optional[TSCDataFrame]) – Time series with control states (only necessary if the model was fit with control input).

  • y (None) – ignored

  • sample_weight – passed to TSCScoring.__call__().

Returns:

score

Return type:

float