---
title: passmanager (latest version)
description: API reference for qiskit.passmanager in the latest version of qiskit
source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/qiskit/passmanager
---

# Passmanager

`qiskit.passmanager`

## Overview

The Qiskit pass manager is inspired by the [LLVM compiler](https://llvm.org/). The compiler infrastructure separates responsibilities into three main components: tasks, flow controllers, and pass managers.

A compilation pipeline executes a sequence of [`Task`](/docs/api/qiskit/qiskit.passmanager.Task "qiskit.passmanager.Task") objects, each of which takes an intermediate representation (IR) as input, performs work, and returns a, possibly different, IR as output. Where [`Task`](/docs/api/qiskit/qiskit.passmanager.Task "qiskit.passmanager.Task") defines the interface, an atomic task is a *pass*, which subclasses [`GenericPass`](/docs/api/qiskit/qiskit.passmanager.GenericPass "qiskit.passmanager.GenericPass") and implements its abstract [`run()`](/docs/api/qiskit/qiskit.passmanager.GenericPass#run "qiskit.passmanager.GenericPass.run") method. This is the class that should be used as base class when implementing a custom compiler pass.

Flow controllers provide execution models for a set of tasks. The simplest flow controller is a [`FlowControllerLinear`](/docs/api/qiskit/qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear"), which simply executes a set of tasks in a linear sequence. More advanced flow controllers include loops or conditional execution. These are, for example, used in Qiskit’s preset transpiler pipelines for higher optimization levels where optimizations are run until a convergence criterion is met.

Pass managers are responsible for managing the tasks, including scheduling required analyses and enabling modification of the task sequence by the user. Qiskit provides two IR-generic pass managers in this module, and a pass manager specialized to [`DAGCircuit`](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") as IR in [`qiskit.transpiler`](/docs/api/qiskit/transpiler#module-qiskit.transpiler "qiskit.transpiler"). The IR-generic ones are:

- [`BasePassManager`](/docs/api/qiskit/qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager"): a pass manager with fixed IR. This pass manager allows modifying the set of tasks to be run and supports parallel execution of multiple inputs by means of [`parallel_map()`](/docs/api/qiskit/utils#qiskit.utils.parallel_map "qiskit.utils.parallel_map"). This class has support for additional conversion of an input program representation to the internal IR, and a conversion to an output program format.

  The [`BasePassManager`](/docs/api/qiskit/qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager") is the base class for Qiskit’s preset pass managers for [`DAGCircuit`](/docs/api/qiskit/qiskit.dagcircuit.DAGCircuit "qiskit.dagcircuit.DAGCircuit") transpilation, such as returned by [`generate_preset_pass_manager()`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager "qiskit.transpiler.generate_preset_pass_manager"). There, implicit conversions to and from [`QuantumCircuit`](/docs/api/qiskit/qiskit.circuit.QuantumCircuit "qiskit.circuit.QuantumCircuit") as input and output program format are used.

- [`MultiStagePassManager`](/docs/api/qiskit/qiskit.passmanager.MultiStagePassManager "qiskit.passmanager.MultiStagePassManager"): a staged pass manager where each stage can preserve or lower the IR. A stage is defined by a [`Task`](/docs/api/qiskit/qiskit.passmanager.Task "qiskit.passmanager.Task") or an iterable thereof, which can also be grouped inside a [`BasePassManager`](/docs/api/qiskit/qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager"). The stages must be set up such that the output IR of the current stage matches the input IR of the next stage, there are (currently) no automatic translations.

Pass managers also provide infrastructure to pass a [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") with context-information through every task and a callback function for introspection. The [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet") is a free-form dictionary, which can be populated and read by a pass during execution, or read by a flow-controller to control pass execution. The property set is portable and handed over from pass to pass at execution. In addition to the property set, tasks also receive a [`WorkflowStatus`](/docs/api/qiskit/qiskit.passmanager.WorkflowStatus "qiskit.passmanager.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 [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet"), which contains information about the IR being optimized.

The callback is called by [`GenericPass`](/docs/api/qiskit/qiskit.passmanager.GenericPass "qiskit.passmanager.GenericPass") instances expecting the following signature:

```python
def callback(
    *,
    task: Task[IR_IN, IR_OUT],
    passmanager_ir: IR_OUT,
    property_set: PropertySet,
    running_time: float,
    count: int
) -> None:
    ...
```

Note that this signature differs slightly for passes and pass managers defined in the [`qiskit.transpiler`](/docs/api/qiskit/transpiler#module-qiskit.transpiler "qiskit.transpiler") module.

## Examples

We look into a toy optimization task, namely, preparing a row of numbers and removing a digit if the number is five. Such a 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.

```python
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 `_passmanager_frontend()` method defines the conversion from the input data to IR, and `_passmanager_backend()` defines the conversion from the IR to output data. The pass manager backend is also given an `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.

```python
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 a random row of numbers returns new numbers that don’t contain five.

```python
pm = ToyPassManager()
pm.append(task)

pm.run([123456789, 45654, 36785554])
```

Output:

```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.

```python
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 [`ConditionalController`](/docs/api/qiskit/qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController") that runs the stored tasks only when the condition is met.

```python
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.

```python
pm = ToyPassManager()
pm.append(analysis_task)
pm.append(conditional_task)

pm.run([123456789, 45654, 36785554])
```

Output:

```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 in the following class API documentation.

## Interface

### Passes

|                                                                                                     |                                           |
| --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| [`GenericPass`](/docs/api/qiskit/qiskit.passmanager.GenericPass "qiskit.passmanager.GenericPass")() | Base class of a single pass manager task. |
| [`Task`](/docs/api/qiskit/qiskit.passmanager.Task "qiskit.passmanager.Task")()                      | An interface of the pass manager task.    |

### Pass managers

|                                                                                                                                             |                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [`BasePassManager`](/docs/api/qiskit/qiskit.passmanager.BasePassManager "qiskit.passmanager.BasePassManager")(\[tasks, max\_iteration])     | Pass manager base class.                       |
| [`MultiStagePassManager`](/docs/api/qiskit/qiskit.passmanager.MultiStagePassManager "qiskit.passmanager.MultiStagePassManager")(\*\*stages) | A staged pass manager supporting multiple IRs. |

### Flow controllers

|                                                                                                                                                           |                                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`BaseController`](/docs/api/qiskit/qiskit.passmanager.BaseController "qiskit.passmanager.BaseController")(\[options])                                    | Base class of controller.                                                                                     |
| [`FlowControllerLinear`](/docs/api/qiskit/qiskit.passmanager.FlowControllerLinear "qiskit.passmanager.FlowControllerLinear")(\[tasks, options])           | A standard flow controller that runs tasks one after the other.                                               |
| [`ConditionalController`](/docs/api/qiskit/qiskit.passmanager.ConditionalController "qiskit.passmanager.ConditionalController")(\[tasks, condition, ...]) | A flow controller runs the pipeline once if the condition is true, or does nothing if the condition is false. |
| [`DoWhileController`](/docs/api/qiskit/qiskit.passmanager.DoWhileController "qiskit.passmanager.DoWhileController")(\[tasks, do\_while, options])         | Run the given tasks in a loop until the `do_while` condition on the property set becomes `False`.             |

### Compilation state

|                                                                                                                                                   |                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`PropertySet`](/docs/api/qiskit/qiskit.passmanager.PropertySet "qiskit.passmanager.PropertySet")                                                 | A default dictionary-like object.                                                  |
| [`WorkflowStatus`](/docs/api/qiskit/qiskit.passmanager.WorkflowStatus "qiskit.passmanager.WorkflowStatus")(\[count, completed\_passes, ...])      | Collection of compilation status of workflow, i.e. pass manager run.               |
| [`PassManagerState`](/docs/api/qiskit/qiskit.passmanager.PassManagerState "qiskit.passmanager.PassManagerState")(workflow\_status, property\_set) | A portable container object that pass manager tasks communicate through generator. |

### Exceptions

#### PassManagerError

*exception* `qiskit.passmanager.PassManagerError(*message)`

[GitHub](https://github.com/Qiskit/qiskit/tree/stable/2.5/qiskit/passmanager/exceptions.py#L18-L19)

Bases: [`QiskitError`](/docs/api/qiskit/exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError")

Pass manager error.

Set the error message.