pysparq 0.1.0__tar.gz

pysparq-0.1.0/.clang-format

@@ -0,0 +1,123 @@
+---
+Language: Cpp
+BasedOnStyle: LLVM
+
+# Indentation
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ContinuationIndentWidth: 4
+
+# Line length
+ColumnLimit: 120
+
+# Braces
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: false
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  BeforeCatch: false
+  BeforeElse: false
+  IndentBraces: false
+
+BreakBeforeBraces: Attach
+
+# Namespaces
+NamespaceIndentation: None
+CompactNamespaces: false
+
+# Classes/Structs
+AccessModifierOffset: -4
+EmptyLineBeforeAccessModifier: LogicalBlock
+EmptyLineAfterAccessModifier: Never
+
+# Functions
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortLambdasOnASingleLine: All
+AlwaysBreakTemplateDeclarations: Yes
+
+# Parameters and arguments
+BinPackParameters: false
+BinPackArguments: false
+ExperimentalAutoDetectBinPacking: false
+AllowAllParametersOfDeclarationOnANextLine: true
+
+# Constructor initializers
+BreakConstructorInitializers: BeforeColon
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+
+# Inheritance
+BreakInheritanceList: BeforeColon
+
+# Alignment
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands: true
+AlignTrailingComments: true
+PointerAlignment: Left
+ReferenceAlignment: Pointer
+
+# Spacing
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: true
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyParentheses: false
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+
+# Comments
+AlignTrailingComments:
+  Kind: Always
+  OverEmptyLines: 0
+ReflowComments: true
+
+# Includes
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^<.*\.h>'
+    Priority: 1
+    SortPriority: 0
+  - Regex: '^<.*'
+    Priority: 2
+    SortPriority: 1
+  - Regex: '^".*\.h"'
+    Priority: 3
+    SortPriority: 2
+  - Regex: '^".*'
+    Priority: 4
+    SortPriority: 3
+SortIncludes: CaseSensitive
+
+# Other
+KeepEmptyLinesAtTheStartOfBlocks: false
+MaxEmptyLinesToKeep: 1
+SeparateDefinitionBlocks: Always
+SortUsingDeclarations: LexicographicNumeric
+Standard: c++17
+
+# Penalties
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PenaltyIndentedWhitespace: 0

pysparq-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

pysparq-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,69 @@
+---
+name: Bug 报告
+about: 创建报告以帮助我们改进项目
+title: '[Bug] '
+labels: bug
+assignees: ''
+---
+
+## 问题描述
+
+<!-- 清晰简洁地描述你遇到的问题 -->
+
+## 复现步骤
+
+<!-- 提供详细的步骤来复现该问题 -->
+
+1. 步骤 1: '...'
+2. 步骤 2: '...'
+3. 步骤 3: '...'
+4. 出现错误
+
+## 期望行为 vs 实际行为
+
+<!-- 描述你期望发生什么，以及实际发生了什么 -->
+
+**期望:** [描述期望的行为]
+
+**实际:** [描述实际发生的行为]
+
+## 环境信息
+
+<!-- 请提供以下信息 -->
+
+- **操作系统**: [例如 Ubuntu 22.04, Windows 11, macOS 14]
+- **编译器**: [例如 GCC 11.4, Clang 15, MSVC 2022]
+- **CMake 版本**: [例如 3.25.1]
+- **项目版本/Commit**: [例如 main 分支最新, v1.2.3]
+- **CUDA 版本** (如适用): [例如 CUDA 12.1]
+- **Python 版本** (如适用): [例如 Python 3.10]
+
+## 最小复现示例
+
+<!-- 如果可能，提供最小化的代码示例来复现问题 -->
+
+```cpp
+// 在此处粘贴代码
+```
+
+或者 Python 代码：
+
+```python
+# 在此处粘贴代码
+```
+
+## 错误日志
+
+<!-- 粘贴相关的错误日志或堆栈跟踪 -->
+
+```
+在此处粘贴错误日志
+```
+
+## 截图
+
+<!-- 如果适用，添加截图来帮助解释问题 -->
+
+## 其他信息
+
+<!-- 任何其他相关信息，如你是否已尝试修复 -->

