ket

TypeScript quantum circuit simulator. Immutable API, seven backends (statevector, MPS, density matrix, Clifford, stabilizer rank, tensor-network contraction, Pauli path), 14 import/export formats, zero dependencies. Runs in Node.js ≥ 22 and any modern browser.

Install

npm install @kirkelliott/ket

Or load directly in a browser via CDN (no bundler needed):

<script type="module">
  import { Circuit } from 'https://unpkg.com/@kirkelliott/ket/dist/ket.min.js'

  const bell = new Circuit(2).h(0).cnot(0, 1)
  console.log(bell.stateAsString())  // 0.7071|00⟩ + 0.7071|11⟩
</script>

Or as a plain script tag — no module setup, works in any page:

<script src="https://unpkg.com/@kirkelliott/ket"></script>
<script>
  const bell = new ket.Circuit(2).h(0).cnot(0, 1)
</script>

The global build is a second format, not a second copy — the compat entry re-exports the main bundle, so a Circuit from either entry point is the same class. No dependencies in any of them. Node.js ≥ 22; worker parallelism (workers: N) needs ≥ 22.3 and otherwise falls back to single-threaded, as it does in a browser.

Quick start

import { Circuit } from '@kirkelliott/ket'

// Build a Bell state
const bell = new Circuit(2).h(0).cnot(0, 1)

bell.draw()           // ASCII diagram
bell.stateAsString()  // '0.7071|00⟩ + 0.7071|11⟩'
bell.exactProbs()     // { '11': 0.4999999999999999, '00': 0.4999999999999999 }
                      // analytic — the last digit is float rounding, not shot noise

// Shot-based sampling
const result = bell
  .creg('out', 2)
  .measure(0, 'out', 0)
  .measure(1, 'out', 1)
  .run({ shots: 1000, seed: 42 })
// result.probs → { '00': ~0.5, '11': ~0.5 }

Conventions

All bitstrings use q0 leftmost throughout the entire API — matching Qiskit, Cirq, and textbooks.

• '10' → q0=1, q1=0
• amplitude('10'), exactProbs()['10'], initialState: '10' all follow q0-left

Circuit constructor

const c = new Circuit(3)
const aria = Circuit.device('aria-1')  // new Circuit(25)

State inspection

Circuit composition

Concatenates two circuits of the same width. Classical registers are merged; custom gate definitions merged (this wins on name conflicts). Mismatched qubit counts throw TypeError.

const prep = new Circuit(2).h(0).cnot(0, 1)
const rot  = new Circuit(2).rz(Math.PI / 4, 0).rz(Math.PI / 4, 1)
const full = prep.compose(rot)

Parametric circuits

Gate angles can be symbolic strings. Use .bind() to substitute values. Calling statevector() or any export on a circuit with unbound parameters throws a TypeError listing the missing names.

const ansatz = new Circuit(2)
  .ry('theta', 0)
  .rz('phi', 0)
  .cnot(0, 1)

ansatz.params  // ['phi', 'theta']

const bound = ansatz.bind({ theta: Math.PI / 4, phi: 0.1 })
bound.statevector()  // runs normally

Gates that accept symbolic angles: rx, ry, rz, vz, u1, p, u2, u3, gpi, gpi2, xx, yy, zz, xy, ms, crx, cry, crz, cu1, cu2, cu3.

Single-qubit gates

Two-qubit gates

Three-qubit gates

Custom unitary gate

Matrix must be 2ᴺ × 2ᴺ where N is the number of qubits. Entries can be plain number (real) or { re, im } complex objects. Supported in statevector, density matrix, and MPS (1 and 2-qubit only). Throws in runClifford.

const SWAP = [[1,0,0,0],[0,0,1,0],[0,1,0,0],[0,0,0,1]]
circuit.unitary(SWAP, 0, 1)

