driftlet 0.4.0 → 0.6.0

package/src/checks.js

@@ -0,0 +1,268 @@
+// 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 } = model;
+  const label = (rdef) => rdef?.equation ?? JSON.stringify(rdef?.nu ?? rdef);
+  const ledgers = species.map((sp) => ({ species: sp.name, z: sp.z, terms: [] }));
+  const add = (i, what, rate) => {
+    if (rate !== 0 && Number.isFinite(rate)) ledgers[i].terms.push({ what, rate });
+  };
+  species.forEach((sp, i) => {
+    add(i, 'left contact', sol.contacts.left.flux[sp.name]);
+    add(i, 'right contact', -sol.contacts.right.flux[sp.name]);
+    sol.ports.forEach((p) => add(i, `port ${p.name}`, p.flux[sp.name]));
+  });
+  model.reactions.forEach((rx, k) => {
+    const total = sol.bulkReactions[k].total, what = label(def.bulkReactions?.[k]);
+    for (const { i, nu } of rx.reactants) add(i, what, -nu * total);
+    for (const { i, nu } of rx.products) add(i, what, nu * total);
+  });
+  model.interfaces.forEach((itf, f) => {
+    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 } of rx.part) add(i, what, nu * rate);
+    });
+  });
+
+  // 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, i) => size(l) > 1e-9 * natural[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.species}: ${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} species' sources and sinks sum to zero ${ok ? `(to ${sig(worst, 1)})` : `only to ${sig(worst, 2)}: not a steady state`}; 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

@@ -139,14 +139,19 @@ export function describe(def) {
     }
     const parts = [mat.epsr > 0 ? `εr ${mat.epsr}` : 'strictly neutral (ε = 0)'];
     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, else the fixed charge's.
-    let zzc = 0;
+    // 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, 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;
     });
-    if (zzc === 0) zzc = Math.abs(reg.fixedCharge) / FARADAY;
+    // 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) {
@@ -197,7 +202,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

@@ -70,6 +70,29 @@ function profile(v, path, what, ok, okText) {
   return { x: Float64Array.from(v.x), values: Float64Array.from(v.values) };
 }
 
+// SRH (trap-assisted) kinetics in place of mass action, for a reaction that consumes exactly one
+// negative and one positive species and makes none, e⁻ + h⁺ = 0:
+//   r = n p (1 − e^{−A/RT}) / (t_p (n + n₁) + t_n (p + p₁)),  p₁ = n p e^{−A/RT} / n₁,
+// with t = τ (s) in the bulk, 1/v (m/s) at a face, and n₁ the negative species' concentration
+// with its level at the trap (default n_i, a midgap trap). p₁ from the state keeps detailed
+// balance exact, whatever lies between the two (a band offset, a φ jump).
+function srhLaw(sdef, path, list, species, timeKeys) {
+  const [kn, kp] = timeKeys;
+  need(isObject(sdef), `${path} must be { ${kn}, ${kp}, n1 }`);
+  fields(sdef, path, [kn, kp, 'n1']);
+  const reactants = list.filter((p) => p.nu < 0);
+  need(
+    list.length === 2 && reactants.length === 2 && reactants.every((p) => p.nu === -1) && species[list[0].i].z * species[list[1].i].z < 0,
+    `${path}: SRH kinetics needs a reaction consuming one negative and one positive species and making none, such as 'e- + h+ = 0'`,
+  );
+  const neg = species[list[0].i].z < 0 ? list[0] : list[1], pos = neg === list[0] ? list[1] : list[0];
+  const time = (key) => {
+    const v = positive(sdef[key], `${path}.${key}`);
+    return key.startsWith('v') ? 1 / v : v; // a velocity's reciprocal is the time it stands for
+  };
+  return { n: neg, p: pos, tn: time(kn), tp: time(kp), n1: sdef.n1 === undefined ? NaN : positive(sdef.n1, `${path}.n1`) };
+}
+
 function nonNegative(v, path) {
   need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${JSON.stringify(v)}`);
   return v;
@@ -324,12 +347,27 @@ export function normalizeDevice(def) {
 // reaction runs only in those materials).
 function normalizeReaction(rdef, path, species, speciesIndex, materials, materialIndex, regions, RT) {
   need(isObject(rdef), `${path} must be an object`);
-  fields(rdef, path, ['nu', 'equation', 'fixed', 'kf']);
+  fields(rdef, path, ['nu', 'equation', 'fixed', 'kf', 'srh']);
   need((rdef.nu === undefined) !== (rdef.equation === undefined), `${path}: give the reaction as nu or as an equation, one of them`);
   const nu = rdef.nu ?? equationStoichiometry(rdef.equation, `${path}.equation`);
   const st = stoichiometry(nu, rdef.equation === undefined ? `${path}.nu` : `${path}.equation`, rdef.fixed, `${path}.fixed`, species, speciesIndex, RT);
   need(st.list.length > 0, `${path}: no mobile participants`);
   need(st.charge === 0, `${path}: charge is not balanced (Σ ν z = ${st.charge})`);
+  // SRH kinetics instead: srh maps material names to { tauN, tauP, n1 }.
+  need((rdef.kf === undefined) !== (rdef.srh === undefined), `${path}: give kf (mass action) or srh (trap-assisted), one of them`);
+  if (rdef.srh !== undefined) {
+    need(isObject(rdef.srh), `${path}.srh must map material names to { tauN, tauP, n1 }`);
+    const srh = new Array(materials.length).fill(null), kf = new Float64Array(materials.length), kfProfile = new Array(materials.length).fill(null);
+    for (const [mname, v] of Object.entries(rdef.srh)) {
+      need(materialIndex.has(mname), `${path}.srh.${mname}: unknown material`);
+      const m = materialIndex.get(mname);
+      srh[m] = srhLaw(v, `${path}.srh.${mname}`, st.list, species, ['tauN', 'tauP']);
+      for (const { i } of st.list) need(materials[m].present[i], `${path}.srh.${mname}: '${species[i].name}' is absent from material '${mname}'`);
+      kf[m] = 1; // (runs here)
+    }
+    const reactants = st.list.map(({ i, nu }) => ({ i, nu: -nu }));
+    return { reactants, products: [], fixedA: st.fixedA, kf, kfProfile, srh, generation: false };
+  }
   need(isObject(rdef.kf), `${path}.kf must map material names to forward rate constants`);
   // Each a number, or a profile { x, values } against the device's x (e.g. absorption); kf[m]
   // is then its largest value, which says whether the reaction runs in that material at all.
@@ -400,7 +438,7 @@ function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex,
   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']);
+    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh']);
     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`);
