acados MPC求解器实战：8个常见错误排查与解决指南

1. 项目概述：与acados共度的一天

如果你正在研究模型预测控制，并且决定尝试一下acados这个开源的求解器框架，那么恭喜你，你选择了一条充满挑战但也极具回报的道路。acados以其高效、模块化的设计，在学术界和工业界都备受推崇，尤其适合嵌入式应用和快速原型开发。但和所有强大的工具一样，从“Hello World”到真正跑通一个属于自己的MPC问题，中间的路往往布满荆棘。这篇文章，就是记录了我——一个同样从零开始的开发者——在一天之内密集使用acados时，连续踩中的8个典型“坑”。我的目标不是提供一个完美的教程，而是像一个同行的伙伴，告诉你这些错误信息背后到底意味着什么，以及我是如何一步步排查并解决的。无论你是刚接触MPC的学生，还是希望将acados集成到项目中的工程师，希望这些“血泪教训”能帮你节省大量在黑暗中摸索的时间。

2. 错误一：ModuleNotFoundError: No module named 'acados_template'

这通常是满怀希望开始时的第一盆冷水。你按照官方文档，用pip install acados顺利安装了核心包，然后兴冲冲地跑起示例脚本，结果终端无情地抛出了这个错误。

2.1 错误根源解析

acados_template是acados生态中一个非常关键的Python接口包，它的核心功能是代码生成。acados的哲学是“一次建模，多处部署”。你需要在Python环境中，使用acados_template来描述你的最优控制问题（OCP），包括系统动力学、成本函数、约束等。然后，这个模板工具会将你的问题描述，转化为高度优化、针对特定求解器（如HPIPM, qpOASES等）的C语言代码。最后，你再编译这些生成的C代码，得到一个可以高效求解你特定MPC问题的“定制化”求解器。

所以，acados_template本身并不包含在acados的PyPI包中。它是一个独立的仓库。官方安装指南通常会引导你先安装acados的C核心库，然后再安装Python接口和模板。对于新手，尤其是想快速验证想法的朋友，很容易错过这一步。

2.2 解决方案与实操步骤

最直接、最推荐的方法是使用acados提供的安装脚本，它会处理大部分依赖和路径问题。

1. 克隆主仓库：首先，你需要获取完整的acados源代码。

   git clone https://github.com/acados/acados.git cd acados

2. 使用安装脚本：在acados根目录下，运行Python安装脚本。-j参数指定并行编译的线程数，可以加快速度。

   pip install -e ./interfaces/acados_template

   这个-e（editable）模式安装非常有用，意味着你对acados_template源码的修改会立即生效，无需重新安装。

3. 环境变量检查：安装脚本通常会尝试设置必要的环境变量，如ACADOS_SOURCE_DIR。但为了保险起见，你可以手动检查一下。打开你的shell配置文件（如~/.bashrc或~/.zshrc），确保有以下类似行（具体路径根据你的安装位置调整）：

   export ACADOS_SOURCE_DIR="/path/to/your/acados" export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ACADOS_SOURCE_DIR/lib

   保存后，执行source ~/.bashrc使其生效。

注意：如果你在Windows上使用WSL或Cygwin，步骤基本相同。纯Windows环境可能会遇到更多编译工具链（如CMake, Make, Visual Studio Build Tools）的问题，建议优先考虑WSL2。

2.3 个人踩坑心得

我曾经试图走“捷径”，只安装PyPI的acados包，然后手动去GitHub下载acados_template的zip包，解压后尝试用python setup.py install。结果陷入了依赖地狱，各种头文件找不到、库链接失败。最终老老实实回到官方脚本，五分钟就解决了问题。教训是：对于这类紧密耦合的科研工程软件，严格遵循官方的一键式安装流程往往是最高效的，即使它看起来步骤多一点。

3. 错误二：CMake Error: The source directory does not contain a CMakeLists.txt

当你成功安装了模板，并开始运行示例代码生成C代码时，可能会在编译环节遇到这个CMake错误。你的终端输出可能显示，代码生成成功了，生成了一个c_generated_code文件夹，但进入该文件夹执行cmake ..时失败了。

3.1 错误根源解析

