boulder-opal-scale-up-sdk 1.0.5__py3-none-any.whl → 1.0.7__py3-none-any.whl

boulderopalscaleupsdk/experiments/ramsey_ef.py

@@ -0,0 +1,62 @@
+# 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.
+
+from typing import Literal
+
+from pydantic import PrivateAttr
+
+from .common import Experiment
+from .waveforms import ConstantWaveform
+
+
+class RamseyEF(Experiment):
+    """
+    Parameters for running a EF Ramsey experiment.
+
+    Attributes
+    ----------
+    transmon : str
+        The reference for the transmon to target.
+    min_delay_ns : int
+        The minimum delay time, in nanoseconds.
+    max_delay_ns : int
+        The maximum delay time, in nanoseconds.
+    delay_step_ns : int
+        The step for generating the list of delays, in nanoseconds.
+    virtual_detuning : float
+        The virtual detuning added between sx_ef pulses, in Hz.
+    recycle_delay_ns : int, optional
+        The delay between consecutive shots, in nanoseconds. Defaults to 200,000 ns.
+    shot_count : int, optional
+        The number of shots to take. Defaults to 400.
+    measure_waveform : ConstantWaveform or None, optional
+        The waveform to use for the measurement pulse.
+        Defaults to the measurement defcal.
+    run_mixer_calibration: bool
+        Whether to run mixer calibrations before running a program. Defaults to False.
+    update : "auto" or "off" or "prompt", optional
+        How the device should be updated after an experiment run. Defaults to auto.
+    """
+
+    _experiment_name: str = PrivateAttr("ramsey_ef")
+
+    transmon: str
+    min_delay_ns: int
+    max_delay_ns: int
+    delay_step_ns: int
+    virtual_detuning: float
+    recycle_delay_ns: int = 200_000
+    shot_count: int = 400
+    measure_waveform: ConstantWaveform | None = None
+    run_mixer_calibration: bool = False
+    update: Literal["auto", "off", "prompt"] = "auto"

boulderopalscaleupsdk/experiments/{readout_classifier_calibration.py → readout_classifier.py}

@@ -19,9 +19,13 @@ from .common import Experiment
 from .waveforms import ConstantWaveform
 
 
-class ReadoutClassifierCalibration(Experiment):
+class ReadoutClassifier(Experiment):
     """
-    Parameters for running calibration of readout classifier for a transmon.
+    Parameters for training a readout classifier.
+
+    This does not optimize the readout pulse itself.
+    The measure waveform is fixed (provided or using the device's default).
+    To optimize the readout pulse use ReadoutOptimization.
 
     Attributes
     ----------
@@ -40,7 +44,7 @@ class ReadoutClassifierCalibration(Experiment):
         How the device should be updated after an experiment run. Defaults to auto.
     """
 
-    _experiment_name: str = PrivateAttr("readout_classifier_calibration")
+    _experiment_name: str = PrivateAttr("readout_classifier")
 
     transmon: str
     recycle_delay_ns: int = 200_000

boulderopalscaleupsdk/experiments/readout_optimization.py

