driftlet 0.11.4 → 0.13.0

package/src/solver.js

@@ -261,17 +261,45 @@ export class SolverError extends Error {
   }
 }
 
+// Lagrange weights at x through the points s0, s1, s2.
+function lagrange3(x, s0, s1, s2) {
+  return [((x - s1) * (x - s2)) / ((s0 - s1) * (s0 - s2)), ((x - s0) * (x - s2)) / ((s1 - s0) * (s1 - s2)), ((x - s0) * (x - s1)) / ((s2 - s0) * (s2 - s1))];
+}
+
+// A gate's rate law (see normalizeGates in device.js) at voltage V: [rate, ∂rate/∂V], 1/s and 1/(s·V).
+function gateRate(law, V) {
+  const { rate, midpoint, scale } = law;
+  if (law.type === 'exp') {
+    // (held finite where Newton's iterates stray to absurd voltages: β_m at −13 V would overflow)
+    const y = (V - midpoint) / scale, v = rate * Math.exp(Math.min(y, 700));
+    return [v, y > 700 ? 0 : v / scale];
+  }
+  if (law.type === 'sigmoid') {
+    const e = Math.exp((midpoint - V) / scale), d = 1 + e;
+    return Number.isFinite(e) ? [rate / d, (rate * e) / (scale * d * d)] : [0, 0];
+  }
+  // expLinear: rate·y/(1 − e^−y), smooth through y = 0 (rate there) and → rate·y for large y
+  const y = (V - midpoint) / scale;
+  if (Math.abs(y) < 1e-6) return [rate * (1 + y / 2), rate / (2 * scale)];
+  if (y < -700) return [0, 0];
+  const em = -Math.expm1(-y), ey = Math.exp(-y); // 1 − e^−y, e^−y
+  return [(rate * y) / em, (rate * (em - y * ey)) / (em * em * scale)];
+}
+
 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), as many as the busiest face has.
-    const nRx = model.interfaces.reduce((m, itf) => Math.max(m, itf.reactions.length), 0);
+    // 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);
     // (and at an electrode port's nodes, one per surface species: its coverage's η)
     const nSurf = model.ports.reduce((m, port) => Math.max(m, port.surface.length), 0);
-    const M = n + 1 + Math.max(nRx, nSurf);
+    // (and a membrane port's gates, after them: each one's fraction open)
+    const nPortSlots = model.ports.reduce((m, port) => Math.max(m, port.surface.length + port.gates.length), 0);
+    const M = n + 1 + Math.max(nRx, nPortSlots);
     const nNodes = grid.nNodes;
     const nFaces = regions.length - 1;
     const nB = nNodes + nFaces;
@@ -306,6 +334,20 @@ export class Solver {
     // The bare fraction θ₀, directly (1 − Σθ cancels as θ → 1); 1 where there's no surface.
     this.th0 = new Float64Array(nNodes).fill(1);
     this.th0Old = new Float64Array(nNodes).fill(1);
+    // Gates: each one's slot (at a face, after its reaction rates; at a membrane port's nodes, after
+    // the surface's coverages) and value at the step's start. Faces' first, then ports', node by
+    // node through each window.
+    this.gatePort = new Int32Array(nNodes).fill(-1);
+    model.ports.forEach((port, k) => port.gates.length > 0 && port.nodes.forEach((g) => (this.gatePort[g] = k)));
+    this.gateList = [
+      ...model.interfaces.flatMap((itf, f) => itf.gates.map((gate, q) => ({ f, q, gate, o: this.blockOfFace[f] * M + 1 + n + itf.reactions.length + q }))),
+      ...model.ports.flatMap((port, k) => Array.from(port.nodes).flatMap((g) => port.gates.map((gate, q) => ({ port: k, g, q, gate, o: this.blockOfNode[g] * M + 1 + n + port.surface.length + q })))),
+    ];
+    this.gateOld = new Float64Array(this.gateList.length);
+    this.gateIndex = new Int32Array(nFaces); // face f's first gate in gateList
+    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));
 
     // Per-node material data, flattened [g·n + i].
     this.present = new Uint8Array(nNodes * n);
@@ -574,12 +616,14 @@ export class Solver {
       for (let i = 0; i < n; i++) active[b * M + 1 + i] = this.present[g * n + i];
       const k = this.surfPort[g];
       if (k >= 0) for (let q = 0; q < model.ports[k].surface.length; q++) active[b * M + 1 + n + q] = 1;
+      const kg = this.gatePort[g], pg = model.ports[kg];
+      if (kg >= 0) for (let q = 0; q < pg.gates.length; q++) active[b * M + 1 + n + pg.surface.length + q] = 1;
     }
     model.interfaces.forEach((itf, f) => {
       const bf = this.blockOfFace[f];
       active[bf * M] = itf.phi.type === 'neutral' ? 0 : 1;
       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; k++) active[bf * M + 1 + n + k] = 1;
+      for (let k = 0; k < itf.reactions.length + itf.gates.length; k++) active[bf * M + 1 + n + k] = 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]++;
@@ -1176,7 +1220,7 @@ export class Solver {
   /** η_i/RT that a fixed contact link imposes (or NaN if the link isn't fixed). */
   contactEta(side, i) {
     const link = this.model.contacts[side].species[i];
-    if (link.type !== 'equilibrium') return NaN;
+    if (link.type !== 'equilibrium' && link.type !== 'velocity') return NaN;
     const z = this.z[i];
     return z === 0 ? link.mu / this.model.RT : (z * (this.termV[side === 'left' ? 0 : 1] + link.offset)) / this.VT;
   }
@@ -1393,6 +1437,11 @@ export class Solver {
       });
       if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
     }
