算法模板指南

概述

unitarylab_algorithms/template.py 提供了在 UnitaryLab 算法框架中实现新算法的最小化脚手架。通过继承 BaseAlgorithm，你的算法将自动获得日志记录、结果格式化、文件保存和统一返回格式等能力。

本指南介绍模板结构，解释每个组成部分的作用，并展示如何将其扩展为真实算法。

模板概览


# unitarylab_algorithms/template.py
 
from typing import Dict, Any
from unitarylab_algorithms.algo_base import BaseAlgorithm
 
class ExampleAlgorithm(BaseAlgorithm):
    """用于在 unitarylab_algorithms/ 下添加新算法的最小化模板。"""
 
    def run(self, n: int = 2) -> Dict[str, Any]:
        """
        运行示例算法。
 
        参数：
            n: 量子比特数
 
        返回：
            包含以下字段的字典：
            - status: 成功时为 'ok'
            - circuit_path: 保存线路图的 SVG 路径
            - plot: 结果文件信息（如 txt 文件名）
        """
        # 1. 记录输入参数
        self.update_input({'n': n})
 
        # 2. 在此构建线路
        # circuit = Circuit(n)
        # circuit.h(0)
        # ...
 
        # 3. 执行算法逻辑
        # result_value = some_computation(circuit)
 
        # 4. 保存线路图
        # circuit_path = self.save_circuit(circuit, name='example')
 
        # 5. 记录输出
        self.update_output({'status': 'ok'})
 
        # 6. 保存文本文件
        self.save_txt()
 
        return {
            'status': 'ok',
            # 'circuit_path': circuit_path,
            # 'plot': [{'format': 'txt', 'filename': 'example_result.txt'}],
        }

逐步指南：编写新算法

第一步——创建文件

在 unitarylab_algorithms/ 下创建目录和文件：


unitarylab_algorithms/
└── my_category/
    └── my_algo/
        └── algorithm.py

第二步——导入 BaseAlgorithm


from typing import Any, Dict, List, Optional
from unitarylab_algorithms.algo_base import BaseAlgorithm
from unitarylab.core import Circuit

第三步——定义类


class MyAlgorithm(BaseAlgorithm):
    """
    本算法功能的简要描述。
    """
 
    def run(self, param_a: int, param_b: float = 1.0) -> Dict[str, Any]:
        ...

第四步——在开头调用 `update_input`

始终记录输入参数，使其出现在格式化结果和保存的文本中：


self.update_input({'param_a': param_a, 'param_b': param_b})

第五步——构建并执行线路


from unitarylab.core import Circuit
 
qc = Circuit(param_a)
qc.h(0)
qc.cx(0, 1)
result = qc.execute()

第六步——保存线路图


circuit_path = self.save_circuit(qc, name='my_algo_circuit')

第七步——记录并保存输出


self.update_output({
    'status': 'ok',
    'my_custom_field': some_value
})
self.log(f"计算完成：{some_value}")
self.save_txt()

第八步——返回标准字典


return {
    'status': 'ok',
    'circuit_path': circuit_path,
    'plot': [{'format': 'txt', 'filename': 'my_algo_result.txt'}],
    'my_custom_field': some_value
}

第九步——添加 `test()` 函数

每个算法都应提供带合理默认值的模块级 test() 函数：


def test(param_a=3, param_b=1.0):
    algo = MyAlgorithm()
    return algo.run(param_a=param_a, param_b=param_b)

BaseAlgorithm 方法参考

方法	使用时机
`self.update_input(dict)`	在 `.run()` 开头记录输入参数
`self.update_output(dict)`	计算完成后记录输出值
`self.log(message)`	打印并记录信息日志
`self.save_circuit(circuit, name)`	将线路持久化到磁盘，返回文件路径
`self.save_txt()`	将格式化结果保存为文本文件
`self.format_result_ascii()`	以字符串形式获取格式化结果（如用于打印）

完整最小示例


# unitarylab_algorithms/my_category/my_algo/algorithm.py
 
from typing import Dict, Any
from unitarylab_algorithms.algo_base import BaseAlgorithm
from unitarylab.core import Circuit
 
 
class MyAlgorithm(BaseAlgorithm):
    """示例：对所有 n 个量子比特施加 H 门，并输出概率分布。"""
 
    def run(self, n: int = 3) -> Dict[str, Any]:
        self.update_input({'n': n})
 
        qc = Circuit(n)
        for i in range(n):
            qc.h(i)
 
        sim_result = qc.execute()
        probs = sim_result.probabilities
 
        circuit_path = self.save_circuit(qc, name='h_all')
 
        self.update_output({'status': 'ok', 'probabilities': probs})
        self.log(f"对 {n} 个量子比特施加 H 门，均匀分布：{len(probs)} 个态。")
        self.save_txt()
 
        return {
            'status': 'ok',
            'circuit_path': circuit_path,
            'plot': [{'format': 'txt', 'filename': 'h_all_result.txt'}],
            'probabilities': probs
        }
 
 
def test(n=3):
    algo = MyAlgorithm()
    return algo.run(n=n)

注册与使用

创建算法后，可直接导入使用，无需任何注册步骤：


from unitarylab_algorithms.my_category.my_algo.algorithm import MyAlgorithm
 
algo = MyAlgorithm()
result = algo.run(n=4)
print(result['status'])

框架使用直接导入方式，无需集中注册。