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

boulderopalscaleupsdk/device/processor/common.py

@@ -12,12 +12,19 @@
 # License for the specific language.
 
 from collections.abc import Callable
-from datetime import datetime, timezone
-from typing import Annotated, Any, Generic, Literal, TypeVar
+from datetime import UTC, datetime
+from types import EllipsisType
+from typing import Annotated, Any, Generic, Literal, Self, TypeVar
 
-from pydantic import BaseModel, BeforeValidator, ConfigDict, TypeAdapter
+from pydantic import BeforeValidator, ConfigDict, TypeAdapter
+from pydantic.dataclasses import dataclass
 
-from boulderopalscaleupsdk.common.dtypes import Duration, DurationNsLike, ISO8601DatetimeUTCLike
+from boulderopalscaleupsdk.common.dtypes import (
+    Duration,
+    DurationNsLike,
+    Frequency,
+    ISO8601DatetimeUTCLike,
+)
 from boulderopalscaleupsdk.common.typeclasses import Combine
 
 T = TypeVar("T")
@@ -25,8 +32,20 @@ T2 = TypeVar("T2")
 CalibrationStatusT = Literal["approximate", "bad", "good", "stale", "unmeasured"]
 
 
-class ComponentParameter(BaseModel, Generic[T]):
-    dtype: Literal["component-parameter"] = "component-parameter"
+@dataclass
+class CalibrationThresholds:
+    good: float
+    approximate: float
+
+    def __post_init__(self):
+        if self.good <= 0 or self.approximate < self.good:
+            raise ValueError(
+                f"Invalid thresholds: good: {self.good}, approximate: {self.approximate}",
+            )
+
+
+@dataclass
+class ComponentParameter(Generic[T]):
     value: T
     err_minus: T | None = None
     err_plus: T | None = None
@@ -40,7 +59,7 @@ class ComponentParameter(BaseModel, Generic[T]):
         cls,
         value: Any,
         target_type: type[float | int | Duration],
-    ) -> "ComponentParameter":
+    ) -> Self:
         """
         Create a ComponentParameter instance from a value, ensuring it matches the target type.
 
@@ -64,7 +83,7 @@ class ComponentParameter(BaseModel, Generic[T]):
         match value:
             case value if isinstance(value, cls):
                 if not isinstance(value.value, target_type):
-                    raise TypeError("invalid value type")
+                    raise TypeError("Invalid value type.")
                 return value
             case _ if target_type in [float, int]:
                 return cls(**value)
@@ -73,7 +92,7 @@ class ComponentParameter(BaseModel, Generic[T]):
                 duration_ns = TypeAdapter(DurationNsLike).validate_python(value_copy.pop("value"))
                 return cls(value=duration_ns, **value_copy)  # type: ignore[arg-type]
             case _:
-                return cls.model_validate(value)
+                raise TypeError("Invalid component value type.")
 
     @staticmethod
     def combine(
@@ -94,7 +113,7 @@ class ComponentParameter(BaseModel, Generic[T]):
                     other.err_plus,
                 ),
                 calibration_status=other.calibration_status,
-                updated_at=datetime.now(tz=timezone.utc),
+                updated_at=datetime.now(tz=UTC),
             )
 
         return Combine[ComponentParameter[T]].create(_combine)
@@ -116,23 +135,113 @@ class ComponentParameter(BaseModel, Generic[T]):
         self.calibration_status = combined.calibration_status
         self.updated_at = combined.updated_at
 
+    def update(
+        self,
+        *,
+        value: T | EllipsisType = ...,
+        err_minus: T | None | EllipsisType = ...,
+        err_plus: T | None | EllipsisType = ...,
+        calibration_status: CalibrationStatusT | EllipsisType = ...,
+    ) -> None:
+        if not isinstance(value, EllipsisType):
+            self.value = value
+        if not isinstance(err_minus, EllipsisType):
+            self.err_minus = err_minus
+        if not isinstance(err_plus, EllipsisType):
+            self.err_plus = err_plus
+        if not isinstance(calibration_status, EllipsisType):
+            self.calibration_status = calibration_status
+        self.updated_at = datetime.now(UTC)
+
+    def simple_update(
+        self,
+        *,
+        value: T | EllipsisType = ...,
+        std: T | None | EllipsisType = ...,
+        calibration_thresholds: CalibrationThresholds | EllipsisType = ...,
+        to_float: Callable[[T], float],
+        from_float: Callable[[float], T],
+    ) -> None:
+        if not isinstance(value, EllipsisType):
+            self.value = value
+        if not isinstance(std, EllipsisType):
+            if std is None:
+                self.err_minus = None
+                self.err_plus = None
+            else:
+                self.err_minus = from_float(to_float(std) / 2.0)
+                self.err_plus = from_float(to_float(std) / 2.0)
+        if (
+            not isinstance(calibration_thresholds, EllipsisType)
+            and self.err_minus is not None
+            and self.err_plus is not None
+        ):
+            self.calibration_status = _get_calibration_status_from_thresholds(
+                value=to_float(self.value),
+                confidence_interval=to_float(self.err_plus) - to_float(self.err_minus),
+                calibration_thresholds=calibration_thresholds,
+            )
+        self.updated_at = datetime.now(UTC)
+
+
+def update_parameter(
+    parameter: ComponentParameter[T],
+    *,
+    value: T | EllipsisType = ...,
+    std: T | None | EllipsisType = ...,
+    calibration_thresholds: CalibrationThresholds | EllipsisType = ...,
+) -> None:
+    """
+    Update a ComponentParameter.
 
