driftlet 1.3.2 → 1.4.0

package/src/diffuse.js

@@ -0,0 +1,240 @@
+// A diffuse (Gouy–Chapman) layer treated analytically: the ions' Boltzmann layer beside a face,
+// between the face's plane of closest approach and a strictly neutral bulk, held as one number
+// per face side instead of on the grid.
+//
+// CONTRACT
+//
+// diffuseLayer(c, z, n, s, kappaUnits, out, lattice, draw) is a pure function of its arguments.
+//   c (mol/m³): the bulk concentrations beside the layer, n of them (species absent there at 0);
+//   z: their charges; s = F ψ/RT, the diffuse drop ψ = φ(plane) − φ(bulk) in thermal units;
+//   kappaUnits = { A: √(ε RT/2)/F (mol/m² per √(mol/m³)), B: √(2 ε RT) (C/m² per √(mol/m³)) },
+//   ε the layer's permittivity (F/m); lattice null (dilute ions) or { cMax, on }, the bulk's lattice
+//   statistics (src/statistics.js), on[i] = 1 for the species on its sites (every charged one);
+//   draw null, or draw[i] = 1 for the species whose transport across the layer is wanted (K below).
+// Dilute, c_i(s) = c_i e^{−z_i s}; crowded (Bikerman: the same sites as the bulk's lattice), divided
+// by D(s) = 1 + Σ_on θ_j (e^{−z_j s} − 1), θ_j = c_j/cMax, and the first integral is then
+// G(s) = cMax ln D + s Σ c_j z_j, its neutral species displaced from the plane (an excess < 0).
+// It writes into out (a scratch object it fills: { q, dqds, dqdc[n], gam[n], dgds[n], dgdc[n×n],
+// K[n], dKds[n], dKdc[n×n], D, dDds, dDdc[n] }: D(s) and its derivatives, 1 and 0 for a dilute layer):
+//   q    the layer's charge per area (C/m²), −B s √R(s), R = G/t²; dilute, R(t) = Σ_j c_j z_j² ρ(z_j t),
+//        ρ(x) = (e^{−x} − 1 + x)/x², so R(t) t² = Σ c_j (e^{−z_j t} − 1 + z_j t), the first
+//        integral of Poisson–Boltzmann (exact where the bulk is neutral, F Σ z c + ρ_fixed = 0,
+//        with any fixed charge uniform through the layer as in the bulk; written with its linear
+//        term so it stays ≥ 0 off neutrality, as Newton's iterates are);
+//   gam  each species' surface excess ∫ (c_i(x) − c_i) dx (mol/m²), c_i A ∫₀ˢ E_i(t)/√R(t) dt,
+//        E_i(t) = (c_i(t)/c_i − 1)/t: smooth through s = 0, where everything vanishes (crowded,
+//        written so that no two large terms cancel, past |X| = 1 by G whole);
+//   K    for each drawn species, the layer's resistance to it in excess of the bulk's it displaces,
+//        as a length (m): K_i = ∫ (c_i/c_i(x) − 1) dx = A ∫₀ˢ H_i(t)/√R(t) dt, H_i = (c_i/c_i(t) − 1)/t.
+//        A flux N_i toward the plane (mol/(m²·s)), through the layer's profile, lowers its level
+//        there: a_plane = a_edge (1 − N_i K_i/(D_i c_i)), exact for a species too dilute to shape the
+//        layer (the reactant a charged electrode repels, the case that matters: K_i grows as
+//        c_i/c_i(plane)), first order in N otherwise; < 0 for one the layer gathers;
+//   and their derivatives: dqds = ∂q/∂s, dqdc[j] = ∂q/∂c_j, dgds[i] = ∂Γ_i/∂s,
+//   dgdc[i·n + j] = ∂Γ_i/∂c_j, dKds[i] = ∂K_i/∂s, dKdc[i·n + j] = ∂K_i/∂c_j (0 where not drawn).
+// Invariants (each says what a reviewer should be able to check here):
+//   1. F Σ z_i Γ_i = q at a neutral bulk (Gauss's law across the layer), to the quadrature's
+//      accuracy (≤ 1e-13 relative).
+//   2. q, Γ_i are odd in (s, z) together: flipping every charge and s gives −q and the same Γ.
+//   3. The derivatives are those of the functions (the quadrature's error aside): ∂/∂s exact by
+//      the fundamental theorem, ∂/∂c_j by the same rule as Γ (and K).
+//   4. Against the Poisson–Boltzmann problem solved in x (scipy solve_bvp), and a z:z salt's
+//      closed forms q = −√(8εRTc) sinh(zs/2), Γ_± = (2c/κ)(e^{∓zs/2} − 1): within 1e-9 and 1e-14
+//      (test/diffuse.test.js, the tables from the answer sheets); crowded, against the same
+//      problem with the lattice's concentrations, and Kilic–Bazant–Ajdari's q for a z:z salt;
+//      K, against ∫ (e^{z φ̃(x)} − 1) dx on that problem's profile, and a z:z salt's closed form
+//      (2/κ)(e^{±zs/2} − 1) (its own Γ with the charge flipped: c/c(x) = e^{+z φ̃}).
+// A dilute layer overstates the charge and the excesses once the plane's concentration passes a
+// few molar; a lattice bounds it at cMax. Arguments past |z s| = 600 are held there (e^600 is
+// the end of double precision), so absurd Newton iterates stay finite.
+
+// Gauss–Legendre, 8 points on [0, 1].
+const GL_X = [0.019855071751231856, 0.10166676129318664, 0.2372337950418355, 0.4082826787521751, 0.5917173212478249, 0.7627662049581645, 0.8983332387068134, 0.9801449282487681];
+const GL_W = [0.05061426814518813, 0.11119051722668724, 0.15685332293894363, 0.18134189168918100, 0.18134189168918100, 0.15685332293894363, 0.11119051722668724, 0.05061426814518813];
+const CAP = 600;
+
+// ρ(x) = (e^{−x} − 1 + x)/x² (1/2 at 0), by its series where the difference would cancel.
+function rho(x) {
+  if (x > CAP) x = CAP;
+  else if (x < -CAP) x = -CAP;
+  if (Math.abs(x) < 0.5) {
+    // Σ_{k≥0} (−x)^k/(k+2)!
+    let term = 0.5, sum = 0.5;
+    for (let k = 1; k < 18; k++) {
+      term *= -x / (k + 2);
+      sum += term;
+    }
+    return sum;
+  }
+  return (Math.expm1(-x) + x) / (x * x);
+}
+
+// e(x) = (1 − e^{−x})/x (1 at 0), so E_i(t) = −z_i e(z_i t).
+function eps1(x) {
+  if (x > CAP) x = CAP;
+  else if (x < -CAP) x = -CAP;
+  return x === 0 ? 1 : -Math.expm1(-x) / x;
+}
+
+// λ(X) = (log1p(X) − X)/X² (−1/2 at 0), by its series where the difference would cancel.
+function lam(X) {
+  if (Math.abs(X) < 0.1) {
+    // Σ_{k≥0} (−1)^{k+1} X^k/(k + 2)
+    let p = 1, sum = 0;
+    for (let k = 0; k < 24; k++, p *= -X) sum -= p / (k + 2);
+    return sum;
+  }
+  return (Math.log1p(X) - X) / (X * X);
+}
+
+// The layer's functions at t (a scratch `at` to fill): R(t) = G(t)/t², each species' E_i(t) =
+// (c_i(t)/c_i − 1)/t, and their ∂/∂c_j, R_j and (crowded) Ec_ij = ∂E_i/∂c_j; and D(t), its ∂/∂t and
+// ∂/∂c_j. Dilute: c_i(t) = c_i e^{−z_i t}; on a lattice of cMax sites, divided by D(t) = 1 + X(t),
+// X = Σ_lattice θ_j (e^{−z_j t} − 1), θ_j = c_j/cMax, and G = cMax ln D + t Σ c_j z_j (Bikerman).
+// Drawn (draw[i]), H_i(t) = (c_i/c_i(t) − 1)/t too, the resistance's integrand, and (crowded)
+// Hc_ij = ∂H_i/∂c_j.
+function functionsAt(c, z, n, t, lat, at, draw) {
+  const { Rj, E, Ec, dDdc, H, Hc } = at;
+  let R = 0;
+  for (let j = 0; j < n; j++) {
+    Rj[j] = z[j] !== 0 ? z[j] * z[j] * rho(z[j] * t) : 0;
+    if (c[j] > 0) R += c[j] * Rj[j];
+    E[j] = z[j] !== 0 ? -z[j] * eps1(z[j] * t) : 0;
+    if (draw) H[j] = draw[j] && z[j] !== 0 ? z[j] * eps1(-z[j] * t) : 0; // (e^{z t} − 1)/t
+  }
+  at.D = 1;
+  at.dDdt = 0;
+  if (!lat) {
+    at.R = R;
+    return at;
+  }
+  // Y = X/t, smooth through 0; D' = −Σ θ z e^{−z t}
+  const { cMax, on } = lat;
+  let Y = 0, dD = 0;
+  for (let j = 0; j < n; j++) {
+    dDdc[j] = 0;
+    if (!on[j] || z[j] === 0) continue;
+    const x = Math.max(-CAP, Math.min(CAP, -z[j] * t));
+    Y -= ((c[j] > 0 ? c[j] : 0) / cMax) * z[j] * eps1(z[j] * t);
+    dD -= ((c[j] > 0 ? c[j] : 0) / cMax) * z[j] * Math.exp(x);
+    dDdc[j] = Math.expm1(x) / cMax;
+  }
+  const X = Y * t, D = 1 + X;
+  at.D = D;
+  at.dDdt = dD;
+  if (Math.abs(X) <= 1) {
+    // the dilute layer's R and a correction, cMax (log1p X − X)/t² = cMax Y² λ(X); its ∂/∂c_j, Y z_j e(z_j t)/D
+    at.R = R + cMax * Y * Y * lam(X);
+    for (let j = 0; j < n; j++) if (on[j] && z[j] !== 0) Rj[j] += (Y * z[j] * eps1(z[j] * t)) / D;
+  } else {
+    // (far out, where the two would cancel: G whole, and ∂G/∂c_j = expm1(−z_j t)/D + z_j t)
+    let Gl = cMax * Math.log1p(X);
+    for (let j = 0; j < n; j++) if (on[j] && z[j] !== 0 && c[j] > 0) Gl += c[j] * z[j] * t;
+    at.R = Gl / (t * t);
+    for (let j = 0; j < n; j++) if (on[j] && z[j] !== 0) Rj[j] = (Math.expm1(Math.max(-CAP, Math.min(CAP, -z[j] * t))) / D + z[j] * t) / (t * t);
+  }
+  // E_i = (e^{−z_i t}/D − 1)/t = (−z_i e(z_i t) − Y)/D, a lattice's neutral species too; ∂E_i/∂c_j = e^{−z_i t} z_j e(z_j t)/(cMax D²)
+  for (let i = 0; i < n; i++) {
+    if (!on[i]) continue;
+    E[i] = (E[i] - Y) / D;
+    const w = Math.exp(Math.max(-CAP, Math.min(CAP, -z[i] * t))) / (cMax * D * D);
+    for (let j = 0; j < n; j++) Ec[i * n + j] = on[j] && z[j] !== 0 ? w * z[j] * eps1(z[j] * t) : 0;
+    // H_i = (e^{z_i t} D − 1)/t = z_i e(−z_i t) + e^{z_i t} Y; ∂H_i/∂c_j = −e^{z_i t} z_j e(z_j t)/cMax
+    if (!draw?.[i]) continue;
+    const up = Math.exp(Math.max(-CAP, Math.min(CAP, z[i] * t)));
+    H[i] += up * Y;
+    for (let j = 0; j < n; j++) Hc[i * n + j] = on[j] && z[j] !== 0 ? (-up * z[j] * eps1(z[j] * t)) / cMax : 0;
+  }
+  return at;
+}
+
+/** The diffuse layer's charge, excesses and their derivatives (see the contract above). */
+export function diffuseLayer(c, z, n, s, { A, B }, out, lat = null, draw = null) {
+  const { dqdc, gam, dgds, dgdc, K, dKds, dKdc } = out;
+  let zmax = 0;
+  for (let i = 0; i < n; i++) if (c[i] > 0) zmax = Math.max(zmax, Math.abs(z[i]));
+  gam.fill(0);
+  dgds.fill(0);
+  dgdc.fill(0);
+  dqdc.fill(0);
+  K.fill(0);
+  dKds.fill(0);
+  dKdc.fill(0);
+  out.D = 1;
+  out.dDds = 0;
+  out.dDdc.fill(0);
+  if (zmax === 0) {
+    out.q = 0;
+    out.dqds = 0;
+    return out;
+  }
+  const holds = (i) => z[i] !== 0 || (lat && lat.on[i]); // (a lattice's neutral species is displaced)
+  const at = out.at ?? (out.at = { Rj: new Float64Array(n), E: new Float64Array(n), Ec: new Float64Array(n * n), dDdc: new Float64Array(n), H: new Float64Array(n), Hc: new Float64Array(n * n) });
+  if (draw) at.Hc.fill(0);
+  // At s itself: the charge and the ∂/∂s.
+  functionsAt(c, z, n, s, lat, at, draw);
+  const sqR = Math.sqrt(at.R);
+  out.q = -B * s * sqR;
+  out.D = at.D;
+  out.dDds = at.dDdt;
+  out.dDdc.set(at.dDdc);
+  let dq = 0;
+  for (let i = 0; i < n; i++) {
+    if (!(c[i] > 0) || !holds(i)) continue;
+    dgds[i] = (c[i] * A * at.E[i]) / sqR;
+    dq += c[i] * z[i] * at.E[i];
+  }
+  if (draw) for (let i = 0; i < n; i++) if (draw[i]) dKds[i] = (A * at.H[i]) / sqR;
+  out.dqds = (B * dq) / (2 * sqR);
+  for (let j = 0; j < n; j++) dqdc[j] = (-B * s * at.Rj[j]) / (2 * sqR);
+  if (s === 0) return out;
+  // ∫₀ˢ by panels a unit of z_max·t wide (each spans at most an e-fold of the integrand), 8 points each.
+  const panels = Math.max(1, Math.ceil(Math.min(Math.abs(s), CAP) * zmax)), h = s / panels;
+  const I = out.I ?? (out.I = new Float64Array(n));
+  I.fill(0);
+  for (let p = 0; p < panels; p++) {
+    for (let k = 0; k < 8; k++) {
+      const t = (p + GL_X[k]) * h, w = GL_W[k] * h;
+      functionsAt(c, z, n, t, lat, at, draw);
+      const r12 = 1 / Math.sqrt(at.R), r32 = r12 / at.R;
+      if (draw) {
+        // K_i = A ∫ H_i R^{-1/2}; its ∂/∂c_j, A ∫ (Hc_ij R^{-1/2} − ½ H_i R_j R^{-3/2})
+        for (let i = 0; i < n; i++) {
+          if (!draw[i]) continue;
+          K[i] += w * at.H[i] * r12;
+          const f = -0.5 * w * at.H[i] * r32;
+          for (let j = 0; j < n; j++) dKdc[i * n + j] += f * at.Rj[j] + w * at.Hc[i * n + j] * r12;
+        }
+      }
+      for (let i = 0; i < n; i++) {
+        if (!holds(i)) continue;
+        I[i] += w * at.E[i] * r12;
+        // ∂/∂c_j of c_i ∫ E_i R^{-1/2}: c_i ∫ (∂E_i/∂c_j R^{-1/2} − ½ E_i R_j R^{-3/2})
+        if (!(c[i] > 0)) continue;
+        const f = -0.5 * w * at.E[i] * r32 * c[i];
+        for (let j = 0; j < n; j++) dgdc[i * n + j] += f * at.Rj[j] + (lat && lat.on[i] ? w * c[i] * at.Ec[i * n + j] * r12 : 0);
+      }
+    }
+  }
+  for (let i = 0; i < n; i++) {
+    if (!holds(i)) continue;
+    gam[i] = (c[i] > 0 ? c[i] : 0) * A * I[i];
+    for (let j = 0; j < n; j++) dgdc[i * n + j] *= A;
+    dgdc[i * n + i] += A * I[i];
+  }
+  if (draw) {
+    for (let i = 0; i < n; i++) K[i] *= A;
+    for (let k = 0; k < n * n; k++) dKdc[k] *= A;
+  }
+  return out;
+}
+
+/** A scratch object for diffuseLayer over n species. */
+export function diffuseScratch(n) {
+  return { q: 0, dqds: 0, dqdc: new Float64Array(n), gam: new Float64Array(n), dgds: new Float64Array(n), dgdc: new Float64Array(n * n), K: new Float64Array(n), dKds: new Float64Array(n), dKdc: new Float64Array(n * n), D: 1, dDds: 0, dDdc: new Float64Array(n) };
+}
+
+/** The constants A = √(εRT/2)/F and B = √(2εRT) for a layer of permittivity eps (F/m) at RT (J/mol). */
+export function diffuseUnits(eps, RT, F) {
+  return { A: Math.sqrt((eps * RT) / 2) / F, B: Math.sqrt(2 * eps * RT) };
+}

