driftlet 0.9.0 → 0.11.4

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

@@ -24,9 +24,9 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  * - **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.
+ *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) (mol/s if the device
+ *   isn't planar) 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
@@ -75,10 +75,13 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
   return { ok, items, text };
 }
 
+// The units of totals through the cross-section: per m² of a planar device, or whole.
+const unitsOf = (model) => (model.geometry.type === 'planar' ? { rate: 'mol/(m²·s)', current: 'A/m²', charge: 'C/m²' } : { rate: 'mol/s', current: 'A', charge: 'C' });
+
 // Each species' steady ledger: in through the terminals, made by the reactions. Rates in
-// mol/(m²·s), positive into the device or made.
+// mol/(m²·s) (mol/s if not planar), positive into the device or made.
 function balance(device, sol) {
-  const { model, def } = device, { species, regions, interfaces } = model;
+  const { model, def } = device, { species, regions, interfaces } = model, units = unitsOf(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
@@ -93,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
@@ -109,22 +114,26 @@ 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) => {
+    // A face's flux and rates are per area; everything else here is a total, through A there.
+    const Af = model.grid.area[model.grid.regionEnd[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];
+      const N = Af * 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);
+      const rate = Af * sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
+      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.
@@ -135,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) {
@@ -147,14 +158,14 @@ function balance(device, sol) {
     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²)` : '');
+    const amp = (r) => (l.z !== 0 ? ` (${sig(FARADAY * Math.abs(l.z) * r)} ${units.current})` : '');
     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`;
+      : `${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, ${units.rate}, + 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 } };
@@ -162,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)));
@@ -172,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;
@@ -223,15 +235,17 @@ function gridCheck(device, sol, tol, gross) {
     }),
   };
   // Started from this solution, interpolated onto the finer grid; failing that, from cold.
-  let other;
+  let other, otherGrid;
   try {
     const dev = new Device(fine);
     dev.solver._warmFrom(device.solver);
     other = dev.solve();
+    otherGrid = dev.model.grid;
     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();
+      otherGrid = cold.model.grid;
     }
   } catch (e) {
     return { name: 'grid', ok: null, summary: `couldn't solve the refined device (${e.message})` };
@@ -242,7 +256,7 @@ function gridCheck(device, sol, tol, gross) {
   // 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²' });
+  if (gross > 0) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: unitsOf(model).current });
   // 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) => {
@@ -251,33 +265,30 @@ function gridCheck(device, sol, tol, gross) {
       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) => {
+  // Each region's charge, against the largest: summed over the nodes' boxes, as the solver's
+  // Gauss law counts it.
+  const charges = (s, grid) => 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);
-    }
+    for (let g = 0; g < s.x.length; g++) if (s.region[g] === r) q += rho(s, g, model, r) * grid.vol[g];
     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;
+    let q = 0, v = 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);
+      v += model.grid.vol[g];
     }
-    return q * (reg.x1 - reg.x0);
+    return q * v;
   }));
-  const qa = charges(sol), qb = charges(other), scaleQ = Math.max(0, ...qa.map(Math.abs), ...qb.map(Math.abs));
+  const qa = charges(sol, model.grid), qb = charges(other, otherGrid), 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²' }));
+    qa.forEach((a, r) => diffs.push({ what: `${named(sol.regions[r])} charge`, a, b: qb[r], rel: Math.abs(qb[r] - a) / scaleQ, unit: unitsOf(model).charge }));
   }
   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)' };

package/src/describe.js

@@ -27,10 +27,11 @@ function equation(...maps) {
   return `${lhs.join(' + ') || '0'} = ${rhs.join(' + ') || '0'}`;
 }
 
-function drive(c) {
+// (Per m² of a planar device; a whole one's current and resistance otherwise.)
+function drive(c, planar) {
   const v = (x) => (isObject(x) ? 'a waveform' : `${num(x)}`);
-  if (c?.I !== undefined) return `driven at I = ${v(c.I)} A/m²`;
-  if (c?.R !== undefined) return `a source of ${v(c.V ?? 0)} V behind R = ${num(c.R)} Ω·m²`;
+  if (c?.I !== undefined) return `driven at I = ${v(c.I)} ${planar ? 'A/m²' : 'A'}`;
+  if (c?.R !== undefined) return `a source of ${v(c.V ?? 0)} V behind R = ${num(c.R)} ${planar ? 'Ω·m²' : 'Ω'}`;
   return `held at ${v(c?.V ?? 0)} V`;
 }
 
@@ -86,8 +87,8 @@ export function unitWarnings(def) {
       }
     }
   });
