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

boulder_opal_scale_up_sdk-1.0.0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.3
+Name: boulder-opal-scale-up-sdk
+Version: 1.0.0
+Summary: Q-CTRL Boulder Opal Scale Up Python SDK
+License: Apache-2.0
+Keywords: black opal,boulder opal,fire opal,nisq,open controls,q control,q ctrl,q-control,q-ctrl,qcontrol,qctrl,quantum,quantum algorithms,quantum circuits,quantum coding,quantum coding software,quantum computing,quantum control,quantum control software,quantum control theory,quantum engineering,quantum error correction,quantum firmware,quantum fundamentals,quantum sensing,qubit,qudit
+Author: Q-CTRL
+Author-email: support@q-ctrl.com
+Maintainer: Q-CTRL
+Maintainer-email: support@q-ctrl.com
+Requires-Python: >=3.10,<3.13
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Distributed Computing
+Requires-Dist: async-timeout (>=4.0.3,<5.0.0) ; python_version < "3.11"
+Requires-Dist: attrs (>=25.1.0,<26.0.0)
+Requires-Dist: googleapis-common-protos (>=1.69.2,<2.0.0)
+Requires-Dist: qctrl-client (>=10.1.0,<11.0.0)
+Project-URL: Facebook, https://www.facebook.com/qctrl
+Project-URL: GitHub, https://github.com/qctrl
+Project-URL: Homepage, https://q-ctrl.com
+Project-URL: LinkedIn, https://www.linkedin.com/company/q-ctrl/
+Project-URL: X, https://x.com/qctrlHQ
+Project-URL: YouTube, https://www.youtube.com/qctrl

boulder_opal_scale_up_sdk-1.0.0.dist-info/RECORD

