4.2 节点文件格式

4.2.1 node.json

本节点的所有配置说明、测试用例等，均集成于 node.json 文件中，您可以通过该文件来学习和配置您用于输入的计算节点。

{
    "id": "684bee08-a78d-4b1f-87a8-91910ca81f38",
    "name": { "cn": , // 前端显示名称，可缺省
              "en": "Hartree-Fock (PySCF)"},
    "version": "1.0.0",
  
    "input":{
        "upstream":[ // 修改名称
            {"var": "struc",  // 变量名 与config.json和main.py一致
             "name": { "cn": , // 前端显示名称，可缺省
                       "en": "structure"},
             "description": "分子结构"}, // 描述
        ],
        "web":[ // 修改名称
            {"var": "basis", 
             "name": { "cn": "原子基组",
                       "en": "atomic basis"},
             "description": "选择原子基组",
             "ui": {"options": ["sto3g", "631g", "ccpvtz"]}}, // 前端输入样式
            {"var": "unit", 
             "name": { "cn": "坐标单位",
                       "en": "coordinate unit"},
             "description": "读入坐标单位",
             "ui": {"options": ["Å", "Bohr"]}},
        ]
    },
    "output":{
        "downstream":[
            {"var": "scf_obj", 
             "name": { "cn": "scf对象",
                       "en": "scf object"},
             "description": "计算对象，来自于pyscf的内部结构，保存了轨道信息"},
            {"var": "ene", 
             "name": { "cn": "能量",
                       "en": "energy"},
             "description": "RHF能量"},
        ],
         "web":[
            {"var": "ene", 
             "name": { "cn": "能量",
                       "en": "energy"},
             "description": "RHF能量",
             "ui": {"plain_text"}} // 前端输出样式

            // 需要确认中间层和前端的交互方式是否能直接传递变量。
        ]
        
       		
    },
    "performance_config_path": "/app/PySCF-HF/performance_config.json",
    "example_config_path": "/app/PySCF-HF/example/test_config.json",
    "contact": {
        "name": "微观纪元量子化学团队",
        "email": "wuchuixiong@miqroera.com",
    },
    "execution_command": "python /app/PySCF-HF/script/main.py  --config_path ${input_config_path}" // 必须囊括 ${input_config_path} 变量
} 

下列表格详细解析了 MiqroForge 系统中节点配置文件的结构与内容。作为确保计算节点正确部署、初始化及高效运行的核心组件，这些配置文件为用户提供清晰的指引：明确各项配置项的含义、数据类型、默认值及是否必需，通过示例配置方案帮助用户根据实际需求进行精准配置。

基本信息

字段名	类型	必填	描述	约束/选项	示例值
id	string	是	节点全局唯一标识符，在初始化节点时自动生成	UUID格式	684bee08-a78d-4b1f-87a8-91910ca81f38
version	string	是	节点版本号	语义化版本	1.0.0
description	string	否	节点功能描述	≤200字符	读取XYZ分子结构，执行HF计算

输入/输出配置 (inputs/outputs)

上图为 PySCF-HF 节点的输入输出流程示意图，节点输入包含上游输入和webUI输入，上游输入表示来自前节点的数据流，webUI输入表示通过webUI输入/上传的数据，输出也采用同样的方式。

1. 上游输入：（upstream）

字段名	类型	必填	描述	约束/选项
var	string	是	字段标识	小写蛇形命名
name	string	否	数据类型
description	string	否	字段描述	输入描述

2. webUI输入 (web)

其他均与upstream一致，仅强调ui一项

字段名	类型	必填	描述	约束/选项	示值
ui	dict	是

3. 下游输入：（downstream）

与upstream一致

4. webUI输出：（web）

其他均与downstream一致，仅强调ui一项

字段名	类型	必填	描述	约束/选项	示值
ui	dict	是

性能配置/测试案例

对于可执行脚本，MiqroForge-Node需要从特定的配置json文件中读取输入和关键字。

字段名	类型	必填	描述	约束/选项
performance_config	string	是	性能配置文件	绝对路径
example_config_path	string	否	测试用例的配置文件	绝对路径
execution_command	string	是	节点执行命令必须包含环境变量

联系信息 (contact)

字段名	类型	必填	描述	约束/选项	示例值
name	string	是	维护者名称	-	"微观纪元量子化学团队"
email	string	是	联系邮箱	有效邮箱格式	"wuchuixiong@miqroera.com"

4.2.2 main.py或其他可执行程序

import argparse
import json
from pyscf import gto, scf

if __name__ == "__main__":

    parser = argparse.ArgumentParser()
    parser.add_argument(
    '-c', '--config_path', type=str,
    help='configuration file path'
  )
    f = open(
        parser.parse_args().config_path,
        'r'
    )
    conf = json.loads(f.read()) # dict from configuration file
    
    mol = gto.M(atom=conf["struc"])
    mol.basis = conf["basis"]
    mol.unit = conf["unit"]
    mol.build()
    
    mf = scf.RHF(mol)
    ene_hf = mf.run().e_tot

    mf.dump_chk(conf['scf_obj'])
    with open(conf["ene"], 'w') as f:
        f.write(str(ene_hf))

main.py 首先从配置文件中加载分子结构、基组和其他参数，建立 Hartree-Fock 计算模型，然后进行自洽场计算以获得系统的 HF 能量，将计算得到的能量结果写入文件，并保存当前的 HF 计算对象，以便在后续过程中直接加载和使用。对于新建节点或修改现有节点，其功能选择与实现过程不会受到太大影响。MiqroForge 平台仅需用户通过特定变量向平台传递输入输出参数，如示例所示，PySCF-HF 节点在 node.json 文件的 input 和 output 字段名称中，为每个输入输出参数都设置了名为 var 的子字段，通过分析可以发现，该 main.py 在读取和输出过程中均包含这些变量。

