Atomsk 原子编号匹配与周期边界
用实际32Cu构型演示一般乱序、周期边界和逐原子属性保留，说明原生命令的适用边界与可复现辅助操作。
阅读本篇目录
两个结构看起来相同，文件里的原子行序却可能不同。直接按行作位移差、传递逐原子属性或比较两帧时，应先建立对应关系。本例提供32原子FCC Cu构型、已知乱序和三个匹配流程；所有几何操作都已实际运行。
1. 先准备文件#
unzip atomsk-command-map-wave147-*.zip -d atomsk-examples
cd atomsk-examples
集群模块为 atomsk/0.13.1，实际为beta0.13.1，GFortran13.3、OpenMP、双精度与独立NetlibLAPACK/BLAS3.12.1。辅助流程使用 ase/3.29.0 的Python3.11.16、ASE3.29.0、NumPy2.3.5和SciPy1.17.1。包内脚本使用已分配范围内的1个CPU线程，无需GPU。
模型采用a=3.6Å的FCC常规晶胞，复制2×2×2得到32Cu；它是明确构造的几何模型，没有结构优化，也不是MD轨迹。乱序由固定种子147生成，原始排列在 NEW-INPUTS.json中。
直接做一般乱序匹配：
bash match.sh 1
head -n 12 helper-work/match-random-helper/matched.mapping.json
结果 matched.xyz采用扩展XYZ，行序对应参考结构；matched.mapping.json记录参考行到目标原始行的1起始编号、每对距离、输入输出哈希和实际库版本。目标坐标没有被改成参考坐标，只调整行序。
2. 为什么不只看equivalences提示#
原生命令的基本形式是：
atomsk --match-id reference.xyz target.xyz matched.cfg
本包第104例使用明确的倒序构型，实际可以恢复原行序：
bash run.sh 104
head -n 20 work/match-reversal-native/result.cfg
但在本次一般乱序模型中，当前版本虽提示32个equivalences，输出的32行顺序仍未对应参考。倒序恰好是自身的逆排列，不能用倒序例推断任意排列也一样。reference/native-limit-comparison.json保留这次真实对照的排列关系，不是可直接用于后续计算的匹配结果。
对一般乱序、跨周期边界和逐原子属性传递，建议使用本包明确的ASE/SciPy辅助流程。它不是Atomsk原生命令，也没有改变集群上的Atomsk程序。
3. 处理周期边界#
bash match.sh 2
head -n 16 helper-work/match-periodic-helper/matched.mapping.json
该例把目标结构实际平移 (0.11,-0.07,0.09)Å后折回7.2Å周期晶胞。所有原子的最小镜像距离应为：
sqrt(0.11^2 + 0.07^2 + 0.09^2) = 0.1584297952 A
靠近边界的原子，直接坐标差可能达到7.13Å左右，而实际最短周期距离只有0.15843Å。辅助脚本使用ASE的最小镜像距离，再按元素分别由SciPy进行一一指派；当前所测原生距离匹配不处理该周期折回情况。
4. 保留每个原子的所有属性#
bash match.sh 3
head -n 5 helper-work/match-auxiliary-helper/matched.xyz
该例附带人工跟踪列 aux_index、vx、vy、vz，用来检查属性是否随原子一起移动；这里的vx/vy/vz是示意标签，不是MD速度。匹配后的aux_index恢复为1000、1001……1031；其余三列也恢复与参考原子一一对应的数值。
传递辅助字段时本例使用扩展XYZ。若从其他程序导入CFG，应同时检查列名与数值，不只检查“文件能打开”。想删去一个字段，当前规范命令的实际例子为：
bash run.sh 106
其原生操作是：
atomsk decorated.xyz -remove-property aux_index result.cfg
本例结果不再包含aux_index，而vx/vy/vz及32个原子坐标仍保留。
5. 对自己的文件执行#
加载环境，在新的输出路径运行：
module load ase/3.29.0
python match.py reference.xyz target.xyz matched.xyz
脚本使用相同元素之间的最小平方距离全局指派，保持目标结构的坐标、晶胞、周期性和逐原子数组。输入须满足：原子数与组成相同、晶胞与PBC相同、1–1000个原子，默认对应距离不超过0.5Å；近邻存在歧义时会停止，不写出一个看似匹配的文件。
这提供的是 接近构型之间的几何对应。大幅扩散、同元素交换、反应、增减原子或相变中的真实历史ID，不能仅靠几何猜测；应在原模拟输出中保留ID。晶胞发生变化时也要先明确坐标变换，本脚本不会自动猜测晶胞关系。
6. 重算、看图与继续使用#
只分析包内附带的实际匹配结果：
bash analyze.sh
ls figures-reference
完整重跑全部原生与辅助例：
bash run-all.sh
完整重算的匹配检查在 analysis/MATCHING-CHECKS.json，新图在 figures/；参考分析对应 analysis-reference/与 figures-reference/。已有结果目录不覆盖，重跑使用新解压目录。其他命令按完整命令导航查找。