+    // Gates start open as far as the starting voltage across their face holds them, α/(α + β).
+    for (const gt of this.gateList) {
+      const { gate, o } = gt, V = this._gateVoltage(gt), a = gateRate(gate.alpha, V)[0], b = gateRate(gate.beta, V)[0];
+      u[o] = a + b > 0 ? a / (a + b) : 0;
+    }
     // A floating electrode spread through a port (without a double layer) starts where its
     // reactions pass the current it's set (none, behind a resistance): at its mixed potential in
     // the start's composition, not level with a held terminal, which can be volts away and pass
@@ -1601,6 +1650,7 @@ export class Solver {
     const { grid, materials, regions } = model;
     sys.clear();
     res.fill(0);
+    this.dtNow = dt;
     if (this.lin) this.lin.reset(1 / dt);
     this.computeConcentrations();
 
@@ -1752,7 +1802,7 @@ export class Solver {
   // A start-of-step net charge (round-off in a solved state) isn't carried over: the neutrality
   // row holds the new state neutral.
   _chargeRows(dt) {
-    const { n, M, res, c, cOld, z, sys, loc, present, termB, termC } = this, R = this.rix, F = FARADAY;
+    const { n, M, res, c, cOld, z, sys, loc, present, termB, termC } = this, R = this.rix, F = FARADAY, live = this._liveTerms();
     const { A, B, C, sizes, offA, offB, offC } = sys, vol = this.model.grid.vol, last = this.nB - 1;
     for (const g of this.chargeNodes) {
       const b = this.blockOfNode[g], lb = b * M, m = sizes[b], mp = b > 0 ? sizes[b - 1] : 0, mn = b < last ? sizes[b + 1] : 0;
@@ -1776,7 +1826,7 @@ export class Solver {
         for (let q = 0, o = offB[b] + lk * m, s = offB[b] + li * m; q < m; q++) B[o + q] += w * B[s + q];
         for (let q = 0, o = offC[b] + lk * mn, s = offC[b] + li * mn; q < mn; q++) C[o + q] += w * C[s + q];
         res[rk] += w * res[ri];
-        for (let t = 0; t < termB.length; t++) termB[t][rk] += w * termB[t][ri];
+        for (const t of live) termB[t][rk] += w * termB[t][ri];
         if (this.lin) this.lin.combine(rk, ri, w);
       }
       // Columns: φ̂' = φ̂ with η fixed becomes φ̂ with η_i shifted by z_i, wherever node g's
@@ -1787,7 +1837,7 @@ export class Solver {
         for (let r = 0, o = offB[b]; r < m; r++) B[o + r * m + p] += zi * B[o + r * m + li];
         if (b > 0) for (let r = 0, mr = mp, o = offC[b - 1]; r < mr; r++) C[o + r * m + p] += zi * C[o + r * m + li];
         if (b < last) for (let r = 0, mr = mn, o = offA[b + 1]; r < mr; r++) A[o + r * m + p] += zi * A[o + r * m + li];
-        for (let t = 0; t < termC.length; t++) termC[t][R[lb]] += zi * termC[t][R[lb + 1 + i]];
+        for (const t of live) termC[t][R[lb]] += zi * termC[t][R[lb + 1 + i]];
       }
       // Storage on the other charged balances, and neutrality: no φ̂' terms, exactly.
       const v = vol[g], oB = offB[b];
@@ -2036,14 +2086,21 @@ export class Solver {
         // 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.
-        const gl = grid.regionEnd[f], gr = gl + 1, kl = gl * n + i, kr = gr * n + i, zi = z[i], P = itf.links[i].P;
+        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 E = Math.expm1(-deta); // η_R − η_L
+        // 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 P = link.P * (gated.length ? this._open(gated, gx) : 1);
         const gBc = P * bernoulli(d) * this.c[kl];
         const dNdd = -P * bernoulliDerivative(d) * this.c[kl] * E;
         res[R[o]] = u[o] + gBc * E;
         this._j(bf, r, bf, r, 1);
+        for (const [q, p] of gated) {
+          const dO = this._dOpen(gated, q, p, gx);
+          if (dO !== 0) this._j(bf, r, bf, 1 + n + itf.reactions.length + q, link.P * bernoulli(d) * this.c[kl] * E * dO);
+        }
         this._j(bf, r, bL, r, -gBc);
         this._j(bf, r, bR, r, gBc * (E + 1));
         if (zi !== 0) {
@@ -2051,12 +2108,18 @@ export class Solver {
           this._j(bf, r, bR, 0, -zi * dNdd);
         }
       } else {
-        // conductance: J = G (V_L − V_R), V = V_T η / z  ⇒  N = G V_T (η_L − η_R) / (z² F)
-        const gG = (itf.links[i].G * VT) / (z[i] * z[i] * F);
+        // conductance: J = G (V_L − V_R), V = V_T η / z  ⇒  N = G V_T (η_L − η_R) / (z² F); gated,
+        // G times Π x^p
+        const gated = itf.links[i].gates ?? [], gx = (q) => u[this._gateSlot(f, q)];
+        const gG0 = (itf.links[i].G * VT) / (z[i] * z[i] * F), gG = gG0 * (gated.length ? this._open(gated, gx) : 1);
         res[R[o]] = u[o] - gG * deta;
         this._j(bf, r, bf, r, 1);
         this._j(bf, r, bL, r, -gG);
         this._j(bf, r, bR, r, gG);
+        for (const [q, p] of gated) {
+          const dO = this._dOpen(gated, q, p, gx);
+          if (dO !== 0) this._j(bf, r, bf, 1 + n + itf.reactions.length + q, -gG0 * deta * dO);
+        }
       }
       res[R[bL * M + r]] += Af * u[o];
       this._j(bL, r, bf, r, Af);
@@ -2064,6 +2127,46 @@ export class Solver {
       this._j(bR, r, bf, r, -Af);
     }
     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);
+  }
+
+  // Full index of face f's gate q (its fraction open).
+  _gateSlot(f, q) {
+    return this.blockOfFace[f] * this.M + 1 + this.n + this.model.interfaces[f].reactions.length + q;
+  }
+
+  // The voltage a gate follows: across its face, or across its port's capacitance at its node.
+  _gateVoltage(gt) {
+    return gt.port === undefined ? this._faceVoltage(gt.f) : this._portVoltage(gt.port, gt.g);
+  }
+
+  // The voltage across port k's capacitance at node g, φ − (V − zeroCharge) (V): a membrane's,
+  // inside (the region) minus outside.
+  _portVoltage(k, g) {
+    const { M, u, uLo, VT } = this, b = this.blockOfNode[g], port = this.model.ports[k];
+    return VT * (u[b * M] + uLo[b * M]) - (this.termV[2 + k] - port.capacitance.zeroCharge);
+  }
+
+  // The voltage across face f, φ_right − φ_left (V).
+  _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]));
+  }
+
+  // Face f's gates, each a row (x − x_old)/dt = α(1 − x) − βx in the voltage across the face.
+  _faceGates(f, bf, bL, bR) {
+    const { res, VT } = this, R = this.rix, itf = this.model.interfaces[f], dt = this.dtNow;
+    const V = this._faceVoltage(f), k0 = 1 + this.n + itf.reactions.length;
+    itf.gates.forEach((gate, q) => {
+      const o = this._gateSlot(f, q), x = this.u[o];
+      const [a, da] = gateRate(gate.alpha, V), [b, db] = gateRate(gate.beta, V);
+      const store = Number.isFinite(dt) ? 1 / dt : 0, j = this.gateIndex[f] + q;
+      res[R[o]] = store * (x - this.gateOld[j]) - (a * (1 - x) - b * x);
+      this._j(bf, k0 + q, bf, k0 + q, store + a + b);
+      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);
+    });
   }
 
   // Scharfetter–Gummel with non-ideal statistics. The excess ex = ζ − ln(c/c_ref) acts as an
