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

@@ -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 }
+      ],
+    })
+  })

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

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
 
         """