Getting Started

Prerequisites

Tessera requires Python 3.10 or higher. The following packages are installed automatically as dependencies:

qiskit >= 2.3
qiskit-ibm-runtime >= 0.46
numpy >= 2.0
networkx >= 3.0

Installation

Clone the repository and install in editable mode:

git clone https://github.com/derrickboyer3/tessera.git
cd tessera
pip install -e .

To also install development dependencies for running tests and benchmarks:

pip install -e .[dev]

Your First Circuit

Once installed, you can transpile a circuit in a few lines. The transpile() function is the main entry point. Pass it a Qiskit circuit and a backend name and it handles everything else.

from qiskit import QuantumCircuit
from tessera.api.transpile import transpile

qc = QuantumCircuit(3)
qc.h(0)
qc.cx(0, 1)
qc.cx(1, 2)
qc.measure_all()

transpiled = transpile(qc, backend="IBM")
print(transpiled)

The output is a standard Qiskit QuantumCircuit with all gates decomposed to the IBM basis set (cx, rz, sx, x, u), qubits mapped to physical hardware positions, and routing SWAPs inserted where needed.

Choosing a Backend

Tessera supports three backends out of the box. Pass the backend name as a string:

# IBM basis: cx, rz, sx, x, u
transpiled = transpile(qc, backend="IBM")

# IonQ basis: rx, ry, rz, cx
transpiled = transpile(qc, backend="IONQ")

# Rigetti basis: rx, rz, cz
transpiled = transpile(qc, backend="RIGETTI")

Each backend uses a default coupling map based on real hardware. See the Backends page for the full list of devices and available coupling map overrides.

Overriding the Coupling Map

Each backend has a default coupling map but you can pass any named coupling map key or a custom TesseraCouplingMapregardless of which backend you're using. The backend controls gate decomposition, the coupling map controls routing topology. They are fully independent.

# Use any named coupling map key with any backend
transpiled = transpile(qc, backend="IBM", coupling_map="IBM_BRISBANE")
transpiled = transpile(qc, backend="IBM", coupling_map="IONQ_ARIA")

# Pass a custom coupling map
from tessera.hardware.coupling_map import TesseraCouplingMap

cm = TesseraCouplingMap(3, [(0, 1), (1, 0), (1, 2), (2, 1)])
transpiled = transpile(qc, backend="IBM", coupling_map=cm)

See the Coupling Maps page for the full list of available named keys.

Debug Mode

Pass debug_on=True to print per-pass gate counts as the circuit moves through the pipeline. Useful for understanding where gates are being added or removed.

transpiled = transpile(qc, backend="IBM", debug_on=True)

[Tessera] Running pass: BasisTranslationPass | Gates: 6
[Tessera] Finished pass: BasisTranslationPass | Gates: 14
[Tessera] Running pass: DenseLayoutPass | Gates: 14
...