L4acados: Learning-based models for acados

Paper: https://arxiv.org/abs/2411.19258

Integrate learning-based Python models into acados for real-time model predictive control.

Usage

1. Define your AcadosOcp, including the nominal dynamics model

   from acados_template import AcadosOcp
   ocp = AcadosOcp()
   # ...

2. Define the residual model using the L4acados ResidualModel (here as a PyTorchResidualModel example):

   import l4acados as l4a
   residual_model = l4a.PyTorchResidualModel(your_pytorch_model)

   Other models can be straightforwardly implemented using as a ResidualModel instance; see here for already available residual models.

3. Generate the L4acados solver object

   l4acados_solver = l4a.ResidualLearningMPC(
       ocp=ocp,
       residual_model=residual_model,
       use_cython=True, # accelerate get/set operations by using the acados Cython interface
   )

4. Done! The ResidualLearningMPC object can be interfaced like the AcadosOcpSolver:

   • l4acados_solver.set(...)
   • l4acados_solver.solve()
   • l4acados_solver.get(...)

   Not all solver interface functions are mapped by the ResidualLearningMPC. You can still access the underlying AcadosOcpSolver object through the l4acados_solver.ocp_solver property. Besides the dynamics model and parameter definition, the l4acados_solver.ocp_solver is equivalent to the acados_solver.ocp_solver generated from the original ocp.

Installation

Install acados

1. Clone

   git submodule update --recursive --init external/acados

2. Build the submodule acados according to the installation instructions:

   mkdir -p external/acados/build
   cd external/acados/build
   cmake -DACADOS_PYTHON=ON .. # do not forget the ".."
   make install -j4

   You can also install acados separately; in this case, refer to the acados version of the submodule in case you encounter errors with a newer version of acados.

3. Install acados Python interface

   pip install -e external/acados/interfaces/acados_template

4. Set environment variables (where $PROJECT_DIR is the directory you cloned the repository into in Step 1):

   export ACADOS_SOURCE_DIR=$PROJECT_DIR/external/acados
   export LD_LIBRARY_PATH=$ACADOS_SOURCE_DIR/lib

Install L4acados with optional dependencies of your choice

Install L4acados with optional dependencies of your choice

pip install -e .[<optional-dependencies>]

Available options:

• (without optional dependencies): Basic ResidualLearningMPC for custom implementations (e.g. Jacobian approximations, finite-difference approximations for e.g. models without sensitivity information)
• [pytorch]: PyTorch models.
• [gpytorch]: GPyTorch models.
• [gpytorch-exo]: GpyTorch models with online-learning improvements.
• not supported yet: JAX, TensorFlow

Contributing

If you would like to contribute features to L4acados, please follow the development installation instructions below to set up your working environment.

Development installation

1. Install L4acados with development dependencies (in addition to the used learning framework, see above):

   pip install -e .[dev]

2. Sync notebooks with jupytext:

   jupytext --set-formats ipynb,py examples/*/*.ipynb

3. Add pre-commit hooks

   pre-commit install

Citing us

If you use this software, please cite our corresponding articles as written below.

General software

@online{lahr_l4acados_2024,
  title = {L4acados: {{Learning-based}} Models for Acados, Applied to {{Gaussian}} Process-Based Predictive Control},
  shorttitle = {L4acados},
  author = {Lahr, Amon and Näf, Joshua and Wabersich, Kim P. and Frey, Jonathan and Siehl, Pascal and Carron, Andrea and Diehl, Moritz and Zeilinger, Melanie N.},
  date = {2024-11-28},
  eprint = {2411.19258},
  eprinttype = {arXiv},
  doi = {10.48550/arXiv.2411.19258},
  pubstate = {prepublished}
}

Zero-Order GP-MPC algorithm

@article{lahr_zero-order_2023,
  title = {Zero-Order optimization for {{Gaussian}} process-based model predictive control},
  author = {Lahr, Amon and Zanelli, Andrea and Carron, Andrea and Zeilinger, Melanie N.},
  year = {2023},
  journal = {European Journal of Control},
  pages = {100862},
  issn = {0947-3580},
  doi = {10.1016/j.ejcon.2023.100862}
}