driftlet 0.12.0 → 0.14.0

package/src/solver.js

@@ -261,12 +261,18 @@ 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') {
-    const v = rate * Math.exp((V - midpoint) / scale);
-    return [v, v / scale];
+    // (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;
@@ -1214,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;
   }
@@ -2341,6 +2347,21 @@ export class Solver {
     return P * -Math.expm1(-(aHi + aLo));
   }
 
+  // A bulk reaction's forward one-way rate at node g (mol/(m³·s)); its backward one is that
+  // times e^{−a}, so their difference is bulkRate's.
+  bulkForward(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) {
+      let a = rx.fixedA;
+      for (let p = 0; p < rx.sp.length; p++) a += rx.nu[p] * (u[b * M + 1 + rx.sp[p]] + uLo[b * M + 1 + rx.sp[p]]);
+      return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], a).forward;
+    }
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P;
+  }
+
   // The larger of a bulk reaction's two one-way rates at node g (mol/(m³·s)): the scale its net
   // rate is read against (in equilibrium the net rate is their round-off).
   bulkOneWay(rx, g) {
@@ -2370,7 +2391,7 @@ export class Solver {
     const dDn = tp * cn + tp * n1 * kN + tn * p1 * (1 - kN);
     const dDp = tp * n1 * kP + tn * cp + tn * p1 * (1 - kP);
     const dDa = tp * n1 * kA + tn * p1 * (-1 - kA);
-    return { rate, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
+    return { rate, forward: np / den, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
   }
 
   // A face reaction (see normalizeFaceReactions). Its rate r_k is an unknown of the face block,
@@ -2519,6 +2540,7 @@ 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;
@@ -2746,7 +2768,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;
@@ -2758,6 +2780,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;
       }
     }
 
@@ -3135,7 +3167,13 @@ export class Solver {
       const alpha = own > maxStep ? maxStep / own : 1;
       this._addToState(delta, -alpha);
       this.floating.forEach((k, a) => (this.termV[k] -= alpha * deltaV[a]));
-      if (alpha === 1 && step < tol) {
+      // A time step's Newton contracts fast from its predictor (1e-2, 1e-9, 1e-15 thermal
+      // units). The next update would be about θ = step/(the last one) times this one, so where
+      // θ/(1 − θ) of it (Hairer and Wanner's estimate) is under tol, this update converged it:
+      // the iteration that would only show that is skipped, a third of a typical step's work.
+      const last = history[history.length - 2], theta = step / last;
+      const contracted = dt !== Infinity && it >= 2 && step < 1e-6 && theta < 0.1 && (theta / (1 - theta)) * step < tol;
+      if (alpha === 1 && (step < tol || contracted)) {
         const done = { converged: true, iterations: it, history, residual: rmax };
         if (islandsOff(it, done)) continue;
         this.computeConcentrations();
@@ -3408,7 +3446,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++;
@@ -3454,24 +3492,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;
   }
@@ -3480,7 +3522,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 };
@@ -3488,18 +3530,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.
@@ -3720,7 +3759,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
@@ -3889,7 +3936,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;
@@ -3929,7 +3976,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);
@@ -4019,8 +4067,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);
@@ -4036,16 +4085,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++) {
@@ -4085,12 +4135,78 @@ 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;
   }
 