这个错误的直接原因是：你没有在正确的目录下运行CMake。acados的代码生成器（acados_template）会在你指定的输出目录（例如c_generated_code）中，生成一个完整的CMake工程。这个工程包含顶层的CMakeLists.txt以及若干子模块的CMakeLists.txt。标准的编译流程是：

1. 在Python中调用generate_c_code函数，指定输出目录为./c_generated_code。
2. 终端切换至./c_generated_code目录。
3. 在该目录下执行cmake .（注意是点号，表示当前目录）或通常更规范的mkdir build && cd build && cmake ..。

如果你在c_generated_code的子文件夹（如build文件夹尚未创建时就在其内部），或者在一个完全无关的目录下运行cmake，自然找不到CMakeLists.txt。

更深层的原因是，新手可能对CMake的“构建树”和“源树”概念不熟悉。CMakeLists.txt必须位于“源树”的根目录。cmake [path_to_source]命令中的路径必须指向这个根目录。

3.2 解决方案与实操步骤

1. 确认生成目录：首先，检查你的Python代码。找到生成C代码的那一行，类似：

   acados_solver.generate(code_export_directory='c_generated_code')

   记住这个c_generated_code路径。假设你的Python脚本在/home/user/my_mpc_project下运行，那么完整路径就是/home/user/my_mpc_project/c_generated_code。

2. 导航至正确目录：打开终端，严格切换到上述路径。

   cd /home/user/my_mpc_project/c_generated_code

3. 执行标准构建流程：这是最稳健的做法。

   mkdir build # 创建一个独立的构建目录，保持源目录清洁 cd build # 进入构建目录 cmake .. # 两个点号！表示向上一级目录（即c_generated_code）寻找CMakeLists.txt make -j4 # 编译，-j4表示使用4个线程并行编译

   如果一切顺利，你会在build目录下看到编译生成的库文件（如.so或.a文件）和可执行文件（如果有的话）。

3.3 个人踩坑心得

我犯过一个更隐晦的错误：我的Python脚本里，生成路径写的是相对路径‘./c_generated_code’，但我是在VSCode的集成终端里，从项目子目录执行的脚本。这导致生成的c_generated_code文件夹位置和我的预期不符。教训是：在Python脚本中，最好使用os.path模块来构造绝对路径，确保输出目录位置明确。例如：

import os code_export_dir = os.path.join(os.path.dirname(__file__), ‘c_generated_code’) acados_solver.generate(code_export_directory=code_export_dir)

这样，无论从哪个工作目录执行脚本，生成的文件都会位于脚本文件所在的目录下。

4. 错误三：Solver ‘XXX‘ not available. Tried to create solver with empty model!

这个错误信息看起来有点令人困惑，它提到了两个可能的问题：求解器不可用，以及模型为空。通常，后者是前者的根本原因。

4.1 错误根源解析

在acados中，创建一个求解器（AcadosOcpSolver）需要两个核心部分：模型和选项。

• 模型：这是一个AcadosModel对象，你必须至少定义模型的name和动力学方程f（对于显式ODE）或f_impl（对于隐式ODE）。如果这个模型对象是“空”的——即你没有正确定义name和动力学——acados就无法知道你要求解什么问题。
• 求解器不可用：这个提示是结果。因为模型为空，acados内部在尝试配置求解器时失败，它回退地告诉你请求的求解器（可能是你选项里指定的qp_solver如PARTIAL_CONDENSING_HPIPM）对于这个“空问题”不可用。

所以，问题的核心几乎总是：你的模型定义不完整或不正确。常见的原因有：

1. 忘记给模型对象的name属性赋值。
2. 定义了动力学函数f，但其表达式字符串有语法错误，或者涉及的变量（如x，u）未在模型维度中正确定义。
3. 对于离散系统，需要使用dyn_expr而不是f，用混了会导致模型为空。

4.2 解决方案与实操步骤

你需要像侦探一样，仔细检查模型构建的每一步。下面是一个正确构建模型的最小示例：

