boulder-opal-scale-up-sdk 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

boulderopalscaleupsdk/device/controller/qblox.py

@@ -47,11 +47,11 @@ import dataclasses
 import enum
 import re
 from dataclasses import dataclass
-from typing import Annotated, Any, Literal, TypeVar
+from typing import Annotated, Any, ClassVar, Literal, Self, TypeVar
 
 from pydantic import BaseModel, BeforeValidator, Field, PlainSerializer, model_validator
 
-from boulderopalscaleupsdk.common.dtypes import Self
+from boulderopalscaleupsdk.device.controller.base import Backend, ControllerType
 
 # ==================================================================================================
 # Addressing
@@ -96,11 +96,11 @@ class ModuleAddr:
     def parse(cls, data: str) -> Self:
         mch = _RE_MODULE_ADDR.match(data)
         if mch is None:
-            raise ValueError("could not parse module address")
+            raise ValueError("Could not parse module address.")
         return cls(cluster=mch.group("cluster"), slot=int(mch.group("slot")))
 
 
-@dataclass(frozen=True, eq=True)
+@dataclass(frozen=True)
 class SequencerAddr:
     """Address to a sequencer (located on a specific module) in a QBLOX control stack."""
 
@@ -112,6 +112,12 @@ class SequencerAddr:
     def module(self) -> ModuleAddr:
         return ModuleAddr(self.cluster, self.slot)
 
+    def __hash__(self) -> int:
+        return hash(str(self))
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, SequencerAddr) and str(other) == str(self)
+
     def __str__(self) -> str:
         """Address as a string.
 
@@ -124,7 +130,7 @@ class SequencerAddr:
     def parse(cls, data: str) -> Self:
         mch = _RE_SEQUENCER_ADDR.match(data)
         if mch is None:
-            raise ValueError("could not parse sequencer address")
+            raise ValueError("Could not parse sequencer address.")
         return cls(
             cluster=mch.group("cluster"),
             slot=int(mch.group("slot")),
@@ -158,7 +164,7 @@ class PortAddr:
     def parse(cls, data: str) -> Self:
         mch = _RE_PORT_ADDR.match(data)
         if mch is None:
-            raise ValueError("could not parse port address")
+            raise ValueError("Could not parse port address.")
         direction: Literal["out", "in"] = "out" if mch.group("dir") == "O" else "in"
         return cls(
             cluster=mch.group("cluster"),
@@ -179,7 +185,7 @@ def _addr_validator(dtype: type[T]) -> BeforeValidator:
             return obj
         if isinstance(obj, str):  # Parse from JSON
             return dtype.parse(obj)
-        raise TypeError(f"Invalid type {type(obj).__name__} for {type(dtype).__name__}")
+        raise TypeError(f"Invalid type {type(obj).__name__} for {type(dtype).__name__}.")
 
     return BeforeValidator(_validator)
 
@@ -234,9 +240,9 @@ class ComplexChannel(BaseModel):
         ii = self.i_port
         qq = self.q_port
         if ii.cluster != qq.cluster or ii.slot != qq.slot:
-            raise ValueError("I and Q ports must be on the same cluster+module")
+            raise ValueError("I and Q ports must be on the same cluster+module.")
         if ii.direction != qq.direction:
-            raise ValueError("I and Q ports must be the same direction")
+            raise ValueError("I and Q ports must be in the same direction.")
         return self
 
 
@@ -283,19 +289,26 @@ class ElementConnection(BaseModel):  # pragma: no cover
             raise ValueError("I/O channels for an element must be on the same module.")
         return self
 
+    @property
+    def module(self) -> ModuleAddr:
+        return self.ch_out.module
+
 
-class ControllerInfo(BaseModel):  # pragma: no cover
+class QBLOXControllerInfo(BaseModel):  # pragma: no cover
     """
     Controller information needed for program compilation and control.
 
     Attributes
     ----------
