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,
    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`	`callable \| None`	`None`	Custom path-finding function for the SWAP router. Defaults to BFS if not provided
`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`
`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,
    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`	`callable \| None`	`None`	Custom path-finding function for the SWAP router
`strict`	`bool`	`True`	Strict adjacency mode for optimization passes
`epsilon`	`float`	`1e-9`	Near-zero rotation threshold for `MergeRotationsPass`
`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 on the circuit, the output is sized to max(layout.values()) + 1 physical qubits. 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.