Adoption Dynamics of Python-based Quantum Programming Ecosystems: An Empirical Study

This package contains the dataset, analysis notebooks, and figures supporting a research article submitted to a conference. The study analyses 397 Python-based quantum programming libraries (QPLibs) adopted in 2,722 GitHub repositories. The data is mined from the GitHub REST/GraphQL APIs and PyPI on 16 January 2026; all file dates and analysis windows are anchored to that snapshot. Folder layout replication_package/ ├── requirements.txt # Python packages used by the notebooks ├── data/ # raw + processed datasets (also data.zip) ├── figures/ # final figures used in the paper (also figures.zip) └── scripts_notebooks/ # Jupyter notebooks reproducing the analysis (also scripts_notebooks.zip) Notebooks (scripts_notebooks/) The notebooks are intended to be run in the order below. Each one reads files in data/ and writes its outputs back there; the figures are written to figures/. File Paper section Purpose data_collection.ipynb Section III, Fig. 1, Tables I–II End-to-end pipeline: repository identification (GitHub REST search), dependency-file and import extraction (GraphQL + raw content), pre-processing, PyPI lookup, and QPLib selection. Produces the final 397 QPLibs and 2,722 repositories. RQ1.ipynb Section IV, Fig. 2, Table III Ecosystem evolution: QPLib release timeline per QPE, growth rate, maintenance, adoption concentration (Gini index). RQ2.ipynb Section V, Fig. 3, Table IV Declared adoption / de-adoption at the QPE level, mined from commit histories of dependency files. RQ3.ipynb Section VI, Tables V–VI Dependency hygiene: under- and over-declaration of QPLibs (declared vs. imported), Kruskal–Wallis and Dunn pairwise tests. RQ4.ipynb Section VII, Fig. 4, Table VII Multi-ecosystem usage: co-occurrence, lag between adopting the first and second QPE, cross-ecosystem switching. dep_file_parsers.py Section III-B Helper module with regex/TOML parsers for requirements*.txt, pyproject.toml, setup.py, setup.cfg, Pipfile, and environment.yml. A Python environment satisfying requirements.txt is sufficient to run all notebooks. A GitHub personal access token is required only if data_collection.ipynb is re-executed against the GitHub API; all downstream notebooks operate solely on the cached data files in data/. Data files (data/) The pipeline (Fig. 1 of the paper) produces these files in roughly the order listed. Repository identification (Section III-A) File Description Maps to raw_candidates.jsonl 8,024 candidate repositories returned by the GitHub search/repositories endpoint for the 23 quantum key terms, with metadata (stars, default branch, archived flag, language, topics, …). Section III-A, Table I (initial) active_no_dup_no_arch_repos.jsonl 4,309 repositories retained after de-duplication, archived-repo filtering, and the activity-since-2025 filter. Section III-A, Table I (final) Dependency and import extraction (Section III-B) File Description repo_files_all.jsonl Snapshot, at data-collection time, of every recognised dependency file at the HEAD branch of each repository: file type, raw text, and the list of declared packages. repo_imports.jsonl Imports extracted from up to 50 .py files per repository (prioritising src/, core/, lib/, package/). repo_files_all_pkgs.jsonl Per-repository union of declared dependencies and observed imports — input for the dependency-hygiene analysis (RQ3). import_deps.jsonl Intermediate by-repo dependency-file view used during pre-processing. QPLib identification (Section III-C, Table II) File Description pkg_pypi.jsonl PyPI metadata (description, classifiers) per candidate package, used to decide whether a package is quantum-related. pkg_repo_pypi.jsonl Per-package: list of repositories that adopt it, plus the PyPI metadata. package_parent_framework.csv Mapping from each QPLib to its parent QPE (e.g., pennylane-qiskit → pennylane and qiskit). Implements the QPLib↔QPE assignment described in Section IV. selected_packages.jsonl Final 397 QPLibs retained by the selection criteria in Table II, with QPE membership flags. selected_repos.jsonl Final 2,722 repositories that adopt at least one of the 397 QPLibs. checkpoint.json Progress checkpoint written by data_collection.ipynb so long-running API calls can resume. Not used by the analysis itself. Longitudinal data for adoption / de-adoption (Sections V, VII) File Description dependency_file_commits.jsonl Up to 100 most recent commits per dependency file per repository (commit hash, commit date, file type, author). commits_package_presence.jsonl For every (repository, package, commit) triple, whether the package was present in the dependency file at that commit. Drives the adoption / de-adoption event detection. adoption_deadoption_events.jsonl Per-event records (already_present, adoption, de_adoption) with timestamps, used to build Fig. 3 and Table IV. rq2_first_adoption_per_repo_qpf.csv Per repository × parent QPE, the date of the first observed adoption event — used by RQ2 (cohort 2) and RQ4 (lag and switching). Pre-computed inputs for figures and tables File Description rq1_qplib_release_dates.csv Per QPLib: associated repositories, first/latest PyPI release dates, total releases, and status — input for Fig. 2 and Table III. Figures (figures/) File Paper artefact dataselection.pdf Fig. 1 — Overview of the QPLib identification process. rq1_number_qplibs_evol.pdf Fig. 2 — Monthly cumulative number of new QPLibs released per QPE. rq2_adoption_deadoption_panel.pdf Fig. 3 — Daily cumulative adoption (top) and de-adoption (bottom) per QPE. rq3_hygiene_heatmap_combined.pdf Visual companion to Section VI on dependency hygiene (over- / under-declaration). rq4_lag_to_second_qpf.pdf Fig. 4 — Distribution of days between first and second QPE adoption in multi-QPE repositories. Reproducing the results Install dependencies: pip install -r requirements.txt. Open the notebooks in scripts_notebooks/ and run them in the order RQ1 → RQ2 → RQ3 → RQ4. The cached data in data/ is sufficient — the notebooks read the *.jsonl and *.csv files listed above and regenerate every figure and statistical result reported in the paper. To re-mine the dataset from scratch, set a GitHub token and run data_collection.ipynb. The data snapshot was taken on 16 January 2026; a fresh re-mine will return more recent (and likely larger) numbers because the GitHub corpus and PyPI release history continue to grow. Citation If you use this dataset or analysis, please cite this Zenodo record (DOI: 10.5281/zenodo.18895240).本压缩包包含投稿至某学术会议的研究论文配套数据集、分析笔记本与论文配图。本研究针对2722个GitHub仓库中使用的397个基于Python的量子编程库（Quantum Programming Libraries，QPLibs）展开分析。相关数据于2026年1月16日通过GitHub REST/GraphQL应用程序编程接口（API）与Python包索引（PyPI）采集得到，所有文件时间戳与分析窗口均锚定该采集快照节点。 ### 文件夹结构 replication_package/ ├── requirements.txt # 本系列笔记本运行所需的Python依赖包 ├── data/ # 原始与预处理数据集（亦包含压缩包data.zip） ├── figures/ # 论文最终配图（亦包含压缩包figures.zip） └── scripts_notebooks/ # 用于复现分析流程的Jupyter笔记本（亦包含压缩包scripts_notebooks.zip） ### 分析笔记本 本系列笔记本需按照如下顺序运行。每个笔记本均读取`data/`目录下的文件，并将输出结果写入该目录；生成的图片则保存至`figures/`目录。 | 文件 | 论文对应章节、图表与表格 | 功能说明 | |--------------------------|--------------------------------|--------------------------------------------------------------------------| | data_collection.ipynb | 第三章、图1、表I至表II | 端到端分析流程：仓库识别（通过GitHub REST搜索）、依赖文件与导入语句提取（结合GraphQL与原始内容接口）、预处理、PyPI检索以及QPLib筛选，最终生成397个QPLib与2722个关联仓库。 | | RQ1.ipynb | 第四章、图2、表III | 生态演化分析：按量子编程生态（Quantum Programming Ecosystem，QPE）划分的QPLib发布时间线、增长速率、维护状态与采用集中度（基尼系数）。 | | RQ2.ipynb | 第五章、图3、表IV | 按QPE维度统计的声明式采用与弃用行为，从依赖文件的提交历史中挖掘得到。 | | RQ3.ipynb | 第六章、表V至表VI | 依赖卫生分析：QPLib的声明不足与过度声明问题（声明依赖与实际导入的对比），采用Kruskal-Wallis检验与Dunn两两事后检验。 | | RQ4.ipynb | 第七章、图4、表VII | 多生态使用分析：跨QPE的共现关系、首次与二次采用QPE的时间间隔、跨生态切换行为。 | | dep_file_parsers.py | 第三章B节 | 辅助工具模块，包含针对`requirements*.txt`、`pyproject.toml`、`setup.py`、`setup.cfg`、`Pipfile`与`environment.yml`的正则与TOML解析器。 | 满足`requirements.txt`配置的Python运行环境即可运行所有笔记本。仅当重新通过GitHub API执行`data_collection.ipynb`时，才需要配置GitHub个人访问令牌；其余后续笔记本仅需读取`data/`目录下的缓存数据文件即可运行。 ### 数据文件（`data/`目录） 本分析流程（对应论文图1）按照如下大致顺序生成以下文件。 #### 仓库识别（对应论文第三章A节） | 文件名称 | 描述 | 对应论文章节与表格 | |-----------------------------------|----------------------------------------------------------------------|----------------------------------| | raw_candidates.jsonl | 针对23个量子相关关键词调用GitHub `search/repositories`接口返回的8024个候选仓库，包含元数据（星标数、默认分支、归档状态、开发语言、主题标签等）。 | 第三章A节、表I（初始候选集） | | active_no_dup_no_arch_repos.jsonl | 经去重、过滤归档仓库与2025年后活跃性筛选后保留的4309个仓库。 | 第三章A节、表I（最终候选集） | #### 依赖文件与导入语句提取（对应论文第三章B节） | 文件名称 | 描述 | |---------------------------|----------------------------------------------------------------------| | repo_files_all.jsonl | 采集时刻各仓库HEAD分支下所有识别到的依赖文件快照：文件类型、原始文本与声明的依赖包列表。 | | repo_imports.jsonl | 从每个仓库最多50个`.py`文件中提取的导入语句（优先读取`src/`、`core/`、`lib/`、`package/`目录下的文件）。 | | repo_files_all_pkgs.jsonl | 每个仓库的声明依赖与实际导入的并集，作为依赖卫生分析（RQ3）的输入数据。 | | import_deps.jsonl | 预处理阶段生成的按仓库划分的中间依赖文件视图。 | #### QPLib识别（对应论文第三章C节、表II） | 文件名称 | 描述 | |-------------------------------|----------------------------------------------------------------------| | pkg_pypi.jsonl | 各候选包的PyPI元数据（描述、分类器），用于判断包是否与量子相关。 | | pkg_repo_pypi.jsonl | 每个包对应的关联仓库列表与PyPI元数据。 | | package_parent_framework.csv | 每个QPLib与其所属QPE的映射表（例如`pennylane-qiskit` → `pennylane`与`qiskit`），实现第四章所述的QPLib与QPE关联分配规则。 | | selected_packages.jsonl | 经表II所述筛选标准保留的最终397个QPLib，包含其QPE归属标记。 | | selected_repos.jsonl | 最终2722个至少使用1个上述QPLib的关联仓库。 | | checkpoint.json | `data_collection.ipynb`生成的进度检查点，用于恢复长时间运行的API调用，不用于分析流程本身。 | #### 用于分析采用与弃用行为的纵向数据（对应论文第五章、第七章） | 文件名称 | 描述 | |-----------------------------------|----------------------------------------------------------------------| | dependency_file_commits.jsonl | 每个仓库每个依赖文件最多100条最新提交记录（提交哈希、提交日期、文件类型、作者）。 | | commits_package_presence.jsonl | 针对每个（仓库、包、提交）三元组，记录该提交时刻依赖文件中是否包含该包，用于驱动采用与弃用事件检测。 | | adoption_deadoption_events.jsonl | 按事件划分的记录（已存在、采用、弃用），包含时间戳，用于生成图3与表IV。 | | rq2_first_adoption_per_repo_qpf.csv | 按仓库×QPE维度统计的首次观测到采用事件的日期，用于RQ2（队列2）与RQ4（时间间隔与生态切换）分析。 | #### 用于生成图表与表格的预计算输入数据 | 文件名称 | 描述 | |-----------------------------------|----------------------------------------------------------------------| | rq1_qplib_release_dates.csv | 每个QPLib的关联仓库列表、首次/最新PyPI发布日期、总发布次数与状态，作为图2与表III的输入数据。 | ### 论文配图（`figures/`目录） | 文件名称 | 对应论文配图 | |-------------------------------------------|---------------------------------------| | dataselection.pdf | 图1：QPLib识别流程总览 | | rq1_number_qplibs_evol.pdf | 图2：按QPE划分的月度累计新增QPLib数量 | | rq2_adoption_deadoption_panel.pdf | 图3：按QPE维度的每日累计采用（上）与弃用（下）行为 | | rq3_hygiene_heatmap_combined.pdf | 第六章依赖卫生分析（过度/不足声明）的可视化辅助图表 | | rq4_lag_to_second_qpf.pdf | 图4：多QPE仓库中首次与二次采用QPE的时间间隔分布 | ### 结果复现步骤 1. 安装依赖：执行`pip install -r requirements.txt`。 2. 打开`scripts_notebooks/`目录下的笔记本，并按照`RQ1 → RQ2 → RQ3 → RQ4`的顺序运行。本项目已提供`data/`目录下的缓存数据，笔记本将读取上述`.jsonl`与`.csv`文件并重新生成论文中报告的所有图表与统计结果。 3. 若需从头重新采集数据集，请配置GitHub个人访问令牌并运行`data_collection.ipynb`。本次数据采集于2026年1月16日完成，重新采集将得到更新（且规模可能更大）的结果，因为GitHub代码仓库与PyPI的发布历史仍在持续增长。 ### 引用说明 若使用本数据集或分析代码，请引用该Zenodo存档（DOI: 10.5281/zenodo.18895240）。