@molcrafts/molrs 0.0.1 → 0.0.5

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, MolCrafts
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,175 +1,86 @@
-# molrs-wasm: WASM bindings for molrs
+# @molcrafts/molrs
 
-Object-oriented WASM bindings for molrs using FFI handle-based architecture.
+[![npm](https://img.shields.io/npm/v/@molcrafts/molrs.svg)](https://www.npmjs.com/package/@molcrafts/molrs)
 
-## Quick Start
+WebAssembly bindings for the [molrs](https://github.com/MolCrafts/molrs) molecular modeling toolkit.
 
-```javascript
-import init, { Frame, XyzReader } from './pkg/molrs.js';
+## Install
 
-await init();
-
-// Create a new frame
-const frame = new Frame();
-const atoms = frame.createBlock("atoms");
-
-// Set column data
-atoms.setColumnF32("x", new Float32Array([1.0, 2.0, 3.0]));
-const data = atoms.getColumnF32("x");
-
-// Read from file
-const reader = new XyzReader(fileContent);
-const loadedFrame = reader.read(0);
-```
-
-## API Reference
-
-### Frame
-
-The main container for molecular data.
-
-```javascript
-const frame = new Frame();
-
-// Create a block
-const atoms = frame.createBlock("atoms");
-
-// Get an existing block
-const atomsAgain = frame.getBlock("atoms");
-
-// Remove a block
-frame.removeBlock("atoms");
-
-// Clear all blocks
-frame.clear();
-
-// Drop the frame (invalidates all blocks)
-frame.drop();
+```bash
+npm install @molcrafts/molrs
 ```
 
-### Block
+## Quick start
 
-A block contains columnar data with consistent row counts.
+```js
+import init, { parseSMILES, generate3D, writeFrame } from "@molcrafts/molrs";
 
-```javascript
-const block = frame.createBlock("atoms");
-
-// Set column data
-const positions = new Float32Array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
-const shape = new Uint32Array([2, 3]); // 2 atoms, 3 coordinates each
-block.setColumnF32("positions", positions, shape);
-
-// Set integer columns (e.g., atom ids or bond indices)
-const ids = new BigInt64Array([1n, 2n, 3n]);
-block.setColumnI64("id", ids);
-
-// Get column data (returns copy)
-const data = block.getColumnF32("positions"); // Float32Array
-const idData = block.getColumnI64("id"); // BigInt64Array
-
-// Get column with shape info
-const { data, shape } = block.getColumnF32WithShape("positions");
+await init();
 
-// Query block info
-const keys = block.keys(); // ["positions"]
-const nrows = block.nrows(); // 2
+// Parse SMILES → 3D coordinates → XYZ string
+const ir = parseSMILES("CCO");
+const frame = ir.toFrame();
+const mol3d = generate3D(frame, "fast");
+console.log(writeFrame(mol3d, "xyz"));
 ```
 
-## File I/O
+## API
 
-### Reading Files
+### Data model
 
-```javascript
-// XYZ files
-const xyzReader = new XyzReader(fileContent);
-const frameCount = xyzReader.len();
-const frame = xyzReader.read(0); // Read frame 0
+- **`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
 
-// PDB files
-const pdbReader = new PdbReader(pdbContent);
-const frame2 = pdbReader.read(0);
+### I/O
 
-// LAMMPS data files
-const lammpsReader = new LammpsReader(lammpsContent);
-const frame3 = lammpsReader.read(0);
-```
+- `parseSMILES(smiles)` → `SmilesIR` → `.toFrame()`
+- `XYZReader`, `PDBReader`, `LAMMPSReader` — file format parsers
+- `writeFrame(frame, "xyz" | "pdb")` — serialize to string
+- `SimulationReader` — Zarr V3 trajectory reader
 
-### Writing Files
+### 3D generation
 
-```javascript
-// TODO: Writer API needs implementation
-// const output = writeFrame(frame, "xyz");
-```
+- `generate3D(frame, speed?)` — MMFF94 coordinate generation (`"fast"` | `"normal"` | `"thorough"`)
 
-## TypeScript Example
+### Analysis
 
-```typescript
-import init, { Frame, Block, XyzReader } from './pkg/molrs.js';
+```js
+import { LinkedCell, RDF } from "@molcrafts/molrs";
 
-await init();
+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
 
-// Create frame and block
-const frame: Frame = new Frame();
-const atoms: Block = frame.createBlock("atoms");
-
-// Set positions
-const positions = new Float32Array([
-  0.0, 0.0, 0.0,  // atom 1
-  1.0, 0.0, 0.0,  // atom 2
-  0.0, 1.0, 0.0,  // atom 3
-]);
-atoms.setColumnF32("x", positions);
-
-// Query data
-const nAtoms = atoms.nrows(); // 3
-const x = atoms.getColumnF32("x");
-console.log(x[0]); // 0.0
-
-// Read from file
-const reader = new XyzReader(fileContent);
-const loadedFrame = reader.read(0);
-if (loadedFrame) {
-  const loadedAtoms = loadedFrame.getBlock("atoms");
-  if (loadedAtoms) {
-    console.log(`Loaded ${loadedAtoms.nrows()} atoms`);
-  }
-}
+const rdf = new RDF(100, 5.0);
+const result = rdf.compute(frame, nlist);
+console.log(result.binCenters(), result.rdf());
 ```
 
-## Handle Invalidation
+- **`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
 
-Handles follow strict invalidation rules:
+Frames without a simulation box are supported — a non-periodic bounding box is auto-generated.
 
-- **Block handles** become invalid when:
-  - The parent frame is dropped
-  - The block is removed from the frame
-  - The frame is cleared
+### Block column conventions
 
-- **Frame handles** become invalid when:
-  - `frame.drop()` is called
+| 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) |
 
-Attempting to use an invalid handle will throw an error.
-
-## Architecture
-
-This WASM layer is a thin wrapper around `molrs-ffi`, which provides:
-- Stable handle-based references (no raw pointers)
-- Explicit invalidation semantics
-- Consistent behavior across Python and WASM
-
-The API is designed to be:
-- **Object-oriented**: Natural class hierarchy (Frame → Block)
-- **Type-safe**: Clear ownership and lifetime semantics
-- **Explicit**: No hidden copies or implicit conversions
-- **Simple**: Store is hidden - Frame is the main entry point
-
-## Testing
+## Build from source
 
 ```bash
-cargo test -p molrs-wasm --lib
+wasm-pack build --target bundler --scope molcrafts --out-name molrs
 ```
 
-For WASM-specific tests:
-```bash
-wasm-pack test --node wasm
-```
+## License
+
+BSD-3-Clause