driftlet 1.3.2 → 1.4.0

package/src/boundaries.js

@@ -33,6 +33,19 @@
 //     carrier at activity 1), or saturating (vmax), or SRH; −Af·ν·r into each participant's row.
 //   gates (_faceGates): (x − x_old)/dt − α(V)(1 − x) + β(V)x = 0, V = φ_R − φ_L (no storage at
 //     dt = ∞).
+//   diffuse layers (_diffuseTerms; itf.diffuse, on each strictly neutral side: s.diffList, its
+//     q, Γ and their derivatives from computeConcentrations, src/diffuse.js): each a slot after
+//     the gates, its drop s = Fψ/RT, which puts that side's plane at φ̂_edge + s: the φ law (each
+//     form above) runs to the planes, φ̂ → φ̂ + s. Its row: q(s, c_edge) − Q, Q the charge the face
+//     gives that side (D on the left, −(D + sheetCharge) on the right); −Af·q in the edge node's
+//     Gauss row, and Af (Γ_i − Γ_i,old)/dt in its balances (none at dt = ∞). A reaction's
+//     participant on that side reacts at the plane: its c times e^{−z s} in the rate (Butler–Volmer
+//     and saturating; SRH beside a layer is refused by normalizeDevice), and its level there w
+//     above the edge node's (a slot after the drops, _diffuseDraws: its η + w, its c times e^w;
+//     row 1 − e^w − N K/(D c), N what the reactions take from that side, K the layer's
+//     resistance to it; where K < 0, −w − X/√(1 + X²), X = N K/(D c)); a
+//     permeability link runs between the planes (c e^{−z s} at each, its drift over φ̂ + s), and
+//     gates follow the voltage between them (_faceVoltage).
 //
 // The terminals (_terminals), in order: the sources refreshed (_refreshSources); the live
 // terminals' termB, termC zeroed, and termDI, termDX, termI, qg, qgSlope; each port's terms but
@@ -78,15 +91,18 @@
 //      from outside, read from its residual (so the current is conserved through the device).
 //   3. A face's flux enters its two edge nodes with opposite signs, times Af.
 //   4. Where μ̄ is level across a link (or a = 0 for a reaction), its flux (rate) is exactly 0.
+//   4b. A diffuse layer's side holds the face's charge in the layer: at its row's solution the
+//      edge box's own charge (vol·ρ) is what its other terms put there, as without the face.
 //   5. The readouts (contactFlux, contactD, portFlux, portQ, portRates) are those of the state
 //      assembled, written at every assembly.
 // Tests: test/contacts.test.js, test/ports.test.js, test/terminals.test.js, test/circuit.test.js,
 // test/gates.test.js, test/membrane.test.js, test/kinetics.test.js, test/coverage.test.js,
-// test/capacitance.test.js, test/metal.test.js, test/jacobian.test.js.
+// test/capacitance.test.js, test/metal.test.js, test/diffuse.test.js, test/jacobian.test.js.
 
 import { sgFlux } from './bernoulli.js';
 import { FARADAY } from './constants.js';
 import { sourceAt } from './device.js';
+import { diffuseLayer } from './diffuse.js';
 import { powi, powr } from './pow.js';
 
 // Butler–Volmer factor g(a) = e^{αa} − e^{−(1−α)a} = e^{−(1−α)a}·expm1(a) (precise near a = 0),
