QE COUPLE:用C程序调用pw.x内核
用两个H2键长的实际SCF说明C2PW调用、MPI通信器、返回状态、库链接和Slurm运行。
阅读本篇目录
通常做材料计算,直接用pw.x即可。如果要把QE嵌入自己的程序,COUPLE提供了C/C++和Fortran调用入口。本篇写一个很小的C程序,读取标准QE输入,完成计算后返回C主程序,继续打印返回状态并结束MPI。
下载C源文件、CMake配置、两份结构输入和4次实际输出。本例链接已有QE 7.6 CPU库,编译环境为oneAPI2024.2、Intel MPI2021.13和MKL;兼容依赖包括ELPA、HDF5、Libxc及MBD。只编译自己的客户端,不修改或重编公共QE。
1. 先看结果#
unzip qe-COUPLE-H2-wave1173-*.zip
cd qe-COUPLE-H2
bash read.sh
bash plot.sh
cat analysis/QE-COUPLE-H2-energy.csv

| H—H键长/Å | C接口总能量/Ry | pw.x总能量/Ry |
|---|---|---|
| 0.74 | -2.24013385 | -2.24013385 |
| 1.00 | -2.20937506 | -2.20937506 |
这是两个固定结构、两种调用的4次SCF。能量在输出精度内一致;两个点不构成完整势能曲线,也不是结构优化结果。
2. 标准QE输入仍然需要准备#
inputs/H2-0p74/API/input.in:
&CONTROL
calculation='scf', prefix='H2', pseudo_dir='../../pseudo', outdir='./tmp'
/
&SYSTEM
ibrav=1, celldm(1)=12, nat=2, ntyp=1, ecutwfc=25, occupations='fixed'
/
&ELECTRONS
conv_thr=1.0d-8, mixing_beta=0.4
/
ATOMIC_SPECIES
H 1.00794 H.pz-vbc.UPF
ATOMIC_POSITIONS angstrom
H 0.0 0.0 -0.370000
H 0.0 0.0 0.370000
K_POINTS gamma
第二个结构把两原子的z改为-0.500000和0.500000 Å。每个结构的API与pw.x输入完全一致,各用自己的tmp目录。立方盒12 Bohr、25 Ry截断、Γ点、2个电子。准备脚本从官方站点下载本例H赝势并核对SHA256;正式精度需要增加盒子和截断能做收敛测试。
3. 完整C客户端#
src/client.c:
#include <mpi.h>
#include <stdio.h>
#include <string.h>
#include <libqecouple.h>
int main(int argc, char **argv) {
int status=-999, rank=0, finalized=0;
char input[81]="input.in";
MPI_Init(&argc,&argv);
MPI_Comm_rank(MPI_COMM_WORLD,&rank);
if(argc>1) { if(strlen(argv[1])>79) { MPI_Finalize(); return 64; } strcpy(input,argv[1]); }
if(rank==0) { printf("CLIENT_BEGIN API=%d INPUT=%s\n",QE_LIBCOUPLE_API_VERSION,input); fflush(stdout); }
c2libpwscf((int)MPI_Comm_c2f(MPI_COMM_WORLD),1,1,1,1,1,1,&status,input);
if(rank==0) { printf("CLIENT_RETURN STATUS=%d\n",status); fflush(stdout); }
MPI_Finalized(&finalized);
if(!finalized) MPI_Finalize();
if(rank==0) printf("CLIENT_DONE MPI_FINALIZED=1\n");
return status;
}
关键点有三个:先初始化MPI;用MPI_Comm_c2f把通信器转换成Fortran可接收的句柄;调用后检查status,再处理MPI收尾。接口有自己的并行参数,本例全部设为1,实际只运行一个MPI进程。
本版输入文件名在Fortran接口中长度为80,因此用当前目录的短文件名input.in。程序显式限制传入路径长度,避免长路径被截断。不要把“函数返回”理解成可以随意在同一进程里重复初始化整个QE环境。
4. 编译自己的客户端#
bash build.sh
ls build/qe-client
脚本相当于:
module load qe/7.6-8173m
cmake -S src -B build -DCMAKE_C_COMPILER=mpiicx -DCMAKE_Fortran_COMPILER=mpiifx
cmake --build build --parallel 1
CMake读取安装好的QE目标和兼容依赖。qe_couple提供包装入口,qe_pw提供PW计算例程。这里最终由Intel Fortran编译器链接运行库,而main来自C,所以需要-nofor-main,避免同时引入一个Fortran主程序。
src/CMakeLists.txt已给出完整依赖设置:
cmake_minimum_required(VERSION 3.24)
project(qe_couple_h2 LANGUAGES C Fortran)
set(QE_ROOT "/public/software/qe/7.6/8173m" CACHE PATH "QE library installation")
set(QE_DEPS "/public/software/qe/deps/7.6/8173m" CACHE PATH "QE compatible dependencies")
set(BLA_VENDOR Intel10_64lp_seq)
find_package(MPI REQUIRED COMPONENTS C Fortran)
find_package(OpenMP REQUIRED COMPONENTS Fortran)
find_package(LAPACK REQUIRED)
find_package(Libxc CONFIG REQUIRED PATHS "${QE_DEPS}/libxc/lib/cmake/Libxc" NO_DEFAULT_PATH)
find_package(HDF5 CONFIG REQUIRED PATHS "${QE_DEPS}/hdf5/cmake" NO_DEFAULT_PATH)
find_package(Mbd CONFIG REQUIRED PATHS "${QE_ROOT}/lib/cmake/mbd" NO_DEFAULT_PATH)
add_library(VendorFFTW INTERFACE IMPORTED)
set_target_properties(VendorFFTW PROPERTIES INTERFACE_LINK_LIBRARIES "LAPACK::LAPACK")
find_package(qe CONFIG REQUIRED PATHS "${QE_ROOT}/lib/cmake/qe" NO_DEFAULT_PATH)
add_executable(qe-client client.c)
target_include_directories(qe-client PRIVATE "${QE_ROOT}/include/qe/qe_couple")
target_link_libraries(qe-client PRIVATE qe_couple qe_pw MPI::MPI_C)
set_target_properties(qe-client PROPERTIES LINKER_LANGUAGE Fortran)
# Intel Fortran links the libraries; the program entry point is C main.
target_link_options(qe-client PRIVATE -nofor-main)
换到别的平台时,须使用与QE库兼容的编译器、MPI、整数接口和依赖;不能只把一个.a文件复制过去就假定可用。
5. 准备并通过Slurm运行#
bash prepare.sh
sbatch job.slurm
squeue -u "$USER"
tail -f slurm-作业号.out
模板为CPU分区、单MPI进程、单线程。内部实际命令分别是:
# 在各自的计算目录中执行
../../../build/qe-client input.in > native.out
pw.x -in input.in > native.out
客户端先写出CLIENT_BEGIN API=1,完成SCF后输出:
JOB DONE.
CLIENT_RETURN STATUS=0
CLIENT_DONE MPI_FINALIZED=1
最后两行来自我们自己的C主程序,可以确认控制流已经返回,而不是只看到QE结束提示。
6. 提取和继续开发#
bash read.sh work-new analysis-new
bash plot.sh analysis-new figures-new
读取脚本比较两个结构各自的接口与原生总能量,并检查返回状态和MPI结束顺序。自己的程序若要读取物理结果,可以按标准输出或QE保存数据的格式实现解析;本例接口本身没有凭空返回“能量数组”。C2CP和QMMM是另外的入口,其输入、通信和数据交换需求不同,不能把这份C2PW代码直接当成它们的运行示例。