iqm-station-control-client 8.0.0__py3-none-any.whl → 9.0.0__py3-none-any.whl

iqm/station_control/client/utils.py

@@ -1,20 +1,27 @@
-#  ********************************************************************************
-#  Copyright (c) 2021-2024 IQM Finland Oy.
-#  All rights reserved. Confidential and proprietary.
+# Copyright 2025 IQM
 #
-#  Distribution or reproduction of any information contained herein
-#  is prohibited without IQM Finland Oy’s prior written permission.
-#  ********************************************************************************
-
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 """Utility functions for IQM Station Control Client."""
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable
 
+import requests
 from tqdm.auto import tqdm
 
-from exa.common.data.value import ObservationValue
+from iqm.station_control.client.iqm_server.iqm_server_client import IqmServerClient
+from iqm.station_control.client.station_control import StationControlClient
 from iqm.station_control.interface.models import Statuses
-from iqm.station_control.interface.models.observation import ObservationBase
+from iqm.station_control.interface.station_control import StationControlInterface
 
 
 def get_progress_bar_callback() -> Callable[[Statuses], None]:
@@ -31,14 +38,34 @@ def get_progress_bar_callback() -> Callable[[Statuses], None]:
     return _create_and_update_progress_bars
 
 
-def calset_from_observations(calset_observations: Iterable[ObservationBase]) -> dict[str, ObservationValue]:
-    """Create a calibration set from the given observations.
+def init_station_control(
+    root_url: str, get_token_callback: Callable[[], str] | None = None, **kwargs
+) -> StationControlInterface:
+    """Initialize a new station control instance connected to the given remote.
 
-    Args:
-        calset_observations: observations that form a calibration set
+    Client implementation is selected automatically based on the remote station: if the remote station
+    is running the IQM Server software stack, then the IQM Server client implementation (with a limited
+    feature set) is chosen. If the remote station is running the SC software stack, then the Station
+    Control client implementation (with the full feature set) is chosen.
 
