driftlet 0.16.4 → 1.0.0

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

@@ -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 */
 
@@ -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)

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)) {

package/src/solver.js

@@ -1905,6 +1905,22 @@ export class Solver {
       });
       if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
     }
+    // A floating port linked to its carrier (no reactions, no double layer: a wire into an
+    // insertion host) starts at that carrier's level across its window, not at 0 V.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      const i = port?.terminal, link = i === null || i === undefined ? null : port.species[i];
+      if (!port || port.reactions.length > 0 || port.capacitance || !link || link.type === 'blocked' || z[i] === 0) continue;
+      let w = 0, sum = 0;
+      port.nodes.forEach((g, j) => {
+        const a = this.model.grid.vol[g] * (this.portArea[t.index]?.[j] ?? 1); // (a window with no area: by volume)
+        w += a;
+        sum += (a * this.VT * u[this.blockOfNode[g] * M + 1 + i]) / z[i];
+      });
+      // (Levels at the start mean something only against a held terminal's, as for a contact.)
+      const held = [0, 1].find((h) => !this.floating.includes(h) && Number.isFinite(level(this.terms[h].side)));
+      if (w > 0 && held !== undefined) this.termV[k] = this.termV[held] + sum / w - (link.offset ?? 0) - level(this.terms[held].side);
+    }
     // Gates start open as far as the starting voltage across their face holds them, α/(α + β).
     for (const gt of this.gateList) {
       const { gate, o } = gt, V = this._gateVoltage(gt), a = gateRate(gate.alpha, V)[0], b = gateRate(gate.beta, V)[0];
@@ -3967,8 +3983,12 @@ export class Solver {
     const trace = { t: [], current: [], voltage: [], ...(sample ? { probes: sample.out } : {}) };
     let steps = 0, rejected = 0, iterations = 0, failed = false;
     // Already there (an animation frame with no time to add): nothing to do, and the step size
-    // carried to the next call stays as it was.
-    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace };
+    // carried to the next call stays as it was. A time already passed, or reached again outside
+    // an animation, is most likely advance(dt) read as a duration: say so.
+    if (!(tEnd > this.time)) {
+      const relative = tEnd < this.time || (this.time > 0 && opts.budgetMs === undefined);
+      return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace, ...(relative ? { stopped: `advance(${tEnd}) did nothing: ${absolute}. To run for a further dt, advance(sol.time + dt)` } : {}) };
+    }
     const t0 = this.time;
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;

package/src/sources.js

