TKET Compiler and Python API (pytket)

Common errors

• ImportError: DLL load failed: The specified module could not be found.

  cause This error, particularly on Windows with older Python versions (e.g., 3.7, 3.8), often indicates issues with underlying C++ dependencies that pytket relies on (e.g., related to the `pytket._tket.pauli` module).
  fix Ensure you are using a supported Python version (>=3.10 for recent pytket versions). If the issue persists, consider using an official Python distribution or a virtual environment, and ensure all system dependencies are correctly installed. For M1 Macs, `brew install openblas` and `pip install scipy` first may be required.

• RuntimeError: Cannot merge circuits as both contain unit: l[0].

  cause This error occurs when attempting to compose two circuits using methods like `Circuit.append()` or the `*` operator, and both circuits contain `UnitID`s (qubits/bits) with the same names, leading to ambiguity in composition.
  fix Before merging, rename the `UnitID`s in one or both circuits to ensure they are distinct using `Circuit.rename_units()`. Alternatively, use `Circuit.add_circuit()` for subcircuit insertion if unit unification is not desired.

• pip install pytket results in an outdated version, despite a newer version being on PyPI.

  cause Your current Python environment or `pip` version does not meet the minimum requirements of the latest `pytket` release (e.g., Python < 3.10 for pytket >= 1.24.0, or an old `pip` version).
  fix First, upgrade `pip`: `pip install --upgrade pip`. Then, ensure your Python version meets the `pytket` requirements (>=3.10 for current versions). Upgrade Python if necessary.

• The `pytket.extensions.qiskit.PlacementPass` on a `SquareGrid` architecture causes `RuntimeError` when running on `AerBackend`.

  cause This is a known, currently open issue specific to certain combinations of placement passes and backend configurations within the `pytket-qiskit` extension.
  fix Check the `pytket-qiskit` GitHub issues or documentation for updates on this specific bug. As a workaround, try using a different placement pass, or a different backend for compilation/simulation if possible.

Warnings

• breaking Major API changes occurred between pytket 0.x.y, 1.x.y, and 2.x.y. Code written for older major versions might not be compatible with newer ones.
  Fix: Refer to the official pytket user guide and changelog for migration instructions when upgrading major versions.
• breaking pytket versions 1.24.0 and above require Python 3.10 or higher. Older Python environments (e.g., 3.7, 3.8, 3.9) will only install older, incompatible versions of pytket.
  Fix: Upgrade your Python environment to 3.10 or newer before installing pytket. Ensure pip is also up-to-date (`pip install --upgrade pip`).
• gotcha Qubit ordering conventions in pytket differ from some other quantum SDKs (e.g., Qiskit). Circuits that appear identical in their gate sequence might correspond to different unitary operations when converted or interpreted across libraries.
  Fix: Be aware of qubit ordering when converting circuits to/from other frameworks or when comparing results. Consult the documentation for specific extension modules (e.g., pytket-qiskit) regarding conversion specifics.
• gotcha Most pytket extensions (e.g., `pytket-qiskit`, `pytket-cirq`, `pytket-quantinuum`) are separate pip packages and must be installed explicitly in addition to the core `pytket` library. Attempting to import components from an uninstalled extension will result in an ImportError.
  Fix: Install the necessary extension package using `pip install pytket-X` where `X` is the name of the extension (e.g., `pip install pytket-qiskit`).

Install

• pip install pytket Install core pytket library
• pip install pytket-qiskit pytket-cirq Install common extension modules (e.g., for Qiskit, Cirq integration)

Imports

• Circuit

  from pytket import Circuit

  The primary class for building and manipulating quantum circuits.
• OpType

  from pytket.circuit import OpType

  Used to specify a wide variety of quantum operations.
• Transform

  from pytket.transform import Transform

  Provides access to circuit transformation and optimization passes.
• AerBackend

  from pytket.extensions.qiskit import AerBackend

  Example of importing a backend from an extension module. Extension modules (e.g., pytket-qiskit) must be installed separately.

Quickstart

This quickstart demonstrates how to create a simple Bell state circuit, compile it using a Qiskit Aer simulator backend (requires `pytket-qiskit`), and then execute it to retrieve measurement counts. This illustrates the basic workflow of circuit construction, compilation, and execution.

from pytket import Circuit
from pytket.extensions.qiskit import AerBackend

# 1. Create a quantum circuit (Bell state)
circ = Circuit(2) # 2 qubits
circ.H(0)        # Hadamard on qubit 0
circ.CX(0, 1)    # CNOT with control 0, target 1

# 2. Compile the circuit for a backend (using Qiskit Aer simulator for demonstration)
# Note: pytket-qiskit extension must be installed for AerBackend
backend = AerBackend()
compiled_circ = backend.get_compiled_circuit(circ)

# 3. Execute the circuit
# For real devices, this may involve authentication (e.g., IBMQ credentials)
# For local simulators, no special setup is typically needed.
# We'll run 100 shots and retrieve measurement counts.
handle = backend.process_circuit(compiled_circ, n_shots=100)
result = backend.get_result(handle)

print(f"Circuit: {circ}")
print(f"Compiled Circuit: {compiled_circ}")
print(f"Measurement counts: {result.get_counts()}")