ket

TypeScript quantum circuit simulator. Immutable API, four backends (statevector, MPS, density matrix, Clifford), 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>

Two bundle flavors ship in the package: ket.js (341 kB unminified, for bundlers that tree-shake) and ket.min.js (154 kB, for direct CDN use). The unpkg field points to the minified build. No dependencies either way.

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()     // { '00': 0.5, '11': 0.5 }

// 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:

All 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

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

IONQ_DEVICES additionally exposes nativeGates for compilation and validation — aria-1, forte-1, and harmony.

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.

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))

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()  // { '00': 0.5, '11': 0.5 }
rho.get(0, 0)        // { re: 0.5, 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.