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 (unminified, for bundlers that tree-shake) and ket.min.js (110 kB, for direct CDN use). The unpkg field points to the minified build.

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)

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

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

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

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

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

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.

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

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

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.