driftlet 0.5.0 → 0.6.0

package/src/devices.js

@@ -0,0 +1,135 @@
+// Curated devices, for driftlet/kit: whole definitions from a published parameter set (light and
+// contacts included), with reference results from an independent code to check a run against.
+// Each returns ordinary definition data, to print, edit and pass to new Device.
+
+import { AVOGADRO, FARADAY, GAS_CONSTANT, units } from './constants.js';
+import { photogeneration } from './sources.js';
+import { drive } from './stack.js';
+
+const m3 = (x) => x / AVOGADRO, eV = units.eV;
+
+// IonMonger's default parameters (parameters_template.m, IonMonger 2.0): Courtier, Cave, Walker,
+// Richardson & Foster, J. Comput. Electron. 18, 1435 (2019). Levels in eV on the vacuum scale,
+// densities per m³, D in m²/s, lifetimes in s, recombination velocities in m/s.
+const P = {
+  T: 298, b: 400e-9, eps: 24.1, alpha: 1.3e7, Ec: -3.7, Ev: -5.4, Dn: 1.7e-4, Dp: 1.7e-4, gc: 8.1e24, gv: 5.8e24,
+  N0: 1.6e25, DIinf: 6.5e-8, EAI: 0.58, // vacancy D = DIinf·exp(−EAI/kT), ≈ 1.0e-17 m²/s at 298 K
+  dE: 1e24, gcE: 5e25, EcE: -4.0, bE: 100e-9, epsE: 10, DE: 1e-5,
+  dH: 1e24, gvH: 5e25, EvH: -5.1, bH: 200e-9, epsH: 3, DH: 1e-6,
+  tn: 3e-9, tp: 3e-7, vnE: 1e5, vpE: 10, vnH: 0.1, vpH: 1e5, Fph: 1.4e21,
+};
+
+/**
+ * IonMonger's default planar perovskite solar cell: TiO₂ (100 nm) | MAPbI₃ (400 nm) with mobile
+ * iodide vacancies over an equal immobile background | spiro-OMeTAD (200 nm), at 298 K, lit
+ * through the TiO₂. Species e⁻, h⁺ and the vacancies 'V+'. Recombination is SRH at both faces
+ * (IonMonger's interface law is driftlet's face SRH, with n₁ from the TiO₂'s electron density)
+ * and, with `bulkSRH`, SRH through midgap traps in the perovskite (τₙ = 3 ns, τₚ = 300 ns).
+ * Light is 1.4e21 photons/(m²·s) at α = 1.3e7 /m (IonMonger's one sun), times `light`. The left
+ * contact is the TiO₂'s, at 0 V; the right is the spiro's, at `V`, so photocurrent is positive.
+ *
+ * `PEROVSKITE_SCANS` holds IonMonger's own results for this cell, scan by scan.
+ * @param {{ V?: import('./types.js').Source | { V?: import('./types.js').Source, I?: import('./types.js').Source, R?: number }, light?: number, bulkSRH?: boolean }} [opts]
+ * @returns {import('./types.js').DeviceDefinition}
+ */
+export function perovskiteCell({ V = 1.2, light = 1, bulkSRH = true } = {}) {
+  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
+  const DI = P.DIinf * Math.exp(-P.EAI / VT);
+  return {
+    T,
+    species: [
+      { name: 'e-', z: -1 },
+      { name: 'h+', z: 1 },
+      { name: 'V+', z: 1 }, // iodide vacancies
+    ],
+    materials: {
+      // Levels on the vacuum scale: μ° is the band edge's depth (minus it, for electrons).
+      'TiO₂': { epsr: P.epsE, species: { 'e-': { D: P.DE, mu0: eV(P.EcE), cRef: m3(P.gcE) } } },
+      'MAPbI₃': {
+        epsr: P.eps,
+        species: {
+          'e-': { D: P.Dn, mu0: eV(P.Ec), cRef: m3(P.gc) },
+          'h+': { D: P.Dp, mu0: eV(-P.Ev), cRef: m3(P.gv) },
+          'V+': { D: DI, mu0: 0, cRef: m3(P.N0) },
+        },
+      },
+      'spiro-OMeTAD': { epsr: P.epsH, species: { 'h+': { D: P.DH, mu0: eV(-P.EvH), cRef: m3(P.gvH) } } },
+    },
+    regions: [
+      { material: 'TiO₂', length: P.bE, fixedCharge: FARADAY * m3(P.dE) },
+      { material: 'MAPbI₃', length: P.b, fixedCharge: -FARADAY * m3(P.N0), c0: { 'V+': m3(P.N0) } },
+      { material: 'spiro-OMeTAD', length: P.bH, fixedCharge: -FARADAY * m3(P.dH) },
+    ],
+    interfaces: [
+      // Recombination through interface states (SRH), saturating at one carrier's capture: holes
+      // reaching the TiO₂ recombine at v_p however many electrons wait there.
+      { dipole: 0, species: { 'e-': 'equilibrium' }, reactions: [{ equation: 'e-(left) + h+ = 0', srh: { vn: P.vnE, vp: P.vpE, n1: m3((P.dE / n0) * ni) } }] },
+      { dipole: 0, species: { 'h+': 'equilibrium' }, reactions: [{ equation: 'e- + h+(right) = 0', srh: { vn: P.vnH, vp: P.vpH, n1: m3(ni) } }] },
+    ],
+    contacts: {
+      left: { V: 0, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'bulk' },
+      right: { ...drive(V, 'perovskiteCell: V'), terminal: 'h+', species: { 'h+': 'equilibrium' }, phi: 'bulk' },
+    },
+    bulkReactions: [
+      ...(bulkSRH ? [{ equation: 'e- + h+ = 0', srh: { 'MAPbI₃': { tauN: P.tn, tauP: P.tp } } }] : []),
+      ...(light > 0 ? [photogeneration({ material: 'MAPbI₃', flux: m3(P.Fph * light), alpha: P.alpha, mu: eV(3), from: P.bE, to: P.bE + P.b })] : []),
+    ],
+    grid: { hmin: 0.05e-9, hmax: 5e-9, ratio: 1.15 },
+  };
+}
+
+/**
+ * IonMonger's J–V scans of `perovskiteCell()` (IonMonger 2.0, commit 1ae4f9e, run in GNU Octave):
+ * steady state at 1.2 V under light, then 1.2 → 0 → 1.2 V at `rate` (V/s). `full` is the cell
+ * as given (bulk SRH on); `noBulkSRH` is `perovskiteCell({ bulkSRH: false })`. Per scan: J0, the
+ * current at 0 V (A/m²); each sweep's maximum power Pmax (W/m², the largest V·J among IonMonger's
+ * 201 output points per loop) and Voc (V, interpolated); and the hysteresis index
+ * hi = (Pmax,rev − Pmax,fwd)/Pmax,rev. `hysteresis()` reads the same from a run's trace.
+ * driftlet reproduces these to 0.15 % in hi, 0.5 W/m² in Pmax and 2 mV in Voc (its test suite).
+ */
+export const PEROVSKITE_SCANS = Object.freeze({
+  source: 'IonMonger 2.0 (github.com/PerovskiteSCModelling/IonMonger, commit 1ae4f9e), default parameters',
+  full: [
+    { rate: 0.001, J0: 220.66, rev: { Pmax: 201.95, Voc: 1.09296 }, fwd: { Pmax: 200.42, Voc: 1.08517 }, hi: 0.00756 },
+    { rate: 0.01, J0: 220.89, rev: { Pmax: 210.97, Voc: 1.11157 }, fwd: { Pmax: 195.18, Voc: 1.06566 }, hi: 0.07483 },
+    { rate: 0.1, J0: 222.28, rev: { Pmax: 216.46, Voc: 1.11698 }, fwd: { Pmax: 144.85, Voc: 1.01277 }, hi: 0.33083 },
+    { rate: 1, J0: 223.01, rev: { Pmax: 217.02, Voc: 1.11712 }, fwd: { Pmax: 210.91, Voc: 1.08238 }, hi: 0.02815 },
+    { rate: 10, J0: 223.01, rev: { Pmax: 217.04, Voc: 1.11708 }, fwd: { Pmax: 216.55, Voc: 1.11509 }, hi: 0.00225 },
+    { rate: 100, J0: 223.06, rev: { Pmax: 217.09, Voc: 1.11708 }, fwd: { Pmax: 216.93, Voc: 1.11693 }, hi: 0.0007 },
+    { rate: 1000, J0: 223.54, rev: { Pmax: 217.58, Voc: 1.11714 }, fwd: { Pmax: 216.48, Voc: 1.11699 }, hi: 0.00505 },
+  ],
+  noBulkSRH: [
+    { rate: 0.001, J0: 220.96, rev: { Pmax: 203.06, Voc: 1.0957 }, fwd: { Pmax: 201.54, Voc: 1.08762 }, hi: 0.00751 },
+    { rate: 0.01, J0: 221.17, rev: { Pmax: 214.35, Voc: 1.1168 }, fwd: { Pmax: 196.01, Voc: 1.06737 }, hi: 0.08556 },
+    { rate: 0.1, J0: 222.43, rev: { Pmax: 221.67, Voc: 1.12199 }, fwd: { Pmax: 145.73, Voc: 1.01331 }, hi: 0.3426 },
+    { rate: 1, J0: 223.02, rev: { Pmax: 222.39, Voc: 1.12257 }, fwd: { Pmax: 213.41, Voc: 1.08376 }, hi: 0.04038 },
+    { rate: 10, J0: 223.02, rev: { Pmax: 222.54, Voc: 1.12263 }, fwd: { Pmax: 221.77, Voc: 1.11951 }, hi: 0.00348 },
+    { rate: 100, J0: 223.07, rev: { Pmax: 222.61, Voc: 1.12264 }, fwd: { Pmax: 222.38, Voc: 1.1223 }, hi: 0.00103 },
+    { rate: 1000, J0: 223.55, rev: { Pmax: 223.12, Voc: 1.12271 }, fwd: { Pmax: 221.98, Voc: 1.12252 }, hi: 0.00513 },
+  ],
+});
+
+/**
+ * A J–V loop's figures of merit, from a transient's trace (`{ t, voltage, current }`, as a
+ * recorder or advance() gives it): the loop splits at time `turn` into the sweep before (`rev`)
+ * and after (`fwd`). Each sweep's maximum power V·I (W/m², the largest among the trace's points)
+ * and its open-circuit voltage (where I changes sign, interpolated linearly); and the
+ * hysteresis index (Pmax,rev − Pmax,fwd)/Pmax,rev. Power out is positive, so a cell whose
+ * current runs the other way should have it negated first.
+ * @param {{ t: ArrayLike<number>, voltage: ArrayLike<number>, current: ArrayLike<number> }} trace
+ * @param {number} turn s
+ */
+export function hysteresis(trace, turn) {
+  const out = {};
+  for (const [name, on] of [['rev', (t) => t <= turn], ['fwd', (t) => t >= turn]]) {
+    const pts = [];
+    for (let k = 0; k < trace.t.length; k++) if (on(trace.t[k]) && Number.isFinite(trace.current[k])) pts.push([trace.voltage[k], trace.current[k]]);
+    pts.sort((a, b) => a[0] - b[0]);
+    const k = pts.findIndex(([, I], j) => j > 0 && pts[j - 1][1] > 0 && I <= 0);
+    const Voc = k > 0 ? pts[k - 1][0] + (pts[k - 1][1] * (pts[k][0] - pts[k - 1][0])) / (pts[k - 1][1] - pts[k][1]) : NaN;
+    out[name] = { Pmax: Math.max(...pts.map(([V, I]) => V * I)), Voc };
+  }
+  return { ...out, hi: (out.rev.Pmax - out.fwd.Pmax) / out.rev.Pmax };
+}

