@molcrafts/molrs 0.0.8 → 0.0.12

package/molrs.d.ts

@@ -1114,6 +1114,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 +1215,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 +1325,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 +1607,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,6 +1624,10 @@ 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);
@@ -1807,25 +1881,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 +1915,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 +2138,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 +2156,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`.
      *
-     * Throws if the frame cannot be cloned or the computation fails.
+     * # Arguments
+     *
+     * * `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 +2272,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 +2289,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 +2754,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, LAMMPSDumpReader, LAMMPSReader, 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";

package/molrs_bg.js

@@ -1651,6 +1651,38 @@ export class Frame {
         }
         return ret[0] === 0 ? undefined : Grid.__wrap(ret[0]);
     }
+    /**
+     * 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);
+     * }
+     * ```
+     * @param {string} name
+     * @returns {number | undefined}
+     */
+    getMetaScalar(name) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.frame_getMetaScalar(this.__wbg_ptr, ptr0, len0);
+        return ret[0] === 0 ? undefined : ret[1];
+    }
     /**
      * Return the names of all grids attached to this frame.
      *
@@ -1766,6 +1798,26 @@ export class Frame {
             throw takeFromExternrefTable0(ret[0]);
         }
     }
+    /**
+     * 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"]
+     * ```
+     * @returns {string[]}
+     */
+    metaNames() {
+        const ret = wasm.frame_metaNames(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free_command_export(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
     /**
      * Create a new, empty `Frame` with no blocks and no simulation box.
      *
@@ -1912,6 +1964,44 @@ export class Frame {
         }
         return ret[0] !== 0;
     }
+    /**
+     * 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");
+     * ```
+     * @param {string} name
+     * @param {string} value
+     */
+    setMeta(name, value) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(value, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.frame_setMeta(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Attach or detach a simulation box.
      *
@@ -2288,6 +2378,10 @@ export class GyrationTensor {
     }
     /**
      * 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.
      * @param {Frame} frame
      * @param {ClusterResult} cluster_result
      * @returns {Float64Array}
@@ -2328,6 +2422,10 @@ export class InertiaTensor {
     }
     /**
      * 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.
      * @param {Frame} frame
      * @param {ClusterResult} cluster_result
      * @returns {Float64Array}
@@ -2734,25 +2832,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();
      * ```
      * @param {Frame} frame
      */
@@ -2782,16 +2878,16 @@ export class MSD {
         return this;
     }
     /**
-     * Reset the analysis, clearing reference and all results.
+     * Reset the analysis, clearing the trajectory buffer.
      */
     reset() {
         wasm.msd_reset(this.__wbg_ptr);
     }
     /**
-     * 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)
      *
@@ -2803,6 +2899,9 @@ export class MSD {
      */
     results() {
         const ret = wasm.msd_results(this.__wbg_ptr);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
         var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
         wasm.__wbindgen_free_command_export(ret[0], ret[1] * 4, 4);
         return v1;
@@ -3168,15 +3267,16 @@ if (Symbol.dispose) PDBReader.prototype[Symbol.dispose] = PDBReader.prototype.fr
 /**
  * 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)
@@ -3185,11 +3285,14 @@ if (Symbol.dispose) PDBReader.prototype[Symbol.dispose] = PDBReader.prototype.fr
  * 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 {
@@ -3204,64 +3307,88 @@ export class RDF {
         wasm.__wbg_rdf_free(ptr, 0);
     }
     /**
-     * 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.
+     * @param {Frame} frame
+     * @param {NeighborList} neighbors
+     * @returns {RDFResult}
+     */
+    compute(frame, neighbors) {
+        _assertClass(frame, Frame);
+        _assertClass(neighbors, NeighborList);
+        const ret = wasm.rdf_compute(this.__wbg_ptr, frame.__wbg_ptr, neighbors.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return RDFResult.__wrap(ret[0]);
+    }
+    /**
+     * 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);
      * ```
-     * @param {Frame} frame
      * @param {NeighborList} neighbors
+     * @param {number} volume
      * @returns {RDFResult}
      */
-    compute(frame, neighbors) {
-        _assertClass(frame, Frame);
+    computeWithVolume(neighbors, volume) {
         _assertClass(neighbors, NeighborList);
-        const ret = wasm.rdf_compute(this.__wbg_ptr, frame.__wbg_ptr, neighbors.__wbg_ptr);
+        const ret = wasm.rdf_computeWithVolume(this.__wbg_ptr, neighbors.__wbg_ptr, volume);
         if (ret[2]) {
             throw takeFromExternrefTable0(ret[1]);
         }
         return RDFResult.__wrap(ret[0]);
     }
     /**
-     * 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
      * ```
      * @param {number} n_bins
      * @param {number} r_max
+     * @param {number | null} [r_min]
      */
-    constructor(n_bins, r_max) {
-        const ret = wasm.rdf_new(n_bins, r_max);
-        this.__wbg_ptr = ret >>> 0;
+    constructor(n_bins, r_max, r_min) {
+        const ret = wasm.rdf_new(n_bins, r_max, !isLikeNone(r_min), isLikeNone(r_min) ? 0 : r_min);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
         RDFFinalization.register(this, this.__wbg_ptr, this);
         return this;
     }
@@ -3339,6 +3466,14 @@ export class RDFResult {
         const ret = wasm.rdfresult_pairCounts(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Inner cutoff in A (lower edge of bin 0).
+     * @returns {number}
+     */
+    get rMin() {
+        const ret = wasm.rdfresult_rMin(this.__wbg_ptr);
+        return ret;
+    }
     /**
      * Zero-copy `Float64Array` view of normalized g(r). Same invalidation
      * caveat.
@@ -3349,7 +3484,7 @@ export class RDFResult {
         return ret;
     }
     /**
-     * Simulation box volume used in the normalization, in A^3.
+     * Normalization volume in A^3 (from the SimBox or the explicit caller value).
      * @returns {number}
      */
     get volume() {
@@ -3375,6 +3510,10 @@ export class RadiusOfGyration {
     }
     /**
      * 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.
      * @param {Frame} frame
      * @param {ClusterResult} cluster_result
      * @returns {Float64Array}
@@ -4171,6 +4310,195 @@ export class WasmArray {
 }
 if (Symbol.dispose) WasmArray.prototype[Symbol.dispose] = WasmArray.prototype.free;
 
+/**
+ * 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 {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmKMeansFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmkmeans_free(ptr, 0);
+    }
+    /**
+     * 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.
+     * @param {Float64Array} coords
+     * @param {number} n_rows
+     * @param {number} n_dims
+     * @returns {Int32Array}
+     */
+    fit(coords, n_rows, n_dims) {
+        const ptr0 = passArrayF64ToWasm0(coords, wasm.__wbindgen_malloc_command_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmkmeans_fit(this.__wbg_ptr, ptr0, len0, n_rows, n_dims);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+    /**
+     * 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`.
+     * @param {number} k
+     * @param {number} max_iter
+     * @param {number} seed
+     */
+    constructor(k, max_iter, seed) {
+        const ret = wasm.wasmkmeans_new(k, max_iter, seed);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0] >>> 0;
+        WasmKMeansFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) WasmKMeans.prototype[Symbol.dispose] = WasmKMeans.prototype.free;
+
+/**
+ * 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 {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmPca2Finalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmpca2_free(ptr, 0);
+    }
+    /**
+     * 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.
+     * @param {Float64Array} matrix
+     * @param {number} n_rows
+     * @param {number} n_cols
+     * @returns {WasmPcaResult}
+     */
+    fitTransform(matrix, n_rows, n_cols) {
+        const ptr0 = passArrayF64ToWasm0(matrix, wasm.__wbindgen_malloc_command_export);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.wasmpca2_fitTransform(this.__wbg_ptr, ptr0, len0, n_rows, n_cols);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return WasmPcaResult.__wrap(ret[0]);
+    }
+    /**
+     * Create a new PCA calculator. The struct carries no state — all
+     * parameters are supplied on [`fitTransform`](Self::fit_transform).
+     */
+    constructor() {
+        const ret = wasm.wasmpca2_new();
+        this.__wbg_ptr = ret >>> 0;
+        WasmPca2Finalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) WasmPca2.prototype[Symbol.dispose] = WasmPca2.prototype.free;
+
+/**
+ * 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 {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmPcaResult.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmPcaResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmPcaResultFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmpcaresult_free(ptr, 0);
+    }
+    /**
+     * 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.
+     * @returns {Float64Array}
+     */
+    coords() {
+        const ret = wasm.wasmpcaresult_coords(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Explained variance per component as `Float64Array` of length 2.
+     * `variance[0] >= variance[1]` by construction.
+     * @returns {Float64Array}
+     */
+    variance() {
+        const ret = wasm.wasmpcaresult_variance(this.__wbg_ptr);
+        return ret;
+    }
+}
+if (Symbol.dispose) WasmPcaResult.prototype[Symbol.dispose] = WasmPcaResult.prototype.free;
+
 /**
  * XYZ / Extended XYZ file reader.
  *
@@ -4592,6 +4920,14 @@ export function __wbg_new_from_slice_ede497d29b90a4ad(arg0, arg1) {
     const ret = new Int32Array(getArrayI32FromWasm0(arg0, arg1));
     return ret;
 }
+export function __wbg_new_with_length_33f0a4c41f7ce2fc(arg0) {
+    const ret = new Int32Array(arg0 >>> 0);
+    return ret;
+}
+export function __wbg_new_with_length_5cfd777b51078805(arg0) {
+    const ret = new Float64Array(arg0 >>> 0);
+    return ret;
+}
 export function __wbg_next_0340c4ae324393c3() { return handleError(function (arg0) {
     const ret = arg0.next();
     return ret;
@@ -4612,6 +4948,12 @@ export function __wbg_push_471a5b068a5295f6(arg0, arg1) {
     const ret = arg0.push(arg1);
     return ret;
 }
+export function __wbg_set_5637e648df81c8e5(arg0, arg1, arg2) {
+    arg0.set(getArrayF64FromWasm0(arg1, arg2));
+}
+export function __wbg_set_6c7215e0274bbbf2(arg0, arg1, arg2) {
+    arg0.set(getArrayI32FromWasm0(arg1, arg2));
+}
 export function __wbg_stack_3b0d974bbf31e44f(arg0, arg1) {
     const ret = arg1.stack;
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
@@ -4727,6 +5069,15 @@ const TopologyRingInfoFinalization = (typeof FinalizationRegistry === 'undefined
 const WasmArrayFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmarray_free(ptr >>> 0, 1));
+const WasmKMeansFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmkmeans_free(ptr >>> 0, 1));
+const WasmPca2Finalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmpca2_free(ptr >>> 0, 1));
+const WasmPcaResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmpcaresult_free(ptr >>> 0, 1));
 const SmilesIRFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_smilesir_free(ptr >>> 0, 1));

package/package.json

@@ -5,7 +5,7 @@
     "MolCrafts"
   ],
   "description": "WASM bindings for molrs",
-  "version": "0.0.8",
+  "version": "0.0.12",
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",