Add initial demo notebook and codespace config

[bachase]

This repository and initial comment fixes unitaryfoundation/ucc#296.

I decided to go with a separate repository over adding directly to the ucc repo to keep management cleaner and avoid it interfering with normal ucc development workflow.

For now, I did need to put a development version of ucc in the requirements.txt file until a version with unitaryfoundation/ucc#293 is released.

You should be able to try out the Github codespace, by selecting this initial-prototype branch, clicking the code/codespace to launch one for this branch.

I'm not yet sure how codespace caches the images, but for the first time the codespace was setup, it took a few minutes to install the right version of python and the requirements. If that is the same for others, I can look into speeding it up.

[willzeng]

This is great! This has a good walkthrough structure and it's going to be a great user experience in the end.

Had a few bugs in my run through that are commented here.

Also, codespaces defaulted to recommend that I use the Python 3.12.8 kernel which then didn't have ucc installed. When I switched it to Python 3.12.9 manually the notebook worked. This fix may not have been obvious for a user at the start and could add friction. Perhaps there is a way to avoid that default or to install ucc on a few versions in case?

[willzeng]

This cell resulted in this error for me:

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[3], line 8
      3 qubits = cirq.LineQubit.range(2)
      4 cirq_circuit = cirq.Circuit(
      5     cirq.H(qubits[0]),
      6     cirq.CNOT(qubits[0], qubits[1])
      7 )
----> 8 cirq_compiled_circuit = compile(cirq_circuit)
     10 print(cirq_circuit)
     11 print("------------------------")

TypeError: compile() missing required argument 'filename' (pos 2)

[willzeng]

This gave error:

---------------------------------------------------------------------------
TypeError                                 Traceback (most recent call last)
Cell In[4], line 7
      3 num_qubits = 10
      4 random_circuit = random_clifford_circuit(
      5     num_qubits, gates=input_gates, num_gates=10 * num_qubits * num_qubits
      6 )
----> 7 compiled_random_circuit = compile(random_circuit)
      8 print(f"Number of multi-qubit gates in original circuit: {random_circuit.num_nonlocal_gates()}")
      9 print(f"Gates used in original circuit: {random_circuit.count_ops()}")

TypeError: compile() missing required argument 'filename' (pos 2)

[willzeng]

These errors happened again in other cells but will suppress making the same comment

[bachase]

This is great! This has a good walkthrough structure and it's going to be a great user experience in the end.

Had a few bugs in my run through that are commented here.

Also, codespaces defaulted to recommend that I use the Python 3.12.8 kernel which then didn't have ucc installed. When I switched it to Python 3.12.9 manually the notebook worked. This fix may not have been obvious for a user at the start and could add friction. Perhaps there is a way to avoid that default or to install ucc on a few versions in case?

Thanks @willzeng -- I'll play some more with the codespace settings to avoid having to do that and the added friction with the different ucc version.

[jordandsullivan]

Thanks @bachase . I got the codespace to work after waiting a few minutes for it to spin up and then restarting the jupyter kernel.

Bell state

So I know that the Bell state generation code snippet is taken from our README, but practically speaking that was just meant to show that you can switch between frontends easily. Nathan was originally going to update those code snippets in unitaryfoundation/ucc#203 to be a bit more compelling.

Long story short, a Bell state (containing just H and CNOT) shouldn't get compiled down to anything else, so not really compelling to demonstrate UCC's performance.

And in fact here (as well as the TKET case), UCC is inserting extra gates where none are needed, which may be something we want to investigate:

Random Clifford

On the random clifford circuit, it is probably worth emphasizing that the UCC compiled number is actually 2-qubit gates (since the target gate set only includes cx and no higher qubit-count gates), while the number of gates generated in the random clifford can include gates on more than 2 qubits. This will help clarify why the number of compiled gates is higher than uncompiled.

This issue was meant to break those into separate counting functions unitaryfoundation/ucc#46, but we decided to simply decompose our benchmark circuits into 2 qubit gates before running each of the compile functions, to have a shared starting point. Probably also worth mentioning that different devices have different native gatesets, so decomposition is necessary.

Custom passes

Given that we are trying to give this demo tomorrow to folks who have compiler expertise, perhaps it is better to focus on diving into how you would implement a custom pass and focus less on performance. We could ask what their normal workflow looks like for implementing new passes and try to figure out how they would map onto UCC.

[bachase]

Thanks for your review and feedback @jordandsullivan!

1. Bell state Good catch on what should've been a no-op on the Bell state circuit. I'll investigate that an open a corresponding issue in ucc repo
2. Random Clifford I can add that detail to the text in the notebook. Can you confirm which gates in the generated clifford circuit are acting on more than 2 qubits? It looks like the target is all 1 or 2 qubit gates in the example. But agreed that we have a more restrictive target basis in the compilation.
   • Use idiomatic circuit.num_nonlocal_gates for qiskit circuits ucc#286 might be related a bit here? And maybe not a good change based on the nuances you highlight.
3. Custom Passes Yes, open to that being a focal point. I admit, I'm still unclear on how to frame the value prop for compiler pass writers here, so will be good to talk that out loud in the demo.

[bachase]

Pushed an update to address #2 and now uses the latest custom pass approach as discussed in unitaryfoundation/ucc#292

[nathanshammah]

Thanks @bachase and @jordandsullivan.

The notebook looks very nice to me, modulo Jordan's comments. It ran fine in Codespaces now with the new commit.

"You'll notice a much bigger change in this circuit, but again compiling to the default target gateset": I understand that you mean that here the number of gates increased? I would say it explicitly.

@jordandsullivan yes thanks for the reminder on the circuits issue.

[bachase]

"You'll notice a much bigger change in this circuit, but again compiling to the default target gateset": I understand that you mean that here the number of gates increased? I would say it explicitly.

Snuck in a fix for that.

[jordandsullivan]

Looks good @bachase . Thanks for addressing these and creating corresponding issues; I like the new framing.

[willzeng]

Great addition! *William Zeng* *President* *Unitary Foundation - because evolution is unitary* Unitary Foundation <http://www.unitary.foundation/> | Linkedin <https://www.linkedin.com/company/unitary-foundation/> | Bluesky <https://bsky.app/profile/unitaryfoundation.bsky.social> | X <https://x.com/unitaryfdn> | Discord <https://discord.com/invite/unitary-fund-764231928676089909#>

…

On Thu, Mar 13, 2025 at 5:49 AM, Brad Chase ***@***.***> wrote: Merged #1 <#1> into main. — Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABHZDAWN5BDXEPQBCIURU5T2UBQQFAVCNFSM6AAAAABYR7O2GKVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJWG4YTONJSG4ZTIMA> . You are receiving this because you were mentioned.Message ID: ***@***.***>