driftlet 0.14.0 → 0.16.4

package/llms.txt

@@ -28,9 +28,9 @@ materials, insertion hosts), data.md and reliability.md (what's validated, and t
 From a CDN, pin the version you tested against:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -61,8 +61,9 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
 - **Check before trusting.** `sol.converged` must be true; read `sol.warnings`, where a failed
   solve always says why. `describe(def)` (kit) summarises a definition and flags likely unit
   slips. Once a device works, log `check(dev, sol).text` (kit) once: each species' ledger,
-  conservation in transients, and a steady state on a grid twice as fine (a FAIL means refine;
-  a transient you rerun on a finer grid yourself).
+  conservation in transients, a steady state on a grid twice as fine (a FAIL means refine;
+  a transient you rerun on a finer grid yourself) and with its species listed in reverse (a
+  FAIL there means a solve converged somewhere that isn't steady: compare a long advance()).
 
 ## How a device is written
 
@@ -73,14 +74,15 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
 - **The library** is pieces with `species` and `materials`: `semiconductor('Si')` (Si, Ge, GaAs, at
   300 K), `aqueous(names)` (H⁺ Li⁺ Na⁺ K⁺ Ag⁺ Cu²⁺ Zn²⁺ Fe²⁺ Fe³⁺ OH⁻ Cl⁻ NO₃⁻ SO₄²⁻ in water, at 25
   °C; `{ epsr: 0 }` makes it strictly neutral, with no double layers), `metal('Ag')` (Ag Cu Au Al Zn
-  Li Pt). A semiconductor's textbook numbers are in `SEMICONDUCTORS.Si` (`Eg` and `chi` in eV, `Nc`
-  and `Nv` in cm⁻³, `mun` and `mup` in cm²/(V·s), `epsr`); in the material, e⁻'s and h⁺'s `cRef` are
-  N_c and N_v in mol/m³ and h⁺'s `mu0` is the gap (e⁻'s is 0), so n_i = √(N_c N_v) e^(−E_g/2RT),
-  6.7e9 cm⁻³ for Si. A species it lacks is pushed into both lists (`z: 0` for a neutral one):
-  `lib.species.push({ name: 'A-', z: -1, cRef: 1000 })`, `lib.materials.water.species['A-'] = { D,
-  mu0 }`. Only μ° differences within a reaction matter: for a redox couple μ°_red − μ°_ox = −F·E°
-  (against SHE, the library's μ°_H⁺ being 0). An insulator is a material with no species: `{
-  species: [], materials: { SiO2: { epsr: 3.9, species: {} } } }`.
+  Li Pt), all from `driftlet/kit`. A semiconductor's textbook numbers are in `SEMICONDUCTORS.Si`
+  (`Eg` and `chi` in eV, `Nc` and `Nv` in cm⁻³, `mun` and `mup` in cm²/(V·s), `epsr`); in the
+  material, e⁻'s and h⁺'s `cRef` are N_c and N_v in mol/m³ and h⁺'s `mu0` is the gap (e⁻'s is 0),
+  so n_i = √(N_c N_v) e^(−E_g/2RT), 6.7e9 cm⁻³ for Si. A species it lacks is pushed into both lists
+  (`z: 0` for a neutral one): `lib.species.push({ name: 'A-', z: -1, cRef: 1000 })`,
+  `lib.materials.water.species['A-'] = { D, mu0 }`. Only μ° differences within a reaction matter:
+  for a redox couple μ°_red − μ°_ox = −F·E° (against SHE, the library's μ°_H⁺ being 0). An
+  insulator is a material with no species: `{ species: [], materials: { SiO2: { epsr: 3.9, species:
+  {} } } }`.
 - **Faces.** Between two different non-metals, give an alignment, `{ dipole }` or `{ step: {
   species: 'e-', value } }` (J/mol), or `phi: 'neutral'`. `vacuumDipole(def, { material, anchor:
   'e-', offset: χ }, …)` estimates a dipole from electron affinities (Anderson's rule); it reads
@@ -95,7 +97,8 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   (`capacitance`, `gates`). A BJT's base contact is a port on a narrow window of the base,
   `{ region: 'base', from, to, V, terminal: 'h+', species: { 'h+': 'equilibrium' } }`.
 - **Drives.** A terminal is held at a voltage `V`, driven by a current `I` (open circuit is
-  `I: 0`), or behind a resistance `{ V, R }`. Either can be a waveform: a table `{ t, values }`
+  `I: 0`), or behind a resistance `{ V, R }`; in `build()`, the same object goes where the
+  voltage would (`ohmic({ I: 0 }, ['e-'])`, `ohmic({ V: 1, R: 1e3 }, ['e-'])`). Either can be a waveform: a table `{ t, values }`
   (piecewise linear; a step is two points at one time), or the kit's `pulse({ start, width,
   amplitude, rise, base })`, `square({ high, low, period, duty })`, `ramp({ from, to, duration,
   start })` or `triangle({ from, to, period })` (out and back each period from t = 0: a cyclic
@@ -111,8 +114,8 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   { tauN, tauP } }` in place of `kf` (s), or at a face `{ equation: 'e-(left) + h+(right) = 0',
   srh: { vn, vp } }` (m/s); with τ_N ≪ τ_p it gives n-type silicon's holes a lifetime τ_p at any
   injection. Light is a reaction from a reservoir (`photon = e- + h+`, uniform), or absorbed as
