原生物质点法实现阅读指南

物质点法（Material Point Method，MPM）用粒子保存材料状态，在背景网格上 计算力和速度，再把结果传回粒子。这里的计算在 NovaPhy C++/CUDA 中执行。 Newton 指接口和算法对齐目标，不表示运行时调用 Newton 或 Warp。

后端名称与接口兼容

原生应变有限元后端统一使用 strain_fem：

• 头文件和源文件位于 novaphy/include/fluid/mpm/implicit/backends/strain_fem/ 和 novaphy/src/fluid/mpm/implicit/backends/strain_fem/。
• 装配等内部命名空间为 novaphy::mpm::implicit::strain_fem::cuda::launch。
• 文件名前缀 newton_fem_ 改为 strain_fem_；对应的 include 和构建清单同步迁移。

strain 表示应变，fem 是有限元方法（Finite Element Method）的缩写。 这个名称描述数值方法；Newton 的参考算法来源在注释和第三方声明中保留。

此次属于源码组织调整。现有 RheologyMode::NewtonFEM、NewtonFEM* 类型、 newton_fem_* 配置/函数与 --newton-fem-* 命令行参数继续保持兼容， Newton 对照场景也保持原名。它们的历史拼写不表示需要外部 Newton 运行时。 内部命名空间和头文件路径已变更，使用这些内部 C++ 接口的下游代码需更新 include、 限定名，并重新编译链接；不能混用迁移前后的二进制。

从哪里开始 review

入口	关注点
novaphy/src/fluid/mpm/implicit/solver_implicit_mpm.cpp	step 是 Python/C++ 公共状态边界；读取调用者输入、同步碰撞体、选择后端并输出材料历史。
novaphy/src/fluid/mpm/implicit/backends/strain_fem/implicit_mpm_strain_fem_cuda_world_int3.cpp	detail_advance_newton_fem_cuda_world_int3 串联稀疏网格 CUDA 计算；先粒子到网格，再装配与求解，最后网格到粒子和历史写回。
novaphy/include/fluid/mpm/implicit/backends/strain_fem/strain_fem_world_int3_context.h	区分求解器工作缓冲和从输入/输出 State 借用的设备数组；np、Va、A 分别是粒子、活跃节点、活跃单元数。
novaphy/include/fluid/mpm/implicit/backends/strain_fem/strain_fem_dense_state.h	restore_dense_warmstart / merge_dense_warmstart 按物理单元 ID 恢复/合并应力，避免把活跃数组的槽位误当作单元身份。
novaphy/include/fluid/mpm/implicit/backends/strain_fem/strain_fem_host_material_cache.h	材料缓存按内容比较；历史相关硬化不属于可直接复用的材料基础参数。
novaphy/include/fluid/mpm/implicit/backends/strain_fem/nodal_raster_cache.h	碰撞栅格化按批次查询和提交；调用者必须把影响结果的几何/配置纳入键。
novaphy/src/fluid/mpm/implicit/backends/strain_fem/p2g_compensated_grouped.cuh	每组八个 CUDA 线程准备粒子贡献，按既有顺序做 float32 补偿求和，保留舍入行为。
novaphy/src/fluid/mpm/implicit/backends/strain_fem/strain_fem_cuda_coupling_graph.cpp	内部材料/接触迭代图的捕获、复用和失败处理；含进程共享资源，不能据此宣称并发或外部整步捕获能力。
python/demos/mpm/newton_ref/grain_official.py	advance 在物理步和表面投影之后更新可视颗粒；原位推进仍需保存上一时刻的位置/变换。

状态与缓存

state_in 提供粒子位置、速度和材料历史；state_out 接收结果。 弹性变形 Fe、总变形 F、仿射速度梯度 C、塑性体积比 Jp 和应力 都影响后续计算，不能仅恢复位置速度来替代完整快照。

GPU 路径可能已经更新输出设备数组，但尚未同步 CPU 镜像。 host_dirty 表示这种同步状态，不表示输入数据可以被忽略。 原位推进时读写对象相同，因此写回前必须保护后续仍要读取的历史。 网格、材料和碰撞缓存用于减少重复准备；缓存命中不能代替输入 State 的有效性判断。

