LAMMPS fix graphics/arrows 详解：用 dump image 在分子动力学图像中绘制向量箭头

fix graphics/arrows 是 LAMMPS GRAPHICS 包提供的可视化扩展命令，它允许在 dump image 渲染的图像中为原子或 chunk 添加箭头图形，用于直观展示每原子（per-atom）的偶极矩、受力、速度以及任意自定义向量属性，或每 chunk（per-chunk）的质心位移、角动量、偶极矩等向量数据。本文以 fix_graphics_arrows.rst 为核心，结合 fix_graphics_arrows.cpp 源码与相关文档，完整讲解命令语法、五种绘图模式、与 dump image 的协作方式及底层实现原理，读者阅读后可直接在自己的输入脚本中复现粒子偶极、速度场、分子偶极矩等向量可视化方案。

命令语法与参数总览

fix graphics/arrows 的完整语法如下：

fix ID group-ID graphics/arrows Nevery mode keyword args ...

各部分的含义：

• ID, group-ID：与所有 fix 命令 相同的通用参数。其中 group-ID 指定要显示属性的原子组，可以是动态组（dynamic group），从而支持随时间变化的原子集合（如通过 group ... region 动态划分的组）。
• graphics/arrows：该 fix 的样式名。
• Nevery：每隔多少个时间步更新一次箭头图形数据。必须与对应的 dump image 命令中的 N 参数保持一致，LAMMPS 会在两者设置不兼容时报错停止。
• mode：绘图模式，取值为 dipole、force、velocity、variable、chunk 之一，各模式的参数见下文。
• keyword = autoscale（可选）：自动缩放箭头，使其平均长度达到给定值 value。

从源码 fix_graphics_arrows.cpp 可以看到，Nevery 通过 utils::inumeric 解析且必须大于 0，同时该 fix 声明了 global_freq = nevery、dynamic_group_allow = 1、scalar_flag = 1，即它支持动态组、按 Nevery 周期执行，并输出一个全局标量（当前缩放系数）。此外，setmask() 只注册了 END_OF_STEP 回调（fix_graphics_arrows.cpp），意味着箭头数据在每个积分步结束时刷新。

五种 mode 及其参数

mode	参数	说明
dipole	scale radius	绘制每原子偶极矩向量，scale 为长度缩放因子，radius 为箭头半径（长度单位）
force	scale radius	绘制每原子受力向量
velocity	scale radius	绘制每原子速度向量
variable	xval yval zval radius	用三个常量或变量构造自定义向量
chunk	chunk-ID pos-ID vec-ID scale radius	绘制每 chunk 的向量数据

对于 dipole、force、velocity 三种模式，参数含义一致：

• scale：向量长度缩放因子。应选择使「scale × 每原子向量模长」与原子坐标量级相当的值，这样箭头在图像中才能清晰可见。在 variable 与 chunk 模式中由 scale 参数或 autoscale 关键字确定。
• radius：箭头宽度（渲染半径），单位为长度单位，源码中要求必须 > 0（见 fix_graphics_arrows.cpp 等处的错误检查）。

variable 模式的细节

xval、yval、zval 定义自定义向量的三个分量，可由数字常量或 atom-style / equal-style 变量（见 variable 命令）构成：

• 若某个分量是变量，需写成 v_name 形式，其中 name 是变量名。
• 变量每个时间步都会被求值一次，其值用于定义每个原子的箭头。
• 由于变量可以引用 compute、fix、自定义每原子属性（fix property/atom） 以及其他变量，因此几乎可以构造 LAMMPS 中任意每原子属性的箭头。

源码中的解析逻辑（fix_graphics_arrows.cpp）证实了这一点：每个分量参数若以 v_ 开头则被识别为变量名并设置 varflag，否则解析为普通数值；在 init() 阶段（fix_graphics_arrows.cpp）会校验变量确实存在且是 atom-style 或 equal-style，否则报错。

chunk 模式的细节

• chunk-ID：compute chunk/atom 命令的 ID（见 compute chunk/atom 文档）。chunk 是原子集合，LAMMPS 提供多种 per-chunk compute 来计算它们的属性，可参考 Howto chunk 了解如何定义 chunk 并度量体系属性。
• pos-ID：一个 per-chunk compute 的 ID，用于提供箭头位置。最常用的是 compute com/chunk（针对"可移动"的分子类 chunk）或 compute property/chunk（针对空间分箱类 chunk）。
• vec-ID：一个 per-chunk compute 的 ID，用于提供箭头向量。
• 两个 per-chunk compute 都必须返回至少 3 列的全局数组，且只使用前三列；若 compute 计算的是张量，则只使用其迹（trace）。

当前与 chunk 模式兼容的 compute 包括：

