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

boulderopalscaleupsdk/experiments/common.py

@@ -0,0 +1,96 @@
+# 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 BaseModel, ConfigDict, Field
+from pydantic.dataclasses import dataclass
+
+
+class Experiment(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    _experiment_name: str
+
+    @property
+    def experiment_name(self) -> str:
+        return self._experiment_name
+
+
+class LinspaceIterable(BaseModel):
+    """A linear space of float values."""
+
+    dtype: Literal["linspace"] = "linspace"
+
+    # The starting value.
+    start: float
+    # The final value.
+    stop: float
+    # The number of values. Defaults to 101.
+    count: int = Field(default=101)
+
+
+class RangeIterable(BaseModel):
+    """A range of values with a specified step."""
+
+    dtype: Literal["range"] = "range"
+
+    # The starting value.
+    start: float
+    # The final value.
+    stop: float
+    # The step between values.
+    step: float
+
+
+class CWSIterable(BaseModel):
+    """A range of linearly spaced values in center ± width/2."""
+
+    dtype: Literal["cws"] = "cws"
+
+    # The central value. Defaults to the expected value.
+    center: float | None
+    # The range width.
+    width: float
+    # The step between values.
+    step: float
+
+
+class HypIterable(BaseModel):
+    """
+    A hyperbolic iterable of values in center ± width/2,
+    with points more concentrated around the center.
+    """
+
+    dtype: Literal["hyp"] = "hyp"
+
+    # The central value. Defaults to the expected value.
+    center: float | None
+    # The range width.
+    width: float
+    # The number of values. Defaults to 51.
+    count: int = Field(default=51)
+
+
+@dataclass
+class ConstantWaveform:
+    duration_ns: int
+    scale: float
+    waveform_type: Literal["constant"] = "constant"
+
+
+@dataclass
+class GaussianWaveform:
+    duration_ns: int
+    amplitude: float
+    sigma: float
+    waveform_type: Literal["gaussian"] = "gaussian"

boulderopalscaleupsdk/experiments/power_rabi.py

@@ -0,0 +1,60 @@
+# 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 .common import (
+    ConstantWaveform,
+    CWSIterable,
+    Experiment,
+    GaussianWaveform,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+DEFAULT_SHOT_COUNT = 400
+
+
+class PowerRabi(Experiment):
+    """
+    Parameters for running a Power Rabi experiment.
+
+    Parameters
+    ----------
+    qubit : int
+        The qubit whose resonator 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.
+    drive_waveform : GaussianWaveform
+        The waveform to use for the drive pulse.
+    measure_waveform : ConstantWaveform
+        The waveform to use for the measurement pulse.
+    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 400.
+    pulse_vp : float, optional
+        The voltage per pulse. If None, a default value will be used.
+    """
+
+    _experiment_name: str = PrivateAttr("power_rabi")
+
+    qubit: int
+    scales: list[float] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = None
+    drive_waveform: GaussianWaveform
+    measure_waveform: ConstantWaveform
+    recycle_delay_ns: int
+    shot_count: int = DEFAULT_SHOT_COUNT
+    pulse_vp: float | None = None

boulderopalscaleupsdk/experiments/ramsey.py

@@ -0,0 +1,55 @@
+# 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 .common import Experiment
+
+DEFAULT_RECYCLE_DELAY_NS = 10_000
+DEFAULT_SHOT_COUNT = 400
+
+
+class Ramsey(Experiment):
+    """
+    Parameters for running a Ramsey experiment.
+
+    Parameters
+    ----------
+    qubit : int
+        The qubit whose resonator 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
+        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 400.
+    """
+
+    _experiment_name: str = PrivateAttr("ramsey")
+
+    qubit: int
+    max_delay_ns: int
+    min_delay_ns: int
+    delay_step_ns: int
+    detuning: float
+    recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
+    shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/experiments/resonator_spectroscopy.py

@@ -0,0 +1,64 @@
+# 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 .common import (
+    CWSIterable,
+    Experiment,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+DEFAULT_DURATION_NS = 2000  # ns
+DEFAULT_RECYCLE_DELAY_NS = 1000  # ns
+DEFAULT_SHOT_COUNT = 100
+
+
+class ResonatorSpectroscopy(Experiment):
+    """
+    Parameters for running a resonator spectroscopy experiment.
+
+    Parameters
+    ----------
+    qubit : int
+        The qubit whose 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.
+        If None, frequencies around the readout frequency will be used.
+    readout_amplitude : float, optional
+        The amplitude of the readout pulse.
+        If None, a default amplitude will be used.
+    duration_ns : int, optional
+        The duration of the readout 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 1000 ns.
+    shot_count : int, optional
+        The number of shots to be taken in the experiment.
+        Defaults to 100.
+    """
+
+    _experiment_name: str = PrivateAttr("resonator_spectroscopy")
+
+    qubit: int
+    frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
+        None
+    )
+    readout_amplitude: float | None = None
+    duration_ns: int = DEFAULT_DURATION_NS
+    recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
+    shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_bias.py

