SymForce 官方项目横幅

SymForce

Stars

面向机器人系统的高性能符号计算、代码生成与非线性优化库,将 Python 中的几何和符号模型转换为可部署的 C++、Rust 等运行时代码,并服务于 SLAM、计算机视觉、运动规划和自主系统。

Symbolic ComputationCode Generation · OptimizationPython · C++ · Rust
SYMBOLIC CODEGEN · RUST TYPE SYSTEM

六个元素,不代表它就是六维向量

生成代码不仅要保留数值,还必须把符号矩阵的行列结构带进目标语言的静态类型。

SYMBOLIC RETURN · MATRIX23
123456
ROWS2×COLS3
SHAPE · 2 × 3
BEFORE · ELEMENT COUNT ONLYSVector<f64, 6>
142536
ROWS ?COLS ?
2 × 3 → 6 × 1
AFTER · SHAPE-AWARE FORMATTER
rows == 1
or cols == 1?
NO
SMatrix<f64, 2, 3>
RETURN SIGNATURECONSTRUCTOR
2 BACKENDS · CARGO BUILD ✓
形状丢失

2×3 被压平成 SVector<6>

Rust codegen 的单返回值路径把所有 `Matrix` 都格式化为 `nalgebra::SVector<scalar, rows × cols>`。这虽然保留了元素数量,却丢失二维形状:`Matrix23` 的函数签名和构造器都会变成 `SVector<f64, 6>`,调用方在 Rust 类型系统中再也看不到 2 行、3 列的矩阵语义。

类型语义

元素数量不能替代行列维度

元素数量相同不等于类型等价,`2×3`、`3×2` 与 `6×1` 必须拥有不同的静态形状。项目的多输出路径已经用 `format_typename` 正确区分向量和矩阵,因此单返回值不应另写一套压平规则;同时,返回签名与实际构造器必须复用同一个判断,否则生成代码仍会出现类型不一致。

路径统一

签名与构造器共享 shape-aware formatter

在单返回值模板的两处关键位置——函数返回类型和返回值构造器——把 `format_vector` 统一替换为现有的 shape-aware `format_typename`。新增非方阵 `Matrix23` 回归,让 SymEngine 与 SymPy 两个后端都生成并编译 `SMatrix<f64, 2, 3>`;原有 `Matrix31` 则继续保持 `SVector<f64, 3>`。

回归边界

矩阵恢复形状,向量保持原行为

修复关闭 #439,并由维护者 Aaron Miller 批准后以作者为 Zhewen Tan 的上游提交 `6582930` 进入 `main`,提交正文明确关闭 PR #467。全部 29 项检查完成,其中 28 项成功、1 项发布任务按条件跳过;覆盖 Python 3.10–3.14、GCC、Clang、macOS、x86_64 与 aarch64 wheel 构建。

SymForce 官方符号计算、代码生成与优化架构图
官方架构图展示了 SymForce 的完整数据链:符号工具箱建立几何与用户函数,Codegen 将同一模型生成面向运行时的代码,再把残差和导数交给 C++ 或 Python 优化器。本次修复位于中间的 Rust 代码生成边界,确保符号矩阵的行列结构能够准确进入 nalgebra 静态类型。