MQT-QMAP量子电路映射工具开发指南

项目概述

MQT-QMAP是一个专注于量子电路映射的开源工具，它能够将量子算法中定义的逻辑电路转换为适合特定量子处理器架构的物理电路。该项目采用C++作为核心实现语言，并通过Python接口提供便捷的使用方式。

开发环境搭建

获取源代码

开发者可以通过以下方式获取项目代码：

1. 对于外部贡献者，建议先创建项目分支
2. 对于内部开发人员，可以直接克隆主仓库

git clone <仓库地址> mqt-qmap
cd mqt-qmap
git checkout -b 你的分支名称

依赖管理

项目核心依赖包括：

• C++17兼容编译器
• CMake 3.24+
• Z3 SMT求解器(≥4.8.15)

各平台安装方法：

• Ubuntu: sudo apt-get install libz3-dev
• macOS: brew install z3
• 也可通过Python包管理器安装: pip install z3-solver

C++开发指南

构建系统配置

项目使用CMake作为构建系统，推荐构建流程：

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 8

关键构建选项说明：

• BUILD_MQT_QMAP_TESTS: 控制是否构建测试套件
• USE_SYSTEM_BOOST: 使用系统Boost库

代码质量保证

1. 代码风格：遵循LLVM编码规范
2. 静态分析：使用clang-tidy进行代码检查
3. 自动格式化：通过clang-format保持代码风格一致

推荐开发工具：

• CLion：内置CMake和clang工具链支持
• VS Code：配合clangd扩展提供完整开发体验

测试策略

项目使用GoogleTest框架进行单元测试，测试执行方式：

ctest -C Release --test-dir build

测试覆盖率要求：

• 新增代码应保持或提高现有覆盖率水平
• 测试案例应具有实际验证价值

文档规范

C++代码应使用Doxygen格式注释，包括：

• 类和方法的功能说明
• 参数和返回值描述
• 复杂算法的实现细节

Python开发指南

开发环境配置

推荐使用uv工具管理Python环境：

uv sync

传统pip方式：

python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate.bat  # Windows
pip install -ve .

绑定开发

Python接口通过pybind11实现，关键目录：

• bindings/: C++/Python绑定代码
• python/mqt/qmap: Python包实现

开发注意事项：

• Python代码修改会立即生效
• C++代码修改需要重新构建

测试执行

使用pytest框架，推荐通过nox运行：

nox -s tests  # 所有Python版本
nox -s tests-3.12  # 指定版本

测试目录结构：

• test/python/: 包含所有Python测试案例

开发最佳实践

1. 提交前检查：配置pre-commit钩子自动执行代码检查
2. 持续集成：CI系统会执行完整构建和测试流程
3. 文档同步：代码修改应同步更新相关文档

通过遵循本指南，开发者可以高效地为MQT-QMAP项目做出贡献，共同推进量子计算工具链的发展。