driftlet 0.5.0 → 0.7.0

package/src/checks.js

@@ -0,0 +1,302 @@
+// Checks on a solved device, for driftlet/kit: what any result should satisfy, worked out from the
+// definition and the solution, so a page can show that its numbers hold up without its author
+// writing each check by hand. Each check says what it compared and whether it passed.
+
+import { Device } from './index.js';
+import { FARADAY } from './constants.js';
+import { unitWarnings } from './describe.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)));
+
+/**
+ * @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, sol, { refine = true, tol = 1e-2 } = {}) {
+  sol ??= device.solution();
+  const { model, solver, def } = device;
+  const steady = sol.steady ?? solver.atSteady;
+  const items = [];
+
+  items.push(
+    sol.converged
+      ? { name: 'converged', ok: true, summary: `${steady ? 'steady state' : `transient at t = ${sig(sol.time)} s`}, converged` }
+      : { name: 'converged', ok: false, summary: "the solve didn't converge: these numbers aren't a solution" },
+  );
+
+  const warnings = [...sol.warnings, ...unitWarnings(def)];
+  // Heuristics, so a prompt to look (null) rather than a failure.
+  items.push({
+    name: 'warnings',
+    ok: warnings.length === 0 ? true : null,
+    summary: warnings.length === 0 ? 'none' : `${warnings.length}: ${warnings.join(' · ')}`,
+    details: { warnings },
+  });
+
+  // The rest checks a solution, which an unconverged state isn't.
+  if (sol.converged) {
+    const ledger = steady ? balance(device, sol) : null;
+    items.push(ledger ?? conservation(sol));
+    if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+  }
+
+  const ok = sol.converged && items.every((it) => it.ok !== false);
+  const mark = (it) => (it.ok === true ? 'ok  ' : it.ok === false ? 'FAIL' : '?   ');
+  const text = items.map((it) => `${mark(it)} ${it.name}: ${it.summary}${it.details?.lines?.length ? `\n${it.details.lines.map((l) => `       ${l}`).join('\n')}` : ''}`).join('\n');
+  return { ok, items, text };
+}
+
+// Each species' steady ledger: in through the terminals, made by the reactions. Rates in
+// mol/(m²·s), positive into the device or made.
+function balance(device, sol) {
+  const { model, def } = device, { species, regions, interfaces } = model;
+  const label = (rdef) => rdef?.equation ?? JSON.stringify(rdef?.nu ?? rdef);
+  // Each species' compartments: runs of regions it's present in, joined by faces it crosses
+  // freely (in equilibrium). A face it crosses only by a law (a permeability, a conductance) or
+  // by a reaction divides them, and what crosses there is a term in each side's ledger.
+  const ledgers = [], home = species.map(() => new Int32Array(regions.length).fill(-1));
+  species.forEach((sp, i) => {
+    let open = null;
+    regions.forEach((reg, r) => {
+      if (!model.materials[reg.material].present[i]) return void (open = null);
+      if (open && interfaces[r - 1].links[i].type === 'equilibrium') open.regions.push(r);
+      else ledgers.push((open = { species: sp.name, z: sp.z, i, regions: [r], terms: [] }));
+      home[i][r] = ledgers.length - 1;
+    });
+  });
+  const add = (i, r, what, rate) => {
+    const l = home[i][r];
+    if (!(l >= 0 && rate !== 0 && Number.isFinite(rate))) return;
+    const same = ledgers[l].terms.find((t) => t.what === what); // a bulk reaction, region by region
+    if (same) same.rate += rate;
+    else ledgers[l].terms.push({ what, rate });
+  };
+  const last = regions.length - 1;
+  species.forEach((sp, i) => {
+    add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
+    add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
+    model.ports.forEach((port, k) => add(i, port.region, `port ${sol.ports[k].name}`, sol.ports[k].flux[sp.name]));
+  });
+  model.reactions.forEach((rx, k) => {
+    const what = label(def.bulkReactions?.[k]);
+    sol.bulkReactions[k].regions.forEach((total, r) => {
+      for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total);
+      for (const { i, nu } of rx.products) add(i, r, what, nu * total);
+    });
+  });
+  interfaces.forEach((itf, f) => {
+    // Across the face, where it divides a species' compartments.
+    species.forEach((sp, i) => {
+      const type = itf.links[i].type;
+      if (type === 'equilibrium' || type === 'blocked') return;
+      const N = sol.interfaces[f].N[sp.name];
+      add(i, f, `across face ${f} (${type})`, -N);
+      add(i, f + 1, `across face ${f} (${type})`, N);
+    });
+    itf.reactions.forEach((rx, k) => {
+      const rate = sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
+      for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate);
+    });
+  });
+  // A species in one compartment is named alone; one in several, by where.
+  const several = species.map((_, i) => ledgers.filter((l) => l.i === i).length > 1);
+  for (const l of ledgers) {
+    const names = l.regions.map((r) => sol.regions[r].name);
+    l.compartment = names.length === 1 ? names[0] : `${names[0]} to ${names.at(-1)}`;
+    l.title = several[l.i] ? `${l.species} in ${l.compartment}` : l.species;
+  }
+
+  // A species at rest (nothing beyond round-off moving, against what it could carry) isn't reported.
+  const size = (l) => Math.max(0, ...l.terms.map((t) => Math.abs(t.rate)));
+  const natural = naturalScales(device, sol);
+  const moving = ledgers.filter((l) => size(l) > 1e-9 * natural[l.i]);
+  let worst = 0;
+  const lines = [];
+  for (const l of moving) {
+    const sum = l.terms.reduce((a, t) => a + t.rate, 0);
+    l.residual = sum / size(l);
+    worst = Math.max(worst, Math.abs(l.residual));
+    // Terms that matter, largest first; a charged species' as a current too.
+    const shown = l.terms.filter((t) => Math.abs(t.rate) > 1e-6 * size(l)).sort((a, b) => Math.abs(b.rate) - Math.abs(a.rate));
+    const amp = (r) => (l.z !== 0 ? ` (${sig(FARADAY * Math.abs(l.z) * r)} A/m²)` : '');
+    lines.push(`${l.title}: ${shown.map((t) => `${t.what}: ${t.rate > 0 ? '+' : ''}${sig(t.rate)}${amp(t.rate)}`).join('; ')}`);
+  }
+  const ok = worst < 1e-6;
+  const summary =
+    moving.length === 0
+      ? 'nothing flows or reacts (equilibrium)'
+      : `${moving.length === 1 ? 'one ledger sums' : `${moving.length} ledgers sum`} to zero ${ok ? `(to ${sig(worst, 1)})` : `only to ${sig(worst, 2)}: not a steady state`}: each species' sources and sinks, mol/(m²·s), + in or made`;
+  // The largest current any charged species carries anywhere: the scale a net current is read against.
+  const gross = Math.max(0, ...moving.filter((l) => l.z !== 0).map((l) => FARADAY * Math.abs(l.z) * size(l)));
+  return { name: 'balance', ok, summary, details: { ledgers, worst, lines, gross } };
+}
+
+// What each species could carry, mol/(m²·s): by transport, D·c/L in each region (a metal's
+// carrier, σRT/(z²F²L)), and by its bulk reactions, their one-way rates. In equilibrium the net
+// flows are round-off of these.
+function naturalScales(device, sol) {
+  const { model, solver } = device, { species } = model;
+  const box = (g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? sol.x[g] - sol.x[g - 1] : 0) + (g + 1 < sol.x.length && sol.region[g + 1] === sol.region[g] ? sol.x[g + 1] - sol.x[g] : 0)) / 2;
+  return species.map((sp, i) => {
+    let S = 0;
+    model.regions.forEach((reg, r) => {
+      const mat = model.materials[reg.material], L = reg.length;
+      if (mat.conductor) {
+        if (mat.conductor.i === i) S = Math.max(S, (mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        return;
+      }
+      if (!mat.present[i] || !(mat.D[i] > 0)) return;
+      let cmax = 0;
+      for (let g = 0; g < sol.x.length; g++) if (sol.region[g] === r && Number.isFinite(sol.c[sp.name][g])) cmax = Math.max(cmax, sol.c[sp.name][g]);
+      S = Math.max(S, (mat.D[i] * cmax) / L);
+    });
+    solver.rxs.forEach((rx) => {
+      const p = rx.sp.indexOf(i);
+      if (p < 0) return;
+      let gross = 0;
+      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += box(g) * solver.bulkOneWay(rx, g);
+      S = Math.max(S, Math.abs(rx.nu[p]) * gross);
+    });
+    return S;
+  });
+}
+
+// Closed, unreacting stretches keep their amounts in a transient.
+function conservation(sol) {
+  const closed = sol.conservation.filter((st) => !st.connected && !st.reactive);
+  if (closed.length === 0) return { name: 'conservation', ok: true, summary: 'nothing closed to conserve (every species reaches a terminal or reacts)' };
+  // Relative to the amount, but a drift below 1e-20 mol/m² (1e-15 C/m²) is nothing: a floating
+  // metal's excess electrons are themselves ~0.
+  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 ? 0 : Math.abs(st.drift))));
+  return {
+    name: 'conservation',
+    ok: worst < 1e-8,
+    summary: `${closed.length} closed stretch${closed.length > 1 ? 'es' : ''} (a species held between blocking faces) kept ${worst < 1e-8 ? `to ${sig(worst, 1)}` : `only to ${sig(worst, 2)}`} of what ${closed.length > 1 ? 'they' : 'it'} held plus what came in`,
+    details: { worst },
+  };
+}
+
+// The same device on a grid twice as fine (half the cells' sizes, the square root of the
+// grading ratio), solved from this solution interpolated onto it, against this solution.
+function gridCheck(device, sol, tol, gross) {
+  const { def, model } = device;
+  const fine = {
+    ...def,
+    regions: def.regions.map((reg, r) => {
+      if (model.materials[model.regions[r].material].conductor) return reg;
+      const g = { ...(def.grid ?? {}), ...(reg.grid ?? {}) };
+      if (def.grid === undefined && reg.grid === undefined) Object.assign(g, { hmin: reg.length / 1000, hmax: reg.length / 20 });
+      const out = { ratio: Math.sqrt(g.ratio ?? 1.2), minCells: 2 * (g.minCells ?? 8) };
+      if (g.hmin !== undefined) out.hmin = g.hmin / 2;
+      if (g.hmax !== undefined) out.hmax = g.hmax / 2;
+      return { ...reg, grid: out };
+    }),
+  };
+  // Started from this solution, interpolated onto the finer grid; failing that, from cold.
+  let other;
+  try {
+    const dev = new Device(fine);
+    dev.solver._warmFrom(device.solver);
+    other = dev.solve();
+    if (!other.converged) {
+      const cold = new Device(fine);
+      if (sol.time > 0) cold.solver.time = sol.time; // waveforms at the same time
+      other = cold.solve();
+    }
+  } catch (e) {
+    return { name: 'grid', ok: null, summary: `couldn't solve the refined device (${e.message})` };
+  }
+  if (!other.converged) return { name: 'grid', ok: null, summary: "the device on a twice-finer grid didn't solve; check resolution by hand" };
+
+  const diffs = [];
+  // The current, against the largest current any species carries (so at open circuit, or in
+  // equilibrium, round-off isn't read as a change).
+  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross);
+  if (gross > 0) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: 'A/m²' });
+  // Floating terminals (driven by a current): their voltages, against the larger and the thermal voltage.
+  const VT = model.RT / FARADAY;
+  model.terminals.forEach((t, k) => {
+    if (device.solver.floating.includes(k)) {
+      const a = sol.terminals[t.name].V, b = other.terminals[t.name].V;
+      diffs.push({ what: `${t.name} voltage`, a, b, rel: Math.abs(b - a) / Math.max(Math.abs(a), Math.abs(b), VT), unit: 'V' });
+    }
+  });
+  // Each region's charge (C/m²), against the largest: summed over the nodes' boxes, as the
+  // solver's Gauss law counts it.
+  const charges = (s) => s.regions.map((_, r) => {
+    let q = 0;
+    for (let g = 0; g < s.x.length; g++) {
+      if (s.region[g] !== r) continue;
+      const left = g > 0 && s.region[g - 1] === r ? s.x[g] - s.x[g - 1] : 0, right = g + 1 < s.x.length && s.region[g + 1] === r ? s.x[g + 1] - s.x[g] : 0;
+      q += rho(s, g, model, r) * ((left + right) / 2);
+    }
+    return q;
+  });
+  // Charges at round-off (strictly neutral regions) aren't compared: against the gross charge
+  // the regions hold, |fixed| + Σ|z|c, they must be more than a millionth.
+  const content = Math.max(...sol.regions.map((reg, r) => {
+    let q = 0;
+    for (let g = 0; g < sol.x.length; g++) {
+      if (sol.region[g] !== r) continue;
+      let a = Math.abs(model.regions[r].fixedCharge ?? 0);
+      for (const sp of model.species) if (Number.isFinite(sol.c[sp.name][g])) a += FARADAY * Math.abs(sp.z * sol.c[sp.name][g]);
+      q = Math.max(q, a);
+    }
+    return q * (reg.x1 - reg.x0);
+  }));
+  const qa = charges(sol), qb = charges(other), scaleQ = Math.max(0, ...qa.map(Math.abs), ...qb.map(Math.abs));
+  if (scaleQ > 1e-6 * content) {
+    const named = (reg) => (/^region \d+$/.test(reg.name) ? `${reg.name} (${reg.material})` : reg.name);
+    qa.forEach((a, r) => diffs.push({ what: `${named(sol.regions[r])} charge`, a, b: qb[r], rel: Math.abs(qb[r] - a) / scaleQ, unit: 'C/m²' }));
+  }
+  const worst = diffs.reduce((w, d) => (d.rel > (w?.rel ?? -1) ? d : w), null);
+  if (!worst) return { name: 'grid', ok: true, summary: 'nothing to compare (no current, charge or floating voltage)' };
+  const ok = worst.rel <= tol;
+  return {
+    name: 'grid',
+    ok,
+    summary:
+      `on a grid twice as fine (${sol.x.length} → ${other.x.length} nodes), the largest change is ${worst.what}, ${sig(worst.a, 5)} → ${sig(worst.b, 5)} ${worst.unit} ` +
+      `(${sig(worst.rel, 2)}${ok ? '' : `, over ${sig(tol, 1)}: refine the grid (hmin, hmax), most likely where profiles are steepest`})`,
+    details: { diffs, nodes: [sol.x.length, other.x.length] },
+  };
+}
+
+// Charge density at a node of region r, C/m³: the species plus the region's fixed charge.
+function rho(s, g, model, r) {
+  let q = model.regions[r].fixedCharge ?? 0;
+  for (const sp of model.species) {
+    const c = s.c[sp.name][g];
+    if (Number.isFinite(c)) q += FARADAY * sp.z * c;
+  }
+  return q;
+}

package/src/describe.js

@@ -141,13 +141,17 @@ export function describe(def) {
     if (reg.fixedCharge !== 0) parts.push(`fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(Math.abs(reg.fixedCharge) / FARADAY)}`);
     // The screening concentration: Σ z²c from the initial composition, plus the carriers that
     // balance the fixed charge (doping), which c0 doesn't list.
-    let zzc = 0;
+    let zzc = 0, q = reg.fixedCharge / FARADAY; // q: the charge c0 leaves unbalanced
     species.forEach((sp, i) => {
       if (!mat.present[i]) return;
-      if (Number.isFinite(reg.c0[i])) zzc += sp.z * sp.z * reg.c0[i];
-      else if (reg.c0Profile[i]) zzc += sp.z * sp.z * Math.max(...reg.c0Profile[i].values);
+      const c = Number.isFinite(reg.c0[i]) ? reg.c0[i] : reg.c0Profile[i] ? Math.max(...reg.c0Profile[i].values) : 0;
+      zzc += sp.z * sp.z * c;
+      q += sp.z * c;
     });
-    zzc += Math.abs(reg.fixedCharge) / FARADAY; // the mobile charge that balances the doping
+    // Plus the mobile charge that balances whatever c0 leaves unbalanced: a doped layer's
+    // carriers, which c0 doesn't list (and nothing, where c0 lists them, as a perovskite's
+    // vacancies over their background).
+    zzc += Math.abs(q);
     const Dmax = Math.max(0, ...species.map((sp, i) => (mat.present[i] && sp.z !== 0 ? mat.D[i] : 0)));
     const Dmin = Math.min(...species.map((sp, i) => (mat.present[i] && mat.D[i] > 0 ? mat.D[i] : Infinity)));
     if (mat.epsr > 0 && zzc > 0) {
@@ -182,8 +186,15 @@ export function describe(def) {
       const law = itf.phi.type === 'capacitive' ? `capacitive, C = ${num(itf.phi.C)} F/m²` : itf.phi.type;
       const align = itf.conductor ? (itf.phi.type === 'capacitive' ? `, zeroCharge ${num(itf.zeroCharge)} V` : '') : itf.phi.type === 'neutral' ? '' : `, dipole ${num(itf.dipole)} V`;
       const blocked = species.filter((sp, i) => itf.links[i].type === 'blocked' && materials[L.material].present[i] && materials[R.material].present[i]).map((sp) => sp.name);
-      const rx = (idef.reactions ?? []).map((r) => r.equation ?? equation(r.left, r.right));
-      lines.push(`  ${L.name} | ${R.name}: ${law}${align}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}`);
+      const kinetics = (r) => (r.vmax !== undefined ? ` (saturating, vmax ${num(r.vmax)} mol/(m²·s))` : r.srh ? ' (SRH)' : '');
+      const rx = (idef.reactions ?? []).map((r) => (r.equation ?? equation(r.left, r.right)) + kinetics(r));
+      const laws = species.flatMap((sp, i) => {
+        const l = itf.links[i];
+        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²`] : [];
+      });
+      lines.push(
+        `  ${L.name} | ${R.name}: ${law}${align}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}`,
+      );
     });
   }
 
@@ -198,7 +209,7 @@ export function describe(def) {
   (def.ports ?? []).forEach((p, k) => lines.push(`  port ${model.ports[k].name}: ${drive(p)}, in ${regions[model.ports[k].region].name}`));
   if ((def.bulkReactions ?? []).length) {
     lines.push('bulk reactions:');
-    for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)} in ${Object.keys(rx.kf ?? {}).join(', ')}`);
+    for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)}${rx.srh ? ' (SRH)' : ''} in ${Object.keys(rx.kf ?? rx.srh ?? {}).join(', ')}`);
   }
   if (times.length) lines.push('time scales:', ...times);
   if (warnings.length) lines.push('warnings:', ...warnings.map((w) => `  ${w}`));

package/src/device.js

@@ -16,7 +16,7 @@ export { DeviceError };
 
 // Contacts use the same laws as internal faces: the outside is a phase with known levels.
 const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange']);
-const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance']);
+const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance', 'permeability']);
 const PHI_LINK_TYPES = new Set(['bulk', 'neutral', 'capacitive', 'pinned']);
 const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells'];
 // The fields of each kind of species link (to an outside phase, or across a face).
@@ -433,12 +433,17 @@ function stoichiometry(map, path, fixed, fixedPath, species, speciesIndex, RT) {
 //   r = k0 Π_{ν<0} (c/c_ref)^{|ν|(1−α)} Π_{ν>0} (c/c_ref)^{να} (e^{αa} − e^{−(1−α)a})
 // (a conductor's carrier has activity 1, so no factor). That's mass action with rate constants
 // that depend on the electrical part of the affinity, and exactly zero at A = 0.
+// Or saturating (a transporter or an enzyme that turns over at most vmax per area): with K a
+// half-saturation concentration for each species the forward reaction consumes,
+//   r = vmax Π_{ν<0} (c/(c + K))^{|ν|} (1 − e^{−a}),
+// Michaelis–Menten in each substrate, and still exactly zero at A = 0 (the backward rate is the
+// one detailed balance implies).
 function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT) {
   need(idef.reactions === undefined || Array.isArray(idef.reactions), `${where}.reactions must be an array`);
   return (idef.reactions ?? []).map((rdef, k) => {
     const rpath = `${where}.reactions[${k}]`;
     need(isObject(rdef), `${rpath} must be { equation, fixed, k0, alpha } or { left, right, fixed, k0, alpha }`);
-    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh']);
+    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh', 'vmax', 'K']);
     let sides = rdef;
     if (rdef.equation !== undefined) {
       need(rdef.left === undefined && rdef.right === undefined, `${rpath}: give the reaction as an equation or as left and right, not both`);
@@ -458,6 +463,22 @@ function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex,
     }
     need(part.length > 0, `${rpath}: no species participate`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    if (rdef.vmax !== undefined || rdef.K !== undefined) {
+      need(rdef.k0 === undefined && rdef.alpha === undefined && rdef.srh === undefined, `${rpath}: give vmax and K (saturating), srh, or k0 and alpha (Butler–Volmer), one of them`);
+      const vmax = positive(rdef.vmax, `${rpath}.vmax (mol/(m²·s))`);
+      need(isObject(rdef.K), `${rpath}.K must map each species the forward reaction consumes to its half-saturation concentration (mol/m³)`);
+      for (const name of Object.keys(rdef.K)) {
+        need(part.some((p) => p.nu < 0 && species[p.i].name === name), `${rpath}.K.${name}: not a species the forward reaction consumes`);
+        positive(rdef.K[name], `${rpath}.K.${name} (mol/m³)`);
+      }
+      for (const p of part) {
+        if (p.nu >= 0) continue;
+        const mat = p.side ? matR : matL;
+        need(!mat.conductor, `${rpath}: saturating kinetics is for dissolved substrates, not a metal's ${species[p.i].name}`);
+        need(rdef.K[species[p.i].name] !== undefined, `${rpath}.K.${species[p.i].name}: give a half-saturation concentration for every species the forward reaction consumes`);
+      }
+      return { part, fixedA, vmax, K: part.map((p) => (p.nu < 0 ? rdef.K[species[p.i].name] : 0)) };
+    }
     if (rdef.srh !== undefined) {
       need(rdef.k0 === undefined && rdef.alpha === undefined, `${rpath}: give srh or k0 (and alpha), not both`);
       const srh = srhLaw(rdef.srh, `${rpath}.srh`, part, species, ['vn', 'vp']);
@@ -741,7 +762,8 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   const sheetCharge = idef.sheetCharge === undefined ? 0 : finite(idef.sheetCharge, `${where}.sheetCharge`);
 
   // Per-species laws across the face: local equilibrium (default where present on both sides),
-  // blocked, or an ohmic interface conductance G (S/m²).
+  // blocked, an ohmic interface conductance G (S/m²), or a permeability P (m/s): electrodiffusion
+  // through a thin membrane in a constant field, Goldman–Hodgkin–Katz.
   const links = defaultInterfaceLinks(matL, matR, species);
   if (idef.species !== undefined) {
     need(isObject(idef.species), `${where}.species must map species names to interface links`);
@@ -751,12 +773,16 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
       const i = speciesIndex.get(sname);
       const link = typeof raw === 'string' ? { type: raw } : raw;
       need(isObject(link) && INTERFACE_LINK_TYPES.has(link.type), `${lpath}.type must be one of ${[...INTERFACE_LINK_TYPES].join(', ')}`);
-      fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : ['type']);
+      fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : link.type === 'permeability' ? ['type', 'P'] : ['type']);
       if (link.type !== 'blocked') need(matL.present[i] && matR.present[i], `${lpath}: '${sname}' must be present on both sides`);
       if (link.type === 'conductance') {
         need(species[i].z !== 0, `${lpath}: a conductance link needs a charged species`);
         positive(link.G, `${lpath}.G`);
       }
+      if (link.type === 'permeability') {
+        positive(link.P, `${lpath}.P (m/s)`);
+        need(matL.modelOf[i] < 0 && matR.modelOf[i] < 0, `${lpath}: a permeability link needs ideal (dilute) statistics for '${sname}' on both sides`);
+      }
       links[i] = { ...link };
     }
   }
@@ -847,6 +873,7 @@ function normalizeConductorInterface(idef, where, matL, matR, species, speciesIn
       const i = speciesIndex.get(sname);
       const link = typeof raw === 'string' ? { type: raw } : raw;
       need(isObject(link) && INTERFACE_LINK_TYPES.has(link.type), `${lpath}.type must be one of ${[...INTERFACE_LINK_TYPES].join(', ')}`);
+      need(link.type !== 'permeability', `${lpath}: a permeability link is for a membrane between two solutions, not at a conductor`);
       fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : ['type']);
       if (link.type !== 'blocked') need(matL.present[i] && matR.present[i], `${lpath}: '${sname}' must be present on both sides`);
       if (link.type === 'conductance') {

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/index.js

@@ -160,7 +160,7 @@ export class Device {
    * (one array per probe, alongside `trace.t`): what a detector at x sees.
    * @param {number} tEnd s
    * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-   *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
+   *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {