driftlet 0.16.2 → 1.0.0

package/src/blockTridiagonal.js

@@ -124,7 +124,15 @@ export class BlockTridiagonal {
           }
         }
       }
-      const ratio = luFactor(lu, o, piv, offX[i], m, this);
+      let ratio = luFactor(lu, o, piv, offX[i], m, this);
+      // A pivot far below the entries it's formed from may be round-off alone (the level of a
+      // region that only the blocks after it hold): its value, 7e-32 or 3e-16 or 0 as the
+      // unknowns happen to be listed, then scales all that follows (by 1e31, and the next block
+      // lost its own pivot outright). Redone with each entry's magnitudes carried (see
+      // cancellation), a pivot 1e-18 of them, all its digits lost, is perturbed like one that
+      // cancelled to exactly nothing. (At 1e-15 it can still hold a digit Newton needs: a port's
+      // steady solve wandered instead of converging.)
+      if (this.staticPivots && ratio < 1e-12) ratio = this._noisyPivots(i);
       if (!(ratio > 0)) {
         this.factored = false;
         this.singularBlock = i;
@@ -146,6 +154,70 @@ export class BlockTridiagonal {
     this.factored = true;
   }
 
+  // Block i again, its W and LU with the magnitudes each entry is formed from (as cancellation()
+  // does), perturbing pivots 1e-18 of theirs. Returns the block's pivot ratio.
+  _noisyPivots(i) {
+    const { A, B, sizes, offA, offB, offC, offX } = this, cp = this._cp, lu = this._lu, piv = this._piv;
+    const m = sizes[i], mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], o = offB[i], oc = i > 0 ? offC[i - 1] : 0;
+    const S = (this._mag ??= new Float64Array(this._tmp.length * this._tmp.length));
+    for (let r = 0; r < m; r++) {
+      for (let c = 0; c < m; c++) {
+        let v = B[o + r * m + c], sum = Math.abs(v);
+        for (let k = 0; k < mp; k++) {
+          const a = A[oa + r * mp + k];
+          if (a === 0) continue;
+          const t = a * cp[oc + k * m + c];
+          v -= t;
+          sum += Math.abs(t);
+        }
+        lu[o + r * m + c] = v;
+        S[r * m + c] = sum;
+      }
+    }
+    let maxEntry = 0;
+    for (let k = 0; k < m * m; k++) maxEntry = Math.max(maxEntry, Math.abs(lu[o + k]));
+    if (maxEntry === 0) return 0;
+    let minPivot = Infinity;
+    for (let k = 0; k < m; k++) {
+      let best = k, bestVal = Math.abs(lu[o + k * m + k]);
+      for (let r = k + 1; r < m; r++) {
+        const v = Math.abs(lu[o + r * m + k]);
+        if (v > bestVal) { best = r; bestVal = v; }
+      }
+      piv[offX[i] + k] = best;
+      if (best !== k) {
+        for (let c = 0; c < m; c++) {
+          let t = lu[o + k * m + c];
+          lu[o + k * m + c] = lu[o + best * m + c];
+          lu[o + best * m + c] = t;
+          t = S[k * m + c];
+          S[k * m + c] = S[best * m + c];
+          S[best * m + c] = t;
+        }
+      }
+      const sum = S[k * m + k];
+      if (bestVal <= 1e-18 * sum || bestVal === 0) {
+        const size = sum > 0 ? 1e-15 * sum : 1e-15 * maxEntry;
+        bestVal = size;
+        lu[o + k * m + k] = lu[o + k * m + k] < 0 ? -size : size;
+        this.perturbedPivots++;
+      }
+      if (bestVal < minPivot) minPivot = bestVal;
+      const inv = 1 / lu[o + k * m + k];
+      for (let r = k + 1; r < m; r++) {
+        const f = (lu[o + r * m + k] *= inv);
+        if (f !== 0) {
+          const af = Math.abs(f);
+          for (let c = k + 1; c < m; c++) {
+            lu[o + r * m + c] -= f * lu[o + k * m + c];
+            S[r * m + c] += af * S[k * m + c];
+          }
+        }
+      }
+    }
+    return minPivot / maxEntry;
+  }
+
   /**
    * Solve with the current factorisation. `rhs` and `out` are Float64Arrays of length `size`
    * (node-major); they may be the same array.

package/src/channels.js

@@ -1,7 +1,7 @@
 // driftlet/kit: voltage-gated channels as plain definition data. Hodgkin and Huxley's squid axon:
 // its gates, and permeabilities for its Na⁺, K⁺ and leak channels, for a membrane face.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 
 const fail = (message) => {
@@ -49,13 +49,15 @@ export function ghkCurrent(z, inside, outside, V, T) {
  * port along a region: links that are their linear conductances, G = g × area per volume, gated the
  * same, each ion's reversal potential following from the port's bath and the concentrations inside
  * (so `inside`, `outside` and `at` aren't needed).
- * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
+ * @param {{ inside: object, outside: object, T: number, g?: { Na?: number, K?: number, leak?: number },
  *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string }, linear?: boolean, area?: number }} opts concentrations in
  *   mol/m³ by species name, K, S/m², V
  * @returns {{ gates: object, species: object }}
  */
