iqm-station-control-client 9.10.0__tar.gz → 9.12.0__tar.gz

{iqm_station_control_client-9.10.0 → iqm_station_control_client-9.12.0}/CHANGELOG.rst

@@ -2,6 +2,27 @@
 Changelog
 =========
 
+Version 9.12.0 (2025-08-08)
+===========================
+
+Features
+--------
+
+- QON subclasses are now pydantic dataclasses.
+- Modifies typing of QON subclasses to validate some of the inputs using regex.
+- Add ``QONMetricRegistry`` to register parsing of QON metric subclasses for different methods.
+- Refactor ``QONMetric`` into a base class, with new subclasses ``QONGateMetric`` and ``QONSystemMetric`` to handle gate-related and gate-unrelated metric generation.
+- Add more strict regex validation on QON subclasses.
+- Update tests to reflect the new structure and validation rules.
+
+Version 9.11.0 (2025-08-07)
+===========================
+
+Features
+--------
+
+- Fix naming conventions related to Pulse level access as ``Pulla``.
+
 Version 9.10.0 (2025-08-07)
 ===========================
 

{iqm_station_control_client-9.10.0/src/iqm_station_control_client.egg-info → iqm_station_control_client-9.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-station-control-client
-Version: 9.10.0
+Version: 9.12.0
 Summary: Python client for communicating with Station Control Service
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

{iqm_station_control_client-9.10.0 → iqm_station_control_client-9.12.0}/src/iqm/station_control/client/qon.py

@@ -16,10 +16,12 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
-from dataclasses import dataclass, field
 from enum import StrEnum
 import logging
-from typing import Any, Final, TypeAlias
+from typing import Annotated, Any, Final, TypeAlias
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
 
 from iqm.station_control.interface.models.observation import ObservationBase
 
@@ -35,6 +37,9 @@ _SUFFIX_SEPARATOR: Final[str] = ":"
 LOCUS_SEPARATOR: Final[str] = "__"
 """Separates QPU components in a locus string."""
 
+_PATTERN: Final[str] = r"^[A-Za-z_][A-Za-z0-9_]*$"
+"""Regex that most observation name parts must follow."""
+
 Locus: TypeAlias = tuple[str, ...]
 """Sequence of QPU component physical names a quantum operation acts on. The order may matter."""
 
@@ -77,7 +82,7 @@ def _parse_suffixes(suffixes: Iterable[str]) -> Suffixes:
     return dict(sorted(suffix_dict.items()))
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, config={"extra": "forbid"})  # do not allow unknown keyword args
 class QON:
     """Qualified observation name.
 
@@ -103,7 +108,7 @@ class QON:
         raise NotImplementedError
 
     @classmethod
-    def from_str(cls, name: str) -> "QON":
+    def from_str(cls, name: str) -> QON:
         """Parse an observation name into a QON object.
 
         Args:
@@ -162,7 +167,7 @@ class QONCharacterization(QON):
         return _FIELD_SEPARATOR.join([self.domain, "model", self.component, self.quantity])
 
     @classmethod
-    def _parse(cls, rest: str) -> "QONCharacterization":
+    def _parse(cls, rest: str) -> QONCharacterization:
         """Parse a characterization observation name."""
         parts = rest.split(_FIELD_SEPARATOR, maxsplit=1)
         if len(parts) < 2:
@@ -175,8 +180,131 @@ class QONCharacterization(QON):
         )
 
 
+class QONMetricRegistry:
+    """Registry for QONMetric subclasses, mapping method names to parser classes.
+
+    Allows extensible registration of new metric parsing strategies for new methods.
+    """
+
+    _registry: dict[str, type[QONMetric]] = {}
+    """Mapping from QONMetric method name to the subclass that handles it."""
+    _inv_registry: dict[type[QONMetric], frozenset[str]] = {}
+    """Mapping from QONMetric subclass to the methods it handles."""
+
+    @classmethod
+    def register(cls, method_names: Iterable[str]):
+        """Decorator for registering a QONMetric subclass as the parser for one or more method names.
+
+        Args:
+            method_names: One or more method names to associate with the subclass.
+
+        Returns:
+            The decorator function.
+
+        """
+
+        def decorator(subclass: type[QONMetric]):
+            for name in method_names:
+                if (owner := cls._registry.get(name)) is not None:
+                    raise ValueError(f"Method {name} already registered to {owner.__name__}")
+                cls._registry[name] = subclass
+            cls._inv_registry[subclass] = frozenset(method_names)
+            return subclass
+
+        return decorator
+
+    @classmethod
+    def get_parser(cls, method_name: str) -> type[QONMetric]:
+        """Retrieve the parser class for a given method name.
+
+        Args:
+            method_name: The method name to look up.
+
+        Returns:
+            The QONMetric subclass registered for the method.
+
+        Raises:
+            UnknownObservationError: ``method_name`` is not registered.
+
+        """
+        try:
+            return cls._registry[method_name]
+        except KeyError:
+            raise UnknownObservationError("Unknown quality metric.")
+
+    @classmethod
+    def registered_methods(cls) -> list[str]:
+        """Get a list of all registered method names.
+
+        Returns:
+            List of registered method names.
+
+        """
+        return list(cls._registry.keys())
+
+
 @dataclass(frozen=True)
 class QONMetric(QON):