-  const capacitance = (path, phi) => {
-    if (isObject(phi) && phi.C > 10) warn(`${path}.phi.C`, `${num(phi.C)} F/m² is over 1000 µF/cm²; C is F/m² (1 µF/cm² = 0.01 F/m²)`);
+  const capacitance = (path, C) => {
+    if (C > 10) warn(path, `${num(C)} F/m² is over 1000 µF/cm²; C is F/m² (1 µF/cm² = 0.01 F/m²)`);
   };
   const kinetics = (path, reactions) => {
     (reactions ?? []).forEach((rx, k) => {
@@ -96,13 +97,18 @@ export function unitWarnings(def) {
   };
   (def.interfaces ?? []).forEach((f, k) => {
     if (!isObject(f)) return;
-    capacitance(`interfaces[${k}]`, f.phi);
+    capacitance(`interfaces[${k}].phi.C`, f.phi?.C);
     kinetics(`interfaces[${k}]`, f.reactions);
   });
+  (def.ports ?? []).forEach((p, k) => {
+    if (!isObject(p)) return;
+    capacitance(`ports[${k}].capacitance.C`, p.capacitance?.C);
+    kinetics(`ports[${k}]`, p.reactions);
+  });
   for (const side of ['left', 'right']) {
     const c = def.contacts?.[side];
     if (!isObject(c)) continue;
-    capacitance(`contacts.${side}`, c.phi);
+    capacitance(`contacts.${side}.phi.C`, c.phi?.C);
     for (const [sname, v] of Object.entries(c.bath?.c ?? {})) conc(`contacts.${side}.bath.c.${sname}`, v);
     if (typeof c.V === 'number' && Math.abs(c.V) > 50) warn(`contacts.${side}.V`, `${c.V} V is a very large bias; voltages are V`);
   }
@@ -209,11 +215,11 @@ export function describe(def) {
     const ct = model.contacts[side];
     const linked = species.filter((sp, i) => ct.species[i].type !== 'blocked').map((sp) => sp.name);
     const term = ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
-    lines.push(`  ${side}: ${drive(cdef)}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
+    lines.push(`  ${side}: ${drive(cdef, model.geometry.type === 'planar')}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
   }
   (def.ports ?? []).forEach((p, k) => {
     const port = model.ports[k];
-    lines.push(`  port ${port.name}: ${drive(p)}, in ${regions[port.region].name}`);
+    lines.push(`  port ${port.name}: ${drive(p, model.geometry.type === 'planar')}, in ${regions[port.region].name}`);
     // an electrode spread through the window
     if (port.reactions.length) lines.push(`    an electrode (its ${species[port.terminal].name} at the port's level), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} of it per m³, reacting:`);
     for (const rx of p.reactions ?? []) lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${rx.alpha}${rx.bare ? ', on bare metal' : ''}`);

package/src/device.js

@@ -312,10 +312,7 @@ export function normalizeDevice(def) {
     need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
     ct.passes = passes;
   }
-  need(
-    terminals.some((t) => t.drive.kind === 'V'),
-    'every terminal is driven by a current, so the device\'s overall level floats: hold at least one at a voltage V',
-  );
+  checkLevel(terminals.map((t) => t.drive), terminals.map((t) => (t.kind === 'port' ? ports[t.index] : contacts[t.side])));
 
   // --- grid
   if (def.grid !== undefined) {
@@ -568,6 +565,20 @@ function normalizeSource(v, path) {
   return { t: Float64Array.from(v.t), values: Float64Array.from(v.values), repeat: v.repeat === true };
 }
 
+// Something must hold the device's overall level: a terminal held at a voltage, and if any is
+// driven by a current, one held that passes current (one that passes none, a closed end, ties the
+// level of nothing, and the driven terminal's voltage would float with φ).
+function checkLevel(drives, owners) {
+  need(drives.some((d) => d.kind === 'V'), "every terminal is driven by a current, so the device's overall level floats: hold at least one at a voltage V");
+  const driven = drives.findIndex((d) => d.kind === 'I');
+  if (driven < 0) return;
+  const name = (k) => (k < 2 ? `contacts.${k === 0 ? 'left' : 'right'}` : `ports[${k - 2}]`);
+  need(
+    drives.some((d, k) => d.kind === 'V' && owners[k].passes),
+    `${name(driven)} is driven by a current, but no terminal held at a voltage passes any, so nothing fixes the level its voltage is read against: hold one that does (the port of an electrode at V: 0, say: at the only electrode of a device, the same as I: 0)`,
+  );
+}
+
 /**
  * The terminals' drives alone (in terminal order: left, right, then the ports), from a definition
  * whose structure is unchanged: for a fast update of sources.
@@ -582,7 +593,7 @@ export function normalizeDrives(def, model) {
     need(model.contacts[side].passes || drives[k].kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
   }
   model.ports.forEach((port, k) => need(port.passes || drives[2 + k].kind === 'V', `ports[${k}].I: this port passes no current (it exchanges only neutral species), so give it no drive`));
-  need(drives.some((d) => d.kind === 'V'), "every terminal is driven by a current, so the device's overall level floats: hold at least one at a voltage V");
+  checkLevel(drives, [model.contacts.left, model.contacts.right, ...model.ports]);
   return drives;
 }
 

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;
@@ -107,15 +123,27 @@ export class Device {
         for (const k of solver.floating) if (old.terms[k].name === solver.terms[k].name) solver.termV[k] = old.termV[k];
       }
       // What each stretch conserves from here: a stretch that was closed and still is (same
-      // species, same regions) keeps its amount; any other (newly closed, split, merged, open)
-      // starts from what the carried state holds.
+      // species, same regions, same boxes) keeps its amount; any other (newly closed, split,
+      // merged, open, or with its boxes resized by a new grid or geometry) starts from what the
+      // carried state holds.
       const key = (st) => `${st.species}:${st.regions[0]}-${st.regions[1]}`;
       const before = new Map(old.stretches.map((st, k) => [key(st), k]));
+      const va = old.model.grid.vol, vb = model.grid.vol, sameBoxes = va.length === vb.length && va.every((v, g) => v === vb[g]);
       solver.referenceAmounts = solver.stretches.map((st) => {
         const k = before.get(key(st));
-        return k !== undefined && !old.stretches[k].connected && !st.connected ? old.referenceAmounts[k] + old.boundaryIntake[k] : solver.amount(st);
+        return sameBoxes && k !== undefined && !old.stretches[k].connected && !st.connected ? old.referenceAmounts[k] + old.boundaryIntake[k] : solver.amount(st);
       });
       solver.boundaryIntake.fill(0);
+      // Each surface's reference likewise: kept where its window and the boxes are unchanged.
+      const sameSurface = (j) => {
+        const [k, q] = solver.surfCols[j], o = old.surfCols.findIndex(([kk, qq]) => old.model.ports[kk].name === model.ports[k].name && qq === q);
+        const a = old.model.ports[old.surfCols[o]?.[0]], b = model.ports[k];
+        return o >= 0 && a.surface[q].name === b.surface[q].name && a.nodes.length === b.nodes.length && a.nodes.every((g, w) => g === b.nodes[w]) ? o : -1;
+      };
+      solver.surfaceRef = Float64Array.from(solver.surfCols, (_, j) => {
+        const o = sameBoxes ? sameSurface(j) : -1;
+        return o >= 0 ? old.surfaceRef[o] : solver.surfaceAmount(j);
+      });
     }
     return this;
   }
@@ -190,7 +218,7 @@ export class Device {
    */
   _checkpoint() {
     const solver = this.solver;
-    return { def: this.def, model: this.model, solver, snap: solver._snapshot(), solvedV: solver.solvedV, referenceAmounts: solver.referenceAmounts.slice() };
+    return { def: this.def, model: this.model, solver, snap: solver._snapshot(), solvedV: solver.solvedV, referenceAmounts: solver.referenceAmounts.slice(), surfaceRef: solver.surfaceRef.slice() };
   }
 
   /**
@@ -208,6 +236,7 @@ export class Device {
     cp.solver._restore(cp.snap);
     cp.solver.solvedV = cp.solvedV;
     cp.solver.referenceAmounts = cp.referenceAmounts.slice();
+    cp.solver.surfaceRef = cp.surfaceRef.slice();
   }
 
   /**