Transpile API

Tessera exposes two ways to transpile a circuit. The top-level transpile() function for most use cases, and the TesseraTranspiler class directly if you need more control over the pipeline. Both produce the same output; transpile() is a thin convenience wrapper around TesseraTranspiler.

transpile()

The main entry point. Takes a Qiskit circuit and returns a transpiled Qiskit circuit ready for the target backend.

Signature

from tessera.api.transpile import transpile

transpile(
    circuit,
    backend="IBM",
    coupling_map=None,
    pathfinder=None,
    strict=True,
    epsilon=1e-9,
    optimization_iterations=1,
    max_iterations=1000,
    layout_algorithm="dense",
    debug_on=False
)

Parameters

Parameter	Type	Default	Description
`circuit`	`QuantumCircuit`	required	The Qiskit circuit to transpile
`backend`	`str`	`"IBM"`	Backend name. Must match a key in the backend registry. Available: `"IBM"`, `"IONQ"`, `"RIGETTI"`
`coupling_map`	`str \| TesseraCouplingMap \| None`	`None`	Hardware topology for routing. Pass a registry key string, a `TesseraCouplingMap` instance, or `None`to use the backend's default
`pathfinder`	`str \| callable \| None`	`None`	Routing algorithm for the swap router. Accepts a registered key (`"bfs"`, `"a_star"`, `"sabre"`), a custom pairwise callable `(start, end) -> list[int]`, or `None` (treated as `"bfs"`). See Routing Algorithms.
`strict`	`bool`	`True`	If `True`, optimization passes use strict adjacency mode. If `False`, commutative cancellation is allowed
`epsilon`	`float`	`1e-9`	Rotation angles below this threshold are treated as zero and dropped by `MergeRotationsPass`
`optimization_iterations`	`int`	`1`	Number of times to run the optimization loop (Cancel Adjacent + Merge Rotations). `1` is a single pass; any positive integer runs that many iterations; `-1` iterates until gate count stabilizes (bounded by `max_iterations`).
`max_iterations`	`int`	`1000`	Safety cap on loop iterations when `optimization_iterations=-1`. Ignored when a fixed positive integer is used.
`layout_algorithm`	`str \| callable`	`"dense"`	Layout algorithm for qubit placement. Accepts a registered key (`"dense"`, `"sabre"`, `"trivial"`) or a custom callable `(circuit, coupling_map) -> dict[int, int]`. See Layout Algorithms.
`debug_on`	`bool`	`False`	If `True`, prints per-pass gate counts and total transpile time to stdout

Returns

A transpiled QuantumCircuitwith all gates in the target backend's basis set, qubits mapped to physical positions, and routing SWAPs inserted where needed.

Raises

ValueError when backend is not a recognized registry key
ValueError when coupling_map is a string that is not a recognized registry key
ValueError when the circuit has more qubits than the coupling map supports

TesseraTranspiler

The class that owns the pass pipeline. transpile() constructs one of these internally. Use it directly if you want to build the pipeline once and run it multiple times, or if you want to inspect or modify the pass manager before executing.

Constructor

from tessera.transpiler import TesseraTranspiler

transpiler = TesseraTranspiler(
    circuit,
    coupling_map,
    backend="IBM",
    pathfinder=None,
    strict=True,
    epsilon=1e-9,
    optimization_iterations=1,
    max_iterations=1000,
    layout_algorithm="dense",
    debug_on=False
)

Constructor Parameters

Parameter	Type	Default	Description
`circuit`	`QuantumCircuit`	required	The Qiskit circuit to transpile
`coupling_map`	`TesseraCouplingMap`	required	Hardware topology. Must be a resolved `TesseraCouplingMap` instance because string keys are not accepted here
`backend`	`str`	`"IBM"`	Backend name matching a key in the backend registry
`pathfinder`	`str \| callable \| None`	`None`	Routing algorithm name, custom pairwise callable, or `None` (treated as `"bfs"`)
`strict`	`bool`	`True`	Strict adjacency mode for optimization passes
`epsilon`	`float`	`1e-9`	Near-zero rotation threshold for `MergeRotationsPass`
`optimization_iterations`	`int`	`1`	Optimization loop iteration count. `-1` runs until gate count stabilizes
`max_iterations`	`int`	`1000`	Safety cap on loop iterations when in convergence mode
`layout_algorithm`	`str \| callable`	`"dense"`	Layout algorithm name or custom callable
`debug_on`	`bool`	`False`	Per-pass debug logging

Methods

execute(): runs the full pass pipeline and returns a transpiled QuantumCircuit. Can be called multiple times on the same instance.

result = transpiler.execute()

Example: building and reusing a transpiler

from tessera.transpiler import TesseraTranspiler
from tessera.backends.coupling_maps import IBM_DEFAULT_COUPLING_MAP

transpiler = TesseraTranspiler(qc, IBM_DEFAULT_COUPLING_MAP, backend="IBM")

result1 = transpiler.execute()
# modify qc or inspect pass_manager here if needed
result2 = transpiler.execute()

Converters

If you need to work with Tessera's IR directly rather than going through the transpiler, the converter functions are available as a public utility.

from_qiskit(qc): converts a Qiskit QuantumCircuit to a TesseraCircuit. No layout is set on the output, so the circuit is in logical qubit space as written.

from tessera.converters import from_qiskit

tc = from_qiskit(qc)

to_qiskit(tc): converts a TesseraCircuit back to a Qiskit QuantumCircuit. If a layout is present, the output is sized to cover both the highest physical qubit in the layout and the highest qubit index referenced in the routed instructions, which matters when routing has pushed qubits onto positions higher than anything in a sparse layout. If no layout is present, it falls back to tc.num_qubits.

from tessera.converters import to_qiskit

qc = to_qiskit(tc)

Neither function performs any transformation. They are pure format conversions. All circuit transformations happen in passes.