const S = [
  [{ re: 1, im: 0 }, { re: 0, im: 0 }],
  [{ re: 0, im: 0 }, { re: 0, im: 1 }],
]
circuit.unitary(S, 0)

Complex numbers and gate matrices

Rather than writing { re, im } by hand, use the exported helpers. c(re, im?) builds a Complex; ZERO, ONE, and I are the constants:

import { c, ZERO, ONE, I, add, mul, scale, conj, norm2 } from '@kirkelliott/ket'

const S = [[ONE, ZERO], [ZERO, I]]
circuit.unitary(S, 0)

mul(I, I)      // { re: -1, im: 0 }
norm2(c(3, 4)) // 25

Every built-in gate's matrix is exported too, so you can compose or inspect them directly — useful for building Kraus operators and custom channels:

import { H, X, Y, Z, S, Si, T, Ti, V, Vi, Rx, Ry, Rz, U1, U2, U3,
         Xx, Yy, Zz, Xy, ISwap, SrSwap, Gpi, Gpi2, Ms, Id } from '@kirkelliott/ket'

H                  // fixed gates are matrix values: 2×2
Rx(Math.PI)        // parameterised gates are functions returning a matrix
Ms(0, 0)           // IonQ native Mølmer–Sørensen, 4×4
Gpi(0), Gpi2(0)    // IonQ native single-qubit, 2×2

IonQ native gates

Use circuit.checkDevice('aria-1') to validate a circuit against a device's native gate set before calling circuit.toIonQ().

Simulation backends

If you don't want to choose, don't. simulate() inspects the circuit and routes it to the cheapest exact backend — Clifford if every gate is Clifford, statevector below statevectorLimit qubits (default 20), MPS above it:

circuit.simulate({ shots: 1024 })

// Which one ran?
const d = circuit.simulate({ shots: 1024 })
d.backend   // 'clifford' | 'statevector' | 'mps'
d.peakChi   // peak bond dimension, when the MPS path ran

Or pick a backend yourself:

The last two are not shot samplers — contraction returns amplitudes and Pauli path returns an expectation value, so neither is reachable from simulate(). Call them directly.

All shot-based backends accept an initialState option to start from an arbitrary computational basis state:

circuit.run({ initialState: '110' })
circuit.runMps({ shots: 1000, initialState: '110' })
circuit.statevector({ initialState: '110' })

Distribution

Every shot-based method — simulate(), run(), runMps(), runClifford() — returns a Distribution.

Readout error mitigation

Given a known symmetric bit-flip probability, mitigateReadout() inverts the readout confusion matrix and returns corrected probabilities:

const noisy = circuit.run({ shots: 8192, noise: { pMeas: 0.02 } })
const fixed = noisy.mitigateReadout(0.02)

noisy.probs['00']  // biased by SPAM error
fixed.probs['00']  // corrected

Measurements & classical control

const c = new Circuit(2)
  .creg('out', 2)
  .h(0).cnot(0, 1)
  .measure(0, 'out', 0)
  .measure(1, 'out', 1)

const result = c.run({ shots: 1000, seed: 42 })
// result.probs → { '00': ~0.5, '11': ~0.5 }

// Conditional gate
const teleport = new Circuit(3)
  .if('out', 1, q => q.x(2))
  .if('out', 2, q => q.z(2))

Noise models

All three stochastic backends accept a noise option — either a named device or explicit parameters:

// Named device profile
circuit.run({ noise: 'forte-1' })
circuit.runClifford({ shots: 10000, noise: 'aria-1' })
circuit.dm({ noise: 'h2-1' })

// Custom depolarizing parameters
circuit.run({ noise: { p1: 0.001, p2: 0.005, pMeas: 0.004 } })

T1 / T2 relaxation

Convert hardware coherence times into per-gate probabilities:

const tGate = 200e-9, T1 = 50e-6, T2 = 30e-6

