driftlet 1.3.0 → 1.3.3

package/src/impedance.js

@@ -22,33 +22,44 @@
 //   → { f, Z: { re, im }, relError, profiles? }, Z in Ω·m² (Ω for a non-planar device) at each
 //   frequency.
 //   Throws a SolverError where the terminal doesn't exist, has a series resistance, or every
-//   other terminal is driven by a current (no return path: Z infinite), or where a frequency
-//   isn't positive and finite.
+//   other terminal is driven by a current (no return path: Z infinite), where a frequency
+//   isn't positive and finite, or where the linearised system is singular at one.
 //   Linearised about the present state: (J + iωS)·δx + Σ_k B_k δV_k = 0 for the grid's rows and,
 //   for each floating terminal k (driven by a current), (C_k + iωC′_k)·δx + (DI_k + iωDI′_k) δV_k
 //   + Σ_k2 (DX + iωDX′)_k,k2 δV_k2 = δI_k, with J the steady Jacobian (dt = ∞) and S, C′, DI′,
-//   DX′ the storage parts, (X(dt) − X(∞))·dt at dt = 1e-30. A floating terminal that alone feeds
+//   DX′ the storage parts, (X(dt) − X(∞))·dt at dt = 1e-30. The measured terminal is always
+//   excited by its voltage: driven by a current, it's measured as if held (δV = 1, Z = 1/δI, the
+//   same input impedance), its circuit row out of the small system, its current read as a held
+//   one's (with its circuit law's change where it has one); its profiles then scaled by Z, per
+//   unit current. A floating terminal that alone feeds
 //   a conserved combination (a circuit law: a constraint or time law with its circuit row) has
 //   its current read by that combination's change at every frequency, iω F δS/λ plus what a
-//   resistance passes: at dt = 1e-30 every circuit law reads by the change (this.lawForm), and
-//   its steady parts are C = 0, DI = 1/R (0 driven by a current), DX = 0. The measured terminal: held at a
-//   voltage, δV = 1 and Z = 1/δI, δI its current into the device; driven by a current, δI = 1
-//   and Z = δV. Every other terminal keeps its drive: held, δV = 0 (AC ground); driven, δI = 0
-//   (AC open).
+//   resistance passes: at dt = 1e-30 every circuit law with a current to count (λ set) reads by
+//   the change (this.lawForm), and
+//   its steady parts are C = 0, DI = 1/R (0 driven by a current), DX = 0. δI is the measured
+//   terminal's current into the device. Every other terminal keeps its drive: held, δV = 0 (AC
+//   ground); driven, δI = 0 (AC open).
 //   Each frequency: J + iωS with each row divided by its largest entry, factorised, preconditions
 //   GMRES (m 12, 8 restarts, tol 1e-8; its best iterate kept) on the exact J·v (difference form).
-//   Solved: y, the response with the floating terminals held (to the measured one's δV, or none),
+//   A floating contact otherwise reads its current, in its circuit row, at the reading of least
+//   error by the solved responses (its own, or any cut between it and a port's window: the same
+//   current); and where every other terminal floats, a reading with no direct V dependence (a
+//   cut's, a law's change) reads y as Σ X_b, every terminal's uniform shift passing nothing.
+//   Solved: y, the response with the floating terminals held (to the measured one's δV = 1),
 //   and X_k, to each floating terminal's unit δV_k; then the floating terminals' rows, a small
 //   complex system, for their δV; δx = y − Σ X_k δV_k.
 //   The current read (held terminal): DI + iωDI′ + Σ (DX + iωDX′) δV + (C + iωC′)·δx, its error