@@ -420,6 +458,15 @@ 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.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']);
+      for (const p of part) {
+        const mat = p.side ? matR : matL;
+        need(!mat.conductor, `${rpath}.srh: SRH kinetics is for carriers in semiconductors, not a metal's ${species[p.i].name}`);
+      }
+      return { part, fixedA, srh };
+    }
     return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`) };
   });
 }
@@ -820,7 +867,7 @@ function defaultInterfaceLinks(matL, matR, species) {
 
 function transferCoefficient(v, path) {
   if (v === undefined) return 0.5;
-  need(isFiniteNumber(v) && v > 0 && v < 1, `${path} must be between 0 and 1, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v >= 0 && v <= 1, `${path} must be between 0 and 1, got ${JSON.stringify(v)}`);
   return v;
 }
 

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

@@ -63,13 +63,22 @@ export class Device {
   }
 
   /**
-   * Change part of the definition (deep-merged). A change to the terminals' drives alone (V, I,
-   * R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
+   * Change part of the definition (deep-merged). A contact given V or I drops the other, so
+   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. A change to the terminals'
+   * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
    * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
    * @param {object} patch a partial device definition, merged into the current one
    * @returns {this}
    */
   set(patch) {
+    // A contact given a new kind of drive drops the old one: { I: 0 } replaces a held V.
+    for (const side of ['left', 'right']) {
+      const c = patch?.contacts?.[side];
+      if (c && typeof c === 'object') {
+        if ('I' in c && !('V' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, V: undefined } } };
+        else if ('V' in c && !('I' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, I: undefined } } };
+      }
+    }
     const def = merge(this.def, patch);
     // Only the terminals' drives changed: update them in place, keeping the solver and its state
     // (a step in a source restarts the time stepping's order, as at any discontinuity).

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

@@ -257,12 +257,13 @@ export function levelChart(tr, { width = 640, height = 360, ylabel = 'voltage (V
 
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
- * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
+ * diagram of electrons and holes. Options are those of `traces()` and `levelChart()`.
  * @param {import('./types.js').Solution} sol
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}
  */
 export function bandDiagram(sol, opts = {}) {
-  const { width, height, ylabel, range, xlim, title, ytick, ...pick } = opts;
+  const { width, height, ylabel = opts.energy ? 'electron energy (eV)' : undefined, range, xlim, title, ytick, ...pick } = opts;
   return levelChart(traces(sol, pick), { width, height, ylabel, range, xlim, title, ytick });
 }