+    controller_type: Literal[ControllerType.QBLOX]
+        The type of controller, which is always `ControllerType.QBLOX` for this class.
     modules: dict[ModuleAddrType, ModuleType]
         The modules connected to the QBLOX stack.
     elements: dict[str, ElementConnection]
         The addressable control elements for the stack.
     """
 
+    controller_type: Literal[ControllerType.QBLOX] = ControllerType.QBLOX
     modules: dict[ModuleAddrType, ModuleType]
     elements: dict[str, ElementConnection]
 
@@ -313,7 +326,7 @@ class SequencerParams(BaseModel):
     marker_ovr_value: int | None = Field(default=None)
     mod_en_awg: bool | None = Field(default=None)
     demod_en_acq: bool | None = Field(default=None)
-    sync_en: bool | None = Field(default=True)
+    sync_en: bool | None = Field(default=None)
     nco_prop_delay_comp_en: bool | None = Field(default=True)
     integration_length_acq: int | None = Field(default=None)
 
@@ -353,17 +366,27 @@ class AcquisitionConfig(BaseModel):
 class SequenceProgram(BaseModel):
     """A Q1 Sequence Program."""
 
+    backend: ClassVar = Backend.QBLOX_Q1ASM
+
     program: str
     waveforms: dict[str, IndexedData] = {}
     weights: dict[str, IndexedData] = {}
     acquisitions: dict[str, AcquisitionConfig] = {}
     acquisition_scopes: list[str] = []
+    params: SequencerParams = SequencerParams()
+    params_only: bool = False
 
-    def sequence_data(self) -> dict[str, Any]:
+    def sequence_data(self) -> dict[str, Any] | None:
+        if self.params_only:
+            return None
         return self.model_dump(include={"program", "waveforms", "weights", "acquisitions"})
 
-    def dump(self) -> bytes:
-        return self.model_dump_json().encode("utf-8")
+    def dumps(self) -> str:
+        return self.model_dump_json()
+
+    @classmethod
+    def loads(cls, data: str) -> Self:
+        return cls.model_validate_json(data)
 
 
 class PreparedSequenceProgram(BaseModel):  # pragma: no cover
@@ -373,7 +396,6 @@ class PreparedSequenceProgram(BaseModel):  # pragma: no cover
     sequencer_number: int
     ch_out: ChannelType
     ch_in: ChannelType | None = None
-    sequencer_params: SequencerParams = SequencerParams()
 
     @property
     def sequencer_addr(self) -> SequencerAddr:
@@ -395,8 +417,12 @@ class PreparedProgram(BaseModel):
     modules: dict[ModuleAddrType, PreparedModule]  # The set of modules this program will target.
     sequence_programs: dict[str, PreparedSequenceProgram]  # The individual element programs.
 
-    def dump(self) -> bytes:
-        return self.model_dump_json().encode("utf-8")
+    def dumps(self) -> str:
+        return self.model_dump_json()
+
+    @classmethod
+    def loads(cls, data: str) -> Self:
+        return cls.model_validate_json(data)
 
 
 # ==================================================================================================

boulderopalscaleupsdk/device/controller/quantum_machines.py

@@ -11,105 +11,103 @@
 # distributed under the License is distributed on an "AS IS" BASIS. See the
 # License for the specific language.
 
-import logging
-import os
-from typing import Literal
-from unittest.mock import patch
-
-from pydantic import BaseModel, Field, model_validator
-
-from boulderopalscaleupsdk.common.dtypes import Duration, DurationNsLike, Self, TimeUnit
-from boulderopalscaleupsdk.third_party.quantum_machines.config import (
-    ControllerConfigType,
-    OctaveConfig121,
-    OPX1000ControllerConfigType,
+from typing import Literal, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
 )
+
+from boulderopalscaleupsdk.common.dtypes import Duration, DurationNsLike, TimeUnit
+from boulderopalscaleupsdk.device.controller.base import ControllerType
+from boulderopalscaleupsdk.third_party import quantum_machines as qm
+from boulderopalscaleupsdk.third_party.quantum_machines import config as qm_config
 from boulderopalscaleupsdk.third_party.quantum_machines.constants import (
     MIN_TIME_OF_FLIGHT,
     QUA_CLOCK_CYCLE,
 )
 
-from .base import BaseControllerInfo
-
-# Disable QM logging and telemetry
-os.environ["QM_DISABLE_STREAMOUTPUT"] = "True"  # Used in 1.1.0
-_qm_logger = logging.getLogger("qm")
-_qm_logger.disabled = True
-
-# Disable unwanted telemetry/logging modules in QM
-_qm_patch_targets = [
-    "qm._loc._get_loc",
-    "qm.program.expressions._get_loc",
-    "qm.program.StatementsCollection._get_loc",
-    "qm.qua._get_loc",
-    "qm.qua._dsl._get_loc",
-    "qm.qua._expressions._get_loc",
-    "qm.qua.AnalogMeasureProcess._get_loc",
-    "qm.qua.DigitalMeasureProcess._get_loc",
-    "qm.datadog_api.DatadogHandler",
-]
-for target in _qm_patch_targets:
-    try:
-        _m = patch(target).__enter__()
-        _m.return_value = ""
-    except (AttributeError, ModuleNotFoundError):  # noqa: PERF203
-        pass
-
-PortRef = str
+QPUPortRef = str
 OctaveRef = str
 ControllerRef = str
-PortNum = int
-PortMapping = tuple[OctaveRef, PortNum]
+ControllerPort = int
+
+
+class QuaProgram(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    program: qm.QuaProgramMessage
+    config: qm_config.QuaConfig
+
+    @field_serializer("program")
+    def serialize_program(self, program: qm.QuaProgramMessage) -> str:
+        return program.to_json()
 
+    @field_validator("program", mode="before")
+    @classmethod
+    def deserialize_program(cls, program: object) -> qm.QuaProgramMessage:
+        if isinstance(program, qm.QuaProgramMessage):
+            return program
+        if isinstance(program, str | bytes):
+            return qm.QuaProgramMessage().from_json(program)
+        raise TypeError(f"Could not parse program from {type(program).__name__}.")
 
-class OctaveConfig(OctaveConfig121):
+    def dumps(self) -> str:
+        return self.model_dump_json()
+
+    @classmethod
+    def loads(cls, data: str) -> Self:
+        return cls.model_validate_json(data)
+
+
+class OctaveConfig(qm_config.OctaveConfig121):
     host: str | None = Field(default=None)
     port: int | None = Field(default=None)
 
-    def to_qm_octave_config_121(self) -> OctaveConfig121:
-        return OctaveConfig121.model_validate(self.model_dump())
+    def to_qm_octave_config_121(self) -> qm_config.OctaveConfig121:
+        return qm_config.OctaveConfig121.model_validate(self.model_dump())
 
 
 class DrivePortConfig(BaseModel):
     port_type: Literal["drive"] = "drive"
-    port_mapping: PortMapping
+    port_mapping: tuple[OctaveRef, ControllerPort]
 
 
 class FluxPortConfig(BaseModel):
     port_type: Literal["flux"] = "flux"
-    port_mapping: PortMapping
+    port_mapping: tuple[ControllerRef, ControllerPort]
 
 
 class ReadoutPortConfig(BaseModel):
     port_type: Literal["readout"] = "readout"
-    port_mapping: PortMapping
+    port_mapping: tuple[OctaveRef, ControllerPort]
     time_of_flight: DurationNsLike
     smearing: DurationNsLike = Field(default=Duration(0, TimeUnit.NS))
 
     @model_validator(mode="after")
     def _validate_readout_port_config(self) -> Self:
-        min_time_of_flight_ns = MIN_TIME_OF_FLIGHT.convert(TimeUnit.NS).value
-        time_of_flight_ns = self.time_of_flight.convert(TimeUnit.NS).value
-        smearing_ns = self.smearing.convert(TimeUnit.NS).value
-        qua_clock_cycle_ns = QUA_CLOCK_CYCLE.convert(TimeUnit.NS).value
-
-        if time_of_flight_ns < min_time_of_flight_ns:
+        time_of_flight_ns = self.time_of_flight.to_ns().value
+        if time_of_flight_ns < MIN_TIME_OF_FLIGHT.to_ns().value:
             raise ValueError(f"time_of_flight must be >= {MIN_TIME_OF_FLIGHT}")
 
-        if time_of_flight_ns % qua_clock_cycle_ns != 0:
+        if time_of_flight_ns % QUA_CLOCK_CYCLE.to_ns().value != 0:
             raise ValueError(f"time_of_flight must be a multiple of {QUA_CLOCK_CYCLE}")
 
-        if smearing_ns > time_of_flight_ns - 8:
+        if self.smearing.to_ns().value > time_of_flight_ns - 8:
             raise ValueError(f"smearing must be at most {time_of_flight_ns - 8} ns")
 
         return self
 
 
-OPXControllerConfig = ControllerConfigType
-OPX1000ControllerConfig = OPX1000ControllerConfigType
+OPXControllerConfig = qm_config.ControllerConfigType
+OPX1000ControllerConfig = qm_config.OPX1000ControllerConfigType
 
 
-class QuantumMachinesControllerInfo(BaseControllerInfo):
+class QuantumMachinesControllerInfo(BaseModel):
     """
     QuantumMachinesControllerInfo is a data model that represents the configuration
     and port settings for quantum machine controllers.
