driftlet 0.4.0 → 0.6.0

package/src/recorder.js

@@ -0,0 +1,89 @@
+// A transient recorder, for driftlet/kit: advance() in pieces (a run to completion, or a little
+// each animation frame), with the trace joined up across calls and whole solutions kept as
+// frames, for scrubbing back through a run or plotting snapshots side by side.
+
+import { DeviceError } from './errors.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+/**
+ * Record a device's transient. Frames are whole solutions: at the start, then at each of
+ * `times` (or every `every` seconds from the start), which `advance()` lands on exactly; with
+ * neither, at the end of each `advance()` call. The trace (`t`, `current`, `voltage`, and
+ * `probes` if given) runs from the start through every accepted step of every call.
+ * @param {import('./index.js').Device} device
+ * @param {{ every?: number, times?: number[], probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
+ */
+export function recorder(device, opts = {}) {
+  const { every, times, probes } = opts;
+  if (every !== undefined && times !== undefined) fail('recorder: give every or times, not both');
+  if (every !== undefined && !(every > 0 && Number.isFinite(every))) fail('recorder: every must be a time > 0 (s)');
+  if (times !== undefined && !(Array.isArray(times) && times.every(Number.isFinite))) fail('recorder: times must be an array of times (s)');
+  const first = device.solution();
+  const t0 = first.time;
+  const schedule = times ? [...times].filter((t) => t > t0).sort((a, b) => a - b) : null;
+  const scheduled = schedule !== null || every !== undefined;
+  let next = every !== undefined ? 1 : 0; // the next frame due: schedule[next], or t0 + next·every
+  const due = () => (schedule ? schedule[next] : every !== undefined ? t0 + next * every : undefined);
+
+  const trace = { t: [first.time], current: [first.current], voltage: [first.terminals.right.V - first.terminals.left.V] };
+  if (probes) trace.probes = device.solver._probes(probes).read().map((v) => [v]); // the start's readings
+  const frames = [first];
+
+  /**
+   * Advance to tEnd (s), stopping at each frame time on the way to keep a frame. Takes
+   * advance()'s options; with `budgetMs` it returns when that much wall time is spent, `done`
+   * saying whether tEnd was reached. Returns the latest solution (its own `trace` is only the
+   * last piece: the recorder's `trace` is the whole run).
+   * @param {number} tEnd
+   * @param {object} [aopts] as for Device.advance()
+   */
+  function advance(tEnd, aopts = {}) {
+    const start = now(), budget = aopts.budgetMs ?? Infinity;
+    let sol;
+    for (;;) {
+      const stop = due();
+      const target = stop !== undefined && stop < tEnd ? stop : tEnd;
+      const left = budget - (now() - start);
+      sol = device.advance(target, { ...aopts, ...(probes ? { probes } : {}), budgetMs: left > 0 ? left : 0 });
+      const tr = sol.trace;
+      for (let k = 0; k < tr.t.length; k++) {
+        trace.t.push(tr.t[k]);
+        trace.current.push(tr.current[k]);
+        trace.voltage.push(tr.voltage[k]);
+        if (probes) tr.probes.forEach((p, j) => trace.probes[j].push(p[k]));
+      }
+      if (!sol.converged || !sol.done) break;
+      if (target === stop) {
+        frames.push(sol);
+        next++;
+      }
+      if (target === tEnd) break;
+      if (now() - start > budget) {
+        sol.done = false;
+        break;
+      }
+    }
+    if (!scheduled && sol.converged && sol.time > frames.at(-1).time) frames.push(sol);
+    return sol;
+  }
+
+  /**
+   * The frame at or just before time t (the first frame before the start).
+   * @param {number} t
+   */
+  function frame(t) {
+    let lo = 0, hi = frames.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (frames[mid].time <= t) lo = mid;
+      else hi = mid - 1;
+    }
+    return frames[lo];
+  }
+
+  return { advance, frame, frames, trace };
+}

package/src/solution.js

@@ -27,6 +27,7 @@ export function makeSolution(solver, result = {}) {
     V: {},
     Vstd: {},
     time: solver.time,
+    steady: solver.atSteady,
     converged: result.converged ?? true,
     iterations: result.iterations ?? 0,
     steps: result.steps,
@@ -121,7 +122,24 @@ export function makeSolution(solver, result = {}) {
     const N = {};
     for (let i = 0; i < n; i++) N[species[i].name] = u[b * M + 1 + i];
     const rates = itf.reactions.map((_, k) => u[b * M + 1 + n + k]); // mol/(m²·s), forward
-    return { dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+    return { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+  });
+
+  // Bulk reactions: each one's forward rate at every node (mol/(m³·s), NaN where it doesn't run),
+  // and integrated over each region and the device (mol/(m²·s)), by the nodes' control volumes,
+  // just as the balances count it.
+  sol.bulkReactions = solver.rxs.map((rx) => {
+    const rate = new Float64Array(nNodes).fill(NaN), regions = model.regions.map(() => 0);
+    let total = 0;
+    for (let g = 0; g < nNodes; g++) {
+      const m = solver.nodeMaterial[g];
+      if (!(rx.kf[m] > 0)) continue;
+      rate[g] = solver.bulkRate(rx, g);
+      const amount = grid.vol[g] * rate[g];
+      regions[grid.nodeRegion[g]] += amount;
+      total += amount;
+    }
+    return { rate, regions, total };
   });
 
   // Total charge per area in the device (space charge plus sheet charges).

package/src/solver.js

@@ -321,6 +321,7 @@ export class Solver {
     this.jR = new Float64Array(M);
     this.time = 0;
     this.lastDt = Infinity;
+    this.atSteady = false; // whether the state is a converged steady solve
     // Contact bookkeeping, filled by assemble(): particle flux toward +x through each contact,
     // and the displacement there (the metal's surface charge for a neutral link).
     this.contactFlux = { left: new Float64Array(n), right: new Float64Array(n) };
@@ -362,6 +363,7 @@ export class Solver {
     const { x: gx, segLength } = model.grid;
     this.rxs = model.reactions.map((rx) => ({
       kf: rx.kf,
+      srh: rx.srh, // per material: SRH kinetics in place of mass action, or null
       kfNode: Float64Array.from(gx, (x, g) => {
         const m = this.nodeMaterial[g], p = rx.kfProfile[m];
         return p ? profileMean(p, x - (g > 0 ? segLength[g - 1] : 0) / 2, x + (g < segLength.length ? segLength[g] : 0) / 2) : rx.kf[m];
@@ -563,9 +565,63 @@ export class Solver {
       // The row replaced: the basis vector's own stretch (its weight is 1, and no other vector has one).
       add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch);
     }
+    // A combination of immobile stretches (trap states: X⁰ + X⁻ under e⁻ + X⁰ = X⁻) is conserved
+    // node by node, since nothing carries it anywhere: at each node its weighted sum stays what
+    // it was, a row local to that node's block, in place of the balance row of one of them.
+    this.localConstraints = [];
+    const immobile = (st) => {
+      for (let q = st.regions[0]; q <= st.regions[1]; q++) if (materials[regions[q].material].D[st.species] > 0) return false;
+      return true;
+    };
+    for (const w of this.moieties) {
+      const parts = [...w.keys()].filter((k) => w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
+      const sts = parts.map((p) => this.stretches[p.stretch]);
+      if (sts.some((st) => st.conserved || !immobile(st) || conductor(st))) continue;
+      if (sts.some((st) => st.nodes[0] !== sts[0].nodes[0] || st.nodes[1] !== sts[0].nodes[1])) continue; // (side by side only)
+      for (const st of sts) st.conserved = true;
+      const row = parts.find((p) => p.w === 1) ?? parts[0];
+      this.localConstraints.push({
+        parts: parts.map((p) => ({ i: this.stretches[p.stretch].species, w: p.w })),
+        row: 1 + this.stretches[row.stretch].species,
+        nodes: sts[0].nodes,
+        reference: new Float64Array(sts[0].nodes[1] - sts[0].nodes[0] + 1),
+      });
+    }
     this.constrained = false;
   }
 
+  // Each local constraint's weighted sum at each node, as the state holds it now: what a steady
+  // solve keeps.
+  _captureLocal() {
+    const { n, c } = this;
+    for (const lc of this.localConstraints) {
+      for (let g = lc.nodes[0]; g <= lc.nodes[1]; g++) {
+        let t = 0;
+        for (const { i, w } of lc.parts) t += w * c[g * n + i];
+        lc.reference[g - lc.nodes[0]] = t;
+      }
+    }
+  }
+
+  // The local constraints' rows (steady solves only): Σ w c_i − reference at each node.
+  _applyLocalConstraints() {
+    const { n, M, c, res, dA: d } = this;
+    for (const lc of this.localConstraints) {
+      for (let g = lc.nodes[0]; g <= lc.nodes[1]; g++) {
+        const b = this.blockOfNode[g];
+        if (this.loc[b * M + lc.row] < 0) continue;
+        this._replaceRow(b, lc.row);
+        let t = 0;
+        for (const { i, w } of lc.parts) {
+          t += w * c[g * n + i];
+          this._dc(g, i, d);
+          for (let s = 0; s < M; s++) if (d[s] !== 0) this._j(b, lc.row, b, s, w * d[s]);
+        }
+        res[this.rix[b * M + lc.row]] = t - lc.reference[g - lc.nodes[0]];
+      }
+    }
+  }
+
   // A basis of the conserved combinations of stretch amounts: the null space of the
   // stoichiometry (a row per reaction, over the stretches it touches) together with a unit row
   // for each stretch fed from outside. Exact integer data, so plain elimination will do.
@@ -747,6 +803,7 @@ export class Solver {
   // After the terminals' drives change (Device.set): which are floating, and the held values. A
   // change of source is a discontinuity, so time stepping restarts its order.
   redrive() {
+    this.atSteady = false;
     const before = this.floating;
     this.floating = this.terms.flatMap((t, k) => (t.drive.kind === 'I' || t.drive.R > 0 ? [k] : []));
     if (this.floating.length !== before.length) this.deltaV = null;
@@ -1115,6 +1172,7 @@ export class Solver {
     // flux), then contacts, then the circuit rows of the floating ones.
     this._terminals(dt);
     if (this.constrained && dt === Infinity && this.constraints.length > 0) this._applyConstraints();
+    if (this.constrained && dt === Infinity && this.localConstraints.length > 0) this._applyLocalConstraints();
     this.transformed = this.combining && dt !== Infinity;
     if (this.transformed) this._chargeRows(dt);
   }
@@ -1304,6 +1362,26 @@ export class Solver {
     const dr = this.dA;
     for (let x = 0; x < rxs.length; x++) {
       const rx = rxs[x];
+      const law = rx.srh?.[this.nodeMaterial[g]];
+      if (law) {
+        // SRH: dr is ∂rate/∂slot directly, from its sensitivities to ln n, ln p and a.
+        let aHi = rx.fixedA, aLo = 0;
+        for (let p = 0; p < rx.sp.length; p++) {
+          aHi += rx.nu[p] * u[b * M + 1 + rx.sp[p]];
+          aLo += rx.nu[p] * uLo[b * M + 1 + rx.sp[p]];
+        }
+        const { rate, Cn, Cp, Ca } = this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], aHi + aLo);
+        dr.fill(0);
+        this._dlnc(g, law.n.i, Cn, dr);
+        this._dlnc(g, law.p.i, Cp, dr);
+        for (let p = 0; p < rx.sp.length; p++) dr[1 + rx.sp[p]] += Ca * rx.nu[p];
+        for (let p = 0; p < rx.sp.length; p++) {
+          const row = 1 + rx.sp[p], w = v * rx.nu[p];
+          res[R[b * M + row]] += w * rate;
+          for (let k = 0; k < M; k++) if (dr[k] !== 0) this._j(b, row, b, k, w * dr[k]);
+        }
+        continue;
+      }
       let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g], aHi = rx.fixedA, aLo = 0;
       dr.fill(0); // ∂ ln P / ∂slot
       // Participants: reactants with ν > 0, then products with ν < 0.
@@ -1639,6 +1717,53 @@ export class Solver {
     d[0] = -this._Kz(g, k);
   }
 
+  // A bulk reaction's rate at node g (mol/(m³·s), forward), as assembled: for the solution.
+  bulkRate(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    let aHi = rx.fixedA, aLo = 0;
+    for (let p = 0; p < rx.sp.length; p++) {
+      aHi += rx.nu[p] * u[b * M + 1 + rx.sp[p]];
+      aLo += rx.nu[p] * uLo[b * M + 1 + rx.sp[p]];
+    }
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], aHi + aLo).rate;
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P * -Math.expm1(-(aHi + aLo));
+  }
+
+  // The larger of a bulk reaction's two one-way rates at node g (mol/(m³·s)): the scale its net
+  // rate is read against (in equilibrium the net rate is their round-off).
+  bulkOneWay(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    let a = rx.fixedA;
+    for (let p = 0; p < rx.sp.length; p++) a += rx.nu[p] * (u[b * M + 1 + rx.sp[p]] + uLo[b * M + 1 + rx.sp[p]]);
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], a).oneWay;
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P * Math.max(1, Math.exp(-a));
+  }
+
+  // SRH kinetics (see srhLaw in device.js): the rate, and its sensitivities to ln n, ln p and
+  // a = A/RT. With no n₁ given, the trap is midgap: n₁ = p₁ = n_i = √(n p e^{−a}).
+  _srhRate(law, cn, cp, a) {
+    const { tn, tp } = law, lnnp = Math.log(cn) + Math.log(cp);
+    let n1, kN = 0, kP = 0, kA = 0; // ln n₁ = kN ln n + kP ln p + kA a + const
+    if (Number.isNaN(law.n1)) {
+      n1 = Math.exp((lnnp - a) / 2);
+      kN = kP = 0.5;
+      kA = -0.5;
+    } else n1 = law.n1;
+    const p1 = Math.exp(lnnp - a - Math.log(n1)), np = cn * cp;
+    const den = tp * (cn + n1) + tn * (cp + p1), f = -Math.expm1(-a);
+    const rate = (np * f) / den;
+    const dDn = tp * cn + tp * n1 * kN + tn * p1 * (1 - kN);
+    const dDp = tp * n1 * kP + tn * cp + tn * p1 * (1 - kP);
+    const dDa = tp * n1 * kA + tn * p1 * (-1 - kA);
+    return { rate, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
+  }
+
   // A face reaction (see normalizeFaceReactions). Its rate r_k is an unknown of the face block,
   // with the row r_k − rate(u_L, u_R) = 0, and each participant's edge node takes ν·r_k (made
   // there when ν > 0). The rate couples the two edge nodes only through the face block between
@@ -1650,24 +1775,34 @@ export class Solver {
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     const al = rx.alpha;
     const dL = this.dA.fill(0), dR = this.dB.fill(0); // ∂ ln(prefactor)/∂slot, per side
-    let pref = rx.k0, aHi = rx.fixedA, aLo = 0;
+    let pref = rx.k0, aHi = rx.fixedA, aLo = 0, rate;
     for (const p of rx.part) {
       const g = p.side ? gR : gL, b = p.side ? bR : bL, o = b * M + 1 + p.i;
       aHi -= p.nu * u[o];
       aLo -= p.nu * uLo[o];
-      if (this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
+      if (rx.srh || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
       pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
     }
-    const { g: bv, gp } = bvFactor(aHi + aLo, al);
-    const rate = pref * bv;
-    // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
-    for (let s = 0; s < M; s++) {
-      dL[s] *= rate;
-      dR[s] *= rate;
+    if (rx.srh) {
+      // SRH, with n and p each at its own side's edge node.
+      const { n: pn, p: pp } = rx.srh, gn = pn.side ? gR : gL, gq = pp.side ? gR : gL;
+      const s = this._srhRate(rx.srh, c[gn * n + pn.i], c[gq * n + pp.i], aHi + aLo);
+      rate = s.rate;
+      this._dlnc(gn, pn.i, s.Cn, pn.side ? dR : dL);
+      this._dlnc(gq, pp.i, s.Cp, pp.side ? dR : dL);
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= s.Ca * p.nu;
+    } else {
+      const { g: bv, gp } = bvFactor(aHi + aLo, al);
+      rate = pref * bv;
+      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
+      for (let s = 0; s < M; s++) {
+        dL[s] *= rate;
+        dR[s] *= rate;
+      }
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= pref * gp * p.nu;
     }
-    for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= pref * gp * p.nu;
     const slot = 1 + n + k, o = bf * M + slot;
     res[R[o]] = u[o] - rate;
     this._j(bf, slot, bf, slot, 1);
@@ -2066,6 +2201,7 @@ export class Solver {
    * the start-of-step values, and dt/a0 replaces dt.
    */
   step(dt, opts = {}) {
+    this.atSteady = false;
     const prev = this.history[0];
     const w = prev ? dt / prev.dt : 0;
     const bdf = opts.method === 'bdf2' && prev !== undefined && w <= 2;
@@ -2148,6 +2284,9 @@ export class Solver {
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
     let grow = 0; // longer first steps tried after a Newton failure (see below)
+    // The shortest step worth trying: round-off relative to the time, or the device's fastest
+    // time scale, whichever is shorter (a cold start can need steps far below a long run's 1e-14).
+    const floor = Math.min(1e-14 * Math.max(tEnd, 1e-300), this.fastestTime() * 1e-2);
     const pred = new Float64Array(this.u.length), guess = new Float64Array(this.u.length);
     const factor = (err, p) => (err > 0 ? Math.min(2, Math.max(0.2, 0.9 * Math.exp(Math.log(tol / err) / (p + 1)))) : 2);
     while (this.time < tEnd) {
@@ -2204,7 +2343,7 @@ export class Solver {
             grow = 3;
             dt = h / 4;
           }
-          if (dt < 1e-14 * Math.max(tEnd, 1e-300)) { failed = true; break; }
+          if (dt < floor) { failed = true; break; }
           continue;
         }
       } else {
@@ -2213,7 +2352,7 @@ export class Solver {
         if (!r.converged) {
           rejected++;
           dt = h / 4;
-          if (dt < 1e-14 * Math.max(tEnd, 1e-300)) { failed = true; break; }
+          if (dt < floor) { failed = true; break; }
           continue;
         }
         p = this._predict(pred, r.bdf);
@@ -2357,6 +2496,39 @@ export class Solver {
     return mx;
   }
 
+  // Start from another solver's state for the same device on another grid (a refined one): each
+  // node's unknowns interpolated linearly in x within its region, each face's copied, and the
+  // terminals' voltages. A warm start for a steady solve; nothing else is carried over.
+  _warmFrom(src) {
+    const { M, u, uLo } = this, grid = this.model.grid, sg = src.model.grid;
+    if (src.M !== M || sg.regionStart.length !== grid.regionStart.length) throw new Error('_warmFrom: a different device');
+    const value = (b, k) => src.u[b * M + k] + src.uLo[b * M + k];
+    for (let r = 0; r < grid.regionStart.length; r++) {
+      let a = sg.regionStart[r];
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const x = grid.x[g];
+        while (a + 1 < sg.regionEnd[r] && sg.x[a + 1] < x) a++;
+        const b = Math.min(a + 1, sg.regionEnd[r]), h = sg.x[b] - sg.x[a];
+        const w = h > 0 ? Math.min(1, Math.max(0, (x - sg.x[a]) / h)) : 0;
+        const ba = src.blockOfNode[a], bb = src.blockOfNode[b], bg = this.blockOfNode[g];
+        for (let k = 0; k < M; k++) {
+          u[bg * M + k] = (1 - w) * value(ba, k) + w * value(bb, k);
+          uLo[bg * M + k] = 0;
+        }
+      }
+    }
+    for (let f = 0; f < this.nFaces; f++) {
+      for (let k = 0; k < M; k++) {
+        u[this.blockOfFace[f] * M + k] = value(src.blockOfFace[f], k);
+        uLo[this.blockOfFace[f] * M + k] = 0;
+      }
+    }
+    this.termV.set(src.termV);
+    this.solvedV = src.solvedV;
+    this.time = src.time;
+    this.computeConcentrations();
+  }
+
   _snapshot() {
     return {
       u: Float64Array.from(this.u),
@@ -2364,6 +2536,7 @@ export class Solver {
       cOld: Float64Array.from(this.cOld),
       time: this.time,
       lastDt: this.lastDt,
+      atSteady: this.atSteady,
       contactDStart: this.contactDStart,
       contactDOld: this.contactDOld,
       contactDEnd: this.contactDEnd,
@@ -2380,6 +2553,7 @@ export class Solver {
     this.cOld.set(s.cOld);
     this.time = s.time;
     this.lastDt = s.lastDt;
+    this.atSteady = s.atSteady;
     this.contactDStart = s.contactDStart;
     this.contactDOld = s.contactDOld;
     this.contactDEnd = s.contactDEnd;
@@ -2734,6 +2908,17 @@ export class Solver {
     return Number.isFinite(dMin) ? (L * L) / dMin : 1;
   }
 
+  // The fastest diffusion time: across the smallest cell, at the largest D.
+  fastestTime() {
+    let dMax = 0;
+    for (const mat of this.model.materials) {
+      for (let i = 0; i < this.n; i++) if (mat.present[i]) dMax = Math.max(dMax, mat.D[i]);
+    }
+    let h = Infinity;
+    for (const s of this.model.grid.segLength) if (s > 0) h = Math.min(h, s);
+    return dMax > 0 && Number.isFinite(h) ? (h * h) / dMax : this.slowestTime();
+  }
+
   /**
    * Steady state.
    * - If every species stretch is fed by a contact, nothing is conserved on its own, so the
@@ -2744,8 +2929,18 @@ export class Solver {
    * If Newton fails, dt ramps up from a small value (pseudo-transient continuation) instead.
    * The clock is not advanced, and open-system conservation bookkeeping restarts here.
    */
+  // Steady state from the present one; `atSteady` says whether the state is one (until a step or
+  // a change of drive).
   solveSteady(opts = {}) {
+    const r = this._steadyFromHere(opts);
+    this.atSteady = r.converged;
+    return r;
+  }
+
+  _steadyFromHere(opts) {
     this.conditioning = null;
+    this.computeConcentrations();
+    this._captureLocal(); // immobile combinations keep, node by node, what they hold now
     this.sourceTime = this.time;
     // Continuation applies where the right terminal is held at a voltage, against a held left one.
     const [dl, dr] = [this.terms[0].drive, this.terms[1].drive];
@@ -2921,8 +3116,10 @@ export class Solver {
         history.push({ dt, converged: r.converged, iterations: r.iterations, maxStep: 3 });
       }
       if (!r.converged) {
+        // Pseudo-transient continuation: down from a slow time scale until a step converges,
+        // as far as the fastest (slow ions mustn't stop it short of what a cold start needs).
         dt = dt >= giant ? tau * 1e-6 : dt / 4;
-        if (dt < tau * 1e-15) break;
+        if (dt < Math.min(tau * 1e-15, this.fastestTime() * 1e-2)) break;
         continue;
       }
       if (dt === Infinity) {

package/src/stack.js

@@ -59,7 +59,7 @@ export function layer(material, length, more = {}) {
 
 // A drive: a number is a held voltage, a waveform { t, values } a voltage waveform, and an
 // object with V, I or R is the drive itself.
-function drive(d, path) {
+export function drive(d, path) {
   if (d === undefined) return { V: 0 };
   if (typeof d === 'number') return { V: d };
   if (isObject(d) && Array.isArray(d.t)) return { V: d };

package/src/traces.js

@@ -62,7 +62,11 @@ export function typeset(name, z) {
  * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
  * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
  * @param {import('./types.js').Solution} sol
- * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ * With `energy: true` it's the familiar band diagram instead, energy up: electrons and holes as
+ * electron energies in eV (E = −V: E_c and E_v from the standard levels, E_Fn and E_Fp, or E_F
+ * where only electrons are present, from the levels), with any redox levels and φ (as −qφ) turned
+ * over too. Only electrons and holes have bands; ions are refused (draw them as species voltages).
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[], energy?: boolean,
  *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
  *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
  *   species to show (default: every charged one), whether to show standard levels (default true)
@@ -73,31 +77,40 @@ export function typeset(name, z) {
  * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
  *   faces: number[], range: [number, number] }}
  */
-export function traces(sol, { species, standard = true, phi = false, levels = [], labels = {}, shifts = {} } = {}) {
+export function traces(sol, { species, standard = true, phi = false, energy = false, levels = [], labels = {}, shifts = {} } = {}) {
   const names = Object.keys(sol.V);
   const role = (name) => speciesRole(sol, name).role;
   const slotOf = (name) => speciesRole(sol, name).slot;
-  const shown = species ?? names.filter((name) => finite(sol.V[name]));
+  const carriers = ['e-', 'h+'];
+  const shown = species ?? names.filter((name) => finite(sol.V[name]) && (!energy || carriers.includes(name)));
+  if (energy) {
+    for (const name of shown) {
+      if (!carriers.includes(name)) throw new Error(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
+    }
+  }
+  const sign = energy ? -1 : 1, unit = energy ? 'eV' : 'V';
+  const bipolar = names.includes('h+');
+  const energyLabels = { 'V:e-': bipolar ? 'E_{Fn}' : 'E_F', 'Vstd:e-': 'E_c', 'V:h+': 'E_{Fp}', 'Vstd:h+': 'E_v' };
   const zOf = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
   const pretty = (name) => (name in zOf ? typeset(name, zOf[name]) : name);
   const series = [];
   for (const name of shown) {
     if (!names.includes(name)) throw new Error(`traces: no charged species '${name}' in the solution`);
     const shift = shifts[name] ?? 0;
-    const at = (y) => (shift ? y.map((v) => v + shift) : y);
+    const at = (y) => (shift || energy ? Array.from(y, (v) => sign * v + shift) : y);
     const common = { species: name, role: role(name), slot: slotOf(name), ...(shift ? { shift } : {}) };
-    if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
-    if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
+    if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: energy ? energyLabels[`V:${name}`] : `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
+    if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: energy ? energyLabels[`Vstd:${name}`] : `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
   }
   if (Array.isArray(phi)) {
     const known = sol.regions.flatMap((r) => [r.name, r.material]);
     for (const name of phi) if (!known.includes(name)) throw new Error(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
     const inside = sol.regions.map((r) => phi.includes(r.name) || phi.includes(r.material));
-    series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? v : NaN)) });
-  } else if (phi) series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: sol.phi });
+    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
+  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Array.from(sol.phi, (v) => -v) : sol.phi });
   const couples = [...new Set(levels.map((lv) => lv.half.equation))];
   levels.forEach((lv, k) => {
-    const y = level(sol, lv.half, { standard: lv.standard });
+    const y = energy ? Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
     series.push({
       id: `level:${k}`,
       label: lv.label ?? `${lv.standard ? 'V° ' : ''}${lv.half.equation.split(' ').map(pretty).join(' ')}`,
@@ -109,7 +122,7 @@ export function traces(sol, { species, standard = true, phi = false, levels = []
   });
   for (const s of series) {
     if (labels[s.id] !== undefined) s.label = labels[s.id];
-    if (s.shift) s.label += ` ⌇${s.shift > 0 ? '+' : '−'}${Math.abs(s.shift)} V`;
+    if (s.shift) s.label += ` ⌇${s.shift > 0 ? '+' : '−'}${Math.abs(s.shift)} ${unit}`;
   }
   let lo = Infinity, hi = -Infinity;
   for (const s of series) {

package/src/types.js

@@ -201,7 +201,9 @@
  * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number }[]} ports what each
  *   internal port brings into the device
- * @property {{ dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
+ * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
+ * @property {{ rate: Float64Array, regions: number[], total: number }[]} bulkReactions each bulk reaction's
+ *   forward rate per node (mol/(m³·s), NaN where it doesn't run), and per region and in all (mol/(m²·s))
  * @property {number} charge total charge in the device, C/m²
  * @property {{ species: string, regions: number[], spectator: boolean, connected: boolean, reactive: boolean,
  *   amount: number, reference: number, intake: number, drift: number }[]} conservation
@@ -209,6 +211,7 @@
  * @property {boolean} converged
  * @property {number} iterations
  * @property {number} time s
+ * @property {boolean} steady whether this is a converged steady state (solve()), not a transient's
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
  * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] advance():

package/types/checks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {object} CheckItem
+ * @property {string} name what was checked: 'converged', 'warnings', 'balance', 'conservation' or 'grid'
+ * @property {boolean | null} ok whether it passed (null: look at it, a warning or a check that
+ *   couldn't be made)
+ * @property {string} summary one line
+ * @property {object} [details] the numbers behind it
+ */
+/**
+ * Check a device's present state (pass the solution solve() or advance() returned, for its
+ * convergence and warnings):
+ * - **converged**: the last solve converged.
+ * - **warnings**: the solution's warnings (unresolved double layers, steep profiles, weakly held
+ *   parts) and the definition's likely unit slips.
+ * - **balance** (a steady state): each species' ledger, what comes in through each terminal and
+ *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) and, for a charged
+ *   species, as a current F·|z|·rate. The terms must sum to zero; under light it's J = F(G − R),
+ *   and it says where every carrier went.
+ * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
+ *   what came in.
+ * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
+ *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
+ *   wants less). The discretisation is second order, so the change estimates this grid's error
+ *   (about 3/4 of it).
+ * @param {import('./index.js').Device} device
+ * @param {object} [sol] the solution to check (default: the device's present state)
+ * @param {{ refine?: boolean, tol?: number }} [opts]
+ * Every check passed when `ok`; an item with `ok: null` (a warning, or a check that couldn't be
+ * made) asks you to look, and doesn't fail it. `text` is a line per check, marked ok, FAIL or ?.
+ * @returns {{ ok: boolean, items: CheckItem[], text: string }}
+ */
+export function check(device: import("./index.js").Device, sol?: object, { refine, tol }?: {
+    refine?: boolean;
+    tol?: number;
+}): {
+    ok: boolean;
+    items: CheckItem[];
+    text: string;
+};
+export type CheckItem = {
+    /**
+     * what was checked: 'converged', 'warnings', 'balance', 'conservation' or 'grid'
+     */
+    name: string;
+    /**
+     * whether it passed (null: look at it, a warning or a check that
+     * couldn't be made)
+     */
+    ok: boolean | null;
+    /**
+     * one line
+     */
+    summary: string;
+    /**
+     * the numbers behind it
+     */
+    details?: object;
+};