{"id":9263,"library":"pytket","title":"TKET Compiler and Python API (pytket)","description":"pytket is a Python module that provides an interface to TKET, a hardware-agnostic quantum computing toolkit and optimizing compiler developed by Quantinuum. It enables users to design, optimize, and execute quantum circuits on various backend devices and simulators. The library is actively maintained with frequent minor version releases, typically on a monthly cycle, and occasional patch releases for bug fixes, focusing on superior performance for NISQ (noisy intermediate-scale quantum) devices.","status":"active","version":"2.16.0","language":"en","source_language":"en","source_url":"https://github.com/quantinuum/tket","tags":["quantum computing","quantum compiler","quantum circuit","optimization","NISQ","physics"],"install":[{"cmd":"pip install pytket","lang":"bash","label":"Install core pytket library"},{"cmd":"pip install pytket-qiskit pytket-cirq","lang":"bash","label":"Install common extension modules (e.g., for Qiskit, Cirq integration)"}],"dependencies":[{"reason":"Required for pytket versions >= 1.24.0. Older Python versions will install older pytket versions.","package":"Python 3.10+","optional":false},{"reason":"For integration with Qiskit, including conversion and backend access.","package":"pytket-qiskit","optional":true},{"reason":"For integration with Cirq, including conversion and backend access.","package":"pytket-cirq","optional":true},{"reason":"For integration with Quantinuum devices and simulators.","package":"pytket-quantinuum","optional":true}],"imports":[{"note":"The primary class for building and manipulating quantum circuits.","symbol":"Circuit","correct":"from pytket import Circuit"},{"note":"Used to specify a wide variety of quantum operations.","symbol":"OpType","correct":"from pytket.circuit import OpType"},{"note":"Provides access to circuit transformation and optimization passes.","symbol":"Transform","correct":"from pytket.transform import Transform"},{"note":"Example of importing a backend from an extension module. Extension modules (e.g., pytket-qiskit) must be installed separately.","symbol":"AerBackend","correct":"from pytket.extensions.qiskit import AerBackend"}],"quickstart":{"code":"from pytket import Circuit\nfrom pytket.extensions.qiskit import AerBackend\n\n# 1. Create a quantum circuit (Bell state)\ncirc = Circuit(2) # 2 qubits\ncirc.H(0)        # Hadamard on qubit 0\ncirc.CX(0, 1)    # CNOT with control 0, target 1\n\n# 2. Compile the circuit for a backend (using Qiskit Aer simulator for demonstration)\n# Note: pytket-qiskit extension must be installed for AerBackend\nbackend = AerBackend()\ncompiled_circ = backend.get_compiled_circuit(circ)\n\n# 3. Execute the circuit\n# For real devices, this may involve authentication (e.g., IBMQ credentials)\n# For local simulators, no special setup is typically needed.\n# We'll run 100 shots and retrieve measurement counts.\nhandle = backend.process_circuit(compiled_circ, n_shots=100)\nresult = backend.get_result(handle)\n\nprint(f\"Circuit: {circ}\")\nprint(f\"Compiled Circuit: {compiled_circ}\")\nprint(f\"Measurement counts: {result.get_counts()}\")","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the official pytket user guide and changelog for migration instructions when upgrading major versions.","message":"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.","severity":"breaking","affected_versions":"0.x.y -> 1.x.y, 1.x.y -> 2.x.y"},{"fix":"Upgrade your Python environment to 3.10 or newer before installing pytket. Ensure pip is also up-to-date (`pip install --upgrade pip`).","message":"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.","severity":"breaking","affected_versions":"pytket >= 1.24.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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).","error":"ImportError: DLL load failed: The specified module could not be found."},{"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.","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.","error":"RuntimeError: Cannot merge circuits as both contain unit: l[0]."},{"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.","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).","error":"pip install pytket results in an outdated version, despite a newer version being on PyPI."},{"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.","cause":"This is a known, currently open issue specific to certain combinations of placement passes and backend configurations within the `pytket-qiskit` extension.","error":"The `pytket.extensions.qiskit.PlacementPass` on a `SquareGrid` architecture causes `RuntimeError` when running on `AerBackend`."}]}