-//   estimated from its terms' round-off and the solves' residuals; for a contact, also across
+//   estimated from its terms' round-off, the solves' residuals, and each unknown's round-off in
+//   its own row, ε Σ_k |A_jk x_k| / |A_jj| (a metal's current unknown, G Δη to a huge G: a
+//   bound, cautious where the coupled system pins it better); for a contact, also across
 //   each cut (_currentCuts: a segment's linearised total current, conduction and displacement,
 //   between that contact and the nearest port's window where there are ports), the reading with
 //   the least error taken; and where every other terminal floats, by Kirchhoff, Σ δV_k/R_k over
 //   those behind a resistance, its error (ε + the solves' residual)·|δV_k|/R_k. With no floating
 //   terminal, cuts, and that error over 1% of the current:
 //   the response split into each region's uniform shift (_regionShift) and a remainder solved to
-//   GMRES's floor, the shift's effect taken only at the rows it can touch (_regionEdgeRows), and
+//   GMRES's floor, the shift's effect taken only at the rows it can touch (_regionEdgeRows; a
+//   metal's carriers shifted, its current unknown not), and
 //   that reading kept where its error is less.
 //   relError: per frequency, the chosen reading's error estimate over |δI| (held); driven, the
 //   same estimate of its unit current read back from δx. Cautious: it can exceed the true error
@@ -75,8 +86,7 @@
 // Also written, left as the last assembly at dt = ∞ left them: this.sourceTime (the present
 // time), cOld, thOld, th0Old, gateOld (the present state's), contactDStart, portQStart, the
 // residual, the Jacobian and the terminal terms, sysRest and the concentrations; this.lawForm
-// (every circuit law by the change, until a step sets it afresh). _regionShift treats every
-// node's slot 0 as φ̂, a metal's flux unknown too: harmless while a metal region is one cell.
+// (every circuit law by the change, until a step sets it afresh).
 // Tests: test/impedance.test.js (Macdonald's blocking electrodes, a junction's depletion
 // capacitance, a MOS capacitor at both terminals, ports, profiles, Fermi–Dirac against
 // Boltzmann); the demos' EIS.
@@ -218,8 +228,8 @@ export class SmallSignal {
    * gives (J + iωM)·δx + Σ B_k δV_k = rhs for the grid's rows, and (C_k + iωC′_k)·δx +
    * (∂I_k/∂V_k)·δV_k = δI_set,k for each floating terminal's circuit row, with J the steady
    * Jacobian and M the storage part (from J(dt) = J + M/dt), B_k = ∂res/∂V_k and C_k = ∂I_k/∂x.
-   * At the measured terminal, a held voltage is perturbed (rhs = −B δV) and its current read
-   * from C, or a driven current is perturbed and its voltage solved for. The other terminals
+   * At the measured terminal, its voltage is perturbed (rhs = −B δV) and its current read, held
+   * or driven by a current alike (one input impedance; see the contract). The other terminals
    * keep their drives: held ones at AC ground, driven ones at AC open circuit.
    * Z = δV/δI with I into the device (positive real part for a passive device).
    * @param {ArrayLike<number>} frequencies Hz
@@ -249,8 +259,14 @@ export class SmallSignal {
           `its impedance is infinite. Measure at one of those instead (impedance(f, { terminal: '${others[0].name}' }), its voltage against '${terminal}'), or hold one of them at a voltage`,
       );
     }
-    const N = nB * M, fl = this.floating, K = fl.length;
-    const kirchhoff = dT.kind === 'V' && others.every((t) => t.drive.kind === 'I' || t.drive.R > 0);
+    // Z is the device's input impedance at kT, the same whether its voltage is perturbed and its
+    // current read or the other way round. A terminal driven by a current is measured as if held
+    // (δV = 1, Z = 1/δI) to read that current as a held one's is (cuts, Kirchhoff, a circuit law's
+    // change): read through its own circuit row instead, at its contact alone, it was a metal's or
+    // a barrier's round-off (a reverse-biased diode's contact 4.3% off dV/dI; a Schottky
+    // contact's Re Z −32 for 1282), with an error estimate that never saw it.
+    const N = nB * M, fl = this.floating.filter((k) => k !== kT), K = fl.length;
+    const kirchhoff = others.every((t) => t.drive.kind === 'I' || t.drive.R > 0);
     this.sourceTime = this.time;
     this.computeConcentrations();
     this.cOld.set(this.c);
@@ -271,11 +287,14 @@ export class SmallSignal {
     // flux at dt = ∞ and by the change at dt = 1e-30, a floating gate's current was counted
     // twice (its capacitance 2× dQ/dV); read by the flux throughout, through a metal it is the
     // round-off of G Δη (a gate behind 1 kΩ·m², measured at the back contact: Re Z = −2.7).
-    this.lawForm = new Map([...this.constraints, ...this.timeLaws].map((cs) => [cs, true]));
+    // (A law that counts no current, λ unset, as for a terminal at no current that feeds
+    // nothing, can't be read by its change: forced to, a closed Fe³⁺/Fe²⁺ cell's Z was NaN.)
+    const byChange = (cs) => cs.circuit >= 0 && !(cs.contacts?.length > 0) && Number.isFinite(cs.lambda) && cs.lambda !== 0;
+    this.lawForm = new Map([...this.constraints, ...this.timeLaws].map((cs) => [cs, byChange(cs)]));
     this.assemble(dts);
     for (const cs of [...this.constraints, ...this.timeLaws]) {
       const k = cs.circuit;
-      if (k < 0 || !fl.includes(k) || cs.contacts?.length > 0) continue;
+      if (!byChange(cs) || !(fl.includes(k) || (k === kT && dT.kind === 'I'))) continue;
       Ct[k].fill(0);
       DI[k] = this.terms[k].drive.R > 0 ? 1 / this.terms[k].drive.R : 0;
       DX[k].fill(0);
@@ -288,11 +307,31 @@ export class SmallSignal {
     // 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));
+    const allCuts = this._currentCuts(), windows = this.model.ports.flatMap((p) => Array.from(p.nodes));
+    const lo = windows.length ? Math.min(...windows) : Infinity, hi = windows.length ? Math.max(...windows) : -Infinity;
+    const cutsOf = (k) => allCuts.filter((cut) => (k === 0 ? cut.s + 1 <= lo : cut.s >= hi));
+    const cuts = kT < 2 ? cutsOf(kT) : null;
+    // A floating contact on a metal: its circuit row's current through the metal is the current
+    // unknown G Δη, round-off to a huge G (a Pt electrode behind 3000 Ω·m², read at the bath: Z −
+    // R came out 70.5 for 3070.5). Any cut between it and a port's window carries the same current
+    // (a metal stores none; the total current is continuous through its face), so each frequency
+    // reads it where its error, by the solved responses, is least (see readings, below).
+    const lawRead = new Set([...this.constraints, ...this.timeLaws].filter(byChange).map((cs) => cs.circuit));
+    const choices = new Map(); // k → [{ c, cs, di, dis, dx, dxs }]: its own reading, then each cut's
+    for (const k of fl) {
+      if (k > 1 || lawRead.has(k)) continue;
+      const own = { c: Ct[k].slice(), cs: Cs[k].slice(), di: DI[k], dis: DIs[k], dx: DX[k].slice(), dxs: DXs[k].slice() }, list = [own];
+      const sgn = k === 0 ? 1 : -1, R = this.terms[k].drive.R;
+      for (const cut of cutsOf(k)) {
+        const c = new Float64Array(own.c.length), cs = new Float64Array(own.c.length);
+        cut.idx.forEach((x, a) => {
+          if (this.rix[x] >= this.sys.size) return;
+          c[this.rix[x]] += sgn * cut.g[a];
+          cs[this.rix[x]] += sgn * cut.d[a];
+        });
+        list.push({ c, cs, di: R > 0 ? 1 / R : 0, dis: 0, dx: new Float64Array(own.dx.length), dxs: new Float64Array(own.dx.length) });
+      }
+      if (list.length > 1) choices.set(k, list);
     }
     // 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
@@ -348,7 +387,12 @@ export class SmallSignal {
           }
         }
       }
-      csys.factor();
+      try {
+        csys.factor();
+      } catch (err) {
+        // (it threw a bare Error, its block number all it said: a cell 2.8 V off its pzc)
+        throw new SolverError(`impedance: the linearised equations are singular at ${f} Hz (${err.message}): some part of the device is held by nothing at that frequency, as a double layer far from where it balances can leave it. See the steady state's warnings (solve()).`);
+      }
       const sx = (X, vr, out) => {
         for (let blk = 0; blk < nB; blk++) {
           const m = sizes[blk], mp = blk > 0 ? sizes[blk - 1] : 0, mn = blk < nB - 1 ? sizes[blk + 1] : 0;
@@ -404,24 +448,77 @@ export class SmallSignal {
       };
       let accuracy = 1e-14; // (relative, of the solves: the readouts' error is weighed with it)
       // y: the response with the floating terminals held; X_k: to a unit δV_k.
-      const heldT = dT.kind === 'V';
       for (let j = 0; j < Nc; j++) {
-        rr[j] = heldT ? -Bt[kT][j] * scale[j] : 0;
+        rr[j] = -Bt[kT][j] * scale[j];
         ri[j] = 0;
       }
-      solve(rr, ri, yr, yi, heldT ? kT : -1, heldT ? 1 : 0);
+      solve(rr, ri, yr, yi, kT, 1);
       fl.forEach((k, a) => {
         for (let j = 0; j < Nc; j++) rr[j] = Bt[k][j] * scale[j];
         ri.fill(0);
         solve(rr, ri, Xr[a], Xi[a], k, -1);
       });
+      // Each unknown's round-off in its own row: |x_j| to ε Σ_k |A_jk x_k| / |A_jj|, A = J + iωS. A
+      // metal's current unknown, G Δη to a huge G, is known only to ε G |δη| this way, which the
+      // terms' round-off alone never saw (a platinum electrode's current read 20% off at 1 nHz,
+      // its estimate 1e-8).
+      const rowFloor = (xr0, xi0) => {
+        const out = new Float64Array(Nc);
+        for (let blk = 0; blk < nB; blk++) {
+          const m = sizes[blk], mp = blk > 0 ? sizes[blk - 1] : 0, mn = blk < nB - 1 ? sizes[blk + 1] : 0;
+          for (let r = 0; r < m; r++) {
+            let acc = 0;
+            const row = (X, o, len, x0) => {
+              for (let cc = 0; cc < len; cc++) acc += (Math.abs(J[X][o + cc]) + w * Math.abs(S[X][o + cc])) * Math.hypot(xr0[x0 + cc], xi0[x0 + cc]);
+            };
+            if (mp) row('A', offA[blk] + r * mp, mp, offX[blk - 1]);
+            row('B', offB[blk] + r * m, m, offX[blk]);
+            if (mn) row('C', offC[blk] + r * mn, mn, offX[blk + 1]);
+            const dIdx = offB[blk] + r * m + r, diag = Math.hypot(J.B[dIdx], w * S.B[dIdx]);
+            out[offX[blk] + r] = diag > 0 ? (1.1e-16 * acc) / diag : 0;
+          }
+        }
+        return out;
+      };
+      // Each floating metal contact's reading, of those it can take, with the least error by the
+      // solved responses (their terms' round-off and each unknown's in its own row).
+      const gaugeRead = new Set(lawRead); // (readings with no direct dependence on any V: see y below)
+      if (choices.size) {
+        const eps = 1.1e-16, parts = [[yr, yi], ...fl.map((_, b) => [Xr[b], Xi[b]])];
+        const mag = new Float64Array(Nc), floor = new Float64Array(Nc);
+        for (const [pr, pi] of parts) {
+          const rf = rowFloor(pr, pi);
+          for (let j = 0; j < Nc; j++) {
+            mag[j] += Math.hypot(pr[j], pi[j]);
+            floor[j] += rf[j];
+          }
+        }
+        for (const [k, list] of choices) {
+          let best = null, least = Infinity;
+          for (const r of list) {
+            let e = eps * (Math.abs(r.di) + w * Math.abs(r.dis));
+            for (let j = 0; j < Nc; j++) e += (Math.abs(r.c[j]) + w * Math.abs(r.cs[j])) * (eps * mag[j] + floor[j]);
+            if (e < least) [best, least] = [r, e];
+          }
+          if (best !== list[0]) gaugeRead.add(k);
+          Ct[k].set(best.c);
+          Cs[k].set(best.cs);
+          DI[k] = best.di;
+          DIs[k] = best.dis;
+          DX[k].set(best.dx);
+          DXs[k].set(best.dxs);
+        }
+      }
       // The floating terminals' circuit rows, a small complex system for their δV.
       const Ar = Array.from({ length: K }, () => new Float64Array(K + 1)), Ai = Array.from({ length: K }, () => new Float64Array(K + 1));
       fl.forEach((k, a) => {
+        let sre = 0, sim = 0;
         for (let b = 0; b < K; b++) {
           const [re, im] = dot(k, w, Xr[b], Xi[b]);
           Ar[a][b] = -re;
           Ai[a][b] = -im;
+          sre += re;
+          sim += im;
         }
         Ar[a][a] += DI[k];
         Ai[a][a] += w * DIs[k];
@@ -432,9 +529,14 @@ export class SmallSignal {
           Ar[a][b] += DX[k][k2];
           Ai[a][b] += w * DXs[k][k2];
         });
-        const [yre, yim] = dot(k, w, yr, yi);
-        Ar[a][K] = (k === kT ? 1 : 0) - yre - (heldT ? DX[k][kT] : 0);
-        Ai[a][K] = -yim - (heldT ? w * DXs[k][kT] : 0);
+        // Every terminal shifted alike moves nothing and passes no current, and y + Σ (−X_b) is
+        // that shift where kT and the floating terminals are all there are: so a reading with
+        // no direct dependence on a V reads y as Σ X_b, exactly, from responses it resolves, where
+        // y itself is nearly that shift and its current a difference of them (a Pt electrode
+        // behind 3000 Ω·m², at 1 nHz: its cuts read y 10% apart).
+        const [yre, yim] = kirchhoff && gaugeRead.has(k) ? [sre, sim] : dot(k, w, yr, yi);
+        Ar[a][K] = -yre - DX[k][kT];
+        Ai[a][K] = -yim - w * DXs[k][kT];
       });
       const dV = complexSolve(Ar, Ai, K);
       // δx = y − Σ X_k δV_k
@@ -475,7 +577,8 @@ export class SmallSignal {
           const [re, im] = dot(kT, w, p.r, p.i);
           Ir += re;
           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);
+          p.rf ??= rowFloor(p.r, p.i);
+          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 + p.rf[j]);
         }
         // Kirchhoff, where every other terminal floats: what they pass comes back through kT,
         // δI = Σ δV_k/R_k over those behind a resistance (one driven by a current passes no small
