Python aiida-firecrest 包详解与实战案例

1. 引言aiida-firecrest 是 AiiDA 生态中的一个插件包用于将 AiiDA 工作流引擎与 FirecREST 高性能计算网关对接。FirecREST 是欧洲多所超算中心如 CSCS提供的 RESTful API 网关它屏蔽了底层 SSH、作业调度系统Slurm、LSF 等的差异让用户通过统一的 HTTPS 接口提交作业、管理文件、查询资源。aiida-firecrest 让 AiiDA 的进程可以直接通过 FirecREST 在远程超算上执行从而把「计算任务调度」和「数据溯源管理」无缝衔接起来。本文将从功能特性、安装配置、核心语法与参数、9 个实际应用案例、常见错误与使用注意事项五个方面系统介绍 aiida-firecrest 包的使用方法。2. 功能概述aiida-firecrest 的核心功能可以概括为以下几点远程作业提交通过 FirecREST 网关向超算集群提交计算作业支持 Slurm、LSF、PBS 等主流调度系统。文件传输在本地与远程超算之间上传、下载文件支持递归目录操作。作业状态查询实时查询作业运行状态、退出码、资源占用等信息。计算资源发现自动发现远程集群的可用分区、队列、节点数等资源信息。与 AiiDA 数据溯源集成所有远程操作均记录为 AiiDA 的进程节点自动保存输入输出文件、参数和日志实现完整的可复现性。多集群支持可在同一 AiiDA 实例中配置多个 FirecREST 端点分别对接不同超算中心。3. 安装与配置3.1 环境要求aiida-firecrest 要求 Python 3.8 及以上版本并需要预先安装 AiiDA 核心版本 2.0 以上。建议使用虚拟环境如 conda 或 venv隔离依赖。3.2 安装步骤推荐使用 pip 安装pip install aiida-firecrest如果需要安装开发版本可以从 GitHub 仓库克隆后执行git clone https://github.com/aiidateam/aiida-firecrest.git cd aiida-firecrest pip install -e .3.3 初始化 AiiDA 与插件安装完成后需要先初始化 AiiDA 数据库再加载 aiida-firecrest 插件# 初始化 AiiDA 核心 verdi setup 重新加载插件 verdi plugin list aiida.firecrest确认插件加载成功后即可开始配置计算资源。3.4 配置 FirecREST 计算资源在 AiiDA 中远程超算被抽象为「计算资源Computer」。使用 verdi 命令创建 FirecREST 类型的计算资源verdi computer create -L mycluster -H firecrest.example.org --transportfirecrest --schedulerslurm mycluster其中-L指定标签-H指定 FirecREST 网关主机名--transportfirecrest表示使用 FirecREST 传输插件--schedulerslurm指定远程调度系统类型。创建后需要配置认证信息verdi computer configure firecrest mycluster配置向导会要求输入 FirecREST 的 base URL、机器名machine name、访问令牌token等参数。配置完成后可以测试连接verdi computer test mycluster4. 核心语法与参数4.1 传输插件参数aiida-firecrest 的传输层基于 FirecREST API主要参数如下参数名类型必填说明base_urlstr是FirecREST 网关的根地址如 https://firecrest.example.orgmachinestr是目标超算的机器名如 daint、pizdainttokenstr是访问 FirecREST API 的认证令牌timeoutint否请求超时时间秒默认 60poll_intervalint否作业状态轮询间隔秒默认 104.2 调度器参数调度器负责解析远程作业状态常用参数包括参数名类型说明scheduler_typestr调度系统类型如 slurm、lsf、pbsnum_cpus_per_machineint每个节点分配的 CPU 核数num_machinesint作业使用的节点数max_wallclock_secondsint作业最大运行时长秒queue_namestr目标队列或分区名称accountstr计费账户名4.3 代码Code配置在 AiiDA 中远程可执行程序被抽象为「代码」。创建 FirecREST 远程代码的语法verdi code create --labelmycode --computermycluster --remote-abs-path/path/to/executable --input-pluginfirecrest其中--remote-abs-path指定远程机器上可执行文件的绝对路径。4.4 Python API 使用示例在 Python 脚本中可以通过 AiiDA 的 API 直接提交作业from aiida.engine import run from aiida.orm import Code, Dict from aiida_firecrest.calculations import FirecrestCalculation 加载远程代码 code Code.get_from_string(mycodemycluster) 准备输入参数 inputs { code: code, parameters: Dict(dict{greeting: Hello, FirecREST!}), metadata: { options: { resources: {num_machines: 1, num_mpiprocs_per_machine: 1}, max_wallclock_seconds: 3600, queue_name: normal, } } } 提交计算 result run(FirecrestCalculation, **inputs) print(result)5. 实际应用案例5.1 案例一远程运行 Hello World这是最基础的入门案例验证 aiida-firecrest 能否在远程超算上执行简单命令。首先创建远程代码指向/bin/echo然后通过 Python API 提交from aiida.engine import run from aiida.orm import Code, Dict from aiida_firecrest.calculations import FirecrestCalculation code Code.get_from_string(echomycluster) inputs { code: code, parameters: Dict(dict{message: Hello from AiiDA via FirecREST!}), metadata: {options: {resources: {num_machines: 1}}} } result run(FirecrestCalculation, **inputs) print(result[stdout].get_content())运行成功后可以在 AiiDA 的进程列表中看到该作业的完整记录包括输入参数、输出内容和运行日志。5.2 案例二批量提交多个独立作业在材料科学中经常需要对同一结构进行多组参数扫描。利用 AiiDA 的 workchain 机制可以批量提交多个 FirecREST 作业from aiida.engine import WorkChain, run from aiida.orm import Code, Dict, Int from aiida_firecrest.calculations import FirecrestCalculation class BatchScan(WorkChain): classmethod def define(cls, spec): super().define(spec) spec.input(code, valid_typeCode) spec.input(parameters_list, valid_typelist) spec.outline(cls.submit_all) spec.output(results, valid_typelist) def submit_all(self): results [] for params in self.inputs.parameters_list: inputs { code: self.inputs.code, parameters: Dict(dictparams), metadata: {options: {resources: {num_machines: 1}}} } results.append(self.submit(FirecrestCalculation, **inputs)) self.out(results, results) 提交 10 组参数扫描 params_list [{temperature: i * 100} for i in range(10)] result run(BatchScan, codecode, parameters_listparams_list)5.3 案例三远程文件上传与下载aiida-firecrest 支持在本地与远程超算之间传输文件。以下示例演示如何上传输入文件并下载输出文件from aiida.orm import Computer, AuthInfo from aiida_firecrest.transports import FirecrestTransport 获取计算资源 computer Computer.collection.get(labelmycluster) authinfo AuthInfo.collection.get(computercomputer) 建立传输通道 with FirecrestTransport(authinfo) as transport: # 上传本地文件到远程 transport.put(/local/path/input.dat, /remote/path/input.dat) # 下载远程文件到本地 transport.get(/remote/path/output.dat, /local/path/output.dat) # 递归上传目录 transport.put(/local/dir, /remote/dir, recursiveTrue)5.4 案例四结合 Slurm 调度器提交并行作业对于需要多节点并行计算的任务可以在 metadata 中指定资源参数from aiida.engine import run from aiida.orm import Code, Dict from aiida_firecrest.calculations import FirecrestCalculation code Code.get_from_string(mpi_programmycluster) inputs { code: code, parameters: Dict(dict{input_file: input.dat}), metadata: { options: { resources: { num_machines: 4, num_mpiprocs_per_machine: 32, }, max_wallclock_seconds: 7200, queue_name: normal, account: project123, } } } result run(FirecrestCalculation, **inputs)该作业会向 Slurm 提交一个使用 4 个节点、每个节点 32 个 MPI 进程的并行任务。5.5 案例五工作流中动态生成输入文件在复杂工作流中往往需要根据前一步的输出动态生成下一步的输入。以下示例展示如何在 workchain 中动态写入远程输入文件from aiida.engine import WorkChain, run from aiida.orm import Code, Dict, SinglefileData from aiida_firecrest.calculations import FirecrestCalculation class DynamicInputWorkChain(WorkChain): classmethod def define(cls, spec): super().define(spec) spec.input(code, valid_typeCode) spec.input(base_parameters, valid_typeDict) spec.outline(cls.prepare_inputs, cls.run_calculation) spec.output(result, valid_typeDict) def prepare_inputs(self): # 根据 base_parameters 动态生成输入文件内容 content ftemperature {self.inputs.base_parameters[temperature]}\n content fpressure {self.inputs.base_parameters[pressure]}\n input_file SinglefileData.from_string(content, filenameinput.dat) self.ctx.input_file input_file def run_calculation(self): inputs { code: self.inputs.code, parameters: Dict(dict{input_file: input.dat}), input_file: self.ctx.input_file, metadata: {options: {resources: {num_machines: 1}}} } future self.submit(FirecrestCalculation, **inputs) self.out(result, future)/code/pre 5.6 案例六多集群资源调度 aiida-firecrest 支持在同一 AiiDA 实例中配置多个超算集群。以下示例演示如何根据任务类型选择不同的集群 from aiida.orm import Code 在不同集群上创建代码 code_cscs Code.get_from_string(programcscs_cluster) code_epfl Code.get_from_string(programepfl_cluster) 根据任务类型选择集群 def select_cluster(task_type): if task_type large_scale: return code_cscs # 大规模任务提交到 CSCS else: return code_epfl # 小规模任务提交到 EPFL 提交任务 code select_cluster(large_scale) inputs { code: code, parameters: Dict(dict{task: large_scale_simulation}), metadata: {options: {resources: {num_machines: 8}}} } result run(FirecrestCalculation, **inputs) 5.7 案例七作业状态监控与失败重试 在实际生产中作业可能因超时、资源不足等原因失败。以下示例展示如何监控作业状态并自动重试 from aiida.engine import WorkChain, run, while_ from aiida.orm import Code, Dict from aiida_firecrest.calculations import FirecrestCalculation class RetryWorkChain(WorkChain): max_retries 3 classmethod def define(cls, spec): super().define(spec) spec.input(code, valid_typeCode) spec.input(parameters, valid_typeDict) spec.outline( cls.submit_job, while_(cls.should_retry)(cls.resubmit_job), cls.finalize ) spec.output(success, valid_typebool) def submit_job(self): inputs { code: self.inputs.code, parameters: self.inputs.parameters, metadata: {options: {resources: {num_machines: 1}}} } self.ctx.job self.submit(FirecrestCalculation, **inputs) self.ctx.retry_count 0 def should_retry(self): if not self.ctx.job.is_finished_ok: self.ctx.retry_count 1 return self.ctx.retry_count lt; self.max_retries return False def resubmit_job(self): self.report(fJob failed, retrying ({self.ctx.retry_count}/{self.max_retries})) self.submit_job() def finalize(self): self.out(success, self.ctx.job.is_finished_ok) result run(RetryWorkChain, codecode, parametersDict(dict{task: heavy_job})) 5.8 案例八与数据溯源结合的可复现实验《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。