-  it goes in,
-  `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })`.
+  it goes in, `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })`. To switch
+  it during a run, `set()` the device's `bulkReactions` (the state and the step size carry over).
 - **Electrode kinetics.** A face reaction's `k0` (mol/(m²·s)) is its rate with every participant
   at cRef: i₀ = nF·k0 there, and k0 = k°·cRef for a textbook k° in m/s (1 cm/s at 1 M is
   `k0: 10`).
@@ -145,6 +148,14 @@ const tK = D['K+'] / (D['K+'] + D['Cl-']), VT = (GAS_CONSTANT * 298.15) / FARADA
 console.log(`EMF ${(sol.terminals.right.V * 1e3).toFixed(3)} mV, 2t₊V_T ln 10 = ${(2 * tK * VT * Math.log(10) * 1e3).toFixed(3)} mV`); // 58.048, 58.047
 ```
 
+An ion-exchange membrane is a layer whose material has its ions slower, with a `fixedCharge` (−X·F
+for X mol/m³ of fixed anions), between layers of water. A bath against the membrane itself names
+its own material, `bath(c, 'Cl-', 0, { material: 'water' })`, and meets it through a Donnan step.
+An exchange or partition constant between the membrane and the water is a difference of μ°:
+give the membrane's ions μ° shifted from the water's by s_i, and K = e^(−(s_Na − s_H)/RT) for
+Na⁺ against H⁺ (a large K draws in salt too, unless the co-ion's s is raised). The membrane
+demo's page script is a worked example.
+
 ## Template: a semiconductor junction
 
 ```js