package/src/impedance.js

@@ -84,7 +84,7 @@
 //      in J (the assembly here runs with this.steady false).
 //   4. Deterministic: the same state, frequencies and options give the same Z, bit for bit.
 // Also written, left as the last assembly at dt = ∞ left them: this.sourceTime (the present
-// time), cOld, thOld, th0Old, gateOld (the present state's), contactDStart, portQStart, the
+// time), cOld, thOld, th0Old, gamOld, gateOld (the present state's), contactDStart, portQStart, the
 // residual, the Jacobian and the terminal terms, sysRest and the concentrations; this.lawForm
 // (every circuit law by the change, until a step sets it afresh).
 // Tests: test/impedance.test.js (Macdonald's blocking electrodes, a junction's depletion
@@ -272,6 +272,7 @@ export class SmallSignal {
     this.cOld.set(this.c);
     this.thOld.set(this.th);
     this.th0Old.set(this.th0);
+    this.gamOld.set(this.gam);
     this.gateList.forEach((gt, j) => (this.gateOld[j] = this.u[gt.o] + this.uLo[gt.o]));
     this.assemble(Infinity);
     this.contactDStart = { ...this.contactD };

package/src/kit.js

@@ -50,10 +50,14 @@ export function vacuumLevel(def, side, path = 'vacuum') {
   if (!Number.isFinite(side.offset)) fail(`${path}.offset must be a finite number (V)`);
   if (side.anchor === 'phi') return -side.offset;
   const sp = (def.species ?? []).find((s) => s.name === side.anchor);
-  if (!sp) fail(`${path}.anchor must be 'phi' or a charged species, got ${JSON.stringify(side.anchor)}`);
+  if (!sp)
+    fail(
+      `${path}.anchor must be 'phi' or a charged species of the device, got ${JSON.stringify(side.anchor)}` +
+        (typeof side.anchor === 'string' ? ` (to anchor on it, list it in the library: aqueous([..., '${side.anchor}']), say)` : ''),
+    );
   if (!(sp.z !== 0)) fail(`${path}.anchor: '${side.anchor}' is neutral, so it has no level in volts`);
   const entry = mat.species?.[side.anchor];
-  if (!isObject(entry)) fail(`${path}.anchor: '${side.anchor}' is absent from '${side.material}'`);
+  if (!isObject(entry)) fail(`${path}.anchor: '${side.anchor}' is absent from '${side.material}' (to anchor on it, give the material that species)`);
   if (!Number.isFinite(entry.mu0)) fail(`${path}.anchor: '${side.anchor}' in '${side.material}' has no mu0`);
   return entry.mu0 / (sp.z * FARADAY) - side.offset;
 }

package/src/lawRows.js

@@ -59,7 +59,9 @@
 //   affinity         pin: fixedA − Σ ν η at the face's two nodes = 0, ∂ = −ν.
 //   constraint       in a balance row, a pin: amount − ref = 0 (ref: its reference without
 //                    terminals, else lawRefs; with no reference captured there, none, the amount
-//                    held where it is), its ∂ from lawAmount. In terminal k's circuit row
+//                    held where it is), its ∂ from lawAmount. A stretch's amount is Σ vol·c over
+//                    its nodes and A_f Γ_i of each face's diffuse layer at them (s.gam; its ∂
+//                    by the layer's drop and its edge node's slots). In terminal k's circuit row
 //                    (in place of what Solver._terminals wrote): the same, its contacts' charges
 //                    λ·D_in/F added from s.contactQ[t] (as Solver._contact captured them in this
 //                    assembly), termDI and termDX from the electrodes' charges' ∂/∂V.
@@ -316,6 +318,28 @@ function lawAmount(s, cs) {
       }
     }
   }
