@molcrafts/molrs

WebAssembly bindings for the molrs molecular modeling toolkit.

Full documentation lives at https://docs.molcrafts.org/molrs/. The WASM reference is published at https://docs.molcrafts.org/molrs/reference/wasm/.

Install

npm install @molcrafts/molrs

Quick start

import init, { parseSMILES, generate3D, writeFrame } from "@molcrafts/molrs";

await init();

// Parse SMILES → 3D coordinates → XYZ string
const ir = parseSMILES("CCO");
const frame = ir.toFrame();
const mol3d = generate3D(frame, "fast");
console.log(writeFrame(mol3d, "xyz"));

API

Data model

• Frame — container mapping string keys ("atoms", "bonds") to Blocks
• Block — column store with typed arrays. Float columns are Float64Array (F = f64).
• Box — simulation box with periodic boundary conditions

I/O

• parseSMILES(smiles) → SmilesIR → .toFrame()
• XYZReader, PDBReader, LAMMPSReader — file format parsers
• writeFrame(frame, "xyz" | "pdb" | "lammps-data" | "lammps-dump") — serialize to string
• MolRecReader — MolRec Zarr V3 reader

3D generation

• generate3D(frame, speed?, seed?) — MMFF94 coordinate generation ("fast" | "medium" | "better")

Force fields + geometry optimization

const typifier = new UFFTypifier();                 // or MMFF94Typifier / MMFF94STypifier
const typed    = typifier.typify(frame);
const pots     = typifier.toPotentials(typed);      // no .ff()
const report   = new LBFGS(pots).run(typed, 200);   // Optimizer(pots).run(frame, n_steps)
// optional: new LBFGS(pots, neighborList).run(typed, 200)
// no neighborList → internal bruteforce topology pair list (exclude 1-2/1-3)

• UFF — full RDKit default table (entire periodic table + oxidation states)
• MMFF94 / MMFF94s — Merck force fields
• no GFN-FF
• no free-function intramolecularPairs / insertIntramolecularPairs

Analysis

import { NeighborList, RDF } from "@molcrafts/molrs";

const nl = new NeighborList(5.0);         // cutoff = 5.0 A, O(N) cell list
nl.build(frame);                          // index only — no pair table
const nlist = nl.neighbors();             // materialize: distSq + disp

const rdf = new RDF(100, 5.0);
const result = rdf.compute(frame, nlist);
console.log(result.binCenters(), result.rdf());

A self search is half-shell: each unordered pair appears once, with i < j. neighbors() keeps both physical columns by default — that names the columns, not the pair direction. Pass { distSq: false } or { disp: false } to drop one; a column that was not stored reads back as undefined, never as a fabricated zero array. disp is the unnormalized minimum-image displacement r_j - r_i (Å), flattened three values per pair.

• NeighborList — neighbor-search engine (build / update index, neighbors materializes); NeighborList.bruteForce(cutoff) selects the O(N²) reference backend
• Neighbors — the materialized pair table (numPairs, queryPointIndices(), pointIndices(), distSq(), disp())
• LinkedCell / BruteForce — compatibility aliases that build and materialize in one call; LinkedCell.query(refFrame, other) is the cross-search door
• 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

| Block | Column | Type | Description | |-------|--------|------|-------------| | atoms | symbol | string | Element symbol | | atoms | x, y, z | F | Cartesian coordinates | | atoms | mass | F | Atomic mass | | atoms | charge | F | Partial charge | | bonds | i, j | u32 | Atom indices | | bonds | bond_type | U32 | 0 unknown, 1 single, 2 double, 3 triple, 4 aromatic | | bonds | bond_number | U32 | Localized Lewis/Kekulé integer (never fractional) |

F is the molrs core float type — always f64.

Build from source

wasm-pack build --release --target bundler --scope molcrafts --out-name molrs

This writes pkg/ — the npm package. pkg/package.json is auto-generated by wasm-pack with name @molcrafts/molrs. Consumers link it directly:

// consumer's package.json
"dependencies": {
  "@molcrafts/molrs": "link:../path/to/molrs-wasm/pkg"
}

Then npm install creates a symlink — rebuilding pkg/ (via wasm-pack build) is picked up immediately by the consumer's dev server. No npm link dance needed.

Variants (optional)

Default build compiles all subsystems (smiles, io, compute, embed). To build a smaller wasm containing only a subset, use Cargo features:

wasm-pack build --release --target bundler --scope molcrafts \
  --out-name molrs \
  --no-default-features --features io,smiles

Note: variants are mutually exclusive at runtime — you can't mix a compute-only build with an io-only build in the same app, because each produces a separate wasm module with its own Frame class identity.

License

BSD-3-Clause