Serialization interface

doc/source/conf.py

@@ -18,6 +18,11 @@
 
 import qibolab
 
+# TODO: the following is a workaround for Sphinx doctest, cf.
+# - https://github.com/qiboteam/qibolab/commit/e04a6ab
+# - https://github.com/pydantic/pydantic/discussions/7763
+import qibolab.instruments.zhinst
+
 # -- Project information -----------------------------------------------------
 
 project = "qibolab"

doc/source/getting-started/experiment.rst

@@ -37,14 +37,10 @@ In this example, the qubit is controlled by a Zurich Instruments' SHFQC instrume
         AcquisitionConfig,
         OscillatorConfig,
     )
+
     from qibolab.instruments.zhinst import ZiChannel, Zurich
+    from qibolab.parameters import Parameters
     from qibolab.platform import Platform
-    from qibolab.serialize import (
-        load_instrument_settings,
-        load_qubits,
-        load_runcard,
-        load_settings,
-    )
 
     NAME = "my_platform"  # name of the platform
     ADDRESS = "localhost"  # ip address of the ZI data server
@@ -61,8 +57,9 @@ In this example, the qubit is controlled by a Zurich Instruments' SHFQC instrume
         device_setup.add_instruments(SHFQC("device_shfqc", address="DEV12146"))
 
         # Load and parse the runcard (i.e. parameters.json)
-        runcard = load_runcard(FOLDER)
-        qubits, _, pairs = load_qubits(runcard)
+        runcard = Parameters.load(FOLDER)
+        qubits = runcard.native_gates.single_qubit
+        pairs = runcard.native_gates.pairs
         qubit = qubits[0]
 
         # define component names, and load their configurations
@@ -74,14 +71,6 @@ In this example, the qubit is controlled by a Zurich Instruments' SHFQC instrume
         qubit.probe = IqChannel(name=probe, lo=readout_lo, mixer=None, acquisition=acquire)
         qubit.acquisition = AcquireChannel(name=acquire, probe=probe, twpa_pump=None)
 