• compute angmom/chunk
• compute com/chunk
• compute dipole/chunk（含 dipole/tip4p/chunk）
• compute gyration/chunk（可带 tensor 关键字）
• compute gyration/shape/chunk
• compute inertia/chunk
• compute msd/chunk
• compute omega/chunk
• compute property/chunk（需带 coord1 coord2 coord3 参数）
• compute reduce/chunk（需三个及以上属性）
• compute torque/chunk
• compute vacf/chunk
• compute vcm/chunk

源码在 init() 中（fix_graphics_arrows.cpp）会逐一校验 chunk/atom compute 与两个 per-chunk compute 是否存在，并要求它们 array_flag 为真且列数不少于 3，不满足时报 "not compatible" 错误。

官方示例

示例一：最简用法

fix vec all graphics/arrows 10 velocity 20.0 0.066 autoscale 0.5

每 10 步为所有原子绘制速度箭头，初始缩放因子 20.0、箭头半径 0.066，并启用 autoscale 使箭头平均长度为 0.5。

示例二：variable 模式

fix vec all graphics/arrows 100 variable v_xnorm v_znorm 0.0 0.066

每 100 步用变量 v_xnorm、v_znorm 和常量 0.0 构成向量绘制箭头。

示例三：chunk 模式

fix vec all graphics/arrows 100 chunk molchunk com dip 1.0 0.05

每 100 步以 molchunk（分子 chunk）的质心为箭头起点（com），以分子偶极矩（dip）为向量，缩放 1.0、半径 0.05。

示例四：点偶极子（来自 examples/dipole）

examples/dipole/in.dipole 中的偶极子体系是一个完整的二维点偶极子算例（atom_style hybrid sphere dipole），其被注释掉的绘图片段展示了完整的箭头可视化配置：

variable dumpfreq index 250
fix      arrows   all graphics/arrows ${dumpfreq} dipole 1.2 0.15
dump     viz      all image ${dumpfreq} dipole-2d-*.ppm type type atom no &
                      size 600 600 zoom 1.8 shiny 0.2  fsaa yes ssao yes 31257 0.3 &
                      box yes 0.015 fix arrows const 0 0  center s 0.5 0.5 0
dump_modify  viz pad 6 fcolor arrows steelblue ftrans arrows 1

这段脚本用 dipole 模式在 2D 偶极子体系中渲染每个粒子的偶极矩箭头，并将箭头颜色设为 steelblue、完全不透明。上图即为该算例的渲染结果。

与 dump image 的集成：fix 关键字与样式控制

fix graphics/arrows 设计上就是与 dump image 的 fix 关键字配合使用。dump image 的 fix 关键字格式为：

fix fixID color fflag1 fflag2

• fixID：提供图形对象的 fix 的 ID（此处即 graphics/arrows 的 fix ID）。
• color：颜色样式，可取 type、element 或 const。使用 type 或 element 时箭头默认采用与对应原子类型相同的颜色；使用 const 时默认颜色为白色，可通过 dump_modify fcolor 修改。
• fflag1、fflag2：由 fix 定义含义的两个数值标志（见 dump_image.rst）。

对于 graphics/arrows：

• fflag1 用于调整箭头长度。由于长度已由该 fix 的 scale/autoscale 设定或计算，应将其设为 0.0。
• fflag2 用于调整渲染箭头的半径。由于半径本身就是该 fix 的输入参数，建议也设为 0.0。

颜色与透明度：dump_modify fcolor / ftrans

• dump_modify fcolor fixID color：在使用 const 颜色样式时，为 fix 提供的图形对象设置颜色。颜色名可以是 140 种预定义颜色之一，也可以是 dump_modify color 自定义的颜色（dump_image.rst）。
• dump_modify ftrans fixID transparency：设置 fix 图形对象的透明度，取值 0.0（完全透明）到 1.0（完全不透明），默认 1.0；与 fsaa on 组合使用时推荐 0.25、0.5 或 0.75（dump_image.rst）。

综合示例（来自 Howto viz）

Howto_viz.rst 给出了一个同时展示每原子速度箭头、每分子偶极矩箭头以及体系总偶极矩对象的高级示例：

compute molchunk all chunk/atom molecule
compute cpos all com/chunk molchunk wrap yes
compute cdip all dipole/chunk molchunk
fix vel all graphics/arrows 10 velocity 50.0 0.066 autoscale 0.25
fix vec all graphics/arrows 10 chunk molchunk cpos cdip 3 0.1

compute dip all dipole
variable scale equal 0.75
variable dip1x equal -v_scale*c_dip[1]
variable dip1y equal -v_scale*c_dip[2]
variable dip1z equal -v_scale*c_dip[3]
variable dip2x equal v_scale*c_dip[1]
variable dip2y equal v_scale*c_dip[2]
variable dip2z equal v_scale*c_dip[3]
fix dipole all graphics/objects 1 arrow 1  v_dip1x v_dip1y v_dip1z v_dip2x v_dip2y v_dip2z 0.3 0.2