Delassus 缓存保存的是由柔度、粒子到网格的耦合系数和节点质量共同决定的 矩阵分解。粒子移动时，即使活跃单元集合不变，矩阵也可能变化；不能以 “热身若干步”作为必然命中的条件。重复同一完整输入快照可以验证缓存复用。 已有粒子的材料值不会随配置默认值自动改变；修改默认阻尼后，需要调用 solver.notify_model_changed(novaphy.solvers.SolverNotifyFlags.ModelProperties) 重新绑定材料。模型提供逐粒子材料列时，以模型中的值为准。

启用延迟同步时，run_implicit_mpm_steps 将结果发布到输出 State 的设备数组， 不主动拉回全部历史。读取 state.particle_q 只取得位置快照，求解器完整历史的 host_dirty 仍可为真；需要完整同步时显式调用 solver.sync_particles_to_world(state)。 同步前后，输出 State 的位置、速度及五类材料历史应保持一致。

投影坐标与碰撞距离单位

米制网格的粒子投影在局部坐标 x_local = x_world - domain_origin 中执行。 因此世界平面 n · x_world = offset_world 必须对应 offset_local = offset_world - n · domain_origin；密集驻留、稀疏驻留和回退路径 遵循同一换算，不能因开启 GPU 驻留而改变碰撞位置。

网格碰撞查询返回世界距离。转为归一化粒子坐标时，距离和穿入容差 0.01 * world_voxel_size 都必须除以同一个变换后的法线长度。 例如体素大小为 0.05 米时，容差为 0.5 毫米：1 毫米穿入应纠正至该容差内， 0.25 毫米穿入无需纠正；扩大计算域不会改变这个物理尺度。 解析平面的偏移和单位法向已经是局部坐标，因此还需将米制容差与碰撞厚度 一起乘以 |S⁻¹ n_local|，其中 S 是域各轴长度组成的对角矩阵。 该比例等于 1 / |S n_world|，也适用于非均匀域中的倾斜平面； 米制网格的比例为 1。平面单独换算，网格仍按各自查询法向转换，配置值不被改写。 例如厚度为 2 毫米、容差为 0.5 毫米时，应纠正到几何平面外 1.5 毫米处， 而不会随计算域扩大成 15 毫米。

回归测试覆盖 CPU、CUDA 临时缓冲、密集驻留及稀疏驻留四条路径， 包括 0.25 倍、单位、10 倍及非均匀域，水平/倾斜平面，零/非零厚度、 容差内外粒子、独立输入输出和重复投影。

名称对照

旧名称或术语	实际含义
M3b / m3b	开发里程碑 3b：逐粒子材料参数的多材料示例。区域是砂、雪、泥，以及可选静止粒子底层。新文件名使用 multi_material，旧 Python 符号保留兼容。
V	历史交付快照标签，不是算法、材料或 API 版本。
S20	历史优化步骤编号；此 PR 中指 Grain 场景原位推进，同时保留渲染历史、检查点恢复和双缓冲回退。
P24–P39	历史性能任务编号范围，不是用户配置。PR 中具体包含缓冲区/材料/网格缓存复用、设备驻留、分组粒子到网格计算、求解器数据布局和 CUDA Graph 复用等改动；编号本身不表示加速比例。
world_int3	用三个整数表示世界网格单元坐标。
P2G / G2P	粒子到网格 / 网格到粒子数据传递。
GS	Gauss–Seidel（高斯–赛德尔）迭代求解。
Q1 / S2	网格基函数选择：三线性 / 二次 serendipity（缩减节点的二次插值）。这些是数值方法名称，区别于历史任务编号。

推荐使用 --multi-material-profile、--multi-material-coordinate-frame、 --multi-material-dense-180k 和 --multi-material / --no-multi-material。 原 --m3b-*、--m3b / --no-m3b 仍是等价别名，不要求现有脚本立即迁移。 预设仍按原规则应用；例如 newton-world 预设会指定世界坐标和多材料场景。 单材料示例可使用 --multi-material-profile default --no-multi-material --material sand。

来源声明统一在根目录 THIRD_PARTY_NOTICES；完整 NVIDIA/Warp 许可正文 复用 vendor/warp_native/LICENSE.md，两者都随 wheel 分发。