Main module (dmdlab.dmd)

The dynamic mode decomposition is a regression technique for discovering the global dynamical operator describing a state space dynamical system from measurement data. The discovered operator is decomposed into the dominant spatiotemporal coherent structures stored as eigenvalues and DMD modes.

DMD

Dynamic mode decomposition.

dmdlab.dmd.DMD.__init__(self, X2, X1, ts, **kwargs)

X2 = A X1

Parameters

  • X2 (ndarray of float) – Left side data matrix with columns containing states at sequential times.

  • X1 (ndarray of float) – Right side data matrix with columns containing states at sequential times.

  • U (ndarray of float) – Control signal(s) with columns containing controls.

  • ts (ndarray of float) – Time measurements

  • **kwargs – see Keyword arguments.

Keyword Arguments

  • threshold (real, int) – Truncate the singular values associated with DMD modes. default None.

  • threshold_type (str) – One of {‘number’, ‘percent’}. default ‘percent’.

dmdlab.dmd.DMD.X2

Left side data matrix

Type

ndarray of float

dmdlab.dmd.DMD.X1

Right side data matrix

Type

ndarray of float

dmdlab.dmd.DMD.U

Control signal data matrix

Type

ndarray of float

dmdlab.dmd.DMD.t0

Initial time.

Type

float

dmdlab.dmd.DMD.dt

Step size.

Type

float

dmdlab.dmd.DMD.orig_timesteps

Original times matching X1.

Type

ndarray of float

dmdlab.dmd.DMD.A

Learned drift operator.

Type

ndarray of float

dmdlab.dmd.DMD.Atilde

Projected A.

Type

ndarray of float

dmdlab.dmd.DMD.eigs

Eigenvalues of Atilde.

Type

list of float

dmdlab.dmd.DMD.modes

DMD modes are eigenvectors of Atilde (shared by A).

Type

ndarray of float

class dmdlab.dmd.DMD(X2, X1, ts, **kwargs)
predict_cts(ts=None, x0=None)

Predict the future state using the continuous operator A.

Parameters

  • ts (ndarray of float) – Array of time-steps to predict. default self.orig_timesteps.

  • x0 (ndarray of float) – The initial value. default self.x0.

Returns

Predicted state for each control input.

Return type

ndarray of float

predict_dst(ts=None, x0=None)

Predict the future state using continuous approximation to the discrete A.

Parameters

  • ts (ndarray of float) – Array of time-steps to predict. default self.orig_timesteps.

  • x0 (ndarray of float) – The initial value. default self.x0.

Returns

Predicted state for each control input.

Return type

ndarray of float

time_spectrum(ts, system='discrete')

Returns a continuous approximation to the time dynamics of A.

Note that A_dst = e^(A_cts dt). Suppose (operator, eigs) pairs are denoted (A_dst, Y) for the discrete case and (A_cts, Omega) for the continuous case. The eigenvalue correspondence is e^log(Y)/dt = Omega.

Parameters

  • ts (ndarray of float) – Times.

  • system ({'continuous', 'discrete'}) – default ‘discrete’.

Returns

Evaluations of modes at ts.

Return type

ndarray of float

DMDc

Dynamic mode decomposition with control.

dmdlab.dmd.DMDc.__init__(self, X2, X1, U, ts, **kwargs)

X2 = A X1 + B U

Parameters

  • X2 (ndarray of float) – Left side data matrix with columns containing states at sequential times.

  • X1 (ndarray of float) – Right side data matrix with columns containing states at sequential times.

  • U (ndarray of float) – Control signal(s) with columns containing controls.

  • ts (ndarray of float) – Time measurements

  • **kwargs – see Keyword arguments.

Keyword Arguments

  • threshold (real, int) – Truncate the singular values associated with DMD modes. default None.

  • threshold_type (str) – One of {‘number’, ‘percent’}. default ‘percent’.

dmdlab.dmd.DMDc.X2

Left side data matrix

Type

ndarray of float

dmdlab.dmd.DMDc.X1

Right side data matrix

Type

ndarray of float

dmdlab.dmd.DMDc.U

Control signal data matrix

Type

ndarray of float

dmdlab.dmd.DMDc.t0

Initial time.

Type

float

dmdlab.dmd.DMDc.dt

Step size.

Type

float

dmdlab.dmd.DMDc.orig_timesteps

Original times matching X1.

Type

ndarray of float

dmdlab.dmd.DMDc.A

Learned drift operator.

Type

ndarray of float

dmdlab.dmd.DMDc.Atilde

Projected A.

Type

ndarray of float

dmdlab.dmd.DMDc.B

Learned control operator.

Type

ndarray of float

dmdlab.dmd.DMDc.Btilde

projected B.

Type

ndarray of float

dmdlab.dmd.DMDc.eigs

Eigenvalues of Atilde.

Type

list of float

dmdlab.dmd.DMDc.modes

