From c0d4838501a6b223e855818e457f058bbd11e674 Mon Sep 17 00:00:00 2001
From: HGSilveri <henrique.silverio@tecnico.ulisboa.pt>
Date: Mon, 9 Dec 2024 10:54:24 +0100
Subject: [PATCH 1/7] Setting up Markdown support

---
 docs/requirements.txt | 1 +
 docs/source/conf.py   | 1 +
 2 files changed, 2 insertions(+)

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..3e4e9f50 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",

From 82c2070b086db5aa1466a45980eac44da9b4362d Mon Sep 17 00:00:00 2001
From: HGSilveri <henrique.silverio@tecnico.ulisboa.pt>
Date: Mon, 9 Dec 2024 14:09:11 +0100
Subject: [PATCH 2/7] Convert Conventions page to markdown

---
 docs/source/conf.py         |  17 +++
 docs/source/conventions.md  | 260 ++++++++++++++++++++++++++++++++++++
 docs/source/conventions.rst | 246 ----------------------------------
 3 files changed, 277 insertions(+), 246 deletions(-)
 create mode 100644 docs/source/conventions.md
 delete mode 100644 docs/source/conventions.rst

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3e4e9f50..410bd7f3 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -43,6 +43,23 @@
     "sphinx_autodoc_typehints",
 ]
 
+myst_enable_extensions = [
+    "amsmath",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    # "fieldlist",
+    # "html_admonition",
+    "html_image",
+    # "linkify",
+    # "replacements",
+    # "smartquotes",
+    # "strikethrough",
+    # "substitution",
+    # "tasklist",
+]
+
 # 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

From 3ab86c50112c74b90579c8aab9483884ac885b29 Mon Sep 17 00:00:00 2001
From: HGSilveri <henrique.silverio@tecnico.ulisboa.pt>
Date: Mon, 9 Dec 2024 14:42:30 +0100
Subject: [PATCH 3/7] Attempt to use auto-generated labels

---
 docs/source/conf.py                                             | 2 ++
 .../advanced_features/State Preparation with the SLM Mask.ipynb | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 410bd7f3..e40503e2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -60,6 +60,8 @@
     # "tasklist",
 ]
 
