driftlet 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/channels.js

@@ -28,7 +28,7 @@ export function ghkCurrent(z, inside, outside, V, T) {
 }
 
 /**
- * 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)
@@ -40,13 +40,21 @@ export function ghkCurrent(z, inside, outside, V, T) {
  * (`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 = HH_T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {} } = {}) {
-  need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name');
+export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {}, linear = false, area } = {}) {
   need(num(T) && T > 0, `hodgkinHuxley: T must be a temperature in K, got ${T}`);
   need(num(at), `hodgkinHuxley: at must be a voltage (V), got ${at}`);
   const G = { Na: 1200, K: 360, leak: 3, ...g };
@@ -54,6 +62,21 @@ export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-',
   const q10 = Math.exp(Math.log(3) * ((T - HH_T) / 10)); // Q₁₀ = 3
   const scaled = (r) => ({ ...r, rate: r.rate * q10 });
   const gates = Object.fromEntries(Object.entries(HH_GATES).map(([k, gt]) => [k, { alpha: scaled(gt.alpha), beta: scaled(gt.beta) }]));
+  need(typeof linear === 'boolean', `hodgkinHuxley: linear must be true or false, got ${linear}`);
+  if (area !== undefined || linear) {
+    need(area === undefined || (num(area) && area > 0), `hodgkinHuxley: area must be the membrane per volume (m²/m³; 2/a for an axon of radius a), got ${area}`);
+    for (const [k, v] of Object.entries(G)) need(num(v) && v > 0, `hodgkinHuxley: g.${k} must be a conductance > 0 (S/m²), got ${v}`);
+    const per = area ?? 1; // per volume along a port, or per area on a face
+    return {
+      gates,
+      species: {
+        [Na]: { type: 'conductance', G: G.Na * per, gates: { m: 3, h: 1 } },
+        [K]: { type: 'conductance', G: G.K * per, gates: { n: 4 } },
+        [leak]: { type: 'conductance', G: G.leak * per },
+      },
+    };
+  }
+  need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name (or, for a membrane port, its area)');
   const P = (name, z, gval, what) => {
     need(num(inside[name]) && inside[name] > 0 && num(outside[name]) && outside[name] > 0, `hodgkinHuxley: give ${name}'s concentration inside and outside (mol/m³), for its ${what}`);
     need(num(gval) && gval > 0, `hodgkinHuxley: g.${what} must be a conductance > 0 (S/m²), got ${gval}`);

package/src/describe.js

@@ -202,7 +202,7 @@ export function describe(def) {
       const laws = species.flatMap((sp, i) => {
         const l = itf.links[i];
         const gated = (l.gates ?? []).map(([q, p]) => itf.gates[q].name + (p > 1 ? `^${p}` : '')).join('·');
-        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s${gated ? ` × ${gated}` : ''}`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²`] : [];
+        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s${gated ? ` × ${gated}` : ''}`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²${gated ? ` × ${gated}` : ''}`] : [];
       });
       const gates = (itf.gates ?? []).map((g) => g.name);
       lines.push(

package/src/device.js

@@ -15,7 +15,7 @@ import { stoichiometry as equationStoichiometry, faceSides, parseEquation } from
 export { DeviceError };
 
 // Contacts use the same laws as internal faces: the outside is a phase with known levels.
-const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange']);
+const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange', 'velocity']);
 const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance', 'permeability']);
 const PHI_LINK_TYPES = new Set(['bulk', 'neutral', 'capacitive', 'pinned']);
 const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells'];
@@ -25,6 +25,7 @@ const LINK_FIELDS = {
   equilibrium: ['type', 'offset', 'mu'],
   conductance: ['type', 'G', 'offset'],
   exchange: ['type', 'k', 'mu'],
+  velocity: ['type', 'v', 'offset', 'mu'],
 };
 
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -669,7 +670,7 @@ function normalizeGeometry(g) {
 // the window, `area` (m²/m³) of it per volume.
 function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT) {
   need(isObject(pdef), `${path} must be an object`);
-  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance', 'gates']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance', 'gates', 'bath']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -691,9 +692,27 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
   surface.forEach((sp, s) => need(reactions.some((rx) => rx.part.some((p) => p.side === 2 && p.s === s)), `${path}.surface.${sp.name}: no reaction of the port makes or uses it`));
   const capacitance = portCapacitance(pdef, path, mat);
   // Gates (a membrane's channels): they follow the voltage across the port's capacitance.
-  const gates = normalizeGates(pdef.gates, path, mat, mat);
+  const gates = normalizeGates(pdef.gates, path, mat, mat, "the port's capacitance");
   need(gates.length === 0 || capacitance !== null, `${path}.gates: a gate follows the voltage across the port's capacitance (a membrane's), so give the port one`);
   need(pdef.species === undefined ? reactions.length > 0 || capacitance !== null : isObject(pdef.species), `${path}.species must map species names to port links`);
+  // A bath: the outside's composition. The port's V is then the outside's φ, and each linked
+  // species' level there, against it, follows from the composition through the window's
+  // statistics, (μ° + RT ζ)/(zF) (or μ for a neutral one), unless its link gives one. Only the
+  // linked species' levels are taken, so it needn't list (or balance) the rest.
+  let bathLevel = null;
+  if (pdef.bath !== undefined) {
+    need(isObject(pdef.bath) && isObject(pdef.bath.c), `${path}.bath must be { c: { species: concentration } }`);
+    fields(pdef.bath, `${path}.bath`, ['c']);
+    const cb = new Float64Array(species.length);
+    for (const [sname, v] of Object.entries(pdef.bath.c)) {
+      need(speciesIndex.has(sname), `${path}.bath.c.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
+      const i = speciesIndex.get(sname);
+      need(mat.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from ${reg.name} (material '${mat.name}'), so its level outside means nothing here`);
+      cb[i] = positive(v, `${path}.bath.c.${sname}`);
+    }
+    const zb = bathZeta(mat, cb, reg.background);
+    bathLevel = (i) => (cb[i] > 0 ? mat.mu0[i] + RT * zb[i] : undefined); // μ̄ − zFφ outside
+  }
   const links = species.map(() => ({ type: 'blocked' }));
   for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
     const lpath = `${path}.species.${sname}`;
@@ -708,14 +727,15 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     const z = species[i].z;
     // The outside level: an offset from V for charged species, an absolute μ for neutral ones.
     let level;
+    const fromBath = bathLevel?.(i);
     if (z === 0) {
       need(link.type !== 'conductance', `${lpath}: a neutral species exchanges by { type: 'exchange', k, mu }`);
-      level = { mu: finite(link.mu, `${lpath}.mu (the outside μ, J/mol)`) };
+      level = { mu: finite(link.mu ?? fromBath, `${lpath}.mu (the outside μ, J/mol${bathLevel ? `; or give '${sname}' in the bath` : ''})`) };
     } else {
       need(link.type !== 'exchange', `${lpath}: a charged species exchanges by { type: 'conductance', G }`);
       need(link.mu === undefined, `${lpath}: a charged species is held by an offset from the port voltage, not by mu`);
-      const offset = link.offset ?? (terminal === i ? 0 : undefined);
-      need(offset !== undefined, `${lpath}.offset: give V_i − V (V); only the terminal species defaults to 0`);
+      const offset = link.offset ?? (fromBath !== undefined ? fromBath / (z * FARADAY) : !bathLevel && terminal === i ? 0 : undefined);
+      need(offset !== undefined, bathLevel ? `${lpath}: give '${sname}' in the bath (or an offset, V_i − V)` : `${lpath}.offset: give V_i − V (V); only the terminal species defaults to 0 (or give the port a bath)`);
       level = { offset: finite(offset, `${lpath}.offset`) };
     }
     // On a metal, G is a lumped conductance per area (S/m²), spread over its thickness.
@@ -968,10 +988,10 @@ function gatedBy(raw, gates, lpath, where) {
     return [q, p];
   });
 }
-function normalizeGates(raw, where, matL, matR) {
+function normalizeGates(raw, where, matL, matR, across = 'the face') {
   if (raw === undefined) return [];
   need(isObject(raw), `${where}.gates must map gate names to { alpha, beta }`);
-  need(!matL.phiFree && !matR.phiFree, `${where}.gates: a gate follows the voltage across the face, which needs φ on both sides`);
+  need(!matL.phiFree && !matR.phiFree, `${where}.gates: a gate follows the voltage across ${across}, which needs φ there`);
   return Object.entries(raw).map(([name, gdef]) => {
     const gpath = `${where}.gates.${name}`;
     need(isObject(gdef), `${gpath} must be { alpha, beta }`);
@@ -1153,6 +1173,22 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
         links[i] = { type: 'conductance', G: positive(link.G, `${lpath}.G`), offset: finite(offset, `${lpath}.offset`) };
         continue;
       }
+      if (link.type === 'velocity') {
+        // A surface velocity: N_in = v (c_eq − c), c_eq the edge's concentration in equilibrium
+        // with the outside level (thermionic emission over a barrier, a contact's surface
+        // recombination velocity), v c (e^((μ̄_out − μ̄)/RT) − 1) for any statistics.
+        const v = positive(link.v, `${lpath}.v (m/s)`);
+        if (species[i].z === 0) {
+          need(link.offset === undefined, `${lpath}: a neutral species' outside level is its mu (J/mol), not an offset`);
+          links[i] = { type: 'velocity', v, mu: finite(link.mu, `${lpath}.mu (the outside μ, J/mol)`) };
+          continue;
+        }
+        need(link.mu === undefined, `${lpath}: a charged species' outside level is an offset from the terminal voltage, not a mu`);
+        const offset = link.offset ?? (terminal === i ? 0 : undefined);
+        need(offset !== undefined, `${lpath}.offset: give V_i − V_terminal (V) of the outside reservoir; only the terminal species defaults to 0`);
+        links[i] = { type: 'velocity', v, offset: finite(offset, `${lpath}.offset`) };
+        continue;
+      }
       if (link.type === 'exchange') {
         // A neutral species exchanging with the outside at its μ: N_in = k (μ_out − μ)/RT.
         need(species[i].z === 0, `${lpath}: a charged species exchanges by { type: 'conductance', G }`);
@@ -1184,12 +1220,19 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     const bath = cdef.bath;
     need(isObject(bath) && isObject(bath.c), `${path}.bath must be { c: { species: concentration }, reference }`);
     fields(bath, `${path}.bath`, ['c', 'reference', 'offset']);
-    need(speciesIndex.has(bath.reference), `${path}.bath.reference: unknown species ${JSON.stringify(bath.reference)}${known(speciesIndex)}`);
-    const r = speciesIndex.get(bath.reference);
+    // Without a reference, V is the bath's φ (an ideal salt bridge: the membrane potential's
+    // convention), and the terminal is the first charged species in it.
+    const byPhi = bath.reference === undefined;
+    if (byPhi) need(bath.offset === undefined, `${path}.bath.offset: an offset places the reference species, and this bath has none (its V is its φ)`);
+    else need(speciesIndex.has(bath.reference), `${path}.bath.reference: unknown species ${JSON.stringify(bath.reference)}${known(speciesIndex)}`);
+    const r = byPhi
+      ? species.findIndex((sp) => sp.z !== 0 && bath.c[sp.name] > 0)
+      : speciesIndex.get(bath.reference);
+    need(r >= 0, `${path}.bath: the bath needs a charged species`);
     need(species[r].z !== 0, `${path}.bath.reference: the reference species must be charged`);
-    need(bath.c[bath.reference] !== undefined, `${path}.bath.reference: '${bath.reference}' must be in the bath`);
-    need(cdef.terminal === undefined || terminal === r, `${path}.terminal must be the bath's reference species`);
-    terminal = r;
+    need(bath.c[species[r].name] !== undefined, `${path}.bath.reference: '${bath.reference}' must be in the bath`);
+    need(byPhi || cdef.terminal === undefined || terminal === r, `${path}.terminal must be the bath's reference species`);
+    terminal = byPhi && terminal !== null ? terminal : r;
     let charge = region.fixedCharge / FARADAY, scale = Math.abs(charge);
     const cb = new Float64Array(species.length);
     for (const [sname, v] of Object.entries(bath.c)) {
@@ -1205,7 +1248,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     const zb = bathZeta(mat, cb, region.background);
     const level = (i) => mat.mu0[i] + RT * zb[i]; // μ̄ − zFφ_bath
     const refOffset = bath.offset === undefined ? 0 : finite(bath.offset, `${path}.bath.offset`);
-    const beta = refOffset - level(r) / (species[r].z * FARADAY); // φ_bath − V
+    const beta = byPhi ? 0 : refOffset - level(r) / (species[r].z * FARADAY); // φ_bath − V
     for (let i = 0; i < species.length; i++) {
       if (!(cb[i] > 0)) continue;
       links[i] =

package/src/index.js

@@ -166,7 +166,12 @@ export class Device {
    * @returns {Solution}
    */
   solve(opts) {
-    return makeSolution(this.solver, this.solver.solveSteady(opts));
+    // A solve that fails reports the state it failed in, and leaves the device as it was: a
+    // device with no steady state (a host filling at a current) can still advance() from there.
+    const snap = this.solver._snapshot();
+    const sol = makeSolution(this.solver, this.solver.solveSteady(opts));
+    if (!sol.converged) this.solver._restore(snap);
+    return sol;
   }
 
   /**

package/src/solution.js

@@ -191,7 +191,7 @@ export function makeSolution(solver, result = {}) {
 
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,
   // gate contacts), check the local Debye length against the adjacent cell.
-  sol.warnings = [...(model.warnings ?? [])];
+  sol.warnings = [...(model.warnings ?? []), ...(result.stopped ? [result.stopped] : [])];
   // A surface covered almost completely: its coverages' η barely move anything below ~1e-10 bare,
   // and Newton loses them (a transient can stall there).
   sol.ports.forEach((p) => {
@@ -207,9 +207,17 @@ export function makeSolution(solver, result = {}) {
   const cond = solver.conditioning, un = solver.unreached;
   if (result.converged === false && un) {
     const [[V0, I0], [V1, I1]] = [un.low, un.high], g = (x) => x.toPrecision(3), A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    // The opposite sign within reach: likely a sign slip (a drive is the current into the device).
+    const flipped = Math.min(I0, I1) <= -un.target && -un.target <= Math.max(I0, I1);
     sol.warnings.push(
       `${un.terminal}: no steady state passes the driven current ${g(un.target)} ${A}; held from ${g(V0)} V to ${g(V1)} V ` +
-        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.`,
+        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.` +
+        (flipped ? ` (It passes ${g(-un.target)} ${A}: if that was meant, a terminal's current is into the device.)` : '') +
+        // Nothing passed at any voltage: the device only stores what comes in (a host filling, a
+        // capacitor charging), so it has no steady state at a current.
+        (Math.max(Math.abs(I0), Math.abs(I1)) < 1e-6 * Math.abs(un.target)
+          ? ' It passes almost nothing steadily at any voltage, so it may only store what comes in (a host filling, a capacitor charging), which has no steady state at a current: advance() in time instead.'
+          : ''),
     );
   } else if (result.converged === false && cond && cond.digits > 12) {
     const digits = Number.isFinite(cond.digits) ? `lost ${cond.digits.toFixed(0)} of its ~16 digits` : 'was exactly singular';
@@ -219,6 +227,12 @@ export function makeSolution(solver, result = {}) {
         'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).',
     );
   }
+  if (result.converged === false && !result.stopped && !un && !(cond && cond.digits > 12)) {
+    sol.warnings.push(
+      'the solve did not converge, and nothing specific showed why. ' +
+        'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
+    );
+  }
   const debye = (g) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     const s2 = solver.screening(g); // zᵀKz: Σ z² c for ideal statistics

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;
   }
@@ -2519,6 +2525,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 +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;
@@ -2758,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;
       }
     }
 
@@ -3408,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++;
@@ -3454,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;
   }
@@ -3480,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 };
@@ -3488,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.
@@ -3720,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
@@ -3889,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;
@@ -3929,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);
@@ -4019,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);
@@ -4036,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++) {
@@ -4085,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;
@@ -4264,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.
@@ -4278,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;
@@ -4319,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 };
   }
 
@@ -4410,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;
@@ -4474,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);
@@ -4501,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;
@@ -4518,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();
     }
   }

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 }) } };
 }