:mod:`heat.decomposition.dmd` ============================= .. py:module:: heat.decomposition.dmd .. autoapi-nested-parse:: Module implementing the Dynamic Mode Decomposition (DMD) algorithm. Module Contents --------------- .. function:: _torch_matrix_diag(diagonal) .. py:class:: DMD(svd_solver: Optional[str] = 'full', svd_rank: Optional[int] = None, svd_tol: Optional[float] = None) Bases: :class:`heat.RegressionMixin`, :class:`heat.BaseEstimator` Dynamic Mode Decomposition (DMD), plain vanilla version with SVD-based implementation. The time series of which DMD shall be computed must be provided as a 2-D DNDarray of shape (n_features, n_timesteps). Please, note that this deviates from Heat's convention that data sets are handeled as 2-D arrays with the feature axis being the second axis. :param svd_solver: Specifies the algorithm to use for the singular value decomposition (SVD). Options are 'full' (default), 'hierarchical', and 'randomized'. :type svd_solver: str, optional :param svd_rank: The rank to which SVD shall be truncated. For `'full'` SVD, `svd_rank = None` together with `svd_tol = None` (default) will result in no truncation. For `svd_solver='full'`, at most one of `svd_rank` or `svd_tol` may be specified. For `svd_solver='hierarchical'`, either `svd_rank` (rank to truncate to) or `svd_tol` (tolerance to truncate to) must be specified. For `svd_solver='randomized'`, `svd_rank` must be specified and determines the the rank to truncate to. :type svd_rank: int, optional :param svd_tol: The tolerance to which SVD shall be truncated. For `'full'` SVD, `svd_tol = None` together with `svd_rank = None` (default) will result in no truncation. For `svd_solver='hierarchical'`, either `svd_tol` (accuracy to truncate to) or `svd_rank` (rank to truncate to) must be specified. For `svd_solver='randomized'`, `svd_tol` is meaningless and must be None. :type svd_tol: float, optional :ivar svd_solver: The algorithm used for the singular value decomposition (SVD). :vartype svd_solver: str :ivar svd_rank: The rank to which SVD shall be truncated. :vartype svd_rank: int :ivar svd_tol: The tolerance to which SVD shall be truncated. :vartype svd_tol: float :ivar rom_basis_: The reduced order model basis. :vartype rom_basis_: DNDarray :ivar rom_transfer_matrix_: The reduced order model transfer matrix. :vartype rom_transfer_matrix_: DNDarray :ivar rom_eigenvalues_: The reduced order model eigenvalues. :vartype rom_eigenvalues_: DNDarray :ivar rom_eigenmodes_: The reduced order model eigenmodes ("DMD modes") :vartype rom_eigenmodes_: DNDarray .. rubric:: Notes We follow the "exact DMD" method as described in [1], Sect. 2.2. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. rubric:: References [1] J. L. Proctor, S. L. Brunton, and J. N. Kutz, "Dynamic Mode Decomposition with Control," SIAM Journal on Applied Dynamical Systems, vol. 15, no. 1, pp. 142-161, 2016. .. attribute:: svd_solver :annotation: = 'full' .. attribute:: svd_rank :annotation: = None .. attribute:: svd_tol :annotation: = None .. attribute:: rom_basis_ :annotation: = None .. attribute:: rom_transfer_matrix_ :annotation: = None .. attribute:: rom_eigenvalues_ :annotation: = None .. attribute:: rom_eigenmodes_ :annotation: = None .. attribute:: dmdmodes_ :annotation: = None .. attribute:: n_modes_ :annotation: = None .. role:: raw-html(raw) :format: html .. method:: fit(X: heat.DNDarray) -> Self Fits the DMD model to the given data. :param X: The time series data to fit the DMD model to. Must be of shape (n_features, n_timesteps). :type X: DNDarray .. method:: predict_next(X: heat.DNDarray, n_steps: int = 1) -> heat.DNDarray Predicts and returns the state(s) after n_steps-many time steps for given a current state(s). :param X: The current state(s) for the prediction. Must have the same number of features as the training data, but can be batched for multiple current states, i.e., X can be of shape (n_features,) or (n_features, n_current_states). The output will have the same shape as the input. :type X: DNDarray :param n_steps: The number of steps to predict into the future. Default is 1, i.e., the next time step is predicted. :type n_steps: int, optional .. method:: predict(X: heat.DNDarray, steps: Union[int, List[int]]) -> heat.DNDarray Predics and returns future states given a current state(s) and returns them all as an array of size (n_steps, n_features). This function avoids a time-stepping loop (i.e., repeated calls to 'predict_next') and computes the future states in one go. To do so, the number of future times to predict must be of moderate size as an array of shape (n_steps, self.n_modes_, self.n_modes_) must fit into memory. Moreover, it must be ensured that: - the array of initial states is not split or split along the batch axis (axis 1) and the feature axis is small (i.e., self.rom_basis_ is not split) :param X: The current state(s) for the prediction. Must have the same number of features as the training data, but can be batched for multiple current states, i.e., X can be of shape (n_features,) or (n_current_states, n_features). :type X: DNDarray :param steps: if int: predictions at time step 0, 1, ..., steps-1 are computed if List[int]: predictions at time steps given in the list are computed :type steps: int or List[int] .. method:: __str__() .. py:class:: DMDc(svd_solver: Optional[str] = 'full', svd_rank: Optional[int] = None, svd_tol: Optional[float] = None) Bases: :class:`heat.RegressionMixin`, :class:`heat.BaseEstimator` Dynamic Mode Decomposition with Control (DMDc), plain vanilla version with SVD-based implementation. The time series of states and controls must be provided as 2-D DNDarrays of shapes (n_state_features, n_timesteps) and (n_control_features, n_timesteps), respectively. Please, note that this deviates from Heat's convention that data sets are handeled as 2-D arrays with the feature axis being the second axis. :param svd_solver: Specifies the algorithm to use for the singular value decomposition (SVD). Options are 'full' (default), 'hierarchical', and 'randomized'. :type svd_solver: str, optional :param svd_rank: The rank to which SVD of the states shall be truncated. For `'full'` SVD, `svd_rank = None` together with `svd_tol = None` (default) will result in no truncation. For `svd_solver='full'`, at most one of `svd_rank` or `svd_tol` may be specified. For `svd_solver='hierarchical'`, either `svd_rank` (rank to truncate to) or `svd_tol` (tolerance to truncate to) must be specified. For `svd_solver='randomized'`, `svd_rank` must be specified and determines the the rank to truncate to. :type svd_rank: int, optional :param svd_tol: The tolerance to which SVD of the states shall be truncated. For `'full'` SVD, `svd_tol = None` together with `svd_rank = None` (default) will result in no truncation. For `svd_solver='hierarchical'`, either `svd_tol` (accuracy to truncate to) or `svd_rank` (rank to truncate to) must be specified. For `svd_solver='randomized'`, `svd_tol` is meaningless and must be None. :type svd_tol: float, optional :ivar svd_solver: The algorithm used for the singular value decomposition (SVD). :vartype svd_solver: str :ivar svd_rank: The rank to which SVD shall be truncated. :vartype svd_rank: int :ivar svd_tol: The tolerance to which SVD shall be truncated. :vartype svd_tol: float :ivar rom_basis_: The reduced order model basis. :vartype rom_basis_: DNDarray :ivar rom_transfer_matrix_: The reduced order model transfer matrix. :vartype rom_transfer_matrix_: DNDarray :ivar rom_control_matrix_: The reduced order model control matrix. :vartype rom_control_matrix_: DNDarray :ivar rom_eigenvalues_: The reduced order model eigenvalues. :vartype rom_eigenvalues_: DNDarray :ivar rom_eigenmodes_: The reduced order model eigenmodes ("DMD modes") :vartype rom_eigenmodes_: DNDarray .. rubric:: Notes We follow the approach described in [1], Sects. 3.3 and 3.4. In the case that svd_rank is prescribed, the rank of the SVD of the full system matrix is set to svd_rank + n_control_features; cf. https://github.com/dynamicslab/pykoopman for the same approach. Please note that "rank" in the context of SVD always refers to the number of singular values/vectors to compute (i.e., "rank" refers to the mathematical rank of a matrix). This is completely different from the notion of "(MPI-)rank", i.e., the ID given to a process, in a parallel MPI-application. .. rubric:: References [1] J. L. Proctor, S. L. Brunton, and J. N. Kutz, "Dynamic Mode Decomposition with Control," SIAM Journal on Applied Dynamical Systems, vol. 15, no. 1, pp. 142-161, 2016. .. attribute:: svd_solver :annotation: = 'full' .. attribute:: svd_rank :annotation: = None .. attribute:: svd_tol :annotation: = None .. attribute:: rom_basis_ :annotation: = None .. attribute:: rom_transfer_matrix_ :annotation: = None .. attribute:: rom_control_matrix_ :annotation: = None .. attribute:: rom_eigenvalues_ :annotation: = None .. attribute:: rom_eigenmodes_ :annotation: = None .. attribute:: dmdmodes_ :annotation: = None .. attribute:: n_modes_ :annotation: = None .. attribute:: n_modes_system_ :annotation: = None .. role:: raw-html(raw) :format: html .. method:: fit(X: heat.DNDarray, C: heat.DNDarray) -> Self Fits the DMD model to the given data. :param X: The time series data of states to fit the DMD model to. Must be of shape (n_state_features, n_timesteps). :type X: DNDarray :param C: The time series of control inputs to fit the DMD model to. Must be of shape (n_control_features, n_timesteps). :type C: DNDarray .. method:: predict(X: heat.DNDarray, C: heat.DNDarray) -> heat.DNDarray Predicts and returns future states given the current state(s) ``X`` and control trajectory ``C``. :param X: The current state(s) for the prediction. Must have the same number of features as the training data, but can be batched for multiple current states, i.e., X can be of shape (n_state_features,) or (n_batch, n_state_features). :type X: DNDarray :param C: The control trajectory for the prediction. Must have the same number of control features as the training data, i.e., C must be of shape (n_control_features,) --for a single time step-- or (n_control_features, n_timesteps). :type C: DNDarray .. method:: __str__()