quantum-forge 2.7.1 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Real quantum mechanics for game developers. Superposition, entanglement, and interference powered by a compiled C++ quantum simulator running via WebAssembly.
 
-This is the core package: WASM loader, quantum property manager, and Vite plugin. For the full game framework (engine, rendering, input, audio, and more), install [`quantum-forge-engine`](https://www.npmjs.com/package/quantum-forge-engine) instead. It depends on this package, so one install gets both.
+This is the core package: WASM loader, quantum property handles, and Vite plugin. For the full game framework (engine, rendering, input, audio, and more), install [`quantum-forge-engine`](https://www.npmjs.com/package/quantum-forge-engine) instead. It depends on this package, so one install gets both.
 
 ## Install
 
@@ -26,46 +26,52 @@ export default defineConfig({
 
 > **ESM note:** If using `vite.config.js` (not `.ts` or `.mjs`), add `"type": "module"` to your `package.json`.
 
-### 2. Use Quantum Mechanics
+### 2. Declare a quantum property
 
 ```typescript
-import { ensureLoaded, getModule, QuantumPropertyManager } from "quantum-forge/quantum";
+import { ensureLoaded, quantum } from "quantum-forge/quantum";
 
-await ensureLoaded(); // once, before any quantum call
+await ensureLoaded(); // once, before the first quantum() call
 
-const qpm = new QuantumPropertyManager({ dimension: 2 });
-const m = getModule(); // gates and measurement live here, not on the manager
-
-const qubit = qpm.acquireProperty(); // |0⟩, from the pool
-m.hadamard(qubit);                   // equal superposition
+const color = quantum(["red", "green", "blue"]); // a qutrit, starts "red"
+color.superpose();                               // equal superposition (alias for hadamard())
 
 // Read without collapsing
-m.probabilities([qubit]);
-// [{ probability: 0.5, qudit_values: [0] }, { probability: 0.5, qudit_values: [1] }]
+color.probability("green");  // 1/3
+color.probabilities();
+// [{ value: "red", probability: 1/3 }, { value: "green", ... }, { value: "blue", ... }]
 
-// Measure (collapses to 0 or 1)
-const [value] = m.measure_properties([qubit]);
+// Measure (collapses to one value)
+const seen = color.measure(); // "red", "green" or "blue"
 
-// Return the handle to the pool, reset to |0⟩
-qpm.releaseProperty(qubit, value);
+// End its life. dispose() measures, then frees the qudit for the next quantum() call.
+color.dispose();
 ```
 
-`QuantumPropertyManager` owns handles: `acquireProperty`, `releaseProperty`, `setProperty` / `getProperty` / `deleteProperty` by id, and `getModule()`. Games usually extend it and wrap the module calls in game-specific methods.
+A property is declared by the values it can take, and the dimension is how many there are.
+`quantum(3)` is the numeric form, with values `0`, `1`, `2`. A property needs at least two
+values. A `using` declaration disposes the handle at the end of the scope; it needs TypeScript
+5.2 or newer with `"ESNext.Disposable"` in the tsconfig `lib`. Code that never writes `using`
+needs neither.
 
 ### 3. Entanglement
 
+Entanglement is what an interaction leaves behind. A gate that touches two properties is an
+interaction:
+
 ```typescript
-const a = qpm.acquireProperty();
-const b = qpm.acquireProperty();
+import { quantum, measure } from "quantum-forge/quantum";
 
-m.cycle(a);           // a = |1⟩
-m.i_swap(a, b, 0.5);  // half iSwap: exactly one of the pair ends up |1⟩
+const a = quantum([false, true]).flip(); // a = true
+const b = quantum([false, true]);        // b = false
+a.iSwap(b, 0.5);                         // half iSwap: exactly one of the pair ends up true
 
-const [va, vb] = m.measure_properties([a, b]);
-// va + vb === 1, every time
+const [va, vb] = measure(a, b);          // one step, both collapse
+// va !== vb, every time
 ```
 
-Predicated gates entangle too. `m.shift(b, undefined, [a.is(1)])` is a CNOT: `b` flips only where `a` is `|1⟩`. Predicates are the third argument, so pass `undefined` as the fraction to get the discrete gate.
+So is a gate whose predicate reads another property. `b.flip({ when: [a.is(true)] })` is a
+CNOT: `b` flips only where `a` is `true`. `a.is(1)` builds the same predicate by index.
 
 ## Editions
 
@@ -103,26 +109,36 @@ Node 22 or newer.
 
 | Export | Contents |
 |--------|----------|
-| `quantum-forge/quantum` | `ensureLoaded`, `startBackgroundLoad`, `isReady`, `getModule`, `QuantumPropertyManager`, `QuantumRecorder`, `useQuantumForgeBuild`, `setWasmBasePath`, `getVersion`, `getMaxDimension`, `getMaxQudits`, `getMaxStateSize`, `getAttribution`, `registerServiceWorker`, `OP` |
+| `quantum-forge/quantum` | `quantum`, `Quantum`, `measure`, `forcedMeasure`, `probabilities`, `densityMatrix`, `measureWhen`, `forcedMeasureWhen`, `probabilityWhen`, `phaseRotate`, `isQuantum`, `observeQuantum`, `clearQuantumCache`, `QuantumRecorder`, `ensureLoaded`, `startBackgroundLoad`, `isReady`, `useQuantumForgeBuild`, `setWasmBasePath`, `getVersion`, `getMaxDimension`, `getMaxQudits`, `getMaxStateSize`, `getAttribution`, `registerServiceWorker`, `OP` |
 | `quantum-forge/logging` | `Logger` |
 | `quantum-forge/vite-plugin` | `quantumForgeVitePlugin` |
 
 ## Gates
 
-All gates are functions on the module from `getModule()`. Each takes the target property, an optional `fraction`, and optional `predicates`.
-
-| Gate | Qudits | Description |
-|------|--------|-------------|
-| `hadamard` | 1 | Equal superposition |
-| `cycle` | 1 | \|0⟩→\|1⟩→\|2⟩→\|0⟩ (a NOT at dimension 2) |
-| `shift` (`x`) | 1 | Inverse of cycle; same as cycle at dimension 2 |
-| `clock` (`z`) | 1 | Phase rotation |
-| `y` | 1 | Pauli Y, dimension 2 only |
-| `i_swap` | 2 | Entangling swap; `fraction` is required |
-| `swap` | 2 | Value swap |
-| `phase_rotate` | any | Phase on the states matching the predicates |
-
-Measurement: `measure_properties`, `measure_predicate`, `forced_measure_properties`. Read-only: `probabilities`, `predicate_probability`, `reduced_density_matrix`. Omit `fraction` for the discrete gate; pass a number for the continuous variant (`0.5` is the square root of the gate).
+Gates are methods on the handle. Each alias runs exactly the same gate as the physics name
+beside it.
+
+| Gate | Alias | Qudits | Description |
+|------|-------|--------|-------------|
+| `hadamard` | `superpose` | 1 | Equal superposition |
+| `inverseHadamard` | | 1 | Undoes `hadamard` |
+| `cycle` | `next`, and `flip` on qubits | 1 | \|0⟩→\|1⟩→\|2⟩→\|0⟩ (a NOT at dimension 2) |
+| `shift` | `previous` | 1 | Inverse of cycle; same as cycle at dimension 2 |
+| `clock` | `phase` | 1 | Phase rotation |
+| `x`, `z` | | 1 | Pauli X (same as `shift`) and Pauli Z (same as `clock`) |
+| `y` | | 1 | Pauli Y, dimension 2 only |
+| `iSwap(other, fraction)` | | 2 | Entangling swap; `fraction` is required |
+| `swap(other)` | | 2 | Value swap |
+| `phaseRotate(angle, { when })` | | any | Free function: phase on the part of the state where the predicates hold |
+
+Every gate except `inverseHadamard`, `swap` and `iSwap` takes an optional fraction first. An
+omitted fraction, or exactly 1, is the discrete gate; any other number is the continuous
+version, and 0.5 is the square root of the gate. Predicates go last, in `{ when: [...] }`.
+
+Measurement: `prop.measure()`, `measure(...props)`, `measureWhen(preds)`, and the forced
+variants for replays and tests, which throw if the forced value has zero probability.
+Read-only: `prop.probability(value)`, `prop.probabilities()`,
+`probabilities(...props)`, `probabilityWhen(preds)`, `densityMatrix(...props)`.
 
 ## Documentation