-export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {}, linear = false, area } = {}) {
-  need(num(T) && T > 0, `hodgkinHuxley: T must be a temperature in K, got ${T}`);
+export function hodgkinHuxley({ inside, outside, T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {}, linear = false, area } = {}) {
+  checkOptions('hodgkinHuxley', arguments[0], ['inside', 'outside', 'T', 'g', 'leak', 'leakZ', 'at', 'names', 'linear', 'area']);
+  // T sets the gates' rates, so it must be the device's: never defaulted (their 6.3 °C, under a body-temperature device, doubled a spike's peak, silently).
+  need(num(T) && T > 0, `hodgkinHuxley: T must be the device's temperature in K (their own experiments were at 279.45 K, 6.3 °C), got ${T}`);
   need(num(at), `hodgkinHuxley: at must be a voltage (V), got ${at}`);
   const G = { Na: 1200, K: 360, leak: 3, ...g };
   const Na = names.Na ?? 'Na+', K = names.K ?? 'K+';

package/src/checks.js

@@ -5,6 +5,7 @@
 import { Device } from './index.js';
 import { FARADAY } from './constants.js';
 import { unitWarnings } from './describe.js';
+import { checkOptions } from './errors.js';
 
 const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs(v) >= 1e4 || Math.abs(v) < 1e-2 ? v.toExponential(p - 1) : String(+v.toPrecision(p)));
 
@@ -29,6 +30,11 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
+ * - **order** (a steady state, with `refine` and `order`, the defaults): the device solved from
+ *   its definition twice, its species listed as given and in reverse, which must give the same
+ *   steady state (each terminal's voltage and current, each species' amount). A solve that
+ *   depends on the listing has converged somewhere that isn't steady without noticing (round 11's
+ *   fuzzer found it in ~1% of random reacting devices, by exactly this test).
  * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
  *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
