driftlet 0.9.0 → 0.10.0

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
@@ -114,16 +117,18 @@ function balance(device, sol) {
     });
   });
   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}`;
+      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);
     });
   });
@@ -147,14 +152,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 } };
@@ -223,15 +228,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 +249,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 +258,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/index.js

@@ -107,15 +107,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 +202,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 +220,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();
   }
 
   /**

package/src/polarization.js

@@ -21,12 +21,15 @@ const fail = (message) => {
  * @param {{ face: number } | { port: string | number, x?: number }} where a face's index, or a port
  *   (name or index) and the position in its window (m, the device's x; default its first node)
  * @param {number | ArrayLike<number>} V the metal's level(s), V
- * @returns {{ V: Float64Array, current: Float64Array, reactions: { equation: string, level: number,
+ * @param {{ surface?: 'held' | 'equilibrium' }} [opts] an electrode port's surface coverages: held as
+ *   in `sol` (the default: this instant's curves), or in equilibrium at each V (the steady-state
+ *   curve, with a passive film's active–passive peak), each species by the reaction that makes it
+ * @returns {{ V: Float64Array, current: Float64Array, bare?: Float64Array, reactions: { equation: string, level: number,
  *   rate: Float64Array, current: Float64Array }[] }} per reaction: its equilibrium level here (where
  *   its rate is zero), its rate (mol/(m²·s) of electrode, forward) and its current (A/m², anodic
  *   positive: into the solution); and their sum
  */
-export function polarization(device, sol, where, V) {
+export function polarization(device, sol, where, V, opts = {}) {
   const model = device.model, { species, grid, RT } = model, solver = device.solver;
   const Vs = Float64Array.from(typeof V === 'number' ? [V] : V);
   let reactions, nodeOf, carrier, names, surface = null; // (an electrode port's coverages at the spot)
@@ -58,16 +61,17 @@ export function polarization(device, sol, where, V) {
   } else fail('polarization: say where, { face: f } or { port: name, x }');
   if (reactions.length === 0) fail('polarization: no reactions there');
 
-  const out = reactions.map((rx, k) => {
+  // Each reaction as a = base + s·V − Σ ν_s ln a_s (the surface species' activities apart), with
+  // its prefactor apart from them too, so a surface can be held or re-equilibrated at each V.
+  const parts = reactions.map((rx, k) => {
     if (rx.srh) fail('polarization: SRH kinetics has no electrode level');
-    // a = A/RT = a0 + s·V: everything but the carrier at its level, and the carrier's part.
-    let a0 = rx.fixedA, s = 0, q = 0, pref = rx.vmax ? rx.vmax : rx.k0;
+    let base = rx.fixedA, s = 0, q = 0, pref = rx.vmax ? rx.vmax : rx.k0;
+    const surf = [];
     rx.part.forEach((p, x) => {
       if (p.side === 2) {
-        // a surface species, at activity θ/θ₀ (μ = μ° + RT ln(θ/θ₀))
-        const ln = Math.log(surface.theta[p.s] / surface.bare), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
-        a0 -= (p.nu * (surface.sp[p.s].mu0 / RT + ln));
-        pref *= Math.exp(e * ln);
+        // a surface species: μ = μ° + RT ln a, a = θ/θ₀
+        base -= (p.nu * surface.sp[p.s].mu0) / RT;
+        surf.push({ s: p.s, nu: p.nu, e: p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha });
         return;
       }
       if (p.side === carrier.side && p.i === carrier.i) {
@@ -75,7 +79,7 @@ export function polarization(device, sol, where, V) {
         return;
       }
       const g = nodeOf(p), name = species[p.i].name;
-      a0 -= (p.nu * sol.mu[name][g]) / RT;
+      base -= (p.nu * sol.mu[name][g]) / RT;
       q += p.side === carrier.side ? 0 : p.nu * species[p.i].z; // charge the forward reaction puts into the solution
       const c = sol.c[name][g];
       if (rx.vmax) {
@@ -83,14 +87,45 @@ export function polarization(device, sol, where, V) {
       } else pref *= powr(c / solver.cRef[g * species.length + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
     });
     if (s === 0) fail(`polarization: reaction ${k} there takes no ${species[carrier.i].name} from the metal`);
-    if (rx.bare) pref *= surface ? surface.bare : 1; // on bare metal only
-    const rate = Float64Array.from(Vs, (v) => {
-      const a = a0 + s * v;
-      return rx.vmax ? pref * -Math.expm1(-a) : pref * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
+    return { rx, k, base, s, q, pref, surf };
+  });
+  // The surface's activities (ln a) and bare fraction at a level: held as `sol` has them, or in
+  // equilibrium there, each species by the first reaction that makes it from the solution alone.
+  const held = surface && surface.theta.map((t) => Math.log(t / surface.bare));
+  let former = null;
+  if (surface && opts.surface === 'equilibrium') {
+    former = surface.sp.map((sp, x) => {
+      const f = parts.find((pt) => pt.surf.length === 1 && pt.surf[0].s === x);
+      if (!f) fail(`polarization: no reaction makes ${sp.name} from the solution alone, so its equilibrium coverage isn't defined`);
+      return f;
+    });
+  } else if (opts.surface !== undefined && opts.surface !== 'held') fail("polarization: surface must be 'held' (the default) or 'equilibrium'");
+  const surfaceAt = (v) => {
+    if (!surface) return { lnA: [], bare: 1 };
+    // base + s v − ν ln a = 0 for each species' former
+    const lnA = former ? former.map((f) => (f.base + f.s * v) / f.surf[0].nu) : held;
+    if (!former) return { lnA, bare: surface.bare };
+    const m = Math.max(0, ...lnA);
+    let sum = Math.exp(-m);
+    for (const l of lnA) sum += Math.exp(l - m);
+    return { lnA, bare: Math.exp(-m) / sum };
+  };
+  const at = Array.from(Vs, (v) => surfaceAt(v));
+  const out = parts.map(({ rx, k, base, s, q, pref, surf }) => {
+    const rate = Float64Array.from(Vs, (v, j) => {
+      const { lnA, bare } = at[j];
+      let a = base + s * v, p = pref * (rx.bare ? bare : 1);
+      for (const u of surf) {
+        a -= u.nu * lnA[u.s];
+        p *= Math.exp(u.e * lnA[u.s]);
+      }
+      return rx.vmax ? p * -Math.expm1(-a) : p * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
     });
-    return { equation: names?.[k]?.equation ?? `reaction ${k}`, level: -a0 / s, rate, current: rate.map((r) => q * FARADAY * r) };
+    // (its level with the surface as held)
+    const aHeld = surf.reduce((t, u) => t - u.nu * (held ? held[u.s] : 0), base);
+    return { equation: names?.[k]?.equation ?? `reaction ${k}`, level: -aHeld / s, rate, current: rate.map((r) => q * FARADAY * r) };
   });
   const current = new Float64Array(Vs.length);
   for (const r of out) for (let j = 0; j < Vs.length; j++) current[j] += r.current[j];
