From ecdafa200ec41bb9e4123307c648b097dc5f1203 Mon Sep 17 00:00:00 2001 From: John Long Date: Wed, 24 Apr 2024 09:46:49 -0400 Subject: [PATCH] Potential New Docstring Format (#929) * propose new docstring format * Add more to example * Fix lint * add standard docstring * added potential pitfalls section * ran black lint --- docs/javascripts/mathjax.js | 10 +++ mkdocs.yml | 7 +++ src/bloqade/builder/coupling.py | 106 +++++++++++++++++++++++++++----- 3 files changed, 109 insertions(+), 14 deletions(-) create mode 100644 docs/javascripts/mathjax.js diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js new file mode 100644 index 000000000..3828300a7 --- /dev/null +++ b/docs/javascripts/mathjax.js @@ -0,0 +1,10 @@ +document$.subscribe(({ body }) => { + renderMathInElement(body, { + delimiters: [ + { left: "$$", right: "$$", display: true }, + { left: "$", right: "$", display: false }, + { left: "\\(", right: "\\)", display: false }, + { left: "\\[", right: "\\]", display: true } + ], + }) + }) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 507b015ea..828448252 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -166,3 +166,10 @@ markdown_extensions: - pymdownx.tasklist: custom_checkbox: true - pymdownx.tilde + - pymdownx.arithmatex: + generic: true + +extra_javascript: + - javascripts/mathjax.js + - https://polyfill.io/v3/polyfill.min.js?features=es6 + - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js \ No newline at end of file diff --git a/src/bloqade/builder/coupling.py b/src/bloqade/builder/coupling.py index 1a3554549..175ffee84 100644 --- a/src/bloqade/builder/coupling.py +++ b/src/bloqade/builder/coupling.py @@ -6,24 +6,102 @@ class LevelCoupling(Builder): @property def detuning( self, - ) -> Detuning: # field is summation of one or more drives, - # waveform + spatial modulation = drive + ) -> Detuning: """ - Specify the [`Detuning`][bloqade.builder.field.Detuning] - [`Field`][bloqade.builder.Field] of your program. + Specify the [`Detuning`][bloqade.builder.field.Detuning] [`Field`][bloqade.builder.field.Field] of your program. You will be able to specify the spatial modulation afterwards. - A "field" is a summation of one or more "drives", with a drive being the sum - of a waveform and spatial modulation. + Args: + None - You are currently building the spatial modulation component and will be - able to specify a waveform. + Returns: + [`Detuning`][bloqade.builder.field.Detuning]: A program node representing the detuning field. - - You can do this by: - - `...detuning.uniform`: To address all atoms in the field - - `...detuning.location(locations, scales)`: To address atoms at specific - locations via indices - - `...detuning.scale(coeffs)` - - To address all atoms with an individual scale factor + ??? abstract "Background and Context" + + In the Many-Body Rydberg 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. + $$ + + The detuning is specified by the term $\Delta_j(t)$ and specifies how off-resonant the laser being applied to the atoms is from the atomic energy transition, which is driven by the Rabi frequency $\Omega_j(t)$. + + The detuning is described by a field, which is the summation of one or more drives, with the drive being the sum of a waveform and spatial modulation: + + $$ + \sum_j \Delta_j(t) = \sum_j \sum_a C^{a}_{j} f_{a}(t) + $$ + + Note that the spatial modulation $C_{j}$ scales how much of the detuning waveform is experienced by the atom at site $j$. You can specify the scaling that all atoms feel to be + identical (global detuning) or you can specify different scaling for different atoms (local detuning). + + ??? example "Examples" + + ```python + from bloqade import start + + # specify geometry, in this case just one atom + geometry = start.add_position((0,0)) + # specify your coupling (either `rydberg` or `hyperfine`) + coupling = geometry.rydberg + # Begin specifying your detuning + coupling.detuning + ``` + Alternatively you may start with building your Rabi field and then reach the ability to build your detuning like so: + + ```python + from bloqade import start + geometry = start.add_position((0,0)) + coupling = geometry.rydberg + rabi_field = coupling.rabi.amplitude.uniform.constant(duration = 1.0, value = 1.0) + detuning = rabi_field.detuning + ``` + + + ??? info "Applications" + + * [Single Qubit Floquet Dynamics](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-1-floquet/) + * [Two Qubit Adiabatic Sweep](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-2-two-qubit-adiabatic/) + * [1D Z2 State Preparation](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-3-time-sweep/) + * [2D State Preparation](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-3-2d-ordered-state/) + * [Quantum Scar Dynamics](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-4-quantum-scar-dynamics/) + * [Solving the Maximal Independent Set Problem on defective King Graph](https://queracomputing.github.io/bloqade-python-examples/latest/examples/example-5-MIS-UDG/) + + ??? warning "Potential Pitfalls" + + Bloqade allows you to build a field for the Detuning in the form of: + + $$ + \sum_j \Delta_j(t) = \sum_j \sum_a C^{a}_{j} f_{a}(t) + $$ + + Where your field can contain multiple drives. + + In reality the hardware only supports the following configuration: + + $$ + \Delta_{i}(t) = \Delta_{1}(t) + c_{i} \Delta_{2}(t) + $$ + + $$ + c_i \in [0, 1] + $$ + + $$ + \Delta_{2}(t) \leq 0 + $$ + + Where $\Delta_{1}(t)$ is your global detuning (establishable via [`uniform`][bloqade.builder.field.Detuning.uniform]) and $\Delta_{2}(t)$ is your + local detuning waveform with the spatial modulation $c_{i}$ establishable via [`location`][bloqade.builder.field.Detuning.location] or [`scale`][bloqade.builder.field.Detuning.scale]. + + # Next Possible Steps + + You may continue building your program via: + + - [`uniform`][bloqade.builder.field.Detuning.uniform]: To address all atoms in the field + - [`location(locations, scales)`][bloqade.builder.field.Detuning.location]: To address atoms at specific + locations via indices + - [`scale(coeffs)`][bloqade.builder.field.Detuning.scale]: To address all atoms with an individual scale factor """