Document cirq interoperability (#256)

This is a WIP. Also, requires
QuEraComputing/bloqade-circuit#311 to be merged
and released first.

---------

Co-authored-by: John Long <jlong@quera.com>

Author: david-pl

docs/digital/cirq_interop/cirq_to_squin.md

@@ -0,0 +1,151 @@
+# Converting cirq to squin
+
+If you want to obtain a squin kernel from a circuit, you can use the `load_circuit` method in the `squin.cirq` submodule.
+What you're effectively doing is lowering a circuit to a squin IR.
+This IR can then be further lowered to eventually run on hardware.
+
+## Basic examples
+
+Here are some basic usage examples to help you get started.
+
+```python
+from bloqade import squin
+import cirq
+
+qubits = cirq.LineQubit.range(2)
+circuit = cirq.Circuit(
+    cirq.H(qubits[0]),
+    cirq.CX(qubits[0], qubits[1]),
+    cirq.measure(qubits)
+)
+
+# let's have a look
+print(circuit)
+
+main_loaded = squin.cirq.load_circuit(circuit, kernel_name="main_loaded")
+```
+
+The above is equivalent to writing the following kernel function yourself:
+
+```python
+@squin.kernel
+def main():
+    q = squin.qubit.new(2)
+    H = squin.op.h()
+    CX = squin.op.cx()
+    squin.qubit.apply(H, q[0])
+    squin.qubit.apply(CX, q)
+    squin.qubit.measure(q)
+```
+
+You can further inspect the lowered kernel as usual, e.g. by printing the IR.
+Let's compare the manually written version and the loaded version:
+
+```python
+main.print()
+main_loaded.print()
+```
+
+The resulting IR is equivalent, yet the loaded is a bit longer since the automated loading can make fewer assumptions about the code.
+Still, you can use the kernel as any other, e.g. by calling it from another kernel or running it via a simulator.
+
+## Noise
+
+Lowering a noisy circuit to squin is also supported.
+All common channels in cirq will be lowered to an equivalent noise statement in squin.
+
+```python
+from bloqade import squin
+import cirq
+
+qubits = cirq.LineQubit.range(2)
+noisy_circuit = cirq.Circuit(
+    cirq.H(qubits[0]),
+    cirq.CX(qubits[0], qubits[1]),
+    cirq.depolarize(p=0.01).on_each(qubits),
+)
+
+# let's have a look
+print(noisy_circuit)
+
+noisy_kernel = squin.cirq.load_circuit(noisy_circuit)
+noisy_kernel.print()
+```
+
+This becomes especially useful when used together with a `cirq.NoiseModel` that automatically adds noise to a circuit via `circuit.with_noise(model)`.
+
+## Composability of kernels
+
+You may also run into a situation, where you define a circuit that is used as part of a larger one, maybe even multiple times.
+In order to allow you to do something similar here, you can pass in and / or return the qubit register in a loaded kernel.
+Both these options are controlled by simple keyword arguments.
+
+### Qubits as argument to the kernel function
+
+Setting `register_as_argument=True` when loading a kernel, will result in a squin kernel function that accepts (and requires) a single argument of type `IList[Qubit]`.
+This means you can use a loaded circuit as part of another kernel function.
+Check it out:
+
+```python
+from bloqade import squin
+import cirq
+
+qubits = cirq.LineQubit.range(2)
+circuit = cirq.Circuit(
+    cirq.H(qubits[0]),
+    cirq.CX(qubits[0], qubits[1]),
+)
+
+sub_kernel = squin.cirq.load_circuit(circuit, register_as_argument=True, kernel_name="sub_kernel")
+
+
+@squin.kernel
+def main():
+    q = squin.qubit.new(4)
+
+    # entangle qubits 1 and 2
+    sub_kernel([q[0], q[1]])
+
+    # entangle qubits 3 and 4
+    sub_kernel([q[2], q[3]])
+
+
+main.print()
+```
+
+Looking at the IR of the resulting kernel, you can see that there is are `invoke sub_kernel` statements present, which call the lowered circuit with the given arguments.
+
+### Qubits as return value from the kernel
+
+Similarly to above, you may also want to return a list of qubits from a loaded kernel.
+Let's adapt the above to instantiate and return a pair of entangled qubits using the same circuit:
+
+```python
+
+sub_kernel = squin.cirq.load_circuit(circuit, return_register=True, kernel_name="sub_kernel")
+
+@squin.kernel
+def main():
+    # instantiate and entangle a list of two qubits
+    q1 = sub_kernel()
+
+    # do it again, to get another set
+    q2 = sub_kernel()
+
+    # now we have 4 qubits to work with
+    ...
+
+main.print()
+```
+
+
+!!! note
+    You can also mix both options by setting `register_as_argument = True` and `return_register = True` in order to obtain a kernel function that both accepts and returns a list of qubits.
+
+
+## Limitations
+
+There are some limitations when loading circuits.
+One, for example, is that custom gates are not supported as you can't generally know how to lower them to a squin statement.
+
+If you find a missing feature, please feel free to [open a GitHub issue](https://github.com/QuEraComputing/bloqade-circuit/issues).

docs/digital/cirq_interop/index.md

@@ -0,0 +1,35 @@
+# Interoperability with cirq
+
+The [Cirq](https://quantumai.google/cirq) framework is a powerful tool for writing quantum circuits targeting near-term devices.
+Instead of reinventing the wheel, Bloqade offers convenient interoperability with Cirq that allows you to jointly use both libraries in order to develop your quantum program.
+
+Specifically, you can turn a [`cirq.Circuit`](https://quantumai.google/reference/python/cirq/Circuit) object into a [squin](../dialects_and_kernels.md#squin) kernel function and vice versa.
+
+For details on each of these, please see the documentation pages below:
+
+* [Obtaining a squin kernel function from a `cirq.Circuit`](./cirq_to_squin.md)
+* [Emitting a `cirq.Circuit` from a squin kernel](./squin_to_cirq.md)
+
+For the API reference, please see the `cirq` submodule in the [squin API docs](../../reference/squin.md).
+
+## TL;DR
+
+Here's a short example:
+
+```python
+from bloqade import squin
+import cirq
+
+q = cirq.LineQubit.range(2)
+circuit = cirq.Circuit(
+    cirq.H(q[0]),
+    cirq.CX(q[0], q[1])
+)
+print(circuit)
+
+main = squin.cirq.load_circuit(circuit)
+main.print()
+
+roundtrip_circuit = squin.cirq.emit_circuit(main)
+print(roundtrip_circuit)
+```

docs/digital/cirq_interop/squin_to_cirq.md

@@ -0,0 +1,59 @@
+# Converting squin to Cirq
+
+You can convert a squin kernel function to a `cirq.Circuit` object.
+The output circuit will feature gates that most closely resemble the kernel you put in.
+
+## Basic usage
+
+You can obtain a circuit using the `squin.cirq.emit_circuit` function.
+
+```python
+from bloqade import squin
+
+@squin.kernel
+def main():
+    q = squin.qubit.new(2)
+    h = squin.op.h()
+    squin.qubit.apply(h, q[0])
+    cx = squin.op.cx()
+    squin.qubit.apply(cx, q[0], q[1])
+    squin.qubit.measure(q)
+
+circuit = squin.cirq.emit_circuit(main)
+print(circuit)
+```
+
+There is one crucial difference between a squin kernel and a cirq circuit:
+the qubits are defined inside a kernel, whereas for a circuit they are defined outside.
+
+The default behavior here is to emit a set of `cirq.LineQubit`, which is of the correct length.
+They will be sorted by their `Qid` (position) according to the order they appear in the kernel.
+
+## Customizing qubits
+
+By default, a set of `cirq.LineQubit`s of the appropriate size is created internally, on which the resulting circuit operates.
+This may be undesirable sometimes, e.g. when you want to combine multiple circuits or if you want to have qubits of a different type.
+
+To allow modifications here, you can simply pass in a list of qubits (a sequence of `cirq.Qid`s) into the emit function.
+
+```python
+import cirq
+
+qubits = cirq.GridQubit.rect(rows=1, cols=2)
+circuit = squin.cirq.emit_circuit(main, qubits=qubits)
+print(circuit)
+```
+
+Note, that the qubits will be used in the resulting circuit in the order they appear in `squin.qubit.new` statements.
+
+!!! warning
+
+    When passing in a list of qubits, you need to make sure there is sufficiently many qubits.
+    Otherwise, you may get indexing errors.
+
+## Limitations
+
+Please note that there are some limitations, especially regarding control flow.
+Using `if` statements or loops inside a kernel function may lead to errors.
+
+If you run into an issue that you think should be supported, please [report an issue on the GitHub repository](https://github.com/QuEraComputing/bloqade-circuit/issues).

mkdocs.yml

@@ -47,6 +47,10 @@ nav:
     - Simulator Device:
       - digital/simulator_device/simulator_device.md
       - digital/simulator_device/tasks.md
+    - Interoperability with Cirq:
+      - "digital/cirq_interop/index.md"
+      - "digital/cirq_interop/cirq_to_squin.md"
+      - "digital/cirq_interop/squin_to_cirq.md"
     - Circuits:
       - Quantum Fourier Transform: "digital/examples/qft.py"
       - GHZ state preparation: "digital/examples/ghz.py"