From 796073760b9d43a69546dc259194139c47b02a1a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Henrique=20Silv=C3=A9rio?=
 <29920212+HGSilveri@users.noreply.github.com>
Date: Wed, 11 Dec 2024 13:10:35 +0100
Subject: [PATCH] Converting the Conventions page to markdown (#777)

* Setting up Markdown support

* Convert Conventions page to markdown

* Attempt to use auto-generated labels
---
 docs/requirements.txt                         |   1 +
 docs/source/conf.py                           |  20 ++
 docs/source/conventions.md                    | 260 ++++++++++++++++++
 docs/source/conventions.rst                   | 246 -----------------
 .../State Preparation with the SLM Mask.ipynb |   2 +-
 5 files changed, 282 insertions(+), 247 deletions(-)
 create mode 100644 docs/source/conventions.md
 delete mode 100644 docs/source/conventions.rst

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 9a81cc89..5c9ef500 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -5,6 +5,7 @@ sphinx_autodoc_typehints == 1.21.3
 nbsphinx
 nbsphinx-link
 ipython >= 8.10 # Avoids bug with code highlighting
+myst-parser
 
 # Not on PyPI
 # pandoc
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 507fb065..e40503e2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -34,6 +34,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "myst_parser",
     "nbsphinx",
     "nbsphinx_link",
     "sphinx.ext.autodoc",
@@ -42,6 +43,25 @@
     "sphinx_autodoc_typehints",
 ]
 
