polypus

---

Polypus is a quantum computing library with a Rust core and Python bindings. It splits shots and optimizer populations across n_qpus and runs them on a local simulator, on CESGA's CUNQA distributed QPUs or on CESGA's QMIO quantum processor. Changing the target means changing one argument, not the algorithm code. Around that core, Polypus builds, draws and exports circuits natively, trains variational circuits and quantum machine learning models, and runs Shor's algorithm end to end.

New in 0.8.0: Shor's algorithm, native circuit drawings, OpenQASM 3, adaptive Differential Evolution (SHADE and L-SHADE), CMA-ES, Adam, SPSA, Rotosolve, external ask/tell optimizers and native QML models. The release has breaking changes: read Upgrading from 0.7 before you upgrade.

Highlights

Feature
Multi-QPU execution	Shots and populations are split across n_qpus; results come back per QPU and merged.
Variational training	Differential Evolution (classic, SHADE or L-SHADE), Particle Swarm, Quantum Natural Gradient, CMA-ES, Adam (or momentum), SPSA and Rotosolve behind one train() call, or an ask/tell optimizer from Optuna, Nevergrad, pycma or your own code through polypus.External. A run can start from an earlier result (initial_point), re-evaluate its best candidates in a final batch (final_shots) and report or stop each iteration (callback).
Quantum machine learning	Your own Qiskit circuits (qml.train, qml.predict), or native models (qml.Model) built from encoders, ansatz layers (QCNN included) and Pauli readouts, with exact gradients, exact simulation, minibatches and save/load.
Native cost observables	QUBO and Ising costs are evaluated in Rust, without a Python call per bitstring.
Rust circuit engine	polypus.Circuit imports and exports OpenQASM 2 and 3, exports QIR, composes circuits and draws itself as text or SVG, with no plotting library. Parameter binding runs without the GIL, about 3x faster than Qiskit's assign_parameters.
Shor's algorithm	polypus.shor.factor factors an integer end to end on any backend, from the classical shortcuts to Beauregard's order-finding circuit, and reports the share of shots on the order's peaks, to compare with an ideal circuit and with random outcomes. The QFT and the order-finding circuit are templates in polypus.circuits.templates, built in Rust.
Reproducible runs	Every simulated run reports the seed it used; pass it back to replay the run.
Safe on shared machines	Simulations are sized against a memory budget, and a circuit that cannot fit is refused before allocation instead of being killed by the OOM killer.

Installation

pip install polypus-quantum

The package imports as polypus; pip installs Qiskit 2 and Qiskit Aer 0.17 with it. Wheels are published for CPython 3.10 to 3.13 on Linux (x86_64 and aarch64), macOS on Apple Silicon and Windows (x86_64). On other platforms, Intel Macs included, pip builds the source distribution, which needs a Rust toolchain (1.85 or newer).

To use	Install
Local simulators (Aer and native)	pip install polypus-quantum
Optuna, Nevergrad or pycma through polypus.External	pip install "polypus-quantum[optuna]" ([nevergrad], [cma])
CUNQA	Polypus, plus CUNQA >=2.4,<4 on the cluster. CUNQA 2.3 is not supported (it names the qraise argument cores, not cores_per_qpu)
QMIO	Polypus built from source with the qmio feature: bash install.sh --qmio
The Rust crates	cargo add polypus-circuit, or any crate under Architecture; all but three are pure Rust

git clone https://github.com/Bahia-Software/polypus.git
cd polypus
bash install.sh            # interactive; --yes takes the defaults, --no-tests skips the test suite

Or by hand:

pip install -r requirements-dev.txt
maturin build --release --out dist
pip install dist/polypus_quantum-*.whl

For development, maturin develop --release installs both packages in editable mode instead: edits to Python files take effect at once, and only a Rust change needs the command run again.

The name polypus on PyPI belongs to an unrelated project, so the distribution is polypus-quantum. The import name and the Rust crate are polypus.

import polypus does no work and writes nothing. The first native simulation of a process (polypus.statevector, or backend="polypus") measures once per machine, in under a second, the qubit count at which the simulator's gate kernels go parallel, and caches it in $XDG_CACHE_HOME/polypus/ (or ~/.cache/polypus/). Set POLYPUS_NO_AUTOCALIBRATE=1 to skip it (CI, containers); see Performance.

