[API] Hiding pulser.Pulse and pulser.Register - breaking change (#92)

For the sake of pedagogy, we're trying to hide pulser as much as possible.
With this PR, we remove all visible references to pulser.Pulse and pulser.Register,
replacing them withour own ir.Pulse and ir.Register.

Author: Yoric

examples/tutorial 1a - Using a Quantum Device to Extract Machine-Learning Features - low-level.ipynb

@@ -131,7 +131,7 @@
     "example_graph, example_register, example_pulse = compiled[64]\n",
     "\n",
     "# The molecule, as laid out on the Quantum Device.\n",
-    "example_register.draw(blockade_radius=pl.AnalogDevice.min_atom_distance + 0.01)\n",
+    "example_register.draw()\n",
     "\n",
     "# The laser pulse used to control its state evolution.\n",
     "example_pulse.draw()"
@@ -143,7 +143,7 @@
    "source": [
     "## Experimenting with registers and pulses\n",
     "\n",
-    "You can, of course, adopt different registers or pulses, using the underlying Pulser Framework."
+    "You may experiment with different pulses, by passing arguments to `compile_pulse`."
    ]
   },
   {
@@ -152,24 +152,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import pulser\n",
-    "\n",
-    "example_register = pulser.Register({\"q0\": (0, 0)})\n",
-    "example_pulse = pulser.Pulse.ArbitraryPhase(\n",
-    "    amplitude=pulser.waveforms.RampWaveform(duration=150, start=100, stop=300),\n",
-    "    phase=pulser.waveforms.ConstantWaveform(duration=150, value=15),\n",
-    "    post_phase_shift=5\n",
-    ")\n",
-    "\n",
-    "example_register.draw()\n",
-    "example_pulse.draw()"
+    "example_pulse = graphs_to_compile[0].compile_pulse(normalized_amplitude=0.1, normalized_duration=0.1) # arbitrary values\n",
+    "example_pulse.draw()\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For this, you'll probably want to take a look at [the documentation of Pulser](https://pulser.readthedocs.io/)."
+    "You can experiment further, using arbitrary pulses and registers, but for this, you'll have to use the low-level Pulser framework, which goes beyond the scope of this tutorial. You may find further details on pulses and registers in [the documentation of Pulser](https://pulser.readthedocs.io/)."
    ]
   },
   {
@@ -189,7 +180,7 @@
    "outputs": [],
    "source": [
     "from qek.data.processed_data import ProcessedData\n",
-    "from qek.backends import QutipBackend\n",
+    "from qek.target.backends import QutipBackend\n",
     "\n",
     "# In this tutorial, to make things faster, we'll only run the graphs that require 5 qubits or less.\n",
     "# If you wish to run more entries, feel free to increase this value.\n",
@@ -203,10 +194,10 @@
     "processed_dataset = []\n",
     "backend = QutipBackend(device=pl.AnalogDevice)\n",
     "for graph, register, pulse in tqdm(compiled):\n",
-    "    if len(register.qubits) > MAX_QUBITS:\n",
+    "    if len(register) > MAX_QUBITS:\n",
     "        continue\n",
     "    states = await backend.run(register=register, pulse=pulse)\n",
-    "    processed_dataset.append(ProcessedData.from_register(register=register, pulse=pulse, device=pl.AnalogDevice, state_dict=states, target=graph.target))"
+    "    processed_dataset.append(ProcessedData.custom(register=register, pulse=pulse, device=pl.AnalogDevice, state_dict=states, target=graph.target))"
    ]
   },
   {
@@ -241,7 +232,7 @@
     "HAVE_PASQAL_ACCOUNT = False # If you have a PASQAL Cloud account, fill in the details and set this to `True`.\n",
     "\n",
     "if HAVE_PASQAL_ACCOUNT: \n",
-    "    from qek.backends import RemoteQPUBackend\n",
+    "    from qek.target.backends import RemoteQPUBackend\n",
     "    processed_dataset = []\n",
     "\n",
     "    # Initialize connection\n",
@@ -281,7 +272,7 @@
     "\n",
     "        # Send the work to the QPU and await the result\n",
     "        states = await backend.run(register=register, pulse=pulse)\n",
-    "        processed_dataset.append(ProcessedData.from_register(register=register, pulse=pulse, device=device, state_dict=states, target=graph.target))"
+    "        processed_dataset.append(ProcessedData.custom(register=register, pulse=pulse, device=device, state_dict=states, target=graph.target))"
    ]
   },
   {

examples/tutorial 1b - Training SVM QEK - low-level - generic dataset.ipynb

@@ -239,7 +239,7 @@
    "outputs": [],
    "source": [
     "example_graph, example_register, example_pulse = compiled[53]\n",
-    "example_register.draw(blockade_radius=pl.AnalogDevice.min_atom_distance + 0.01)\n",
+    "example_register.draw()\n",
     "example_pulse.draw()"
    ]
   },