+myst_enable_extensions = [
+    "amsmath",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    # "fieldlist",
+    # "html_admonition",
+    "html_image",
+    # "linkify",
+    # "replacements",
+    # "smartquotes",
+    # "strikethrough",
+    # "substitution",
+    # "tasklist",
+]
+
+myst_heading_anchors = 3
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
diff --git a/docs/source/conventions.md b/docs/source/conventions.md
new file mode 100644
index 00000000..73c7e3b3
--- /dev/null
+++ b/docs/source/conventions.md
@@ -0,0 +1,260 @@
+# Conventions
+
+## States and Bases
+
+### Bases
+
+A basis refers to a set of two eigenstates. The transition between
+these two states is said to be addressed by a channel that targets that basis. Namely:
+
+```{eval-rst}
+.. list-table::
+   :align: center
+   :widths: 50 35 35
+   :header-rows: 1
+
+   * - Basis
+     - Eigenstates
+     - ``Channel`` type
+   * - ``ground-rydberg``
+     - :math:`|g\rangle,~|r\rangle`
+     - ``Rydberg``
+   * - ``digital``
+     - :math:`|g\rangle,~|h\rangle`
+     - ``Raman``
+   * - ``XY``
+     - :math:`|0\rangle,~|1\rangle`
+     - ``Microwave``
+
+
+```
+
+### Qutrit state
+
+The qutrit state combines the basis states of the `ground-rydberg` and `digital` bases,
+which share the same ground state, $|g\rangle$. This qutrit state comes into play
+in the digital approach, where the qubit state is encoded in $|g\rangle$ and
+$|h\rangle$ but then the Rydberg state $|r\rangle$ is accessed in multi-qubit
+gates.
+
+The qutrit state's basis vectors are defined as:
+
+$$
+|r\rangle = (1, 0, 0)^T,~~|g\rangle = (0, 1, 0)^T, ~~|h\rangle = (0, 0, 1)^T.
+$$
+
+### Qubit states
+
+:::{caution}
+There is no implicit relationship between a state's vector representation and its
+associated measurement value. To see the measurement value of a state for each
+measurement basis, see {ref}`spam-table` .
+:::
+
+When using only the `ground-rydberg` or `digital` basis, the qutrit state is not
+needed and is thus reduced to a qubit state. This reduction is made simply by tracing-out
+the extra basis state, so we obtain
+
+- `ground-rydberg`: $|r\rangle = (1, 0)^T,~~|g\rangle = (0, 1)^T$
+- `digital`: $|g\rangle = (1, 0)^T,~~|h\rangle = (0, 1)^T$
+
+On the other hand, the `XY` basis uses an independent set of qubit states that are
+labelled $|0\rangle$ and $|1\rangle$ and follow the standard convention:
+
+- `XY`: $|0\rangle = (1, 0)^T,~~|1\rangle = (0, 1)^T$
+
+### Multi-partite states
+
+The combined quantum state of multiple atoms respects their order in the `Register`.
+For a register with ordered atoms `(q0, q1, q2, ..., qn)`, the full quantum state will be
+
+$$
+|q_0, q_1, q_2, ...\rangle = |q_0\rangle \otimes |q_1\rangle \otimes |q_2\rangle \otimes ... \otimes |q_n\rangle
+$$
+
+:::{note}
+The atoms may be labelled arbitrarily without any inherent order, it's only the
+order with which they are stored in the `Register` (as returned by
+`Register.qubit_ids`) that matters .
+:::
+
+
+## State Preparation and Measurement
+
+```{eval-rst}
+.. list-table:: Initial State and Measurement Conventions
+   :name: spam-table
+   :align: center
+   :widths: 60 40 75
+   :header-rows: 1
+
+   * - Basis
+     - Initial state
+     - Measurement
+   * - ``ground-rydberg``
+     - :math:`|g\rangle`
+     - |
+       | :math:`|r\rangle \rightarrow 1`
+       | :math:`|g\rangle,|h\rangle \rightarrow 0`
+   * - ``digital``
+     - :math:`|g\rangle`
+     - |
+       | :math:`|h\rangle \rightarrow 1`
+       | :math:`|g\rangle,|r\rangle \rightarrow 0`
+   * - ``XY``
+     - :math:`|0\rangle`
+     - |
+       | :math:`|1\rangle \rightarrow 1`
+       | :math:`|0\rangle \rightarrow 0`
+```
+
+### Measurement samples order
+
+Measurement samples are returned as a sequence of 0s and 1s, in
+the same order as the atoms in the `Register` and in the multi-partite state.
+
+For example, a four-qutrit state $|q_0, q_1, q_2, q_3\rangle$ that's
+projected onto $|g, r, h, r\rangle$ when measured will record a count to
+sample
+
+- `0101`, if measured in the `ground-rydberg` basis
+- `0010`, if measured in the `digital` basis
+
+## Hamiltonians
+
+Independently of the mode of operation, the Hamiltonian describing the system
+can be written as
+
+$$
+H(t) = \sum_i \left (H^D_i(t) + \sum_{j<i}H^\text{int}_{ij} \right),
+$$
+
+where $H^D_i$ is the driving Hamiltonian for atom $i$ and
+$H^\text{int}_{ij}$ is the interaction Hamiltonian between atoms $i$
+and $j$. Note that, if multiple basis are addressed, there will be a
+corresponding driving Hamiltonian for each transition.
+
+### Driving Hamiltonian
+
+The driving Hamiltonian describes the coherent excitation of an individual atom
+between two energies levels, $|a\rangle$ and $|b\rangle$, with
+Rabi frequency $\Omega(t)$, detuning $\delta(t)$ and phase $\phi(t)$.
+
+:::{figure} files/two_level_ab.png
+:align: center
+:alt: The energy levels for the driving Hamiltonian.
+:width: 200
+
+The coherent excitation is driven between a lower energy level, $|a\rangle$, and a higher energy level,
+$|b\rangle$, with Rabi frequency $\Omega(t)$ and detuning $\delta(t)$.
+:::
+
+:::{warning}
+In this form, the Hamiltonian is **independent of the state vector representation of each basis state**,
+but it still assumes that $|b\rangle$ **has a higher energy than** $|a\rangle$.
+:::
+
+$$
+H^D(t) / \hbar = \frac{\Omega(t)}{2} e^{-i\phi(t)} |a\rangle\langle b| + \frac{\Omega(t)}{2} e^{i\phi(t)} |b\rangle\langle a| - \delta(t) |b\rangle\langle b|
+$$
+
+#### Pauli matrix form
+
+A more conventional representation of the driving Hamiltonian uses Pauli operators
+instead of projectors. However, this form now **depends on the state vector definition**
+of $|a\rangle$ and $|b\rangle$.
+
+##### Pulser's state-vector definition
+
+In Pulser, we consistently define the state vectors according to their relative energy.
+In this way we have, for any given basis, that
+
+$$
+|b\rangle = (1, 0)^T,~~|a\rangle = (0, 1)^T
+$$
+
+Thus, the Pauli and excited state occupation operators are defined as
+
+$$
+\hat{\sigma}^x = |a\rangle\langle b| + |b\rangle\langle a|, \\
+\hat{\sigma}^y = i|a\rangle\langle b| - i|b\rangle\langle a|, \\
+\hat{\sigma}^z = |b\rangle\langle b| - |a\rangle\langle a|  \\
+\hat{n} = |b\rangle\langle b| = (1 + \sigma_z) / 2
+$$
+
+and the driving Hamiltonian takes the form
+
+$$
+H^D(t) / \hbar = \frac{\Omega(t)}{2} \cos\phi(t) \hat{\sigma}^x
+- \frac{\Omega(t)}{2} \sin\phi(t) \hat{\sigma}^y
+- \delta(t) \hat{n}
+$$
+
+##### Alternative state-vector definition
+
+Outside of Pulser, the alternative definition for the basis state
+vectors might be taken:
+
+$$
+|a\rangle = (1, 0)^T,~~|b\rangle = (0, 1)^T
+$$
+
+This changes the operators and Hamiltonian definitions,
+as rewriten below with highlighted differences.
+
+$$
+\hat{\sigma}^x = |a\rangle\langle b| + |b\rangle\langle a|, \\
+\hat{\sigma}^y = \textcolor{red}{-}i|a\rangle\langle b| \textcolor{red}{+}i|b\rangle\langle a|, \\
+\hat{\sigma}^z = \textcolor{red}{-}|b\rangle\langle b| \textcolor{red}{+} |a\rangle\langle a|  \\
+\hat{n} = |b\rangle\langle b| = (1 \textcolor{red}{-} \sigma_z) / 2
+$$
+
+$$
+H^D(t) / \hbar = \frac{\Omega(t)}{2} \cos\phi(t) \hat{\sigma}^x
+\textcolor{red}{+}\frac{\Omega(t)}{2} \sin\phi(t) \hat{\sigma}^y
+- \delta(t) \hat{n}
+$$
+
+:::{note}
+A common case for the use of this alternative definition arises when
+trying to reconcile the basis states of the `ground-rydberg` basis
+(where $|r\rangle$ is the higher energy level) with the
+computational-basis state-vector convention, thus ending up with
+
+$$
+|0\rangle = |g\rangle = |a\rangle = (1, 0)^T,~~|1\rangle = |r\rangle = |b\rangle = (0, 1)^T
+$$
+:::
+
+### Interaction Hamiltonian
+
+The interaction Hamiltonian depends on the states involved in the sequence.
+When working with the `ground-rydberg` and `digital` bases, atoms interact
+when they are in the Rydberg state $|r\rangle$:
+
+$$
+H^\text{int}_{ij} = \frac{C_6}{R_{ij}^6} \hat{n}_i \hat{n}_j
+$$
+
+where $\hat{n}_i = |r\rangle\langle r|_i$ (the projector of
+atom $i$ onto the Rydberg state), $R_{ij}^6$ is the distance
+between atoms $i$ and $j$ and $C_6$ is a coefficient
+depending on the specific Rydberg level of $|r\rangle$.
+
+On the other hand, with the two Rydberg states of the `XY`
+basis, the interaction Hamiltonian takes the form
+
+$$
+H^\text{int}_{ij} =  \frac{C_3}{R_{ij}^3} (\hat{\sigma}_i^{+}\hat{\sigma}_j^{-} + \hat{\sigma}_i^{-}\hat{\sigma}_j^{+})
+$$
+
+where $C_3$ is a coefficient that depends on the chosen Ryberg states
+and
+
+$$
+\hat{\sigma}_i^{+} =  |1\rangle\langle 0|_i,~~~\hat{\sigma}_i^{-} =  |0\rangle\langle 1|_i
+$$
+
+:::{note}
+The definitions given for both interaction Hamiltonians are independent of the chosen state vector convention.
+:::
diff --git a/docs/source/conventions.rst b/docs/source/conventions.rst
deleted file mode 100644
index 32e55afb..00000000
--- a/docs/source/conventions.rst
+++ /dev/null
@@ -1,246 +0,0 @@
-****************************************
-Conventions
-****************************************
-
-States and Bases
-####################################
-
-Bases
-*******
-A basis refers to a set of two eigenstates. The transition between
-these two states is said to be addressed by a channel that targets that basis. Namely:
-
-.. list-table:: 
-   :align: center
-   :widths: 50 35 35
-   :header-rows: 1
-
-   * - Basis
-     - Eigenstates
-     - ``Channel`` type
-   * - ``ground-rydberg``
-     - :math:`|g\rangle,~|r\rangle`
-     - ``Rydberg``
-   * - ``digital``
-     - :math:`|g\rangle,~|h\rangle`
-     - ``Raman``
-   * - ``XY``
-     - :math:`|0\rangle,~|1\rangle`
-     - ``Microwave``
-
-
-
-Qutrit state
-******************
-
-The qutrit state combines the basis states of the ``ground-rydberg`` and ``digital`` bases, 
-which share the same ground state, :math:`|g\rangle`. This qutrit state comes into play
-in the digital approach, where the qubit state is encoded in :math:`|g\rangle` and 
-:math:`|h\rangle` but then the Rydberg state :math:`|r\rangle` is accessed in multi-qubit
-gates.
-
-The qutrit state's basis vectors are defined as:
-
-.. math:: |r\rangle = (1, 0, 0)^T,~~|g\rangle = (0, 1, 0)^T, ~~|h\rangle = (0, 0, 1)^T.
-
-Qubit states
-**************
-
-.. warning:: 
-  There is no implicit relationship between a state's vector representation and its 
-  associated measurement value. To see the measurement value of a state for each 
-  measurement basis, see :ref:`SPAM` .
-
-When using only the ``ground-rydberg`` or ``digital`` basis, the qutrit state is not
-needed and is thus reduced to a qubit state. This reduction is made simply by tracing-out
-the extra basis state, so we obtain
-
-* ``ground-rydberg``: :math:`|r\rangle = (1, 0)^T,~~|g\rangle = (0, 1)^T`
-* ``digital``: :math:`|g\rangle = (1, 0)^T,~~|h\rangle = (0, 1)^T`
-
-On the other hand, the ``XY`` basis uses an independent set of qubit states that are 
-labelled :math:`|0\rangle` and :math:`|1\rangle` and follow the standard convention:
-
-* ``XY``: :math:`|0\rangle = (1, 0)^T,~~|1\rangle = (0, 1)^T`
-
-Multi-partite states
-*************************
-
-The combined quantum state of multiple atoms respects their order in the ``Register``.
-For a register with ordered atoms ``(q0, q1, q2, ..., qn)``, the full quantum state will be
-
-.. math:: |q_0, q_1, q_2, ...\rangle = |q_0\rangle \otimes |q_1\rangle \otimes |q_2\rangle \otimes ... \otimes |q_n\rangle
-
-.. note::
-  The atoms may be labelled arbitrarily without any inherent order, it's only the
-  order with which they are stored in the ``Register`` (as returned by 
-  ``Register.qubit_ids``) that matters .
-
-.. _SPAM:
-
-State Preparation and Measurement
-####################################
-
-.. list-table:: Initial State and Measurement Conventions
-   :align: center
-   :widths: 60 40 75
-   :header-rows: 1
-
-   * - Basis
-     - Initial state
-     - Measurement
-   * - ``ground-rydberg``
-     - :math:`|g\rangle`
-     - |
-       | :math:`|r\rangle \rightarrow 1`
-       | :math:`|g\rangle,|h\rangle \rightarrow 0`
-   * - ``digital``
-     - :math:`|g\rangle`
-     - |
-       | :math:`|h\rangle \rightarrow 1`
-       | :math:`|g\rangle,|r\rangle \rightarrow 0`
-   * - ``XY``
-     - :math:`|0\rangle`
-     - |
-       | :math:`|1\rangle \rightarrow 1`
-       | :math:`|0\rangle \rightarrow 0`
-
-Measurement samples order
-***************************
-
-Measurement samples are returned as a sequence of 0s and 1s, in
-the same order as the atoms in the ``Register`` and in the multi-partite state.
-
-For example, a four-qutrit state :math:`|q_0, q_1, q_2, q_3\rangle` that's
-projected onto :math:`|g, r, h, r\rangle` when measured will record a count to
-sample
-
-* ``0101``, if measured in the ``ground-rydberg`` basis
-* ``0010``, if measured in the ``digital`` basis
-
-Hamiltonians
-####################################
-
-Independently of the mode of operation, the Hamiltonian describing the system
-can be written as
-
-.. math:: H(t) = \sum_i \left (H^D_i(t) + \sum_{j<i}H^\text{int}_{ij} \right), 
-
-where :math:`H^D_i` is the driving Hamiltonian for atom :math:`i` and
-:math:`H^\text{int}_{ij}` is the interaction Hamiltonian between atoms :math:`i`
-and :math:`j`. Note that, if multiple basis are addressed, there will be a 
-corresponding driving Hamiltonian for each transition.
-
-
-Driving Hamiltonian
-*********************
-
-The driving Hamiltonian describes the coherent excitation of an individual atom
-between two energies levels, :math:`|a\rangle` and :math:`|b\rangle`, with
-Rabi frequency :math:`\Omega(t)`, detuning :math:`\delta(t)` and phase :math:`\phi(t)`.
-
-.. figure:: files/two_level_ab.png
-  :align: center
-  :width: 200
-  :alt: The energy levels for the driving Hamiltonian.
-
-  The coherent excitation is driven between a lower energy level, :math:`|a\rangle`, and a higher energy level,
-  :math:`|b\rangle`, with Rabi frequency :math:`\Omega(t)` and detuning :math:`\delta(t)`.
-
-.. warning::
-  In this form, the Hamiltonian is **independent of the state vector representation of each basis state**,
-  but it still assumes that :math:`|b\rangle` **has a higher energy than** :math:`|a\rangle`.
-
-.. math:: H^D(t) / \hbar = \frac{\Omega(t)}{2} e^{-i\phi(t)} |a\rangle\langle b| + \frac{\Omega(t)}{2} e^{i\phi(t)} |b\rangle\langle a| - \delta(t) |b\rangle\langle b|
-
-Pauli matrix form
----------------------
-
-A more conventional representation of the driving Hamiltonian uses Pauli operators 
-instead of projectors. However, this form now **depends on the state vector definition**
-of :math:`|a\rangle` and :math:`|b\rangle`.
-
-Pulser's state-vector definition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In Pulser, we consistently define the state vectors according to their relative energy.
-In this way we have, for any given basis, that
-
-.. math:: |b\rangle = (1, 0)^T,~~|a\rangle = (0, 1)^T
-
-Thus, the Pauli and excited state occupation operators are defined as
-
-.. math::
-
-  \hat{\sigma}^x = |a\rangle\langle b| + |b\rangle\langle a|, \\
-  \hat{\sigma}^y = i|a\rangle\langle b| - i|b\rangle\langle a|, \\
-  \hat{\sigma}^z = |b\rangle\langle b| - |a\rangle\langle a|  \\
-  \hat{n} = |b\rangle\langle b| = (1 + \sigma_z) / 2 
-
-and the driving Hamiltonian takes the form
-
-.. math:: 
-  
-  H^D(t) / \hbar = \frac{\Omega(t)}{2} \cos\phi(t) \hat{\sigma}^x 
-  - \frac{\Omega(t)}{2} \sin\phi(t) \hat{\sigma}^y 
-  - \delta(t) \hat{n}
-
-
-Alternative state-vector definition
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Outside of Pulser, the alternative definition for the basis state 
-vectors might be taken:
-
-.. math:: |a\rangle = (1, 0)^T,~~|b\rangle = (0, 1)^T
-
-This changes the operators and Hamiltonian definitions, 
-as rewriten below with highlighted differences.
-
-.. math::
-
-  \hat{\sigma}^x = |a\rangle\langle b| + |b\rangle\langle a|, \\
-  \hat{\sigma}^y = \textcolor{red}{-}i|a\rangle\langle b| \textcolor{red}{+}i|b\rangle\langle a|, \\
-  \hat{\sigma}^z = \textcolor{red}{-}|b\rangle\langle b| \textcolor{red}{+} |a\rangle\langle a|  \\
-  \hat{n} = |b\rangle\langle b| = (1 \textcolor{red}{-} \sigma_z) / 2 
-
-.. math:: 
-  
-  H^D(t) / \hbar = \frac{\Omega(t)}{2} \cos\phi(t) \hat{\sigma}^x 
-  \textcolor{red}{+}\frac{\Omega(t)}{2} \sin\phi(t) \hat{\sigma}^y 
-  - \delta(t) \hat{n}
-
-.. note::
-  A common case for the use of this alternative definition arises when
-  trying to reconcile the  basis states of the ``ground-rydberg`` basis 
-  (where :math:`|r\rangle` is the higher energy level) with the 
-  computational-basis state-vector convention, thus ending up with 
-
-  .. math:: |0\rangle = |g\rangle = |a\rangle = (1, 0)^T,~~|1\rangle = |r\rangle = |b\rangle = (0, 1)^T
-
-
-Interaction Hamiltonian
-*************************
-
-The interaction Hamiltonian depends on the states involved in the sequence. 
-When working with the ``ground-rydberg`` and ``digital`` bases, atoms interact
-when they are in the Rydberg state :math:`|r\rangle`:
-
-.. math:: H^\text{int}_{ij} = \frac{C_6}{R_{ij}^6} \hat{n}_i \hat{n}_j
-
-where :math:`\hat{n}_i = |r\rangle\langle r|_i` (the projector of
-atom :math:`i` onto the Rydberg state), :math:`R_{ij}^6` is the distance 
-between atoms :math:`i` and :math:`j` and :math:`C_6` is a coefficient
-depending on the specific Rydberg level of :math:`|r\rangle`.
-
-On the other hand, with the two Rydberg states of the ``XY``
-basis, the interaction Hamiltonian takes the form
-
-.. math:: H^\text{int}_{ij} =  \frac{C_3}{R_{ij}^3} (\hat{\sigma}_i^{+}\hat{\sigma}_j^{-} + \hat{\sigma}_i^{-}\hat{\sigma}_j^{+})
-
-where :math:`C_3` is a coefficient that depends on the chosen Ryberg states
-and 
-
-.. math:: \hat{\sigma}_i^{+} =  |1\rangle\langle 0|_i,~~~\hat{\sigma}_i^{-} =  |0\rangle\langle 1|_i
-
-.. note:: The definitions given for both interaction Hamiltonians are independent of the chosen state vector convention.
\ No newline at end of file
diff --git a/tutorials/advanced_features/State Preparation with the SLM Mask.ipynb b/tutorials/advanced_features/State Preparation with the SLM Mask.ipynb
index 807cd2c9..a4826ced 100644
--- a/tutorials/advanced_features/State Preparation with the SLM Mask.ipynb	
+++ b/tutorials/advanced_features/State Preparation with the SLM Mask.ipynb	
@@ -154,7 +154,7 @@
    "id": "21c01972",
    "metadata": {},
    "source": [
-    "Now let's see how the system evolves under this masked pulse. Since the pulse only acts on the first qubit, we expect the final state to be $\\left| 100 \\right\\rangle$, or, according to [Pulser's conventions for XY basis states](../conventions.rst#qubit-states), $(0,1)^T \\otimes (1,0)^T \\otimes (1,0)^T$ in the Hilbert space $C^8$:"
+    "Now let's see how the system evolves under this masked pulse. Since the pulse only acts on the first qubit, we expect the final state to be $\\left| 100 \\right\\rangle$, or, according to [Pulser's conventions for XY basis states](../conventions.md#qubit-states), $(0,1)^T \\otimes (1,0)^T \\otimes (1,0)^T$ in the Hilbert space $C^8$:"
    ]
   },
   {