@@ -143,35 +159,44 @@ export class BoundaryTerms {
     const grid = model.grid, interfaces = model.interfaces;
     const bf = this.blockOfFace[f], bL = bf - 1, bR = bf + 1;
     const itf = interfaces[f];
+    // A diffuse layer's drop s on a side (src/diffuse.js) puts that side's plane, where the Stern
+    // layer ends, at φ̂_edge + s: [left, right] layer indices (−1: none) and slots.
+    const [dlL, dlR] = this.diffAt[f], dl = this.diffList;
+    const sOf = (d) => (d < 0 ? 0 : u[dl[d].o]);
+    const jS = (rs, d, v) => d >= 0 && this._j(bf, rs, bf, dl[d].slot, v);
     // φ law: pinned jump (dipole), Helmholtz capacitor, or no charge at all (neutral).
     const law = itf.phi.type;
     const condSide = itf.conductor && law !== 'neutral' ? itf.conductor.side : null;
     if (condSide) {
       // Against a metal: the other side's φ is tied to the metal's Fermi level V_F = V_T η/z.
       const im = itf.conductor.i, bm = condSide === 'left' ? bL : bR, bo = condSide === 'left' ? bR : bL;
-      const sg = condSide === 'left' ? 1 : -1;
+      const sg = condSide === 'left' ? 1 : -1, dlo = condSide === 'left' ? dlR : dlL;
       const vf = (u[bm * M + 1 + im] + uLo[bm * M + 1 + im]) / z[im]; // V_F / V_T
-      const gap = vf - itf.zeroCharge / VT - (u[bo * M] + uLo[bo * M]); // (V_F − zeroCharge − φ_edge)/V_T
+      const gap = vf - itf.zeroCharge / VT - (u[bo * M] + uLo[bo * M]) - sOf(dlo); // (V_F − zeroCharge − φ_plane)/V_T
       if (law === 'pinned') {
         res[R[bf * M]] = gap;
         this._j(bf, 0, bm, 1 + im, 1 / z[im]);
         this._j(bf, 0, bo, 0, -1);
+        jS(0, dlo, -1);
       } else {
-        // D toward the other side = C (V_F − zeroCharge − φ_edge); toward +x that's sg times it.
+        // D toward the other side = C (V_F − zeroCharge − φ_plane); toward +x that's sg times it.
         const kC = itf.phi.C * VT;
         res[R[bf * M]] = u[bf * M] - sg * kC * gap;
         this._j(bf, 0, bf, 0, 1);
         this._j(bf, 0, bm, 1 + im, (-sg * kC) / z[im]);
         this._j(bf, 0, bo, 0, sg * kC);
+        jS(0, dlo, sg * kC);
       }
     } else if (law === 'neutral') {
       // D = 0 (not an unknown); the jump is whatever each side's neutrality needs
     } else {
-      const jump = u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]) - itf.dipole / VT;
+      const jump = u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]) + sOf(dlR) - sOf(dlL) - itf.dipole / VT;
       if (law === 'pinned') {
         res[R[bf * M]] = jump;
         this._j(bf, 0, bR, 0, 1);
         this._j(bf, 0, bL, 0, -1);
+        jS(0, dlR, 1);
+        jS(0, dlL, -1);
       } else {
         // D = −C (φ_R − φ_L − dipole): displacement toward +x drops across the layer.
         const kC = itf.phi.C * VT;
@@ -179,6 +204,8 @@ export class BoundaryTerms {
         this._j(bf, 0, bf, 0, 1);
         this._j(bf, 0, bR, 0, kC);
         this._j(bf, 0, bL, 0, -kC);
+        jS(0, dlR, kC);
+        jS(0, dlL, -kC);
       }
     }
     // D_f enters each side's Gauss row; a metal side holds it as surface carriers instead. The
@@ -192,6 +219,8 @@ export class BoundaryTerms {
       res[R[bR * M]] -= Af * (u[bf * M] + itf.sheetCharge);
       this._j(bR, 0, bf, 0, -Af);
     }
+    if (dlL >= 0) this._diffuseTerms(dlL, bf, Af);
+    if (dlR >= 0) this._diffuseTerms(dlR, bf, Af);
     for (let i = 0; i < n; i++) {
       const r = 1 + i, o = bf * M + r;
       const type = itf.links[i].type;
@@ -208,14 +237,17 @@ export class BoundaryTerms {
         // materials). Between like solutions it's Goldman–Hodgkin–Katz's flux,
         //   N = P·zu·(c_L − c_R e^{zu})/(e^{zu} − 1),  u = (φ_R − φ_L)/V_T,
         // and it's exactly zero where μ̄ is level.
+        // Beside a diffuse layer, between its plane's: c e^{−z s} at each, the drift over the
+        // drop between the planes (s acting as φ̂ does on its side).
         const gl = grid.regionEnd[f], gr = gl + 1, kl = gl * n + i, kr = gr * n + i, zi = z[i], link = itf.links[i];
         const shift = this.mu0hat[kr] - this.mu0hat[kl] - Math.log(this.cRef[kr] / this.cRef[kl]);
-        const d = zi * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M])) + shift;
+        const sL = sOf(dlL), sR = sOf(dlR), cl = this.c[kl] * (sL === 0 ? 1 : Math.exp(-zi * sL)), cr = this.c[kr] * (sR === 0 ? 1 : Math.exp(-zi * sR));
+        const d = zi * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]) + sR - sL) + shift;
         // Gated: P × Π x^p, each x taken in [0, 1] (Newton's iterates can stray past its ends).
         const gated = link.gates ?? [], gx = (q) => u[this._gateSlot(f, q)];
-        const N1 = gated.length ? sgFlux(link.P, d, -deta, this.c[kl], this.c[kr], this.sg)[0] : 0; // (fully open)
+        const N1 = gated.length ? sgFlux(link.P, d, -deta, cl, cr, this.sg)[0] : 0; // (fully open)
         const P = link.P * (gated.length ? this._open(gated, gx) : 1);
-        const sg = sgFlux(P, d, -deta, this.c[kl], this.c[kr], this.sg); // (−deta = η_R − η_L)
+        const sg = sgFlux(P, d, -deta, cl, cr, this.sg); // (−deta = η_R − η_L)
         const N = sg[0], dNdd = sg[1];
         res[R[o]] = u[o] - N;
         this._j(bf, r, bf, r, 1);