import acados_template as at import numpy as np from casadi import SX, vertcat, sin # 1. 创建OCP对象和模型对象 ocp = at.AcadosOcp() model = at.AcadosModel() # 2. 定义模型名称（必须！） model.name = ‘my_simple_pendulum’ # 3. 定义状态和控制输入（使用CasADi的SX符号变量） x = SX.sym(‘x’, 2) # 假设状态为 [角度, 角速度] u = SX.sym(‘u’, 1) # 控制输入为扭矩 model.x = x model.u = u # 4. 定义动力学微分方程（连续时间） # 假设系统： dx0/dt = x1, dx1/dt = -sin(x0) + u f_expl = vertcat(x[1], -sin(x[0]) + u[0]) # 显式ODE右边项 model.f_expl_expr = f_expl # 指定显式动力学表达式 # ！！！关键检查点：确保表达式正确 print(“Model dynamics expression:”, model.f_expl_expr) # 5. 将模型链接到OCP ocp.model = model # 6. 继续设置OCP的其他部分（成本函数、约束、时间步长等）... # ocp.dims.N = 20 # ocp.cost.cost_type = ‘LINEAR_LS’ # ... # 7. 创建求解器 solver = at.AcadosOcpSolver(ocp) # 此时应该不再报错

排查清单：

• [ ]model.name已设置。
• [ ]model.x和model.u已正确定义为CasADi符号变量。
• [ ] 动力学表达式（f_expl_expr或f_impl_expr或dyn_expr）已赋值，且其维度与model.x的维度匹配。
• [ ] 表达式中的所有变量（如sin,cos,exp）都是从casadi模块导入或使用CasADi符号运算。
• [ ] 在创建求解器之前，使用print语句输出关键表达式，肉眼检查是否正确。

4.3 个人踩坑心得

我最常栽在动力学表达式上。有一次，我写f_expl = vertcat(x[1], -sin(x[0]) + u)，看起来没问题。但错误是u是一个1维向量，在CasADi的运算中，-sin(x[0])是一个标量，而u是一个1x1的矩阵（但仍然是矩阵类型）。在某些情况下，CasADi可以广播，但有时会出问题。更安全的写法是显式取元素：-sin(x[0]) + u[0]。另一个教训是：对于简单的表达式，先用print打印出来看看；对于复杂系统，可以尝试用casadi.Function将表达式编译成函数，并传入一些测试数值，看输出是否符合预期。这能提前发现很多符号推导上的错误。

5. 错误四：Failed to load shared library ‘libacados.so‘: libblas.so.3: cannot open shared object file

编译通过了，但在Python中导入或运行生成的求解器时，遇到了动态链接库加载失败的问题。这是典型的运行时依赖缺失。

5.1 错误根源解析

acados生成的求解器是一个共享库（例如libacados_ocp_solver.so），它本身依赖于其他一些共享库，比如：

• libacados.so: acados的核心库。
• libblas.so.3,liblapack.so.3: 线性代数计算库。
• libhpipm.so,libqpOASES.so: 具体的QP求解器库。
• libcasadi.so: CasADi符号计算库。

你的系统在运行时，需要通过动态链接器（通常是ld.so）找到这些库。LD_LIBRARY_PATH环境变量就是告诉系统去哪些额外目录寻找共享库。如果这个变量没有包含acados及其依赖库的安装路径，就会报“cannot open shared object file”错误。

5.2 解决方案与实操步骤

解决方案是确保动态链接器能找到所有必需的库。

1. 定位库文件：首先，找到这些.so文件都在哪里。

   • acados核心库和求解器库：通常在$ACADOS_SOURCE_DIR/lib下。
   • CasADi库：如果你用conda安装的casadi，可能在$CONDA_PREFIX/lib下；如果用pip安装，可能位于Python的site-packages/casadi目录下的lib子文件夹中（比较分散）。
   • BLAS/LAPACK：通常是系统级库，在/usr/lib或/usr/lib/x86_64-linux-gnu下。如果缺失，需要安装系统包，例如在Ubuntu上：sudo apt-get install libblas-dev liblapack-dev。

2. 更新LD_LIBRARY_PATH：将包含这些.so文件的目录添加到环境变量中。最好在你的shell配置文件中永久设置。

   # 编辑 ~/.bashrc 或 ~/.zshrc export ACADOS_SOURCE_DIR="/home/user/acados" # 如果你还没设置的话 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ACADOS_SOURCE_DIR/lib # 如果casadi库不在标准路径，也需要添加。一个查找的方法是： # python -c “import casadi; print(casadi.__file__)” # 假设输出 /home/user/miniconda3/lib/python3.9/site-packages/casadi/__init__.py # 那么库路径可能是 /home/user/miniconda3/lib export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/user/miniconda3/lib

   保存后，运行source ~/.bashrc。

