GitHub

DataDrivenDMD

DataDrivenDMD provides operator-based inference. If we assume the following structure of a discrete dynamical system

\[x_{i+1} = f(x_{i}, p, t, u_{i})\]

Then a valid Koopman representation states, that the system can be expressed as

\[\varphi_{i+1} = \mathcal K \circ \varphi_i\]

where $\mathcal K$ denotes the Koopman operator, which is linear. However, this comes at the price of lifting the original state space $x \in \mathbb R^{n_x}$ into its observables $\varphi \in \mathbb C^{n_\varphi}$ with $n_x \leq n_{\varphi} \leq \infty$ . The important and most crucial fact here is the last inequality. While Koopman stated that any dynamical system can be expressed this way, it might well be that it can only be done in infinite dimensions.

Luckily, we can approximate the operator via Dynamic Mode Decomposition:

\[\hat \varphi_{i+1} \approx K \hat \varphi_i\]

with $K \in \mathbb C^{n_d \times n_d}$ being a simple matrix, not necessary limited to the complex domain. A similar result holds for time continuous systems in the form of the Koopman generator:

\[\partial_t \hat \varphi \approx K_G \hat \varphi\]

Algorithms

The abstract algorithm below is a developer interface for extending the Koopman solver. Users should generally select one of the concrete algorithms.

DataDrivenDMD.AbstractKoopmanAlgorithm — Type
AbstractKoopmanAlgorithm

Developer interface for algorithms that estimate a Koopman operator or generator. This interface is intended for DataDrivenDiffEq solver packages and advanced extensions, not ordinary application code.

Interface

A subtype must implement alg(X, Y) -> (K, B), where X and Y are lifted data matrices with one observation per column, K is an operator representation convertible by Matrix, and B is the input map or an empty matrix when no controls are used. A controlled implementation may additionally implement alg(X, Y, U) -> (K, B). The generic four-argument forms support a supplied input map or nothing and are provided by this package.

To participate in the common solve workflow, the subtype must be usable by the generic DataDrivenDiffEq.get_fit_targets and CommonSolve.solve! methods for InternalDataDrivenProblem. The two-argument method is required; the three-argument method is required when the basis contains controls. The returned K must represent a square operator on the lifted state space, and B must have the corresponding output-by-control shape. A custom algorithm should preserve these dimensions so that the result can be converted back to a DataDrivenDiffEq.Basis.

Arguments

  • X::AbstractArray: lifted input data, with features in rows and observations in columns.
  • Y::AbstractArray: lifted target data with the same number of columns as X.
  • U::AbstractArray: optional control data with one column per observation.
  • B::AbstractArray or nothing: an optional input map supplied by the common four-argument adapter.

Returns

Return (K, B). K is an operator representation accepted by the result constructor, and B is an input map or an empty matrix when the fit is uncontrolled.

Example

    using LinearAlgebra

struct MyKoopman <: DataDrivenDMD.AbstractKoopmanAlgorithm end

    function (::MyKoopman)(X, Y)
        return eigen(Y / X), zeros(eltype(X), size(Y, 1), 0)
    end
source
DataDrivenDMD.DMDPINV — Type
mutable struct DMDPINV <: DataDrivenDMD.AbstractKoopmanAlgorithm

Approximates the Koopman operator K based on

K = Y / X

where Y and X are data matrices. Returns a Eigen factorization of the operator.

Arguments

  • X::AbstractArray: lifted state data, with one observation per column.
  • Y::AbstractArray: lifted next-state data with the same number of columns as X.
  • U::AbstractArray: optional control data for the controlled DMDc form.

Returns

Return (K, B), where K is an Eigen factorization and B is an empty matrix for the uncontrolled form or the learned input map for the controlled form.

Fields

Signatures

Example

X = [1.0 2.0; 2.0 4.0]
Y = [2.0 4.0; 4.0 8.0]
K, B = DMDPINV()(X, Y)
isempty(B)
source
DataDrivenDMD.DMDSVD — Type
mutable struct DMDSVD{T} <: DataDrivenDMD.AbstractKoopmanAlgorithm

Approximates the Koopman operator K based on the singular value decomposition of X such that:

K = Y*V*Σ*U'