+  // Each species' flux toward +x across every segment, at the current state (concentrations
+  // computed): totals through the cross-section, mol/s (mol/(m²·s) for a planar device). A face's
+  // segment, between its pair of nodes, carries the face's flux; a conductor's, its carrier's.
+  // These are the fluxes the balances add up (displacement aside), from the same formulas.
+  segmentFluxes() {
+    const { model, n, M, u, uLo, c, z, ex } = this;
+    const { grid, materials, regions, interfaces } = model;
+    const out = Array.from({ length: n }, () => new Float64Array(grid.nNodes - 1));
+    for (let r = 0; r < regions.length; r++) {
+      const reg = regions[r], mat = materials[reg.material], vel = reg.velocity;
+      for (let s = grid.regionStart[r]; s < grid.regionEnd[r]; s++) {
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s];
+        if (mat.conductor) {
+          out[mat.conductor.i][s] = u[bL * M];
+          continue;
+        }
+        for (let i = 0; i < n; i++) {
+          if (!mat.present[i] || mat.D[i] === 0) continue;
+          const pe = (vel * h) / mat.D[i];
+          const d = z[i] * (u[bR * M] - u[bL * M]) + ex[(s + 1) * n + i] - ex[s * n + i] - pe;
+          const deta = u[bR * M + 1 + i] - u[bL * M + 1 + i] + (uLo[bR * M + 1 + i] - uLo[bL * M + 1 + i]) - pe;
+          out[i][s] = -(mat.D[i] / h) * bernoulli(d) * c[s * n + i] * Math.expm1(deta);
+        }
+        if (reg.mixing > 0) {
+          // Eddy mixing (see _segmentMixing): −(D_mix/h) c̄_i (Δη_i − z_i q), c̄ the logarithmic mean.
+          const on = [...Array(n).keys()].filter((i) => mat.present[i] && mat.D[i] > 0);
+          const cb = [], de = [];
+          let S = 0, Q = 0;
+          for (const k of on) {
+            const a = c[s * n + k], b = c[(s + 1) * n + k];
+            cb[k] = a === b ? a : (b - a) / Math.log(b / a);
+            de[k] = u[bR * M + 1 + k] - u[bL * M + 1 + k] + (uLo[bR * M + 1 + k] - uLo[bL * M + 1 + k]);
+            S += z[k] * z[k] * cb[k];
+            Q += z[k] * cb[k] * de[k];
+          }
+          const q = S > 0 ? Q / S : 0;
+          for (const i of on) out[i][s] -= (reg.mixing / h) * cb[i] * (de[i] - z[i] * q);
+        }
+      }
+    }
+    interfaces.forEach((itf, f) => {
+      const gL = grid.regionEnd[f], b = this.blockOfFace[f];
+      for (let i = 0; i < n; i++) if (itf.links[i].type !== 'blocked') out[i][gL] = grid.area[gL] * u[b * M + 1 + i];
+    });
+    return out;
+  }
+
+  // A face's one-way fluxes for each species crossing it by permeability, per area: toward +x
+  // and toward −x, whose difference is its net flux (Ussing's unidirectional fluxes; GHK's two
+  // terms between like solutions). null for a species crossing any other way.
+  faceOneWay(f) {
+    const { model, n, M, u, uLo, z } = this, itf = model.interfaces[f], grid = model.grid;
+    const bL = this.blockOfFace[f] - 1, bR = bL + 2, gl = grid.regionEnd[f], gr = gl + 1;
+    return itf.links.map((link, i) => {
+      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;
+      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];
+      return [right, right * Math.exp(deta)];
+    });
+  }
+
   // Complex profiles of δφ (V), δμ̄ (J/mol) and δc (mol/m³) from a small-signal solution.
   _smallSignalProfiles(xr, xi) {
     const { n, M, z, VT, model } = this;
@@ -4264,7 +4380,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.
@@ -4278,7 +4394,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;
@@ -4319,17 +4435,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 };
   }
 
@@ -4410,13 +4532,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;
@@ -4474,12 +4598,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);
@@ -4501,7 +4631,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;
@@ -4518,9 +4648,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();
     }
   }

package/src/stack.js