Quickstart

Run a circuit on 4 QPUs

import polypus

bell = polypus.Circuit(2).h(0).cx(0, 1).measure_all()
result = polypus.run_quantum_circuit(
    bell, shots=1000, infrastructure="local", backend="polypus", n_qpus=4
)

result.counts  # one counts dict per QPU
result.merged_counts  # e.g. {'00': 487, '11': 513}

backend="polypus" is the native Rust simulator, which does not load Qiskit Aer. OpenQASM 2.0 strings are accepted the same way.

Run it on Qiskit Aer

result = polypus.run_quantum_circuit(
    bell, shots=1000, infrastructure="local", backend="aer"
)

Aer is the default backend. It also runs Qiskit QuantumCircuit objects and noise models; see Choosing a local backend. If import qiskit_aer fails with cannot allocate memory in static TLS block, see Troubleshooting.

Draw it

print(bell)

     ┌───┐       ┌─┐
q0: ─┤ H ├───■───┤M├─────
     └───┘   │   └╥┘
           ┌─┴─┐  ║  ┌─┐
q1: ───────┤ X ├──╫──┤M├─
           └───┘  ║  └╥┘
                  ║   ║
c2: ══════════════╩═══╩══
                  0   1

The drawing is native, with no plotting library. bell.draw(ascii=True) draws it in plain ASCII, bell.draw("svg") returns an SVG document, and a Jupyter notebook displays the SVG by itself; see Drawing.

Train a QAOA circuit for MaxCut

import polypus

edges = [(0, 1), (1, 2), (2, 3), (3, 0)]
gamma, beta = polypus.Param(0), polypus.Param(1)

qaoa = polypus.Circuit(4)
for q in range(4):
    qaoa.h(q)
for i, j in edges:
    qaoa.rzz(i, j, gamma)
for q in range(4):
    qaoa.rx(q, beta)
qaoa.measure_all()

# Cut size as a QUBO, evaluated natively. Optimizers maximise.
cut = polypus.Qubo(
    4,
    linear=[(q, 2.0) for q in range(4)],
    quadratic=[(i, j, -2.0) for i, j in edges],
)

result = polypus.train(
    qaoa,
    polypus.DE(generations=100, population_size=50, seed=42),
    shots=1024,
    n_qpus=1,
    dimensions=2,
    expectation_function=cut,
    infrastructure="local",
    backend="polypus",
    nodes=1,
    cores_per_qpu=1,
    id="maxcut",
)
result.best_params, result.best_fitness

To try another optimizer, replace polypus.DE with polypus.PSO, polypus.QNG, polypus.CMAES, polypus.Adam, polypus.SPSA or polypus.Rotosolve (for circuits whose every parameter is one single-Pauli rotation), switch DE to SHADE or L-SHADE with strategy="shade" or strategy="lshade", or run an optimizer from another library with polypus.External; to run on CUNQA, set infrastructure="cunqa" and remove backend="polypus", since CUNQA's QPUs run Aer. The rest of the code stays the same.

Choosing an optimizer compares them on MaxCut at the same evaluation budget; in that benchmark, the best mean result came from giving half of the budget to L-SHADE and the other half to Adam, started from L-SHADE's best_params with initial_point=. Since best_fitness is the best of many noisy estimates, final_shots= re-evaluates the best candidates in one more batch once the optimizer stops, with that many shots per circuit; callback= reports or stops each iteration.

Factor 15 with Shor's algorithm

from polypus.shor import factor

result = factor(15, a=7, infrastructure="local", backend="polypus", seed=1)
result.factors, result.method, result.order  # ((3, 5), 'quantum', 4)
result.peak_share, result.uniform_peak_share  # (0.734375, 0.03515625)

factor builds Beauregard's order-finding circuit (polypus.circuits.templates.shor_order_finding, 18 qubits for 15) and runs it with run_quantum_circuit, so it takes the same infrastructure and backend. method="quantum" says that the order was read off the counts, not that the circuit worked: for that, compare peak_share, the share of shots on the order's peaks, with the 3/4 that an ideal circuit puts there for order 4 and with uniform_peak_share, the share that random outcomes would give. The local simulators hold 30 qubits, numbers below 128 with the default counting register, and each qubit more doubles a run's time and memory; see Factoring with Shor.

