ARES 外部程序接口
CALYPSO
CALYPSO（Crystal structure AnaLYsis by Particle Swarm Optimization）是一种基于粒子群优化算法（PSO）的晶体结构预测方法， 由吉林大学的 Ma 和 Wang 团队开发。 该方法仅需给定化合物的化学组成，即可在特定外部条件（例如压力）下预测稳定或亚稳结构, 无需依赖任何已知结构或实验输入。CALYPSO 利用粒子群智能优化算法， 已被广泛应用于金属、半导体、氧化物、硫化物以及高压超导材料的结构预测研究。
ARES 提供了与 CALYPSO 的无缝接口，可直接对 CALYPSO 生成的候选结构进行高效的结构优化。 此外，ARES 支持基于 ACNN 机器学习势的主动学习流程，从而在保持高精度的同时大幅降低计算成本， 使其能够高效处理大体系或多组分材料的结构预测任务。
接口结构
接口模块位于 interface/ARES-CALYPSO 目录下，主要包含以下子模块：
SPLIT_ARES.sh：ARES 与 CALYPSO 交互的核心脚本，用于控制 CALYPSO 程序运行、多结构优化以及作业提交管理。acnn_deploy：主动学习工作流部署模块，实现机器学习模型训练、候选结构筛选及 DFT 验证的全自动工作流调度。interface/ss/：包含主动学习相关的模块化工具，以及实用的结构分析和 Slurm 任务检查脚本。
配置方法
软件已在 x86_64 Linux 平台上成功测试。
依赖项
Libtorch：（预编译 C++11 ABI 版本，以支持更广泛的平台）OpenBLAS：（用于 CPU 加速分子动力学模拟）[编译时使用 make USE_OPENMP=1]CUDA：（可选，用于 GPU 加速。可考虑同时安装 cuDNN）
解压 acnn-x.x.x.tgz，然后进入解压后的目录 acnn-x.x.x/：
$ tar -xvf acnn-v3.tar.gz
x acnn-v3/
x acnn-v3/CMakeLists.txt
x acnn-v3/README.md
x acnn-v3/al/
x acnn-v3/al/al-py/
...
x acnn-v3/src/utilities.h
x acnn-v3/src/utilsnnp.cpp
x acnn-v3/src/utilsnnp.h
$ cd acnn
修改 prefix.cmake 文件，以指定依赖包的路径。
# user modify
set(CUDA_TOOLKIT_ROOT_DIR /path/to/cuda) # optional
set(CMAKE_CXX_COMPILER /path/to/c++compiler) # required
set(Torch_DIR /path/to/libtorch) # required
set(OpenBLAS_DIR /path/to/openblas) # required
set(Python_EXECUTABLE /python/to/python3) # optional for python interface
set(pybind11_DIR /path/to/pybind11) # optional for python interface(see Python Interface)
执行以下复合命令以进行默认安装：
$ cmake -B build
$ cmake --build build --target acnn
可执行文件将位于 acnn/build 目录下。你可以考虑将该目录添加到系统的 $PATH 中。
$ export PATH=$(pwd)/build:$PATH
$ export PATH=$(pwd)/interface/ss:$PATH
要确认安装是否成功，请执行以下命令：
$ acnn
输出菜单将提供有关如何使用 acnn 进行模拟的说明。此外，程序将尝试创建一个输入控制文件模版。
备注
强烈建议使用 g++ 版本 9 或更高版本来编译 acnn。 其他编译器系列（例如 ifort）不受支持。
acnn_relax 用于大规模批量结构优化，采用在 ARES 中实现的 BFGS 算法。
$ cd acnn/interface/bfgs
$ cmake -B build
$ cmake --build build --target acnn_relax
$ export PATH=$(pwd)/interface/bfgs/build:$PATH
示例 1：ARES第一性原理结构预测
本小节介绍如何使用 ARES 结合 CALYPSO 进行基于 第一性原理 的晶体结构预测。 通常需要准备以下文件：
SPLIT_ARES.sh：ARES 与 CALYPSO 交互的核心脚本，用于控制 CALYPSO 程序运行、多结构优化以及作业提交管理。input.dat：CALYPSO 输入文件。*.upf：赝势文件。
以 SiC 体系为例（该示例已随软件一同发布，可供参考）：
$ ls
C_ONCV_PBE-1.2.upf SPLIT_ARES.sh Si_ONCV_PBE-1.2.upf input.dat
input.dat 文件内容如下
SystemName = Si-C
NumberOfSpecies = 2
NameOfAtoms = Si C
NumberOfAtoms = 1 1 # Si 1 C 1
NumberOfFormula = 1 4 # 1-4 fu
Volume = 48 # per formula
Ialgo = 2 # lpso
PsoRatio = 0.7
PopSize = 40
Command = pwd # do not matter
Isym = True
MaxStep = 0
Split = True # KEEP True
@DistanceOfIon
1.4 1.3
1.3 1.2
@End
SPLIT_ARES.sh 是程序运行控制文件，也是程序的输入文件，其用法如下：
Usage: ./SPLIT_ARES.sh [options]
Options:
-r Run program
-debug Enable debug mode
-help Show this help
Behaviors:
./SPLIT_ARES.sh Print parameters
./SPLIT_ARES.sh -r Run program (normal mode)
./SPLIT_ARES.sh -r -debug Run program in debug mode
./SPLIT_ARES.sh -help Print this help
-debug 模式可在每次结构优化过程中保存所有由 ARES 生成的文件，包括多级优化阶段的输入、输出及任务脚本等内容。
此外，用户需根据研究体系自行修改脚本头部的相关参数，主要包括：
SYSTEM="Si C" # system name
CALYPSO="~/bin/calypso_ares.x" # CALYPSO bin
STEP=20 # Max CALYPSO step
ARES="~/bin/ARES/ares" # directory of ares bin
PRESSURE="0" # in GPa
PSEUDO="Si_ONCV_PBE-1.2.upf C_ONCV_PBE-1.2.upf" # pseudo-potential
JOB_NAME="ARES-RELAX" # slurm job name
PARTITION="amd9654" # slurm partition
MAXJOB="4" # number of max `ares` jobs
然后修改 ARES_IN 文件中的计算精度和多级优化步骤次数：
ARES_IN=(
"\
#
INPUT_PARAMETERS
cal_type = cell-relax #relax
force_thr = 0.1
relax_method = bfgs
sym = 2
pseudo_rcut = 10
pseudo_mesh = 1
ecutwfc = 400
basis = pw
smearing = mp
sigma = 0.01
mixing_type = broyden
mixing_beta = 0.7
scf_thr = 1e-8
stress_thr = 1.0
pseudo_dir = .
pseudo_file = $PSEUDO
#isolver = dav
kpar = 4
kspacing = 0.2 # 1/bohr
pressure = $(echo "$PRESSURE * 10"|bc -l)
"
"\
#
INPUT_PARAMETERS
cal_type = cell-relax #relax
force_thr = 0.01
relax_method = bfgs
sym = 2
pseudo_rcut = 10
pseudo_mesh = 1
ecutwfc = 600
basis = pw
smearing = mp
sigma = 0.01
mixing_type = broyden
mixing_beta = 0.7
scf_thr = 1e-8
stress_thr = 1.0
pseudo_dir = .
pseudo_file = $PSEUDO
#isolver = dav
kpar = 4
kspacing = 0.14 # 1/bohr
pressure = $(echo "$PRESSURE * 10"|bc -l)
"
"\
#
INPUT_PARAMETERS
cal_type = cell-relax #relax
force_thr = 0.01
relax_method = bfgs
sym = 2
pseudo_rcut = 10
pseudo_mesh = 1
ecutwfc = 600
basis = pw
smearing = mp
sigma = 0.01
mixing_type = broyden
mixing_beta = 0.7
scf_thr = 1e-8
stress_thr = 1.0
pseudo_dir = .
pseudo_file = $PSEUDO
#isolver = dav
kpar = 4
kspacing = 0.14 # 1/bohr
pressure = $(echo "$PRESSURE * 10"|bc -l)
"
"\
#
INPUT_PARAMETERS
cal_type = cell-relax
force_thr = 0.01
relax_method = bfgs
sym = 2
pseudo_rcut = 10
pseudo_mesh = 1
ecutwfc = 600
basis = pw
smearing = mp
sigma = 0.01
mixing_type = broyden
mixing_beta = 0.7
scf_thr = 1e-8
stress_thr = 1.0
pseudo_dir = .
pseudo_file = $PSEUDO
#isolver = dav
kpar = 4
kspacing = 0.10 # 1/bohr
pressure = $(echo "$PRESSURE * 10"|bc -l)
"
)
这里采用四级结构优化方案，计算精度由低到高逐步提升，从而有效降低 ARES 在初始非平衡结构阶段的计算开销。
准备完毕后，执行以下命令启动结构预测过程：
$ ./SPLIT_ARES.sh -r
程序将自动迭代进行结构预测与优化。
结构预测结果可通过 CALYPSO-analyse-tool 进行分析:
$ cak.py
$ cat Analysis_Output.dat
No. Enthalpy 0.1
1 ( 187) -130.74141 F-43m(216)
2 ( 396) -130.60643 F-43m(216)
3 ( 615) -130.60533 F-43m(216)
4 ( 260) -130.60426 F-43m(216)
5 ( 184) -130.60302 P6_3mc(186)
6 ( 612) -130.59820 P6_3mc(186)
7 ( 238) -130.58654 I-4m2(119)
8 ( 412) -130.54539 P6_3mc(186)
9 ( 593) -130.49717 P4_2/mnm(136)
10 ( 278) -130.48836 C2(5)
11 ( 92) -130.44045 Cmc2_1(36)
12 ( 468) -130.36515 R3m(160)
13 ( 229) -130.27912 P3m1(156)
14 ( 63) -130.25170 P3_121(152)
15 ( 485) -130.25145 P3_221(154)
16 ( 123) -130.24996 P3_221(154)
17 ( 540) -130.24974 P3_121(152)
18 ( 318) -130.24876 R3m(160)
19 ( 33) -130.24221 R-3m(166)
20 ( 62) -130.22821 C2(5)
...
成功预测出 F-43m SiC
示例 2：ARES 结合 ACNN 主动学习实现结构预测
本小节提供了一个基于主动学习的晶体结构搜索示例，用于展示完整的工作流程，同时为类似任务提供参考。
在此示例中，我们在常压下对 C 进行主动学习结构搜索。
首先使用 acnn_deploy 进行工作流的部署，有关 acnn_deploy 的用法可通过执行程序获得：
$ acnn_deploy
.o. .oooooo. ooooo ooo ooooo ooo
.888. d8P' `Y8b `888b. `8' `888b. `8'
.8.888. 888 8 `88b. 8 8 `88b. 8
.8' `888. 888 8 `88b. 8 8 `88b. 8
.88ooo8888. 888 8 `88b.8 8 `88b.8
.8' `888. `88b ooo 8 `888 8 `888
o88o o8888o `Y8bood8P' o8o `8 o8o `8
Attention Coupled Neural Network
ACNN developer group (xieyu@jlu.edu.cn)
Copyright (c) 2022-2025
Please cite the following:
[1] J. Li et al., arXiv:2505.08159
Contact Prof. Yu Xie for support
Error: All options (--pressure, --seed, --minbonds, --partition, --backend) are required and must each appear only once.
Usage: acnn_deploy [OPTIONS]
Input target pressure[GPa] and seed
acnn_deploy -p 40 -s SrB -b Sr-Sr=2.075,Sr-B=1.671,B-B=1.267 -n amd9654 -e ares
options:
-p, --pressure [pressure] Target pressure in GPa
-s, --seed [seed] Seed name
-b, --minbonds [bonds] Set minimum bond distances (e.g., Sr-Sr=2.075,Sr-B=1.671,B-B=1.267)
-n, --partition [partition] Set partition
-e, --backend [FP backend] Set FP calculation backend (ares / vasp)
-h, --help, -? Print usage information and exit
$ acnn_deploy -p 0.0001 -s C -b C-C=1.2 -n amd9654 -e ares
$ ls
DFT PD POT RELAX RSS SEED XSF auto
某些文件（例如赝势文件和 DFT 计算输入文件）需要用户根据自身的具体计算需求进行相应修改，以满足个性化的计算设置。
ARES 输入文件
$ vi DFT/dyn_ares_in
25 TXT="\
26 # Generate by ACNN $(date)
27
28 INPUT_PARAMETERS
29 cal_type = scf #relax # cell-relax
30 #force_thr = 0.01
31 #stress_thr = 1.0
32 #relax_method = bfgs
33
34 sym = 2
35 pseudo_rcut = 10
36 pseudo_mesh = 1
37 ecutwfc = 1200
38 basis = pw
39 smearing = mp
40 sigma = 0.01
41 mixing_type = broyden
42 mixing_beta = 0.7
43 scf_thr = 1e-8
44 pseudo_dir = .
45 pseudo_file = $PSEUDO
46 #isolver = dav
47
48 kpar = 2
49 kspacing = 0.106 # 1/bohr
50 pressure = 0.001
...
Slurm 任务脚本
$ vi DFT/sub.sh
及赝势
$ ls DFT/*upf
DFT/C.upf
生成初始随机结构，准备好的结构应放置在 RSS/Base 目录中：
$ ls RSS/Base
C-2457776-286-1.res
C-2457776-286-2.res
C-2457776-286-3.res
C-2457797-283-1.res
C-2457797-283-2.res
C-2457797-283-3.res
ACNN 并不限制结构生成的来源，而只是对结构载体文件的格式作出严格规范。
运行工作流，一种有效的方式是根据个人偏好，使用 nohup 或 tmux 在后台运行程序：
$ tmux new -s C
$ ./auto > log 2>&1 &
$ ctrl+b d
$ tmux attach -t C
或者
$ nohup ./auto > log 2>&1 &
能量序列（单质）及相图（变组分）在 PD/ 目录中，以下是预测出的石墨、金刚石和六方金刚石结构图。
参考文献
Li et al., arXiv:2505.08159 (2025).