Pattern Usage Dataset

Pattern Usage Dataset是由圣保罗大学研究团队构建的量子软件模式使用数据集，旨在记录开源项目中量子设计模式的采纳情况。该数据集包含从80个开源项目的904个Python脚本中提取的611个模式检测实例，覆盖23种量子模式，数据来源包括Qiskit、PennyLane、Classiq等五个量子框架。数据集通过qpa管道自动检测生成，结合知识库和语义匹配技术实现高精度识别。该数据集服务于量子软件工程领域，支持模式采纳分析、演化研究及工具评估，为理解量子编程实践提供了实证基础。The Pattern Usage Dataset is a quantum software pattern usage dataset constructed by a research team from the University of São Paulo, which aims to document the adoption of quantum design patterns in open-source projects. This dataset contains 611 pattern detection instances extracted from 904 Python scripts across 80 open-source projects, covering 23 types of quantum patterns. Its data sources include five quantum frameworks such as Qiskit, PennyLane, and Classiq. The dataset is automatically generated via the qpa pipeline, with high-precision recognition achieved through the combination of knowledge base and semantic matching techniques. This dataset serves the field of quantum software engineering, supporting pattern adoption analysis, evolution research, and tool evaluation, and providing an empirical foundation for understanding quantum programming practices.

原始信息汇总

qpa — 量子模式分析器（Quantum Patterns Analyzer）数据集详情

概述

qpa 是一个开源的 Python 工具，用于自动挖掘开源项目中的量子计算模式使用情况。它从主流量子框架构建知识库，发现并克隆相关的 GitHub 仓库，并使用语义搜索在 Jupyter Notebook 中检测模式实现。该工具附带两个协同子系统：一个用于构建 Neo4j 谱系图（graph build），另一个用于 LLM 知识库分类评估（KB-classification evaluation）。

工作流程

工具分三个阶段运行：

1. 数据收集：通过 GitHub API 查询 Python 量子仓库（按星标、贡献者和活跃度筛选），本地克隆仓库并下载 PlanQK 模式图谱。
2. 知识库构建：从五个种子框架（Qiskit、PennyLane、Classiq、Qiskit Algorithms、Qiskit Machine Learning）提取核心量子概念，并对照模式目录分类；自动为每个目标项目构建动态知识库。
3. 模式检测：将 Jupyter Notebook 转为 Python 脚本，通过四个活跃语义通道扫描，聚合结果生成结构化报告。

匹配通道

通道	启用状态	阈值	匹配内容
name	是	0.88	AST 提取的函数调用名 vs 知识库概念短名
summary	是	0.78	文件注释块 vs 知识库概念文档摘要
title	是	0.76	Notebook 标题 vs 知识库概念摘要
pattern_desc	是	0.80	文件注释块 vs 模式意图文本
defined_doc	否	0.85	文件中定义的类/函数文档字符串 vs 知识库摘要
internal_keywords	否	0.78	知识库概念内部标记签名 vs 调用点名称
internal_comments	否	0.75	知识库概念内联注释 vs 文件注释块

后三个通道默认关闭，因为当前阈值下在全量语料上产生零匹配。另有关键词否决机制过滤基于文本的通道，运行时可通过配置文件调节。

当前数据集指标

指标	主要采用语料库	完整混合语料库
仓库数量	80	83
含脚本的仓库	47	50
分析的 Python 脚本	904	1,144
有匹配的项目	37	40
唯一检测数	611	1,100
唯一文件-模式对	500	880
有匹配的文件	358	531
检测到的模式（知识库中 23 种）	23	23

Qrisp 留出评估结果

	精确率	召回率	F1
微平均	0.913	0.583	0.712
宏平均	0.636	0.413	0.488
微平均（基线，无词汇扩展）	0.846	0.306	0.449

基线行仅使用种子知识库；动态知识库将召回率从 0.306 提升至 0.583，微平均 F1 从 0.449 提升至 0.712。

关键输出文件

文件	描述
docs/third_party_final_pattern_report.md	主要实践者采用报告（排除三个官方框架示例仓库）
data/third_party_quantum_concept_matches_with_patterns.csv	主要实践者采用检测数据集
docs/final_pattern_report.md	完整混合语料报告
data/quantum_concept_matches_with_patterns.csv	完整混合语料检测数据集
data/dynamic_kb/<project>/	各项目动态知识库条目
data/report/*.csv	细分统计表

环境要求

• Python 3.12+（管道通过 uv 创建自有 .venv）
• just 命令运行器
• Git
• Docker（just all 及图谱构建必需；just lite 不需要）
• 可选环境变量：GITHUB_TOKEN（仅用于刷新仓库发现）、TOGETHER_API_KEY（仅用于 LLM 知识库分类评估）

快速入门

使用 just all 可从已提交的仓库列表和固定提交进行端到端复制（首次运行 60–90 分钟），无需 API 密钥。也可单独运行各阶段命令，如种子知识库提取、动态知识库构建、模式检测、Qrisp 评估、图谱构建等。

嵌入模型

使用 all-mpnet-base-v2（sentence-transformers），最大 384 个 token，无 API 调用、无不确定性，保证可复现性。

搜集汇总

数据集介绍

构建方式

Pattern Usage Dataset的构建源于对量子软件模式在开源项目中实际应用情况的系统性挖掘。研究者首先扩展了PlanQK模式目录，形成包含61个模式的分类体系，并构建了将286个来自五种量子框架（Qiskit、PennyLane、Classiq、Qiskit Algorithms和Qiskit Machine Learning）的组件映射到这些模式的知识库。随后，基于qpa工具，对从GitHub精选的80个开源项目中的904个Python脚本进行静态分析，通过名称匹配、摘要匹配、标题匹配和模式描述匹配四种通道，以及两阶段词汇扩展策略，检测代码中的模式使用实例，并记录每个检测的文件、行号、匹配组件和相似度分数，最终形成包含611个检测记录的数据集。

使用方法

该数据集可用于多种量子软件工程研究场景。研究者可利用检测结果进行模式采用率的横截面分析，比较不同框架或项目间的模式使用差异。组合图支持深入探究模式之间的依赖关系、共现机制，以及框架内部实现结构。数据集还可用于验证模式检测工具的准确性，例如在Qrisp等未纳入知识库的框架上进行评估，或与其他检测方法进行对比。此外，数据集可作为量子模式相关的实证基准，支持模式目录的演进研究，以及框架演化和模式使用趋势的纵向分析。

背景与挑战

背景概述

量子软件模式为构建量子程序提供了高层抽象，然而关于其在实际开发中采纳情况的经验证据仍十分匮乏。为填补这一空白，圣保罗大学的研究团队在先前将量子模式图谱扩展为包含61种模式的目录，并构建了连接框架组件与模式的知识库，同时开发了从开源代码中挖掘模式实现的工具。该研究团队进一步提升了工具的检测精度与覆盖范围，引入词汇扩展与图数据库技术，在多个量子框架中系统性分析了模式的采用与组合方式。该数据集汇聚了286个框架组件与模式目录的映射关系，以及由此产生的模式使用数据，为量子软件工程领域提供了可复现的实证基础，推动了关于模式采纳及其演化的深入理解。

当前挑战

该数据集面临的挑战集中于多维度。首先，量子软件模式的定义与实现之间往往存在显著差异，如何准确地将抽象模式映射至具体框架组件是一大难题，尤其当目标框架的命名约定与知识库不一致时，检测精度显著下降。其次，大规模检测过程中，区分开发者显式调用的模式与框架内部间接引入的模式尤为困难，这直接影响对模式真实采纳情况的判断。此外，构建该数据集需整合多源框架，各框架组件数量庞大且持续演化，如何设计半自动化的分类机制以维系知识库的时效性与准确性亦构成挑战。再者，不同框架对同一模式的封装粒度存在差异，这不仅影响检测的计数结果，也使得跨框架的比较与解读变得复杂。

常用场景

经典使用场景

该数据集主要用于量子软件模式挖掘与组成分析，其经典使用场景在于从开源量子项目中自动检测模式实现，并构建构成图以揭示模式在框架内部的组装方式。研究者可借助该数据集重复量子模式采纳研究，分析不同框架（如Qiskit、PennyLane、Classiq等）中模式的分布与共现规律，进而评估模式的实际应用程度。此外，该数据集支持对模式检测工具进行精度评估，例如在Qrisp这类未纳入知识库的框架上，通过词汇扩展策略提升检测的召回率与F1分数，为量子软件工程中的模式实证研究提供了可复现的基础设施。

解决学术问题

该数据集解决了量子软件工程中缺乏模式采纳经验证据的学术问题，为量子模式在实践中是否被使用、如何被使用提供了大规模实证依据。以往研究多停留在模式定义与分类层面，而该数据集通过自动挖掘80个开源项目中的模式实例，验证了23个模式均在实际代码中出现，并揭示了模式在不同抽象层级上的分布。此外，数据集支持区分开发者直接调用与框架内部引入的模式，澄清了原始检测计数可能混淆直接使用与间接使用的问题，从而为模式采纳的真实程度提供了更精确的度量，推动了量子软件模式研究从理论探讨走向实证分析。

实际应用

在实际应用中，该数据集可用于量子软件开发工具链的优化与验证。例如，开发者可利用知识库与模式检测管道，自动识别其量子项目中所使用的模式组件，从而获得代码结构的语义标注，辅助代码理解与维护。基于构成图，框架开发者可以比较不同框架对同一模式的实现粒度，为框架设计提供参考；教育工作者可据此设计量子编程教学案例，展示模式在不同框架中的典型用法。此外，该数据集支持框架版本的演进分析，追踪模式实现的变化，从而为量子软件生态的持续集成与工具链升级提供数据支持。

数据集最近研究

最新研究方向

该数据集支撑的最新研究方向聚焦于量子软件模式的实证分析与演化追踪，通过构建调用组合图揭示模式在框架内部的实现组装方式，并利用LLM集成实现知识库的半自动维护与扩展。研究已从静态检测走向动态组合与精度评估，在Qrisp框架上通过词汇扩展将micro-F1提升至0.712，同时借助图数据库分析自然涌现出模式共现、直接与间接调用区分及框架粒度的对比，为量子软件工程提供了可复现的量化工具与数据集，推动了模式采纳研究的科学化与系统化。

相关研究论文

• From Pattern Detection to Composition Analysis in Quantum Software

  圣保罗大学 · 2026年