The tutorials, in English and Spanish, go step by step from a first circuit to a native classifier, covering gates, Qiskit and OpenQASM interoperability, local and cluster execution, teleportation, the QFT, Shor's algorithm, Deutsch-Jozsa, Grover and variational training; examples/ has complete scripts.

Backends

infrastructure	backend	Runs on	Seeded	Notes
"local"	"aer" (default)	Qiskit Aer	Yes	Full Qiskit circuit support
"local"	"polypus"	Native Rust statevector	Yes	Terminal measurements only (ADR 0001)
"cunqa"		CUNQA QPUs over SLURM	Yes	nodes, cores_per_qpu and walltime (HH:MM:SS) size the allocation
"qmio"		QMIO quantum processor	No	Pure-Rust ZeroMQ client; build with the qmio feature. The endpoint comes from ZMQ_SERVER or options={"endpoint": ...}

polypus.backend_compatibility(qc) lists, for each backend (Aer, native, CUNQA, QMIO), why it would reject a circuit, without running it; resources=True also checks the native qubit ceiling and memory budget. Third-party backends plug in through a Rust trait or a Python worker; see Writing a backend.

User guide

Topic	Covers
Running circuits	RunResult, multi-QPU runs, seeds, choosing a local backend, errors, troubleshooting
Variational training	train parameters, TrainResult, cost functions, DE (classic, SHADE, L-SHADE), PSO, QNG, CMA-ES, Adam, SPSA, Rotosolve and external optimizers; starting points, final re-evaluation, callbacks, and a benchmark for choosing an optimizer
Quantum machine learning	qml.train with Qiskit circuits, labels, SampleCost and qml.predict; native models with qml.Model: layers, readout, losses, fit, prediction, saving
Circuits and interchange	polypus.Circuit, the Rust builder, angle expressions, composing, templates (QFT, Shor's order finding), factoring with Shor, drawing, OpenQASM 2 and 3, QIR
Memory budget	POLYPUS_MEM_BUDGET, cgroup detection, InsufficientMemoryError
Performance	Batched simulation, GIL-free binding, gate-parallel auto-calibration

The API reference is the rustdoc of the workspace crates. The Python API is documented in the user guide and in the type stubs and docstrings of python/polypus/.

Architecture

Polypus is a Cargo workspace. Only the three crates marked PyO3 link against Python; the others can be used from any Rust project. Every crate is published on crates.io with each release; polypus-backend, polypus-backend-conformance, polypus-subprocess-backend and polypus-qml from 0.8.0.

Crate	Role
polypus	Python extension, exception hierarchy, re-exports
polypus-circuit	Circuit representation, composition, templates (QFT, Shor's order finding), text and SVG drawings, OpenQASM 2 and 3, QIR
polypus-sim	Statevector simulator
polypus-optimizers	DE (classic, SHADE, L-SHADE), PSO, QNG, CMA-ES, Adam (or momentum), SPSA and Rotosolve, and a bridge to ask/tell optimizers
polypus-observable	QUBO and Ising cost observables
polypus-qml	Quantum machine learning models: datasets, layers, readout and losses
polypus-physics	Monte Carlo transport and Pauli-sum Hamiltonians
polypus-backend	The QuantumBackend trait that backends implement and the Planner that sizes circuit waves
polypus-backend-conformance	Conformance tests for backends

Design notes: contracts, engineering rules, architecture decisions. To contribute, see CONTRIBUTING. Release history: CHANGELOG. To report a vulnerability, see SECURITY; community rules are in the Code of Conduct.

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.8.0}
}

The same metadata is in CITATION.cff, which GitHub shows as Cite this repository.

License

Polypus is developed by Bahía Software with the Galicia Supercomputing Center (CESGA) and is licensed under the European Union Public Licence 1.2. Bundled third-party data (IAEA EPDL photon interaction files) is not covered by the EUPL; see NOTICE.