@@ -2345,16 +2448,26 @@ export class Solver {
     }
   }
 
+  // The terminals whose ∂res/∂V (termB) and ∂I/∂x (termC) are kept, exactly: the floating ones,
+  // which the Newton solve borders on, or all of them (allTerminals: for the impedance, which reads
+  // its terminal's). A held terminal's are otherwise left as they fall (written but not kept
+  // consistent), which spares a device with dozens of ports (an axon's nodes of Ranvier) the cost
+  // of carrying each one's two dense vectors through every assembly.
+  _liveTerms() {
+    if (this.allTerminals) return this._allTerms ?? (this._allTerms = this.terms.map((_, k) => k));
+    return this.floating;
+  }
+
   // Every terminal's terms: its voltage held or floating, how the residual depends on it
   // (termB), its current into the device (termI) and how that depends on the state (termC).
   _terminals(dt) {
     this._refreshSources();
-    for (let k = 0; k < this.terms.length; k++) {
+    for (const k of this._liveTerms()) {
       this.termB[k].fill(0);
       this.termC[k].fill(0);
-      this.termDI[k] = 0;
-      this.termI[k] = 0;
     }
+    this.termDI.fill(0);
+    this.termI.fill(0);
     this.qg.fill(0);
     this.qgSlope.fill(0);
     this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt, false));
@@ -2412,13 +2525,17 @@ export class Solver {
           flux[i] += res[R[o]];
           this._captureRow(b, r, zF, C);
           this._replaceRow(b, r);
+          for (const Bk of this.termB) Bk[R[o]] = 0; // (other ports' terms in the row replaced)
           this._j(b, r, b, r, 1);
           res[R[o]] = -deta;
           B[R[o]] += -z[i] / VT;
           continue;
         }
-        // conductance: s = G V_T (η_out − η)/(z² F); exchange: s = k (η_out − η)
-        const kk = link.type === 'conductance' ? (link.G * VT) / (z[i] * z[i] * F) : link.k;
+        // conductance: s = G V_T (η_out − η)/(z² F); exchange: s = k (η_out − η). Gated, G times
+        // Π x^p, the gates at this node (each taken in [0, 1]).
+        const kk0 = link.type === 'conductance' ? (link.G * VT) / (z[i] * z[i] * F) : link.k;
+        const gated = link.gates ?? [], q0 = 1 + n + port.surface.length;
+        const open = gated.length ? this._open(gated, (q) => u[b * M + q0 + q]) : 1, kk = kk0 * open;
         res[R[o]] -= v * kk * deta;
         this._j(b, r, b, r, v * kk);
         flux[i] += v * kk * deta;
@@ -2427,6 +2544,12 @@ export class Solver {
           C[R[o]] += -zF * v * kk;
           this.termDI[k] += (zF * v * kk * z[i]) / VT;
         }
+        for (const [q, p] of gated) {
+          const d = this._dOpen(gated, q, p, (qq) => u[b * M + q0 + qq]);
+          if (d === 0) continue;
+          this._j(b, r, b, q0 + q, -v * kk0 * deta * d);
+          if (z[i] !== 0) C[R[b * M + q0 + q]] += zF * v * kk0 * deta * d;
+        }
       }
     }
     if (holds) {
@@ -2435,6 +2558,7 @@ export class Solver {
     }
     port.reactions.forEach((rx, x) => this._portReaction(port, rx, this.portArea[k - 2], this.portRates[k - 2][x], flux, k));
     if (port.capacitance) this._portCapacitance(port, k, dt);
+    if (port.gates.length > 0) this._portGates(port, k, dt);
     if (port.surface.length > 0 && Number.isFinite(dt)) this._surfaceStorage(port, dt);
   }
 