DMD modes are eigenvectors of Atilde (shared by A).

Type

ndarray of float

class dmdlab.dmd.DMDc(X2, X1, U, ts, **kwargs)
predict_cts(control=None, x0=None, dt=None)

Predict the future state using continuous evolution.

Evolve the system from X0 as long as control is available, using the continuous evolution while u is constant,

X_dot = A X + B u x(t+dt) = e^{dt A}(x(t) + dt B u(t))

Default behavior (control=None) is to use the original control. (If the underlying A is desired, format zeros_like u that runs for the desired time.) Be sure that dt matches the train dt if using delay embeddings.

Parameters

  • control (ndarray of float) – The control signal. A zero-order hold is assumed between time steps. The dt must match the training data if time-delays are used.

  • x0 (ndarray of float) – The initial value.

  • dt (float) – The time-step between control inputs.

Returns

Predicted state for each control input.

Return type

ndarray of float

predict_dst(control=None, x0=None)

Predict the future state using discrete evolution.

Evolve the system from X0 as long as control is available, using the discrete evolution X_2 = A X_1 + B u_1.

Default behavior (control=None) is to use the original control. (If the underlying A is desired, format zeros_like u that runs for the desired time.)

Parameters

  • control (ndarray of float) – The control signal.

  • x0 (ndarray of float) – The initial value.

Returns

Predicted state for each control input.

Return type

ndarray of float

BiDMD

Bilinear dynamic mode decomposition.

dmdlab.dmd.biDMD.__init__(self, X2, X1, U, ts, **kwargs)

X2 = A X1 + U B X1

Parameters

  • X2 (ndarray of float) – Left side data matrix with columns containing states at sequential times.

  • X1 (ndarray of float) – Right side data matrix with columns containing states at sequential times.

  • U (ndarray of float) – Control signal(s) with columns containing controls.

  • ts (ndarray of float) – Time measurements

  • **kwargs – see Keyword arguments.

Keyword Arguments

  • shift (int) – Number of time delays in order to match times in the nonlinear term. default 0.

  • threshold (real, int) – Truncate the singular values associated with DMD modes. default None.

  • threshold_type (str) – One of {‘number’, ‘percent’}. default ‘percent’.

dmdlab.dmd.biDMD.X2

Left side data matrix

Type

ndarray of float

dmdlab.dmd.biDMD.X1

Right side data matrix

Type

ndarray of float

dmdlab.dmd.biDMD.U

Control signal data matrix

Type

ndarray of float

dmdlab.dmd.biDMD.Ups

augmented state U*X1.

Type

ndarray of float

dmdlab.dmd.biDMD.t0

Initial time.

Type

float

dmdlab.dmd.biDMD.dt

Step size.

Type

float

dmdlab.dmd.biDMD.orig_timesteps

Original times matching X1.

Type

ndarray of float

dmdlab.dmd.biDMD.A

Learned drift operator.

Type

ndarray of float

dmdlab.dmd.biDMD.Atilde

Projected A.

Type

ndarray of float

dmdlab.dmd.biDMD.B

Learned nonlinear control operator.

Type

ndarray of float

dmdlab.dmd.biDMD.Btilde

projected B.

Type

ndarray of float

dmdlab.dmd.biDMD.eigs

Eigenvalues of Atilde.

Type

list of float

dmdlab.dmd.biDMD.modes

DMD modes are eigenvectors of Atilde (shared by A).

Type

ndarray of float

class dmdlab.dmd.biDMD(X2, X1, U, ts, **kwargs)
predict_cts(control=None, x0=None, dt=None)

Predict the future state using continuous evolution.

Evolve the system from X0 as long as control is available, using the continuous evolution while u is constant,

x_{t+1} = e^{A dt + u B dt } x_t

Parameters

  • control (ndarray of float) – The control signal. A zero-order hold is assumed between time steps. The dt must match the training data if time-delays are used.

  • x0 (ndarray of float) – The initial value.

  • dt (float) – The time-step between control inputs.

Returns

Predicted state for each control input.

Return type

ndarray of float

predict_dst(control=None, x0=None)

Predict the future state using discrete evolution.

Evolve the system from X0 as long as control is available, using the discrete evolution:

x_1 = A x_0 + B (u.x_0)

= [A B] [x_0, u.x_0]^T

Parameters

  • control (ndarray of float) – The control signal.

  • () (x0) – The initial value.

Returns

Predicted state for each control input.

Return type

ndarray of float

BiDMDc

Bilinear dynamic mode decomposition with control.

dmdlab.dmd.biDMDc.__init__(self, X2, X1, U, ts, **kwargs)

X2 = A X1 + U B X1 + D U

Parameters

  • X2 (ndarray of float) – Left side data matrix with columns containing states at sequential times.

  • X1 (ndarray of float) – Right side data matrix with columns containing states at sequential times.

  • U (ndarray of float) – Control signal(s) with columns containing controls.

  • ts (ndarray of float) – Time measurements

  • **kwargs – see Keyword arguments.

