企业官网建设流程全解析

• 科研
• 科学计算
• 高性能计算

fix planeforce是 LAMMPS 中用于运动学约束的 fix 风格：它通过逐原子减去法向力分量，使指定原子组的所有受力都落在由一个法向量定义的平面内，从而让这些原子被"锁"在某个平面上运动。本文以官方文档 fix_planeforce.rst 为核心，完整讲解其语法、参数、物理含义与重启/输出行为，并结合 src/fix_planeforce.cpp 与 src/KOKKOS/fix_planeforce_kokkos.cpp 的源码实现、单元测试 展开分析，帮助你在分子模拟中正确使用这一约束工具。

命令语法与参数

官方文档给出的语法为：

fix ID group-ID planeforce x y z

各参数含义：

• ID、group-ID：fix 命令通用参数，ID是 fix 的标识符，group-ID指定受约束的原子组（ID/group-ID的通用语义见 fix 命令文档）；
• planeforce：该 fix 风格名；
• x y z：一个三维向量，作为约束平面的法向量。力在这个平面上的分量被保留，垂直于平面的分量被剔除。

文档给出的示例：

fix hold boundary planeforce 1.0 0.0 0.0

含义：对boundary原子组施加约束，法向量为 (1,0,0)，即约束平面为yz 平面，该组原子在 x 方向上的受力被全部消除。

工作原理：减去力的法向分量

文档描述部分指出：fix planeforce调整组内每个原子的受力，使得只有位于法向量 (x,y,z) 所定义平面内的力分量保留，做法是减去垂直于该平面的力分量。并且文档强调：如果原子的初始速度为 0（或本身位于平面内），那么此后它将持续在平面内运动。

从源码看，这一描述与实现完全对应。post_force()是核心，src/fix_planeforce.cpp 中的关键循环为：

for (int i = 0; i < nlocal; i++) if (mask[i] & groupbit) { dot = f[i][0] * xdir + f[i][1] * ydir + f[i][2] * zdir; f[i][0] -= dot * xdir; f[i][1] -= dot * ydir; f[i][2] -= dot * zdir; }

其中xdir/ydir/zdir是归一化后的法向量（见下文），dot即力向量在法向上的投影f·n，随后从三个分量中各减去dot * n_i，这正是向量投影公式f' = f − (f·n)n——标准的"去法向分量"操作。由于只保留mask[i] & groupbit的原子，约束只作用于指定原子组。

这里有一个值得注意的工程细节：它是直接修改力数组atom->f，而不是通过addpostforce()累加一个反作用项。因此：

• 该 fix 不存储任何全局或逐原子量，无法被 output 类命令访问（与文档"No global or per-atom quantities are stored"一致）；
• 它本质上是一种"力投影"，每步对总力做一次正交化，物理效果等价于施加了无限刚度的约束。

法向量的解析、校验与归一化

构造函数（src/fix_planeforce.cpp）对输入做了两层校验：

1. 参数个数：narg != 6时直接报错Illegal fix planeforce command，即必须恰好提供ID group-ID planeforce x y z六个 token；
2. 零向量拒绝：若sqrt(x²+y²+z²) == 0.0同样报错。法向量为零向量时无法定义平面，因此该检查是必需的。

随后法向量被就地归一化为单位向量（xdir /= len; ydir /= len; zdir /= len;）。这意味着你可以传入任意非零长度的法向量，例如fix hold boundary planeforce 2.0 0.0 0.0与1.0 0.0 0.0效果完全相同，投影计算只依赖方向。这一点文档没有明说，但源码可以确认。

另外，构造函数中设置了dynamic_group_allow = 1（src/fix_planeforce.cpp）。从Fix基类的默认值（dynamic_group_allow = 0，见 src/fix.cpp）可以推断：该 fix 明确允许其原子组在运行中动态变化（例如配合group ... sort或fix group/group等动态组机制），组内成员变化会即时影响受力投影的范围。

与积分器的对接：setmask、RESPA 与能量最小化

fix在 LAMMPS 中通过setmask()声明自己介入积分循环的哪些阶段。FixPlaneForce::setmask()（src/fix_planeforce.cpp）返回三个标志：

mask |= POST_FORCE; // 普通积分步：力计算完成、更新位置/速度之前 mask |= POST_FORCE_RESPA; // RESPA 多时间步积分 mask |= MIN_POST_FORCE; // minimize 能量最小化

这解释了文档 "Restart, fix_modify, output, run start/stop, minimize info" 一节的结论——该 fix 的力在minimize命令调用的能量最小化过程中同样生效。

setup()中的处理逻辑（src/fix_planeforce.cpp）进一步说明其对不同积分风格的支持方式：

• 若积分风格以verlet开头（含md、fix/extern之外的常规 MD），在 setup 阶段调用一次post_force()，投影基于当前力场即时生效；
• 否则（如 RESPA 多时间步），逐层遍历Respa积分器的每个层级，copy_flevel_f→post_force_respa→copy_f_flevel，对每一层的时间步长分别施加投影。

post_force_respa()内部直接转调post_force()（src/fix_planeforce.cpp），因此各层级执行的是同一套投影运算。

重启、fix_modify 与输出行为

