qc-parallelizer 1.0.0__py3-none-any.whl

qc_parallelizer/__init__.py

@@ -0,0 +1 @@
+from .parallelizer import describe, execute, rearrange

qc_parallelizer/base.py

@@ -0,0 +1,35 @@
+import qiskit
+import qiskit.circuit
+import qiskit.providers
+import qiskit.result
+import qiskit.transpiler
+
+
+class Types:
+    Layout = list | dict | qiskit.transpiler.Layout
+    Backend = qiskit.providers.BackendV2
+    Result = qiskit.result.result.Result
+    Qubit = qiskit.circuit.Qubit
+
+
+class Exceptions:
+    class MissingParameter(Exception):
+        """A required parameter or part of a parameter is missing."""
+
+    class MissingInformation(Exception):
+        """
+        Required information is missing from data. For example, a circuit object was passed that
+        does not contain required metadata.
+        """
+
+    class ParameterConflict(Exception):
+        """Two or more passed parameters or parts of parameters are in mutual conflict."""
+
+    class CircuitBackendCompatibility(Exception):
+        """One or more given circuits cannot be executed on any given backends."""
+
+    class InvalidLayout(Exception):
+        """
+        One or more given circuit layouts are not valid. This can be due to incompleteness or
+        duplicate/overlapping definitions.
+        """

qc_parallelizer/generic/backendtools.py

@@ -0,0 +1,14 @@
+import qiskit.providers
+
+
+def get_neighbor_sets(backend: qiskit.providers.BackendV2) -> list[set[int]]:
+    """
+    Returns sets of physical neighbors in the backend's topology.
+    """
+
+    edges = backend.coupling_map.get_edges()
+    neighbors = [set() for _ in range(backend.num_qubits)]
+    for from_, to in edges:
+        neighbors[from_].add(to)
+        neighbors[to].add(from_)
+    return neighbors

qc_parallelizer/generic/circuittools.py