-def get_calibration_status_from_thresholds(
+    Parameters
+    ----------
+    parameter : ComponentParameter[T]
+        The parameter to update.
+    value : T | EllipsisType, optional
+        The parameter value. If not provided, the value is left unchanged.
+    std : T | None | EllipsisType, optional
+        The standard deviation to set the parameter errors.
+        If None, the errors are cleared.
+        If not provided, the error is left unchanged.
+    calibration_thresholds : CalibrationThresholds
+        The thresholds to update the calibration status.
+        If not provided, the status is left unchanged.
+        If the parameter errors are not set, the status is left unchanged.
+    """
+
+    # Use type of value to determine generic T.
+    match parameter.value:
+        case float():
+            parameter.simple_update(
+                value=value,
+                std=std,
+                calibration_thresholds=calibration_thresholds,
+                to_float=float,  # type: ignore[arg-type]
+                from_float=float,  # type: ignore[arg-type]
+            )
+        case Frequency():
+            parameter.simple_update(
+                value=value,
+                std=std,
+                calibration_thresholds=calibration_thresholds,
+                to_float=Frequency.to_float_hz,  # type: ignore[arg-type]
+                from_float=Frequency.from_float_hz,  # type: ignore[arg-type]
+            )
+        case _:
+            raise TypeError(f"Unsupported type in update: {type(parameter.value)}.")
+
+
+def _get_calibration_status_from_thresholds(
     value: float,
     confidence_interval: float,
-    good_threshold: float,
-    approximate_threshold: float,
+    calibration_thresholds: CalibrationThresholds,
 ) -> CalibrationStatusT:
-    if good_threshold <= 0 or approximate_threshold <= 0 or good_threshold >= approximate_threshold:
-        raise ValueError(
-            f"Invalid thresholds: good: {good_threshold}, approximate: {approximate_threshold}",
-        )
-
     relative_uncertainty = abs(confidence_interval / value)
 
-    if relative_uncertainty < good_threshold:
+    if relative_uncertainty < calibration_thresholds.good:
         return "good"
-    if relative_uncertainty < approximate_threshold:
+    if relative_uncertainty < calibration_thresholds.approximate:
         return "approximate"
     return "bad"
 

boulderopalscaleupsdk/device/processor/superconducting_processor.py

@@ -14,7 +14,7 @@
 from copy import deepcopy
 from typing import Annotated, Any, Literal, Union, get_args, get_origin
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, TypeAdapter
 
 from boulderopalscaleupsdk.common.dtypes import (
     Duration,
@@ -81,9 +81,9 @@ class Transmon(Component[Literal["tunable"]]):
     )
 
 
-class Resonator(Component[Literal["dispersive"]]):
+class Resonator(Component[Literal["readout"]]):
     dtype: Literal["resonator"] = "resonator"
-    traits: list[Literal["dispersive"]] = Field(default=["dispersive"])
+    traits: list[Literal["readout"]] = Field(default=["readout"])
 
     frequency_high: FloatComponentParameter | None = Field(
         default=None,
@@ -109,6 +109,33 @@ class Resonator(Component[Literal["dispersive"]]):
         default=ComponentParameter(value=0.0),
         json_schema_extra={"display": {"label": "vp_high", "unit": "V", "scale": 1}},
     )
+    purcell_coupling: FloatComponentParameter = Field(
+        default=ComponentParameter(value=0.0),
+        json_schema_extra={"display": {"label": "purcell_coupling", "unit": "MHz", "scale": 1e-6}},
+    )
+    purcell_frequency: FloatComponentParameter = Field(
+        default=ComponentParameter(value=0.0),
+        json_schema_extra={"display": {"label": "purcell_frequency", "unit": "MHz", "scale": 1e-6}},
+    )
+
+
+class Coupler(Component[Literal["tunable"]]):
+    dtype: Literal["coupler"] = "coupler"
+    traits: list[Literal["tunable"]] = Field(default=["tunable"])
+
+    # Tunable coupler parameters
+    dc_bias: FloatComponentParameter = Field(
+        default=ComponentParameter(value=0.0),
+        json_schema_extra={"display": {"label": "dc_bias", "unit": "V", "scale": 1}},
+    )
+    fmax_bias: FloatComponentParameter = Field(
+        default=ComponentParameter(value=0.0),
+        json_schema_extra={"display": {"label": "fmax_bias", "unit": "V", "scale": 1}},
+    )
+    bias_period: FloatComponentParameter = Field(
+        default=ComponentParameter(value=0.0),
+        json_schema_extra={"display": {"label": "bias_period", "unit": "V", "scale": 1}},
+    )
 
 
 class Port(Component[Literal["drive", "readout", "flux"]]):
@@ -128,7 +155,7 @@ class Feedline(Component[Literal["feedline"]]):
     traits: list = Field(default=[])
 
 
-SuperconductingComponentType = Transmon | Resonator | Port | Feedline | Filter
+SuperconductingComponentType = Transmon | Resonator | Port | Feedline | Filter | Coupler
 
 
 class Edge(BaseModel):
@@ -143,14 +170,14 @@ class TemplateParam(BaseModel):
 
 
 class ProcessorTemplate(BaseModel):
-    elements: dict[str, Transmon | Resonator | Port | Feedline | Filter]
+    elements: dict[str, Transmon | Resonator | Port | Feedline | Filter | Coupler]
     edges: list[Edge]
 
 
 class SuperconductingProcessorTemplate(BaseModel):
     build: list[TemplateParam]
     templates: dict[str, ProcessorTemplate]
-    device_parameters: dict[str, Transmon | Resonator | Port | Feedline | Filter] = Field(
+    device_parameters: dict[str, Transmon | Resonator | Port | Feedline | Filter | Coupler] = Field(
         default={},
     )
 
@@ -221,13 +248,32 @@ class SuperconductingProcessor(Processor):
             raise KeyError(f"Component with ID '{component_id}' does not exist.")
 
         component = self.nodes[component_id]
-        replacement_component = {
-            k: ComponentParameter(value=v).model_dump()
-            if k not in ["dtype", "traits"] and v is not None
-            else v
-            for k, v in params.items()
-        }
-        self.nodes[component_id] = type(component).model_validate(replacement_component)
+        updated_component = deepcopy(component)
+
+        for k, v in params.items():
+            component_param = getattr(updated_component, k)
+            if not isinstance(component_param, ComponentParameter):
+                raise ValueError(f"Invalid or unexpected parameter for {type(component)}.")  # noqa: TRY004
+
+            if k in ["dtype", "traits"]:
+                raise ValueError("Invalid attempt to modify component type or traits.")
+
+            if v is None:
+                continue
+
+            match v:
+                case ComponentParameter():
+                    setattr(updated_component, k, v)
+                case _:
+                    component_param.update(
+                        value=v,
+                        err_minus=None,
+                        err_plus=None,
+                        calibration_status="unmeasured",
+                    )
+                    setattr(updated_component, k, component_param)
+
+        self.nodes[component_id] = type(component).model_validate(updated_component.model_dump())
 
     def get_component(self, component_id: str) -> SuperconductingComponentType:
         """
@@ -279,13 +325,13 @@ def _coerce_component_params(
             continue
 
         try:
-            dumped = value.model_dump()
+            dumped = TypeAdapter(type(value)).dump_python(value)
             coerced = expected_type(**dumped)
             setattr(component, field_name, coerced)
         except Exception as e:
             raise ValueError(
                 f"Failed to coerce field '{field_name}' of type "
-                "'{expected_type}' with value '{value}': {e}",
+                "'{expected_type}' with value '{value}': {e}.",
             ) from e
 
     return component

boulderopalscaleupsdk/experiments/__init__.py

@@ -15,6 +15,7 @@
 
 __all__ = [
     "CWSIterable",
+    "Chi01Scan",
     "ConstantWaveform",
     "Experiment",
     "GaussianWaveform",
@@ -23,11 +24,15 @@ __all__ = [
     "PowerRabi",
     "Ramsey",
     "RangeIterable",
+    "ReadoutClassifierCalibration",
     "ResonatorSpectroscopy",
     "ResonatorSpectroscopyByBias",
     "ResonatorSpectroscopyByPower",
+    "TransmonAnharmonicity",
+    "TransmonSpectroscopy",
 ]
 
+from .chi01_scan import Chi01Scan
 from .common import (
     ConstantWaveform,
     CWSIterable,
@@ -39,6 +44,9 @@ from .common import (
 )
 from .power_rabi import PowerRabi
 from .ramsey import Ramsey
+from .readout_classifier_calibration import ReadoutClassifierCalibration
 from .resonator_spectroscopy import ResonatorSpectroscopy
 from .resonator_spectroscopy_by_bias import ResonatorSpectroscopyByBias
 from .resonator_spectroscopy_by_power import ResonatorSpectroscopyByPower
+from .transmon_anharmonicity import TransmonAnharmonicity
+from .transmon_spectroscopy import TransmonSpectroscopy

boulderopalscaleupsdk/experiments/chi01_scan.py

@@ -0,0 +1,56 @@
+# 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 pydantic import PrivateAttr
+
+from boulderopalscaleupsdk.experiments.common import (
+    CWSIterable,
+    Experiment,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+DEFAULT_RECYCLE_DELAY_NS = 10_000
+DEFAULT_SHOT_COUNT = 100
+
+
+class Chi01Scan(Experiment):
+    """
+    Parameters for running an experiment to find the dispersive shift for a transmon
+    resonator pair.
+
+    Attributes
+    ----------
+    transmon : str
+        The reference for the transmon to target in the experiment.
+    frequencies : list[int] or LinspaceIterable or RangeIterable or CWSIterable
+                  or HypIterable or None, optional
+        The frequencies at which to scan.
+        If None, frequencies around the readout frequency will be used.
+    recycle_delay_ns : int, optional
+        The delay time between consecutive shots of the experiment, in nanoseconds.
+        Defaults to 10000 ns.
+    shot_count : int, optional
+        The number of shots to be taken in the experiment.
+        Defaults to 100.
+    """
+
+    _experiment_name: str = PrivateAttr("chi01_scan")
+
+    transmon: str
+    frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
+        None
+    )
+    recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
+    shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/experiments/common.py

@@ -26,7 +26,11 @@ class Experiment(BaseModel):
         return self._experiment_name
 
 
-class LinspaceIterable(BaseModel):
+class _RangeIterable(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class LinspaceIterable(_RangeIterable):
     """A linear space of float values."""
 
     dtype: Literal["linspace"] = "linspace"
@@ -39,7 +43,7 @@ class LinspaceIterable(BaseModel):
     count: int = Field(default=101)
 
 
-class RangeIterable(BaseModel):
+class RangeIterable(_RangeIterable):
     """A range of values with a specified step."""
 
     dtype: Literal["range"] = "range"
@@ -52,7 +56,7 @@ class RangeIterable(BaseModel):
     step: float
 
 
-class CWSIterable(BaseModel):
+class CWSIterable(_RangeIterable):
     """A range of linearly spaced values in center ± width/2."""
 
     dtype: Literal["cws"] = "cws"
@@ -65,7 +69,7 @@ class CWSIterable(BaseModel):
     step: float
 
 
-class HypIterable(BaseModel):
+class HypIterable(_RangeIterable):
     """
     A hyperbolic iterable of values in center ± width/2,
     with points more concentrated around the center.

boulderopalscaleupsdk/experiments/power_rabi.py

@@ -32,8 +32,8 @@ class PowerRabi(Experiment):
 
     Parameters
     ----------
-    qubit : int
-        The qubit whose resonator to target in the experiment.
+    transmon : str
+        The reference for the transmon to target in the experiment.
     scales : list[float] or LinspaceIterable or RangeIterable
             or CWSIterable or HypIterable or None, optional
         The scaling factors for the drive pulse amplitude. If None, a default scan will be used.
@@ -51,7 +51,7 @@ class PowerRabi(Experiment):
 
     _experiment_name: str = PrivateAttr("power_rabi")
 
-    qubit: int
+    transmon: str
     scales: list[float] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = None
     drive_waveform: GaussianWaveform
     measure_waveform: ConstantWaveform

boulderopalscaleupsdk/experiments/ramsey.py

@@ -17,6 +17,7 @@ from .common import Experiment
 
 DEFAULT_RECYCLE_DELAY_NS = 10_000
 DEFAULT_SHOT_COUNT = 400
+DEFAULT_DURATION_NS = 2_000
 
 
 class Ramsey(Experiment):
@@ -25,18 +26,22 @@ class Ramsey(Experiment):
 
     Parameters
     ----------
-    qubit : int
-        The qubit whose resonator to target in the experiment.
+    transmon : str
+        The reference for the transmon to target in the experiment.
     max_delay_ns : int
         The maximum delay time, in nanoseconds.
     min_delay_ns : int
         The minimum delay time, in nanoseconds.
     delay_step_ns : int
         The step for generating the list of delays, in nanoseconds.
-    detuning : float
-        The difference between the drive signal frequency and the qubit frequency,
-        in Hz.
-    recycle_delay_ns : float, optional
+    virtual_detuning : float
+        The difference between the drive signal frequency and the qubit frequency, in Hz.
+    readout_amplitude : float
+        The amplitude of the readout pulse.
+    duration_ns : int, optional
+        The duration of the pulse, in nanoseconds.
+        Defaults to 2000 ns.
+    recycle_delay_ns : int, optional
         The delay time between consecutive shots of the experiment, in nanoseconds.
         Defaults to 10000 ns.
     shot_count : int, optional
@@ -46,10 +51,12 @@ class Ramsey(Experiment):
 
     _experiment_name: str = PrivateAttr("ramsey")
 
-    qubit: int
+    transmon: str
     max_delay_ns: int
     min_delay_ns: int
     delay_step_ns: int
-    detuning: float
+    virtual_detuning: float
+    readout_amplitude: float
+    duration_ns: int = DEFAULT_DURATION_NS
     recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
     shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/experiments/readout_classifier_calibration.py

@@ -0,0 +1,24 @@
+from pydantic import PrivateAttr
+
+from boulderopalscaleupsdk.experiments.common import Experiment
+
+
+class ReadoutClassifierCalibration(Experiment):
+    """
+    Parameters for running calibration of readout classifier for a transmon.
+
+    Parameters
+    ----------
+    transmon : str
+        The reference for the transmon to target in the experiment.
+    recycle_delay_ns : int
+        The delay time between consecutive shots of the experiment, in nanoseconds.
+    shot_count : int, optional
+        The number of shots to be taken in the experiment.
+        Defaults to 5000.
+    """
+
+    _experiment_name: str = PrivateAttr("readout_classifier_calibration")
+    transmon: str
+    recycle_delay_ns: int
+    shot_count: int = 5000

boulderopalscaleupsdk/experiments/resonator_spectroscopy.py

@@ -32,8 +32,8 @@ class ResonatorSpectroscopy(Experiment):
 
     Parameters
     ----------
-    qubit : int
-        The qubit whose resonator to target in the experiment.
+    resonator : str
+        The reference for the resonator to target in the experiment.
     frequencies : list[int] or LinspaceIterable or RangeIterable or CWSIterable
                   or HypIterable or None, optional
         The frequencies at which to scan.
@@ -54,7 +54,7 @@ class ResonatorSpectroscopy(Experiment):
 
     _experiment_name: str = PrivateAttr("resonator_spectroscopy")
 
-    qubit: int
+    resonator: str
     frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
         None
     )

boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_bias.py

@@ -33,12 +33,12 @@ class ResonatorSpectroscopyByBias(Experiment):
 
     Parameters
     ----------
-    qubit : int
-        The qubit whose resonator to target in the experiment.
-    bias_qubits : list[int] or None, optional
-        The qubits whose biases to target.
-        If None, defaults to the qubit.
-    frequencies : list[float] or LinspaceIterable or RangeIterable or CWSIterable
+    resonator : str
+        The reference for the resonator to target in the experiment.
+    bias_transmons : list[str] or None, optional
+        The transmons to bias.
+        If None, it defaults to transmon coupled to the resonator.
+    frequencies : list[int] or LinspaceIterable or RangeIterable or CWSIterable
                   or HypIterable or None, optional
         The frequencies at which to scan.
         If None, frequencies around the readout frequency will be used.
@@ -49,10 +49,10 @@ class ResonatorSpectroscopyByBias(Experiment):
     readout_amplitude : float, optional
         The amplitude of the readout pulse.
         Defaults to None.
-    duration_ns : float, optional
+    duration_ns : int, optional
         The duration of the pulse, in nanoseconds.
         Defaults to 2000 ns.
-    recycle_delay_ns : float, optional
+    recycle_delay_ns : int, optional
         The delay time between consecutive shots of the experiment, in nanoseconds.
         Defaults to 10000 ns.
     shot_count : int, optional
@@ -62,8 +62,8 @@ class ResonatorSpectroscopyByBias(Experiment):
 
     _experiment_name: str = PrivateAttr("resonator_spectroscopy_by_bias")
 
-    qubit: int
-    bias_qubits: list[int] | None = None
+    resonator: str
+    bias_transmons: list[str] | None = None
     frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
         None
     )

boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_power.py

@@ -32,8 +32,8 @@ class ResonatorSpectroscopyByPower(Experiment):
 
     Parameters
     ----------
-    qubit : int
-        The qubit whose resonator to target in the experiment.
+    resonator : str
+        The reference for the resonator to target in the experiment.
     frequencies : list[int] or LinspaceIterable or RangeIterable or CWSIterable
                   or HypIterable or None, optional
         The frequencies at which to scan.
@@ -54,7 +54,7 @@ class ResonatorSpectroscopyByPower(Experiment):
 
     _experiment_name: str = PrivateAttr("resonator_spectroscopy_by_power")
 
-    qubit: int
+    resonator: str
     frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
         None
     )