qiskit 1.0.0b1__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

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,336 @@
+# 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 Type, Any
+
+from qiskit.utils.deprecation import deprecate_func
+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)
+
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg="All tasks must be provided at construction time of the controller object.",
+    )
+    def append(
+        self,
+        passes: Task | list[Task],
+    ):
+        """Add new task to pipeline.
+
+        Args:
+            passes: A new task or list of tasks to add.
+        """
+        if not isinstance(passes, Iterable):
+            passes = [passes]
+
+        tasks = list(self.tasks)
+        for task in passes:
+            if not isinstance(task, Task):
+                raise TypeError(
+                    f"New task {task} is not a valid pass manager pass or flow controller."
+                )
+            tasks.append(task)
+        self.tasks = tuple(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)
+
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg="All tasks must be provided at construction time of the controller object.",
+    )
+    def append(
+        self,
+        passes: Task | list[Task],
+    ):
+        """Add new task to pipeline.
+
+        Args:
+            passes: A new task or list of tasks to add.
+        """
+        if not isinstance(passes, Iterable):
+            passes = [passes]
+
+        tasks = list(self.tasks)
+        for task in passes:
+            if not isinstance(task, Task):
+                raise TypeError(
+                    f"New task {task} is not a valid pass manager pass or flow controller."
+                )
+            tasks.append(task)
+        self.tasks = tuple(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("Maximum iteration reached. max_iteration=%i" % 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)
+
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg="All tasks must be provided at construction time of the controller object.",
+    )
+    def append(
+        self,
+        passes: Task | list[Task],
+    ):
+        """Add new task to pipeline.
+
+        Args:
+            passes: A new task or list of tasks to add.
+        """
+        if not isinstance(passes, Iterable):
+            passes = [passes]
+
+        tasks = list(self.tasks)
+        for task in passes:
+            if not isinstance(task, Task):
+                raise TypeError(
+                    f"New task {task} is not a valid pass manager pass or flow controller."
+                )
+            tasks.append(task)
+        self.tasks = tuple(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
+
+
+class FlowController(BaseController):
+    """A legacy factory for other flow controllers.
+
+    .. warning::
+
+        This class is primarily for compatibility with legacy versions of Qiskit, and in general,
+        you should prefer simply instantiating the controller you want, and adding it to the
+        relevant :class:`.PassManager` or other controller.  Its use is deprecated.
+
+    This allows syntactic sugar for writing pipelines. For example::
+
+        FlowController.add_flow_controller("my_condition", CustomController)
+
+        controller = FlowController.controller_factory(
+            [PassA(), PassB()],
+            {"max_iteration": 1000},
+            condition=lambda prop_set: prop_set["x"] == 0,
+            do_while=lambda prop_set: prop_set["x"] < 100,
+            my_condition=lambda prop_set: prop_set["y"] = "abc",
+        )
+
+    This creates a nested flow controller that runs when the value :code:`x` in the
+    :class:`.PropertySet` is zero and repeats the pipeline until the value becomes 100.
+    In each innermost loop, the custom iteration condition provided by
+    the ``CustomController`` is also evaluated.
+
+    .. warning::
+
+        :class:`.BaseController` must be directly subclassed to define a custom flow controller.
+        This class provides a controller factory method, which consumes a class variable
+        :attr:`.registered_controllers`. Subclassing FlowController may cause
+        unexpected behavior in the factory method.
+        Note that factory method implicitly determines the priority of the builtin controllers
+        when multiple controllers are called together,
+        and the behavior of generated controller is hardly debugged.
+    """
+
+    registered_controllers = {
+        "condition": ConditionalController,
+        "do_while": DoWhileController,
+    }
+    hierarchy = [
+        "condition",
+        "do_while",
+    ]
+
+    @classmethod
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg=(
+            "Controller object must be explicitly instantiated. "
+            "Building controller with keyword arguments may yield race condition when "
+            "multiple keyword arguments are provided together, which is likely unsafe."
+        ),
+    )
+    def controller_factory(
+        cls,
+        passes: Task | list[Task],
+        options: dict,
+        **controllers,
+    ):
+        """Create a new flow controller with normalization.
+
+        Args:
+            passes: A list of optimization tasks.
+            options: Option for this flow controller.
+            controllers: Dictionary of controller callables keyed on flow controller alias.
+
+        Returns:
+            An instance of normalized flow controller.
+        """
+        if None in controllers.values():
+            raise PassManagerError("The controller needs a callable. Value cannot be None.")
+
+        if isinstance(passes, BaseController):
+            instance = passes
+        else:
+            instance = FlowControllerLinear(passes, options=options)
+
+        if controllers:
+            # Alias in higher hierarchy becomes outer controller.
+            for alias in cls.hierarchy[::-1]:
+                if alias not in controllers:
+                    continue
+                class_type = cls.registered_controllers[alias]
+                init_kwargs = {
+                    "options": options,
+                    alias: controllers.pop(alias),
+                }
+                instance = class_type([instance], **init_kwargs)
+
+        return instance
+
+    @classmethod
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg=(
+            "Controller factory method is deprecated and managing the custom flow controllers "
+            "with alias no longer helps building the task pipeline. "
+            "Controllers must be explicitly instantiated and appended to the pipeline."
+        ),
+    )
+    def add_flow_controller(
+        cls,
+        name: str,
+        controller: Type[BaseController],
+    ):
+        """Adds a flow controller.
+
+        Args:
+            name: Alias of controller class in the namespace.
+            controller: Flow controller class.
+        """
+        cls.registered_controllers[name] = controller
+        if name not in cls.hierarchy:
+            cls.hierarchy.append(name)
+
+    @classmethod
+    @deprecate_func(
+        since="0.45.0",
+        additional_msg=(
+            "Controller factory method is deprecated and managing the custom flow controllers "
+            "with alias no longer helps building the task pipeline. "
+            "Controllers must be explicitly instantiated and appended to the pipeline."
+        ),
+    )
+    def remove_flow_controller(
+        cls,
+        name: str,
+    ):
+        """Removes a flow controller.
+
+        Args:
+            name: Alias of the controller to remove.
+
+        Raises:
+            KeyError: If the controller to remove was not registered.
+        """
+        if name not in cls.hierarchy:
+            raise KeyError("Flow controller not found: %s" % name)
+        del cls.registered_controllers[name]
+        cls.hierarchy.remove(name)

