User guide

This guide covers the basics of using Qdislib, as well as details on the main algorithms included in the library for circuit partitioning, simulation, and distributed execution.

Qdislib supports gate cutting and wire cutting techniques to decompose large quantum circuits and execute them on distributed and heterogeneous environments. All computations are parallelized transparently using PyCOMPSs.

Example

Below is a basic example demonstrating how to construct a quantum circuit and apply gate cutting using Qdislib:

from qibo import models, gates
import Qdislib as qd  # qd is Qdislib

# Build a 10-qubit circuit
def entire_circuit():
    c = models.Circuit(10)
    c.add(gates.H(0))
    c.add(gates.RX(1, 0.3))
    c.add(gates.RY(2, 0.4))
    c.add(gates.RZ(3, 0.5))
    c.add(gates.CZ(0, 1))
    c.add(gates.CZ(1, 2))
    c.add(gates.CZ(2, 3))
    c.add(gates.CZ(3, 4))
    c.add(gates.CZ(4, 5))
    c.add(gates.CZ(5, 6))
    return c

circuit = entire_circuit()

# Find a gate to cut
cut = qd.find_cut(circuit)

# Apply gate cutting
result = qd.gate_cutting(circuit, cut)
print("Reconstructed expectation value:", result)

It is worth noting that, although the code above looks completely sequential, all Qdislib algorithms and operations are internally parallelized using PyCOMPSs.

How to run Qdislib

Qdislib can be installed and used as a regular Python library. However, because it relies on PyCOMPSs to parallelize its tasks, you must execute Qdislib applications with the runcompss or enqueue_compss command-line tools provided by PyCOMPSs:

runcompss my_Qdislib_application.py

Alternatively, inside Jupyter notebooks, you can use the ipycompss interface:

import ipycompss
ipycompss.start(project="project.xml", resources="resources.xml", monitor=True, graph=True)

Refer to the quickstart guide and examples for details on PyCOMPSs setup and configuration.

Algorithms

Qdislib includes two core circuit cutting strategies:

  • Gate Cutting: Cuts selected two-qubit gates to divide a circuit into smaller, independently executable subcircuits. These are then simulated and post-processed to reconstruct the expectation value of the original circuit.

  • Wire Cutting: Cuts “wires” (qubit connections) between gates to disconnect logical qubits. This requires more advanced processing, often involving state preparation and postselection logic.

Find Cut Function

To simplify the cutting process, Qdislib provides the find_cut utility to automatically suggest suitable locations for gate or wire cutting:

cut = qd.find_cut(circuit)                       # Gate cand wire utting suggestion
wire_cut = qd.find_cut(circuit, gate_cut=False)  # Wire cutting suggestion
gate_cut = qd.find_cut(circuit, wire_cut=False)  # Gate cutting suggestion

The returned list contains candidate gate names or gate pairs that are suitable cut points.

Subcircuit Generation Only

In addition to executing the full gate or wire cutting workflow, Qdislib also allows users to only extract the subcircuits without performing expectation value reconstruction. This enables:

  • Custom execution of subcircuits (e.g., submitting to specific quantum devices).

  • Saving/loading subcircuits for delayed simulation.

  • Manual post-processing outside Qdislib.

You can generate and retrieve subcircuits using:

# For gate cutting
subcircuits = qd.gate_cutting_subcircuits(circuit, gate_cut)

# For wire cutting
subcircuits = qd.wire_cutting_subcircuits(circuit, wire_cut)

The returned subcircuits list contains all subcomponents resulting from the cutting process. These can be simulated independently using Qiskit, Qibo, or submitted to QPUs.

This modular structure gives users fine-grained control over hybrid quantum-classical workflows.

Resource Allocation

Qdislib is designed to run efficiently across CPUs, GPUs, and quantum devices depending on the user’s configuration and available resources. By default, simulation is performed on CPU backends.

Using GPUs

Qdislib includes support for GPU-accelerated execution using cuQuantum (with Qiskit) and Qibojit (with Qibo). GPU support is available for the following algorithms:

  • gate_cutting

  • wire_cutting

To enable GPU execution, set the following variable before running your application:

reconstruction = qd.gate_cutting(circuit, cut, gpu=True, gpu_min_qubits=18)

When enabled, Qdislib offloads eligible subcircuit simulations to GPU, while still coordinating the overall computation through CPU. This GPU usage is transparent to the user: memory transfers are handled internally and automatically