Quantum API

import {
  QuantumPropertyManager,
  QuantumRecorder,
  ensureLoaded,
  startBackgroundLoad,
  isReady,
  getModule,
  getQuantumForge,
  getVersion,
  getMaxDimension,
  getMaxQudits,
  getWasmMemoryBytes,
  setWasmBasePath,
  registerServiceWorker,
} from "quantum-forge/quantum";

import type {
  QuantumOperation,
  SerializedPredicate,
  PredicateSpec,
  QuantumRecorderHook,
} from "quantum-forge/quantum";

Module Loading

ensureLoaded(): Promise<void>

Loads the WASM module. Must complete before any quantum operations. Caches the result — subsequent calls resolve immediately.

startBackgroundLoad(logger?: LoggerInterface): void

Begins loading in the background via requestIdleCallback. Call early for faster perceived startup.

isReady(): boolean

Non-blocking check. Returns true if the module has finished loading.

setWasmBasePath(path: string): void

Set the URL path where WASM files are served. Default: "/quantum-forge". Must be called before ensureLoaded().

registerServiceWorker(swPath?: string): Promise<ServiceWorkerRegistration | null>

Register the offline caching service worker. Default path: "/quantum-forge-sw.js".

Module Queries

getModule(): QFModule

Returns the loaded WASM module for gate calls and queries.

getVersion(): string

WASM module version string.

getMaxDimension(): number

Maximum qudit dimension supported by this build.

getMaxQudits(): number

Maximum number of qudits supported by this build.

getWasmMemoryBytes(): number | null

Current WASM heap usage in bytes.

QuantumPropertyManager

Base class for quantum property lifecycle management. Extend or compose this in your game.

Constructor

new QuantumPropertyManager(options?: {
  dimension?: number;  // default: 2
  logger?: LoggerInterface;
})

Public API

Method	Returns	Description
acquireProperty()	QFProperty	Get a property at |0⟩ (pool first, then fresh)
releaseProperty(prop, value)	void	Reset to |0⟩ and return to pool
setProperty(id, prop)	void	Map a string ID to a property handle
getProperty(id)	QFProperty | undefined	Get handle by ID
hasProperty(id)	boolean	Check if ID exists
deleteProperty(id)	void	Remove ID mapping (does not release)
removeProperty(id)	void	Measure + release + delete in one call
getModule()	QFModule	Access the WASM module for all gate and query calls
dimension	number	The configured dimension (readonly)
clear()	void	Clear all properties and pool
size	number	Number of registered properties
poolSize	number	Number of pooled (recycled) properties
setRecorder(recorder)	void	Attach a QuantumRecorder for opt-in operation logging
getRecorder()	QuantumRecorderHook | undefined	Get attached recorder

WASM Gate Functions

All gates are called via getModule(). Names are snake_case.

Single-Property Gates

Function	Signature	Description
cycle	m.cycle(prop, fraction?, predicates?)	Cyclic permutation (NOT for dim=2)
shift	m.shift(prop, fraction?, predicates?)	Shift gate / Pauli X
hadamard	m.hadamard(prop, fraction?, predicates?)	Hadamard gate
inverse_hadamard	m.inverse_hadamard(prop, predicates?)	Adjoint Hadamard
clock	m.clock(prop, fraction, predicates?)	Clock gate / Z-rotation
y	m.y(prop, fraction?, predicates?)	Pauli Y (dim=2 only, throws otherwise)
reset	m.reset(prop, value)	Reset property to |0⟩ from known value

Two-Property Gates

Function	Signature	Description
i_swap	m.i_swap(p1, p2, fraction, predicates?)	iSwap entanglement gate
swap	m.swap(p1, p2, predicates?)	Swap two properties

Phase

Function	Signature	Description
phase_rotate	m.phase_rotate(predicates, angle)	Phase rotation (predicates required)

Measurement

Function	Returns	Description
m.measure_properties(props)	number[]	Measure and collapse
m.forced_measure_properties(props, values)	number[]	Force specific outcomes (replay)
m.measure_predicate(predicates)	number	Projective predicate measurement (0 or 1)

Read-Only Queries

m.probabilities(props: QFProperty[]): Array<{
  probability: number;
  qudit_values: number[];
}>

m.reduced_density_matrix(props: QFProperty[]): Array<{
  row_values: number[];
  col_values: number[];
  value: { real: number; imag: number };
}>

QuantumRecorder

Opt-in recording and replay of quantum operations. Attach to a manager via setRecorder().

Constructor

new QuantumRecorder(manager: QuantumPropertyManager)

Recording API

Method	Returns	Description
startRecording()	void	Begin recording; resets log
stopRecording()	QuantumOperation[]	Stop and return log
isRecording()	boolean	Check recording status
getOperationLog()	QuantumOperation[]	Get log copy (even while recording)
replayLog(ops)	void	Clear manager state and replay from log
recordOp(op)	void	Record a gate operation manually
getIndex(prop)	number | undefined	Get recorded index for a property
buildWasmPredicates(specs)	QFPredicate[]	Build WASM predicates from specs
serializePredicates(specs)	SerializedPredicate[] | undefined	Serialize for log

See Recording & Replay for usage guide.

PredicateSpec

interface PredicateSpec {
  property: QFProperty;
  value: number;
  isEqual: boolean;  // true = "is this value", false = "is NOT this value"
}

QuantumOperation

Union type for all recorded operations. See Recording & Replay for the full type definition.