Skip to content

qttools.boundary_conditions.lyapunov#

source package qttools.boundary_conditions.lyapunov

Classes

  • Doubling — A solver for the Lyapunov equation using iterative doubling.

  • Spectral — A solver for the Lyapunov equation by using the matrix spectrum.

  • LyapunovSystem — A lyapunov system solver with memoization and system reduction.

  • LyapunovSolver — Solver interface for the discrete-time Lyapunov equation.

  • LyapunovSystemReducer — A lyapunov system reducer.

source class Doubling(max_iterations: int = 10, convergence_rel_tol: float = 1e-05, convergence_abs_tol: float = 1e-08)

Bases : LyapunovSolver

A solver for the Lyapunov equation using iterative doubling.

Initializes the solver.

Parameters

  • max_iterations : int, optional — The maximum number of iterations to perform.

  • convergence_rel_tol : float, optional — The required relative accuracy for convergence.

  • convergence_abs_tol : float, optional — The required absolute accuracy for convergence. Either convergence_rel_tol or convergence_abs_tol must be satisfied.

source class Spectral(num_ref_iterations: int = 2, eig_compute_location: str = 'numpy', use_pinned_memory: bool = True)

Bases : LyapunovSolver

A solver for the Lyapunov equation by using the matrix spectrum.

Initializes the spectral Lyapunov solver.

Parameters

  • num_ref_iterations : int, optional — The number of refinement iterations to perform.

  • eig_compute_location : str, optional — The location where to compute the eigenvalues and eigenvectors. Can be either "numpy" or "cupy" or "nvmath".

  • use_pinned_memory : bool, optional — Whether to use pinnend memory if cupy is used. Default is True.

source class LyapunovSystem(boundary_solver: LyapunovSolver, cache_compressor: None = None, system_reducer: SystemReducer | None = None, num_ref_iterations: int = 2, relative_tol: float = 0.2, absolute_tol: float = 1e-06, warning_threshold: float = 0.1, memoization_mode: str = 'auto', agreement_threshold: float = 0.999)

Bases : BaseBoundarySystem

A lyapunov system solver with memoization and system reduction.

The lyapyunov equation to be solved is given by:

$$\mathbf{x} = \mathbf{q} + \mathbf{a} \mathbf{x}  \mathbf{a}^H$$

Initializes the lyapunov system.

Parameters

  • boundary_solver : LyapunovSolver — The lyapunov solver to be memoized.

  • cache_compressor : object, optional — An object with 'compress' and 'decompress' methods to handle cache compression. If None, no compression is applied.

  • num_ref_iterations : int, optional — The number of fixed-point iterations to refine the solution. Default is 2.

  • relative_tol : float, optional — The relative tolerance for convergence. Default is 0.2.

  • absolute_tol : float, optional — The absolute tolerance for convergence. Default is 1e-6.

  • warning_threshold : float, optional — The threshold for issuing a warning about high residuals. Default is 0.1.

  • memoization_mode : str, optional — The memoization mode. Can be 'off', 'auto', 'force-after-first', or 'force'. Default is 'auto'.

  • agreement_threshold : float, optional — The threshold for agreement across MPI ranks to consider a memoized solution valid. Default is 0.999.

  • reduce_sparsity : bool, optional — Whether to reduce the sparsity of the system matrix. If sparsity of any obc is changed during runtime, then the cache needs to be invalidated. Default is True.

  • assume_constant_sparsity : bool, optional — Whether to assume that the sparsity pattern of the system matrix remains constant during runtime. If True, the sparsity pattern is only computed once. Default is True.

source class LyapunovSolver()

Bases : ABC

Solver interface for the discrete-time Lyapunov equation.

The discrete-time Lyapunov equation is defined as:

\[ X - A X A^H = Q \]

source class LyapunovSystemReducer(reduce_sparsity: bool = True, assume_constant_sparsity: bool = True)

Bases : SystemReducer

A lyapunov system reducer.

The lyapunov system can exhibit sparsity, which can be exploited to reduce the size of the system. Either zero rows or zero cols in the system matrix can be reduced, depending on which is more prevalent. Utilizing both would be possible but is not implemented yet, as it would require more complex bookkeeping of the reduced system. In addition, such systems do currently not occure in quatrex.

Initializes the lyapunov system.

Parameters

  • reduce_sparsity : bool, optional — Whether to reduce the sparsity of the system matrix. If sparsity of any obc is changed during runtime, then the cache needs to be invalidated. Default is True.

  • assume_constant_sparsity : bool, optional — Whether to assume that the sparsity pattern of the system matrix remains constant during runtime. If True, the sparsity pattern is only computed once. Default is True.

Methods

  • contract_system — Contract the boundary system to a reduced system. Both zero rows and zero cols can be reduced, but only the one with more zero rows/cols is reduced.

  • expand_solution — Expand the solution from the reduced system to the full system.

  • expand_residuals — Expand the residuals from the reduced system to the full system.

source method LyapunovSystemReducer.contract_system(boundary_system: tuple[NDArray, ...]) → tuple[NDArray, ...]

Contract the boundary system to a reduced system. Both zero rows and zero cols can be reduced, but only the one with more zero rows/cols is reduced.

Parameters

  • boundary_system : tuple[NDArray, ...] — The full boundary system to solve. It is expected to be a tuple (a, q) where 'a' is the system matrix and 'q' is the right-hand side matrix.

Returns

  • reduced_system : tuple[NDArray, ...] — The reduced boundary system.

Raises

  • ValueError

source method LyapunovSystemReducer.expand_solution(boundary_system: tuple[NDArray, ...], reduced_system: tuple[NDArray, ...], reduced_solution: NDArray) → NDArray

Expand the solution from the reduced system to the full system.

Parameters

  • boundary_system : tuple[NDArray, ...] — The full boundary system to solve. It is expected to be a tuple (a, q) where 'a' is the system matrix and 'q' is the right-hand side matrix.

  • reduced_system : tuple[NDArray, ...] — The reduced boundary system to solve. It is expected to be a tuple (a, q) where 'a' is the reduced system matrix and 'q' is the reduced right-hand side matrix.

  • reduced_solution : NDArray — The solution of the reduced system.

Returns

  • full_solution : NDArray — The solution of the full system.

Raises

  • ValueError

source method LyapunovSystemReducer.expand_residuals(boundary_system: tuple[NDArray, ...], reduced_system: tuple[NDArray, ...], rel_residuals: NDArray, abs_residuals: NDArray) → tuple[NDArray, NDArray]

Expand the residuals from the reduced system to the full system.

The reduced lyapynov system has the same residuals as the full system.

Parameters

  • boundary_system : tuple[NDArray, ...] — The full boundary system to solve. It is expected to be a tuple (a, q) where 'a' is the system matrix and 'q' is the right-hand side matrix.

  • reduced_system : tuple[NDArray, ...] — The reduced boundary system to solve. It is expected to be a tuple (a, q) where 'a' is the reduced system matrix and 'q' is the reduced right-hand side matrix.

  • rel_residuals : NDArray — The relative residuals of the reduced system.

  • abs_residuals : NDArray — The absolute residuals of the reduced system.

Returns

  • full_rel_residuals : NDArray — The relative residuals of the full system.

  • full_abs_residuals : NDArray — The absolute residuals of the full system.