package/src/kit.js

@@ -11,6 +11,9 @@ 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 { 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', 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;
@@ -1715,6 +1717,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 +1761,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,
@@ -2171,6 +2201,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;
@@ -2465,6 +2496,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 +2536,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 +2553,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 +2929,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;
+};

package/types/devices.d.ts

@@ -0,0 +1,77 @@
+/**
+ * IonMonger's default planar perovskite solar cell: TiO₂ (100 nm) | MAPbI₃ (400 nm) with mobile
+ * iodide vacancies over an equal immobile background | spiro-OMeTAD (200 nm), at 298 K, lit
+ * through the TiO₂. Species e⁻, h⁺ and the vacancies 'V+'. Recombination is SRH at both faces
+ * (IonMonger's interface law is driftlet's face SRH, with n₁ from the TiO₂'s electron density)
+ * and, with `bulkSRH`, SRH through midgap traps in the perovskite (τₙ = 3 ns, τₚ = 300 ns).
+ * Light is 1.4e21 photons/(m²·s) at α = 1.3e7 /m (IonMonger's one sun), times `light`. The left
+ * contact is the TiO₂'s, at 0 V; the right is the spiro's, at `V`, so photocurrent is positive.
+ *
+ * `PEROVSKITE_SCANS` holds IonMonger's own results for this cell, scan by scan.
+ * @param {{ V?: import('./types.js').Source | { V?: import('./types.js').Source, I?: import('./types.js').Source, R?: number }, light?: number, bulkSRH?: boolean }} [opts]
+ * @returns {import('./types.js').DeviceDefinition}
+ */
+export function perovskiteCell({ V, light, bulkSRH }?: {
+    V?: import("./types.js").Source | {
+        V?: import("./types.js").Source;
+        I?: import("./types.js").Source;
+        R?: number;
+    };
+    light?: number;
+    bulkSRH?: boolean;
+}): import("./types.js").DeviceDefinition;
+/**
+ * A J–V loop's figures of merit, from a transient's trace (`{ t, voltage, current }`, as a
+ * recorder or advance() gives it): the loop splits at time `turn` into the sweep before (`rev`)
+ * and after (`fwd`). Each sweep's maximum power V·I (W/m², the largest among the trace's points)
+ * and its open-circuit voltage (where I changes sign, interpolated linearly); and the
+ * hysteresis index (Pmax,rev − Pmax,fwd)/Pmax,rev. Power out is positive, so a cell whose
+ * current runs the other way should have it negated first.
+ * @param {{ t: ArrayLike<number>, voltage: ArrayLike<number>, current: ArrayLike<number> }} trace
+ * @param {number} turn s
+ */
+export function hysteresis(trace: {
+    t: ArrayLike<number>;
+    voltage: ArrayLike<number>;
+    current: ArrayLike<number>;
+}, turn: number): {
+    hi: number;
+};
+/**
+ * IonMonger's J–V scans of `perovskiteCell()` (IonMonger 2.0, commit 1ae4f9e, run in GNU Octave):
+ * steady state at 1.2 V under light, then 1.2 → 0 → 1.2 V at `rate` (V/s). `full` is the cell
+ * as given (bulk SRH on); `noBulkSRH` is `perovskiteCell({ bulkSRH: false })`. Per scan: J0, the
+ * current at 0 V (A/m²); each sweep's maximum power Pmax (W/m², the largest V·J among IonMonger's
+ * 201 output points per loop) and Voc (V, interpolated); and the hysteresis index
+ * hi = (Pmax,rev − Pmax,fwd)/Pmax,rev. `hysteresis()` reads the same from a run's trace.
+ * driftlet reproduces these to 0.15 % in hi, 0.5 W/m² in Pmax and 2 mV in Voc (its test suite).
+ */
+export const PEROVSKITE_SCANS: Readonly<{
+    source: "IonMonger 2.0 (github.com/PerovskiteSCModelling/IonMonger, commit 1ae4f9e), default parameters";
+    full: {
+        rate: number;
+        J0: number;
+        rev: {
+            Pmax: number;
+            Voc: number;
+        };
+        fwd: {
+            Pmax: number;
+            Voc: number;
+        };
+        hi: number;
+    }[];
+    noBulkSRH: {
+        rate: number;
+        J0: number;
+        rev: {
+            Pmax: number;
+            Voc: number;
+        };
+        fwd: {
+            Pmax: number;
+            Voc: number;
+        };
+        hi: number;
+    }[];
+}>;