@@ -0,0 +1,240 @@
+import warnings
+from typing import Any
+
+import qiskit
+
+from . import layouts
+
+
+def count_gates(circuit: qiskit.QuantumCircuit):
+    """
+    Returns gate counts for each qubit in the given circuit, including measurements, but excluding
+    barriers. For example, for a circuit that looks like this:
+
+    ```
+         ┌───┐          ┌─┐
+    q_0: ┤ H ├───────■──┤M├───
+         ├───┤┌───┐┌─┴─┐└╥┘┌─┐
+    q_1: ┤ X ├┤ H ├┤ X ├─╫─┤M├
+         ├───┤└┬─┬┘└───┘ ║ └╥┘
+    q_2: ┤ H ├─┤M├───────╫──╫─
+         └───┘ └╥┘       ║  ║
+    c: 3/═══════╩════════╩══╩═
+                2        0  1
+    ```
+
+    The returned counts would look like this:
+
+    ```
+    {q_0: 3, q_1: 4, q_2: 2}
+    ```
+    """
+
+    gate_count = {qubit: 0 for qubit in circuit.qubits}
+    for operation, qubits, _ in circuit.data:
+        if operation.name == "barrier":
+            continue
+        for qubit in qubits:
+            gate_count[qubit] += 1
+    return gate_count
+
+
+def remove_idle_qubits(
+    circuit: qiskit.QuantumCircuit,
+    layout: layouts.QILayout | None = None,
+    allow_layout_replacement: bool = True,
+):
+    """
+    Removes idle qubits from a circuit. An idle qubit is a qubit that no operations, including
+    measurements, touch during the execution of the circuit. A layout for the circuit may also be
+    provided via the `layout` parameter, which will be updated to not contain the idle qubits.
+
+    Registers are immutable, so the operation is done by reconstructing the circuit gate by gate
+    with a reduced set of registers. Register names are lost in the process, and all remaining
+    active qubits are placed in a new quantum register.
+
+    If the circuit contains layout information, which is the case after transpilation, this function
+    will read that information to determine original register names. The resulting pruned circuit
+    will not contain layout information, since removing qubits violates some assumptions that other
+    functionality in Qiskit relies on. If you wish to force this function to ignore the layout data,
+    though, set `allow_layout_replacement` to `False` - this will use original register names, but
+    not the embedded layout.
+    """
+
+    if circuit.layout is not None and allow_layout_replacement:
+        layout = layouts.QILayout.from_circuit(circuit)
+
+    gate_count = count_gates(circuit)
+    idle_indices = {index for index, qubit in enumerate(circuit.qubits) if gate_count[qubit] == 0}
+    if len(idle_indices) == 0:
+        if layout is None:
+            return circuit
+        return circuit, layout
+
+    active_qubits = [
+        qubit for index, qubit in enumerate(circuit.qubits) if index not in idle_indices
+    ]
+
+    qreg_mapping = {}
+    new_qreg = qiskit.QuantumRegister(len(active_qubits))
+    for new_index, old_qubit in enumerate(active_qubits):
+        qreg_mapping[old_qubit] = new_qreg[new_index]
+
+    new_circuit = qiskit.QuantumCircuit(
+        new_qreg,
+        *circuit.cregs,
+        name=circuit.name,
+        global_phase=circuit.global_phase,
+        metadata=circuit.metadata,
+    )
+
+    for operation, qubits, clbits in circuit.data:
+        new_qubits = [qreg_mapping[qubit] for qubit in qubits if qubit in qreg_mapping]
+        if len(new_qubits) != len(qubits):
+            # Some operations need to be adjusted. Currently, this is only the case for barriers,
+            # since they "operate" on registers, but they do not affect a qubit's activity. So, if
+            # we encounter a barrier that was placed partially on active qubits, we lower the qubit
+            # count. This does not seem to have any side effects.
+
+            operation = operation.copy()
+            operation.num_qubits = len(new_qubits)
+        new_circuit.append(operation, new_qubits, clbits)
+
+    if layout is not None:
+        new_layout = layout.copy()
+
+        # Since we are dealing with indices, which, inherently, keep pointing at the same index even
+        # if the underlying array shifts, we must iterate in decreasing order to not invalidate
+        # later indices
+        modified = False
+        for index in sorted(idle_indices, reverse=True):
+            if index in new_layout.vkeys:
+                new_layout.remove(virt=index, decrement_keys=True)
+                modified = True
+
+        # If the layout was not modified, the new object is discarded and the old layout is returned
+        # instead - this avoids unnecessary copies in memory
+        return new_circuit, (new_layout if modified else layout)
+
+    return new_circuit
+
+
+def pad_to_width(circuit: qiskit.QuantumCircuit, width: int, in_place=True):
+    """
+    Pads a circuit with unused qubits to the specified width. The newly added padding qubits will be
+    placed in a new single quantum register, called "padding".
+    """
+
+    num_padding = width - circuit.num_qubits
+    if num_padding > 0:
+        if not in_place:
+            circuit = circuit.copy()
+        circuit.add_register(qiskit.QuantumRegister(num_padding, name="padding"))
+    return circuit
+
+
+def get_neighbor_sets(circuit: qiskit.QuantumCircuit) -> list[set[int]]:
+    """
+    Returns a list of sets of indices that represent all neighbors that qubits have in the given
+    circuit. For non-transpiled circuits, this may also mean other than physically immediate
+    neighbors - as a counterexample, a qubit that interacts with every other qubit will have all
+    other qubits in its neighbor set, even if that is physically impossible.
+
+    From another point of view, each set represents which qubits the corresponding qubit interacts
+    with during the execution of the circuit. Barriers are not counted as interaction.
+
+    For example, for the circuit below,
+
+    ```
+    q_0: ──■────■────■──
+           │  ┌─┴─┐  │
+    q_1: ──■──┤ X ├──┼──
+         ┌─┴─┐└───┘  │
+    q_2: ┤ X ├───────┼──
+         └───┘     ┌─┴─┐
+    q_3: ──────────┤ X ├
+                   └───┘
+    ```
+
+    this function returns
+
+    ```
+    [{1, 2, 3}, {0, 2}, {0, 1}, {0}]
+    ```
+    """
+
+    neighbors = [set() for _ in range(circuit.num_qubits)]
+    for operation, qubits, _ in circuit.data:
+        if operation.name == "barrier":
+            continue
+        qubit_indices = [circuit.find_bit(qb).index for qb in qubits]
+        for i, qb_i in enumerate(qubit_indices):
+            for qb_j in qubit_indices[i + 1 :]:
+                neighbors[qb_i].add(qb_j)
+                neighbors[qb_j].add(qb_i)
+    return neighbors
+
+
+def combine_for_backend(
+    circuits: list[tuple[qiskit.QuantumCircuit, Any, layouts.QILayout]],
+    backend: qiskit.providers.BackendV2,
+    name: str | None = None,
+):
+    """
+    This function combines multiple circuits into a larger host circuit in a backend-aware manner.
+    It requires a list of circuits, each of which must be represented by a (circuit, metadata,
+    layout) triple. The returned circuit's width is the same as the backend size.
+
+    The second element of the triple (metadata) is embedded into the circuit's "internal metadata".
+    This allows for internal metadata to be stored, such as the index of the circuit in some
+    original ordering, while preserving the actual metadata of the circuit.
+
+    The resulting circuit will contain metadata about the hosted circuits that the user should not
+    touch.
+    """
+
+    host_circuit = qiskit.QuantumCircuit(
+        backend.num_qubits,
+        metadata={"_hosted_circuits": []},
+        name=name or f"{backend.num_qubits}-qubit host",
+    )
+
+    for index, (subcircuit, metadata, layout) in enumerate(circuits):
+        creg_mapping = {}
+        for old_reg in subcircuit.cregs:
+            new_reg = qiskit.ClassicalRegister(old_reg.size, name=f"circ{index}.{old_reg.name}")
+            for i in range(old_reg.size):
+                creg_mapping[old_reg[i]] = new_reg[i]
+            host_circuit.add_register(new_reg)
+
+        host_circuit.metadata["_hosted_circuits"].append(
+            {
+                "name": subcircuit.name,
+                "original_metadata": subcircuit.metadata,
+                "internal_metadata": metadata,
+                "registers": {
+                    "clbit": {"sizes": {f"{reg.name}": reg.size for reg in subcircuit.cregs}},
+                },
+            },
+        )
+
+        qreg_indices = {
+            virt_qubit: subcircuit.find_bit(virt_qubit).index for virt_qubit in subcircuit.qubits
+        }
+        qreg_mapping = {
+            virt_qubit: host_circuit.qubits[layout[qreg_indices[virt_qubit]]]
+            for virt_qubit in subcircuit.qubits
+            if qreg_indices[virt_qubit] in layout
+        }
+
+        for operation, qubits, clbits in subcircuit.data:
+            if any(qubit not in qreg_mapping for qubit in qubits):
+                print(f"oh noes! instruction '{operation.name}' skipped")  # TODO: warn
+                continue
+            host_circuit.append(
+                operation,
+                [qreg_mapping[qubit] for qubit in qubits],
+                [creg_mapping[clbit] for clbit in clbits],
+            )
+
+    return host_circuit