@@ -193,9 +204,9 @@ a CDN needs a long virtual-time budget, 30 s.)
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/plot.js';
 
 const def = build({
   T: 300,
@@ -220,17 +231,15 @@ see "Reading level diagrams" below.
 
 For an explainer, `particles(sol, { weight, cap })` (kit) draws a solution as dots, each `weight`
 mol/m² of a species, hopping at rates taken from the solution: on average their density is its
-concentration and their net crossing its flux. A friendly first figure for teaching, as long as
-the page says it samples the continuum solution and how much a dot is. Where a dot would be lost
-among millions (majority carriers, a bath), a cell over `cap` dots is a sea: shade it by
-`expected(name)`. Each frame: `swarm.step(dt)` in the device's time (about h²/D per hop, h a
-cell), then draw `swarm.dots` (`{ species, x }`) and `swarm.events` (`'unmade'` is a
-recombination; `'cross'` an ion through a membrane between two seas); on a new steady solution,
-`swarm.update(sol, { resample: true })`. A membrane's permeability (1e-8 m/s) is tiny beside
-D/h in the water (0.02 m/s for 100 nm cells), so an ion beside it hops ~1e6 times per crossing:
-a membrane page shows seas and crossing events, not walking ions.
-The pn demo's page script draws a diode's carriers on its band diagram this way, and the axon
-demo's the ions crossing its membrane (`cap: 0`, every cell a sea, so only the crossings).
+concentration and their net crossing its flux. Say on the page that it samples the continuum
+solution, and how much a dot is. Where a dot would be lost among millions (majority carriers, a
+bath), a cell over `cap` dots is a sea: shade it by `expected(name)`. Each frame,
+`swarm.step(dt)` in the device's time (about h²/D per hop, h a cell), then draw `swarm.dots`
+(`{ species, x }`) and `swarm.events` (`'unmade'` is a recombination, `'cross'` an ion through a
+membrane between two seas); on a new steady solution, `swarm.update(sol, { resample: true })`.
+An ion beside a cell membrane hops ~1e6 times per crossing, so a membrane page shows seas and
+crossing events, not walking ions. The demos' page scripts do this for a diode's carriers (pn),
+ions crossing a nerve membrane (axon, `cap: 0`) and Donnan exclusion (membrane).
 
 ## Template: a solar cell
 
@@ -263,6 +272,15 @@ const oc = new Device(cell({ I: 0 })).solve(); // open circuit
 console.log(`J_sc = ${sc.current.toFixed(1)} A/m², V_oc = ${oc.terminals.right.V.toFixed(3)} V`);
 ```
 
+In an organic cell, light makes excitons: a neutral species `X` in the donor, made by
+`photogeneration({ ..., makes: 'X' })` and decaying by `{ equation: 'X = 0', kf: { donor: 1 / tau } }`.
+They split at the donor/acceptor face by a reaction there, `X = h+(left) + e-(right)` with e⁻ and
+h⁺ blocked at the face (the reaction moves them), and its reverse is charge-transfer
+recombination; the face's `step` sets E_CT. With `alpha: 0` the splitting is a velocity
+k0/cRef, a Robin condition on the exciton profile; with α > 0 it's k0/cRef · e^(α(E_X − E_CT)/RT).
+The organic demo's page script is a worked example (J_sc against exciton diffusion theory, V_oc
+against detailed balance).
+
 For a perovskite cell, prefer the curated `perovskiteCell({ V, light, bulkSRH })`: IonMonger's
 default cell (mobile iodide vacancies), with its J–V scans at seven rates in `PEROVSKITE_SCANS`
 and `hysteresis(trace, turn)` to read the same figures from yours.
@@ -308,11 +326,14 @@ for (const Vg of [-2, -0.95, 0, 0.4, 2]) {
   console.log(`V_G ${Vg} V: C/C_ox ${(C / Cox).toFixed(3)}`); // 0.949, 0.701 (flat band), 0.267, 0.375, 0.973
 }
 // At flat band the silicon is a capacitor of ε/L_D, its Debye length's.
-const LD = Math.sqrt((11.7 * EPS0 * GAS_CONSTANT * 300) / (FARADAY * FARADAY * NA));
-console.log(`flat band, theory: ${(1 / (1 + (Cox * LD) / (11.7 * EPS0))).toFixed(3)}`); // 0.699
+const LD = Math.sqrt((11.9 * EPS0 * GAS_CONSTANT * 300) / (FARADAY * FARADAY * NA)); // (the kit's Si: ε 11.9)
+console.log(`flat band, theory: ${(1 / (1 + (Cox * LD) / (11.9 * EPS0))).toFixed(3)}`); // 0.701
 ```
 
-`dev.impedance([f], { terminal: 'left' })` gives the same C at low frequency. Draw it with
+`dev.impedance([f], { terminal: 'left' })` (C = Im(1/Z)/ω, from `{ f, Z: { re, im } }`) gives
+the same C at any frequency with the port; without it, only below the minority supply's knee
+(generation, or diffusion from the back contact: 0.01 Hz and below), and the high-frequency C–V
+above. Draw it with
 `bandDiagram(sol, { energy: true, phi: ['SiO2'] })`: across an insulator φ is the line to draw.
 
 ## Template: a Schottky diode
@@ -419,10 +440,12 @@ console.log(level(sol, silver)[mid] - level(sol, SHE, { standard: true })[mid]);
 
 A working electrode, a stagnant layer, and the stirred bulk as a bath whose terminal is its
 reference species (Cl⁻: an Ag/AgCl reference). An electrode's potential against SHE is its
-electrons' V minus φ in the bulk (with the library's μ°). The working electrode's current is
-positive when oxidising. The layer's resistance is in series (uncompensated IR: keep it thin, or
-the supporting salt strong); a 100:1 excess of salt still leaves the limiting current about 1%
-off pure diffusion.
+electrons' V minus φ in the bulk (with the library's μ°), and a Cl⁻ terminal sits ~1.36 V above
+that, so an electrode held at 0 V beside it is strongly anodic: `describe(def)` says where SHE
+sits, and an offset of that much (`bath(c, 'Cl-', 0, { offset })`) makes the terminal read SHE.
+The working electrode's current is positive when oxidising. The layer's resistance is in series
+(uncompensated IR: keep it thin, or the supporting salt strong); a 100:1 excess of salt still
+leaves the limiting current about 1% off pure diffusion.
 
 ```js
 import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
@@ -665,7 +688,9 @@ capacitance and gated channels to an outside given as a `bath` (the port's V is
 outside's φ). `hodgkinHuxley({ T, area })` writes HH's channels for it, `area` being the membrane
 per volume, 2/a. Cable theory isn't put in; it comes out of the ions' drift. `ports[k].Vm[j]` and
 `ports[k].gates[name][j]` give the membrane at each node. A myelinated axon is regions, each with
-its own port (an internode's just a small capacitance).
+its own port (an internode's just a small capacitance). Nothing warns of a grid too coarse for
+the spike's front: the speed comes out 3% low on 2 mm cells, 0.2% on 0.5 mm, for a = 238 µm
+(scale h with √a). The stimulus is a current per volume, so a thinner axon needs it as 1/a.
 
 ```js
 import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