pysparq-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,97 @@
+---
+name: 功能请求
+about: 为项目提出新功能建议
+title: '[Feature] '
+labels: enhancement
+assignees: ''
+---
+
+## 功能描述
+
+<!-- 清晰简洁地描述你希望添加的功能 -->
+
+## 使用场景
+
+<!-- 描述这个功能将在什么场景下使用，解决什么问题 -->
+
+### 背景
+
+[描述背景信息]
+
+### 目标用户
+
+[这个功能主要服务于哪些用户]
+
+### 使用示例
+
+```cpp
+// 期望的 C++ API 使用示例
+QRAMSimulator sim(10);  // 10 量子比特
+sim.load(address, data);
+auto result = sim.execute();
+```
+
+或 Python：
+
+```python
+# 期望的 Python API 使用示例
+import pyqsparse
+
+sim = pyqsparse.QRAMSimulator(10)
+sim.load(address, data)
+result = sim.execute()
+```
+
+## 期望的 API/接口
+
+<!-- 如果适用，描述你期望的接口设计 -->
+
+### 提议的接口
+
+```cpp
+// 类/函数声明示例
+class NewFeature {
+public:
+    NewFeature(int param);
+    Result process(const Input& input);
+};
+```
+
+### 参数说明
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `param` | `int` | 参数描述 |
+| `input` | `Input` | 输入描述 |
+
+## 替代方案
+
+<!-- 描述你考虑过的其他替代方案 -->
+
+### 方案 1: [方案名称]
+
+[描述]
+
+**优点:**
+- ...
+
+**缺点:**
+- ...
+
+### 方案 2: [方案名称]
+
+[描述]
+
+**优点:**
+- ...
+
+**缺点:**
+- ...
+
+## 额外上下文
+
+<!-- 任何其他相关信息，如参考文档、相关项目等 -->
+
+- 相关文献: [链接]
+- 参考实现: [链接]
+- 相关 Issue: #123

pysparq-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,71 @@
+## PR 类型
+
+<!-- 在相关选项前的 [ ] 中填入 x -->
+
+- [ ] Bug 修复 (non-breaking change which fixes an issue)
+- [ ] 新功能 (non-breaking change which adds functionality)
+- [ ] 破坏性变更 (breaking change which would cause existing functionality to not work as expected)
+- [ ] 文档更新
+- [ ] 代码重构
+- [ ] 性能优化
+- [ ] 测试相关
+
+## 变更描述
+
+<!-- 描述这个 PR 做了什么，为什么做这些变更 -->
+
+### 主要变更
+
+1. [描述变更 1]
+2. [描述变更 2]
+3. [描述变更 3]
+
+### 技术细节
+
+<!-- 如果是复杂变更，提供技术实现细节 -->
+
+## 测试情况
+
+<!-- 描述你如何测试这些变更 -->
+
+- [ ] 单元测试通过
+- [ ] 集成测试通过
+- [ ] 手动测试通过
+
+### 测试环境
+
+- 操作系统: [例如 Ubuntu 22.04]
+- 编译器: [例如 GCC 11.4]
+- CMake 版本: [例如 3.25.1]
+
+### 性能影响
+
+<!-- 如果适用，描述性能变化 -->
+
+- [ ] 性能提升
+- [ ] 性能下降
+- [ ] 无显著影响
+
+## 关联 Issue
+
+<!-- 使用关键字自动关闭相关 Issue: Fixes #123, Closes #456, Resolves #789 -->
+
+Fixes #
+
+## 检查清单
+
+- [ ] 代码遵循项目编码规范
+- [ ] 所有测试通过
+- [ ] 新增代码有适当测试覆盖
+- [ ] 文档已更新（如需要）
+- [ ] Commit message 清晰有意义
+- [ ] 没有引入编译警告
+- [ ] 向后兼容（如为 bugfix 或新功能）
+
+## 截图/日志
+
+<!-- 如果适用，添加截图或日志来演示变更 -->
+
+## 其他信息
+
+<!-- 任何其他相关信息 -->