@@ -0,0 +1,76 @@
+# 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 .common import (
+    CWSIterable,
+    Experiment,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+DEFAULT_DURATION_NS = 2000
+DEFAULT_SHOT_COUNT = 100
+DEFAULT_RECYCLE_DELAY_NS = 10_000
+DEFAULT_BIASES = LinspaceIterable(start=-0.49, stop=0.49, count=21)
+
+
+class ResonatorSpectroscopyByBias(Experiment):
+    """
+    Parameters for running a resonator spectroscopy by power 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
+                  or HypIterable or None, optional
+        The frequencies at which to scan.
+        If None, frequencies around the readout frequency will be used.
+    biases : list[int] or LinspaceIterable or RangeIterable or CWSIterable
+             or HypIterable, optional
+        The biases at which to scan.
+        If None, defaults to 21 points between -0.49 and 0.49.
+    readout_amplitude : float, optional
+        The amplitude of the readout pulse.
+        Defaults to None.
+    duration_ns : float, optional
+        The duration of the pulse, in nanoseconds.
+        Defaults to 2000 ns.
+    recycle_delay_ns : float, 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("resonator_spectroscopy_by_bias")
+
+    qubit: int
+    bias_qubits: list[int] | None = None
+    frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
+        None
+    )
+    biases: list[float] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable = (
+        DEFAULT_BIASES
+    )
+    readout_amplitude: float | None = None
+    duration_ns: int = DEFAULT_DURATION_NS
+    recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
+    shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_power.py

@@ -0,0 +1,64 @@
+# 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 .common import (
+    CWSIterable,
+    Experiment,
+    HypIterable,
+    LinspaceIterable,
+    RangeIterable,
+)
+
+DEFAULT_DURATION_NS = 2000  # ns
+DEFAULT_RECYCLE_DELAY_NS = 1000  # ns
+DEFAULT_SHOT_COUNT = 100
+
+
+class ResonatorSpectroscopyByPower(Experiment):
+    """
+    Parameters for running a resonator spectroscopy by power experiment.
+
+    Parameters
+    ----------
+    qubit : int
+        The qubit whose 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.
+        If None, frequencies around the readout frequency will be used.
+    powers : list[int] or None, optional
+        The powers at which to scan the readout pulse.
+        If None, a default power scan will be used.
+    duration_ns : int, optional
+        The duration of the readout 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 1000 ns.
+    shot_count : int, optional
+        The number of shots to be taken in the experiment.
+        Defaults to 100.
+    """
+
+    _experiment_name: str = PrivateAttr("resonator_spectroscopy_by_power")
+
+    qubit: int
+    frequencies: list[int] | LinspaceIterable | RangeIterable | CWSIterable | HypIterable | None = (
+        None
+    )
+    powers: list[float] | None = None
+    duration_ns: int = DEFAULT_DURATION_NS
+    recycle_delay_ns: int = DEFAULT_RECYCLE_DELAY_NS
+    shot_count: int = DEFAULT_SHOT_COUNT

boulderopalscaleupsdk/grpc_interceptors/__init__.py

@@ -0,0 +1,16 @@
+# 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 .auth import AuthInterceptor
+
+__all__ = ["AuthInterceptor"]

boulderopalscaleupsdk/grpc_interceptors/auth.py

@@ -0,0 +1,101 @@
+# 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 inspect
+
+import grpc
+import grpc.aio
+from qctrlclient import ApiKeyAuth
+
+
+class AuthInterceptor(
+    grpc.UnaryUnaryClientInterceptor,
+    grpc.UnaryStreamClientInterceptor,
+    grpc.StreamUnaryClientInterceptor,
+    grpc.StreamStreamClientInterceptor,
+    grpc.aio.UnaryUnaryClientInterceptor,
+    grpc.aio.UnaryStreamClientInterceptor,
+    grpc.aio.StreamUnaryClientInterceptor,
+    grpc.aio.StreamStreamClientInterceptor,
+):
+    def __init__(self, auth: ApiKeyAuth):
+        self.auth = auth
+
+    def _add_auth_metadata(self, client_call_details):
+        token = self.auth.access_token
+
+        # Add Authorization header to metadata
+        metadata = client_call_details.metadata if client_call_details.metadata else []
+        metadata = [*metadata, ("authorization", f"Bearer {token}")]
+
+        return client_call_details._replace(metadata=metadata)
+
+    async def _async_intercept(self, continuation, client_call_details, request):
+        new_details = self._add_auth_metadata(client_call_details)
+        return await continuation(new_details, request)
+
+    def _sync_intercept(self, continuation, client_call_details, request):
+        new_details = self._add_auth_metadata(client_call_details)
+        return continuation(new_details, request)
+
+    def intercept_unary_unary(self, continuation, client_call_details, request):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_intercept(continuation, client_call_details, request)
+        return self._sync_intercept(continuation, client_call_details, request)
+
+    async def intercept_unary_unary_async(
+        self,
+        continuation,
+        client_call_details,
+        request,
+    ):
+        return await self._async_intercept(continuation, client_call_details, request)
+
+    def intercept_unary_stream(self, continuation, client_call_details, request):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_intercept(continuation, client_call_details, request)
+        return self._sync_intercept(continuation, client_call_details, request)
+
+    async def intercept_unary_stream_async(
+        self,
+        continuation,
+        client_call_details,
+        request,
+    ):
+        return await self._async_intercept(continuation, client_call_details, request)
+
+    def intercept_stream_unary(self, continuation, client_call_details, request_iterator):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_intercept(continuation, client_call_details, request_iterator)
+        return self._sync_intercept(continuation, client_call_details, request_iterator)
+
+    async def intercept_stream_unary_async(
+        self,
+        continuation,
+        client_call_details,
+        request,
+    ):
+        return await self._async_intercept(continuation, client_call_details, request)
+
+    def intercept_stream_stream(self, continuation, client_call_details, request_iterator):  # type: ignore[override]
+        if inspect.iscoroutinefunction(continuation):
+            return self._async_intercept(continuation, client_call_details, request_iterator)
+        return self._sync_intercept(continuation, client_call_details, request_iterator)
+
+    async def intercept_stream_stream_async(
+        self,
+        continuation,
+        client_call_details,
+        request,
+    ):
+        return await self._async_intercept(continuation, client_call_details, request)

boulderopalscaleupsdk/plotting/__init__.py

@@ -0,0 +1,24 @@
+# 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.
+
+"""Plotting library."""
+
+__all__ = [
+    "Marker",
+    "Plot",
+    "PlotData1D",
+    "PlotData2D",
+    "VLine",
+]
+
+from .dtypes import Marker, Plot, PlotData1D, PlotData2D, VLine