Phase 1 implementation of DQI by jf-kong · Pull Request #90 · qiboteam/qiboopt

jf-kong · 2026-05-07T08:11:42Z

Summary

Adds a Phase 1 implementation of Decoded Quantum Interferometry (DQI), the non-variational quantum optimisation algorithm of Jordan et al., Optimization by Decoded Quantum Interferometry, arXiv:2408.08292 (v5), Nature 646:831–836 (2025).

DQI takes a max-LIN / max-XOR-SAT instance over GF(2) and produces samples concentrated on near-optimal solutions. This is a fundamentally different paradigm from the QAOA/XQAOA path that the rest of qiboopt is built on, so it lives in a sibling src/qiboopt/dqi/ module rather than as a method on QUBO.

What's added

New package src/qiboopt/dqi/ with:

MaxXORSAT (max_xorsat.py) — problem class wrapping (B, s) with helpers for evaluating Hamming distance to the target.
optimal_weights (weights.py) — principal eigenvector of the tridiagonal matrix from Theorem 3.4 / Eq. 70 of the paper.
weighted_dicke_amplitudes / dicke_circuit (dicke.py) — brute-force amplitude-encoded weighted Dicke superposition on the error register.
dqi_circuit (circuit.py) — full m + n qubit DQI circuit following §8.1.2: weighted Dicke prep → Z^{s_i} phasing → CNOT network for B^T y → in-circuit syndrome decoder → Hadamard transform on the solution register.
SyndromeDecoder / LUTDecoder / get_decoder (decoders/) — pluggable decoder API, with a brute-force lookup-table decoder as the Phase 1 implementation.
DQISolver (solver.py) — end-to-end solver with error-register post-selection on |0^m⟩, plus is_dqi_exact and decoder_success_probability diagnostics that make LUT-collision behaviour observable.
Sphinx page at doc/source/api-reference/dqi.rst, registered in the API index.
scipy ^1.13 added as a direct dependency (used by the tridiagonal eigenproblem in weights.py).
qiboopt.dqi re-exported from the top-level package.

Tests added for circuit construction, decoders, Dicke prep, MaxXORSAT, the weight vector, and end-to-end solver behaviour.

Phase 1 limitations (called out in the docs)

Practical only for m + n ≤ 16 on a state-vector simulator.
Brute-force Dicke prep materialises a dense 2^m × 2^m unitary and is hard-capped at m = 12. Replacing this with a count-register + Bärtschi–Eidenbenz construction is left to a future phase.
No solve_dqi entry point on QUBO; most QUBOs are not faithfully expressible as max-LIN, and we don't want to imply a generic-dense speedup.

Out of scope for this PR

Non-LUT decoders (BP, Gauss–Jordan, greedy).
Count-register Dicke prep.
Noise-model studies.

codecov · 2026-05-07T08:12:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (9272c82) to head (2612617).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main       #90    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            4        13     +9     
  Lines          660       998   +338     
==========================================
+ Hits           660       998   +338

Flag	Coverage Δ
unittests	`100.00% <100.00%> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/qiboopt/__init__.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/__init__.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/circuit.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/decoders/__init__.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/decoders/base.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/decoders/lut.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/dicke.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/max_xorsat.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/solver.py	`100.00% <100.00%> (ø)`
src/qiboopt/dqi/weights.py	`100.00% <100.00%> (ø)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

for more information, see https://pre-commit.ci

shangtai

Thanks for the PR.

I have left some comments especially for the documentations part.

shangtai · 2026-08-03T07:41:34Z

+1. Prepare the weighted Dicke superposition
+   :math:`\sum_{k=0}^{\ell} w_k \ket{D^m_k}` on the error register, where
+   :math:`w` is the principal eigenvector of the tridiagonal matrix
+   :math:`A^{(m, \ell, 0)}` of paper Eq. 70.


Suggested change

:math:`A^{(m, \ell, 0)}` of paper Eq. 70.

:math:`A^{(m, \ell, 0)}` of Eq. 70 in the paper.

shangtai · 2026-08-03T07:51:17Z