+myst_heading_anchors = 3
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
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$:"
    ]
   },
   {

From d62edaf39adf043d1ce8f53ccd89f661cc0668db Mon Sep 17 00:00:00 2001
From: a_corni <antoine.cornillot@pasqal.com>
Date: Thu, 12 Dec 2024 11:01:48 +0100
Subject: [PATCH 4/7] Introduce section about hardware

---
 docs/source/hardware.md | 62 +++++++++++++++++++++++++++++++++++++++++
 docs/source/index.rst   |  1 +
 2 files changed, 63 insertions(+)
 create mode 100644 docs/source/hardware.md

diff --git a/docs/source/hardware.md b/docs/source/hardware.md
new file mode 100644
index 00000000..919d4e79
--- /dev/null
+++ b/docs/source/hardware.md
@@ -0,0 +1,62 @@
+# Neutral-atom Hardware
+
+## How does a neutral-atom Quantum Computer work ?
+
+A neutral-atom Quantum Computer is composed of neutral-atoms (typically, atoms of Rubidium or Cesium that belong to the first column of the Mendeleiev table, but quantum computing platforms have also been built using atoms of Ytterbium and Dysprosium that belong to the second column of the Mendeleiev table). To perform quantum computations with these atoms, we "cool" them down to very small temperatures (typically, $`10\mu`K) using lasers. Note: The neutral-atoms are in fact slowed down, and the temperature here is associated to their speed. Neutral-atom Quantum Computers are sometimes named cold-atom Quantum Computers because the atoms are "cold", ie there associated temperature is small.
+
+Since these atoms are cold, they can be trapped in space using another kind of lasers (see the `RegisterLayout` object in the extended section). They can then be rearranged and re-trapped in a specific pattern, that we name the register (see the `Register` section of the fundamentals). The atoms spend enough time trapped such that we are sure they are all in the ground state (the initial state for the computations, see the [conventions page](conventions.md)).
+
+The computation in itself can then happen: a serie of laser pulses are applied on the atoms to modify their state. The laser pulses can target different transition, each transition being associated to a different laser channel (see below).
+
+Once the computation is over, the state of the atoms is measured. Here as well, this is done using lasers: some light is shine on the atoms, the atoms that re-emit this light are measured in the ground-state and are labelled `0`, the others are described as being in an excited state and are labelled `1` (see the [convention page](conventions.md) for more). 
+
+## Physical parameters to take into account in quantum computations
+
+As sketched in the above section, making a quantum computation with a neutral-atom device involves multiple steps and the use of multiple lasers. At each step and laser used, the physics of the device constrains the displacement of the atoms. In `Pulser`, all the physical constrains are stored in the `Device` object.
+
+### Device
+
+The `Device` class stores all the physical constrains the quantum computations should match. To perform any computation using Pulser, it is necessary to provide a device. For convenience, some examples of typical physical devices are included and can be accessed via `pulser.devices`. These devices are instances of the `Device` class. They are constrained by physical considerations and all their parameters are defined. An example of such a `Device`, the `pulser.AnalogDevice`, is provided below.
+
+If we go back to the timeline of a quantum computation using a neutral-atom device, the first step is the trapping of atoms in space and their rearrangement into a defined register. The first constraints concern the definition of the layout of traps and the register. They can be defined in 2D or 3D (check the `dimensions` attribute) but the register of atoms must be a subset of the layout of traps. Therefore, some constrains apply to both: the distance between each traps/atoms must be greater than the distance `min_atom_distance`, the traps/atoms should not be defined at a distance greater than `max_radial_distance` from the center.
+
+The register is a subset of the number of traps because by default some stochastical effects are at play, such that in theory a trap has a probability 1/2 to be filled by an atom. That way, there is a maximum number of traps of the layout that can be filled by an atom from the register (given by `max_layout_filling`), and there is also an optimal for this filling, (given by `optimal_layout_filling`).
+
+In terms of performance, there is a maximum number of atoms that can be trapped and rearranged in the register (`max_atom_num`) and a maximum number of traps that can be defined in the layout (`max_layout_traps`). From the considerations above, these two numbers are different. There is also a minimum number of traps to have in the layout (`min_layout_traps`).
+
+The considerations about the layout are unnessary if the device does not require one to be associated with the `Register`, which is given by the `requires_layout` parameter. If `requires_layout` is True, then the `Register` must have a layout associated to it. We invite you to check the layout section in the advanced features to see how to attach a layout to a register in detail. Generating a layout spatially is a complex operation that needs some calibrations. Some devices provide a bank of pre-calibrated layouts in the `pre_calibrated_layouts` attribute, for which the calibration has already been performed (meaning, the computations will be faster than for a non-calibrated layout). If the device does not accept new layouts (`accepts_new_layouts` is False), then the register must be a subset of one of the pre-calibrated layouts.
+
+Now that we have seen all the constraints regarding the definition of the register of atoms, the next step of a quantum computation is to apply a sequence of pulses targeting a specific transition using `Channels`. The list of channels available in the device are accessible via the `channels` property. Some specific `Channels` are the `DetuningMapModulator` channels, that are listed in the `dmm_channels` property. These specific channels are further detailed in [their section in the extended features](tutorials/dmm.nblink). They are associated with the concept of SLM mask that some device supports (the `supports_slm_mask` attribute, check [the section on SLM](tutorials/slm_mask.nblink) to learn more).
+
+The physical constraints applied by a `Channel` are described below. More globally than a channel, the duration of the sequence of pulses should not be longer than `max_sequence_duration`. When a pulse is applied on a `Channel`, the atoms can interact between each other depending on the transition targeted by the `Channel`. When the channel aims at exciting the atoms to the rydberg state, then the Rydberg coefficient is defined from a `rydberg_level` defined in the device (see the [conventions page](conventions.md)). When using the `Microwave` channel, the `C_3` coefficient is defined by the `interaction_coeff_xy`.
+
+The device can also define some parameters used at execution on the backend. A backend can be a QPU (it should then have an associated device) or an emulator. In either case, the maximum number of runs, that is, the maximum number of times the cycle register-pulser-measurement can be performed for a quantum program, can be defined in the device (`max_runs`). The device also contains all the information about the noise to model the device (like, the temperature of the atoms) in `default_noise_model`. You can read more about the backends and the noise model in the [backend section](./tutorials/backends.nblink).
+
+### Channels
+
+Each pulse modifying the state of the atoms is applied via a laser channel. A channel targets a specific transition between two states, named the eigenstates. These two eigenstates form a basis. You can check the basis currently implemented in Pulser and their associated eigenstates in the [conventions page](./conventions.md). A laser channel can address the atoms globally (all the atoms are addressed at the same time) or locally (atoms are targeted separately). This is described by the `addressing` attribute of the `Channel` object.
+
+The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst##pulse)). The laser channels constrain these parameters: 
+- the duration must to be longer than `min_duration` but shorter than `max_duration`. It also has to be a multiple of `clock_duration`. 
+- the amplitude must be between 0 and `max_amp`. If the amplitude of a pulse is not constant equal to zero, its average must be higher than `min_avg_amp`.
+- the detuning must be between -`max_abs_detuning` and `max_abs_detuning`.
+
+When using channels having a local `addressing`, other constraints emerge. For instance, there is a maximum number of atoms that can be targeted by each pulse (`max_targets`). Changing the atoms targeted by the channel takes also some time. This time must be greater than `min_retarget_interval` and is sometimes forced to be `fixed_retarget_t`. However, these channels are hard to implement in hardware and a prefered way to program local channels must be the `DMM` channels, `DMM` meaning Detuning-Map Modulator, which is explained in [another section](./tutorials/dmm.nblink).
+
+All the channels have a modulation bandwidth (`mod_bandwidth`), which impacts the shape of the pulses programmed by the users. This arises from the optical elements we use to control the amplitude, detuning, phase of the pulses. We detail the influence of this modulation bandwidth in the [extended features](./tutorials/output_mod_eom.nblink), but it means that the effective duration of the pulses seen by the atoms is longer than what was programmed. A remedy to this can be to use other optical elements, that have a longer modulation bandwidth (i.e. better response time) but can only take constant pulses. These optical elements are named the `EOM`, and one can activate an "EOM mode" on a channel that has an `eom_config`. To check whether or not a channel supports this operation, one can call the `supports_eom()` method of the `Channel`. To read more about EOM and its configuration in a `Channel`, please refer to the [EOM section](./tutorials/output_mod_eom.nblink).
+
+Finally, the laser channel applied on the atoms has a propagation direction (`propagation_dir`). This information is only relevant for emulation purposes. 
+
+### Conclusion and extension
+
+The `Device` object stores all the physical information to take into account when making a quantum computation using a neutral-atom Quantum Processing Unit. An example of such a `Device` is detailed below with the `AnalogDevice`. As we have seen above, there are lots of physical constraints that are taken into account when you add an operation to your `Sequence`. However, for development perspectives, you could want to relax some conditions: what if there was no condition on the duration of the sequence ? or on the amplitude of the pulses applied to a specific channel ? You can work with a `VirtualDevice`, a kind of device that allows some of the physical constraints to not be defined. Check the [section on `VirtualDevice`](./tutorials/virtual_devices.nblink) to learn more.
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index bdccc5b3..8301ca9d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -61,6 +61,7 @@ computers and simulators, check the pages in :doc:`review`.
 
    review
    conventions
+   hardware
 
 .. toctree::
    :maxdepth: 2

From 17b333b629640acd22ef22a4cce75daf9328e6dd Mon Sep 17 00:00:00 2001
From: a_corni <antoine.cornillot@pasqal.com>
Date: Thu, 12 Dec 2024 11:32:55 +0100
Subject: [PATCH 5/7] Redirect api core

---
 docs/source/hardware.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/hardware.md b/docs/source/hardware.md
index 919d4e79..6bab1834 100644
--- a/docs/source/hardware.md
+++ b/docs/source/hardware.md
@@ -36,7 +36,7 @@ The device can also define some parameters used at execution on the backend. A b
 
 Each pulse modifying the state of the atoms is applied via a laser channel. A channel targets a specific transition between two states, named the eigenstates. These two eigenstates form a basis. You can check the basis currently implemented in Pulser and their associated eigenstates in the [conventions page](./conventions.md). A laser channel can address the atoms globally (all the atoms are addressed at the same time) or locally (atoms are targeted separately). This is described by the `addressing` attribute of the `Channel` object.
 
-The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst##pulse)). The laser channels constrain these parameters: 
+The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst)). The laser channels constrain these parameters: 
 - the duration must to be longer than `min_duration` but shorter than `max_duration`. It also has to be a multiple of `clock_duration`. 
 - the amplitude must be between 0 and `max_amp`. If the amplitude of a pulse is not constant equal to zero, its average must be higher than `min_avg_amp`.
 - the detuning must be between -`max_abs_detuning` and `max_abs_detuning`.