dump viz all image 100 image-*.png element type size 600 600 zoom 1.3 view 70 20 shiny 0.1 &
             bond atom 0.2 box yes 0.025 axes no 0.0 0.0 center s 0.5 0.5 0.5 fsaa yes &
             fix dipole const 0 0 fix vec const 0 0 fix vel const 0 0 ssao yes 315465 0.8
dump_modify viz pad 6 boxcolor white backcolor gray element O H  bdiam 1 0.2 &
             adiam 1 0.5 adiam 2 0.3 acolor 1 silver acolor 2 red fcolor vec goldenrod &
             fcolor dipole forestgreen ftrans dipole 0.75 fcolor vel cyan ftrans vel 0.5

要点：

• fix vec 用 chunk 模式以分子质心为起点绘制分子偶极矩箭头；fix vel 用 velocity 模式加 autoscale 0.25 绘制速度箭头。
• dump 命令通过 fix dipole const 0 0、fix vec const 0 0、fix vel const 0 0 一次性叠加三类图形对象。
• dump_modify 用 fcolor/ftrans 分别为不同 fix 的箭头着色并设置透明度（如总偶极绿色且 0.75 透明、速度青色且 0.5 透明）。

autoscale 自动缩放与全局标量输出

可选的 autoscale value 关键字让 fix 动态计算 scale，使箭头平均长度恰好等于 value。自动算出的缩放系数 = value 除以所选向量属性的平均模长。

• 该 fix 会计算一个全局标量，代表当前显示箭头的缩放系数，可被各种 输出命令（如 thermo、print、dump 等）作为全局标量访问。
• 若未使用 autoscale，该标量就是命令中设定的 scale 值，默认 1.0。
• 该标量是 "intensive"（强度量）。

源码实现细节（fix_graphics_arrows.cpp）：在 end_of_step() 中，首先对每个本地位移原子累加向量模长（MathExtra::len3），然后通过 MPI_Allreduce 跨所有进程求和并除以总原子数得到平均长度，最后 scale = autovalue / average_length；若平均长度为零则回退为 1.0。compute_scalar()（fix_graphics_arrows.cpp）直接返回当前的 scale 供输出命令使用。

底层实现：数据流与渲染参数

从源码可以还原箭头数据的完整生成流程：

1. 收集阶段：end_of_step() 在每个积分步结束时重建 imgobjs 与 imgparms 数组（fix_graphics_arrows.cpp）。每条记录包含 10 个参数：原子类型、箭头起点坐标（x、y、z）、向量分量（3 个）、scale、2.0 * radius 以及固定值 0.2（fix_graphics_arrows.cpp），并标记为 Graphics::ARROW 图元。
2. 模式分支：
   • dipole 直接取 atom->mu 数组（要求原子具有偶极属性，即 atom_style dipole 或包含它的 hybrid 样式，见 atom_style 文档）；
   • force 取 atom->f，velocity 取 atom->v；
   • variable 通过 input->variable->compute_atom()（atom-style）或 compute_equal()（equal-style）求值各分量；
   • chunk 调用 cchunk->setup_chunks() 确定 chunk 数，并强制调用 cpos->compute_array() 与 cvec->compute_array() 获取位置与向量数组。
3. 与 dump 协作：fix 通过 image() 方法（fix_graphics_arrows.cpp）把 imgobjs、imgparms 与对象数量交给 dump image 渲染，这正是 dump image ... fix ID color fflag1 fflag2 所消费的数据。

需要特别注意的是，数据收集被推迟到 setup() 阶段（fix_graphics_arrows.cpp）以保证被引用的力、compute 与变量均已就绪；在 variable 或 chunk 模式下还会用 modify->clearstep_compute() / addstep_compute() 管理 compute 的求值时机，确保每个输出时间步都能取到最新数据。

限制与注意事项

• 包依赖：该 fix 属于 GRAPHICS 包，只有以该包编译的 LAMMPS 才可用，参见 Build package。
• dipole 模式：要求使用 atom style dipole 或包含 dipole 的 hybrid 原子样式；源码中通过 atom->mu_flag 检查并在缺失时报错（fix_graphics_arrows.cpp）。
• Nevery 一致性：fix 的 Nevery 必须与 dump image 的 N 一致，否则 LAMMPS 报错停止。
• 重启文件：该 fix 不向二进制重启文件写入任何信息。
• fix_modify：没有任何 fix_modify 选项适用于该 fix。
• 张量处理：在 chunk 模式中，若 per-chunk compute 输出的是张量，只使用其迹的前三个相关值；所有兼容 compute 均需提供至少 3 列数据。

相关命令

• fix graphics/chunk
• fix graphics/labels
• fix graphics/isosurface
• fix graphics/lines
• fix graphics/objects
• fix graphics/periodic
• fix graphics/replica
• compute hbond/local
• dump image

默认情况下 autoscale 关闭。完整的 GRAPHICS 可视化命令清单及更多应用示例可查阅 Howto viz 一节。