+    """Base class for QON representing a gate quality metric.
+
+    Subclasses implement parsing and string representation for specific methods.
+    """
+
+    method: Annotated[str, Field(pattern=_PATTERN)]
+    locus: str
+    """Sequence of names of QPU components on which the gate is applied, or on which the experiment is run."""
+    metric: Annotated[str, Field(pattern=r"^[A-Za-z_0-9][A-Za-z0-9_]*$")]
+    """Measured metric."""
+
+    def __post_init__(self):
+        if self.method not in QONMetricRegistry._inv_registry[self.__class__]:
+            raise UnknownObservationError(
+                f"{self.__class__.__name__} is not registered to handle the method {self.method}"
+            )
+
+    @property
+    def domain(self) -> Domain:
+        """Return the QON domain for metrics."""
+        return Domain.METRIC
+
+    @classmethod
+    def _parse(cls, method: str, method_specific_part: str) -> QONMetric:
+        """Parse a metric observation name using the appropriate registered subclass.
+
+        Args:
+            method: The method name.
+            method_specific_part: The method-specific part of the metric observation name.
+
+        Returns:
+            Parsed metric name.
+
+        Raises:
+            UnknownObservationError: ``method`` is not registered.
+
+        """
+        parser_cls = QONMetricRegistry.get_parser(method)
+        return parser_cls._parse(method, method_specific_part)
+
+
+@QONMetricRegistry.register(
+    [
+        "rb",
+        "irb",
+        "ssro",
+        "restless_ssro",
+        "readout_rb",
+        "qndness",
+        "msmt_qndness",
+        "npopex_echo",
+        "npopex_long",
+        "coherence_cz",
+        "ncz_swap",
+        "entanglement_coherence",
+        "conditional_reset",
+    ]
+)
+@dataclass(frozen=True)
+class QONGateMetric(QONMetric):
     """QON representing a gate quality metric.
 
     Has the form ``metrics.{method}.{method_specific_part}``.
@@ -209,97 +337,107 @@ class QONMetric(QON):
         locus: QB4
         metric: fidelity
         suffixes: {"par": "d2"}
-
-    ``metrics.ghz_state.QB1__QB2.coherence_lower_bound``
-
-        method: ghz_state
-        gate: None
-        implementation: None
-        locus: QB1__QB2
-        metric: coherence_lower_bound
-        suffixes: {}
-
     """
 
-    method: str
-    gate: str | None
+    gate: Annotated[str, Field(pattern=_PATTERN)]
     """Name of the gate/quantum operation."""
-    implementation: str | None
+    implementation: Annotated[str, Field(pattern=_PATTERN)]
     """Name of the gate implementation."""
-    locus: str
-    """Sequence of names of QPU components on which the gate/operation is applied."""
-    metric: str
-    """Measured metric."""
-    suffixes: Suffixes = field(default_factory=dict)
+    suffixes: Suffixes = Field(default_factory=dict)
     """Suffixes defining the metric further (if any)."""
 
-    @property
-    def domain(self) -> Domain:
-        return Domain.METRIC
-
     def __str__(self) -> str:
-        if self.method == "ghz_state":
-            parts = [self.domain, self.method, self.locus, self.metric]
-        else:
-            gate_str = self.gate if self.gate is not None else ""
-            impl_str = self.implementation if self.implementation is not None else ""
-            parts = [self.domain, self.method, gate_str, impl_str, self.locus, self.metric]
+        parts = [self.domain, self.method, self.gate, self.implementation, self.locus, self.metric]
         name = _FIELD_SEPARATOR.join(parts)
