Skip to content

Transpiler API Reference

The transpiler optimises circuits before execution by running a configurable sequence of transformation passes.

Built-in Passes

Pass Description
RemoveRedundantGates Cancels adjacent self-inverse gates (e.g. H-H, X-X).
MergeRotations Merges consecutive rotations around the same axis.

Usage

from hlquantum.transpiler import transpile, Transpiler
from hlquantum.transpiler import RemoveRedundantGates, MergeRotations

# Quick — use the default pass set
optimised = transpile(circuit)

# Custom — pick your own passes
t = Transpiler(passes=[RemoveRedundantGates(), MergeRotations()])
optimised = t.run(circuit)

Writing a Custom Pass

Subclass TranspilationPass and implement the run(circuit) method:

from hlquantum.transpiler import TranspilationPass

class MyPass(TranspilationPass):
    def run(self, circuit):
        # Return a new, optimised Circuit
        ...

Optimization and transpilation logic.

MergeRotations

Bases: TranspilationPass

Merges consecutive rotation gates on the same qubit.

Source code in hlquantum/transpiler.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class MergeRotations(TranspilationPass):
    """Merges consecutive rotation gates on the same qubit."""

    def run(self, circuit: QuantumCircuit) -> QuantumCircuit:
        if len(circuit.gates) < 2:
            return circuit

        new_circuit = QuantumCircuit(circuit.num_qubits)
        new_circuit.metadata = circuit.metadata.copy()

        i = 0
        while i < len(circuit.gates):
            gate = circuit.gates[i]
            if (gate.name in ("rx", "ry", "rz") and 
                i + 1 < len(circuit.gates) and 
                circuit.gates[i+1].name == gate.name and 
                circuit.gates[i+1].targets == gate.targets):

                from hlquantum.circuit import Parameter
                a, b = gate.params[0], circuit.gates[i+1].params[0]
                if isinstance(a, Parameter) or isinstance(b, Parameter):
                    new_circuit.gates.append(gate)
                    i += 1
                    continue

                import math
                new_angle = (a + b) % (2 * math.pi)
                if abs(new_angle) < 1e-10 or abs(new_angle - 2 * math.pi) < 1e-10:
                    i += 2
                    continue
                merged_gate = Gate(name=gate.name, targets=gate.targets, params=(new_angle,))
                new_circuit.gates.append(merged_gate)
                i += 2
                continue
            new_circuit.gates.append(gate)
            i += 1
        return new_circuit

RemoveRedundantGates

Bases: TranspilationPass

Removes consecutive gates that cancel out (e.g., H H).

Source code in hlquantum/transpiler.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
class RemoveRedundantGates(TranspilationPass):
    """Removes consecutive gates that cancel out (e.g., H H)."""

    def run(self, circuit: QuantumCircuit) -> QuantumCircuit:
        if not circuit.gates:
            return circuit

        new_circuit = QuantumCircuit(circuit.num_qubits)
        new_circuit.metadata = circuit.metadata.copy()

        i = 0
        while i < len(circuit.gates):
            gate = circuit.gates[i]
            if (i + 1 < len(circuit.gates) and 
                gate.name == circuit.gates[i+1].name and 
                gate.targets == circuit.gates[i+1].targets and 
                gate.controls == circuit.gates[i+1].controls and
                gate.name in ("h", "x", "y", "z", "cx", "cz", "swap")):
                i += 2
                continue
            new_circuit.gates.append(gate)
            i += 1
        return new_circuit

TranspilationPass

Bases: ABC

Base class for a transpilation pass.

Source code in hlquantum/transpiler.py 
11
12
13
14
15
16
17
class TranspilationPass(ABC):
    """Base class for a transpilation pass."""

    @abstractmethod
    def run(self, circuit: QuantumCircuit) -> QuantumCircuit:
        """Run the pass on the circuit."""
        ...

run(circuit) abstractmethod

Run the pass on the circuit.

Source code in hlquantum/transpiler.py 
14
15
16
17
@abstractmethod
def run(self, circuit: QuantumCircuit) -> QuantumCircuit:
    """Run the pass on the circuit."""
    ...

Transpiler

Orchestrates transpilation passes.

Source code in hlquantum/transpiler.py 
84
85
86
87
88
89
90
91
92
93
94
95
class Transpiler:
    """Orchestrates transpilation passes."""

    def __init__(self, passes: Optional[List[TranspilationPass]] = None) -> None:
        self.passes = passes or [RemoveRedundantGates(), MergeRotations()]

    def transpile(self, circuit: QuantumCircuit) -> QuantumCircuit:
        """Apply passes to the circuit."""
        optimized = circuit
        for p in self.passes:
            optimized = p.run(optimized)
        return optimized

transpile(circuit)

Apply passes to the circuit.

Source code in hlquantum/transpiler.py 
90
91
92
93
94
95
def transpile(self, circuit: QuantumCircuit) -> QuantumCircuit:
    """Apply passes to the circuit."""
    optimized = circuit
    for p in self.passes:
        optimized = p.run(optimized)
    return optimized

transpile(circuit)

Transpile using default transpiler.

Source code in hlquantum/transpiler.py 
101
102
103
def transpile(circuit: QuantumCircuit) -> QuantumCircuit:
    """Transpile using default transpiler."""
    return _default_transpiler.transpile(circuit)