driftlet 1.3.2 → 1.4.0

package/src/solver.js

@@ -10,8 +10,9 @@ import { Assembly } from './assemble.js';
 import { BlockTridiagonal } from './blockTridiagonal.js';
 import { bernoulli, SG_FAR, sgFlux } from './bernoulli.js';
 import { BoundaryTerms } from './boundaries.js';
-import { FARADAY } from './constants.js';
+import { EPS0, FARADAY } from './constants.js';
 import { sourceAt } from './device.js';
+import { diffuseScratch, diffuseUnits } from './diffuse.js';
 import { DeviceError } from './errors.js';
 import { conservedMoieties, findLaws, noCurrent } from './laws.js';
 import { newton as newtonFn } from './newton.js';
@@ -60,15 +61,29 @@ export class SolverError extends Error {
   }
 }
 
+// The species a face's diffuse layer on that side (0 left, 1 right) passes to its reactions:
+// each participant there that the layer holds (charged, or on its lattice), but SRH's (refused
+// beside a layer), in species order. A flux across the layer lowers each one's level at the plane.
+function drawSpecies(itf, side, species) {
+  const lat = itf.diffuse.lattice[side], out = new Set();
+  for (const rx of itf.reactions) {
+    if (rx.srh) continue;
+    for (const p of rx.part) if (p.side === side && (species[p.i].z !== 0 || lat?.on[p.i])) out.add(p.i);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
 export class Solver {
   constructor(model) {
     this.model = model;
     const { grid, species, materials, regions, contacts } = model;
     const n = species.length;
     // 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) and one per gate (its fraction open), as many as the
-    // busiest face has.
-    const nRx = model.interfaces.reduce((m, itf) => Math.max(m, itf.reactions.length + itf.gates.length), 0);
+    // one per face reaction (its rate), one per gate (its fraction open) and one per diffuse
+    // layer (its drop) and one per species that layer passes to a face reaction (its level at the
+    // plane: drawSpecies), as many as the busiest face has.
+    const nDiff = (itf) => (itf.diffuse ? [0, 1].reduce((m, side) => m + ((side ? itf.diffuse.right : itf.diffuse.left) ? 1 + drawSpecies(itf, side, species).length : 0), 0) : 0);
+    const nRx = model.interfaces.reduce((m, itf) => Math.max(m, itf.reactions.length + itf.gates.length + nDiff(itf)), 0);
     // (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);
     // (and a membrane port's gates, after them: each one's fraction open)
@@ -122,6 +137,36 @@ export class Solver {
     let j = 0;
     for (let f = 0; f < nFaces; j += model.interfaces[f].gates.length, f++) this.gateIndex[f] = j;
     this.portGateIndex = model.ports.map((port) => ((j += port.nodes.length * port.gates.length), j - port.nodes.length * port.gates.length));
+    // Diffuse layers (src/diffuse.js): one per strictly neutral side of a face that has them, in
+    // face order, left side first. Each: its face f, side (0 left, 1 right), edge node g and its
+    // block b, its drop s = Fψ/RT in slot o of the face's block (after the gates), the layer's
+    // constants, its lattice (crowded: { cMax, on }, the species on it; or null, dilute), which
+    // species it holds an excess of (the charged, and a lattice's neutral ones, displaced), and
+    // its scratch (q, Γ and their derivatives, D, from computeConcentrations). Γ
+    // [d·n + i], the excesses, now and at the step's start; diffAt[f] = [left d, right d] (−1: none).
+    // And the species it passes to the face's reactions (the drawn: each one's level at the plane
+    // in slot drawSlot[i], after both sides' drops, −1 where not drawn; draw[i] = 1 for them), and
+    // their diffusivities there, Dm.
+    this.diffList = [];
+    this.diffAt = model.interfaces.map(() => [-1, -1]);
+    model.interfaces.forEach((itf, f) => {
+      if (!itf.diffuse) return;
+      let slot = 1 + n + itf.reactions.length + itf.gates.length;
+      const sides = [0, 1].filter((side) => (side ? itf.diffuse.right : itf.diffuse.left));
+      let level = slot + sides.length;
+      for (const side of sides) {
+        const g = side ? grid.regionStart[f + 1] : grid.regionEnd[f];
+        this.diffAt[f][side] = this.diffList.length;
+        const lat = itf.diffuse.lattice[side], drawSlot = new Int32Array(n).fill(-1);
+        for (const i of drawSpecies(itf, side, species)) drawSlot[i] = level++;
+        const draw = drawSlot.some((q) => q >= 0) ? Uint8Array.from(drawSlot, (q) => (q >= 0 ? 1 : 0)) : null;
+        const Dm = model.materials[regions[grid.nodeRegion[g]].material].D;
+        this.diffList.push({ f, side, g, b: this.blockOfNode[g], slot, o: this.blockOfFace[f] * M + slot, units: diffuseUnits(itf.diffuse.epsr * EPS0, model.RT, FARADAY), dl: diffuseScratch(n), lat, holds: Uint8Array.from(species, (sp, i) => (sp.z !== 0 || lat?.on[i] ? 1 : 0)), drawSlot, draw, Dm });
+        slot++;
+      }
+    });
+    this.gam = new Float64Array(this.diffList.length * n);
+    this.gamOld = new Float64Array(this.diffList.length * n);
 
     // Per-node material data, flattened [g·n + i].
     this.present = new Uint8Array(nNodes * n);
@@ -177,6 +222,7 @@ export class Solver {
     // A face with φ undefined on both sides holds no charge, whatever its law says.
     model.interfaces.forEach((itf, f) => {
       if (itf.phi.type !== 'neutral' && this.phiUndefined[grid.regionEnd[f]] && this.phiUndefined[grid.regionEnd[f] + 1]) itf.phi = { type: 'neutral' };
+      // (a diffuse side has ions, so φ is defined there: the face above never has one)
     });
 
     // Unknowns as compensated double-doubles, u + uLo. Only differences of η need the extra
@@ -438,6 +484,10 @@ export class Solver {
       for (let i = 0; i < n; i++) active[bf * M + 1 + i] = itf.links[i].type === 'blocked' ? 0 : 1;
       for (let k = 0; k < itf.reactions.length + itf.gates.length; k++) active[bf * M + 1 + n + k] = 1;
     });
+    for (const d of this.diffList) {
+      active[d.o] = 1;
+      for (const q of d.drawSlot) if (q >= 0) active[this.blockOfFace[d.f] * M + q] = 1;
+    }
     const sizes = new Int32Array(nB), loc = (this.loc = new Int32Array(nB * M).fill(-1));
     for (let b = 0; b < nB; b++) for (let r = 0; r < M; r++) if (active[b * M + r]) loc[b * M + r] = sizes[b]++;
     const sys = (this.sys = new BlockTridiagonal(nB, sizes));
@@ -624,6 +674,18 @@ export class Solver {
     this.contactLaw = found.contactLaw;
     this.carriers = found.carriers;
     this.unkept = found.unkept; // (laws no row here can keep: see _directSteady)
+    // (room in each law's derivative for the diffuse layers' excesses, which src/laws.js, reading
+    // the structure alone, doesn't count: each layer's drop and its edge node's slots)
+    if (this.diffList.length > 0) {
+      const more = this.diffList.length * (this.M + 1);
+      for (const cs of [...this.constraints, ...this.timeLaws]) {
+        const idx = new Int32Array(cs.idx.length + more), w = new Float64Array(cs.w.length + more);
+        idx.set(cs.idx);
+        w.set(cs.w);
+        cs.idx = idx;
+        cs.w = w;
+      }
+    }
     this.contactQ = [null, null]; // (each contact's charge as _contact captures it, for contactLaw)
     this.pinnedIslands = [];
     this.islandsOn = false; // (newton() turns them on, see there)
@@ -652,12 +714,22 @@ export class Solver {
     return port.surface[0].capacity * s;
   }
 
-  /** Total amount (mol per unit area) of a stretch's species in the current state. */
+  /** Total amount (mol per unit area) of a stretch's species in the current state, its faces' diffuse layers' included. */
   amount(stretch) {
     const { n, c, model } = this;
     const vol = model.grid.vol;
     let s = 0;
     for (let g = stretch.nodes[0]; g <= stretch.nodes[1]; g++) s += vol[g] * c[g * n + stretch.species];
+    return s + this._diffuseHeld(stretch, this.gam);
+  }
+
+  // What the faces' diffuse layers hold of a stretch's species (mol, per area if planar), by the
+  // excesses gam (now, or gamOld at the step's start).
+  _diffuseHeld(stretch, gam) {
+    let s = 0;
+    this.diffList.forEach((dl, k) => {
+      if (dl.g >= stretch.nodes[0] && dl.g <= stretch.nodes[1]) s += this.model.grid.area[dl.g] * gam[k * this.n + stretch.species];
+    });
     return s;
   }
 
@@ -848,6 +920,7 @@ export class Solver {
       cOld: Float64Array.from(this.cOld),
       thOld: Float64Array.from(this.thOld),
       th0Old: Float64Array.from(this.th0Old),
+      gamOld: Float64Array.from(this.gamOld),
       gateOld: Float64Array.from(this.gateOld),
       time: this.time,
       lastDt: this.lastDt,
@@ -872,6 +945,7 @@ export class Solver {
     this.cOld.set(s.cOld);
     this.thOld.set(s.thOld);
     this.th0Old.set(s.th0Old);
+    this.gamOld.set(s.gamOld);
     this.gateOld.set(s.gateOld);
     this.time = s.time;
     this.lastDt = s.lastDt;
@@ -972,19 +1046,22 @@ export class Solver {
       if (link.type !== 'permeability') return null;
       const kl = gl * n + i, kr = gr * n + i;
       const shift = this.mu0hat[kr] - this.mu0hat[kl] - Math.log(this.cRef[kr] / this.cRef[kl]);
-      const d = z[i] * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M])) + shift;
+      // (between the diffuse layers' planes, where the face has them: see _face)
+      const [dL, dR] = this.diffAt[f], sL = dL < 0 ? 0 : u[this.diffList[dL].o], sR = dR < 0 ? 0 : u[this.diffList[dR].o];
+      const cl = this.c[kl] * Math.exp(-z[i] * sL), cr = this.c[kr] * Math.exp(-z[i] * sR);
+      const d = z[i] * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M]) + sR - sL) + shift;
       const deta = u[bR * M + 1 + i] - u[bL * M + 1 + i] + (uLo[bR * M + 1 + i] - uLo[bL * M + 1 + i]);
       const gated = link.gates ?? [];
       const P = link.P * (gated.length ? this._open(gated, (q) => u[this._gateSlot(f, q)]) : 1);
-      const right = P * bernoulli(d) * this.c[kl];
+      const right = P * bernoulli(d) * cl;
       // (far up a drift, right × e^Δη is 0·∞: the backward one is then sgFlux's, whole)
-      return [right, d < SG_FAR ? right * Math.exp(deta) : sgFlux(P, d, deta, this.c[kl], this.c[kr], this.sg)[3]];
+      return [right, d < SG_FAR ? right * Math.exp(deta) : sgFlux(P, d, deta, cl, cr, this.sg)[3]];
     });
   }
 
   // Add this step's contact fluxes (at the converged state) to each stretch's intake.
   // (A BDF2 step also moves each amount by Σ v (c* − c_n), its history term.)
