Documentation

docs/explanation/approximations/adiabatic_elimination.md

@@ -1,3 +1,5 @@
+# Adiabatic Elimination <div style="float:right;"> [![](https://img.shields.io/badge/Implementation-7C4DFF)][oqd_trical.light_matter.compiler.approximate.AdiabaticElimination] </div>
+
 The adiabatic elimination step serves to ignore negligible physics that may result in long simulation run times or simulations being aborted entirely by QuTiP.
 
 ## Single-Photon Adiabatic Elimination
@@ -8,7 +10,7 @@ A simple example of this in action is a three level system $|0\rangle, |1\rangle
 
 It also predicts that $\Delta_{0002}$ and $\Delta_{0012}$ will be large since the laser is far-detuned from these transitions (refer to Section 2.1 for subscript meanings). Because the probability $P$ of exciting the transition goes as $\frac{\Omega^2}{\Delta^2}$ for large $\Delta$, we expect transitions into level 2 to be extremely unlikely.
 
-As such, a RewriteRule named [PureElimination][trical.light_matter.compiler.rule.adiabatic_elimination.PureElimination] is tasked with traversing the Hamiltonian tree, and if $\Omega_{00ij}^2 / \Delta_{00ij}^2 \ll$ than the user-defined threshold, it will remove all terms coupling levels $i$ and $j$ ($|i\rangle\langle j|$). This has the same effect as simply removing $|2\rangle$ from the Hilbert space entirely as far as levels 0 and 1 are concerned.
+As such, a RewriteRule named [AdiabaticElimination][oqd_trical.light_matter.compiler.approximate.AdiabaticElimination] is tasked with traversing the Hamiltonian tree, and if $\Omega_{00ij}^2 / \Delta_{00ij}^2 \ll$ than the user-defined threshold, it will remove all terms coupling levels $i$ and $j$ ($|i\rangle\langle j|$). This has the same effect as simply removing $|2\rangle$ from the Hilbert space entirely as far as levels 0 and 1 are concerned.
 
 ## Raman Transitions
 

docs/explanation/approximations/lamb_dicke.md

@@ -1,3 +1,5 @@
+# Lamb-Dicke Approximation <div style="float:right;"> [![](https://img.shields.io/badge/Implementation-7C4DFF)][oqd_trical.light_matter.compiler.approximate.FirstOrderLambDickeApprox] </div>
+
 We saw in the derivation of the system Hamiltonian that the displacement operator on a motional mode is given by
 
 $$
@@ -96,7 +98,7 @@ $$
 <!-- prettier-ignore -->
 /// admonition | Note
     type: note
-The matrix elements are not computed until the abstract syntax tree representation is converted to a QuTiP-compatible object by the [QutipConversion][trical.backend.qutip.QutipConversion] rewrite rule.
+The matrix elements are not computed until the abstract syntax tree representation is converted to a QuTiP-compatible object by the [QutipCodeGeneration][oqd_trical.backend.qutip.codegen.QutipCodeGeneration] conversion rule.
 
 ///
 

docs/explanation/approximations/rotating_wave.md

@@ -1,8 +1,10 @@
+# Rotating Wave Approximation (RWA) <div style="float:right;"> [![](https://img.shields.io/badge/Implementation-7C4DFF)][oqd_trical.light_matter.compiler.approximate.RotatingWaveApprox] </div>
+
 The rotating wave approximation (RWA) simply states that any terms in the Hamiltonian oscillating faster than a user-specified cutoff, $\omega_{\text{cutoff}}$, are neglected.
 