3. 使用ldd工具诊断：这是一个极其有用的工具。在终端里，对你编译生成的求解器共享库运行ldd。

   cd /path/to/your/c_generated_code/build ldd libacados_ocp_solver.so

   输出会列出该文件依赖的所有共享库，以及系统找到它们的位置。如果某个库显示not found，那就是问题所在。你需要找到那个库的路径，并将其加入LD_LIBRARY_PATH。

4. 临时解决方案（不推荐长期使用）：你也可以在运行Python脚本前，在终端临时设置：

   LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/acados/lib:/path/to/casadi/lib python your_script.py

5.3 个人踩坑心得

我遇到过最棘手的情况是，系统里有多个版本的BLAS库（如OpenBLAS和Intel MKL）。ldd显示它链接的是libblas.so.3，但这个文件实际上是一个软链接，指向了错误的版本，导致符号不兼容。解决方案是使用update-alternatives来管理系统BLAS的默认版本，或者更彻底地，在编译acados时，通过CMake选项显式指定BLAS/LAPACK库的路径。教训是：当遇到链接库问题时，ldd是你的第一把手术刀，它能清晰地揭示依赖关系。对于科学计算库，管理好版本和路径一致性至关重要。

6. 错误五：QP solver returned error status 3 (or -3)

当你的求解器终于成功创建并开始求解时，最令人沮丧的莫过于求解器本身返回错误。状态3或-3在acados常用的HPIPM求解器中，通常表示在求解二次规划问题时遇到了数值问题，例如矩阵不正定、约束矛盾导致无可行解等。

6.1 错误根源解析

MPC问题在每一步都会被转化为一个QP问题。返回错误状态3，意味着当前迭代点的QP子问题求解失败。原因多种多样，但归根结底是问题构造的“病态”：

1. Hessian矩阵不正定：你的成本函数可能不是凸的。对于线性二次型成本，权重矩阵Q，R必须是半正定和正定的。如果你把R（控制权重）设为零矩阵，或者Q中有负权重，就会导致问题非凸。
2. 约束冲突：你设定的状态约束或控制约束可能过于严格，在给定的动力学下，从当前状态出发，无论如何都找不到一条满足所有约束的轨迹。例如，要求一个扭矩有限的电机在一步之内将高速旋转的飞轮瞬间刹停。
3. 数值缩放不当：状态变量（如位置，单位是米）和控制变量（如力，单位是牛顿）在数值上可能相差好几个数量级。这会导致QP问题的Hessian矩阵条件数很大，求解器数值稳定性变差，容易失败。
4. 初始猜测不合理：acados的SQP算法需要一个初始猜测（对状态和控制的初始轨迹）。如果这个猜测离解太远，甚至不满足约束，也可能导致第一步QP就失败。

6.2 解决方案与实操步骤

这是一个调试过程，需要你系统地检查问题表述。

1. 检查成本函数权重：确保你的Q和R矩阵是正定/半正定的。一个简单的做法是，在对角线上使用小的正数。

   nx = 4 # 状态维度 nu = 2 # 控制维度 Q = np.eye(nx) # 单位矩阵是正定的 R = 0.1 * np.eye(nu) # 控制权重通常比状态权重小，但必须是正数 # 在acados模板中设置 ocp.cost.W = scipy.linalg.block_diag(Q, R) # 对于LINEAR_LS类型

2. 放松约束：在开发初期，先不要加约束，或者把约束边界设得非常大（-inf到+inf），让问题先能求解。然后逐步收紧约束，观察在哪一步开始失败，从而定位矛盾的约束。

3. 引入数值缩放：这是一个非常重要的技巧。为你的状态和输入定义缩放因子。

   # 假设状态 x = [位置(m), 速度(m/s), 角度(rad), 角速度(rad/s)] # 位置和速度量级在1左右，角度在π左右，角速度在10左右 x_scaling = np.array([1.0, 1.0, 3.14, 10.0]) u_scaling = np.array([100.0]) # 假设控制输入是力，量级在100N左右 # 在acados中，可以通过设置成本函数和约束中的缩放矩阵来实现 # 一种方法是在定义模型后，对符号变量进行缩放 # 更直接的方法是在求解器选项中设置（如果接口支持）

   本质上，你需要让所有变量在数值上处于相近的量级（理想情况是1附近）。这能极大改善问题的条件数。