@@ -268,7 +268,7 @@
    "outputs": [],
    "source": [
     "from qek.data.processed_data import ProcessedData\n",
-    "from qek.backends import QutipBackend\n",
+    "from qek.target.backends import QutipBackend\n",
     "\n",
     "# In this tutorial, to make things faster, we'll only run 5 qubits or less.\n",
     "# If you wish to run more entries, feel free to increase this value.\n",
@@ -282,10 +282,10 @@
     "processed_dataset = []\n",
     "executor = QutipBackend(device=pl.AnalogDevice)\n",
     "for graph, register, pulse in tqdm(compiled):\n",
-    "    if len(register.qubits) > MAX_QUBITS:\n",
+    "    if len(register) > MAX_QUBITS:\n",
     "        continue\n",
     "    states = await executor.run(register=register, pulse=pulse)\n",
-    "    processed_dataset.append(ProcessedData.from_register(register=register, pulse=pulse, device=pl.AnalogDevice, state_dict=states, target=graph.target))"
+    "    processed_dataset.append(ProcessedData.custom(register=register, pulse=pulse, device=pl.AnalogDevice, state_dict=states, target=graph.target))"
    ]
   },
   {
@@ -313,7 +313,7 @@
     "HAVE_PASQAL_ACCOUNT = False # If you have a PASQAL Cloud account, fill in the details and set this to `True`.\n",
     "\n",
     "if HAVE_PASQAL_ACCOUNT: \n",
-    "    from qek.backends import RemoteQPUBackend\n",
+    "    from qek.target.backends import RemoteQPUBackend\n",
     "    processed_dataset = []\n",
     "\n",
     "    # Initialize connection\n",
@@ -353,7 +353,7 @@
     "\n",
     "        # Send the work to the QPU and await the result\n",
     "        states = await executor.run(register=register, pulse=pulse)\n",
-    "        processed_dataset.append(ProcessedData.from_register(register=register, pulse=pulse, device=device, state_dict=states, target=graph.target))"
+    "        processed_dataset.append(ProcessedData.custom(register=register, pulse=pulse, device=device, state_dict=states, target=graph.target))"
    ]
   },
   {
@@ -565,7 +565,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.15"
+   "version": "3.12.3"
   }
  },
  "nbformat": 4,

qek/data/extractors.py

