iqm-station-control-client 11.3.1__py3-none-any.whl → 12.0.0__py3-none-any.whl

iqm/station_control/interface/models/circuit.py

@@ -0,0 +1,348 @@
+# 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.
+"""Models related to quantum circuit execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING, Annotated, Any, TypeAlias
+from uuid import UUID
+
+from pydantic import AliasChoices, BeforeValidator, Field, PlainSerializer, WithJsonSchema, computed_field
+
+from exa.common.helpers.deprecation import format_deprecated
+from iqm.pulse import Circuit
+from iqm.station_control.interface.pydantic_base import PydanticBase
+
+if TYPE_CHECKING:
+    from iqm.pulse import Circuit, CircuitOperation
+
+
+PRXSequence: TypeAlias = list[tuple[float, float]]
+"""Sequence of PRX gates. A generic PRX gate is defined by rotation angle and phase angle, theta and phi,
+respectively."""
+
+QIRCode: TypeAlias = str
+"""QIR program code in string representation."""
+
+
+# TODO: remove when CUDA-Q supports the new circuit format
+@dataclass
+class _Instruction:
+    """An instruction in a quantum circuit. Old format."""
+
+    name: str
+    implementation: str | None = None
+    qubits: tuple[str, ...] = field(default_factory=tuple)
+    args: dict[str, Any] = field(default_factory=dict)
+
+    def to_cpc_type(self) -> CircuitOperation:
+        """Convert the model to a dataclass."""
+        return CircuitOperation(
+            name=self.name,
+            implementation=self.implementation,
+            locus=self.qubits,
+            args=self.args,
+        )
+
+
+# TODO: remove when CUDA-Q supports the new circuit format
+@dataclass
+class _Circuit:
+    """Quantum circuit to be executed. Old format."""
+
+    name: str
+    instructions: tuple[_Instruction, ...] = field(default_factory=tuple)
+    metadata: dict[str, Any] | None = None
+
+    def to_cpc_type(self) -> Circuit:
+        """Convert the model to a dataclass."""
+        return Circuit(
+            name=self.name,
+            instructions=tuple(instruction.to_cpc_type() for instruction in self.instructions),
+        )
+
+
+CircuitBatch: TypeAlias = list[Circuit | _Circuit | QIRCode]
+"""Sequence of quantum circuits to be executed together in a single batch."""
+
+
+CircuitMeasurementResults: TypeAlias = dict[str, list[list[int]]]
+"""Measurement results from a single circuit.
+
+For each measurement operation in the circuit, maps the measurement key to the corresponding results.
+``results[key][shot][qubit_index]`` is the result of measuring the
+``qubit_index``'th qubit in measurement operation ``key`` in the shot ``shot``.
+The results are non-negative integers representing the computational basis state (for qubits, 0 or 1)
+that was the measurement outcome.
+"""
+
+CircuitMeasurementResultsBatch: TypeAlias = list[CircuitMeasurementResults]
+"""Type that represents measurement results for a batch of circuits."""
+
+
+class HeraldingMode(StrEnum):
+    """Heralding mode for circuit execution.
+
+    Heralding is the practice of generating data about the state of qubits prior to execution of a circuit.
+    This can be achieved by measuring the qubits immediately before executing each shot for a circuit.
+    """
+
+    NONE = "none"
+    """Do not do any heralding."""
+    ZEROS = "zeros"
+    """For each circuit, perform a heralding measurement after the initial reset on all the QPU components
+    used in the circuit that have the "measure" operation available in the calset.
+    Only retain shots where all the components are measured to be in the zero state.
+
+    Note: in this mode, the number of shots returned after execution will be <= the requested amount
+    due to the post-selection based on heralding data.
+    If zero shots would be returned, the job will have the FAILED status."""
+
+
+class MoveGateValidationMode(StrEnum):
+    """MOVE gate validation mode for circuit compilation. This options is meant for advanced users."""
+
+    STRICT = "strict"
+    """Perform standard MOVE gate validation: MOVE(qubit, resonator) gates must only
+    appear in sandwiches (pairs). Inside a sandwich there must be no gates acting on the
+    MOVE qubit, and no other MOVE gates acting on the resonator."""
+    ALLOW_PRX = "allow_prx"
+    """Allow PRX gates on the MOVE qubit inside MOVE sandwiches during validation."""
+    NONE = "none"
+    """Do not perform any MOVE gate validation."""
+
+
+class MoveGateFrameTrackingMode(StrEnum):
+    """MOVE gate reference frame tracking mode for circuit compilation. This option is meant for advanced users."""
+
+    FULL = "full"
+    """Apply both explicit z rotations on the resonator, and a dynamic phase correction
+    due to qubit-resonator detuning, to the qubit at the end of a MOVE sandwich."""
+    NO_DETUNING_CORRECTION = "no_detuning_correction"
+    """Only apply explicit z rotations on the resonator to the qubit at the end of the sandwich.
+    Do not apply a detuning correction, the user is expected to do this manually."""
+    NONE = "none"
+    """Do not perform any MOVE gate frame tracking. The user is expected to do this manually."""
+
+
+class DDMode(StrEnum):
+    """Dynamical Decoupling (DD) mode for circuit execution."""
+
+    DISABLED = "disabled"
+    """Do not apply dynamical decoupling."""
+    ENABLED = "enabled"
+    """Apply dynamical decoupling."""
+
+
+class DDStrategy(PydanticBase):
+    """Describes a particular dynamical decoupling strategy.
+
+    The current standard DD stategy can be found in :attr:`~iqm.cpc.compiler.dd.STANDARD_DD_STRATEGY`,
+    but users can use this class to provide their own dynamical decoupling strategies.
+
+    See Ezzell et al., Phys. Rev. Appl. 20, 064027 (2022) for information on DD sequences.
+    """
+
+    # TODO station-control-client docs need to support bibtex citations.
+    # TODO :cite:`Ezzell_2022`
+
+    merge_contiguous_waits: bool = Field(default=True)
+    """Merge contiguous ``Wait`` instructions into one if they are separated only by ``Block`` instructions."""
+
+    target_qubits: frozenset[str] | None = Field(default=None)
+    """Qubits on which dynamical decoupling should be applied. If ``None``, all qubits are targeted."""
+
+    skip_leading_wait: bool = Field(default=True)
+    """Skip processing leading ``Wait`` instructions."""
+
+    skip_trailing_wait: bool = Field(default=True)
+    """Skip processing trailing ``Wait`` instructions."""
+
+    gate_sequences: list[tuple[int, str | PRXSequence, str]] = Field(default_factory=list)
+    """Available decoupling gate sequences to choose from in this strategy.
+
+    Each sequence is defined by a tuple of ``(ratio, gate pattern, align)``:
+
+        * ratio: Minimal duration for the sequence (in PRX gate durations).
+
+        * gate pattern: Gate pattern can be defined in two ways. It can be a string containing "X" and "Y" characters,
+          encoding a PRX gate sequence. For example, "YXYX" corresponds to the
+          XY4 sequence, "XYXYYXYX" to the EDD sequence, etc. If more flexibility is needed, a gate pattern can be
+          defined as a sequence of PRX gate argument tuples (that contain a rotation angle and a phase angle). For
+          example, sequence "YX" could be written as ``[(math.pi, math.pi / 2), (math.pi, 0)]``.
+
+        * align: Controls the alignment of the sequence within the time window it is inserted in. Supported values:
+
+          - "asap": Corresponds to a ASAP-aligned sequence with no waiting time before the first pulse.
+          - "center": Corresponds to a symmetric sequence.
+          - "alap": Corresponds to a ALAP-aligned sequence.
+
+    The Dynamical Decoupling algorithm uses the best fitting gate sequence by first sorting them
+    by ``ratio`` in descending order. Then the longest fitting pattern is determined by comparing ``ratio``
+    with the duration of the time window divided by the PRX gate duration.
+    """
+
+
+def _parse_legacy_qubit_mapping(value: Any) -> dict[str, str] | None:
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return {str(key): str(value) for key, value in value.items()}
+    # Deprecated since 2025-11-03.
+    # `qubit_mapping` currently uses the legacy list format on the wire,
+    # but it should eventually be replaced with the new `QubitMapping` (dict-based) format.
+    # The switch can only be made once all legacy clients have been updated,
+    # as they still depend on receiving the old response format.
+    return {item["logical_name"]: item["physical_name"] for item in value}
+
+
+def _serialize_as_legacy_qubit_mapping(mapping: dict[str, str] | None) -> list[dict[str, str]] | None:
+    if mapping is None:
+        return None
+    # Deprecated since 2025-11-03.
+    # `qubit_mapping` currently uses the legacy list format on the wire,
+    # but it should eventually be replaced with the new `QubitMapping` (dict-based) format.
+    # The switch can only be made once all legacy clients have been updated,
+    # as they still depend on receiving the old response format.
+    return [{"logical_name": k, "physical_name": v} for k, v in mapping.items()]
+
+
+LEGACY_QUBIT_MAPPING_SCHEMA = {
+    "anyOf": [
+        {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["logical_name", "physical_name"],
+                "properties": {
+                    "logical_name": {"type": "string"},
+                    "physical_name": {"type": "string"},
+                },
+                "additionalProperties": False,
+            },
+        },
+        {"type": "null"},
+    ]
+}
+
+
+QubitMapping = Annotated[
+    dict[str, str],
+    BeforeValidator(_parse_legacy_qubit_mapping),
+    PlainSerializer(_serialize_as_legacy_qubit_mapping),
+    WithJsonSchema(LEGACY_QUBIT_MAPPING_SCHEMA),
+]
+"""Mapping from logical qubit names to physical qubit names."""
+
+
+# ATTENTION: Do **not** rename RunRequest model!
+# IQM Server implements circuit validation by loading the StationControl OpenAPI specification
+# and using this (JSON) schema for the validation. OpenAPI specification contains schemas for
+# all station control models so the name of the schema (= name of this dataclass) is used to
+# select the correct schema. If you intend to rename or move this model, consult IQM Server
+# team to ensure that nothing gets broken!! Sub-schemas (e.g. Circuit) can be renamed freely
+# - FastAPI uses local schema references so the renamed references are resolved correctly,
+# as long as all the referenced schemas are added to the OpenAPI specification
+# (which is done automatically by FastAPI/Pydantic,
+# unless there are some really weird stuff in the dataclas definition).
+#
+# In addition to the schema name, IQM Server depends on the following features:
+#
+#  * RunRequest has "shots" integer property
+#  * RunRequest has "circuits" array property
+#
+# If you change those properties, coordinate the changes with IQM Server team!
+class PostJobsRequest(PydanticBase):
+    """Request to Station Control run a job that executes a batch of quantum circuits."""
+
+    circuits: CircuitBatch = Field(...)
+    """Batch of quantum circuit(s) to execute."""
+    calibration_set_id: UUID | None = Field(None)
+    """ID of the calibration set to use, or None to use the current default calibration set."""
+    qubit_mapping: QubitMapping | None = Field(None)
+    """Mapping from logical qubit names to physical qubit names, or None if ``circuits`` use physical qubit names."""
+    shots: int = Field(1, gt=0)
+    """How many times to execute each circuit in the batch, must be greater than zero."""
+    max_circuit_duration_over_t2: float | None = Field(None)
+    """Circuits are disqualified on the server if they are longer than this fraction
+       of the T2 time of the worst qubit used.
+       If set to 0.0, no circuits are disqualified. If set to None the server default value is used."""
+    heralding_mode: HeraldingMode = Field(HeraldingMode.NONE)
+    """Which heralding mode to use during the execution of circuits in this request."""
+    move_gate_validation: MoveGateValidationMode = Field(
+        MoveGateValidationMode.STRICT,
+        validation_alias=AliasChoices("move_gate_validation", "move_validation_mode"),
+    )
+    """Which method of MOVE gate validation to use in circuit compilation."""
+    move_gate_frame_tracking: MoveGateFrameTrackingMode = Field(
+        MoveGateFrameTrackingMode.FULL,
+        validation_alias=AliasChoices("move_gate_frame_tracking", "move_gate_frame_tracking_mode"),
+    )
+    """Which method of MOVE gate frame tracking to use for circuit compilation."""
+    active_reset_cycles: int | None = Field(None)
+    """Number of active ``reset`` operations inserted at the beginning of each circuit for each active qubit.
+    ``None`` means active reset is not used but instead reset is done by waiting (relaxation). Integer values smaller
+    than 1 result in neither active nor reset by wait being used, in which case any reset operations must be explicitly
+    added in the circuit."""
+    dd_mode: DDMode = Field(DDMode.DISABLED)
+    """Whether dynamical decoupling is enabled or disabled during the execution."""
+    dd_strategy: DDStrategy | None = Field(None)
+    """Dynamical decoupling strategy to be used during the execution, if DD is enabled.
+    If None, use the server default strategy."""
+
+    @computed_field(
+        json_schema_extra={
+            "deprecated": True,
+            "description": format_deprecated(
+                old="`move_validation_mode`", new="`move_gate_validation`", since="2025-10-17"
+            ),
+        },
+    )
+    def move_validation_mode(self) -> MoveGateValidationMode:
+        return self.move_gate_validation
+
+    @computed_field(
+        json_schema_extra={
+            "deprecated": True,
+            "description": format_deprecated(
+                old="`move_gate_frame_tracking_mode`", new="`move_gate_frame_tracking`", since="2025-10-17"
+            ),
+        },
+    )
+    def move_gate_frame_tracking_mode(self) -> MoveGateFrameTrackingMode:
+        return self.move_gate_frame_tracking
+
+
+RunRequest: TypeAlias = PostJobsRequest
+
+
+class CircuitMeasurementCounts(PydanticBase):
+    """Circuit measurement counts in histogram representation."""
+
+    measurement_keys: list[str]
+    """Measurement keys in the order they are concatenated to form the state bitstrings in :attr:`counts`.
+
+    For example, if :attr:`measurement_keys` is ``['mk_1', 'mk2']`` and ``'mk_1'`` measures ``QB1``
+    and ``'mk_2'`` measures ``QB3`` and ``QB5``, then :attr:`counts` could contains keys such as ``'010'`` representing
+    shots where ``QB1`, ``QB3`` and ``QB5`` were observed to be in the state :math:`|010\rangle`.
+    """
+    counts: dict[str, int]
+    """Mapping from computational basis states, represented as bitstrings, to the number of times they were observed
+    when executing the circuit."""
+
+
+CircuitMeasurementCountsBatch: TypeAlias = list[CircuitMeasurementCounts]
+"""Measurement results in histogram representation for each circuit in the batch."""

iqm/station_control/interface/models/dynamic_quantum_architecture.py

@@ -13,14 +13,16 @@
 # limitations under the License.
 """Dynamic quantum architecture (DQA) related interface models."""
 
-from typing import Any
+from functools import cached_property
+import re
+from typing import Any, TypeAlias
 from uuid import UUID
 
-from pydantic import Field, StrictStr, field_validator
+from pydantic import Field, field_validator
 
 from iqm.station_control.interface.pydantic_base import PydanticBase
 
-Locus = tuple[StrictStr, ...]
+Locus: TypeAlias = tuple[str, ...]
 """Names of the QPU components (typically qubits) a quantum operation instance is acting on, e.g. `("QB1", "QB2")`."""
 
 
@@ -80,6 +82,42 @@ class GateInfo(PydanticBase):
             return new_value
         raise ValueError("'override_default_implementation' must be a dict.")
 
+    @cached_property
+    def loci(self) -> tuple[Locus, ...]:
+        """Returns all loci which are available for at least one of the implementations.
+
+        The loci are sorted first based on the first locus component, then the second, etc.
+        The sorting of individual locus components is first done alphabetically based on their
+        non-numeric part, and then components with the same non-numeric part are sorted numerically.
+        An example of loci sorted this way would be:
+
+            ('QB1', 'QB2'),
+            ('QB2', 'COMPR1'),
+            ('QB2', 'QB3'),
+            ('QB3', 'COMPR1'),
+            ('QB3', 'COMPR2'),
+            ('QB3', 'QB1'),
+            ('QB10', 'QB2'),
+
+        """
+        loci_set = {locus for impl in self.implementations.values() for locus in impl.loci}
+        loci_sorted = sorted(loci_set, key=lambda locus: tuple(map(_component_sort_key, locus)))
+        return tuple(loci_sorted)
+
+    def get_default_implementation(self, locus: Locus) -> str:
+        """Default implementation of this gate for the given locus.
+
+        Args:
+            locus: gate locus
+
+        Returns:
+            Name of the default implementation of this gate for ``locus``.
+
+        """
+        if (impl := self.override_default_implementation.get(locus)) is not None:
+            return impl
+        return self.default_implementation
+
 
 class DynamicQuantumArchitecture(PydanticBase):
     """The dynamic quantum architecture (DQA).
@@ -117,3 +155,23 @@ class DynamicQuantumArchitecture(PydanticBase):
         ],
     )
     """Mapping of gate names to information about the gates."""
+
+    @cached_property
+    def components(self) -> tuple[str, ...]:
+        """All locus components (qubits and computational resonators) sorted.
+
+        The components are first sorted alphabetically based on their non-numeric part, and then
+        components with the same non-numeric part are sorted numerically. An example of components
+        sorted this way would be: ('COMPR1', 'COMPR2', 'QB1', 'QB2', 'QB3', 'QB10', 'QB11', 'QB20').
+        """
+        return tuple(sorted(self.qubits + self.computational_resonators, key=_component_sort_key))
+
+
+def _component_sort_key(component_name: str) -> tuple[str, int, str]:
+    """Sorting key for QPU component names."""
+
+    def get_numeric_id(name: str) -> int:
+        match = re.search(r"(\d+)", name)
+        return int(match.group(1)) if match else 0
+
+    return re.sub(r"[^a-zA-Z]", "", component_name), get_numeric_id(component_name), component_name

iqm/station_control/interface/models/jobs.py

@@ -11,60 +11,89 @@
 # 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.
-"""Job executor artifact and state models."""
+"""Job-related models."""
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from datetime import datetime
 from enum import Enum
 import functools
+from typing import TypeAlias
 from uuid import UUID
 
 from iqm.station_control.interface.pydantic_base import PydanticBase
 
+_Progress: TypeAlias = tuple[str, int, int]
+"""Describes the progress of an arbitrary task: (label, value, max_value)."""
+
+ProgressCallback: TypeAlias = Callable[[list[_Progress]], None]
+"""Callback function for reporting progress on a list of tasks."""
+
+Statuses: TypeAlias = list[_Progress]
+"""Progress of the parallel sweeps of a job.
+Used in Station Control. Deprecated, should not be used anywhere else."""
+
 
 class TimelineEntry(PydanticBase):
-    """Status and timestamp pair as described in a job timeline."""
+    """Status and timestamp pair for a job timeline."""
 
     status: JobExecutorStatus
+    """Job status that was reached."""
     timestamp: datetime
+    """Time at which ``status`` was reached."""
 
 
 class JobResult(PydanticBase):
-    """Progress information about a running job."""
+    """Progress information for the JobExecutorStatus.EXECUTION_STARTED stage of a job."""
+
+    # TODO redesign, should not be called JobResult since it's a progress indicator
 
     job_id: UUID
-    parallel_sweep_progress: list[tuple[str, int, int]]
+    """ID of the job."""
+    parallel_sweep_progress: list[_Progress]
+    """Progress of the sweeps if we are in the JobExecutorStatus.EXECUTION_STARTED stage, otherwise empty."""
     interrupted: bool
+    """True iff the job was canceled."""
 
 
 class JobError(PydanticBase):
-    """Error log for a job."""
+    """Error message for a job."""
 
     full_error_log: str
+    """Full error message for logging."""
     user_error_message: str
+    """Short, human-readable error message for users."""
 
 
 class JobData(PydanticBase):
     """Status, artifacts and metadata of a job."""
 
+    # TODO redesign
+
     job_id: UUID
     """Unique ID of the job."""
     job_status: JobExecutorStatus
     """Current job status."""
-    job_result: JobResult
-    """Progress information for the job."""  # FIXME why is it called JobResult? can it be None?
-    # job_result: The output of a progressing or a successful job. This includes progress indicators.
+    job_result: JobResult  # TODO should not be called JobResult, it's progress info for the execution stage
+    """Progress information for the JobExecutorStatus.EXECUTION_STARTED stage of a job."""
     job_error: JobError | None
-    """Error message(s) for a failed job."""
+    """Error message(s) for a failed job, otherwise None."""
     position: int | None
-    """If the job is not completed, its position in the current queue.
-    1 means this task will be executed next. In other cases the value is 0."""
+    """Number of jobs ahead of this job in its current queue.
+    None means the job has reached a terminal status.
+    """
 
 
+# NOTE: Keep JobExecutorStatus inheriting from Enum (not StrEnum).
+# Our tests do ordering like:  str(JobExecutorStatus.X) > JobExecutorStatus.Y
+# With Enum, the right operand isn’t a str, so Python dispatches to the Enum’s comparison methods,
+# where we implement definition-order (<, >) logic.
+# With StrEnum, members are str subclasses; when a plain str is on the left, Python uses str.__gt__
+# (lexicographic) and never calls our enum’s ordering, so string↔enum ordering fails.
 @functools.total_ordering
 class JobExecutorStatus(Enum):
-    """Different states a job can be in.
+    """Different statuses 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

iqm/station_control/interface/models/observation_set.py

@@ -17,8 +17,9 @@ from datetime import datetime
 import enum
 import uuid
 
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, computed_field
 
+from exa.common.helpers.deprecation import format_deprecated
 from iqm.station_control.interface.models.observation import ObservationLite
 from iqm.station_control.interface.pydantic_base import PydanticBase
 
@@ -41,8 +42,6 @@ class ObservationSetBase(PydanticBase):
 
     observation_set_type: ObservationSetType
     """Indicates the type (i.e. purpose) of the observation set."""
-    observation_ids: list[int]
-    """Database IDs of the observations belonging to the observation set."""
     describes_id: uuid.UUID | None = Field(default=None)
     """Unique identifier of the observation set this observation set describes."""
     invalid: bool = Field(default=False)
@@ -52,6 +51,9 @@ class ObservationSetBase(PydanticBase):
 class ObservationSetDefinition(ObservationSetBase):
     """The content of the observation set object when creating it."""
 
+    observation_ids: list[int]
+    """Database IDs of the observations belonging to the observation set."""
+
     model_config = ConfigDict(
         extra="forbid",  # Forbid any extra attributes
     )
@@ -60,6 +62,8 @@ class ObservationSetDefinition(ObservationSetBase):
 class ObservationSetData(ObservationSetBase):
     """The content of the observation set stored in the database."""
 
+    observation_ids: list[int]
+    """Database IDs of the observations belonging to the observation set."""
     dut_label: str | None
     """String representation of the DUT the observation set is associated with. Can only be None for generic sets."""
     observation_set_id: uuid.UUID
@@ -90,12 +94,32 @@ class ObservationSetUpdate(PydanticBase):
     """Flag indicating if the set is invalid. Automated systems must not use invalid sets."""
 
 
-class ObservationSetWithObservations(ObservationSetData):
+class ObservationSetWithObservations(ObservationSetBase):
     """The content of the observation set stored in the database, with a list of observations."""
 
+    dut_label: str | None
+    """String representation of the DUT the observation set is associated with. Can only be None for generic sets."""
+    observation_set_id: uuid.UUID
+    """Unique identifier of the observation set."""
+    created_timestamp: datetime
+    """Time when the object was created in the database."""
+    end_timestamp: datetime | None
+    """Time when the observation set was finalized. If ``None``, the set is not finalized yet."""
     observations: list[ObservationLite]
     """Observations belonging to the observation set."""
 
+    @computed_field(
+        return_type=list[int],
+        json_schema_extra={
+            "deprecated": True,
+            "description": format_deprecated(old="`observation_ids`", new="`observations`", since="2025-10-06"),
+        },
+    )
+    def observation_ids(self) -> list[int]:
+        """Database IDs of the observations belonging to the observation set."""
+        # "observation_ids" is deprecated to unify the format with IQM Server which uses "observations"
+        return [observation.observation_id for observation in self.observations]
+
 
 class QualityMetrics(ObservationSetWithObservations):
     """The content of the quality metric set stored in the database, with a list of observations and calibration set."""

iqm/station_control/interface/models/run.py

@@ -13,7 +13,7 @@
 # limitations under the License.
 """Run related station control interface models."""
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Any
 import uuid
@@ -34,9 +34,9 @@ class RunBase:
     """Identifier of the Experiment (:attr:`.Experiment.name`)."""
     experiment_label: str
     """Freeform label of the Experiment. As opposed to `experiment_name`, no core logic relies on this value."""
-    options: dict[str, Any] | None
+    options: dict[str, Any] = field(default_factory=dict)
     """Experiment-specific options or toggles that generated the run."""
-    software_version_set_id: int | None
+    software_version_set_id: int = 0
     """Unique identifier of the software version set of the current Python runtime."""
 
 
@@ -44,9 +44,9 @@ class RunBase:
 class RunConfigurationBase:
     """Abstract base class of the run configuration data."""
 
-    additional_run_properties: dict[str, Any] | None
+    additional_run_properties: dict[str, Any] = field(default_factory=dict)
     """A free-form dictionary of data, used to store information that does not fall into other categories."""
-    hard_sweeps: dict[str, NdSweep] | None
+    hard_sweeps: dict[str, NdSweep] = field(default_factory=dict)
     """Maps :attr:`.SweepBase.return_parameters` to "hardware sweep specification" which specifies
     how the data measured at each spot should be interpreted and shaped.
     The hard sweep specification is in the same format as :attr:`.SweepBase.sweeps`,
@@ -54,12 +54,12 @@ class RunConfigurationBase:
     An empty list is interpreted such that the return parameter is a scalar.
     The hard sweep specification can also be `None`,
     in which case the shape will be whatever the instrument returns."""
-    components: list[str]
+    components: list[str] = field(default_factory=list)
     """Components that participate in this run."""
-    default_data_parameters: list[str]
+    default_data_parameters: list[str] = field(default_factory=list)
     """The subset of :attr:`.SweepBase.return_parameters` that were added by default, not by the user.
     Used to select which data to analyze and plot."""
-    default_sweep_parameters: list[str]
+    default_sweep_parameters: list[str] = field(default_factory=list)
     """The subset of :attr:`.SweepBase.sweeps` parameters were added by default, not by the user.
     Used to select which data to analyze and plot."""
 

iqm/station_control/interface/models/sweep.py

@@ -52,7 +52,13 @@ class SweepDefinition(SweepBase):
 
 @dataclass(kw_only=True)
 class SweepData(SweepBase):
-    """The content of the sweep stored in the database."""
+    """The content of the sweep stored in the database.
+
+    The raw data for each spot in the sweep is saved as NumPy arrays,
+    and the complete data for the whole sweep is saved as an ``xarray.Dataset``
+    which has ``SweepBase.sweeps`` as coordinates and
+    ``SweepBase.return_parameters`` data as ``xarray.DataArray`` s.
+    """
 
     created_timestamp: datetime
     """Time when the object was created in the database."""