QuoNic — Quantum programming, as simple as writing Python

QuoNic is a tool that makes quantum programming as simple as writing Python.

No QuantumCircuit to learn, no backend to understand, no manual measure. If you can write Python, you can write quantum programs.

中文文档

30-second quick start

from quonic import qgate, qshow
from quonic.gates import H, CX

qgate(H, 0)
qgate(CX, 0, 1)
qshow()

This is the Bell state — the most classic result in quantum computing. The same thing takes 10+ lines in raw Qiskit. QuoNic does it in 3. The result appears directly in your terminal or Jupyter.

More copy-and-run examples (GHZ, qif, QInt, Grover, VQE, QAOA, noise, GPU acceleration, error mitigation) live in examples/.

5-minute tutorial

Step 1: Install

pip install quonic

Step 2: Your first quantum circuit (Bell state)

from quonic import qgate, qshow
from quonic.gates import H, CX

qgate(H, 0)      # Hadamard on qubit 0
qgate(CX, 0, 1)  # CNOT: entangle qubits 0 and 1
qshow()           # Run and display

Step 3: Switch backend (same code, different simulator)

qshow(backend='qiskit')      # IBM Qiskit
qshow(backend='cirq')        # Google Cirq
qshow(backend='qulacs')      # Qulacs (fast C++)
qshow(backend='tensorcircuit') # TensorCircuit (JAX)

Step 4: Add noise

qshow(noise=0.05)  # 5% depolarizing noise

Step 5: GPU acceleration

qshow(method='gpu')  # Auto-select best GPU backend

That's it. Same code, any backend, any hardware. That's the QuoNic way.

Installation

pip install quonic

Backends are optional dependencies — install only what you need. To install all backends (plus numpy/scipy for the algorithm templates) in one shot:

pip install 'quonic[qiskit,cirq,pennylane,algorithms,all-sim]'

To install a single backend, e.g. only Cirq: pip install 'quonic[cirq]'. Calling an uninstalled backend raises a clear message (English by default; set QUONIC_LANG=zh for Chinese).

Additional simulator backends (Qulacs / TensorCircuit / CUDA-Q / MindQuantum / QPanda3 / CqLib): pip install 'quonic[all-sim]' or install individually, e.g. pip install 'quonic[qulacs]'.

Hardware / cloud backends (IBM Quantum / AWS Braket / Azure Quantum / IonQ / Rigetti / Xanadu / QuEra): pip install 'quonic[all-hw]' or install individually.

⚠️ Hardware backends are untested. IBM Quantum, AWS Braket, Azure Quantum, IonQ, Rigetti, Xanadu, and QuEra backends are provided as-is without real-hardware validation. Use at your own risk. Local simulators (Qulacs / TensorCircuit / QPanda3 / CuPy / native) are fully tested.

GPU acceleration: pip install 'quonic[gpu]' (CuPy).

Visualization is a separate optional dependency: pip install 'quonic[viz]' (matplotlib only — no Graphviz / Seaborn / NetworkX).

Core features

1. Minimal syntax: a Bell state in 3 lines

You don't need to understand "quantum circuit objects", pick a "backend simulator", or write measure by hand. QuoNic handles all of it.

2. Switch every backend with one argument

# Use the Qiskit simulator (default)
qshow(backend='qiskit')

# Switch to Cirq
qshow(backend='cirq')

# Switch to Qulacs (high-performance C++)
qshow(backend='qulacs')

# Switch to TensorCircuit (JAX/TensorFlow/PyTorch)
qshow(backend='tensorcircuit')

# Noise simulation
qshow(backend='qiskit', noise=0.05)

# Real hardware (Quantum Inspire) — requires login
qshow(backend='qi')                    # QX cloud simulator (default; verify before submitting)
qshow(backend='qi', device='tuna9')    # Tuna-9 real device
qshow(backend='qi', device='tuna17')   # Tuna-17 real device
qshow(backend='qi', device='qx')       # QX cloud simulator

The same code, unchanged, runs on any backend. Minimal syntax + backend independence is QuoNic's combined differentiator.

3. Conditional gates and "if = superposition"

QuoNic implements quantum superposition control with qif and draws a strict line between two concepts:

• Quantum superposition control (qif, implemented): when the control qubit is in a superposition, the branches are not measured — they interfere coherently and produce real entanglement. This is "both branches happen at once", not "measure then pick one".

  from quonic import qgate, qif, qshow
  from quonic.gates import H, X, I
  
  qgate(H, 0)                       # control qubit enters superposition
  qif(0).then(X, 1).else_(I, 1)     # q0==1 flips q1, else nothing (= controlled X)
  qshow()
  

  The I in else_(I, ...) is the identity gate, so "controlled gate = qif special case" reads naturally.
• Conditional gates (classical control, planned): measure first, then branch on the result — a "classical branch after collapse".

  # Planned: condition on the measurement result
  # qgate(H, 0)
  # if qgate(MEASURE, 0) == 0:
  #     qgate(X, 1)
  # else:
  #     qgate(Z, 1)
  

We don't dress up "classical branching after measurement" as "superposition" — teaching wrong physics is worse than not teaching at all.

4. Genuinely beginner-friendly

• Clear error messages (English by default, Chinese via QUONIC_LANG=zh): they tell you what went wrong, why, and how to fix it
• Autocomplete: gate names and parameters are hinted in VS Code / Jupyter
• Automatic measurement: forgot to write measure? qshow() fills it in

