Adding function to create a quirk url from a bloq by Axel-pappalardo · Pull Request #1821 · quantumlib/Qualtran

Axel-pappalardo · 2026-02-26T14:59:25Z

As per the title, This adds a function which yields a quirk url from a qualtran bloq.
The function isn't perfect, and runs into many limitation:

Quirk limitation (it will only work for small circuit <16 qubits)
It only handles operation made with control, anti-control and NOT for now (but this should be easily expandable by adding new operations in the handled_operations dict), operations not handled are simply ignored.
Does not handle CBit (but should be possible to implement later if needed)

It works by using the musical score of the bloq to look through the operations column per column and thus can use a LineManager.

I also implemented a default LineManager SparseLineManager to avoid an issue where if 2 different qubit lines share the same horizontal line in a musical score (which can happen with Partition) they would be put on the same line in Quirk (this is because to determine Quirk coordinates for an operation we only look at its coordinates in the musical score).
SparseLineManager avoid this issue by reserving the slots used by any line that ends after a Partition and freeing them only if the adjoint of that Partition appears again. (for example, if I join 3 QBit into a QAny(3), the slots used by the 3 QBit are reserved until I split the QAny(3) back into 3 QBit).

An example generated with that code:
Lookup table

It could still have some issue with certain Bloq, but making specific LineManager should help
Let me know what you think

google-cla · 2026-02-26T14:59:37Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

qualtran/quirk_interop/bloq_to_quirk.py

mpharrigan · 2026-02-27T22:54:30Z

qualtran/quirk_interop/bloq_to_quirk_test.py

+def test_bloq_to_quirk():
+    bloq_to_quirk(Add(QUInt(5)))
+    bloq_to_quirk(MultiTargetCNOT(5))
+
+
+def test_bloq_to_quirk_on_atomic():
+    bloq_to_quirk(Toffoli())


can we add more robust testing than this?

I added more testing, hope this is satisfactory, testing is complicated as quirk url as quite long and pasting long url is something I prefer to avoid

…eManager + more testing

qualtran/quirk_interop/bloq_to_quirk.py

mpharrigan · 2026-03-06T21:43:06Z

qualtran/quirk_interop/bloq_to_quirk_test.py

+@pytest.mark.parametrize("n", range(3, 6))
+def test_composite_bloq_to_quirk_url_shape(n):
+    cbloq = MultiTargetCNOT(n).decompose_bloq().flatten()
+    url = composite_bloq_to_quirk(cbloq)
+
+    assert url.startswith('https://algassert.com/quirk#circuit={"cols":[')
+    assert url.endswith(']}')
+
+
+def test_bloq_to_quirk():
+    url_add = bloq_to_quirk(Add(QUInt(5)))
+    assert url_add.startswith('https://algassert.com/quirk#circuit={"cols":[')
+    assert url_add.endswith(']}')
+    url_mtcnot = bloq_to_quirk(MultiTargetCNOT(3))
+    assert (
+        url_mtcnot
+        == 'https://algassert.com/quirk#circuit={"cols":[[1,"•",1,"X"],[1,"•","X",1],["•","X",1,1],[1,"•","X",1],[1,"•",1,"X"]]}'
+    )
+
+
+def test_negate_to_quirk():
+    url = bloq_to_quirk(Negate(QUInt(2)))
+    assert (
+        url
+        == 'https://algassert.com/quirk#circuit={"cols":[["X",1,1,1,1],[1,"X",1,1,1],[1,1,1,"X",1],[1,"•",1,"•","X"],["X",1,1,1,"•"],[1,"•",1,"•","X"],["X",1,"•",1,1],[1,"X",1,"•",1],[1,1,1,"X",1]]}'
+    )


these tests would break if we change the implementation details of MultiTargetCNOT, Add, Negate, ...

Can you just wire up a simple circuit with bloq builder for testing? then the actual circuit can be small too and the url won't be huge

mpharrigan · 2026-03-06T21:43:19Z

/gemini review

gemini-code-assist

Code Review