@@ -228,6 +260,8 @@ export class BoundaryTerms {
         if (zi !== 0) {
           this._j(bf, r, bL, 0, zi * dNdd + zi * N);
           this._j(bf, r, bR, 0, -zi * dNdd);
+          jS(r, dlL, zi * dNdd + zi * N);
+          jS(r, dlR, -zi * dNdd);
         }
       } else {
         // conductance: J = G (V_L − V_R), V = V_T η / z  ⇒  N = G V_T (η_L − η_R) / (z² F); gated,
@@ -250,6 +284,113 @@ export class BoundaryTerms {
     }
     itf.reactions.forEach((rx, k) => this._faceReaction(rx, k, f, bf, bL, bR, Af));
     if (itf.gates.length > 0) this._faceGates(f, bf, bL, bR);
+    if (dlL >= 0) this._diffuseDraws(dlL, bf);
+    if (dlR >= 0) this._diffuseDraws(dlR, bf);
+  }
+
+  // Layer d's drawn species (those its face's reactions take or make at its plane): each one's
+  // level there, w = ln(a_plane/a_edge), below the edge node's by the flux N its reactions draw
+  // across the layer's resistance K (src/diffuse.js), D c (1 − e^w) = N K: its row, 1 − e^w − N K/(D c).
+  // Where it repels the species, K grows as c/c(plane), and the plane can run out of it (at
+  // N = D c/K). Where it gathers one, K < 0, bounded by about the layer's width (the bulk the grid
+  // counts in its place conducts it less well): a correction of order λ_D/L, and a negative
+  // resistance in series, which far from the solution can draw a product's plane level down the
+  // more of it is made; its row is bounded there (below).
+  _diffuseDraws(d, bf) {
+    const { n, M, u, c, res } = this, R = this.rix;
+    const { b, g, side, f, dl, drawSlot, Dm } = this.diffList[d], itf = this.model.interfaces[f];
+    if (!drawSlot.some((q) => q >= 0)) return;
+    const dc = this._diffuseChain(d), K0 = 1 + n;
+    for (let i = 0; i < n; i++) {
+      const q = drawSlot[i];
+      if (q < 0) continue;
+      // N, what the reactions take from this side (mol/(m²·s)), from their rates' slots
+      let N = 0;
+      itf.reactions.forEach((rx, k) => {
+        for (const p of rx.part) if (p.side === side && p.i === i) N -= p.nu * u[bf * M + K0 + k];
+      });
+      // X = N K/(D c); where the layer gathers the species (K < 0) the row is w = −X/√(1 + X²)
+      // instead, the same to O(X³) where it's solved (|X| about λ_D/L there) and bounded far off
+      const K = dl.K[i], w = u[bf * M + q], cc = Math.max(c[g * n + i], 1e-300), Dc = Dm[i] * cc, X = (N * K) / Dc;
+      const gathered = K < 0, root = Math.sqrt(1 + X * X), gX = gathered ? 1 / (root * root * root) : 1;
+      res[R[bf * M + q]] = gathered ? -w - X / root : -Math.expm1(w) - X;
+      this._j(bf, q, bf, q, gathered ? -1 : -Math.exp(Math.min(700, w)));
+      itf.reactions.forEach((rx, k) => {
+        let nu = 0;
+        for (const p of rx.part) if (p.side === side && p.i === i) nu += p.nu;
+        if (nu !== 0) this._j(bf, q, bf, K0 + k, (gX * nu * K) / Dc);
+      });
+      this._j(bf, q, bf, this.diffList[d].slot, (-gX * N * dl.dKds[i]) / Dc);
+      // through the edge node's c: K's ∂/∂c_j, and 1/c_i's
+      for (let r = 0; r <= n; r++) {
+        let v = (K * dc[i * M + r]) / cc;
+        for (let j = 0; j < n; j++) v -= dl.dKdc[i * n + j] * dc[j * M + r];
+        if (v !== 0) this._j(bf, q, b, r, (gX * N * v) / Dc);
+      }
+    }
+  }
+
+  // Diffuse layer d's terms (src/diffuse.js; its q and Γ from computeConcentrations): its row,
+  // q(s, c) equal to the charge its side holds (D on the left, −(D + sheetCharge) on the right);
+  // its charge in the edge box's Gauss row and its excesses in the box's balances, stored like the
+  // box's own ions (so the box's bulk stays neutral, and what the face's charge draws in is
+  // counted). The edge node's c enters through its ∂c_j/∂(φ̂, η) (_diffuseChain).
+  _diffuseTerms(d, bf, Af) {
+    const { n, M, u, res, gam, gamOld } = this, R = this.rix, dt = this.dtNow;
+    const { b, slot, o, side, f, dl, holds } = this.diffList[d], dc = this._diffuseChain(d);
+    const sheet = this.model.interfaces[f].sheetCharge, w = this.dW ?? (this.dW = new Float64Array(M));
+    // ∂(Σ_j a_j c_j)/∂(the edge node's slot r), into w
+    const chain = (a) => {
+      w.fill(0);
+      for (let j = 0; j < n; j++) if (a[j] !== 0) for (let r = 0; r <= n; r++) w[r] += a[j] * dc[j * M + r];
+      return w;
+    };
+    // its row (per area): q − Q
+    res[R[o]] = dl.q - (side ? -(u[bf * M] + sheet) : u[bf * M]);
+    this._j(bf, slot, bf, slot, dl.dqds);
+    this._j(bf, slot, bf, 0, side ? 1 : -1);
+    chain(dl.dqdc);
+    for (let r = 0; r <= n; r++) {
+      if (w[r] === 0) continue;
+      this._j(bf, slot, b, r, w[r]);
+      this._j(b, 0, b, r, -Af * w[r]); // (and the box's charge: −Af·q in its Gauss row)
+    }
+    res[R[b * M]] -= Af * dl.q;
+    this._j(b, 0, bf, slot, -Af * dl.dqds);
+    // the box's store of each species it holds: Af (Γ_i − Γ_i,old)/dt
+    if (!Number.isFinite(dt)) return;
+    const k = Af / dt;
+    for (let i = 0; i < n; i++) {
+      if (!this.present[this.diffList[d].g * n + i] || !holds[i]) continue;
+      res[R[b * M + 1 + i]] += k * (gam[d * n + i] - gamOld[d * n + i]);
+      this._j(b, 1 + i, bf, slot, k * dl.dgds[i]);
+      chain(dl.dgdc.subarray(i * n, i * n + n));
+      for (let r = 0; r <= n; r++) if (w[r] !== 0) this._j(b, 1 + i, b, r, k * w[r]);
+    }
+  }
+
+  // Layer d's edge node's ∂c_j/∂(slot r) for r = φ̂, η_1…η_n, [j·M + r] (src/regions.js, _dc).
+  _diffuseChain(d) {
+    const { n, M } = this, g = this.diffList[d].g, out = this.diffList[d].chain ?? (this.diffList[d].chain = new Float64Array(n * M));
+    const t = this.dV2 ?? (this.dV2 = new Float64Array(M));
+    for (let j = 0; j < n; j++) {
+      if (!this.present[g * n + j]) {
+        out.fill(0, j * M, (j + 1) * M);
+        continue;
+      }
+      this._dc(g, j, t);
+      out.set(t, j * M);
+    }
+    return out;
+  }
+
+  // The diffuse layers' charges and excesses at the present state (after the concentrations).
+  _diffuseLayers() {
+    const { n, u, c, z, gam } = this;
+    this.diffList.forEach((d, k) => {
+      diffuseLayer(c.subarray(d.g * n, d.g * n + n), z, n, u[d.o], d.units, d.dl, d.lat, d.draw);
+      gam.set(d.dl.gam, k * n);
+    });
   }
 
   // Full index of face f's gate q (its fraction open).