@@ -0,0 +1,50 @@
+boulderopalscaleupsdk/__init__.py,sha256=nD3YDqPiE52mmuUrIlDUrYSyljpMsDJvc5HsubBUSs4,592
+boulderopalscaleupsdk/agent/__init__.py,sha256=aFkAtHJDOdXA126JklxYz0ix1k4lCcLLS9DQp8zUKMk,1092
+boulderopalscaleupsdk/agent/worker.py,sha256=qoGmYBqrDTiifer2W_mFz8sR5cYcUJ5-oTvALPtvCVo,7640
+boulderopalscaleupsdk/common/__init__.py,sha256=vLaJ1FP36xV5eX6VD7nShqxVBm3UzsBMIK1pmSiTIag,550
+boulderopalscaleupsdk/common/dtypes.py,sha256=LGA6i1AioWS2yvtXnlbrgc2-iJLVY0RkAHzTxOUF6uY,11219
+boulderopalscaleupsdk/common/typeclasses.py,sha256=FZHyTcuCQH5niqFPZmIyoO2zN6mA661h8kyvDcYFryg,3033
+boulderopalscaleupsdk/device/__init__.py,sha256=47Esmn8cdjVFOIHCeI9mEYYKwqM_K_sESFimj_D18iA,710
+boulderopalscaleupsdk/device/common.py,sha256=ZLXpmORKQYntX7DeKZ8pd49Ju1jzidR2q2EeN3TNwTI,1909
+boulderopalscaleupsdk/device/config_loader.py,sha256=AvMNH4J2SpRGdtyWglJXNHJestGHFQdAM8DmUh_TotQ,3300
+boulderopalscaleupsdk/device/controller/__init__.py,sha256=gkjhvarEIE7cLnwxgl2vuKG6ddpJtgJCr2E7T_yRd5s,935
+boulderopalscaleupsdk/device/controller/base.py,sha256=BbQN26ehLIHgLqqwZpn7QhDzMxogQz0gXH5yK0J_cb0,653
+boulderopalscaleupsdk/device/controller/qblox.py,sha256=pzR1oS4Ycxs8VowJhMVnbEWS_31u8bX-6yeHwL83VqM,21725
+boulderopalscaleupsdk/device/controller/quantum_machines.py,sha256=kf9cvuig37qCfrk_82UsIR7V09wskAE9fYNb68DBZcU,5014
+boulderopalscaleupsdk/device/device.py,sha256=ze_27Q97Kp2YxW9qiqXMnax02KZgcOjmekJpOHHquSA,1118
+boulderopalscaleupsdk/device/processor/__init__.py,sha256=uVmeVHunBNLeQj5YjQTaR0Gf2zoXcSjtEv2t-zD-zxs,919
+boulderopalscaleupsdk/device/processor/common.py,sha256=hU2g0UaXZhmycCChMazDLSYYCnqO0RsApFd5CmhXS0g,5397
+boulderopalscaleupsdk/device/processor/superconducting_processor.py,sha256=J5fUZfn2Q-dI8qbgO_3gm01HaGVg3E1U50ha0PbsczU,10297
+boulderopalscaleupsdk/experiments/__init__.py,sha256=Np_80a-oOWoGBA1BO6od8yUoxz7WP-9CmPpRGzbTm50,1297
+boulderopalscaleupsdk/experiments/common.py,sha256=nxcXx0XJbsGQx7t899wXbxCOyJZwFTMl4cvzjosyAJ4,2381
+boulderopalscaleupsdk/experiments/power_rabi.py,sha256=k96FAtF0jGjzd3x2orsQZt2T9IymKAx5pX-rgMVAwPE,2048
+boulderopalscaleupsdk/experiments/ramsey.py,sha256=DD0Y3aRM_iVXKFQSDbCfPoZ-uo8yEw4G-H7bh5MltbE,1747
+boulderopalscaleupsdk/experiments/resonator_spectroscopy.py,sha256=CC8kD-Ph5RlUzVTNdtzTYirrYyBi1whq5Gj5ZZO79j4,2177
+boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_bias.py,sha256=9NEOCss1J0X8FXRxFlb6J0s0aQh-zq5v8tPPX7SlDJE,2736
+boulderopalscaleupsdk/experiments/resonator_spectroscopy_by_power.py,sha256=OHbN9nKzmJmIHU4S5MdmELjLDu0nTEgNksUgnEUzNpo,2211
+boulderopalscaleupsdk/grpc_interceptors/__init__.py,sha256=PkdOlllLbRWycofvGCCxDY60Ydp_U0QM5l4u3Fsnno4,616
+boulderopalscaleupsdk/grpc_interceptors/auth.py,sha256=E8x8Q_s2y2ODNEU1hYPUEvkXP1qF_BOdWJh5L7_85TU,4066
+boulderopalscaleupsdk/plotting/__init__.py,sha256=BnEBs59gMIjHHtmowah8BuUTTfHAakqlmYdbzYSvcyg,730
+boulderopalscaleupsdk/plotting/dtypes.py,sha256=uEbvLiTUXgXHbIsaLw_qQy8iPX3QXdIZaI-TRFPRE8w,7098
+boulderopalscaleupsdk/protobuf/v1/agent_pb2.py,sha256=T8s1pJWsCkNgUwt4cUHMjf5j6YvyCcsFrLPKW5pJdpA,5304
+boulderopalscaleupsdk/protobuf/v1/agent_pb2.pyi,sha256=hFbkqtvhDi07sKaml-oYP7UTmlOuuqt3xXas8U_9AKA,2309
+boulderopalscaleupsdk/protobuf/v1/agent_pb2_grpc.py,sha256=UegXJdsZ0eEKgAzw-bIKf9CH4tdN6bo0Qx4ekd7t6UA,6914
+boulderopalscaleupsdk/protobuf/v1/device_pb2.py,sha256=Upx7_CwiUvN7xH18kx8A5HtVoC4zOsTizah8ytnlN1s,8603
+boulderopalscaleupsdk/protobuf/v1/device_pb2.pyi,sha256=8WiyZW8I8Z6SOgBbRLlcICR2gWzD_d5n3xju4GWq26U,4880
+boulderopalscaleupsdk/protobuf/v1/device_pb2_grpc.py,sha256=WLesWpFrqs6woRYOYZC1dWmJ2Nl38DvBxQ1ob6n-gAA,13747
+boulderopalscaleupsdk/protobuf/v1/task_pb2.py,sha256=7NWFFBEPij8B9dvexRia3B_T9-oOCDwayASCglvBtO4,7086
+boulderopalscaleupsdk/protobuf/v1/task_pb2.pyi,sha256=QWciGKFD1AcaAhqgym0ZwNtIlNT85HhOTBdivEC6QJE,5952
+boulderopalscaleupsdk/protobuf/v1/task_pb2_grpc.py,sha256=yP2FZ148RmSYFHivatCXuM13oRBDA5wBwmvhZQNBTXQ,5826
+boulderopalscaleupsdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+boulderopalscaleupsdk/routines/__init__.py,sha256=cowyGcDR2ln2nDAguw6JmilSRxwFhGis2Kg0plT82r8,154
+boulderopalscaleupsdk/routines/common.py,sha256=Lav4eH4GJyRJXBZwmhA3b34UTgck5x4URex3SBSctwM,224
+boulderopalscaleupsdk/routines/resonator_mapping.py,sha256=nbbnAaImH4Bpjw67PSdlEX8SY7_2-KRoVHk1NQCDUr8,284
+boulderopalscaleupsdk/third_party/__init__.py,sha256=b9T2IVfz9bMenSsLQuaf4A14ySinjNnSGx68hLsFHZE,596
+boulderopalscaleupsdk/third_party/quantum_machines/__init__.py,sha256=oYtqq0Iw2tGxnXZ2kkUmVhNplRD0StlP-jw168sH3BU,1565
+boulderopalscaleupsdk/third_party/quantum_machines/config.py,sha256=eJFs1MGaThIC7AR-iz8SDCEZssf7io_cvn0wUjL8Qrk,19912
+boulderopalscaleupsdk/third_party/quantum_machines/constants.py,sha256=5PpAi6MZ53yEinBHerY2ssi30BR37JnLBWL21irpZ8Y,870
+boulderopalscaleupsdk/utils/__init__.py,sha256=vLaJ1FP36xV5eX6VD7nShqxVBm3UzsBMIK1pmSiTIag,550
+boulderopalscaleupsdk/utils/serial_utils.py,sha256=SzvY-WFD0b8IGSh6PTv7F9y1W2IPPYmj8pY3AsX-xlM,2062
+boulder_opal_scale_up_sdk-1.0.0.dist-info/METADATA,sha256=hsUMkexqKKXYkipWU07rqqOSUL-wLBB8mUrw9oqb7d8,2025
+boulder_opal_scale_up_sdk-1.0.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+boulder_opal_scale_up_sdk-1.0.0.dist-info/RECORD,,