-        suffixes = _SUFFIX_SEPARATOR.join(f"{key}={value}" for key, value in self.suffixes.items())
-        if suffixes:
-            return f"{name}:{suffixes}"
+        if self.suffixes:
+            suffix_str = _SUFFIX_SEPARATOR.join(f"{k}={v}" for k, v in sorted(self.suffixes.items()))
+            return f"{name}:{suffix_str}"
         return name
 
     @classmethod
-    def _parse(cls, method: str, method_specific_part: str) -> "QONMetric":
-        """Parse a gate quality metric name.
+    def _parse(cls, method: str, method_specific_part: str) -> QONGateMetric:
+        """Parse a metric observation name that includes a gate and an implementation.
 
         Args:
-            method: Method used to measure the gate metric.
-            method_specific_part: Dot-separated fields specific to ``method``, possibly followed by suffixes.
+            method: The method name.
+            method_specific_part: The method-specific part of the metric observation name.
+
+        Returns:
+            Parsed metric name.
 
         Raises:
-            ValueError: Failed to parse ``name`` because it was syntactically incorrect.
-            UnknownObservationError: Failed to parse ``name`` because it contains unknown elements.
+            ValueError: Observation name is malformed.
 
         """
-        # gate metrics may have suffixes, split them off
-        fragments = method_specific_part.split(_SUFFIX_SEPARATOR)
-        suffixes = _parse_suffixes(fragments[1:])
-
-        # parse the rest of the method specific part
-        fields = fragments[0]
-        if method in ("rb", "irb", "ssro"):
-            # {gate}.{implementation}.{locus_str}.{metric}"
-            parts = fields.split(_FIELD_SEPARATOR, maxsplit=3)
-            if len(parts) < 4:
-                raise ValueError(f"{method} gate quality metric name has less than 6 parts")
-            gate, implementation, locus, metric = parts
-            return cls(
-                method=method,
-                gate=gate,
-                implementation=implementation,
-                locus=locus,
-                metric=metric,
-                suffixes=suffixes,
-            )
+        parts, suffixes = _split_obs_name(method_specific_part, maxsplit=3)
+        if len(parts) < 4:
+            raise ValueError(f"{method} gate quality metric name has less than 6 parts")
+        gate, implementation, locus, metric = parts
+        return cls(
+            method=method,
+            gate=gate,
+            implementation=implementation,
+            locus=locus,
+            metric=metric,
+            suffixes=suffixes,
+        )
 
-        if method == "ghz_state":
-            # {locus_str}.{metric}
-            parts = fields.split(_FIELD_SEPARATOR, maxsplit=1)
-            if len(parts) < 2:
-                raise ValueError(f"{method} gate quality metric name has less than 4 parts")
-            locus, metric = parts
-            return cls(
-                method=method,
-                gate=None,
-                implementation=None,
-                locus=locus,
-                metric=metric,
-                suffixes=suffixes,
-            )
 
-        raise UnknownObservationError("Unknown gate quality metric.")
+@QONMetricRegistry.register(["ghz_state", "coherence_gef", "relaxation_ef", "simultaneous_coherence_gef", "t1_coupled"])
+@dataclass(frozen=True)
+class QONSystemMetric(QONMetric):
+    """QON representing a system quality metric.
+
+    Has the form ``metrics.{method}.{locus}.{metric}``.
+
+    Can parse/represent e.g. the following metrics:
+
+    ``metrics.irb.circuit.random_circuit.QB4.fidelity:par=d2``
+
+        method: irb
+        gate: circuit
+        implementation: random_circuit
+        locus: QB4
+        metric: fidelity
+        suffixes: {"par": "d2"}
+
+    ``metrics.ghz_state.QB1__QB2.coherence_lower_bound``
+
+        method: ghz_state
+        locus: QB1__QB2
+        metric: coherence_lower_bound
+
+    Subclasses implement parsing and string representation for specific methods.
+    """
+
+    def __str__(self) -> str:
+        parts = [self.domain, self.method, self.locus, self.metric]
+        return _FIELD_SEPARATOR.join(parts)
+
+    @classmethod
+    def _parse(cls, method: str, method_specific_part: str) -> QONSystemMetric:
+        """Parse a metric observation name without a gate or an implementation.
+
+        Args:
+            method: The method name.
+            method_specific_part: The method-specific part of the metric observation name.
+
+        Returns:
+            Parsed metric name.
+
+        Raises:
+            ValueError: Observation name is malformed.
+
+        """
+        parts = method_specific_part.split(_FIELD_SEPARATOR, maxsplit=1)
+        if len(parts) < 2:
+            raise ValueError(f"{method} system quality metric name has less than 4 parts")
+        locus, metric = parts
+        return cls(
+            method=method,
+            locus=locus,
+            metric=metric,
+        )
 
 
 @dataclass(frozen=True)
@@ -309,7 +447,7 @@ class QONControllerSetting(QON):
     Has the form ``controllers.{controller}[.{subcontroller}]*.{setting}``.
     """
 