-Looking at the [general Hamiltonian](/explanation/hamiltonian_construction/derivation#eqn:general_hamiltonian), we see that these oscillating terms will arise from the product of $e^{-i\Delta_{nmjk}t}$ and the matrix elements of $D(\alpha)$. Because we are computing these via Laguerre polynomials, it is straightforward to derive a condition on what terms must be dropped.
+Looking at the [general Hamiltonian](../hamiltonian_construction/derivation.md#eqn:general_hamiltonian), we see that these oscillating terms will arise from the product of $e^{-i\Delta_{nmjk}t}$ and the matrix elements of $D(\alpha)$. Because we are computing these via Laguerre polynomials, it is straightforward to derive a condition on what terms must be dropped.
 
-Let's first consider one of these oscillating terms for when $m\geq n$. Plugging in $\alpha = i\eta e^{i\nu t}$ into [first order Lamb-Dicke approximation](/explanation/approximations/lamb_dicke#eqn:first_order_lamb_dicke), we get
+Let's first consider one of these oscillating terms for when $m\geq n$. Plugging in $\alpha = i\eta e^{i\nu t}$ into [first order Lamb-Dicke approximation](lamb_dicke.md#eqn:first_order_lamb_dicke), we get
 
 $$
     \begin{align}

docs/explanation/hamiltonian_construction/derivation.md

@@ -11,8 +11,7 @@ Derive the [general Hamiltonian](#eqn:general_hamiltonian) of the trapped-ion sy
 - $M$ lasers
 - $L$ phonon modes
 
-Implemented with [ConstructHamiltonian][oqd_trical.light_matter.compiler.codegen.ConstructHamiltonian]
-
+Implemented with [ConstructHamiltonian][oqd_trical.light_matter.compiler.codegen.ConstructHamiltonian] for the full Hamiltonian without any of the approximations used below.
 ///
 
 ## Simple 2-level Ion System
@@ -77,7 +76,7 @@ $$
 <!-- prettier-ignore -->
 /// admonition | Note
     type: note
-The computation of the matrix elements: $\langle 1|\vec{r}_e \cdot \vec{\epsilon}_l | 0\rangle$, for dipole and quadropole transitions is described [here](/explanation/hamiltonian_construction/matrix_elements).
+The computation of the matrix elements: $\langle 1|\vec{r}_e \cdot \vec{\epsilon}_l | 0\rangle$, for dipole and quadropole transitions is described [here](matrix_elements.md).
 ///
 
 ### Interaction Picture for Spin

docs/explanation/hamiltonian_construction/matrix_elements.md

@@ -8,26 +8,50 @@ Compute the multipole matrix elements with [compute_matrix_element][oqd_trical.l
 
 ///
 
-Multipole matrix elements determine the coupling between transitions. The Rabi frequencies is defined as $\Omega = \frac{eE_0}{\hbar} \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle$. In this section we'll describe how these $\langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle$ elements are computed. Currently, TrICal supports matrix element computation for both E1 and E2 transitions.
+Multipole matrix elements determine the coupling between transitions. The Rabi frequencies is defined as
 
-Let's consider a transition from level 0 to 1 in an ion with nuclear spin $I$ and associated quantum numbers: $M_i, J_i, F_i$; these are the magnetization (a.k.a. $m_F$), spin-orbital, and total angular momentum quantum numbers. Also, let $q = M_2 - M_1$, the change in magnetization quantum number in the transiton.
+$$
+\Omega = \begin{cases}
+    \frac{eE_0}{\hbar} \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle \, \text{for electric transitions} \\
+    \frac{B_0}{\hbar} \langle 1|\vec{\mu} \cdot \hat{b}|0 \rangle \, \text{for magnetic transitions}
+\end{cases}
+$$
+
+In this section we'll describe how these $\langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle, \langle 1|\vec{\mu} \cdot \hat{b}|0 \rangle$ elements are computed. Currently, TrICal supports matrix element computation for:
+
+- [Electric dipole (E1)](#__tabbed_1_1)
+- [Magnetic dipole (M1)](#__tabbed_1_2)
+- [Electric quadrupole (E2)](#__tabbed_1_3)
+
+Let's consider a transition from level 0 to 1 in an ion with nuclear spin $I$ and associated quantum numbers:
+
+| symbol          | definition                                |
+| --------------- | ----------------------------------------- |
+| $M_i$           | magnetization (a.k.a. $m_F$)              |
+| $J_i$           | spin-orbital                              |
+| $F_i$           | total angular momentum                    |
+| $q = M_1 - M_0$ | change in magnetization for the transiton |
 
 /// tab | Electric Dipole Transitions
 
 For dipole transitions, $q$ can be $0, \pm 1$, each of which corresponds to a required polarization $\hat{q}$:
 
-- $\hat{q} = \frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ i\\ 0 \end{pmatrix}$ drives $q = -1$ transitions
-- $\hat{q} = \begin{pmatrix} 0\\ 0\\ 1 \end{pmatrix}$ drives $q = 0$ transitions ($\pi$ polarized)
-- $\hat{q} = \frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ -i\\ 0 \end{pmatrix}$ drives $q = 1$ transitions
+|              | $q$ | $\hat{q}$                                                     |
+| ------------ | --- | ------------------------------------------------------------- |
+| $\sigma_{-}$ | -1  | $\frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ i\\ 0 \end{pmatrix}$  |
+| $\pi$        | 0   | $\frac{1}{\sqrt{2}} \begin{pmatrix} 0\\ 0\\ 1 \end{pmatrix}$  |
+| $\sigma_{+}$ | 1   | $\frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ -i\\ 0 \end{pmatrix}$ |
 
-As a result, the matrix element will depend on the overlap between the laser's polarization $\hat{\epsilon}$ and the required $\hat{q}$.
+As a result, the matrix element will depend on the overlap between the laser's polarization (electric field direction) $\hat{\epsilon}$ and the required $\hat{q}$.
 
 <!-- prettier-ignore -->
 //// admonition | Important
     type: important
 
+////
+
 $$
-    \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle = \frac{1}{\omega_0 e}\sqrt{\frac{3\pi\epsilon_0\hbar c^3}{\omega_0 A_{10}}} \sqrt{(2F_1 + 1)(2F_0 + 1)}
+    \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle = \frac{1}{\omega_0 e}\sqrt{\frac{3\pi\epsilon_0\hbar c^3 A_{10}}{\omega_0 }} \sqrt{(2F_1 + 1)(2F_0 + 1)}
     \begin{Bmatrix}
         J_0 & J_1 & 1\\
         F_1 & F_0 & I
@@ -38,6 +62,38 @@ $$
     \end{pmatrix}
 $$
 
+where $\{\}$ refers to the Wigner-6j symbol and $()$ refers to the Wigner-3j symbol.
+
+///
+
+/// tab | Magnetic Dipole Transitions
+
+For dipole transitions, $q$ can be $0, \pm 1$, each of which corresponds to a required polarization $\hat{q}$:
+
+|              | $q$ | $\hat{q}$                                                     |
+| ------------ | --- | ------------------------------------------------------------- |
+| $\sigma_{-}$ | -1  | $\frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ i\\ 0 \end{pmatrix}$  |
+| $\pi$        | 0   | $\frac{1}{\sqrt{2}} \begin{pmatrix} 0\\ 0\\ 1 \end{pmatrix}$  |
+| $\sigma_{+}$ | 1   | $\frac{1}{\sqrt{2}} \begin{pmatrix} 1\\ -i\\ 0 \end{pmatrix}$ |
+
+As a result, the matrix element will depend on the overlap between the laser's magnetic field direction $\hat{b} = \hat{k} \times \hat{\epsilon}$ and the required $\hat{q}$.
+
+<!-- prettier-ignore -->
+//// admonition | Important
+    type: important
+
+$$
+    \langle 1|\vec{\mu} \cdot \hat{b}|0 \rangle = \sqrt{\frac{3 \hbar \epsilon_0 c^5 A_{10}}{16 \pi^3 \omega_0^3}} \sqrt{(2F_1 + 1)(2F_0 + 1)}
+    \begin{Bmatrix}
+        J_0 & J_1 & 1\\
+        F_1 & F_0 & I
+    \end{Bmatrix} \nonumber \\
+    \sqrt{2J_1+1} \hat{q}\cdot\hat{b}\begin{pmatrix}
+        F_1 & 1 & F_0\\
+        M_1 & -q & -M_0
+    \end{pmatrix}
+$$
+
 ////
 
 where $\{\}$ refers to the Wigner-6j symbol and $()$ refers to the Wigner-3j symbol.
@@ -46,7 +102,9 @@ where $\{\}$ refers to the Wigner-6j symbol and $()$ refers to the Wigner-3j sym
 
 /// tab | Electric Quadrupole Transitions
 
-For quadrupole transitions, the laser's unit wave-vector $\hat{k}$ becomes relevant for coupling (in addition to its polarization). In particular, the coupling strength is now proportional to the overlap between $\hat{k}$ and $\hat{Q}\hat{\epsilon}$; $\hat{Q}$ is a matrix that depends on the value for $q$, which can now be one of $0, \pm 1, \pm 2$:
+For quadrupole transitions, the laser's unit wavevector $\hat{k}$ becomes relevant for coupling (in addition to its polarization). In particular, the coupling strength is now proportional to the overlap between $\hat{k}$ and $\hat{Q}\hat{\epsilon}$.
+
+$\hat{Q}$ is a matrix that depends on the value for $q$, which can now be one of $0, \pm 1, \pm 2$:
 
 | $q$ | $\hat{Q}$                                                                             |
 | --- | ------------------------------------------------------------------------------------- |
@@ -56,14 +114,12 @@ For quadrupole transitions, the laser's unit wave-vector $\hat{k}$ becomes relev
 | 1   | $\frac{1}{\sqrt{6}}\begin{pmatrix} 0 & 0 & -1\\ 0 & 0 & i\\ -1 & i & 0\end{pmatrix}$  |
 | 2   | $\frac{1}{\sqrt{6}}\begin{pmatrix} 1 & -i & 0\\ -i & -1 & 0\\ 0 & 0 & 0\end{pmatrix}$ |
 
-This logic is handled in TrICal under the same helper function under the _polarization_map_ dictionary.
-
 <!-- prettier-ignore -->
 //// admonition | Important
     type: important
 
 $$
-    \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle = \frac{1}{\omega_0 e}\sqrt{\frac{15\pi\epsilon_0\hbar c^3}{\omega_0 A_{10}}} \sqrt{(2F_1 + 1)(2F_0 + 1)}
+    \langle 1|\vec{r}_e \cdot \hat{\epsilon}|0 \rangle = \frac{1}{\omega_0 e}\sqrt{\frac{15\pi\epsilon_0\hbar c^3 A_{10}}{\omega_0}} \sqrt{(2F_1 + 1)(2F_0 + 1)}
     \begin{Bmatrix}
         J_0 & J_1 & 2\\
         F_1 & F_0 & I

docs/explanation/reference.md

@@ -40,7 +40,11 @@ note = {Publisher: American Physical Society},
 pages = {1857--1881},
 file = {Full Text PDF:C\:\\Users\\Salieri\\Zotero\\storage\\VIPIQIPJ\\Cahill and Glauber - 1969 - Ordered Expansions in Boson Amplitude Operators.pdf:application/pdf},
 }
+```
+
+## Atomic Physics <div style="float:right;"> [![](https://img.shields.io/badge/Book-40C4FF)](https://academic.oup.com/book/52827?login=false) </div>
 
+```bib
 @book{foot_atomic_2005,
 title = {Atomic {Physics}},
 isbn = {978-0-19-850695-9},

docs/get-started/installation.md

@@ -12,8 +12,4 @@ Install with pip:
 pip install .
 ```
 
-TrICal has a dependency on [oqd_compiler_infrastructure](https://github.com/OpenQuantumDesign/compiler_infrastructure), which can be installed with:
-
-```sh
-pip install git+https://github.com/OpenQuantumDesign/compiler_infrastructure.git
-```
+TrICal has a dependency on [oqd-compiler-infrastructure](https://github.com/OpenQuantumDesign/oqd-compiler-infrastructure) and [oqd-core](https://github.com/OpenQuantumDesign/oqd-core).

docs/get-started/outlook.md

@@ -3,9 +3,10 @@
 - [ ] `oqd_trical.mechanical` uses atomic interface from [`oqd-core`](https://github.com/openquantumdesign/oqd-core).
 - [ ] `oqd_trical.mechanical` change autograd backend to jax.
 - [ ] Compute Zeeman shifts based on magnetic field.
-- [ ] Rule for rotating wave approximation.
-- [ ] Rule for moving into interaction picture for a rotating frame of reference.
-- [ ] Rule for performing adiabatic elimination.
-- [ ] Unit test for `oqd_trical`
-- [ ] [`ConstructHamiltonian`][oqd_trical.light_matter.compiler.codegen] support for sequential within parallel protocol
-- [ ] Sort out units
+- [x] Rule for Lamb-Dicke approximation. <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/16) </div>
+- [x] Rule for rotating wave approximation. <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/16) </div>
+- [x] Rule for moving into interaction picture for a rotating frame of reference. <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/16) </div>
+- [x] Rule for performing adiabatic elimination. <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/27) </div>
+- [ ] Unit test for `oqd_trical` <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/18) </div>
+- [x] [`ConstructHamiltonian`][oqd_trical.light_matter.compiler.codegen] support for sequential within parallel protocol <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/29) </div>
+- [x] Sort out units <div style="float:right;"> [![](https://img.shields.io/badge/Pull%20Request-76FF03)](https://github.com/OpenQuantumDesign/oqd-trical/pull/25) </div>

docs/index.md

@@ -4,7 +4,7 @@ TrICal (Trapped-Ion Calculator) is a python package for simulating trapped-ion p
 /// admonition | Warning
     type: warning
 TrICal is still currently in heavy development, breaking changes might be made!
-Refer to [Features in development](/get-started/outlook).
+Refer to [Features in development](get-started/outlook.md).
 ///
 
 Given a description of a trapped-ion experiment with:
@@ -22,9 +22,9 @@ Given a description of a trapped-ion experiment with:
 2. Applies approximations to the system Hamiltonian.
 3. Connects with a quantum simulation backend (e.g. QuTiP) to perform simulations.
 
-![](../figures/pipeline.png)
+![](figures/pipeline.png)
 ///
 
 TrICal is developed under [Open Quantum Design (OQD)](https://openquantumdesign.org/) as a component of the OQD open-source full stack quantum computer with trapped-ions.
 
-![](../figures/stack_diagram.png)
+![](figures/stack_diagram.png)

docs/reference/backend/dynamiqs.md

@@ -0,0 +1,9 @@
+<!-- prettier-ignore -->
+::: oqd_trical.backend.dynamiqs
+    options:
+        members: [
+            "DynamiqsBackend",
+            "DynamiqsCodeGeneration",
+            "DynamiqsVM",
+            "interface"
+        ]

docs/reference/backend/qutip.md

@@ -0,0 +1,9 @@
+<!-- prettier-ignore -->
+::: oqd_trical.backend.qutip
+    options:
+        members: [
+            "QutipBackend",
+            "QutipCodeGeneration",
+            "QutipVM",
+            "interface"
+        ]

docs/reference/compiler/analysis.md

@@ -0,0 +1 @@
+::: oqd_trical.light_matter.compiler.analysis

docs/reference/compiler/approximate.md

@@ -0,0 +1 @@
+::: oqd_trical.light_matter.compiler.approximate

docs/reference/compiler/canonicalize.md

@@ -0,0 +1 @@
+::: oqd_trical.light_matter.compiler.canonicalize

docs/reference/compiler/codegen.md

@@ -0,0 +1,7 @@
+<!-- prettier-ignore -->
+::: oqd_trical.light_matter.compiler
+    options:
+        members: [
+            "codegen",
+            "utils"
+        ]

docs/reference/compiler/visualize.md

@@ -0,0 +1 @@
+::: oqd_trical.light_matter.compiler.visualization

docs/reference/interface.md

@@ -1 +1,7 @@
+<!-- prettier-ignore -->
 ::: oqd_trical.light_matter.interface
+    options:
+        members: [
+            "emulator",
+            "operator",
+        ]

mkdocs.yaml

@@ -1,5 +1,6 @@
 site_name: Open Quantum Design - TrICal
 site_description: Trapped-ion Calculator
+site_url: https://openquantumdesign.github.io/oqd-trical/
 
 repo_name: OpenQuantumDesign/oqd-trical
 repo_url: https://github.com/OpenQuantumDesign/oqd-trical
@@ -38,20 +39,28 @@ nav:
       - Reference: explanation/reference.md
   - API Reference:
       - Mechanical:
-          - Potential: reference/potential.md
-          - Trapped Ions: reference/trappedions.md
-          - Spin Lattice: reference/spinlattice.md
+          - Potential: reference/mechanical/potential.md
+          - Trapped Ions: reference/mechanical/trappedions.md
+          - Spin Lattice: reference/mechanical/spinlattice.md
       - Light Matter Interactions:
           - Interface: reference/interface.md
-          - Compiler: reference/compiler.md
-      - Backend:
-          - QuTiP: reference/qutip.md
-          - Dynamiqs: reference/dynamiqs.md
+          - Compiler:
+              - Code Generation: reference/compiler/codegen.md
+              - Analysis: reference/compiler/analysis.md
+              - Canonicalization: reference/compiler/canonicalize.md
+              - Approximation: reference/compiler/approximate.md
+              - Visualization: reference/compiler/visualize.md
+      - Backends:
+          - QuTiP: reference/backend/qutip.md
+          - Dynamiqs: reference/backend/dynamiqs.md
       - Miscellaneous: reference/misc.md
 
 theme:
   name: material
 
+  logo: img/oqd-logo.png
+  favicon: img/oqd-logo.png
+
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
@@ -84,6 +93,7 @@ theme:
     - toc.follow
 
 plugins:
+  - search
   - mkdocstrings:
       handlers:
         python:
@@ -101,7 +111,7 @@ plugins:
             separate_signature: false
             group_by_category: true
             members_order: "source"
-          import:
+          inventories:
             - https://docs.python.org/3/objects.inv
             - https://numpy.org/doc/stable/objects.inv
             - https://matplotlib.org/stable/objects.inv

src/oqd_trical/backend/dynamiqs/__init__.py

@@ -12,12 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from . import interface
 from .base import DynamiqsBackend
 from .codegen import DynamiqsCodeGeneration
 from .vm import DynamiqsVM
 
-__all__ = [
-    "DynamiqsBackend",
-    "DynamiqsCodeGeneration",
-    "DynamiqsVM",
-]
+__all__ = ["DynamiqsBackend", "DynamiqsCodeGeneration", "DynamiqsVM", "interface"]

src/oqd_trical/backend/qutip/__init__.py

@@ -12,12 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from . import interface
 from .base import QutipBackend
 from .codegen import QutipCodeGeneration
 from .vm import QutipVM
 
-__all__ = [
-    "QutipBackend",
-    "QutipCodeGeneration",
-    "QutipVM",
-]
+__all__ = ["QutipBackend", "QutipCodeGeneration", "QutipVM", "interface"]