+  // What the faces' diffuse layers hold of it (src/diffuse.js): A_f Γ_i at their edge nodes, Γ a
+  // function of the layer's drop and the edge node's c (through its ∂c_j/∂(φ̂, η): _diffuseChain).
+  for (const { stretch, w } of cs.parts) {
+    const st = s.stretches[stretch], i = st.species;
+    s.diffList.forEach((dl, k) => {
+      const g = dl.g;
+      if (g < st.nodes[0] || g > st.nodes[1] || !dl.holds[i]) return;
+      const f = w * s.model.grid.area[g], b = dl.b, D = dl.dl, dc = s._diffuseChain(k);
+      amount += f * s.gam[k * n + i];
+      gross += Math.abs(f * s.gam[k * n + i]);
+      cs.idx[len] = s.rix[dl.o];
+      cs.w[len++] = f * D.dgds[i];
+      for (let r = 0; r <= n; r++) {
+        if (s.loc[b * M + r] < 0) continue;
+        let v = 0;
+        for (let j = 0; j < n; j++) v += D.dgdc[i * n + j] * dc[j * M + r];
+        if (v === 0) continue;
+        cs.idx[len] = s.rix[b * M + r];
+        cs.w[len++] = f * v;
+      }
+    });
+  }
   // 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] = s.surfCols[col], port = s.model.ports[k], G = port.surface[0].capacity, ns = port.surface.length;