4. 提供更好的初始猜测：不要使用全零初始猜测。可以根据模型动力学，做一个简单的前向模拟来生成初始状态轨迹。对于控制输入，可以初始化为稳态控制量或零。

   solver = at.AcadosOcpSolver(ocp) N = ocp.dims.N x0 = np.array([0.1, 0.0, 0.0, 0.0]) # 初始状态 for i in range(N): solver.set(i, ‘x’, x0) # 将所有节点的状态初始猜测设为x0（不一定好，但比零好） solver.set(i, ‘u’, np.zeros(nu)) # 控制初始猜测设为零 solver.set(0, ‘lbx’, x0) # 设置初始状态约束 solver.set(0, ‘ubx’, x0)

5. 启用求解器调试输出：在创建AcadosOcpSolver时，可以设置选项来打印更详细的求解信息。

   ocp.solver_options.qp_solver_cond_N = 5 # 打印条件数 ocp.solver_options.print_level = 1 # 增加打印级别

   这可以帮助你看到QP求解器内部发生了什么。

6.3 个人踩坑心得

我曾经为一个四旋翼无人机设计MPC，状态包括位置、速度、姿态和角速度。一开始总是返回状态3。我检查了权重和约束，都没问题。最后用print_level=1输出信息，发现Hessian矩阵的条件数高达1e12。问题出在缩放上：位置的单位是米（量级1-10），姿态是四元数（量级1），但角速度的单位是弧度/秒（量级可能只有0.1）。我将角速度状态乘以10（相当于改变其单位），同时相应调整了成本函数中对应的权重，条件数立刻下降到1e6左右，求解器变得非常稳定。教训是：数值缩放不是可选项，而是设计高性能、鲁棒MPC控制器的必修课。在定义模型之后，花时间分析一下各状态和输入的大致量级，并预先做好缩放。

7. 错误六：Invalid value for parameter ‘T‘: expected positive scalar

这个错误发生在你设置OCP问题参数时，通常与时间相关参数有关。T通常表示预测时域的总时间，或者单个时间步长。

7.1 错误根源解析

在acados中，时间设置有几个关键参数，容易混淆：

• ocp.solver_options.tf: 整个预测时域的总时间（Horizon length）。
• ocp.dims.N: 预测时域内的离散阶段数（Number of shooting intervals）。
• 每个阶段的时间步长dt = tf / N。

错误“expected positive scalar”意味着你传递给T（或tf）的值不是正数。可能的原因：

1. 你直接设置了一个负数或零。
2. 你设置了一个非标量值（如数组或矩阵）。
3. 更隐蔽的情况：你从某个变量中计算tf，但那个变量由于之前的计算错误变成了NaN（非数字）或inf（无穷大），它们也不是有效的正标量。

7.2 解决方案与实操步骤

你需要仔细检查设置时间参数的代码段。

1. 明确设置tf和N：在构建OCP对象后，尽早设置它们。

   ocp = at.AcadosOcp() # ... 设置 model ... ocp.dims.N = 20 # 20个离散区间 ocp.solver_options.tf = 2.0 # 总预测时间为2秒 # 此时，时间步长 dt = 2.0 / 20 = 0.1秒

2. 验证数值：在设置前，打印一下你要赋的值。

   tf = 2.0 print(f”tf value: {tf}, type: {type(tf)}“) # 应输出: tf value: 2.0, type: <class ‘float’> assert tf > 0, “tf must be positive” ocp.solver_options.tf = tf

3. 注意时间步长的一致性：如果你使用的是shooting_nodes（一种更灵活的设置各阶段时间步长的方式），则需要确保所有时间步长为正，并且总和等于tf（如果同时设置了tf）。通常，更简单的方式是只设置N和tf，让acados自动计算均匀的dt。

4. 检查依赖变量：如果你的tf是从其他计算中得来的，确保那些计算没有错误。例如，避免除以零导致inf。

7.3 个人踩坑心得

