Polypus

A distributed quantum computing library — Rust core, Python bindings, one API across simulators and real QPUs.

Table of Contents

• What is Polypus?
• Key Features
• Quickstart
• Installation
  • From source
  • CUNQA
• Usage
  • Running a Quantum Circuit
  • Distributing Shots Across Multiple QPUs
  • Training Variational Circuits
    • Differential Evolution
    • Particle Swarm Optimization
    • Quantum Natural Gradient
  • Training QML Classifiers
• Rust-Native Circuits
  • From Python
  • From Rust
  • QASM 2.0 Import
  • Performance Notes
• Project Architecture
• Documentation
• Citing Polypus
• Credits
• Dependencies
• License

What is Polypus?

Polypus is an open-source distributed quantum computing library: it runs quantum circuits and trains variational quantum algorithms (VQE, QAOA, QML, …) across one or many QPUs — simulated or real — without changing your circuit code. The core is written in Rust for performance and correctness; Python bindings (via PyO3) make it a drop-in accelerator for existing Qiskit workflows.

It is built for researchers and engineers who need to:

• scale shot execution and population-based training across multiple QPUs instead of one,
• swap between a local simulator, CESGA's CUNQA platform, or CESGA's QMIO real QPU without touching algorithm code,
• keep a Python-friendly API while getting Rust-level performance on the hot paths (parameter binding, batched simulation).

Status: Polypus is under active development (current version: 0.7.2) and is published on PyPI as polypus-quantum — pip install polypus-quantum (it imports as polypus). See Installation.

Key Features

• Multi-QPU execution — run any Qiskit QuantumCircuit, a native polypus.Circuit, or an OpenQASM 2.0 string, and automatically split shots across n_qpus to cut wall-clock time.
• Unified variational training — Differential Evolution, Particle Swarm Optimization, and Quantum Natural Gradient behind a single polypus.train() API; switch optimizers by changing one argument, populations are distributed across QPUs automatically.
• Backend-agnostic — local simulation via Qiskit Aer, CESGA's CUNQA distributed QPU platform, and CESGA's QMIO real quantum processor, the last reached through a pure-Rust, GIL-free ZeroMQ client.
• Native circuit engine (polypus-circuit) — optional pure-Rust circuit representation with OpenQASM 2.0 and QIR export; parameter binding is ~3x faster than Qiskit's assign_parameters and GIL-free, so concurrent evaluation threads bind candidates truly in parallel.
• A real Cargo workspace, not a monolith — circuits, simulator, optimizers, cost observables, physics layer, execution backends, orchestration, evaluation, and logger are independent, individually testable crates; the pure-Rust ones have no Python dependency and are usable from any Rust project.

Quickstart

Same project, three names — pip install polypus-quantum · import polypus · cargo add polypus. See Installation.

git clone https://github.com/Bahia-Software/polypus.git
cd polypus
bash install.sh --no-tests

import polypus

bell = polypus.Circuit(2).h(0).cx(0, 1).measure_all()
result = polypus.run_quantum_circuit(bell, shots=1000, infrastructure="local")
print(result.counts[0])  # first (here, only) QPU, e.g. {'00': 512, '11': 488}
print(result.merged_counts)  # total over every QPU — the one to read with n_qpus > 1

See Usage for Qiskit circuits, multi-QPU distribution, and variational training.

Installation

Same project, three names — pip install polypus-quantum · import polypus · cargo add polypus. The name polypus on PyPI is taken by an unrelated project, so the Python distribution is published as polypus-quantum; the Python import name and the Rust crate both stay polypus.

The recommended way to install Polypus is from PyPI:

pip install polypus-quantum

Then import polypus (see Quickstart). CUNQA and the QMIO real-QPU backend are optional extras — see CUNQA below and the from-source build for --features qmio.

From source

To build from a checkout — for contributors, or to enable the qmio backend — use the provided script:

bash install.sh

This will interactively guide you through installing dependencies, building the wheel, and optionally running the test suite. For non-interactive environments (CI/CD):

bash install.sh --yes        # all defaults, run all tests
bash install.sh --no-tests   # skip tests

pip install -r requirements-dev.txt

maturin build --release --out dist
pip install dist/polypus_quantum-*.whl

CUNQA

To install CUNQA please refer to the CUNQA GitHub repository.

Usage

Check the examples/ directory for complete, runnable scripts.

Running a Quantum Circuit

Pass the circuit, the number of shots, the infrastructure and the number of QPUs:

result = polypus.run_quantum_circuit(
    qc, shots=NUM_SHOTS, infrastructure=INFRASTRUCTURE, n_qpus=1
)

Distributing Shots Across Multiple QPUs

Set n_qpus > 1 to split the shots across available QPUs and reduce execution time:

result = polypus.run_quantum_circuit(
    qc, shots=NUM_SHOTS, infrastructure=INFRASTRUCTURE, n_qpus=10
)

When infrastructure="cunqa", two optional kwargs size the SLURM allocation for the distributed QPUs:

result = polypus.run_quantum_circuit(
    qc, shots=NUM_SHOTS, infrastructure="cunqa", n_qpus=10, nodes=2, cores_per_qpu=4
)
print(len(result.counts))  # 10 — one counts dict per QPU
print(result.merged_counts)  # their total, over all NUM_SHOTS shots

Both must be >= 1 for "cunqa" (a 0 reaching SLURM is rejected with a ValueError). They are ignored by infrastructure="local" and "qmio", so those calls omit them.

Both calls return a RunResult with the same shape whatever n_qpus is. result.counts is always a list[dict[str, int]] with one dict per QPU, in the order the shots were split (length n_qpus, so result.counts[0] is the first QPU's counts for any n_qpus; a QPU left with no shots when shots < n_qpus is an empty {}). result.merged_counts is a single dict[str, int] summing all of them — the circuit's counts over every shot, and usually what you want with n_qpus > 1. The manifest fields result.id, result.seed, result.backend and result.infrastructure record the run for logging and replay. Pass seed=... to run_quantum_circuit() for reproducible shot noise on every simulated backend (native "polypus", Aer, and CUNQA's simulated QPUs); result.seed reports the effective seed used (None only for the "qmio" infrastructure, which is real hardware and rejects an explicit seed).

Training Variational Circuits

Polypus optimizes variational quantum circuits via polypus.train(). The optimizer is selected by passing a method object as the second argument. Polypus distributes the population individuals across the available QPUs automatically.

The common parameters for all methods are:

If CUNQA is not available, set infrastructure="local".

Differential Evolution

result = polypus.train(
    qc,
    polypus.DE(
        generations=MAX_GENERATIONS, population_size=POPULATION_SIZE, tolerance=TOL
    ),
    shots=N_SHOTS,
    n_qpus=N_QPUS,
    dimensions=2 * layers,
    expectation_function=bitstring_to_obj,
    infrastructure=infrastructure,
    nodes=NUM_NODES,
    cores_per_qpu=CORES_PER_QPU,
    id=id,
)

train() (and qml.train()) return a TrainResult carrying the full optimization outcome, not just the tuned parameters:

print(result.best_params)  # list[float] — the optimized parameters
print(result.best_fitness)  # float — cost/fitness at those parameters
print(result.iterations_run)  # int — iterations actually run (early-stopping aware)
print(result.converged)  # bool — whether the convergence criterion was met
print(
    result.seed
)  # int — the effective RNG seed; pass it back as seed=... to reproduce the run

Pin reproducibility with the seed keyword (polypus.train(..., seed=42)) or on the optimizer itself (polypus.DE(..., seed=42)); with no seed, one is drawn from OS entropy and reported back in result.seed.

Particle Swarm Optimization

result = polypus.train(
    qc,
    polypus.PSO(
        generations=MAX_GENERATIONS,
        population_size=POPULATION_SIZE,
        bounds=(0.0, np.pi),
        tolerance=TOL,
    ),
    shots=N_SHOTS,
    n_qpus=N_QPUS,
    dimensions=2 * layers,
    expectation_function=bitstring_to_obj,
    infrastructure=infrastructure,
    nodes=NUM_NODES,
    cores_per_qpu=CORES_PER_QPU,
    id=id,
)

Quantum Natural Gradient

QNG requires a variance_function callable that estimates the diagonal quantum Fisher information matrix element for each parameter. Default hyperparameters: learning_rate=0.1, finite_difference_step=0.1, tikhonov_reg=0.05.

result = polypus.train(
    qc,
    polypus.QNG(
        variance_fn,
        max_iters=MAX_GENERATIONS,
        bounds=(0.0, np.pi),
        learning_rate=0.1,
        finite_difference_step=0.1,
        tikhonov_reg=0.05,
    ),
    shots=N_SHOTS,
    n_qpus=N_QPUS,
    dimensions=2 * layers,
    expectation_function=bitstring_to_obj,
    infrastructure=infrastructure,
    nodes=NUM_NODES,
    cores_per_qpu=CORES_PER_QPU,
    id=id,
)

Training QML Classifiers

polypus.qml.train() trains a data-encoding circuit: a Qiskit feature_map encodes each row of x_train (one sample per row, len(feature_map.parameters) values each), an ansatz holds the trainable weights, and the optimizer maximises the mean per-sample score over the training set. It takes the same optimizers and parameters as train().

Pass y_train (one label per row) to train a supervised model: each sample is then scored against its own label. Here a binary classifier reads out the parity of the measured bits:

from qiskit.circuit.library import real_amplitudes, zz_feature_map

feature_map = zz_feature_map(feature_dimension=4, reps=2)
ansatz = real_amplitudes(num_qubits=4, reps=2)


def correct(bitstring, label):  # 1.0 when the read-out matches the label
    return float(bitstring.count("1") % 2 == label)


result = polypus.qml.train(
    feature_map,
    ansatz,
    X_train,  # shape (n_samples, 4)
    polypus.DE(generations=50, population_size=20),
    shots=1024,
    n_qpus=1,
    dimensions=len(ansatz.parameters),
    expectation_function=correct,  # fitness = expected training accuracy
    infrastructure="local",
    nodes=1,
    cores_per_qpu=1,
    id="qml_classifier",
    y_train=y_train,  # shape (n_samples,): class indices
)

With y_train, expectation_function takes one of three forms:

For example, a polypus.SampleCost can maximise the log-likelihood, i.e. minimise the cross-entropy:

import math


def log_likelihood(counts, label):
    hits = sum(n for bits, n in counts.items() if bits.count("1") % 2 == label)
    # Clip before the log: every score must be finite.
    return math.log(max(hits / sum(counts.values()), 1e-6))


expectation_function = polypus.SampleCost(log_likelihood)

Integer labels (Python or NumPy ints and bools) reach your function as int; if any label is not an integer, all of them arrive as float (regression targets). y_train is validated before anything runs: a length other than the number of rows, a NaN/inf, a string or a one-hot row is rejected with the offending index. Without y_train, one expectation_function(bitstring) is shared by every sample, as before.

To evaluate a trained model, polypus.qml.predict() builds the circuits training ran and executes every sample in one scheduled run: one backend batch and, on CUNQA, one allocation. Its RunResult.counts holds one dict per row, in row order; map them to classes with the objective's read-out:

run = polypus.qml.predict(
    feature_map,
    ansatz,
    X_test,
    result.best_params,
    shots=1024,
    infrastructure="local",
    seed=7,
)


def majority_parity(counts):
    odd = sum(n for bits, n in counts.items() if bits.count("1") % 2)
    return int(odd > sum(counts.values()) - odd)


predictions = [majority_parity(counts) for counts in run.counts]

With n_qpus > 1 the samples are spread over the QPUs; one sample's shots are never split. See examples/basic_qml.py for a complete classifier, from training to held-out accuracy.

Rust-Native Circuits

The repository is a Cargo workspace; polypus-circuit is its pure-Rust quantum circuit crate — no PyO3/Python dependency, so circuits can be built and serialized without the GIL. crates/polypus (the Python extension) re-exports its API as polypus.Circuit. Qiskit circuits remain fully supported; the Rust API is an additional, high-performance path.

From Python

polypus.Circuit is accepted by run_quantum_circuit and train exactly like a Qiskit QuantumCircuit (an OpenQASM 2.0 string also works for run_quantum_circuit):

import polypus

# Fully bound circuit → run directly
bell = polypus.Circuit(2).h(0).cx(0, 1).measure_all()
result = polypus.run_quantum_circuit(bell, shots=1000, infrastructure="local")

# Parameterized ansatz → train (binding happens in Rust, GIL-free)
qaoa = (
    polypus.Circuit(4)
    .h(0)
    .h(1)
    .h(2)
    .h(3)
    .rzz(0, 1, polypus.Param(0))
    .rzz(1, 2, polypus.Param(0))
    .rzz(2, 3, polypus.Param(0))
    .rzz(3, 0, polypus.Param(0))
    .rx(0, polypus.Param(1))
    .rx(1, polypus.Param(1))
    .rx(2, polypus.Param(1))
    .rx(3, polypus.Param(1))
    .measure_all()
)
result = polypus.train(
    qaoa,
    polypus.DE(generations=100, population_size=50),
    shots=1024,
    n_qpus=1,
    dimensions=2,
    expectation_function=my_cost,
    infrastructure="local",
    nodes=1,
    cores_per_qpu=1,
    id="qaoa",
)

From Rust

use polypus_circuit::{ParameterizedCircuit, Param};

let qc = ParameterizedCircuit::new(4)
    .h(0).h(1).h(2).h(3)
    .rzz(0, 1, Param(0)).rzz(1, 2, Param(0)).rzz(2, 3, Param(0)).rzz(3, 0, Param(0))
    .rx(0, Param(1)).rx(1, Param(1)).rx(2, Param(1)).rx(3, Param(1))
    .measure_all();

let qasm: String = qc.to_qasm2_with_params(&[0.4, 0.8])?; // OpenQASM 2.0
let qir_ll: String = qc.to_qir_with_params(&[0.4, 0.8])?; // QIR LLVM IR text (.ll)
let qir_bc: Vec<u8> = qc.to_qir_bitcode_with_params(&[0.4, 0.8])?; // QIR bitcode (.bc)

The generated OpenQASM 2.0 uses standard qelib1.inc gate names and is accepted by Qiskit (QuantumCircuit.from_qasm_str) and Aer.

to_qir_bitcode_with_params requires llvm-as available in PATH because Polypus assembles the textual QIR module into LLVM bitcode externally.

From Python, both outputs are also available:

qc = polypus.Circuit(2).h(0).cx(0, 1).measure_all()
qir_text = qc.to_qir()  # str (.ll)
qir_bitcode = qc.to_qir_bitcode()  # bytes (.bc)

QASM 2.0 Import

Circuit.from_qasm2 is the inverse of to_qasm2 — it accepts the QASM this library exports and Qiskit's qasm2.dumps output (u/p/u1/u2 are canonicalised to u3, swap to its cx decomposition; multiple registers are flattened; constant expressions like pi/2 are evaluated). Parse errors raise ValueError with the offending line number.

import polypus
from qiskit import qasm2

qc = polypus.Circuit.from_qasm2(qasm2.dumps(qiskit_circuit))  # interop
qc = polypus.Circuit.from_qasm2(open("ansatz.qasm").read())  # persistence
qc.rz(1, 0.5).measure_all()  # imported circuits are regular builders

Round-trip guarantee (verified by tests): for any circuit produced by this library, export → import → export is byte-identical. The same API exists in Rust as ParameterizedCircuit::from_qasm2.

Performance Notes

• Parameter binding: ~3x faster than Qiskit's assign_parameters and, crucially, GIL-free — concurrent evaluation threads bind candidates truly in parallel (see benchmarks/bench_native_vs_qiskit.py).
• Batched simulation: the local backend submits each evaluation batch (e.g. a whole DE population) in a single AerSimulator.run call with max_parallel_experiments=0, so Aer's C++ engine runs the experiments in parallel across cores with the GIL released. Measured ~1.4–2.1x end-to-end training speedup vs per-circuit submission, growing with circuit size (see benchmarks/bench_batching.py). Distributed backends cap each wave's concurrency at n_qpus via their QuantumBackend::capabilities (BackendCapabilities::max_concurrency), which the Planner enforces.
• Native circuits shine brightest with backends that consume OpenQASM directly (e.g. CUNQA), where the Qiskit re-parse disappears entirely.
• Automatic gate-parallel calibration: the native (backend="polypus") statevector simulator switches its gate kernels to the parallel path at a machine-specific qubit count. The first import polypus on a machine measures that crossover once (well under a second) and caches it under $XDG_CACHE_HOME/polypus/ (or ~/.cache/polypus/); every later import reuses the cache with no measurement. This runs on the real runtime hardware, so pip install polypus-quantum wheel users get a tuned threshold with no manual step. It fails safe — a read-only cache dir (containers/CI) falls back to the default threshold without error, and correctness is never affected. Set POLYPUS_NO_AUTOCALIBRATE=1 to skip it entirely (CI, containers, reproducibility runs); you can also tune it explicitly at any time with polypus.calibrate_parallel_threshold().

Project Architecture

Polypus is a Cargo workspace of focused crates plus one Python package:

Only crates/polypus, crates/polypus-infrastructure and crates/polypus-evaluation link against Python (via PyO3); every other Rust crate is dependency-free with respect to PyO3 and can be used standalone from any Rust project.

Documentation

• API reference (generated with cargo doc, covers the Rust crates and the PyO3 bindings): https://bahia-software.github.io/polypus/
• Runnable, end-to-end scripts: examples/
• Performance benchmarks and how to reproduce them: benchmarks/

Citing Polypus

If Polypus is useful in your research, please cite it:

@software{polypus,
  author  = {Fernández Prada, Diego Beltrán and Sóñora Pombo, Víctor and Figueiras Gómez, Sergio and Boubeta Martínez, Miguel and Pérez González, Kevin and Sendón Caamaño, Uxía and {Galicia Supercomputing Center (CESGA)}},
  title   = {{Polypus: A Distributed Quantum Computing Library}},
  year    = {2026},
  url     = {https://github.com/Bahia-Software/polypus},
  doi     = {10.5281/zenodo.22913065},
  version = {0.7.2}
}

Credits

• Diego Beltrán Fernández Prada
• Víctor Sóñora Pombo
• Sergio Figueiras Gómez
• Miguel Boubeta Martínez
• Kevin Pérez González
• Uxía Sendón Caamaño
• Galicia Supercomputing Center (CESGA)

Dependencies

Polypus relies on the following Python packages:

See requirements-dev.txt and requirements-examples.txt for the full pinned dependency lists.

License

Polypus is licensed under the European Union Public Licence, version 1.2 (EUPL-1.2). See LICENSE for the full text.