Learning 4 CasADi 框架

L4CasADi 能够将 PyTorch 训练的模型无缝集成到 CasADi 中，从而实现高效且可能由硬件加速的数值优化。对 PyTorch 模型的唯一要求是可导出和可微分。

                                                                    

两个 L4CasADi 示例：通过 NeRF 的无碰撞轨迹以及在湍流中的导航

arXiv: Learning for CasADi：数值优化中的数据驱动模型

演讲：Youtube

L4CasADi v2 的重大变更

根据首批用例的反馈，L4CasADi v2 在设计时充分考虑了效率与简洁性。

这带来了以下几项重大变更：

• L4CasADi v2 可以利用 PyTorch 的批处理功能来提升效率。当设置 batched=True 时，L4CasADi 会将输入张量的第一个维度视为批次维度。因此，该维度上的各元素之间的一阶和二阶导数都被假定为稀疏零矩阵。为了充分利用这一点，在你的 CasADi 程序中，不要多次调用 L4CasADi 函数，而是将所有输入批量合并后只进行一次 L4CasADi 调用。例如，对比非批处理的 NeRF 示例和批处理的 NeRF 示例，后者速度提升了 5 到 10 倍。
• L4CasADi v2 不再改变输入的形状，因为这一行为曾引发混淆。传递给 PyTorch 模型的张量将完全匹配 CasADi 输入变量的精确维度。你需要确保 PyTorch 模型能够正确处理二维输入矩阵！相应地，参数 model_expects_batch_dim 已被移除。
• 默认情况下，L4CasADi v2 不会提供 Hessian 矩阵，而只会提供伴随梯度的雅可比矩阵。对于大多数优化问题来说，这已经足够了。不过，你也可以通过设置 generate_jac_jac=True 来显式请求生成 Hessian 矩阵。

目录

• 使用 L4CasADi 的项目
• 安装
  • 先决条件
  • Windows 安装
  • 仅 CPU 的 pip 安装
  • 仅 CPU 的源码安装
  • GPU (CUDA)
• 快速入门
• 在线学习
• Naive L4CasADi - 适用于小型多层感知器模型。
• 实时 L4CasADi - 适用于结合 Acados 的快速 MPC。
• 示例

如果你使用了本框架，请引用以下两篇论文：

@article{salzmann2023neural,
  title={实时神经网络 MPC：用于四旋翼无人机及敏捷机器人平台的深度学习模型预测控制},
  author={Salzmann, Tim 和 Kaufmann, Elia 和 Arrizabalaga, Jon 和 Pavone, Marco 和 Scaramuzza, Davide 和 Ryll, Markus},
  journal={IEEE Robotics and Automation Letters},
  doi={10.1109/LRA.2023.3246839},
  year={2023}
}

