direct_data_driven_mpc.utilities.models.lti_model

Classes for modeling Linear Time-Invariant (LTI) systems.

This module provides classes for representing and simulating discrete-time LTI systems using a state-space representation.

Classes

LTIModel	A class representing a Linear Time-Invariant (LTI) system in state-space form.
LTISystemModel	A class for a Linear Time-Invariant (LTI) system in state-space form based on a specified YAML configuration file.

class LTIModel

A class representing a Linear Time-Invariant (LTI) system in state-space form.

The system is defined by its state-space matrices A, B, C, D, and can simulate its behavior and perform tasks such as estimating initial states and calculating equilibrium points.

Attributes:

• A (numpy.ndarray) – The State matrix of the system.

• B (numpy.ndarray) – The Input matrix of the system.

• C (numpy.ndarray) – The Output matrix of the system.

• D (numpy.ndarray) – The Feedforward matrix of the system.

• eps_max (float) – The upper bound of the system measurement noise.

• n (int) – The order of the system (number of states).

• m (int) – The number of inputs to the system.

• p (int) – The number of outputs of the system.

• x (numpy.ndarray) – The internal state vector of the system.

• Ot (numpy.ndarray) – The observability matrix of the system.

• Tt (numpy.ndarray) – The Toeplitz input-output matrix of the system.

__init__(A: ndarray, B: ndarray, C: ndarray, D: ndarray, eps_max: float = 0.0)

Initialize a Linear Time-Invariant (LTI) system with state-space matrices A, B, C, D.

Parameters:

• A (numpy.ndarray) – The State matrix of the system.

• B (numpy.ndarray) – The Input matrix of the system.

• C (numpy.ndarray) – The Output matrix of the system.

• D (numpy.ndarray) – The Feedforward matrix of the system.

• eps_max (float) – The upper bound of the system measurement noise. Defaults to 0.0.

simulate_step(u: ndarray, w: ndarray) → ndarray

Simulate a single time step of the LTI system with a given input u and measurement noise w.

The system simulation follows the state-space equations:

\[ \begin{align}\begin{aligned}x(k+1) = A * x(k) + B * u(k)\\y(k) = C * x(k) + D * u(k) + w(k)\end{aligned}\end{align} \]

Parameters:

• u (numpy.ndarray) – The input vector of shape (m,) at the current time step, where m is the number of inputs.

• w (numpy.ndarray) – The measurement noise vector of shape (p,) at the current time step, where p is the number of outputs.

Returns:

np.ndarray – The output vector y of shape (p,) at the current time step, where p is the number of outputs.

Note

This method updates the x attribute, which represents the internal state vector of the system, after simulation.

simulate(U: ndarray, W: ndarray, steps: int) → ndarray

Simulate the LTI system over multiple time steps.

Parameters:

• U (numpy.ndarray) – An input matrix of shape (steps, m) where steps is the number of time steps and m is the number of inputs.

• W (numpy.ndarray) – A noise matrix of shape (steps, p) where steps is the number of time steps and p is the number of outputs.

• steps (int) – The number of simulation steps.

Returns:

np.ndarray – The output matrix Y of shape (steps, p) containing the simulated system outputs at each time step.

Note

This method updates the x attribute, which represents the internal state vector of the system, after each simulation step.

get_initial_state_from_trajectory(U: ndarray, Y: ndarray) → ndarray

Estimate the initial state of the system corresponding to an input-output trajectory.

This method uses a least squares observer with the Toeplitz input-output and observability matrices of the system to estimate its initial state from the input (U) and output (Y) trajectory.

Parameters:

• U (numpy.ndarray) – An input vector of shape (n, ), where n is the order of the system.

• Y (numpy.ndarray) – An outputs vector of shape (n, ), where n is the order of the system.

Returns:

np.ndarray – A vector of shape (n, ) representing the estimated initial state of the system .

Raises:

ValueError – If U or Y are not shaped (n, ).

get_equilibrium_output_from_input(u_eq: ndarray) → ndarray

Calculate the equilibrium output y_eq corresponding to an input u_eq so they represent an equilibrium pair of the system.

This method calculates the equilibrium output under zero initial conditions using the final value theorem.

Parameters:

u_eq (numpy.ndarray) – A vector of shape (m, 1) representing an input of the system, where m is the number of inputs to the system.

Returns:

np.ndarray – A vector of shape (p, 1) representing the equilibrium output y_eq, where p is the number of outputs of the system.

get_equilibrium_input_from_output(y_eq: ndarray) → ndarray

Calculate the equilibrium input u_eq corresponding to an output y_eq so they represent an equilibrium pair of the system.

This method calculates the equilibrium input under zero initial conditions using the final value theorem.

Parameters:

y_eq (numpy.ndarray) – A vector of shape (p, 1) representing an output of the system, where p is the number of outputs of the system.

Returns:

np.ndarray – A vector of shape (m, 1) representing the equilibrium input u_s, where m is the number of inputs to the system.

set_state(state: ndarray) → None

Set a new state for the system.

Parameters:

state (numpy.ndarray) – A vector of shape (n, ) representing the new system state, where n is the order of the system.

Raises:

ValueError – If state does not match the dimensions of the state vector of the system.

set_eps_max(eps_max: float) → None

Set the upper bound of the system measurement noise.

Parameters:

eps_max (float) – The new value for the upper bound of the system measurement noise.

class LTISystemModel

A class for a Linear Time-Invariant (LTI) system in state-space form based on a specified YAML configuration file.

Attributes:

• A (numpy.ndarray) – System state matrix.

• B (numpy.ndarray) – Input matrix.

• C (numpy.ndarray) – Output matrix.

• D (numpy.ndarray) – Feedforward matrix.

• eps_max (float) – Upper bound of the system measurement noise.

• verbose (int) – The verbosity level: 0 = no output, 1 = minimal output, 2 = detailed output.

Note

This class dynamically loads the model parameters from a YAML configuration file.

__init__(config_file: str, model_key: str, verbose: int = 0)

Initialize a Linear Time-Invariant (LTI) system model by loading parameters from a YAML config file.

Parameters:

• config_file (str) – The path to the YAML configuration file.

• model_key (str) – The key to access the specific model parameters in the config file.

• verbose (int) – The verbosity level: 0 = no output, 1 = minimal output, 2 = detailed output.

Raises:

• FileNotFoundError – If the YAML configuration file is not found.

• ValueError – If model_key or the required matrices (A, B, C, or D) are missing in the configuration file, or if the dimensions of the required matrices are incorrect.