driftlet 0.10.0 → 0.11.4

package/docs/reliability.md

@@ -0,0 +1,122 @@
+# How far to trust it
+
+A drift–diffusion solver is quick to start and slow to finish. The first version solves a pn
+junction; the trouble comes after, with what real devices ask of it:
+
+- concentrations spanning 30 orders of magnitude in one device (majority carriers beside
+  minority ones, a salt beside the ions its double layer excludes);
+- double layers a millionth of the device's length, resolved or not;
+- species whose amount is fixed rather than their level (a blocked ion, a floating base, a
+  closed cell's salt), which makes the steady equations singular;
+- populations held only by couplings of 1e-17 (an inversion layer fed by ~1e3 minority
+  carriers per cm³), which a factorisation loses to round-off;
+- terminals driven by a current, which may be beyond what the device can pass;
+- small-signal currents read from sums whose terms are 1e17 times bigger.
+
+Each of these makes a plain Newton solver fail, or worse, converge to the wrong answer. driftlet
+has met them, mostly through the two kinds of testing below, and its numerics are built around
+them ([numerics](numerics.md)). This page says what that testing covers and what it found, and
+what is known not to work.
+
+## Correct: the validation suite
+
+Every physics feature is checked against an analytic result, or an independent code where
+there isn't one: `npm test`, over 300 tests, each a worked device with its closed form. They include
+Shockley's diode equation, depletion and MOS charge, collection theory under Beer–Lambert light,
+Gouy–Chapman and Kilic–Bazant–Ajdari double layers, Donnan and Teorell–Meyer–Sievers
+partitions, Goldman–Hodgkin–Katz, the limiting current and Butler–Volmer kinetics, the
+Macdonald and finite-length Warburg impedances, Cottrell and spherical diffusion, and the
+second law (the free energy in through the terminals equals what's dissipated, every term
+non-negative). Against other codes: IonMonger's perovskite J–V hysteresis (finite elements,
+Octave), and liquid-junction potentials against JPCalc, LJPcalc and JLJP. The README's
+[validation table](../README.md#validation) lists each with its tolerance.
+
+Each solution can check itself too: `check()` from `driftlet/kit` balances every species'
+ledger (what comes in through each terminal, is made or destroyed), the conservation
+bookkeeping of a transient, and the grid (the device solved again on a grid twice as fine).
+
+## Robust: random devices
+
+The validation suite shows driftlet is right where it converges. Whether it converges, on
+devices nobody tuned it for, is what `npm run stress` tests. It builds random but plausible
+devices in five families:
+
+| Family | What's drawn |
+|---|---|
+| Semiconductor stacks | Si, Ge or GaAs; 1–3 layers n, p or intrinsic, doping 1e14–1e19 cm⁻³, 50 nm–10 µm each; no recombination, band-to-band or SRH (τ from 1 ns to 10 µs); sometimes lit; sometimes a Schottky contact |
+| MOS capacitors | Si, Ge or GaAs, doped 1e15–1e18 cm⁻³; oxide 1–20 nm; Au, Al or Pt gate at any flat-band offset; with or without generation |
+| Electrolyte cells | one to three salts from the data library's ions, 0.1 mM–1 M, 1 µm–1 mm; double layers resolved or strictly neutral; bath, reversible or blocking electrodes |
+| Electrodes | Ag, Cu or Zn deposition, or Fe³⁺/Fe²⁺ on platinum, with Butler–Volmer kinetics over four decades of k₀; with or without a supporting salt; against a second electrode or a bath |
+| Liquid junctions | two mixed solutions, 1 µM–1 M, sharp or graded, at open circuit |
+
+Each device goes through what a user would do with it: a cold solve at no bias, and one at a
+bias; a warm sweep to that bias; open circuit, where it's lit; a current drive (a fraction of
+what passes at 1 V); a transient after a voltage step; and the impedance about equilibrium,
+from far below its slowest relaxation to 1 GHz. Every result is judged by `check()`, and by what must hold whatever the device:
+levels flat at equilibrium with no current, warm and cold solves agreeing, the current driven
+being the one passed, the impedance passive (to 1e-3 of |Z|) and, at low frequency, equal to
+the steady dI/dV,
+and a MOS capacitance never above its oxide's. Each case is seeded from its family and index, so
+any failure reruns alone (`npm run stress -- semi 79`).
+
+At 500 devices per family (about three minutes on a desktop), 11,380 of 11,381 scenarios pass:
+
+| Family | Cold at 0 V | Cold at bias | Warm sweep | Open circuit or current | Transient | Impedance |
+|---|---|---|---|---|---|---|
+| Semiconductor stacks | 500/500 | 500/500 | 500/500 | 105/105 | 500/500 | 395/395 |
+| MOS capacitors | 500/500 | 500/500 | 500/500 | | 500/500 | 500/500 |
+| Electrolyte cells | 500/500 | 500/500 | 500/500 | | 500/500 | 381/381 |
+| Electrodes | 500/500 | 500/500 | 500/500 | 500/500 | 500/500 | 500/500 |
+| Liquid junctions | | | | 500/500 | 499/500 | |
+
+(Impedance only where the device has an equilibrium to linearise about; open circuit only for
+lit cells.) The one that fails is among the known limits below: a junction on a grid far too
+coarse for its double layers.
+`bench/stress.json` keeps the summary.
+
+Most of what driftlet's numerics do differently began as a failure here: the impedance's
+current read across the quietest cut of the device rather than at the contact, GMRES judged by
+its true residual, blocked species held flat in steady solves, continuations for a current drive
+and for light, and Newton refining its solves where a factorisation loses a mode, with an exact
+$`J \cdot v`$.
+
+## Hard cases
+
+`npm run hard` keeps a corpus of named cases that were hard once (sharp 3 M | 1 µM junctions on
+short steps, an inversion layer filling over minutes, a solar cell's open circuit on a 0.25 nm
+grid, corroding drops), with their step and factorisation counts against a committed baseline,
+so a change that makes one worse shows.
+
+## Known limits
+
+- **A population held only through couplings far below double precision** is solved in steady
+  state by refining Newton's solves, as far as its own equations resolve it: a bipolar stack's
+  floating base at bias (a p⁺ base whose holes are held ~1e14 more weakly than they move within
+  it) is, and a closed Fe³⁺/Fe²⁺ cell driven by a current near its limit, where Fe³⁺ falls 20
+  orders below Fe²⁺, is found as the held voltage that passes it. Where a solve fails, its warning
+  says where it lost its digits (a transient gets there). A region held only through its faces (by
+  conductances 1e-24 of its own, or by neighbours conducting 1e20 times less) is solved directly
+  through its balance summed over it, where its own fluxes cancel exactly
+  ([islands](numerics.md#steady-state)): its current comes out right to ~1e-15, where it was
+  up to 16× off. A population held that weakly within a region, or fed by a reaction, isn't
+  covered, and its solve can still converge to the wrong level; the terminal currents then
+  don't add up, which is the thing to check.
+- **The impedance is resolved to about 1e-4 of |Z|** where its solves are hardest: the real
+  part of a nearly ideal capacitor (a closed redox cell with almost none of one partner), 1e-7 of
+  |Z|, can come out slightly negative. Its DC limit matches the steady dI/dV in every stress case.
+- **Strictly neutral regions on very short steps** lose digits at a neutral face between very
+  different solutions (3 M against 1 µM at steps of 1e-11 s).
+- **An unresolved double layer** (a cell coarser than the Debye length) gives a charge that
+  depends on the grid, and in a sharp junction between very different solutions can stop a
+  transient; the solution warns. So does a steep profile on too coarse a cell.
+- **A surface covered to a bare fraction below ~1e-10** barely affects anything any more, and
+  the solver struggles with it (the hard corpus's passivating drop without a double layer stops
+  partway through its hour); the solution warns, and suggests a less stable film.
+- **Currents below ~0.1 nA/m²** (a GaAs junction's leakage without recombination) aren't resolved
+  between solves; such a current is zero for any practical purpose.
+- **A failed solve says so:** `converged: false`, with a warning naming where the system lost
+  its digits, or which current no voltage reaches. In these tests, every steady state and
+  transient reported converged has passed `check()` and the invariants above.
+- What driftlet doesn't model at all (more than one dimension, cross-diffusion, heat, optics,
+  field-dependent mobility) is in the [README](../README.md#what-it-doesnt-do), and open
+  numerical work in the [roadmap](../ROADMAP.md).

package/llms.txt

@@ -14,9 +14,9 @@ docs/conventions.md (signs and levels) and docs/data.md (the data library).
 From a CDN, pin the version:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -346,6 +346,11 @@ for (const Vd of [0.1, 0.5, 1, 1.5, 2, 3]) {
 }
 ```
 
+To sweep the gate on one device instead, patch the port by name: `dev.set({ ports: { gate: { V } } })`
+(a drive only, so it's cheap and keeps the state as a warm start). An organic electrochemical
+transistor is the same with a volumetric capacitance C*: `area: 1 / t, capacitance: { C: Cstar * t }`
+(docs/device.md, "A capacitance through a window").
+
 ## Template: a transient, with a pulse injected sideways
 
 A **port** feeds a window of nodes inside a region from the side (a point contact, an injector,
@@ -418,9 +423,9 @@ solve), as long as it settles rather than ping-pongs.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.10.0",
+  "version": "0.11.4",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {
@@ -30,6 +30,7 @@
     "test": "node --test",
     "bench": "node bench/bench.js",
     "hard": "node bench/hard.js",
+    "stress": "node bench/stress.js",
     "smoke": "node tools/smoke.js",
     "shots": "node tools/shots.js",
     "prepublishOnly": "npm test && npm run types",

package/src/blockTridiagonal.js

@@ -74,6 +74,14 @@ export class BlockTridiagonal {
     this.minPivotRatio = Infinity;
     /** The block found exactly singular by the last factor(), or −1. */
     this.singularBlock = -1;
+    /**
+     * Static pivoting: an exactly zero pivot (all its candidates cancelled to nothing) is
+     * replaced by 1e-15 of its block's largest entry rather than thrown on, for a caller that
+     * refines its solves (and counted in `perturbedPivots`).
+     */
+    this.staticPivots = false;
+    /** How many pivots the last factor() replaced. */
+    this.perturbedPivots = 0;
   }
 
   /** Zero all of A, B, C (ready for fresh assembly). */
@@ -86,13 +94,14 @@ export class BlockTridiagonal {
 
   /**
    * Factorise the current A, B, C. A, B, C are left untouched.
-   * Throws if a diagonal block is exactly singular.
+   * Throws if a diagonal block is exactly singular (unless `staticPivots`).
    */
   factor() {
     const { n, A, B, C, sizes, offA, offB, offC, offX } = this;
     const lu = this._lu, piv = this._piv, cp = this._cp, tmp = this._tmp;
     let minRatio = Infinity;
     this.singularBlock = -1;
+    this.perturbedPivots = 0;
 
     for (let i = 0; i < n; i++) {
       const m = sizes[i], o = offB[i];
@@ -110,7 +119,7 @@ export class BlockTridiagonal {
           }
         }
       }
-      const ratio = luFactor(lu, o, piv, offX[i], m);
+      const ratio = luFactor(lu, o, piv, offX[i], m, this);
       if (!(ratio > 0)) {
         this.factored = false;
         this.singularBlock = i;
@@ -244,7 +253,7 @@ export class BlockTridiagonal {
 
 // In-place LU with partial pivoting of the m×m block at a[o…]. Row swaps are recorded in
 // piv[p…]. Returns min |pivot| / max |entry| (0 if singular).
-function luFactor(a, o, piv, p, m) {
+function luFactor(a, o, piv, p, m, perturb = null) {
   let maxEntry = 0;
   for (let k = 0; k < m * m; k++) {
     const v = Math.abs(a[o + k]);
@@ -259,7 +268,11 @@ function luFactor(a, o, piv, p, m) {
       if (v > bestVal) { best = r; bestVal = v; }
     }
     piv[p + k] = best;
-    if (bestVal === 0) return 0;
+    if (bestVal === 0) {
+      if (!perturb?.staticPivots) return 0;
+      bestVal = a[o + best * m + k] = 1e-15 * maxEntry;
+      perturb.perturbedPivots++;
+    }
     if (bestVal < minPivot) minPivot = bestVal;
     if (best !== k) {
       for (let c = 0; c < m; c++) {

package/src/checks.js

@@ -96,7 +96,9 @@ function balance(device, sol) {
       home[i][r] = ledgers.length - 1;
     });
   });
-  const add = (i, r, what, rate) => {
+  const partners = new Map(); // a reaction term's species: its net rate is round-off against any of theirs
+  const add = (i, r, what, rate, species) => {
+    if (species) partners.set(what, species);
     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
@@ -112,8 +114,9 @@ function balance(device, sol) {
   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);
+      const all = [...rx.reactants, ...rx.products].map((p) => p.i);
+      for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total, all);
+      for (const { i, nu } of rx.products) add(i, r, what, nu * total, all);
     });
   });
   interfaces.forEach((itf, f) => {
@@ -129,7 +132,8 @@ function balance(device, sol) {
     });
     itf.reactions.forEach((rx, k) => {
       const rate = Af * 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);
+      const all = rx.part.map((p) => p.i);
+      for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate, all);
     });
   });
   // A species in one compartment is named alone; one in several, by where.
@@ -140,10 +144,12 @@ function balance(device, sol) {
     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.
+  // A species at rest (nothing beyond round-off moving, against what it or its reactions' partners
+  // 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]);
+  const natural = naturalScales(device, sol), inSolution = naturalScales(device, sol, false); // (partners' scale: not a metal's conductance)
+  const scale = (l) => Math.max(natural[l.i], ...l.terms.flatMap((t) => (partners.get(t.what) ?? []).map((j) => inSolution[j])));
+  const moving = ledgers.filter((l) => size(l) > 1e-8 * scale(l));
   let worst = 0;
   const lines = [];
   for (const l of moving) {
@@ -167,8 +173,9 @@ function balance(device, sol) {
 
 // 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) {
+// flows are round-off of these. Without `conductors`, transport through conductor regions isn't
+// counted.
+function naturalScales(device, sol, conductors = true) {
   const { model, solver } = device, { species, grid } = model;
   // (totals through the cross-section, as the ledgers are: its largest in each region)
   const area = model.regions.map((_, r) => Math.max(...grid.area.subarray(grid.regionStart[r], grid.regionEnd[r] + 1)));
@@ -177,7 +184,7 @@ function naturalScales(device, sol) {
     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, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        if (conductors && mat.conductor.i === i) S = Math.max(S, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
         return;
       }
       if (!mat.present[i] || !(mat.D[i] > 0)) return;

package/src/difference.js

@@ -0,0 +1,142 @@
+// The dilute kernels' Jacobian terms kept in difference form, for an exact J·v.
+//
+// Assembled, a Scharfetter–Gummel flux's dependence on η at its two ends is two entries, G and
+// −G(1 + E), that cancel for a nearly uniform v; where G is huge (an inversion layer's 0.1 nm
+// cells), J·v loses the flux to round-off. Kept as terms, each is evaluated on differences first:
+//   δN = a·(δη_L − z δφ̂_L) + b·(δη_R − δη_L) + d·(δφ̂_R − δφ̂_L),
+// with a = −G E (through c_L), b = −G(1 + E) and d = z ∂N/∂Δ (through the drift). A node's
+// storage and space charge depend on δη_i − z_i δφ̂ alone; the displacement on δφ̂_R − δφ̂_L. A
+// uniform shift of a region (z_i s on each η_i, s on φ̂) then gives exactly zero, as it must.
+//
+// Indices are compact (the solver's rix), with the sink (index N) for an unknown that isn't one:
+// vectors passed in are read there as zero.
+export class DifferenceTerms {
+  constructor(N, nodes, segments) {
+    this.N = N;
+    this.dead = new Uint8Array(N + 1); // rows replaced since (a contact's level, a held stretch)
+    this.nI = new Int32Array(nodes); // node term: η column (= its balance row), φ̂ column (= Gauss row)
+    this.nP = new Int32Array(nodes);
+    this.nZ = new Float64Array(nodes);
+    this.nMass = new Float64Array(nodes); // storage per unit (δη − z δφ̂), times 1/dt (or iω)
+    this.nCharge = new Float64Array(nodes); // into the Gauss row, per unit (δη − z δφ̂)
+    this.sI = new Int32Array(4 * segments); // segment term: η_L, η_R, φ̂_L, φ̂_R
+    this.sZ = new Float64Array(segments);
+    this.sC = new Float64Array(3 * segments); // a, b, d
+    this.dI = new Int32Array(2 * segments); // displacement: φ̂_L, φ̂_R
+    this.dK = new Float64Array(segments);
+    this.combos = []; // [rk, ri, w]: row rk += w × row ri (strictly neutral nodes' charge rows)
+    this.t = new Float64Array(N + 1);
+    this.x = new Float64Array(N + 1);
+    this.reset();
+  }
+
+  // Afresh for an assembly; `rate` multiplies storage in captured rows (1/dt).
+  reset(rate = 0) {
+    this.rate = rate;
+    this.nn = this.ns = this.nd = 0;
+    this.dead.fill(0);
+    this.combos.length = 0;
+  }
+
+  node(i, p, z, mass, charge) {
+    const k = this.nn++;
+    this.nI[k] = i;
+    this.nP[k] = p;
+    this.nZ[k] = z;
+    this.nMass[k] = mass;
+    this.nCharge[k] = charge;
+  }
+
+  segment(iL, iR, pL, pR, z, a, b, d) {
+    const k = this.ns++;
+    this.sI[4 * k] = iL;
+    this.sI[4 * k + 1] = iR;
+    this.sI[4 * k + 2] = pL;
+    this.sI[4 * k + 3] = pR;
+    this.sZ[k] = z;
+    this.sC[3 * k] = a;
+    this.sC[3 * k + 1] = b;
+    this.sC[3 * k + 2] = d;
+  }
+
+  displacement(pL, pR, k) {
+    const q = this.nd++;
+    this.dI[2 * q] = pL;
+    this.dI[2 * q + 1] = pR;
+    this.dK[q] = k;
+  }
+
+  kill(row) {
+    this.dead[row] = 1;
+  }
+
+  combine(rk, ri, w) {
+    this.combos.push([rk, ri, w]);
+  }
+
+  // into[col] += w × row's coefficients, the steady ones plus `mass` times the storage's (a row
+  // captured as plain entries: a contact's current, read before its row is replaced).
+  capture(row, w, mass, into) {
+    const N = this.N, add = (col, v) => {
+      if (col < N && v !== 0) into[col] += w * v;
+    };
+    for (let k = 0; k < this.nn; k++) {
+      const i = this.nI[k], p = this.nP[k], z = this.nZ[k];
+      let f = 0;
+      if (row === i) f += mass * this.nMass[k];
+      if (row === p) f += this.nCharge[k];
+      if (f === 0) continue;
+      add(i, f);
+      add(p, -z * f);
+    }
+    for (let k = 0; k < this.ns; k++) {
+      const iL = this.sI[4 * k], iR = this.sI[4 * k + 1];
+      const s = row === iL ? 1 : row === iR ? -1 : 0;
+      if (s === 0) continue;
+      const z = this.sZ[k], a = this.sC[3 * k], b = this.sC[3 * k + 1], d = this.sC[3 * k + 2];
+      add(iL, s * (a - b));
+      add(iR, s * b);
+      add(this.sI[4 * k + 2], s * (-z * a - d));
+      add(this.sI[4 * k + 3], s * d);
+    }
+    for (let q = 0; q < this.nd; q++) {
+      const pL = this.dI[2 * q], pR = this.dI[2 * q + 1], s = row === pL ? 1 : row === pR ? -1 : 0;
+      if (s === 0) continue;
+      add(pL, s * this.dK[q]);
+      add(pR, -s * this.dK[q]);
+    }
+  }
+
+  // out += (steady terms) × v + mass × (storage terms) × v, over the live rows. v is read over
+  // its first N entries; transformed (the solver's charge rows), it's mapped back by the caller.
+  apply(v, out, steady = 1, mass = 0) {
+    const { N, t, x } = this;
+    for (let j = 0; j < N; j++) x[j] = v[j];
+    x[N] = 0;
+    t.fill(0);
+    const { nI, nP, nZ, nMass, nCharge } = this;
+    for (let k = 0; k < this.nn; k++) {
+      const i = nI[k], p = nP[k], w = x[i] - nZ[k] * x[p];
+      t[i] += mass * nMass[k] * w;
+      t[p] += steady * nCharge[k] * w;
+    }
+    if (steady !== 0) {
+      const { sI, sZ, sC, dI, dK } = this;
+      for (let k = 0; k < this.ns; k++) {
+        const iL = sI[4 * k], iR = sI[4 * k + 1], pL = sI[4 * k + 2], pR = sI[4 * k + 3];
+        const dN = steady * (sC[3 * k] * (x[iL] - sZ[k] * x[pL]) + sC[3 * k + 1] * (x[iR] - x[iL]) + sC[3 * k + 2] * (x[pR] - x[pL]));
+        t[iL] += dN;
+        t[iR] -= dN;
+      }
+      for (let q = 0; q < this.nd; q++) {
+        const pL = dI[2 * q], pR = dI[2 * q + 1], dD = -steady * dK[q] * (x[pR] - x[pL]);
+        t[pL] += dD;
+        t[pR] -= dD;
+      }
+    }
+    for (let j = 0; j < N; j++) if (this.dead[j]) t[j] = 0;
+    for (const [rk, ri, w] of this.combos) t[rk] += w * t[ri];
+    for (let j = 0; j < N; j++) out[j] += t[j];
+    return out;
+  }
+}

package/src/index.js

@@ -1,6 +1,6 @@
 // driftlet: 1D drift–diffusion–reaction solver.
 
-import { normalizeDevice } from './device.js';
+import { normalizeDevice, DeviceError } from './device.js';
 import { Solver, SolverError } from './solver.js';
 import { makeSolution } from './solution.js';
 import { merge } from './merge.js';
@@ -64,20 +64,32 @@ export class Device {
 
   /**
    * 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'
+   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
+   * `{ ports: { gate: { V: 0.2 } } }` (an array replaces them all). 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.
+    // A terminal given a new kind of drive drops the old one: { I: 0 } replaces a held V.
+    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
     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 } } };
+      if (c && typeof c === 'object') patch = { ...patch, contacts: { ...patch.contacts, [side]: redrive(c) } };
+    }
+    // Ports: an array replaces them all; an object patches them by name, { gate: { V: 0.2 } }.
+    const ports = patch?.ports;
+    if (ports !== undefined && !Array.isArray(ports)) {
+      if (ports === null || typeof ports !== 'object') throw new DeviceError('set: ports must be an array (replacing them all) or an object of patches by port name, e.g. { gate: { V: 0.2 } }');
+      const old = this.def.ports ?? [];
+      for (const name of Object.keys(ports)) {
+        if (!old.some((p, k) => (p.name ?? `ports[${k}]`) === name)) throw new DeviceError(`set: ports.${name}: no port named '${name}'${old.length ? ` (the ports: ${old.map((p, k) => p.name ?? `ports[${k}]`).join(', ')})` : ''}`);
       }
+      patch = { ...patch, ports: old.map((p, k) => {
+        const q = ports[p.name ?? `ports[${k}]`];
+        return q === undefined ? p : merge(p, redrive(q));
+      }) };
     }
     const def = merge(this.def, patch);
     // Only the terminals' drives changed: update them in place, keeping the solver and its state
@@ -97,6 +109,10 @@ export class Device {
     if (old && old.u.length === solver.u.length && old.n === solver.n) {
       solver.u.set(old.u);
       solver.uLo.set(old.uLo);
+      // A node newly on an electrode's surface (a window moved, a surface added) starts at its
+      // starting coverages, not at whatever its slots held.
+      const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
+      for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
       solver.computeConcentrations();
       solver.time = old.time;
       solver.contactDEnd = old.contactDEnd;

package/src/solution.js

@@ -193,8 +193,14 @@ export function makeSolution(solver, result = {}) {
       );
     }
   });
-  const cond = solver.conditioning;
-  if (result.converged === false && cond && cond.digits > 12) {
+  const cond = solver.conditioning, un = solver.unreached;
+  if (result.converged === false && un) {
+    const [[V0, I0], [V1, I1]] = [un.low, un.high], g = (x) => x.toPrecision(3), A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    sol.warnings.push(
+      `${un.terminal}: no steady state passes the driven current ${g(un.target)} ${A}; held from ${g(V0)} V to ${g(V1)} V ` +
+        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.`,
+    );
+  } else if (result.converged === false && cond && cond.digits > 12) {
     const digits = Number.isFinite(cond.digits) ? `lost ${cond.digits.toFixed(0)} of its ~16 digits` : 'was exactly singular';
     sol.warnings.push(
       `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): part of the device is held ` +