@inproceedings{{salzmann2024l4casadi,
  title={Learning for CasADi：数值优化中的数据驱动模型},
  author={Salzmann, Tim 和 Arrizabalaga, Jon 和 Andersson, Joel 和 Pavone, Marco 和 Ryll, Markus},
  booktitle={动力学与控制学习会议 (L4DC)},
  year={2024}
}

使用 L4CasADi 的项目

• 实时神经网络 MPC：用于四旋翼无人机及敏捷机器人平台的深度学习模型预测控制
  论文 | 代码
• AC4MPC：用于非线性模型预测控制的演员-评论家强化学习
  论文
• 基于强化学习的 MPC，结合神经动力学模型
  论文
• 用于障碍物感知局部运动规划的神经势场
  论文 | 视频 | 代码
• 基于深度神经网络的 N-MPC，利用深度图像实现避障
  论文 | 代码
• 基于 NNMPC 的自动驾驶规划与跟踪一体化框架，考虑路面变化
  论文

如果你的项目正在使用 L4CasADi，并希望在此处展示，请联系我们。

安装

前置条件

无论您是从源代码安装还是通过 pip 安装，都需要满足以下要求：

• 可用的构建系统：兼容 CMake 的 C++ 编译器。
  • 在 Linux/macOS 上： 建议使用 GCC 10 或更高版本。
  • 在 Windows 上： 必须安装 CMake 和 Visual C++ 构建工具（请勿使用 GCC 编译器）。
• 在您的 Python 环境中安装 PyTorch (>=2.0)。
  python -c "import torch; print(torch.__version__)"

Windows 安装

对于在 Windows 上安装的用户，请确保执行以下步骤：

1. 安装 CMake 和 Visual C++ 构建工具： 下载并安装 CMake 和 Visual C++ 构建工具。
2. 确保工具已添加到 PATH： 确保 CMake 和 Visual C++ 构建工具都已添加到系统的 PATH 中。这可以通过安装程序（选择更新 PATH 的选项）或手动完成。
3. 注意文件路径长度： 在构建 L4CasADi 模型时，确保目录路径不超过 Windows 的最大字符限制。过长的路径可能会导致构建问题，因此尽可能选择路径较短的目录。

使用 pip 安装（仅 CPU）

• 确保已安装 Torch 的 CPU 版本： pip install torch>=2.0 --index-url https://download.pytorch.org/whl/cpu
• 确保所有构建依赖项已安装：

  setuptools>=68.1
  scikit-build>=0.17
  cmake>=3.27
  ninja>=1.11
  

• 运行： pip install l4casadi --no-build-isolation

从源代码安装（仅 CPU）

• 克隆仓库： git clone https://github.com/Tim-Salzmann/l4casadi.git
• 通过以下命令安装所有构建依赖项： pip install -r requirements_build.txt
• 从源代码构建： pip install . --no-build-isolation

--no-build-isolation 标志是 L4CasADi 找到并链接已安装的 PyTorch 所必需的。

GPU（CUDA）

CUDA 的安装需要安装 nvcc，它是 CUDA 工具包的一部分，在 Linux 上可以通过以下命令安装： sudo apt-get -y install cuda-toolkit-XX-X（其中 XX-X 是您已安装的 CUDA 版本，例如 12-3）。安装 CUDA 工具包后，nvcc 通常位于 /usr/local/cuda/bin/nvcc。

确保可以执行 nvcc -V，然后运行 pip install l4casadi --no-build-isolation 或者 CUDACXX=<PATH_TO_NVCC> pip install . --no-build-isolation 来从源代码构建。

如果 nvcc 不在您的路径中，您可以为 L4CasADi 指定 nvcc 的路径。例如： CUDACXX=<PATH_TO_NVCC> pip install l4casadi --no-build-isolation。

快速入门

在 Python 中定义一个 L4CasADi 模型，只需提供一个预先定义好的 PyTorch 模型即可，操作非常简单：

import l4casadi as l4c

l4c_model = l4c.L4CasADi(pyTorch_model, device='cpu')

其中，PyTorch 模型的架构没有限制，大型模型可以借助专用硬件加速。

在线学习与更新

L4CasADi 支持在 CasADi 图中在线更新 PyTorch 模型。要使用此功能，在初始化 L4CasADi 时传递 mutable=True。要更新模型，调用 L4CasADi 对象上的 update 函数。您可以选择性地传入更新后的模型作为参数。如果不传入模型，则假定在初始化时传入的参考模型已被更新，并将用于更新。

Naive L4CasADi

虽然 L4CasADi 在设计时考虑了效率，内部利用了 PyTorch 的 C++ 接口，但这仍然可能带来一定的开销，对于小型、简单的模型来说，这种开销可能会显得过大。因此，L4CasADi 还提供了一个 NaiveL4CasADiModule，它直接使用 CasADi 操作重新创建 PyTorch 的计算图，并复制权重——从而生成纯 C 计算图，避免了与 PyTorch 的上下文切换。然而，这种方法仅限于一小部分预定义的 PyTorch 操作——仅支持 MultiLayerPerceptron 模型和 CPU 推理。

当网络层数少于三层，且每层仅有 64 个神经元（或等效规模）时，PyTorch 框架本身的开销会占据主导地位。对于小于该规模的模型，我们建议使用 NaiveL4CasADiModule。而对于更大的模型，这种开销则变得可以忽略，此时应使用 L4CasADi。

https://github.com/Tim-Salzmann/l4casadi/blob/f7b16fba90f4d3ee53217b560f26b47e6b23e44a/examples/naive/readme.py#L5-L9

实时 L4CasADi

实时 L4CasADi（原 ML-CasADi 中的“近似”方法）是驱动 实时神经 MPC 的底层框架。它用局部泰勒近似替换复杂模型。对于某些优化过程（如具有多个射击节点的 MPC），这可以显著提高优化速度。然而，“实时 L4CasADi”有许多限制（仅支持 Python，无法生成 C(++) 代码等），因此它并不能完全替代 L4CasADi。相反，它是一个针对特定应用场景的补充框架。

更多信息请参见 这里。

https://github.com/Tim-Salzmann/l4casadi/blob/f7b16fba90f4d3ee53217b560f26b47e6b23e44a/l4casadi/realtime/examples/readme.py#L32-L43

示例

https://github.com/Tim-Salzmann/l4casadi/blob/f7b16fba90f4d3ee53217b560f26b47e6b23e44a/examples/readme.py#L28-L40

请注意，仅支持 casadi.MX 符号变量作为输入。 多输入多输出函数可以通过在传递给模型时连接符号输入，并在 PyTorch 函数内部将其拆分来实现。 要使用 GPU（CUDA），只需在 L4CasADi 构造函数中传递 device="cuda" 即可。 更多示例：

• 无碰撞最小化 snap 优化轨迹穿过 NeRF：examples/nerf_trajectory_optimization
• 节能鱼类在湍流中的导航：examples/fish_turbulent_flow
• 使用 L4CasADi 模型作为目标函数和约束的简单非线性规划：examples/simple_nlp.py
• L4CasADi 在纯 C(++) 项目中的应用：examples/cpp_executable
• 在 Matlab 中使用 PyTorch L4CasADi 模型：examples/matlab

Acados 集成

要将本框架与 Acados 配合使用，请按照以下步骤操作：

• 按照 安装说明 进行安装。
• 安装 Python 接口。
• 确保正确设置 LD_LIBRARY_PATH（在 macOS 上为 DYLD_LIBRARY_PATH）。
• 确保正确设置 ACADOS_SOURCE_DIR。

关于如何在 Acados 框架中将 PyTorch 模型用作模型预测控制的动力学模型的示例，可在 examples/acados.py 中找到。

若要将 L4CasADi 与 Acados 结合使用，需在 AcadosOcp.solver_options 中相应地设置 model_external_shared_lib_dir 和 model_external_shared_lib_name。

ocp.solver_options.model_external_shared_lib_dir = l4c_model.shared_lib_dir
ocp.solver_options.model_external_shared_lib_name = l4c_model.name

GitHub 链接

补充信息

预热

请注意，PyTorch 会在首次执行时构建计算图。因此，首次调用 CasADi 函数时会比较慢。您可以在实际使用之前，先调用生成的 CasADi 函数一到多次，以完成预热并进入优化的执行状态。

L4CasADi 快速上手指南

L4CasADi 是一个能够将 PyTorch 训练的深度学习模型无缝集成到 CasADi 数值优化框架中的工具。它支持硬件加速，适用于需要数据驱动模型的复杂优化问题（如模型预测控制 MPC、轨迹规划等）。

环境准备

在开始之前，请确保您的系统满足以下要求：

系统要求

• 操作系统：Linux, macOS 或 Windows。
• 编译器：
  • Linux/macOS：推荐 GCC 10 或更高版本。
  • Windows：必须安装 CMake 和 Visual C++ Build Tools（不要使用 GCC）。
• Python 版本：建议 Python 3.8+。

前置依赖

• PyTorch：版本需 >=2.0。

  python -c "import torch; print(torch.__version__)"
  

• 构建工具（用于从源码编译或 pip 安装时的构建过程）：

  setuptools>=68.1
  scikit-build>=0.17
  cmake>=3.27
  ninja>=1.11
  

注意：Windows 用户请确保 CMake 和 Visual C++ Build Tools 已添加到系统环境变量 PATH 中，且项目路径不要超过 Windows 的最大字符长度限制。

安装步骤

方案一：CPU 版本安装（推荐大多数用户）

如果您仅需在 CPU 上运行，或者尚未安装 GPU 版本的 PyTorch，请按以下步骤操作：

1. 安装 CPU 版 PyTorch（使用官方源或国内镜像）：

   # 使用官方源
   pip install torch>=2.0 --index-url https://download.pytorch.org/whl/cpu
   
   # 或使用清华大学镜像加速
   pip install torch>=2.0 --index-url https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 安装构建依赖：

   pip install setuptools>=68.1 scikit-build>=0.17 cmake>=3.27 ninja>=1.11
   

3. 安装 L4CasADi：

   关键：必须添加 --no-build-isolation 参数，以便 L4CasADi 能正确链接已安装的 PyTorch。

   pip install l4casadi --no-build-isolation
   

方案二：GPU (CUDA) 版本安装

如果您需要使用 GPU 加速，请先确保安装了完整的 CUDA Toolkit 和 nvcc 编译器。

1. 安装 CUDA Toolkit (以 Ubuntu 为例)：

   sudo apt-get -y install cuda-toolkit-12-3  # 请将版本号替换为您需要的版本
   

   验证安装：nvcc -V 应能正常输出版本信息。

2. 安装 L4CasADi： 如果 nvcc 不在系统路径中，需指定路径：

   export CUDACXX=/usr/local/cuda/bin/nvcc  # 替换为实际 nvcc 路径
   pip install l4casadi --no-build-isolation
   

   或者直接指定变量安装：

   CUDACXX=/usr/local/cuda/bin/nvcc pip install l4casadi --no-build-isolation
   

方案三：从源码安装

如需使用最新开发版功能：

git clone https://github.com/Tim-Salzmann/l4casadi.git
cd l4casadi
pip install -r requirements_build.txt
pip install . --no-build-isolation

基本使用

L4CasADi 的核心用法非常简单：只需将一个标准的 PyTorch 模型包装即可在 CasADi 中使用。

1. 定义 PyTorch 模型

首先定义并训练好你的 PyTorch 模型（必须是可微分且可追踪的）。

import torch
import torch.nn as nn

class SimpleNet(nn.Module):
    def __init__(self):
        super(SimpleNet, self).__init__()
        self.fc = nn.Linear(2, 1)

    def forward(self, x):
        return self.fc(x)

pytorch_model = SimpleNet()
# 假设这里已经加载了训练好的权重
# pytorch_model.load_state_dict(...) 
pytorch_model.eval()

2. 包装为 L4CasADi 模型

使用 l4c.L4CasADi 进行包装。

import l4casadi as l4c
import casadi as ca

# 初始化 L4CasADi 模型
# device 可以是 'cpu' 或 'cuda'
l4c_model = l4c.L4CasADi(pytorch_model, device='cpu')

# 创建 CasADi 符号变量
x = ca.SX.sym('x', 2)

# 将 CasADi 符号传入 L4CasADi 模型，生成 CasADi 函数
# 此时 l4c_model(x) 返回的是一个 CasADi 表达式
casadi_expr = l4c_model(x)

# 创建 CasADi 函数用于数值计算或优化
f = ca.Function('f', [x], [casadi_expr])

# 测试运行
import numpy as np
test_input = np.array([1.0, 2.0])
result = f(test_input)
print(f"Optimization result: {result}")

进阶提示：在线更新模型

如果需要在优化过程中动态更新神经网络权重（例如在线学习），请在初始化时设置 mutable=True：

l4c_model = l4c.L4CasADi(pytorch_model, device='cpu', mutable=True)

# ... 在优化循环中 ...
# 更新模型权重
new_weights = ... 
pytorch_model.load_state_dict(new_weights)
l4c_model.update()  # 通知 CasADi 图更新

性能优化建议

• 批量处理 (Batching)：L4CasADi v2 支持批量输入以提升效率。如果您的应用场景涉及多个采样点，请将输入维度合并，并在调用时利用批处理能力，这通常能带来 5-10 倍的速度提升。
• 小模型选择：如果您的网络非常小（少于 3 层隐藏层，每层少于 64 神经元），PyTorch 的调用开销可能占主导。此时建议使用 NaiveL4CasADiModule，它将直接转换为纯 CasADi/C 代码，但仅支持简单的 MLP 结构。