This PR adds a new feature to generate Quirk URLs from bloqs. The implementation is mostly correct, but there are several critical issues in SparseLineManager that could lead to runtime errors due to incorrect handling of DanglingT instances. I've provided suggestions to fix these. Additionally, there are opportunities to improve code quality and portability in composite_bloq_to_quirk by refactoring the line removal logic and using the webbrowser module instead of a hardcoded subprocess call.

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+        dual_candidates = [
+            (rpos.seq_x, soq.binst.i)  # type: ignore[union-attr]
+            for soq, rpos in self.soq_assign.items()
+            if rpos.y == line and rpos.seq_x > start and soq.binst.bloq_is(dual_cls)
+        ]


The soq.binst attribute can be a DanglingT instance, which does not have bloq_is or i attributes. Accessing them will lead to a runtime AttributeError. You should add a check to ensure soq.binst is a BloqInstance before accessing these attributes.

Suggested change

dual_candidates = [

(rpos.seq_x, soq.binst.i) # type: ignore[union-attr]

for soq, rpos in self.soq_assign.items()

if rpos.y == line and rpos.seq_x > start and soq.binst.bloq_is(dual_cls)

]

from qualtran import BloqInstance

dual_candidates = [

(rpos.seq_x, soq.binst.i)

for soq, rpos in self.soq_assign.items()

if isinstance(soq.binst, BloqInstance)

and rpos.y == line

and rpos.seq_x > start

and soq.binst.bloq_is(dual_cls)

]

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+        join_to_split = {}
+        for soq, rpos in self.soq_assign.items():
+            if soq.binst.bloq_is(Join) and soq.idx == ():
+                dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Split)
+                if dual_id is not None:
+                    join_to_split[soq.binst.i] = dual_id  # type: ignore[union-attr]
+        return join_to_split


The soq.binst attribute can be a DanglingT instance, which does not have bloq_is or i attributes. Accessing them will lead to a runtime AttributeError. You should add a check to ensure soq.binst is a BloqInstance before accessing these attributes.

Suggested change

join_to_split = {}

for soq, rpos in self.soq_assign.items():

if soq.binst.bloq_is(Join) and soq.idx == ():

dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Split)

if dual_id is not None:

join_to_split[soq.binst.i] = dual_id # type: ignore[union-attr]

return join_to_split

from qualtran import BloqInstance

join_to_split = {}

for soq, rpos in self.soq_assign.items():

if isinstance(soq.binst, BloqInstance) and soq.binst.bloq_is(Join) and soq.idx == ():

dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Split)

if dual_id is not None:

join_to_split[soq.binst.i] = dual_id

return join_to_split

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+        split_to_join = {}
+        for soq, rpos in self.soq_assign.items():
+            if soq.binst.bloq_is(Split) and soq.idx != ():
+                dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Join)
+                if dual_id is not None:
+                    split_to_join[soq.binst.i] = dual_id  # type: ignore[union-attr]
+        return split_to_join


The soq.binst attribute can be a DanglingT instance, which does not have bloq_is or i attributes. Accessing them will lead to a runtime AttributeError. You should add a check to ensure soq.binst is a BloqInstance before accessing these attributes.

Suggested change

split_to_join = {}

for soq, rpos in self.soq_assign.items():

if soq.binst.bloq_is(Split) and soq.idx != ():

dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Join)

if dual_id is not None:

split_to_join[soq.binst.i] = dual_id # type: ignore[union-attr]

return split_to_join

from qualtran import BloqInstance

split_to_join = {}

for soq, rpos in self.soq_assign.items():

if isinstance(soq.binst, BloqInstance) and soq.binst.bloq_is(Split) and soq.idx != ():

dual_id = self._find_dual_on_line(rpos.y, rpos.seq_x, Join)

if dual_id is not None:

split_to_join[soq.binst.i] = dual_id

return split_to_join

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+    def maybe_reserve(self, binst, reg, idx):
+        # Reserve one slot so a partitioned wire can reclaim the same vertical region
+        # at its dual Join/Split.
+        if binst.bloq_is(Join) and reg.shape:
+            dual_id = self._join_to_split_id.get(binst.i)
+            self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)
+
+        if binst.bloq_is(Split) and not reg.shape:
+            dual_id = self._split_to_join_id.get(binst.i)
+            self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)


