Package: odmd
odmdA python package for online dynamic mode decomposition (Online DMD) and window dynamic mode decomposition (Window DMD) algorithms proposed in thispaper. For matlab implementation, seethis repo.To get started,pip install odmd --upgradeA variant of this algorithm for efficient data-driven online model learning (system identification) and control is implemented inosysid(trypip install osysid --upgrade). This algorithm has been show to be effective for flow separation control, see thispaperfor more details.Showcase: 2D linear time-varying systemWe take a 2D time-varying system given bydx/dt = A(t)xwhere x = [x1,x2]', A(t) = [0, w(t); -w(t), 0], w(t)=1+epsilon*t, epsilon=0.1. The slowly time-varying eigenvlaues of A(t) are pure imaginary, +(1+0.1t)j and -(1+0.1t)j, where j is the imaginary unit.Here we show how the proposed algorithm can be used to learn a model of the system. For more detail, seedemo.Time-varying state evolutionThe system is oscillating with increasing frequency (frequency increased from 1 to 2 in 10 secs).Tracking eigenvalues with online/window DMDIf we apply online/window DMD, the learned model can track the time-varying eigenvalues very well.Online DMD with weighting factor makes the learned model much more adaptive and tracks the true eigenvalues closely.Window DMD is designed to better track time-varying dynamics, even if no weighting is used.HightlightsHere are some hightlights about this algorithm, and for more detail please refer to thispaperEfficient data-driven online linear/nonlinear model learning (system identification). Any nonlinear and/or time-varying system is locally linear, as long as the model is updated in real-time wrt to new measurements.It finds the exact optimal solution (in the sense of least square error), without any approximation (unlike stochastic gradient descent).It achieves theoretical optimal time and space complexity.The time complexity (flops for one iteration) is O(n^2), where n is state dimension. This is much faster than standard algorithm O(n^2 * t), where t is the current time step (number of measurements). In online applications, t >> n and essentially will go to infinity.The space complexity is O(n^2), which is far more efficient than standard algorithm O(n * t) (t >> n).A weighting factor (in (0, 1]) can be used to place more weight on recent data, thus making the model more adaptive.It has been successfully applied to flow separation control problem, and achived real-time closed loop control. See thispaperfor details.InstallUse pippip install odmd --upgradeManual installCreate virtual env if neededpython3 -m venv .venv
source .venv/bin/activateClone from github and installgit clone https://github.com/haozhg/odmd.git
cd odmd/
python3 -m pip install -e .TestTo run testscd tests/
pip install r requirements.txt
python -m pytest .Algorithm DescriptionThis is a brief introduction to the algorithm. For full technical details, see thispaper, and chapter 3 and chapter 7 of thisPhD thesis.Unknown dynamical systemSuppose we have a (discrete) nonlinear and/or time-varyingdynamical system, and the state space representation isz(t) = f(t, z(t-1))where t is (discrete) time, z(t) is state vector.In general, a variant of this algorithm (trypip install osysid, seehere) also works if we have a nonlinear and/or time-varying mapy(t) = f(t, x(t))where x(t) is the input and y(t) is the output. Notice that dynamical system is a special case of nonlinear maps, by taking y(t) = z(t) and x(t) = z(t-1).It is assumed that we have measurements z(t) for t = 0,1,...T.However, we do not know function f.We aim to learn a linear model for the unknown dynamical system from measurement data up to time T.We want to the model to be updated efficiently in real-time as new measurement data becomes available.From now on, we will denote y(t) = z(t) and x(t) = z(t-1), so that the dynamical system can be written in this formy(t) = f(t, x(t))Online DMD algorithm descriptionThe algorithm is implemented in classOnlineDMD.At time step t, define two matrixX(t) = [x(1),x(2),...,x(t)],Y(t) = [y(1),y(2),...,y(t)],that contain all the past snapshot pairs, where x(t), y(t) are the n dimensional state vector, y(t) = f(t, x(t)) is the image of x(t), f() is the dynamics.  Here, if the (discrete-time) dynamics are given by z(t) = f(t, z(t-1)), then x(t), y(t) should be measurements corresponding to consecutive states z(t-1) and z(t).We would like to learn an adaptive online linear model M (a matrix) sty(t) = M * x(t)The matrix M is updated in real-time when new measurement becomes available. We aim to find the best M that leads to least-squre errors.An exponential weighting factor rho=sigma^2 (0<rho<=1) that places more weight on recent data can be incorporated into the definition of X(t) and Y(t) such thatX(t) = [sigma^(t-1)*x(1),sigma^(t-2)*x(2),…,sigma^(1)*x(t-1),x(t)],Y(t) = [sigma^(t-1)*y(1),sigma^(t-2)*y(2),...,sigma^(1)*y(t-1),y(t)].At time t+1, the matrices becomeX(t+1) = [x(1),x(2),…,x(t),x(t+1)],Y(t+1) = [y(1),y(2),…,y(t),y(t+1)].We need to incorporate a new snapshot pair x(t+1), y(t+1) into the least-square objective function. We can update the DMD matrix A(t) online by efficient rank-1 updating online DMD algorithm.The time complexity (multiply–add operation for one iteration) is O(n^2),and space complexity is O(n^2), where n is the state dimension.Window DMD algorithm descriptionThe algorithm is implemented in classWindowDMD.At time step t, define two matrixX(t) = [x(t-w+1),x(t-w+2),...,x(t)],Y(t) = [y(t-w+1),y(t-w+2),...,y(t)]that contain the recent w snapshot pairs from a finite time window, where x(t), y(t) are the n dimensional state vector, y(t) = f(t, x(t)) is the image of x(t), f() is the dynamics. Here, if the (discrete-time) dynamics are given by z(t) = f(t, z(t-1)), then x(t), y(t) should be measurements corresponding to consecutive states z(t-1) and z(t).Similarly, we formulate this as a least-square optimization problem.An exponential weighting factor rho=sigma^2 (0<rho<=1) that places more weight on recent data can be incorporated into the definition of X(t) and Y(t) such thatX(t) = [sigma^(w-1)*x(t-w+1),sigma^(w-2)*x(t-w+2),…,sigma^(1)*x(t-1),x(t)],Y(t) = [sigma^(w-1)*y(t-w+1),sigma^(w-2)*y(t-w+2),…,sigma^(1)*y(t-1),y(t)].At time t+1, the data matrices becomeX(t+1) = [x(t-w+2),x(t-w+3),…,x(t+1)],Y(t+1) = [y(t-w+2),y(t-w+3),…,y(t+1)].The models needs to forget the oldest snapshot pair x(t-w+1),y(t-w+1), and remember the newest snapshot pair x(t+1),y(t+1). We can update the DMD matrix A(t) online by efficient rank-2 updating window DMD algroithm.The time complexity (multiply–add operation for one iteration) is O(n^2),and space complexity is O(wn+2n^2), where n is the state dimension, and w is the window size. Typically w is taken to be O(n), e.g, w = 2n, or 10n.DemoSeedemofor python notebooks.demo_online.ipynbshows how to use online DMD to learn adaptive online model for 2D time varying system.demo_window.ipynbshows how to use online DMD to learn adaptive online model for 2D time varying system.Authors:Hao ZhangReferenceIf you you used these algorithms or this python package in your work, please consider citingZhang, Hao, Clarence W. Rowley, Eric A. Deem, and Louis N. Cattafesta. 
"Online dynamic mode decomposition for time-varying systems." 
SIAM Journal on Applied Dynamical Systems 18, no. 3 (2019): 1586-1609.BibTeX@article{zhang2019online,
  title={Online dynamic mode decomposition for time-varying systems},
  author={Zhang, Hao and Rowley, Clarence W and Deem, Eric A and Cattafesta, Louis N},
  journal={SIAM Journal on Applied Dynamical Systems},
  volume={18},
  number={3},
  pages={1586--1609},
  year={2019},
  publisher={SIAM}
}Date createdApril 2017LicenseMITIf you want to use this package, but find license permission an issue, pls contact me athaozhang at alumni dot princeton dot edu.IssuesIf there is any comment/suggestion, or if you find any bug, feel free tocreate an issuehere, orfork this repo, make changes, and create a pull request (merge from your fork to this repo)