WASM Quickstart¶
The npm package @molcrafts/molrs exports the classes and functions generated
by wasm-bindgen. It is built for bundlers (Vite, webpack, Rollup with a
WebAssembly plugin): importing the package loads and starts the WebAssembly
module, so there is no separate initialization call.
1. Install and Import¶
Configure your bundler to load .wasm modules. A custom build with
wasm-pack build --target web instead exports an async default init()
that must be awaited before any other call.
2. Parse, Embed, and Export¶
const ir = parseSMILES("CCO");
const frame2d = ir.toFrame();
const frame3d = generate3D(frame2d, "fast", 42);
console.log(writeFrame(frame3d, "xyz"));
The API shape mirrors Python, with JavaScript naming conventions:
parse_smiles becomes parseSMILES, and to_frame becomes toFrame. The
TypeScript declarations in the package (molrs.d.ts) are the source of truth
for exported names.
3. Inspect Columns¶
Frames contain blocks, and blocks contain typed columns. A column reads back
as the typed array of its stored dtype — Float64Array for floats — and no
method names a dtype:
const atoms = frame3d.get("atoms"); // throws if absent; check with frame3d.has("atoms")
const x = atoms.copy("x"); // owned Float64Array
const y = atoms.copy("y");
const z = atoms.copy("z");
console.log(atoms.nrows, atoms.dtype("x"), x[0], y[0], z[0]);
copy returns an owned typed array that is safe to keep. view(key) returns
a zero-copy view into WebAssembly memory instead; it is faster for large
columns but becomes invalid when the module's memory grows, so read it
immediately or prefer copy until profiling says otherwise. set(key, array)
writes a column and takes its dtype from the typed array's constructor
(Float32Array and plain number[] are refused). The
package README
has the full dtype table.
4. Read Record Files¶
The browser reads the same *.mrec record files that
Python and Rust write. A packed *.mrec.zip arrives as bytes:
import { TrajectoryReader, readMrecFrameFromZip } from "@molcrafts/molrs";
const bytes = new Uint8Array(await (await fetch("run.mrec.zip")).arrayBuffer());
const reader = TrajectoryReader.fromZip(bytes);
const first = reader.readFrame(0);
console.log(reader.countFrames(), first?.get("atoms").nrows);
const snapshot = readMrecFrameFromZip(
new Uint8Array(await (await fetch("water.mrec.zip")).arrayBuffer()),
);
TrajectoryReader.fromStore reads chunks on demand through callbacks, so a
large trajectory never has to be downloaded whole.
5. Build from Source¶
The npm publish pipeline uses this bundler target:
This writes molrs-wasm/pkg/. That directory is generated and ignored by git.
Applications can link it locally during development:
6. Variant Builds¶
The default npm build includes SMILES, I/O, compute, conformer, Voronoi, builder, and stream support. Smaller local builds can disable default Cargo features, but a page should load only one variant of the package at a time because each WebAssembly module owns a distinct JavaScript class identity.