kontrol.dmd

Primary modules

kontrol.dmd.dmd

Dynamic mode decomposition class

class kontrol.dmd.dmd.DMD(snapshot_1, snapshot_2=None, truncation_value=None, dt=1, run=False)

Bases: object

Dynamic mode decomposition class

Parameters

  • snapshot_1 (array) – The 2-D snapshot array.

  • snapshot_2 (array, optional) – The 2-D snapshot array at next time step. If not provided, snapshot_1[:, :-1] becomes snapshot_1 and snapshot_2[:, 1:] becomes snapshot_2. Defaults None.

  • truncation_value (float, optional) – The truncation value (order/rank) of the system. Defaults None.

  • dt (float, optional) – The time difference between two snapshots. Defaults 1.

  • run (bool, optional) – Run dynamic mode decomposition upon construction. Computes DMD modes, Reduced-order model, etc. truncation_value must be specified for this to work. Defaults False.

snapshot_1

The 2-D snapshot matrix

Type

array

snapshot_2

The 2-D snapshot matrix at next time step.

Type

array

truncation_value

The truncation value (order/rank) of the system.

Type

int

dt

The time difference between two snapshots.

Type

float

u

The left singular vector of the snapshot_1 matrix.

Type

array

vh

The right singular vector (conjugate-transposed) of the snapshot_1 matrix.

Type

array

sigma

The singular values of the snapshot_1 matrix

Type

array

u_truncated

The truncated left singular vector of the snapshot_1 matrix.

Type

array

vh_truncated

The truncated right singular vector (conjugate-transposed) of the snapshot_1 matrix.

Type

array

sigma_truncated

The truncated singular values of the snapshot_1 matrix

Type

array

A_reduced

The reduced-order model of the dynamics.

Type

array

w_reduced

The eigenvalues of the reduced-order model.

Type

array

v_reduced

The eigenvectors of the reduced-order model.

Type

array

dmd_modes

The DMD modes.

Type

array

complex_frequencies

The complex frequencies of the modes.

Type

array

v_constant

The constant vector of the time dynamics, determined by initial conditions.

Type

array

time_dynamics

The time dynamics of the ODE solution.

Type

array

prediction

The predicted time series.

Type

array

property A_reduced

Reduced-order model

property complex_frequencies

Complex frequencies

compute_complex_frequencies(dt=None)

Compute the complex frequencies

Parameters

dt (float, optional) – The time spacing between snapshots. Specified as self.dt or in constructor option. Defaults 1.

Returns

complex_frequencies – Array of complex frequencies

Return type

array

compute_dmd_modes()

Compute the DMD modes

Returns

dmd_modes – The DMD modes.

Return type

array

compute_reduced_model()

Compute the reduced-order model

Returns

A_reduced – Matrix representing the reduced-order model.

Return type

array

property dt

Time difference between the snapshots

eig_reduced_model()

Eigen decomposition of the reduced-order model

Returns

  • w_reduced (array) – The list of eigenvalues.

  • v_reduced (array) – Eigenvalues as columns.

low_rank_approximation(truncation_value=None)

Truncate the svd.

Paramters

truncation_valueint, optional

The truncation value (order/rank) of the system. Specify as self.truncation_value or via the constuctor option. Defaults None.

returns

  • u_truncated (array) – Truncated unitary matrix having left singular vectors as columns.

  • sigma_truncated (array) – Truncated singular values.

  • vh_truncated (array) – Truncated unitary matrix having right singular vectors as rows.

predict(t, t_constant=None, i_constant=0)

Predict the future states given a time array

Parameters

  • t (array) – The time array

  • t_constant (float, optional) – Time at which the constant vector is calculated. Defaults to be t[0] if not given.

  • i_constant (int, optional) – Index of the snapshot_1 at which the constant vector is calculated. Defaults 0.

Returns

prediction – Predicted states.

Return type

array

Notes

The constant vector is the vector that evolves and is evaluated using the initial/boundary values. Set t_constant and i_constant to where the prediction of the time series begins.

property prediction

The ODE solution

run()

Run the DMD algorithm, compute dmd modes and complex frequencies

property sigma

Singular values

property sigma_truncated

Singular values truncated

property snapshot_1

Snapshot 1

property snapshot_2

Snapshot 1

svd()

Decompose the snapshot 1

Returns

  • u (array) – Unitary matrix having left singular vectors as columns.

  • sigma (array) – The singular values.

  • vh (array) – Unitary matrix having right singular vectors as rows.

property time_dynamics

Time dynamics of the ODE solution

property truncation_value

Truncation value (order/rank) of the system

property u

Left singular vectors

property u_truncated

Left singular vectors (truncated)

property v_constant

Constant vector of the ODE solution

property vh

Right singular vectors

property vh_truncated

Right singular vectors (truncated)

kontrol.dmd.forecast

kontrol.dmd.forecast.dmd_forecast(past, t_past, t_future, order=None, truncation_value=None, truncate_threshold=0.99, t_constant=None, i_constant=-1, return_dmd=False)

Produce a short term forecast from past time series data using DMD.

Parameters

  • past (array) – Past time series

  • t_past (array) – Past time axis.

  • t_future (array) – The time stamps of the future prediction. Preferably some time after t_past.

  • order (int, optional) – The order of hankelization. Defaults to int(len(past)/2).

  • truncation_value (int, optional) – The number of modes to be taken. If not provided, kontrol.dmd.auto_truncate() will be used with the parameter truncate_threshold to obtain the value.

  • truncate_threshold (float, optional) – Truncate modes that has singular values less than this fraction of the total. This should within [0, 1], with 0 being all modes accepted and 1 being all modes truncated. Defaults to 0.99.

  • t_constant (int, optional) – Time at which the constant vector is defined. Only make sense if it’s a value in t_past. Defaults t_past[-1].

  • i_constant (int, optional) – The index of the column vector in the data matrix (snapshot) at t_constant. Defaults -1.

  • return_dmd (boolean, optional) – Return the DMD instance if True. Defaults to False.

Returns

  • forecast (array) – The forecast

  • dmd (kontrol.dmd.DMD, optional) – The DMD instance used to produce the forecast.

Examples

t_past = np.linspace(0, 10, 1024) # Some time axis.
t_future = np.linspace(10, 15, 512) # Forecast between t=[10, 15].
time_series = ... # Some time series
forecast = dmd_forecast(time_series, t_past, t_future)

Secondary modules

kontrol.dmd.utils

Utility functions for Dymanic Mode Decomposition.

kontrol.dmd.utils.auto_truncate(sigma, threshold=0.99)

Automatically get truncation value

Parameters

  • sigma (array) – Singular values. Arranged from large to small values.

  • threshold (float, optional) – Only include singular values so their sum is threshold of the original sum. Defaults 0.99.

Returns

truncation_value – Amount of singular values that are required to reach the threshold sum.

Return type

int

kontrol.dmd.utils.hankel(array, order)

Hankelize an array

Parameters

  • array (array) – Array with rows as channels and columns as samples

  • order (int) – The number of rows of the hankelized matrix.

Returns

hankel_array – The hankelized array

Return type

array

Examples