-        configs = {}
-        component_params = runcard["components"]
-        configs[drive] = IqConfig(**component_params[drive])
-        configs[probe] = IqConfig(**component_params[probe])
-        configs[acquire] = AcquisitionConfig(**component_params[acquire])
-        configs[drive_lo] = OscillatorConfig(**component_params[drive_lo])
-        configs[readout_lo] = OscillatorConfig(**component_params[readout_lo])
-
         zi_channels = [
             ZiChannel(qubit.drive, device="device_shfqc", path="SGCHANNELS/0/OUTPUT"),
             ZiChannel(qubit.probe, device="device_shfqc", path="QACHANNELS/0/OUTPUT"),
@@ -90,15 +79,10 @@ In this example, the qubit is controlled by a Zurich Instruments' SHFQC instrume
 
         controller = Zurich(NAME, device_setup=device_setup, channels=zi_channels)
 
-        instruments = load_instrument_settings(runcard, {controller.name: controller})
-        settings = load_settings(runcard)
         return Platform(
-            NAME,
-            qubits,
-            pairs,
-            configs,
-            instruments,
-            settings,
+            name=NAME,
+            runcard=runcard,
+            instruments={controller.name: controller},
             resonator_type="3D",
         )
 

doc/source/main-documentation/qibolab.rst

@@ -56,7 +56,7 @@ We can easily access the names of channels and other components, and based on th
     :hide:
 
     Drive channel name: qubit_0/drive
-    Drive frequency: 4000000000
+    Drive frequency: 4000000000.0
     Drive channel qubit_0/drive does not use an LO.
 
 Now we can create a simple sequence (again, without explicitly giving any qubit specific parameter, as these are loaded automatically from the platform, as defined in the runcard):
@@ -251,11 +251,8 @@ To illustrate, here are some examples of single pulses using the Qibolab API:
     pulse = Pulse(
         duration=40,  # Pulse duration in ns
         amplitude=0.5,  # Amplitude relative to instrument range
-        frequency=1e8,  # Frequency in Hz
         relative_phase=0,  # Phase in radians
         envelope=Rectangular(),
-        channel="channel",
-        qubit=0,
     )
 
 In this way, we defined a rectangular drive pulse using the generic Pulse object.
@@ -268,11 +265,8 @@ Alternatively, you can achieve the same result using the dedicated :class:`qibol
     pulse = Pulse(
         duration=40,  # timing, in all qibolab, is expressed in ns
         amplitude=0.5,  # this amplitude is relative to the range of the instrument
-        frequency=1e8,  # frequency are in Hz
         relative_phase=0,  # phases are in radians
         envelope=Rectangular(),
-        channel="channel",
-        qubit=0,
     )
 
 Both the Pulses objects and the PulseShape object have useful plot functions and several different various helper methods.

doc/source/tutorials/calibration.rst

@@ -118,7 +118,7 @@ complex pulse sequence. Therefore with start with that:
         AveragingMode,
         AcquisitionType,
     )
-    from qibolab.serialize_ import replace
+    from qibolab.serialize import replace
 
     # allocate platform
     platform = create_platform("dummy")

doc/source/tutorials/lab.rst

@@ -34,11 +34,11 @@ using different Qibolab primitives.
         instrument = DummyInstrument("my_instrument", "0.0.0.0:0")
 
         # create the qubit object
-        qubit = Qubit(0)
+        qubit = Qubit(name=0)
 
         # assign channels to the qubit
         qubit.probe = IqChannel(name="probe", mixer=None, lo=None, acquisition="acquire")
-        qubit.acquire = AcquireChannel(name="acquire", twpa_pump=None, probe="probe")
+        qubit.acquisition = AcquireChannel(name="acquire", twpa_pump=None, probe="probe")
         qubit.drive = Iqchannel(name="drive", mixer=None, lo=None)
 
         # define configuration for channels
@@ -112,16 +112,16 @@ hold the parameters of the two-qubit gates.
     )
 
     # create the qubit objects
-    qubit0 = Qubit(0)
-    qubit1 = Qubit(1)
+    qubit0 = Qubit(name=0)
+    qubit1 = Qubit(name=1)
 
     # assign channels to the qubits
     qubit0.probe = IqChannel(name="probe_0", mixer=None, lo=None, acquisition="acquire_0")
-    qubit0.acquire = AcquireChannel(name="acquire_0", twpa_pump=None, probe="probe_0")
+    qubit0.acquisition = AcquireChannel(name="acquire_0", twpa_pump=None, probe="probe_0")
     qubit0.drive = IqChannel(name="drive_0", mixer=None, lo=None)
     qubit0.flux = DcChannel(name="flux_0")
     qubit1.probe = IqChannel(name="probe_1", mixer=None, lo=None, acquisition="acquire_1")
-    qubit1.acquire = AcquireChannel(name="acquire_1", twpa_pump=None, probe="probe_1")
+    qubit1.acquisition = AcquireChannel(name="acquire_1", twpa_pump=None, probe="probe_1")
     qubit1.drive = IqChannel(name="drive_1", mixer=None, lo=None)
 
     # assign single-qubit native gates to each qubit
@@ -177,18 +177,21 @@ hold the parameters of the two-qubit gates.
     )
 
     # define the pair of qubits
-    pair = QubitPair(qubit0.name, qubit1.name)
-    pair.native_gates = TwoQubitNatives(
-        CZ=FixedSequenceFactory(
-            PulseSequence(
-                [
-                    (
-                        qubit0.flux.name,
-                        Pulse(duration=30, amplitude=0.005, envelope=Rectangular()),
-                    ),
-                ]
+    pair = QubitPair(
+        qubit1=qubit0.name,
+        qubit2=qubit1.name,
+        native_gates=TwoQubitNatives(
+            CZ=FixedSequenceFactory(
+                PulseSequence(
+                    [
+                        (
+                            qubit0.flux.name,
+                            Pulse(duration=30, amplitude=0.005, envelope=Rectangular()),
+                        ),
+                    ]
+                )
             )
-        )
+        ),
     )
 
 Some architectures may also have coupler qubits that mediate the interactions.
@@ -209,9 +212,9 @@ coupler but qibolab will take them into account when calling :class:`qibolab.nat
     )
 
     # create the qubit and coupler objects