@@ -37,12 +43,13 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   (about 3/4 of it).
  * @param {import('./index.js').Device} device
  * @param {object} [sol] the solution to check (default: the device's present state)
- * @param {{ refine?: boolean, tol?: number }} [opts]
+ * @param {{ refine?: boolean, tol?: number, order?: boolean }} [opts]
  * Every check passed when `ok`; an item with `ok: null` (a warning, or a check that couldn't be
  * made) asks you to look, and doesn't fail it. `text` is a line per check, marked ok, FAIL or ?.
  * @returns {{ ok: boolean, items: CheckItem[], text: string }}
  */
-export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
+export function check(device, sol, { refine = true, tol = 1e-2, order = true } = {}) {
+  checkOptions('check', arguments[2], ['refine', 'tol', 'order']);
   sol ??= device.solution();
   const { model, solver, def } = device;
   const steady = sol.steady ?? solver.atSteady;
@@ -66,8 +73,17 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
   // The rest checks a solution, which an unconverged state isn't.
   if (sol.converged) {
     const ledger = steady ? balance(device, sol) : null;
+    // A reaction the steady state needs at equilibrium, left far from it (too slow to see: the
+    // solution warns of it), isn't steady, however quietly its ledgers sum: "equilibrium" was
+    // printed beside that warning.
+    const stuck = steady ? solver.stuckReactions() : [];
+    if (ledger && stuck.length > 0) {
+      ledger.ok = false;
+      ledger.summary = `not a steady state: ${stuck.map((s) => `${s.where} is ${sig(s.affinity * solver.VT * 1e3)} mV of affinity from equilibrium`).join(', ')}, too slow for the solve to see (see the warnings); its ledgers say only that nothing moves fast enough to count`;
+    }
     items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+    if (steady && refine && order && model.species.length > 1) items.push(orderCheck(device, sol, ledger.details.gross));
     // A transient's answer depends on its whole history (and on drives set along the way), so
     // only a run of its own on a finer grid can check it.
     else if (refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
@@ -156,7 +172,10 @@ function balance(device, sol) {
   const size = (l) => Math.max(0, ...l.terms.map((t) => Math.abs(t.rate)));
   const natural = naturalScales(device, sol), inSolution = naturalScales(device, sol, false); // (partners' scale: not a metal's conductance)
   const scale = (l) => Math.max(natural[l.i], ...l.terms.flatMap((t) => (partners.get(t.what) ?? []).map((j) => inSolution[j])));
-  const moving = ledgers.filter((l) => size(l) > 1e-8 * scale(l));
+  // Small flows count too where they balance, as real ones do to round-off (a diode at 1 µV,
+  // 1e-19 of its scale, to 1e-15), and round-off doesn't. (Above 1e-8 of the scale, any.)
+  const balanced = (l) => Math.abs(l.terms.reduce((a, t) => a + t.rate, 0)) <= 1e-9 * size(l);
+  const moving = ledgers.filter((l) => size(l) > 1e-8 * scale(l) || (size(l) > 1e-20 * scale(l) && balanced(l)));
   let worst = 0;
   const lines = [];
   for (const l of moving) {
@@ -314,6 +333,62 @@ function gridCheck(device, sol, tol, gross) {
   };
 }
 
+// The device solved from its definition with its species listed as given and in reverse: the
+// same steady state either way, or one of them isn't steady. (Both from the definition, not this
+// state, whose closed amounts a transient or set() may have moved from c0.)
+function orderCheck(device, sol, gross) {
+  const { def, model } = device;
+  const solveAt = (d) => {
+    const dev = new Device(d);
+    if (sol.time > 0) dev.solver.time = sol.time; // waveforms at the same time
+    return dev.solve();
+  };
+  let a, b;
+  try {
+    a = solveAt(def);
+    b = solveAt({ ...def, species: [...def.species].reverse() });
+  } catch (e) {
+    return { name: 'order', ok: null, summary: `could not solve the device with its species reversed (${e.message})` };
+  }
+  if (!a.converged || !b.converged) {
+    const which = a.converged ? 'listed in reverse' : b.converged ? 'listed as given' : 'listed either way';
+    return { name: 'order', ok: null, summary: `the device solved from its definition did not converge with its species ${which}: compare with a long advance() by hand` };
+  }
+  const VT = model.RT / FARADAY, diffs = [];
+  // (Currents only where the ledgers see something move: in equilibrium they're round-off of
+  // whatever exchanges fastest, an electrode's couple, and a wrong state shows in the voltages
+  // and amounts instead.)
+  // (and above 1e-16 of what the species could carry, as the grid check's floor: a drift at
+  // 1e-16 A/m², still moving at 1e12 s, isn't worth reporting)
+  const natural = naturalScales(device, sol), floorI = 1e-16 * FARADAY * Math.max(0, ...model.species.map((sp, i) => Math.abs(sp.z) * natural[i]).filter(Number.isFinite));
+  for (const [name, t] of Object.entries(a.terminals)) {
+    const u = b.terminals[name];
+    diffs.push({ what: `${name} voltage`, a: t.V, b: u.V, rel: Math.abs(u.V - t.V) / (1e-6 * Math.max(VT, Math.abs(t.V))), unit: 'V' });
+    if (gross > 0 && Math.max(Math.abs(t.current), Math.abs(u.current), gross) > floorI) diffs.push({ what: `${name} current`, a: t.current, b: u.current, rel: Math.abs(u.current - t.current) / (1e-3 * Math.max(Math.abs(t.current), Math.abs(u.current), gross)), unit: unitsOf(model).current });
+  }
+  const vol = model.grid.vol, amount = (s, name) => s.x.reduce((m, _, g) => m + (Number.isFinite(s.c[name][g]) ? vol[g] * s.c[name][g] : 0), 0);
+  const amounts = model.species.map((sp) => [sp.name, amount(a, sp.name), amount(b, sp.name)]);
+  const most = Math.max(0, ...amounts.map(([, x, y]) => Math.max(Math.abs(x), Math.abs(y))));
+  for (const [name, x, y] of amounts) diffs.push({ what: `${name} amount`, a: x, b: y, rel: Math.abs(y - x) / (1e-6 * Math.max(Math.abs(x), Math.abs(y)) + 1e-12 * most), unit: 'mol/m²' });
+  // Agreeing to near round-off (a µV, a millionth of an amount): ok. Within a thousand times that
+  // (a mV, a thousandth), enough for any plot, but a weakly held part of one solve not quite
+  // steady: look. Beyond: one of them isn't a steady state.
+  const worst = diffs.reduce((w, d) => (d.rel > (w?.rel ?? -1) ? d : w), null);
+  const ok = !(worst.rel > 1) ? true : worst.rel > 1e3 ? false : null;
+  const what = `${worst.what} ${sig(worst.a, 6)} → ${sig(worst.b, 6)} ${worst.unit}`;
+  return {
+    name: 'order',
+    ok,
+    summary:
+      ok === true
+        ? 'the same steady state with the species listed in reverse'
+        : ok === null
+          ? `listed in reverse, the species give nearly the same steady state (${what}): not to round-off, so some weakly held part is not quite steady in one of them`
+          : `listed in reverse, the species give a different steady state: ${what}. One of them is not steady, though its solve converged, or the device has more than one steady state (one of them perhaps unstable): compare with a long advance() from the start, kick each and watch it with dtMax (see numerics.md, Steady state), and please report the device.`,
+    details: { diffs },
+  };
+}
+
 // Charge density at a node of region r, C/m³: the species plus the region's fixed charge.
 function rho(s, g, model, r) {
   let q = model.regions[r].fixedCharge ?? 0;

package/src/data.js

@@ -3,7 +3,7 @@
 // only. How levels line up at an interface, and a surface's work function, belong to that
 // interface or surface and are never in here.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY, GAS_CONSTANT, AVOGADRO } from './constants.js';
 
 const fail = (message) => {
@@ -72,6 +72,7 @@ export const METALS = freeze(
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
 export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
+  checkOptions('aqueous', arguments[1], ['epsr', 'material']);
   if (!Array.isArray(names) || names.length === 0) fail('aqueous: give a list of ions, e.g. aqueous([\'Na+\', \'Cl-\'])');
   const species = [], entries = {};
   for (const name of names) {
@@ -93,6 +94,8 @@ export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
 export function semiconductor(name, { material = name } = {}) {
+  if (arguments[1]?.T !== undefined) fail('semiconductor: the data are for 300 K and take no T: give the device T: 300, or write your own material for another temperature (SEMICONDUCTORS has the numbers)');
+  checkOptions('semiconductor', arguments[1], ['material']);
   const sc = SEMICONDUCTORS[name];
   if (!sc) fail(`semiconductor: no data for '${name}' (the library has ${Object.keys(SEMICONDUCTORS).join(', ')})`);
   const VT = (GAS_CONSTANT * 300) / FARADAY;
@@ -121,6 +124,7 @@ export function semiconductor(name, { material = name } = {}) {
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
 export function metal(name, { material = name } = {}) {
+  checkOptions('metal', arguments[1], ['material']);
   const m = METALS[name];
   if (!m) fail(`metal: no data for '${name}' (the library has ${Object.keys(METALS).join(', ')})`);
   return { species: [{ name: 'e-', z: -1 }], materials: { [material]: { conductor: { species: 'e-', conductivity: m.conductivity } } } };

package/src/device.js

@@ -1316,7 +1316,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
       fixed !== 0
         ? `${path}.bath: the bath is the end material '${mat.name}' at this composition, and with its fixed charge (${fixed} mol/m³ of charge) it is not neutral (net ${charge}). ` +
             `For a solution outside a charged region, give the solution's material (bath.material), whose composition is then neutral on its own`
-        : `${path}.bath: composition is not neutral (net ${charge} mol/m³ of charge)`,
+        : `${path}.bath: composition is not neutral (net ${charge} mol/m³ of charge): add the counter-ions' share`,
     );
     // The reference species pins the bath's φ; every other species follows from composition.
     const zb = bathZeta(bm, cb, own ? 0 : region.background);

package/src/devices.js

@@ -5,6 +5,7 @@
 import { AVOGADRO, FARADAY, GAS_CONSTANT, units } from './constants.js';
 import { photogeneration } from './sources.js';
 import { drive } from './stack.js';
+import { checkOptions } from './errors.js';
 
 const m3 = (x) => x / AVOGADRO, eV = units.eV;
 
@@ -33,6 +34,7 @@ const P = {
  * @returns {import('./types.js').DeviceDefinition}
  */
 export function perovskiteCell({ V = 1.2, light = 1, bulkSRH = true } = {}) {
+  checkOptions('perovskiteCell', arguments[0], ['V', 'light', 'bulkSRH']);
   const { T } = P, VT = (GAS_CONSTANT * T) / FARADAY;
   const ni = Math.sqrt(P.gc * P.gv) * Math.exp(-(P.Ec - P.Ev) / (2 * VT));
   const n0 = P.gc * Math.exp((P.EcE + VT * Math.log(P.dE / P.gcE) - P.Ec) / VT); // the perovskite's n at the TiO₂'s Fermi level

package/src/equation.js

@@ -2,7 +2,7 @@
 // definition's reactions can be written this way; they compile to signed stoichiometry (ν < 0
 // consumed by the forward reaction, left to right as written).
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -163,6 +163,7 @@ export const SHE = Object.freeze(half('2 H+ + 2 e- = H2', { H2: 0 }));
  * @returns {Float64Array}
  */
 export function level(sol, halfReaction, { standard = false } = {}) {
+  checkOptions('level', arguments[2], ['standard']);
   if (!isObject(halfReaction)) fail('level: give a half-reaction from half()');
   const { equation, fixed = {} } = halfReaction;
   const terms = parseEquation(equation, 'level');

package/src/errors.js

@@ -6,3 +6,36 @@ export class DeviceError extends Error {
     this.name = 'DeviceError';
   }
 }
+
+// The nearest of `names` to a mistyped one: the same but for case, '_' or '-', or one or two
+// letters off (dtmax for dtMax, engery for energy).
+function nearest(name, names) {
+  const plain = (s) => s.toLowerCase().replace(/[_-]/g, '');
+  const edits = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      const next = [i];
+      for (let j = 1; j <= b.length; j++) next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      row = next;
+    }
+    return row[b.length];
+  };
+  return names.find((n) => plain(n) === plain(name)) ?? names.find((n) => n.length > 3 && edits(plain(n), plain(name)) <= 2);
+}
+
+/**
+ * A function's options: a name it doesn't take (a typo) is an error, not silently ignored.
+ * @param {string} where the function, for the message
+ * @param {unknown} opts
+ * @param {string[]} allowed
+ * @param {new (message: string) => Error} [Kind]
+ */
+export function checkOptions(where, opts, allowed, Kind = DeviceError) {
+  if (opts === undefined || opts === null) return;
+  if (typeof opts !== 'object' || Array.isArray(opts)) throw new Kind(`${where}: options must be an object (${allowed.join(', ')})`);
+  for (const k of Object.keys(opts)) {
+    if (opts[k] === undefined || allowed.includes(k)) continue;
+    const near = nearest(k, allowed);
+    throw new Kind(`${where}: no option '${k}'${near ? ` (did you mean '${near}'?)` : ''}; the options are ${allowed.join(', ')}`);
+  }
+}

package/src/grid.js

@@ -10,6 +10,7 @@
 // cell widths outright (`cells`), as a metal region does: one cell, exact for Ohm's law.
 
 const DEFAULTS = Object.freeze({ ratio: 1.2, minCells: 8 });
+const MAX_CELLS = 1e6; // a live demo's grid has hundreds to thousands
 
 /**
  * Cell widths for one region: fine at both ends, growing toward the middle.
@@ -52,6 +53,17 @@ export function gradedCells(length, { hmin, hmax, ratio = DEFAULTS.ratio, minCel
  */
 export function buildGrid(regions, opts = {}) {
   if (!Array.isArray(regions) || regions.length === 0) throw new Error('grid needs at least one region');
+  // A grid far past any demo's (most often a length given in µm as if in m) would only exhaust
+  // memory: refuse it before building it. Each region needs at least length/hmax cells.
+  const least = regions.map((reg) => {
+    const g = { ...DEFAULTS, ...opts, ...(reg.grid ?? {}) };
+    return reg.cells ? reg.cells.length : reg.length / Math.min(g.hmax ?? Infinity, reg.length / g.minCells);
+  });
+  const total = least.reduce((s, n) => s + n, 0);
+  if (!(total <= MAX_CELLS)) {
+    const r = least.indexOf(Math.max(...least)), g = { ...opts, ...(regions[r].grid ?? {}) };
+    throw new RangeError(`at least ${total.toExponential(1)} cells, past the ${MAX_CELLS.toExponential(0)} a device may have: ${regions[r].name ?? `region ${r}`} is ${regions[r].length} m long at hmax ${g.hmax ?? '(none)'} m. Lengths are in metres (units.um(1) is 1e-6): check them, or raise hmax`);
+  }
 
   const perRegion = regions.map((reg) => reg.cells ?? gradedCells(reg.length, { ...opts, ...(reg.grid ?? {}) }));
   const nNodes = perRegion.reduce((s, cells) => s + cells.length + 1, 0);

package/src/index.js

@@ -4,13 +4,11 @@ import { normalizeDevice, DeviceError } from './device.js';
 import { Solver, SolverError } from './solver.js';
 import { makeSolution } from './solution.js';
 import { merge } from './merge.js';
+import { checkOptions } from './errors.js';
 
-export { DeviceError, normalizeDevice } from './device.js';
+export { DeviceError } from './device.js';
 import { normalizeDrives } from './device.js';
 export { SolverError } from './solver.js';
-export { buildGrid, gradedCells } from './grid.js';
-export { BlockTridiagonal } from './blockTridiagonal.js';
-export { bernoulli, bernoulliDerivative } from './bernoulli.js';
 export * from './constants.js';
 
 // Whether two definitions differ only in their terminals' drives (V, I, R on the contacts and
@@ -32,7 +30,10 @@ function sameExceptDrives(a, b) {
   for (const k of keys) {
     if (k === 'contacts') {
       const ca = a.contacts ?? {}, cb = b.contacts ?? {};
-      for (const side of new Set([...Object.keys(ca), ...Object.keys(cb)])) if (!eq(ca[side] ?? {}, cb[side] ?? {}, true)) return false;
+      for (const side of new Set([...Object.keys(ca), ...Object.keys(cb)])) {
+        if (side !== 'left' && side !== 'right') return false; // a misspelt side: rebuild, which says so
+        if (!eq(ca[side] ?? {}, cb[side] ?? {}, true)) return false;
+      }
     } else if (k === 'ports') {
       const pa = a.ports ?? [], pb = b.ports ?? [];
       if (pa.length !== pb.length || pa.some((p, i) => !eq(p, pb[i], true))) return false;
@@ -41,6 +42,9 @@ function sameExceptDrives(a, b) {
   return true;
 }
 
+// A method's options: a name it doesn't take (a typo, dtmax for dtMax) is an error, not ignored.
+const options = (opts, method, allowed) => checkOptions(method, opts, allowed, SolverError);
+
 /** @typedef {import('./types.js').DeviceDefinition} DeviceDefinition */
 /** @typedef {import('./types.js').Solution} Solution */
 
@@ -63,8 +67,8 @@ export class Device {
   }
 
   /**
-   * Change part of the definition (deep-merged). A contact given V or I drops the other, so
-   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
+   * Change part of the definition (deep-merged). A contact given V or I drops the other (and
+   * given I, any series R), so `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
    * `{ ports: { gate: { V: 0.2 } } }` (an array replaces them all). A change to the terminals'
    * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
    * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
@@ -73,7 +77,8 @@ export class Device {
    */
   set(patch) {
     // A terminal given a new kind of drive drops the old one: { I: 0 } replaces a held V.
-    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
+    // (A current drives a terminal alone: given I, a contact drops V and any series R too.)
+    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined, ...('R' in c ? {} : { R: undefined }) } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
     for (const side of ['left', 'right']) {
       const c = patch?.contacts?.[side];
       if (c && typeof c === 'object') patch = { ...patch, contacts: { ...patch.contacts, [side]: redrive(c) } };
@@ -178,6 +183,7 @@ export class Device {
    * @returns {Solution}
    */
   solve(opts) {
+    options(opts, 'solve', ['maxSteps', 'tol', 'continuation']);
     // A solve that fails reports the state it failed in, and leaves the device as it was: a
     // device with no steady state (a host filling at a current) can still advance() from there.
     const snap = this.solver._snapshot();
@@ -195,6 +201,7 @@ export class Device {
    * @returns {Solution}
    */
   step(dt, opts) {
+    options(opts, 'step', ['method']);
     return makeSolution(this.solver, this.solver.advance(dt, opts));
   }
 
@@ -210,22 +217,26 @@ export class Device {
    * @returns {Solution}
    */
   advance(tEnd, opts) {
+    options(opts, 'advance', ['tol', 'dt0', 'dtMax', 'budgetMs', 'maxSteps', 'method', 'probes']);
     return makeSolution(this.solver, this.solver.integrate(tEnd, opts));
   }
 
   /**
    * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its
    * held voltage is perturbed (or its driven current), the others keep their drives.
-   * Z = δV/δI with I into the device (Ω·m²).
+   * Z = δV/δI with I into the device (Ω·m²), with the steady state's `warnings`.
    * @param {ArrayLike<number>} frequencies Hz
    * @param {{ terminal?: string, profiles?: boolean }} [opts] the terminal (default 'right'), and
    *   whether to return complex profiles per frequency
    * @returns {import('./types.js').ImpedanceResult}
    */
   impedance(frequencies, opts) {
+    options(opts, 'impedance', ['terminal', 'profiles']);
     const steady = this.solver.solveSteady();
     if (!steady.converged) throw new SolverError('impedance: the steady state did not converge');
-    return this.solver.impedance(frequencies, opts);
+    // The steady state's warnings (an unresolved double layer, say) hold for the impedance too.
+    const { warnings } = makeSolution(this.solver, steady);
+    return { ...this.solver.impedance(frequencies, opts), warnings };
   }
 
   /**

package/src/junction.js

@@ -3,7 +3,7 @@
 // junction (steady between two baths, it is Planck's; stepping from a sharp boundary, a free
 // diffusion junction); these are for comparison, and for quick estimates.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 
 const fail = (message) => {
@@ -40,6 +40,7 @@ function neutral(list, side, what) {
  * @param {{ T?: number }} [opts] K (default 298.15)
  */
 export function henderson(left, right, ions, { T = 298.15 } = {}) {
+  checkOptions('henderson', arguments[3], ['T']);
   const list = prepare(left, right, ions, 'henderson');
   neutral(list, 'cL', 'henderson');
   neutral(list, 'cR', 'henderson');
@@ -66,6 +67,7 @@ export function henderson(left, right, ions, { T = 298.15 } = {}) {
  * @param {{ T?: number, steps?: number }} [opts] K (default 298.15); RK4 steps across (default 4000)
  */
 export function planck(left, right, ions, { T = 298.15, steps = 4000 } = {}) {
+  checkOptions('planck', arguments[3], ['T', 'steps']);
   const list = prepare(left, right, ions, 'planck');
   neutral(list, 'cL', 'planck');
   neutral(list, 'cR', 'planck');

package/src/kit.js

@@ -6,7 +6,7 @@ import { DeviceError } from './errors.js';
 import { FARADAY } from './constants.js';
 
 export { build, combine, layer, ohmic, bath } from './stack.js';
-export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
+export { half, SHE, level } from './equation.js';
 export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from './sources.js';

package/src/live.js

@@ -6,6 +6,7 @@
 
 import { Device } from './index.js';
 import { merge } from './merge.js';
+import { checkOptions } from './errors.js';
 
 const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v) && !ArrayBuffer.isView(v);
 const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
@@ -118,6 +119,7 @@ export class Session {
  * @returns {Live}
  */
 export function live(def, { worker = false, onsolution, maxRamp = 32 } = {}) {
+  checkOptions('live', arguments[1], ['worker', 'onsolution', 'maxRamp']);
   const engine = worker ? workerEngine(def, worker, maxRamp) : localEngine(def, maxRamp);
   let pending = [], busy = false;
   const api = {

package/src/particles.js

@@ -23,6 +23,7 @@
 // and its minority carriers as dots, each one injected, drifting, diffusing and recombining.
 
 import { GAS_CONSTANT } from './constants.js';
+import { checkOptions } from './errors.js';
 
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
@@ -53,6 +54,7 @@ const NONE = 0, DOT = 1, OUTSIDE = 2; // nothing (closed); a cell of dots; a sea
  * @param {() => number} [opts.random] a uniform random source in [0, 1) (default Math.random)
  */
 export function particles(sol, { species, dots = 200, weight, cap = Infinity, cells = 120, random = Math.random } = {}) {
+  checkOptions('particles', arguments[1], ['species', 'dots', 'weight', 'cap', 'cells', 'random']);
   const names = species ?? sol.species.map((s) => s.name).filter((nm) => sol.c[nm].some((v) => v > 0));
   for (const nm of names) if (!sol.c[nm]) throw new RangeError(`particles: no species ${JSON.stringify(nm)} in the solution`);
   if (!(dots > 0 && Number.isFinite(dots))) throw new RangeError(`particles: dots must be a positive number, got ${dots}`);

package/src/plot.js

@@ -14,6 +14,7 @@
 
 import { traces } from './traces.js';
 import { powi } from './pow.js';
+import { checkOptions } from './errors.js';
 
 // Colours by role, light and dark (validated together for colour-vision deficiency; line weight,
 // dash and the legend carry identity too). A role with more members than colours cycles.
@@ -31,6 +32,7 @@ const ROLES = ['electron', 'cation', 'anion', 'redox'];
  * @param {{ dark?: boolean }} [opts]
  */
 export function themeColor(role, slot, { dark = false } = {}) {
+  checkOptions('themeColor', arguments[2], ['dark']);
   const list = THEME[dark ? 'dark' : 'light'][role];
   return list[slot % list.length];
 }
@@ -140,6 +142,7 @@ const instance = Math.random().toString(36).slice(2, 8);
  * @returns {string}
  */
 export function levelChart(tr, { width = 640, height = 360, ylabel = 'voltage (V)', range, xlim, title, ytick = fmt } = {}) {
+  checkOptions('levelChart', arguments[1], ['width', 'height', 'ylabel', 'range', 'xlim', 'title', 'ytick']);
   const id = `driftlet-plot-${instance}-${++counter}`;
   const { x, series, regions } = tr;
   const xs = xlim ? xlim[0] : x[0], xe = xlim ? xlim[1] : x[x.length - 1];
@@ -264,6 +267,7 @@ export function levelChart(tr, { width = 640, height = 360, ylabel = 'voltage (V
  * @returns {string}
  */
 export function bandDiagram(sol, opts = {}) {
+  checkOptions('bandDiagram', arguments[1], ['width', 'height', 'ylabel', 'range', 'xlim', 'title', 'ytick', 'species', 'standard', 'phi', 'energy', 'levels', 'labels', 'shifts']);
   const { width, height, ylabel = opts.energy ? 'electron energy (eV)' : undefined, range, xlim, title, ytick, ...pick } = opts;
   return levelChart(traces(sol, pick), { width, height, ylabel, range, xlim, title, ytick });
 }

package/src/polarization.js

@@ -2,7 +2,7 @@
 // beside the electrode held as it is and the metal's level moved, which is what an Evans diagram
 // plots. Where the net current crosses zero is the spot's open-circuit (mixed) potential.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY } from './constants.js';
 import { powi, powr } from './pow.js';
 
@@ -30,6 +30,7 @@ const fail = (message) => {
  *   positive: into the solution); and their sum
  */
 export function polarization(device, sol, where, V, opts = {}) {
+  checkOptions('polarization', arguments[4], ['surface']);
   const model = device.model, { species, grid, RT } = model, solver = device.solver;
   const Vs = Float64Array.from(typeof V === 'number' ? [V] : V);
   let reactions, nodeOf, carrier, names, surface = null; // (an electrode port's coverages at the spot)

package/src/recorder.js

@@ -2,7 +2,7 @@
 // each animation frame), with the trace joined up across calls and whole solutions kept as
 // frames, for scrubbing back through a run or plotting snapshots side by side.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -18,6 +18,7 @@ const now = () => (typeof performance !== 'undefined' ? performance.now() : Date
  * @param {{ every?: number, times?: number[], probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number } | { interface: number, species?: string, gate?: string })[] }} [opts]
  */
 export function recorder(device, opts = {}) {
+  checkOptions('recorder', arguments[1], ['every', 'times', 'probes']);
   const { every, times, probes } = opts;
   if (every !== undefined && times !== undefined) fail('recorder: give every or times, not both');
   if (every !== undefined && !(every > 0 && Number.isFinite(every))) fail('recorder: every must be a time > 0 (s)');