Background.md draft

docs/home/background.md

@@ -0,0 +1,69 @@
+# Background
+
+## Neutral Atom Qubits
+
+The qubits that QuEra's neutral atom computer *Aquila* and Bloqade are designed to emulate are based on *neutral atoms*. As the name implies they are atoms that are neutrally charged but are also capable of achieving a [Rydberg state](https://en.wikipedia.org/wiki/Rydberg_atom) where a single electron can be excited to an incredibly high energy level without ionizing the atom.
+
+This incredibly excited electron energy level $|r\rangle$ and its default ground state $|g\rangle$ create a two-level system where superposition can occur. For enabling interaction between two or more qubits and achieving entanglement, when the neutral atoms are in the Rydberg state a phenomenon known as the Rydberg blockade can occur where an atom in the Rydberg state prevents a neighboring atom from also being excited to the same state.
+
+For a more nuanced and in-depth read about the neutral atoms that Bloqade and *Aquila* use, refer to QuEra's qBook section on [Qubits by puffing up atoms](https://qbook.quera.com/learn/?course=6630211af30e7d0013c66147&file=6630211af30e7d0013c66149).
+
+## Analog vs Digital Quantum Computing
+
+There are two modes of quantum computation that [neutral atoms](#neutral-atom-qubits) are capable of: [*Analog*](#analog-mode) and [*Digital*](#digital-mode). 
+
+You can find a brief explanation of the distinction below but for a more in-depth explanation you can refer to QuEra's qBook section on [Analog vs Digital Quantum Computing](https://qbook.quera.com/learn/?course=6630211af30e7d0013c66147&file=6630211af30e7d0013c6614a)
+
+### Analog Mode
+
+In the analog mode (supported by Bloqade and Aquila) you control your computation through the parameters of a [time-dependent Hamiltonian](#rydberg-many-body-hamiltonian) that influences all the qubits at once. There are options for [local control](#local-control) of the Hamiltonian on certain qubits however.
+
+
+### Digital Mode
+
+In the Digital Mode individual or multiple groups of qubits are controlled by applying *gates* (individual unitary operations). For [neutral atoms](#neutral-atom-qubits), this digital mode can be accomplished with the introduction of hyperfine coupling, enabling a quantum state to be stored for long periods of time while also allowing for multi-qubit gates.
+
+## Rydberg Many-Body Hamiltonian
+
+When you emulate a program in Bloqade, you are emulating the time evolution of the Rydberg many-body Hamiltonian which looks like this:
+
+$$
+i \hbar \dfrac{\partial}{\partial t} | \psi \rangle = \hat{\mathcal{H}}(t) | \psi \rangle,  \\
+$$
+
+$$
+\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,
+$$
+
+where: $\Omega_j$, $\phi_j$, and $\Delta_j$ denote the Rabi frequency *amplitude*, laser *phase*, and the *detuning* of the driving laser field on atom (qubit) $j$ coupling the two states  $| g_j \rangle$ (ground state) and $| r_j \rangle$ (Rydberg state); $\hat{n}_j = |r_j\rangle \langle r_j|$ is the number operator, and $V_{jk} = C_6/|\mathbf{x}_j - \mathbf{x}_k|^6$ describes the Rydberg interaction (van der Waals interaction) between atoms $j$ and $k$ where $\mathbf{x}_j$ denotes the *position* of the atom $j$; $C_6$ is the Rydberg interaction constant that depends on the particular Rydberg state used. For Bloqade, the default $C_6 = 862690 \times 2\pi \text{ MHz μm}^6$ for $|r \rangle = \lvert 70S_{1/2} \rangle$ of the $^{87}$Rb atoms; $\hbar$ is the reduced Planck's constant.
+
+## Local Control
+
+The [Rydberg Many-Body Hamiltonian](#rydberg-many-body-hamiltonian) already implies from its subscripts that you can also have local control over your atoms. In Bloqade this local control extends to any term in the Hamiltonian while on *Aquila* this is currently restricted to the $\Delta_j$ laser detuning term.
+
+*Fields* in Bloqade give you local (single-atom) control over the many-body Rydberg Hamiltonian.
+
+They are a sum of one or more *spatial modulations*, which allows you to *scale* the amplitude of the waveform across the different sites in the system:
+
+$$
+F_{i}(t) = \sum_{\alpha} C_{i}^{\alpha}f_{\alpha}(t) 
+$$
+
+$$
+C_{i}^{\alpha} \in \mathbb{R} 
+$$
+
+$$
+f_{\alpha}(t) \colon \mathbb{R} \to \mathbb{R}
+$$
+
+The $i$-th component of the field is used to generate the *drive* at the $i$-th site.
+
+Note that the drive is only applied if the $i$-th site is filled with an atom.
+
+You build fields in Bloqade by first specifying the spatial modulation followed by the waveform
+it should be multiplied by.
+
+In the case of a *uniform* spatial modulation, it can be interpreted as 
+a constant scaling factor where $C_{i}^{\alpha} = 1.0$.
+

docs/home/quick_start.md

@@ -1,6 +1,3 @@
-<!--If anything gets too long, break it into a separate section-->
-<!-- users will jump to the stuff they want, they won't scroll through it all-->
-<!-- Follow Configurations.jl structure -->
 # Quick Start
 
 All the sections below are self-contained, you can click on the links in the Table of Contents to read the relevant parts. 
@@ -103,10 +100,10 @@ After you've [defined a geometry](#defining-atom-geometry) you:
 
 * Specify which level coupling to drive: `rydberg` or `hyperfine`
 * Specify `detuning`, `rabi.amplitude` or `rabi.phase`
-* Specify the [spatial modulation]()
+* Specify the [spatial modulation][local-control]
 
 Which then leads you to the ability to specify a waveform of interest and begin constructing your pulse sequence. 
-In the example below, we target the ground-Rydberg level coupling to drive with uniform [spatial modulation]() for the Rabi amplitude. Our waveform is a piecewise linear one which ramps from $0$ to $5 \,\text{rad/us}$, holds that value for $1 \,\text{us}$ and then ramps back down to $0 \,\text{rad/us}$.
+In the example below, we target the ground-Rydberg level coupling to drive with uniform [spatial modulation][local-control] for the Rabi amplitude. Our waveform is a piecewise linear one which ramps from $0$ to $5 \,\text{rad/us}$, holds that value for $1 \,\text{us}$ and then ramps back down to $0 \,\text{rad/us}$.
 
 ```python
 from bloqade import start
@@ -129,7 +126,7 @@ You aren't restricted to just piecewise linear waveforms however, you can also s
 
 ## Arbitrary Functions as Waveforms
 
-For more complex waveforms it may provde to be tedious trying to chain together a large number of [`piecewise_constant`]() or [`piecewise_linear`]() methods and instead easier to just define the waveform as a function of time.
+For more complex waveforms it may provide to be tedious trying to chain together a large number of [`piecewise_constant`]() or [`piecewise_linear`]() methods and instead easier to just define the waveform as a function of time.
 
 Bloqade lets you easily plug in an arbitrary function with `.fn`:
 
@@ -251,7 +248,7 @@ program_2  = geometry_2.apply(pulse_sequence)
 ## Emulation
 
 When you've completed the definition of your program you can use Bloqade's own emulator to get results.
-The emulation performs the [time evolution]() of the [analog Rydberg Hamiltonian]().
+The emulation performs the [time evolution][rydberg-hamiltonian] of the [analog Rydberg Hamiltonian][rydberg-hamiltonian].
 Here we say we want to the program to be run and measurements obtained 1000 times.
 
 ```python
@@ -275,7 +272,7 @@ results = your_program.bloqade.python().run(1000)
 
 To submit your program to hardware ensure you have your AWS Braket credentials loaded. You will need to use the [AWS CLI]() to do this.
 
-Then it's just a matter of selecting the *Aquila* on Braket backend. Before going any further Bloqade provides two options for running your program on actul hardware:
+Then it's just a matter of selecting the *Aquila* on Braket backend. Before going any further Bloqade provides two options for running your program on actual hardware:
 
 * Using `.run` is blocking, meaning you will not be able to execute anything else while Bloqade waits for results
 * Using `.run_async` lets you submit to hardware and continue any further execution, while also letting you query the status of your program in the queue.
@@ -487,3 +484,6 @@ from bloqade import load
 emulation_results = load("emulation_results.json")
 hardware_results = load("hardware_results.json")
 ```
+
+[local-control]: background.md#local-control
+[rydberg-hamiltonian]: background.md#rydberg-many-body-hamiltonian

docs/index.md

@@ -14,7 +14,7 @@
 
 ## What is Bloqade?
 
-Bloqade is a Python SDK for [QuEra's](https://www.quera.com/) neutral atom quantum computer *Aquila* (check out our [paper](https://arxiv.org/abs/2306.11727)!). It's designed to make writing and analyzing the results of [analog quantum programs]() on *Aquila* as easy as possible. It features [custom atom geometries](index.md#customizable-atom-geometries) and [flexible waveform definitions](index.md#flexible-pulse-sequence-construction) in both [emulation and real hardware](index.md#hardware-and-emulation-backends). Bloqade interfaces with the [AWS Braket](https://aws.amazon.com/braket/) cloud service where *Aquila*  is hosted, enabling you to submit programs as well as retrieve and analyze real hardware results all-in-one.
+Bloqade is a Python SDK for [QuEra's](https://www.quera.com/) neutral atom quantum computer *Aquila* (check out our [paper](https://arxiv.org/abs/2306.11727)!). It's designed to make writing and analyzing the results of [analog quantum programs](home/background.md#analog-vs-digital-quantum-computing) on *Aquila* as easy as possible. It features [custom atom geometries](index.md#customizable-atom-geometries) and [flexible waveform definitions](index.md#flexible-pulse-sequence-construction) in both [emulation and real hardware](index.md#hardware-and-emulation-backends). Bloqade interfaces with the [AWS Braket](https://aws.amazon.com/braket/) cloud service where *Aquila*  is hosted, enabling you to submit programs as well as retrieve and analyze real hardware results all-in-one.
 
 ## Installation
 
@@ -26,7 +26,7 @@ pip install bloqade
 
 ## A Glimpse of Bloqade
 
-Let's try a simple example where we drive a [Rabi oscillation][rabi-oscillation-wiki] on a single [neutral atom](). Don't worry if you're unfamiliar with [neutral atom]() physics, (you can check out our Background for more information!) the goal here is to just give you a taste of what Bloqade can do.
+Let's try a simple example where we drive a [Rabi oscillation][rabi-oscillation-wiki] on a single [neutral atom][neutral-atom-qubits]. Don't worry if you're unfamiliar with [neutral atom][neutral-atom-qubits] physics, (you can check out our Background for more information!) the goal here is to just give you a taste of what Bloqade can do.
 
 We start by defining where our atoms go, otherwise known as the *atom geometry*. In this particular example we will use a small Honeycomb lattice:
 
@@ -48,7 +48,7 @@ geometry.show()
 </picture>
 </div>
 
-We now define what the [time evolution]() looks like using a *pulse sequence*. The pulse sequence here is the time profile of the Rabi Drive targeting the ground-Rydberg two level transition, which causes the [Rabi oscillations][rabi-oscillation-wiki]. We choose a constant waveform with a value of $\frac{\pi}{2} \text{rad}/\text{us}$ and a duration of $1.0 \,\text{us}$.
+We now define what the [time evolution][rydberg-hamiltonian] looks like using a *pulse sequence*. The pulse sequence here is the time profile of the Rabi Drive targeting the ground-Rydberg two level transition, which causes the [Rabi oscillations][rabi-oscillation-wiki]. We choose a constant waveform with a value of $\frac{\pi}{2} \text{rad}/\text{us}$ and a duration of $1.0 \,\text{us}$.
 This produces a $\frac{\pi}{2}$ rotation on the [Bloch sphere](https://en.wikipedia.org/wiki/Bloch_sphere) meaning our final measurements should be split 50/50 between the ground and Rydberg state.
 
 ```python
@@ -60,7 +60,7 @@ rabi_program = (
 )
 ```
 <!--explain what uniform is-->
-Here `rabi.amplitude` means exactly what it is, the Rabi amplitude term of the [Hamiltonian](). `uniform` refers to applying the waveform uniformly across all the atom locations. 
+Here `rabi.amplitude` means exactly what it is, the Rabi amplitude term of the [Hamiltonian][rydberg-hamiltonian]. `uniform` refers to applying the waveform uniformly across all the atom locations. 
 
 We can visualize what our program looks like again with `.show()`:
 
@@ -153,8 +153,6 @@ hardware_bitstring_counts = hardware_results.report().counts()
 
 ### Customizable Atom Geometries 
 
-<!--show that you can add_position on predefined geometries-->
-
 You can easily explore a number of common geometric lattices with Bloqade's `atom_arrangement`'s:
 
 ```python
@@ -301,6 +299,8 @@ emulation_results.report().show()
 
 ## Contributing to Bloqade
 
-Bloqade is released under the [Apache License, Version 2.0](https://github.com/QuEraComputing/bloqade-python/blob/main/LICENSE). If you'd like the chance to shape the future of [neutral atom]() quantum computation, see our [Contributing Guide](contributing/index.md) for more info!
+Bloqade is released under the [Apache License, Version 2.0](https://github.com/QuEraComputing/bloqade-python/blob/main/LICENSE). If you'd like the chance to shape the future of [neutral atom][neutral-atom-qubits] quantum computation, see our [Contributing Guide](contributing/index.md) for more info!
 
-[rabi-oscillation-wiki]: https://en.wikipedia.org/wiki/Rabi_cycle
+[rabi-oscillation-wiki]: https://en.wikipedia.org/wiki/Rabi_cycle
+[neutral-atom-qubits]: home/background.md#neutral-atom-qubits
+[rydberg-hamiltonian]: home/background.md#rydberg-many-body-hamiltonian

mkdocs.yml

@@ -12,6 +12,7 @@ nav:
   - Home:
     - index.md
     - Quickstart: home/quick_start.md
+    - Background: home/background.md
     - Getting Started: home/getting_started.md
     - Advanced Usage: home/advanced_usage.md
     - Gotchas: home/gotchas.md