-    qubit0 = Qubit(0)
-    qubit1 = Qubit(1)
-    coupler_01 = Qubit(100)
+    qubit0 = Qubit(name=0)
+    qubit1 = Qubit(name=1)
+    coupler_01 = Qubit(name=100)
 
     # assign channel(s) to the coupler
     coupler_01.flux = DcChannel(name="flux_coupler_01")
@@ -220,24 +223,21 @@ coupler but qibolab will take them into account when calling :class:`qibolab.nat
     # Look above example
 
     # define the pair of qubits
-    pair = QubitPair(qubit0.name, qubit1.name)
-    pair.native_gates = TwoQubitNatives(
-        CZ=FixedSequenceFactory(
-            PulseSequence(
-                [
-                    (
-                        coupler_01.flux.name,
-                        Pulse(
-                            duration=30,
-                            amplitude=0.005,
-                            frequency=1e9,
-                            envelope=Rectangular(),
-                            qubit=qubit1.name,
-                        ),
-                    )
-                ],
+    pair = QubitPair(
+        qubit1=qubit0.name,
+        qubit2=qubit1.name,
+        native_gates=TwoQubitNatives(
+            CZ=FixedSequenceFactory(
+                PulseSequence(
+                    [
+                        (
+                            coupler_01.flux.name,
+                            Pulse(duration=30, amplitude=0.005, envelope=Rectangular()),
+                        )
+                    ],
+                )
             )
-        )
+        ),
     )
 
 The platform automatically creates the connectivity graph of the given chip
@@ -277,7 +277,7 @@ since ``create()`` is part of a Python module, is is possible to load parameters
 from an external file or database.
 
 Qibolab provides some utility functions, accessible through
-:py:mod:`qibolab.serialize`, for loading calibration parameters stored in a JSON
+:py:mod:`qibolab.parameters`, for loading calibration parameters stored in a JSON
 file with a specific format. We call such file a runcard. Here is a runcard for
 a two-qubit system:
 
@@ -476,7 +476,7 @@ however the pulses under ``native_gates`` should comply with the
 Providing the above runcard is not sufficient to instantiate a
 :class:`qibolab.platform.Platform`. This should still be done using a
 ``create()`` method, however this is significantly simplified by
-``qibolab.serialize``. The ``create()`` method should be put in a
+``qibolab.parameters``. The ``create()`` method should be put in a
 file named ``platform.py`` inside the ``my_platform`` directory.
 Here is the ``create()`` method that loads the parameters of
 the above runcard:
@@ -495,11 +495,7 @@ the above runcard:
         DcConfig,
         IqConfig,
     )
-    from qibolab.serialize import (
-        load_runcard,
-        load_qubits,
-        load_settings,
-    )
+    from qibolab.parameters import Parameters
     from qibolab.instruments.dummy import DummyInstrument
 
     FOLDER = Path.cwd()
@@ -511,8 +507,9 @@ the above runcard:
         instrument = DummyInstrument("my_instrument", "0.0.0.0:0")
 
         # create ``Qubit`` and ``QubitPair`` objects by loading the runcard
-        runcard = load_runcard(folder)
-        qubits, _, pairs = load_qubits(runcard)
+        runcard = Parameters.load(folder)
+        qubits = runcard.native_gates.single_qubit
+        pairs = runcard.native_gates.pairs
 
         # define channels and load component configs
         configs = {}
@@ -540,14 +537,13 @@ the above runcard:
         # create dictionary of instruments
         instruments = {instrument.name: instrument}
         # load ``settings`` from the runcard
-        settings = load_settings(runcard)
         return Platform(
             "my_platform",
             qubits,
             pairs,
             configs,
             instruments,
-            settings,
+            settings=runcard.settings,
             resonator_type="2D",
         )
 
@@ -563,8 +559,10 @@ With the following additions for coupler architectures:
         instrument = DummyInstrument("my_instrument", "0.0.0.0:0")
 
         # create ``Qubit`` and ``QubitPair`` objects by loading the runcard
-        runcard = load_runcard(folder)
-        qubits, couplers, pairs = load_qubits(runcard)
+        runcard = Parameters.load(folder)
+        qubits = runcard.native_gates.single_qubit
+        couplers = runcard.native_gates.coupler
+        pairs = runcard.native_gates.pairs
 
         # define channels and load component configs
         configs = {}
@@ -644,7 +642,7 @@ The runcard can contain an ``instruments`` section that provides these parameter
     }
 
 
-These settings are loaded when creating the platform using :meth:`qibolab.serialize.load_instrument_settings`.
+These settings are loaded when creating the platform using :meth:`qibolab.parameters.load_instrument_settings`.
 Note that the key used in the runcard should be the same with the name used when instantiating the instrument,
 in this case ``"twpa_pump"``.
 
@@ -662,11 +660,7 @@ in this case ``"twpa_pump"``.
         DcConfig,
         IqConfig,
     )
-    from qibolab.serialize import (
-        load_runcard,
-        load_qubits,
-        load_settings,
-    )
+    from qibolab.parameters import Parameters
     from qibolab.instruments.dummy import DummyInstrument
 
     FOLDER = Path.cwd()
@@ -678,8 +672,9 @@ in this case ``"twpa_pump"``.
         instrument = DummyInstrument("my_instrument", "0.0.0.0:0")
 
         # create ``Qubit`` and ``QubitPair`` objects by loading the runcard
-        runcard = load_runcard(folder)
-        qubits, _, pairs = load_qubits(runcard)
+        runcard = Parameters.load(folder)
+        qubits = runcard.native_gates.single_qubit
+        pairs = runcard.native_gates.pairs
 
         # define channels and load component configs
         configs = {}
@@ -706,16 +701,12 @@ in this case ``"twpa_pump"``.
 
         # create dictionary of instruments
         instruments = {instrument.name: instrument}
-        # load instrument settings from the runcard
-        instruments = load_instrument_settings(runcard, instruments)
-        # load ``settings`` from the runcard
-        settings = load_settings(runcard)
         return Platform(
             "my_platform",
             qubits,
             pairs,
             configs,
             instruments,
-            settings,
+            settings=runcard.settings,
             resonator_type="2D",
         )

doc/source/tutorials/pulses.rst

@@ -22,7 +22,7 @@ pulses (:class:`qibolab.pulses.Pulse`) through the
                     envelope=Gaussian(rel_sigma=0.2),
                 ),
             ),
-            ("channel_1", Delay(duration=100, channel="1")),
+            ("channel_1", Delay(duration=100)),
             (
                 "channel_1",
                 Pulse(

pyproject.toml

@@ -87,6 +87,7 @@ qm = ["qm-qua", "qualang-tools"]
 zh = ["laboneq"]
 rfsoc = ["qibosoq"]
 los = ["qcodes", "qcodes_contrib_drivers", "pyvisa-py"]
+twpa = ["qcodes", "qcodes_contrib_drivers", "pyvisa-py"]
 emulator = ["qutip"]
 
 
@@ -101,6 +102,7 @@ test-docs = "make -C doc doctest"
 [tool.pylint.master]
 output-format = "colorized"
 disable = ["E1123", "E1120", "C0301"]
+generated-members = ["qibolab.native.RxyFactory", "pydantic.fields.FieldInfo"]
 
 [tool.pytest.ini_options]
 testpaths = ['tests/']