pysparq-0.1.0/.github/workflows/cmake-multi-platform.yml

@@ -0,0 +1,266 @@
+name: CMake on multiple platforms
+
+on:
+  push:
+    branches: [ "main", "develop" ]
+  pull_request:
+    branches: [ "main", "develop" ]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ============================================================================
+  # Main build job
+  # ============================================================================
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Linux + GCC + C++17
+          - name: "Ubuntu + GCC + C++17"
+            os: ubuntu-24.04
+            build_type: Release
+            c_compiler: gcc
+            cpp_compiler: g++
+            cpp_standard: 17
+          # Linux + GCC + C++20
+          - name: "Ubuntu + GCC + C++20"
+            os: ubuntu-24.04
+            build_type: Release
+            c_compiler: gcc
+            cpp_compiler: g++
+            cpp_standard: 20
+          # Windows + MSVC
+          - name: "Windows + MSVC"
+            os: windows-latest
+            build_type: Release
+            c_compiler: cl
+            cpp_compiler: cl
+            cpp_standard: 17
+
+    env:
+      BUILD_DIR: ${{ github.workspace }}/build
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        submodules: 'true'
+
+    # --- ccache (Linux only) ---
+    - name: Install ccache
+      if: runner.os == 'Linux'
+      run: sudo apt-get update && sudo apt-get install -y ccache
+
+    - name: Configure ccache
+      if: runner.os == 'Linux'
+      run: |
+        ccache --set-config=max_size=2G
+        ccache --set-config=compression=true
+        ccache -z
+
+    - name: Cache ccache
+      if: runner.os == 'Linux'
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/ccache
+        key: ccache-${{ runner.os }}-${{ matrix.cpp_compiler }}-${{ matrix.cpp_standard }}-${{ github.sha }}
+        restore-keys: |
+          ccache-${{ runner.os }}-${{ matrix.cpp_compiler }}-${{ matrix.cpp_standard }}-
+
+    # --- sccache (Windows only) ---
+    - name: Install sccache
+      if: runner.os == 'Windows'
+      run: |
+        $sccacheVersion = "0.9.1"
+        $url = "https://github.com/mozilla/sccache/releases/download/v${sccacheVersion}/sccache-v${sccacheVersion}-x86_64-pc-windows-msvc.zip"
+        Invoke-WebRequest -Uri $url -OutFile sccache.zip
+        Expand-Archive -Path sccache.zip -DestinationPath sccache
+        echo "$env:GITHUB_WORKSPACE\sccache\sccache-v${sccacheVersion}-x86_64-pc-windows-msvc" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+    - name: Cache sccache
+      if: runner.os == 'Windows'
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/sccache
+        key: sccache-${{ runner.os }}-msvc-${{ matrix.cpp_standard }}-${{ github.sha }}
+        restore-keys: |
+          sccache-${{ runner.os }}-msvc-${{ matrix.cpp_standard }}-
+
+    # --- CMake configure ---
+    - name: Configure CMake
+      shell: bash
+      run: |
+        EXTRA_ARGS=""
+        if [ "$RUNNER_OS" = "Linux" ]; then
+          EXTRA_ARGS="-DCMAKE_CXX_COMPILER_LAUNCHER=ccache"
+        elif [ "$RUNNER_OS" = "Windows" ]; then
+          EXTRA_ARGS="-DCMAKE_CXX_COMPILER_LAUNCHER=sccache"
+        fi
+        cmake -B "$BUILD_DIR" \
+          -DCMAKE_CXX_COMPILER=${{ matrix.cpp_compiler }} \
+          -DCMAKE_C_COMPILER=${{ matrix.c_compiler }} \
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }} \
+          -DCMAKE_CXX_STANDARD=${{ matrix.cpp_standard }} \
+          -DCACHED_REGISTER_SIZE=50 \
+          $EXTRA_ARGS \
+          -S .
+
+    # --- Build ---
+    - name: Build
+      shell: bash
+      run: cmake --build "$BUILD_DIR" --config ${{ matrix.build_type }} --parallel 4
+
+    - name: Show ccache stats
+      if: runner.os == 'Linux'
+      run: ccache -s
+
+    - name: Show sccache stats
+      if: runner.os == 'Windows'
+      run: sccache --show-stats
+
+    # --- Test ---
+    - name: Test (Unix)
+      if: runner.os != 'Windows'
+      working-directory: ${{ env.BUILD_DIR }}
+      env:
+        PROJECT_ROOT: ${{ github.workspace }}
+      run: ctest --output-on-failure -j4
+
+    - name: Test (Windows)
+      if: runner.os == 'Windows'
+      working-directory: ${{ env.BUILD_DIR }}
+      env:
+        PROJECT_ROOT: ${{ github.workspace }}
+      run: ctest --output-on-failure -C ${{ matrix.build_type }} -j4
+
+    # --- Python package ---
+    - name: Build Python Package
+      run: pip install .
+
+    - name: Test Python Package
+      run: python -c "import pysparq; pysparq.test_import()"
+
+    - name: Validate Stub Synchronization
+      if: runner.os == 'Linux' && matrix.cpp_standard == '17'
+      run: |
+        pip install pybind11-stubgen
+        pybind11-stubgen pysparq._core -o /tmp/stubs
+        diff PySparQ/pysparq/_core.pyi /tmp/stubs/pysparq/_core.pyi || \
+          (echo "::error::Stub files are out of sync. Regenerate with: pybind11-stubgen pysparq._core -o PySparQ/pysparq/" && exit 1)
+
+  # ============================================================================
+  # Python tests with multiple versions
+  # ============================================================================
+  python-tests:
+    name: "Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-24.04, windows-latest]
+        python-version: ['3.10', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: 'true'
+
+    - name: Setup Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest numpy
+
+    - name: Build and install package
+      run: pip install -v .
+
+    - name: Run import test
+      run: python -c "import pysparq; pysparq.test_import()"
+
+    - name: Run pytest
+      shell: bash
+      run: |
+        if [ -d "PySparQ/test" ]; then
+          pytest PySparQ/test/ -v || true
+        else
+          echo "No Python tests found"
+        fi
+
+  # ============================================================================
+  # Documentation build job
+  # ============================================================================
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: 'true'
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install Documentation Dependencies
+      run: |
+        pip install -r docs/sphinx/requirements.txt
+        sudo apt-get update && sudo apt-get install -y doxygen graphviz pandoc
+
+    - name: Generate Doxygen Documentation
+      run: doxygen Doxyfile
+
+    - name: Build Sphinx Documentation
+      run: |
+        cd docs/sphinx
+        make html
+
+    - name: Upload documentation artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation
+        path: |
+          docs/api/html/
+          docs/sphinx/build/html/
+        retention-days: 30
+
+    - name: Prepare Pages directory
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      run: |
+        mkdir -p pages-deploy
+
+        # Landing page
+        cp docs/index.html pages-deploy/index.html
+
+        # Sphinx docs (Python API)
+        mkdir -p pages-deploy/python
+        cp -r docs/sphinx/build/html/* pages-deploy/python/
+
+        # Doxygen docs (C++ API)
+        mkdir -p pages-deploy/api
+        cp -r docs/api/html/* pages-deploy/api/
+
+        # Other docs
+        cp docs/architecture.md pages-deploy/
+        cp docs/operators.md pages-deploy/
+        cp docs/README.md pages-deploy/
+
+    - name: Deploy to GitHub Pages
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: pages-deploy/
+        publish_branch: gh-pages