where Y and X = U*Σ*V' are data matrices. The singular value decomposition is truncated via the truncation parameter, which can either be an Int indicating an index-based truncation or a Real indicating a tolerance-based truncation. Returns a Eigen factorization of the operator.

Arguments

  • X::AbstractArray: lifted state data, with one observation per column.
  • Y::AbstractArray: lifted next-state data with the same number of columns as X.
  • U::AbstractArray: optional control data for the controlled DMDc form.
  • truncation: an integer rank or a real-valued relative singular-value tolerance.

Returns

Return (K, B), where K is an Eigen factorization and B is the learned input map or an empty matrix when controls are absent.

Fields

  • truncation: Indicates the truncation

Signatures

Example

K, B = DMDSVD(1)([1.0 2.0; 2.0 4.0], [2.0 4.0; 4.0 8.0])
size(Matrix(K)) == (1, 1)
source
DataDrivenDMD.TOTALDMD — Type
mutable struct TOTALDMD{R, A} <: DataDrivenDMD.AbstractKoopmanAlgorithm

Approximates the Koopman operator K with the algorithm alg over the rank-reduced data matrices Xᵣ = X Qᵣ and Yᵣ = Y Qᵣ, where Qᵣ originates from the singular value decomposition of the joint data Z = [X; Y]. Based on this paper.

If rtol ∈ (0, 1) is given, the singular value decomposition is reduced to include only entries bigger than rtol*maximum(Σ). If rtol is an integer, the reduced SVD up to rtol is used for computation.

Arguments

  • X::AbstractArray: lifted input data, with one observation per column.
  • Y::AbstractArray: lifted target data with the same number of columns as X.
  • U::AbstractArray: optional control data.
  • truncation: rank or relative singular-value tolerance used for the joint SVD.
  • alg::AbstractKoopmanAlgorithm: algorithm applied after the joint reduction.

Returns

Return (K, B) from alg after the data are projected onto the retained singular subspace.

Fields

  • truncation

  • alg

Signatures

Example

alg = TOTALDMD(1, DMDPINV())
K, B = alg([1.0 2.0; 2.0 4.0], [2.0 4.0; 4.0 8.0])
isempty(B)
source
DataDrivenDMD.FBDMD — Type
mutable struct FBDMD{R} <: DataDrivenDMD.AbstractKoopmanAlgorithm

Approximates the Koopman operator K via the forward-backward DMD. It is assumed that K = sqrt(K₁*inv(K₂)), where K₁ is the approximation via forward and K₂ via DMDSVD. Based on this paper.

If truncation ∈ (0, 1) is given, the singular value decomposition is reduced to include only entries bigger than truncation*maximum(Σ). If truncation is an integer, the reduced SVD up to truncation is used for computation.

Arguments

  • X::AbstractArray: lifted input data, with one observation per column.
  • Y::AbstractArray: lifted target data with the same number of columns as X.
  • U::AbstractArray: optional control data. This form delegates to the wrapped DMDSVD algorithm.
  • truncation: rank or relative singular-value tolerance used by the wrapped DMDSVD algorithm.

Returns

Return (K, B), where K is an Eigen factorization and B is an empty matrix for uncontrolled data or the learned input map for controlled data.

Fields

  • alg

Signatures

Example

K, B = FBDMD(1)([1.0 2.0; 2.0 4.0], [2.0 4.0; 4.0 8.0])
isempty(B)
source

Result API

DataDrivenDMD.KoopmanResult — Type
struct KoopmanResult{K, B, C, Q, P, T} <: DataDrivenDiffEq.AbstractDataDrivenResult

Result returned by DataDrivenDMD solvers.

Fields

  • k: Matrix representation of the operator / generator

  • b: Matrix representation of the inputs mapping

  • c: Matrix representation of the pullback onto the states

  • q: Internal matrix used for updating

  • p: Internal matrix used for updating

  • rss: Residual sum of squares

  • loglikelihood: Loglikelihood

  • nullloglikelihood: Nullloglikelihood

  • dof: Degrees of freedom

  • nobs: Number of observations

  • retcode: Returncode

The k, b, and c fields represent the learned operator, input map, and output map. q and p retain update matrices used by the online formulation; they are developer state and should not be edited by callers. The remaining fields implement the StatsAPI.StatisticalModel interface.

Returns

The constructor returns a result whose operator and maps are compatible with get_operator, get_inputmap, and get_outputmap.

source