-  _accumulateBoundaryIntake(dt, cN) {
+  _accumulateBoundaryIntake(dt, cN, gamN = this.gamOld) {
     this._assembleBookkeeping(dt);
     this.contactDEnd = { ...this.contactD };
     this.portQEnd = Float64Array.from(this.portQ);
@@ -1008,6 +1085,7 @@ export class Solver {
       if (driven.has(k)) q = driven.get(k);
       let hist = 0;
       for (let g = st.nodes[0]; g <= st.nodes[1]; g++) hist += vol[g] * (cOld[g * n + st.species] - cN[g * n + st.species]);
+      hist += this._diffuseHeld(st, this.gamOld) - this._diffuseHeld(st, gamN);
       this.boundaryIntake[k] += q * dt + hist;
     });
   }

package/src/start.js

@@ -29,9 +29,11 @@
 //      otherwise it's the running φ̂, or where a conductor on the left or an electrode spread
 //      through the region has a reaction that can balance, the φ̂ that balances it (by bisection;
 //      a trial a non-ideal model refuses counts its ideal charge, which has the sign there). Where
-//      neutrality is out of reach (c0's amounts leave a charge no held level balances), the
-//      running φ̂, and a strictly neutral region is noted in s.unbalanced (for a transient that
-//      fails from it to say why). A strictly
+//      neutrality is out of reach (c0's amounts leave a charge no held level balances): in a
+//      strictly neutral region the running φ̂, the region noted in s.unbalanced (for a transient
+//      that fails from it to say why); otherwise the φ̂ nearest the running one, toward less
+//      charge, where the charge is at most ε V_T/(F L²) (L the region's length: what it holds with
+//      a thermal voltage across it), or where it stops falling (a fixed charge). A strictly
 //      neutral region (ε = 0) with every charged species' amount given must have a neutral c0:
 //      an error otherwise. A non-ideal material's composition comes from its statistics
 //      (materialAt).