@@ -310,9 +310,9 @@ def compile(
             try:
                 register = graph.compile_register()
                 pulse = graph.compile_pulse()
-                sequence = pl.Sequence(register=register, device=graph.device)
+                sequence = pl.Sequence(register=register.register, device=graph.device)
                 sequence.declare_channel("ising", "rydberg_global")
-                sequence.add(pulse, "ising")
+                sequence.add(pulse.pulse, "ising")
             except CompilationError as e:
                 # In some cases, we produce graphs that pass `is_embeddable` but cannot be compiled.
                 # It _looks_ like this is due to rounding errors. We're investigating this in issue #29,

qek/data/graphs.py

@@ -19,6 +19,7 @@
 import torch_geometric.utils as pyg_utils
 from rdkit.Chem import AllChem
 
+from qek.target import targets
 from qek.shared.error import CompilationError
 from qek.shared._utils import graph_to_mol
 
@@ -199,7 +200,7 @@ def is_embeddable(self) -> bool:
     SEQUENCE_DEFAULT_AMPLITUDE_RAD_PER_US = 1.0 * 2 * np.pi
     SEQUENCE_DEFAULT_DURATION_NS = 660
 
-    def compile_register(self) -> pl.Register:
+    def compile_register(self) -> targets.Register:
         """Create a Quantum Register based on a graph.
 
         Returns:
@@ -225,13 +226,13 @@ def compile_register(self) -> pl.Register:
             pl.Sequence(register=reg, device=self.device)
         except ValueError as e:
             raise CompilationError(f"The graph is not compatible with {self.device}: {e}")
-        return reg
+        return targets.Register(device=self.device, register=reg)
 
     def compile_pulse(
         self,
         normalized_amplitude: float | None = None,
         normalized_duration: float | None = None,
-    ) -> pl.Pulse:
+    ) -> targets.Pulse:
         """Extract a Pulse for this graph.
 
         A Pulse represents the laser applied to the atoms on the device.
@@ -290,7 +291,7 @@ def compile_pulse(
             detuning=pl.waveforms.RampWaveform(absolute_duration, 0, 0),
             phase=0.0,
         )
-        return pulse
+        return targets.Pulse(pulse)
 
 
 class MoleculeGraph(BaseGraph):

qek/data/processed_data.py

@@ -13,6 +13,7 @@
 
 from qek.data.graphs import EPSILON_RADIUS_UM
 from qek.shared._utils import make_sequence
+from qek.target import targets
 
 logger = logging.getLogger(__name__)
 
@@ -68,10 +69,10 @@ def __init__(
         self.target = target
 
     @classmethod
-    def from_register(
+    def custom(
         cls,
-        register: pl.Register,
-        pulse: pl.Pulse,
+        register: targets.Register,
+        pulse: targets.Pulse,
         device: pl.devices.Device,
         state_dict: dict[str, int | np.int64],
         target: int | None,

qek/shared/_utils.py

@@ -8,11 +8,12 @@
 import numpy as np
 import numpy.typing as npt
 import pulser
-from pulser import Pulse, Register
 from pulser.devices import Device
 from qek.shared.error import CompilationError
 import rdkit.Chem as Chem
 
+from qek.target import targets
+
 
 def graph_to_mol(
     graph: nx.Graph,
@@ -32,11 +33,11 @@ def graph_to_mol(
     m = Chem.MolFromSmiles("")
     mw = Chem.RWMol(m)
     atom_index = {}
-    for n, d in graph.nodes(data="x"):
+    for n, d in graph.nodes(data="x"):  # type: ignore
         d = np.asarray(d)
         idx_d: int = inverse_one_hot(d, dim=0)[0]
         atom_index[n] = mw.AddAtom(Chem.Atom(node_mapping[idx_d]))
-    for a, b, d in graph.edges(data="edge_attr"):
+    for a, b, d in graph.edges(data="edge_attr"):  # type: ignore
         start = atom_index[a]
         end = atom_index[b]
         d = np.asarray(d)
@@ -64,7 +65,9 @@ def inverse_one_hot(array: npt.ArrayLike, dim: int) -> np.ndarray:
     return np.nonzero(tmp_array == 1.0)[dim]
 
 
-def make_sequence(device: Device, pulse: Pulse, register: Register) -> pulser.Sequence:
+def make_sequence(
+    device: Device, pulse: targets.Pulse, register: targets.Register
+) -> pulser.Sequence:
     """
     Build a sequence for a device from a pulse and a register.
 
@@ -82,9 +85,9 @@ def make_sequence(device: Device, pulse: Pulse, register: Register) -> pulser.Se
         CompilationError if the pulse + register are not compatible with the device.
     """
     try:
-        sequence = pulser.Sequence(register=register, device=device)
+        sequence = pulser.Sequence(register=register.register, device=device)
         sequence.declare_channel("ising", "rydberg_global")
-        sequence.add(pulse, "ising")
+        sequence.add(pulse.pulse, "ising")
         return sequence
     except ValueError as e:
         raise CompilationError(f"This pulse/register cannot be executed on the device: {e}")

qek/target/__init__.py

@@ -0,0 +1,3 @@
+"""
+Quantum compilation targets
+"""