Restructure digital tutorials (#266)

In light of more tutorials coming in (see #260 ) I figured
re-structuring that section of the docs makes sense.

This also adds a very short example showing how you can manually include
noise in a squin kernel.

That example requires
QuEraComputing/bloqade-circuit#441 to be merged
and released though.

Author: david-pl

docs/digital/dialects_and_kernels.md

@@ -1,14 +1,39 @@
 # Dialects and kernels
 
+Bloqade provides a set of pre-defined dialects, with which you can write your programs and circuits.
+
+Once you have your kernel, you can inspect their intermediate representation (IR), apply different optimizations using [compiler passes](../quick_start/circuits/compiler_passes/index.md), or run them on a [(simulator) device](./simulator_device/simulator_device.md).
+
 !!! info
     A **kernel** function is a piece of code that runs on specialized hardware such as a quantum computer.
 
     A **dialect** is a domain-specific language (DSL) with which you can write such a kernel.
     Each dialect comes with a specific set of statements and instructions you can use in order to write your program.
 
-Bloqade provides a set of pre-defined dialects, with which you can write your programs and circuits.
 
-Once you have your kernel, you can inspect their intermediate representation (IR), apply different optimizations using [compiler passes](../quick_start/circuits/compiler_passes/index.md), or run them on a [(simulator) device](./simulator_device/simulator_device.md).
+When running code that targets a specialized execution environment, there are typically several layers involved.
+At the surface, the programmer writes functions in a syntax that may resemble a host language (e.g., Python), but is actually expressed in a dialect— a domain-specific variant with its own semantics.
+A decorator marks these functions so they can be intercepted before normal host-language execution.
+All dialects can be used by decorating a function.
+
+!!! info
+    Here's a short primer on decorators: a decorator in Python is simply a function (or any callable really) that takes in another function as argument and returns yet another function (callable).
+    Usually, the returned function will be a modified version of the input.
+    Decorators are used with the `@` syntax.
+
+
+Instead of running directly, the kernel function body is parsed and translated (lowered) into an intermediate representation (IR).
+This IR can be manipulated (e.g. to perform optimizations) and can later be executed by an interpreter that understands the dialect's semantics.
+The interpreter uses an internal instruction set to execute the code on the intended backend, which may be a simulator, virtual machine, or physical device.
+This separation lets developers write high-level, expressive code while the interpreter ensures it runs correctly in the target environment.
+[QuEra's Kirin](https://queracomputing.github.io/kirin/latest/) infrastructure uses this concept by defining custom dialects that are tailored towards the needs to program neutral atom quantum computers.
+While the dialects are not python syntax, Kirin still uses the python interpreter to execute the code.
+
+
+!!! note
+    It is important to understand that when you are writing a kernel function in a dialect you are generally **not writing Python** code, even though it looks a lot like it.
+    Therefore, kernel functions can usually not be called directly.
+    Think of this as trying to execute another programming language with the Python interpreter: of course, that will error.
 
 
 # Available dialects
@@ -128,18 +153,39 @@ main.print()
 
 ## squin
 
-This dialect is, in a sense, more expressive than the qasm2 dialects: it allows you to specify operators rather than just gate applications.
-That can be useful if you're trying to e.g. simulate a Hamiltonian time evolution.
-
 !!! warning
     The squin dialect is in an early stage of development.
     Expect substantial changes to it in the near future.
 
+
+This dialect is, in a sense, more expressive than the qasm2 dialects: it allows you to specify operators rather than just gate applications.
+That can be useful if you're trying to e.g. simulate a Hamiltonian time evolution.
+
+For simple circuits, however, gate applications also have short-hand standard library definitions defined in the `squin.gate` submodule.
 Here's a short example:
 
 ```python
 from bloqade import squin
 
+@squin.kernel
+def main():
+    q = squin.qubit.new(2)
+    squin.gate.h(q[0])
+    squin.gate.cx(q[0], q[1])
+    return squin.qubit.measure(q)
+
+# have a look at the IR
+main.print()
+```
+
+
+As mentioned above, you can also build up more complex "operators" that are then applied to any number of qubits.
+To show how you can do that, here's an example on how to write the above kernel defining the gates as separate operators.
+This isn't exactly a practical use-case, but serves as an example.
+
+```python
+from bloqade import squin
+
 @squin.kernel
 def main():
     q = squin.qubit.new(2)
@@ -148,10 +194,10 @@ def main():
     # apply a hadamard to only the first qubit
     h1 = squin.op.kron(h, squin.op.identity(sites=1))
 
-    squin.qubit.apply(h1, q)
+    squin.qubit.apply(h1, q[0], q[1])
 
     cx = squin.op.cx()
-    squin.qubit.apply(cx, q)
+    squin.qubit.apply(cx, q[0], q[1])
 
     return squin.qubit.measure(q)
 

docs/digital/examples/noisy_ghz.py renamed to docs/digital/examples/interop/noisy_ghz.py

@@ -23,7 +23,7 @@
 
 # <div align="center">
 # <picture>
-#    <img src="../ghz_linear_circuit.svg" >
+#    <img src="../../ghz_linear_circuit.svg" >
 # </picture>
 # </div>
 
@@ -60,13 +60,13 @@ def ghz_linear_program():
 # <p>
 # Before going any further, it's worth distinguishing between the concept of circuit depth and circuit execution depth.
 # For example, in the following implementation, each CX gate instruction inside the for-loop is executed in sequence.
-# So even thought the circuit depth is $log(N) = n$, the circuit execution depth is still $N$.
+# So even though the circuit depth is $log(N) = n$, the circuit execution depth is still $N$.
 # </p>
 # </div>
 
 # <div align="center">
 # <picture>
-#    <img src="../ghz_log_circuit.svg" >
+#    <img src="../../ghz_log_circuit.svg" >
 # </picture>
 # </div>
 

docs/digital/examples/noisy_ghz_fidelity.svg renamed to docs/digital/examples/interop/noisy_ghz_fidelity.svg

@@ -5,18 +5,11 @@
 # our high-level programming features.
 #
 # To begin, we will import the `qasm2` module from the `bloqade` package and the `PyQrack`
-# backend from the `bloqade.pyqrack` module, which can be installed via
-#
-# ```bash
-# pip install bloqade-pyqrack[backend]
-# ```
-# with the `backend` being one of ` pyqrack`, `pyqrack-cpu`, `pyqrack-cuda` depending on
-# the hardware and OS you have. see [README](https://github.com/QuEraComputing/bloqade-pyqrack?tab=readme-ov-file#which-extra-do-i-install)
-# for mote details.
+# backend from the `bloqade.pyqrack` module.
 # %%
 import math
 
-from bloqade.pyqrack import PyQrack
+from bloqade.pyqrack import StackMemorySimulator
 
 from bloqade import qasm2
 
@@ -56,13 +49,13 @@ def main():
 # to see the final state of the qubits after applying the QFT circuit.
 # <div align="center">
 # <picture>
-#    <img src="../qft.svg" >
+#    <img src="../../qft.svg" >
 # </picture>
 # </div>
 
 
 # %%
-device = PyQrack()
+device = StackMemorySimulator(min_qubits=3)
 qreg = device.run(main)
 print(qreg)