direct_data_driven_mpc.utilities.visualization.control_plot_anim

Functions for generating and saving animated control input-output plots.

This module provides functions for generating and saving animated input-output plots with setpoints using Matplotlib.

The animated plots consist of separate subplots for inputs and outputs, with optional highlighting of the initial measurement period for data-driven control systems. They are highly customizable and can be saved in various formats (e.g., GIF, MP4) using FFMPEG.

Functions

initialize_data_animation(axis, data, ...[, ...])	Initialize plot elements for a data series animation with setpoints.
plot_input_output_animation(u_k, y_k, y_s[, ...])	Create a Matplotlib animation showing the progression of input-output data over time.
save_animation(animation, total_frames, fps, ...)	Save a Matplotlib animation using an ffmpeg writer with progress bar tracking.
update_data_animation(index, data, setpoint, ...)	Update the plot elements in a data series animation with setpoints.

plot_input_output_animation(u_k: ndarray, y_k: ndarray, y_s: ndarray, u_s: ndarray | None = None, u_bounds_list: list[tuple[float, float]] | None = None, y_bounds_list: list[tuple[float, float]] | None = None, inputs_line_params: dict[str, Any] | None = None, outputs_line_params: dict[str, Any] | None = None, setpoints_line_params: dict[str, Any] | None = None, bounds_line_params: dict[str, Any] | None = None, dynamic_setpoint_lines: bool = False, u_setpoint_var_symbol: str = 'u^s', y_setpoint_var_symbol: str = 'y^s', initial_steps: int | None = None, initial_steps_label: str | None = None, continuous_updates: bool = False, initial_excitation_text: str = 'Init. Excitation', initial_measurement_text: str = 'Init. Measurement', control_text: str = 'Data-Driven MPC', display_initial_text: bool = True, display_control_text: bool = True, figsize: tuple[float, float] = (12.0, 8.0), dpi: int = 300, interval: float = 20.0, points_per_frame: int = 1, fontsize: int = 12, legend_params: dict[str, Any] | None = None, title: str | None = None) → FuncAnimation

Create a Matplotlib animation showing the progression of input-output data over time.

This function generates a figure with two rows of subplots: the top subplots display control inputs and the bottom subplots display system outputs. Each subplot shows the data series for each sequence alongside its setpoint. The appearance of plot lines and legends can be customized by passing dictionaries of Matplotlib line and legend properties.

The number of data points shown in each animation frame and the animation speed can be configured via the points_per_frame and interval parameters, respectively. These parameters allow control over the speed at which data is shown in the animation, as well as the total number of animation frames required to display all the data.

If provided, the first ‘initial_steps’ time steps can be highlighted to emphasize the initial input-output data measurement period representing the data-driven system characterization phase in a Data-Driven MPC algorithm. Additionally, custom labels can be displayed to indicate the initial measurement and the subsequent MPC control periods, but only if there is enough space to prevent them from overlapping with other plot elements.

Parameters:

• u_k (numpy.ndarray) – An array containing control input data of shape (T, m), where m is the number of inputs and T is the number of time steps.

• y_k (numpy.ndarray) – An array containing system output data of shape (T, p), where p is the number of outputs and T is the number of time steps.

• y_s (numpy.ndarray) – An array containing output setpoint values of shape (T, p), where p is the number of outputs and T is the number of time steps.

• u_s (np.ndarray | None) – An array containing input setpoint values of shape (T, m), where m is the number of inputs and T is the number of time steps. If None, input setpoint lines will not be plotted. Defaults to None.

• u_bounds_list (list[tuple[float, float]] | None) – A list of tuples (lower_bound, upper_bound) specifying bounds for each input data sequence. If provided, horizontal lines representing these bounds will be plotted in each subplot. If None, no horizontal lines will be plotted. The number of tuples must match the number of input data sequences. Defaults to None.

• y_bounds_list (list[tuple[float, float]] | None) – A list of tuples (lower_bound, upper_bound) specifying bounds for each output data sequence. If provided, horizontal lines representing these bounds will be plotted in each subplot. If None, no horizontal lines will be plotted. The number of tuples must match the number of output data sequences. Defaults to None.

• inputs_line_params (dict[str, Any] | None) – A dictionary of Matplotlib properties for customizing the lines used to plot the input data series (e.g., color, linestyle, linewidth). If not provided, Matplotlib’s default line properties will be used.

• outputs_line_params (dict[str, Any] | None) – A dictionary of Matplotlib properties for customizing the lines used to plot the output data series (e.g., color, linestyle, linewidth). If not provided, Matplotlib’s default line properties will be used.

• setpoints_line_params (dict[str, Any] | None) – A dictionary of Matplotlib properties for customizing the lines used to plot the setpoint values (e.g., color, linestyle, linewidth). If not provided, Matplotlib’s default line properties will be used.

• bounds_line_params (dict[str, Any] | None) – A dictionary of Matplotlib properties for customizing the lines used to plot the bounds of input-output data series (e.g., color, linestyle, linewidth). If not provided, Matplotlib’s default line properties will be used.