qc_parallelizer/generic/generic.py

@@ -0,0 +1,45 @@
+def get_connected_qubit_sets(
+    neighbors: list[set[int]],
+) -> list[set[int]]:
+    """
+    Returns a list of sets of connected qubits. Qubits are separated into two different sets if
+    there is no path along the gates/couplers between them.
+
+    The `neighbors` parameter can be computed with `get_neighbot_sets` from either `circuit_tools`
+    or `backend_tools`, depending on which you are working with.
+    """
+
+    not_seen = set(range(len(neighbors)))
+    connected_sets = []
+
+    while len(not_seen) > 0:
+        seen = set()
+        search_set = {not_seen.pop()}
+        while len(search_set) > 0:
+            qubit_index = search_set.pop()
+            seen.add(qubit_index)
+            for nb in neighbors[qubit_index]:
+                if nb in not_seen:
+                    not_seen.remove(nb)
+                    search_set.add(nb)
+        connected_sets.append(seen)
+
+    return connected_sets
+
+
+def get_edges(
+    neighbors: list[set[int]],
+) -> set[tuple[int, int]]:
+    """
+    Returns a set of edges between qubits. If there is a gate (virtual) or coupler (physical)
+    between two qubits, there is an edge between them.
+
+    Edges are not duplicated for both directions, but only one edge is returned per edge with the
+    indices sorted in ascending order.
+    """
+
+    edges = set()
+    for from_, nb_set in enumerate(neighbors):
+        for to in nb_set:
+            edges.add((min(from_, to), max(from_, to)))
+    return edges

