driftlet 0.16.4 → 1.0.1

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)));
 
@@ -48,6 +49,7 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  * @returns {{ ok: boolean, items: CheckItem[], text: string }}
  */
 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;
@@ -170,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) {
@@ -379,7 +384,7 @@ function orderCheck(device, sol, gross) {
         ? '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: compare with a long advance(), and please report the device.`,
+          : `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 },
   };
 }

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

@@ -355,8 +355,8 @@ export function normalizeDevice(def) {
   // A contact that passes nothing can't be driven by a current.
   for (const side of ['left', 'right']) {
     const ct = contacts[side];
-    const passes = ct.species.some((l) => l.type !== 'blocked') || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
+    const passes = ct.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0) || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
+    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked charged species, no gate)`);
     ct.passes = passes;
   }
   checkLevel(terminals.map((t) => t.drive), terminals.map((t) => (t.kind === 'port' ? ports[t.index] : contacts[t.side])));
@@ -889,7 +889,13 @@ function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, sur
     need(part.some((p) => p.side === 0 || p.side === 2), `${rpath}: no species of the port's region or its surface takes part`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
     need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
-    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
+    const alpha = transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare = rdef.bare === true;
+    // Langmuir sites: the reaction fills Δ of them going forward, and its transition state holds
+    // m bare ones (those it fills, or one if it runs only on bare metal), so the forward rate
+    // goes as θ₀^m and the backward as θ₀^(m−Δ): the prefactor's θ₀^(m(1−α)+(m−Δ)α), with each
+    // surface species at its coverage θ.
+    const fills = part.reduce((t, p) => t + (p.side === 2 ? p.nu : 0), 0), m = Math.max(fills, 0, bare ? 1 : 0);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha, bare, sites: m * (1 - alpha) + (m - fills) * alpha };
   });
 }
 
@@ -1316,7 +1322,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 */
 
@@ -179,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();
@@ -196,6 +201,7 @@ export class Device {
    * @returns {Solution}
    */
   step(dt, opts) {
+    options(opts, 'step', ['method']);
     return makeSolution(this.solver, this.solver.advance(dt, opts));
   }
 
@@ -211,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)
@@ -114,10 +115,10 @@ export function polarization(device, sol, where, V, opts = {}) {
   const out = parts.map(({ rx, k, base, s, q, pref, surf }) => {
     const rate = Float64Array.from(Vs, (v, j) => {
       const { lnA, bare } = at[j];
-      let a = base + s * v, p = pref * (rx.bare ? bare : 1);
+      let a = base + s * v, p = pref * (rx.sites ? powr(bare, rx.sites) : 1);
       for (const u of surf) {
         a -= u.nu * lnA[u.s];
-        p *= Math.exp(u.e * lnA[u.s]);
+        p *= Math.exp(u.e * lnA[u.s]) * powr(bare, u.e); // its coverage θ = θ₀ a
       }
       return rx.vmax ? p * -Math.expm1(-a) : p * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
     });

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)');

package/src/solution.js

@@ -87,7 +87,7 @@ export function makeSolution(solver, result = {}) {
   }
   solver._assembleBookkeeping(solver.lastDt);
   sol.contacts = {};
-  sol.gates = {};
+  sol.plates = {};
   for (const side of ['left', 'right']) {
     const ct = contacts[side];
     const flux = {};
@@ -107,7 +107,7 @@ export function makeSolution(solver, result = {}) {
     if (ct.phi.type === 'capacitive' || ct.phi.type === 'pinned') {
       // Charge on the gate (or metal) plate, per area if the device is planar: +D at the left, −D
       // at the right.
-      sol.gates[side] = { V, D, charge: side === 'left' ? D : -D };
+      sol.plates[side] = { V, D, charge: side === 'left' ? D : -D };
     }
   }
   sol.current = sol.contacts.right.current;
@@ -313,11 +313,24 @@ export function makeSolution(solver, result = {}) {
   // refined. Flag it where it lowers that capacitance by over 2%. (Where the box is the smaller
   // part, as an ε = 0 metal's against a semiconductor's depletion, it's a fine stand-in for the
   // metal's own screening.)
-  const boxed = (g, h, phi, other, where) => {
+  // And a reaction at the face sees that box's composition, which holding the charge σ shifts
+  // by about z·σ/(Cbox·V_T) for an ion of charge z: a Frumkin effect set by the mesh, which grows
+  // without limit as the box shrinks. Flag it past 1%.
+  const boxed = (g, h, phi, other, where, sigma = 0, reacting = []) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     if (mat.conductor || mat.epsr !== 0 || solver.phiUndefined?.[g]) return;
     const s2 = solver.screening(g), Cbox = (F * F * s2 * h) / (2 * RT);
     if (!(s2 > 0)) return;
+    const ion = reacting.filter((i) => species[i].z !== 0).reduce((a, i) => (a < 0 || Math.abs(species[i].z) > Math.abs(species[a].z) ? i : a), -1);
+    const shift = ion < 0 ? 0 : (Math.abs(species[ion].z * sigma) / Cbox) * (F / RT);
+    if (shift > 0.01) {
+      sol.warnings.push(
+        `${where}: the reaction here sees the strictly neutral cell beside the face (${h.toExponential(2)} m), which holds the face's charge as a diffuse layer that wide: ` +
+          `${species[ion].name} there is shifted by about ${(100 * shift).toPrecision(2)}%, a Frumkin effect set by the mesh that grows as the cell shrinks. ` +
+          `Set the face's zeroCharge near its rest potential (so it holds little charge), coarsen that cell to ${((200 * Math.abs(species[ion].z * sigma)) / (F * s2)).toExponential(1)} m or more, ` +
+          'or resolve the double layer (epsr > 0, hmin below the Debye length).',
+      );
+    }
     let C = phi.C;
     if (phi.type === 'pinned') {
       const om = other < 0 ? null : model.materials[model.regions[grid.nodeRegion[other]].material];
@@ -338,8 +351,10 @@ export function makeSolution(solver, result = {}) {
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
-    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`);
-    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`);
+    const reacting = (side) => itf.reactions.flatMap((rx) => rx.part.filter((p) => p.side === side).map((p) => p.i));
+    const sigma = sol.interfaces[f].D;
+    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`, sigma, reacting(0));
+    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
   if (resolves(contacts.left)) {