-  return { V: Vs, current, reactions: out };
+  return { V: Vs, current, ...(surface ? { bare: Float64Array.from(at, (x) => x.bare) } : {}), reactions: out };
 }

package/src/solution.js

@@ -106,17 +106,17 @@ export function makeSolution(solver, result = {}) {
       flux[species[i].name] = solver.portFlux[k][i];
       current += F * species[i].z * solver.portFlux[k][i];
     }
-    if (port.capacitance) {
-      // a capacitance's charging current, and its charge (the port's side), like a gate's
-      const dt = solver.lastDt;
-      current += Number.isFinite(dt) ? (solver.portQ[k] - solver.portQOld[k]) / dt : 0;
-    }
     const out = { name: port.name, V: solver.termV[2 + k], flux, current };
-    if (port.capacitance) out.charge = solver.portQ[k];
     if (port.capacitance) {
-      // its charge per area of electrode at each node, σ = C (V − zeroCharge − φ)
-      const { C: Cs, zeroCharge } = port.capacitance;
-      out.sigma = Float64Array.from(port.nodes, (g) => Cs * (solver.termV[2 + k] - zeroCharge - phi[g]));
+      // A capacitance's charging current, and its charge (the port's side), like a gate's; and
+      // its charge per area of electrode at each node, σ = C (V − zeroCharge − φ) (none at an
+      // end whose φ its contact sets: the contact holds that charge).
+      const dt = solver.lastDt;
+      out.current += Number.isFinite(dt) ? (solver.portQ[k] - solver.portQOld[k]) / dt : 0;
+      out.charge = solver.portQ[k];
+      const { C: Cs, zeroCharge } = port.capacitance, last = model.grid.nNodes - 1;
+      const sets = (side) => ['pinned', 'bulk'].includes(model.contacts[side].phi.type);
+      out.sigma = Float64Array.from(port.nodes, (g) => ((g === 0 && sets('left')) || (g === last && sets('right')) ? 0 : Cs * (solver.termV[2 + k] - zeroCharge - phi[g])));
     }
     if (port.area !== null) {
       out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
@@ -181,6 +181,18 @@ export function makeSolution(solver, result = {}) {
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,
   // gate contacts), check the local Debye length against the adjacent cell.
   sol.warnings = [...(model.warnings ?? [])];
+  // A surface covered almost completely: its coverages' η barely move anything below ~1e-10 bare,
+  // and Newton loses them (a transient can stall there).
+  sol.ports.forEach((p) => {
+    if (!p.bare) return;
+    const min = Math.min(...p.bare);
+    if (min < 1e-10) {
+      sol.warnings.push(
+        `ports ${p.name}: its surface is covered to a bare fraction of ${min.toExponential(1)} at x = ${p.x[p.bare.indexOf(min)].toExponential(3)} m. ` +
+          'Below ~1e-10 the coverage barely affects anything and the solver struggles with it; a passive metal blocks to 1e-3–1e-6, so make the film less stable (raise its μ°).',
+      );
+    }
+  });
   const cond = solver.conditioning;
   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';