@@ -0,0 +1,57 @@
+# 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.
+
+from typing import Literal
+
+from pydantic import PrivateAttr
+
+from .common import (
+    CWSIterable,
+    Experiment,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+
+class ReadoutOptimization(Experiment):
+    """
+    Parameters for optimizing the readout classifier.
+
+    Parameters
+    ----------
+    transmon : str
+        The reference for the transmon to target.
+    frequencies : list[int] or LinspaceIterable or RangeIterable or CWSIterable or HypIterable
+        The readout frequencies to sweep, in Hz.
+    amplitudes : list[float]
+        The readout amplitudes to sweep.
+    recycle_delay_ns : int
+        The delay between consecutive shots, in nanoseconds. Defaults to 200,000 ns.
+    shot_count : int, optional
+        The number of shots to take. Defaults to 5,000.
+    run_mixer_calibration: bool
+        Whether to run mixer calibrations before running a program. Defaults to False.
+    update : "auto" or "off", optional
+        How the device should be updated after an experiment run. Defaults to auto.
+    """
+
+    _experiment_name: str = PrivateAttr("readout_optimization")
+
+    transmon: str
+    frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable
+    amplitudes: list[float]
+    recycle_delay_ns: int = 200_000
+    shot_count: int = 5000
+    run_mixer_calibration: bool = False
+    update: Literal["auto", "off"] = "auto"

boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_bias.py

@@ -24,8 +24,6 @@ from .common import (
 )
 from .waveforms import ConstantWaveform
 
-DEFAULT_BIASES = LinspaceIterable(start=-0.49, stop=0.49, count=21)
-
 
 class ResonatorSpectroscopyByBias(Experiment):
     """
@@ -44,7 +42,7 @@ class ResonatorSpectroscopyByBias(Experiment):
         Defaults to a scan around the readout frequency.
     biases : list[int] or LinspaceIterable or RangeIterable or CWSIterable \
              or HypIterable, optional
-        The biases at which to scan, in Volts.
+        The biases at which to scan, in volts.
         Defaults to 21 points between -0.49 and 0.49.
     recycle_delay_ns : int, optional
         The delay between consecutive shots, in nanoseconds. Defaults to 1,000 ns.
@@ -67,7 +65,7 @@ class ResonatorSpectroscopyByBias(Experiment):
         None
     )
     biases: list[float] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable = (
-        DEFAULT_BIASES
+        LinspaceIterable(start=-0.49, stop=0.49, count=21)
     )
     recycle_delay_ns: int = 1_000
     shot_count: int = 100

boulderopalscaleupsdk/experiments/t2.py

@@ -22,7 +22,7 @@ class T2(Experiment):
     """
     Parameters for running a T2 experiment.
 
-    Parameters
+    Attributes
     ----------
     transmon : str
         The reference for the transmon to target.

boulderopalscaleupsdk/experiments/transmon_anharmonicity.py

@@ -24,8 +24,6 @@ from .common import (
 )
 from .waveforms import ConstantWaveform
 
-DEFAULT_RECYCLE_DELAY_NS = 1_000  # ns
-
 
 class TransmonAnharmonicity(Experiment):
     """

boulderopalscaleupsdk/experiments/waveforms.py

@@ -29,6 +29,9 @@ class ConstantWaveform(_Waveform):  # pragma: no cover
     amplitude: float
     waveform_type: Literal["Constant"] = "Constant"
 
+    def __str__(self):
+        return f"ConstantWaveform(duration_ns={self.duration_ns}, amplitude={self.amplitude})"
+
 
 @dataclass
 class GaussianWaveform(_Waveform):  # pragma: no cover
@@ -37,6 +40,12 @@ class GaussianWaveform(_Waveform):  # pragma: no cover
     sigma: float
     waveform_type: Literal["Gaussian"] = "Gaussian"
 
+    def __str__(self):
+        return (
+            f"GaussianWaveform(duration_ns={self.duration_ns}, "
+            f"amplitude={self.amplitude}, sigma={self.sigma})"
+        )
+
 
 @dataclass
 class DragCosineWaveform(_Waveform):  # pragma: no cover
@@ -47,6 +56,12 @@ class DragCosineWaveform(_Waveform):  # pragma: no cover
     center: float
     waveform_type: Literal["DragCosineWaveform"] = "DragCosineWaveform"
 
+    def __str__(self):
+        return (
+            f"DragCosineWaveform(duration_ns={self.duration_ns}, amplitude={self.amplitude}, "
+            f"drag={self.drag}, buffer_ns={self.buffer_ns}, center={self.center})"
+        )
+
 
 Waveform = Annotated[
     ConstantWaveform | GaussianWaveform | DragCosineWaveform,

boulderopalscaleupsdk/grpc_interceptors/error.py

@@ -0,0 +1,318 @@
+# 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.
+
+from __future__ import annotations
+
+import inspect
+import re
+from typing import TYPE_CHECKING, Any
+
+import grpc
+import grpc.aio
+
+from boulderopalscaleupsdk.errors import ScaleUpServerError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterable, AsyncIterator
+
+# ------------------------
+# Helpers
+# ------------------------
+
+_GRPC_MESSAGE_RE = re.compile(r'grpc_message:"([^"]+)"')
+
+
+def _extract_peer_message(err: grpc.RpcError) -> str | None:
+    dbg = getattr(err, "debug_error_string", None)
+    if callable(dbg):
+        try:
+            s = dbg()
+        except (AttributeError, TypeError, RuntimeError):
+            return None
+        if isinstance(s, str):
+            m = _GRPC_MESSAGE_RE.search(s)
+            if m:
+                return m.group(1)
+    return None
+
+
+def _concise_error(err: grpc.RpcError, *, include_code: bool = False) -> str:
+    msg = _extract_peer_message(err) or (err.details() or "An unknown error occurred.")
+    if include_code:
+        try:
+            return f"{err.code().name}: {msg}"
+        except (AttributeError, ValueError):
+            pass
+    return msg
+
+
+# ------------------------
+# SYNC wrappers
+# ------------------------
+
+
+class _UnaryUnaryCallWrapper:
+    """Proxy that prettifies errors when .result() is called (sync)."""
+
+    def __init__(self, inner: Any, include_code: bool) -> None:
+        self._inner = inner
+        self._include_code = include_code
+
+    def result(self, timeout: float | None = None) -> Any:
+        try:
+            return self._inner.result(timeout)
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+    def __bool__(self) -> bool:
+        return bool(self._inner)
+
+
+class _SyncRespIterWrapper:
+    """Wrap response-stream iterator to prettify RpcError during iteration (sync)."""
+
+    def __init__(self, inner: Any, include_code: bool) -> None:
+        self._inner = inner
+        self._include_code = include_code
+
+    def __iter__(self):
+        try:
+            yield from self._inner
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+
+class _SyncReqIterWrapper:
+    """Wrap request-stream iterator to prettify RpcError while producing items (sync)."""
+
+    def __init__(self, inner: Any, include_code: bool) -> None:
+        self._inner = inner
+        self._include_code = include_code
+
+    def __iter__(self):
+        try:
+            yield from self._inner
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+
+# ------------------------
+# ASYNC wrappers
+# ------------------------
+
+
+class _AioRespAsyncIterWrapper:
+    """
+    Async iterator proxy that prettifies errors from response streams (async).
+    Accepts the Call object (UnaryStreamCall or StreamStreamCall).
+    """
+
+    def __init__(self, inner: Any, include_code: bool) -> None:
+        self._inner = inner
+        self._include_code = include_code
+
+    def __aiter__(self) -> AsyncIterator[Any]:
+        async def gen() -> AsyncIterator[Any]:
+            try:
+                async for item in self._inner:
+                    yield item
+            except grpc.RpcError as e:
+                raise ScaleUpServerError(
+                    _concise_error(e, include_code=self._include_code),
+                ) from None
+
+        return gen()
+
+    async def initial_metadata(self) -> Any:
+        try:
+            return await self._inner.initial_metadata()
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    async def trailing_metadata(self) -> Any:
+        try:
+            return await self._inner.trailing_metadata()
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def cancel(self) -> None:
+        return self._inner.cancel()
+
+    def code(self) -> Any:
+        return self._inner.code()
+
+    def details(self) -> str:
+        return self._inner.details()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._inner, name)
+
+
+class _AioReqAsyncIterWrapper:
+    """
+    Async request iterator wrapper that prettifies errors when producing request items.
+    Takes any AsyncIterable (not necessarily an AsyncIterator).
+    """
+
+    def __init__(self, inner: AsyncIterable[Any], include_code: bool) -> None:
+        self._inner = inner
+        self._include_code = include_code
+
+    def __aiter__(self) -> AsyncIterator[Any]:
+        async def gen() -> AsyncIterator[Any]:
+            try:
+                async for item in self._inner:
+                    yield item
+            except grpc.RpcError as e:
+                raise ScaleUpServerError(
+                    _concise_error(e, include_code=self._include_code),
+                ) from None
+
+        return gen()
+
+
+# ------------------------
+# Unified interceptor (sync + aio)
+# ------------------------
+
+
+class ErrorFormatterInterceptor(
+    # sync interfaces
+    grpc.UnaryUnaryClientInterceptor,
+    grpc.UnaryStreamClientInterceptor,
+    grpc.StreamUnaryClientInterceptor,
+    grpc.StreamStreamClientInterceptor,
+    # aio interfaces
+    grpc.aio.UnaryUnaryClientInterceptor,
+    grpc.aio.UnaryStreamClientInterceptor,
+    grpc.aio.StreamUnaryClientInterceptor,
+    grpc.aio.StreamStreamClientInterceptor,
+):
+    """
+    Prettifies gRPC errors raised by the server into ScaleUpServerError.
+
+    Works with both sync (grpc) and async (grpc.aio) channels.
+
+    - Detects whether `continuation` is a coroutine function.
+    - In async case, returns a coroutine that yields wrapped awaitable/async-iterable calls.
+    - In sync case, returns wrapped blocking call objects/iterators.
+    """
+
+    def __init__(self, include_code: bool = False) -> None:
+        self._include_code = include_code
+
+    # ---------- UNARY -> UNARY ----------
+
+    async def _async_unary_unary(self, continuation, client_call_details, request) -> Any:
+        try:
+            call = continuation(client_call_details, request)  # awaitable call
+            # Await here so callers receive the *message*, mirroring AuthInterceptor.
+            return await call
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def _sync_unary_unary(self, continuation, client_call_details, request) -> Any:
+        try:
+            call = continuation(client_call_details, request)  # blocking call
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+        return _UnaryUnaryCallWrapper(call, self._include_code)
+
+    def intercept_unary_unary(self, continuation, client_call_details, request):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_unary_unary(continuation, client_call_details, request)
+        return self._sync_unary_unary(continuation, client_call_details, request)
+
+    # ---------- UNARY -> STREAM ----------
+
+    async def _async_unary_stream(self, continuation, client_call_details, request) -> Any:
+        try:
+            resp_call = continuation(client_call_details, request)  # async-iterable call
+            # Do NOT await: return an iterator wrapper that prettifies stream errors.
+            return _AioRespAsyncIterWrapper(resp_call, self._include_code)
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def _sync_unary_stream(self, continuation, client_call_details, request) -> Any:
+        try:
+            resp_iter = continuation(client_call_details, request)  # iterator
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+        return _SyncRespIterWrapper(resp_iter, self._include_code)
+
+    def intercept_unary_stream(self, continuation, client_call_details, request):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_unary_stream(continuation, client_call_details, request)
+        return self._sync_unary_stream(continuation, client_call_details, request)
+
+    # ---------- STREAM -> UNARY ----------
+
+    async def _async_stream_unary(self, continuation, client_call_details, request_iterator) -> Any:
+        try:
+            wrapped_req = _AioReqAsyncIterWrapper(request_iterator, self._include_code)
+            call = continuation(client_call_details, wrapped_req)  # awaitable call
+            # Await and return the *message*.
+            return await call
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def _sync_stream_unary(self, continuation, client_call_details, request_iterator) -> Any:
+        try:
+            wrapped_req = _SyncReqIterWrapper(request_iterator, self._include_code)
+            call = continuation(client_call_details, wrapped_req)  # blocking call
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+        return _UnaryUnaryCallWrapper(call, self._include_code)
+
+    def intercept_stream_unary(self, continuation, client_call_details, request_iterator):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_stream_unary(continuation, client_call_details, request_iterator)
+        return self._sync_stream_unary(continuation, client_call_details, request_iterator)
+
+    # ---------- STREAM -> STREAM ----------
+
+    async def _async_stream_stream(
+        self,
+        continuation,
+        client_call_details,
+        request_iterator,
+    ) -> Any:
+        try:
+            wrapped_req = _AioReqAsyncIterWrapper(request_iterator, self._include_code)
+            resp_call = continuation(client_call_details, wrapped_req)  # async-iterable call
+            # Return iterator wrapper.
+            return _AioRespAsyncIterWrapper(resp_call, self._include_code)
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+
+    def _sync_stream_stream(self, continuation, client_call_details, request_iterator) -> Any:
+        try:
+            wrapped_req = _SyncReqIterWrapper(request_iterator, self._include_code)
+            resp_iter = continuation(client_call_details, wrapped_req)  # iterator
+        except grpc.RpcError as e:
+            raise ScaleUpServerError(_concise_error(e, include_code=self._include_code)) from None
+        return _SyncRespIterWrapper(resp_iter, self._include_code)
+
+    def intercept_stream_stream(self, continuation, client_call_details, request_iterator):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_stream_stream(continuation, client_call_details, request_iterator)
+        return self._sync_stream_stream(continuation, client_call_details, request_iterator)

boulderopalscaleupsdk/plotting/dtypes.py

@@ -19,7 +19,6 @@ from pydantic import (
     BaseModel,
     BeforeValidator,
     ConfigDict,
-    Field,
     PlainSerializer,
     ValidationError,
 )
@@ -87,7 +86,7 @@ class PlotConfig(BaseModel):
     report: PlotReport | None = None
 
 
-@dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+@dataclass(config=ConfigDict(arbitrary_types_allowed=True, extra="forbid"))
 class PlotData1D:
     x: _SerializableArray
     y: _SerializableArray
@@ -113,7 +112,7 @@ class PlotData1D:
             raise ValueError("The shapes of y and y_error must match.")
 
 
-@dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+@dataclass(config=ConfigDict(arbitrary_types_allowed=True, extra="forbid"))
 class HeatmapData:
     x: _SerializableArray
     y: _SerializableArray
@@ -123,6 +122,7 @@ class HeatmapData:
 
     # Whether to display the heatmap values as text.
     heatmap_text: bool = False
+    color_map: Literal["sequential", "divergent"] = "sequential"
 
     def __post_init__(self):
         if self.x.ndim != 1:
@@ -158,12 +158,12 @@ class LinePlot(BaseModel):
 
     config: PlotConfig
     heatmap: HeatmapData | None = None
-    lines: Annotated[list[PlotData1D], Field(min_length=1)]
+    lines: list[PlotData1D] = []
     markers: list[Marker] = []
     vlines: list[VLine] = []
 
 
-@dataclass(config=ConfigDict(arbitrary_types_allowed=True))
+@dataclass(config=ConfigDict(arbitrary_types_allowed=True, extra="forbid"))
 class HistogramData:
     data: _SerializableArray
     label: str | None = None