qiskit/passmanager/passmanager.py

@@ -0,0 +1,317 @@
+# 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.
+
+"""Manager for a set of Passes and their scheduling during transpilation."""
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable
+from itertools import chain
+from typing import Any
+
+import dill
+
+from qiskit.tools.parallel import parallel_map
+from .base_tasks import Task, PassManagerIR
+from .exceptions import PassManagerError
+from .flow_controllers import FlowControllerLinear
+from .compilation_status import PropertySet, WorkflowStatus, PassManagerState
+
+logger = logging.getLogger(__name__)
+
+
+class BasePassManager(ABC):
+    """Pass manager base class."""
+
+    def __init__(
+        self,
+        tasks: Task | list[Task] = (),
+        max_iteration: int = 1000,
+    ):
+        """Initialize an empty pass manager object.
+
+        Args:
+            tasks: A pass set to be added to the pass manager schedule.
+            max_iteration: The maximum number of iterations the schedule will be looped if the
+                condition is not met.
+        """
+        self._tasks = []
+        self.max_iteration = max_iteration
+        self.property_set = PropertySet()
+
+        if tasks:
+            self.append(tasks)
+
+    def append(
+        self,
+        tasks: Task | list[Task],
+    ) -> None:
+        """Append tasks to the schedule of passes.
+
+        Args:
+            tasks: A set of pass manager tasks to be added to schedule.
+
+        Raises:
+            TypeError: When any element of tasks is not a subclass of passmanager Task.
+        """
+        if isinstance(tasks, Task):
+            tasks = [tasks]
+        if any(not isinstance(t, Task) for t in tasks):
+            raise TypeError("Added tasks are not all valid pass manager task types.")
+
+        self._tasks.append(tasks)
+
+    def replace(
+        self,
+        index: int,
+        tasks: Task | list[Task],
+    ) -> None:
+        """Replace a particular pass in the scheduler.
+
+        Args:
+            index: Task index to replace, based on the position in :meth:`tasks`
+            tasks: A set of pass manager tasks to be added to schedule.
+
+        Raises:
+            TypeError: When any element of tasks is not a subclass of passmanager Task.
+            PassManagerError: If the index is not found.
+        """
+        try:
+            self._tasks[index] = tasks
+        except IndexError as ex:
+            raise PassManagerError(f"Index to replace {index} does not exists") from ex
+
+    def remove(self, index: int) -> None:
+        """Removes a particular pass in the scheduler.
+
+        Args:
+            index: Pass index to remove, based on the position in :meth:`passes`.
+
+        Raises:
+            PassManagerError: If the index is not found.
+        """
+        try:
+            del self._tasks[index]
+        except IndexError as ex:
+            raise PassManagerError(f"Index to replace {index} does not exists") from ex
+
+    def __setitem__(self, index, item):
+        self.replace(index, item)
+
+    def __len__(self):
+        return len(self._tasks)
+
+    def __getitem__(self, index):
+        new_passmanager = self.__class__(max_iteration=self.max_iteration)
+        new_passmanager._tasks = self._tasks[index]
+        return new_passmanager
+
+    def __add__(self, other):
+        new_passmanager = self.__class__(max_iteration=self.max_iteration)
+        new_passmanager._tasks = self._tasks
+        if isinstance(other, self.__class__):
+            new_passmanager._tasks += other._tasks
+            return new_passmanager
+        else:
+            try:
+                new_passmanager.append(other)
+                return new_passmanager
+            except PassManagerError as ex:
+                raise TypeError(
+                    "unsupported operand type + for %s and %s" % (self.__class__, other.__class__)
+                ) from ex
+
+    @abstractmethod
+    def _passmanager_frontend(
+        self,
+        input_program: Any,
+        **kwargs,
+    ) -> PassManagerIR:
+        """Convert input program into pass manager IR.
+
+        Args:
+            in_program: Input program.
+
+        Returns:
+            Pass manager IR.
+        """
+        pass
+
+    @abstractmethod
+    def _passmanager_backend(
+        self,
+        passmanager_ir: PassManagerIR,
+        in_program: Any,
+        **kwargs,
+    ) -> Any:
+        """Convert pass manager IR into output program.
+
+        Args:
+            passmanager_ir: Pass manager IR after optimization.
+            in_program: The input program, this can be used if you need
+                any metadata about the original input for the output.
+                It should not be mutated.
+
+        Returns:
+            Output program.
+        """
+        pass
+
+    def run(
+        self,
+        in_programs: Any | list[Any],
+        callback: Callable = None,
+        **kwargs,
+    ) -> Any:
+        """Run all the passes on the specified ``in_programs``.
+
+        Args:
+            in_programs: Input programs to transform via all the registered passes.
+                A single input object cannot be a Python builtin list object.
+                A list object is considered as multiple input objects to optimize.
+            callback: A callback function that will be called after each pass execution. The
+                function will be called with 4 keyword arguments::
+
+                    task (GenericPass): the pass being run
+                    passmanager_ir (Any): depending on pass manager subclass
+                    property_set (PropertySet): the property set
+                    running_time (float): the time to execute the pass
+                    count (int): the index for the pass execution
+
+                The exact arguments pass expose the internals of the pass
+                manager and are subject to change as the pass manager internals
+                change. If you intend to reuse a callback function over
+                multiple releases be sure to check that the arguments being
+                passed are the same.
+
+                To use the callback feature you define a function that will
+                take in kwargs dict and access the variables. For example::
+
+                    def callback_func(**kwargs):
+                        task = kwargs['task']
+                        passmanager_ir = kwargs['passmanager_ir']
+                        property_set = kwargs['property_set']
+                        running_time = kwargs['running_time']
+                        count = kwargs['count']
+                        ...
+
+            kwargs: Arbitrary arguments passed to the compiler frontend and backend.
+
+        Returns:
+            The transformed program(s).
+        """
+        if not self._tasks and not kwargs and callback is None:
+            return in_programs
+
+        is_list = True
+        if not isinstance(in_programs, list):
+            in_programs = [in_programs]
+            is_list = False
+
+        if len(in_programs) == 1:
+            out_program = _run_workflow(
+                program=in_programs[0],
+                pass_manager=self,
+                callback=callback,
+                **kwargs,
+            )
+            if is_list:
+                return [out_program]
+            return out_program
+
+        del callback
+        del kwargs
+
+        # Pass manager may contain callable and we need to serialize through dill rather than pickle.
+        # See https://github.com/Qiskit/qiskit-terra/pull/3290
+        # Note that serialized object is deserialized as a different object.
+        # Thus, we can resue the same manager without state collision, without building it per thread.
+        return parallel_map(
+            _run_workflow_in_new_process,
+            values=in_programs,
+            task_kwargs={"pass_manager_bin": dill.dumps(self)},
+        )
+
+    def to_flow_controller(self) -> FlowControllerLinear:
+        """Linearize this manager into a single :class:`.FlowControllerLinear`,
+        so that it can be nested inside another pass manager.
+
+        Returns:
+            A linearized pass manager.
+        """
+        flatten_tasks = list(self._flatten_tasks(self._tasks))
+        return FlowControllerLinear(flatten_tasks)
+
+    def _flatten_tasks(self, elements: Iterable | Task) -> Iterable:
+        """A helper method to recursively flatten a nested task chain."""
+        if not isinstance(elements, Iterable):
+            return [elements]
+        return chain(*map(self._flatten_tasks, elements))
+
+
+def _run_workflow(
+    program: Any,
+    pass_manager: BasePassManager,
+    **kwargs,
+) -> Any:
+    """Run single program optimization with a pass manager.
+
+    Args:
+        program: Arbitrary program to optimize.
+        pass_manager: Pass manager with scheduled passes.
+        **kwargs: Keyword arguments for IR conversion.
+
+    Returns:
+        Optimized program.
+    """
+    flow_controller = pass_manager.to_flow_controller()
+    initial_status = WorkflowStatus()
+
+    passmanager_ir = pass_manager._passmanager_frontend(
+        input_program=program,
+        **kwargs,
+    )
+    passmanager_ir, _ = flow_controller.execute(
+        passmanager_ir=passmanager_ir,
+        state=PassManagerState(
+            workflow_status=initial_status,
+            property_set=pass_manager.property_set,
+        ),
+        callback=kwargs.get("callback", None),
+    )
+    out_program = pass_manager._passmanager_backend(
+        passmanager_ir=passmanager_ir,
+        in_program=program,
+        **kwargs,
+    )
+
+    return out_program
+
+
+def _run_workflow_in_new_process(
+    program: Any,
+    pass_manager_bin: bytes,
+) -> Any:
+    """Run single program optimization in new process.
+
+    Args:
+        program: Arbitrary program to optimize.
+        pass_manager_bin: Binary of the pass manager with scheduled passes.
+
+    Returns:
+          Optimized program.
+    """
+    return _run_workflow(
+        program=program,
+        pass_manager=dill.loads(pass_manager_bin),
+    )