-    Returns:
-        calibration set
+    Args:
+        root_url: Remote station control service URL. For IQM Server remotes, this is the "Quantum Computer URL"
+            value from the web dashboard.
+        get_token_callback: A callback function that returns a token (str) which will be passed in Authorization
+            header in all requests.
 
     """
-    return {obs.dut_field: obs.value for obs in calset_observations}
+    try:
+        headers = {"Authorization": get_token_callback()} if get_token_callback else {}
+        response = requests.get(f"{root_url}/about", headers=headers)
+        response.raise_for_status()
+        about = response.json()
+        if isinstance(about, dict) and about.get("iqm_server") is True:
+            # If about information has iqm_server flag, it means that we're communicating
+            # with IQM server instead of direct Station Control service, hence we need to
+            # use the specialized client
+            return IqmServerClient(root_url, get_token_callback=get_token_callback, **kwargs)
+        # Using direct station control by default
+        return StationControlClient(root_url=root_url, get_token_callback=get_token_callback, **kwargs)
+    except Exception as e:
+        raise RuntimeError("Failed to initialize the client.") from e

iqm/station_control/interface/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/list_with_meta.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,8 +14,17 @@
 """Station control interface models."""
 
 from iqm.station_control.interface.models.dut import DutData, DutFieldData
+from iqm.station_control.interface.models.dynamic_quantum_architecture import (
+    DynamicQuantumArchitecture,
+    GateImplementationInfo,
+    GateInfo,
+    Locus,
+)
 from iqm.station_control.interface.models.jobs import (
+    JobData,
     JobExecutorStatus,
+    JobResult,
+    TimelineEntry,
 )
 from iqm.station_control.interface.models.observation import (
     ObservationData,
@@ -27,6 +36,8 @@ from iqm.station_control.interface.models.observation_set import (
     ObservationSetData,
     ObservationSetDefinition,
     ObservationSetUpdate,
+    ObservationSetWithObservations,
+    QualityMetrics,
 )
 from iqm.station_control.interface.models.run import RunData, RunDefinition, RunLite
 from iqm.station_control.interface.models.sequence import (
@@ -35,6 +46,7 @@ from iqm.station_control.interface.models.sequence import (
     SequenceResultData,
     SequenceResultDefinition,
 )
+from iqm.station_control.interface.models.static_quantum_architecture import StaticQuantumArchitecture
 from iqm.station_control.interface.models.sweep import SweepData, SweepDefinition
 from iqm.station_control.interface.models.type_aliases import (
     DutType,

iqm/station_control/interface/models/dut.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/dynamic_quantum_architecture.py

@@ -0,0 +1,98 @@
+# Copyright 2025 IQM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Dynamic quantum architecture (DQA) related interface models."""
+
+from uuid import UUID
+
+from pydantic import Field, StrictStr
+
+from iqm.station_control.interface.pydantic_base import PydanticBase
+
+Locus = tuple[StrictStr, ...]
+"""Names of the QPU components (typically qubits) a quantum operation instance is acting on, e.g. `("QB1", "QB2")`."""
+
+
+class GateImplementationInfo(PydanticBase):
+    """Information about an implementation of a quantum gate/operation."""
+
+    loci: tuple[Locus, ...] = Field(
+        examples=[(("COMP_R", "QB1"), ("COMP_R", "QB2"))],
+    )
+    """Loci for which this gate implementation has been calibrated."""
+
+
+class GateInfo(PydanticBase):
+    """Information about a quantum gate/operation."""
+
+    implementations: dict[str, GateImplementationInfo] = Field(
+        examples=[
+            {
+                "tgss": GateImplementationInfo(loci=(("COMP_R", "QB1"), ("COMP_R", "QB2"))),
+                "crf": GateImplementationInfo(loci=(("COMP_R", "QB1"), ("COMP_R", "QB2"))),
+            }
+        ],
+    )
+    """Mapping of available implementation names to information about the implementations."""
+
+    default_implementation: str = Field(
+        examples=["tgss"],
+    )
+    """Default implementation for the gate.
+    
+    Used unless overridden by :attr:`override_default_implementation`,
+    or unless the user requests a specific implementation for a particular gate in the circuit using
+    :attr:`iqm.cocos.app.api.request_models.Instruction.implementation`."""
+
+    override_default_implementation: dict[Locus, str] = Field(
+        examples=[{("COMP_R", "QB2"): "crf"}],
+    )
+    """Mapping of loci to implementation names that override ``default_implementation`` for those loci."""
+
+
+class DynamicQuantumArchitecture(PydanticBase):
+    """The dynamic quantum architecture (DQA).
+
+    Describes gates/operations for which calibration data exists in the calibration set.
+    """
+
+    calibration_set_id: UUID = Field(
+        examples=["cd4dd889-b88b-4370-ba01-eb8262ad9c53"],
+    )
+    """ID of the calibration set from which this DQA was generated."""
+
+    qubits: list[str] = Field(
+        examples=[["QB1", "QB2"]],
+    )
+    """Qubits that appear in at least one gate locus in the calibration set."""
+
+    computational_resonators: list[str] = Field(
+        examples=[["COMP_R"]],
+    )
+    """Computational resonators that appear in at least one gate locus in the calibration set."""
+
+    gates: dict[str, GateInfo] = Field(
+        examples=[
+            {
+                "cz": GateInfo(
+                    implementations={
+                        "tgss": GateImplementationInfo(loci=(("COMP_R", "QB1"), ("COMP_R", "QB2"))),
+                        "crf": GateImplementationInfo(loci=(("COMP_R", "QB1"), ("COMP_R", "QB2"))),
+                    },
+                    default_implementation="tgss",
+                    override_default_implementation={("COMP_R", "QB2"): "crf"},
+                )
+            }
+        ],
+    )
+    """Mapping of gate names to information about the gates."""

iqm/station_control/interface/models/jobs.py

@@ -59,7 +59,7 @@ class JobData(PydanticBase):
 class JobExecutorStatus(Enum):
     """Enumeration of different states a job can be in. The ordering of these statuses is important,
     and execution logic relies on it. Thus, if a new status is added, ensure that it is slotted
-    in at the appropriate place. See the __lt__ implementation for further details.
+    in at the appropriate place. See the :meth:`__lt__` implementation for further details.
     """
 
     # Received by the server
