@seantalts/stanli 0.19.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -43,6 +43,22 @@ const fit = await sample({
43
43
  `historySize` and Pathfinder's own `initRadius` are also supported. This mode
44
44
  does not perform PSIS resampling.
45
45
 
46
+ `fastMath: true` opts a model into fast mode, as `fast_math` does in Python and
47
+ R: Stan source is compiled with fused multiply-add rewriting, the runtime
48
+ regroups sums, and likelihood terms that repeat over the data are evaluated
49
+ once per distinct case. Results can differ from the default in the last bits.
50
+ It is off by default, `fit.fastMath` reports the mode a fit ran in, and it
51
+ needs the portable compiler (`stanli-compiler.js`). With a precompiled `mir`,
52
+ give `compile()` and `sample()` the same value:
53
+
54
+ ```js
55
+ const { mir } = await compile({ code, fastMath: true });
56
+ const fit = await sample({ mir, data, fastMath: true });
57
+ fit.fastMath; // true
58
+ ```
59
+
60
+ See [fast mode](../docs/fast-mode.md) for what it changes and how accurate it is.
61
+
46
62
  For NUTS, `await diagnose(fit)` returns the same text report as the R and
47
63
  Python bindings: divergences, maximum-treedepth saturation, E-BFMI,
48
64
  rank-normalized R-hat, and bulk/tail ESS. Pass an array of fits from the
package/index.mjs CHANGED
@@ -89,10 +89,25 @@ export function preload(opts) {
89
89
  return Promise.all(jobs);
90
90
  }
91
91
 
92
+ function fastMathOption(value) {
93
+ if (value == null) return false;
94
+ if (typeof value !== "boolean")
95
+ throw new TypeError("fastMath must be true or false");
96
+ return value;
97
+ }
98
+
92
99
  /** Compile Stan source to portable MIR (one worker loads stanc3).
93
- * @returns {Promise<{mir: string, ms: {stanc: number}}>} */
100
+ * @param {Object} opts
101
+ * @param {string} opts.code
102
+ * @param {boolean} [opts.fastMath=false] Compile in fast mode (fused
103
+ * multiply-add rewriting; numerics may differ from CmdStan in the last
104
+ * bits). Pass the same value to sample() together with the returned MIR.
105
+ * Needs the portable stanli compiler.
106
+ * @returns {Promise<{mir: string, fastMath: boolean,
107
+ * ms: {stanc: number}}>} */
94
108
  export function compile(opts) {
95
- return request({ cmd: "compile", code: opts.code }, opts);
109
+ return request({ cmd: "compile", code: opts.code,
110
+ fastMath: fastMathOption(opts.fastMath) }, opts);
96
111
  }
97
112
 
98
113
  function pathfinderInitOptions(value) {
@@ -144,6 +159,11 @@ function pathfinderInitOptions(value) {
144
159
  * @param {number} [opts.maxError] WALNUTS only: largest drift in the
145
160
  * joint log density allowed across one macro step before the step is
146
161
  * halved within the trajectory. Omit for the runtime default (0.5).
162
+ * @param {boolean} [opts.fastMath=false] Opt this model into fast mode:
163
+ * Stan source is compiled with fused multiply-add rewriting and the
164
+ * runtime may use faster kernels whose results can differ from CmdStan
165
+ * in the last bits. With a precompiled `mir`, pass the same value that
166
+ * `compile()` was given. The default leaves every result unchanged.
147
167
  * @param {function(string)} [opts.onProgress] Stage announcements.
148
168
  * @param {function(Object)} [opts.onLive] Streaming draws while NUTS
149
169
  * runs: {liveMeta: {names, warmup, samples}} once per call, then
@@ -153,7 +173,7 @@ function pathfinderInitOptions(value) {
153
173
  * message per L-BFGS iterate.
154
174
  * @returns {Promise<{names: string[], samples: number, generatedStart: number,
155
175
  * columns: Object<string, Float64Array>,
156
- * exactLp: boolean,
176
+ * exactLp: boolean, fastMath: boolean,
157
177
  * sampler: string, maxDepth: number|null,
158
178
  * samplerStats: Float64Array|null,
159
179
  * pathfinder?: {path: {iter, lp}[], khat: number,
@@ -180,6 +200,7 @@ export function sample(opts) {
180
200
  const sampler = opts.sampler === "walnuts" || opts.sampler === "pathfinder"
181
201
  ? opts.sampler : "nuts";
182
202
  const pathfinderInit = pathfinderInitOptions(opts.pathfinderInit);
203
+ const fastMath = fastMathOption(opts.fastMath);
183
204
  if (pathfinderInit && sampler !== "nuts")
184
205
  throw new RangeError("pathfinderInit is available only with NUTS");
185
206
  return request({
@@ -197,9 +218,10 @@ export function sample(opts) {
197
218
  sampler,
198
219
  maxError: opts.maxError == null ? 0 : opts.maxError,
199
220
  pathfinderInit,
221
+ fastMath,
200
222
  }, opts).then((done) => {
201
223
  const { names, samples, generatedStart, ms, exactLp, pathfinder,
202
- sampler, maxDepth } = done;
224
+ sampler, maxDepth, fastMath } = done;
203
225
  const flat = new Float64Array(done.columns);
204
226
  const columns = {};
205
227
  names.forEach((name, i) => {
@@ -207,8 +229,8 @@ export function sample(opts) {
207
229
  });
208
230
  const samplerStats = done.samplerStats
209
231
  ? new Float64Array(done.samplerStats) : null;
210
- return { names, samples, generatedStart, columns, ms, exactLp, pathfinder,
211
- sampler, maxDepth, samplerStats };
232
+ return { names, samples, generatedStart, columns, ms, exactLp, fastMath,
233
+ pathfinder, sampler, maxDepth, samplerStats };
212
234
  });
213
235
  }
214
236
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@seantalts/stanli",
3
- "version": "0.19.0",
3
+ "version": "0.20.0",
4
4
  "description": "Full Stan in the browser: stanc3 compiles the model in JS, a WASM runtime lowers it to an op graph and runs NUTS. No server, no C++ toolchain.",
5
5
  "type": "module",
6
6
  "main": "index.mjs",