@@ -63,7 +65,8 @@
 //      equilibrated by step 2 (a transient's first step), its amount over the two nodes is kept.
 //   2. A species given by its level starts at the level of what feeds it, as step 1 orders them.
 //   3. Where a level-fixed charged species responds, each node starts neutral (Σ z c + the fixed
-//      charge = 0) to the bisection's tolerance, unless neutrality is out of reach (step 1); a
+//      charge = 0) to the bisection's tolerance, unless neutrality is out of reach (step 1: then
+//      its charge at most ε V_T/(F L²), or the least φ̂ gives, to the bisection's tolerance); a
 //      strictly neutral region given by amounts is neutral by its c0, checked.
 //   4. Steps 2 and 3 change no concentration but as they say: step 3 is a gauge (φ̂ and each η by
 //      z·Δ), step 2 moves the passing species between a face's two nodes only.
@@ -81,7 +84,7 @@
 // Tests: every test (each device starts here); test/transient.test.js on what a start must be.
 
 import { gateRate } from './boundaries.js';
-import { FARADAY } from './constants.js';
+import { EPS0, FARADAY } from './constants.js';
 import { sourceAt } from './device.js';
 import { profileAt, SolverError } from './solver.js';
 
@@ -260,13 +263,39 @@ export function initFromComposition(s) {
       while (charge(lo) < 0 && lo > -1e4) lo -= 2 * (hi - lo);
       while (charge(hi) > 0 && hi < 1e4) hi += 2 * (hi - lo);
       // Out of reach (every responding carrier has one sign and nothing balances it, as in an
-      // undoped layer that holds only holes): keep the running φ̂ rather than run it to ±∞.
+      // undoped layer that holds only holes): not run to ±∞, but where the charge is no more than
+      // the region holds with a thermal voltage across it, ε V_T/(F L²), or as little as it gets
+      // (a fixed charge left). Kept at the running φ̂ (a contact's level), a hole-only layer 100
+      // nm thick started full of the anode's 1e27 m⁻³ holes, 7 kV of space charge: with traps in
+      // it, every step failed from there.
       if (charge(lo) < 0 || charge(hi) > 0) {
         // In a strictly neutral region that's a start that can't be: the amounts c0 gives leave
         // a charge no level-held species can balance. Noted, for a transient that fails from it
         // to say so (a steady solve, its levels from the contacts, can still find the state).
-        if (mat.epsr === 0) s.unbalanced.push(r);
-        return ph;
+        if (mat.epsr === 0) {
+          s.unbalanced.push(r);
+          return ph;
+        }
+        const L = grid.x[grid.regionEnd[r]] - grid.x[grid.regionStart[r]];
+        const most = (mat.epsr * EPS0 * model.RT) / (FARADAY * FARADAY * L * L);
+        const q0 = charge(ph), dir = q0 > 0 ? 1 : -1; // (the charge falls as φ̂ rises)
+        if (!(Math.abs(q0) > most)) return ph;
+        let a = ph, qa = Math.abs(q0);
+        for (let step = 1; step < 1e4; step *= 2) {
+          let b = a + dir * step;
+          const qb = Math.abs(charge(b));
+          if (qb <= most) {
+            for (let it = 0; it < 100 && Math.abs(b - a) > 1e-9; it++) {
+              const m = 0.5 * (a + b);
+              if (Math.abs(charge(m)) > most) a = m;
+              else b = m;
+            }
+            return b;
+          }
+          if (!(qb < qa * (1 - 1e-9))) return a; // (a fixed charge: as little as it gets)
+          [a, qa] = [b, qb];
+        }
+        return a;
       }
       for (let it = 0; it < 200 && hi - lo > 1e-12; it++) {
         const m = 0.5 * (lo + hi);

package/src/statistics.js

@@ -207,6 +207,7 @@ function latticeModel(idx, cRef, cMax) {
   return {
     type: 'lattice',
     idx,
+    cMax, // (read by a face's diffuse layer beside it, which crowds on the same sites: src/diffuse.js)
     // c_a = c_max w_a / (1 + Σ w), w_a = (c_ref,a / c_max) e^{ζ_a}; K = diag(c) − c cᵀ/c_max.
     evaluate(zeta, c, K) {
       let m = 0;

package/src/steady.js

@@ -49,11 +49,14 @@
 //      (this.stepped), on a direct device with continuation not off, the same again from a cold
 //      start (initFromComposition), whose u and uLo become the stages' start (termV stays the
 //      start's: a floating terminal keeps the voltage the transient left it at).
-//   2. Continuation: generation ramped up (_generationContinuation); a terminal driven by a
-//      terminals behind a resistance held (at their source voltages, or where every other
-//      terminal is driven by a current at V_src − I R, Kirchhoff's I), then the resistances put
-//      back and the steady system solved from there (_resistanceContinuation); a terminal
-//      driven by a current, not bound (_bound), held at voltages instead (_floatingContinuation); with
+//   2. Continuation: generation ramped up (_generationContinuation); terminals behind a
+//      resistance (_resistanceContinuation): one whose current Kirchhoff doesn't give, held at
+//      voltages marched to its load line's crossing (_floatingContinuation with a line); else, or
+//      where that fails, each held (at its source voltage, or where every other terminal is
+//      driven by a current at V_src − I R, Kirchhoff's I), then the resistances put back and the
+//      steady system solved from there (and where that fails for one terminal held by
+//      Kirchhoff, its load line); a terminal driven by a current, not bound (_bound), held at
+//      voltages instead (_floatingContinuation); with
 //      canContinue, the right contact's voltage ramped to its target (_continuation): from the
 //      voltages of the last converged solve (this.solvedV), the left contact's first where it
 //      moved, else from level contacts, a cold start.
@@ -69,7 +72,8 @@
 //   (∞ where the device can be solved directly; else 1e6·tau): a first step at ∞ that fails is
 //   retried once with maxStep 3. A step that fails sends dt down (to tau·1e-6 from giant, then
 //   ÷4, stopping below min(1e-15·tau, 1e-2·fastestTime)); one that converges sends it back up
-//   (×2 after a failure, growing by ×1.5 to ×10 a step; past 1e6·tau, giant); on a direct device,
+//   (×2 after a failure, growing by ×1.5 to ×10 a step; past 1e6·tau, giant, or on a direct
+//   device past 1e12·tau); on a direct device,
 //   once dt ≥ tau, a step at ∞ is tried once a decade of dt, the state kept where it fails. Past
 //   giant (not direct), dt grows ×10 a step to 1e6·giant. Converged where a step at ∞ converged,
 //   or, not direct, where a step of dt ≥ giant moved the potentials under tol (finished by one
@@ -130,7 +134,7 @@
 //      here is more than u, uLo, termV and time: this.solvedV, this.stepped, whether the history
 //      is empty (this.violent) and the drives, all of which choose the stages.
 //   5. Reach: time steps reach a mode as slow as ~1e12·tau (1e6·tau a step, past the giant; on a
-//      direct device no finite step is longer than 1e6·tau). A reaction that alone settles a
+//      direct device by finite steps to 1e12·tau). A reaction that alone settles a
 //      closed combination, slower than that, isn't waited out: the solve fails or converges where
 //      it began, and stuckReactions names it (Solution's warnings, both ways).
 // Tests: every Device.solve goes through here; test/steady.test.js (the stages, the laws, the
@@ -462,8 +466,10 @@ export class SteadySolves {
     }
   }
 
-  // Each terminal behind a resistance held at its source voltage (R taken off), solved, then the
-  // resistances put back and the steady system solved from that state.
+  // One terminal behind a resistance: its load line's crossing by held solves. Otherwise (or where
+  // that fails), each terminal behind a resistance held at its source voltage (R taken off; at
+  // V_src − I R where Kirchhoff gives I), solved, then the resistances put back and the steady
+  // system solved from that state.
   _resistanceContinuation(opts, r) {
     const ks = this.floating.filter((k) => this.terms[k].drive.kind === 'V' && this.terms[k].drive.R > 0);
     const drives = ks.map((k) => this.terms[k].drive);
@@ -479,8 +485,29 @@ export class SteadySolves {
       const I = -this.terms.reduce((t, tm, j) => (j === k ? t : t + sourceAt(tm.drive.src, this.time)), 0);
       return V - I * d.R;
     };
-    let heldOk = false;
     const start = [Float64Array.from(this.u), Float64Array.from(this.uLo), Float64Array.from(this.termV)];
+    const restore = () => {
+      this.u.set(start[0]);
+      this.uLo.set(start[1]);
+      this.termV.set(start[2]);
+      this.computeConcentrations();
+    };
+    // One terminal behind R, the rest not all driven by currents (so its current isn't known):
+    // its crossing with the load line, (V_src − V)/R, by held solves, as an open circuit's is
+    // with its target, first. Held at its source instead, the state is I R from the answer and
+    // the pseudo-transient relaxes it over R C at Newton's pace through that swing (a lit Schottky
+    // diode passing 0.9 A/m²: 0.05 s at 1 Ω·m², 10 s at 1e4, 105 s at 1e5, steps ∝ R).
+    const d = drives[0], Vs = sourceAt(d.src, this.time), line = (V) => (Vs - V) / d.R;
+    const byLine = ks.length === 1 && !others;
+    if (byLine) {
+      const q = this._floatingContinuation(opts, r, ks[0], line);
+      if (q.converged) return q;
+      restore(); // (from where this stage began, not where the failed one left it)
+      steps = q.steps ?? steps;
+      iterations = q.iterations ?? iterations;
+      history.splice(0, history.length, ...(q.history ?? []));
+    }
+    let heldOk = false;
     try {
       const held = ks.map(at);
       ks.forEach((k, j) => (this.terms[k].drive = { ...this.terms[k].drive, src: { value: held[j] }, R: 0 }));
@@ -497,16 +524,10 @@ export class SteadySolves {
     }
     const q = heldOk ? this._steadySteps(opts) : { converged: false, steps: 0, iterations: 0, history: [] };
     const done = { ...q, steps: steps + q.steps, iterations: iterations + q.iterations, history: [...history, ...q.history] };
-    if (q.converged || ks.length !== 1) return done;
-    // One terminal behind R, the rest not all driven by currents (so its current isn't known):
-    // its crossing with the load line, (V_src − V)/R, by held solves, as an open circuit's is
-    // with its target (a silver cell held at 0 V on one side, 16 V behind R on the other, failed).
-    const d = drives[0], Vs = sourceAt(d.src, this.time);
-    this.u.set(start[0]);
-    this.uLo.set(start[1]);
-    this.termV.set(start[2]);
-    this.computeConcentrations(); // (from where this stage began, not where the failed one left it)
-    return this._floatingContinuation(opts, done, ks[0], (V) => (Vs - V) / d.R);
+    if (q.converged || ks.length !== 1 || byLine) return done;
+    // Where Kirchhoff's hold failed too, the load line.
+    restore();
+    return this._floatingContinuation(opts, done, ks[0], line);
   }
 
   // Steady solves with the generation reactions' rates scaled from 1e-30 up to 1, ×100 a step
@@ -687,7 +708,10 @@ export class SteadySolves {
       if (dt < giant) {
         dt *= grow; // ramping up after a failure
         grow = Math.min(10, grow * 1.5);
-        if (dt > 1e6 * tau) dt = giant; // then the direct steady solve (or the giant step)
+        // Then the giant step; or, solved directly, on to 1e12 τ, the direct solve tried once a
+        // decade (above): jumping to dt = ∞ at 1e6 τ, its failure sent dt back to 1e-6 τ, round
+        // and round below 70 s, where traps filled by 1e9 cm⁻³ electrons took 1e3 s (τ 7e-5 s).
+        if (dt > (direct ? 1e12 : 1e6) * tau) dt = giant;
       } else if (dt < 1e6 * giant) {
         dt *= 10; // conserved amounts present and still moving: let dt keep growing (capped)
       }
@@ -734,7 +758,9 @@ export class SteadySolves {
       // it, and there's nothing here to shift.
       if (!st.spectator || this.model.materials[this.model.regions[st.regions[0]].material].conductor) return;
       const want = this.referenceAmounts[k];
-      const ideal = this.nodeIdeal.subarray(st.nodes[0], st.nodes[1] + 1).every((v) => v === 1);
+      // (one shift of η scales an ideal stretch's amount exactly, but not what a diffuse layer
+      // at its edge holds, whose excess isn't proportional to c: iterate there too)
+      const ideal = this.nodeIdeal.subarray(st.nodes[0], st.nodes[1] + 1).every((v) => v === 1) && this._diffuseHeld(st, this.gam) === 0;
       for (let it = 0; it < (ideal ? 1 : 30); it++) {
         const now = this.amount(st);
         if (!(now > 0) || now === want) return;
@@ -746,6 +772,9 @@ export class SteadySolves {
             const dc = this.nodeIdeal[g] ? this.c[g * n + st.species] : this.K[g * n * n + st.species * (n + 1)];
             dA += this.model.grid.vol[g] * dc;
           }
+          this.diffList.forEach((dl, d) => {
+            if (dl.g >= st.nodes[0] && dl.g <= st.nodes[1]) dA += this.model.grid.area[dl.g] * dl.dl.dgdc[st.species * (n + 1)] * this.c[dl.g * n + st.species];
+          });
           shift = (want - now) / dA;
           if (!(Math.abs(shift) > 1e-16)) return;
         }

package/src/timeSteps.js

@@ -8,7 +8,8 @@
 // in docs/internals.md. The Solver's own step, advance and integrate call them (the API, the
 // steady solves' time stepping and the kit call those). What they use of it:
 //   s.newton(dt, opts)  solves the equations at the step's end, from the state as it stands,
-//                       with storage (c − c*)/dt against s.cOld, s.thOld, s.th0Old, s.gateOld,
+//                       with storage (c − c*)/dt against s.cOld, s.thOld, s.th0Old, s.gamOld (the
+//                       diffuse layers' excesses), s.gateOld,
 //                       s.contactDStart, s.portQStart; leaves the state at its last iterate.
 //   s._snapshot() / s._restore(snap)  the whole time state (u, uLo, termV, the start-of-step
 //                       values, time, lastDt, history, the boundary intake, sourceTime).
@@ -17,7 +18,7 @@
 //
 // The state: u + uLo (Newton's unknowns, η and φ̂ in thermal units), termV (terminal voltages),
 // time. The history: s.history, the accepted steps before this one, newest first, at most 3,
-// each { t (its start), dt, u (its start state), c, th, th0, g (gates), D (contacts' D), Q
+// each { t (its start), dt, u (its start state), c, th, th0, gam, g (gates), D (contacts' D), Q
 // (ports' charges) }: what BDF2 and the predictor need.
 //
 // step(s, dt, opts) → newton's result (+ bdf)
@@ -128,7 +129,7 @@ export function step(s, dt, opts = {}) {
   // What the step overwrites before Newton runs, for a failed one to put back: the Solution read
   // after it takes its contacts' fluxes against the start-of-step values (a host emptied by its
   // current read its contact's Li⁺ flux 8× off at the same state).
-  const was = { cOld: Float64Array.from(s.cOld), thOld: Float64Array.from(s.thOld), th0Old: Float64Array.from(s.th0Old), gateOld: Float64Array.from(s.gateOld), contactDStart: s.contactDStart, portQStart: s.portQStart, atSteady: s.atSteady };
+  const was = { cOld: Float64Array.from(s.cOld), thOld: Float64Array.from(s.thOld), th0Old: Float64Array.from(s.th0Old), gamOld: Float64Array.from(s.gamOld), gateOld: Float64Array.from(s.gateOld), contactDStart: s.contactDStart, portQStart: s.portQStart, atSteady: s.atSteady };
   s.atSteady = false;
   const prev = s.history[0];
   const w = prev ? dt / prev.dt : 0;
@@ -137,7 +138,7 @@ export function step(s, dt, opts = {}) {
   s.uPrevLo.set(s.uLo);
   s.termVPrev.set(s.termV);
   s.computeConcentrations();
-  const cN = Float64Array.from(s.c), thN = Float64Array.from(s.th), th0N = Float64Array.from(s.th0);
+  const cN = Float64Array.from(s.c), thN = Float64Array.from(s.th), th0N = Float64Array.from(s.th0), gamN = Float64Array.from(s.gam);
   const gN = Float64Array.from(s.gateList, (gt) => s.u[gt.o] + s.uLo[gt.o]);
   // 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.
@@ -155,6 +156,7 @@ export function step(s, dt, opts = {}) {
     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++) s.thOld[k] = b1 * thN[k] - b2 * prev.th[k];
     for (let k = 0; k < th0N.length; k++) s.th0Old[k] = b1 * th0N[k] - b2 * prev.th0[k];
+    for (let k = 0; k < gamN.length; k++) s.gamOld[k] = b1 * gamN[k] - b2 * prev.gam[k];
     for (let k = 0; k < gN.length; k++) s.gateOld[k] = b1 * gN[k] - b2 * prev.g[k];
     s.contactDStart = { left: b1 * DN.left - b2 * prev.D.left, right: b1 * DN.right - b2 * prev.D.right };
     s.portQStart = QN.map((q, k) => b1 * q - b2 * prev.Q[k]);
@@ -163,6 +165,7 @@ export function step(s, dt, opts = {}) {
     s.cOld.set(cN);
     s.thOld.set(thN);
     s.th0Old.set(th0N);
+    s.gamOld.set(gamN);
     s.gateOld.set(gN);
     s.contactDStart = DN;
     s.portQStart = QN;
@@ -205,13 +208,13 @@ export function step(s, dt, opts = {}) {
   }
   result.bdf = bdf;
   if (result.converged) {
-    s.history.unshift({ t: s.time, dt, u: Float64Array.from(s.uPrev), c: cN, th: thN, th0: th0N, g: gN, D: DN, Q: QN });
+    s.history.unshift({ t: s.time, dt, u: Float64Array.from(s.uPrev), c: cN, th: thN, th0: th0N, gam: gamN, g: gN, D: DN, Q: QN });
     if (s.history.length > 3) s.history.length = 3;
     s.time = tEnd;
     s.lastDt = dtEff;
     s.contactDOld = s.contactDStart;
     s.portQOld = s.portQStart;
-    s._accumulateBoundaryIntake(dtEff, cN);
+    s._accumulateBoundaryIntake(dtEff, cN, gamN);
     // (In time, the state is no longer the steady solve's that a continuation would start from.)
     if (!s.steady) {
       s.solvedV = undefined;
@@ -224,6 +227,7 @@ export function step(s, dt, opts = {}) {
     s.cOld.set(was.cOld);
     s.thOld.set(was.thOld);
     s.th0Old.set(was.th0Old);
+    s.gamOld.set(was.gamOld);
     s.gateOld.set(was.gateOld);
     s.contactDStart = was.contactDStart;
     s.portQStart = was.portQStart;

package/src/types.js

@@ -114,6 +114,15 @@
  * @property {Record<string, number>} [K] with vmax: a half-saturation concentration (mol/m³) for
  *   every species the forward reaction consumes
  */
+/**
+ * A face's diffuse layer on one side, in a solution.
+ * @typedef {object} DiffuseLayerResult
+ * @property {number} psi the drop from the side's edge node to the plane, φ_plane − φ_edge (V)
+ * @property {number} charge the layer's charge (C/m²)
+ * @property {Record<string, number>} excess each ion's surface excess, ∫ (c − c_edge) dx (mol/m²)
+ * @property {Record<string, number>} plane each ion's concentration at the plane, c e^{−zFψ/RT} (mol/m³; on a
+ *   lattice, over its crowding; for what a face reaction takes or makes there, times its level's drop across the layer)
+ */
 /**
  * One face between consecutive regions. For different materials under a 'pinned' or
  * 'capacitive' law, exactly one alignment (step or dipole) is required.
@@ -124,6 +133,9 @@
  * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials;
  *   beside a conductor 'neutral' or capacitive, required next to an ε > 0 material)
  * @property {number} [sheetCharge] C/m²
+ * @property {{ epsr: number }} [diffuse] a Gouy–Chapman diffuse layer below the grid on each strictly
+ *   neutral (ε = 0) side of a charged face, of relative permittivity epsr: the side's share of the
+ *   face's charge held as its ions' surface excesses, the face's reactions at its plane
  * @property {Record<string, InterfaceSpeciesLink>} [species] per-species laws (default equilibrium
  *   where present on both sides and mobile on one, blocked otherwise; a species reacting at the
  *   face and present on both sides has no default)
@@ -283,11 +295,13 @@
  *   side holds; with gates, each gate's fraction open at each node and the voltage they follow (V)
  * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>,
  *   rates: number[], links: Record<string, string>, oneWay?: Record<string, [number, number]>,
- *   gates?: Record<string, number>, V?: number }[]} interfaces each face: the regions it joins, its dipole
+ *   gates?: Record<string, number>, V?: number,
+ *   diffuse?: { left?: DiffuseLayerResult, right?: DiffuseLayerResult } }[]} interfaces each face: the regions it joins, its dipole
  *   (V) and sheet charge (C/m²), its displacement D (C/m²), each species' flux N across it and each face
  *   reaction's net rate (mol/(m²·s), toward +x and forward), how each species that crosses it does (its
  *   link type); for those crossing by permeability, the one-way fluxes [toward +x, toward −x] whose
- *   difference is N; with gates, each one's fraction open and the voltage they follow, φ_right − φ_left (V)
+ *   difference is N; with gates, each one's fraction open and the voltage they follow, φ_right − φ_left (V; between the diffuse layers' planes, where it has them);
+ *   with a diffuse layer, each side's
  * @property {{ rate: Float64Array, forward: Float64Array, nu: Record<string, number>, regions: number[], total: number }[]} bulkReactions
  *   each bulk reaction's net rate per node (mol/(m³·s), forward minus backward, NaN where it doesn't
  *   run), its one-way forward rate (the backward is forward − rate), what one forward reaction makes

package/types/boundaries.d.ts

@@ -2,12 +2,20 @@ export function gateRate(law: any, V: any): number[];
 export class BoundaryTerms {
     _portRate(port: any, rx: any, g: any): number;
     _face(f: any): void;
+    _diffuseDraws(d: any, bf: any): void;
+    _diffuseTerms(d: any, bf: any, Af: any): void;
+    dW: Float64Array<any>;
+    _diffuseChain(d: any): any;
+    dV2: Float64Array<any>;
+    _diffuseLayers(): void;
     _gateSlot(f: any, q: any): any;
     _gateVoltage(gt: any): number;
     _portVoltage(k: any, g: any): number;
     _faceVoltage(f: any): number;
     _faceGates(f: any, bf: any, bL: any, bR: any): void;
     _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any, Af: any): void;
+    dWr: Float64Array<any>;
+    aWr: Float64Array<any>;
     _liveTerms(): any;
     _allTerms: any;
     _terminals(dt: any): void;

package/types/diffuse.d.ts

@@ -0,0 +1,25 @@
+/** The diffuse layer's charge, excesses and their derivatives (see the contract above). */
+export function diffuseLayer(c: any, z: any, n: any, s: any, { A, B }: {
+    A: any;
+    B: any;
+}, out: any, lat?: any, draw?: any): any;
+/** A scratch object for diffuseLayer over n species. */
+export function diffuseScratch(n: any): {
+    q: number;
+    dqds: number;
+    dqdc: Float64Array<any>;
+    gam: Float64Array<any>;
+    dgds: Float64Array<any>;
+    dgdc: Float64Array<ArrayBuffer>;
+    K: Float64Array<any>;
+    dKds: Float64Array<any>;
+    dKdc: Float64Array<ArrayBuffer>;
+    D: number;
+    dDds: number;
+    dDdc: Float64Array<any>;
+};
+/** 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: any, RT: any, F: any): {
+    A: number;
+    B: number;
+};

package/types/newton.d.ts

@@ -1,4 +1,4 @@
-export function maxPotentialStep(s: any, delta: any, deltaV?: any): number;
+export function maxPotentialStep(s: any, delta: any, deltaV?: any, layers?: boolean): number;
 export function newton(s: any, dt: any, { maxIter, tol, maxStep, islands }?: {
     maxIter?: number;
     tol?: number;

package/types/solver.d.ts

@@ -32,6 +32,10 @@ export class Solver {
     gateOld: Float64Array<ArrayBuffer>;
     gateIndex: Int32Array<ArrayBuffer>;
     portGateIndex: any;
+    diffList: any[];
+    diffAt: any;
+    gam: Float64Array<ArrayBuffer>;
+    gamOld: Float64Array<ArrayBuffer>;
     present: Uint8Array<ArrayBuffer>;
     cRef: Float64Array<ArrayBuffer>;
     mu0hat: Float64Array<ArrayBuffer>;
@@ -234,8 +238,9 @@ export class Solver {
     _surfaceStart(g: any): void;
     /** Amount (mol per unit area) of surface column j's species, Γ Σ v·a·θ, in the current state. */
     surfaceAmount(j: any): number;
-    /** Total amount (mol per unit area) of a stretch's species in the current state. */
+    /** Total amount (mol per unit area) of a stretch's species in the current state, its faces' diffuse layers' included. */
     amount(stretch: any): number;
+    _diffuseHeld(stretch: any, gam: any): number;
     redrive(): void;
     deltaV: any;
     _drivenKey(): any;
@@ -280,6 +285,7 @@ export class Solver {
         cOld: Float64Array<ArrayBuffer>;
         thOld: Float64Array<ArrayBuffer>;
         th0Old: Float64Array<ArrayBuffer>;
+        gamOld: Float64Array<ArrayBuffer>;
         gateOld: Float64Array<ArrayBuffer>;
         time: number;
         lastDt: number;
@@ -308,6 +314,6 @@ export class Solver {
     _terminalCurrent(): number;
     segmentFluxes(): Float64Array<ArrayBuffer>[];
     faceOneWay(f: any): any;
-    _accumulateBoundaryIntake(dt: any, cN: any): void;
+    _accumulateBoundaryIntake(dt: any, cN: any, gamN?: Float64Array<ArrayBuffer>): void;
 }
 import { BlockTridiagonal } from './blockTridiagonal.js';