• dynamic_setpoint_lines (bool) – Whether to update setpoint lines dynamically. If False, they will be fully plotted at the start using all setpoint data.

• u_setpoint_var_symbol (str) – The variable symbol used to label the input setpoint data series (e.g., “u^s”).

• y_setpoint_var_symbol (str) – The variable symbol used to label the output setpoint data series (e.g., “y^s”).

• initial_steps (int | None) – The number of initial time steps during which input-output measurements were taken for the data-driven characterization of the system. This highlights the initial measurement period in the plot. If None, no special highlighting will be applied. Defaults to None.

• initial_steps_label (str | None) – Label text to use for the legend entry representing the initial input-output measurement highlight in the plot. If None, this element will not appear in the legend. Defaults to None.

• continuous_updates (bool) – Whether the initial measurement period highlight should move with the latest data to represent continuous input-output measurement updates. Defaults to False.

• initial_excitation_text (str) – Label text to display over the initial excitation period of the input plots. Default is “Init. Excitation”.

• initial_measurement_text (str) – Label text to display over the initial measurement period of the output plots. Default is “Init. Measurement”.

• control_text (str) – Label text to display over the post-initial control period. Default is “Data-Driven MPC”.

• display_initial_text (bool) – Whether to display the initial_text label on the plot. Default is True.

• display_control_text (bool) – Whether to display the control_text label on the plot. Default is True.

• figsize (tuple[float, float]) – The (width, height) dimensions of the created Matplotlib figure.

• dpi (int) – The DPI resolution of the figure.

• interval (float) – The time between frames in milliseconds. Defaults to 20 ms.

• points_per_frame (int) – The number of data points shown per animation frame. Increasing this value reduces the number of frames required to display all the data, resulting in faster data transitions. Defaults to 1.

• fontsize (int) – The fontsize for labels and axes ticks.

• legend_params (dict[str, Any] | None) – A dictionary of Matplotlib properties for customizing the plot legend (e.g., fontsize, loc, handlelength). If not provided, Matplotlib’s default legend properties will be used.

• title (str | None) – The title for the created plot figure. If None, no title will be displayed. Defaults to None.

Returns:

FuncAnimation – A Matplotlib FuncAnimation object that animates the progression of input-output data over time.

Raises:

ValueError – If any array dimensions mismatch expected shapes, or if the lengths of u_bounds_list or y_bounds_list do not match the number of subplots.

initialize_data_animation(axis: Axes, data: ndarray, setpoint: ndarray | None, index: int, data_line_params: dict[str, Any], setpoint_line_params: dict[str, Any], bounds_line_params: dict[str, Any], dynamic_setpoint_lines: bool, var_symbol: str, setpoint_var_symbol: str, var_label: str, initial_text: str, control_text: str, fontsize: int, legend_params: dict[str, Any], data_lines: list[Line2D], setpoint_lines: list[Line2D], rects: list[Rectangle], right_rect_lines: list[Line2D], left_rect_lines: list[Line2D], init_texts: list[Text], control_texts: list[Text], y_axis_centers: list[float], bounds: tuple[float, float] | None = None, initial_steps: int | None = None, initial_steps_label: str | None = None, continuous_updates: bool = False, legend_loc: str = 'best') → None

Initialize plot elements for a data series animation with setpoints.

This function initializes and appends several elements to the plot, such as plot lines representing data, rectangles and lines representing an initial input-output data measurement period, and text labels for both the initial measurement and control periods. It also adjusts the axis limits and stores the y-axis center values. The appearance of plot lines and legends can be customized by passing dictionaries of Matplotlib line and legend properties.

Parameters:

• axis (Axes) – The Matplotlib axis object to plot on.

• data (numpy.ndarray) – An array containing data to be plotted.

• setpoint (np.ndarray | None) – An array containing setpoint values to be plotted. If None, the setpoint line will not be plotted.

• index (int) – The index of the data used for labeling purposes (e.g., “u_1”, “u_2”). If set to -1, subscripts will not be added to labels.

• data_line_params (dict[str, Any]) – A dictionary of Matplotlib properties for customizing the line used to plot the data series (e.g., color, linestyle, linewidth).

• setpoint_line_params (dict[str, Any]) – A dictionary of Matplotlib properties for customizing the line used to plot the setpoint value (e.g., color, linestyle, linewidth).

• bounds_line_params (dict[str, Any]) – A dictionary of Matplotlib properties for customizing the lines used to plot the bounds of the data series (e.g., color, linestyle, linewidth).

• dynamic_setpoint_lines (bool) – Whether to update setpoint lines dynamically. If False, they will be fully plotted at the start using all setpoint data.

• var_symbol (str) – The variable symbol used to label the data series (e.g., “u” for inputs, “y” for outputs).

• setpoint_var_symbol (str) – The variable symbol used to label the setpoint data series (e.g., “u^s” for inputs, “y^s” for outputs).

• var_label (str) – The variable label representing the control signal (e.g., “Input”, “Output”).

• initial_text (str) – Label text to display over the initial measurement period of the plot.

• control_text (str) – Label text to display over the post-initial control period.

• fontsize (int) – The fontsize for labels and axes ticks.

