Update documentation to match the upcoming SQUIN refactor (#291)

FYI, @jon-wurtz I updated the tutorial you wrote in order to match the
new semantics. Something to keep in mind while working on coming
tutorials.

Also, we need to support lowering of `cirq.ZZPowGate` or, equivalently,
`cirq.CZPowGate` for arbitrary exponents again, which is something I
still need to address.

Still need to rewrite the actual documentation pages.

---------

Co-authored-by: Rafael Haenel <[email protected]>
Co-authored-by: John Long <[email protected]>

Author: 3 people

docs/background.md

@@ -2,7 +2,7 @@
 
 ## Neutral Atom Qubits
 
-A key feature of a quantum computer is the ability to physically represent qubits. In neutral atom computers, the qubit is represented in the electronic state of the valence electron of Rubdidium 87. Arrays of individual atoms are held by laser tweezers, and quantum computations are executed by manipulating the electronic state of each atom using lasers and RF fields. Entanglement can be generated using the [Rydberg state](https://en.wikipedia.org/wiki/Rydberg_atom), which is a highly excited state that strongly interacts with adjacent atoms through a $R^{-6}$ power law Van der Waals force.
+A key feature of a quantum computer is the ability to physically represent qubits. In neutral atom computers, the qubit is represented in the electronic state of the valence electron of Rubidium 87. Arrays of individual atoms are held by laser tweezers, and quantum computations are executed by manipulating the electronic state of each atom using lasers and RF fields. Entanglement can be generated using the [Rydberg state](https://en.wikipedia.org/wiki/Rydberg_atom), which is a highly excited state that strongly interacts with adjacent atoms through a $R^{-6}$ power law Van der Waals force.
 
 
 
@@ -14,7 +14,7 @@ $$
 i \hbar \dfrac{\partial}{\partial t} | \psi \rangle = \hat{\mathcal{H}}(t) | \psi \rangle,  \\
 $$
 
-Were $H$ is a time-dependent "Rydberg atom" Hamiltonian.
+where $H$ is a time-dependent "Rydberg atom" Hamiltonian.
 
 $$
 \frac{\mathcal{H}(t)}{\hbar} = \sum_j \frac{\Omega_j(t)}{2} \left( e^{i \phi_j(t) } | g_j \rangle  \langle r_j | + e^{-i \phi_j(t) } | r_j \rangle  \langle g_j | \right) - \sum_j \Delta_j(t) \hat{n}_j + \sum_{j < k} V_{jk} \hat{n}_j \hat{n}_k,

docs/blog/posts/2023/bloqade-release.md

@@ -78,7 +78,7 @@ adiabatic_program = (
         ],
     )
     .assign(max_rabi=15.8, max_detuning=16.33)
-    .batch_assign(lattice_spacing=np.arrange(4.0, 7.0, 0.5))
+    .batch_assign(lattice_spacing=np.arange(4.0, 7.0, 0.5))
 )
 
 # Launch your program on your choice of Braket or in-house emulator...
@@ -121,7 +121,7 @@ During the next year, we plan on continuing development of Bloqade's python inte
 
 That's right! However, there's a key motivating factor for the reason we created Bloqade Python that's distinct for Bloqade.jl's existence.
 
-Bloqade.jl is primarily geared as a *high-performance emulator*. It allows you to design complex neutral-atom algorithms that may not necessarily run on our hardware BUT are excellent if you're exploring novel physical phenonema/algorithms or as a tool for pedagogical purposes.
+Bloqade.jl is primarily geared as a *high-performance emulator*. It allows you to design complex neutral-atom algorithms that may not necessarily run on our hardware BUT are excellent if you're exploring novel physical phenomena/algorithms or as a tool for pedagogical purposes.
 
 Bloqade.jl does have the ability to submit to [*Aquila*](https://www.quera.com/aquila), our flagship quantum computer, but for more complex tasks such as sweeping parameters (e.g. running the same program on hardware with slightly different parameters each time) or advanced post-processing, it becomes cumbersome quite quickly.
 

docs/blog/posts/2025/a-new-journey.md

@@ -38,4 +38,4 @@ The first step in Bloqade's journey was building out the analog mode SDK, design
 
 ## Learn more
 
-Bloqade is an open-source project and can be freely downloaded and modified; you can learn how to do so [here](../../../install.md). If you want to see how to write programs with of the new `bloqade` package, check out our examples [here](../../../digital/index.md). If you would like to learn more about QuEra Computing Inc., check out our [webpage](https://quera.com) as well as discover our many [academic publications and demonstrations](https://www.quera.com/news#publications).
+Bloqade is an open-source project and can be freely downloaded and modified; you can learn how to do so [here](../../../install.md). If you want to see how to write programs with the new `bloqade` package, check out our examples [here](../../../digital/index.md). If you would like to learn more about QuEra Computing Inc., check out our [webpage](https://quera.com) as well as discover our many [academic publications and demonstrations](https://www.quera.com/news#publications).

docs/contrib.md

@@ -27,7 +27,7 @@ or for a specific test file with the `-s` flag to show the output of the program
 pytest -s tests/test_program.py
 ```
 
-lots of tests contains pretty printing of the IR themselves, so it's useful to see the output.
+lots of tests contain pretty printing of the IR themselves, so it's useful to see the output.
 
 ## Code style
 
@@ -37,7 +37,7 @@ good-to-have practices:
 ### Naming
 
 - try not to use abbreviation as names, unless it's a common abbreviation like `idx` for `index`
-- try not create a lot of duplicated name prefix unless the extra information is necessary when accessing the class object.
+- try not to create a lot of duplicated name prefix unless the extra information is necessary when accessing the class object.
 - try to use `snake_case` for naming variables and functions, and `CamelCase` for classes.
 
 ### Comments
@@ -47,7 +47,7 @@ good-to-have practices:
 
 ## Documentation
 
-We use `just` for mangaging command line tools and scripts. It should be installed when you run `uv sync`. To build the documentation, simply run:
+We use `just` for managing command line tools and scripts. It should be installed when you run `uv sync`. To build the documentation, simply run:
 
 ```bash
 just doc

docs/digital/cirq_interop/cirq_to_squin.md

@@ -1,6 +1,6 @@
 # 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.
+If you want to obtain a squin kernel from a circuit, you can use the `load_circuit` method in the `cirq_utils` 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.
 
@@ -9,7 +9,7 @@ This IR can then be further lowered to eventually run on hardware.
 Here are some basic usage examples to help you get started.
 
 ```python
-from bloqade import squin
+from bloqade import squin, cirq_utils
 import cirq
 
 qubits = cirq.LineQubit.range(2)
@@ -22,19 +22,17 @@ circuit = cirq.Circuit(
 # let's have a look
 print(circuit)
 
-main_loaded = squin.cirq.load_circuit(circuit, kernel_name="main_loaded")
+main_loaded = cirq_utils.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)
+    q = squin.qalloc(2)
+    squin.h(q[0])
+    squin.cx(q[0], q[1])
     squin.qubit.measure(q)
 ```
 
@@ -55,7 +53,7 @@ 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
+from bloqade import cirq_utils
 import cirq
 
 qubits = cirq.LineQubit.range(2)
@@ -68,7 +66,7 @@ noisy_circuit = cirq.Circuit(
 # let's have a look
 print(noisy_circuit)
 
-noisy_kernel = squin.cirq.load_circuit(noisy_circuit)
+noisy_kernel = cirq_utils.load_circuit(noisy_circuit)
 noisy_kernel.print()
 ```
 
@@ -87,7 +85,7 @@ This means you can use a loaded circuit as part of another kernel function.
 Check it out:
 
 ```python
-from bloqade import squin
+from bloqade import squin, cirq_utils
 import cirq
 
 qubits = cirq.LineQubit.range(2)
@@ -96,12 +94,12 @@ circuit = cirq.Circuit(
     cirq.CX(qubits[0], qubits[1]),
 )
 
-sub_kernel = squin.cirq.load_circuit(circuit, register_as_argument=True, kernel_name="sub_kernel")
+sub_kernel = cirq_utils.load_circuit(circuit, register_as_argument=True, kernel_name="sub_kernel")
 
 
 @squin.kernel
 def main():
-    q = squin.qubit.new(4)
+    q = squin.qalloc(4)
 
     # entangle qubits 1 and 2
     sub_kernel([q[0], q[1]])
@@ -122,7 +120,7 @@ Let's adapt the above to instantiate and return a pair of entangled qubits using
 
 ```python
 
-sub_kernel = squin.cirq.load_circuit(circuit, return_register=True, kernel_name="sub_kernel")
+sub_kernel = cirq_utils.load_circuit(circuit, return_register=True, kernel_name="sub_kernel")
 
 @squin.kernel
 def main():

docs/digital/cirq_interop/index.md

@@ -10,14 +10,14 @@ 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/bloqade-circuit/src/bloqade/squin.md).
+For the API reference, please see the `cirq_utils` submodule in the API reference, specifically [here](../../reference/bloqade-circuit/src/bloqade/cirq_utils/lowering.md) and [here](../../reference/bloqade-circuit/src/bloqade/cirq_utils/emit/base.md).
 
 ## TL;DR
 
 Here's a short example:
 
 ```python
-from bloqade import squin
+from bloqade import cirq_utils
 import cirq
 
 q = cirq.LineQubit.range(2)
@@ -27,9 +27,9 @@ circuit = cirq.Circuit(
 )
 print(circuit)
 
-main = squin.cirq.load_circuit(circuit)
+main = cirq_utils.load_circuit(circuit)
 main.print()
 
-roundtrip_circuit = squin.cirq.emit_circuit(main)
+roundtrip_circuit = cirq_utils.emit_circuit(main)
 print(roundtrip_circuit)
 ```

docs/digital/cirq_interop/squin_to_cirq.md

@@ -5,21 +5,21 @@ The output circuit will feature gates that most closely resemble the kernel you
 
 ## Basic usage
 
-You can obtain a circuit using the `squin.cirq.emit_circuit` function.
+You can obtain a circuit using the `cirq_utils.emit_circuit` function.
 
 ```python
-from bloqade import squin
+from bloqade import squin, cirq_utils
 
 @squin.kernel
 def main():
-    q = squin.qubit.new(2)
+    q = squin.qalloc(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)
+circuit = cirq_utils.emit_circuit(main)
 print(circuit)
 ```
 
@@ -40,11 +40,11 @@ To allow modifications here, you can simply pass in a list of qubits (a sequence
 import cirq
 
 qubits = cirq.GridQubit.rect(rows=1, cols=2)
-circuit = squin.cirq.emit_circuit(main, qubits=qubits)
+circuit = cirq_utils.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.
+Note, that the qubits will be used in the resulting circuit in the order they appear in `squin.qalloc` statements.
 
 !!! warning
 

docs/digital/dialects_and_kernels/index.md

@@ -52,15 +52,15 @@ Have a look at the (growing) [examples collection](../examples/), where you can
 
 ## [squin](./squin.md)
 
-With this dialect, you can structure your program in terms of operators rather than gate applications, or define circuits.
+This is the central dialect of bloqade-circuit, with which you can write your quantum programs.
+Rather than just defining circuits in terms of gates and qubits, this dialect also makes it possible to use control flow.
 Have a look at [the dedicated documentation page](./squin.md) and the corresponding [API reference](../../reference/bloqade-circuit/src/bloqade/squin/).
 
 **Use cases**:
 
 * Writing a program that represents a circuit.
 * If you require control flow (loops and if-statements, ...) and composability (function definitions, recursion, ...).
 * Simulation including noise.
-* Hamiltonian simulation (work in progress).
 
 
 ## [qasm2](./qasm2.md)