driftlet 0.16.2 → 1.0.0

package/src/solution.js

@@ -87,7 +87,7 @@ export function makeSolution(solver, result = {}) {
   }
   solver._assembleBookkeeping(solver.lastDt);
   sol.contacts = {};
-  sol.gates = {};
+  sol.plates = {};
   for (const side of ['left', 'right']) {
     const ct = contacts[side];
     const flux = {};
@@ -107,7 +107,7 @@ export function makeSolution(solver, result = {}) {
     if (ct.phi.type === 'capacitive' || ct.phi.type === 'pinned') {
       // Charge on the gate (or metal) plate, per area if the device is planar: +D at the left, −D
       // at the right.
-      sol.gates[side] = { V, D, charge: side === 'left' ? D : -D };
+      sol.plates[side] = { V, D, charge: side === 'left' ? D : -D };
     }
   }
   sol.current = sol.contacts.right.current;
@@ -152,6 +152,16 @@ export function makeSolution(solver, result = {}) {
     }
     return out;
   });
+  // A floating terminal passes what its circuit says, exactly (see passedCurrent).
+  if (sol.converged) {
+    for (const k of solver.floating) {
+      const I = solver.passedCurrent(k);
+      if (k === 0) sol.contacts.left.current = I;
+      else if (k === 1) sol.contacts.right.current = -I;
+      else sol.ports[k - 2].current = I;
+    }
+  }
+  sol.current = sol.contacts.right.current;
   sol.terminalVoltage = sol.contacts.right.V - sol.contacts.left.V;
   // Every terminal (the contacts, then the ports by name): its voltage and its current into the
   // device, conduction plus displacement. They sum to zero in steady state.
@@ -303,11 +313,24 @@ export function makeSolution(solver, result = {}) {
   // refined. Flag it where it lowers that capacitance by over 2%. (Where the box is the smaller
   // part, as an ε = 0 metal's against a semiconductor's depletion, it's a fine stand-in for the
   // metal's own screening.)
-  const boxed = (g, h, phi, other, where) => {
+  // And a reaction at the face sees that box's composition, which holding the charge σ shifts
+  // by about z·σ/(Cbox·V_T) for an ion of charge z: a Frumkin effect set by the mesh, which grows
+  // without limit as the box shrinks. Flag it past 1%.
+  const boxed = (g, h, phi, other, where, sigma = 0, reacting = []) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     if (mat.conductor || mat.epsr !== 0 || solver.phiUndefined?.[g]) return;
     const s2 = solver.screening(g), Cbox = (F * F * s2 * h) / (2 * RT);
     if (!(s2 > 0)) return;
+    const ion = reacting.filter((i) => species[i].z !== 0).reduce((a, i) => (a < 0 || Math.abs(species[i].z) > Math.abs(species[a].z) ? i : a), -1);
+    const shift = ion < 0 ? 0 : (Math.abs(species[ion].z * sigma) / Cbox) * (F / RT);
+    if (shift > 0.01) {
+      sol.warnings.push(
+        `${where}: the reaction here sees the strictly neutral cell beside the face (${h.toExponential(2)} m), which holds the face's charge as a diffuse layer that wide: ` +
+          `${species[ion].name} there is shifted by about ${(100 * shift).toPrecision(2)}%, a Frumkin effect set by the mesh that grows as the cell shrinks. ` +
+          `Set the face's zeroCharge near its rest potential (so it holds little charge), coarsen that cell to ${((200 * Math.abs(species[ion].z * sigma)) / (F * s2)).toExponential(1)} m or more, ` +
+          'or resolve the double layer (epsr > 0, hmin below the Debye length).',
+      );
+    }
     let C = phi.C;
     if (phi.type === 'pinned') {
       const om = other < 0 ? null : model.materials[model.regions[grid.nodeRegion[other]].material];
@@ -328,8 +351,10 @@ export function makeSolution(solver, result = {}) {
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
-    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`);
-    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`);
+    const reacting = (side) => itf.reactions.flatMap((rx) => rx.part.filter((p) => p.side === side).map((p) => p.i));
+    const sigma = sol.interfaces[f].D;
+    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`, sigma, reacting(0));
+    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
   if (resolves(contacts.left)) {
@@ -361,6 +386,15 @@ export function makeSolution(solver, result = {}) {
       }
     });
   });
+  // A reaction a steady state needs at equilibrium, left out of it (see stuckReactions).
+  if (sol.steady) {
+    for (const { where, affinity } of solver.stuckReactions()) {
+      sol.warnings.push(
+        `${where}: out of equilibrium by ${(affinity * solver.VT * 1e3).toPrecision(3)} mV of affinity wherever it acts, yet nothing else makes or uses what it changes, so a steady state needs it at equilibrium. ` +
+          'Its rate is too small for the solve to resolve, and it was left where the solve began: this is not a steady state. Raise its rate constant (the steady state does not depend on it), or advance() in time to see how slowly it gets there.',
+      );
+    }
+  }
   // Any other species denser than any material can be (1e6 mol/m³: water is 5.5e4, a metal's
   // atoms ~1.5e5): a level set where the device can't follow it, such as a contact's for one ion
   // far from its neighbours' (Na⁺ held at 1.2e37 mol/m³, whose currents then read 1e28 A/m²).

package/src/solver.js

@@ -491,7 +491,7 @@ export class Solver {
     this.steady = false; // inside a steady solve: sources at the present time, not a step's end
     // The floating ones are extra unknowns, solved with the grid's by bordering (_solveBordered).
     this.floating = this.terms.flatMap((t, k) => (t.drive.kind === 'I' || t.drive.R > 0 ? [k] : []));
-    this.drivenKey = this.terms.map((t) => `${t.drive.kind}${t.drive.R > 0 ? 'R' : ''}`).join();
+    this.drivenKey = this._drivenKey();
     this.lawRefs = new Map(); // what a steady solve keeps behind a terminal at no current (_captureLaws)
     this.chargeRefs = new Map(); // …and the charge a terminal at no current that only charges keeps
     // Per terminal: B = ∂res/∂V (compact column), C = ∂I/∂x (compact row), ∂I/∂V, and for a
@@ -882,6 +882,73 @@ export class Solver {
     // first, so that the first takes that row, and the rest have its multiple taken off.
     const through = (w) => this.carriers.some((k, j) => w[X + j] !== 0);
     const held = new Map(); // (terminal → the combination in place of its circuit row)
+    // Reactions' equilibria first. A face reaction that alone changes some combination (without
+    // it, w would be conserved: Ag⁺ closed in a cell where Ag⁺ + e⁻ = Ag(s) is its one source, or
+    // Ag⁺ + AgNO₃ where it also complexes) has that combination's summed balance rows equal to its
+    // rate, w·ν times it, which a steady state sets to zero. The rate is a poor row: k₀ times a
+    // function of the levels, beside diffusion's terms in the same balances. An Ag⁺/Ag couple
+    // 1e-20 as fast as Fe³⁺/Fe²⁺ on the same platinum was lost to their round-off, the
+    // open-circuit potential settling where silver wasn't (−0.4661 V, the joint equilibrium
+    // −0.5004 V), and 1e-15 to 1e-18 failed. Its affinity says the same at any k₀ (each kinetic
+    // form vanishes only there), so it stands in for one of those rows (see _applyAffinities),
+    // chosen by the same elimination, and a stretch's: never a circuit row.
+    // The slowest first, whose rate rows are the poorest, and each row picked by the reaction's
+    // own terms, never by where its species are listed: the same rows in any listing. (Picked by
+    // listing, an electrode's two couples took different rows with the species reversed, and
+    // Newton converged in one listing and crawled in the other.)
+    this.affinities = [];
+    const faceRx = model.interfaces.flatMap((itf, f) => itf.reactions.map((rx) => ({ f, rx, key: rx.part.map((p) => `${model.species[p.i].name}:${p.side}:${p.nu}`).sort().join() })));
+    faceRx.sort((a, b) => a.rx.k0 - b.rx.k0 || (a.key < b.key ? -1 : a.key > b.key ? 1 : a.f - b.f));
+    for (const { f, rx } of faceRx) {
+      const nu = new Float64Array(S);
+      let inFlat = false;
+      for (const p of rx.part) {
+        const k = this.stretchOf[(f + p.side) * this.n + p.i];
+        if (k < 0 || this.flatStretches.includes(this.stretches[k])) inFlat = true;
+        else nu[k] += p.nu;
+      }
+      if (inFlat) continue; // (held flat at a contact's levels, in equilibrium already)
+      // (Not one fed by a terminal driven by a current: its sum is the rate plus what that
+      // passes. Silver's, e⁻ + Fe²⁺ with the electrons fed, or Ag⁺ + AgNO₃, which nothing is.
+      // A current held at zero passes nothing: an electrode at open circuit feeding a closed
+      // pool of Ag⁺ beside a slow Fe³⁺/Fe²⁺ couple settled 78 mV off, its iron not stationary.)
+      const passes = (k) => !this._noCurrent(this.terms[k]);
+      const fed = (w) => w.some((x, k) => x !== 0 && ((k >= X && passes(this.carriers[k - X])) || (k < S && driven(this.stretches[k]).some(passes))));
+      // Any of the combinations it alone changes will do, with any conserved amount added (whose
+      // summed balance is zero too): one of them needs a row of its own left to take. (Silver's,
+      // e⁻ − Fe³⁺ beside a closed iron couple that had Fe³⁺'s, is e⁻ + Fe²⁺ with the iron added.)
+      const news = this._conservedMoieties(true, [], rx).filter((w) => Math.abs(nu.reduce((t, x, k) => t + x * w[k], 0)) > 1e-9 && !fed(w));
+      const kept = laws.filter((l) => !fed(l));
+      const tries = [...news, ...news.flatMap((w) => kept.flatMap((l) => [1, -1].map((sg) => w.map((x, m) => x + sg * l[m]))))];
+      for (const w of tries) {
+        const v = new Float64Array(S + T);
+        for (let k = 0; k < S; k++) {
+          if (w[k] === 0) continue;
+          const st = this.stretches[k];
+          if (this._moves(st) && !spectators.has(rowOf(k))) v[k] = w[k];
+          if (this.z[st.species] !== 0) for (const t of driven(st)) v[S + t] = w[k] / this.z[st.species];
+        }
+        for (const [col, row] of chosen) {
+          const fc = v[col];
+          if (fc !== 0) for (let j = 0; j < S + T; j++) v[j] -= fc * row[j];
+        }
+        const scale = v.reduce((m, x) => Math.max(m, Math.abs(x)), 0);
+        if (!(scale > 1e-9)) continue;
+        // (Never a metal's carriers, nor a stretch a terminal feeds, even at no current: their rows
+        // carry the terminal's current, and Pt's electrons standing for an iron couple's balance
+        // put the electrode at 602 V.)
+        const ok = (j) => j !== undefined && j >= 0 && j < S && Math.abs(v[j]) > 1e-9 * scale && !conductor(this.stretches[j]) && this.terms.every((_, t) => !this._feeds(t, this.stretches[j]));
+        // (One of its own species first, then weight 1, the largest, and by name.)
+        const own = (k) => rx.part.some((p) => p.i === this.stretches[k].species && this.stretchOf[(f + p.side) * this.n + p.i] === k);
+        const key = (k) => [own(k) ? 0 : 1, Math.abs(v[k]) === 1 ? 0 : 1, -Math.abs(v[k]), model.species[this.stretches[k].species].name, this.stretches[k].regions[0]];
+        const less = (a, b) => { const ka = key(a), kb = key(b); for (let j = 0; j < ka.length; j++) if (ka[j] !== kb[j]) return ka[j] < kb[j]; return false; };
+        const col = [...Array(S).keys()].filter(ok).reduce((b, k) => (b < 0 || less(k, b) ? k : b), -1);
+        if (col < 0) continue;
+        chosen.push([col, v.map((x) => x / v[col])]);
+        this.affinities.push({ rx, f, row: rowOf(col), idx: new Int32Array(rx.part.length), w: new Float64Array(rx.part.length), len: 0, res: 0 });
+        break;
+      }
+    }
     for (let w of [...laws.filter(through), ...laws.filter((w) => !through(w))]) {
       for (const [j, k] of this.carriers.entries()) {
         const c = held.get(k);
@@ -947,7 +1014,7 @@ export class Solver {
     this.pinnedIslands = [];
     this.islandsOn = false; // (newton() turns them on, see there)
     this.pins = [];
-    const used = new Set(this.constraints.map((cs) => cs.row).filter((o) => o >= 0));
+    const used = new Set([...this.constraints.map((cs) => cs.row).filter((o) => o >= 0), ...this.affinities.map((af) => af.row)]);
     for (const st of this.stretches) {
       const i = st.species, [s0, s1] = st.regions;
       if (!st.mobile || conductor(st)) continue;
@@ -1160,7 +1227,7 @@ export class Solver {
   // charges, so a combination weighted by z there is conserved while it passes none: a battery's
   // cathode, its electrons behind an open circuit, keeps its charge. Exact integer data, so plain
   // elimination will do.
-  _conservedMoieties(drives = false, alsoCurrent = []) {
+  _conservedMoieties(drives = false, alsoCurrent = [], skip = null) {
     const { model, n, z } = this, S = this.stretches.length;
     // With `drives`, an electrode port driven by a current whose reactions take its carrier from
     // the electrode has a column of its own, last: what the electrode holds, its charge Q/(zF),
@@ -1169,12 +1236,14 @@ export class Solver {
     const byCurrent = (t, k) => t.drive.kind === 'I' || alsoCurrent.includes(k); // (with `alsoCurrent`, terminals counted as such)
     this.carriers = drives ? this.terms.flatMap((t, k) => (byCurrent(t, k) && k >= 2 && model.ports[k - 2].reactions.length > 0 ? [k] : [])) : [];
     const X = S + this.surfCols.length, C = X + this.carriers.length;
-    const rows = [];
+    // (With `skip`, a reaction left out: the combinations that it alone changes come out too, and
+    // its own rows, over the columns, are handed back as `basis.skipped`.)
+    const rows = [], skipped = [];
     model.interfaces.forEach((itf, f) => {
       for (const rx of itf.reactions) {
         const row = new Float64Array(C);
         for (const p of rx.part) row[this.stretchOf[(f + p.side) * n + p.i]] += p.nu;
-        rows.push(row);
+        (rx === skip ? skipped : rows).push(row);
       }
     });
     // An electrode surface's species are columns too, after the stretches (S + j for surface
@@ -1183,12 +1252,13 @@ export class Solver {
     model.ports.forEach((port, k) => {
       for (const rx of port.reactions) {
         const row = new Float64Array(C); // (the electrode's carrier is outside the device)
+        if (rx === skip) skipped.push(row);
         for (const p of rx.part) {
           if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
           else if (p.side === 2) row[S + this.surfColOf[k] + p.s] += p.nu;
           else if (this.carriers.includes(k + 2)) row[X + this.carriers.indexOf(k + 2)] += p.nu;
         }
-        rows.push(row);
+        if (rx !== skip) rows.push(row);
       }
     });
     model.regions.forEach((reg, q) => {
@@ -1197,7 +1267,7 @@ export class Solver {
         const row = new Float64Array(C);
         for (const p of rx.reactants) row[this.stretchOf[q * n + p.i]] -= p.nu;
         for (const p of rx.products) row[this.stretchOf[q * n + p.i]] += p.nu;
-        rows.push(row);
+        (rx === skip ? skipped : rows).push(row);
       }
     });
     const unit = (k) => {
@@ -1254,6 +1324,7 @@ export class Solver {
       w.own = free; // (its weight is 1 there, and no other vector's is: the row it replaces)
       basis.push(w);
     }
+    basis.skipped = skipped;
     return basis;
   }
 
@@ -1508,12 +1579,67 @@ export class Solver {
     if (this.floating.length !== before.length) this.deltaV = null;
     // A terminal newly driven by a current (or no longer) can close a combination behind it.
     // (and one put behind a resistance, or taken from it, its time steps' reading: see _laws)
-    this.drivenKey = this.terms.map((t) => `${t.drive.kind}${t.drive.R > 0 ? 'R' : ''}`).join();
+    this.drivenKey = this._drivenKey();
     if (this.drivenKey !== driven) this._laws();
     this._refreshSources();
     this.history = [];
   }
 
+  // After a steady solve: each reaction that alone changes some combination nothing else feeds
+  // (see _laws), whose total rate a steady state therefore sets to zero, but whose affinity has one
+  // sign wherever it acts, so that its total can't be zero. Too slow to show, its rate lost to
+  // round-off, it was left where the solve began: a slow complexation 43 mV off, an electrode
+  // port's slow couple at its starting composition, each converged without a word. (A face
+  // reaction stands on its affinity, so it's only caught here if that couldn't be arranged.)
+  stuckReactions() {
+    const { n, M, u, uLo, model } = this, grid = model.grid, S = this.stretches.length, X = S + this.surfCols.length, out = [];
+    const passes = (k) => !this._noCurrent(this.terms[k]);
+    const fed = (w) => w.some((x, k) => x !== 0 && ((k >= X && passes(this.carriers[k - X])) || (k < S && this.terms.some((t, j) => t.drive.kind === 'I' && passes(j) && this._feeds(j, this.stretches[k])))));
+    const needed = (rx) => {
+      const basis = this._conservedMoieties(true, [], rx);
+      return basis.some((w) => !fed(w) && basis.skipped.some((row) => Math.abs(row.reduce((t, x, k) => t + x * w[k], 0)) > 1e-9));
+    };
+    const eta = (g, slot) => u[this.blockOfNode[g] * M + slot] + uLo[this.blockOfNode[g] * M + slot];
+    const report = (where, as) => {
+      if (as.length === 0 || !(as.every((a) => a > 1e-6) || as.every((a) => a < -1e-6))) return;
+      out.push({ where, affinity: as.reduce((m, a) => (Math.abs(a) < Math.abs(m) ? a : m)) });
+    };
+    model.interfaces.forEach((itf, f) => {
+      const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
+      itf.reactions.forEach((rx, q) => {
+        if (this.affinities.some((af) => af.rx === rx) || !needed(rx)) return;
+        report(`interfaces[${f}].reactions[${q}]`, [rx.part.reduce((a, p) => a - p.nu * eta(p.side ? gR : gL, 1 + p.i), rx.fixedA)]);
+      });
+    });
+    model.reactions.forEach((mrx, x) => {
+      const rx = this.rxs[x];
+      if (rx.generation || !needed(mrx)) return;
+      const as = [];
+      for (let g = 0; g < this.nNodes; g++) if (rx.kfNode[g] > 0 || rx.srh?.[this.nodeMaterial[g]]) as.push(rx.sp.reduce((a, i, p) => a + rx.nu[p] * eta(g, 1 + i), rx.fixedA));
+      report(`bulkReactions[${x}]`, as);
+    });
+    model.ports.forEach((port, k) => {
+      port.reactions.forEach((rx, q) => {
+        if (!needed(rx)) return;
+        let aV = rx.fixedA;
+        for (const p of rx.part) if (p.side === 1) aV -= p.nu * this.portEta(port, p.i);
+        report(`ports[${k}].reactions[${q}]`, port.nodes.map((g) => rx.part.reduce((a, p) => (p.side === 1 ? a : a - p.nu * eta(g, p.side === 2 ? 1 + n + p.s : 1 + p.i)), aV)));
+      });
+    });
+    return out;
+  }
+
+  // How each terminal is driven, as far as the laws care (see _laws): by a voltage or a current,
+  // behind a resistance or not, and a current that's held at zero throughout (which feeds a
+  // combination nothing, so a reaction's affinity may stand in for its summed balance).
+  _drivenKey() {
+    return this.terms.map((t) => `${t.drive.kind}${t.drive.R > 0 ? 'R' : ''}${this._noCurrent(t) ? '0' : ''}`).join();
+  }
+
+  _noCurrent(t) {
+    return t.drive.kind === 'I' && !(t.drive.R > 0) && t.drive.src.value === 0;
+  }
+
   // Held terminals take their sources' values at sourceTime (a floating one keeps its voltage,
   // an unknown; one behind a resistance reads its source voltage in _circuit).
   _refreshSources() {
@@ -1779,6 +1905,22 @@ export class Solver {
       });
       if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
     }
+    // A floating port linked to its carrier (no reactions, no double layer: a wire into an
+    // insertion host) starts at that carrier's level across its window, not at 0 V.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      const i = port?.terminal, link = i === null || i === undefined ? null : port.species[i];
+      if (!port || port.reactions.length > 0 || port.capacitance || !link || link.type === 'blocked' || z[i] === 0) continue;
+      let w = 0, sum = 0;
+      port.nodes.forEach((g, j) => {
+        const a = this.model.grid.vol[g] * (this.portArea[t.index]?.[j] ?? 1); // (a window with no area: by volume)
+        w += a;
+        sum += (a * this.VT * u[this.blockOfNode[g] * M + 1 + i]) / z[i];
+      });
+      // (Levels at the start mean something only against a held terminal's, as for a contact.)
+      const held = [0, 1].find((h) => !this.floating.includes(h) && Number.isFinite(level(this.terms[h].side)));
+      if (w > 0 && held !== undefined) this.termV[k] = this.termV[held] + sum / w - (link.offset ?? 0) - level(this.terms[held].side);
+    }
     // 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];
@@ -2031,10 +2173,11 @@ export class Solver {
     // balances, the last two kept aside for _solveBordered.
     const steady = this.steady && dt === Infinity;
     if (steady) this._flatRows();
+    if (steady && this.affinities.length > 0) this._applyAffinities();
     if (steady && this.constraints.length > 0) this._applyConstraints();
     if (steady && this.localConstraints.length > 0) this._applyLocalConstraints();
     this.pinnedIslands = steady && this.islandsOn ? this._applyIslands() : [];
-    this.pins = steady ? [...this.constraints.filter((cs) => cs.circuit < 0), ...this.pinnedIslands] : [];
+    this.pins = steady ? [...this.constraints.filter((cs) => cs.circuit < 0), ...this.affinities, ...this.pinnedIslands] : [];
     this.transformed = this.combining && dt !== Infinity;
     if (this.transformed) this._chargeRows(dt);
   }
@@ -3274,6 +3417,31 @@ export class Solver {
     }
   }
 
+  // Steady solves: each reaction that alone changes a combination (see _laws) held at its
+  // equilibrium, a = fixedA − Σ ν η = 0, in place of one of that combination's balance rows (a pin,
+  // like an amount's).
+  _applyAffinities() {
+    const { M, u, uLo, res } = this, grid = this.model.grid;
+    for (const af of this.affinities) {
+      const b0 = Math.floor(af.row / M), r0 = af.row % M;
+      this._replaceRow(b0, r0);
+      this._j(b0, r0, b0, r0, 1);
+      res[this.rix[af.row]] = 0;
+      const gL = grid.regionEnd[af.f], gR = grid.regionStart[af.f + 1];
+      let hi = af.rx.fixedA, lo = 0, len = 0;
+      for (const p of af.rx.part) {
+        const o = this.blockOfNode[p.side ? gR : gL] * M + 1 + p.i;
+        hi -= p.nu * u[o];
+        lo -= p.nu * uLo[o];
+        if (this.loc[o] < 0) continue;
+        af.idx[len] = this.rix[o];
+        af.w[len++] = -p.nu;
+      }
+      af.len = len;
+      af.res = hi + lo;
+    }
+  }
+
   // Zero one row of the Jacobian (all three blocks), ready to be replaced.
   _replaceRow(b, rs) {
     const l = this.loc[b * this.M + rs];
@@ -3411,8 +3579,13 @@ export class Solver {
       // stops refining.
       const x0 = Float64Array.from(x);
       const ok = gmresReal(op, pb, x, { m: 8, restarts: 1, tol: 1e-8 });
-      let c = 0;
-      for (let j = 0; j < N + K; j++) c = Math.max(c, Math.abs(x[j] - x0[j]));
+      // (Measured on the potentials, as Newton's own step is: a rate the plain solve left
+      // unsolved, at a perturbed pivot, can need a correction of 41.7 mol/(m²·s).)
+      const dx = new Float64Array(N + 1), dV = new Float64Array(K);
+      for (let j = 0; j < N; j++) dx[j] = x[j] - x0[j];
+      for (let a = 0; a < K; a++) dV[a] = x[N + a] - x0[N + a];
+      if (this.transformed) this._untransform(dx);
+      const c = this._maxPotentialStep(dx, dV);
       if (!ok || !(c < 1)) return false;
       for (let j = 0; j < N; j++) delta[j] = x[j];
       for (let a = 0; a < K; a++) deltaV[a] = x[N + a];
@@ -3464,7 +3637,19 @@ export class Solver {
     // A/m² of noise), their rows can throw Newton off instead: if it doesn't converge again
     // within a dozen iterations, the plain solution stands.
     this.islandsOn = islands;
-    let rounds = 0, kept = null;
+    let rounds = 0, kept = null, perturbed = false;
+    // Converged by a small update, but solved at a perturbed pivot, or in a steady solve (where a
+    // factorisation that lost a row's digits left a reaction's rate 3.6e7 off it, the update
+    // small, an I = 0 electrode at a voltage 0.4 V from its steady one): the residual itself,
+    // assembled at the state, must be small too (each row scaled by its largest Jacobian entry).
+    const unsolved = () => {
+      if (!perturbed && dt !== Infinity) return false;
+      this.assemble(dt);
+      this._equilibrate();
+      let r = 0;
+      for (let k = 0; k < this.SINK; k++) r = Math.max(r, Math.abs(this.res[k]));
+      return !(r < 1e-6);
+    };
     const islandsOff = (it, result) => {
       if (dt !== Infinity || !this.steady || this.islands.length === 0 || rounds >= 2 || !(this._kirchhoff() > 1e-9)) return false;
       this.islandsOn = true;
@@ -3509,6 +3694,13 @@ export class Solver {
       } catch (err) {
         return fail({ converged: false, iterations: it, history, error: err.message });
       }
+      // A pivot perturbed (one that cancelled to exactly nothing) can leave a row unsolved, its
+      // update small while its residual isn't: the same couple written twice on an electrode at
+      // open circuit converged with one spelling's rate row 41.7 mol/(m²·s) off, the couple
+      // 1.5 RT from equilibrium. Refine the solves (exact J·v) wherever one was, and before
+      // taking a small update for convergence there, look at the residual itself (see unsolved).
+      perturbed = this.sys.perturbedPivots > 0;
+      if (perturbed && !noRefine) refine = true;
       try {
         const pins = this.pins;
         deltaV.fill(0);
@@ -3547,6 +3739,7 @@ export class Solver {
       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)) {
+        if (unsolved()) return fail({ converged: false, iterations: it, history, error: 'a row left unsolved at a pivot that cancelled exactly' });
         const done = { converged: true, iterations: it, history, residual: rmax };
         if (islandsOff(it, done)) continue;
         this.computeConcentrations();
@@ -3567,6 +3760,7 @@ export class Solver {
       if (refine) refined++;
       else if (!noRefine && alpha === 1 && it >= 3 && step > 0.25 * p1 && (step < 1e-4 || (step > p1 && p1 > p2))) refine = true;
       if (alpha === 1 && it >= 4 && (!refine || refined >= 1 || noRefine) && step < floor && p1 < floor && step > 0.25 * p1 && p1 > 0.25 * p2) {
+        if (unsolved()) return fail({ converged: false, iterations: it, history, error: 'a row left unsolved at a pivot that cancelled exactly' });
         const done = { converged: true, iterations: it, history, residual: rmax, roundoff: true };
         if (islandsOff(it, done)) continue;
         this.computeConcentrations();
@@ -3676,11 +3870,7 @@ export class Solver {
       this.portQEnd = Float64Array.from(this.portQ);
     }
     const DN = { ...this.contactDEnd }, QN = Float64Array.from(this.portQEnd);
-    if (opts.guess) {
-      // Start Newton from a predicted state (e.g. extrapolated from the history).
-      this.u.set(opts.guess);
-      this.uLo.fill(0);
-    }
+    if (opts.guess) this._guess(opts.guess); // start Newton from a predicted state
     let dtEff = dt;
     if (bdf) {
       const a0 = (1 + 2 * w) / (1 + w), b1 = (1 + w) / a0, b2 = (w * w) / (1 + w) / a0;
@@ -3717,10 +3907,7 @@ export class Solver {
         this.u.set(this.uPrev);
         this.uLo.set(this.uPrevLo);
         this.termV.set(this.termVPrev);
-        if (opts.guess) {
-          this.u.set(opts.guess);
-          this.uLo.fill(0);
-        }
+        if (opts.guess) this._guess(opts.guess);
         const again = this.newton(dtEff, { ...opts, islands: true });
         result = { ...again, iterations: result.iterations + again.iterations };
       }
@@ -3730,10 +3917,7 @@ export class Solver {
         this.u.set(this.uPrev);
         this.uLo.set(this.uPrevLo);
         this.termV.set(this.termVPrev);
-        if (opts.guess) {
-          this.u.set(opts.guess);
-          this.uLo.fill(0);
-        }
+        if (opts.guess) this._guess(opts.guess);
         for (const cs of this.lawForm.keys()) this.lawForm.set(cs, true);
         const again = this.newton(dtEff, opts);
         result = { ...again, iterations: result.iterations + again.iterations };
@@ -3766,6 +3950,19 @@ export class Solver {
     return result;
   }
 
+  // Newton's unknowns set to a guess (e.g. extrapolated from the history). Only its unknowns: the
+  // other slots never change (see _activeSlots), and among them is a gauge, an insertion host's
+  // φ̂, that nothing pulls back. Extrapolated through steps that grow, it wandered off
+  // geometrically, 147 to 8000 thermal units in a battery's first 100 s and 1e11 by 1e5 s, where
+  // its species' levels (η − zφ̂, summed back by the host's statistics) lost their digits to it.
+  _guess(guess) {
+    const { u, uLo } = this;
+    for (const k of this.fullOf) {
+      u[k] = guess[k];
+      uLo[k] = 0;
+    }
+  }
+
   /**
    * Adaptive time stepping to tEnd: variable-step BDF2 (or backward Euler), with the local error
    * estimated against an explicit predictor through the previous states, and controlled to
@@ -3786,8 +3983,13 @@ export class Solver {
     const trace = { t: [], current: [], voltage: [], ...(sample ? { probes: sample.out } : {}) };
     let steps = 0, rejected = 0, iterations = 0, failed = false;
     // Already there (an animation frame with no time to add): nothing to do, and the step size
-    // carried to the next call stays as it was.
-    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace };
+    // carried to the next call stays as it was. A time already passed, or reached again outside
+    // an animation, is most likely advance(dt) read as a duration: say so.
+    if (!(tEnd > this.time)) {
+      const relative = tEnd < this.time || (this.time > 0 && opts.budgetMs === undefined);
+      return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace, ...(relative ? { stopped: `advance(${tEnd}) did nothing: ${absolute}. To run for a further dt, advance(sol.time + dt)` } : {}) };
+    }
+    const t0 = this.time;
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
     // The shortest step worth trying: round-off relative to the time, or the device's fastest
@@ -3800,8 +4002,10 @@ export class Solver {
       if (steps + rejected >= maxSteps || clock() - start > budgetMs) break;
       // Within round-off of the end (a target a hair past a breakpoint just landed on, say):
       // snap to it rather than attempt a step of ~1e-13 s, which can't be resolved and, in a
-      // strictly neutral device, fails outright.
-      if (tEnd - this.time <= 1e-10 * Math.abs(tEnd)) {
+      // strictly neutral device, fails outright. Round-off of the time and negligible beside the
+      // interval asked for: by the time alone, a GITT pulse of 0.01 s at t = 1e9 s was skipped
+      // whole (the time moved, nothing else did), and from 1e10 s 17% of a pulse train's charge.
+      if (tEnd - this.time <= 1e-10 * Math.abs(tEnd) && tEnd - this.time <= 1e-9 * (tEnd - t0)) {
         this.time = tEnd;
         break;
       }
@@ -3895,7 +4099,10 @@ export class Solver {
     // 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.`;
+    // (What usually does it, most likely first. Round 11's agents read the old list, which led
+    // with a drive's jump, as blaming a modest current pulse: a host emptied at its surface, and
+    // an electrode at open circuit with no double layer, held only by a slow reaction.)
+    if (failed) stopped = `${at}: a step did not converge even when shortened to ${dt.toExponential(1)} s. Look for: a host or surface driven to its limit (emptied or filled at its surface by a current it can no longer pass); an electrode at open circuit held only by a slow reaction, with no double-layer capacitance to keep its level (give its face one: phi capacitive); a drive's jump too big for one step (ramp it); a driven current the device cannot 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 } : {}) };
   }
@@ -4113,8 +4320,19 @@ export class Solver {
     this.computeConcentrations();
   }
 
+  // What a floating terminal k passes into the device, which its circuit row holds exactly once
+  // converged: the current it's driven by, or (V_source − V)/R behind a resistance (the source
+  // as the last step saw it, before any jump at its end). Read as a flux through a metal instead,
+  // it carried that flux's round-off, G Δη with G huge: a gate behind R read 1.5e-4 off wherever
+  // Newton stopped an update early, and below ~1e-16 A/m², nothing but noise.
+  passedCurrent(k) {
+    const d = this.terms[k].drive, src = sourceAt(d.src, this.time, !this.atSteady);
+    return d.kind === 'I' ? src : (src - this.termV[k]) / d.R;
+  }
+
   // Terminal current toward +x at the right contact, from the last assembly at this state.
   _terminalCurrent() {
+    if (this.floating.includes(1)) return -this.passedCurrent(1);
     let I = 0;
     for (let i = 0; i < this.n; i++) I += FARADAY * this.z[i] * this.contactFlux.right[i];
     const dt = this.lastDt;

package/src/sources.js

@@ -1,7 +1,7 @@
 // driftlet/kit: sources as plain definition data. Waveforms for a terminal's V or I, an injector
 // port, and band-to-band recombination from a lifetime. Each returns an ordinary spec value.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -19,6 +19,7 @@ const num = (v) => typeof v === 'number' && Number.isFinite(v);
  * @returns {{ t: number[], values: number[] }}
  */
 export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {}) {
+  checkOptions('pulse', arguments[0], ['start', 'width', 'amplitude', 'rise', 'base']);
   need(num(width) && width > 0, `pulse: width must be > 0 (s), got ${width}`);
   need(num(amplitude), `pulse: amplitude must be a finite number (V or A/m²), got ${amplitude}`);
   need(num(start) && start >= 0, `pulse: start must be ≥ 0 (s), got ${start}`);
@@ -35,6 +36,7 @@ export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {})
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function square({ high, low, period, duty = 0.5 } = {}) {
+  checkOptions('square', arguments[0], ['high', 'low', 'period', 'duty']);
   need(num(high) && num(low), `square: high and low must be finite numbers, got ${high} and ${low}`);
   need(num(period) && period > 0, `square: period must be > 0 (s), got ${period}`);
   need(num(duty) && duty > 0 && duty < 1, `square: duty must be between 0 and 1, got ${duty}`);
@@ -49,6 +51,7 @@ export function square({ high, low, period, duty = 0.5 } = {}) {
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function triangle({ from, to, period } = {}) {
+  checkOptions('triangle', arguments[0], ['from', 'to', 'period']);
   need(num(from) && num(to), `triangle: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(period) && period > 0, `triangle: period must be > 0 (s), got ${period}`);
   return { t: [0, period / 2, period], values: [from, to, from], repeat: true };
@@ -60,6 +63,7 @@ export function triangle({ from, to, period } = {}) {
  * @returns {{ t: number[], values: number[] }}
  */
 export function ramp({ from, to, duration, start = 0 } = {}) {
+  checkOptions('ramp', arguments[0], ['from', 'to', 'duration', 'start']);
   need(num(from) && num(to), `ramp: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(duration) && duration > 0, `ramp: duration must be > 0 (s), got ${duration}`);
   need(num(start) && start >= 0, `ramp: start must be ≥ 0 (s), got ${start}`);
@@ -78,6 +82,7 @@ export function ramp({ from, to, duration, start = 0 } = {}) {
  * @returns {object} a port, for the definition's `ports`
  */
 export function injector({ name = 'injector', region, from, to, species, I, headroom = 2.5 } = {}) {
+  checkOptions('injector', arguments[0], ['name', 'region', 'from', 'to', 'species', 'I', 'headroom']);
   need(region !== undefined, 'injector: give the region (its name or index)');
   need(num(from) && num(to) && to > from, `injector: from and to must bound the window, in m from the region's left end (got ${from}, ${to})`);
   need(typeof species === 'string', 'injector: give the species it injects, e.g. species: \'h+\'');
@@ -96,6 +101,7 @@ export function injector({ name = 'injector', region, from, to, species, I, head
  * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
  */
 export function recombination({ material, tau, majority } = {}) {
+  checkOptions('recombination', arguments[0], ['material', 'tau', 'majority']);
   need(typeof material === 'string', 'recombination: give the material, by name');
   need(num(tau) && tau > 0, `recombination: tau must be > 0 (s), got ${tau}`);
   need(num(majority) && majority > 0, `recombination: majority must be the majority carrier density > 0 (mol/m³; units.perCm3 converts), got ${majority}`);
@@ -117,6 +123,7 @@ export function recombination({ material, tau, majority } = {}) {
  * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
  */
 export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes = 'e- + h+' } = {}) {
+  checkOptions('photogeneration', arguments[0], ['material', 'flux', 'alpha', 'mu', 'from', 'to', 'makes']);
   need(typeof material === 'string', 'photogeneration: give the material, by name');
   need(num(flux) && flux >= 0, `photogeneration: flux must be the photon flux ≥ 0 entering the material (mol/(m²·s)), got ${flux}`);
   need(num(alpha) && alpha > 0, `photogeneration: alpha must be the absorption coefficient > 0 (1/m; 1/cm × 100), got ${alpha}`);