@@ -362,6 +386,7 @@ function lawStart(s, cs) {
   for (const { stretch, w } of cs.parts) {
     const st = s.stretches[stretch], i = st.species;
     for (let g = st.nodes[0]; g <= st.nodes[1]; g++) a += w * vol[g] * s.cOld[g * n + i];
+    s.diffList.forEach((dl, k) => dl.g >= st.nodes[0] && dl.g <= st.nodes[1] && (a += w * s.model.grid.area[dl.g] * s.gamOld[k * n + i]));
   }
   for (const { col, w } of cs.surface) {
     const [k, q] = s.surfCols[col], port = s.model.ports[k], G = port.surface[0].capacity;

package/src/newton.js

@@ -20,8 +20,10 @@
 //      its message.
 //   2. Solved for the update; refined (7) where refining is on.
 //   3. Its size: `step`, the largest |Δ| over φ̂ and each present η at the grid's nodes (a metal's
-//      carrier, not its flux slot), each coverage and gate fraction, and each floating terminal's
-//      |ΔV|/V_T; `own`, the same without the terminals.
+//      carrier, not its flux slot), each coverage and gate fraction, each diffuse layer's drop and
+//      its drawn species' plane levels, and each floating terminal's |ΔV|/V_T; `own`, the same
+//      without the terminals and the diffuse layers, each plane level's own update clipped to
+//      ±maxStep first.
 //   4. Fails where step isn't finite ('non-finite update'), or where own > 1e4 after the first
 //      iteration, or own > 10× the first's after the sixth ('diverging').
 //   5. Added, damped by α = min(1, maxStep/own) (the terminal voltages by the same α), u and uLo
@@ -283,8 +285,22 @@ function refineSolve(s, dt, delta, deltaV) {
   }
 }
 
-// Largest update among the potential-like unknowns (φ̂ and η at grid nodes).
-export function maxPotentialStep(s, delta, deltaV = s.deltaV) { // (deltaV null: the device's potentials only)
+// Each diffuse layer's drawn species' plane level, its update clipped to ±maxStep.
+function clipLevels(s, delta, maxStep) {
+  const R = s.rix;
+  for (const d of s.diffList) {
+    const bf = s.blockOfFace[d.f];
+    for (const q of d.drawSlot) {
+      if (q < 0) continue;
+      const k = R[bf * s.M + q];
+      if (Math.abs(delta[k]) > maxStep) delta[k] = Math.sign(delta[k]) * maxStep;
+    }
+  }
+}
+
+// Largest update among the potential-like unknowns (φ̂ and η at grid nodes; layers false leaves out
+// the diffuse layers' drops and plane levels).
+export function maxPotentialStep(s, delta, deltaV = s.deltaV, layers = true) { // (deltaV null: the device's potentials only)
   const { n, M } = s;
   const R = s.rix; // (the sink entry of delta is 0)
   let mx = 0;
@@ -299,6 +315,11 @@ export function maxPotentialStep(s, delta, deltaV = s.deltaV) { // (deltaV null:
     if (k >= 0) for (let q = 0; q < s.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + n + q]]));
   }
   for (const gt of s.gateList) mx = Math.max(mx, Math.abs(delta[R[gt.o]])); // a gate's fraction open
