direct-data-driven-mpc 1.3.0

Robust and nonlinear Direct Data-Driven MPC controllers for LTI and nonlinear systems in Python

Direct Data-Driven Model Predictive Control (MPC)

Robust Data-Driven MPC	Nonlinear Data-Driven MPC
Robust controller applied to an LTI system.	Nonlinear controller applied to a nonlinear system.

This repository provides a Python implementation of Direct Data-Driven Model Predictive Control (MPC) controllers for Linear Time-Invariant (LTI) and nonlinear systems using CVXPY. It includes robust and nonlinear controllers implemented based on the Data-Driven MPC schemes presented in the papers "Data-Driven Model Predictive Control With Stability and Robustness Guarantees" and "Linear Tracking MPC for Nonlinear Systems—Part II: The Data-Driven Case" by J. Berberich et al.

A direct data-driven controller maps measured input-output data from an unknown system directly onto the controller without requiring an explicit system identification step. This approach is particularly useful in applications where the system dynamics are too complex to be modeled accurately or where traditional system identification methods are impractical or difficult to apply.

📖 View the full project documentation on our documentation page.

---

Disclaimer: This is an independent project based on the referenced papers and does not contain the official implementations from the authors.

---

Table of Contents

• Requirements
• Installation
• Usage
• Paper Reproduction
• Code Structure
  • Direct Data-Driven MPC Controller
  • Model Simulation
  • Controller Creation
  • Data-Driven Controller Simulation
  • Visualization (Static and Animated Plots)
  • Examples
  • Configuration Files
• License
• Citation

Requirements

This package requires the following:

• Python (>=3.10, <3.13). Python 3.13 is not fully supported, as some dependencies have not been compiled for this version yet. We recommend using Python 3.10 to 3.12.
• FFmpeg: Required for saving animations (e.g., GIF or MP4).
  • On Windows: You can download FFmpeg from the official FFmpeg website. Ensure it's correctly added to your system's PATH.
  • On Unix: You can install it using your package manager. For Debian/Ubuntu:

    sudo apt install ffmpeg
    

  Verify the installation by running this command:

  ffmpeg -version
  

Installation

Install direct-data-driven-mpc via PyPI:

pip install direct-data-driven-mpc

Note: We recommend using a virtual environment to install this package, although it is not required.

For Contributors:

If you plan to contribute to or develop the project, follow these steps to set up a local development environment:

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/pavelacamposp/direct-data-driven-mpc.git && cd direct-data-driven-mpc
   

2. Create and activate a virtual environment:
   • Unix/macOS:

     python3 -m venv .venv && source .venv/bin/activate
     

   • Windows:

     python -m venv venv && venv\Scripts\activate
     

3. Install the package with development dependencies:

   pip install -e ".[dev]"
   

This will install tools like pre-commit and mypy. To enable automatic checks before each commit using pre-commit hooks, run:

pre-commit install

Usage

The example scripts lti_dd_mpc_example.py and nonlinear_dd_mpc_example.py demonstrate the setup, simulation, and data visualization of the Data-Driven MPC controllers applied to LTI and nonlinear systems, respectively.

To run the example scripts, use the following commands:

• Data-Driven MPC for LTI systems:

  Run the example script with a seed of 18, a simulation length of 400 steps, a verbosity level of 1, and save the generated animation to a file:

  python examples/lti_control/lti_dd_mpc_example.py --seed 18 --t_sim 400 --verbose 1 --save_anim
  

• Data-Driven MPC for Nonlinear systems:

  Run the example script with a seed of 0, a simulation length of 3000 steps, a verbosity level of 1, and save the generated animation to a file:

  python examples/nonlinear_control/nonlinear_dd_mpc_example.py --seed 0 --t_sim 3000 --verbose 1 --save_anim
  

[!NOTE] The --save_anim flag requires FFmpeg to be installed. See the Requirements section for more details.

Customizing Controller Parameters

To use different controller parameters, modify the configuration files in examples/config/controllers/ for each controller, or specify a custom configuration file using the --controller_config_path argument.

Customizing System Models

Example system parameters are defined in examples/config/models/.

• LTI system: Parameters can be modified directly in four_tank_system_params.yaml.
• Nonlinear system: The system dynamics are defined in nonlinear_cstr_model.py and its parameters in nonlinear_cstr_system_params.yaml.

Customizing Plots

Matplotlib properties for input-output plots can be customized by modifying plot_params.yaml.

Additional Information

Some key arguments used in the scripts are listed below:

Argument	Type	Description
--controller_config_path	str	Path to the YAML file containing Data-Driven MPC controller parameters.
--t_sim	int	Simulation length in time steps.
--save_anim	flag	If passed, saves the generated animation to a file using FFmpeg.
--anim_path	str	Path where the generated animation file will be saved. Includes the file name and its extension (e.g., data-driven_mpc_sim.gif).
--verbose	int	Verbosity level: 0 = no output, 1 = minimal output, 2 = detailed output.

To get the full list of arguments, run each script with the --help flag.

---

For a deeper understanding of the project and how the controllers operate, we recommend reading through the scripts and the docstrings of the implemented utility functions and classes. The documentation includes detailed descriptions of how the implementations follow the Data-Driven MPC controller schemes and algorithms described in the referenced papers.

Paper Reproduction

Reproduction scripts are provided to validate our implementations by comparing them with the results presented in the referenced papers.

• Data-Driven MPC for LTI systems:

  The reproduction is implemented in robust_lti_dd_mpc_reproduction.py. This script closely follows the example presented in Section V of [1], which demonstrates various Robust Data-Driven MPC controller schemes applied to a four-tank system model.

  To run the script, execute the following command:

  python examples/lti_control/robust_lti_dd_mpc_reproduction.py
  

• Data-Driven MPC for Nonlinear systems:

  The reproduction is included in the example script nonlinear_dd_mpc_example.py, which closely follows the example presented in Section V of [2] for the control of a nonlinear continuous stirred tank reactor (CSTR) system.

  To run the script, execute the following command:

  python examples/nonlinear_control/nonlinear_dd_mpc_example.py --seed 0
  

The figures below show the expected output from executing these scripts. The graphs from our results closely resemble those shown in Fig. 2 of [1] and Fig. 2 of [2], with minor differences due to randomization.

LTI Data-Driven MPC	Nonlinear Data-Driven MPC
Reproduction of results from [1]	Reproduction of results from [2]

Code Structure

Direct Data-Driven MPC Controller

The project is structured as a Python package, encapsulating the core logic of the Data-Driven MPC controllers within the following modules:

• direct_data_driven_mpc/lti_data_driven_mpc_controller.py: Implements a Data-Driven MPC controller for LTI systems in the LTIDataDrivenMPCController class. This implementation is based on the Nominal and Robust Data-Driven MPC schemes described in [1].
• direct_data_driven_mpc/nonlinear_data_driven_mpc_controller.py: Implements a Data-Driven MPC controller for nonlinear systems in the NonlinearDataDrivenMPCController class. This implementation is based on the Nonlinear Data-Driven MPC scheme described in [2].

The utility module direct_data_driven_mpc/utilities/hankel_matrix_utils.py is used for constructing Hankel matrices and evaluating whether data sequences are persistently exciting of a given order.

Model Simulation

The following utility modules have been implemented to simulate LTI and nonlinear systems:

• direct_data_driven_mpc/utilities/models/lti_model.py: Implements the LTIModel and LTISystemModel classes for simulating LTI systems.
• direct_data_driven_mpc/utilities/models/nonlinear_model.py: Implements the NonlinearSystem class for simulating nonlinear systems.

Controller Creation

To modularize the creation of Data-Driven MPC controllers, the following utility modules are provided:

• direct_data_driven_mpc/utilities/controller/controller_creation.py: Provides functions for creating Data-Driven MPC controller instances from specified configuration parameters for both LTI and nonlinear controllers.
• direct_data_driven_mpc/utilities/controller/controller_params.py: Provides functions for loading Data-Driven MPC controller parameters from YAML configuration files for both LTI and nonlinear controllers.
• direct_data_driven_mpc/utilities/controller/initial_data_generation.py: Provides functions for generating input-output data from LTI and nonlinear systems, which can be used as initial trajectories in Data-Driven MPC controller creation.

Data-Driven Controller Simulation

The direct_data_driven_mpc/utilities/controller/data_driven_mpc_sim.py module implements the main control loops for both Data-Driven MPC controllers, following Algorithms 1 and 2 of [1] for LTI systems and Algorithm 1 of [2] for nonlinear systems.

Visualization (Static and Animated Plots)

Custom functions are provided in direct_data_driven_mpc/utilities/visualization/ to display input-output data in static and animated plots. These functions use Matplotlib for visualization and FFmpeg for saving animations in various formats (e.g., GIF, MP4).

Examples

The examples directory contains scripts that demonstrate the operation of the Data-Driven MPC controller and reproduce the results presented in the referenced papers.

• examples/lti_control/lti_dd_mpc_example.py: Demonstrates the setup, simulation, and data visualization of a Data-Driven MPC controller applied to an LTI system.
• examples/lti_control/robust_lti_dd_mpc_reproduction.py: Implements a reproduction of the example presented in [1], showing various Robust Data-Driven MPC schemes applied to an LTI system.
• examples/nonlinear_control/nonlinear_dd_mpc_example.py: Demonstrates the setup, simulation, and data visualization of a Data-Driven MPC controller applied to a nonlinear system while closely following the example presented in [2].

Configuration Files

The system and controller parameters used in the example scripts are defined in YAML configuration files in examples/config/. These parameters are based on the examples from Section V of [1] for LTI systems, and from Section V of [2] for nonlinear systems.

• Data-Driven MPC controllers:
  • examples/config/controllers/lti_dd_mpc_example_params.yaml: Defines parameters for a Data-Driven MPC controller designed for LTI systems.
  • examples/config/controllers/nonlinear_dd_mpc_example_params.yaml: Defines parameters for a Data-Driven MPC controller designed for nonlinear systems.
• Models:
  • examples/config/models/four_tank_system_params.yaml: Defines system model parameters for a linearized version of a four-tank system.
  • examples/config/models/nonlinear_cstr_system_params.yaml: Defines system model parameters for a nonlinear continuous stirred tank reactor (CSTR) system.
• Plots:
  • examples/config/plots/plot_params.yaml: Defines Matplotlib properties of lines, legends, and figures for input-output plots.

A YAML loading function is provided in direct_data_driven_mpc/utilities/yaml_config_loading.py.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Citation

If you use these controller implementations in your research, please cite the original papers:

Data-Driven MPC Control for Linear Time-Invariant (LTI) systems

[1] J. Berberich, J. Köhler, M. A. Müller and F. Allgöwer, "Data-Driven Model Predictive Control With Stability and Robustness Guarantees," in IEEE Transactions on Automatic Control, vol. 66, no. 4, pp. 1702-1717, April 2021, doi: 10.1109/TAC.2020.3000182.

BibTex entry:

@ARTICLE{9109670,
  author={Berberich, Julian and Köhler, Johannes and Müller, Matthias A. and Allgöwer, Frank},
  journal={IEEE Transactions on Automatic Control},
  title={Data-Driven Model Predictive Control With Stability and Robustness Guarantees},
  year={2021},
  volume={66},
  number={4},
  pages={1702-1717},
  doi={10.1109/TAC.2020.3000182}}

Data-Driven MPC Control for Nonlinear systems

[2] J. Berberich, J. Köhler, M. A. Müller and F. Allgöwer, "Linear Tracking MPC for Nonlinear Systems—Part II: The Data-Driven Case," in IEEE Transactions on Automatic Control, vol. 67, no. 9, pp. 4406-4421, Sept. 2022, doi: 10.1109/TAC.2022.3166851.

BibTex entry:

@ARTICLE{9756053,
  author={Berberich, Julian and Köhler, Johannes and Müller, Matthias A. and Allgöwer, Frank},
  journal={IEEE Transactions on Automatic Control},
  title={Linear Tracking MPC for Nonlinear Systems—Part II: The Data-Driven Case},
  year={2022},
  volume={67},
  number={9},
  pages={4406-4421},
  doi={10.1109/TAC.2022.3166851}}