Initial dbsw-tabu-qaoa package

Author: gmh1784050934-netizen

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: pytest

.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+env/
+.idea/
+.vscode/
+*.log
+results/
+*.jsonl

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial GitHub-ready package layout.
+- Added Python API and CLI for Tabu-QAOA solving.
+- Added exact and QCover/Qulacs subproblem backends.
+- Added examples, tests, CI, and input-format documentation.

CITATION.cff

@@ -0,0 +1,7 @@
+cff-version: 1.2.0
+message: "If you use dbsw-qaoa in academic work, please cite this repository."
+title: "dbsw-tabu-qaoa: A packaged Tabu-QAOA solver"
+version: "0.1.0"
+date-released: "2026-06-01"
+authors:
+  - name: "DBSW-QAOA contributors"

LICENSE

@@ -0,0 +1,124 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal Entity
+authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+express or implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+You are solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages arising as a
+result of this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations. However, in accepting such obligations, You may act
+only on Your own behalf and on Your sole responsibility.

NOTICE

@@ -0,0 +1,11 @@
+dbsw-tabu-qaoa
+Copyright 2026 DBSW-QAOA contributors
+
+This project includes QCover/Qulacs simulator components copied from Qcover:
+
+  Qcover
+  Copyright BAQIS 2021, 2022
+  Licensed under the Apache License, Version 2.0.
+
+The original source files in D:\Google\qaoa_solve\Tabu-QAOA were not modified
+while preparing this package.

docs/input-format.md

@@ -0,0 +1,62 @@
+# Input Format
+
+`dbsw-qaoa solve` accepts three input formats.
+
+## QUBO Edge List
+
+Use `--format qubo`.
+
+```text
+problem_size 4
+0 0 1.0
+0 1 2.0
+1 1 -1.0
+2 3 0.5
+```
+
+The optional `problem_size` line gives the number of binary variables. Each
+remaining line is:
+
+```text
+i j coefficient
+```
+
+Variables are zero-indexed. If both `(i, j)` and `(j, i)` are present with the
+same coefficient, the duplicate is kept once. If the two directions differ,
+their values are summed.
+
+## Dense Matrix
+
+Use `--format matrix`.
+
+```text
+1.0 2.0 0.0
+0.0 -1.0 0.5
+0.0 0.0 2.0
+```
+
+Rows may be whitespace-separated or comma-separated. The matrix must be square.
+
+## Max-Cut Edge List
+
+Use `--format maxcut`.
+
+```text
+problem_size 3
+0 1 1.0
+1 2 1.0
+0 2 1.0
+```
+
+Each non-comment line is an undirected weighted graph edge:
+
+```text
+u v weight
+```
+
+The loader converts the graph to a QUBO with diagonal node-degree terms and
+off-diagonal `-2 * weight` terms.
+
+## Comments
+
+All formats allow comments beginning with `#`.

examples/basic_usage.py

@@ -0,0 +1,17 @@
+from dbsw_qaoa import SolverConfig, solve_tabu_qaoa
+
+
+def main() -> None:
+    qubo = {
+        (0, 0): 1.0,
+        (1, 1): 1.0,
+        (0, 1): 2.0,
+    }
+    config = SolverConfig(iterations=1, submatrix=2, backend="exact", seed=3)
+    result = solve_tabu_qaoa(qubo, size=2, config=config)
+
+    print(result.to_dict())
+
+
+if __name__ == "__main__":
+    main()

examples/maxcut_triangle.txt

@@ -0,0 +1,5 @@
+# Weighted triangle Max-Cut instance.
+problem_size 3
+0 1 1.0
+1 2 1.0
+0 2 1.0

examples/qubo_4.txt

@@ -0,0 +1,8 @@
+# Small QUBO example.
+problem_size 4
+0 0 1.0
+1 1 1.0
+2 2 -1.0
+3 3 -1.0
+0 1 2.0
+2 3 0.5