stanwasm 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,12 @@
 # stanwasm
 
+[![npm](https://img.shields.io/npm/v/stanwasm?logo=npm&color=cb3837)](https://www.npmjs.com/package/stanwasm)
+[![crates.io](https://img.shields.io/crates/v/stanwasm?logo=rust&color=e43717)](https://crates.io/crates/stanwasm)
+[![bundle](https://img.shields.io/badge/wasm-514%20KB%20%7C%20192%20KB%20gzip-654ff0?logo=webassembly&logoColor=white)](https://github.com/habakan/stanwasm/blob/main/docs/en/BENCHMARKS.md)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/habakan/stanwasm/blob/main/LICENSE)
+
 Stan probabilistic models compiled and sampled **entirely in the browser**.
-Pure Rust compiled to WebAssembly, a single ~482 KB bundle (~180 KB gzipped),
+Pure Rust compiled to WebAssembly, a single ~514 KB bundle (~192 KB gzipped),
 with [nuts-rs](https://github.com/pymc-devs/nuts-rs) embedded as the sampler.
 No server, no cmdstan, no round trip.
 
@@ -11,6 +16,19 @@ No server, no cmdstan, no round trip.
 > [Stan Playground](https://github.com/flatironinstitute/stan-playground) —
 > this is for browser-embedded use cases where those do not fit.
 
+## Browser support
+
+Chrome, Edge, Firefox, Safari and Node.js, plus every browser on iOS and
+iPadOS. Verified under Playwright's three engines: Chromium 151, Firefox 153
+and WebKit 26.5 all instantiate the module and sample.
+
+Safari failed outright before 0.1.1 — WebKit rejects a module containing
+[relaxed SIMD](https://github.com/WebAssembly/relaxed-simd) opcodes at
+validation time, and `pulp` emitted them. This package ships the prebuilt wasm
+with that resolved, so nothing is required of you; see
+[the README](https://github.com/habakan/stanwasm#browser-support) for the
+details and the one caveat that applies to the Rust crate.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stanwasm",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Stan inference engine for WebAssembly (Rust port).",
   "type": "module",
   "main": "./index.js",

package/pkg/README.md

@@ -1,5 +1,9 @@
 # stanwasm
 
+[![crates.io](https://img.shields.io/crates/v/stanwasm?logo=rust&color=e43717)](https://crates.io/crates/stanwasm)
+[![npm](https://img.shields.io/npm/v/stanwasm?logo=npm&color=cb3837)](https://www.npmjs.com/package/stanwasm)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/habakan/stanwasm/blob/main/LICENSE)
+
 The wasm-bindgen API behind stanwasm: parse, compile and sample a Stan model
 entirely inside the browser.
 

package/pkg/stanwasm.d.ts

@@ -2,31 +2,25 @@
 /* eslint-disable */
 
 /**
- * One compiled Stan model. Holds both the parsed AST (`Model`) and a
- * pre-traced `Compiled` for fast log-prob evaluation. Sampling consumes
- * the `Compiled` and re-builds it from the retained AST afterwards, so
- * the same `StanModel` instance can be sampled repeatedly.
+ * One compiled Stan model: the parsed AST plus a pre-traced `Compiled`.
+ * Sampling consumes the `Compiled` and rebuilds it from the AST after.
  */
 export class StanModel {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * AOT-compile this model to a self-contained wasm module. Returns the
-     * wasm bytes (callers can pass these to `WebAssembly.instantiate` to
-     * obtain an independent log_prob_grad runtime — useful for Web Workers
-     * or for inspection).
+     * AOT-compile this model to a self-contained wasm module. Pass the bytes to
+     * `WebAssembly.instantiate` for an independent log_prob_grad runtime.
      */
     compileToWasm(): Uint8Array;
     /**
-     * Constrained values of `parameters` + `transformed parameters` for one
-     * unconstrained draw (e.g. one row out of `sample()`'s output), flattened
-     * in `paramNames()` order.
+     * Constrained `parameters` + `transformed parameters` for one
+     * unconstrained draw, flattened in `paramNames()` order.
      */
     constrainDraw(unconstrained: Float64Array): Float64Array;
     /**
-     * Stop step-sampling early (or clean up after it finished naturally —
-     * safe to call either way) and restore `logProbGrad`/`sample` by
-     * re-tracing, same as `sample()` does at the end of a run.
+     * Stop step-sampling (safe after it ended naturally too) and restore
+     * `logProbGrad`/`sample` by re-tracing.
      */
     finishStepSampling(): void;
     /**
@@ -35,18 +29,8 @@ export class StanModel {
      */
     genQuantityNames(): string[];
     /**
-     * Evaluate `generated quantities` for a batch of unconstrained draws
-     * (e.g. `sample()`'s output). `draws` is a flat row-major buffer of
-     * shape `(n_draws, n_params)`; the result is `(n_draws, n_gen_quantities)`,
-     * row-major, in `genQuantityNames()` order. A single RNG stream (seeded
-     * by `seed`) is shared across all draws so repeated `_rng` calls don't
-     * repeat the same values draw-to-draw.
-     *
-     * Note: unlike `sampleViaAot`, there is no AOT-compiled counterpart of
-     * this method — `compileToWasm` only exports `log_prob_grad`. Generated
-     * quantities involve RNG and branching that the flat-tape AOT codegen
-     * doesn't model, and (running once per draw rather than once per NUTS
-     * leapfrog step) don't need it for performance.
+     * `generated quantities` over row-major `(n_draws, n_params)` draws.
+     * Result is row-major in `genQuantityNames()` order; one seeded RNG stream.
      */
     generatedQuantities(draws: Float64Array, num_draws: number, seed: bigint): Float64Array;
     /**
@@ -69,38 +53,18 @@ export class StanModel {
      */
     sample(init: Float64Array, num_warmup: number, num_draws: number, seed: bigint): Float64Array;
     /**
-     * Same as `sample`, but evaluates `log_prob_grad` through a
-     * pre-instantiated AOT-compiled model wasm bound via `setAotExports`.
-     * V8 JITs the unrolled forward+backward pass in the AOT module, which
-     * can be substantially faster than the in-process tape replay used by
-     * `sample`. Both produce identical samples for a given seed.
+     * `sample` through a `setAotExports`-bound AOT wasm instead of tape replay;
+     * V8 JITs the unrolled pass. Identical samples for a given seed.
      */
     sampleViaAot(init: Float64Array, num_warmup: number, num_draws: number, seed: bigint): Float64Array;
     /**
-     * Start a step-by-step NUTS run: unlike `sample()`, which runs the whole
-     * chain inside one wasm call and returns only at the end, this leaves
-     * the sampler's state alive in the `StanModel` instance so `stepDraw()`
-     * can advance it one draw at a time — genuinely watching the sampler
-     * work, not replaying an already-finished chain. Consumes the internal
-     * `Compiled` the same way `sample()` does; call `finishStepSampling()`
-     * (or exhaust `stepDraw()` up to `num_warmup + num_draws` calls, which
-     * does it automatically) before using `logProbGrad`/`sample` again.
+     * Start a NUTS run that `stepDraw()` advances one draw at a time. Consumes
+     * the `Compiled`: call `finishStepSampling()` before `logProbGrad`/`sample`.
      */
     startStepSampling(init: Float64Array, num_warmup: number, num_draws: number, seed: bigint): void;
     /**
-     * Advance the step-sampling chain started by `startStepSampling` by
-     * exactly one draw. Returns a flat array: `n_params` position values,
-     * then `1.0`/`0.0` for whether this draw was still in the warmup
-     * (tuning) phase, then `1.0`/`0.0` for whether it diverged, then the
-     * leapfrog `step_size` and `num_steps` nuts-rs actually used for this
-     * draw — these come straight out of nuts-rs's own dual-averaging
-     * adaptation and trajectory-length search, not anything this crate
-     * computes, so they're a way to show the real sampler internals at
-     * work rather than just the resulting draw. Once the requested
-     * `num_warmup + num_draws` draws have all been returned, this
-     * automatically restores `logProbGrad`/`sample` (by re-tracing, same as
-     * `sample()` does) and further calls fail until `startStepSampling` runs
-     * again.
+     * Advance one draw: `n_params` positions, tuning and diverging as `1.0`/`0.0`,
+     * then nuts-rs's own `step_size` and `num_steps`. Restores `sample` when done.
      */
     stepDraw(): Float64Array;
     /**
@@ -115,13 +79,8 @@ export class StanModel {
 export function clearAotExports(): void;
 
 /**
- * Runs once when the wasm module is instantiated. Forwards Rust panics
- * (Stan-typo'd names and invalid RNG parameters are now clean `JsError`s
- * instead, but a handful of internal-invariant panics remain, e.g. index
- * out of bounds on a malformed AST) to `console.error` with a real message
- * and backtrace, instead of an opaque `RuntimeError: unreachable`. The
- * panicking call still traps the instance — this is diagnostics, not
- * recovery — but it means a bug report can include what actually broke.
+ * Forwards Rust panics to `console.error` with a message and backtrace rather
+ * than an opaque `RuntimeError: unreachable`. Diagnostics: the instance still traps.
  */
 export function init_panic_hook(): void;
 
@@ -132,9 +91,8 @@ export function init_panic_hook(): void;
 export function setAotExports(exports: any): void;
 
 /**
- * Returns the linear memory backing this wasm module. Pass to
- * `WebAssembly.instantiate` as the `stan.memory` import when bringing up an
- * AOT model so the two modules share buffers (zero-copy bridge).
+ * The linear memory backing this module. Pass as the `stan.memory` import when
+ * instantiating an AOT model so the two share buffers.
  */
 export function sharedMemory(): any;
 

package/pkg/stanwasm.js

@@ -5,10 +5,8 @@ import * as import2 from "./snippets/stanwasm-2319b34998707c5e/js/aot_bridge.js"
 
 
 /**
- * One compiled Stan model. Holds both the parsed AST (`Model`) and a
- * pre-traced `Compiled` for fast log-prob evaluation. Sampling consumes
- * the `Compiled` and re-builds it from the retained AST afterwards, so
- * the same `StanModel` instance can be sampled repeatedly.
+ * One compiled Stan model: the parsed AST plus a pre-traced `Compiled`.
+ * Sampling consumes the `Compiled` and rebuilds it from the AST after.
  */
 export class StanModel {
     __destroy_into_raw() {
@@ -22,10 +20,8 @@ export class StanModel {
         wasm.__wbg_stanmodel_free(ptr, 0);
     }
     /**
-     * AOT-compile this model to a self-contained wasm module. Returns the
-     * wasm bytes (callers can pass these to `WebAssembly.instantiate` to
-     * obtain an independent log_prob_grad runtime — useful for Web Workers
-     * or for inspection).
+     * AOT-compile this model to a self-contained wasm module. Pass the bytes to
+     * `WebAssembly.instantiate` for an independent log_prob_grad runtime.
      * @returns {Uint8Array}
      */
     compileToWasm() {
@@ -38,9 +34,8 @@ export class StanModel {
         return v1;
     }
     /**
-     * Constrained values of `parameters` + `transformed parameters` for one
-     * unconstrained draw (e.g. one row out of `sample()`'s output), flattened
-     * in `paramNames()` order.
+     * Constrained `parameters` + `transformed parameters` for one
+     * unconstrained draw, flattened in `paramNames()` order.
      * @param {Float64Array} unconstrained
      * @returns {Float64Array}
      */
@@ -56,9 +51,8 @@ export class StanModel {
         return v2;
     }
     /**
-     * Stop step-sampling early (or clean up after it finished naturally —
-     * safe to call either way) and restore `logProbGrad`/`sample` by
-     * re-tracing, same as `sample()` does at the end of a run.
+     * Stop step-sampling (safe after it ended naturally too) and restore
+     * `logProbGrad`/`sample` by re-tracing.
      */
     finishStepSampling() {
         wasm.stanmodel_finishStepSampling(this.__wbg_ptr);
@@ -75,18 +69,8 @@ export class StanModel {
         return v1;
     }
     /**
-     * Evaluate `generated quantities` for a batch of unconstrained draws
-     * (e.g. `sample()`'s output). `draws` is a flat row-major buffer of
-     * shape `(n_draws, n_params)`; the result is `(n_draws, n_gen_quantities)`,
-     * row-major, in `genQuantityNames()` order. A single RNG stream (seeded
-     * by `seed`) is shared across all draws so repeated `_rng` calls don't
-     * repeat the same values draw-to-draw.
-     *
-     * Note: unlike `sampleViaAot`, there is no AOT-compiled counterpart of
-     * this method — `compileToWasm` only exports `log_prob_grad`. Generated
-     * quantities involve RNG and branching that the flat-tape AOT codegen
-     * doesn't model, and (running once per draw rather than once per NUTS
-     * leapfrog step) don't need it for performance.
+     * `generated quantities` over row-major `(n_draws, n_params)` draws.
+     * Result is row-major in `genQuantityNames()` order; one seeded RNG stream.
      * @param {Float64Array} draws
      * @param {number} num_draws
      * @param {bigint} seed
@@ -178,11 +162,8 @@ export class StanModel {
         return v2;
     }
     /**
-     * Same as `sample`, but evaluates `log_prob_grad` through a
-     * pre-instantiated AOT-compiled model wasm bound via `setAotExports`.
-     * V8 JITs the unrolled forward+backward pass in the AOT module, which
-     * can be substantially faster than the in-process tape replay used by
-     * `sample`. Both produce identical samples for a given seed.
+     * `sample` through a `setAotExports`-bound AOT wasm instead of tape replay;
+     * V8 JITs the unrolled pass. Identical samples for a given seed.
      * @param {Float64Array} init
      * @param {number} num_warmup
      * @param {number} num_draws
@@ -201,14 +182,8 @@ export class StanModel {
         return v2;
     }
     /**
-     * Start a step-by-step NUTS run: unlike `sample()`, which runs the whole
-     * chain inside one wasm call and returns only at the end, this leaves
-     * the sampler's state alive in the `StanModel` instance so `stepDraw()`
-     * can advance it one draw at a time — genuinely watching the sampler
-     * work, not replaying an already-finished chain. Consumes the internal
-     * `Compiled` the same way `sample()` does; call `finishStepSampling()`
-     * (or exhaust `stepDraw()` up to `num_warmup + num_draws` calls, which
-     * does it automatically) before using `logProbGrad`/`sample` again.
+     * Start a NUTS run that `stepDraw()` advances one draw at a time. Consumes
+     * the `Compiled`: call `finishStepSampling()` before `logProbGrad`/`sample`.
      * @param {Float64Array} init
      * @param {number} num_warmup
      * @param {number} num_draws
@@ -223,19 +198,8 @@ export class StanModel {
         }
     }
     /**
-     * Advance the step-sampling chain started by `startStepSampling` by
-     * exactly one draw. Returns a flat array: `n_params` position values,
-     * then `1.0`/`0.0` for whether this draw was still in the warmup
-     * (tuning) phase, then `1.0`/`0.0` for whether it diverged, then the
-     * leapfrog `step_size` and `num_steps` nuts-rs actually used for this
-     * draw — these come straight out of nuts-rs's own dual-averaging
-     * adaptation and trajectory-length search, not anything this crate
-     * computes, so they're a way to show the real sampler internals at
-     * work rather than just the resulting draw. Once the requested
-     * `num_warmup + num_draws` draws have all been returned, this
-     * automatically restores `logProbGrad`/`sample` (by re-tracing, same as
-     * `sample()` does) and further calls fail until `startStepSampling` runs
-     * again.
+     * Advance one draw: `n_params` positions, tuning and diverging as `1.0`/`0.0`,
+     * then nuts-rs's own `step_size` and `num_steps`. Restores `sample` when done.
      * @returns {Float64Array}
      */
     stepDraw() {
@@ -258,13 +222,8 @@ export function clearAotExports() {
 }
 
 /**
- * Runs once when the wasm module is instantiated. Forwards Rust panics
- * (Stan-typo'd names and invalid RNG parameters are now clean `JsError`s
- * instead, but a handful of internal-invariant panics remain, e.g. index
- * out of bounds on a malformed AST) to `console.error` with a real message
- * and backtrace, instead of an opaque `RuntimeError: unreachable`. The
- * panicking call still traps the instance — this is diagnostics, not
- * recovery — but it means a bug report can include what actually broke.
+ * Forwards Rust panics to `console.error` with a message and backtrace rather
+ * than an opaque `RuntimeError: unreachable`. Diagnostics: the instance still traps.
  */
 export function init_panic_hook() {
     wasm.init_panic_hook();
@@ -280,9 +239,8 @@ export function setAotExports(exports) {
 }
 
 /**
- * Returns the linear memory backing this wasm module. Pass to
- * `WebAssembly.instantiate` as the `stan.memory` import when bringing up an
- * AOT model so the two modules share buffers (zero-copy bridge).
+ * The linear memory backing this module. Pass as the `stan.memory` import when
+ * instantiating an AOT model so the two share buffers.
  * @returns {any}
  */
 export function sharedMemory() {