@molcrafts/molrs 0.0.6 → 0.0.8

package/molrs.d.ts

@@ -5,14 +5,14 @@
  * Column-oriented data store with typed arrays.
  *
  * Each column is identified by a string key and has a fixed data type
- * (`f32`, `i32`, `u32`, `string`). All columns in a block must have
+ * (`F`, `i32`, `u32`, `string`). All columns in a block must have
  * the same number of rows.
  *
  * # Supported column types
  *
  * | JS type | Rust type | dtype string | Setter | Getter (copy) | Getter (view) |
  * |---------|-----------|-------------|--------|---------------|---------------|
- * | `Float32Array` | `f32` | `"f32"` | `setColF32` | `copyColF32` | `viewColF32` |
+ * | `Float32Array` / `Float64Array` | `F` | `"f32"` / `"f64"` | `setColF` | `copyColF` | `viewColF` |
  * | `Int32Array` | `i32` | `"i32"` | `setColI32` | `copyColI32` | `viewColI32` |
  * | `Uint32Array` | `u32` | `"u32"` | `setColU32` | `copyColU32` | `viewColU32` |
  * | `string[]` | `String` | `"string"` | `setColStr` | `copyColStr` | -- |
@@ -21,21 +21,21 @@
  *
  * ```js
  * const block = new Block();
- * block.setColF32("x", new Float32Array([1.0, 2.0, 3.0]));
- * block.setColF32("y", new Float32Array([0.0, 0.0, 0.0]));
+ * block.setColF("x", coordsX);
+ * block.setColF("y", coordsY);
  * console.log(block.nrows()); // 3
  * console.log(block.keys());  // ["x", "y"]
  *
- * const x = block.copyColF32("x"); // owned copy, safe to keep
+ * const x = block.copyColF("x"); // owned copy, safe to keep
  * ```
  */
 export class Block {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Owned `Float32Array` copy of a column.
+     * Owned JS float typed-array copy of a column.
      *
-     * Returns a new JS `Float32Array` that is an independent copy of
+     * Returns a new JS float typed array that is an independent copy of
      * the column data. Safe to store and use across allocations.
      *
      * # Arguments
@@ -44,20 +44,20 @@ export class Block {
      *
      * # Returns
      *
-     * An owned `Float32Array` copy of the column.
+     * An owned JS float typed-array copy of the column.
      *
      * # Errors
      *
-     * Throws if the column does not exist or is not of type `f32`.
+     * Throws if the column does not exist or is not of the active float type.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const x = block.copyColF32("x");
+     * const x = block.copyColF("x");
      * console.log(x[0]); // 1.0
      * ```
      */
-    copyColF32(key: string): Float32Array;
+    copyColF(key: string): Float64Array;
     /**
      * Owned `Int32Array` copy of a column.
      *
@@ -120,7 +120,8 @@ export class Block {
     /**
      * Return the data type string for a column.
      *
-     * Possible return values: `"f32"`, `"i32"`, `"u32"`, `"bool"`,
+     * Possible return values: `"f32"` or `"f64"` for float columns,
+     * plus `"i32"`, `"u32"`, `"bool"`,
      * `"string"`, `"u8"`. Returns `undefined` if the column does
      * not exist.
      *
@@ -135,7 +136,7 @@ export class Block {
      * # Example (JavaScript)
      *
      * ```js
-     * console.log(block.dtype("x"));      // "f32"
+     * console.log(block.dtype("x"));      // "f32" or "f64"
      * console.log(block.dtype("symbol")); // "string"
      * ```
      */
@@ -197,7 +198,7 @@ export class Block {
      *
      * ```js
      * const block = new Block();
-     * block.setColF32("values", new Float32Array([1, 2, 3]));
+     * block.setColF("values", values);
      * ```
      */
     constructor();
@@ -241,12 +242,12 @@ export class Block {
      */
     renameColumn(old_key: string, new_key: string): boolean;
     /**
-     * Set a float column from a `Float32Array`.
+     * Set a float column from a JS float typed array.
      *
      * # Arguments
      *
      * * `key` - Column name (e.g., `"x"`, `"mass"`, `"charge"`)
-     * * `data` - `Float32Array` with the column values
+     * * `data` - JS float typed array with the column values
      * * `shape` - Optional shape array for multi-dimensional data
      *   (e.g., `[N, 3]` for an Nx3 matrix stored flat). If omitted,
      *   the data is stored as a 1D column.
@@ -259,12 +260,12 @@ export class Block {
      * # Example (JavaScript)
      *
      * ```js
-     * block.setColF32("x", new Float32Array([1.0, 2.0, 3.0]));
+     * block.setColF("x", xCoords);
      * // Multi-dimensional: 2 rows x 3 columns
-     * block.setColF32("pos", new Float32Array([1,2,3, 4,5,6]), [2, 3]);
+     * block.setColF("pos", positions, [2, 3]);
      * ```
      */
-    setColF32(key: string, data: Float32Array, shape?: Uint32Array | null): void;
+    setColF(key: string, data: Float64Array, shape?: Uint32Array | null): void;
     /**
      * Set a signed integer column from an `Int32Array`.
      *
@@ -326,13 +327,13 @@ export class Block {
      */
     setColU32(key: string, data: Uint32Array): void;
     /**
-     * Zero-copy `Float32Array` view into WASM linear memory.
+     * Zero-copy JS float typed-array view into WASM linear memory.
      *
      * Returns a view backed directly by the block's storage in WASM
      * memory. This avoids copying but the view becomes **invalid**
      * if WASM linear memory grows (due to any allocation).
      *
-     * Use [`copyColF32`](Block::copy_col_f32) for a safe, long-lived copy.
+     * Use [`copyColF`](Block::copy_col_f) for a safe, long-lived copy.
      *
      * # Arguments
      *
@@ -340,20 +341,20 @@ export class Block {
      *
      * # Returns
      *
-     * A `Float32Array` view into WASM memory.
+     * A JS float typed-array view into WASM memory.
      *
      * # Errors
      *
-     * Throws if the column does not exist or is not of type `f32`.
+     * Throws if the column does not exist or is not of the active float type.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const view = block.viewColF32("x"); // zero-copy, use immediately
-     * const copy = block.copyColF32("x"); // safe to keep
+     * const view = block.viewColF("x"); // zero-copy, use immediately
+     * const copy = block.copyColF("x"); // safe to keep
      * ```
      */
-    viewColF32(key: string): Float32Array;
+    viewColF(key: string): Float64Array;
     /**
      * Zero-copy `Int32Array` view into WASM linear memory.
      *
@@ -411,8 +412,8 @@ export class Block {
  * # Example (JavaScript)
  *
  * ```js
- * const h = new Float32Array([10, 0, 0, 0, 10, 0, 0, 0, 10]);
- * const origin = new Float32Array([0, 0, 0]);
+ * const h = floatArrayH;
+ * const origin = floatArrayOrigin;
  * const box = new Box(h, origin, true, true, true);
  * console.log(box.volume()); // 1000.0
  * console.log(box.lengths().toCopy()); // [10, 10, 10]
@@ -427,7 +428,7 @@ export class Box {
      * # Arguments
      *
      * * `a` - Side length of the cube in angstrom (A)
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -444,12 +445,12 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
+     * const origin = originVec;
      * const box = Box.cube(10.0, origin, true, true, true);
      * console.log(box.volume()); // 1000.0
      * ```
      */
-    static cube(a: number, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
+    static cube(a: number, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
     /**
      * Calculate displacement vectors between two sets of coordinates.
      *
@@ -478,8 +479,8 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const a = WasmArray.from(new Float32Array([1,1,1]), [1,3]);
-     * const b = WasmArray.from(new Float32Array([9,9,9]), [1,3]);
+     * const a = WasmArray.from(aCoords, [1, 3]);
+     * const b = WasmArray.from(bCoords, [1, 3]);
      * const d = box.delta(a, b, true); // minimum-image displacement
      * ```
      */
@@ -496,7 +497,7 @@ export class Box {
      * * `b` - `WasmArray` with shape `[N, 3]` (target positions in A)
      * * `minimum_image` - If `true`, apply minimum image convention
      * * `out_block` - Target [`Block`] to write the result into
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -538,7 +539,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const L = box.lengths().toCopy(); // Float32Array [10, 10, 10]
+     * const L = box.lengths().toCopy(); // Float32Array or Float64Array [10, 10, 10]
      * ```
      */
     lengths(): WasmArray;
@@ -547,10 +548,10 @@ export class Box {
      *
      * # Arguments
      *
-     * * `h` - 3x3 cell matrix as `Float32Array` with 9 elements in
+     * * `h` - 3x3 cell matrix as a float typed array with 9 elements in
      *   row-major order: `[h00, h01, h02, h10, h11, h12, h20, h21, h22]`.
      *   All values in angstrom (A).
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom.
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -569,12 +570,12 @@ export class Box {
      *
      * ```js
      * // Triclinic box
-     * const h = new Float32Array([10, 2, 0, 0, 10, 0, 0, 0, 10]);
-     * const origin = new Float32Array([0, 0, 0]);
+     * const h = hMatrix;
+     * const origin = originVec;
      * const box = new Box(h, origin, true, true, true);
      * ```
      */
-    constructor(h: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
+    constructor(h: Float64Array, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
     /**
      * Return the box origin as a `WasmArray` with shape `[3]`.
      *
@@ -587,7 +588,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const o = box.origin().toCopy(); // Float32Array [0, 0, 0]
+     * const o = box.origin().toCopy(); // Float32Array or Float64Array [0, 0, 0]
      * ```
      */
     origin(): WasmArray;
@@ -596,9 +597,9 @@ export class Box {
      *
      * # Arguments
      *
-     * * `lengths` - Box dimensions as `Float32Array` with 3 elements
+     * * `lengths` - Box dimensions as a float typed array with 3 elements
      *   `[lx, ly, lz]` in angstrom (A)
-     * * `origin` - 3D origin vector as `Float32Array` with 3 elements
+     * * `origin` - 3D origin vector as a float typed array with 3 elements
      *   `[x, y, z]` in angstrom
      * * `pbc_x` - Enable periodic boundary in x direction
      * * `pbc_y` - Enable periodic boundary in y direction
@@ -615,12 +616,12 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
-     * const box = Box.ortho(new Float32Array([10, 20, 30]), origin, true, true, true);
+     * const origin = originVec;
+     * const box = Box.ortho(lengthsVec, origin, true, true, true);
      * console.log(box.volume()); // 6000.0
      * ```
      */
-    static ortho(lengths: Float32Array, origin: Float32Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
+    static ortho(lengths: Float64Array, origin: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean): Box;
     /**
      * Return the box tilt factors as a `WasmArray` with shape `[3]`.
      *
@@ -636,7 +637,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const t = box.tilts().toCopy(); // Float32Array [0, 0, 0]
+     * const t = box.tilts().toCopy(); // Float32Array or Float64Array [0, 0, 0]
      * ```
      */
     tilts(): WasmArray;
@@ -648,7 +649,7 @@ export class Box {
      *
      * * `coords` - `WasmArray` with shape `[N, 3]` (fractional, dimensionless)
      * * `out_block` - Target [`Block`]
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -669,7 +670,7 @@ export class Box {
      *
      * * `coords` - `WasmArray` with shape `[N, 3]` (Cartesian, A)
      * * `out_block` - Target [`Block`]
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -702,7 +703,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const frac = WasmArray.from(new Float32Array([0.5, 0.5, 0.5]), [1, 3]);
+     * const frac = WasmArray.from(fracCoords, [1, 3]);
      * const cart = box.toCart(frac);
      * console.log(cart.toCopy()); // [5, 5, 5] for a 10x10x10 box
      * ```
@@ -731,7 +732,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const cart = WasmArray.from(new Float32Array([5, 5, 5]), [1, 3]);
+     * const cart = WasmArray.from(coords, [1, 3]);
      * const frac = box.toFrac(cart);
      * console.log(frac.toCopy()); // [0.5, 0.5, 0.5] for a 10x10x10 box
      * ```
@@ -771,7 +772,7 @@ export class Box {
      * # Example (JavaScript)
      *
      * ```js
-     * const pos = WasmArray.from(new Float32Array([12, -1, 5]), [1, 3]);
+     * const pos = WasmArray.from(positions, [1, 3]);
      * const wrapped = box.wrap(pos); // wraps into [0, lx) x [0, ly) x [0, lz)
      * ```
      */
@@ -787,7 +788,7 @@ export class Box {
      * * `coords` - `WasmArray` with shape `[N, 3]` containing
      *   Cartesian coordinates in angstrom (A)
      * * `out_block` - Target [`Block`] to write the result into
-     * * `out_key` - Column name for the result (f32, shape `[N, 3]`)
+     * * `out_key` - Column name for the result (float, shape `[N, 3]`)
      *
      * # Errors
      *
@@ -803,6 +804,55 @@ export class Box {
     wrapToBlock(coords: WasmArray, out_block: Block, out_key: string): void;
 }
 
+/**
+ * Mass-weighted cluster center calculator.
+ */
+export class CenterOfMass {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute centers of mass.
+     */
+    compute(frame: Frame, cluster_result: ClusterResult): CenterOfMassResult;
+    /**
+     * Create a center-of-mass calculator.
+     *
+     * Pass `null` for uniform masses, or a float typed array of per-particle masses.
+     */
+    constructor(masses?: Float64Array | null);
+}
+
+/**
+ * Result of center-of-mass computation.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const com = new CenterOfMass().compute(frame, clusterResult);
+ * com.centersOfMass();   // Float32Array or Float64Array [x0,y0,z0, ...]
+ * com.clusterMasses();   // Float32Array or Float64Array
+ * ```
+ */
+export class CenterOfMassResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Zero-copy `Float64Array` view of mass-weighted centers, flat
+     * `[x0,y0,z0, x1,y1,z1, ...]`. **Invalidated** on WASM memory growth.
+     */
+    centersOfMass(): Float64Array;
+    /**
+     * Zero-copy `Float64Array` view of total mass per cluster.
+     * **Invalidated** on WASM memory growth.
+     */
+    clusterMasses(): Float64Array;
+    /**
+     * Number of clusters.
+     */
+    readonly numClusters: number;
+}
+
 /**
  * Distance-based cluster analysis using BFS on the neighbor graph.
  *
@@ -869,6 +919,26 @@ export class Cluster {
     constructor(min_cluster_size: number);
 }
 
+/**
+ * Geometric cluster centers with minimum image convention.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const centers = new ClusterCenters().compute(frame, clusterResult);
+ * // Float32Array or Float64Array [x0,y0,z0, x1,y1,z1, ...]
+ * ```
+ */
+export class ClusterCenters {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute geometric centers. Returns a flat float typed array `[x0,y0,z0, ...]`.
+     */
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor();
+}
+
 /**
  * Result of a distance-based cluster analysis.
  *
@@ -924,10 +994,10 @@ export class ClusterResult {
  * # Conventions
  *
  * - The `"atoms"` block should contain per-atom properties: `symbol`
- *   (string), `x`/`y`/`z` (f32, coordinates in angstrom), and optionally
- *   `mass` (f32, atomic mass units) and `charge` (f32, elementary charges).
+ *   (string), `x`/`y`/`z` (F, coordinates in angstrom), and optionally
+ *   `mass` (F, atomic mass units) and `charge` (F, elementary charges).
  * - The `"bonds"` block should contain bond topology: `i`/`j` (u32,
- *   zero-based atom indices) and `order` (f32, bond order: 1.0 = single,
+ *   zero-based atom indices) and `order` (F, bond order: 1.0 = single,
  *   1.5 = aromatic, 2.0 = double, 3.0 = triple).
  *
  * # Example (JavaScript)
@@ -935,7 +1005,7 @@ export class ClusterResult {
  * ```js
  * const frame = new Frame();
  * const atoms = frame.createBlock("atoms");
- * atoms.setColF32("x", new Float32Array([0.0, 1.54]));
+ * atoms.setColF("x", xCoords);
  * ```
  */
 export class Frame {
@@ -977,7 +1047,7 @@ export class Frame {
      *
      * ```js
      * const atoms = frame.createBlock("atoms");
-     * atoms.setColF32("x", new Float32Array([1.0, 2.0]));
+     * atoms.setColF("x", xCoords);
      * ```
      */
     createBlock(key: string): Block;
@@ -1017,11 +1087,57 @@ export class Frame {
      * ```js
      * const atoms = frame.getBlock("atoms");
      * if (atoms) {
-     *   const x = atoms.copyColF32("x");
+     *   const x = atoms.copyColF("x");
      * }
      * ```
      */
     getBlock(key: string): Block | undefined;
+    /**
+     * Retrieve a named grid attached to this frame.
+     *
+     * Returns a cloned [`Grid`] wrapper, or `undefined` if the grid does
+     * not exist. The returned object is independent of the frame — mutations
+     * to it are not reflected in the frame without a subsequent
+     * [`insertGrid`](Frame::insert_grid) call.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to retrieve.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const g = frame.getGrid("chgcar");
+     * if (g) {
+     *   const arr = g.getArray("rho");
+     * }
+     * ```
+     */
+    getGrid(name: string): Grid | undefined;
+    /**
+     * Return the names of all grids attached to this frame.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = frame.gridNames(); // e.g. ["chgcar", "spin"]
+     * ```
+     */
+    gridNames(): Array<any>;
+    /**
+     * Returns `true` if a named grid is attached to this frame.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to look up.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.hasGrid("chgcar"); // true or false
+     * ```
+     */
+    hasGrid(name: string): boolean;
     /**
      * Insert a block by deep-copying its data into this frame's store.
      *
@@ -1049,6 +1165,31 @@ export class Frame {
      * ```
      */
     insertBlock(key: string, block: Block): void;
+    /**
+     * Attach a grid to this frame under the given name.
+     *
+     * If a grid with the same name already exists it is replaced. The grid
+     * data is moved into the frame; the JS `Grid` object becomes empty after
+     * this call and should not be reused.
+     *
+     * # Arguments
+     *
+     * * `name` — Name to store the grid under (e.g., `"chgcar"`).
+     * * `grid` — The [`Grid`] to attach.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+     * grid.insertArray("rho", rhoData);
+     * frame.insertGrid("chgcar", grid);
+     * ```
+     */
+    insertGrid(name: string, grid: Grid): void;
     /**
      * Create a new, empty `Frame` with no blocks and no simulation box.
      *
@@ -1078,6 +1219,24 @@ export class Frame {
      * ```
      */
     removeBlock(key: string): void;
+    /**
+     * Remove a named grid from this frame.
+     *
+     * # Arguments
+     *
+     * * `name` — Grid name to remove.
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.removeGrid("chgcar");
+     * ```
+     */
+    removeGrid(name: string): void;
     /**
      * Rename a block from `old_key` to `new_key`.
      *
@@ -1162,21 +1321,290 @@ export class Frame {
      * # Example (JavaScript)
      *
      * ```js
-     * const origin = new Float32Array([0, 0, 0]);
+     * const origin = originVec;
      * frame.simbox = Box.cube(10.0, origin, true, true, true);
      * ```
      */
     set simbox(value: Box | null | undefined);
 }
 
+/**
+ * A uniform spatial grid storing multiple named scalar arrays.
+ *
+ * All arrays in a `Grid` share the same spatial definition: dimensions
+ * (`[nx, ny, nz]`), Cartesian origin, cell matrix (columns are lattice
+ * vectors, matching VASP/molrs convention), and periodic boundary flags.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * // Create a 10×10×10 cubic grid
+ * const origin = new Float32Array([0, 0, 0]);
+ * const cell = new Float32Array([
+ *   10, 0, 0,   // first column (a vector)
+ *    0,10, 0,   // second column (b vector)
+ *    0, 0,10,   // third column (c vector)
+ * ]);
+ * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+ *
+ * // Insert a density array (must have length = 10*10*10 = 1000)
+ * const rho = new Float32Array(1000).fill(1.0);
+ * grid.insertArray("rho", rho);
+ *
+ * // Retrieve it
+ * const arr = grid.getArray("rho");
+ * console.log(arr.toCopy());
+ * ```
+ */
+export class Grid {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Names of all scalar arrays stored in this grid.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = grid.arrayNames(); // e.g. ["rho", "spin"]
+     * ```
+     */
+    arrayNames(): Array<any>;
+    /**
+     * Cell matrix in Ångström as a flat array of length 9 in column-major
+     * order (columns are lattice vectors, matching VASP/molrs convention).
+     *
+     * Layout: `[col0_x, col0_y, col0_z, col1_x, col1_y, col1_z, col2_x, col2_y, col2_z]`
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const c = grid.cell();
+     * const flat = c.toCopy(); // Float32Array of length 9
+     * ```
+     */
+    cell(): WasmArray;
+    /**
+     * Grid dimensions `[nx, ny, nz]`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.dim()); // [10, 10, 10]
+     * ```
+     */
+    dim(): Uint32Array;
+    /**
+     * Retrieve a named scalar array as a zero-copy `Float64Array` view
+     * over the underlying WASM memory. Flat row-major order, length
+     * `nx * ny * nz`. Use [`Grid::dim`] for shape.
+     *
+     * **Warning**: the view is invalidated on any WASM memory growth.
+     * Copy it in JS (`new Float64Array(view)`) if it needs to outlive
+     * subsequent allocations.
+     *
+     * Returns `undefined` if the named array does not exist.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const view = grid.getArray("rho");          // zero-copy
+     * const copy = new Float64Array(view);        // owned copy if needed
+     * ```
+     */
+    getArray(name: string): Float64Array | undefined;
+    /**
+     * Returns `true` if a named array is present in this grid.
+     *
+     * # Arguments
+     *
+     * * `name` — Array name to look up.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * grid.hasArray("rho"); // true or false
+     * ```
+     */
+    hasArray(name: string): boolean;
+    /**
+     * Insert (or replace) a named scalar array.
+     *
+     * The provided `data` must have exactly `nx * ny * nz` elements in
+     * row-major `(ix, iy, iz)` order.
+     *
+     * # Arguments
+     *
+     * * `name` — Array name.
+     * * `data` — Float32Array with length equal to `grid.total()`.
+     *
+     * # Errors
+     *
+     * Throws if `data.length != nx * ny * nz`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const rho = new Float32Array(grid.total()).fill(0.5);
+     * grid.insertArray("rho", rho);
+     * ```
+     */
+    insertArray(name: string, data: Float64Array): void;
+    /**
+     * Returns `true` if no arrays are stored.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.isEmpty()); // true for a freshly created grid
+     * ```
+     */
+    isEmpty(): boolean;
+    /**
+     * Number of named arrays stored in this grid.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.len()); // e.g. 2
+     * ```
+     */
+    len(): number;
+    /**
+     * Create a new empty grid with the given spatial definition.
+     *
+     * # Arguments
+     *
+     * * `dim_x`, `dim_y`, `dim_z` — Number of grid points along each axis.
+     * * `origin` — Float32Array of length 3: Cartesian origin in Ångström.
+     * * `cell` — Float32Array of length 9: cell matrix in column-major order.
+     *   `cell[0..3]` is the first lattice vector (a), `cell[3..6]` is b,
+     *   `cell[6..9]` is c (matching VASP/molrs convention where columns are
+     *   lattice vectors).
+     * * `pbc_x`, `pbc_y`, `pbc_z` — Periodic boundary flags for each axis.
+     *
+     * # Errors
+     *
+     * Throws if `origin` does not have length 3, or `cell` does not have
+     * length 9.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const origin = new Float32Array([0, 0, 0]);
+     * const cell = new Float32Array([10,0,0, 0,10,0, 0,0,10]);
+     * const grid = new Grid(10, 10, 10, origin, cell, true, true, true);
+     * ```
+     */
+    constructor(dim_x: number, dim_y: number, dim_z: number, origin: Float64Array, cell: Float64Array, pbc_x: boolean, pbc_y: boolean, pbc_z: boolean);
+    /**
+     * Cartesian origin in Ångström as a 1-D array of length 3.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const o = grid.origin();
+     * const arr = o.toCopy(); // Float32Array [ox, oy, oz]
+     * ```
+     */
+    origin(): WasmArray;
+    /**
+     * Periodic boundary flags as a `Uint8Array`-compatible slice.
+     *
+     * Each element is `1` (periodic) or `0` (not periodic).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.pbc()); // [1, 1, 1]
+     * ```
+     */
+    pbc(): Uint8Array;
+    /**
+     * Total number of voxels: `nx * ny * nz`.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * console.log(grid.total()); // 1000 for a 10×10×10 grid
+     * ```
+     */
+    total(): number;
+}
+
+/**
+ * Gyration tensor per cluster.
+ *
+ * Returns flat array: `[g00,g01,g02, g10,g11,g12, g20,g21,g22, ...]` per cluster.
+ */
+export class GyrationTensor {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute gyration tensors. Returns a flat float typed array (9 values per cluster).
+     */
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor();
+}
+
+/**
+ * Moment of inertia tensor per cluster.
+ */
+export class InertiaTensor {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute inertia tensors. Returns a flat float typed array (9 values per cluster).
+     */
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor(masses?: Float64Array | null);
+}
+
+/**
+ * LAMMPS dump trajectory file reader.
+ *
+ * Reads multi-frame LAMMPS dump files (the format produced by the
+ * `dump` command). Each frame produces a [`Frame`] containing an
+ * `"atoms"` block with columns matching the dump header (e.g.
+ * `id`, `type`, `x`, `y`, `z`, `vx`, `vy`, `vz`).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const reader = new LAMMPSDumpReader(dumpContent);
+ * console.log(reader.len()); // number of timesteps
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * ```
+ */
+export class LAMMPSDumpReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Check whether the file contains no frames.
+     */
+    isEmpty(): boolean;
+    /**
+     * Return the number of frames in the dump file.
+     */
+    len(): number;
+    /**
+     * Create a new LAMMPS dump reader from string content.
+     */
+    constructor(content: string);
+    /**
+     * Read a frame at the given step index.
+     */
+    read(step: number): Frame | undefined;
+}
+
 /**
  * LAMMPS data file reader.
  *
  * Reads LAMMPS data files (the format written by `write_data`). The
  * reader produces a [`Frame`] containing:
  *
- * - `"atoms"` block: `type` (i32), `x`, `y`, `z` (f32, angstrom),
- *   and optionally `charge` (f32)
+ * - `"atoms"` block: `type` (i32), `x`, `y`, `z` (F, angstrom),
+ *   and optionally `charge` (F)
  * - `"bonds"` block (if present): `i`, `j` (u32), `type` (i32)
  * - Simulation box (`simbox`) with PBC
  *
@@ -1280,7 +1708,7 @@ export class LinkedCell {
      * Finds all unique pairs `(i < j)` of atoms within the cutoff
      * distance using the cell-list algorithm.
      *
-     * The frame must have an `"atoms"` block with `x`, `y`, `z` (f32) columns.
+     * The frame must have an `"atoms"` block with `x`, `y`, `z` (F) columns.
      * If the frame has a `simbox`, periodic boundary conditions are used.
      * Otherwise, a free-boundary bounding box is auto-generated.
      *
@@ -1301,7 +1729,7 @@ export class LinkedCell {
      * ```js
      * const lc = new LinkedCell(3.0);
      * const nlist = lc.build(frame);
-     * const dists = nlist.distances(); // Float32Array
+     * const dists = nlist.distances(); // Float32Array or Float64Array
      * ```
      */
     build(frame: Frame): NeighborList;
@@ -1385,7 +1813,7 @@ export class MSD {
      * # Arguments
      *
      * * `frame` - Frame with `"atoms"` block containing
-     *   `x`, `y`, `z` (f32) columns
+     *   `x`, `y`, `z` (F) columns
      *
      * # Errors
      *
@@ -1446,7 +1874,7 @@ export class MSD {
  * ```js
  * const result = msd.compute(frame);
  * console.log(result.mean);              // number (A^2)
- * console.log(result.perParticle());     // Float32Array (A^2)
+ * console.log(result.perParticle());     // Float32Array or Float64Array (A^2)
  * ```
  */
 export class MSDResult {
@@ -1454,12 +1882,11 @@ export class MSDResult {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Per-particle squared displacements as `Float32Array` in A^2.
-     *
-     * `perParticle()[i]` is `|r_i(t) - r_i(0)|^2` for particle `i`.
-     * Length equals the number of atoms.
+     * Zero-copy `Float64Array` view of per-particle squared displacements
+     * in A². `perParticle()[i]` is `|r_i(t) - r_i(0)|²` for particle `i`.
+     * **Invalidated** on WASM memory growth; copy in JS if needed.
      */
-    perParticle(): Float32Array;
+    perParticle(): Float64Array;
     /**
      * System-average mean squared displacement in A^2.
      *
@@ -1469,6 +1896,19 @@ export class MSDResult {
     readonly mean: number;
 }
 
+/**
+ * Reader for MolRec Zarr v3 archives.
+ */
+export class MolRecReader {
+    free(): void;
+    [Symbol.dispose](): void;
+    countAtoms(): number;
+    countFrames(): number;
+    free(): void;
+    constructor(files: Map<any, any>);
+    readFrame(t: number): Frame | undefined;
+}
+
 /**
  * Result of a neighbor search: all atom pairs within a distance cutoff.
  *
@@ -1493,7 +1933,7 @@ export class MSDResult {
  *
  * const i = nlist.queryPointIndices(); // Uint32Array
  * const j = nlist.pointIndices();      // Uint32Array
- * const d = nlist.distances();         // Float32Array (in A)
+ * const d = nlist.distances();         // Float32Array or Float64Array (in A)
  * ```
  */
 export class NeighborList {
@@ -1501,28 +1941,26 @@ export class NeighborList {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Squared pairwise distances in A^2, as a `Float32Array`.
-     *
-     * More efficient than `distances()` when you only need to
-     * compare or threshold distances.
+     * Zero-copy `Float64Array` view of squared pairwise distances in A^2.
+     * Same invalidation caveat as [`queryPointIndices`](Self::query_point_indices).
      */
-    distSq(): Float32Array;
+    distSq(): Float64Array;
     /**
-     * Pairwise distances in angstrom (A), as a `Float32Array`.
+     * Pairwise distances in angstrom (A). Computed lazily from `distSq`.
      *
-     * `distances()[k]` is the distance between query point
-     * `queryPointIndices()[k]` and reference point `pointIndices()[k]`.
+     * Returns an owned copy because distances are derived on the fly
+     * (`sqrt` per pair) rather than stored.
      */
-    distances(): Float32Array;
+    distances(): Float64Array;
     /**
-     * Reference point indices (`j`) for each pair, as a `Uint32Array`.
+     * Zero-copy `Uint32Array` view of reference point indices (`j`).
+     * Same invalidation caveat as [`queryPointIndices`](Self::query_point_indices).
      */
     pointIndices(): Uint32Array;
     /**
-     * Query point indices (`i`) for each pair, as a `Uint32Array`.
-     *
-     * The `k`-th pair connects query point `queryPointIndices()[k]`
-     * to reference point `pointIndices()[k]`.
+     * Zero-copy `Uint32Array` view of query point indices (`i`) over
+     * WASM memory. **Invalidated** on any WASM memory growth — copy
+     * in JS (`new Uint32Array(view)`) if it needs to outlive later calls.
      */
     queryPointIndices(): Uint32Array;
     /**
@@ -1552,8 +1990,8 @@ export class NeighborList {
  *
  * PDB files contain a single molecular structure. The reader produces
  * a [`Frame`] with an `"atoms"` block containing columns such as
- * `name` (string), `resname` (string), `x`, `y`, `z` (f32, angstrom),
- * and optionally `occupancy` and `bfactor` (f32).
+ * `name` (string), `resname` (string), `x`, `y`, `z` (F, angstrom),
+ * and optionally `occupancy` and `bfactor` (F).
  *
  * # Example (JavaScript)
  *
@@ -1562,7 +2000,7 @@ export class NeighborList {
  * const frame = reader.read(0);
  * const atoms = frame.getBlock("atoms");
  * const names = atoms.copyColStr("name"); // ["CA", "CB", ...]
- * const x = atoms.copyColF32("x");
+ * const x = atoms.copyColF("x");
  * ```
  */
 export class PDBReader {
@@ -1648,8 +2086,8 @@ export class PDBReader {
  * const rdf = new RDF(100, 5.0);
  * const result = rdf.compute(frame, nlist);
  *
- * const r  = result.binCenters();  // Float32Array, bin centers in A
- * const gr = result.rdf();         // Float32Array, g(r) values
+ * const r  = result.binCenters();  // Float32Array or Float64Array, bin centers in A
+ * const gr = result.rdf();         // Float32Array or Float64Array, g(r) values
  * ```
  */
 export class RDF {
@@ -1679,7 +2117,7 @@ export class RDF {
      *
      * ```js
      * const result = rdf.compute(frame, nlist);
-     * const gr = result.rdf(); // Float32Array
+     * const gr = result.rdf(); // Float32Array or Float64Array
      * ```
      */
     compute(frame: Frame, neighbors: NeighborList): RDFResult;
@@ -1711,9 +2149,9 @@ export class RDF {
  *
  * ```js
  * const result = rdf.compute(frame, nlist);
- * const r  = result.binCenters();  // Float32Array [0.025, 0.075, ...]
- * const gr = result.rdf();         // Float32Array, normalized g(r)
- * const nr = result.pairCounts();  // Float32Array, raw counts
+ * const r  = result.binCenters();  // Float32Array or Float64Array [0.025, 0.075, ...]
+ * const gr = result.rdf();         // Float32Array or Float64Array, normalized g(r)
+ * const nr = result.pairCounts();  // Float32Array or Float64Array, raw counts
  * console.log("Volume:", result.volume, "A^3");
  * console.log("N_ref:", result.numPoints);
  * ```
@@ -1723,28 +2161,26 @@ export class RDFResult {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Bin center positions as `Float32Array` in angstrom (A).
-     *
-     * Length equals `n_bins` (the value passed to the `RDF` constructor).
+     * Zero-copy `Float64Array` view of bin center positions in A.
+     * Length equals `n_bins`. **Invalidated** on WASM memory growth;
+     * copy in JS if it needs to outlive later calls.
      */
-    binCenters(): Float32Array;
+    binCenters(): Float64Array;
     /**
-     * Bin edge positions as `Float32Array` in angstrom (A).
-     *
-     * Length is `n_bins + 1` (one more than bin centers).
+     * Zero-copy `Float64Array` view of bin edge positions in A.
+     * Length is `n_bins + 1`. Same invalidation caveat.
      */
-    binEdges(): Float32Array;
+    binEdges(): Float64Array;
     /**
-     * Raw (un-normalized) pair counts per bin as `Float32Array`.
+     * Zero-copy `Float64Array` view of raw (un-normalized) pair counts
+     * per bin. Same invalidation caveat.
      */
-    pairCounts(): Float32Array;
+    pairCounts(): Float64Array;
     /**
-     * Normalized g(r) values as `Float32Array` (dimensionless).
-     *
-     * A uniform ideal gas has g(r) = 1.0 everywhere. Peaks indicate
-     * preferred interatomic distances (coordination shells).
+     * Zero-copy `Float64Array` view of normalized g(r). Same invalidation
+     * caveat.
      */
-    rdf(): Float32Array;
+    rdf(): Float64Array;
     /**
      * Number of reference points used in the normalization.
      */
@@ -1756,112 +2192,63 @@ export class RDFResult {
 }
 
 /**
- * Reader for Zarr V3 simulation archives.
+ * Radius of gyration per cluster.
+ */
+export class RadiusOfGyration {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compute radii of gyration. Returns a float typed array of length `numClusters`.
+     */
+    compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
+    constructor(masses?: Float64Array | null);
+}
+
+/**
+ * MDL molfile / SDF (V2000 CTAB) reader.
+ *
+ * Parses the connection table found in `.mol` files and the record
+ * blocks of `.sdf` files. Coordinates come directly from the file —
+ * no 3D generation is performed. Only V2000 is supported; V3000
+ * records throw on read.
  *
- * Wraps [`SimulationStore`] from `molrs-core` for reading trajectory
- * frames and system metadata from an in-memory Zarr store. The store
- * is populated from a `Map<string, Uint8Array>` of file paths to
- * binary content.
+ * Produces a [`Frame`] with:
+ * - `"atoms"` block: `element` (string), `id` (u32, 1-based),
+ *   `x`, `y`, `z` (F, angstrom)
+ * - `"bonds"` block (if present): `atomi`, `atomj` (u32, 0-based),
+ *   `order` (u32)
+ *
+ * Multi-record SDF files expose each record as a separate frame via
+ * `read(step)`.
  *
  * # Example (JavaScript)
  *
  * ```js
- * const files = new Map();
- * files.set("zarr.json", new Uint8Array([...]));
- * files.set("system/.zarray", new Uint8Array([...]));
- * // ... etc.
- *
- * const reader = new SimulationReader(files);
- * const frame = reader.readFrame(0);
+ * const reader = new SDFReader(sdfContent);
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * const x = atoms.copyColF("x");
  * ```
  */
-export class SimulationReader {
+export class SDFReader {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Return the number of atoms in the system topology.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * console.log(reader.countAtoms()); // e.g., 256
-     * ```
+     * Check whether the file contains no records.
      */
-    countAtoms(): number;
+    isEmpty(): boolean;
     /**
-     * Return the number of trajectory frames in the archive.
-     *
-     * Returns `0` if no trajectory data is present.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string on I/O errors.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * console.log(reader.countFrames()); // e.g., 1000
-     * ```
+     * Return the total number of records in the SDF file.
      */
-    countFrames(): number;
+    len(): number;
     /**
-     * Create a reader from a map of file paths to binary content.
-     *
-     * The map keys are relative paths within the Zarr archive
-     * (e.g., `"zarr.json"`, `"system/.zarray"`). Values are the
-     * raw bytes of each file as `Uint8Array`.
-     *
-     * # Arguments
-     *
-     * * `files` - `Map<string, Uint8Array>` mapping archive paths
-     *   to their binary content
-     *
-     * # Returns
-     *
-     * A new `SimulationReader` ready to read frames.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string if the archive cannot be opened
-     * (e.g., missing required metadata files).
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const reader = new SimulationReader(filesMap);
-     * ```
+     * Create a new SDF reader from a string containing the file content.
      */
-    constructor(files: Map<any, any>);
+    constructor(content: string);
     /**
-     * Read a trajectory frame at the given time index.
-     *
-     * The returned [`Frame`] merges the static system topology
-     * (atoms, bonds) with the per-frame trajectory data (positions,
-     * velocities, etc.) at time step `t`.
-     *
-     * # Arguments
-     *
-     * * `t` - Zero-based time step index
-     *
-     * # Returns
-     *
-     * A [`Frame`] with merged system + trajectory data, or `undefined`
-     * if no trajectory is present.
-     *
-     * # Errors
-     *
-     * Throws a `JsValue` string on I/O or deserialization errors.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const frame = reader.readFrame(0);
-     * if (frame) {
-     *   const x = frame.getBlock("atoms").copyColF32("x");
-     * }
-     * ```
+     * Read the frame (SDF record) at the given step index.
      */
-    readFrame(t: number): Frame | undefined;
+    read(step: number): Frame | undefined;
 }
 
 /**
@@ -1882,7 +2269,7 @@ export class SimulationReader {
  *
  * const frame = ir.toFrame();
  * const atoms = frame.getBlock("atoms");
- * console.log(atoms.copyColStr("symbol")); // ["C", "C", "O", "H", ...]
+ * console.log(atoms.copyColStr("element")); // ["C", "C", "O", "H", ...]
  * ```
  */
 export class SmilesIR {
@@ -1898,7 +2285,7 @@ export class SmilesIR {
      *   are added. No 3D coordinates are present -- use
      *   [`generate3D`](crate::generate_3d_wasm) to embed coordinates.
      * - `"bonds"` block: `i`, `j` (u32, zero-based atom indices),
-     *   `order` (f32, bond order: 1.0 = single, 1.5 = aromatic,
+     *   `order` (F, bond order: 1.0 = single, 1.5 = aromatic,
      *   2.0 = double, 3.0 = triple).
      *
      * # Returns
@@ -1915,7 +2302,7 @@ export class SmilesIR {
      * ```js
      * const frame = ir.toFrame();
      * const bonds = frame.getBlock("bonds");
-     * const order = bonds.copyColF32("order");
+     * const order = bonds.copyColF("order");
      * ```
      */
     toFrame(): Frame;
@@ -1936,26 +2323,183 @@ export class SmilesIR {
 }
 
 /**
- * Owned f32 array with ndarray-compatible shape metadata.
+ * Graph-based molecular topology with automated detection of angles,
+ * dihedrals, impropers, connected components, and rings (SSSR).
+ *
+ * API mirrors igraph / molpy conventions.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const topo = Topology.fromFrame(frame);
+ * console.log(topo.nAtoms, topo.nBonds);
+ *
+ * const angles = topo.angles();       // Uint32Array [i,j,k, ...]
+ * const dihedrals = topo.dihedrals(); // Uint32Array [i,j,k,l, ...]
+ * const cc = topo.connectedComponents(); // Int32Array per-atom labels
+ *
+ * const rings = topo.findRings();
+ * console.log(rings.numRings);
+ * ```
+ */
+export class Topology {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Add a single atom.
+     */
+    addAtom(): void;
+    /**
+     * Add a bond between atoms `i` and `j`.
+     */
+    addBond(i: number, j: number): void;
+    /**
+     * All angle triplets as flat `Uint32Array` `[i,j,k, ...]`.
+     */
+    angles(): Uint32Array;
+    /**
+     * Whether atoms `i` and `j` are directly bonded.
+     */
+    areBonded(i: number, j: number): boolean;
+    /**
+     * All bond pairs as flat `Uint32Array` `[i0,j0, i1,j1, ...]`.
+     */
+    bonds(): Uint32Array;
+    /**
+     * Per-atom connected component labels as `Int32Array`.
+     *
+     * Labels are 0-based and contiguous. Each atom gets a component ID.
+     * Atoms in the same connected subgraph share the same label.
+     */
+    connectedComponents(): Int32Array;
+    /**
+     * Degree (number of bonds) of atom `idx`.
+     */
+    degree(idx: number): number;
+    /**
+     * Delete an atom by index.
+     */
+    deleteAtom(idx: number): void;
+    /**
+     * Delete a bond by edge index.
+     */
+    deleteBond(idx: number): void;
+    /**
+     * All proper dihedral quartets as flat `Uint32Array` `[i,j,k,l, ...]`.
+     */
+    dihedrals(): Uint32Array;
+    /**
+     * Compute the Smallest Set of Smallest Rings (SSSR).
+     */
+    findRings(): TopologyRingInfo;
+    /**
+     * Build a topology from a Frame's `bonds` block.
+     *
+     * Reads the `atoms` block for atom count and `bonds` block for
+     * `i`, `j` columns (Uint32).
+     */
+    static fromFrame(frame: Frame): Topology;
+    /**
+     * All improper dihedral quartets as flat `Uint32Array` `[center,i,j,k, ...]`.
+     */
+    impropers(): Uint32Array;
+    /**
+     * Neighbor atom indices of atom `idx` as `Uint32Array`.
+     */
+    neighbors(idx: number): Uint32Array;
+    /**
+     * Create a topology with `n` atoms and no bonds.
+     */
+    constructor(n_atoms: number);
+    /**
+     * Number of unique angles.
+     */
+    readonly nAngles: number;
+    /**
+     * Number of atoms (vertices).
+     */
+    readonly nAtoms: number;
+    /**
+     * Number of bonds (edges).
+     */
+    readonly nBonds: number;
+    /**
+     * Number of connected components.
+     */
+    readonly nComponents: number;
+    /**
+     * Number of unique proper dihedrals.
+     */
+    readonly nDihedrals: number;
+}
+
+/**
+ * Result of ring detection (SSSR) on a topology graph.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const rings = topo.findRings();
+ * console.log(rings.numRings);
+ * console.log(rings.ringSizes());   // Uint32Array
+ * console.log(rings.isAtomInRing(0));
+ *
+ * // Get all rings as flat array [size0, idx0_0, idx0_1, ..., size1, ...]
+ * const data = rings.rings();
+ * ```
+ */
+export class TopologyRingInfo {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Per-atom boolean mask as `Uint8Array` (0 or 1). 1 if atom is in any ring.
+     */
+    atomRingMask(n_atoms: number): Uint8Array;
+    /**
+     * Whether atom `idx` belongs to any ring.
+     */
+    isAtomInRing(idx: number): boolean;
+    /**
+     * Number of rings containing atom `idx`.
+     */
+    numAtomRings(idx: number): number;
+    /**
+     * Size of each ring as `Uint32Array`.
+     */
+    ringSizes(): Uint32Array;
+    /**
+     * All rings as flat `Uint32Array` with length-prefixed encoding:
+     * `[size0, atom0, atom1, ..., size1, atom0, atom1, ...]`.
+     */
+    rings(): Uint32Array;
+    /**
+     * Total number of rings detected.
+     */
+    readonly numRings: number;
+}
+
+/**
+ * Owned float array with ndarray-compatible shape metadata.
  *
- * Stores a flat `Vec<f32>` together with a shape descriptor (e.g.,
+ * Stores a flat `Vec<F>` together with a shape descriptor (e.g.,
  * `[N, 3]` for an Nx3 coordinate matrix). Used for passing
  * multi-dimensional numeric data across the WASM boundary.
  *
  * # Memory layout
  *
  * Data is stored in row-major (C) order, matching ndarray's default
- * and JavaScript's `Float32Array` convention.
+ * and JavaScript's float typed-array convention.
  *
  * # Example (JavaScript)
  *
  * ```js
  * // Create a 2x3 zero array
  * const arr = new WasmArray([2, 3]);
- * arr.writeFrom(new Float32Array([1,2,3, 4,5,6]));
+ * arr.writeFrom(floatArray);
  *
  * // Or from existing data
- * const arr2 = WasmArray.from(new Float32Array([1,2,3]), [1, 3]);
+ * const arr2 = WasmArray.from(floatArray, [1, 3]);
  *
  * // Get data back
  * const copy = arr.toCopy();       // safe owned copy
@@ -1966,15 +2510,15 @@ export class WasmArray {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Return the data type string. Always `"float"` for `WasmArray`.
+     * Return the concrete float dtype string for this build.
      */
     dtype(): string;
     /**
-     * Create a `WasmArray` from an existing JS `Float32Array`.
+     * Create a `WasmArray` from an existing JS float typed array.
      *
      * # Arguments
      *
-     * * `data` - Source `Float32Array`
+     * * `data` - Source float typed array (`Float32Array` or `Float64Array`)
      * * `shape` - Optional shape. If omitted, defaults to `[data.length]` (1D).
      *
      * # Returns
@@ -1988,11 +2532,11 @@ export class WasmArray {
      * # Example (JavaScript)
      *
      * ```js
-     * const arr = WasmArray.from(new Float32Array([1,2,3,4,5,6]), [2, 3]);
+     * const arr = WasmArray.from(floatArray, [2, 3]);
      * console.log(arr.shape()); // [2, 3]
      * ```
      */
-    static from(data: Float32Array, shape?: Uint32Array | null): WasmArray;
+    static from(data: Float64Array, shape?: Uint32Array | null): WasmArray;
     /**
      * Check whether the array contains no elements.
      */
@@ -2052,13 +2596,13 @@ export class WasmArray {
      * # Example (JavaScript)
      *
      * ```js
-     * const arr = WasmArray.from(new Float32Array([1, 2, 3]));
+     * const arr = WasmArray.from(floatArray);
      * console.log(arr.sum()); // 6.0
      * ```
      */
     sum(): number;
     /**
-     * Create an owned JS `Float32Array` copy of the data.
+     * Create an owned JS float typed-array copy of the data.
      *
      * The returned array is an independent copy that is safe to store
      * and use regardless of subsequent WASM memory operations.
@@ -2069,9 +2613,9 @@ export class WasmArray {
      * const copy = arr.toCopy(); // safe to keep indefinitely
      * ```
      */
-    toCopy(): Float32Array;
+    toCopy(): Float64Array;
     /**
-     * Zero-copy `Float32Array` view over this array's backing storage.
+     * Zero-copy float typed-array view over this array's backing storage.
      *
      * **Warning**: The returned view becomes **invalid** if WASM linear
      * memory grows (due to any allocation). Use [`toCopy`](WasmArray::to_copy)
@@ -2079,7 +2623,8 @@ export class WasmArray {
      *
      * # Safety (internal)
      *
-     * Uses `Float32Array::view` which creates an unowned view into
+     * Uses the corresponding JS float typed-array `view` constructor,
+     * which creates an unowned view into
      * WASM memory. The view must not outlive the `WasmArray` and must
      * not be used after any allocation that could trigger memory growth.
      *
@@ -2090,16 +2635,16 @@ export class WasmArray {
      * // Do NOT allocate between view creation and use
      * ```
      */
-    toTypedArray(): Float32Array;
+    toTypedArray(): Float64Array;
     /**
-     * Overwrite the array contents from a JS `Float32Array`.
+     * Overwrite the array contents from a JS float typed array.
      *
      * The source array must have exactly the same number of elements
      * as this `WasmArray` (i.e., the shape is preserved).
      *
      * # Arguments
      *
-     * * `arr` - Source `Float32Array` with matching length
+     * * `arr` - Source float typed array with matching length
      *
      * # Errors
      *
@@ -2109,10 +2654,10 @@ export class WasmArray {
      *
      * ```js
      * const wa = new WasmArray([3]);
-     * wa.writeFrom(new Float32Array([1.0, 2.0, 3.0]));
+     * wa.writeFrom(floatArray);
      * ```
      */
-    write_from(arr: Float32Array): void;
+    write_from(arr: Float64Array): void;
 }
 
 /**
@@ -2120,7 +2665,7 @@ export class WasmArray {
  *
  * Supports multi-frame trajectory files. Each frame produces a
  * [`Frame`] with an `"atoms"` block containing `element` (string)
- * and `x`, `y`, `z` (f32, coordinates in angstrom) columns.
+ * and `x`, `y`, `z` (F, coordinates in angstrom) columns.
  *
  * # Example (JavaScript)
  *
@@ -2131,7 +2676,7 @@ export class WasmArray {
  *
  * const frame = reader.read(0); // first frame
  * const atoms = frame.getBlock("atoms");
- * const x = atoms.copyColF32("x");
+ * const x = atoms.copyColF("x");
  * ```
  */
 export class XYZReader {
@@ -2208,13 +2753,13 @@ export class XYZReader {
 /**
  * Generate 3D coordinates for a molecular [`Frame`].
  *
- * The input frame must have an `"atoms"` block with a `"symbol"`
+ * The input frame must have an `"atoms"` block with a `"element"`
  * string column (element symbols like `"C"`, `"N"`, `"O"`). A
- * `"bonds"` block with `i`, `j` (u32) and `order` (f32) columns
+ * `"bonds"` block with `i`, `j` (u32) and `order` (F) columns
  * is required for correct geometry.
  *
  * Returns a **new** [`Frame`] with 3D coordinates added as `x`, `y`,
- * `z` (f32, angstrom) columns in the `"atoms"` block.
+ * `z` (F, angstrom) columns in the `"atoms"` block.
  *
  * # Arguments
  *
@@ -2247,9 +2792,9 @@ export class XYZReader {
  * const frame3d = generate3D(frame2d, "fast", 42);
  *
  * const atoms = frame3d.getBlock("atoms");
- * const x = atoms.copyColF32("x"); // Float32Array with 3D x-coords
- * const y = atoms.copyColF32("y");
- * const z = atoms.copyColF32("z");
+ * const x = atoms.copyColF("x"); // Float32Array or Float64Array with 3D x-coords
+ * const y = atoms.copyColF("y");
+ * const z = atoms.copyColF("z");
  * ```
  */
 export function generate3D(frame: Frame, speed?: string | null, seed?: number | null): Frame;
@@ -2301,7 +2846,7 @@ export function start(): void;
  *
  * ```js
  * const mem = wasmMemory();
- * const buf = new Float32Array(mem.buffer, ptr, len);
+ * const buf = new Float64Array(mem.buffer, ptr, len); // or Float32Array in default builds
  * ```
  */
 export function wasmMemory(): WebAssembly.Memory;