@justinelliottcobb/amari-wasm 0.22.0 → 0.23.0

package/README.md

@@ -32,6 +32,30 @@ Amari is a comprehensive mathematical computing library that brings advanced alg
 
 Also includes bindings for: amari-network (geometric network analysis), amari-optimization (gradient descent, NSGA-II), amari-info-geom (Fisher metrics, statistical manifolds), amari-calculus (differential geometry, manifolds).
 
+### v0.23.0 Arbitrary-Signature GA (new in development)
+
+The `0.23.0` release introduces generic runtime-signature multivector support:
+
+- `WasmGenericMultivector(p, q, r)` — create and operate on multivectors of any Clifford algebra signature Cl(p, q, r) at runtime. Signature is chosen at construction time and all operations (geometric product, inner product, outer product, reverse, grade projection, exp, normalize, inverse) automatically use the correct metric.
+- `WasmGenericRotor` — rotors for any signature, created from bivectors via the exponential map.
+- **Match-table dispatch** for all 84 signatures with total dimension ≤ 6 (compile-time optimized).
+- **Cayley-table fallback** for larger dimensions with thread-local caching.
+
+8 fast-path aliases provide pre-configured wrappers for the most common signatures:
+
+| Alias | Signature | Use case |
+|-------|-----------|----------|
+| `WasmMultivector300` / `GA` | Cl(3,0,0) | 3D Euclidean rotations, graphics |
+| `WasmMultivector210` / `ST` | Cl(2,1,0) | 2+1 spacetime physics |
+| `WasmMultivector310` / `MINK` | Cl(3,1,0) | 3+1 Minkowski relativity |
+| `WasmMultivector200` / `PL` | Cl(2,0,0) | 2D planar / complex numbers |
+| `WasmMultivector030` / `QUAT` | Cl(0,3,0) | Pure quaternion algebra |
+| `WasmMultivector410` / `CGA` | Cl(4,1,0) | Conformal GA (translations as rotors) |
+| `WasmMultivector500` / `P5D` | Cl(5,0,0) | 5D Euclidean / projective GA |
+| `WasmMultivector110` / `S2D` | Cl(1,1,0) | Split-complex / 1+1 spacetime |
+
+Backward compatibility: `WasmMultivector` and `WasmRotor` remain as aliases for `WasmMultivector300` and `WasmRotor300`.
+
 ### v0.22.0 CGT / Surreal WASM Surface
 
 The `0.22.0` release exposes the new short-game and short-surreal Rust APIs to JavaScript/TypeScript:
@@ -74,39 +98,47 @@ yarn add @justinelliottcobb/amari-wasm
 ## Quick Start
 
 ```typescript
-import init, { WasmMultivector, WasmRotor } from '@justinelliottcobb/amari-wasm';
+import init, {
+  WasmGenericMultivector,
+  WasmGenericRotor,
+  WasmMultivector,   // alias for WasmMultivector300 (Cl 3,0,0)
+  WasmRotor,
+} from '@justinelliottcobb/amari-wasm';
 
 async function main() {
   await init();
 
-  // Create basis vectors
-  const e1 = WasmMultivector.basis_vector(0);
-  const e2 = WasmMultivector.basis_vector(1);
-
-  // Compute geometric product
-  const product = e1.geometric_product(e2);
-  console.log(product.to_string()); // e12 (bivector)
-
-  // Create a rotor for 90-degree rotation
-  const rotor = WasmRotor.from_axis_angle(
-    WasmMultivector.basis_vector(2),
-    Math.PI / 2
-  );
-
-  // Rotate a vector
-  const vector = WasmMultivector.from_coefficients(
-    new Float64Array([1, 0, 0, 0, 0, 0, 0, 0])
-  );
-  const rotated = rotor.rotate_vector(vector);
-
-  // Clean up WASM memory
-  e1.free(); e2.free(); product.free();
-  rotor.free(); vector.free(); rotated.free();
+  // ── Generic API: any signature at runtime ──
+
+  // Cl(2,1,0) — 2+1 spacetime
+  const e1 = WasmGenericMultivector.basisVector(2, 1, 0, 0);
+  const e3 = WasmGenericMultivector.basisVector(2, 1, 0, 2);
+
+  // e3 squares to -1 in Cl(2,1,0) (negative metric signature)
+  const e3Sq = e3.geometric_product(e3);
+  console.log(e3Sq.getCoefficient(0)); // -1
+
+  // ── Fast-path alias: Cl(3,0,0) Euclidean ──
+
+  const a = WasmMultivector.basisVector(0);  // e1
+  const b = WasmMultivector.basisVector(1);  // e2
+  const product = a.geometric_product(b);
+  console.log(product.getCoefficients()); // [0, 0, 0, 1, 0, 0, 0, 0] = e12
+
+  // ── Rotor in Cl(3,0,0) ──
+
+  const bivector = a.outer_product(b); // e12 bivector plane
+  const rotor = WasmGenericRotor.fromBivector(bivector, Math.PI / 2);
+  const rotated = rotor.apply(a);
+  // 90° rotation in e12 plane: e1 → e2
+  console.log(Math.abs(rotated.getCoefficient(2))); // ≈ 1.0
 }
 
 main();
 ```
 
+**Fast-path aliases**: `WasmMultivector300`, `WasmMultivector210` (ST), `WasmMultivector310` (Minkowski), `WasmMultivector200` (planar), `WasmMultivector030` (quaternion), `WasmMultivector410` (CGA), `WasmMultivector500` (5D), `WasmMultivector110` (split). Each has a matching `WasmRotor*` and a TypeScript convenience export (`GA`, `ST`, `MINK`, `PL`, `QUAT`, `CGA`, `P5D`, `S2D`).
+
 See the [docs/](docs/) directory for detailed guides and API references for each module.
 
 ## Use Cases