简介：acados 是一套面向非线性最优控制（NMPC）的快速嵌入式求解器，适合机器人、自动驾驶、无人机、过程控制等对实时性有严格要求的场景，可用于解决大规模非线性优化问题的在线求解。资源提供 C、Python、MATLAB 与 Octave 多语言接口，并内置 CasADi 集成示例，可帮助算法工程师快速从仿真验证过渡到嵌入式部署，适用于需要掌握实时 NMPC 的中高级开发者。压缩包共 1227 个文件，约 21.72MB，主体为 C 源码（371 个 .c）、MATLAB 脚本（296 个 .m）、头文件（122 个 .h）、Python 文件（88 个 .py），并包含 makefile、CMake 配置、shell 脚本、Markdown/PDF 文档等，便于跨平台编译与查阅；包内同时提供链式系统求解、Hessian 计算、CasADi ERK4 集成等多类数值示例，便于对照理解整个求解流程。目前已有 1979 人学习下载，适合需要掌握 acados 安装配置、了解 NMPC 求解流程，或者准备将求解器集成到自身控制系统的中高级开发者。通过这套源码包，读者可以获得可编译的完整工程、多语言调用示例与构建脚本，大幅节省环境搭建和排错时间，从而加速自己的控制算法落地。
1. 为什么嵌入式最优控制选择acados：实时迭代与C基因
我从一个失望的下午开始说这事。之前在某机器人平台上做非线性模型预测控制，CasADi+IPOPT在工控机上能交出40ms的解，但要塞进一块主频400MHz的MCU，连想都不用想。后来换了acados，同样是动态避障问题，RTI模式下每步求解稳定跑到3ms以内，生成的C代码去掉动态内存分配，目标板内存预算直接降了一个量级。acados不是另一个求解器封装，它是一整套由C语言实现的非线性最优控制(NMPC)工具链：把非线性优化拆成“每个采样周期只解一个二次规划(QP)”，配合内置的高性能内点法和实时迭代机制，让嵌入式设备也有机会跑实时NMPC。这篇文章就是我从选型、Python验证、C代码生成到实际部署踩坑的完整记录。
2. 求解器选型与核心方法论：从OCP到QP的迭代逻辑
2.1 最优控制问题的标准形式：先搞清楚要解什么
NMPC要解决的问题可以用一段话描述：给定从当前状态x0出发的预测时域N步，找到控制序列u0..uN-1和状态序列x1..xN，使动力学x(k+1)=f(x(k),u(k))成立，并且代价函数J最小，还得满足状态和控制不等式约束。代价函数通常是半正定二次型或更一般的非线性最小二乘，约束包括控制幅值、控制增量、状态安全边界。acados在内部把这个问题离散成带带状结构的非线性规划，然后用迭代法去逼近。
很多读者第一次接触acados，容易把它当成一个黑盒求解器直接往里丢问题，结果并不理想。实际上，acados对问题的组织方式和通用NLP求解器有一个重要差异：它默认你要输出“可预测计算量”的解，而不是“高精度”的解。因此问题建模时，哪些量进代价、哪些量进约束、哪些量只是状态，都要提前想清楚，否则后面的QP求解和RTI行为会完全不一样。
2.2 为什么非线性问题要反复线性化：SQP与RTI的分工
非线性最优控制不能像线性MPC那样直接解析求解，常见思路是序列二次规划(SQP)：在每一次主迭代中，把非线性动力学在当前(x,u)处线性化，把代价函数在参考点附近做二阶近似，得到一个带线性约束的QP，解出搜索方向后沿方向步进，重复直到收敛。SQP收敛性好，但每步都要重新计算导数和因子分解，在嵌入式上未必划算。
RTI(实时迭代)是SQP的一个变体，把“收敛到最优”这个目标让给反馈机制：每个采样周期只做一次线性化和一次QP求解，解出来的控制量直接给被控对象，下个周期再重复。由于系统本身在闭环反馈中，这种次优解在工程上往往足够，而单步计算量上限也可以事先算死。acados把这两条路径同时放在nlp_solver_type里，用'SQP'做离线验证，用'SQP_RTI'做实时部署。我的习惯是先离线用SQP把轨迹形态调对，再切到RTI看闭环效果。
一次RTI周期内部可以拆成两个阶段：准备阶段(preparation)计算雅可比、离散化并完成condensing；反馈阶段(feedback)只做一次QP求解。这样拆分的好处是准备阶段的耗时可以通过并行计算或预计算抵消，反馈阶段的耗时极短且固定。这种设计对控制任务很重要，因为准备阶段虽然在实时循环内，但对硬件抢占和中断不那么敏感，而反馈阶段必须硬实时完成。acados把这套时序暴露给用户后，很多开发者会把准备阶段放到协处理器上跑，MCU只保留反馈阶段的QP求解。
2.3 acados里都有什么：积分器、QP求解器与线性代数库的配合
acados不是只有一个核心算法，而是由几个可替换模块组成。模型被交给积分器做离散化，常见选项是显式Runge-Kutta(ERK)和隐式Runge-Kutta(IRK)。ERK适合刚性不强但有明确导数的问题，IRK适合刚性强或约束多的场景。离散化之后，问题转成一个带banded结构的QP，acados默认用HPIPM求解，它提供部分凝结和完全凝结两条路径，把带状稀疏结构变成稠密小规模的QP来降低内存带宽。
condensing是一个容易被忽略但实际决定实时性能的环节。MPC问题本身的QP具有带状稀疏结构，直接交给通用稀疏求解器，内存访问模式会非常差。condensing把未来时域状态通过动力学约束消去，只保留控制变量作为自由度，得到一个稠密的但规模小很多的QP；HPIPM内部还有部分凝结路径，可以在内存和速度之间折衷。对MCU来说，condensing产生的中间矩阵往往是占用内存的大头，调选项时要重点看这一步。
底层线性代数用的是BLASFEO，这是专门为嵌入式优化做过性能调优的库，比直接调BLAS更可控。每个模块都能替换：QP求解器可以换成qpOASES，集成过程可以导出成C代码。换来换去的主要目的是在不同的问题规模、采样周期和目标硬件算力之间找平衡点。模块化让acados不像CasADi那样只提供高层接口，而是把实时闭环需要的每个细节都摆到桌面上，代价是配置项偏多。
2.4 选型对比：同样是NLP求解器，acados赢在哪
做NMPC常见的选择还有CasADi+IPOPT、GRAMPC和个别商业求解器。CasADi+IPOPT是离线最优控制的强项，IPOPT采用内点法，每次迭代都要做大规模稀疏线性求解，实时性和内存可控性都不适合MCU；GRAMPC实现了基于显式积分器策略的求解方案，代码量小，但问题灵活性弱。把特性放一起看：
| 特性 | acados | CasADi+IPOPT | GRAMPC |
|---|---|---|---|
| 核心语言 | C | C++/部分C | C |
| 实时迭代(RTI) | 原生支持 | 不支持 | 有类似机制但较弱 |
| 代码生成 | 支持导出C代码 | 部分生成 | 编译前生成 |
| 动态内存分配 | 尽量避免 | 常规使用 | 较少 |
| 适合场景 | 嵌入式NMPC实时控制 | 离线轨迹优化 | 简单模型快速验证 |
我一般按两个维度选型：目标平台是否有MMU/浮点加速，以及问题是“算一遍给参考轨迹”还是“每帧都得给出控制量”。前者直接选CasADi+IPOPT，后者优先考虑acados。如果只是验证数学模型，用GRAMPC也无妨，但它对约束类型和代价函数形式的支持较少，后面要加状态依赖约束时会束手束脚。
所以我的选型顺序很固定：第一步，看模型是否刚性，决定IRK还是ERK；第二步，看目标平台内存和浮点能力，决定是否做代码生成；第三步，看实时性需求，选择SQP还是RTI。这些问题在acados里都有明确参数对应，而不是玄学。把这些先想清楚，后面移植到C/C++或者嵌入式时就不需要大改。
3. Python端快速复现一个无人机避障NMPC：从建模到解出轨迹
3.1 安装与环境检查：Python接口 + CasADi 一条龙
先说明安装路径。acados提供Python模板接口acados_template，它负责生成C代码并编译为动态库，所以终端里需要已经具备gcc和cmake。常见做法是先编译acados本体，再设置环境变量让Python接口能定位到库文件：
# 编译核心库 git clone <acados仓库地址> $HOME/acados cd $HOME/acados mkdir build && cd build cmake .. && make install # 环境变量 export ACADOS_ROOT=$HOME/acados export LD_LIBRARY_PATH=$ACADOS_ROOT/lib:$LD_LIBRARY_PATH # Python 接口 pip install acados克隆地址这里不写了，从官方发布主页拿即可。编译完成后，先跑一遍自带的最小示例，如果solver.solve()能返回0，说明环境没问题。这一步我省略过，结果第一次跑就报找不到libacados.so，排错半小时后才发现是LD_LIBRARY_PATH没导入新终端。环境变量这种事没有技巧，每次开新终端都要export，要么写进shellrc。提示：如果使用Jupyter，重启内核后环境变量也要重新生效。
3.2 定义运动学模型：二维双积分器加推力约束
以平面无人机避障为例子，状态取四个分量：位置px、py，速度vx、vy；控制量是水平方向加速度。动力学是标准的双积分器，模型用CasADi符号定义。acados对模型的定义非常直接：把符号变量和右端函数填进AcadosModel即可。
import casadi as cs from acados_template import AcadosOcp, AcadosOcpSolver, AcadosModel px = cs.SX.sym('px'); py = cs.SX.sym('py') vx = cs.SX.sym('vx'); vy = cs.SX.sym('vy') x = cs.vertcat(px, py, vx, vy) ax = cs.SX.sym('ax'); ay = cs.SX.sym('ay') u = cs.vertcat(ax, ay) f_cont = cs.vertcat(vx, vy, ax, ay) model = AcadosModel() model.name = 'drone_2d_track' model.x = x model.u = u model.f_expl_expr = f_cont这里f_expl_expr是显式动力学表达式，acados会基于它做显式RK积分。如果动力学是隐式的，比如DAE系统，就要换f_impl_expr并额外提供雅可比。双积分器虽然简单，但它能暴露NMPC里大多数数值问题：奇异性、约束激活、噪声放大，后面部署到真实无人机前，先在这个模型上验证代码流程是值得的。
3.3 配置代价、约束与预测时域：关键参数都写在这儿
关键参数设置直接决定性能。预测时域N选20，采样时间0.05s，配置如下：
ocp = AcadosOcp() ocp.model = model ocp.dims.N = 20 ocp.solver_options.tf = 1.0 # N * dt # 代价：位置偏差与速度偏差 ocp.cost.cost_type = 'NONLINEAR_LS' ocp.cost.W = cs.diag([10.0, 10.0, 1.0, 1.0]) ocp.cost.W_0 = 0.1 * ocp.cost.W ocp.cost.yref = [0.0, 0.0, 0.0, 0.0] # 预测终点参考 # 加速度约束 ocp.constraints.constr_type = 'BGH' ocp.constraints.lbu = [-2.0, -2.0] ocp.constraints.ubu = [ 2.0, 2.0] ocp.constraints.idxbu = [0, 1] # 初始状态 ocp.constraints.x0 = [0.0, 0.0, 1.0, 0.0]不少新手会在这里把cost_type误设成LINEAR_LS，那个版本要求yref和W都是常量矩阵，适合线性时不变问题。NONLINEAR_LS允许把避障项、终端代价等以非线性函数塞进去，代价里每一项都能是状态的函数，灵活性高很多。预测时域N选择要看被控对象动态：时间常数越快，N可以越小，但N太小会导致约束不可行；N太大会让condensing后的QP变量变多，嵌入式内存吃紧。这个例子用N=20，在几百兆主频的MCU上通常来得及。
避障的真正窍门在约束项。给模型加一个圆形障碍约束，用con_h_expr定义非线性不等式，满足h(x,u)>=0即可：
obs_x = 2.0; obs_y = 0.5; r_obs = 0.8 dist = (px - obs_x)**2 + (py - obs_y)**2 model.con_h_expr = dist - r_obs**2 ocp.constraints.lh = [0.0] ocp.constraints.uh = [1e5]这个约束要求无人机始终在障碍圆外侧，lh取0意味着“距离平方必须大于等于半径平方”。约束的方向一旦搞反，求解器会把轨迹往障碍里压还觉得自己做得很对。
3.4 求解与轨迹提取：看数据而不是只看动画
配置求解器参数并实例化求解器。我用SQP_RTI验证实时性，同时把qp_solver设为部分凝结HPIPM：
ocp.solver_options.integrator_type = 'ERK' ocp.solver_options.qp_solver = 'PARTIAL_CONDENSING_HPIPM' ocp.solver_options.nlp_solver_type = 'SQP_RTI' solver = AcadosOcpSolver(ocp, json_file='ocp_acados_ocp.json') status = solver.solve() for k in range(ocp.dims.N + 1): state_k = solver.get(k, 'x') control_k = solver.get(k, 'u') # 边界点无控制量时需处理第一次实例化会比较慢，因为要生成C代码并本地编译；后续直接读json文件会快很多。解完之后直接从solver对象里取每步状态和控制，不要只看是否返回0。status返回0只说明求解器正常返回，不代表轨迹满足约束，要检查状态序列有没有越界、控制序列有没有抖动，这些在动画里不容易看见。通常我还会把轨迹和参考路径画在同一张图里，叠加约束边界，这样引脚问题一目了然。
如果求解状态返回非0，不要急着调权重。先看NLP残差和QP状态，acados日志会给出solver status和迭代次数。常见情况是初值离约束边界太远，把x0往后拉一点，或者先跑一拍SQP预热再切换RTI。这个细节是很多新手卡壳的地方。
4. 部署到嵌入式目标：C代码生成、内存约束与实时性调优
4.1 code export 导出C代码：从Python到C的流程
在Python环境里验证完后，下一步是把OCP配置导出成C代码，在目标板上使用。acados的Python接口在实例化solver时已经会生成一份C代码，但要部署到嵌入式，需要额外指定导出目录并关闭本机构建：
ocp.code_export_directory = 'drone_track_c' # 设置嵌入式相关选项 ocp.solver_options.qp_solver = 'PARTIAL_CONDENSING_HPIPM' ocp.solver_options.integrator_type = 'ERK' ocp.solver_options.nlp_solver_type = 'SQP_RTI' ocp.solver_options.print_level = 0 solver = AcadosOcpSolver(ocp, json_file='ocp.json', build=False)build=False的含义是不在当前机器上编译，只把C源码和CMakeLists生成到指定目录。导出后目录里会出现acados_solver.c、acados_solver.h、model/目录下包含动力学雅可比和残差函数。这套C代码不带运行时解释器，数据都是静态数组，进入main函数之前内存布局已经固定。整个移植过程我都建议先做一次“代码导出->交叉编译->运行最小案例”的最小闭环，不要直接拿整车系统上线。
4.2 在裸机/RTOS上二次封装：关键调用与内存预算
生成的C代码入口风格类似：先创建求解器，循环里调用solve，结束后释放。只是用C语言写时，求解器句柄和所有工作内存都通过上下文结构体传入：
#include "acados_solver.h" /* 在任务创建时初始化一次 */ ocp_nlp_solver_config *config; ocp_nlp_dims *dims; ocp_nlp_in *nlp_in; ocp_nlp_out *nlp_out; void *solver = acados_solver_create(&config, &dims, &nlp_in, &nlp_out);循环体里每周期只做一件事：更新初始状态和参考值，调用求解函数，取出控制量。这样一个RTOS任务里就可以稳定跑NMPC。但这里的重点不是函数名，而是内存预算。生成的代码里如果把输入状态、输出控制、中间雅可比、QP因子分解矩阵都静态分配，内存占用是可计算的：大约等于状态维度x(控制维度+1)x预测步数的若干倍，加上HPIPM的因子分解内存。我在A板子上遇到过两次内存踩踏，最后都是因为dims没有按照目标平台字节对齐，结构体里用#pragma pack压了字节，导致协处理器访问越界。在CMakeLists中还要加上-mfloat-abi=hard -mfpu=fpv5-d16这类选项，如果浮点单元没开或者用了软浮点，求解时间会放大十倍以上。这个坑在所有ARM平台都常见，属于编译链而不是acados本身的问题。
4.3 实时性验证手段：每周期毫秒级抖动怎么抓
嵌入式上最怕的不是平均求解慢，而是偶尔一次超时。要在代码里给solver_solve计时间，简单可靠的做法是用周期时钟：
uint32_t t0 = DWT->CYCCNT; acados_solver_solve(solver, nlp_in, nlp_out); uint32_t dt_ticks = DWT->CYCCNT - t0; double ms = (double)dt_ticks / (SystemCoreClock / 1000.0); if (ms > budget_ms) flag_timeout = 1;这个计时放在真正的控制循环里才有意义，不要放在调试断点环境里测。连续跑几千帧后统计最大耗时和P99耗时，比平均值更能说明问题。如果最大耗时是平均值的几倍，多半是RTI中的残差和雅可比计算触发了cache miss，或者第一次调用时缓存未预热。可以把敏感数据放到CCM内存或锁缓存，但前提是先确认热点在哪，不要凭感觉改内存布局。
5. 避坑/常见问题/排查：5个让求解器“毁于一旦”的细节
5.1 模型名称重复：所有求解结果都指向同一个残差
现象：同时定义两个动力学模型，分别构造solver，结果第二个solver的输出和第一个一模一样。原因：acados按model.name生成C文件和动态库名称，模型名都叫drone时，第二个实例覆盖了第一个的代码缓存，符号找不到时还会静默复用旧库。解决：每个模型取唯一名称，删除build与ocp.json缓存后重新生成。从那以后我的模型名都带日期后缀，防止遗忘。
5.2 首次solve段错误：环境变量与JIT缓存的锅
现象：Python接口第一次调用solver.solve()就Segmentation fault，在Jupyter里直接重启内核。原因：LD_LIBRARY_PATH没有指向libacados.so所在目录，或者libstdc++版本不匹配，接口层加载到旧动态库。解决：先确认环境变量有效：
echo $ACADOS_ROOT ldd ocp_acados_ocp.so | grep acados如果ldd显示not found，重新export并重开终端。这个问题看起来玄学，实际是动态库路径问题。
5.3 板上第一帧正常、后面卡死：动态内存分配惹的祸
现象：部署到RTOS目标板，冷启动第一帧能算出控制量，第二次调用solve时HardFault或卡死。原因：模板C代码默认会使用malloc/free分配部分内部缓冲区，RTOS堆配置不足，第一次运行后缓冲区未释放或内存碎片化。解决：检查生成的代码里是否包含ocp_nlp_solver_create中的malloc调用，在RTOS配置中放大堆，或者启用内存池模式并提前预热。更稳妥的做法是在工程中使用静态分配版本，把OCP_NLP_COMMON_WITH_MEM这类编译开关打开。在量产上，我宁可多占几百字节RAM，也不要隐藏的malloc。
5.4 QP频繁返回不可行：硬约束太苛刻
现象：solver返回STATUS_INFEASIBLE，但离线用SQP就能解出轨迹。原因：RTI每个周期只做一次线性化，把非线性避障约束在当前点线性化后，线性QP可能在预测时域后半段出现约束冲突；惯性更大的系统尤其明显。解决：给状态相关约束设置软约束，把con_h_expr改成代价项，或者扩大避障半径，留出线性化误差余量。建模时也要注意约束的方向：dist-r^2>=0写成lh=0、uh=1e4才是合理的，如果搞反了会整段轨迹穿过障碍但求解器还认为可行。
5.5 RTI轨迹比参考慢一个周期：把它当反馈控制器用
现象：在仿真中对比SQP和RTI，RTI的轨迹平滑且无越界，但整体落后参考轨迹一个采样周期。原因：RTI不给“全收敛”解，它把未收敛的残差留给下一次线性化去修正，反馈延迟是算法的内在代价，本身不是bug。解决：把采样周期缩短，或者把预测时域起点换成当前周期预测状态，不要用上一周期状态做rollout。实践中我会把N保持不小于系统主导时间常数的3倍，否则落后会更明显。
6. 验证与进阶：把acados真正“压榨”到极限的三步操作
6.1 用rti_phase区分仿真与实时模式
SQP_RTI并不是只能全程实时跑。acados的RTI分三个阶段：准备、反馈、展开，分别对应线性化/离散化、QP求解、状态响应更新。调试时把ocp.solver_options.rti_phase = 0可以让求解器执行完整的SQP迭代直到收敛，用于确认问题可解；确认后再切回RTI模式，观察闭环行为和离线求解是否接近。这个小开关是调试过程中最便宜的“后悔药”，强烈建议先跑一遍收敛模式再上实时。
6.2 量化单步耗时：从日志中定位瓶颈
部署时不建议只靠断点测时长。可以在每帧记录各阶段耗时，把线性化时间、condensing时间、QP求解时间分别打点。如果QP求解时间占比不高，瓶颈反而是雅可比计算模型太复杂，那就考虑降低模型复杂度或改用查表。如果第一步耗时稳定、后续几步波动大，多半是内存缓存命中率差异。把这个日志工具直接放进控制任务里，后面每次换目标板都能用。
| 阶段 | 典型耗时占比 | 优化方向 |
|---|---|---|
| 雅可比与模型求值 | 40% | 简化模型、查表 |
| condensing | 20% | 换部分凝结/完全凝结 |
| QP求解 | 35% | 调HPIPM容差与迭代上限 |
6.3 从硬约束到软约束的最后一个台阶
最后一个技巧是把避障、控制量饱和这类硬约束逐渐改成软约束。硬约束在QP里是可行域边界，线性化不确定时容易让整个QP不可行；软约束把违反量加权进代价，虽然不能保证绝对安全，但换来的是求解器在各个周期都不会失败。对安全关键项我习惯保留少量硬约束，比如控制量幅值，这是执行机构物理极限；而避障距离这类由传感器估计出来的量则用软约束，配合松弛因子，整个控制器健壮很多。做项目到现在，我每接手一个新的NMPC工程都会强制走一遍这个流程：先离线SQP确认可行，再切RTI看闭环延迟，最后把约束按层级拆成硬软两类，用这套顺序之后几乎没有再被求解器问题卡住过，希望帮到你。
本文还有配套的精品资源，点击获取