@@ -269,10 +410,12 @@ export class BoundaryTerms {
     return VT * (u[b * M] + uLo[b * M]) - (this.termV[2 + k] - port.capacitance.zeroCharge);
   }
 
-  // The voltage across face f, φ_right − φ_left (V).
+  // The voltage across face f, φ_right − φ_left (V): between its diffuse layers' planes, where it
+  // has them (what the face's own layer, a membrane, has across it).
   _faceVoltage(f) {
-    const { M, u, uLo, VT } = this, bf = this.blockOfFace[f], bL = bf - 1, bR = bf + 1;
-    return VT * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]));
+    const { M, u, uLo, VT } = this, bf = this.blockOfFace[f], bL = bf - 1, bR = bf + 1, [dL, dR] = this.diffAt[f];
+    const planes = (dR < 0 ? 0 : u[this.diffList[dR].o]) - (dL < 0 ? 0 : u[this.diffList[dL].o]);
+    return VT * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]) + planes);
   }
 
   // Face f's gates, each a row (x − x_old)/dt = α(1 − x) − βx in the voltage across the face.
@@ -288,6 +431,10 @@ export class BoundaryTerms {
       const dV = -(da * (1 - x) - db * x) * VT; // per unit φ̂_R, and minus that per unit φ̂_L
       this._j(bf, k0 + q, bR, 0, dV);
       this._j(bf, k0 + q, bL, 0, -dV);
+      // (and per unit of each diffuse layer's drop, as of its side's φ̂)
+      const [dlL, dlR] = this.diffAt[f];
+      if (dlR >= 0) this._j(bf, k0 + q, bf, this.diffList[dlR].slot, dV);
+      if (dlL >= 0) this._j(bf, k0 + q, bf, this.diffList[dlL].slot, -dV);
     });
   }
 
@@ -302,30 +449,66 @@ export class BoundaryTerms {
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     const al = rx.alpha;
     const dL = this.dA.fill(0), dR = this.dB.fill(0); // ∂ ln(prefactor)/∂slot, per side
+    // Beside a diffuse layer (src/diffuse.js), a participant reacts at the plane, where its
+    // concentration is c e^{−z s}/D(s) (its μ̄ level through the layer; D = 1 unless the layer is
+    // crowded): dS[side] = ∂ ln(prefactor)/∂s, and a crowded D's ∂/∂c_j into the side's slots.
+    const dla = this.diffAt[f], dS = [0, 0];
+    const layer = (p) => (dla[p.side] < 0 ? null : this.diffList[dla[p.side]]), atPlane = (p) => layer(p) && (this.z[p.i] !== 0 || layer(p).lat?.on[p.i]);
+    // A drawn participant's level at the plane is w below its edge node's (_diffuseDraws): its c
+    // there e^w times as much, its η w more; the face-block slot of that w, or −1.
+    const wSlot = (p) => (atPlane(p) ? layer(p).drawSlot[p.i] : -1);
+    const wOf = (p) => (wSlot(p) < 0 ? 0 : u[bf * M + wSlot(p)]);
+    const plane = (p) => (atPlane(p) ? Math.exp(Math.max(-700, Math.min(700, -this.z[p.i] * u[layer(p).o] + wOf(p)))) / layer(p).dl.D : 1);
+    const dW = this.dWr ?? (this.dWr = new Float64Array(M)), aW = this.aWr ?? (this.aWr = new Float64Array(M)); // ∂ ln(prefactor), ∂a by each face slot w
+    dW.fill(0);
+    aW.fill(0);
+    // ∂ ln(e^{−z s}/D) by s, and w·(−∂ ln D/∂c_j) through the edge node's slots into d
+    const planeSlope = (p) => -this.z[p.i] - layer(p).dl.dDds / layer(p).dl.D;
+    const crowdInto = (p, w, d) => {
+      const L = layer(p);
+      if (!L.lat || w === 0) return;
+      const dc = this._diffuseChain(dla[p.side]);
+      for (let j = 0; j < n; j++) {
+        const a = (-w * L.dl.dDdc[j]) / L.dl.D;
+        if (a !== 0) for (let r = 0; r <= n; r++) d[r] += a * dc[j * M + r];
+      }
+    };
     let pref = rx.k0, aHi = rx.fixedA, aLo = 0, rate;
     for (const p of rx.part) {
       const g = p.side ? gR : gL, b = p.side ? bR : bL, o = b * M + 1 + p.i;
-      aHi -= p.nu * u[o];
+      aHi -= p.nu * (u[o] + wOf(p));
       aLo -= p.nu * uLo[o];
+      if (wSlot(p) >= 0) aW[wSlot(p)] -= p.nu;
       if (rx.srh || rx.vmax || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       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);
+      pref *= powr((c[g * n + p.i] * plane(p)) / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
+      if (atPlane(p)) {
+        dS[p.side] += e * planeSlope(p);
+        crowdInto(p, e, p.side ? dR : dL);
+        if (wSlot(p) >= 0) dW[wSlot(p)] += e;
+      }
     }
     if (rx.vmax) {
       // Saturating: r = vmax Π (c/(c + K))^{|ν|} (1 − e^{−a}); ∂ln S/∂ln c = |ν| K/(c + K).
       let S = 1;
       rx.part.forEach((p, q) => {
         if (p.nu >= 0) return;
-        const g = p.side ? gR : gL, cc = c[g * n + p.i], K = rx.K[q];
+        const g = p.side ? gR : gL, cc = c[g * n + p.i] * plane(p), K = rx.K[q];
         S *= powi(cc / (cc + K), -p.nu);
         this._dlnc(g, p.i, (-p.nu * K) / (cc + K), p.side ? dR : dL);
+        if (atPlane(p)) {
+          dS[p.side] += ((-p.nu * K) / (cc + K)) * planeSlope(p);
+          crowdInto(p, (-p.nu * K) / (cc + K), p.side ? dR : dL);
+          if (wSlot(p) >= 0) dW[wSlot(p)] += (-p.nu * K) / (cc + K);
+        }
       });
       const a = aHi + aLo, back = Math.exp(-a);
       rate = rx.vmax * S * -Math.expm1(-a);
       for (let s = 0; s < M; s++) {
         dL[s] *= rate;
         dR[s] *= rate;
+        dW[s] = rate * dW[s] + rx.vmax * S * back * aW[s];
       }
       for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= rx.vmax * S * back * p.nu;
     } else if (rx.srh) {
@@ -343,12 +526,15 @@ export class BoundaryTerms {
       for (let s = 0; s < M; s++) {
         dL[s] *= rate;
         dR[s] *= rate;
+        dW[s] = rate * dW[s] + pref * gp * aW[s];
       }
       for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= pref * gp * p.nu;
     }
     const slot = 1 + n + k, o = bf * M + slot;
     res[R[o]] = u[o] - rate;
     this._j(bf, slot, bf, slot, 1);
+    for (const sd of [0, 1]) if (dS[sd] !== 0) this._j(bf, slot, bf, this.diffList[dla[sd]].slot, -rate * dS[sd]);
+    if (!rx.srh) for (let q = 0; q < M; q++) if (dW[q] !== 0) this._j(bf, slot, bf, q, -dW[q]);
     for (let s = 0; s < M; s++) {
       if (dL[s] !== 0) this._j(bf, slot, bL, s, -dL[s]);
       if (dR[s] !== 0) this._j(bf, slot, bR, s, -dR[s]);

package/src/checks.js

@@ -181,6 +181,12 @@ function balance(device, sol) {
   // 1e-19 of its scale, to 1e-15), and round-off doesn't. (Above 1e-8 of the scale, any.)
   const balanced = (l) => Math.abs(l.terms.reduce((a, t) => a + t.rate, 0)) <= 1e-9 * size(l);
   const moving = ledgers.filter((l) => size(l) > 1e-8 * scale(l) || (size(l) > 1e-20 * scale(l) && balanced(l)));
+  // What's left unbalanced can be round-off or a small real flow the solve didn't settle (a
+  // reverse diode behind a resistance, 1.3 µA/m² at 4e-15 of its scale, balanced to 8e-5 by a
+  // solve that stalled), and nothing here tells them apart: round-off reaches 8e-12 of the scale
+  // in the stress devices, and one in a thousand of those flows balances to 1%. So above ε of the
+  // scale it isn't called equilibrium: the largest is named, as what balance can't check.
+  const unsure = ledgers.filter((l) => !moving.includes(l) && size(l) > 1e-16 * scale(l)).sort((a, b) => size(b) / scale(b) - size(a) / scale(a))[0];
   let worst = 0;
   const lines = [];
   for (const l of moving) {
@@ -195,7 +201,9 @@ function balance(device, sol) {
   const ok = worst < 1e-6;
   const summary =
     moving.length === 0
-      ? 'nothing flows or reacts (equilibrium)'
+      ? unsure
+        ? `nothing flows that it can tell from round-off: the largest, ${unsure.title} at ${sig(size(unsure))} ${units.rate}${unsure.z !== 0 ? ` (${sig(FARADAY * Math.abs(unsure.z) * size(unsure))} ${units.current})` : ''}, is ${sig(size(unsure) / scale(unsure), 1)} of what it could carry and doesn't balance (to ${sig(Math.abs(unsure.terms.reduce((a, t) => a + t.rate, 0)) / size(unsure), 1)}), so it's round-off, or a flow too small for this check`
+        : '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, ${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)));
@@ -373,7 +381,10 @@ function orderCheck(device, sol, gross) {
     diffs.push({ what: `${name} voltage`, a: t.V, b: u.V, rel: Math.abs(u.V - t.V) / (1e-6 * Math.max(VT, Math.abs(t.V))), unit: 'V' });
     if (gross > 0 && Math.max(Math.abs(t.current), Math.abs(u.current), gross) > floorI) diffs.push({ what: `${name} current`, a: t.current, b: u.current, rel: Math.abs(u.current - t.current) / (1e-3 * Math.max(Math.abs(t.current), Math.abs(u.current), gross)), unit: unitsOf(model).current });
   }
-  const vol = model.grid.vol, amount = (s, name) => s.x.reduce((m, _, g) => m + (Number.isFinite(s.c[name][g]) ? vol[g] * s.c[name][g] : 0), 0);
+  // (with what the faces' diffuse layers hold, below the grid)
+  const vol = model.grid.vol, area = model.grid.area;
+  const held = (s, name) => s.interfaces.reduce((m, itf, f) => m + Object.entries(itf.diffuse ?? {}).reduce((t, [side, d]) => t + area[side === 'left' ? model.grid.regionEnd[f] : model.grid.regionStart[f + 1]] * (d.excess[name] ?? 0), 0), 0);
+  const amount = (s, name) => s.x.reduce((m, _, g) => m + (Number.isFinite(s.c[name][g]) ? vol[g] * s.c[name][g] : 0), 0) + held(s, name);
   const amounts = model.species.map((sp) => [sp.name, amount(a, sp.name), amount(b, sp.name)]);
   const most = Math.max(0, ...amounts.map(([, x, y]) => Math.max(Math.abs(x), Math.abs(y))));
   for (const [name, x, y] of amounts) diffs.push({ what: `${name} amount`, a: x, b: y, rel: Math.abs(y - x) / (1e-6 * Math.max(Math.abs(x), Math.abs(y)) + 1e-12 * most), unit: unitsOf(model).amount });

package/src/describe.js

@@ -213,6 +213,8 @@ export function describe(def) {
       }
       const law = itf.phi.type === 'capacitive' ? `capacitive, C = ${num(itf.phi.C)} F/m²` : itf.phi.type;
       const align = itf.conductor ? (itf.phi.type === 'capacitive' ? `, zeroCharge ${num(itf.zeroCharge)} V` : '') : itf.phi.type === 'neutral' ? '' : `, dipole ${num(itf.dipole)} V`;
+      const sides = itf.diffuse ? [itf.diffuse.left && L.name, itf.diffuse.right && R.name].filter(Boolean) : [];
+      const diffuse = sides.length ? `; a diffuse layer below the grid (Gouy–Chapman, εr ${num(itf.diffuse.epsr)}) on the ${sides.join(' and ')} side${sides.length > 1 ? 's' : ''}` : '';
       const blocked = species.filter((sp, i) => itf.links[i].type === 'blocked' && materials[L.material].present[i] && materials[R.material].present[i]).map((sp) => sp.name);
       const kinetics = (r) => (r.vmax !== undefined ? ` (saturating, vmax ${num(r.vmax)} mol/(m²·s))` : r.srh ? ' (SRH)' : '');
       const rx = (idef.reactions ?? []).map((r) => (r.equation ?? equation(r.left, r.right)) + kinetics(r));
@@ -223,7 +225,7 @@ export function describe(def) {
       });
       const gates = (itf.gates ?? []).map((g) => g.name);
       lines.push(
-        `  ${L.name} | ${R.name}: ${law}${align}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}${gates.length ? `; gates (voltage-dependent, see interfaces[f].gates): ${gates.join(', ')}` : ''}`,
+        `  ${L.name} | ${R.name}: ${law}${align}${diffuse}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}${gates.length ? `; gates (voltage-dependent, see interfaces[f].gates): ${gates.join(', ')}` : ''}`,
       );
     });
   }

package/src/device.js

@@ -811,6 +811,7 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
       need(speciesIndex.has(sname), `${path}.bath.c.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
       const i = speciesIndex.get(sname);
       need(mat.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from ${reg.name} (material '${mat.name}'), so its level outside means nothing here`);
+      need(v !== 0, `${path}.bath.c.${sname}: a bath holds each species it lists at its level, and at 0 there is none (ln 0); a species absent from the bulk (a product, say) is a trace there, 1e-6 of the rest or so, so that it can leave`);
       cb[i] = positive(v, `${path}.bath.c.${sname}`);
     }
     const zb = bathZeta(mat, cb, reg.background);
@@ -993,7 +994,7 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   // macroscopic limit; the alignment then drops out. 'capacitive': a Helmholtz layer,
   // D = C (Δφ − dipole). Between two ε = 0 (strictly neutral) materials the default is neutral.
   if (matL.conductor || matR.conductor) return normalizeConductorInterface(idef, where, matL, matR, species, speciesIndex, RT);
-  fields(idef, where, ['phi', 'dipole', 'step', 'sheetCharge', 'species', 'reactions', 'gates']);
+  fields(idef, where, ['phi', 'dipole', 'step', 'sheetCharge', 'species', 'reactions', 'gates', 'diffuse']);
   const bothNeutral = (matL.epsr === 0 && matR.epsr === 0) || matL.phiFree || matR.phiFree;
   const rawPhi = idef.phi ?? (bothNeutral ? 'neutral' : 'pinned');
   const phi = typeof rawPhi === 'string' ? { type: rawPhi } : { ...rawPhi };
@@ -1004,7 +1005,7 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   // A pinned face is a capacitor of infinite C. With no field on either side (ε = 0), its
   // charge would sit as free excess ions in the edge cells at no cost, so nothing determines it.
   need(
-    !(phi.type === 'pinned' && matL.epsr === 0 && matR.epsr === 0),
+    !(phi.type === 'pinned' && matL.epsr === 0 && matR.epsr === 0 && idef.diffuse === undefined),
     `${where}.phi: 'pinned' between two ε = 0 materials leaves the face's charge undetermined (no field on either side to hold it); ` +
       "use 'neutral' (the default: a free Donnan jump), or { type: 'capacitive', C } for a charged layer such as a lipid bilayer",
   );
@@ -1075,7 +1076,55 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
 
   const reactions = normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT);
   checkReactingLinks(reactions, idef, where, matL, matR, species);
-  return { phi, dipole, sheetCharge, links, reactions, gates, conductor: null };
+  const diffuse = normalizeDiffuse(idef.diffuse, where, phi, matL, matR, species, reactions);
+  return { phi, dipole, sheetCharge, links, reactions, gates, conductor: null, diffuse };
+}
+
+// A face's diffuse layers (src/diffuse.js): { epsr } gives each strictly neutral side of a
+// charged face a Gouy–Chapman layer below the grid, of that permittivity, holding the side's
+// share of the face's charge as surface excesses of its ions instead of as excess ions in the
+// edge cell. Normalised to { epsr, left, right } (the sides that have one), or null.
+function normalizeDiffuse(raw, where, phi, matL, matR, species, reactions) {
+  if (raw === undefined) return null;
+  const path = `${where}.diffuse`;
+  need(isObject(raw), `${path} must be { epsr } (the diffuse layer's relative permittivity)`);
+  fields(raw, path, ['epsr']);
+  const epsr = positive(raw.epsr, `${path}.epsr`);
+  need(phi.type !== 'neutral', `${path}: a neutral face holds no charge, so it has no diffuse layer; give phi a capacitive (Stern) or pinned law`);
+  const charged = (mat) => species.some((sp, i) => mat.present[i] && sp.z !== 0);
+  const holds = (mat) => !mat.conductor && !mat.phiFree && mat.epsr === 0 && charged(mat);
+  const left = holds(matL), right = holds(matR);
+  need(
+    left || right,
+    `${path}: neither side is a strictly neutral (ε = 0) material with ions in it, so there is no diffuse layer below the grid to model; ` +
+      'where ε > 0 the grid resolves the double layer itself (refine it below the Debye length)',
+  );
+  const lattice = [null, null];
+  for (const [mat, has, side] of [[matL, left, 0], [matR, right, 1]]) {
+    if (!has) continue;
+    // Its ions dilute (ideal), or all on one lattice (crowding: Bikerman's layer, on the bulk's own sites).
+    const charged = species.flatMap((sp, i) => (mat.present[i] && sp.z !== 0 ? [i] : []));
+    const md = mat.modelOf[charged[0]] >= 0 ? mat.models[mat.modelOf[charged[0]]] : null;
+    for (const i of charged) {
+      need(
+        md ? mat.modelOf[i] >= 0 && mat.models[mat.modelOf[i]] === md && md.type === 'lattice' : mat.modelOf[i] < 0,
+        `${path}: '${species[i].name}' in '${mat.name}' has statistics a diffuse layer can't take: its ions must all be ideal (a dilute layer) ` +
+          'or all on one lattice model (a crowded one, on the same sites); or resolve the double layer (epsr > 0, hmin below the Debye length)',
+      );
+    }
+    if (md) lattice[side] = { cMax: md.cMax, on: Uint8Array.from(species, (_, i) => (md.idx.includes(i) ? 1 : 0)) };
+    for (let i = 0; i < species.length; i++) {
+      need(
+        !(mat.present[i] && species[i].z !== 0 && !(mat.D[i] > 0)),
+        `${path}: '${species[i].name}' is charged and can't move in '${mat.name}' (D = 0), so it can't gather into a diffuse layer as a Boltzmann layer's ions do; ` +
+          'make it fixed charge (the region\'s fixedCharge), or resolve the double layer (epsr > 0)',
+      );
+    }
+    for (const rx of reactions) {
+      if (rx.srh && rx.part.some((p) => p.side === side)) need(false, `${path}: SRH kinetics beside a diffuse layer isn't supported (its carriers would be read at the plane); resolve the layer instead`);
+    }
+  }
+  return { epsr, left, right, lattice };
 }
 
 // A face's gates (Hodgkin–Huxley): each a fraction x in [0, 1] with first-order kinetics in the
@@ -1157,7 +1206,7 @@ function normalizeConductor(mat, mname, path, species, speciesIndex) {
 function normalizeConductorInterface(idef, where, matL, matR, species, speciesIndex, RT) {
   if (idef === undefined || idef === null) idef = {};
   need(isObject(idef), `${where} must be an object`);
-  fields(idef, where, ['phi', 'zeroCharge', 'dipole', 'step', 'sheetCharge', 'species', 'reactions']); // (the alignment fields only to say why not)
+  fields(idef, where, ['phi', 'zeroCharge', 'dipole', 'step', 'sheetCharge', 'species', 'reactions', 'diffuse']); // (the alignment fields only to say why not)
   const side = matL.conductor ? (matR.conductor ? 'both' : 'left') : 'right';
   const other = side === 'left' ? matR : matL;
   const metal = side === 'right' ? matR.conductor : matL.conductor;
@@ -1211,7 +1260,8 @@ function normalizeConductorInterface(idef, where, matL, matR, species, speciesIn
   }
   const reactions = normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT);
   checkReactingLinks(reactions, idef, where, matL, matR, species);
-  return { phi, dipole: 0, zeroCharge, sheetCharge: 0, links, reactions, gates: [], conductor: { side, i: metal.i } };
+  const diffuse = normalizeDiffuse(idef.diffuse, where, phi, matL, matR, species, reactions);
+  return { phi, dipole: 0, zeroCharge, sheetCharge: 0, links, reactions, gates: [], conductor: { side, i: metal.i }, diffuse };
 }
 
 // A species present on both sides crosses freely; one that can't move on either (D = 0, trap