官方文档明确列出了该 fix 在 LAMMPS 各类机制下的行为，全部可从源码印证：

• 二进制重启：不向 restart 文件写入任何该 fix 的信息。这是因为其全部状态只有三个归一化法向量分量，由输入脚本重建即可，无需持久化；
• fix_modify：fix_modify 的所有选项对该 fix 均无意义（它没有可修改的力场属性，也不是基于能量求力的风格）；
• 输出：它不存储任何全局或逐原子量，因此各种 output 命令（compute、dump、thermo等）都无法读取其内部数据。若需要监控约束效果，通常的做法是自行compute相关原子的坐标/速度分量来间接验证；
• run start/stop：该 fix 没有任何参数能配合 run 命令的start/stop关键字使用；
• minimize：如前所述，该 fix 产生的力约束在 minimize 调用的能量最小化中同样被施加（MIN_POST_FORCE掩码 +min_post_force()转调post_force()，见 src/fix_planeforce.cpp）。

加速器变体 fix planeforce/kk

文档开头声明：Accelerator Variant:planeforce/kk，即该 fix 提供 Kokkos 加速实现。按照 LAMMPS 加速器风格的通用规则（见 accel_styles.rst），带kk后缀的风格与不带后缀的版本功能等价、参数相同，结果在舍入误差范围内一致，属于 KOKKOS 包的一部分，需在构建时启用该包才可用；你也可以通过命令行-suffix开关或输入脚本中的suffix命令自动替换为加速风格。

Kokkos 实现位于 src/KOKKOS/fix_planeforce_kokkos.cpp，继承自FixPlaneForce，构造函数中设置kokkosable = 1以注册加速能力。其post_force()的流程是：

1. atomKK->sync(execution_space, F_MASK | MASK_MASK)——把力数组与组掩码同步到设备；
2. Kokkos::parallel_for对0..nlocal范围并行执行逐原子的投影运算（operator()内与 CPU 版公式完全相同，只是使用KK_FLOAT视图）；
3. atomKK->modified(execution_space, F_MASK)——标记力数组已被修改。

一个重要的适用前提：Kokkos 版的init()中有显式检查（src/KOKKOS/fix_planeforce_kokkos.cpp）：

if (utils::strmatch(update->integrate_style,"^respa")) error->all(FLERR, Error::NOLASTLINE, "Cannot (yet) use respa with fix planeforce/kk");

即planeforce/kk目前尚不支持 RESPA 多时间步积分，若积分风格以respa开头会直接报错。CPU 版planeforce则通过setup()的逐层循环支持 RESPA。因此如果你的工作流使用respa积分且希望用加速版，需要退回非/kk风格。

单元测试验证

仓库的 force-styles 单元测试框架中包含一个专门针对该 fix 的用例：unittest/force-styles/tests/fix-timestep-planeforce.yaml。其配置要点：

• 前置条件（prerequisites）：atom full与fix planeforce均已编译；
• 在通用测试流程末尾注入post_commands：

fix move all nve fix test solute planeforce 0.2 -0.2 0.0

• 使用的输入与体系文件为 in.fourmol（atom_style full的四分子体系，含 LJ 对势、谐波键/角/二面体）、coeffs.fourmol 和 data.fourmol；其中coeffs.fourmol定义了group solute molecule 1:2，fix test solute planeforce 0.2 -0.2 0.0即对溶质分子组施加法向量为 (0.2, −0.2, 0) 的平面约束。

该测试将加入 fix 后的位置/速度结果与基准数值（run_pos/run_vel，epsilon 5e-12）做比对，是验证planeforce力投影数值正确性的回归测试。

实用建议与限制

• 初始状态很关键：文档明确指出，只有当原子初始速度为 0 或本身位于平面内时，它才会"持续"在平面内运动。若初始速度含有法向分量，fix 只消除法向力，不直接改写速度，法向速度仍会保留（虽然不再增长）。因此正确用法是先用velocity/初始数据把组内原子的法向速度清零；
• 无限制、无默认值：文档 "Restrictions" 与 "Default" 两节均为none，该 fix 无特殊限制，也不存在默认行为或可选参数；
• 与同类约束搭配：文档 "Related commands" 关联了 fix lineforce——planeforce约束原子在平面内运动，lineforce则约束原子在直线上运动，两者可组合使用（如先 planeforce 定面，再 lineforce 定线），实现更严格的运动学约束；
• 组合约束示例：文档示例fix hold boundary planeforce 1.0 0.0 0.0常用于将边界原子限制在 yz 平面内，抑制其在 x 方向的漂移；对任意倾斜平面，只需按几何关系写出平面法向量即可，无需归一化（源码会自行归一）。

相关源码与文档路径

综上，fix planeforce是一个语义清晰、实现紧凑的力投影约束：语法固定为fix ID group-ID planeforce x y z，通过正交化去除法向力分量实现平面约束；它支持普通 MD、RESPA 与minimize，但不写重启信息、无输出量、不接受fix_modify选项；/kk加速版功能等价但暂不支持 RESPA。理解这些细节后，你可以在模拟中精确控制特定原子组的运动自由度。

• 科研
• 科学计算
• 高性能计算