+  if (layers) for (const d of s.diffList) { // a diffuse layer's drop, and its drawn species' levels at its plane, as η
+    const bf = s.blockOfFace[d.f];
+    mx = Math.max(mx, Math.abs(delta[R[d.o]]));
+    for (const q of d.drawSlot) if (q >= 0) mx = Math.max(mx, Math.abs(delta[R[bf * M + q]]));
+  }
   return mx;
 }
 
@@ -484,8 +505,13 @@ export function newton(s, dt, { maxIter = 60, tol = 1e-10, maxStep = 10, islands
     // linearly (conductance links, held levels, a capacitive face), so a large swing in one is
     // safe, and damping it would throttle the whole update (a current-driven port switching
     // off, its voltage collapsing by hundreds of volts, crawled 10 thermal units at a time).
+    // (So do the diffuse layers' drops, set by the potentials, and their drawn species' plane
+    // levels, each level's own update clipped to maxStep instead: far from the solution a
+    // reaction's rate can ask more of its layer than it can pass, and the level's update then
+    // heads for −∞.)
+    clipLevels(s, delta, maxStep);
     const step = maxPotentialStep(s, delta, deltaV);
-    const own = maxPotentialStep(s, delta, null);
+    const own = maxPotentialStep(s, delta, null, false);
     // A refined correction the next update keeps (under a tenth of it) was a lost mode: this
     // device's time steps are refined from now on, a convergence taken only on a refined update.
     if (candidate > 0 && step < 0.1 * candidate) s.lostMode = true;

package/src/regions.js

@@ -20,7 +20,9 @@
 //     potential; a species no model holds is ideal there;
 //   a conductor's node: no bulk concentration; its carrier's c is the excess charge of a charged
 //     face's sheet, sheetSign·D·A/(zF·vol);
-//   absent species: c = 0; then the coverages (_coverages: Langmuir, θ_s = e^{ζ_s}/(1 + Σe^ζ)).
+//   absent species: c = 0; then the coverages (_coverages: Langmuir, θ_s = e^{ζ_s}/(1 + Σe^ζ)),
+//   and the faces' diffuse layers from their edge nodes' c and their drops (_diffuseLayers in
+//   src/boundaries.js: q, Γ and their derivatives, into each layer's scratch and gam).
 //   ∂c_i/∂η_j = K_ij, ∂c_i/∂φ̂ = −(Kz)_i (_Kz; _dlnc adds these as ∂ln c, _dc sets them as ∂c).
 //   At a non-ideal node of a region with eddy mixing (nodeDK), K's slope dK = ∂K/∂ζ as well.
 //
@@ -70,8 +72,8 @@
 //   2. A segment's flux goes into its two nodes' rows with opposite signs, the same number.
 //   3. At a level μ̄ along a segment (Δη = 0, no velocity), its flux and mixing are exactly 0;
 //      at a = 0 a bulk reaction's rate is exactly 0.
-//   4. computeConcentrations writes c, K, ex, th, th0, dK at the nodeDK nodes (and scratch:
-//      zeta, the statistics models' work arrays) and nothing else; the kernels write res,
+//   4. computeConcentrations writes c, K, ex, th, th0, gam, dK at the nodeDK nodes (and scratch:
+//      zeta, the statistics models' work arrays, the diffuse layers' dl) and nothing else; the kernels write res,
 //      sys (or lin), termB/termC (the charge rows), and scratch kept on the Solver (dA, dB, jL,
 //      jR, sg, mixWork, mixCrowd) or cached on a material (mobile).
 //   5. The charge rows are an invertible transformation of the equations at the node (the same
@@ -156,6 +158,7 @@ export class RegionTerms {
       }
     }
     this._coverages();
+    if (this.diffList.length > 0) this._diffuseLayers();
   }
 
   _work(md) {

package/src/solution.js

@@ -6,6 +6,10 @@
 
 import { EPS0, FARADAY } from './constants.js';
 
+// A diffuse layer's plane past this concentration (mol/m³, 5 M) has its counter-ions closer than
+// hydrated ions pack, beyond what a dilute layer describes.
+const DIFFUSE_CROWDED = 5000;
+
 export function makeSolution(solver, result = {}) {
   const { model, n, M, u, c, VT } = solver;
   const { grid, species, contacts, interfaces } = model;
@@ -184,6 +188,21 @@ export function makeSolution(solver, result = {}) {
     out.links = Object.fromEntries(itf.links.flatMap((l, i) => (l.type === 'blocked' ? [] : [[species[i].name, l.type]])));
     const oneWay = solver.faceOneWay(f);
     if (oneWay.some((w) => w)) out.oneWay = Object.fromEntries(oneWay.flatMap((w, i) => (w ? [[species[i].name, w]] : [])));
+    // Its diffuse layers (src/diffuse.js), per side: the drop ψ = φ(plane) − φ(edge) (V), the
+    // layer's charge (C/m²) and each ion's surface excess (mol/m²), and each ion's concentration
+    // at the plane, c e^{−zFψ/RT} (mol/m³), which the face's reactions see.
+    solver.diffAt[f].forEach((d, side) => {
+      if (d < 0) return;
+      const dl = solver.diffList[d], sd = u[dl.o], excess = {}, plane = {};
+      for (let i = 0; i < n; i++) {
+        if (!solver.present[dl.g * n + i]) continue;
+        excess[species[i].name] = solver.gam[d * n + i];
+        // (crowded: over D; drawn by a reaction, times e^w, its level there below the edge's)
+        const w = dl.drawSlot[i] < 0 ? 0 : u[solver.blockOfFace[f] * solver.M + dl.drawSlot[i]];
+        plane[species[i].name] = (c[dl.g * n + i] * Math.exp(-species[i].z * sd + w)) / (dl.holds[i] ? dl.dl.D : 1);
+      }
+      (out.diffuse ??= {})[side ? 'right' : 'left'] = { psi: solver.VT * sd, charge: dl.dl.q, excess, plane };
+    });
     if (itf.gates.length > 0) {
       // Each gate's fraction open, and the voltage across the face that drives them.
       out.gates = Object.fromEntries(itf.gates.map((gate, q) => [gate.name, u[solver._gateSlot(f, q)]]));
@@ -222,6 +241,7 @@ export function makeSolution(solver, result = {}) {
     q += grid.vol[g] * rho;
   }
   interfaces.forEach((itf, f) => (q += itf.sheetCharge * grid.area[grid.regionEnd[f]]));
+  solver.diffList.forEach((d) => (q += d.dl.q * grid.area[d.g])); // (the diffuse layers', held below the grid)
   sol.charge = q;
 
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,
@@ -272,10 +292,16 @@ export function makeSolution(solver, result = {}) {
         'advance() in time instead, or give the still species a small D where it is still.',
     );
   } else if (slow.length > 0) {
+    // Too slow to wait out only where the solve waited: where no time step was taken at all, the
+    // start was the trouble (a hole-only layer full of the anode's holes, with traps: "raise its
+    // rate constant" changed nothing, ×1e4).
+    const waited = (result.history ?? []).some((h) => h.converged && h.dt > 0);
     for (const { where, affinity } of slow) {
       sol.warnings.push(
         `the solve did not converge, likely because ${where} is out of equilibrium by ${(affinity * solver.VT * 1e3).toPrecision(3)} mV of affinity, yet nothing else makes or uses what it changes, so a steady state needs it at equilibrium: ` +
-          'it is too slow for the steady solve to wait out. Raise its rate constant (the steady state does not depend on it), or advance() in time.',
+          (waited
+            ? 'it is too slow for the steady solve to wait out. Raise its rate constant (the steady state does not depend on it), or advance() in time.'
+            : 'the solve failed from its first steps, so start it nearer that equilibrium: c0 near it, or solve without the reaction and set() it back.'),
       );
     }
   } else if (result.converged === false && cond && cond.digits > 12) {
@@ -364,7 +390,8 @@ export function makeSolution(solver, result = {}) {
       sol.warnings.push(
         `${where}: the reaction here sees the strictly neutral cell beside the face (${h.toExponential(2)} m), which holds the face's charge as a diffuse layer that wide: ` +
           `${species[ion].name} there is shifted by about ${(100 * shift).toPrecision(2)}%, a Frumkin effect set by the mesh that grows as the cell shrinks. ` +
-          `Set the face's zeroCharge near its rest potential (so it holds little charge), coarsen that cell to ${((200 * Math.abs(species[ion].z * sigma)) / (F * s2)).toExponential(1)} m or more, ` +
+          "Give the face a diffuse layer below the grid (diffuse: { epsr: 78.4 }, say, for water), which holds that charge where it belongs on any grid; " +
+          `or set the face's zeroCharge near its rest potential (so it holds little charge), coarsen that cell to ${((200 * Math.abs(species[ion].z * sigma)) / (F * s2)).toExponential(1)} m or more, ` +
           'or resolve the double layer (epsr > 0, hmin below the Debye length).',
       );
     }
@@ -379,7 +406,7 @@ export function makeSolution(solver, result = {}) {
       `${where}: the face's charge sits in the strictly neutral cell beside it (${h.toExponential(2)} m), which acts as a diffuse layer that wide ` +
         `(${Cbox.toPrecision(2)} F/m² in series), ${lowers}, so it depends on the mesh. ` +
         (Number.isFinite(C)
-          ? `Coarsen the grid there: a cell of ${((2 * 49 * C * RT) / (F * F * s2)).toExponential(1)} m or more keeps it within 2%.`
+          ? `${where.startsWith('interfaces') ? 'Give the face a diffuse layer below the grid (diffuse: { epsr }), or coarsen' : 'Coarsen'} the grid there: a cell of ${((2 * 49 * C * RT) / (F * F * s2)).toExponential(1)} m or more keeps it within 2%.`
           : "Give the face a Helmholtz capacitance (phi: { type: 'capacitive', C }), or make it neutral."),
     );
   };
@@ -389,9 +416,22 @@ export function makeSolution(solver, result = {}) {
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
     const reacting = (side) => itf.reactions.flatMap((rx) => rx.part.filter((p) => p.side === side).map((p) => p.i));
-    const sigma = sol.interfaces[f].D;
-    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`, sigma, reacting(0));
-    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
+    const sigma = sol.interfaces[f].D, [dlL, dlR] = solver.diffAt[f];
+    // (a side with a diffuse layer holds the face's charge there, below the grid, not in its cell)
+    if (dlL < 0) boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`, sigma, reacting(0));
+    if (dlR < 0) boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
+    // A dilute (Boltzmann) layer piles counter-ions at the plane without limit; past a few molar
+    // they'd have no room, and the layer's charge and capacitance are overstated.
+    for (const [side, dd] of Object.entries(sol.interfaces[f].diffuse ?? {})) {
+      if (itf.diffuse.lattice[side === 'left' ? 0 : 1]) continue; // (a crowded layer can't pass its sites)
+      const [name, top] = Object.entries(dd.plane).reduce((a, e) => (e[1] > a[1] ? e : a), ['', 0]);
+      if (top > DIFFUSE_CROWDED) {
+        sol.warnings.push(
+          `interfaces[${f}] (${side} side): the diffuse layer's plane holds ${name} at ${top.toPrecision(3)} mol/m³ (a drop of ${(1e3 * dd.psi).toPrecision(3)} mV), ` +
+            'past where ions have room to pack, so this dilute layer overstates its charge and capacitance. A smaller Stern capacitance C, or a zeroCharge nearer the operating potential, keeps the drop modest.',
+        );
+      }
+    }
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
   if (solved && resolves(contacts.left)) {