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 , which defines a linear dynamical system
with being the (column) state vectors of the system at timestep . Note, that the state vectors , 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 , the generator ofor the spectrum of either or . The spectrum of the Koopman matrix (or similar its generator) is obtained by solving the eigenproblem of the matrix
where are the right eigenvectors and 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:
The DMD modes - or eigenvectors - remain constant and the vector can be understood as a “spectrally adapted initial state”, which is obtained from and the eigenvectors.
All subclasses of
DMDBase
are also subclasses ofLinearDynamicalSystem
and must therefore set up and specify the system (seesetup_sys_spectral()
andsetup_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
See also
Attributes Summary
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 toNone
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:
- 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:
- 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 plusdt_
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 inputfeature_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:
- 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:
- 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: