driftlet 0.8.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,14 +215,16 @@ 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}`);
+    for (const rx of p.reactions ?? []) lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${rx.alpha}${rx.bare ? ', on bare metal' : ''}`);
+    if (port.capacitance) lines.push(`    a capacitance of ${num(port.capacitance.C)} F/m² through the window (zero charge at ${num(port.capacitance.zeroCharge)} V), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} per m³`);
+    if (port.surface.length) lines.push(`    its surface: ${port.surface.map((sp) => sp.name).join(', ')} on ${num(port.surface[0].capacity)} mol/m² of sites (Langmuir)`);
   });
   if ((def.bulkReactions ?? []).length) {
     lines.push('bulk reactions:');

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) {
@@ -351,6 +348,15 @@ export function normalizeDevice(def) {
     need(nodes.length > 0, `ports[${k}]: the window [${port.from}, ${port.to}] m holds no grid node; widen it or refine the grid`);
     port.nodes = Int32Array.from(nodes);
   });
+  // A node's surface belongs to one electrode.
+  const surfaced = new Int32Array(grid.nNodes).fill(-1);
+  ports.forEach((port, k) => {
+    if (port.surface.length === 0) return;
+    for (const g of port.nodes) {
+      need(surfaced[g] < 0, `ports[${k}]: its window overlaps ports[${surfaced[g]}]'s, and both have a surface; a spot of metal has one surface`);
+      surfaced[g] = k;
+    }
+  });
 
   return {
     T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports, geometry,
@@ -559,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.
@@ -573,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;
 }
 
@@ -649,7 +669,7 @@ function normalizeGeometry(g) {
 // the window, `area` (m²/m³) of it per volume.
 function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT) {
   need(isObject(pdef), `${path} must be an object`);
-  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -666,8 +686,11 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     need(speciesIndex.has(pdef.terminal), `${path}.terminal: unknown species ${JSON.stringify(pdef.terminal)}${known(speciesIndex)}`);
     terminal = speciesIndex.get(pdef.terminal);
   }
-  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT);
-  need(pdef.species === undefined ? reactions.length > 0 : isObject(pdef.species), `${path}.species must map species names to port links`);
+  const surface = portSurface(pdef, path, speciesIndex);
+  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface);
+  surface.forEach((sp, s) => need(reactions.some((rx) => rx.part.some((p) => p.side === 2 && p.s === s)), `${path}.surface.${sp.name}: no reaction of the port makes or uses it`));
+  const capacitance = portCapacitance(pdef, path, mat);
+  need(pdef.species === undefined ? reactions.length > 0 || capacitance !== null : isObject(pdef.species), `${path}.species must map species names to port links`);
   const links = species.map(() => ({ type: 'blocked' }));
   for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
     const lpath = `${path}.species.${sname}`;
@@ -697,48 +720,94 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     if (link.type === 'exchange') level.k = positive(link.k, `${lpath}.k (mol/(m³·s))`);
     links[i] = { type: link.type, ...level };
   }
-  need(links.some((l) => l.type !== 'blocked') || reactions.length > 0, `${path}.species: the port exchanges no species`);
+  need(links.some((l) => l.type !== 'blocked') || reactions.length > 0 || capacitance !== null, `${path}.species: the port exchanges no species`);
   // One that exchanges only neutral species (an O₂ supply) carries no current, so its voltage is
   // nobody's business: it can't be driven by one.
-  const passes = reactions.length > 0 || links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
+  const passes = reactions.length > 0 || capacitance !== null || links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
   need(passes || drive.kind === 'V', `${path}.I: this port passes no current (it exchanges only neutral species), so give it no drive`);
   let area = null;
-  if (reactions.length > 0) {
+  if (reactions.length > 0 || capacitance !== null) {
     need(pdef.area !== undefined, `${path}.area: give the electrode's area per volume of the window (m²/m³, e.g. 1/h for a film of thickness h on it), a number or a profile`);
     area = typeof pdef.area === 'number' ? { value: positive(pdef.area, `${path}.area (m²/m³)`) } : profile(pdef.area, `${path}.area`, 'areas per volume (m²/m³)', (a) => a >= 0, 'an area per volume ≥ 0');
-  } else need(pdef.area === undefined, `${path}.area: only a port with reactions has an electrode area`);
-  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area };
+  } else need(pdef.area === undefined, `${path}.area: only an electrode (a port with reactions or a capacitance) has an area`);
+  need(surface.length === 0 || reactions.length > 0, `${path}.surface: only an electrode (a port with reactions) has a surface`);
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area, surface, capacitance };
+}
+
+// A capacitance spread through the window: a gate along a channel, an electrode's double layer.
+// Per area of electrode it holds σ = C (V − zeroCharge − φ) on the port's side, and the window
+// the opposite: the region's charge balance (Gauss's law, or neutrality at ε = 0) gains aσ.
+function portCapacitance(pdef, path, mat) {
+  if (pdef.capacitance === undefined) return null;
+  const cpath = `${path}.capacitance`;
+  need(isObject(pdef.capacitance), `${cpath} must be { C, zeroCharge }`);
+  fields(pdef.capacitance, cpath, ['C', 'zeroCharge']);
+  need(!mat.conductor && !mat.phiFree, `${cpath}: a capacitance couples to φ, which a ${mat.conductor ? 'conductor' : 'region with no free charge'} doesn't have`);
+  return { C: positive(pdef.capacitance.C, `${cpath}.C (F/m² of electrode)`), zeroCharge: pdef.capacitance.zeroCharge === undefined ? 0 : finite(pdef.capacitance.zeroCharge, `${cpath}.zeroCharge (V)`) };
+}
+
+// An electrode port's surface species: coverages θ of its sites (Langmuir: each takes one site,
+// μ = μ° + RT ln(θ/θ₀) with θ₀ = 1 − Σθ the bare fraction), Γ mol of sites per m² of electrode.
+function portSurface(pdef, path, speciesIndex) {
+  if (pdef.surface === undefined) return [];
+  need(isObject(pdef.surface), `${path}.surface must map surface species to { mu0, capacity, theta0 }`);
+  const list = Object.entries(pdef.surface).map(([name, d]) => {
+    const spath = `${path}.surface.${name}`;
+    need(!speciesIndex.has(name), `${spath}: '${name}' is a species of the device; a surface species is the port's own, with its own name`);
+    need(isObject(d), `${spath} must be { mu0, capacity, theta0 }`);
+    fields(d, spath, ['mu0', 'capacity', 'theta0']);
+    const theta0 = d.theta0 === undefined ? 1e-6 : positive(d.theta0, `${spath}.theta0`);
+    return { name, mu0: finite(d.mu0, `${spath}.mu0 (J/mol)`), capacity: positive(d.capacity, `${spath}.capacity (mol of sites per m² of electrode)`), theta0 };
+  });
+  need(list.length > 0, `${path}.surface: give at least one surface species, or leave it out`);
+  const caps = new Set(list.map((sp) => sp.capacity));
+  need(caps.size === 1, `${path}.surface: the species share the electrode's sites, so give them one capacity`);
+  need(list.reduce((t, sp) => t + sp.theta0, 0) < 1, `${path}.surface: the starting coverages (theta0) must sum to less than 1`);
+  return list;
 }
 
 // A port's reactions: Butler–Volmer, as at a face, between species of the port's region and the
 // port's terminal species (a metal's carrier, activity 1, at the port's level), per area of the
 // electrode: part side 0 for the region's species, side 1 for the carrier.
-function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT) {
+function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface = []) {
   need(pdef.reactions === undefined || Array.isArray(pdef.reactions), `${path}.reactions must be an array`);
   const list = pdef.reactions ?? [];
   if (list.length === 0) return [];
   need(!mat.conductor, `${path}.reactions: a port on a conductor is a wire; reactions belong on a face, or on a port in the solution`);
+  // The metal's countercharge (each spot's double layer) is below the grid, so the solution
+  // beside it must be neutral, as in porous-electrode theory; with ε > 0 the reactions would
+  // leave a net charge with nothing to balance it.
+  need(mat.epsr === 0 || mat.phiFree, `${path}.reactions: an electrode spread through a window needs its region strictly neutral (ε = 0): its double layers are below the grid`);
   need(terminal !== null && species[terminal].z !== 0, `${path}.terminal: a port with reactions needs its electrode's carrier as its terminal species (e.g. 'e-')`);
   need(!mat.present[terminal], `${path}.terminal: '${species[terminal].name}' is in the port's region too, so a reaction can't tell the electrode's from the region's`);
   const carrier = species[terminal].name;
   return list.map((rdef, k) => {
     const rpath = `${path}.reactions[${k}]`;
     need(isObject(rdef) && typeof rdef.equation === 'string', `${rpath} must be { equation, fixed, k0, alpha }`);
-    fields(rdef, rpath, ['equation', 'fixed', 'k0', 'alpha']);
+    fields(rdef, rpath, ['equation', 'fixed', 'k0', 'alpha', 'bare']);
     const holds = (name) => speciesIndex.has(name) && Boolean(mat.present[speciesIndex.get(name)]);
-    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier, conductor: true }, rdef.fixed, `${rpath}.equation`);
+    const onSurface = (name) => surface.findIndex((sp) => sp.name === name);
+    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier || onSurface(name) >= 0, conductor: true }, rdef.fixed, `${rpath}.equation`);
     const part = [];
     let fixedA = 0, charge = 0;
-    for (const [key, side] of [['left', 0], ['right', 1]]) {
-      const st = stoichiometry(sides[key], `${rpath}.equation`, rdef.fixed, `${rpath}.fixed`, species, speciesIndex, RT);
+    // The electrode's side: its carrier, and its surface species (side 2, neutral, by index s).
+    const electrode = {};
+    for (const [name, nu] of Object.entries(sides.right)) {
+      const s = onSurface(name);
+      if (s >= 0) part.push({ s, nu, side: 2 });
+      else electrode[name] = nu;
+    }
+    for (const [map, side] of [[sides.left, 0], [electrode, 1]]) {
+      const st = stoichiometry(map, `${rpath}.equation`, rdef.fixed, `${rpath}.fixed`, species, speciesIndex, RT);
       for (const { i, nu } of st.list) part.push({ i, nu, side });
       fixedA += st.fixedA;
       charge += st.charge;
     }
     need(part.some((p) => p.side === 1), `${rpath}: no '${carrier}' from the electrode takes part`);
-    need(part.some((p) => p.side === 0), `${rpath}: no species of the port's region takes part`);
+    need(part.some((p) => p.side === 0 || p.side === 2), `${rpath}: no species of the port's region or its surface takes part`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
-    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`) };
+    need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
   });
 }
 
@@ -762,7 +831,7 @@ function checkAnchors(regions, materials, interfaces, contacts, species, ports =
   const anchored = new Set();
   if (anchors(contacts.left)) anchored.add(find(0));
   if (anchors(contacts.right)) anchored.add(find(nR - 1));
-  for (const port of ports) if (port.reactions.length > 0 || port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
+  for (const port of ports) if (port.reactions.length > 0 || port.capacitance || port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
   for (let r = 0; r < nR; r++) {
     const mat = materials[regions[r].material];
     const charged = species.some((sp, i) => mat.present[i] && sp.z !== 0);

package/src/index.js

@@ -100,21 +100,34 @@ export class Device {
       solver.computeConcentrations();
       solver.time = old.time;
       solver.contactDEnd = old.contactDEnd;
+      if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)
       // Floating terminals keep their voltages (a good start), where the terminals match.
       if (old.terms.length === solver.terms.length) {
         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;
   }
@@ -189,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() };
   }
 
   /**
@@ -207,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,15 +21,18 @@ 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;
+  let reactions, nodeOf, carrier, names, surface = null; // (an electrode port's coverages at the spot)
   if (where?.face !== undefined) {
     const f = where.face, itf = model.interfaces[f];
     if (!itf) fail(`polarization: no face ${f} (the device has ${model.interfaces.length})`);
@@ -49,22 +52,34 @@ export function polarization(device, sol, where, V) {
     if (where.x !== undefined) for (const h of port.nodes) if (Math.abs(grid.x[h] - where.x) < Math.abs(grid.x[g] - where.x)) g = h;
     carrier = { side: 1, i: port.terminal };
     nodeOf = () => g;
+    if (port.surface.length > 0) {
+      const w = port.nodes.indexOf(g), theta = port.surface.map((sp) => sol.ports[k].coverage[sp.name][w]);
+      surface = { sp: port.surface, theta, bare: sol.ports[k].bare[w] };
+    }
     reactions = port.reactions;
     names = device.def.ports?.[k]?.reactions;
   } 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: μ = μ° + 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) {
         s -= (p.nu * species[p.i].z * FARADAY) / RT;
         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) {
@@ -72,13 +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`);
-    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

@@ -107,11 +107,29 @@ export function makeSolution(solver, result = {}) {
       current += F * species[i].z * solver.portFlux[k][i];
     }
     const out = { name: port.name, V: solver.termV[2 + k], flux, current };
-    if (port.reactions.length > 0) {
-      // An electrode spread through the window: where it sits, and each reaction's rate there.
+    if (port.capacitance) {
+      // 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]);
       out.area = Float64Array.from(solver.portArea[k]);
+    }
+    if (port.reactions.length > 0) {
+      // An electrode spread through the window: each reaction's rate at its nodes.
       out.rates = solver.portRates[k].map((r) => Float64Array.from(r)); // mol/(m²·s), forward
+      // its surface: each species' coverage θ at each node of the window
+      if (port.surface.length > 0) {
+        out.coverage = Object.fromEntries(port.surface.map((sp, q) => [sp.name, Float64Array.from(port.nodes, (g) => solver.th[g * solver.nSurf + q])]));
+        out.bare = Float64Array.from(port.nodes, (g) => solver.th0[g]); // θ₀, to full precision however covered
+      }
     }
     return out;
   });
@@ -163,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';