README
¶
Goqu
Kamehame-Hadamard!
Goqu lets you build, simulate, transpile, and run quantum circuits in pure Go. No C bindings, no Python interop, no external dependencies in the core — just go get and go.
Quick Start
go get github.com/splch/goqu@latest
Create a Bell state in five lines:
c, _ := builder.New("bell", 2).
H(0).
CNOT(0, 1).
MeasureAll().
Build()
sim := statevector.New(2)
counts, _ := sim.Run(c, 1024)
fmt.Println(counts) // map[00:~512 11:~512]
Features
| 28+ gates | H, CNOT, Toffoli, RX/RY/RZ, U3, IonQ native gates, custom unitaries, and more |
| 7 simulators | Statevector (up to 28 qubits), density matrix, Clifford, pulse-level, Pauli, noise channels, operator theory |
| 7 hardware backends | IonQ, IBM Quantum, Google, AWS Braket, Rigetti, Quantinuum, and local |
| Transpilation | SABRE routing, gate decomposition (Euler, KAK, Barenco), 4 optimization levels, equivalence verification |
| Pulse programming | OpenPulse model with 5 waveform types, gate-to-pulse calibration, OpenQASM 3.0 parsing |
| Serialization | OpenQASM 2.0 & 3.0 round-trip, Quil emission |
| Visualization | ASCII, SVG, and LaTeX circuit diagrams |
| Observability | OpenTelemetry and Prometheus bridges (optional separate modules) |
| Job management | Concurrent submission, polling, retry with circuit breaker |
Run on Real Hardware
// Transpile for IonQ's native gate set
compiled, _ := pipeline.Run(circuit, pipeline.OptLevel2, target.IonQ())
// Submit to IonQ
backend := ionq.New(apiKey)
result, _ := backend.Run(ctx, compiled, 1000)
Interactive Notebooks
Four Jupyter notebooks (powered by gonb) walk through the SDK:
- Getting Started — circuits, visualization, simulation
- Simulation & Noise — density matrix, noise channels, Pauli expectations
- Variational Circuits — symbolic parameters, sweeps, QASM round-trip
- Transpilation — hardware targeting, optimization levels, before/after comparison
Development
make test # Run tests
make test-race # Race detector
make lint # golangci-lint
make bench # Statevector & density matrix benchmarks
make fuzz # Fuzz parsers and transpiler passes
make coverage # HTML coverage report
License
MIT — Spencer Churchill
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backend defines the interface for quantum execution backends.
|
Package backend defines the interface for quantum execution backends. |
|
ibm
Package ibm implements a backend.Backend for IBM Quantum via the Qiskit Runtime V2 API.
|
Package ibm implements a backend.Backend for IBM Quantum via the Qiskit Runtime V2 API. |
|
ionq
Package ionq implements a backend.Backend for the IonQ quantum cloud via its REST API (v0.4).
|
Package ionq implements a backend.Backend for the IonQ quantum cloud via its REST API (v0.4). |
|
local
Package local provides a backend.Backend backed by the in-process statevector simulator.
|
Package local provides a backend.Backend backed by the in-process statevector simulator. |
|
mock
Package mock provides a configurable backend.Backend for testing job managers and pipelines without network calls.
|
Package mock provides a configurable backend.Backend for testing job managers and pipelines without network calls. |
|
quantinuum
Package quantinuum implements a backend.Backend for Quantinuum's H-series trapped-ion quantum computers via the Quantinuum Machine API (v1).
|
Package quantinuum implements a backend.Backend for Quantinuum's H-series trapped-ion quantum computers via the Quantinuum Machine API (v1). |
|
circuit
|
|
|
builder
Package builder provides a fluent API for constructing quantum circuits.
|
Package builder provides a fluent API for constructing quantum circuits. |
|
draw
Package draw renders quantum circuits as text, SVG, and LaTeX diagrams.
|
Package draw renders quantum circuits as text, SVG, and LaTeX diagrams. |
|
gate
Package gate defines the Gate interface and provides a standard library of quantum gates.
|
Package gate defines the Gate interface and provides a standard library of quantum gates. |
|
ir
Package ir defines the circuit intermediate representation.
|
Package ir defines the circuit intermediate representation. |
|
param
Package param provides symbolic parameters and expressions for parameterized quantum circuits.
|
Package param provides symbolic parameters and expressions for parameterized quantum circuits. |
|
internal
|
|
|
mathutil
Package mathutil provides internal math helpers shared across goqu packages.
|
Package mathutil provides internal math helpers shared across goqu packages. |
|
piformat
Package piformat formats rotation angles as human-readable pi fractions.
|
Package piformat formats rotation angles as human-readable pi fractions. |
|
job
|
|
|
manager
Package manager provides concurrent job submission, polling, and result retrieval across multiple quantum backends.
|
Package manager provides concurrent job submission, polling, and result retrieval across multiple quantum backends. |
|
retry
Package retry provides retry policies with exponential backoff and a circuit breaker for protecting against repeated backend failures.
|
Package retry provides retry policies with exponential backoff and a circuit breaker for protecting against repeated backend failures. |
|
Package observe provides zero-dependency observability hooks for goqu.
|
Package observe provides zero-dependency observability hooks for goqu. |
|
Package pulse provides types for pulse-level quantum control.
|
Package pulse provides types for pulse-level quantum control. |
|
defcal
Package defcal maps gate-level circuits to pulse programs via calibration tables.
|
Package defcal maps gate-level circuits to pulse programs via calibration tables. |
|
qasmparse
Package qasmparse parses OpenQASM 3.0 with OpenPulse cal {} blocks into pulse.Program objects.
|
Package qasmparse parses OpenQASM 3.0 with OpenPulse cal {} blocks into pulse.Program objects. |
|
waveform
Package waveform provides standard pulse envelope shapes for the pulse package.
|
Package waveform provides standard pulse envelope shapes for the pulse package. |
|
qasm
|
|
|
emitter
Package emitter serializes a quantum circuit as OpenQASM 3.0 source text.
|
Package emitter serializes a quantum circuit as OpenQASM 3.0 source text. |
|
parser
Package parser implements a hand-written recursive descent parser for OpenQASM source.
|
Package parser implements a hand-written recursive descent parser for OpenQASM source. |
|
token
Package token defines the lexical token types for OpenQASM 3.0 parsing.
|
Package token defines the lexical token types for OpenQASM 3.0 parsing. |
|
quil
|
|
|
emitter
Package emitter writes a Circuit as Quil source.
|
Package emitter writes a Circuit as Quil source. |
|
sim
|
|
|
clifford
Package clifford implements an efficient stabilizer-state simulator using the Aaronson-Gottesman tableau representation.
|
Package clifford implements an efficient stabilizer-state simulator using the Aaronson-Gottesman tableau representation. |
|
densitymatrix
Package densitymatrix implements a density matrix quantum simulator supporting mixed states and noise channels.
|
Package densitymatrix implements a density matrix quantum simulator supporting mixed states and noise channels. |
|
noise
Package noise defines quantum noise channels and noise models for use with the density matrix simulator.
|
Package noise defines quantum noise channels and noise models for use with the density matrix simulator. |
|
operator
Package operator provides quantum channel representations and conversions.
|
Package operator provides quantum channel representations and conversions. |
|
pauli
Package pauli provides Pauli algebra types and efficient expectation value computation for statevector and density matrix simulators.
|
Package pauli provides Pauli algebra types and efficient expectation value computation for statevector and density matrix simulators. |
|
pulsesim
Package pulsesim simulates pulse programs via statevector evolution.
|
Package pulsesim simulates pulse programs via statevector evolution. |
|
statevector
Package statevector implements a full statevector quantum simulator supporting up to 28 qubits.
|
Package statevector implements a full statevector quantum simulator supporting up to 28 qubits. |
|
Package sweep provides parameter sweep types for evaluating variational quantum circuits across ranges of parameter values.
|
Package sweep provides parameter sweep types for evaluating variational quantum circuits across ranges of parameter values. |
|
Package transpile provides the quantum circuit transpilation framework.
|
Package transpile provides the quantum circuit transpilation framework. |
|
analysis
Package analysis provides circuit analysis helpers for transpilation passes.
|
Package analysis provides circuit analysis helpers for transpilation passes. |
|
decompose
Package decompose provides gate decomposition algorithms for single-qubit and two-qubit unitaries.
|
Package decompose provides gate decomposition algorithms for single-qubit and two-qubit unitaries. |
|
pass
Package pass provides individual transpilation passes for circuit optimization and target compliance.
|
Package pass provides individual transpilation passes for circuit optimization and target compliance. |
|
pipeline
Package pipeline provides pre-built transpilation pipelines with four optimization levels.
|
Package pipeline provides pre-built transpilation pipelines with four optimization levels. |
|
routing
Package routing inserts SWAP gates to satisfy hardware connectivity constraints using the SABRE algorithm.
|
Package routing inserts SWAP gates to satisfy hardware connectivity constraints using the SABRE algorithm. |
|
target
Package target defines hardware target descriptions for transpilation.
|
Package target defines hardware target descriptions for transpilation. |
|
verify
Package verify checks circuit equivalence using statevector simulation.
|
Package verify checks circuit equivalence using statevector simulation. |
Click to show internal directories.
Click to hide internal directories.