Keyword Arguments

  • shift (int) – Number of time delays in order to match times in the nonlinear term. default 0.

  • threshold (real, int) – Truncate the singular values associated with DMD modes. default None.

  • threshold_type (str) – One of {‘number’, ‘percent’}. default ‘percent’.

dmdlab.dmd.biDMDc.X2

Left side data matrix

Type

ndarray of float

dmdlab.dmd.biDMDc.X1

Right side data matrix

Type

ndarray of float

dmdlab.dmd.biDMDc.U

Control signal data matrix

Type

ndarray of float

dmdlab.dmd.biDMDc.Ups

augmented state U*X1.

Type

ndarray of float

dmdlab.dmd.biDMDc.t0

Initial time.

Type

float

dmdlab.dmd.biDMDc.dt

Step size.

Type

float

dmdlab.dmd.biDMDc.orig_timesteps

Original times matching X1.

Type

ndarray of float

dmdlab.dmd.biDMDc.A

Learned drift operator.

Type

ndarray of float

dmdlab.dmd.biDMDc.Atilde

Projected A.

Type

ndarray of float

dmdlab.dmd.biDMDc.B

Learned nonlinear control operator.

Type

ndarray of float

dmdlab.dmd.biDMDc.Btilde

projected B.

Type

ndarray of float

dmdlab.dmd.biDMDc.D

Learned control operator.

Type

ndarray of float

dmdlab.dmd.biDMDc.eigs

Eigenvalues of Atilde.

Type

list of float

dmdlab.dmd.biDMDc.modes

DMD modes are eigenvectors of Atilde (shared by A).

Type

ndarray of float

class dmdlab.dmd.biDMDc(X2, X1, U, ts, **kwargs)
predict_cts(control=None, x0=None, dt=None)

Predict the future state using continuous evolution.

Evolve the system from X0 as long as control is available, using the continuous evolution while u is constant,

x_{t+1} = e^{A dt + u B dt } (x_t + dt * D u_t}

Parameters

  • control (ndarray of float) – The control signal. A zero-order hold is assumed between time steps. The dt must match the training data if time-delays are used.

  • x0 (ndarray of float) – The initial value.

  • dt (float) – The time-step between control inputs.

Returns

Predicted state for each control input.

Return type

ndarray of float

predict_dst(control=None, x0=None)

Predict the future state using discrete evolution.

Evolve the system from X0 as long as control is available, using the discrete evolution,

x_1 = A x_0 + B (u*x_0) + D u

= [A B D] [x_0, u*x_0, u ]^T

Parameters

  • control (ndarray of float) – The control signal.

  • () (x0) – The initial value.

Returns

Predicted state for each control input.

Return type

ndarray of float

Data processing utilities (dmdlab.process)

dmdlab.process.cts_from_dst(dA, dB, dt)

Convert discrete state space matrices with time step dt to continuous matrices by inverting

exp(dt*[[cA, cB], = [[dA, dB],

[0, 0 ]]) [0, 1 ]]

Require dA in R^(na x na) and dB in R^(na x nb). The zero and identity components make the matrix square.

Parameters

  • dA (ndarray of float) – discrete A.

  • dB (ndarray of float) – discrete B.

  • dt (float) – Time step.

Returns

tuple containing:

(ndarray of float): Continuous A. (ndarray of float): Continuous B.

Return type

(tuple)

dmdlab.process.delay_embed(X, shift)

Delay-embed the matrix X with measurements from future times.

Parameters

  • X (ndarray of float) – Data matrix with columns storing states at sequential time measurements.

  • shift (int) – Number of future times copies to augment to the current time state.

Returns

The function maps (d, t) to (shift+1, d, t-shft) which is then stacked

into ((shift+1)*d, t-shift).

Return type

(ndarray of float)

dmdlab.process.dst_from_cts(cA, cB, dt)

Convert constant continuous state space matrices to discrete matrices with time step dt using:

exp(dt*[[cA, cB], = [[dA, dB],

[0, 0 ]]) [0, 1 ]]

Require cA in R^(na x na) and cB in R^(na x nb). The zero and identity components make the matrix square.

Parameters

  • cA (ndarray of float) – Continuous A.

  • cB (ndarray of float) – Continuous B.

  • dt (float) – Time step.

Returns

tuple containing:

(ndarray of float): discrete A. (ndarray of float): discrete B.

Return type

(tuple)

Plotting utilities (dmdlab.plot)

dmdlab.plot.plot_eigs(eigs, **kwargs)

Plot the provided eigenvalues (of the dynamics operator A).

Parameters

  • eigs (ndarray of complex) –

  • **kwargs – kwargs of matplotlib.pyplot.subplots

Returns

Tuple containing:

fig: figure object ax: axes object

Return type

(tuple)