@@ -503,7 +606,7 @@ export class SmallSignal {
               // (g + iωd)(xr + i xi)
               re += gk * p.fr[x] - dk * p.fi[x];
               im += gk * p.fi[x] + dk * p.fr[x];
-              e += (Math.abs(gk) + Math.abs(dk)) * (eps * Math.hypot(p.fr[x], p.fi[x]) + p.floor);
+              e += (Math.abs(gk) + Math.abs(dk)) * (eps * Math.hypot(p.fr[x], p.fi[x]) + p.floor + (this.rix[x] < Nc ? p.rf[this.rix[x]] : 0));
             }
           }
           if (e < err) [err, Ir, Ii] = [e, sgn * re, sgn * im];
@@ -524,7 +627,7 @@ export class SmallSignal {
         return [fr, fi];
       };
       let Zr, Zi;
-      if (heldT) {
+      {
         // δI per volt: (C + iωC′)·δx + (∂I/∂V)(1 + iω′) at the terminal…
         let { Ir, Ii, err } = read([{ r: yr, i: yi, fr: xr, fi: xi, floor: accuracy * largest(yr, yi) }]);
         // …and where the solves leave that unresolved (the estimate past 1% of the current), the
@@ -565,14 +668,10 @@ export class SmallSignal {
         const d2 = Ir * Ir + Ii * Ii; // Z = 1/δI
         Zr = Ir / d2;
         Zi = -Ii / d2;
-      } else {
-        // δV per unit current; its error as the unit current's, read back from δx, is uncertain
-        // (round-off in the current's terms, and the solves' residuals: see read)
-        const a = fl.indexOf(kT);
-        Zr = dV.re[a];
-        Zi = dV.im[a];
-        const back = read([{ r: yr, i: yi, fr: xr, fi: xi, floor: accuracy * largest(yr, yi) }], [Zr, Zi]);
-        out.relError[q] = back.err / Math.hypot(back.Ir, back.Ii);
+      }
+      // (profiles per unit excitation: for a terminal driven by a current, per A/m², δx·Z)
+      if (profiles && dT.kind === 'I') {
+        for (let j = 0; j < N; j++) [xr[j], xi[j]] = [xr[j] * Zr - xi[j] * Zi, xr[j] * Zi + xi[j] * Zr];
       }
       out.Z.re[q] = Zr;
       out.Z.im[q] = Zi;
@@ -590,9 +689,12 @@ export class SmallSignal {
     for (let r = 0; r < model.regions.length; r++) {
       let sr = 0, si = 0, k = 0;
       const g0 = grid.regionStart[r], g1 = grid.regionEnd[r];
+      // (a metal's slot 0 is its segment's current, not φ̂: shifted, a platinum region of many
+      // cells read its electrode's current 8% off, at an error estimate of 1e-8)
+      const phiAt = (g) => this.nodeConductor[g] < 0 && loc[this.blockOfNode[g] * M] >= 0;
       for (let g = g0; g <= g1; g++) {
         const o = this.blockOfNode[g] * M;
-        if (loc[o] >= 0) {
+        if (phiAt(g)) {
           sr += yr[R[o]];
           si += yi[R[o]];
           k++;
@@ -614,7 +716,7 @@ export class SmallSignal {
       si /= k;
       for (let g = g0; g <= g1; g++) {
         const o = this.blockOfNode[g] * M;
-        if (loc[o] >= 0) {
+        if (phiAt(g)) {
           er[R[o]] = sr;
           ei[R[o]] = si;
         }

package/src/index.js

@@ -132,6 +132,7 @@ export class Device {
       solver.sourceTime = old.sourceTime;
       solver._refreshSources();
       solver.dtNext = old.dtNext;
+      solver.coldStart = old.coldStart; // (a carried state is as cold as it was: see equilibrateFaces)
       solver.contactDEnd = old.contactDEnd;
       if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)

package/src/kit.js

@@ -50,10 +50,14 @@ export function vacuumLevel(def, side, path = 'vacuum') {
   if (!Number.isFinite(side.offset)) fail(`${path}.offset must be a finite number (V)`);
   if (side.anchor === 'phi') return -side.offset;
   const sp = (def.species ?? []).find((s) => s.name === side.anchor);
-  if (!sp) fail(`${path}.anchor must be 'phi' or a charged species, got ${JSON.stringify(side.anchor)}`);
+  if (!sp)
+    fail(
+      `${path}.anchor must be 'phi' or a charged species of the device, got ${JSON.stringify(side.anchor)}` +
+        (typeof side.anchor === 'string' ? ` (to anchor on it, list it in the library: aqueous([..., '${side.anchor}']), say)` : ''),
+    );
   if (!(sp.z !== 0)) fail(`${path}.anchor: '${side.anchor}' is neutral, so it has no level in volts`);
   const entry = mat.species?.[side.anchor];
-  if (!isObject(entry)) fail(`${path}.anchor: '${side.anchor}' is absent from '${side.material}'`);
+  if (!isObject(entry)) fail(`${path}.anchor: '${side.anchor}' is absent from '${side.material}' (to anchor on it, give the material that species)`);
   if (!Number.isFinite(entry.mu0)) fail(`${path}.anchor: '${side.anchor}' in '${side.material}' has no mu0`);
   return entry.mu0 / (sp.z * FARADAY) - side.offset;
 }

package/src/newton.js

@@ -75,7 +75,9 @@
 // Also written: s.islandsOn (as asked, or on by 8); s.lostMode, s.accepted (7); s.delta, s.deltaV,
 // s.rowDiv; what an assembly writes, at the returned state where a probe or 6's check ran;
 // s.conditioning (a steady solve's failure: the worst cancellation a factorisation showed, for
-// its message).
+// its message); s.modelError, the message of a SolverError a statistics model threw at a state
+// Newton reached (in the assembly, or computing the concentrations where it stops), which fails
+// the call rather than leaving it (cleared by solveSteady and integrate, for their failures).
 // Tests: every solve and step goes through here; test/newton.test.js (the islands round, the
 // residual check's failure) and the MOS gate step in test/ports.test.js (a lost mode, to 1e-6);
 // test/jacobian.test.js checks the system it solves. The devices that needed each branch are in
@@ -401,6 +403,19 @@ export function newton(s, dt, { maxIter = 60, tol = 1e-10, maxStep = 10, islands
   };
   // A steady solve that fails: record how nearly singular the system was, and where; or, failing
   // with the islands' rows in, go back to the solution without them.
+  // The concentrations at the state Newton stops at, where a statistics model can refuse it (a
+  // Debye–Hückel solution past its range, at the converged state of a transient: the error was
+  // thrown from here, uncaught, out of solve() and advance()). Its message, for the failure.
+  const settle = () => {
+    try {
+      s.computeConcentrations();
+      return null;
+    } catch (err) {
+      if (!(err instanceof SolverError)) throw err;
+      s.modelError = err.message;
+      return err.message;
+    }
+  };
   const fail = (r) => {
     if (kept) {
       s.u.set(kept.u);
@@ -430,6 +445,7 @@ export function newton(s, dt, { maxIter = 60, tol = 1e-10, maxStep = 10, islands
     } catch (err) {
       // A statistics model can fail far from the solution (e.g. Debye–Hückel beyond its range).
       if (!(err instanceof SolverError)) throw err;
+      s.modelError = err.message;
       return fail({ converged: false, iterations: it, history, error: err.message });
     }
     equilibrate(s);
@@ -500,7 +516,8 @@ export function newton(s, dt, { maxIter = 60, tol = 1e-10, maxStep = 10, islands
       const done = { converged: true, iterations: it, history, residual: rmax };
       if (probed()) continue;
       if (islandsOff(it, done)) continue;
-      s.computeConcentrations();
+      const refused = settle();
+      if (refused) return fail({ converged: false, iterations: it, history, error: refused });
       return done;
     }
     // Converged as far as round-off allows: the updates are already tiny (below 1e-6 thermal
@@ -523,12 +540,13 @@ export function newton(s, dt, { maxIter = 60, tol = 1e-10, maxStep = 10, islands
       const done = { converged: true, iterations: it, history, residual: rmax, roundoff: true };
       if (probed()) continue;
       if (islandsOff(it, done)) continue;
-      s.computeConcentrations();
+      const refused = settle();
+      if (refused) return fail({ converged: false, iterations: it, history, error: refused });
       return done;
     }
   }
-  s.computeConcentrations();
-  return fail({ converged: false, iterations: maxIter, history });
+  const refused = settle();
+  return fail({ converged: false, iterations: maxIter, history, ...(refused ? { error: refused } : {}) });
 }
 
 // How far the terminal currents (as last assembled) are from adding up to zero, relative to the

package/src/solution.js

@@ -272,10 +272,16 @@ export function makeSolution(solver, result = {}) {
         'advance() in time instead, or give the still species a small D where it is still.',
     );
   } else if (slow.length > 0) {
+    // Too slow to wait out only where the solve waited: where no time step was taken at all, the
+    // start was the trouble (a hole-only layer full of the anode's holes, with traps: "raise its
+    // rate constant" changed nothing, ×1e4).
+    const waited = (result.history ?? []).some((h) => h.converged && h.dt > 0);
     for (const { where, affinity } of slow) {
       sol.warnings.push(
         `the solve did not converge, likely because ${where} is out of equilibrium by ${(affinity * solver.VT * 1e3).toPrecision(3)} mV of affinity, yet nothing else makes or uses what it changes, so a steady state needs it at equilibrium: ` +
-          'it is too slow for the steady solve to wait out. Raise its rate constant (the steady state does not depend on it), or advance() in time.',
+          (waited
+            ? 'it is too slow for the steady solve to wait out. Raise its rate constant (the steady state does not depend on it), or advance() in time.'
+            : 'the solve failed from its first steps, so start it nearer that equilibrium: c0 near it, or solve without the reaction and set() it back.'),
       );
     }
   } else if (result.converged === false && cond && cond.digits > 12) {
@@ -311,6 +317,11 @@ export function makeSolution(solver, result = {}) {
       `the solve did not converge from a start far from equilibrium: ${solver.violent.join('; ')}, its double layer uncharged. ` +
         'Hold that terminal at a voltage first, solve(), then let it float (set its I: 0): it keeps the state the held one gave it.',
     );
+  } else if (result.converged === false && !result.stopped && !un && !ch && !lost && slow.length === 0 && !(cond && cond.digits > 12) && solver.modelError) {
+    sol.warnings.push(
+      `the solve did not converge: the states it reached were refused by a statistics model: ${solver.modelError}. ` +
+        'The model doesn\'t hold there: a smaller concentration or drive, or a model for it (lattice for crowding).',
+    );
   } else if (result.converged === false && !result.stopped && !un && !ch && !lost && slow.length === 0 && !(cond && cond.digits > 12)) {
     sol.warnings.push(
       'the solve did not converge, and nothing specific showed why. ' +

package/src/solver.js

@@ -291,9 +291,15 @@ export class Solver {
     this.termDX = this.terms.map(() => new Float64Array(this.terms.length));
     this.termRes = new Float64Array(this.terms.length);
     this._refreshSources();
-    // A floating terminal starts level with the first held one (no current).
-    const level = this.termV[this.terms.findIndex((_, k) => !this.floating.includes(k))];
-    for (const k of this.floating) this.termV[k] = this.terms[k].drive.kind === 'V' ? this.termV[k] : level;
+    // A floating terminal starts level with the first held one (no current); where none is held,
+    // with the source behind the first resistance (it was NaN there, and a metal contact's
+    // carrier, its level from that V, asked for a c0 a conductor can't be given), else 0.
+    const heldK = this.terms.findIndex((_, k) => !this.floating.includes(k)), behindR = this.terms.find((t) => t.drive.R > 0);
+    const level = heldK >= 0 ? this.termV[heldK] : behindR ? sourceAt(behindR.drive.src, this.time) : 0;
+    // (One behind a resistance too: at its own source, a silver cell held at 0 V and 16 V behind R
+    // began with 16 V across it; left at 0 V, one behind a −30 V source beside a current began
+    // with 30 V across it. Level, the circuit rows move them from a device at rest.)
+    for (const k of this.floating) this.termV[k] = level;
     // Accepted steps, most recent first: start time, size, start state (for BDF2 and the
     // error estimate of adaptive stepping).
     this.history = [];
@@ -830,6 +836,7 @@ export class Solver {
     }
     this.termV.set(src.termV);
     this.solvedV = src.solvedV;
+    this.coldStart = src.coldStart;
     this.time = src.time;
     this.computeConcentrations();
   }
@@ -855,6 +862,7 @@ export class Solver {
       history: this.history.slice(),
       termV: Float64Array.from(this.termV),
       sourceTime: this.sourceTime,
+      coldStart: this.coldStart,
     };
   }
 
@@ -878,6 +886,7 @@ export class Solver {
     this.history = s.history.slice();
     this.termV.set(s.termV);
     this.sourceTime = s.sourceTime;
+    this.coldStart = s.coldStart;
     this.computeConcentrations();
   }