From b3ca064c9036d63d688e3679af42c74439eff33a Mon Sep 17 00:00:00 2001
From: a_corni <antoine.cornillot@pasqal.com>
Date: Thu, 12 Dec 2024 11:36:44 +0100
Subject: [PATCH 6/7] Add pulse section

---
 docs/source/hardware.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/hardware.md b/docs/source/hardware.md
index 6bab1834..db984156 100644
--- a/docs/source/hardware.md
+++ b/docs/source/hardware.md
@@ -36,7 +36,7 @@ The device can also define some parameters used at execution on the backend. A b
 
 Each pulse modifying the state of the atoms is applied via a laser channel. A channel targets a specific transition between two states, named the eigenstates. These two eigenstates form a basis. You can check the basis currently implemented in Pulser and their associated eigenstates in the [conventions page](./conventions.md). A laser channel can address the atoms globally (all the atoms are addressed at the same time) or locally (atoms are targeted separately). This is described by the `addressing` attribute of the `Channel` object.
 
-The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst)). The laser channels constrain these parameters: 
+The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst#pulse)). The laser channels constrain these parameters: 
 - the duration must to be longer than `min_duration` but shorter than `max_duration`. It also has to be a multiple of `clock_duration`. 
 - the amplitude must be between 0 and `max_amp`. If the amplitude of a pulse is not constant equal to zero, its average must be higher than `min_avg_amp`.
 - the detuning must be between -`max_abs_detuning` and `max_abs_detuning`.