@@ -87,16 +87,18 @@ export function ohmic(d = 0, carriers = ['e-', 'h+']) {
 }
 
 /**
- * A bath: a neutral composition `c` (mol/m³) held at the contact, its levels referred to the
- * charged `reference` species (the ion a reference electrode would sense, e.g. Cl⁻ for
- * Ag/AgCl), which is the terminal.
+ * A bath: a neutral composition `c` (mol/m³) held at the contact. With a `reference`, the charged
+ * species a reference electrode would sense (Cl⁻ for Ag/AgCl), its levels are referred to that
+ * species, which is the terminal. Without one, `bath(c, drive)`, the terminal voltage is the
+ * bath's φ: an ideal salt bridge, the convention of membrane potentials.
  * @param {Record<string, number>} c
- * @param {string} reference
+ * @param {string | number | object} [reference] the reference species, or the drive
  * @param {number | object} [drive]
  * @param {{ offset?: number }} [opts] where the reference species sits relative to the terminal
  *   voltage, V_ref = V + offset (V)
  */
 export function bath(c, reference, d = 0, { offset } = {}) {
+  if (typeof reference !== 'string') return { ...drive(reference ?? 0, 'bath'), bath: { c: { ...c } } };
   return { ...drive(d, 'bath'), bath: { c: { ...c }, reference, ...(offset === undefined ? {} : { offset }) } };
 }
 

package/src/types.js

@@ -114,7 +114,8 @@
  * @typedef {'blocked' | 'equilibrium'
  *   | { type: 'equilibrium', offset?: number, mu?: number }
  *   | { type: 'conductance', G: number, offset?: number }
- *   | { type: 'exchange', k: number, mu: number }} ContactSpeciesLink
+ *   | { type: 'exchange', k: number, mu: number }
+ *   | { type: 'velocity', v: number, offset?: number, mu?: number }} ContactSpeciesLink
  */
 /**
  * 'bulk': the end node is plain bulk (locally neutral, no double layer); 'neutral': no charge at

package/types/channels.d.ts

@@ -1,6 +1,6 @@
 export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): number;
 /**
- * Hodgkin and Huxley's squid-axon channels, for a membrane face with the outside on its left
+ * Hodgkin and Huxley's squid-axon channels: for a membrane face with the outside on its left
  * (so the gates' voltage, φ_right − φ_left, is the membrane potential): the face's `gates`, and
  * `species` links for Na⁺ (P·m³h), K⁺ (P·n⁴) and the leak (ungated), to spread into the face
  * beside its φ law, `{ phi: { type: 'capacitive', C: 0.01 }, ...hh }`, adding links (or blocks)
@@ -12,12 +12,21 @@ export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): n
  * (`leak`, of charge `leakZ`: Cl⁻ by default, whose Nernst level in squid is near their leak
  * reversal, −54 mV). The
  * rates are theirs at 6.3 °C, scaled to `T` by Q₁₀ = 3.
+ *
+ * Or with `linear: true`, Hodgkin and Huxley's own linear channels on the face: conductance links,
+ * G = g, gated the same, whose currents are g(V − E) with E each ion's Nernst level at the
+ * concentrations on either side (so `inside`, `outside` and `at` aren't needed).
+ *
+ * Or, given `area` (membrane per volume of the region, 2/a for an axon of radius a), for a membrane
+ * port along a region: links that are their linear conductances, G = g × area per volume, gated the
+ * same, each ion's reversal potential following from the port's bath and the concentrations inside
+ * (so `inside`, `outside` and `at` aren't needed).
  * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
- *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string } }} opts concentrations in
+ *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string }, linear?: boolean, area?: number }} opts concentrations in
  *   mol/m³ by species name, K, S/m², V
  * @returns {{ gates: object, species: object }}
  */
-export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names }?: {
+export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names, linear, area }?: {
     inside: object;
     outside: object;
     T?: number;
@@ -33,6 +42,8 @@ export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names }?
         Na?: string;
         K?: string;
     };
+    linear?: boolean;
+    area?: number;
 }): {
     gates: object;
     species: object;

package/types/checks.d.ts

@@ -18,7 +18,8 @@
  *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
- * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
+ *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
  *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
  *   wants less). The discretisation is second order, so the change estimates this grid's error

package/types/kit.d.ts