5. Smart scheduler: automatically picks the fastest method

Quantum simulation has four methods whose speeds differ by orders of magnitude — picking wrong hits a wall:

QuoNic's scheduler picks automatically based on circuit features (gate types, treewidth, whether it contains noise) — you never specify the method by hand. Measured evidence: GHZ(24) is 36× faster, QAOA(24) 19× faster; Grover's mcz only runs on statevector, and the scheduler routes around methods that would crash.

from quonic.scheduler import schedule
rec = schedule(circuit)   # -> Recommendation(backend='qiskit', method='stabilizer')

See scheduler benchmarks and measurements.

6. GPU acceleration — one argument

qshow(method='gpu')                              # GPU on current backend
qshow(backend='qulacs', method='gpu')            # qulacs GPU (fallback CuPy)

The scheduler can also pick the best GPU backend automatically:

from quonic.scheduler import recommend_backend_gpu, circuit_features

rec = recommend_backend_gpu(circuit_features(circuit))
# -> Recommendation(backend='qulacs', method='gpu')

Install: pip install 'quonic[gpu]' (CuPy) or pip install 'quonic[qulacs]' (native GPU).

7. Full visualization suite: 23 chart types with only Matplotlib

from quonic.viz import plot_circuit, plot_counts, plot_decision_tree

plot_circuit(circuit)        # gate-sequence circuit diagram
plot_counts(result)          # measurement histogram
plot_decision_tree()         # scheduler decision tree

The 23 chart types span four layers: core needs (circuit / histogram / topology), scheduler evidence (method comparison / decision tree / heatmap / fallback chain / feature radar), algorithm teaching (energy convergence / Grover amplitude / statevector / Bloch sphere), and quantum states (density matrix / entanglement / gate matrix / routing / per-gate state evolution / noise cost). All with matplotlib as the single dependency, lazy-loaded, zero overhead on import quonic. See visualization suite.

QuoNic vs Qiskit

Why the name QuoNic?

QuoNic is an acronym for Quantum Unified Operation Native Interface Core:

Pronounced /ˈkwɑnɪk/ ("kwah-nik").

Currently supported backends

Note: Qiskit / Cirq / PennyLane / Qulacs / TensorCircuit / QPanda3 run on local simulators. CUDA-Q requires NVIDIA CUDA. MindQuantum requires Linux/macOS. CqLib is cloud-only (TianYan platform). Quantum Inspire real hardware is reached via qshow(backend="qi", device="tuna9").

To pave the way for hardware, QuoNic already ships CouplingMap (coupling graph), the compile() compilation seam, and decompose() gate decomposition — which expands higher-order gates (cp / ccx / mcz) into the basic gate set. The latter is QuoNic's own "portable core": users aren't locked to one backend's circuit shape, and Grover's mcz decomposes into cx / h / p so it runs on every backend method. A greedy SWAP router route_swaps() is built in (with plot_routing visualization), so wiring up IBM / domestic engines later only touches the compilation layer — no changes to the IR or scheduler.

Parallel execution

from quonic import qgate, qshow_all, run_circuits
from quonic.gates import H, CX, X

# Run the same circuit on multiple backends in parallel
qgate(H, 0)
qgate(CX, 0, 1)
results = qshow_all(['qiskit', 'cirq', 'qulacs'])

# Run different circuits in parallel
def bell(): qgate(H, 0); qgate(CX, 0, 1)
def flip(): qgate(X, 0)
results = run_circuits([bell, flip], backend='qiskit')

77 Algorithm Templates

QuoNic ships 77 algorithm templates across 10 domains — from foundational quantum computing to cutting-edge research demos. Each algorithm has documented boundary conditions and usage examples. See the full algorithm report.

Usage

from quonic.algorithms import grover, vqe, qaoa_maxcut, deutsch_jozsa

# Grover search for |11>
result = grover("11", 2, shots=1024)

# VQE ground state energy
hamiltonian = [(1.0, "ZZ"), (1.0, "XI"), (1.0, "IX")]
result = vqe(hamiltonian, 2)

# QAOA MaxCut
result = qaoa_maxcut([(0,1), (1,2), (0,2)], 3, p=2)

# Deutsch-Jozsa
result = deutsch_jozsa(2, my_oracle, shots=100)

Algorithm catalog

Full = standard algorithm, works on simulator, meaningful results. Demo = minimal demonstration of core concept, not production-grade.

Docs and tutorials

• Quickstart — up and running in 5 minutes
• Jupyter tutorial — runnable interactive notebook
• Scheduler benchmarks — the measured-data moat behind automatic method selection
• Visualization suite — 23 chart types with only Matplotlib
• Domestic hardware survey — QPanda3 / CqLib integration assessment

Contributing

QuoNic is open source (Apache 2.0) and welcomes all kinds of contribution:

• Report bugs
• Propose new features
• Submit code (new backend adapters, gates, features)
• Improve docs and tutorials

See CONTRIBUTING.md for the development setup, code style, and conventions.

License

QuoNic is licensed under the Apache License 2.0 — friendly to commercial and closed-source use, with patent protection.

Star the project

If QuoNic helps you, please give us a ⭐️ on GitHub. Your support keeps us going.