@molcrafts/molrs 0.0.8 → 0.0.13

package/molrs.d.ts

@@ -117,6 +117,50 @@ export class Block {
      * ```
      */
     copyColU32(key: string): Uint32Array;
+    /**
+     * Allocate a zero-filled float column at `key` with the given shape.
+     *
+     * Pair with [`viewColF`](Block::view_col_f) for zero-copy writes from JS:
+     *
+     * ```js
+     * block.createColF("x", [N]);            // allocate
+     * const view = block.viewColF("x");      // zero-copy view into the column
+     * for (let i = 0; i < N; i++) view[i] = src[i]; // direct write
+     * ```
+     *
+     * # Arguments
+     *
+     * * `key` - Column name
+     * * `shape` - Shape of the column (e.g. `[N]` for 1D, `[N, 3]` for Nx3)
+     *
+     * # Errors
+     *
+     * Throws if the shape is empty, or if the leading dimension conflicts
+     * with existing columns in this block.
+     */
+    createColF(key: string, shape: Uint32Array): void;
+    /**
+     * Allocate a zero-filled i32 column at `key` with the given shape.
+     *
+     * See [`createColF`](Block::create_col_f) for the zero-copy write pattern.
+     *
+     * # Errors
+     *
+     * Throws if the shape is empty, or if the leading dimension conflicts
+     * with existing columns.
+     */
+    createColI32(key: string, shape: Uint32Array): void;
+    /**
+     * Allocate a zero-filled u32 column at `key` with the given shape.
+     *
+     * See [`createColF`](Block::create_col_f) for the zero-copy write pattern.
+     *
+     * # Errors
+     *
+     * Throws if the shape is empty, or if the leading dimension conflicts
+     * with existing columns.
+     */
+    createColU32(key: string, shape: Uint32Array): void;
     /**
      * Return the data type string for a column.
      *
@@ -1114,6 +1158,31 @@ export class Frame {
      * ```
      */
     getGrid(name: string): Grid | undefined;
+    /**
+     * Read a per-frame metadata value as a numeric scalar.
+     *
+     * Returns `Some(v)` if the meta key exists AND its string value parses
+     * as an `f64`. Returns `None` if the key is missing or the value is
+     * non-numeric (e.g., `config="trans"`).
+     *
+     * `frame.meta` is a `HashMap<String, String>`; the ExtXYZ parser stores
+     * all comment-line values as strings. This accessor reads numeric ones
+     * via `str::parse::<f64>`.
+     *
+     * # Arguments
+     *
+     * * `name` — Meta key to look up (e.g., `"energy"`, `"temp"`).
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const energy = frame.getMetaScalar("energy");
+     * if (energy !== undefined) {
+     *   console.log("Energy:", energy);
+     * }
+     * ```
+     */
+    getMetaScalar(name: string): number | undefined;
     /**
      * Return the names of all grids attached to this frame.
      *
@@ -1190,6 +1259,20 @@ export class Frame {
      * ```
      */
     insertGrid(name: string, grid: Grid): void;
+    /**
+     * Return the names of all metadata keys on this frame.
+     *
+     * Includes all keys regardless of whether their values are numeric
+     * or categorical. To filter to numeric keys, iterate and call
+     * [`getMetaScalar`](Self::get_meta_scalar) on each.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * const names = frame.metaNames(); // e.g. ["energy", "config", "temp"]
+     * ```
+     */
+    metaNames(): string[];
     /**
      * Create a new, empty `Frame` with no blocks and no simulation box.
      *
@@ -1286,6 +1369,33 @@ export class Frame {
      * ```
      */
     renameColumn(block_key: string, old_col: string, new_col: string): boolean;
+    /**
+     * Set a per-frame metadata value.
+     *
+     * Stores `value` as the string backing for `name` on `frame.meta`.
+     * Numeric values are read back via
+     * [`getMetaScalar`](Self::get_meta_scalar) by parsing the string
+     * form. `frame.meta` is the single source of truth for per-frame
+     * scalars — no separate aggregation layer is needed on the JS side.
+     *
+     * # Arguments
+     *
+     * * `name` — Meta key (e.g., `"energy"`, `"temp"`).
+     * * `value` — String value. For numeric labels, the caller is
+     *   responsible for converting (e.g., `num.toString()`).
+     *
+     * # Errors
+     *
+     * Throws a `JsValue` string if the frame has been dropped.
+     *
+     * # Example (JavaScript)
+     *
+     * ```js
+     * frame.setMeta("energy", "-3.14");
+     * frame.setMeta("note", "run-42");
+     * ```
+     */
+    setMeta(name: string, value: string): void;
     /**
      * Get the simulation box attached to this frame (if any).
      *
@@ -1541,6 +1651,10 @@ export class GyrationTensor {
     [Symbol.dispose](): void;
     /**
      * Compute gyration tensors. Returns a flat float typed array (9 values per cluster).
+     *
+     * Internally computes the cluster geometric centers (via
+     * [`RsClusterCenters`]) since the new compute trait exposes them as a
+     * required upstream — the old single-frame wasm API hides this detail.
      */
     compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
     constructor();
@@ -1554,49 +1668,15 @@ export class InertiaTensor {
     [Symbol.dispose](): void;
     /**
      * Compute inertia tensors. Returns a flat float typed array (9 values per cluster).
+     *
+     * Internally computes the cluster centers of mass (via
+     * [`RsCenterOfMass`]) since the new compute trait consumes them as a
+     * required upstream — the old single-frame wasm API hides this detail.
      */
     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.
  *
@@ -1680,6 +1760,44 @@ export class LAMMPSReader {
     read(step: number): Frame | undefined;
 }
 
+/**
+ * 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 LAMMPSTrajReader(dumpContent);
+ * console.log(reader.len()); // number of timesteps
+ * const frame = reader.read(0);
+ * const atoms = frame.getBlock("atoms");
+ * ```
+ */
+export class LAMMPSTrajReader {
+    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;
+}
+
 /**
  * Cell-list (linked-cell) based neighbor search.
  *
@@ -1807,25 +1925,23 @@ export class MSD {
     /**
      * Feed a frame into the MSD analysis.
      *
-     * The first frame sets the reference configuration.
-     * Subsequent frames compute MSD relative to that reference.
+     * Internally clones the frame's core data so subsequent mutations on
+     * the JS side (e.g. trajectory playback overwriting buffers) do not
+     * race against pending [`results`](Self::results) calls. The first
+     * frame sets the reference configuration.
      *
      * # Arguments
      *
      * * `frame` - Frame with `"atoms"` block containing
      *   `x`, `y`, `z` (F) columns
      *
-     * # Errors
-     *
-     * Throws if the frame is missing required columns or has a
-     * different number of atoms than the reference.
-     *
      * # Example (JavaScript)
      *
      * ```js
      * const msd = new MSD();
      * msd.feed(frame0);  // sets reference
-     * msd.feed(frame1);  // computes MSD vs frame0
+     * msd.feed(frame1);  // added to trajectory
+     * const series = msd.results();
      * ```
      */
     feed(frame: Frame): void;
@@ -1843,14 +1959,14 @@ export class MSD {
      */
     constructor();
     /**
-     * Reset the analysis, clearing reference and all results.
+     * Reset the analysis, clearing the trajectory buffer.
      */
     reset(): void;
     /**
-     * Return all accumulated MSD results as an array.
+     * Run the stateless [`molrs_compute::MSD`] over every fed frame and
+     * return the per-frame time series.
      *
-     * Returns one [`MSDResult`] per frame fed (including the
-     * reference frame, which has MSD = 0).
+     * The first frame is always the reference, so `results()[0].mean ≈ 0`.
      *
      * # Example (JavaScript)
      *
@@ -2066,15 +2182,16 @@ export class PDBReader {
 /**
  * Radial distribution function g(r) analysis.
  *
- * Computes the pair correlation function by binning neighbor-pair
- * distances into a histogram and normalizing by the ideal-gas
- * density (spherical shell volume normalization).
+ * Bins neighbor-pair distances in `[rMin, rMax]` and normalizes by the
+ * ideal-gas pair density. Defaults follow freud (`rMin = 0`). Periodic
+ * systems take their normalization volume from `frame.simbox`; non-periodic
+ * systems must supply it explicitly via [`computeWithVolume`].
  *
  * # Algorithm
  *
  * g(r) = n(r) / (rho * V_shell(r) * N_ref)
  *
- * where `n(r)` is the pair count in bin `r`, `rho` is the number
+ * where `n(r)` is the pair count in bin `r`, `rho = N/V` is the number
  * density, and `V_shell(r)` is the shell volume for that bin.
  *
  * # Example (JavaScript)
@@ -2083,60 +2200,73 @@ export class PDBReader {
  * const lc = new LinkedCell(5.0);
  * const nlist = lc.build(frame);
  *
- * const rdf = new RDF(100, 5.0);
+ * const rdf = new RDF(100, 5.0);          // rMin defaults to 0
  * const result = rdf.compute(frame, nlist);
  *
- * const r  = result.binCenters();  // Float32Array or Float64Array, bin centers in A
- * const gr = result.rdf();         // Float32Array or Float64Array, g(r) values
+ * // Non-periodic frame: supply the normalization volume.
+ * const resultFree = rdf.computeWithVolume(nlist, volumeA3);
+ *
+ * const r  = result.binCenters();
+ * const gr = result.rdf();
  * ```
  */
 export class RDF {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Compute the RDF from a pre-built neighbor list.
-     *
-     * The frame is needed to read the simulation box volume for
-     * normalization.
+     * Compute g(r) using the simulation-box volume from `frame.simbox`.
      *
      * # Arguments
      *
-     * * `frame` - Frame with a `simbox` set (for volume normalization)
+     * * `frame` - Frame with a `simbox` set (used only for volume)
      * * `neighbors` - Pre-built [`NeighborList`] from [`LinkedCell`]
      *
-     * # Returns
+     * # Errors
      *
-     * An [`RDFResult`] containing bin centers, g(r) values, and raw
-     * pair counts.
+     * Throws if the frame has no `simbox` — use
+     * [`computeWithVolume`](Self::compute_with_volume) for non-periodic frames.
+     */
+    compute(frame: Frame, neighbors: NeighborList): RDFResult;
+    /**
+     * Compute g(r) using an explicit normalization volume (A^3).
      *
-     * # Errors
+     * Use this for non-periodic systems or to override the box volume.
+     * Internally wraps the supplied volume as a cubic SimBox since the
+     * underlying [`molrs_compute::RDF`] pulls its normalization volume from
+     * `frame.simbox`.
+     *
+     * # Arguments
      *
-     * Throws if the frame cannot be cloned or the computation fails.
+     * * `neighbors` - Pre-built [`NeighborList`]
+     * * `volume` - Normalization volume in A^3 (must be finite and > 0)
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const result = rdf.compute(frame, nlist);
-     * const gr = result.rdf(); // Float32Array or Float64Array
+     * const result = rdf.computeWithVolume(nlist, 1000.0);
      * ```
      */
-    compute(frame: Frame, neighbors: NeighborList): RDFResult;
+    computeWithVolume(neighbors: NeighborList, volume: number): RDFResult;
     /**
-     * Create a new RDF analysis with specified binning.
+     * Create a new RDF analysis.
      *
      * # Arguments
      *
      * * `n_bins` - Number of histogram bins
-     * * `r_max` - Maximum radial distance in angstrom (A). Should
-     *   match or be less than the neighbor-search cutoff.
+     * * `r_max` - Upper radial cutoff in angstrom (A). Should be ≤ the
+     *   neighbor-search cutoff.
+     * * `r_min` - Lower radial cutoff in angstrom (A). Optional, defaults
+     *   to 0 (freud convention). Pairs with `d < rMin` or `d == 0` are
+     *   excluded from the histogram.
      *
      * # Example (JavaScript)
      *
      * ```js
-     * const rdf = new RDF(100, 5.0); // 100 bins up to 5 A
+     * const rdf = new RDF(100, 5.0);       // rMin = 0
+     * const rdf2 = new RDF(100, 5.0, 0.5); // exclude d < 0.5 A
      * ```
      */
-    constructor(n_bins: number, r_max: number);
+    constructor(n_bins: number, r_max: number, r_min?: number | null);
 }
 
 /**
@@ -2186,7 +2316,11 @@ export class RDFResult {
      */
     readonly numPoints: number;
     /**
-     * Simulation box volume used in the normalization, in A^3.
+     * Inner cutoff in A (lower edge of bin 0).
+     */
+    readonly rMin: number;
+    /**
+     * Normalization volume in A^3 (from the SimBox or the explicit caller value).
      */
     readonly volume: number;
 }
@@ -2199,6 +2333,10 @@ export class RadiusOfGyration {
     [Symbol.dispose](): void;
     /**
      * Compute radii of gyration. Returns a float typed array of length `numClusters`.
+     *
+     * Internally computes the cluster centers of mass so the single-frame
+     * wasm signature `(frame, cluster)` stays stable despite the new
+     * compute trait needing explicit COM upstream.
      */
     compute(frame: Frame, cluster_result: ClusterResult): Float64Array;
     constructor(masses?: Float64Array | null);
@@ -2660,6 +2798,114 @@ export class WasmArray {
     write_from(arr: Float64Array): void;
 }
 
+/**
+ * Wrapper for [`molrs_compute::kmeans::KMeans`].
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const km = new WasmKMeans(3, 100, 42);
+ * const labels = km.fit(coords, nRows, 2);   // Int32Array
+ * ```
+ */
+export class WasmKMeans {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Cluster a row-major `n_rows × n_dims` coordinate matrix.
+     *
+     * # Returns
+     *
+     * Cluster labels in `0..k` as an owned `Int32Array`, one per row.
+     *
+     * # Errors
+     *
+     * Throws if `k > n_rows`, `n_dims == 0`, the length does not match
+     * `n_rows * n_dims`, or any element is non-finite.
+     */
+    fit(coords: Float64Array, n_rows: number, n_dims: number): Int32Array;
+    /**
+     * Create a new k-means configuration.
+     *
+     * # Arguments
+     *
+     * * `k` — number of clusters (>= 1).
+     * * `max_iter` — maximum Lloyd iterations (>= 1).
+     * * `seed` — RNG seed for k-means++ initialization. Cast to `u64`
+     *   internally (JS numbers are `f64`; integers up to 2^53 pass
+     *   through losslessly).
+     *
+     * # Errors
+     *
+     * Throws if `k == 0` or `max_iter == 0`.
+     */
+    constructor(k: number, max_iter: number, seed: number);
+}
+
+/**
+ * Stateless wrapper for [`molrs_compute::pca::Pca2`].
+ *
+ * All configuration lives on [`fitTransform`](Self::fit_transform).
+ *
+ * # Example (JavaScript)
+ *
+ * ```js
+ * const pca = new WasmPca2();
+ * const result = pca.fitTransform(matrix, nRows, nCols);
+ * const coords   = result.coords();    // Float64Array, length 2 * nRows
+ * const variance = result.variance();  // Float64Array, length 2
+ * ```
+ */
+export class WasmPca2 {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Fit 2-component PCA on a row-major observation matrix and return the
+     * projected coordinates + per-component variance.
+     *
+     * # Arguments
+     *
+     * * `matrix` — row-major `n_rows × n_cols` observation matrix.
+     * * `n_rows` — number of observations.
+     * * `n_cols` — number of features.
+     *
+     * # Errors
+     *
+     * Throws if `n_rows < 3`, `n_cols < 2`, the length does not match
+     * `n_rows * n_cols`, any element is non-finite, or any column has
+     * zero variance.
+     */
+    fitTransform(matrix: Float64Array, n_rows: number, n_cols: number): WasmPcaResult;
+    /**
+     * Create a new PCA calculator. The struct carries no state — all
+     * parameters are supplied on [`fitTransform`](Self::fit_transform).
+     */
+    constructor();
+}
+
+/**
+ * Result of a [`WasmPca2::fit_transform`] call.
+ *
+ * Each accessor returns an **owned** `Float64Array` (copy of the underlying
+ * `Vec`) so JS is free to let this wrapper be GC'd without dangling views.
+ */
+export class WasmPcaResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Projected 2D coordinates as a row-major `Float64Array` of length
+     * `2 * n_rows`. `coords[2 * i + 0]` is the PC1 score for row `i`,
+     * `coords[2 * i + 1]` is PC2.
+     */
+    coords(): Float64Array;
+    /**
+     * Explained variance per component as `Float64Array` of length 2.
+     * `variance[0] >= variance[1]` by construction.
+     */
+    variance(): Float64Array;
+}
+
 /**
  * XYZ / Extended XYZ file reader.
  *

package/molrs.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./molrs_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    Block, Box, CenterOfMass, CenterOfMassResult, Cluster, ClusterCenters, ClusterResult, Frame, Grid, GyrationTensor, InertiaTensor, LAMMPSDumpReader, LAMMPSReader, LinkedCell, MSD, MSDResult, MolRecReader, NeighborList, PDBReader, RDF, RDFResult, RadiusOfGyration, SDFReader, SmilesIR, Topology, TopologyRingInfo, WasmArray, XYZReader, generate3D, parseSMILES, start, wasmMemory, writeFrame
+    Block, Box, CenterOfMass, CenterOfMassResult, Cluster, ClusterCenters, ClusterResult, Frame, Grid, GyrationTensor, InertiaTensor, LAMMPSReader, LAMMPSTrajReader, LinkedCell, MSD, MSDResult, MolRecReader, NeighborList, PDBReader, RDF, RDFResult, RadiusOfGyration, SDFReader, SmilesIR, Topology, TopologyRingInfo, WasmArray, WasmKMeans, WasmPca2, WasmPcaResult, XYZReader, generate3D, parseSMILES, start, wasmMemory, writeFrame
 } from "./molrs_bg.js";