我犯过一个愚蠢的错误：我写了一个函数来计算最优的预测时域tf，基于当前状态和参考速度。但在某些边缘情况下，参考速度为零，我的公式中出现了除以零，导致tf变成了inf。由于这个错误不是每次都发生，所以调试起来很费劲。教训是：对于从公式计算得出的关键参数，一定要加入有效性检查（断言或if语句），防止非法值（NaN, inf, 非正数）流入求解器配置环节。防御性编程在算法集成中非常重要。

8. 错误七：Dimension mismatch between constraint Jacobian and Lagrange multipliers

这个错误信息涉及优化理论中的拉格朗日乘子法，听起来很理论，但通常意味着一个非常实际的编程错误：约束的维度定义与你在其他地方设置的数据维度不匹配。

8.1 错误根源解析

在acados中，当你添加约束（比如状态约束lbx <= x <= ubx，或控制约束lbu <= u <= ubu，或一般非线性约束lh <= h(x,u) <= uh）时，你需要在多个地方保持维度一致：

1. ocp.dims中定义的维度，如nx,nu,nh（非线性约束维度）。
2. 你实际设置的约束上下界数组（lbx,ubx,lbu,ubu,lh,uh）的长度。
3. 非线性约束函数h的输出维度。

“约束雅可比”是约束函数对变量（x, u）的导数矩阵。拉格朗日乘子是与约束对偶的变量。维度不匹配意味着acados内部在构建这个导数矩阵时，发现其行列数与乘子向量的长度对不上。最常见的原因是：你声明了一个维度的约束（比如在ocp.dims.nh设置了2），但你提供的约束上下界数组lh或uh的长度却是3，或者你的约束函数h返回了一个长度为3的向量。

8.2 解决方案与实操步骤

你需要像会计对账一样，仔细核对所有维度的定义。

1. 核对ocp.dims：首先，明确你问题的基本维度。

   ocp.dims.nx = model.x.size()[0] # 状态维度，应从模型获取 ocp.dims.nu = model.u.size()[0] # 控制维度，应从模型获取 ocp.dims.nbx = 2 # 你希望设置路径约束的状态变量个数（例如，只约束前两个状态） ocp.dims.nbu = 1 # 你希望设置路径约束的控制变量个数 ocp.dims.ng = 0 # 线性通用约束维度 ocp.dims.nh = 3 # 非线性约束维度 ocp.dims.nsh = 0 # 软约束维度

2. 核对约束数据：确保你设置的数组长度与上述维度严格匹配。

   # 状态边界约束 (nbx) ocp.constraints.idxbx = np.array([0, 1]) # 约束第0和第1个状态，长度必须等于 nbx=2 ocp.constraints.lbx = np.array([-1.0, -2.0]) # 下界，长度2 ocp.constraints.ubx = np.array([1.0, 2.0]) # 上界，长度2 # 控制边界约束 (nbu) ocp.constraints.idxbu = np.array([0]) # 约束第0个控制输入，长度必须等于 nbu=1 ocp.constraints.lbu = np.array([-50.0]) # 下界，长度1 ocp.constraints.ubu = np.array([50.0]) # 上界，长度1 # 非线性约束 (nh) ocp.constraints.lh = np.array([-0.5, 0.0, -10.0]) # 下界，长度必须等于 nh=3 ocp.constraints.uh = np.array([0.5, 1.0, 10.0]) # 上界，长度3

3. 核对非线性约束函数：如果你的nh > 0，你必须定义model.con_h_expr。确保其输出是一个长度为nh的CasADi向量。

   # 假设我们有3个非线性约束 h(x,u) = [x[0]^2, x[1]+u[0], sin(x[2])] h_expr = vertcat(x[0]**2, x[1] + u[0], sin(x[2])) model.con_h_expr = h_expr print(“h_expr shape:”, h_expr.shape) # 应该输出 (3, 1)

4. 使用维度推断：一个很好的习惯是，尽可能从模型中推断维度，而不是硬编码数字。

   nx = model.x.size()[0] nu = model.u.size()[0] ocp.dims.nx = nx ocp.dims.nu = nu

8.3 个人踩坑心得