@@ -119,6 +117,8 @@ class QuantumMachinesControllerInfo(BaseControllerInfo):
 
     Attributes
     ----------
+    controller_type : Literal[ControllerType.QUANTUM_MACHINES]
+        The type of controller, which is always `ControllerType.QUANTUM_MACHINES`.
     controllers : dict[ControllerRef, OPXControllerConfig | OPX1000ControllerConfig]
         A dictionary mapping controller references to their respective configurations.
         The configurations can be either OPXControllerConfig or OPX1000ControllerConfig.
@@ -132,8 +132,9 @@ class QuantumMachinesControllerInfo(BaseControllerInfo):
         Not derived from OPX Config, this is our custom config.
     """
 
+    controller_type: Literal[ControllerType.QUANTUM_MACHINES] = ControllerType.QUANTUM_MACHINES
     controllers: dict[ControllerRef, OPXControllerConfig | OPX1000ControllerConfig] = Field(
         default={},
     )
     octaves: dict[OctaveRef, OctaveConfig] = Field(default={})
-    port_config: dict[PortRef, DrivePortConfig | FluxPortConfig | ReadoutPortConfig]
+    port_config: dict[QPUPortRef, DrivePortConfig | FluxPortConfig | ReadoutPortConfig]

boulderopalscaleupsdk/device/controller/resolver.py

@@ -0,0 +1,117 @@
+from google.protobuf.json_format import MessageToDict
+from google.protobuf.struct_pb2 import Struct
+
+from boulderopalscaleupsdk.device.controller import (
+    QBLOXControllerInfo,
+    QuantumMachinesControllerInfo,
+)
+from boulderopalscaleupsdk.device.controller.base import (
+    Backend,
+    ControllerType,
+)
+from boulderopalscaleupsdk.protobuf.v1 import agent_pb2
+
+
+class ControllerResolverService:
+    """
+    Service for resolving controller-related types and backends.
+    """
+
+    def resolve_backend_from_controller(
+        self,
+        controller_type: ControllerType | QBLOXControllerInfo | QuantumMachinesControllerInfo,
+    ) -> Backend:
+        """
+        Resolve the backend based on the controller type.
+
+        Parameters
+        ----------
+        controller_type : ControllerType | QBLOXControllerInfo | QuantumMachinesControllerInfo
+            The type of the controller, either as an enum or a data structure.
+
+        Returns
+        -------
+        Backend
+            The corresponding backend for the controller type.
+        """
+        match controller_type:
+            case QuantumMachinesControllerInfo() | ControllerType.QUANTUM_MACHINES:
+                return Backend.QUA
+            case QBLOXControllerInfo() | ControllerType.QBLOX:
+                return Backend.QBLOX_Q1ASM
+
+    def resolve_controller_type_from_request(
+        self,
+        program_request: agent_pb2.RunProgramRequest,
+    ) -> ControllerType:
+        """
+        Resolve the controller type from a RunProgramRequest.
+
+        Parameters
+        ----------
+        program_request : agent_pb2.RunProgramRequest
+            The request containing the controller type.
+
+        Returns
+        -------
+        ControllerType
+            The resolved controller type.
+
+        Raises
+        ------
+        TypeError
+            If the controller type is unknown or not set.
+        ValueError
+            If the controller type in the request is invalid.
+        """
+        try:
+            controller_type = ControllerType(program_request.controller_type)
+        except ValueError as err:
+            raise TypeError(
+                f"Unknown controller type: {program_request.controller_type}",
+            ) from err
+
+        return controller_type
+
+    def resolve_controller_info_from_controller_data_struct(
+        self,
+        data: Struct,
+    ) -> QBLOXControllerInfo | QuantumMachinesControllerInfo:
+        """
+        Resolve the controller info from a Struct data structure.
+
+        Parameters
+        ----------
+        data : Struct
+            The data structure containing the controller information.
+
+        Returns
+        -------
+        QBLOXControllerInfo | QuantumMachinesControllerInfo
+            The resolved controller info type.
+
+        Raises
+        ------
+        TypeError
+            If the controller type is unknown or not set.
+        """
+        ref = MessageToDict(data).get("controller_type", None)
+        controller_type: type[QuantumMachinesControllerInfo | QBLOXControllerInfo]
+        match ref:
+            case ControllerType.QUANTUM_MACHINES.value:
+                controller_type = QuantumMachinesControllerInfo
+            case ControllerType.QBLOX.value:
+                controller_type = QBLOXControllerInfo
+            case None:
+                raise TypeError(
+                    "Controller type is not set in the response. "
+                    "This may indicate that the device does not have a controller set.",
+                )
+            case _:
+                raise TypeError(
+                    f"Unknown controller type: {ref}. "
+                    "This may indicate that the device does not have a controller set.",
+                )
+        return controller_type.model_validate(
+            MessageToDict(data),
+        )

boulderopalscaleupsdk/device/defcal.py

@@ -0,0 +1,61 @@
+# Copyright 2025 Q-CTRL. All rights reserved.
+#
+# Licensed under the Q-CTRL Terms of service (the "License"). Unauthorized
+# copying or use of this file, via any medium, is strictly prohibited.
+# Proprietary and confidential. You may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+#    https://q-ctrl.com/terms
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS. See the
+# License for the specific language.
+
+import re
+from typing import Annotated, Any, Literal
+
+from pydantic import BeforeValidator, PlainSerializer, TypeAdapter
+from pydantic.dataclasses import dataclass
+
+QubitAddr = tuple[int, ...]
+GateName = str
+
+_KEY_PATTERN = r"^.+#\d+(?:-\d+)*$"
+
+
+@dataclass(frozen=True)
+class DataKey:
+    gate: GateName
+    addr: QubitAddr
+
+    def as_tuple(self) -> tuple[GateName, QubitAddr]:
+        return (self.gate, self.addr)
+
+    @staticmethod
+    def from_string(value: Any) -> "DataKey | None":
+        match value:
+            case str():
+                if not re.match(_KEY_PATTERN, value):
+                    raise KeyError(f"invalid string for DataKey {value}")
+                gate, qubit_str = value.split("#", 1)
+                qubit_addr = tuple(int(q) for q in qubit_str.split("-"))
+                return DataKey(gate=gate, addr=qubit_addr)
+            case _:
+                return None
+
+    def serialize_as_string(self) -> str:
+        return f"{self.gate}#{'-'.join(str(i) for i in self.addr)}"
+
+
+DataKeyTypeAdapter = TypeAdapter(DataKey)
+DataKeyLike = Annotated[
+    DataKey,
+    BeforeValidator(lambda x: DataKey.from_string(x) or x),
+    PlainSerializer(lambda x: x.serialize_as_string(), return_type=str),
+]
+
+
+@dataclass
+class DefCalData:
+    body: str
+    status: Literal["calibrated", "uncalibrated"]

boulderopalscaleupsdk/device/device.py

@@ -11,10 +11,15 @@
 # distributed under the License is distributed on an "AS IS" BASIS. See the
 # License for the specific language.
 
+
 from pydantic import BaseModel
 from pydantic.dataclasses import dataclass
 
-from boulderopalscaleupsdk.device.controller.quantum_machines import QuantumMachinesControllerInfo
+from boulderopalscaleupsdk.device.controller import (
+    QBLOXControllerInfo,
+    QuantumMachinesControllerInfo,
+)
+from boulderopalscaleupsdk.device.defcal import DataKeyLike, DefCalData
 from boulderopalscaleupsdk.device.processor import SuperconductingProcessor
 
 
@@ -22,7 +27,8 @@ class Device(BaseModel):
     """Device specification."""
 
     processor: SuperconductingProcessor  # | OtherProcessorTypes
-    controller_info: QuantumMachinesControllerInfo  # | OtherControllerInfoTypes
+    controller_info: QBLOXControllerInfo | QuantumMachinesControllerInfo
+    defcals: dict[DataKeyLike, DefCalData]
 
 
 @dataclass

boulderopalscaleupsdk/device/processor/__init__.py

@@ -12,12 +12,20 @@
 # License for the specific language.
 
 __all__ = [
+    "CalibrationThresholds",
     "ComponentParameter",
     "DurationComponentParameter",
     "FloatComponentParameter",
     "SuperconductingProcessor",
     "SuperconductingProcessorTemplate",
+    "update_parameter",
 ]
 
-from .common import ComponentParameter, DurationComponentParameter, FloatComponentParameter
+from .common import (
+    CalibrationThresholds,
+    ComponentParameter,
+    DurationComponentParameter,
+    FloatComponentParameter,
+    update_parameter,
+)
 from .superconducting_processor import SuperconductingProcessor, SuperconductingProcessorTemplate