E3 验收记录#

学习首页 · PhysX 目录

任务：PhysX Atlas #4。交付：接触、求解器与力观测、原生 C++ 报告复制、中英文入口、课程/roadmap、源码地图与身份清单。

开始时已 fetch 核实实际 main 为 810f7b2361a97dafb3d4eb9db2643d316ec900c2，E1/E2 课程均已实际合入；#4 OPEN、无评论、无进行中 PR，工作树干净。从该基线创建 docs/e3-contact-solvers。本记录对应包含它的 Git 提交，不用文档自写 SHA 形成循环；远端发布状态由随后实际读回的 commit/Issue/PR 决定。

对照验收#

要求

对应交付

结论

A4 原生接触 API

第 2–3 节过滤/通知/CCD、contact/rest offset、Material/combine/柔顺、修改回调；第 7–8 节读回

固定源码课程完成；通知与物理运行未验收

B1 一步管线

第 1 节 NpScene、ScPipeline、CPU PCM/普通 narrow phase、CPU PGS/TGS/GPU context 分支与任务依赖

CPU 路径源码交付；GPU 内核未展开

B2 接触与组合律

第 3–4 节刚性/隐式柔顺、单位/假设、实际材料优先级、patch/strong/torsional friction

源码交付；保留刚柔混合 damping 注释/实现差异

B3 约束/求解

第 4–5 节 effective response、投影、articulation 树响应/CFM 与禁用 self-response 分支、block 布局、PGS/TGS 计数循环、缓存分层和终止

CPU 接触解法源码课完成；不虚构 residual tolerance 或全局矩阵分解

B4 积分与时间

第 5–6 节 position/velocity 阶段、motion velocity、quaternion、TGS h/N、外力开关、三种子步及解析阅读例

源码/公式交付；无稳定性、可微或性能实测

B5 观测与单位

第 7 节 normal/anchor/constraint 的区别、缺项/可用性、平均力与参考点转换

不把报告点冲量当完整 wrench；未运行传感器

原生片段/练习

C++ 复制函数；第 9 节误区；9 道有答案阅读题

无包装框架、无执行入口、无独立评分器

版本/导航

README 中英与正文返回 Sim Atlas；课程/roadmap/source map/manifest 同步

SDK 5.11 源码身份与历史 Isaac/UniSim binary 分开，#126 未知项不回填

源码解释和公式由作者自审，没有宣称独立 reviewer 批准。特别交叉核对：

  • 本版仅保留 patch friction；PGS 按轴、TGS 成对切向钳制。几何/PCM、strong friction 与本次累计冲量不是同一种缓存。

  • PGS 有约束路径至少一遍 velocity/writeback；TGS 用 position iteration 决定内部步长，velocity 阶段不再积分位姿。没有把迭代预算改写成残差容差。

  • 刚柔混合 damping 的实现取 MAX，与头文件概述的“柔顺侧”存在输入边界差异；此为源码观察，没有运行复现结论。

  • extractContacts 只生成法向冲量；friction anchor 有独立位置/冲量。CCD friction stream 缺失，纯 torsional row 没进入 anchor 点冲量；C++ 保留可用性，不把缺项标实测零。

  • Articulation 不能按独立刚体处理；也不能把理论交叉响应或存在的 scalar helper 当成当前 SIMD contact 路径。CFM 入口、尺度/响应缩放和实际分母已区分。

  • 单行冲量、隐式弹簧、恒加速度子步推导均标假设/单位；不冒充完整 CPU/GPU/宿主算法。

实际检查#

环境：Linux、Python 3.12.12、g++ 11.4.0。sources.json 累计 79 个固定源码文件，本项新增 21 个。逐文件下载/读取后用 Git blob 算法校验，并独立把 manifest 全部条目与官方同一提交的 Git tree 对照；不只让 manifest 与本地缓存互相自证。

C++ E3 片段使用的 31 个公开头文件按同一官方 tree/blob 验证。Linux 预处理不使用未公开的 Switch 平台头文件；没有下载或构建 SDK binary。新片段不是 Python，不需要添加 Python 运行案例。

仓库根目录命令（PHYSX_SOURCE 指向含 physx/include 的匹配固定源码树或核验缓存）：

git diff --check
python scripts/check_docs.py
python scripts/check_source_links.py --source-root "$PHYSX_SOURCE"
g++ -std=c++17 -DNDEBUG -fsyntax-only -Wall -Wextra \
  -I "$PHYSX_SOURCE/physx/include" examples/e3_contact_readback.cpp

结果：文档相对文件链接、79 个固定源码 blob 与 295 个源码链接的路径/行范围、空白检查通过；C++ 语法/类型检查退出码 0，无诊断。新文件纳入 staged diff 后再次检查空白与同一组检查。未改 CI 或检查脚本，没有放宽 gate。

源码链接检查只证明被引用行存在及文件身份，不能自动证明语义；语义由本次实际阅读另行核对。check_docs.py 不验远端锚点/浏览器效果，CI 仍仅跑它声明的文档检查。没有把本地 -fsyntax-only 称为链接成功、SDK 构建成功或物理运行成功。

未决与下一步#

未运行任何原生引擎、contact callback、资产、控制器、仿真实验、GPU、训练或基准。片段调用者仍负责 SDK 初始化/销毁、合法过滤、稳定 actor/shape 身份、removed flags、线程同步与完整事件聚合。报告可用性只证明 stream/flag 状态，不保证物理观测的完备或准确。

历史 Isaac Sim 5.1 / UniSim 1.7.10 内置 PhysX 身份与配置继续以 DexLab #126 的证据为准；本次没有尝试用源码默认值补齐。CPU 之外的逐路径实现、完整几何覆盖和宿主传感器仍需后续主题。建议下一项 E4 传感器/渲染，随后满足 E5 依赖；E6 需本项实际合入。复用 DexLab 实验在后续阶段，本项没有另建实验与评分系统。

课程来源 · GitHub · 许可