@molcrafts/molrs 0.0.4 → 0.0.6

package/README.md

@@ -1,72 +1,86 @@
-# molrs-wasm
+# @molcrafts/molrs
 
-WASM bindings for `molrs`, aimed at browser and JavaScript/TypeScript consumers.
+[![npm](https://img.shields.io/npm/v/@molcrafts/molrs.svg)](https://www.npmjs.com/package/@molcrafts/molrs)
 
-## Local build
+WebAssembly bindings for the [molrs](https://github.com/MolCrafts/molrs) molecular modeling toolkit.
+
+## Install
 
 ```bash
-wasm-pack build --target web
-bash scripts/postprocess-pkg.sh
+npm install @molcrafts/molrs
 ```
 
-This produces `pkg/molwasm.js` plus `pkg/typed-views.js` for local use.
+## Quick start
 
-## npm package
+```js
+import init, { parseSMILES, generate3D, writeFrame } from "@molcrafts/molrs";
 
-The published package is `@molcrafts/molrs`.
+await init();
 
-```javascript
-import init, { Frame, WasmArray, XyzReader, writeFrame } from "@molcrafts/molrs";
-import { typedArrayView } from "@molcrafts/molrs/typed-views";
+// Parse SMILES → 3D coordinates → XYZ string
+const ir = parseSMILES("CCO");
+const frame = ir.toFrame();
+const mol3d = generate3D(frame, "fast");
+console.log(writeFrame(mol3d, "xyz"));
+```
 
-await init();
+## API
 
-const frame = new Frame();
-const atoms = frame.createBlock("atoms");
-atoms.set("x", new Float32Array([0.0, 1.0, 2.0]));
+### Data model
 
-const xView = atoms.view("x");
-const xTyped = typedArrayView(xView); // Float32Array
+- **`Frame`** — container mapping string keys (`"atoms"`, `"bonds"`) to `Block`s
+- **`Block`** — column store with typed arrays (`Float32Array`, `Int32Array`, `Uint32Array`, `string[]`)
+- **`Box`** — simulation box with periodic boundary conditions
 
-const xyz = writeFrame(frame, "xyz");
-console.log(xyz);
-```
+### I/O
 
-## Local file usage
+- `parseSMILES(smiles)` → `SmilesIR` → `.toFrame()`
+- `XYZReader`, `PDBReader`, `LAMMPSReader` — file format parsers
+- `writeFrame(frame, "xyz" | "pdb")` — serialize to string
+- `SimulationReader` — Zarr V3 trajectory reader
 
-```javascript
-import init, { Frame, WasmArray, XyzReader, writeFrame } from "./pkg/molwasm.js";
-import { typedArrayView, columnViewMeta } from "./pkg/typed-views.js";
+### 3D generation
 
-await init();
+- `generate3D(frame, speed?)` — MMFF94 coordinate generation (`"fast"` | `"normal"` | `"thorough"`)
 
-const frame = new Frame();
-const atoms = frame.createBlock("atoms");
-atoms.set("x", new Float32Array([0.0, 1.0, 2.0]));
+### Analysis
 
-const xCopy = atoms.view("x").toCopy();
-const xView = atoms.view("x");
-const xTypedArray = typedArrayView(xView); // Float32Array | Uint32Array | Uint8Array
-const xMeta = columnViewMeta(xView);
+```js
+import { LinkedCell, RDF } from "@molcrafts/molrs";
 
-const arr = WasmArray.from(new Float32Array([0, 0, 0, 1, 0, 0]), new Uint32Array([2, 3]));
-const reader = new XyzReader(fileContent);
-const loaded = reader.read(0);
-const xyz = writeFrame(frame, "xyz");
+const lc = new LinkedCell(5.0);           // cutoff = 5.0 A
+const nlist = lc.build(frame);            // self-query (unique pairs i < j)
+const cross = lc.query(refFrame, other);  // cross-query
+
+const rdf = new RDF(100, 5.0);
+const result = rdf.compute(frame, nlist);
+console.log(result.binCenters(), result.rdf());
 ```
 
-## API surface
+- **`LinkedCell`** — cell-list neighbor search (`build()` for self-query, `query()` for cross-query)
+- **`RDF`** — radial distribution function (periodic and free-boundary)
+- **`MSD`** — mean squared displacement
+- **`Cluster`** — distance-based cluster analysis
+
+Frames without a simulation box are supported — a non-periodic bounding box is auto-generated.
+
+### Block column conventions
 
-- `Frame`, `Block`, `ColumnView`, `WasmArray`
-- `typed-views.js` helpers for `ptr + len + shape + dtype`
-- `Box`
-- `XyzReader`, `PdbReader`, `LammpsReader`
-- `SimulationReader`
-- `writeFrame(frame, "xyz" | "pdb")`
+| Block | Column | Type | Description |
+|-------|--------|------|-------------|
+| `atoms` | `symbol` | `string` | Element symbol |
+| `atoms` | `x`, `y`, `z` | `f32` | Cartesian coordinates |
+| `atoms` | `mass` | `f32` | Atomic mass |
+| `atoms` | `charge` | `f32` | Partial charge |
+| `bonds` | `i`, `j` | `u32` | Atom indices |
+| `bonds` | `order` | `f32` | Bond order (1.0, 1.5, 2.0, 3.0) |
 
-## Testing
+## Build from source
 
 ```bash
-cargo test -p molrs-wasm --lib
-wasm-pack test --node
+wasm-pack build --target bundler --scope molcrafts --out-name molrs
 ```
+
+## License
+
+BSD-3-Clause

package/molrs.d.ts

@@ -1,103 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/**
- * Axis-aligned bounding box spatial query for neighbor search.
- *
- * Builds a cell-list spatial index from a [`Frame`]'s atom positions
- * and simulation box, then supports both self-queries (unique pairs
- * within the reference set) and cross-queries (pairs between a
- * query set and the reference set).
- *
- * All distances are in angstrom (A).
- *
- * # Example (JavaScript)
- *
- * ```js
- * const nq = new AABBQuery(frame, 3.0); // cutoff = 3.0 A
- * const selfPairs = nq.querySelf();      // unique pairs (i < j)
- * const crossPairs = nq.query(otherFrame); // cross-query
- *
- * console.log(selfPairs.numPairs);
- * ```
- */
-export class AABBQuery {
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Create a spatial query from a [`Frame`] with a given distance cutoff.
-     *
-     * The frame must have:
-     * - An `"atoms"` block with `x`, `y`, `z` (f32) columns
-     * - A `simbox` (simulation box) set on the frame
-     *
-     * # Arguments
-     *
-     * * `frame` - Reference frame with atom positions and simbox
-     * * `cutoff` - Maximum neighbor distance in angstrom (A)
-     *
-     * # Returns
-     *
-     * A new `AABBQuery` ready for `query()` or `querySelf()`.
-     *
-     * # Errors
-     *
-     * Throws if the frame has no `"atoms"` block, is missing `x`/`y`/`z`
-     * columns, or has no `simbox`.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const nq = new AABBQuery(frame, 5.0);
-     * ```
-     */
-    constructor(frame: Frame, cutoff: number);
-    /**
-     * Cross-query: find all pairs where `i` indexes query points and
-     * `j` indexes the reference points (from the constructor frame).
-     *
-     * # Arguments
-     *
-     * * `query_frame` - Frame with query atom positions (must have
-     *   `"atoms"` block with `x`, `y`, `z` columns)
-     *
-     * # Returns
-     *
-     * A [`NeighborList`] containing all `(i, j, distance)` pairs
-     * within the cutoff.
-     *
-     * # Errors
-     *
-     * Throws if `query_frame` is missing required columns.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const crossPairs = nq.query(otherFrame);
-     * console.log(crossPairs.numPairs);
-     * ```
-     */
-    query(query_frame: Frame): NeighborList;
-    /**
-     * Self-query: find all unique pairs `(i < j)` within the reference
-     * point set (the frame used to construct this query).
-     *
-     * # Returns
-     *
-     * A [`NeighborList`] containing all unique pairs within the cutoff.
-     * The `isSelfQuery` property will be `true`.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const pairs = nq.querySelf();
-     * console.log(pairs.isSelfQuery); // true
-     * console.log(pairs.numPairs);    // number of unique pairs
-     * ```
-     */
-    querySelf(): NeighborList;
-}
-
 /**
  * Column-oriented data store with typed arrays.
  *
@@ -112,7 +15,7 @@ export class AABBQuery {
  * | `Float32Array` | `f32` | `"f32"` | `setColF32` | `copyColF32` | `viewColF32` |
  * | `Int32Array` | `i32` | `"i32"` | `setColI32` | `copyColI32` | `viewColI32` |
  * | `Uint32Array` | `u32` | `"u32"` | `setColU32` | `copyColU32` | `viewColU32` |
- * | `Array<string>` | `String` | `"string"` | `setColStr` | `copyColStr` | -- |
+ * | `string[]` | `String` | `"string"` | `setColStr` | `copyColStr` | -- |
  *
  * # Example (JavaScript)
  *
@@ -174,7 +77,7 @@ export class Block {
      */
     copyColI32(key: string): Int32Array;
     /**
-     * Owned `Array<string>` copy of a string column.
+     * Owned `string[]` copy of a string column.
      *
      * # Arguments
      *
@@ -247,12 +150,12 @@ export class Block {
      * # Example (JavaScript)
      *
      * ```js
-     * if (block.isEmpty()) { /* no columns yet */ }
+     * if (block.isEmpty()) { // no columns yet }
      * ```
      */
     isEmpty(): boolean;
     /**
-     * Return all column names as a JS `Array<string>`.
+     * Return all column names as a JS `string[]`.
      *
      * # Errors
      *
@@ -382,7 +285,7 @@ export class Block {
      */
     setColI32(key: string, data: Int32Array): void;
     /**
-     * Set a string column from a JS `Array<string>`.
+     * Set a string column from a JS `string[]`.
      *
      * # Arguments
      *
@@ -911,8 +814,8 @@ export class Box {
  * # Example (JavaScript)
  *
  * ```js
- * const ns = new NeighborSearch(2.0);
- * const nlist = ns.build(frame);
+ * const lc = new LinkedCell(2.0);
+ * const nlist = lc.build(frame);
  *
  * const cluster = new Cluster(5); // min 5 particles per cluster
  * const result = cluster.compute(frame, nlist);
@@ -1350,86 +1253,189 @@ export class LAMMPSReader {
 }
 
 /**
- * Mean squared displacement (MSD) relative to a reference configuration.
+ * Cell-list (linked-cell) based neighbor search.
  *
- * Computes MSD = <|r(t) - r(0)|^2> for each particle and the
- * system average. Useful for measuring diffusion coefficients
- * via the Einstein relation D = MSD / (6t).
+ * Creates a spatial index from a [`Frame`]'s atom positions and
+ * simulation box, then finds all neighbor pairs within the cutoff
+ * distance.
  *
- * All distances are in angstrom (A), so MSD is in A^2.
+ * All distances are in angstrom (A).
  *
  * # Example (JavaScript)
  *
  * ```js
- * const msd = MSD.fromReference(refFrame);
+ * const lc = new LinkedCell(3.0);       // cutoff = 3.0 A
+ * const nlist = lc.build(frame);         // self-query (unique pairs i < j)
+ * const cross = lc.query(ref, other);    // cross-query
  *
- * for (let t = 0; t < nFrames; t++) {
- *   const frame = reader.read(t);
- *   const result = msd.compute(frame);
- *   console.log(`t=${t}: MSD = ${result.mean} A^2`);
- * }
+ * console.log(nlist.numPairs);
  * ```
- *
- * # References
- *
- * - Einstein, A. (1905). *Annalen der Physik*, 322(8), 549-560.
  */
-export class MSD {
-    private constructor();
+export class LinkedCell {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute MSD for a frame relative to the stored reference.
+     * Build a neighbor list from a [`Frame`] (self-query).
+     *
+     * 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.
+     * If the frame has a `simbox`, periodic boundary conditions are used.
+     * Otherwise, a free-boundary bounding box is auto-generated.
      *
      * # Arguments
      *
-     * * `frame` - Current frame with `"atoms"` block containing
-     *   `x`, `y`, `z` (f32) columns
+     * * `frame` - Frame with atom positions
      *
      * # Returns
      *
-     * An [`MSDResult`] with per-particle and system-average MSD
-     * values in A^2.
+     * A [`NeighborList`] containing all unique pairs within the cutoff.
      *
      * # Errors
      *
-     * Throws if the frame is missing required columns.
+     * Throws if the frame is missing required data.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const result = msd.compute(currentFrame);
-     * console.log(result.mean); // system-average MSD in A^2
+     * const lc = new LinkedCell(3.0);
+     * const nlist = lc.build(frame);
+     * const dists = nlist.distances(); // Float32Array
      * ```
      */
-    compute(frame: Frame): MSDResult;
+    build(frame: Frame): NeighborList;
     /**
-     * Create an MSD analysis from a reference (t=0) frame.
+     * Create a linked-cell neighbor search with the given distance cutoff.
+     *
+     * # Arguments
      *
-     * The reference frame's `"atoms"` block must have `x`, `y`, `z`
-     * (f32) columns. These positions are stored internally and used
-     * as the baseline for all subsequent `compute()` calls.
+     * * `cutoff` - Maximum neighbor distance in angstrom (A)
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const lc = new LinkedCell(5.0);
+     * ```
+     */
+    constructor(cutoff: number);
+    /**
+     * Cross-query: find all pairs where `i` indexes query points and
+     * `j` indexes the reference points.
      *
      * # Arguments
      *
-     * * `ref_frame` - Reference frame (typically the initial
-     *   configuration at t=0)
+     * * `ref_frame` - Frame with reference atom positions
+     * * `query_frame` - Frame with query atom positions (must have
+     *   `"atoms"` block with `x`, `y`, `z` columns)
      *
      * # Returns
      *
-     * A new `MSD` instance.
+     * A [`NeighborList`] containing all `(i, j, distance)` pairs
+     * within the cutoff.
+     *
+     * # Errors
+     *
+     * Throws if either frame is missing required columns.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const lc = new LinkedCell(3.0);
+     * const crossPairs = lc.query(refFrame, otherFrame);
+     * console.log(crossPairs.numPairs);
+     * ```
+     */
+    query(ref_frame: Frame, query_frame: Frame): NeighborList;
+}
+
+/**
+ * Mean squared displacement (MSD) analysis.
+ *
+ * Computes MSD = |r(t) - r(0)|^2 for each particle and the system
+ * average. The first frame fed is automatically used as the reference.
+ * Useful for measuring diffusion coefficients via D = MSD / (6t).
+ *
+ * All distances are in angstrom (A), so MSD is in A^2.
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const msd = new MSD();
+ * for (const frame of trajectory) {
+ *   msd.feed(frame);         // first frame = reference
+ * }
+ * const results = msd.results();  // MSDResult[] per frame
+ * console.log(results[10].mean);  // MSD at frame 10 in A^2
+ * ```
+ *
+ * # References
+ *
+ * - Einstein, A. (1905). *Annalen der Physik*, 322(8), 549-560.
+ */
+export class MSD {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Feed a frame into the MSD analysis.
+     *
+     * The first frame sets the reference configuration.
+     * Subsequent frames compute MSD relative to that reference.
+     *
+     * # Arguments
+     *
+     * * `frame` - Frame with `"atoms"` block containing
+     *   `x`, `y`, `z` (f32) columns
      *
      * # Errors
      *
-     * Throws if the frame is missing required columns.
+     * Throws if the frame is missing required columns or has a
+     * different number of atoms than the reference.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const msd = MSD.fromReference(initialFrame);
+     * const msd = new MSD();
+     * msd.feed(frame0);  // sets reference
+     * msd.feed(frame1);  // computes MSD vs frame0
      * ```
      */
-    static fromReference(ref_frame: Frame): MSD;
+    feed(frame: Frame): void;
+    /**
+     * Create an empty MSD analysis.
+     *
+     * The first frame passed to [`feed`] becomes the reference
+     * configuration (t=0).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const msd = new MSD();
+     * ```
+     */
+    constructor();
+    /**
+     * Reset the analysis, clearing reference and all results.
+     */
+    reset(): void;
+    /**
+     * Return all accumulated MSD results as an array.
+     *
+     * Returns one [`MSDResult`] per frame fed (including the
+     * reference frame, which has MSD = 0).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const results = msd.results();
+     * results.forEach((r, t) => console.log(`t=${t}: MSD=${r.mean}`));
+     * ```
+     */
+    results(): MSDResult[];
+    /**
+     * Number of frames accumulated.
+     */
+    readonly count: number;
 }
 
 /**
@@ -1467,9 +1473,8 @@ export class MSDResult {
  * Result of a neighbor search: all atom pairs within a distance cutoff.
  *
  * Contains pair indices, distances, and squared distances for every
- * neighbor pair found. This object is produced by [`AABBQuery`] or
- * [`NeighborSearch`] and consumed by analysis classes like [`RDF`]
- * and [`Cluster`].
+ * neighbor pair found. This object is produced by [`LinkedCell`]
+ * and consumed by analysis classes like [`RDF`] and [`Cluster`].
  *
  * # Properties
  *
@@ -1483,7 +1488,7 @@ export class MSDResult {
  * # Example (JavaScript)
  *
  * ```js
- * const nlist = nq.querySelf();
+ * const nlist = lc.build(frame);
  * console.log(nlist.numPairs);
  *
  * const i = nlist.queryPointIndices(); // Uint32Array
@@ -1509,18 +1514,6 @@ export class NeighborList {
      * `queryPointIndices()[k]` and reference point `pointIndices()[k]`.
      */
     distances(): Float32Array;
-    /**
-     * **Deprecated**: Use `queryPointIndices()` instead.
-     *
-     * First particle index per pair as `Uint32Array`.
-     */
-    idxI(): Uint32Array;
-    /**
-     * **Deprecated**: Use `pointIndices()` instead.
-     *
-     * Second particle index per pair as `Uint32Array`.
-     */
-    idxJ(): Uint32Array;
     /**
      * Reference point indices (`j`) for each pair, as a `Uint32Array`.
      */
@@ -1533,7 +1526,7 @@ export class NeighborList {
      */
     queryPointIndices(): Uint32Array;
     /**
-     * Whether this result came from a self-query (`querySelf()`).
+     * Whether this result came from a self-query (`build()`).
      *
      * In self-queries, only unique pairs `(i < j)` are reported.
      */
@@ -1554,100 +1547,6 @@ export class NeighborList {
     readonly numQueryPoints: number;
 }
 
-/**
- * **Deprecated**: backward-compatible alias for [`NeighborList`].
- *
- * Use [`NeighborList`] instead. This type is kept only for API
- * compatibility with older code.
- */
-export class NeighborResult {
-    private constructor();
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Squared pairwise distances in A^2 as `Float32Array`.
-     */
-    distSq(): Float32Array;
-    /**
-     * First particle index per pair as `Uint32Array`.
-     */
-    idxI(): Uint32Array;
-    /**
-     * Second particle index per pair as `Uint32Array`.
-     */
-    idxJ(): Uint32Array;
-    /**
-     * Total number of neighbor pairs found.
-     */
-    readonly numPairs: number;
-}
-
-/**
- * Neighbor search using the cell-list (link-cell) algorithm.
- *
- * This is a simpler, backward-compatible interface compared to
- * [`AABBQuery`]. It performs a self-query in a single `build()` call.
- *
- * Prefer [`AABBQuery`] for more flexibility (cross-queries, reusable
- * spatial index).
- *
- * # Example (JavaScript)
- *
- * ```js
- * const ns = new NeighborSearch(3.0); // cutoff = 3.0 A
- * const nbrs = ns.build(frame);
- * console.log(nbrs.numPairs);
- * ```
- */
-export class NeighborSearch {
-    free(): void;
-    [Symbol.dispose](): void;
-    /**
-     * Build a neighbor list from a [`Frame`].
-     *
-     * Performs a self-query: 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
-     * - A `simbox` (simulation box) set on the frame
-     *
-     * # Arguments
-     *
-     * * `frame` - Frame with atom positions and simbox
-     *
-     * # Returns
-     *
-     * A [`NeighborList`] containing all pairs within the cutoff.
-     *
-     * # Errors
-     *
-     * Throws if the frame is missing required data.
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const nbrs = ns.build(frame);
-     * const dists = nbrs.distances(); // Float32Array
-     * ```
-     */
-    build(frame: Frame): NeighborList;
-    /**
-     * Create a neighbor search with the given distance cutoff.
-     *
-     * # Arguments
-     *
-     * * `cutoff` - Maximum neighbor distance in angstrom (A)
-     *
-     * # Example (JavaScript)
-     *
-     * ```js
-     * const ns = new NeighborSearch(5.0);
-     * ```
-     */
-    constructor(cutoff: number);
-}
-
 /**
  * Protein Data Bank (PDB) file reader.
  *
@@ -1743,8 +1642,8 @@ export class PDBReader {
  * # Example (JavaScript)
  *
  * ```js
- * const nq = new AABBQuery(frame, 5.0);
- * const nlist = nq.querySelf();
+ * const lc = new LinkedCell(5.0);
+ * const nlist = lc.build(frame);
  *
  * const rdf = new RDF(100, 5.0);
  * const result = rdf.compute(frame, nlist);
@@ -1765,8 +1664,7 @@ export class RDF {
      * # Arguments
      *
      * * `frame` - Frame with a `simbox` set (for volume normalization)
-     * * `neighbors` - Pre-built [`NeighborList`] from [`AABBQuery`]
-     *   or [`NeighborSearch`]
+     * * `neighbors` - Pre-built [`NeighborList`] from [`LinkedCell`]
      *
      * # Returns
      *

package/molrs.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./molrs_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    AABBQuery, Block, Box, Cluster, ClusterResult, Frame, LAMMPSReader, MSD, MSDResult, NeighborList, NeighborResult, NeighborSearch, PDBReader, RDF, RDFResult, SimulationReader, SmilesIR, WasmArray, XYZReader, generate3D, parseSMILES, start, wasmMemory, writeFrame
+    Block, Box, Cluster, ClusterResult, Frame, LAMMPSReader, LinkedCell, MSD, MSDResult, NeighborList, PDBReader, RDF, RDFResult, SimulationReader, SmilesIR, WasmArray, XYZReader, generate3D, parseSMILES, start, wasmMemory, writeFrame
 } from "./molrs_bg.js";