@@ -36,6 +36,7 @@ export function vacuumZeroCharge(def: object, workFunction: number, inside: Vacu
 export { live } from "./live.js";
 export { recorder } from "./recorder.js";
 export { check } from "./checks.js";
+export { particles } from "./particles.js";
 export { polarization } from "./polarization.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,

package/types/particles.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A swarm of dots sampling a solution's concentrations and fluxes. Amounts are per area (a planar
+ * device's). `step(dt)` moves them on in the device's time, at the rates of the solution last
+ * given; `update(sol)` gives a new one.
+ * @param {object} sol a solution (from solve(), advance(), live(), …)
+ * @param {object} [opts]
+ * @param {string[]} [opts.species] which species (default: every species with a concentration)
+ * @param {number} [opts.dots] about how many dots per species (default 200), for the default weight
+ * @param {number|object} [opts.weight] amount per dot, mol/m²: one number for every species (so
+ *   their dots compare), or { name: weight }; default, each species' total over `dots`
+ * @param {number} [opts.cap] the most dots a cell holds on average before it's a sea (default ∞)
+ * @param {number} [opts.cells] about how many cells across the device (default 120)
+ * @param {() => number} [opts.random] a uniform random source in [0, 1) (default Math.random)
+ */
+export function particles(sol: object, { species, dots, weight, cap, cells, random }?: {
+    species?: string[];
+    dots?: number;
+    weight?: number | object;
+    cap?: number;
+    cells?: number;
+    random?: () => number;
+}): {
+    cells: {
+        x0: any;
+        x1: any;
+        region: any;
+    }[];
+    species: any;
+    weight: {};
+    sea: {};
+    dots: any[];
+    events: any[];
+    crossed: {};
+    time: number;
+    update: (next: any, { resample }?: {
+        resample?: boolean;
+    }) => /*elided*/ any;
+    step: (dt: any, { maxHops }?: {
+        maxHops?: number;
+    }) => /*elided*/ any;
+    expected: (nm: any) => Float64Array<ArrayBuffer>;
+};

package/types/solution.d.ts

@@ -9,6 +9,7 @@ export function makeSolution(solver: any, result?: {}): {
     muStd: {};
     V: {};
     Vstd: {};
+    T: any;
     time: any;
     steady: any;
     converged: any;

package/types/solver.d.ts

@@ -209,9 +209,11 @@ export class Solver {
     mixWork: Float64Array<any>[];
     _dc(g: any, k: any, d: any): void;
     bulkRate(rx: any, g: any): number;
+    bulkForward(rx: any, g: any): any;
     bulkOneWay(rx: any, g: any): number;
     _srhRate(law: any, cn: any, cp: any, a: any): {
         rate: number;
+        forward: number;
         oneWay: number;
         Cn: number;
         Cp: number;
@@ -294,6 +296,7 @@ export class Solver {
      * animation can call it once per frame; the step size carries over between calls.
      */
     integrate(tEnd: any, opts?: {}): {
+        stopped?: string;
         converged: boolean;
         done: boolean;
         steps: number;
@@ -307,7 +310,7 @@ export class Solver {
         };
     };
     landing: any;
-    _extrapolate(out: any, t: any): any;
+    _extrapolate(out: any, h: any): any;
     _predict(pred: any, bdf: any): {
         scale: number;
         order: number;
@@ -381,10 +384,13 @@ export class Solver {
     _regionShift(yr: any, yi: any): Float64Array<any>[];
     _regionEdgeRows(): Uint8Array<any>;
     _currentCuts(): {
+        s: any;
         idx: any[];
         g: any[];
         d: any[];
     }[];
+    segmentFluxes(): Float64Array<ArrayBuffer>[];
+    faceOneWay(f: any): any;
     _smallSignalProfiles(xr: any, xi: any): {
         phi: {
             re: Float64Array<any>;
@@ -424,7 +430,7 @@ export class Solver {
         iterations: any;
         history: any;
     };
-    _continuation(opts: any, level: any, target: any, r: any, warm: any): any;
+    _continuation(opts: any, k: any, level: any, target: any, r: any, warm: any, hold: any): any;
     _solveSteady(opts?: {}): {
         converged: boolean;
         steps: number;