package/types/kit.d.ts

@@ -34,6 +34,8 @@ export function vacuumDipole(def: object, left: VacuumSide, right: VacuumSide):
  */
 export function vacuumZeroCharge(def: object, workFunction: number, inside: VacuumSide): number;
 export { live } from "./live.js";
+export { recorder } from "./recorder.js";
+export { check } from "./checks.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
  * in electron energy, the vacuum level just outside lies (the offset, V). So
@@ -59,4 +61,5 @@ export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
+export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from "./devices.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/recorder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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', region?: string | number }[] }} [opts]
+ */
+export function recorder(device: import("./index.js").Device, opts?: {
+    every?: number;
+    times?: number[];
+    probes?: {
+        x: number;
+        species: string;
+        quantity?: "c" | "V";
+        region?: string | number;
+    }[];
+}): {
+    advance: (tEnd: number, aopts?: object) => import("./types.js").Solution;
+    frame: (t: number) => import("./types.js").Solution;
+    frames: import("./types.js").Solution[];
+    trace: {
+        t: number[];
+        current: number[];
+        voltage: number[];
+    };
+};

package/types/solution.d.ts

@@ -10,6 +10,7 @@ export function makeSolution(solver: any, result?: {}): {
     V: {};
     Vstd: {};
     time: any;
+    steady: any;
     converged: any;
     iterations: any;
     steps: any;