1. 引言
aiida-cusp 是一个基于 AiiDA 工作流框架的 Python 包，用于自动化管理和运行 CUSP（Crystal Unfolding Software Package）晶体电子结构展开计算。它把 CUSP 的输入文件生成、任务提交、结果解析和数据库归档封装为可复现、可追溯的工作流，适合高通量计算和材料基因组研究。
本文将从功能特性、安装方法、核心语法与参数、9 个实际应用案例以及常见错误与注意事项五个方面，系统介绍 aiida-cusp 的使用方法。
2. 功能概述
aiida-cusp 的核心价值在于把 CUSP 计算纳入 AiiDA 的自动化管理体系中，主要功能包括：
- 输入文件自动生成：根据晶体结构、展开路径和计算参数自动生成 CUSP 所需的输入文件。
- 任务提交与监控：通过 AiiDA 的 daemon 机制提交本地或远程计算任务，并自动轮询状态。
- 结果解析与归档：计算完成后自动解析输出文件，提取能带、权重等物理量并存入 AiiDA 数据库。
- 工作流可复现：所有输入输出均以节点形式记录，支持完整的 provenance 追踪。
- 高通量扩展：可与 AiiDA 的 workchain 机制结合，实现批量材料筛选和参数扫描。
3. 安装方法
3.1 环境准备
aiida-cusp 依赖 Python 3.8 及以上版本，以及 AiiDA 核心包。建议使用 conda 或 venv 创建独立环境：
conda create -n aiida-cusp python=3.9 conda activate aiida-cusp3.2 安装 AiiDA 核心
pip install aiida-core3.3 安装 aiida-cusp
从 PyPI 安装稳定版：
pip install aiida-cusp或从 GitHub 源码安装最新开发版：
git clone https://github.com/your-repo/aiida-cusp.git cd aiida-cusp pip install -e .3.4 初始化 AiiDA 配置
verdi setup verdi daemon start4. 核心语法与参数
4.1 数据结构定义
aiida-cusp 定义了若干 AiiDA 数据类型，用于描述 CUSP 计算输入：
from aiida_cusp.data import CuspInputData, CuspStructureData 创建 CUSP 输入数据节点 cusp_input = CuspInputData() cusp_input.set_parameter("kpoints_path", "G-X-M-G") cusp_input.set_parameter("energy_window", [-2.0, 2.0])4.2 计算入口
通过 CuspCalculation 类提交计算任务：
from aiida_cusp.calculations import CuspCalculation from aiida.engine import run 构建计算节点 calc = CuspCalculation( structure=structure_node, parameters=cusp_input, code=code_node, ) result = run(calc)4.3 常用参数说明
| 参数名 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| kpoints_path | str | 高对称点路径，如 "G-X-M-G" | 无 |
| energy_window | list | 能量窗口范围 [Emin, Emax] | [-5, 5] |
| npoints | int | 路径上采样点数 | 100 |
| projection_type | str | 投影类型，可选 "orbital" 或 "atom" | "orbital" |
| spin_polarized | bool | 是否考虑自旋极化 | False |
| soc | bool | 是否考虑自旋轨道耦合 | False |
5. 9 个实际应用案例
5.1 案例一：单材料能带展开
对硅晶体执行标准能带展开计算：
from aiida.orm import load_code from aiida_cusp.data import CuspInputData from aiida_cusp.calculations import CuspCalculation code = load_code("cusp@localhost") structure = load_node("structure_si_pwscf") params = CuspInputData() params.set_parameter("kpoints_path", "G-X-W-K-G") params.set_parameter("npoints", 150) calc = CuspCalculation(structure=structure, parameters=params, code=code) result = run(calc) print("能带展开结果节点:", result["output_bands"].pk)5.2 案例二：合金无序体系展开
对 FeCo 无序合金的超胞计算结果进行展开，恢复有序晶胞的能带图像：
params = CuspInputData() params.set_parameter("kpoints_path", "G-H-N-G") params.set_parameter("projection_type", "atom") params.set_parameter("energy_window", [-3.0, 1.0]) calc = CuspCalculation(structure=supercell_structure, parameters=params, code=code) result = run(calc)5.3 案例三：表面态计算
对 Cu(111) 表面 slab 模型执行投影能带计算，识别表面态特征：
params.set_parameter("kpoints_path", "G-M-K-G") params.set_parameter("projection_type", "orbital") params.set_parameter("npoints", 200)5.4 案例四：自旋极化体系
对铁磁态 Ni 执行自旋分辨的能带展开：
params.set_parameter("spin_polarized", True) params.set_parameter("kpoints_path", "G-X-W-K-G")5.5 案例五：高通量参数扫描
使用 AiiDA 的 workchain 对多种晶格常数执行批量展开计算：
from aiida.engine import WorkChain, if_ class ScanWorkChain(WorkChain): @classmethod def define(cls, spec): super().define(spec) spec.input("structures", valid_type=list) spec.outline( cls.run_calculations, ) def run_calculations(self): for struct in self.inputs.structures: calc = CuspCalculation(structure=struct, parameters=self.inputs.params, code=self.inputs.code) result = run(calc)5.6 案例六：异质结界面态分析
对 MoS2/WSe2 异质结超胞执行展开，分析界面态在布里渊区的分布：
params.set_parameter("kpoints_path", "G-M-K-G") params.set_parameter("projection_type", "atom") params.set_parameter("energy_window", [-1.0, 1.5])5.7 案例七：缺陷体系展开
对含氧空位的 TiO2 超胞执行能带展开，观察缺陷态在带隙中的位置：
params.set_parameter("kpoints_path", "G-X-M-G") params.set_parameter("npoints", 180)5.8 案例八：拓扑材料表面态
对 Bi2Se3 薄膜执行展开计算，验证拓扑表面态的存在：
params.set_parameter("kpoints_path", "G-M-K-G") params.set_parameter("soc", True) params.set_parameter("energy_window", [-0.5, 0.5])5.9 案例九：机器学习数据集构建
批量生成多种材料的展开能带数据，用于训练机器学习模型：
from aiida.engine import submit for material in material_list: calc = CuspCalculation(structure=material.structure, parameters=params, code=code) submit(calc)6. 常见错误与使用注意事项
6.1 常见错误
| 错误现象 | 可能原因 | 解决方法 |
|---|---|---|
| ImportError: No module named aiida_cusp | 包未安装或环境未激活 | 确认 pip install aiida-cusp 成功，检查 conda 环境 |
| ValidationError: kpoints_path 格式错误 | 高对称点路径字符串不符合规范 | 检查路径格式，如 "G-X-M-G" 中字母需大写 |
| NotExistent: Code 节点未找到 | code 未在 AiiDA 中注册 | 使用 verdi code create 注册 CUSP 可执行文件 |
| 计算卡在 submitted 状态 | daemon 未运行或远程连接失败 | 执行 verdi daemon status 检查，重启 daemon |
| 输出文件解析失败 | CUSP 版本与解析器不兼容 | 检查 CUSP 版本，更新 aiida-cusp 或降级 CUSP |
6.2 使用注意事项
- 版本兼容性：aiida-cusp 对 CUSP 版本有要求，安装前确认 CUSP 版本在支持列表中。
- 结构文件格式：输入结构需为 AiiDA 支持的 StructureData 格式，建议从 PWscf 或 VASP 计算节点直接引用。
- k 点路径规范：不同晶系的高对称点名称不同，需参考晶体学标准，避免使用错误的路径标签。
- 资源管理：高通量计算时注意 daemon 的并发数限制，避免任务堆积导致超时。
- 数据归档：计算完成后及时导出结果节点，防止数据库膨胀影响查询性能。
- 自旋轨道耦合：开启 soc 参数时计算成本显著增加，建议先在小体系上验证。
7. 总结
aiida-cusp 将 CUSP 晶体展开计算纳入 AiiDA 自动化框架，显著提升了计算流程的可复现性和管理效率。通过本文的 9 个案例，读者可以覆盖从单材料能带到高通量扫描的典型应用场景。建议在实际使用中先从小体系验证参数设置，再逐步扩展到大规模计算。
《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。