From aec311f276e3e2e780e43692d2eb8c261de7a9fc Mon Sep 17 00:00:00 2001
From: a_corni <antoine.cornillot@pasqal.com>
Date: Thu, 12 Dec 2024 11:59:13 +0100
Subject: [PATCH 7/7] Direct to API core instead of pulse

---
 docs/source/hardware.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/hardware.md b/docs/source/hardware.md
index db984156..6bab1834 100644
--- a/docs/source/hardware.md
+++ b/docs/source/hardware.md
@@ -36,7 +36,7 @@ The device can also define some parameters used at execution on the backend. A b
 
 Each pulse modifying the state of the atoms is applied via a laser channel. A channel targets a specific transition between two states, named the eigenstates. These two eigenstates form a basis. You can check the basis currently implemented in Pulser and their associated eigenstates in the [conventions page](./conventions.md). A laser channel can address the atoms globally (all the atoms are addressed at the same time) or locally (atoms are targeted separately). This is described by the `addressing` attribute of the `Channel` object.
 
-The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst#pulse)). The laser channels constrain these parameters: 
+The pulses that are applied on these laser channels are defined by four parameters: their duration, amplitude, detuning and phase (learn more about pulses [here](./apidoc/core.rst)). The laser channels constrain these parameters: 
 - the duration must to be longer than `min_duration` but shorter than `max_duration`. It also has to be a multiple of `clock_duration`. 
 - the amplitude must be between 0 and `max_amp`. If the amplitude of a pulse is not constant equal to zero, its average must be higher than `min_avg_amp`.
 - the detuning must be between -`max_abs_detuning` and `max_abs_detuning`.