The binst argument can be a DanglingT instance, which does not have a bloq_is method. Calling it will lead to a runtime AttributeError. You should add a check to ensure binst is a BloqInstance before calling this method.

Suggested change

def maybe_reserve(self, binst, reg, idx):

# Reserve one slot so a partitioned wire can reclaim the same vertical region

# at its dual Join/Split.

if binst.bloq_is(Join) and reg.shape:

dual_id = self._join_to_split_id.get(binst.i)

self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)

if binst.bloq_is(Split) and not reg.shape:

dual_id = self._split_to_join_id.get(binst.i)

self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)

def maybe_reserve(self, binst, reg, idx):

from qualtran import BloqInstance

# Reserve one slot so a partitioned wire can reclaim the same vertical region

# at its dual Join/Split.

if isinstance(binst, BloqInstance) and binst.bloq_is(Join) and reg.shape:

dual_id = self._join_to_split_id.get(binst.i)

self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)

if isinstance(binst, BloqInstance) and binst.bloq_is(Split) and not reg.shape:

dual_id = self._split_to_join_id.get(binst.i)

self.reserve_n(1, lambda binst_to_check, reg_to_check: binst_to_check.i == dual_id)

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+    nb_deleted_lines = 0
+    for i in range(
+        msd.max_y + 1
+    ):  # deleting lines of the circuit which are not used (happens with partition)
+        ind = i - nb_deleted_lines
+        for col in circuit:
+            line_is_useless = col[ind] == '1'
+            if not line_is_useless:
+                break
+        if line_is_useless:
+            for col in circuit:
+                col.pop(ind)
+            nb_deleted_lines += 1


The current implementation for removing unused lines is hard to read and inefficient due to modifying lists while iterating over them. A more Pythonic and efficient approach would be to first identify the lines to keep and then construct a new circuit. This improves both readability and performance.

Suggested change

nb_deleted_lines = 0

for i in range(

msd.max_y + 1

): # deleting lines of the circuit which are not used (happens with partition)

ind = i - nb_deleted_lines

for col in circuit:

line_is_useless = col[ind] == '1'

if not line_is_useless:

break

if line_is_useless:

for col in circuit:

col.pop(ind)

nb_deleted_lines += 1

# deleting lines of the circuit which are not used (happens with partition)

if circuit:

num_lines = len(circuit[0])

lines_to_keep = [i for i in range(num_lines) if any(col[i] != '1' for col in circuit)]

circuit = [[col[i] for i in lines_to_keep] for col in circuit]

gemini-code-assist · 2026-03-06T21:49:11Z

qualtran/quirk_interop/bloq_to_quirk.py

+    if open_quirk:
+        subprocess.run(["firefox", url], check=False)


Using subprocess.run with a hardcoded "firefox" is not portable. The webbrowser module is the standard Python way to open a URL in the user's default browser, which is more portable and robust.

Suggested change

if open_quirk:

subprocess.run(["firefox", url], check=False)

if open_quirk:

import webbrowser

webbrowser.open(url)

Axel-pappalardo and others added 3 commits February 26, 2026 10:39

feat: added function to give quirk url from a qualtran's bloq

a6552cc

Merge branch 'quantumlib:main' into bloq_to_quirk

b1c6f0f

fix: linting fix

9d33db3

mpharrigan reviewed Feb 27, 2026

View reviewed changes

fix: implemented recommended correction + bug correction of SparseLin…

3726791

…eManager + more testing

mpharrigan reviewed Mar 6, 2026

View reviewed changes

gemini-code-assist bot reviewed Mar 6, 2026

View reviewed changes

Conversation

Axel-pappalardo commented Feb 26, 2026

Uh oh!

google-cla bot commented Feb 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mpharrigan Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

Axel-pappalardo Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mpharrigan Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

mpharrigan commented Mar 6, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants