qiskit 2.1.0rc1__cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

qiskit/passmanager/__init__.py

@@ -0,0 +1,258 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""
+=======================================
+Passmanager (:mod:`qiskit.passmanager`)
+=======================================
+
+.. currentmodule:: qiskit.passmanager
+
+Overview
+========
+
+The Qiskit pass manager is somewhat inspired by the `LLVM compiler <https://llvm.org/>`_,
+but it is designed to take a Python object as an input instead of plain source code.
+
+The pass manager converts the input Python object into an intermediate representation (IR),
+and it can be optimized and get lowered with a variety of transformations over multiple passes.
+The pass manager framework may employ multiple IRs with interleaved conversion passes,
+depending on the context of the optimization.
+
+.. note::
+
+    Currently there is no actual use/design of multiple IRs in the builtin Qiskit pass managers.
+    The implementation of the :mod:`passmanager` module is agnostic to
+    actual IR types (i.e. no strict type check is performed), and the pass manager works
+    as long as the IR implements all methods required by subsequent passes.
+    A concrete design for the use of multiple IRs might be provided in the future release.
+
+The passes may consume the hardware constraints that the Qiskit backend may provide.
+Finally, the IR is converted back to some Python object.
+Note that the input type and output type are not necessarily the same.
+
+Compilation in the pass manager is a chain of :class:`~.passmanager.Task` executions that
+take an IR and output a new IR with some optimization or data analysis.
+An atomic task is a *pass* which is a subclass of :class:`.GenericPass` that implements
+a :meth:`.~GenericPass.run` method that performs some work on the received IR.
+A set of passes may form a *flow controller*, which is a subclass of
+:class:`.BaseController`, which can implement arbitrary compilation-state-dependent logic for
+deciding which pass will get run next.
+Passes share intermediate data via the :class:`.PropertySet` object which is
+a free-form dictionary. A pass can populate the property set dictionary during the task execution.
+A flow controller can also consume the property set to control the pass execution,
+but this access must be read-only.
+The property set is portable and handed over from pass to pass at execution.
+In addition to the property set, tasks also receive a :class:`.WorkflowStatus` data structure.
+This object is initialized when the pass manager is run and handed over to underlying tasks.
+The status is updated after every pass is run, and contains information about the pipeline state
+(number of passes run, failure state, and so on) as opposed to the :class:`PropertySet`, which
+contains information about the IR being optimized.
+
+A pass manager is a wrapper of the flow controller, with responsibilities of
+
+* Scheduling optimization tasks,
+* Converting an input Python object to a particular Qiskit IR,
+* Initializing a property set and workflow status,
+* Running scheduled tasks to apply a series of transformations to the IR,
+* Converting the IR back to an output Python object.
+
+This indicates that the flow controller itself is type-agnostic, and a developer must
+implement a subclass of the :class:`BasePassManager` to manage the data conversion steps.
+This *veil of ignorance* allows us to choose the most efficient data representation
+for a particular pass manager task, while we can reuse the flow control machinery
+for different input and output types.
+
+A single flow controller always takes a single IR object, and returns a single
+IR object. Parallelism for multiple input objects is supported by the
+:class:`BasePassManager` by broadcasting the flow controller via
+the :func:`.parallel_map` function.
+
+
+Examples
+========
+
+We look into a toy optimization task, namely, preparing a row of numbers
+and remove a digit if the number is five.
+Such task might be easily done by converting the input numbers into string.
+We use the pass manager framework here, putting the efficiency aside for
+a moment to learn how to build a custom Qiskit compiler.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    from qiskit.passmanager import BasePassManager, GenericPass, ConditionalController
+
+    class ToyPassManager(BasePassManager):
+
+        def _passmanager_frontend(self, input_program: int, **kwargs) -> str:
+            return str(input_program)
+
+        def _passmanager_backend(self, passmanager_ir: str, in_program: int, **kwargs) -> int:
+            return int(passmanager_ir)
+
+This pass manager inputs and outputs an integer number, while
+performing the optimization tasks on a string data.
+Hence, input, IR, output type are integer, string, integer, respectively.
+The :meth:`.~BasePassManager._passmanager_frontend` method defines the conversion from the
+input data to IR, and :meth:`.~BasePassManager._passmanager_backend` defines
+the conversion from the IR to output data.
+The pass manager backend is also given an :code:`in_program` parameter that contains the original
+``input_program`` to the front end, for referencing any original metadata of the input program for
+the final conversion.
+
+Next, we implement a pass that removes a digit when the number is five.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    class RemoveFive(GenericPass):
+
+        def run(self, passmanager_ir: str):
+            return passmanager_ir.replace("5", "")
+
+    task = RemoveFive()
+
+Finally, we instantiate a pass manager and schedule the task with it.
+Running the pass manager with random row of numbers returns
+new numbers that don't contain five.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    pm = ToyPassManager()
+    pm.append(task)
+
+    pm.run([123456789, 45654, 36785554])
+
+Output:
+
+.. code-block:: text
+
+    [12346789, 464, 36784]
+
+Now we consider the case of conditional execution.
+We avoid execution of the "remove five" task when the input number is
+six digits or less. Such control can be implemented by a flow controller.
+We start from an analysis pass that provides the flow controller
+with information about the number of digits.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    class CountDigits(GenericPass):
+
+        def run(self, passmanager_ir: str):
+            self.property_set["ndigits"] = len(passmanager_ir)
+
+    analysis_task = CountDigits()
+
+Then, we wrap the remove five task with the :class:`.ConditionalController`
+that runs the stored tasks only when the condition is met.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    def digit_condition(property_set):
+        # Return True when condition is met.
+        return property_set["ndigits"] > 6
+
+    conditional_task = ConditionalController(
+        tasks=[RemoveFive()],
+        condition=digit_condition,
+    )
+
+As before, we schedule these passes with the pass manager and run.
+
+.. plot::
+   :include-source:
+   :nofigs:
+   :context:
+
+    pm = ToyPassManager()
+    pm.append(analysis_task)
+    pm.append(conditional_task)
+
+    pm.run([123456789, 45654, 36785554])
+
+Output:
+
+.. code-block:: text
+
+    [12346789, 45654, 36784]
+
+The "remove five" task is triggered only for the first and third input
+values, which have more than six digits.
+
+With the pass manager framework, a developer can flexibly customize
+the optimization task by combining multiple passes and flow controllers.
+See details for following class API documentations.
+
+
+Interface
+=========
+
+Base classes
+------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   BasePassManager
+   BaseController
+   GenericPass
+
+Flow controllers
+----------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   FlowControllerLinear
+   ConditionalController
+   DoWhileController
+
+Compilation state
+-----------------
+
+.. autosummary::
+   :toctree: ../stubs/
+
+   PropertySet
+   WorkflowStatus
+   PassManagerState
+
+Exceptions
+----------
+
+.. autoexception:: PassManagerError
+"""
+
+from .passmanager import BasePassManager
+from .flow_controllers import (
+    FlowControllerLinear,
+    ConditionalController,
+    DoWhileController,
+)
+from .base_tasks import GenericPass, BaseController
+from .compilation_status import PropertySet, WorkflowStatus, PassManagerState
+from .exceptions import PassManagerError

qiskit/passmanager/base_tasks.py

@@ -0,0 +1,230 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Baseclasses for the Qiskit passmanager optimization tasks."""
+from __future__ import annotations
+
+import logging
+import time
+from abc import abstractmethod, ABC
+from collections.abc import Iterable, Callable, Generator
+from typing import Any
+
+from .compilation_status import RunState, PassManagerState, PropertySet
+
+logger = logging.getLogger(__name__)
+
+# Type alias
+PassManagerIR = Any
+
+
+class Task(ABC):
+    """An interface of the pass manager task.
+
+    The task takes a Qiskit IR, and outputs new Qiskit IR after some operation on it.
+    A task can rely on the :class:`.PropertySet` to communicate intermediate data among tasks.
+    """
+
+    @abstractmethod
+    def execute(
+        self,
+        passmanager_ir: PassManagerIR,
+        state: PassManagerState,
+        callback: Callable = None,
+    ) -> tuple[PassManagerIR, PassManagerState]:
+        """Execute optimization task for input Qiskit IR.
+
+        Args:
+            passmanager_ir: Qiskit IR to optimize.
+            state: State associated with workflow execution by the pass manager itself.
+            callback: A callback function which is caller per execution of optimization task.
+
+        Returns:
+            Optimized Qiskit IR and state of the workflow.
+        """
+        pass
+
+
+class GenericPass(Task, ABC):
+    """Base class of a single pass manager task.
+
+    A pass instance can read and write to the provided :class:`.PropertySet`,
+    and may modify the input pass manager IR.
+    """
+
+    def __init__(self):
+        self.property_set = PropertySet()
+        self.requires: Iterable[Task] = []
+
+    def name(self) -> str:
+        """Name of the pass."""
+        return self.__class__.__name__
+
+    def execute(
+        self,
+        passmanager_ir: PassManagerIR,
+        state: PassManagerState,
+        callback: Callable = None,
+    ) -> tuple[PassManagerIR, PassManagerState]:
+        # Overriding this method is not safe.
+        # Pass subclass must keep current implementation.
+        # Especially, task execution may break when method signature is modified.
+        self.property_set = state.property_set
+
+        if self.requires:
+            # pylint: disable=cyclic-import
+            from .flow_controllers import FlowControllerLinear
+
+            passmanager_ir, state = FlowControllerLinear(self.requires).execute(
+                passmanager_ir=passmanager_ir,
+                state=state,
+                callback=callback,
+            )
+
+        run_state = None
+        ret = None
+        start_time = time.time()
+        try:
+            if self not in state.workflow_status.completed_passes:
+                ret = self.run(passmanager_ir)
+                run_state = RunState.SUCCESS
+            else:
+                run_state = RunState.SKIP
+        except Exception:
+            run_state = RunState.FAIL
+            raise
+        finally:
+            ret = ret or passmanager_ir
+            if run_state != RunState.SKIP:
+                running_time = time.time() - start_time
+                logger.info("Pass: %s - %.5f (ms)", self.name(), running_time * 1000)
+                if callback is not None:
+                    callback(
+                        task=self,
+                        passmanager_ir=ret,
+                        property_set=state.property_set,
+                        running_time=running_time,
+                        count=state.workflow_status.count,
+                    )
+        return ret, self.update_status(state, run_state)
+
+    def update_status(
+        self,
+        state: PassManagerState,
+        run_state: RunState,
+    ) -> PassManagerState:
+        """Update workflow status.
+
+        Args:
+            state: Pass manager state to update.
+            run_state: Completion status of current task.
+
+        Returns:
+            Updated pass manager state.
+        """
+        state.workflow_status.previous_run = run_state
+        if run_state == RunState.SUCCESS:
+            state.workflow_status.count += 1
+            state.workflow_status.completed_passes.add(self)
+        return state
+
+    @abstractmethod
+    def run(
+        self,
+        passmanager_ir: PassManagerIR,
+    ) -> PassManagerIR:
+        """Run optimization task.
+
+        Args:
+            passmanager_ir: Qiskit IR to optimize.
+
+        Returns:
+            Optimized Qiskit IR.
+        """
+        pass
+
+
+class BaseController(Task, ABC):
+    """Base class of controller.
+
+    A controller is built with a collection of pass manager tasks,
+    and a subclass provides a custom logic to choose next task to run.
+    Note a controller can be nested into another controller,
+    and a controller itself doesn't provide any subroutine to modify the input IR.
+    """
+
+    def __init__(
+        self,
+        options: dict[str, Any] | None = None,
+    ):
+        """Create new flow controller.
+
+        Args:
+            options: Option for this flow controller.
+        """
+        self._options = options or {}
+
+    @abstractmethod
+    def iter_tasks(
+        self,
+        state: PassManagerState,
+    ) -> Generator[Task, PassManagerState, None]:
+        """A custom logic to choose a next task to run.
+
+        Controller subclass can consume the state to build a proper task pipeline.  The updated
+        state after a task execution will be fed back in as the "return" value of any ``yield``
+        statements.  This indicates the order of task execution is only determined at running time.
+        This method is not allowed to mutate the given state object.
+
+        Args:
+            state: The state of the passmanager workflow at the beginning of this flow controller's
+                execution.
+
+        Receives:
+            state: the state of pass manager after the execution of the last task that was yielded.
+                The generator does not need to inspect this if it is irrelevant to its logic, nor
+                update it.
+
+        Yields:
+            Task: Next task to run.
+        """
+        pass
+
+    def execute(
+        self,
+        passmanager_ir: PassManagerIR,
+        state: PassManagerState,
+        callback: Callable = None,
+    ) -> tuple[PassManagerIR, PassManagerState]:
+        # Overriding this method is not safe.
+        # Pass subclass must keep current implementation.
+        # Especially, task execution may break when method signature is modified.
+
+        task_generator = self.iter_tasks(state)
+        try:
+            next_task = task_generator.send(None)
+        except StopIteration:
+            return passmanager_ir, state
+        while True:
+            passmanager_ir, state = next_task.execute(
+                passmanager_ir=passmanager_ir,
+                state=state,
+                callback=callback,
+            )
+            try:
+                # Sending the object through the generator implies the custom controllers
+                # can always rely on the latest data to choose the next task to run.
+                next_task = task_generator.send(state)
+            except StopIteration:
+                break
+
+        return passmanager_ir, state

qiskit/passmanager/compilation_status.py

@@ -0,0 +1,74 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2018, 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""A property set dictionary that shared among optimization passes."""
+
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class PropertySet(dict):
+    """A default dictionary-like object."""
+
+    def __missing__(self, key):
+        return None
+
+
+class RunState(Enum):
+    """Allowed values for the result of a pass execution."""
+
+    SUCCESS = 0
+    FAIL = 1
+    SKIP = 2
+
+
+@dataclass
+class WorkflowStatus:
+    """Collection of compilation status of workflow, i.e. pass manager run.
+
+    This data structure is initialized when the pass manager is run,
+    and recursively handed over to underlying tasks.
+    Each pass will update this status once after being executed, and the lifetime of the
+    workflow status object is the time during which the pass manager is running.
+    """
+
+    count: int = 0
+    """Current number of pass execution."""
+
+    completed_passes: set = field(default_factory=set)
+    """Passes already run that have not been invalidated."""
+
+    previous_run: RunState = RunState.FAIL
+    """Status of the latest pass run."""
+
+
+@dataclass
+class PassManagerState:
+    """A portable container object that pass manager tasks communicate through generator.
+
+    This object can contain every information about the running pass manager workflow,
+    except for the IR object being optimized.
+    The data structure consists of two elements; one for the status of the
+    workflow itself, and another one for the additional information about the IR
+    analyzed through pass executions. This container aims at just providing
+    a robust interface for the :meth:`.Task.execute`, and no logic that modifies
+    the container elements must be implemented.
+
+    This object is mutable, and might be mutated by pass executions.
+    """
+
+    workflow_status: WorkflowStatus
+    """Status of the current compilation workflow."""
+
+    property_set: PropertySet
+    """Information about IR being optimized."""

qiskit/passmanager/exceptions.py

@@ -0,0 +1,19 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Qiskit pass manager exceptions."""
+
+from qiskit.exceptions import QiskitError
+
+
+class PassManagerError(QiskitError):
+    """Pass manager error."""

qiskit/passmanager/flow_controllers.py

@@ -0,0 +1,116 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2019, 2023
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Built-in pass flow controllers."""
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Generator
+from typing import Any
+
+from .base_tasks import BaseController, Task
+from .compilation_status import PassManagerState, PropertySet
+from .exceptions import PassManagerError
+
+logger = logging.getLogger(__name__)
+
+
+class FlowControllerLinear(BaseController):
+    """A standard flow controller that runs tasks one after the other."""
+
+    def __init__(
+        self,
+        tasks: Task | Iterable[Task] = (),
+        *,
+        options: dict[str, Any] | None = None,
+    ):
+        super().__init__(options)
+
+        if not isinstance(tasks, Iterable):
+            tasks = [tasks]
+        self.tasks: tuple[Task] = tuple(tasks)
+
+    @property
+    def passes(self) -> list[Task]:
+        """Alias of tasks for backward compatibility."""
+        return list(self.tasks)
+
+    def iter_tasks(self, state: PassManagerState) -> Generator[Task, PassManagerState, None]:
+        for task in self.tasks:
+            state = yield task
+
+
+class DoWhileController(BaseController):
+    """Run the given tasks in a loop until the ``do_while`` condition on the property set becomes
+    ``False``.
+
+    The given tasks will always run at least once, and on iteration of the loop, all the
+    tasks will be run (with the exception of a failure state being set)."""
+
+    def __init__(
+        self,
+        tasks: Task | Iterable[Task] = (),
+        do_while: Callable[[PropertySet], bool] = None,
+        *,
+        options: dict[str, Any] | None = None,
+    ):
+        super().__init__(options)
+
+        if not isinstance(tasks, Iterable):
+            tasks = [tasks]
+        self.tasks: tuple[Task] = tuple(tasks)
+        self.do_while = do_while
+
+    @property
+    def passes(self) -> list[Task]:
+        """Alias of tasks for backward compatibility."""
+        return list(self.tasks)
+
+    def iter_tasks(self, state: PassManagerState) -> Generator[Task, PassManagerState, None]:
+        max_iteration = self._options.get("max_iteration", 1000)
+        for _ in range(max_iteration):
+            for task in self.tasks:
+                state = yield task
+            if not self.do_while(state.property_set):
+                return
+            # Remove stored tasks from the completed task collection for next loop
+            state.workflow_status.completed_passes.difference_update(self.tasks)
+        raise PassManagerError(f"Maximum iteration reached. max_iteration={max_iteration}")
+
+
+class ConditionalController(BaseController):
+    """A flow controller runs the pipeline once if the condition is true, or does nothing if the
+    condition is false."""
+
+    def __init__(
+        self,
+        tasks: Task | Iterable[Task] = (),
+        condition: Callable[[PropertySet], bool] = None,
+        *,
+        options: dict[str, Any] | None = None,
+    ):
+        super().__init__(options)
+
+        if not isinstance(tasks, Iterable):
+            tasks = [tasks]
+        self.tasks: tuple[Task] = tuple(tasks)
+        self.condition = condition
+
+    @property
+    def passes(self) -> list[Task]:
+        """Alias of tasks for backward compatibility."""
+        return list(self.tasks)
+
+    def iter_tasks(self, state: PassManagerState) -> Generator[Task, PassManagerState, None]:
+        if self.condition(state.property_set):
+            for task in self.tasks:
+                state = yield task