我曾经在修改约束时，只更新了ocp.constraints.lh/uh数组的长度，却忘了同步修改ocp.dims.nh。结果nh是2，但我给的上下界数组长度是3，导致了维度不匹配错误。教训是：将维度定义（ocp.dims）和具体数据设置（ocp.constraints）视为一个需要同步更新的整体。每当你增删约束时，必须同时检查并更新这两个地方。写一个小的验证函数，在创建求解器前检查所有维度的一致性，是个好习惯。

9. 错误八：Solver reached maximum number of iterations: 100

求解器没有报错退出，但给出了一个警告，表示它达到了最大迭代次数（默认通常是100）但仍未收敛到满足容差的解。这属于收敛性问题。

9.1 错误根源解析

acados对OCP的求解通常基于序列二次规划（SQP）或类似方法，这是一种迭代算法。在每一步迭代，它求解一个QP子问题，并更新轨迹猜测。迭代终止的条件通常是：KKT条件（最优性条件）的残差小于某个容忍度（tol），或者达到最大迭代次数（max_iter）。

达到最大迭代次数意味着：

1. 问题太难：可能非线性很强，或者初始猜测太差，导致算法进展缓慢，在100步内无法收敛。
2. 容忍度设置过严：tol设置得太小，要求解达到极高的精度，即使残差已经很小了，但还没达到你的标准。
3. 问题本身无解或不光滑：例如，存在不连续的动力学历程或成本函数，导致算法在某个点振荡，无法收敛。
4. 数值问题：同错误五，糟糕的缩放或病态的Hessian矩阵会导致QP子问题求解困难，进而影响外层SQP的收敛。

9.2 解决方案与实操步骤

你需要调整求解器选项，并可能重新审视问题本身。

1. 增加最大迭代次数：这是最简单的尝试。将max_iter调大。

   ocp.solver_options.nlp_solver_max_iter = 500 # 增加到500次

   然后重新运行，观察残差（statistics[‘sqp_iter’]和statistics[‘res_stat’],statistics[‘res_eq’],statistics[‘res_ineq’]）是否在持续下降。如果下降得很慢，可能需要其他调整。

2. 放宽收敛容忍度：对于实时控制，有时不需要极高的精度。适当放宽tol可以加速收敛。

   ocp.solver_options.nlp_solver_tol_stat = 1e-4 # 默认可能是1e-6或更小 ocp.solver_options.nlp_solver_tol_eq = 1e-4 ocp.solver_options.nlp_solver_tol_ineq = 1e-4 ocp.solver_options.nlp_solver_tol_comp = 1e-4

3. 改进初始猜测：提供一个更接近真实解的初始猜测可以显著减少迭代次数。你可以使用上一时刻的求解结果（热启动），或者用简单的控制器（如LQR）生成一条初始轨迹。

4. 调整SQP步长策略：acados提供了一些高级选项。

   ocp.solver_options.nlp_solver_step_length = 0.9 # 减小步长，可能更稳定 ocp.solver_options.globalization = ‘MERIT_BACKTRACKING’ # 使用基于价值函数的线搜索，通常更鲁棒 ocp.solver_options.alpha_min = 1e-2 # 最小步长 ocp.solver_options.alpha_reduction = 0.5 # 步长缩减因子

5. 检查问题可行性：回到错误五的思路，确保你的问题在数学上是良定义的、凸的（或局部凸）、并且约束是可行的。对于高度非凸的问题，可能需要全局优化方法，但这超出了标准acados SQP的范围。

9.3 个人踩坑心得

我为一个带有复杂非凸障碍物约束的机器人路径规划问题设计MPC。一开始，最大迭代次数总是被触达。我首先增加了max_iter到500，发现残差在头50次迭代下降很快，之后几乎停滞。这说明问题可能卡在了某个局部“高原”。我尝试了两种策略：第一，显著放宽初始容忍度（tol_stat=1e-3），让求解器先快速得到一个“粗糙”但可行的解。然后，我用这个解作为下一次MPC步的初始猜测，并将容忍度收紧回1e-6。第二，我引入了“软约束”，给障碍物约束添加了松弛变量和惩罚项，这改变了问题的局部形状，使其更容易收敛。教训是：对于难解的问题，不要只盯着一个旋钮（如max_iter）。需要结合初始猜测、容忍度管理、问题重构（软约束）等多种策略。观察残差下降曲线是诊断收敛问题的关键。