-    controller: str
+    controller: Annotated[str, Field(pattern=_PATTERN)]
     """Name of the controller."""
     rest: str
     """Possible subcontroller names in a dotted structure, ending in the setting name."""
@@ -322,7 +460,7 @@ class QONControllerSetting(QON):
         return _FIELD_SEPARATOR.join([self.domain, self.controller, self.rest])
 
     @classmethod
-    def _parse(cls, controller: str, controller_specific_part: str) -> "QONControllerSetting":
+    def _parse(cls, controller: str, controller_specific_part: str) -> QONControllerSetting:
         """Parse a controller setting observation name."""
         return cls(
             controller=controller,
@@ -337,9 +475,9 @@ class QONGateParam(QON):
     Has the form ``gates.{gate}.{implementation}.{locus_str}.{parameter}``.
     """
 
-    gate: str
+    gate: Annotated[str, Field(pattern=_PATTERN)]
     """Name of the gate/quantum operation."""
-    implementation: str | None
+    implementation: Annotated[str, Field(pattern=_PATTERN)]
     """Name of the gate implementation."""
     locus: str
     """Sequence of names of QPU components on which the gate is applied."""
@@ -351,11 +489,10 @@ class QONGateParam(QON):
         return Domain.GATE_PARAMETER
 
     def __str__(self) -> str:
-        impl_str = self.implementation if self.implementation is not None else ""
-        return _FIELD_SEPARATOR.join([self.domain, self.gate, impl_str, self.locus, self.parameter])
+        return _FIELD_SEPARATOR.join([self.domain, self.gate, self.implementation, self.locus, self.parameter])
 
     @classmethod
-    def _parse(cls, gate: str, rest: str) -> "QONGateParam":
+    def _parse(cls, gate: str, rest: str) -> QONGateParam:
         """Parse a gate parameter observation name."""
         parts = rest.split(_FIELD_SEPARATOR, maxsplit=2)
         if len(parts) < 3:
@@ -369,14 +506,14 @@ class QONGateParam(QON):
         )
 
 
-def _split_obs_name(obs_name: str) -> tuple[list[str], Suffixes]:
+def _split_obs_name(obs_name: str, *, maxsplit: int = -1) -> tuple[list[str], Suffixes]:
     """Split the given observation name into path elements and suffixes."""
     # some observation names may have suffixes, split them off
     fragments = obs_name.split(_SUFFIX_SEPARATOR)
     suffixes = _parse_suffixes(fragments[1:])
 
     # split the path elements
-    path = fragments[0].split(_FIELD_SEPARATOR)
+    path = fragments[0].split(_FIELD_SEPARATOR, maxsplit=maxsplit)
     return path, suffixes
 
 

{iqm_station_control_client-9.10.0 → iqm_station_control_client-9.12.0}/src/iqm/station_control/interface/models/jobs.py

@@ -81,7 +81,7 @@ class JobExecutorStatus(Enum):
     VALIDATION_ENDED = "validation_ended"
     """The job passed validation."""
 
-    # Running PulLA
+    # Running Pulla
     FETCH_CALIBRATION_STARTED = "fetch_calibration_started"
     """Calibration data for the job is being fetched."""
     FETCH_CALIBRATION_ENDED = "fetch_calibration_ended"

{iqm_station_control_client-9.10.0 → iqm_station_control_client-9.12.0/src/iqm_station_control_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-station-control-client
-Version: 9.10.0
+Version: 9.12.0
 Summary: Python client for communicating with Station Control Service
 Author-email: IQM Finland Oy <info@meetiqm.com>
 License:                                  Apache License

iqm_station_control_client-9.12.0/version.txt

@@ -0,0 +1 @@
+9.12.0

iqm_station_control_client-9.10.0/version.txt

@@ -1 +0,0 @@
-9.10.0