@@ -2503,6 +2627,38 @@ export class Solver {
   // on the port's side, so each node's charge balance (its φ row) gains vol·a·σ, and the port
   // passes the charging current d(Σ vol·a·σ)/dt (none in a steady state). An end node whose φ its
   // contact sets is left to the contact.
+  // A membrane port's gates, at each node of its window: (x − x_old)/dt = α(1 − x) − βx in the
+  // voltage across its capacitance there, φ − (V − zeroCharge).
+  _portGates(port, k, dt) {
+    const { n, res, VT } = this, R = this.rix, B = this.termB[k], store = Number.isFinite(dt) ? 1 / dt : 0, q0 = 1 + n + port.surface.length;
+    port.nodes.forEach((g, w) => {
+      const b = this.blockOfNode[g], V = this._portVoltage(k - 2, g);
+      port.gates.forEach((gate, q) => {
+        const o = b * this.M + q0 + q, x = this.u[o], j = this.portGateIndex[k - 2] + w * port.gates.length + q;
+        const [a, da] = gateRate(gate.alpha, V), [bb, db] = gateRate(gate.beta, V);
+        res[R[o]] = store * (x - this.gateOld[j]) - (a * (1 - x) - bb * x);
+        this._j(b, q0 + q, b, q0 + q, store + a + bb);
+        const s = -(da * (1 - x) - db * x); // ∂/∂V_m, with V_m = V_T φ̂ − V + zeroCharge
+        this._j(b, q0 + q, b, 0, s * VT);
+        B[R[o]] += -s;
+      });
+    });
+  }
+
+  // Π x^p over a link's gates (each x taken in [0, 1]), and its derivative in gate q.
+  _open(gated, x) {
+    let open = 1;
+    for (const [q, p] of gated) open *= powi(Math.min(1, Math.max(0, x(q))), p);
+    return open;
+  }
+  _dOpen(gated, q, p, x) {
+    const xq = x(q);
+    if (!(xq > 0 && xq < 1)) return 0;
+    let others = 1;
+    for (const [q2, p2] of gated) if (q2 !== q) others *= powi(Math.min(1, Math.max(0, x(q2))), p2);
+    return p * powi(xq, p - 1) * others;
+  }
+
   _portCapacitance(port, k, dt) {
     const { M, u, uLo, res, VT } = this, R = this.rix, vol = this.model.grid.vol, area = this.portArea[k - 2];
     const { C: Cs, zeroCharge } = port.capacitance, V = this.termV[k], B = this.termB[k], Ct = this.termC[k];
@@ -2597,7 +2753,7 @@ export class Solver {
     }
 
     // Conductance links: J (toward the device) = G (V_out − V_i), V_out = V_t + offset; exchange
-    // links (neutral species): N_in = k (μ_out − μ)/RT.
+    // links (neutral species): N_in = k (μ_out − μ)/RT; velocity links, v (c_eq − c).
     for (let i = 0; i < n; i++) {
       const link = ct.species[i];
       const o = b * M + 1 + i;
@@ -2609,6 +2765,16 @@ export class Solver {
         res[R[o]] -= (Ac * link.G * (Vt + link.offset - Vi)) / (z[i] * F);
         this._j(b, 1 + i, b, 1 + i, (Ac * link.G * VT) / (z[i] * z[i] * F));
         B[R[o]] += (-Ac * link.G) / (z[i] * F);
+      } else if (link.type === 'velocity') {
+        // N_in = v c (e^(η_out − η) − 1): v (c_eq − c), c_eq in equilibrium with the outside.
+        const ci = c[g * n + i], E = Math.exp(Math.min(this.contactEta(side, i) - (u[o] + uLo[o]), 700));
+        const N = Ac * link.v * ci * (E - 1), d = this.dA;
+        res[R[o]] -= N;
+        d.fill(0);
+        this._dlnc(g, i, 1, d);
+        for (let s = 0; s <= n; s++) if (d[s] !== 0) this._j(b, 1 + i, b, s, -N * d[s]);
+        this._j(b, 1 + i, b, 1 + i, Ac * link.v * ci * E);
+        if (z[i] !== 0) B[R[o]] += (-Ac * link.v * ci * E * z[i]) / VT;
       }
     }
 
@@ -2738,7 +2904,7 @@ export class Solver {
 
   // Scale every row by its largest Jacobian entry (in place, residual too).
   _equilibrate() {
-    const { nB, sys, res, termB } = this;
+    const { nB, sys, res, termB } = this, live = this._liveTerms();
     const { A, B, C, sizes, offA, offB, offC, offX } = sys;
     for (let b = 0; b < nB; b++) {
       const m = sizes[b], mp = b > 0 ? sizes[b - 1] : 0, mn = b < nB - 1 ? sizes[b + 1] : 0;
@@ -2758,7 +2924,7 @@ export class Solver {
         for (let k = 0; k < m; k++) B[ob + k] *= s;
         for (let k = 0; k < mn; k++) C[oc + k] *= s;
         res[offX[b] + r] *= s;
-        for (let k = 0; k < termB.length; k++) termB[k][offX[b] + r] *= s; // (each terminal's ∂/∂V)
+        for (const k of live) termB[k][offX[b] + r] *= s; // (each terminal's ∂/∂V)
       }
     }
   }
@@ -2883,6 +3049,7 @@ export class Solver {
       const k = this.surfPort[g]; // an electrode surface's coverages, as η
       if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + n + q]]));
     }
+    for (const gt of this.gateList) mx = Math.max(mx, Math.abs(delta[R[gt.o]])); // a gate's fraction open
     return mx;
   }
 