+   decoder-success branches.
+5. Apply :math:`H^{\otimes n}` on the solution register.
+6. Measure both registers; **post-select** shots whose error register
+   reads :math:`\ket{0^m}` (paper Fig. 4 caption: "postselect on


should we mention Fig. 4, or section 10.3 on Imperfect decoding?

shangtai · 2026-08-03T08:10:16Z

+   diagnostics.
+
+**Where DQI helps.** DQI gives a provable polynomial speedup on the Optimal
+Polynomial Intersection (OPI) family (Section 6 of arXiv:2408.08292) and


should we include a link to the paper here?

shangtai · 2026-08-03T08:14:03Z

+
+**Phase 1 scope.** Currently implemented: :class:`MaxXORSAT` problem class,
+optimal weight vector, weighted Dicke-state preparation, DQI circuit, the
+brute-force lookup-table decoder, and end-to-end :class:`DQISolver`.


Suggested change

brute-force lookup-table decoder, and end-to-end :class:`DQISolver`.

brute-force lookup-table (LUT) decoder, and end-to-end :class:`DQISolver`.

shangtai · 2026-08-03T08:14:31Z

+- Practical only for ``m + n <= 16`` on a state-vector simulator.
+- The brute-force amplitude-encoded Dicke prep materialises a dense
+  :math:`2^m \times 2^m` unitary and is hard-capped at ``m = 12``.
+  Replacing this with a count-register + Bartschi-Eidenbenz construction


should we include a reference here?

shangtai · 2026-08-04T01:51:23Z

Do you think we can simplify the code using qibo.models.encodings.dicke_state?

shangtai · 2026-08-04T02:09:01Z

+
+    .. math::
+
+        A_{k, k+1} = A_{k+1, k} = \sqrt{(k + 1)(m - k)},


our convention is slightly different from the paper, our k+1 is their k. Should we leave a remark?

shangtai · 2026-08-04T02:20:58Z

+
+
+def test_lut_is_exact_false_when_collisions():
+    """The reviewer's example: m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]


Suggested change

"""The reviewer's example: m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]

"""For this test, m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]

shangtai · 2026-08-04T05:50:41Z

+    """DQI's post-selected output puts more weight on the brute-force optimum
+    than uniform sampling would.
+
+    The original buggy implementation passed a "best of N shots" test


Are these comments from debugging?

shangtai · 2026-08-04T05:51:48Z

+
+
+def test_colliding_lut_marks_inexact():
+    """Reviewer's example: m=3, n=2, ell=2, B=[[1,0],[0,1],[1,1]] has 7


comment from interacting with Reviewer agent?

jf-kong added 2 commits May 3, 2026 01:41

initial implementation of DQI example

b28e685

added DQI test

1149920

jf-kong requested review from a team, mho291 and shangtai May 7, 2026 08:11

shangtai linked an issue May 7, 2026 that may be closed by this pull request

Optimization by Decoded Quantum Interferometry #11

Open

jf-kong and others added 2 commits May 8, 2026 22:31

added more tests

5228731

[pre-commit.ci] auto fixes from pre-commit.com hooks

2612617

for more information, see https://pre-commit.ci

shangtai requested changes Aug 4, 2026

View reviewed changes

Navigation Menu

Uh oh!

Phase 1 implementation of DQI - #90

Phase 1 implementation of DQI#90
jf-kong wants to merge 4 commits into
mainfrom
dqi

jf-kong commented May 7, 2026

Uh oh!

codecov Bot commented May 7, 2026 •

edited

Loading

Uh oh!

shangtai left a comment

Uh oh!

shangtai Aug 3, 2026

Uh oh!

shangtai Aug 3, 2026

Uh oh!

shangtai Aug 3, 2026

Uh oh!

shangtai Aug 3, 2026

Uh oh!

shangtai Aug 3, 2026

Uh oh!

shangtai Aug 4, 2026

Uh oh!

shangtai Aug 4, 2026

Uh oh!

shangtai Aug 4, 2026

Uh oh!

shangtai Aug 4, 2026

Uh oh!

shangtai Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	:math:`A^{(m, \ell, 0)}` of paper Eq. 70.
	:math:`A^{(m, \ell, 0)}` of Eq. 70 in the paper.

	brute-force lookup-table decoder, and end-to-end :class:`DQISolver`.
	brute-force lookup-table (LUT) decoder, and end-to-end :class:`DQISolver`.



		def test_lut_is_exact_false_when_collisions():
		"""The reviewer's example: m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]

	"""The reviewer's example: m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]
	"""For this test, m=3, n=2, ell=2 with B=[[1,0],[0,1],[1,1]]



		def test_colliding_lut_marks_inexact():
		"""Reviewer's example: m=3, n=2, ell=2, B=[[1,0],[0,1],[1,1]] has 7

Uh oh!

Conversation

jf-kong commented May 7, 2026

Summary

What's added

Phase 1 limitations (called out in the docs)

Out of scope for this PR

Uh oh!

codecov Bot commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

shangtai left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented May 7, 2026 •

edited

Loading