circuit.run({ shots: 4096, noise: {
  gamma:  1 - Math.exp(-tGate / T1),
  lambda: 1 - Math.exp(-2 * tGate * (1 / T2 - 1 / (2 * T1))),
}})

Custom Kraus channels

Supply your own channel as a set of Kraus operators. They must be trace-preserving — Σ_k K_k^†K_k = I — and one is sampled per shot per gate:

import { c } from '@kirkelliott/ket'

// Amplitude damping written out by hand, γ = 0.01
const g = 0.01
const K0 = [[c(1), c(0)], [c(0), c(Math.sqrt(1 - g))]]
const K1 = [[c(0), c(Math.sqrt(g))], [c(0), c(0)]]

circuit.run({ shots: 4096, noise: { kraus1: [K0, K1] } })

kraus1 applies after single-qubit gates only and kraus2 after two-qubit gates only — neither leaks into the other. Both are supported by run() and dm(), but not by runMps().

Noiseless circuits take the fast path — zero overhead. The density matrix backend applies exact per-gate depolarizing channels (no sampling).

Built-in algorithms

// Grover's search — find |101⟩ in 3 qubits
const circ = grover(3, (c) => {
  c = c.x(1)
  c = c.h(2)
  c = c.ccx(0, 1, 2)
  c = c.h(2)
  c = c.x(1)
  return c
})
circ.exactProbs()  // { '101': ~0.945, ... }

// QPE — estimate phase of T gate (φ = 1/8)
const qpe = phaseEstimation(3,
  (c, ctrl, pow, tgts) => c.cu1(Math.PI * pow / 4, ctrl, tgts[0]), 1)
qpe.run({ shots: 1000, seed: 42, initialState: '0001' })

Shor's algorithm

Not an oracle mock-up. The full Beauregard (2003) circuit, with modular exponentiation decomposed into primitive gates, simulated exactly — O(n³) gates, 2n+1 counting qubits, period recovered by continued fractions.

import { shorBeauregard } from '@kirkelliott/ket'

const r = shorBeauregard(15n, { a: 7n })

r.factors  // [5n, 3n]
r.period   // 4n        — 7⁴ ≡ 1 (mod 15), from phase estimation
r.method   // 'quantum' — the circuit really ran
r.qubits   // 19

Shor's tries classical shortcuts first, and at these sizes they hit often — an even N, or a base sharing a factor with N, is resolved by gcd without building a circuit. method tells you which path ran, so a demo can prove the quantum one did:

shorBeauregard(15n, { a: 3n }).method  // 'classical-gcd' — no circuit
shorBeauregard(15n, { a: 7n }).method  // 'quantum'

This does not reach cryptographic sizes — no classical simulator does. What you get is the real circuit, exactly simulated, at sizes you can inspect.

The building blocks are exported too, so you can assemble the circuit yourself or reuse the number theory:

VQE & optimization

const H = [{ coeff: 0.5, ops: 'ZI' }, { coeff: 0.5, ops: 'IZ' }]
const ansatz = realAmplitudes(2, 2)  // paramCount = 6

const { energy, params, converged } = minimize(
  ansatz, H, Array(ansatz.paramCount).fill(0.1), { lr: 0.2, steps: 500 }
)

VQE beyond statevector width

Ground states obeying an area law stay at low bond dimension, so the MPS variants run ansätze far wider than 2ⁿ amplitudes would allow — a 12-qubit Heisenberg chain costs about what a 12-qubit statevector does, but the same code keeps going into the hundreds:

import { efficientSU2, minimizeMps } from '@kirkelliott/ket'

const ansatz = efficientSU2(12, 2)
const { energy, params } = minimizeMps(
  ansatz, heisenbergH, Array(ansatz.paramCount).fill(0.1),
  { lr: 0.12, steps: 80 }
)

Two circuit methods support this workflow directly:

const s = ansatz.bind(params).bondEntropies()
// s[i] = entropy across the cut between qubit i and i+1

Pauli algebra