@@ -1,7 +1,7 @@
 // driftlet/kit: sources as plain definition data. Waveforms for a terminal's V or I, an injector
 // port, and band-to-band recombination from a lifetime. Each returns an ordinary spec value.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -19,6 +19,7 @@ const num = (v) => typeof v === 'number' && Number.isFinite(v);
  * @returns {{ t: number[], values: number[] }}
  */
 export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {}) {
+  checkOptions('pulse', arguments[0], ['start', 'width', 'amplitude', 'rise', 'base']);
   need(num(width) && width > 0, `pulse: width must be > 0 (s), got ${width}`);
   need(num(amplitude), `pulse: amplitude must be a finite number (V or A/m²), got ${amplitude}`);
   need(num(start) && start >= 0, `pulse: start must be ≥ 0 (s), got ${start}`);
@@ -35,6 +36,7 @@ export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {})
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function square({ high, low, period, duty = 0.5 } = {}) {
+  checkOptions('square', arguments[0], ['high', 'low', 'period', 'duty']);
   need(num(high) && num(low), `square: high and low must be finite numbers, got ${high} and ${low}`);
   need(num(period) && period > 0, `square: period must be > 0 (s), got ${period}`);
   need(num(duty) && duty > 0 && duty < 1, `square: duty must be between 0 and 1, got ${duty}`);
@@ -49,6 +51,7 @@ export function square({ high, low, period, duty = 0.5 } = {}) {
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function triangle({ from, to, period } = {}) {
+  checkOptions('triangle', arguments[0], ['from', 'to', 'period']);
   need(num(from) && num(to), `triangle: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(period) && period > 0, `triangle: period must be > 0 (s), got ${period}`);
   return { t: [0, period / 2, period], values: [from, to, from], repeat: true };
@@ -60,6 +63,7 @@ export function triangle({ from, to, period } = {}) {
  * @returns {{ t: number[], values: number[] }}
  */
 export function ramp({ from, to, duration, start = 0 } = {}) {
+  checkOptions('ramp', arguments[0], ['from', 'to', 'duration', 'start']);
   need(num(from) && num(to), `ramp: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(duration) && duration > 0, `ramp: duration must be > 0 (s), got ${duration}`);
   need(num(start) && start >= 0, `ramp: start must be ≥ 0 (s), got ${start}`);
@@ -78,6 +82,7 @@ export function ramp({ from, to, duration, start = 0 } = {}) {
  * @returns {object} a port, for the definition's `ports`
  */
 export function injector({ name = 'injector', region, from, to, species, I, headroom = 2.5 } = {}) {
+  checkOptions('injector', arguments[0], ['name', 'region', 'from', 'to', 'species', 'I', 'headroom']);
   need(region !== undefined, 'injector: give the region (its name or index)');
   need(num(from) && num(to) && to > from, `injector: from and to must bound the window, in m from the region's left end (got ${from}, ${to})`);
   need(typeof species === 'string', 'injector: give the species it injects, e.g. species: \'h+\'');
@@ -96,6 +101,7 @@ export function injector({ name = 'injector', region, from, to, species, I, head
  * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
  */
 export function recombination({ material, tau, majority } = {}) {
+  checkOptions('recombination', arguments[0], ['material', 'tau', 'majority']);
   need(typeof material === 'string', 'recombination: give the material, by name');
   need(num(tau) && tau > 0, `recombination: tau must be > 0 (s), got ${tau}`);
   need(num(majority) && majority > 0, `recombination: majority must be the majority carrier density > 0 (mol/m³; units.perCm3 converts), got ${majority}`);
@@ -117,6 +123,7 @@ export function recombination({ material, tau, majority } = {}) {
  * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
  */
 export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes = 'e- + h+' } = {}) {
+  checkOptions('photogeneration', arguments[0], ['material', 'flux', 'alpha', 'mu', 'from', 'to', 'makes']);
   need(typeof material === 'string', 'photogeneration: give the material, by name');
   need(num(flux) && flux >= 0, `photogeneration: flux must be the photon flux ≥ 0 entering the material (mol/(m²·s)), got ${flux}`);
   need(num(alpha) && alpha > 0, `photogeneration: alpha must be the absorption coefficient > 0 (1/m; 1/cm × 100), got ${alpha}`);

package/src/stack.js

@@ -4,7 +4,7 @@
 // that you didn't write: it only moves things to where the definition keeps them, and converts
 // the kit's doping shorthand (donors and acceptors).
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -158,8 +158,21 @@ export function build(def) {
   }
   if (pendingFace) fail(`${at(pendingFace.k)}: a face after the last layer (the contact is the boundary there)`);
   if (regions.length === 0) fail('build.stack has no layers');
+  // A contact holding a carrier its layer lacks: most often ohmic()'s default on a metal.
+  for (const [k, end] of [[0, regions[0]], [stack.length - 1, regions[regions.length - 1]]]) {
+    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked') : [];
+    const mat = materials[end.material];
+    if (!isObject(mat)) continue;
+    const has = (s) => (isObject(mat.conductor) ? mat.conductor.species === s : isObject(mat.species) && mat.species[s] !== undefined);
+    const lacks = held.filter((s) => !has(s));
+    if (lacks.length === 0) continue;
+    const kept = held.filter(has);
+    const hint = stack[k].phi === 'bulk' && kept.length > 0 ? `: write ohmic(V, [${kept.map((s) => `'${s}'`).join(', ')}]) (ohmic() holds e- and h+ unless told${isObject(mat.conductor) ? '; a metal has only its carrier' : ''})` : '';
+    fail(`${at(k)}: the contact holds ${lacks.map((s) => `'${s}'`).join(' and ')}, which its layer's material '${end.material}' doesn't have${hint}`);
+  }
 
   function region(item, path) {
+    checkOptions(path, item, ['name', 'material', 'length', 'fixedCharge', 'c0', 'velocity', 'mixing', 'grid', 'donors', 'acceptors']);
     const { donors, acceptors, ...r } = item;
     if (donors !== undefined || acceptors !== undefined) {
       if (r.fixedCharge !== undefined) fail(`${path}: give doping as donors and acceptors, or fixedCharge, not both`);

package/src/statistics.js

@@ -157,7 +157,7 @@ function tableOccupancy(xs, zs, fail) {
     const x = k / 4000;
     const q = r(x);
     if (x > 0 && x < 1 && !(1 + x * (1 - x) * q.d > 1e-9)) {
-      fail(`ocv: the interpolated curve isn't monotone near x = ${x.toFixed(3)} (E must fall steadily with x; add points or smooth the data)`);
+      fail(`ocv: near x = ${x.toFixed(3)} the curve is flat or rising against the ideal-solution slope, (RT/F) ln(x/(1−x)), as on a two-phase plateau (not supported): more points alone won't help; give it some of that slope, adding −a (RT/F) ln(x/(1−x)) to E (a = 0.1 passes at points 0.01 apart, less with points closer near the ends; docs/statistics.md)`);
     }
     rmin = Math.min(rmin, q.v);
     rmax = Math.max(rmax, q.v);

package/src/traces.js

@@ -3,6 +3,7 @@
 // range. Plain data, for any plotting toolkit (driftlet/plot draws it as SVG).
 
 import { level } from './equation.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const finite = (a) => {
   for (let k = 0; k < a.length; k++) if (Number.isFinite(a[k])) return true;
@@ -78,6 +79,8 @@ export function typeset(name, z) {
  *   faces: number[], range: [number, number] }}
  */
 export function traces(sol, { species, standard = true, phi = false, energy = false, levels = [], labels = {}, shifts = {} } = {}) {
+  checkOptions('traces', arguments[1], ['species', 'standard', 'phi', 'energy', 'levels', 'labels', 'shifts']);
+  if (!Array.isArray(levels)) throw new DeviceError("traces: levels must be a list, [{ half }, …], of the half-reactions whose levels to draw");
   const names = Object.keys(sol.V);
   const role = (name) => speciesRole(sol, name).role;
   const slotOf = (name) => speciesRole(sol, name).slot;