@@ -710,8 +735,15 @@ species }` (its flux) or `{ interface: f, gate }`.
 
 - **Events.** To stop at one (a cut-off voltage, a diode's storage time), advance in short calls
   and test after each: a driven current held past what the device can pass fails to converge.
-- **Storage.** A device that only stores what comes in (a battery host filling at a current) has
-  no steady state: `advance()` it from its `c0`, don't `solve()` it (docs/statistics.md).
+- **The first instants.** The first step is sized by error control (from 1e-4 of the interval),
+  so a fast start (an initial plateau, a charging spike) can fall inside it: give `dt0` (and
+  `dtMax`) to see it. A voltage step's first point carries the displacement that charges the bulk
+  at once (a spike of ~1e4 A/m² for ~1e-10 s across a cell's Stern layers): leave it out of
+  integrals of I²R.
+- **Storage.** A device that only stores what comes in (a battery host filling at a current, a
+  gate charging) has no steady state: `advance()` it from its `c0`, don't `solve()` it
+  (docs/statistics.md). At no current (`I: 0`), `solve()` keeps the charge it holds: a closed
+  battery sits at the OCV of its state of charge, a floating gate keeps its charge.
 - **Other steps.** `dev.step(dt)` is one backward-Euler step, and `dev.impedance(frequencies,
   { terminal })` the small-signal Z(f) about the steady state, in Ω·m².
 
@@ -803,7 +835,7 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
   everything floating (hold one terminal at a `V`), a species that reaches no contact without a
   `c0`, an unbalanced `c0` in a closed neutral region (add the counter-ion's share), `'2e-'` for
   `'2 e-'`, a current drive of the wrong sign. `interfaces[f]` is the stack's f-th face.
-- **A gate as a contact on an oxide.** It fails as `'e-' is blocked at this contact`: make the
+- **A gate as a contact on an oxide.** It fails as `'e-' is absent from the end material 'SiO2'`: make the
   gate a metal layer with a capacitive face, as in the MOS template.
 - **`ohmic()` on a metal.** Its default holds e⁻ and h⁺; on a metal write `ohmic(V, ['e-'])`.
 - **Ions on both sides of a reacting face.** Label them, `'Li+(left) = Li+(right)'`, and block

package/package.json

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

package/src/blockTridiagonal.js

@@ -110,16 +110,29 @@ export class BlockTridiagonal {
       if (i === 0 || sizes[i - 1] === 0) {
         for (let k = 0; k < m * m; k++) lu[o + k] = B[o + k];
       } else {
+        // Row by row, skipping A's zeros (a gate or a local unknown has none to its neighbours):
+        // the same sums, subtracted in the same order.
         const mp = sizes[i - 1], oa = offA[i], op = offC[i - 1]; // C'_{i−1}: mp × m
         for (let r = 0; r < m; r++) {
-          for (let c = 0; c < m; c++) {
-            let s = B[o + r * m + c];
-            for (let k = 0; k < mp; k++) s -= A[oa + r * mp + k] * cp[op + k * m + c];
-            lu[o + r * m + c] = s;
+          const or = o + r * m;
+          for (let c = 0; c < m; c++) lu[or + c] = B[or + c];
+          for (let k = 0; k < mp; k++) {
+            const a = A[oa + r * mp + k];
+            if (a === 0) continue;
+            const ok = op + k * m;
+            for (let c = 0; c < m; c++) lu[or + c] -= a * cp[ok + c];
           }
         }
       }
-      const ratio = luFactor(lu, o, piv, offX[i], m, this);
+      let ratio = luFactor(lu, o, piv, offX[i], m, this);
+      // A pivot far below the entries it's formed from may be round-off alone (the level of a
+      // region that only the blocks after it hold): its value, 7e-32 or 3e-16 or 0 as the
+      // unknowns happen to be listed, then scales all that follows (by 1e31, and the next block
+      // lost its own pivot outright). Redone with each entry's magnitudes carried (see
+      // cancellation), a pivot 1e-18 of them, all its digits lost, is perturbed like one that
+      // cancelled to exactly nothing. (At 1e-15 it can still hold a digit Newton needs: a port's
+      // steady solve wandered instead of converging.)
+      if (this.staticPivots && ratio < 1e-12) ratio = this._noisyPivots(i);
       if (!(ratio > 0)) {
         this.factored = false;
         this.singularBlock = i;
@@ -130,8 +143,9 @@ export class BlockTridiagonal {
       if (i < n - 1) {
         const mn = sizes[i + 1], oc = offC[i];
         for (let c = 0; c < mn; c++) {
-          for (let r = 0; r < m; r++) tmp[r] = C[oc + r * mn + c];
-          luSolve(lu, o, piv, offX[i], m, tmp);
+          let any = false;
+          for (let r = 0; r < m; r++) if ((tmp[r] = C[oc + r * mn + c]) !== 0) any = true;
+          if (any) luSolve(lu, o, piv, offX[i], m, tmp); // (a zero column stays zero)
           for (let r = 0; r < m; r++) cp[oc + r * mn + c] = tmp[r];
         }
       }
@@ -140,6 +154,70 @@ export class BlockTridiagonal {
     this.factored = true;
   }
 
+  // Block i again, its W and LU with the magnitudes each entry is formed from (as cancellation()
+  // does), perturbing pivots 1e-18 of theirs. Returns the block's pivot ratio.
+  _noisyPivots(i) {
+    const { A, B, sizes, offA, offB, offC, offX } = this, cp = this._cp, lu = this._lu, piv = this._piv;
+    const m = sizes[i], mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], o = offB[i], oc = i > 0 ? offC[i - 1] : 0;
+    const S = (this._mag ??= new Float64Array(this._tmp.length * this._tmp.length));
+    for (let r = 0; r < m; r++) {
+      for (let c = 0; c < m; c++) {
+        let v = B[o + r * m + c], sum = Math.abs(v);
+        for (let k = 0; k < mp; k++) {
+          const a = A[oa + r * mp + k];
+          if (a === 0) continue;
+          const t = a * cp[oc + k * m + c];
+          v -= t;
+          sum += Math.abs(t);
+        }
+        lu[o + r * m + c] = v;
+        S[r * m + c] = sum;
+      }
+    }
+    let maxEntry = 0;
+    for (let k = 0; k < m * m; k++) maxEntry = Math.max(maxEntry, Math.abs(lu[o + k]));
+    if (maxEntry === 0) return 0;
+    let minPivot = Infinity;
+    for (let k = 0; k < m; k++) {
+      let best = k, bestVal = Math.abs(lu[o + k * m + k]);
+      for (let r = k + 1; r < m; r++) {
+        const v = Math.abs(lu[o + r * m + k]);
+        if (v > bestVal) { best = r; bestVal = v; }
+      }
+      piv[offX[i] + k] = best;
+      if (best !== k) {
+        for (let c = 0; c < m; c++) {
+          let t = lu[o + k * m + c];
+          lu[o + k * m + c] = lu[o + best * m + c];
+          lu[o + best * m + c] = t;
+          t = S[k * m + c];
+          S[k * m + c] = S[best * m + c];
+          S[best * m + c] = t;
+        }
+      }
+      const sum = S[k * m + k];
+      if (bestVal <= 1e-18 * sum || bestVal === 0) {
+        const size = sum > 0 ? 1e-15 * sum : 1e-15 * maxEntry;
+        bestVal = size;
+        lu[o + k * m + k] = lu[o + k * m + k] < 0 ? -size : size;
+        this.perturbedPivots++;
+      }
+      if (bestVal < minPivot) minPivot = bestVal;
+      const inv = 1 / lu[o + k * m + k];
+      for (let r = k + 1; r < m; r++) {
+        const f = (lu[o + r * m + k] *= inv);
+        if (f !== 0) {
+          const af = Math.abs(f);
+          for (let c = k + 1; c < m; c++) {
+            lu[o + r * m + c] -= f * lu[o + k * m + c];
+            S[r * m + c] += af * S[k * m + c];
+          }
+        }
+      }
+    }
+    return minPivot / maxEntry;
+  }
+
   /**
    * Solve with the current factorisation. `rhs` and `out` are Float64Arrays of length `size`
    * (node-major); they may be the same array.

package/src/checks.js

@@ -29,6 +29,11 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   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.
+ * - **order** (a steady state, with `refine` and `order`, the defaults): the device solved from
+ *   its definition twice, its species listed as given and in reverse, which must give the same
+ *   steady state (each terminal's voltage and current, each species' amount). A solve that
+ *   depends on the listing has converged somewhere that isn't steady without noticing (round 11's
+ *   fuzzer found it in ~1% of random reacting devices, by exactly this test).
  * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
  *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
@@ -37,12 +42,12 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   (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]
+ * @param {{ refine?: boolean, tol?: number, order?: boolean }} [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, sol, { refine = true, tol = 1e-2 } = {}) {
+export function check(device, sol, { refine = true, tol = 1e-2, order = true } = {}) {
   sol ??= device.solution();
   const { model, solver, def } = device;
   const steady = sol.steady ?? solver.atSteady;
@@ -66,8 +71,17 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
   // The rest checks a solution, which an unconverged state isn't.
   if (sol.converged) {
     const ledger = steady ? balance(device, sol) : null;
+    // A reaction the steady state needs at equilibrium, left far from it (too slow to see: the
+    // solution warns of it), isn't steady, however quietly its ledgers sum: "equilibrium" was
+    // printed beside that warning.
+    const stuck = steady ? solver.stuckReactions() : [];
+    if (ledger && stuck.length > 0) {
+      ledger.ok = false;
+      ledger.summary = `not a steady state: ${stuck.map((s) => `${s.where} is ${sig(s.affinity * solver.VT * 1e3)} mV of affinity from equilibrium`).join(', ')}, too slow for the solve to see (see the warnings); its ledgers say only that nothing moves fast enough to count`;
+    }
     items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+    if (steady && refine && order && model.species.length > 1) items.push(orderCheck(device, sol, ledger.details.gross));
     // A transient's answer depends on its whole history (and on drives set along the way), so
     // only a run of its own on a finer grid can check it.
     else if (refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
@@ -110,9 +124,12 @@ function balance(device, sol) {
     else ledgers[l].terms.push({ what, rate });
   };
   const last = regions.length - 1;
+  // (A contact that blocks a species is no source of it: what its flux reads there is the end
+  // box's own imbalance, which the ledger must show, not balance.)
+  const through = (side, i) => model.contacts[side].species[i].type !== 'blocked';
   species.forEach((sp, i) => {
-    add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
-    add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
+    if (through('left', i)) add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
+    if (through('right', i)) add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
     model.ports.forEach((port, k) => add(i, port.region, `port ${sol.ports[k].name}`, sol.ports[k].flux[sp.name]));
   });
   model.reactions.forEach((rx, k) => {
@@ -259,8 +276,12 @@ function gridCheck(device, sol, tol, gross) {
   const diffs = [];
   // The current, against the largest current any species carries (so at open circuit, or in
   // equilibrium, round-off isn't read as a change).
-  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross);
-  if (gross > 0) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: unitsOf(model).current });
+  // A current too small for the ledgers to call moving (a diode at low bias: 1e-4 A/m² against
+  // majority carriers that could carry 6e8) is compared still, above a floor at 1e-16 of what the
+  // species could carry, above what solves resolve (~1e-19 of it in a GaAs junction).
+  const natural = naturalScales(device, sol), floorI = 1e-16 * FARADAY * Math.max(0, ...model.species.map((sp, i) => Math.abs(sp.z) * natural[i]).filter(Number.isFinite));
+  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross, floorI);
+  if (gross > 0 || Math.max(Math.abs(sol.current), Math.abs(other.current)) > floorI) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: unitsOf(model).current });
   // Floating terminals (driven by a current): their voltages, against the larger and the thermal voltage.
   const VT = model.RT / FARADAY;
   model.terminals.forEach((t, k) => {
@@ -307,6 +328,62 @@ function gridCheck(device, sol, tol, gross) {
   };
 }
 
+// The device solved from its definition with its species listed as given and in reverse: the
+// same steady state either way, or one of them isn't steady. (Both from the definition, not this
+// state, whose closed amounts a transient or set() may have moved from c0.)
+function orderCheck(device, sol, gross) {
+  const { def, model } = device;
+  const solveAt = (d) => {
+    const dev = new Device(d);
+    if (sol.time > 0) dev.solver.time = sol.time; // waveforms at the same time
+    return dev.solve();
+  };
+  let a, b;
+  try {
+    a = solveAt(def);
+    b = solveAt({ ...def, species: [...def.species].reverse() });
+  } catch (e) {
+    return { name: 'order', ok: null, summary: `could not solve the device with its species reversed (${e.message})` };
+  }
+  if (!a.converged || !b.converged) {
+    const which = a.converged ? 'listed in reverse' : b.converged ? 'listed as given' : 'listed either way';
+    return { name: 'order', ok: null, summary: `the device solved from its definition did not converge with its species ${which}: compare with a long advance() by hand` };
+  }
+  const VT = model.RT / FARADAY, diffs = [];
+  // (Currents only where the ledgers see something move: in equilibrium they're round-off of
+  // whatever exchanges fastest, an electrode's couple, and a wrong state shows in the voltages
+  // and amounts instead.)
+  // (and above 1e-16 of what the species could carry, as the grid check's floor: a drift at
+  // 1e-16 A/m², still moving at 1e12 s, isn't worth reporting)
+  const natural = naturalScales(device, sol), floorI = 1e-16 * FARADAY * Math.max(0, ...model.species.map((sp, i) => Math.abs(sp.z) * natural[i]).filter(Number.isFinite));
+  for (const [name, t] of Object.entries(a.terminals)) {
+    const u = b.terminals[name];
+    diffs.push({ what: `${name} voltage`, a: t.V, b: u.V, rel: Math.abs(u.V - t.V) / (1e-6 * Math.max(VT, Math.abs(t.V))), unit: 'V' });
+    if (gross > 0 && Math.max(Math.abs(t.current), Math.abs(u.current), gross) > floorI) diffs.push({ what: `${name} current`, a: t.current, b: u.current, rel: Math.abs(u.current - t.current) / (1e-3 * Math.max(Math.abs(t.current), Math.abs(u.current), gross)), unit: unitsOf(model).current });
+  }
+  const vol = model.grid.vol, amount = (s, name) => s.x.reduce((m, _, g) => m + (Number.isFinite(s.c[name][g]) ? vol[g] * s.c[name][g] : 0), 0);
+  const amounts = model.species.map((sp) => [sp.name, amount(a, sp.name), amount(b, sp.name)]);
+  const most = Math.max(0, ...amounts.map(([, x, y]) => Math.max(Math.abs(x), Math.abs(y))));
+  for (const [name, x, y] of amounts) diffs.push({ what: `${name} amount`, a: x, b: y, rel: Math.abs(y - x) / (1e-6 * Math.max(Math.abs(x), Math.abs(y)) + 1e-12 * most), unit: 'mol/m²' });
+  // Agreeing to near round-off (a µV, a millionth of an amount): ok. Within a thousand times that
+  // (a mV, a thousandth), enough for any plot, but a weakly held part of one solve not quite
+  // steady: look. Beyond: one of them isn't a steady state.
+  const worst = diffs.reduce((w, d) => (d.rel > (w?.rel ?? -1) ? d : w), null);
+  const ok = !(worst.rel > 1) ? true : worst.rel > 1e3 ? false : null;
+  const what = `${worst.what} ${sig(worst.a, 6)} → ${sig(worst.b, 6)} ${worst.unit}`;
+  return {
+    name: 'order',
+    ok,
+    summary:
+      ok === true
+        ? 'the same steady state with the species listed in reverse'
+        : ok === null
+          ? `listed in reverse, the species give nearly the same steady state (${what}): not to round-off, so some weakly held part is not quite steady in one of them`
+          : `listed in reverse, the species give a different steady state: ${what}. One of them is not steady, though its solve converged: compare with a long advance(), and please report the device.`,
+    details: { diffs },
+  };
+}
+
 // Charge density at a node of region r, C/m³: the species plus the region's fixed charge.
 function rho(s, g, model, r) {
   let q = model.regions[r].fixedCharge ?? 0;

package/src/describe.js

@@ -49,6 +49,10 @@ export function unitWarnings(def) {
     if (c > 1e6) warn(path, `${num(c)} mol/m³ is over 1000 M; concentrations are mol/m³ (units.molar, and units.perCm3 for carriers)`);
   };
   (def.species ?? []).forEach((sp, i) => sp?.cRef !== undefined && conc(`species[${i}].cRef`, sp.cRef));
+  // SRH's n₁ is a concentration too (a value per cm³ typed in is 6e5 times too large)
+  (def.bulkReactions ?? []).forEach((rx, k) => {
+    for (const [m, law] of Object.entries(isObject(rx?.srh) ? rx.srh : {})) if (isObject(law) && law.n1 !== undefined) conc(`bulkReactions[${k}].srh.${m}.n1`, law.n1);
+  });
   for (const [mname, mat] of Object.entries(def.materials ?? {})) {
     if (!isObject(mat)) continue;
     const path = `materials.${mname}`;
@@ -92,13 +96,19 @@ export function unitWarnings(def) {
   };
   const kinetics = (path, reactions) => {
     (reactions ?? []).forEach((rx, k) => {
-      if (rx?.k0 > 10) warn(`${path}.reactions[${k}].k0`, `${num(rx.k0)} mol/(m²·s) is an exchange current of ${num(rx.k0 * FARADAY)} A/m² per electron; k0 is mol/(m²·s)`);
+      // (an exchange current only where electrons take part: an ion transfer's k0 can be large)
+      const said = rx?.equation ?? (rx?.left || rx?.right ? JSON.stringify([rx.left, rx.right]) : null);
+      const electrons = said === null || /(^|[^\w])e-($|[^\w])/.test(said);
+      if (rx?.k0 > 10 && electrons) warn(`${path}.reactions[${k}].k0`, `${num(rx.k0)} mol/(m²·s) is an exchange current of ${num(rx.k0 * FARADAY)} A/m² per electron; k0 is mol/(m²·s)`);
     });
   };
   (def.interfaces ?? []).forEach((f, k) => {
     if (!isObject(f)) return;
     capacitance(`interfaces[${k}].phi.C`, f.phi?.C);
-    kinetics(`interfaces[${k}]`, f.reactions);
+    // (an exchange current is an electrode's: a metal on one side, or sides not yet known; a
+    // splitting exciton's k0, between two semiconductors, is a velocity times cRef)
+    const sides = [def.regions?.[k], def.regions?.[k + 1]].map((r) => (isObject(r) ? def.materials?.[r.material] : undefined));
+    if (sides.some((m) => m === undefined || isObject(m?.conductor))) kinetics(`interfaces[${k}]`, f.reactions);
   });
   (def.ports ?? []).forEach((p, k) => {
     if (!isObject(p)) return;
@@ -149,7 +159,12 @@ export function describe(def) {
       return;
     }
     const parts = [mat.epsr > 0 ? `εr ${mat.epsr}` : 'strictly neutral (ε = 0)'];
-    if (reg.fixedCharge !== 0) parts.push(`fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(Math.abs(reg.fixedCharge) / FARADAY)}`);
+    // (donors and acceptors where there are electrons; an ion exchanger's charge in mol/m³)
+    const doped = species.some((sp, i) => mat.present[i] && (sp.name === 'e-' || sp.name === 'h+'));
+    if (reg.fixedCharge !== 0) {
+      const X = Math.abs(reg.fixedCharge) / FARADAY;
+      parts.push(doped ? `fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(X)}` : `fixed charge ${reg.fixedCharge > 0 ? '+' : '−'}${num(X)} mol/m³`);
+    }
     // The screening concentration: Σ z²c from the initial composition, plus the carriers that
     // balance the fixed charge (doping), which c0 doesn't list.
     let zzc = 0, q = reg.fixedCharge / FARADAY; // q: the charge c0 leaves unbalanced
@@ -216,8 +231,34 @@ export function describe(def) {
     const cdef = def.contacts?.[side];
     const ct = model.contacts[side];
     const linked = species.filter((sp, i) => ct.species[i].type !== 'blocked').map((sp) => sp.name);
-    const term = ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
-    lines.push(`  ${side}: ${drive(cdef, model.geometry.type === 'planar')}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
+    // (a bath without a reference species: its V is its φ)
+    const term = ct.she && !ct.she.reference ? ' (terminal: the bath φ)' : ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
+    // A bath read through a reference species: where the SHE level sits against its terminal,
+    // so a held electrode's V reads on the familiar scale (a Cl⁻ reference on table μ° puts it
+    // 1.37 V below, a surprise to anyone expecting 0 V to mean SHE).
+    let she = '';
+    if (ct.she?.reference) {
+      const d = ct.she.shift, at = Math.abs(d) < 5e-4 ? 'V' : `V ${d < 0 ? '−' : '+'} ${Math.abs(d).toFixed(3)} V`;
+      she = ct.she.exact ? `; the bath's SHE level is at ${at}` : `; the bath's φ is at ${at} (on the usual tables' μ°, where μ°_H⁺ = 0, that's its SHE level)`;
+    }
+    lines.push(`  ${side}: ${drive(cdef, model.geometry.type === 'planar')}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}${she}`);
+    // An outside phase out of equilibrium with a reaction that runs at the contact: the reaction
+    // then runs there for ever, a current at zero bias (H⁺ and OH⁻ given off Kw in a bath, say).
+    const end = regions[side === 'left' ? 0 : regions.length - 1].material;
+    model.reactions.forEach((rx, k) => {
+      if (!(rx.kf[end] > 0) || rx.kfProfile[end]) return; // (light, a profile, is meant to drive)
+      const parts = [...rx.reactants.map(({ i, nu }) => [i, -nu]), ...rx.products.map(({ i, nu }) => [i, nu])];
+      const level = (i) => {
+        const l = ct.species[i];
+        return l.type !== 'equilibrium' ? NaN : species[i].z === 0 ? l.mu : l.offset === undefined ? NaN : species[i].z * FARADAY * l.offset;
+      };
+      // A/RT from the outside's levels (the terminal voltage cancels: Σ ν z = 0)
+      const a = rx.fixedA - parts.reduce((sum, [i, nu]) => sum + nu * level(i), 0) / RT;
+      if (Math.abs(a) > 1e-3) {
+        const rdef = def.bulkReactions[k];
+        warnings.push(`contacts.${side}: the outside isn't in equilibrium with bulkReactions[${k}] (${rdef.equation ?? equation(rdef.nu)}; A = ${num(a)} RT there), so it runs at the contact for ever, a current even at zero bias. Unless that's meant (a source), give the outside a composition in equilibrium with it (H⁺ and OH⁻ at √K_w, say)`);
+      }
+    });
   }
   (def.ports ?? []).forEach((p, k) => {
     const port = model.ports[k];