@@ -111,9 +111,33 @@ class JobExecutorStatus(Enum):
     def __lt__(self, other):
         """Enable comparison according to definition order.
 
-        Examples:
-            >>> JobExecutorStatus.VALIDATION_ENDED < JobExecutorStatus.COMPILATION_ENDED
+        :meta public:
+
+        .. doctest::
+
+            >>> JobExecutorStatus.RECEIVED < JobExecutorStatus.VALIDATION_STARTED
             True
+            >>> sorted(list(JobExecutorStatus.__members__))
+            [
+                JobExecutorStatus.RECEIVED,
+                JobExecutorStatus.VALIDATION_STARTED,
+                JobExecutorStatus.VALIDATION_ENDED,
+                JobExecutorStatus.FETCH_CALIBRATION_STARTED,
+                JobExecutorStatus.FETCH_CALIBRATION_ENDED,
+                JobExecutorStatus.COMPILATION_STARTED,
+                JobExecutorStatus.COMPILATION_ENDED,
+                JobExecutorStatus.SAVE_SWEEP_METADATA_STARTED,
+                JobExecutorStatus.SAVE_SWEEP_METADATA_ENDED,
+                JobExecutorStatus.PENDING_EXECUTION,
+                JobExecutorStatus.EXECUTION_STARTED,
+                JobExecutorStatus.EXECUTION_ENDED,
+                JobExecutorStatus.POST_PROCESSING_PENDING,
+                JobExecutorStatus.POST_PROCESSING_STARTED,
+                JobExecutorStatus.POST_PROCESSING_ENDED,
+                JobExecutorStatus.READY,
+                JobExecutorStatus.FAILED,
+                JobExecutorStatus.ABORTED,
+            ]
 
         """
         if isinstance(other, str):

iqm/station_control/interface/models/observation.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/observation_set.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ import uuid
 
 from pydantic import ConfigDict, Field
 
+from iqm.station_control.interface.models.observation import ObservationLite
 from iqm.station_control.interface.models.type_aliases import ObservationSetType
 from iqm.station_control.interface.pydantic_base import PydanticBase
 
@@ -74,3 +75,16 @@ class ObservationSetUpdate(PydanticBase):
     """
     invalid: bool
     """Flag indicating if the object is invalid. Automated systems must not use invalid objects."""
+
+
+class ObservationSetWithObservations(ObservationSetData):
+    """The content of the observation set stored in the database, with a list of observations."""
+
+    observations: list[ObservationLite]
+    """Observations belonging to the observation set."""
+
+
+class QualityMetrics(ObservationSetWithObservations):
+    """The content of the quality metric set stored in the database, with a list of observations and calibration set."""
+
+    calibration_set: ObservationSetData

iqm/station_control/interface/models/run.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/sequence.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/static_quantum_architecture.py

@@ -0,0 +1,40 @@
+# Copyright 2025 IQM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Static quantum architecture (SQA) related interface models."""
+
+from pydantic import Field
+
+from iqm.station_control.interface.pydantic_base import PydanticBase
+
+
+class StaticQuantumArchitecture(PydanticBase):
+    """The static quantum architecture (SQA) provides information about the QPU.
+
+    For example, the names of its components and the connections between them.
+    """
+
+    qubits: list[str] = Field(
+        examples=[["QB1", "QB2"]],
+    )
+    """Names of the qubits on the QPU, sorted."""
+
+    computational_resonators: list[str] = Field(
+        examples=[["CR1"]],
+    )
+    """Names of the computational resonators on the QPU, sorted."""
+
+    connectivity: list[tuple[str, ...]] = Field(
+        examples=[[("QB1", "QB2"), ("QB1", "CR1")]],
+    )
+    """Components (qubits and computational resonators) connected by a coupler on the QPU, sorted."""

iqm/station_control/interface/models/sweep.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

iqm/station_control/interface/models/type_aliases.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,9 +14,15 @@
 """Type hint aliases used in the station control interface."""
 
 from typing import Literal
+from uuid import UUID
 
 import numpy as np
 
+# Allow using string UUIDs in API calls directly for convenience.
+# StrUUID works if UUIDs will be serialized to strings by the client anyway,
+# and then deserialized back to UUID on the server side.
+StrUUID = str | UUID
+
 DutType = Literal["chip", "twpa"]
 GetObservationsMode = Literal["all_latest", "tags_and", "tags_or", "sequence"]
 ObservationSetType = Literal["calibration-set", "characterization-set", "generic-set", "quality-metric-set"]

iqm/station_control/interface/pydantic_base.py

@@ -1,4 +1,4 @@
-# Copyright 2024 IQM
+# Copyright 2025 IQM
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.