• legend_params (dict[str, Any]) – A dictionary of Matplotlib properties for customizing the plot legend (e.g., fontsize, loc, handlelength). If the ‘loc’ key is present in the dictionary, it overrides the legend_loc value.

• data_lines (list[Line2D]) – The list where the initialized data plot lines will be stored.

• setpoint_lines (list[Line2D]) – The list where the initialized setpoint plot lines will be stored.

• rects (list[Rectangle]) – The list where the initialized rectangles representing the initial measurement region will be stored.

• right_rect_lines (list[Line2D]) – The list where the initialized vertical lines representing the upper boundary of the initial measurement region will be stored.

• left_rect_lines (list[Line2D]) – The list where the initialized vertical lines representing the lower boundary of the initial measurement region will be stored.

• init_texts (list[Text]) – The list where the initialized initial measurement label texts will be stored.

• control_texts (list[Text]) – The list where the initialized control label texts will be stored.

• y_axis_centers (list[float]) – The list where the y-axis center from the adjusted axis will be stored.

• bounds (tuple[float, float] | None) – A tuple (lower_bound, upper_bound) specifying the bounds of the data to be plotted. If provided, horizontal lines representing these bounds will be plotted. Defaults to None.

• initial_steps (int | None) – The number of initial time steps during which input-output measurements were taken for the data-driven characterization of the system. This highlights the initial measurement period in the plot. If None, no special highlighting will be applied. Defaults to None.

• initial_steps_label (str | None) – Label text to use for the legend entry representing the initial input-output measurement highlight in the plot. If None, this element will not appear in the legend. Defaults to None.

• continuous_updates (bool) – Whether the initial measurement period highlight should move with the latest data to represent continuous input-output measurement updates. Defaults to False.

• legend_loc (str) – The location of the legend on the plot. Corresponds to Matplotlib’s loc parameter for legends. Defaults to ‘best’.

Note

This function updates the lines, rects, right_rect_lines, left_rect_lines init_texts, and control_texts with the initialized plot elements. It also adjusts the y-axis limits to a fixed range and stores the center values in y_axis_centers.

update_data_animation(index: int, data: ndarray, setpoint: ndarray | None, data_length: int, points_per_frame: int, initial_steps: int | None, continuous_updates: bool, data_line: Line2D, setpoint_line: Line2D | None, rect: Rectangle | None, y_axis_center: float, right_rect_line: Line2D | None, left_rect_line: Line2D | None, init_text_obj: Text | None, control_text_obj: Text | None, display_initial_text: bool, display_control_text: bool, init_text_width: float, control_text_width: float) → None

Update the plot elements in a data series animation with setpoints.

This function updates data plot elements based on the current data index. If ‘initial_steps’ is provided, it also updates the rectangle and line representing the initial input-output measurement period, as well as the text labels indicating the initial measurement and control periods. These labels will be displayed if there is enough space to prevent them from overlapping with other plot elements.

Parameters:

• index (int) – The current data index.

• data (numpy.ndarray) – An array containing data to be plotted.

• setpoint (np.ndarray | None) – An array containing setpoint values to be plotted. If None, the setpoint line will not be plotted.

• data_length (int) – The length of the data array.

• points_per_frame (int) – The number of data points shown per animation frame.

• initial_steps (int| None) – The number of initial time steps during which input-output measurements were taken for the data-driven characterization of the system. This highlights the initial measurement period in the plot.

• continuous_updates (bool) – Whether the initial measurement period highlight should move with the latest data to represent continuous input-output measurement updates.

• data_line (Line2D) – The plot line corresponding to the data series plot.

• setpoint_line (Line2D | None) – The plot line corresponding to the setpoint series plot. If None, the setpoint line will not be plotted.

• rect (Rectangle | None) – The rectangle representing the initial measurement region.

• y_axis_center (float) – The y-axis center of the plot axis.

• right_rect_line (Line2D | None) – The line object representing the upper boundary of the initial measurement region.

• left_rect_line (Line2D | None]) – The line object representing the lower boundary of the initial measurement region.

• init_text_obj (Text | None) – The text object containing the initial measurement period label.

• control_text_obj (Text | None) – The text object containing the control period label.

• display_initial_text (bool) – Whether to display the initial_text label on the plot.

• display_control_text (bool) – Whether to display the control_text label on the plot.

• init_text_width (float) – The width of the init_text_obj object in data coordinates.

• control_text_width (float) – The width of the control_text_obj object in data coordinates.

save_animation(animation: FuncAnimation, total_frames: int, fps: int, bitrate: int, file_path: str) → None

Save a Matplotlib animation using an ffmpeg writer with progress bar tracking.

This function saves the given Matplotlib animation to the specified file path and displays a progress bar the console to track the saving progress. If the file path contains directories that do not exist, they will be created.

Parameters:

• animation (FuncAnimation) – The animation object to save.

• total_frames (int) – The total number of frames in the animation.

• fps (int) – The frames per second of saved video.

• bitrate (int) – The bitrate of saved video.

• file_path (str) – The path (including directory and file name) where the animation will be saved.