@@ -3104,6 +3271,7 @@ export class Solver {
     this.termVPrev.set(this.termV);
     this.computeConcentrations();
     const cN = Float64Array.from(this.c), thN = Float64Array.from(this.th), th0N = Float64Array.from(this.th0);
+    const gN = Float64Array.from(this.gateList, (gt) => this.u[gt.o] + this.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.
     if (!this.contactDEnd || !this.portQEnd) {
@@ -3124,6 +3292,7 @@ export class Solver {
       for (let k = 0; k < cOld.length; k++) cOld[k] = b1 * cN[k] - b2 * prev.c[k];
       for (let k = 0; k < thN.length; k++) this.thOld[k] = b1 * thN[k] - b2 * prev.th[k];
       for (let k = 0; k < th0N.length; k++) this.th0Old[k] = b1 * th0N[k] - b2 * prev.th0[k];
+      for (let k = 0; k < gN.length; k++) this.gateOld[k] = b1 * gN[k] - b2 * prev.g[k];
       this.contactDStart = { left: b1 * DN.left - b2 * prev.D.left, right: b1 * DN.right - b2 * prev.D.right };
       this.portQStart = QN.map((q, k) => b1 * q - b2 * prev.Q[k]);
       dtEff = dt / a0;
@@ -3131,6 +3300,7 @@ export class Solver {
       this.cOld.set(cN);
       this.thOld.set(thN);
       this.th0Old.set(th0N);
+      this.gateOld.set(gN);
       this.contactDStart = DN;
       this.portQStart = QN;
     }
@@ -3162,7 +3332,7 @@ export class Solver {
     }
     result.bdf = bdf;
     if (result.converged) {
-      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, th: thN, th0: th0N, D: DN, Q: QN });
+      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, th: thN, th0: th0N, g: gN, D: DN, Q: QN });
       if (this.history.length > 3) this.history.length = 3;
       this.time = tEnd;
       this.lastDt = dtEff;
@@ -3255,7 +3425,7 @@ export class Solver {
         }
       } else {
         // (Order 2 once three consistent states can check it.)
-        const r = this.step(h, { method: this.history.length >= 2 ? method : 'be', guess: this._extrapolate(guess, this.time + h) });
+        const r = this.step(h, { method: this.history.length >= 2 ? method : 'be', guess: this._extrapolate(guess, h) });
         iterations += r.iterations;
         if (!r.converged) {
           rejected++;
@@ -3301,24 +3471,28 @@ export class Solver {
     }
     this.dtNext = dt;
     this.landing = undefined;
-    return { converged: !failed, done: this.time >= tEnd, steps, rejected, iterations, trace };
+    // Stopped short, other than on the caller's wall-time budget: say where, and why.
+    let stopped;
+    const at = `advance stopped at t = ${this.time.toPrecision(6)} s of ${tEnd.toPrecision(6)}`;
+    if (failed) stopped = `${at}: a step didn't converge even when shortened to ${dt.toExponential(1)} s. A drive's jump too big for one step (ramp it), a driven current the device can't keep passing (a diode's reverse recovery past its storage time: stop there), or a device the steady solves also find hard.`;
+    else if (this.time < tEnd && steps + rejected >= maxSteps) stopped = `${at}: maxSteps (${maxSteps}) used up (${rejected} of them rejected). Call again to go on, or loosen tol.`;
+    return { converged: !failed, done: this.time >= tEnd, steps, rejected, iterations, trace, ...(stopped ? { stopped } : {}) };
   }
 
-  // Quadratic (or linear) extrapolation of the state to time t, from the current state and the
-  // two most recent history entries: a starting guess for Newton.
-  _extrapolate(out, t) {
+  // Quadratic (or linear) extrapolation of the state a time h ahead, from the current state and
+  // the two most recent history entries: a starting guess for Newton. (In offsets built from the
+  // steps' own lengths, never differences of absolute times: a second into a run, after a jump
+  // that a fine grid resolves in steps of 1e-13 s, those differences keep only 3 digits.)
+  _extrapolate(out, h) {
     const [e0, e1] = this.history;
-    const t0 = this.time, u = this.u;
+    const u = this.u;
     if (!e0) return undefined;
     if (!e1) {
-      const l = (t - t0) / (t0 - e0.t);
+      const l = h / e0.dt;
       for (let k = 0; k < out.length; k++) out[k] = u[k] + l * (u[k] - e0.u[k]);
       return out;
     }
-    const t1 = e0.t, t2 = e1.t;
-    const l0 = ((t - t1) * (t - t2)) / ((t0 - t1) * (t0 - t2));
-    const l1 = ((t - t0) * (t - t2)) / ((t1 - t0) * (t1 - t2));
-    const l2 = ((t - t0) * (t - t1)) / ((t2 - t0) * (t2 - t1));
+    const [l0, l1, l2] = lagrange3(h, 0, -e0.dt, -(e0.dt + e1.dt));
     for (let k = 0; k < out.length; k++) out[k] = l0 * u[k] + l1 * e0.u[k] + l2 * e1.u[k];
     return out;
   }
@@ -3327,7 +3501,7 @@ export class Solver {
   // linear after backward Euler), and the factor turning |u − pred| into the local error.
   _predict(pred, bdf) {
     const [e0, e1, e2] = this.history;
-    const t = this.time, h = e0.dt;
+    const h = e0.dt;
     if (!e1) {
       pred.set(e0.u);
       return { scale: 1, order: 1 };
@@ -3335,18 +3509,15 @@ export class Solver {
     const hp = e1.dt;
     if (bdf && e2) {
       const hpp = e2.dt;
-      // Lagrange through (t0, u0), (t1, u1), (t2, u2) at t.
-      const t0 = e0.t, t1 = e1.t, t2 = e2.t;
-      const l0 = ((t - t1) * (t - t2)) / ((t0 - t1) * (t0 - t2));
-      const l1 = ((t - t0) * (t - t2)) / ((t1 - t0) * (t1 - t2));
-      const l2 = ((t - t0) * (t - t1)) / ((t2 - t0) * (t2 - t1));
+      // Lagrange through the three states before at the new time (offsets as in _extrapolate).
+      const [l0, l1, l2] = lagrange3(0, -h, -(h + hp), -(h + hp + hpp));
       for (let k = 0; k < pred.length; k++) pred[k] = l0 * e0.u[k] + l1 * e1.u[k] + l2 * e2.u[k];
       const w = h / hp;
       const Cc = (h * h * h * (1 + w) * (1 + w)) / (w * (1 + 2 * w));
       const Cp = h * (h + hp) * (h + hp + hpp);
       return { scale: Cc / (Cc + Cp), order: 2 };
     }
-    const l0 = (t - e1.t) / (e0.t - e1.t), l1 = 1 - l0;
+    const l0 = (h + hp) / hp, l1 = 1 - l0;
     for (let k = 0; k < pred.length; k++) pred[k] = l0 * e0.u[k] + l1 * e1.u[k];
     // Backward Euler's error against a linear predictor; after a BDF2 step without enough
     // history this overestimates, which is safe.
@@ -3363,9 +3534,22 @@ export class Solver {
     const fail = (m) => {
       throw new DeviceError(m);
     };
-    if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }');
+    if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }, or { interface, species } / { interface, gate }');
     const plan = probes.map((p, k) => {
       const path = `advance: probes[${k}]`;
+      if (p?.interface !== undefined) {
+        // At a face: a species' flux through it (mol/(m²·s), toward +x), or a gate's fraction open.
+        const f = p.interface, itf = this.model.interfaces[f];
+        if (!(Number.isInteger(f) && itf)) fail(`${path}.interface: no interface ${JSON.stringify(f)} (they're numbered from 0, left to right)`);
+        if (p.gate !== undefined) {
+          const q = itf.gates.findIndex((gt) => gt.name === p.gate);
+          if (q < 0) fail(`${path}.gate: interfaces[${f}] has no gate ${JSON.stringify(p.gate)}${itf.gates.length ? ` (it has ${itf.gates.map((gt) => gt.name).join(', ')})` : ''}`);
+          return { o: this._gateSlot(f, q) };
+        }
+        const i = species.findIndex((sp) => sp.name === p.species);
+        if (i < 0) fail(`${path}.species: no species ${JSON.stringify(p.species)}`);
+        return { o: this.blockOfFace[f] * this.M + 1 + i };
+      }
       const quantity = p?.quantity ?? 'c';
       if (quantity !== 'c' && quantity !== 'V' && quantity !== 'phi') fail(`${path}.quantity must be 'c' (mol/m³), 'V' (the species voltage) or 'phi' (φ, V)`);
       const i = quantity === 'phi' ? -1 : species.findIndex((sp) => sp.name === p?.species);
@@ -3397,7 +3581,7 @@ export class Solver {
     };
     return {
       out,
-      read: () => plan.map((q) => (1 - q.w) * at(q, q.g) + q.w * at(q, q.g + 1)),
+      read: () => plan.map((q) => (q.o !== undefined ? (this.loc[q.o] < 0 ? 0 : this.u[q.o]) : (1 - q.w) * at(q, q.g) + q.w * at(q, q.g + 1))),
       push: (values) => values.forEach((v, k) => out[k].push(v)),
     };
   }
@@ -3415,6 +3599,7 @@ export class Solver {
       const k = this.surfPort[g]; // an electrode surface's coverages, as η
       if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(u[b * M + 1 + n + q] - ref[b * M + 1 + n + q]));
     }
+    for (const { o } of this.gateList) mx = Math.max(mx, Math.abs(u[o] - ref[o])); // (a fraction: 1e-3 of m³ is 0.3% of P)
     return mx;
   }
 
@@ -3458,6 +3643,7 @@ export class Solver {
       cOld: Float64Array.from(this.cOld),
       thOld: Float64Array.from(this.thOld),
       th0Old: Float64Array.from(this.th0Old),
+      gateOld: Float64Array.from(this.gateOld),
       time: this.time,
       lastDt: this.lastDt,
       atSteady: this.atSteady,
@@ -3480,6 +3666,7 @@ export class Solver {
     this.cOld.set(s.cOld);
     this.thOld.set(s.thOld);
     this.th0Old.set(s.th0Old);
+    this.gateOld.set(s.gateOld);
     this.time = s.time;
     this.lastDt = s.lastDt;
     this.atSteady = s.atSteady;
@@ -3515,7 +3702,17 @@ export class Solver {
    * Z = δV/δI with I into the device (positive real part for a passive device).
    * @param {ArrayLike<number>} frequencies Hz
    */
-  impedance(frequencies, { profiles = false, terminal = 'right' } = {}) {
+  impedance(frequencies, opts) {
+    const was = this.allTerminals;
+    this.allTerminals = true; // (it reads its terminal's ∂res/∂V and ∂I/∂x)
+    try {
+      return this._impedance(frequencies, opts);
+    } finally {
+      this.allTerminals = was;
+    }
+  }
+
+  _impedance(frequencies, { profiles = false, terminal = 'right' } = {}) {
     const { M, nB, sys, VT } = this;
     const kT = this.terms.findIndex((t) => t.name === terminal);
     if (kT < 0) throw new SolverError(`impedance: no terminal named '${terminal}' (${this.terms.map((t) => t.name).join(', ')})`);
@@ -3527,6 +3724,7 @@ export class Solver {
     this.cOld.set(this.c);
     this.thOld.set(this.th);
     this.th0Old.set(this.th0);
+    this.gateList.forEach((gt, j) => (this.gateOld[j] = this.u[gt.o]));
     this.assemble(Infinity);
     this.contactDStart = { ...this.contactD };
     this.portQStart = Float64Array.from(this.portQ);
@@ -3540,7 +3738,15 @@ export class Solver {
     for (const X of ['A', 'B', 'C']) S[X] = sys[X].map((v, k) => (v - J[X][k]) * dts);
     const Cs = this.termC.map((v, k) => v.map((x, j) => (x - Ct[k][j]) * dts));
     const DIs = this.termDI.map((x, k) => (x - DI[k]) * dts);
-    const cuts = this._currentCuts();
+    // Where the measured contact's current may be read across a segment: anywhere without
+    // ports; with them, only between it and the nearest window (a port's exchange takes current
+    // in or out along it). Never for a port's own terminal.
+    let cuts = kT < 2 ? this._currentCuts() : null;
+    if (cuts && this.model.ports.length > 0) {
+      const windows = this.model.ports.flatMap((p) => Array.from(p.nodes));
+      const lo = Math.min(...windows), hi = Math.max(...windows);
+      cuts = cuts.filter((cut) => (kT === 0 ? cut.s + 1 <= lo : cut.s >= hi));
+    }
     // J·v for GMRES, exact: the assembled J holds a flux's dependence on η_L and η_R as two
     // entries, and where both are huge (an inversion layer) and v nearly uniform, J·v loses the
     // flux to round-off. So the dilute kernels' terms are kept in difference form (see
@@ -3709,7 +3915,7 @@ export class Solver {
           Ii += im;
           for (let j = 0; j < Nc; j++) err += (Math.abs(c[j]) + w * Math.abs(cs[j])) * (eps * Math.hypot(p.r[j], p.i[j]) + p.floor);
         }
-        if (!cuts || kT >= 2) return { Ir, Ii, err };
+        if (!cuts) return { Ir, Ii, err };
         const sgn = kT === 0 ? 1 : -1;
         for (const cut of cuts) {
           let re = 0, im = 0, e = 0;
@@ -3749,7 +3955,8 @@ export class Solver {
         // taken at its edges; and what's left, small, solved for to GMRES's floor, its error now
         // relative to itself. An electrolyte at its open circuit needs it: the response to its
         // terminal is nearly such a shift, and its current the slope of levels uniform to 1e-14,
-        // more than a double can hold. (Not with ports, whose exchange sees the shift.)
+        // more than a double can hold. (A port's exchange sees the shift: its window's rows are
+        // kept with the edges'.) So does a MOS capacitor's back contact, its channel held by a port.
         if (K === 0 && cuts && err > 1e-2 * Math.hypot(Ir, Ii)) {
           const [er, ei] = this._regionShift(yr, yi);
           const tr = new Float64Array(Nc), ti = new Float64Array(Nc);
@@ -3839,8 +4046,9 @@ export class Solver {
     return [er, ei];
   }
 
-  // Compact rows a region's uniform shift can touch: faces, the nodes beside them, and the two
-  // ends (whatever holds a level from outside). Inside a region, every row is unchanged by it.
+  // Compact rows a region's uniform shift can touch: faces, the nodes beside them, the two ends
+  // and the ports' windows (whatever holds a level from outside). Elsewhere inside a region,
+  // every row is unchanged by it.
   _regionEdgeRows() {
     const { M, loc, nB } = this, R = this.rix;
     const edge = new Uint8Array(this.sys.size);
@@ -3856,16 +4064,17 @@ export class Solver {
       mark(b);
       mark(b + 1);
     }
+    for (const port of this.model.ports) for (const g of port.nodes) mark(this.blockOfNode[g]);
     return edge;
   }
 
-  // The cuts where the impedance may read a small-signal current (null where the current
-  // differs between cuts: a device with ports). Each is the linearised total current toward +x
-  // through one segment of an ideal region, Σ (g + iω d)·δu over the unknowns idx: the
-  // Scharfetter–Gummel fluxes' derivatives (as in _segmentsDilute) and the displacement's.
+  // The cuts where the impedance may read a small-signal current. Each is the linearised total
+  // current toward +x through one segment s of an ideal region, Σ (g + iω d)·δu over the
+  // unknowns idx: the Scharfetter–Gummel fluxes' derivatives (as in _segmentsDilute) and the
+  // displacement's. Without ports it's the same through every cut; with them, only between a
+  // contact and the nearest port's window (see _impedance).
   _currentCuts() {
     const { model, n, M, u, uLo, c, z } = this, F = FARADAY;
-    if (model.ports.length > 0) return null;
     const { grid, materials, regions } = model;
     const cuts = [];
     for (let r = 0; r < regions.length; r++) {
@@ -3905,7 +4114,7 @@ export class Solver {
         }
         if (terms.size === 0) continue;
         const idx = [...terms.keys()];
-        cuts.push({ idx, g: idx.map((x) => terms.get(x)[0]), d: idx.map((x) => terms.get(x)[1]) });
+        cuts.push({ s, idx, g: idx.map((x) => terms.get(x)[0]), d: idx.map((x) => terms.get(x)[1]) });
       }
     }
     return cuts;
@@ -3955,6 +4164,7 @@ export class Solver {
   // Jacobian are left partial (the next assemble() starts afresh). Concentrations must be current.
   _assembleBookkeeping(dt) {
     const { model } = this;
+    this.dtNow = dt;
     const { grid, materials, regions } = model;
     this.res.fill(0);
     for (let r = 0; r < regions.length; r++) {
@@ -4083,7 +4293,7 @@ export class Solver {
     // pseudo-transient ramp: one direct attempt first.
     const quick = (canContinue || this.hasGeneration) && direct && opts.continuation !== false;
     let r = this._solveSteady(quick ? { ...opts, maxSteps: 1 } : opts);
-    if (r.converged) this.solvedV = target;
+    if (r.converged) this.solvedV = [level, target];
     if (r.converged) return r;
     // Generation (e.g. light) holding the device far from equilibrium: ramp it up from nearly
     // nothing, each solve warm from the last.
@@ -4097,7 +4307,7 @@ export class Solver {
       const g = this._generationContinuation(opts, r);
       dimmer = this.dimmer;
       if (g.converged) {
-        this.solvedV = target;
+        this.solvedV = [level, target];
         return g;
       }
       r = g;
@@ -4138,17 +4348,23 @@ export class Solver {
       this.computeConcentrations();
     };
     restart();
-    // Ramp from the last converged voltage when the state is that solution (a warm start),
-    // otherwise from level terminals.
-    const from = this.solvedV !== undefined ? this.solvedV : level;
-    const c = this._continuation(opts, from, target, r, from !== level);
+    // Ramp from the contacts' voltages at the last converged solve when the state is that
+    // solution (a warm start): the left one first where it moved, the right held where it was,
+    // then the right. Otherwise from level terminals.
+    const solved = this.solvedV;
+    let c;
+    if (solved) {
+      c = solved[0] === level ? { ...r, converged: true, ramped: false } : this._continuation(opts, 0, solved[0], level, r, true, solved[1]);
+      // (Ramping the right from level terminals, solve there first: a sweep's start.)
+      if (c.converged) c = this._continuation(opts, 1, solved[1], target, c, c.ramped || solved[1] !== level);
+    } else c = this._continuation(opts, 1, level, target, r, false);
     if (c.converged) {
-      this.solvedV = target;
+      this.solvedV = [level, target];
       return c;
     }
     restart();
     r = this._solveSteady(opts); // the full pseudo-transient ramp
-    if (r.converged) this.solvedV = target;
+    if (r.converged) this.solvedV = [level, target];
     return { ...r, steps: r.steps + c.steps, iterations: r.iterations + c.iterations };
   }
 
@@ -4229,13 +4445,15 @@ export class Solver {
     // Floated, the system can lose what held it doesn't (a closed redox cell driven near its
     // limit: its bordered row 33 digits short), but a current-driven steady state is the held
     // one at the voltage that passes the target: found by held solves, by regula falsi
-    // (Illinois) within the bracket, to 1e-10 of the target.
+    // (Illinois) within the bracket, to 1e-10 of the target, or at open circuit of the largest
+    // current the march saw (a target of 0 is never met exactly).
+    const scale = Math.max(Math.abs(target), ...seen.map(([, I]) => Math.abs(I)));
     try {
       let side = 0;
       for (let it = 0; it < 60; it++) {
         const Vm = Va - (fa * (Vb - Va)) / (fb - fa), fm = hold(Vm);
         if (!Number.isFinite(fm)) return fail();
-        if (Math.abs(fm) <= 1e-10 * Math.abs(target)) return { converged: true, steps, iterations, history, residual: Math.abs(fm) };
+        if (Math.abs(fm) <= 1e-10 * scale) return { converged: true, steps, iterations, history, residual: Math.abs(fm) };
         if (Math.sign(fm) === Math.sign(fb)) {
           [Vb, fb] = [Vm, fm];
           if (side === -1) fa /= 2;
@@ -4293,12 +4511,18 @@ export class Solver {
     }
   }
 
-  _continuation(opts, level, target, r, warm) {
+  // Terminal k (a contact) ramped from `level` to `target` through steady solves, each warm from
+  // the last (`hold`: the other contact's voltage meanwhile, if not its own). A warm ramp that has
+  // nowhere to go converges only if what it started from did (`ramped`): the state it carries
+  // must be some ramp's solution, never just the one a failed solve left.
+  _continuation(opts, k, level, target, r, warm, hold) {
     const sub = this._directSteady() ? { ...opts, maxSteps: 1 } : opts;
     let V = level, dV = (target - level) / 8, steps = r.steps, iterations = r.iterations;
     const history = r.history.slice();
+    if (warm && V === target) return { ...r, converged: r.ramped === true, steps, iterations, history, ramped: r.ramped };
     try {
-      this.sourceOverride.set(1, V);
+      this.sourceOverride.set(k, V);
+      if (hold !== undefined) this.sourceOverride.set(1 - k, hold);
       let q;
       if (!warm) {
         q = this._solveSteady(opts);
@@ -4320,7 +4544,7 @@ export class Solver {
       while (V !== target) {
         const next = Math.abs(target - V) <= Math.abs(dV) ? target : V + dV;
         const u1 = Float64Array.from(this.u), u1Lo = Float64Array.from(this.uLo), v1 = Float64Array.from(this.termV);
-        this.sourceOverride.set(1, next);
+        this.sourceOverride.set(k, next);
         q = this._solveSteady(sub);
         steps += q.steps;
         iterations += q.iterations;
@@ -4337,9 +4561,10 @@ export class Solver {
           if (Math.abs(dV) < 1e-6 * Math.abs(target - level)) return { converged: false, steps, iterations, history };
         }
       }
-      return { converged: true, steps, iterations, history };
+      return { converged: true, steps, iterations, history, ramped: true };
     } finally {
-      this.sourceOverride.delete(1);
+      this.sourceOverride.delete(k);
+      if (hold !== undefined) this.sourceOverride.delete(1 - k);
       this._refreshSources();
     }
   }