Quantum API

typescript

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

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

Module Loading

`ensureLoaded(): Promise<void>`

Loads the WASM module. Must complete before any quantum operations. Caches the result, so 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>`

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.

`getMaxStateSize(): number`

Maximum number of basis amplitudes any single state vector can hold (compile-time limit, currently 100,000). See Lifecycle: State Budget.

`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

typescript

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)
`m.forced_measure_predicate(predicates, value)`	`number`	Force predicate measurement outcome (replay)

Lifecycle

Function	Signature	Description
`destroy`	`m.destroy(prop)`	Factorize the qudit out of its shared state vector and release the property
`is_valid`	`prop.is_valid()`	Check if a property is still usable (returns `false` after `destroy()`)

See Lifecycle & State Management for usage guide.

State Budget Queries

Function	Signature	Returns	Description
`num_active_qudits`	`m.num_active_qudits(prop)`	`number`	Number of qudits in this property's shared quantum state
`state_vector_size`	`m.state_vector_size(prop)`	`number`	Current number of basis amplitudes (sparse size)

See Lifecycle: State Budget for backpressure patterns.

Read-Only Queries

typescript

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

Batch Execution

`m.executeBatch(ops: BatchOp[]): BatchResult`

Execute multiple gate operations in a single WASM call. See Gates: Batch Gate Execution for the full guide.

BatchOp

typescript

type OpCode =
  | 'cycle' | 'shift' | 'clock'
  | 'x' | 'z' | 'y'
  | 'hadamard' | 'inverse_hadamard'
  | 'swap' | 'i_swap'
  | 'phase_rotate';

interface BatchOp {
  op: OpCode;
  target?: QFProperty;
  target2?: QFProperty;       // swap, i_swap
  fraction?: number;          // omit for non-fractional variant
  angle?: number;             // phase_rotate only
  predicates?: QFPredicate[];
}

BatchResult

typescript

interface BatchResult {
  opsExecuted: number;   // how many completed before stopping
  success: boolean;
  errorMessage: string;  // non-empty on failure
}

`m.executeBatchTape(properties: QFProperty[], tape: Float64Array): BatchResult`

High-throughput batch execution using a pre-encoded Float64Array. Bypasses per-op embind marshaling — one bulk memcpy instead of thousands of JS object conversions. Use for pre-built operation sequences with 50+ ops.

Tape format per operation (variable length, minimum 6 doubles):

[opcode, target_idx, target2_idx, fraction, angle, pred_count,
 (pred_prop_idx, pred_value, pred_is_equal) × pred_count]

target_idx / target2_idx: index into properties array, or -1 for none
fraction: NaN for non-fractional gate variant
pred_is_equal: 1.0 for is(), 0.0 for is_not()

OP Constants

typescript

import { OP } from "quantum-forge/quantum";

OP.CYCLE              // 0
OP.SHIFT              // 1
OP.CLOCK              // 2
OP.X                  // 3
OP.Z                  // 4
OP.Y                  // 5
OP.HADAMARD           // 6
OP.INVERSE_HADAMARD   // 7
OP.SWAP               // 8
OP.I_SWAP             // 9
OP.PHASE_ROTATE       // 10
OP.ROTATE_BASIS_PAIR  // 11

ROTATE_BASIS_PAIR has a different tape layout: [11, nq, -1, NaN, angle, 0, a[0]..a[nq-1], b[0]..b[nq-1]]

See Gates: Batch Gate Execution for usage guide.

QuantumRecorder

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

Constructor

typescript

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

typescript

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

QuantumSimulation

Isolated simulation context. Properties created within a simulation can entangle with each other but not with properties from other simulations or the global context. See Lifecycle: QuantumSimulation for usage guide.

Constructor

typescript

new QuantumSimulation()
// or
QuantumForge.createSimulation()

API

Method	Returns	Description
`createProperty(dimension)`	`QFProperty`	Create a property bound to this simulation
`destroyProperty(prop)`	`void`	Factorize one property out, auto-split separable qudits
`factorizeAllSeparable()`	`void`	Scan all shared states and split separable qudits
`getModule()`	`QFModule`	Access the WASM module for gate and query calls
`destroy()`	`void`	Release all properties and state vectors at once

Error Types

All WASM operations throw standard Error objects with a message prefix identifying the error type. See Error Handling for the full guide.

Prefix	Meaning
`[QuantumForgeStateSizeError]`	State vector would exceed the maximum size (100,000 basis amplitudes)
`[QuantumForgeOutOfMemoryError]`	WASM memory allocation failed
`[QuantumForgeError]`	General error (invalid operation, destroyed property, cross-simulation entanglement)

QuantumOperation

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

Quantum API ​

Module Loading ​

ensureLoaded(): Promise<void> ​

startBackgroundLoad(logger?: LoggerInterface): void ​

isReady(): boolean ​

setWasmBasePath(path: string): void ​

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

Module Queries ​

getModule(): QFModule ​

getVersion(): string ​

getMaxDimension(): number ​

getMaxQudits(): number ​

getMaxStateSize(): number ​

getWasmMemoryBytes(): number | null ​

QuantumPropertyManager ​

Constructor ​

Public API ​

WASM Gate Functions ​

Single-Property Gates ​

Two-Property Gates ​

Phase ​

Measurement ​

Lifecycle ​

State Budget Queries ​

Read-Only Queries ​

Batch Execution ​

m.executeBatch(ops: BatchOp[]): BatchResult ​

BatchOp ​

BatchResult ​

m.executeBatchTape(properties: QFProperty[], tape: Float64Array): BatchResult ​

OP Constants ​

QuantumRecorder ​

Constructor ​

Recording API ​

PredicateSpec ​

QuantumSimulation ​

Constructor ​

API ​

Error Types ​

QuantumOperation ​

Quantum API

Module Loading

`ensureLoaded(): Promise<void>`

`startBackgroundLoad(logger?: LoggerInterface): void`

`isReady(): boolean`

`setWasmBasePath(path: string): void`

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

Module Queries

`getModule(): QFModule`

`getVersion(): string`

`getMaxDimension(): number`

`getMaxQudits(): number`

`getMaxStateSize(): number`

`getWasmMemoryBytes(): number | null`

QuantumPropertyManager

Constructor

Public API

WASM Gate Functions

Single-Property Gates

Two-Property Gates

Phase

Measurement

Lifecycle

State Budget Queries

Read-Only Queries

Batch Execution

`m.executeBatch(ops: BatchOp[]): BatchResult`

BatchOp

BatchResult

`m.executeBatchTape(properties: QFProperty[], tape: Float64Array): BatchResult`

OP Constants

QuantumRecorder

Constructor

Recording API

PredicateSpec

QuantumSimulation

Constructor

API

Error Types

QuantumOperation