qc_parallelizer/generic/layouts.py

@@ -0,0 +1,246 @@
+import heapq
+import itertools
+from typing import Any
+
+import qiskit
+import qiskit.dagcircuit
+import qiskit.transpiler
+
+
+def layout_to_dict(
+    layout: qiskit.transpiler.Layout | list | dict | None,
+    circuit: qiskit.QuantumCircuit,
+) -> dict[int, int]:
+    """
+    Given a qubit layout of basically any form that Qiskit understands, this function normalizes it
+    into a dictionary that contains virtual-physical index mappings. That is, keys represent the
+    virtual qubit indices in the circuit, and values represent the physical qubit indices in the
+    backend.
+
+    Note that if the layout cannot be resolved, an empty dict (`{}`) is returned, not None.
+    """
+
+    if isinstance(layout, list):
+        # The Qiskit parser does not have information about registers, so we have to handle this
+        # case separately
+        # TODO: a list of something else, like Qubit objects, might also be given
+        layout = qiskit.transpiler.Layout.from_intlist(layout, *circuit.qregs)
+    else:
+        # If not a list, we let the default parser do its thing - this handles Layout objects,
+        # dicts, and other formats
+        layout = qiskit.compiler.transpiler._parse_initial_layout(layout)
+    # If there is no layout, return an empty mapping
+    if layout is None:
+        return {}
+    # Finally, return a mapping from virtual indices to physical indices
+    return {
+        circuit.find_bit(qubit).index: physical_index
+        for qubit, physical_index in layout.get_virtual_bits().items()
+    }
+
+
+class QILayout:
+    """
+    Class for representing one-to-one qubit index mappings between virtual circuit indices and
+    physical backend indices. Resembles Qiskit's Layout class, but has a restricted and improved
+    set of features.
+
+    Note on terminology: in this context, a layout contains a mapping. While the two terms might be
+    used interchangeably, "layout" refers to a one-to-one mapping that is specifically used to map
+    physical qubits to virtual qubits or vice versa, while "mapping" refers to the dictionary
+    instance(s) that represent it. At least in this class.
+    """
+
+    @classmethod
+    def from_layout(
+        cls,
+        layout: qiskit.transpiler.Layout | list | dict | None,
+        circuit: qiskit.QuantumCircuit,
+    ):
+        return cls(v2p=layout_to_dict(layout, circuit))
+
+    @classmethod
+    def from_circuit(cls, circuit: qiskit.QuantumCircuit):
+        initial_layout = circuit.layout.initial_virtual_layout()
+        return cls(
+            p2v={
+                p: circuit.layout.input_qubit_mapping[v]
+                for p, v in initial_layout.get_physical_bits().items()
+            },
+        )
+
+    @classmethod
+    def from_property_set(
+        cls,
+        property_set: dict[str, Any],
+        dag: qiskit.dagcircuit.DAGCircuit | None = None,
+    ):
+        if property_set["original_qubit_indices"] and property_set["layout"]:
+            return cls(
+                p2v={
+                    p: property_set["original_qubit_indices"][v]
+                    for p, v in property_set["layout"].get_physical_bits().items()
+                },
+            )
+        elif property_set["layout"] and dag is not None:
+            return cls(
+                p2v={
+                    p: dag.find_bit(qubit).index
+                    for p, qubit in property_set["layout"].get_physical_bits().items()
+                },
+            )
+        return cls()
+
+    @classmethod
+    def from_trivial(cls, num_qubits: int):
+        return cls(v2p={i: i for i in range(num_qubits)})
+
+    def __init__(self, v2p: dict[int, int] | None = None, p2v: dict[int, int] | None = None):
+        if v2p is None and p2v is None:
+            self._v2p: dict[int, int] = {}
+            self._p2v: dict[int, int] = {}
+        elif v2p is not None:
+            self._v2p: dict[int, int] = v2p
+            self._p2v: dict[int, int] = {}
+            for k, v in v2p.items():
+                if v is not None:
+                    self._p2v[v] = k
+        elif p2v is not None:
+            self._v2p: dict[int, int] = {}
+            self._p2v: dict[int, int] = p2v
+            for k, v in p2v.items():
+                if v is not None:
+                    self._v2p[v] = k
+        else:
+            raise ValueError("only up to one mapping may be provided as an initializer")
+
+    @property
+    def size(self):
+        return len(self._v2p)
+
+    @property
+    def vkeys(self):
+        return self._v2p.keys()
+
+    @property
+    def pkeys(self):
+        return self._p2v.keys()
+
+    @property
+    def v2p(self):
+        return {v: p for v, p in self._v2p.items() if self._p2v[p] is not None}
+
+    @property
+    def p2v(self):
+        return {p: v for p, v in self._p2v.items() if v is not None}
+
+    def copy(self):
+        return QILayout(p2v={**self._p2v})
+
+    def add(self, virt: int, phys: int):
+        self._v2p[virt] = phys
+        self._p2v[phys] = virt
+
+    def remove(
+        self,
+        virt: int | None = None,
+        phys: int | None = None,
+        decrement_keys: bool = False,
+    ):
+        if virt is not None:
+            phys = self._v2p[virt]
+        elif phys is not None:
+            virt = self._p2v[phys]
+        if virt in self._v2p:
+            del self._v2p[virt]
+        if phys in self._p2v:
+            del self._p2v[phys]
+        if decrement_keys:
+            new_v2p = {}
+            for other_virt in list(self._v2p.keys()):
+                if other_virt > virt:
+                    phys = self._v2p[other_virt]
+                    del self._v2p[other_virt]
+                    new_virt = other_virt - 1
+                    new_v2p[new_virt] = phys
+                    self._p2v[phys] = new_virt
+            self._v2p = {**self._v2p, **new_v2p}
+
+    def block(self, phys: int | set[int]):
+        """
+        Blocks a set of physical indices. The index will be reported as blocked when calling
+        `{is, get}_blocked` and will not appear on `v2p` or `p2v`.
+        """
+
+        if isinstance(phys, int):
+            phys = {phys}
+        for i in phys:
+            self._p2v[i] = None
+
+    def with_entry(self, virt: int, phys: int):
+        return QILayout(p2v={**self._p2v, phys: virt})
+
+    def with_blocked(self, phys: int | set[int]):
+        copy = self.copy()
+        copy.block(phys)
+        return copy
+
+    def is_blocked(self, phys: int):
+        return phys in self._p2v and self._p2v[phys] is None
+
+    def get_blocked(self):
+        return {p for p, v in self._p2v.items() if v is None}
+
+    def insert_blocked_indices(self, phys_set: set[int]):
+        """
+        Similar to `block`, but increments other physical indices as if these qubits were inserted
+        into the backend.
+        """
+        new_phys_indices = {p: p for p in self._p2v.keys()}
+
+        for b in sorted(phys_set):
+            for p in new_phys_indices:
+                if new_phys_indices[p] >= b:
+                    new_phys_indices[p] += 1
+
+        for p, v in sorted(self._p2v.items(), reverse=True):
+            del self._p2v[p]
+            self._p2v[new_phys_indices[p]] = v
+        for v, p in list(self._v2p.items()):
+            self._v2p[v] = new_phys_indices[p]
+        for p in phys_set:
+            self._p2v[p] = None
+
+    def to_qiskit_layout(self, circuit: qiskit.QuantumCircuit) -> qiskit.transpiler.Layout:
+        """
+        Converts to a Qiskit Layout object. Discards blocked indices.
+        """
+        return qiskit.transpiler.Layout({circuit.qubits[v]: p for v, p in self._v2p.items()})
+
+    def __repr__(self):
+        return f"QILayout(p2v={self._p2v.__repr__()})"
+
+    @staticmethod
+    def _p2v_sort_key(item):
+        p, v = item
+        return (v is None, p)
+
+    def __str__(self):
+        return (
+            "{"
+            + ", ".join(
+                (f"!p_{p}" if v is None else f"v_{v} ~ p_{p}")
+                for p, v in sorted(self._p2v.items(), key=self._p2v_sort_key)
+            )
+            + "}"
+        )
+
+    def _iqmstr(self):
+        return (
+            "{"
+            + ", ".join(
+                (f"!QB{p + 1}" if v is None else f"QB{p + 1}: {v}")
+                for p, v in sorted(self._p2v.items(), key=self._p2v_sort_key)
+            )
+            + "}"
+        )