其整体逻辑遵循 "配置驱动" 的计算流程：用户首先在 node.json 中向 MiqroForge 申请，从上游获取一个名为 struc 的分子坐标文件。当 MiqroForge 运行整个工作流时，会将分子坐标文件保存到共享空间，并将该地址写入配置 json 文件。然后执行

python /app/PySCF-HF/script/main.py --config_path ${input_config_path}

该命令也可由用户指定，如果执行 codebash 脚本，可以类似地编写该命令：

./app/PySCF-HF/script/main.sh ${input_config_path}

${input_config_path} 是前面提到的配置 json 文件的地址。用户可以从配置 json 文件中获取分子坐标文件的地址并加载该文件。在本示例中使用了 python 的 argparse 和 json 库。

当您想要输出一个变量时，只需要在配置 json 中声明一个变量名，并将文件输出到该变量所指向的位置，所有的输出都需要保存为文件，但是 webUI 中的输入会直接写入到配置 json 中。

需要注意的是，虽然从配置文件中获得的 I/O 变量都是字符串信息，但有些是直接信息，有些则是可执行文件需要从中获取进一步信息的地址

I/O 变量	内容
上游输入	path
前端输入	string
下游输出	path
前端输出	path

4.2.3 examples/config.json 节点测试及配置说明

在 MiqroForge 平台中，每个节点镜像都包含一个标准化的测试配置文件 test_config.json。此文件位于节点的 /app/example/ 目录中，是验证节点功能的关键工具。

在节点的实际运行中，test_config.json或通过MiqroForge生成的${input_config_path}指向的config文件，他们的作用是作为计算时的输入/输出配置文件。用户在编写可执行程序时，需要保证main.py或其他可执行程序从config文件中读取到变量名。这些变量名和node.json中的变量名要保持一致。

测试配置文件示例（PySCF-HF节点）：

{
    "basis": "6-31g",
    "unit": "Angstrom",
    "struc": "/app/pyscf-hf/example/h2o-0p85.xyz",
    "scf_obj": "/app/pyscf-hf/example/h2o-0p85-mol.chk",
    "ene": "/app/pyscf-hf/example/h2o-0p85-hf-energy.json"
}

测试方法

​ 1. 直接使用测试配置：

# 在容器内执行测试
docker exec <container_name> python /app/script/main.py \
  --config_path /app/example/test_config.json

​ 2. 自定义配置测试：

# 1. 复制测试配置到本地
docker cp <container_name>:/app/example/test_config.json ./my_config.json

# 2. 修改配置参数
# 使用任何文本编辑器修改 my_config.json

# 3. 使用自定义配置测试
docker run -v $(pwd)/my_config.json:/app/test_config.json \
  <node_image> python /app/script/main.py \
  --config_path /app/test_config.json

重要提示：在发布节点前，务必使用内置的 test_config.json 验证节点功能。这是确保节点质量的关键步骤！

4.2.4 Performance_config.json 配置说明

performance_config.json 用于描述节点在不同任务尺度下的性能，是智能调度系统的重要依据。该文件记录了节点的基准性能数据、资源需求估算公式（如分子轨道数与内存与CPU的关系），并给出了合理的并行计算建议和运行环境信息。平台在分配计算资源时，参考文件进行自动优化。

1、Hartree-Fock节点的Performance_config.json解析

{
      "include": true,

      "resource_function": "memory MB = 2*'nao' ('nao' < 200); memory MB = 0.5*'nao' (200 < 'nao' < 1000)",
      "scalability": "轨道数与基组类型有关，内存需求随轨道数有所增长，但增长并非绝对线性",
      "recommand_min_config": "cpu: 4, memory MB: 600",
      "environment": "",

      "benchmark_points": [
        {
          "molecule": "C6H6",
          "num_atoms": 12,
          "basis": "631g",
          "nao": 66,
          "cpu": 4,
          "memory MB": "112",
          "time": "0.14s"
        },
        {
          "molecule": "C6H6",
          "num_atoms": 12,
          "basis": "cc-pvtz",
          "nao": 264,
          "cpu": 4,
          "memory MB": "123",
          "time": "6.7s"
        },
      ],
}

2、Performance_config字段解析说明

字段名	解析
resource_function	内存资源计算公式（根据轨道数nao），变量需以'来注明
scalability	补充resource_function，可以提及其未囊括的区域，或者补充不便用数学公式描述的地方
recommand_min_config	推荐的最小运行资源配置
environment	非必须，软件运行环境（PySCF版本、Python版本等）
benchmark_points	性能测试数据集合，包括多个测试样例
include	是否启用该配置项

3、 Benchmark 测试点说明

该 JSON 文件给出了两个基准测试案例，围绕量子化学计算场景设计，用于验证或对比不同计算配置下的资源消耗与性能表现。每个用例固定分子为 \(C_6H_6\)，包含 12 个原子，CPU 核数为 4，通过变更基组，分别为 631g 和 cc-pvtz ，观察原子轨道数 nao 对计算资源需求和时间效率的影响。结果显示，较小的 631g 基组需 66 个原子轨道，计算耗时 0.14 秒，内存占用 112 MB；而更复杂的 cc-pvtz 基组扩展至 264 个原子轨道，计算时间大幅增加至 6.7 秒，内存占用也略有上升至 123 MB。这一对比清晰地表明，nao 的规模会显著影响计算量，尤其是时间成本呈数十倍增长。这些测试案例为 MiqroForge 的资源规划提供参考，为实际计算任务中平衡精度与效率提供了重要依据。