driftlet 0.8.0 → 0.10.0

package/src/solver.js

@@ -2,7 +2,9 @@
 // and its derivative g′(a) = α e^{αa} + (1−α) e^{−(1−α)a}.
 function bvFactor(a, alpha) {
   const e = Math.exp(-(1 - alpha) * a);
-  return { g: e * Math.expm1(a), gp: alpha * Math.exp(alpha * a) + (1 - alpha) * e };
+  // (far from equilibrium, the plain difference: the product would give 0·∞ there)
+  const g = Math.abs(a) > 50 ? Math.exp(alpha * a) - e : e * Math.expm1(a);
+  return { g, gp: alpha * Math.exp(alpha * a) + (1 - alpha) * e };
 }
 
 // Solve the K×K complex system (Ar + i Ai) x = (last column), partial pivoting by modulus.
@@ -195,13 +197,16 @@ export class Solver {
     // Slots per block: φ̂ (or D, or a conductor's segment flux J), one per species, and at a face
     // one per face reaction (its rate), as many as the busiest face has.
     const nRx = model.interfaces.reduce((m, itf) => Math.max(m, itf.reactions.length), 0);
-    const M = n + 1 + nRx;
+    // (and at an electrode port's nodes, one per surface species: its coverage's η)
+    const nSurf = model.ports.reduce((m, port) => Math.max(m, port.surface.length), 0);
+    const M = n + 1 + Math.max(nRx, nSurf);
     const nNodes = grid.nNodes;
     const nFaces = regions.length - 1;
     const nB = nNodes + nFaces;
     this.n = n;
     this.M = M;
     this.nRx = nRx;
+    this.nSurf = nSurf;
     this.nNodes = nNodes;
     this.nFaces = nFaces;
     this.nB = nB;
@@ -214,6 +219,22 @@ export class Solver {
     this.blockOfFace = new Int32Array(nFaces);
     for (let f = 0; f < nFaces; f++) this.blockOfFace[f] = grid.regionEnd[f] + f + 1;
 
+    // Electrode ports' surfaces: each node's port (−1: none) and its index in the port's window;
+    // the coverages there, θ [g·nSurf + s], now and at the step's start.
+    this.surfPort = new Int32Array(nNodes).fill(-1);
+    this.surfW = new Int32Array(nNodes);
+    model.ports.forEach((port, k) => {
+      if (port.surface.length > 0) port.nodes.forEach((g, w) => ((this.surfPort[g] = k), (this.surfW[g] = w)));
+    });
+    // Each surface species of each port, as a column of what's conserved: [port, species].
+    this.surfCols = model.ports.flatMap((port, k) => port.surface.map((_, q) => [k, q]));
+    this.surfColOf = model.ports.map((port, k) => this.surfCols.findIndex(([kk]) => kk === k));
+    this.th = new Float64Array(nNodes * nSurf);
+    this.thOld = new Float64Array(nNodes * nSurf);
+    // The bare fraction θ₀, directly (1 − Σθ cancels as θ → 1); 1 where there's no surface.
+    this.th0 = new Float64Array(nNodes).fill(1);
+    this.th0Old = new Float64Array(nNodes).fill(1);
+
     // Per-node material data, flattened [g·n + i].
     this.present = new Uint8Array(nNodes * n);
     this.cRef = new Float64Array(nNodes * n);
@@ -327,6 +348,19 @@ export class Solver {
     this.contactFlux = { left: new Float64Array(n), right: new Float64Array(n) };
     this.portFlux = model.ports.map(() => new Float64Array(n)); // into the device, mol/(m²·s)
     this.contactD = { left: 0, right: 0 };
+    // A capacitive port's charge (its side's, Σ vol·a·σ over its window), as the contacts' D: now,
+    // at the step's start and at the previous step's end.
+    this.portQ = new Float64Array(model.ports.length);
+    this.portQStart = new Float64Array(model.ports.length);
+    this.portQOld = new Float64Array(model.ports.length);
+    this.portQEnd = null;
+    // And per node, the charge per volume the capacitances hold against the window (Σ aσ, over
+    // every port with one there: two gates on one channel, say; the ions hold −Σ aσ), its slope
+    // Σ a·C per volt, and the ports [terminal, index in its window].
+    this.qg = new Float64Array(grid.nNodes);
+    this.qgSlope = new Float64Array(grid.nNodes);
+    this.qgTerms = Array.from({ length: grid.nNodes }, () => []);
+    model.ports.forEach((port, k) => port.capacitance && port.nodes.forEach((g, w) => this.qgTerms[g].push([2 + k, w])));
     this.contactDOld = { left: 0, right: 0 };
     this.contactDStart = { left: 0, right: 0 };
     // Terminals (the two contacts, then the ports): each one's voltage (V), held by its source or
@@ -407,11 +441,15 @@ export class Solver {
     // A port that only exchanges (an O₂ supply, a leak) is solved there too: left out, its window
     // fell back on the ill-conditioned terms, and a closed neutral electrolyte whose potential is
     // set only by a face reaction couldn't take a step.
+    // An end node is solved there too if its contact is closed to every ion and leaves φ alone.
     const held = new Uint8Array(nNodes);
-    held[0] = held[nNodes - 1] = 1;
+    const closed = (side) => model.contacts[side].phi.type === 'neutral' && model.contacts[side].species.every((l, i) => species[i].z === 0 ? l.type !== 'equilibrium' : l.type === 'blocked');
+    this.closedEnd = { left: closed('left'), right: closed('right') };
+    held[0] = this.closedEnd.left ? 0 : 1;
+    held[nNodes - 1] = this.closedEnd.right ? 0 : 1;
     for (const port of model.ports) if (port.species.some((l) => l.type === 'equilibrium')) for (const g of port.nodes) held[g] = 1;
     this.chargeNode = new Uint8Array(nNodes);
-    const neutralFace = (f) => f >= 0 && f < model.interfaces.length && model.interfaces[f].phi.type === 'neutral';
+    const neutralFace = (f) => (f === -1 ? this.closedEnd.left : f === model.interfaces.length ? this.closedEnd.right : model.interfaces[f].phi.type === 'neutral');
     regions.forEach((reg, r) => {
       const mat = materials[reg.material];
       if (mat.conductor || mat.epsr !== 0) return;
@@ -435,6 +473,8 @@ export class Solver {
     this._findStretches();
     this.initFromComposition();
     this.referenceAmounts = this.stretches.map((st) => this.amount(st));
+    // And what each surface species held then (a conserved combination through one counts it).
+    this.surfaceRef = Float64Array.from(this.surfCols, (_, j) => this.surfaceAmount(j));
     // ∫ (flux in − flux out) dt through the contacts, per stretch, since the reference.
     this.boundaryIntake = new Float64Array(this.stretches.length);
   }
@@ -453,6 +493,8 @@ export class Solver {
       }
       active[b * M] = this.phiUndefined[g] ? 0 : 1;
       for (let i = 0; i < n; i++) active[b * M + 1 + i] = this.present[g * n + i];
+      const k = this.surfPort[g];
+      if (k >= 0) for (let q = 0; q < model.ports[k].surface.length; q++) active[b * M + 1 + n + q] = 1;
     }
     model.interfaces.forEach((itf, f) => {
       const bf = this.blockOfFace[f];
@@ -559,12 +601,14 @@ export class Solver {
     // its faces; both are left to giant time steps.
     this.constraints = [];
     const conductor = (st) => materials[regions[st.regions[0]].material].conductor;
-    const add = (parts, rowStretch) => {
+    const add = (parts, rowStretch, surface = []) => {
       const st = this.stretches[rowStretch];
-      const nNodes = parts.reduce((m, p) => m + this.stretches[p.stretch].nodes[1] - this.stretches[p.stretch].nodes[0] + 1, 0);
+      let nNodes = parts.reduce((m, p) => m + this.stretches[p.stretch].nodes[1] - this.stretches[p.stretch].nodes[0] + 1, 0);
+      for (const p of surface) nNodes += model.ports[this.surfCols[p.col][0]].nodes.length * model.ports[this.surfCols[p.col][0]].surface.length;
       for (const p of parts) this.stretches[p.stretch].conserved = true;
       this.constraints.push({
         parts,
+        surface,
         row: this.blockOfNode[st.nodes[0]] * this.M + 1 + st.species,
         idx: new Int32Array(nNodes * this.M),
         w: new Float64Array(nNodes * this.M),
@@ -576,12 +620,15 @@ export class Solver {
     this.stretches.forEach((st, k) => {
       if (st.spectator && st.mobile) add([{ stretch: k, w: 1 }], k);
     });
+    const S = this.stretches.length;
     for (const w of this.moieties) {
-      const parts = [...w.keys()].filter((k) => w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
-      if (parts.length === 1 && this.stretches[parts[0].stretch].spectator) continue; // (above)
+      const parts = [...w.keys()].filter((k) => k < S && w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
+      const surface = [...w.keys()].filter((k) => k >= S && w[k] !== 0).map((k) => ({ col: k - S, w: w[k] }));
+      if (parts.length === 0) continue; // (a surface's own: left to giant time steps)
+      if (parts.length === 1 && surface.length === 0 && this.stretches[parts[0].stretch].spectator) continue; // (above)
       if (parts.some((p) => !this.stretches[p.stretch].mobile || conductor(this.stretches[p.stretch]))) continue;
       // The row replaced: the basis vector's own stretch (its weight is 1, and no other vector has one).
-      add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch);
+      add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch, surface);
     }
     // A combination of immobile stretches (trap states: X⁰ + X⁻ under e⁻ + X⁰ = X⁻) is conserved
     // node by node, since nothing carries it anywhere: at each node its weighted sum stays what
@@ -644,26 +691,32 @@ export class Solver {
   // stoichiometry (a row per reaction, over the stretches it touches) together with a unit row
   // for each stretch fed from outside. Exact integer data, so plain elimination will do.
   _conservedMoieties() {
-    const { model, n } = this, S = this.stretches.length;
+    const { model, n } = this, S = this.stretches.length, C = S + this.surfCols.length;
     const rows = [];
     model.interfaces.forEach((itf, f) => {
       for (const rx of itf.reactions) {
-        const row = new Float64Array(S);
+        const row = new Float64Array(C);
         for (const p of rx.part) row[this.stretchOf[(f + p.side) * n + p.i]] += p.nu;
         rows.push(row);
       }
     });
-    for (const port of model.ports) {
+    // An electrode surface's species are columns too, after the stretches (S + j for surface
+    // column j), so a combination that passes through them (A⁺ + e⁻ = S, S + e⁻ = B⁻) is conserved
+    // with what the surface holds.
+    model.ports.forEach((port, k) => {
       for (const rx of port.reactions) {
-        const row = new Float64Array(S); // (the electrode's carrier is outside the device)
-        for (const p of rx.part) if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
+        const row = new Float64Array(C); // (the electrode's carrier is outside the device)
+        for (const p of rx.part) {
+          if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
+          else if (p.side === 2) row[S + this.surfColOf[k] + p.s] += p.nu;
+        }
         rows.push(row);
       }
-    }
+    });
     model.regions.forEach((reg, q) => {
       for (const rx of model.reactions) {
         if (!(rx.kf[reg.material] > 0)) continue;
-        const row = new Float64Array(S);
+        const row = new Float64Array(C);
         for (const p of rx.reactants) row[this.stretchOf[q * n + p.i]] -= p.nu;
         for (const p of rx.products) row[this.stretchOf[q * n + p.i]] += p.nu;
         rows.push(row);
@@ -671,34 +724,34 @@ export class Solver {
     });
     this.stretches.forEach((st, k) => {
       if (!st.contactFed) return;
-      const row = new Float64Array(S);
+      const row = new Float64Array(C);
       row[k] = 1;
       rows.push(row);
     });
     // Reduced row echelon form; the free columns give the null space.
     const pivots = [];
     let r = 0;
-    for (let col = 0; col < S && r < rows.length; col++) {
+    for (let col = 0; col < C && r < rows.length; col++) {
       let best = r;
       for (let i = r + 1; i < rows.length; i++) if (Math.abs(rows[i][col]) > Math.abs(rows[best][col])) best = i;
       if (Math.abs(rows[best][col]) < 1e-9) continue;
       [rows[r], rows[best]] = [rows[best], rows[r]];
       const pr = rows[r], pv = pr[col];
-      for (let j = 0; j < S; j++) pr[j] /= pv;
+      for (let j = 0; j < C; j++) pr[j] /= pv;
       for (let i = 0; i < rows.length; i++) {
         if (i === r || rows[i][col] === 0) continue;
         const fct = rows[i][col];
-        for (let j = 0; j < S; j++) rows[i][j] -= fct * pr[j];
+        for (let j = 0; j < C; j++) rows[i][j] -= fct * pr[j];
       }
       pivots.push(col);
       r++;
     }
-    const isPivot = new Uint8Array(S);
+    const isPivot = new Uint8Array(C);
     for (const col of pivots) isPivot[col] = 1;
     const basis = [];
-    for (let free = 0; free < S; free++) {
+    for (let free = 0; free < C; free++) {
       if (isPivot[free]) continue;
-      const w = new Float64Array(S);
+      const w = new Float64Array(C);
       w[free] = 1;
       pivots.forEach((col, i) => {
         const v = -rows[i][free];
@@ -738,6 +791,19 @@ export class Solver {
           }
         }
       }
+      // What the electrodes' surfaces hold of it: Γ Σ v·a·θ, with ∂θ_s/∂η_x = θ_s (δ_sx − θ_x).
+      for (const { col, w } of cs.surface) {
+        const [k, q] = this.surfCols[col], port = this.model.ports[k], G = port.surface[0].capacity, ns = port.surface.length;
+        reference += w * this.surfaceRef[col];
+        port.nodes.forEach((g, j) => {
+          const f = w * G * vol[g] * this.portArea[k][j], b = this.blockOfNode[g], tq = this.th[g * this.nSurf + q];
+          amount += f * tq;
+          for (let x = 0; x < ns; x++) {
+            cs.idx[len] = this.rix[b * M + 1 + n + x];
+            cs.w[len++] = f * tq * ((q === x ? 1 : 0) - this.th[g * this.nSurf + x]);
+          }
+        });
+      }
       cs.len = len;
       cs.res = amount - reference;
       const b0 = Math.floor(cs.row / M), r0 = cs.row % M;
@@ -816,6 +882,14 @@ export class Solver {
   }
 
 
+  /** Amount (mol per unit area) of surface column j's species, Γ Σ v·a·θ, in the current state. */
+  surfaceAmount(j) {
+    const [k, q] = this.surfCols[j], port = this.model.ports[k], vol = this.model.grid.vol;
+    let s = 0;
+    port.nodes.forEach((g, w) => (s += vol[g] * this.portArea[k][w] * this.th[g * this.nSurf + q]));
+    return port.surface[0].capacity * s;
+  }
+
   /** Total amount (mol per unit area) of a stretch's species in the current state. */
   amount(stretch) {
     const { n, c, model } = this;
@@ -1055,13 +1129,36 @@ export class Solver {
       const shift = level(t.side) - level(this.terms[held].side);
       if (Number.isFinite(shift)) this.termV[k] = this.termV[held] + shift;
     }
+    // Electrode surfaces at their starting coverages: η = μ°/RT + ln(θ/θ₀).
+    for (let g = 0; g < this.nNodes; g++) {
+      const k = this.surfPort[g];
+      if (k < 0) continue;
+      const surf = model.ports[k].surface, b = this.blockOfNode[g], bare = 1 - surf.reduce((t, sp) => t + sp.theta0, 0);
+      surf.forEach((sp, q) => (u[b * M + 1 + n + q] = sp.mu0 / model.RT + Math.log(sp.theta0 / bare)));
+    }
     this.computeConcentrations();
-    // A floating electrode spread through a port starts where its reactions pass the current it's
-    // set (none, behind a resistance): at its mixed potential in the start's composition, not
-    // level with a held terminal, which can be volts away and pass an absurd current.
+    // A floating capacitance starts uncharged (σ = 0 at the window's mean φ), as the starting
+    // composition, neutral without it, assumes; with reactions too, its double layer then charges
+    // toward their mixed potential.
     for (const k of this.floating) {
       const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
-      if (!port || port.reactions.length === 0) continue;
+      if (!port?.capacitance) continue;
+      let w = 0, sum = 0;
+      port.nodes.forEach((g, j) => {
+        if (this.phiUndefined[g]) return;
+        const a = this.model.grid.vol[g] * this.portArea[t.index][j];
+        w += a;
+        sum += a * this.VT * u[this.blockOfNode[g] * M];
+      });
+      if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
+    }
+    // A floating electrode spread through a port (without a double layer) starts where its
+    // reactions pass the current it's set (none, behind a resistance): at its mixed potential in
+    // the start's composition, not level with a held terminal, which can be volts away and pass
+    // an absurd current.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      if (!port || port.reactions.length === 0 || port.capacitance) continue;
       const want = t.drive.kind === 'I' ? sourceAt(t.drive.src, this.time) : 0;
       const current = (V) => {
         this.termV[k] = V;
@@ -1088,18 +1185,19 @@ export class Solver {
 
   // A port reaction's rate per area at node g (mol/(m²·s), forward), at the present state.
   _portRate(port, rx, g) {
-    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    const { n, M, u, uLo, c, nSurf, th } = this, b = this.blockOfNode[g], RT = this.model.RT;
     let pref = rx.k0, a = rx.fixedA;
     for (const p of rx.part) {
       if (p.side === 1) {
         a -= p.nu * this.portEta(port, p.i);
         continue;
       }
-      a -= p.nu * (u[b * M + 1 + p.i] + uLo[b * M + 1 + p.i]);
-      pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
+      const o = b * M + (p.side === 2 ? 1 + n + p.s : 1 + p.i), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
+      a -= p.nu * (u[o] + uLo[o]);
+      pref *= p.side === 2 ? Math.exp(e * (u[o] + uLo[o] - port.surface[p.s].mu0 / RT)) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
     }
-    // (far from equilibrium, the plain difference: bvFactor's product would give 0·∞ there)
-    return pref * (Math.abs(a) > 50 ? Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a) : bvFactor(a, rx.alpha).g);
+    if (rx.bare) pref *= this.th0[g];
+    return pref * bvFactor(a, rx.alpha).g;
   }
 
   // A non-ideal material's composition at φ̂ = ph: level-fixed species (mode 1) at their η,
@@ -1128,6 +1226,23 @@ export class Solver {
     }
   }
 
+  // Each electrode surface's coverages from its η: Langmuir on shared sites, θ_s = e^{ζ_s}/(1 + Σ e^{ζ}),
+  // ζ = η − μ°/RT (so θ_s/θ₀ = e^{ζ_s}), at every node of a surfaced window.
+  _coverages() {
+    const { n, M, u, uLo, nSurf, th } = this, RT = this.model.RT;
+    for (let g = 0; g < this.nNodes; g++) {
+      const k = this.surfPort[g];
+      if (k < 0) continue;
+      const surf = this.model.ports[k].surface, b = this.blockOfNode[g];
+      let m = 0;
+      for (let q = 0; q < surf.length; q++) m = Math.max(m, u[b * M + 1 + n + q] + uLo[b * M + 1 + n + q] - surf[q].mu0 / RT);
+      let sum = Math.exp(-m);
+      for (let q = 0; q < surf.length; q++) sum += (th[g * nSurf + q] = Math.exp(u[b * M + 1 + n + q] + uLo[b * M + 1 + n + q] - surf[q].mu0 / RT - m));
+      for (let q = 0; q < surf.length; q++) th[g * nSurf + q] /= sum;
+      this.th0[g] = Math.exp(-m) / sum;
+    }
+  }
+
   computeConcentrations() {
     const { n, M, u, uLo, c, z } = this;
     for (let g = 0; g < this.nNodes; g++) {
@@ -1150,6 +1265,7 @@ export class Solver {
         c[k] = this.present[k] ? this.cRef[k] * Math.exp(u[b * M + 1 + i] + uLo[b * M + 1 + i] - this.mu0hat[k] - z[i] * phiHat) : 0;
       }
     }
+    this._coverages();
   }
 
   _work(md) {
@@ -1444,6 +1560,18 @@ export class Solver {
         }
       }
       res[R[lb]] -= v * q;
+      // The pivot's row (charge continuity) left storage out, the ions' net charge being constant
+      // under neutrality. Against a capacitance it isn't: neutrality makes it −(aσ + ρ_fixed)/F,
+      // so their storage is that less what the step started with, Σ z c_old, over dt (in units
+      // of the pivot's balance).
+      if (this.qgTerms[g].length > 0) {
+        const f = -v / (FARADAY * z[k] * dt);
+        let qOld = this.rhoFixed[g];
+        for (let i = 0; i < n; i++) if (present[gn + i]) qOld += F * z[i] * cOld[gn + i];
+        res[rk] += f * (this.qg[g] + qOld);
+        B[offB[b] + lk * m + p] += -f * this.qgSlope[g] * this.VT;
+        for (const [kq, w] of this.qgTerms[g]) termB[kq][rk] += f * this.portArea[kq - 2][w] * this.model.ports[kq - 2].capacitance.C;
+      }
     }
   }
 
@@ -1969,7 +2097,10 @@ export class Solver {
       this.termDI[k] = 0;
       this.termI[k] = 0;
     }
-    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k));
+    this.qg.fill(0);
+    this.qgSlope.fill(0);
+    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt, false));
+    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt, true));
     this._contact('left', dt);
     this._contact('right', dt);
     for (const k of this.floating) this._circuit(k);
@@ -2001,16 +2132,18 @@ export class Solver {
 
   // An internal port (terminal k): its exchange with each node of its window, as a source per
   // volume. A held ('equilibrium') level replaces the node's balance row; the source is then that
-  // row's residual, read just before. Its current into the device is Σ z F × the sources.
-  _port(port, flux, k) {
+  // row's residual, read just before. Its current into the device is Σ z F × the sources. In two
+  // passes over the ports: everything else, then the held levels (`holds`), so that a level reads
+  // every other port's terms at its nodes, and none is added into its row after.
+  _port(port, flux, k, dt, holds) {
     const R = this.rix;
     const { n, M, u, uLo, res, z, VT } = this;
     const F = FARADAY, vol = this.model.grid.vol;
     const B = this.termB[k], C = this.termC[k];
-    flux.fill(0);
+    if (!holds) flux.fill(0);
     for (let i = 0; i < n; i++) {
       const link = port.species[i];
-      if (link.type === 'blocked') continue;
+      if (link.type === 'blocked' || (link.type === 'equilibrium') !== holds) continue;
       const r = 1 + i, target = this.portEta(port, i), zF = z[i] * F;
       for (const g of port.nodes) {
         const b = this.blockOfNode[g], o = b * M + r, v = vol[g];
@@ -2037,8 +2170,13 @@ export class Solver {
         }
       }
     }
+    if (holds) {
+      for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
+      return;
+    }
     port.reactions.forEach((rx, x) => this._portReaction(port, rx, this.portArea[k - 2], this.portRates[k - 2][x], flux, k));
-    for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
+    if (port.capacitance) this._portCapacitance(port, k, dt);
+    if (port.surface.length > 0 && Number.isFinite(dt)) this._surfaceStorage(port, dt);
   }
 
   // A port's reaction at each node of its window: Butler–Volmer per area, as at a face, against
@@ -2046,49 +2184,113 @@ export class Solver {
   // volume. Each node's rate is explicit (no unknown of its own): it enters the balances of the
   // species it makes and consumes, and the port's current.
   _portReaction(port, rx, area, rates, flux, k) {
-    const { n, M, u, uLo, c, res, z, VT } = this, R = this.rix, F = FARADAY, vol = this.model.grid.vol;
-    const B = this.termB[k], C = this.termC[k], al = rx.alpha, d = this.dA;
+    const { n, M, u, uLo, c, res, z, VT, nSurf, th } = this, R = this.rix, F = FARADAY, vol = this.model.grid.vol, RT = this.model.RT;
+    const B = this.termB[k], C = this.termC[k], al = rx.alpha, d = this.dA, surf = port.surface;
     // The carrier's part of the affinity, and how it moves with the port's voltage.
     let aV = rx.fixedA, daV = 0, q = 0; // q: charge the forward reaction brings into the device, per event
     for (const p of rx.part) {
       if (p.side === 1) {
         aV -= p.nu * this.portEta(port, p.i);
         daV -= (p.nu * z[p.i]) / VT;
-      } else q += p.nu * z[p.i];
+      } else if (p.side === 0) q += p.nu * z[p.i];
     }
+    const slot = (p) => (p.side === 2 ? 1 + n + p.s : 1 + p.i);
     port.nodes.forEach((g, w) => {
       const b = this.blockOfNode[g], s = vol[g] * area[w];
       d.fill(0);
       let pref = rx.k0, aHi = aV, aLo = 0;
       for (const p of rx.part) {
         if (p.side === 1) continue;
-        const o = b * M + 1 + p.i;
+        const o = b * M + slot(p);
         aHi -= p.nu * u[o];
         aLo -= p.nu * uLo[o];
         const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
-        pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
-        this._dlnc(g, p.i, e, d);
+        if (p.side === 2) {
+          // a surface species at activity θ/θ₀ = e^ζ
+          pref *= Math.exp(e * (u[o] + uLo[o] - surf[p.s].mu0 / RT));
+          d[1 + n + p.s] += e;
+        } else {
+          pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
+          this._dlnc(g, p.i, e, d);
+        }
+      }
+      if (rx.bare) {
+        // on bare metal only: the free fraction θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
+        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= th[g * nSurf + x];
+        pref *= this.th0[g];
       }
       const { g: bv, gp } = bvFactor(aHi + aLo, al);
       const rate = pref * bv;
       rates[w] = rate;
-      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
+      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η = −ν
       for (let t = 0; t < M; t++) d[t] *= rate;
-      for (const p of rx.part) if (p.side === 0) d[1 + p.i] -= pref * gp * p.nu;
+      for (const p of rx.part) if (p.side !== 1) d[slot(p)] -= pref * gp * p.nu;
       const dV = pref * gp * daV;
       for (const p of rx.part) {
         if (p.side === 1) continue;
-        const row = 1 + p.i, o = b * M + row;
-        res[R[o]] -= s * p.nu * rate;
-        flux[p.i] += s * p.nu * rate;
-        for (let t = 0; t < M; t++) if (d[t] !== 0) this._j(b, row, b, t, -s * p.nu * d[t]);
-        B[R[o]] -= s * p.nu * dV;
+        // the region's species per volume of the window; a surface's per area of electrode
+        const row = slot(p), o = b * M + row, f = p.side === 2 ? 1 : s;
+        res[R[o]] -= f * p.nu * rate;
+        if (p.side === 0) flux[p.i] += s * p.nu * rate;
+        for (let t = 0; t < M; t++) if (d[t] !== 0) this._j(b, row, b, t, -f * p.nu * d[t]);
+        B[R[o]] -= f * p.nu * dV;
       }
       for (let t = 0; t < M; t++) if (d[t] !== 0) C[R[b * M + t]] += q * F * s * d[t];
       this.termDI[k] += q * F * s * dV;
     });
   }
 
+  // A capacitance spread through a port's window: per area of electrode, σ = C (V − zeroCharge − φ)
+  // on the port's side, so each node's charge balance (its φ row) gains vol·a·σ, and the port
+  // passes the charging current d(Σ vol·a·σ)/dt (none in a steady state). An end node whose φ its
+  // contact sets is left to the contact.
+  _portCapacitance(port, k, dt) {
+    const { M, u, uLo, res, VT } = this, R = this.rix, vol = this.model.grid.vol, area = this.portArea[k - 2];
+    const { C: Cs, zeroCharge } = port.capacitance, V = this.termV[k], B = this.termB[k], Ct = this.termC[k];
+    const sets = (side) => ['pinned', 'bulk'].includes(this.model.contacts[side].phi.type);
+    let Q = 0, dQdV = 0;
+    port.nodes.forEach((g, w) => {
+      if ((g === 0 && sets('left')) || (g === this.nNodes - 1 && sets('right')) || this.phiUndefined[g]) return;
+      const b = this.blockOfNode[g], s = vol[g] * area[w] * Cs;
+      const q = s * (V - zeroCharge - VT * (u[b * M] + uLo[b * M]));
+      this.qg[g] += area[w] * Cs * (V - zeroCharge - VT * (u[b * M] + uLo[b * M]));
+      this.qgSlope[g] += area[w] * Cs;
+      Q += q;
+      dQdV += s;
+      res[R[b * M]] -= q;
+      this._j(b, 0, b, 0, s * VT);
+      B[R[b * M]] -= s;
+      if (Number.isFinite(dt)) Ct[R[b * M]] += (-s * VT) / dt;
+    });
+    this.portQ[k - 2] = Q;
+    if (Number.isFinite(dt)) {
+      this.termI[k] += (Q - this.portQStart[k - 2]) / dt;
+      this.termDI[k] += dQdV / dt;
+    }
+  }
+
+  // An electrode surface's storage, per area of electrode: Γ (θ_s − θ_s,old)/dt in each surface
+  // species' row, with ∂θ_s/∂η_x = θ_s (δ_sx − θ_x).
+  _surfaceStorage(port, dt) {
+    const { n, M, res, nSurf, th, thOld } = this, R = this.rix, surf = port.surface, G = surf[0].capacity;
+    for (const g of port.nodes) {
+      const b = this.blockOfNode[g];
+      // Near full coverage θ − θ_old cancels (both ~1, the change ~θ₀): the dominant species'
+      // change comes from the small ones instead, Δθ = −Δθ₀ − Σ_others Δθ.
+      let top = 0;
+      for (let q = 1; q < surf.length; q++) if (th[g * nSurf + q] > th[g * nSurf + top]) top = q;
+      for (let q = 0; q < surf.length; q++) {
+        const tq = th[g * nSurf + q];
+        let change = tq - thOld[g * nSurf + q];
+        if (q === top && tq > 0.5) {
+          change = -(this.th0[g] - this.th0Old[g]);
+          for (let x = 0; x < surf.length; x++) if (x !== q) change -= th[g * nSurf + x] - thOld[g * nSurf + x];
+        }
+        res[R[b * M + 1 + n + q]] += (G * change) / dt;
+        for (let x = 0; x < surf.length; x++) this._j(b, 1 + n + q, b, 1 + n + x, ((G * tq) / dt) * ((q === x ? 1 : 0) - th[g * nSurf + x]));
+      }
+    }
+  }
 
   // One contact (terminal 0 or 1): record the flux through its outer face and the current into
   // the device (read from the end box before anything here is added: whatever the box needs
@@ -2107,10 +2309,13 @@ export class Solver {
     const Ac = model.grid.area[g]; // the links' laws are per area: what they pass is that times A here
     const dyn = Number.isFinite(dt);
 
-    // Before anything is added, each balance residual is the flux into the device here.
+    // Before anything is added, each balance residual is the flux into the device here. (A
+    // closed end solved in charge rows has its ions' storage left out until later: none of them
+    // passes, so their flux is zero.)
+    const closedIons = this.combining && dyn && this.chargeNode[g] === 1;
     let I = 0;
     for (let i = 0; i < n; i++) {
-      const active = this.loc[b * M + 1 + i] >= 0;
+      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0);
       const nIn = active ? res[R[b * M + 1 + i]] : 0;
       flux[i] = sgn * nIn; // (toward +x)
       if (active && z[i] !== 0) {
@@ -2245,6 +2450,8 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         if (this.present[g * n + i]) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + i]]));
       }
+      const k = this.surfPort[g]; // an electrode surface's coverages, as η
+      if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + n + q]]));
     }
     return mx;
   }
@@ -2401,14 +2608,15 @@ export class Solver {
     this.uPrevLo.set(this.uLo);
     this.termVPrev.set(this.termV);
     this.computeConcentrations();
-    const cN = Float64Array.from(this.c);
+    const cN = Float64Array.from(this.c), thN = Float64Array.from(this.th), th0N = Float64Array.from(this.th0);
     // Contact displacement before the step: as it was at the end of the previous step (under
     // the parameters then), so a gate-voltage change shows up as displacement current.
-    if (!this.contactDEnd) {
+    if (!this.contactDEnd || !this.portQEnd) {
       this._assembleBookkeeping(dt);
       this.contactDEnd = { ...this.contactD };
+      this.portQEnd = Float64Array.from(this.portQ);
     }
-    const DN = { ...this.contactDEnd };
+    const DN = { ...this.contactDEnd }, QN = Float64Array.from(this.portQEnd);
     if (opts.guess) {
       // Start Newton from a predicted state (e.g. extrapolated from the history).
       this.u.set(opts.guess);
@@ -2419,11 +2627,17 @@ export class Solver {
       const a0 = (1 + 2 * w) / (1 + w), b1 = (1 + w) / a0, b2 = (w * w) / (1 + w) / a0;
       const { cOld } = this;
       for (let k = 0; k < cOld.length; k++) cOld[k] = b1 * cN[k] - b2 * prev.c[k];
+      for (let k = 0; k < thN.length; k++) this.thOld[k] = b1 * thN[k] - b2 * prev.th[k];
+      for (let k = 0; k < th0N.length; k++) this.th0Old[k] = b1 * th0N[k] - b2 * prev.th0[k];
       this.contactDStart = { left: b1 * DN.left - b2 * prev.D.left, right: b1 * DN.right - b2 * prev.D.right };
+      this.portQStart = QN.map((q, k) => b1 * q - b2 * prev.Q[k]);
       dtEff = dt / a0;
     } else {
       this.cOld.set(cN);
+      this.thOld.set(thN);
+      this.th0Old.set(th0N);
       this.contactDStart = DN;
+      this.portQStart = QN;
     }
     // Implicit: sources at the step's end, as seen from within the step (before any jump there).
     // A step landing on a breakpoint ends on it exactly.
@@ -2439,11 +2653,12 @@ export class Solver {
     }
     result.bdf = bdf;
     if (result.converged) {
-      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, D: DN });
+      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, th: thN, th0: th0N, D: DN, Q: QN });
       if (this.history.length > 3) this.history.length = 3;
       this.time = tEnd;
       this.lastDt = dtEff;
       this.contactDOld = this.contactDStart;
+      this.portQOld = this.portQStart;
       this._accumulateBoundaryIntake(dtEff, cN);
     } else {
       this.u.set(this.uPrev);
@@ -2459,7 +2674,7 @@ export class Solver {
   /**
    * Adaptive time stepping to tEnd: variable-step BDF2 (or backward Euler), with the local error
    * estimated against an explicit predictor through the previous states, and controlled to
-   * `tol` thermal units per step in every potential (φ̂, each η, a floating terminal). The first
+   * `tol` thermal units per step in every potential (φ̂, each η, a surface's coverages as η). The first
    * step is checked by step doubling. Stops early when `budgetMs` of wall time is used, so an
    * animation can call it once per frame; the step size carries over between calls.
    */
@@ -2539,7 +2754,8 @@ export class Solver {
           continue;
         }
       } else {
-        const r = this.step(h, { method, guess: this._extrapolate(guess, this.time + h) });
+        // (Order 2 once three consistent states can check it.)
+        const r = this.step(h, { method: this.history.length >= 2 ? method : 'be', guess: this._extrapolate(guess, this.time + h) });
         iterations += r.iterations;
         if (!r.converged) {
           rejected++;
@@ -2559,6 +2775,11 @@ export class Solver {
       }
       steps++;
       grow = 0;
+      // The state the first step started from needn't satisfy the algebraic equations (φ in a
+      // strictly neutral region, an interface's unknowns, after a start or a jump), and they
+      // jump in the first instant; a predictor through it would see that jump as error on every
+      // step after. The history starts from the half step.
+      if (half) this.history.length = 1;
       dt = clamped ? Math.max(dt, h * factor(err, p)) : h * factor(err, p);
       if (atBreak) this.history = []; // the solution's slope jumps here: restart the order
       if (half) {
@@ -2685,6 +2906,8 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         if (this.present[g * n + i]) mx = Math.max(mx, Math.abs(u[b * M + 1 + i] - ref[b * M + 1 + i]));
       }
+      const k = this.surfPort[g]; // an electrode surface's coverages, as η
+      if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(u[b * M + 1 + n + q] - ref[b * M + 1 + n + q]));
     }
     return mx;
   }
@@ -2727,12 +2950,17 @@ export class Solver {
       u: Float64Array.from(this.u),
       uLo: Float64Array.from(this.uLo),
       cOld: Float64Array.from(this.cOld),
+      thOld: Float64Array.from(this.thOld),
+      th0Old: Float64Array.from(this.th0Old),
       time: this.time,
       lastDt: this.lastDt,
       atSteady: this.atSteady,
       contactDStart: this.contactDStart,
       contactDOld: this.contactDOld,
       contactDEnd: this.contactDEnd,
+      portQStart: this.portQStart,
+      portQOld: this.portQOld,
+      portQEnd: this.portQEnd,
       boundaryIntake: Float64Array.from(this.boundaryIntake),
       history: this.history.slice(),
       termV: Float64Array.from(this.termV),
@@ -2744,12 +2972,17 @@ export class Solver {
     this.u.set(s.u);
     this.uLo.set(s.uLo);
     this.cOld.set(s.cOld);
+    this.thOld.set(s.thOld);
+    this.th0Old.set(s.th0Old);
     this.time = s.time;
     this.lastDt = s.lastDt;
     this.atSteady = s.atSteady;
     this.contactDStart = s.contactDStart;
     this.contactDOld = s.contactDOld;
     this.contactDEnd = s.contactDEnd;
+    this.portQStart = s.portQStart;
+    this.portQOld = s.portQOld;
+    this.portQEnd = s.portQEnd;
     this.boundaryIntake.set(s.boundaryIntake);
     this.history = s.history.slice();
     this.termV.set(s.termV);
@@ -2786,8 +3019,11 @@ export class Solver {
     this.sourceTime = this.time;
     this.computeConcentrations();
     this.cOld.set(this.c);
+    this.thOld.set(this.th);
+    this.th0Old.set(this.th0);
     this.assemble(Infinity);
     this.contactDStart = { ...this.contactD };
+    this.portQStart = Float64Array.from(this.portQ);
     this.assemble(Infinity);
     // The steady parts, then the storage parts from an assembly at a tiny dt.
     const J = { A: sys.A.slice(), B: sys.B.slice(), C: sys.C.slice() };
@@ -3075,6 +3311,7 @@ export class Solver {
   _accumulateBoundaryIntake(dt, cN) {
     this._assembleBookkeeping(dt);
     this.contactDEnd = { ...this.contactD };
+    this.portQEnd = Float64Array.from(this.portQ);
     if (!Number.isFinite(dt)) return;
     const last = this.model.regions.length - 1;
     const { n, cOld } = this, vol = this.model.grid.vol;
@@ -3125,6 +3362,18 @@ export class Solver {
   // Steady state from the present one; `atSteady` says whether the state is one (until a step or
   // a change of drive).
   solveSteady(opts = {}) {
+    // A terminal that passes current only by charging (a gate, a capacitance with no species
+    // through it) has no steady state under a current drive: it charges for ever, or at I = 0
+    // keeps whatever charge it started with, which a steady solve doesn't know.
+    const { species } = this.model, ions = (links) => links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
+    for (const k of this.floating) {
+      const t = this.terms[k];
+      if (t.drive.kind !== 'I') continue;
+      const only = t.kind === 'port' ? (p) => p.reactions.length === 0 && !ions(p.species) : (c) => !ions(c.species);
+      if (only(t.kind === 'port' ? this.model.ports[t.index] : this.model.contacts[t.side])) {
+        throw new DeviceError(`${t.kind === 'port' ? `ports[${t.index}]` : `contacts.${t.side}`} passes current only by charging, so driven by a current it has no steady state; hold it at V (or a source behind R), or advance() in time`);
+      }
+    }
     const r = this._steadyFromHere(opts);
     this.atSteady = r.converged;
     return r;