Skip to main content

Current Release Coverage Status Python License

QCut

QCut Diagram

QCut is a quantum circuit knitting package built on top of qiskit for performing gate cuts and resetless wire cuts allowing simulation of larger quantum circuits on smaller quantum devices or simulators at the cost of a circuit overhead. QCut has been designed and tested to work with IQM's qpus, and the Finnish Quantum Computing Infrastructure (FiQCI).

QCut has been built at CSC - IT Center for Science (Finnish IT Center for Science).

See the documentation for the full usage guide, every option, examples and the theory behind the decompositions.

Installation

A UNIX-like system is needed, since PyMetis is used for automatic cut finding. On Windows use WSL.

uv pip install QCut
#or
uv add QCut

QCut does not install a simulator. The examples run on Qiskit Aer: uv pip install qiskit-aer.

For IQM hardware and fake backends, install the extra, which holds Qiskit below 2.2:

uv pip install "QCut[iqm]"

See Getting started for installing from source and other details.

Quick start

Mark where to cut, split the circuit, build the experiment for the observables wanted, run it, and put the expectation values back together:

import QCut as ck
from QCut import cut, cutGate
from qiskit import QuantumCircuit
from qiskit.circuit.library import CXGate
from qiskit_aer import AerSimulator

circuit = QuantumCircuit(5)
for qubit in range(5):
    circuit.ry(0.4 + 0.3 * qubit, qubit)
circuit.cx(0, 1)
circuit.append(**cutGate(CXGate(), 1, 2))  # a gate cut
circuit.cx(2, 3)
circuit.append(cut(), [3])  # a wire cut
circuit.cx(3, 4)

observables = ["IIIIZ", "IIZII", "ZZIII"]

cut_circuit = ck.get_locations_and_subcircuits(circuit)
# On a device with a coupling map, transpile the subcircuits for it here:
# cut_circuit = ck.transpile_circuits(cut_circuit, backend)
experiment = ck.get_experiment_circuits(cut_circuit, observables)

job = ck.submit_experiments(experiment, backend=AerSimulator(), shots=4096)
print(ck.estimate_expectation_values(job.result()))

[0.9204 0.3866 -0.0315], against exact values of [0.9211 0.3806 -0.0292].

find_cuts() finds and places cuts automatically instead, and ck.estimate_run(experiment) calculates what running an experiment will cost before submission. The usage guide goes through each step.

Several circuits at once

CutEstimator and CutQuasiSampler can run a list of cut circuits in one call, shaped like FiQCI-EMS's estimator and sampler:

from QCut import CutEstimator, CutOptions, find_cuts

ghz = QuantumCircuit(6)
ghz.h(0)
for qubit in range(5):
    ghz.cx(qubit, qubit + 1)
found = find_cuts(ghz, options=CutOptions(finder_num_partitions=2))

estimator = CutEstimator(AerSimulator())
job = estimator.run([cut_circuit, found], [observables, "ZZZZZZ"], shots=4096)
print(job.result().expectation_values())

[array([0.9160, 0.3853, -0.0328]), array(0.9999)]

CutQuasiSampler reconstructs the distribution over the qubits a circuit measured instead. See Primitives.

Why QCut

Where one of QCut's joint decompositions applies, the same cuts cost less than with IBM's qiskit-addon-cutting:

QCut addon
three wires cut at the same point γ 15, 240 subexperiments γ 64, 1024
three rotations crossing one split γ 7.16, 264 subexperiments γ 10.5, 432
an rzz and an rxx on each of three crossing pairs γ 115 γ 203

Where none applies the two agree exactly. benchmarks/QCutVsAddon.ipynb has the comparison, run with uv sync --group benchmark.

Documentation

fiqci.fi/QCut. To build it locally:

uv sync --group docs
cd docs
uv run sphinx-build -v -b html . build/sphinx/html -W

Acknowledgements

This project is built on top of Qiskit which is licensed under the Apache 2.0 license.

License

Apache 2.0 license

Metadata

Release files for QCut 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for QCut 2.5.0
File Size Uploaded Provenance Actions
qcut-2.5.0.tar.gz 2.7 MB Without provenance Details for qcut-2.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for QCut 2.5.0
File Interpreter ABI Platform Actions
qcut-2.5.0-py3-none-any.whl Python 3 none any Details for qcut-2.5.0-py3-none-any.whl

Total release size: 2.9 MB

Release files / qcut-2.5.0.tar.gz

Download URL qcut-2.5.0.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
878071266f533744545d6fb13a19a7083ccc4c305610a30ea21e9dc652ff6965
BLAKE2b-256 checksum
How to use checksums
df4e015033224007e894a4a4e6e78c173768027e22be91eed2162f253cf4ab60
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / qcut-2.5.0-py3-none-any.whl

Download URL qcut-2.5.0-py3-none-any.whl
Size 165.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1d5ecc93a2603a2a60fe84e2a788b2a3962c86bdde57718ea4d455ac07b33dc3
BLAKE2b-256 checksum
How to use checksums
8171ca949567fb3c5f527a884047a05e9598dd2c9d95030adac7f6fa62b36828
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for QCut 2.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page