const X = PauliOp.from([{ coeff: 1, ops: 'X' }])
const Y = PauliOp.from([{ coeff: 1, ops: 'Y' }])
X.mul(Y)           // iZ
X.commutator(Y)    // 2iZ

const H1 = PauliOp.from([{ coeff: 1, ops: 'ZI' }, { coeff: 1, ops: 'IZ' }])
const H2 = PauliOp.from([{ coeff: 0.5, ops: 'XX' }])
vqe(circuit, H1.add(H2).toTerms())

Import / Export

// Import
const c = Circuit.fromQASM(`
  OPENQASM 2.0;
  qreg q[2];
  h q[0];
  cx q[0],q[1];
`)

// Export
c.toQASM()     // OpenQASM 2.0 string
c.toIonQ()     // IonQ JSON for hardware submission
c.toCirq()     // Cirq Python code
c.toLatex()    // quantikz LaTeX environment

OpenQASM coverage

fromQASM parses OpenQASM 2.0 and the 3.0 subset that maps onto it, auto-detecting the version.

Supported: any number of qreg/creg (or qubit/bit) declarations, laid out in declaration order — qreg a[2]; qreg b[2]; puts b[0] at qubit 2; gate definitions expanded inline, including parameterised and nested ones; opaque; measure in both the -> and assignment forms; reset; barrier; if (c == N); register-wide broadcast (h q;, measure q -> c;); and all of qelib1.inc plus the U/CX builtins.

Angle expressions accept pi, + - * / ^, parentheses, scientific notation, sin cos tan exp ln sqrt, and — inside a gate body — that gate's own parameters.

Rejected with a TypeError rather than silently mis-parsed: undeclared registers, out-of-range indices, gate arity mismatches, registers that cannot broadcast together, gate modifiers (ctrl @, inv @, pow @), gphase, for/while/def, else, let, and QASM 3 classical types beyond bit.

Devices

import { DEVICES, IONQ_DEVICES, Circuit } from '@kirkelliott/ket'

const forte = DEVICES['forte-1']  // { qubits: 36, noise: { p1, p2, pMeas } }

// Validate before submitting
circuit.checkDevice('aria-1')   // throws if incompatible
circuit.toIonQ()                // safe to call after check

Retired devices are kept in the table so a circuit written against one still reports honestly, rather than silently matching nothing. Rows marked estimated are not vendor-published figures — treat them as order-of-magnitude. Regenerate from IonQ’s API with scripts/refresh-ionq-devices.ts.

IONQ_DEVICES is the subset of DEVICES that declares nativeGates, so it is keyed only by IonQ machines.

Expanding unsupported gates

toIonQ() is a serializer, not a compiler: it rejects any gate outside IonQ’s set rather than silently expanding it, so the gate count you inspect is the gate count you send. toIonQBasis() is the explicit expansion step. QFT and modular-exponentiation circuits are built almost entirely from cu1 and could not previously be exported at all:

const shor = shorCircuit(15n, 7n, 3)
shor.toIonQ()                       // TypeError: 'cu1' is not serializable

const native = shor.toIonQBasis()   // cu1 -> rz + controlled rz; cswap -> controlled x
native.toIonQ()                     // 5,798 gates, submit-ready

shor.toIonQBasis().compile('forte-1')   // and on to gpi/gpi2/ms

Controlled gates are emitted natively, as IonQ’s format expects: a base gate plus a controls array, so ccx is {gate:'x', controls:[a,b], target:t} rather than fifteen Clifford+T gates. What remains is still not free — cu1 becomes two gates and cswap three — so check gateCounts() before submitting. Each rule is exact up to global phase.

Transpiling to native gates

compile(device) rewrites a circuit into the target's hardware-native gate set, returning a new Circuit. For IonQ that means GPI, GPI2, and MS, plus virtual-Z frame rotations that cost nothing on hardware:

const native = new Circuit(2).h(0).cnot(0, 1).compile('forte-1')

native.draw()
// q0: ─Rz(π/2)──GPI2(0)──Rz(π/2)──GPI2(π/2)──MS(0,0)──GPI2(-π/2)──Rz(-π/2)─
//                                               │
// q1: ─GPI2(π)───────────────────────────────MS(0,0)───────────────────────

native.toIonQ()   // submit-ready

Barriers pass through. Gates with no native translation throw TypeError, as do unknown device names — so a failed compile is loud rather than silently approximate.

Running on IonQ hardware

toIonQ() produces the payload; runIonQ submits it, waits and fetches the results. No dependency is added — the client uses the global fetch, so it runs anywhere ket does.

import { Circuit, runIonQ, countsToProbs } from '@kirkelliott/ket'

const bell = new Circuit(2).h(0).cnot(0, 1)
bell.checkDevice('forte-1')            // fail fast, before spending queue time

const { job, counts } = await runIonQ(bell.toIonQ(), {
  apiKey: process.env.IONQ_API_KEY,
  target: 'qpu.forte-1',               // or 'simulator' — free
  shots: 1024,
  noise: { model: 'ideal' },
  onPoll: j => console.log(j.status),
})

countsToProbs(counts, 2, 1024)         // { '00': 0.49, '11': 0.51 }

Results are not on the job object. GET /jobs/{id} returns metadata and a results_url; the histogram lives behind it. runIonQ and getIonQResults follow that automatically — reading job.data will find nothing.

State the noise model rather than inheriting it. Omitting noise leaves the choice to IonQ’s server-side default, which is not guaranteed to be noiseless. At any real depth a device model flattens the distribution completely, and a flat distribution is indistinguishable from a wrong answer. Pass { model: 'ideal' }, or { model: 'forte-1', seed: 100 } to sample a device profile.

Angle units differ between the two gate sets. QIS gates (rx/ry/rz/xx/yy/zz) take rotation in radians — IonQ’s own example gives Rx(π/2) as rotation: 1.5708. The native gates (gpi/gpi2/ms) take phase in turns, where 1.0 = 2π. ket handles both. The distinction is not cosmetic: getting it wrong submits a valid circuit that computes something else, and Clifford-only circuits such as a Bell pair are blind to the error.

Bit order matches, and that is verified rather than assumed. IonQ histogram keys are little-endian integers with qubit i at 2ⁱ, which is exactly ket’s convention, so no conversion is applied. Submitting x(0) on two qubits returns {"1": 1.0}.

Calling from a browser: use a proxy

api.ionq.co sends no access-control-allow-origin, so a browser cannot call it directly. That is a feature: an IonQ API key buys paid hardware time, and a key in a JS bundle is a key anyone can spend. Keep it server-side and forward.

// server — the key never leaves this process
app.post('/api/ionq/jobs', async (req, res) => {
  res.json(await submitIonQ(req.body.input, { apiKey: process.env.IONQ_API_KEY }))
})

// browser — same library, same types, no key
const { id } = await submitIonQ(circuit.toIonQ(), {
  endpoint: '/api/ionq', target: 'qpu.forte-1', shots: 1024,
})

Both halves import the same Circuit, so the browser can simulate for instant feedback and hand the identical object to the server to run on hardware — one representation, no serialisation boundary between two languages.

Visualization

const bell = new Circuit(2).h(0).cnot(0, 1)

console.log(bell.draw())
// q0: ─H──●─
//          │
// q1: ─────⊕─

// Write SVG files
import fs from 'fs'
fs.writeFileSync('bell.svg', bell.toSVG())
fs.writeFileSync('state.svg', bell.blochSphere(0))

Light and dark themes 0.6.1

All three SVG exporters take a theme of 'light' (the default) or 'dark'. The colours are baked into the SVG, so the output stays self-contained — it does not depend on the host page's stylesheet or on prefers-color-scheme:

bell.toSVG({ theme: 'dark' })
bell.blochSphere(0, { theme: 'dark' })

const d = bell.run({ shots: 1024 })
d.toSVG({ theme: 'dark', title: 'bell state' })

Dark swaps the surface for #0c0e18 with light ink and a teal accent; the geometry is identical between themes. An unrecognised theme name throws TypeError rather than silently falling back. Every chart and diagram on this site is generated with theme: 'dark'.

Serialization

Lossless round-trip through JSON. All operation types preserved: gates, measure, reset, if, named sub-circuits.

const json    = circuit.toJSON()
const restored = Circuit.fromJSON(json)

// Or pass a parsed object
const restored2 = Circuit.fromJSON(JSON.parse(json))

Mutable adapter /compat

@kirkelliott/ket/compat exports a QuantumCircuit class with a mutable, column-indexed API: gates are placed at an explicit column, the circuit grows to fit any wire named, and run() stores state on the instance. It matches the API shape used by the quantum-circuit package, so code written against that shape runs unmodified.

import { QuantumCircuit } from '@kirkelliott/ket/compat'

const circuit = new QuantumCircuit(2)
circuit.addGate('h', 0, 0)
circuit.addGate('cx', 1, [0, 1])
circuit.addMeasure(0, 'c', 0)
circuit.run()

circuit.getCregValue('c')          // 0 or 1
circuit.measureAllMultishot(1024)  // { '00': 517, '11': 507 }
circuit.toKet()                    // → Circuit, for the rest of the library

It is an adapter, not a second API to build on. toKet() returns the equivalent immutable Circuit, which is where everything else on this page applies.

Bit order is converted at the boundary: strings from stateAsString and measureAllMultishot put the highest wire leftmost, the opposite of ket's native order. probabilities() and measureAll() are indexed by wire. Measurement is non-destructive — a measure gate writes to its register but leaves the state alone, unless the circuit also has a classically-controlled gate or a reset. Seeding is the one addition: run(initialValues, { seed }) is reproducible, and unseeded runs draw fresh entropy each time.

DensityMatrix

circuit.dm() returns a DensityMatrix — the exact mixed state, with per-gate channels applied analytically rather than sampled. Use it when you want the state itself rather than shot statistics.

const rho = new Circuit(2).h(0).cnot(0, 1).dm({ noise: { p1: 0.01 } })

rho.purity()         // 0.986756 — decoherence has pulled it off 1
rho.entropy()        // 0.057778 bits of mixedness
rho.probabilities()  // { '11': 0.4999999999999999, '00': 0.4999999999999999 }
rho.get(0, 0)        // { re: 0.4999999999999999, im: 0 }

Accepts DmNoiseParams or a named device, and a dense option that tunes the sparse → dense promotion (default 1/32 fill). Practical to about 12 qubits, since ρ is 4ⁿ.

CliffordSim

CliffordSim is exported directly for researchers who need more control than runClifford — custom decoders, syndrome extraction, mid-circuit readout.

import { CliffordSim } from '@kirkelliott/ket'

const sim = new CliffordSim(2)
sim.h(0); sim.cnot(0, 1)

sim.stabilizerGenerators()  // ['+XX', '+ZZ']

// Inject error
sim.x(0)
sim.stabilizerGenerators()  // ['+XX', '-ZZ']  ← syndrome bit flipped

const outcome = sim.measure(0, Math.random())

Quantum error correction

Sweep physical error rate to find the logical threshold:

// Surface code threshold curve
for (const p2 of [0.001, 0.005, 0.01, 0.02, 0.05]) {
  const result = surfaceCode.runClifford({ shots: 10000, noise: { p2 } })
  console.log(p2, result.probs['0'])  // logical error rate vs physical
}

For detailed threshold analysis, use CliffordSim directly to extract stabilizer syndromes after each noise injection step without going through the full circuit runner.