PLUMED网格读取、插值和极值查询

已有一张函数网格时，可把它读回PLUMED，并在给定CV处查询数值。本篇选择函数已知的网格，方便把每个原生插值结果与独立解析式比较。

1. 下载与实际查询#

下载本篇完整输入、原生网格和绘图资料包，保存为example.zip：

python3 -m zipfile -e example.zip .
cd plumed-histogram-grid-examples
bash results.sh
bash read.sh
bash plot.sh

这些命令先读取已完成的实际结果；原生输出在reference-results/，CSV在data/，图在figures/。默认使用集群ASE环境Python，可用YS_ANALYSIS_PYTHON指定含NumPy、ASE和Matplotlib的解释器。

定义无量纲x为距离数值除以1 nm，函数f=(x−0.2)²−0.02，区间为0到0.5。本例只是数学网格，不是材料势能面或自由能面。

2. 网格文件是什么样#

head -n 12 inputs/reference-grid-extension/quadratic.grid

#! FIELDS x f df_x
#! SET min_x 0
#! SET max_x 0.5
#! SET nbins_x 100
#! SET periodic_x false
0 0.02000000000000001 -0.4
0.005 0.018025 -0.39
0.01 0.0161 -0.38
0.015 0.014225 -0.37
0.02 0.0124 -0.36
0.025 0.01062500000000001 -0.35
0.03 0.008900000000000005 -0.34

文件含坐标x、函数f及解析导数df_x，还有区间、网格间隔数与周期性。这里100个间隔对应101个节点，非周期边界。

当前读取器要求文件使用.grid后缀；本例采用简单文件名quadratic.grid。相同内容随意改成.dat会被这一入口拒绝，所以保留包中的命名。

3. 完整输入#

cat inputs/reference-grid-extension/plumed.dat

UNITS LENGTH=nm ENERGY=kj/mol TIME=ps
r: DISTANCE ATOMS=1,2 NOPBC
reference: REFERENCE_GRID FILE=quadratic.grid VALUE=f
value: EVALUATE_FUNCTION_FROM_GRID GRID=reference ARG=r INTERPOLATION_TYPE=spline
maximum: FIND_GRID_MAXIMUM ARG=reference NOINTERPOL
minimum: FIND_GRID_MINIMUM ARG=reference NOINTERPOL
maxvalue: CUSTOM ARG=maximum.optval FUNC=x PERIODIC=NO
minvalue: CUSTOM ARG=minimum.optval FUNC=x PERIODIC=NO
maxposition: CUSTOM ARG=maximum.x_opt FUNC=x PERIODIC=NO
minposition: CUSTOM ARG=minimum.x_opt FUNC=x PERIODIC=NO
PRINT ARG=r,value,maxvalue,minvalue,maxposition,minposition FILE=COLVAR STRIDE=1 FMT=%.14g
DUMPGRID GRID=reference FILE=reference.dat STRIDE=0 FMT=%.14g

REFERENCE_GRID读入函数与导数；EVALUATE_FUNCTION_FROM_GRID按本帧r查询，使用spline插值。这个已知二次函数便于检查插值与坐标单位，不能据此认定任意稀疏真实网格都能恢复原函数。

4. 极值输出与范围#

本例NOINTERPOL在实际网格节点中找极值，不进行连续最优位置搜索。最大值为0.07、位置0.5；最小值为−0.02、位置0.2，都与独立函数对应。

此2.10.1安装中，直接打印极值组件会遇到周期性元数据问题，输入用CUSTOM ... FUNC=x PERIODIC=NO把四个标量明确封装后再打印，数值不变。这个有正有负的参考函数已逐项核对；当前工具对正值密度网格的极小值曾给出0，不能直接套用到任意密度数据。

对密度文件，也可直接读实际网格求节点极值：

py=/public/toolkit/miniconda3/envs/ase-3.29.0/bin/python
"$py" - <<'PYCODE'
import numpy as np
a = np.loadtxt('reference-results/gaussian-kde-explicit-height/density.dat', comments='#')
for name, i in [('minimum', np.argmin(a[:, 1])), ('maximum', np.argmax(a[:, 1]))]:
    print(name, 'x =', a[i, 0], 'value =', a[i, 1])
PYCODE

该命令输出实际密度网格的节点极值，和连续函数的精确极值也要区分。

5. 运行与读取#

在新解压目录执行短串行driver：

bash run.sh
bash read.sh work analysis-new
bash plot.sh analysis-new figures-new work

环境使用CP2K2026.2依赖中的PLUMED2.10.1，run.py已设置相应程序和动态库路径。这些是坐标/网格处理，不做电子结构或MD积分。

head reference-results/reference-grid-extension/COLVAR
cat data/PLUMED-reference-grid-spline-queries.csv

本例33个查询时刻包含初始化帧和32个样本；原生spline值与独立二次函数最大差约4.58×10⁻¹⁶。换成自己的网格时，确认CV范围、周期性、节点顺序、导数列与文件数值一致，范围之外不要默认为有可靠外推。

读取器的文件命名和设置见PLUMED原生实现。