@@ -1359,6 +1409,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
       need(speciesIndex.has(sname), `${path}.bath.c.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
       const i = speciesIndex.get(sname);
       need(bm.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from ${own ? 'the bath' : 'the end'} material '${bm.name}'`);
+      need(v !== 0, `${path}.bath.c.${sname}: a bath holds each species it lists at its level, and at 0 there is none (ln 0); a species absent from the bulk (a product, say) is a trace there, 1e-6 of the rest or so, so that it can leave`);
       cb[i] = positive(v, `${path}.bath.c.${sname}`);
       charge += species[i].z * cb[i];
       scale += Math.abs(species[i].z) * cb[i];
@@ -1413,6 +1464,20 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
       links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0),
       `${path}.phi: 'bulk' needs at least one connected charged species at this contact`,
     );
+    // Neutral at the contact must be possible: an undoped layer of holes alone never is, and
+    // ohmic(V, ['h+']) on one failed with "nothing specific showed why" (round 16's cold agent).
+    if (!mat.conductor && !mat.phiFree && !mat.models.some((md) => md.type === 'insertion')) {
+      const signs = new Set(species.flatMap((sp, i) => (mat.present[i] && sp.z !== 0 ? [Math.sign(sp.z)] : [])));
+      const fixed = Math.sign(region.fixedCharge ?? 0);
+      if (signs.size === 1 && !(fixed !== 0 && !signs.has(fixed))) {
+        const [only] = signs;
+        throw new DeviceError(
+          `${path}.phi: 'bulk' (what ohmic() and a bath use) holds the contact neutral, but '${region.name ?? region.material}' can't be: ` +
+            `its only charged species are ${only > 0 ? 'positive' : 'negative'} and no fixed charge balances them (an undoped layer of one carrier). ` +
+            "For a contact that sets the carrier's density, pin φ instead: phi: 'pinned' with zeroCharge, the contact's level against the carrier's (see docs/device.md, contacts).",
+        );
+      }
+    }
   }
 
   if (terminal !== null) {