boulder_opal_scale_up_sdk-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.0.1
+Root-Is-Purelib: true
+Tag: py3-none-any

boulderopalscaleupsdk/__init__.py

@@ -0,0 +1,14 @@
+# 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.
+
+"""Boulder Opal Scale up SDK package."""

boulderopalscaleupsdk/agent/__init__.py

@@ -0,0 +1,29 @@
+# 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.
+
+"""Agent module.
+
+Agents are responsible for communicating with Q-CTRL APIs to determine a set of tasks to
+perform (generally, QPU tasks such as execution of quantum circuits / configuration).
+Importantly, to both simplify and ensure the security of the QPU adjacent host that the
+agent will run on, the agent must initiate all communications (as opposed to opening a
+port on the host).
+"""
+
+__all__ = [
+    "Agent",
+    "AgentSettings",
+    "TaskHandler",
+]
+
+from boulderopalscaleupsdk.agent.worker import Agent, AgentSettings, TaskHandler

boulderopalscaleupsdk/agent/worker.py

@@ -0,0 +1,244 @@
+# 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.
+
+"""Base agent module.
+
+Contains logic for agent worker.
+"""
+
+import logging
+from abc import abstractmethod
+from typing import Protocol
+
+from google.protobuf import any_pb2
+from google.protobuf.message import Message
+from google.protobuf.struct_pb2 import Struct
+from grpc import aio as grpc
+from grpc import ssl_channel_credentials
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from boulderopalscaleupsdk.protobuf.v1 import agent_pb2, task_pb2, task_pb2_grpc
+
+LOG = logging.getLogger(__name__)
+
+
+class AgentSettings(BaseSettings):
+    """Configuration for the Agent."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="QCTRL_SCALE_UP_",
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    agent_id: str
+    remote_url: str
+
+
+class TaskHandler(Protocol):
+    @abstractmethod
+    async def handle(
+        self,
+        request: agent_pb2.RunQuaProgramRequest
+        | agent_pb2.RunQuantumMachinesMixerCalibrationRequest
+        | agent_pb2.DisplayResultsRequest,
+    ) -> (
+        agent_pb2.RunQuaProgramResponse
+        | agent_pb2.RunQuantumMachinesMixerCalibrationResponse
+        | agent_pb2.DisplayResultsResponse
+        | task_pb2.TaskErrorDetail
+    ): ...
+
+    async def run(
+        self,
+        task: task_pb2.Task,
+    ) -> any_pb2.Any | task_pb2.TaskErrorDetail:
+        request = (
+            _as_run_qua_program_request(
+                task.data,
+            )
+            or _as_run_qua_calibration_request(task.data)
+            or _as_display_results_request(task.data)
+        )
+        match request:
+            case (
+                agent_pb2.RunQuaProgramRequest()
+                | agent_pb2.RunQuantumMachinesMixerCalibrationRequest()
+                | agent_pb2.DisplayResultsRequest()
+            ):
+                return _as_any_message(await self.handle(request))
+            case None:
+                return task_pb2.TaskErrorDetail(
+                    code=task_pb2.TaskError.TASK_ERROR_NOT_IMPLEMENTED,
+                    detail="Unknown or unrecognized request.",
+                )
+
+
+def _as_any_message(message: Message) -> any_pb2.Any:
+    msg = any_pb2.Any()
+    msg.Pack(message)  # type: ignore[reportUnknownMemberType]
+    return msg
+
+
+def _as_run_qua_program_request(
+    task_result: any_pb2.Any,
+) -> agent_pb2.RunQuaProgramRequest | None:
+    request = agent_pb2.RunQuaProgramRequest()
+    unpacked: bool = task_result.Unpack(request)  # type: ignore[reportUnknownMemberType]
+    if not unpacked:
+        return None
+
+    return request
+
+
+def _as_run_qua_calibration_request(
+    task_result: any_pb2.Any,
+) -> agent_pb2.RunQuantumMachinesMixerCalibrationRequest | None:
+    request = agent_pb2.RunQuantumMachinesMixerCalibrationRequest()
+    unpacked: bool = task_result.Unpack(request)  # type: ignore[reportUnknownMemberType]
+    if not unpacked:
+        return None
+
+    return request
+
+
+def _as_display_results_request(
+    task_result: any_pb2.Any,
+) -> agent_pb2.DisplayResultsRequest | None:
+    request = agent_pb2.DisplayResultsRequest()
+    unpacked: bool = task_result.Unpack(request)  # type: ignore[reportUnknownMemberType]
+    if not unpacked:
+        return None
+
+    return request
+
+
+class Agent:
+    """Agent implementation."""
+
+    def __init__(
+        self,
+        agent_settings: AgentSettings,
+        handler: TaskHandler,
+        grpc_interceptors: list[grpc.ClientInterceptor] | None = None,
+    ) -> None:
+        self._settings = agent_settings
+        self._handler = handler
+        self._channel: grpc.Channel | None = self._create_channel(
+            agent_settings.remote_url,
+            grpc_interceptors,
+        )
+        self._agent_manager = task_pb2_grpc.AgentManagerServiceStub(self._channel)
+        self._state: task_pb2.AgentState = task_pb2.AGENT_STATE_ACTIVE_IDLE
+
+    @property
+    def agent_id(self) -> str:
+        """The agent identifier."""
+        return self._settings.agent_id
+
+    def _create_channel(
+        self,
+        url: str,
+        interceptors: list[grpc.ClientInterceptor] | None = None,
+    ) -> grpc.Channel:
+        """
+        Create a gRPC channel.
+        """
+        host = url.split(":")[0]
+        if host in ["localhost", "127.0.0.1", "0.0.0.0", "::"]:
+            channel = grpc.insecure_channel(url)
+        else:
+            channel = grpc.secure_channel(
+                url,
+                credentials=ssl_channel_credentials(),
+                interceptors=interceptors,
+            )
+        return channel
+
+    async def start_session(
+        self,
+        app: str,
+        device_name: str,
+        routine: str,
+        data: Struct | None,
+    ) -> str:
+        if not self._channel:
+            raise RuntimeError("Agent is shutdown.")
+        _data = any_pb2.Any()
+        if data:
+            _data.Pack(data)
+
+        response: task_pb2.AgentTasksResponse = await self._agent_manager.StartSession(
+            task_pb2.StartSessionRequest(
+                agent_id=self.agent_id,
+                app_name=app,
+                device_name=device_name,
+                routine_name=routine,
+                data=_data,
+            ),
+        )
+        self._state = response.target_state
+        await self._resume(response)
+        await self.shutdown()
+        return response.session_id
+
+    async def _resume(self, response: task_pb2.AgentTasksResponse) -> None:
+        tasks = response.tasks
+        while self._state not in [
+            task_pb2.AGENT_STATE_SHUTDOWN_MANAGER_INITIATED,
+            task_pb2.AGENT_STATE_SHUTDOWN_FAULT,
+            task_pb2.AGENT_STATE_SHUTDOWN_CLIENT_INITIATED,
+        ]:
+            task_results: list[task_pb2.TaskResult] = []
+            for task in tasks:
+                err: task_pb2.TaskErrorDetail | None = None
+                result: any_pb2.Any | None = None
+
+                match await self._handler.run(task):
+                    case task_pb2.TaskErrorDetail() as err:
+                        pass
+                    case any_pb2.Any() as result:
+                        pass
+
+                task_results.append(
+                    task_pb2.TaskResult(
+                        task_id=task.task_id,
+                        session_id=task.session_id,
+                        result=result,
+                        error=err,
+                    ),
+                )
+
+            _resp: task_pb2.AgentTasksResponse = await self._agent_manager.UpdateSession(
+                task_pb2.UpdateSessionRequest(
+                    session_id=response.session_id,
+                    current_state=self._state,
+                    results=task_results,
+                    task_in_progress=[],
+                ),
+            )
+
+            tasks = _resp.tasks
+            self._state = _resp.target_state
+
+    async def shutdown(
+        self,
+        timeout: float | None = None,
+        _: BaseException | None = None,
+    ) -> None:
+        """Shutdown the agent."""
+        if self._channel:
+            await self._channel.close(grace=timeout)
+            self._channel = None

boulderopalscaleupsdk/common/__init__.py

@@ -0,0 +1,12 @@
+# 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.