driftlet 0.5.0 → 0.7.0

package/src/junction.js

@@ -0,0 +1,164 @@
+// Liquid-junction potentials from formulas, for driftlet/kit: the diffusion potential φ_R − φ_L
+// between two neutral solutions, as the classical theories give it. A device simulates the actual
+// 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 { FARADAY, GAS_CONSTANT } from './constants.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+
+// The ions both solutions name, with their charge and diffusivity, and both concentrations.
+function prepare(left, right, ions, what) {
+  const names = [...new Set([...Object.keys(left), ...Object.keys(right)])];
+  return names.map((name) => {
+    const ion = ions[name];
+    if (!ion || !Number.isFinite(ion.z) || !(ion.D > 0)) fail(`${what}: no { z, D } for '${name}' in the ions given`);
+    const cL = left[name] ?? 0, cR = right[name] ?? 0;
+    if (!(cL >= 0 && cR >= 0)) fail(`${what}: concentrations must be ≥ 0 (mol/m³), got ${name} ${cL} and ${cR}`);
+    return { name, z: ion.z, D: ion.D, cL, cR };
+  });
+}
+function neutral(list, side, what) {
+  let q = 0, s = 0;
+  for (const p of list) {
+    q += p.z * p[side];
+    s += Math.abs(p.z * p[side]);
+  }
+  if (Math.abs(q) > 1e-9 * s) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution carries a net charge (Σ z·c = ${q.toPrecision(3)} mol/m³)`);
+}
+
+/**
+ * Henderson's liquid-junction potential, φ_R − φ_L (V): the junction taken to be the two solutions
+ * mixed in one proportion at every point (every ion's mixing fraction the same curve). Exact for a single binary salt, a close estimate otherwise (it's what
+ * JPCalc and most electrophysiology corrections use).
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @param {{ T?: number }} [opts] K (default 298.15)
+ */
+export function henderson(left, right, ions, { T = 298.15 } = {}) {
+  const list = prepare(left, right, ions, 'henderson');
+  neutral(list, 'cL', 'henderson');
+  neutral(list, 'cR', 'henderson');
+  let a = 0, b = 0, gL = 0, gR = 0;
+  for (const { z, D, cL, cR } of list) {
+    a += z * D * (cR - cL);
+    b += z * z * D * (cR - cL);
+    gL += z * z * D * cL;
+    gR += z * z * D * cR;
+  }
+  const VT = (GAS_CONSTANT * T) / FARADAY;
+  if (b === 0) return 0;
+  return (-VT * a * Math.log(gR / gL)) / b;
+}
+
+/**
+ * Planck's liquid-junction potential, φ_R − φ_L (V): the steady state of constrained diffusion,
+ * a junction zone held between the two solutions, electroneutral, carrying no current. Solved by
+ * shooting on the Nernst–Planck equations across it (its length drops out). Exact for that
+ * junction; equal to Henderson's for a single binary salt.
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @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 } = {}) {
+  const list = prepare(left, right, ions, 'planck');
+  neutral(list, 'cL', 'planck');
+  neutral(list, 'cR', 'planck');
+  const n = list.length, z = list.map((p) => p.z), D = list.map((p) => p.D), Dmax = Math.max(...D);
+  const scale = Math.max(...list.map((p) => Math.max(p.cL, p.cR)));
+  const cL = list.map((p) => p.cL / scale), cR = list.map((p) => p.cR / scale);
+  // Across the zone (x from 0 to 1, D's scale dropping out with its length), each ion's flux J_i is
+  // constant: c_i' = −J_i/D_i − z_i c_i ψ', with ψ = Fφ/RT, and neutrality fixes the field,
+  // ψ' = −Σ(z_i J_i/D_i)/Σ(z_i² c_i). Integrated from the left; the fluxes are chosen so the
+  // right comes out as given and no current flows.
+  const deriv = (c, J, out) => {
+    let num = 0, den = 0;
+    for (let i = 0; i < n; i++) {
+      num += (z[i] * J[i]) / D[i];
+      den += z[i] * z[i] * Math.max(c[i], 0);
+    }
+    const dpsi = -num / den;
+    for (let i = 0; i < n; i++) out[i] = -J[i] / D[i] - z[i] * c[i] * dpsi;
+    return dpsi;
+  };
+  const shoot = (J) => {
+    const c = cL.slice(), k1 = new Float64Array(n), k2 = new Float64Array(n), k3 = new Float64Array(n), k4 = new Float64Array(n), t = new Float64Array(n);
+    const h = 1 / steps;
+    let psi = 0;
+    for (let s = 0; s < steps; s++) {
+      const p1 = deriv(c, J, k1);
+      for (let i = 0; i < n; i++) t[i] = c[i] + (h / 2) * k1[i];
+      const p2 = deriv(t, J, k2);
+      for (let i = 0; i < n; i++) t[i] = c[i] + (h / 2) * k2[i];
+      const p3 = deriv(t, J, k3);
+      for (let i = 0; i < n; i++) t[i] = c[i] + h * k3[i];
+      const p4 = deriv(t, J, k4);
+      for (let i = 0; i < n; i++) c[i] += (h / 6) * (k1[i] + 2 * k2[i] + 2 * k3[i] + k4[i]);
+      psi += (h / 6) * (p1 + 2 * p2 + 2 * p3 + p4);
+    }
+    return { c, psi };
+  };
+  // Residuals: n − 1 ions reaching the right (the last follows by neutrality), and no current.
+  const residual = (J) => {
+    const { c, psi } = shoot(J), r = new Float64Array(n);
+    for (let i = 0; i < n - 1; i++) r[i] = c[i] - cR[i];
+    let I = 0;
+    for (let i = 0; i < n; i++) I += z[i] * J[i];
+    r[n - 1] = I / Dmax; // scaled like the concentrations
+    return { r, psi };
+  };
+  let J = list.map((_, i) => -D[i] * (cR[i] - cL[i])); // plain diffusion to start
+  let { r, psi } = residual(J);
+  for (let it = 0; it < 50; it++) {
+    const norm = Math.max(...r.map(Math.abs));
+    if (norm < 1e-12) break;
+    // Newton with a finite-difference Jacobian.
+    const Jac = [];
+    for (let k = 0; k < n; k++) {
+      const dJ = 1e-7 * Math.max(Math.abs(J[k]), 1e-3 * D[k]), Jp = J.slice();
+      Jp[k] += dJ;
+      const rp = residual(Jp).r;
+      Jac.push(Array.from(rp, (v, i) => (v - r[i]) / dJ));
+    }
+    const step = solveDense(Jac, r, n);
+    let lambda = 1, next;
+    for (;;) {
+      const Jn = J.map((v, k) => v - lambda * step[k]);
+      next = residual(Jn);
+      if (Math.max(...next.r.map(Math.abs)) < norm || lambda < 1e-3) {
+        J = Jn;
+        break;
+      }
+      lambda /= 2;
+    }
+    ({ r, psi } = next);
+  }
+  if (!(Math.max(...r.map(Math.abs)) < 1e-8)) fail('planck: the shooting did not converge');
+  return ((GAS_CONSTANT * T) / FARADAY) * psi;
+}
+
+// Solves Σ_k A[k][i] x_k = b_i (A given column by column), by Gaussian elimination with pivoting.
+function solveDense(cols, b, n) {
+  const M = Array.from({ length: n }, (_, i) => [...cols.map((col) => col[i]), b[i]]);
+  for (let p = 0; p < n; p++) {
+    let best = p;
+    for (let i = p + 1; i < n; i++) if (Math.abs(M[i][p]) > Math.abs(M[best][p])) best = i;
+    [M[p], M[best]] = [M[best], M[p]];
+    for (let i = p + 1; i < n; i++) {
+      const f = M[i][p] / M[p][p];
+      for (let j = p; j <= n; j++) M[i][j] -= f * M[p][j];
+    }
+  }
+  const x = new Array(n).fill(0);
+  for (let i = n - 1; i >= 0; i--) {
+    let s = M[i][n];
+    for (let j = i + 1; j < n; j++) s -= M[i][j] * x[j];
+    x[i] = s / M[i][i];
+  }
+  return x;
+}

package/src/kit.js

@@ -11,6 +11,10 @@ export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from './sources.js';
 export { describe, unitWarnings } from './describe.js';
+export { recorder } from './recorder.js';
+export { henderson, planck } from './junction.js';
+export { check } from './checks.js';
+export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from './devices.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
 
 const fail = (message) => {

package/src/recorder.js

@@ -0,0 +1,89 @@
+// A transient recorder, for driftlet/kit: advance() in pieces (a run to completion, or a little
+// 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';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+/**
+ * Record a device's transient. Frames are whole solutions: at the start, then at each of
+ * `times` (or every `every` seconds from the start), which `advance()` lands on exactly; with
+ * neither, at the end of each `advance()` call. The trace (`t`, `current`, `voltage`, and
+ * `probes` if given) runs from the start through every accepted step of every call.
+ * @param {import('./index.js').Device} device
+ * @param {{ every?: number, times?: number[], probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+ */
+export function recorder(device, opts = {}) {
+  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)');
+  if (times !== undefined && !(Array.isArray(times) && times.every(Number.isFinite))) fail('recorder: times must be an array of times (s)');
+  const first = device.solution();
+  const t0 = first.time;
+  const schedule = times ? [...times].filter((t) => t > t0).sort((a, b) => a - b) : null;
+  const scheduled = schedule !== null || every !== undefined;
+  let next = every !== undefined ? 1 : 0; // the next frame due: schedule[next], or t0 + next·every
+  const due = () => (schedule ? schedule[next] : every !== undefined ? t0 + next * every : undefined);
+
+  const trace = { t: [first.time], current: [first.current], voltage: [first.terminals.right.V - first.terminals.left.V] };
+  if (probes) trace.probes = device.solver._probes(probes).read().map((v) => [v]); // the start's readings
+  const frames = [first];
+
+  /**
+   * Advance to tEnd (s), stopping at each frame time on the way to keep a frame. Takes
+   * advance()'s options; with `budgetMs` it returns when that much wall time is spent, `done`
+   * saying whether tEnd was reached. Returns the latest solution (its own `trace` is only the
+   * last piece: the recorder's `trace` is the whole run).
+   * @param {number} tEnd
+   * @param {object} [aopts] as for Device.advance()
+   */
+  function advance(tEnd, aopts = {}) {
+    const start = now(), budget = aopts.budgetMs ?? Infinity;
+    let sol;
+    for (;;) {
+      const stop = due();
+      const target = stop !== undefined && stop < tEnd ? stop : tEnd;
+      const left = budget - (now() - start);
+      sol = device.advance(target, { ...aopts, ...(probes ? { probes } : {}), budgetMs: left > 0 ? left : 0 });
+      const tr = sol.trace;
+      for (let k = 0; k < tr.t.length; k++) {
+        trace.t.push(tr.t[k]);
+        trace.current.push(tr.current[k]);
+        trace.voltage.push(tr.voltage[k]);
+        if (probes) tr.probes.forEach((p, j) => trace.probes[j].push(p[k]));
+      }
+      if (!sol.converged || !sol.done) break;
+      if (target === stop) {
+        frames.push(sol);
+        next++;
+      }
+      if (target === tEnd) break;
+      if (now() - start > budget) {
+        sol.done = false;
+        break;
+      }
+    }
+    if (!scheduled && sol.converged && sol.time > frames.at(-1).time) frames.push(sol);
+    return sol;
+  }
+
+  /**
+   * The frame at or just before time t (the first frame before the start).
+   * @param {number} t
+   */
+  function frame(t) {
+    let lo = 0, hi = frames.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (frames[mid].time <= t) lo = mid;
+      else hi = mid - 1;
+    }
+    return frames[lo];
+  }
+
+  return { advance, frame, frames, trace };
+}

package/src/solution.js

@@ -27,6 +27,7 @@ export function makeSolution(solver, result = {}) {
     V: {},
     Vstd: {},
     time: solver.time,
+    steady: solver.atSteady,
     converged: result.converged ?? true,
     iterations: result.iterations ?? 0,
     steps: result.steps,
@@ -124,6 +125,23 @@ export function makeSolution(solver, result = {}) {
     return { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
   });
 
+  // Bulk reactions: each one's forward rate at every node (mol/(m³·s), NaN where it doesn't run),
+  // and integrated over each region and the device (mol/(m²·s)), by the nodes' control volumes,
+  // just as the balances count it.
+  sol.bulkReactions = solver.rxs.map((rx) => {
+    const rate = new Float64Array(nNodes).fill(NaN), regions = model.regions.map(() => 0);
+    let total = 0;
+    for (let g = 0; g < nNodes; g++) {
+      const m = solver.nodeMaterial[g];
+      if (!(rx.kf[m] > 0)) continue;
+      rate[g] = solver.bulkRate(rx, g);
+      const amount = grid.vol[g] * rate[g];
+      regions[grid.nodeRegion[g]] += amount;
+      total += amount;
+    }
+    return { rate, regions, total };
+  });
+
   // Total charge per area in the device (space charge plus sheet charges).
   let q = 0;
   for (let g = 0; g < nNodes; g++) {

package/src/solver.js

@@ -321,6 +321,7 @@ export class Solver {
     this.jR = new Float64Array(M);
     this.time = 0;
     this.lastDt = Infinity;
+    this.atSteady = false; // whether the state is a converged steady solve
     // Contact bookkeeping, filled by assemble(): particle flux toward +x through each contact,
     // and the displacement there (the metal's surface charge for a neutral link).
     this.contactFlux = { left: new Float64Array(n), right: new Float64Array(n) };
@@ -802,6 +803,7 @@ export class Solver {
   // After the terminals' drives change (Device.set): which are floating, and the held values. A
   // change of source is a discontinuity, so time stepping restarts its order.
   redrive() {
+    this.atSteady = false;
     const before = this.floating;
     this.floating = this.terms.flatMap((t, k) => (t.drive.kind === 'I' || t.drive.R > 0 ? [k] : []));
     if (this.floating.length !== before.length) this.deltaV = null;
@@ -993,6 +995,22 @@ export class Solver {
         }
       }
     }
+    // A floating contact facing a held one starts where the start's own composition puts it: the
+    // held voltage plus the difference between the two terminal species' levels beside each
+    // contact (c0 sets them, and φ was chosen for neutrality, not to match either contact), so
+    // that a transient's first reading means something.
+    const level = (side) => {
+      const ct = model.contacts[side], i = ct.terminal;
+      if (i === null || ct.species[i].type !== 'equilibrium' || z[i] === 0) return NaN;
+      const b = this.blockOfNode[side === 'left' ? 0 : grid.nNodes - 1];
+      return (this.VT * u[b * M + 1 + i]) / z[i] - ct.species[i].offset;
+    };
+    for (const k of this.floating) {
+      const t = this.terms[k], held = k === 0 ? 1 : 0;
+      if (t.kind === 'port' || held >= this.terms.length || this.floating.includes(held)) continue;
+      const shift = level(t.side) - level(this.terms[held].side);
+      if (Number.isFinite(shift)) this.termV[k] = this.termV[held] + shift;
+    }
     this.computeConcentrations();
   }
 
@@ -1536,6 +1554,27 @@ export class Solver {
         res[R[o]] = -deta; // μ̄ continuous
         this._j(bf, r, bR, r, 1);
         this._j(bf, r, bL, r, -1);
+      } else if (type === 'permeability') {
+        // Electrodiffusion through a thin membrane in a constant field: Scharfetter–Gummel across
+        // the face with D/h → P, its drift taken over the face's whole jump in the standard level
+        // zφ̂ + μ°/RT − ln c_ref (the φ jump of a capacitive face, and any step between the two
+        // materials). Between like solutions it's Goldman–Hodgkin–Katz's flux,
+        //   N = P·zu·(c_L − c_R e^{zu})/(e^{zu} − 1),  u = (φ_R − φ_L)/V_T,
+        // and it's exactly zero where μ̄ is level.
+        const gl = grid.regionEnd[f], gr = gl + 1, kl = gl * n + i, kr = gr * n + i, zi = z[i], P = itf.links[i].P;
+        const shift = this.mu0hat[kr] - this.mu0hat[kl] - Math.log(this.cRef[kr] / this.cRef[kl]);
+        const d = zi * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M])) + shift;
+        const E = Math.expm1(-deta); // η_R − η_L
+        const gBc = P * bernoulli(d) * this.c[kl];
+        const dNdd = -P * bernoulliDerivative(d) * this.c[kl] * E;
+        res[R[o]] = u[o] + gBc * E;
+        this._j(bf, r, bf, r, 1);
+        this._j(bf, r, bL, r, -gBc);
+        this._j(bf, r, bR, r, gBc * (E + 1));
+        if (zi !== 0) {
+          this._j(bf, r, bL, 0, zi * dNdd - zi * gBc * E);
+          this._j(bf, r, bR, 0, -zi * dNdd);
+        }
       } else {
         // conductance: J = G (V_L − V_R), V = V_T η / z  ⇒  N = G V_T (η_L − η_R) / (z² F)
         const gG = (itf.links[i].G * VT) / (z[i] * z[i] * F);
@@ -1715,6 +1754,34 @@ export class Solver {
     d[0] = -this._Kz(g, k);
   }
 
+  // A bulk reaction's rate at node g (mol/(m³·s), forward), as assembled: for the solution.
+  bulkRate(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    let aHi = rx.fixedA, aLo = 0;
+    for (let p = 0; p < rx.sp.length; p++) {
+      aHi += rx.nu[p] * u[b * M + 1 + rx.sp[p]];
+      aLo += rx.nu[p] * uLo[b * M + 1 + rx.sp[p]];
+    }
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], aHi + aLo).rate;
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P * -Math.expm1(-(aHi + aLo));
+  }
+
+  // The larger of a bulk reaction's two one-way rates at node g (mol/(m³·s)): the scale its net
+  // rate is read against (in equilibrium the net rate is their round-off).
+  bulkOneWay(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    let a = rx.fixedA;
+    for (let p = 0; p < rx.sp.length; p++) a += rx.nu[p] * (u[b * M + 1 + rx.sp[p]] + uLo[b * M + 1 + rx.sp[p]]);
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], a).oneWay;
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P * Math.max(1, Math.exp(-a));
+  }
+
   // SRH kinetics (see srhLaw in device.js): the rate, and its sensitivities to ln n, ln p and
   // a = A/RT. With no n₁ given, the trap is midgap: n₁ = p₁ = n_i = √(n p e^{−a}).
   _srhRate(law, cn, cp, a) {
@@ -1731,7 +1798,7 @@ export class Solver {
     const dDn = tp * cn + tp * n1 * kN + tn * p1 * (1 - kN);
     const dDp = tp * n1 * kP + tn * cp + tn * p1 * (1 - kP);
     const dDa = tp * n1 * kA + tn * p1 * (-1 - kA);
-    return { rate, Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
+    return { rate, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
   }
 
   // A face reaction (see normalizeFaceReactions). Its rate r_k is an unknown of the face block,
@@ -1750,12 +1817,28 @@ export class Solver {
       const g = p.side ? gR : gL, b = p.side ? bR : bL, o = b * M + 1 + p.i;
       aHi -= p.nu * u[o];
       aLo -= p.nu * uLo[o];
-      if (rx.srh || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
+      if (rx.srh || rx.vmax || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
       pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
     }
-    if (rx.srh) {
+    if (rx.vmax) {
+      // Saturating: r = vmax Π (c/(c + K))^{|ν|} (1 − e^{−a}); ∂ln S/∂ln c = |ν| K/(c + K).
+      let S = 1;
+      rx.part.forEach((p, q) => {
+        if (p.nu >= 0) return;
+        const g = p.side ? gR : gL, cc = c[g * n + p.i], K = rx.K[q];
+        S *= powi(cc / (cc + K), -p.nu);
+        this._dlnc(g, p.i, (-p.nu * K) / (cc + K), p.side ? dR : dL);
+      });
+      const a = aHi + aLo, back = Math.exp(-a);
+      rate = rx.vmax * S * -Math.expm1(-a);
+      for (let s = 0; s < M; s++) {
+        dL[s] *= rate;
+        dR[s] *= rate;
+      }
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= rx.vmax * S * back * p.nu;
+    } else if (rx.srh) {
       // SRH, with n and p each at its own side's edge node.
       const { n: pn, p: pp } = rx.srh, gn = pn.side ? gR : gL, gq = pp.side ? gR : gL;
       const s = this._srhRate(rx.srh, c[gn * n + pn.i], c[gq * n + pp.i], aHi + aLo);
@@ -2171,6 +2254,7 @@ export class Solver {
    * the start-of-step values, and dt/a0 replaces dt.
    */
   step(dt, opts = {}) {
+    this.atSteady = false;
     const prev = this.history[0];
     const w = prev ? dt / prev.dt : 0;
     const bdf = opts.method === 'bdf2' && prev !== undefined && w <= 2;
@@ -2416,10 +2500,10 @@ export class Solver {
     if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }');
     const plan = probes.map((p, k) => {
       const path = `advance: probes[${k}]`;
-      const i = species.findIndex((sp) => sp.name === p?.species);
-      if (i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
-      const quantity = p.quantity ?? 'c';
-      if (quantity !== 'c' && quantity !== 'V') fail(`${path}.quantity must be 'c' (mol/m³) or 'V' (the species voltage)`);
+      const quantity = p?.quantity ?? 'c';
+      if (quantity !== 'c' && quantity !== 'V' && quantity !== 'phi') fail(`${path}.quantity must be 'c' (mol/m³), 'V' (the species voltage) or 'phi' (φ, V)`);
+      const i = quantity === 'phi' ? -1 : species.findIndex((sp) => sp.name === p?.species);
+      if (quantity !== 'phi' && i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
       if (quantity === 'V' && species[i].z === 0) fail(`${path}: '${p.species}' is neutral, so it has no voltage; read 'c'`);
       const x = grid.x, inside = (r) => p.x >= x[grid.regionStart[r]] && p.x <= x[grid.regionEnd[r]];
       let r;
@@ -2439,6 +2523,7 @@ export class Solver {
     const out = plan.map(() => []);
     const { n, M } = this;
     const at = (q, g) => {
+      if (q.quantity === 'phi') return this.phiUndefined[g] ? NaN : this.VT * (this.u[this.blockOfNode[g] * M] + this.uLo[this.blockOfNode[g] * M]);
       if (!this.present[g * n + q.i]) return NaN;
       if (q.quantity === 'c') return this.c[g * n + q.i];
       const o = this.blockOfNode[g] * M + 1 + q.i;
@@ -2465,6 +2550,39 @@ export class Solver {
     return mx;
   }
 
+  // Start from another solver's state for the same device on another grid (a refined one): each
+  // node's unknowns interpolated linearly in x within its region, each face's copied, and the
+  // terminals' voltages. A warm start for a steady solve; nothing else is carried over.
+  _warmFrom(src) {
+    const { M, u, uLo } = this, grid = this.model.grid, sg = src.model.grid;
+    if (src.M !== M || sg.regionStart.length !== grid.regionStart.length) throw new Error('_warmFrom: a different device');
+    const value = (b, k) => src.u[b * M + k] + src.uLo[b * M + k];
+    for (let r = 0; r < grid.regionStart.length; r++) {
+      let a = sg.regionStart[r];
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const x = grid.x[g];
+        while (a + 1 < sg.regionEnd[r] && sg.x[a + 1] < x) a++;
+        const b = Math.min(a + 1, sg.regionEnd[r]), h = sg.x[b] - sg.x[a];
+        const w = h > 0 ? Math.min(1, Math.max(0, (x - sg.x[a]) / h)) : 0;
+        const ba = src.blockOfNode[a], bb = src.blockOfNode[b], bg = this.blockOfNode[g];
+        for (let k = 0; k < M; k++) {
+          u[bg * M + k] = (1 - w) * value(ba, k) + w * value(bb, k);
+          uLo[bg * M + k] = 0;
+        }
+      }
+    }
+    for (let f = 0; f < this.nFaces; f++) {
+      for (let k = 0; k < M; k++) {
+        u[this.blockOfFace[f] * M + k] = value(src.blockOfFace[f], k);
+        uLo[this.blockOfFace[f] * M + k] = 0;
+      }
+    }
+    this.termV.set(src.termV);
+    this.solvedV = src.solvedV;
+    this.time = src.time;
+    this.computeConcentrations();
+  }
+
   _snapshot() {
     return {
       u: Float64Array.from(this.u),
@@ -2472,6 +2590,7 @@ export class Solver {
       cOld: Float64Array.from(this.cOld),
       time: this.time,
       lastDt: this.lastDt,
+      atSteady: this.atSteady,
       contactDStart: this.contactDStart,
       contactDOld: this.contactDOld,
       contactDEnd: this.contactDEnd,
@@ -2488,6 +2607,7 @@ export class Solver {
     this.cOld.set(s.cOld);
     this.time = s.time;
     this.lastDt = s.lastDt;
+    this.atSteady = s.atSteady;
     this.contactDStart = s.contactDStart;
     this.contactDOld = s.contactDOld;
     this.contactDEnd = s.contactDEnd;
@@ -2863,7 +2983,15 @@ export class Solver {
    * If Newton fails, dt ramps up from a small value (pseudo-transient continuation) instead.
    * The clock is not advanced, and open-system conservation bookkeeping restarts here.
    */
+  // Steady state from the present one; `atSteady` says whether the state is one (until a step or
+  // a change of drive).
   solveSteady(opts = {}) {
+    const r = this._steadyFromHere(opts);
+    this.atSteady = r.converged;
+    return r;
+  }
+
+  _steadyFromHere(opts) {
     this.conditioning = null;
     this.computeConcentrations();
     this._captureLocal(); // immobile combinations keep, node by node, what they hold now

package/src/stack.js

@@ -59,7 +59,7 @@ export function layer(material, length, more = {}) {
 
 // A drive: a number is a held voltage, a waveform { t, values } a voltage waveform, and an
 // object with V, I or R is the drive itself.
-function drive(d, path) {
+export function drive(d, path) {
   if (d === undefined) return { V: 0 };
   if (typeof d === 'number') return { V: d };
   if (isObject(d) && Array.isArray(d.t)) return { V: d };

package/src/types.js

@@ -201,7 +201,9 @@
  * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number }[]} ports what each
  *   internal port brings into the device
- * @property {{ dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
+ * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
+ * @property {{ rate: Float64Array, regions: number[], total: number }[]} bulkReactions each bulk reaction's
+ *   forward rate per node (mol/(m³·s), NaN where it doesn't run), and per region and in all (mol/(m²·s))
  * @property {number} charge total charge in the device, C/m²
  * @property {{ species: string, regions: number[], spectator: boolean, connected: boolean, reactive: boolean,
  *   amount: number, reference: number, intake: number, drift: number }[]} conservation
@@ -209,6 +211,7 @@
  * @property {boolean} converged
  * @property {number} iterations
  * @property {number} time s
+ * @property {boolean} steady whether this is a converged steady state (solve()), not a transient's
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
  * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] advance():

package/types/checks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {object} CheckItem
+ * @property {string} name what was checked: 'converged', 'warnings', 'balance', 'conservation' or 'grid'
+ * @property {boolean | null} ok whether it passed (null: look at it, a warning or a check that
+ *   couldn't be made)
+ * @property {string} summary one line
+ * @property {object} [details] the numbers behind it
+ */
+/**
+ * Check a device's present state (pass the solution solve() or advance() returned, for its
+ * convergence and warnings):
+ * - **converged**: the last solve converged.
+ * - **warnings**: the solution's warnings (unresolved double layers, steep profiles, weakly held
+ *   parts) and the definition's likely unit slips.
+ * - **balance** (a steady state): each species' ledger, what comes in through each terminal and
+ *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) and, for a charged
+ *   species, as a current F·|z|·rate. The terms must sum to 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.
+ * - **grid** (a steady state, with `refine`, the default): 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
+ *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
+ *   wants less). The discretisation is second order, so the change estimates this grid's error
+ *   (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]
+ * 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: import("./index.js").Device, sol?: object, { refine, tol }?: {
+    refine?: boolean;
+    tol?: number;
+}): {
+    ok: boolean;
+    items: CheckItem[];
+    text: string;
+};
+export type CheckItem = {
+    /**
+     * what was checked: 'converged', 'warnings', 'balance', 'conservation' or 'grid'
+     */
+    name: string;
+    /**
+     * whether it passed (null: look at it, a warning or a check that
+     * couldn't be made)
+     */
+    ok: boolean | null;
+    /**
+     * one line
+     */
+    summary: string;
+    /**
+     * the numbers behind it
+     */
+    details?: object;
+};