iqm-pulla 11.0.0__tar.gz → 11.2.0__tar.gz

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/CHANGELOG.rst

@@ -2,6 +2,22 @@
 Changelog
 =========
 
+Version 11.2.0 (2025-09-12)
+===========================
+
+Features
+--------
+
+- Allow executing jobs in async fashion
+
+Version 11.1.0 (2025-09-12)
+===========================
+
+Features
+--------
+
+- Postprocessing stages.
+
 Version 11.0.0 (2025-09-11)
 ===========================
 

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-pulla
-Version: 11.0.0
+Version: 11.2.0
 Summary: Client library for pulse-level access to an IQM quantum computer
 Author-email: IQM Finland Oy <developers@meetiqm.com>
 License:                                  Apache License

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/docs/Quick Start.ipynb

@@ -388,6 +388,16 @@
     "print(f\"Qiskit result counts:\\n{qiskit_result.get_counts()}\\n\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "1778cf4c",
+   "metadata": {},
+   "source": [
+    "By default, `execute()` submits the job and waits for its completion by polling the server every second, until interrupted. If you pass `wait_completion=False`, then the method will terminate immediately after submitting the job and return a `StationControlResult` object with the job id in `PENDING` status. \n",
+    "\n",
+    "You can then manually retrieve job results by calling `get_execution_result()`. It will also, by default, wait for the job to complete until interrupted. If you pass `wait_completion=False`, then `get_execution_result()` will query the server only once and return the current state; it is then up to you to call `get_execution_result()` until the job is completed."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "2014d3e7",

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/src/iqm/cpc/__init__.py

@@ -14,26 +14,9 @@
 """IQM Circuit to Pulse Compiler.
 
 IQM Circuit to Pulse Compiler is a Python-based library for converting quantum circuits
-into :class:`instruction schedules <exa.pulse.pulse_schedule.PulseSchedule>`
-(which map ``Station Control`` controller names to their pulse playlists) and Station Control settings
+into :class:`instruction schedules <iqm.pulse.playlist.schedule.Schedule>`
+(which map ``Station Control`` controller names to lists of hardware instructions) and Station Control settings
 required for circuit execution, using the calibration data it is given.
 The generated schedules and settings can be sent to Station Control
 for execution on real or simulated quantum hardware.
-
-CPC is normally only accessed indirectly through Cocos or its reference client
-`IQM client <https://docs.meetiqm.com/iqm-client/index.html>`_,
-or a frontend such as
-`Cirq on IQM <https://docs.meetiqm.com/iqm-client/user_guide_cirq.html>`_ or
-`Qiskit on IQM <https://docs.meetiqm.com/iqm-client/user_guide_qiskit.html>`_.
 """
-
-# from importlib.metadata import PackageNotFoundError, version
-
-# try:
-#     # Change here if project is renamed and does not equal the package name
-#     DIST_NAME = "iqm-cocos"
-#     __version__ = version(DIST_NAME)
-# except PackageNotFoundError:  # pragma: no cover
-#     __version__ = "unknown"
-# finally:
-#     del version, PackageNotFoundError

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/src/iqm/cpc/compiler/compiler.py

@@ -20,7 +20,7 @@ can be executed by the IQM server on quantum hardware.
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable
+from collections.abc import Callable, Collection, Iterable
 from copy import deepcopy
 import functools
 import inspect
@@ -28,8 +28,10 @@ import logging
 from typing import TYPE_CHECKING, Any
 
 from opentelemetry import trace
+from typing_extensions import deprecated
 
 from exa.common.data.setting_node import SettingNode
+from exa.common.helpers.deprecation import format_deprecated
 from iqm.cpc.compiler.errors import CalibrationError, ClientError, InsufficientContextError
 from iqm.cpc.interface.compiler import (
     CircuitBoundaryMode,
@@ -187,13 +189,16 @@ class Compiler:
     Args:
         calibration_set: Calibration data.
         chip_topology: Physical layout and connectivity of the quantum chip.
-        channel_properties: Channel properties.
-        component_channels: Mapping between components and their control channels.
-        component_mapping: Custom mapping of components. Defaults to None.
+        channel_properties: Control channel properties for the station.
+        component_channels: Mapping from QPU component name to a mapping from ``('drive', 'flux', 'readout')``
+            to the name of the control channel responsible for that function of the component.
+        component_mapping: Mapping of logical QPU component names to physical QPU component names.
+            ``None`` means the identity mapping.
         options: Circuit execution options.
             Defaults to STANDARD_CIRCUIT_EXECUTION_OPTIONS.
-        stages: List of compilation stages. Defaults to None.
-            Note that in the absence of stages, the compiler will not be ready to compile circuits.
+        stages: Compilation stages to use. ``None`` means none.
+            Note that meaningful circuit compilation requires at least some stages.
+        pp_stages: Post-processing stages to use. ``None`` means none.
         strict: If True, raises CalibrationError on calibration validation failures.
             If False, only logs warnings. Defaults to False.
 
@@ -202,7 +207,7 @@ class Compiler:
 
     """
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         *,
         calibration_set: CalibrationSet,
@@ -211,13 +216,15 @@ class Compiler:
         component_channels: dict[str, dict[str, str]],
         component_mapping: dict[str, str] | None = None,
         options: CircuitExecutionOptions = STANDARD_CIRCUIT_EXECUTION_OPTIONS,
-        stages: list[CompilationStage] | None = None,
+        stages: Collection[CompilationStage] | None = None,
+        pp_stages: Collection[CompilationStage] | None = None,
         strict: bool = False,  # consider extending to e.g. errors: Literal["raise", "warning", "ignore"] = "warning"
     ):
         self._calibration_set = calibration_set
         self.component_mapping = component_mapping
         self.options = options
         self.stages = stages or []
+        self.pp_stages = pp_stages or []
 
         self.builder: ScheduleBuilder = initialize_schedule_builder(
             calibration_set, chip_topology, channel_properties, component_channels
@@ -357,11 +364,12 @@ class Compiler:
         )
         self._refresh()
 
+    @deprecated(format_deprecated(old="`ready`", new=None, since="12.08.2025"))
     def ready(self) -> bool:
         """Check if the compiler is ready to compile circuits. The compiler is ready if at least one stage is defined, and
         all the stages are non-empty.
         """  # noqa: E501
-        if len(self.stages) == 0:
+        if not self.stages:
             return False
         for stage in self.stages:
             if not stage.ready():
@@ -394,7 +402,7 @@ class Compiler:
             full: Iff True, also print the docstring of each pass function.
 
         """
-        if len(self.stages) == 0:
+        if not self.stages:
             print("No stages defined.")
             return
 
@@ -409,7 +417,10 @@ class Compiler:
             print()
 
     def compiler_context(self) -> dict[str, Any]:
-        """Return initial compiler context dictionary. Used automatically by :meth:`Compiler.compile`."""
+        """Return initial compiler context dictionary.
+
+        Used automatically by :meth:`compile`.
+        """
         return {
             "calibration_set": self._calibration_set,
             "builder": self.builder,
@@ -422,27 +433,66 @@ class Compiler:
     def compile(
         self, data: Iterable[Any], context: dict[str, Any] | None = None
     ) -> tuple[Iterable[Any], dict[str, Any]]:
-        """Run all compiler stages. Initial context will be derived from :meth:`Compiler.compiler_context` unless a custom
+        """Run all compiler stages.
+
+            Initial context will be derived using :meth:`compiler_context` unless a custom
+            context dictionary is provided.
+
+        Args:
+            data: Circuits to be compiled.
+            context: Custom initial compiler context dictionary.
+
+        Returns:
+            Compiled ``data``, final context.
+
+        """
+        cpc_logger.info("Running compilation stages...")
+        return self.run_stages(self.stages, data, context or self.compiler_context())
+
+    def postprocess(
+        self, data: Iterable[Any], context: dict[str, Any] | None = None
+    ) -> tuple[Iterable[Any], dict[str, Any]]:
+        """Run all post-processing stages.
+
+        Initial context will be derived using :meth:`compiler_context` unless a custom
         context dictionary is provided.
 
         Args:
-            data: An iterable of circuits to be compiled.
+            data: Any data, e.g. execution results derived from :meth:`Pulla.execute`
             context: Custom initial compiler context dictionary.
 
+        Returns:
+            Postprocessed ``data``, final context.
+
         """  # noqa: E501
-        if not self.ready():
-            raise RuntimeError("Compiler is not ready: no stages defined, or some stages have zero passes.")
+        cpc_logger.info("Running postprocessing stages...")
+        return self.run_stages(self.pp_stages, data, context or self.compiler_context())
+
+    def run_stages(
+        self, stages: Collection[CompilationStage], data: Iterable[Any], context: dict[str, Any]
+    ) -> tuple[Iterable[Any], dict[str, Any]]:
+        """Run the given stages in given order on the given data.
+
+        Args:
+            stages: Stages to run on ``data``.
+            data: The data to be processed.
+            context: Additional information that is passed to the first stage.
+                Each stage may make modifications to ``context`` before it is passed to the next stage.
 
-        # Dictionary of context to be passed through all the passes
-        if context is None:
-            context = self.compiler_context()
+        Returns:
+            Processed data, final context.
 
-        # Run the stages
+        """
+        if not stages:
+            raise RuntimeError("No stages defined.")
         for stage in self.stages:
+            if not stage.ready():
+                raise RuntimeError(f"Stage {stage.name} is not ready.")
+
+        for stage in stages:
             cpc_logger.info('Running stage "%s"...', stage.name)
             data, context = stage.run(data, context)
 
-        cpc_logger.info("Compilation finished.")
         return data, context
 
     def build_settings(self, context: dict[str, Any], shots: int) -> tuple[SettingNode, dict[str, Any]]:

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/src/iqm/pulla/pulla.py

@@ -210,6 +210,7 @@ class Pulla:
         context: dict[str, Any],
         settings: SettingNode,
         verbose: bool = True,
+        wait_completion: bool = True,
     ) -> StationControlResult:
         """Executes a quantum circuit on the remote quantum computer.
 
@@ -218,6 +219,7 @@ class Pulla:
             context: Context object of the successful compiler run, containing the readout mappings.
             settings: Station settings.
             verbose: Whether to print results.
+            wait_completion: If True, returns immediately with job ID. If False, waits for completion.
 
         Returns:
             results of the execution
@@ -240,72 +242,130 @@ class Pulla:
             )
         )
         job_id = uuid.UUID(sweep_response["job_id"])
-        try:
-            logger.info("Created job in queue with ID: %s", job_id)
-            if href := sweep_response.get("job_href"):
-                logger.info("Job link: %s", href)
 
-            logger.info("Waiting for the job to finish...")
+        logger.info("Created job in queue with ID: %s", job_id)
+        if href := sweep_response.get("job_href"):
+            logger.info("Job link: %s", href)
 
-            while True:
-                job_data = self._station_control.get_job(job_id)
-                sc_result = StationControlResult(sweep_id=job_id, task_id=job_id, status=TaskStatus.PENDING)
+        if wait_completion:
+            return self.get_execution_result(job_id, context, verbose, wait_completion=True)
+        else:
+            return StationControlResult(sweep_id=job_id, task_id=job_id, status=TaskStatus.PENDING)
 
-                if job_data.job_status <= JobExecutorStatus.EXECUTION_STARTED:  # type: ignore[operator]
-                    # Wait in the task queue while showing a progress bar
+    def get_execution_result(
+        self,
+        job_id: uuid.UUID,
+        context: dict[str, Any],
+        verbose: bool = True,
+        wait_completion: bool = True,
+    ) -> StationControlResult:
+        """Get execution results.
 
-                    interrupted = self._station_control._wait_job_completion(str(job_id), get_progress_bar_callback())  # type: ignore[attr-defined]
-                    if interrupted:
-                        raise KeyboardInterrupt
-                else:
-                    # job is not in queue or executing, so we can query the sweep
-                    sweep_data = self._station_control.get_sweep(job_id)
-                    if job_data.job_status == JobExecutorStatus.READY:
-                        logger.info("Sweep status: %s", str(sweep_data.job_status))
-
-                        sc_result.status = TaskStatus.READY
-                        sc_result.result = map_sweep_results_to_logical_qubits(
-                            self._station_control.get_sweep_results(job_id),
-                            context["readout_mappings"],
-                            context["options"].heralding_mode,
-                        )
-                        sc_result.start_time = (
-                            sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
-                        )
-                        sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
+        Args:
+            job_id: The ID of the job to process.
+            context: Context object of the successful compiler run, containing the readout mappings.
+            verbose: Whether to print results.
+            wait_completion: If True, waits for job completion. If False, returns current status.
 
-                        if verbose:
-                            # TODO: Consider using just 'logger.debug' here and remove 'verbose'
-                            logger.info(sc_result.result)
+        Returns:
+            The processed station control result.
 
-                        return sc_result
+        """
+        sc_result = StationControlResult(sweep_id=job_id, task_id=job_id, status=TaskStatus.PENDING)
 
-                    if job_data.job_status == JobExecutorStatus.FAILED:
-                        sc_result.status = TaskStatus.FAILED
-                        sc_result.start_time = (
-                            sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
-                        )
-                        sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
-                        sc_result.message = str(job_data.job_error)
-                        logger.error("Submission failed! Error: %s", sc_result.message)
-                        return sc_result
+        try:
+            if wait_completion:
+                logger.info("Waiting for the job to finish...")
 
-                    if job_data.job_status == JobExecutorStatus.ABORTED:
-                        sc_result.status = TaskStatus.FAILED
-                        sc_result.start_time = (
-                            sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
+            while True:
+                job_data = self._station_control.get_job(job_id)
+                sc_result.status = TaskStatus.PENDING
+
+                if job_data.job_status <= JobExecutorStatus.EXECUTION_STARTED:  # type: ignore[operator]
+                    if wait_completion:
+                        # Wait in the task queue while showing a progress bar
+                        interrupted = self._station_control._wait_job_completion(  # type: ignore[attr-defined]
+                            str(job_id), get_progress_bar_callback()
+                        )
+                        if interrupted:
+                            raise KeyboardInterrupt
+                    else:
+                        # Non-blocking check - return current status
+                        sc_result.status = (
+                            TaskStatus.PROGRESS
+                            if job_data.job_status == JobExecutorStatus.EXECUTION_STARTED
+                            else TaskStatus.PENDING
                         )
-                        sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
-                        sc_result.message = str(job_data.job_error)
-                        logger.error("Submission was revoked!")
                         return sc_result
-
-                time.sleep(1)
+                else:
+                    # job is not in queue or executing, so we can query the sweep
+                    result_or_nothing = self._get_result_of_started_job(
+                        context, job_data, job_id, sc_result, wait_completion, verbose
+                    )
+                    if result_or_nothing is not None:
+                        return result_or_nothing
+
+                if wait_completion:
+                    time.sleep(1)
+                else:
+                    break
 
         except KeyboardInterrupt as exc:
-            logger.info("Caught KeyboardInterrupt, revoking job %s", job_id)
-            self._station_control.abort_job(job_id)
+            if wait_completion:
+                logger.info("Caught KeyboardInterrupt, revoking job %s", job_id)
+                self._station_control.abort_job(job_id)
             raise KeyboardInterrupt from exc
 
+        return sc_result
+
+    def _get_result_of_started_job(
+        self,
+        context: dict[str, Any],
+        job_data: Any,
+        job_id: uuid.UUID,
+        sc_result: StationControlResult,
+        wait_completion: bool,
+        verbose: bool,
+    ) -> StationControlResult | None:
+        sweep_data = self._station_control.get_sweep(job_id)
+        if job_data.job_status == JobExecutorStatus.READY:
+            if wait_completion:
+                logger.info("Sweep status: %s", str(sweep_data.job_status))
+
+            sc_result.status = TaskStatus.READY
+            sc_result.result = map_sweep_results_to_logical_qubits(
+                self._station_control.get_sweep_results(job_id),
+                context["readout_mappings"],
+                context["options"].heralding_mode,
+            )
+            sc_result.start_time = sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
+            sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
+
+            if verbose and wait_completion:
+                # TODO: Consider using just 'logger.debug' here and remove 'verbose'
+                logger.info(sc_result.result)
+
+            return sc_result
+
+        if job_data.job_status == JobExecutorStatus.FAILED:
+            sc_result.status = TaskStatus.FAILED
+            sc_result.start_time = sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
+            sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
+            sc_result.message = str(job_data.job_error)
+            if wait_completion:
+                logger.error("Submission failed! Error: %s", sc_result.message)
+            return sc_result
+
+        if job_data.job_status == JobExecutorStatus.ABORTED:
+            sc_result.status = TaskStatus.FAILED
+            sc_result.start_time = sweep_data.begin_timestamp.isoformat() if sweep_data.begin_timestamp else None
+            sc_result.end_time = sweep_data.end_timestamp.isoformat() if sweep_data.end_timestamp else None
+            sc_result.message = str(job_data.job_error)
+            if wait_completion:
+                logger.error("Submission was revoked!")
+            return sc_result
+
+        return None
+
 
 init_loggers({"iqm": "INFO"})

{iqm_pulla-11.0.0 → iqm_pulla-11.2.0}/src/iqm_pulla.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-pulla
-Version: 11.0.0
+Version: 11.2.0
 Summary: Client library for pulse-level access to an IQM quantum computer
 Author-email: IQM Finland Oy <developers@meetiqm.com>
 License:                                  Apache License

iqm_pulla-11.2.0/version.txt

@@ -0,0 +1 @@
+11.2.0

iqm_pulla-11.0.0/version.txt

@@ -1 +0,0 @@
-11.0.0