l4casadi

Real-time L4CasADi is a framework designed to enable Real-time Neural-MPC (Model Predictive Control). It provides a template to approximate a PyTorch model within CasADi using first-order or second-order Taylor Approximations.

Key features include:

• Taylor Approximations: Approximates PyTorch models as first- or second-order Taylor expansions for use in optimization.
• Efficient Updates: Users update the approximation via a Python interface. The parameters required for these updates can be computed in parallel in PyTorch, potentially on a GPU.
• Scalability: This approach is efficient for large models where multiple approximations are required in parallel, such as in MPC with multiple shooting nodes.

L4CasADi provides NaiveL4CasADiModule for very small, simple models (e.g., Multi-Layer Perceptrons). This module recreates the PyTorch graph using pure CasADi operations, avoiding the overhead of context switches to Torch.

Recommendation:

• Use NaiveL4CasADiModule for networks smaller than three hidden layers with 64 neurons each.
• Use standard L4CasADi for larger models where the Torch overhead becomes negligible.

L4CasADi supports multi-input multi-output functions by using the following pattern:

1. Concatenate symbolic inputs when passing them to the model.
2. Split the inputs inside the PyTorch function to match the required shapes.

L4CasADi v2 introduced several changes focused on efficiency and simplicity:

• Batching Support: When passing batched=True, L4CasADi treats the first input dimension as the batch dimension. First and second-order derivatives across this dimension are assumed to be sparse-zero. To maximize performance (5-10x speedup), batch all inputs together into a single L4CasADi call instead of making multiple calls.
• Input Shapes: L4CasADi no longer changes the shape of inputs. The tensor forwarded to the PyTorch model will have the exact dimension of the CasADi input variable. You must ensure your PyTorch model handles a two-dimensional input matrix. The model_expects_batch_dim parameter has been removed.
• Hessian Generation: By default, L4CasADi provides the Jacobian of the Adjoint. To explicitly request the Hessian, pass generate_jac_jac=True.

Real-time L4CasADi can be integrated into Acados (RTI-)MPC workflows. A reference implementation is provided in the mpc_mlp_example.py example, which demonstrates how to use a learned residual dynamic within an Acados MPC setup. While the provided example uses a single integrator with a learned residual set to zero, it serves as a template for full integration.

# See the integration example at:
# ../../examples/realtime/mpc_mlp_example.py

To install the CPU-only version via pip, ensure you have the CPU version of Torch installed and the necessary build dependencies. You must use the --no-build-isolation flag so L4CasADi can link against your installed PyTorch.

# 1. Install Torch CPU version
pip install torch>=2.0 --index-url https://download.pytorch.org/whl/cpu

# 2. Install build dependencies
pip install "setuptools>=68.1" "scikit-build>=0.17" "cmake>=3.27" "ninja>=1.11"

# 3. Install L4CasADi
pip install l4casadi --no-build-isolation

To run the Fish Turbulent Flow example, you must download the required dataset and organize it into a data directory within the example folder. The directory must contain CC.csv, UALL.csv, VALL.csv, and VORTALL.csv files.

Additionally, install the necessary Python dependencies and ensure ffmpeg is installed on your system to generate animations.

# 1. Organize data into the 'data' folder
# fish_turbulent_flow/data/CC.csv, etc.

# 2. Install Python requirements
pip install -r requirements.txt

# 3. Install ffmpeg (required for animations)
# Linux:
sudo apt install ffmpeg
# OSX:
brew install ffmpeg

To use L4CasADi in a notebook environment (like Google Colab), you need to install PyTorch, build tools, and the L4CasADi package itself. Note that L4CasADi requires scikit-build, cmake, and ninja for the build process.

# Install PyTorch (CPU version)
!pip install torch --index-url https://download.pytorch.org/whl/cpu

# Install build dependencies
!pip install scikit-build cmake ninja

# Install L4CasADi from source
!pip install git+https://github.com/Tim-Salzmann/l4casadi --no-build-isolation

If you do not want to use a pre-trained model, you can train the neural network representing the flow from scratch. This is a two-step process:

1. Generate Interpolators: Run generate_interpolators.py to prepare the data.
2. Train Network: Run learn_turbulent_flow.py to perform supervised learning on the generated interpolators.

# Step 1: Generate interpolators
python generate_interpolators.py

# Step 2: Train the network
python learn_turbulent_flow.py