driftlet 0.10.0 → 0.11.4

package/README.md

@@ -13,35 +13,24 @@ to be the engine of live, thermodynamically honest web demos of charge transport
 semiconductors, electrochemical cells, membranes and solid ionic conductors. It handles any mix
 of charged and neutral species, Poisson electrostatics (or strict neutrality), bulk and
 interfacial reactions, heterointerfaces, metals and external circuits, in steady state, in time
-and as small-signal impedance. Every physics feature is validated against analytic results, and
-it's small enough to run in a web page: no dependencies, millisecond solves.
+and as small-signal impedance. It's small enough to run in a web page: no dependencies,
+millisecond solves.
 
 [Live demos](https://markblundeberg.github.io/driftlet/demos/) · [npm](https://www.npmjs.com/package/driftlet) ·
 [reading level diagrams](docs/visualization.md) · [device reference](docs/device.md) ·
 [agent guide](llms.txt)
 
+**Built to be relied on.** A drift–diffusion solver that handles a textbook pn junction is a
+weekend's work; one that keeps working on the devices people actually build is not. driftlet is
+tested two ways: every physics feature against an analytic result or an independent code, and
+thousands of randomly generated devices (junctions, MOS capacitors, solar cells, electrolyte
+cells, electrodes) put through cold solves, sweeps, transients and impedance, every result
+checked. A solve that fails reports it, with what went wrong where it can tell.
+[How far to trust it](docs/reliability.md) has the details, the numbers and the known limits.
+
 **Status: 0.x.** Released on npm and used by the demos, but the API may still change between
 minor versions.
 
-## Is it for your problem?
-
-The same equations go by different names in different fields. If your problem is one-dimensional
-(planar, or radial: spheres and cylinders, or any cross-section varying along x), it's probably here:
-
-| If you work on | you may call it | start from | checked against |
-|---|---|---|---|
-| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions; thin-film transistors (gradual channel, in the [saturation demo](https://markblundeberg.github.io/driftlet/demos/saturation.html#transistor)) | [first example](#a-semiconductor-junction), [pn](https://markblundeberg.github.io/driftlet/demos/pn.html) and [MOS](https://markblundeberg.github.io/driftlet/demos/mos.html) demos, [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
-| Solar cells | photogeneration, radiative and SRH recombination | [solar](https://markblundeberg.github.io/driftlet/demos/solar.html) [organic (excitons)](https://markblundeberg.github.io/driftlet/demos/organic.html) and [perovskite (mobile ions)](https://markblundeberg.github.io/driftlet/demos/perovskite.html) demos, [`ionmonger`](test/ionmonger.test.js), [`reactions`](test/reactions.test.js) and [`generation`](test/generation.test.js) tests: generation is a reaction from a photon reservoir (uniform, or Beer–Lambert with `photogeneration()`), SRH as a rate law, in the bulk and at faces | `J_sc = qG(L_n + L_p + W)`; J_sc under Beer–Lambert against collection theory; Shockley J–V in the dark |
-| Electrochemistry, corrosion | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions, mixed potentials, electrodes under a film | [second example](#an-electrochemical-cell), [cyclic voltammetry](https://markblundeberg.github.io/driftlet/demos/redox.html), [Daniell cell](https://markblundeberg.github.io/driftlet/demos/daniell.html), [saturation](https://markblundeberg.github.io/driftlet/demos/saturation.html), [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js), [`junction`](test/junction.test.js), [`ports`](test/ports.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg; junction potentials against Henderson, Planck, JPCalc and LJPcalc; Wagner–Traud |
-| Batteries, intercalation | OCV, insertion hosts, chemical diffusion | [insertion demo](https://markblundeberg.github.io/driftlet/demos/insertion.html), [`statistics`](test/statistics.test.js) test | composition vs OCV, π²D/4L² relaxation |
-| Double layers, colloids | Poisson–Boltzmann, Gouy–Chapman–Stern, Debye screening, crowding (Bikerman) | [double-layer demo](https://markblundeberg.github.io/driftlet/demos/double-layer.html), [`equilibrium`](test/equilibrium.test.js) test | Gouy–Chapman charge and profile, Kilic–Bazant–Ajdari |
-| Membranes, desalination | Donnan, ion exchange, liquid junctions, water dissociation | [membrane demo](https://markblundeberg.github.io/driftlet/demos/membrane.html), [`equilibrium`](test/equilibrium.test.js), [`neutral`](test/neutral.test.js) tests | Donnan partition, Planck EMF |
-| Solid-state ionics | mixed ionic–electronic conduction, defect chemistry, mobile ions | [`statistics`](test/statistics.test.js), [`reactions`](test/reactions.test.js) tests | mass action from standard potentials |
-| Biophysics, nanofluidics | charged nanochannels and pores, resting potentials, Goldman–Hodgkin–Katz, Nernst, Donnan, pumps and leaks | [charged-nanochannel](https://markblundeberg.github.io/driftlet/demos/channel.html), [resting-potential](https://markblundeberg.github.io/driftlet/demos/cell.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) (a patch pipette's) demos, [`pore`](test/pore.test.js) test; a membrane as a face: a capacitor with ion permeabilities, and the Na⁺/K⁺ pump as a reaction on it ([`membrane`](test/membrane.test.js) test) | GHK potential and current–voltage curve; a resolved lipid layer; Mullins–Noda; the pump's static head; Donnan |
-
-The tests are worked setups, each with its analytic check, so they double as recipes. The
-[validation table](#validation) lists them all.
-
 ## Install
 
 ```sh
@@ -55,7 +44,7 @@ import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG str
 ```
 
 Or straight from a CDN in a page, pinned to a version:
-`https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.11.4/src/index.js` (and `src/kit.js`, `src/plot.js`).
 TypeScript declarations ship in the package. Writing a demo with an LLM agent? Point it at
 [`llms.txt`](llms.txt).
 
@@ -143,7 +132,7 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | | | |
 |---|---|---|
 | [![pn junction](demos/screenshots/pn.png)](https://markblundeberg.github.io/driftlet/demos/pn.html) | [![solar cell](demos/screenshots/solar.png)](https://markblundeberg.github.io/driftlet/demos/solar.html) | [![MOS capacitor](demos/screenshots/mos.png)](https://markblundeberg.github.io/driftlet/demos/mos.html) |
-| **pn junction**: quasi-Fermi levels under bias; I–V against Shockley | **Solar cell**: J<sub>sc</sub> and V<sub>oc</sub> against collection theory | **MOS capacitor**: band bending; C–V against ideal theory |
+| **pn junction**: quasi-Fermi levels under bias; I–V against Shockley | **Solar cell**: J<sub>sc</sub> and V<sub>oc</sub> against collection theory | **MOS capacitor**: band bending; C–V at any frequency, low to high |
 | [![cyclic voltammetry](demos/screenshots/redox.png)](https://markblundeberg.github.io/driftlet/demos/redox.html) | [![Daniell cell](demos/screenshots/daniell.png)](https://markblundeberg.github.io/driftlet/demos/daniell.html) | [![saturation](demos/screenshots/saturation.png)](https://markblundeberg.github.io/driftlet/demos/saturation.html) |
 | **Cyclic voltammetry**: a Fermi level against a redox level | **Daniell cell**: a real salt bridge, leaking, ion by ion | **Saturation**: Ag \| AgNO₃ \| Ag up to its limiting current, and a thin-film transistor pinching off, against the charge-sheet model |
 | [![impedance](demos/screenshots/impedance.png)](https://markblundeberg.github.io/driftlet/demos/impedance.html) | [![ion-exchange membrane](demos/screenshots/membrane.png)](https://markblundeberg.github.io/driftlet/demos/membrane.html) | [![double layer](demos/screenshots/double-layer.png)](https://markblundeberg.github.io/driftlet/demos/double-layer.html) |
@@ -153,6 +142,25 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | [![charged nanochannel](demos/screenshots/channel.png)](https://markblundeberg.github.io/driftlet/demos/channel.html) | [![resting potential](demos/screenshots/cell.png)](https://markblundeberg.github.io/driftlet/demos/cell.html) | [![liquid junctions](demos/screenshots/junction.png)](https://markblundeberg.github.io/driftlet/demos/junction.html) |
 | **Charged nanochannel**: selectivity, overlapping Donnan layers and rectification, against Teorell–Meyer–Sievers | **Resting potential**: leaks and the Na⁺/K⁺ pump, against Mullins–Noda; the run-down to Donnan | **Liquid junctions**: a patch pipette's against Henderson, Planck and LJPcalc; a charged frit |
 
+## Is it for your problem?
+
+The same equations go by different names in different fields. If your problem is one-dimensional
+(planar, or radial: spheres and cylinders, or any cross-section varying along x), it's probably here:
+
+| If you work on | you may call it | start from | checked against |
+|---|---|---|---|
+| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions; thin-film transistors (gradual channel, in the [saturation demo](https://markblundeberg.github.io/driftlet/demos/saturation.html#transistor)) | [first example](#a-semiconductor-junction), [pn](https://markblundeberg.github.io/driftlet/demos/pn.html) and [MOS](https://markblundeberg.github.io/driftlet/demos/mos.html) demos, [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
+| Solar cells | photogeneration, radiative and SRH recombination | [solar](https://markblundeberg.github.io/driftlet/demos/solar.html) [organic (excitons)](https://markblundeberg.github.io/driftlet/demos/organic.html) and [perovskite (mobile ions)](https://markblundeberg.github.io/driftlet/demos/perovskite.html) demos, [`ionmonger`](test/ionmonger.test.js), [`reactions`](test/reactions.test.js) and [`generation`](test/generation.test.js) tests: generation is a reaction from a photon reservoir (uniform, or Beer–Lambert with `photogeneration()`), SRH as a rate law, in the bulk and at faces | `J_sc = qG(L_n + L_p + W)`; J_sc under Beer–Lambert against collection theory; Shockley J–V in the dark |
+| Electrochemistry, corrosion | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions, mixed potentials, electrodes under a film | [second example](#an-electrochemical-cell), [cyclic voltammetry](https://markblundeberg.github.io/driftlet/demos/redox.html), [Daniell cell](https://markblundeberg.github.io/driftlet/demos/daniell.html), [saturation](https://markblundeberg.github.io/driftlet/demos/saturation.html), [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js), [`junction`](test/junction.test.js), [`ports`](test/ports.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg; junction potentials against Henderson, Planck, JPCalc and LJPcalc; Wagner–Traud |
+| Batteries, intercalation | OCV, insertion hosts, chemical diffusion | [insertion demo](https://markblundeberg.github.io/driftlet/demos/insertion.html), [`statistics`](test/statistics.test.js) test | composition vs OCV, π²D/4L² relaxation |
+| Double layers, colloids | Poisson–Boltzmann, Gouy–Chapman–Stern, Debye screening, crowding (Bikerman) | [double-layer demo](https://markblundeberg.github.io/driftlet/demos/double-layer.html), [`equilibrium`](test/equilibrium.test.js) test | Gouy–Chapman charge and profile, Kilic–Bazant–Ajdari |
+| Membranes, desalination | Donnan, ion exchange, liquid junctions, water dissociation | [membrane demo](https://markblundeberg.github.io/driftlet/demos/membrane.html), [`equilibrium`](test/equilibrium.test.js), [`neutral`](test/neutral.test.js) tests | Donnan partition, Planck EMF |
+| Solid-state ionics | mixed ionic–electronic conduction, defect chemistry, mobile ions | [`statistics`](test/statistics.test.js), [`reactions`](test/reactions.test.js) tests | mass action from standard potentials |
+| Biophysics, nanofluidics | charged nanochannels and pores, resting potentials, Goldman–Hodgkin–Katz, Nernst, Donnan, pumps and leaks | [charged-nanochannel](https://markblundeberg.github.io/driftlet/demos/channel.html), [resting-potential](https://markblundeberg.github.io/driftlet/demos/cell.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) (a patch pipette's) demos, [`pore`](test/pore.test.js) test; a membrane as a face: a capacitor with ion permeabilities, and the Na⁺/K⁺ pump as a reaction on it ([`membrane`](test/membrane.test.js) test) | GHK potential and current–voltage curve; a resolved lipid layer; Mullins–Noda; the pump's static head; Donnan |
+
+The tests are worked setups, each with its analytic check, so they double as recipes. The
+[validation table](#validation) lists them all.
+
 ## How to think about it
 
 driftlet insists on thermodynamically honest concepts ([conventions](docs/conventions.md)):
@@ -260,12 +268,12 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Time integration | BE first order, BDF2 second order; adaptive error control | ratios 2, 4 |
 | Advection and eddy mixing | exact convection–diffusion profile; `D + D_mix`; junction EMF unchanged by mixing | 1e-12; 1e-12; 1e-5 |
 | Metal regions | ohmic; Schottky face and MOS gate equal their contact forms; Ag \| AgNO₃ \| Ag with metal electrodes; bipolar electrode at V/2 | 1e-12; 1e-9; 1e-9; 1e-9 |
-| Internal ports | transmission line σV tanh(L/λ)/λ (O(h²)); held level; MOS low-frequency C–V with a grounded channel | 1e-4; 1e-9; 2e-3 |
+| Internal ports | transmission line σV tanh(L/λ)/λ (O(h²)); held level; MOS low-frequency C–V with a grounded channel, and without one the same equilibrium, and a gate step filling the inversion layer to it | 1e-4; 1e-9; 2e-3; 1e-6; 1e-3 |
 | Cross-sections (spherical, cylindrical, any A(x)) | steady diffusion to a sphere and a cylinder (exact on any grid); Cottrell with the spherical term; uptake by a sphere filling from its surface; Debye–Hückel around a charged sphere, potential and charge | 1e-10; 3e-4; 2e-4; 1e-3, 3e-4 |
 | A capacitance through a port | a thin-film transistor against the charge-sheet model (below threshold to saturation, second order); de Levie impedance; gate impedance against dQ/dV | 5e-4; 1e-3; 1e-6 |
 | Electrode surfaces (coverage) | Langmuir isotherm against potential; the charge to fill a surface; the active–passive curve, blocking exactly (1 − θ) | 1e-9; 1e-3; 1e-9 |
 | Electrodes spread through a port | transmission line with the reaction's linear kinetics as the conductance (O(h²)), rates along it; Wagner–Traud mixed potential of two Butler–Volmer couples, floating | 1e-4, 2e-3; 1e-6 V |
-| Impedance | Macdonald blocking-electrode spectrum, 100 Hz–1 GHz; finite-length Warburg (Ag \| AgNO₃ \| Ag); DC limit = differential resistance | 3e-4; 3e-5; 1e-6 |
+| Impedance | Macdonald blocking-electrode spectrum, 100 Hz–1 GHz; finite-length Warburg (Ag \| AgNO₃ \| Ag); DC limit = differential resistance; a p⁺n⁺ junction without recombination, Re Y → dI/dV and C = dQ/dV; a redox electrode against a bath at its open circuit, Re Y → dI/dV | 3e-4; 3e-5; 1e-6; 1e-4, 1e-6; 1e-4 |
 | Conservation | per step, and against time-integrated contact fluxes | 1e-11 relative |
 | Strictly neutral limit (ε = 0) | Planck EMF; polarization with no overlimiting; Donnan at neutral faces | 1e-5; 1e-4; 1e-9 |
 | Fermi–Dirac statistics | `𝓕_{±1/2}` vs quadrature; degenerate bulk; accumulation charge via `𝓕_{3/2}` | 1e-13; 1e-12; 1e-3 |
@@ -284,17 +292,17 @@ checked in CI; times are from a desktop Ryzen 7600X in Node 22:
 | Task | Time | Factorisations |
 |---|---|---|
 | Linear solve, 300 nodes × 7 unknowns (factor + solve) | 0.4 ms | 1 |
-| pn diode (264 nodes): cold equilibrium | 2 ms | 9 |
-| pn diode: I–V sweep 0 → 0.6 V, 31 points | 31 ms | 137 |
-| pn diode: warm jump from +0.4 V to −1 V | 7 ms | 51 |
-| pn diode: adaptive transient, 0 → 0.5 V, 100 ns | 150 ms | 1026 |
-| pn diode: impedance at 20 frequencies | 8 ms | 21 |
-| MOS with a metal gate: C–V sweep, 26 points | 11 ms | 126 |
-| n-Si \| KCl (4 species, 3 unknowns per node): Mott–Schottky sweep, 31 points | 29 ms | 156 |
-| n-Si \| KCl: impedance at 20 frequencies | 10 ms | 21 |
+| pn diode (264 nodes): cold equilibrium | 3 ms | 9 |
+| pn diode: I–V sweep 0 → 0.6 V, 31 points | 29 ms | 137 |
+| pn diode: warm jump from +0.4 V to −1 V | 8 ms | 51 |
+| pn diode: adaptive transient, 0 → 0.5 V, 100 ns | 165 ms | 926 |
+| pn diode: impedance at 20 frequencies | 14 ms | 21 |
+| MOS with a metal gate: C–V sweep, 26 points | 9 ms | 126 |
+| n-Si \| KCl (4 species, 3 unknowns per node): Mott–Schottky sweep, 31 points | 36 ms | 156 |
+| n-Si \| KCl: impedance at 20 frequencies | 16 ms | 21 |
 | Ag \| AgNO₃ \| Ag with double layers: sweep 0 → 0.1 V, 21 points | 12 ms | 81 |
-| Ag \| AgNO₃ \| Ag, neutral: adaptive transient over 1 s | 29 ms | 287 |
-| Silver electrodes with a bipolar plate: sweep 0 → 1 V, 11 points | 27 ms | 63 |
+| Ag \| AgNO₃ \| Ag, neutral: adaptive transient over 1 s | 24 ms | 186 |
+| Silver electrodes with a bipolar plate: sweep 0 → 1 V, 11 points | 25 ms | 54 |
 
 The library has no dependencies and does no DOM access, so it runs in a Web Worker. (A device
 definition is plain data and can be posted to a worker. Devices using custom-function
@@ -307,12 +315,14 @@ No dependencies. Tests use node's built-in runner (Node ≥ 22):
 ```sh
 npm test         # the validation suite
 npm run bench    # typical workloads against bench/baseline.json (--save to update it)
+npm run stress   # random devices, every result checked (--n 500 for more; see docs/reliability.md)
+npm run hard     # the corpus of once-hard cases against bench/hard.json
 npm run types    # TypeScript declarations from the JSDoc, into types/ (fetches TypeScript via npx)
 npm run smoke    # every demo in headless Chrome, every control to its extremes (CHROME=… to choose)
 npm run shots    # retake the demos' screenshots, each caught at a set state (tools/shots.js)
 ```
 
-Design notes and plans: [numerics](docs/numerics.md), [conventions](docs/conventions.md),
+Design notes and plans: [reliability](docs/reliability.md), [numerics](docs/numerics.md), [conventions](docs/conventions.md),
 [statistics](docs/statistics.md), [the kit](docs/kit.md), [reading level diagrams](docs/visualization.md),
 [data](docs/data.md), [roadmap](ROADMAP.md).
 

package/docs/device.md

@@ -594,10 +594,20 @@ ports: [{ name: 'gate', region: 'channel', V: 1.5, area: 1 / 10e-9, capacitance:
 ports: [{ name: 'iron', region: 'film', terminal: 'e-', V: 0, area: 1e4, capacitance: { C: 0.2, zeroCharge: -0.4 }, reactions: [/* … */] }]
 ```
 
+A volumetric capacitance $`C^*`$ (F/m³, an organic electrochemical transistor's) goes in per
+area of a nominal electrode: `area: 1 / t, capacitance: { C: Cstar * t }` for a film t thick
+(`area: 1, C: Cstar` is the same physics, but reads to `describe()` like a unit slip). To read the
+gate's voltage as the film's effective one, put the undisturbed film at φ = 0 (its carrier's
+`cRef` at its doping, `mu0: 0`) and leave `zeroCharge` at 0. The gate charges the carriers
+through their own chemical capacitance too, in series, so $`dQ/dV_G`$ comes out below $`C^*`$
+(about 12% for holes at 1e20 cm⁻³ against 40 F/cm³).
+
 That's the gradual-channel approximation of a field-effect transistor, exact for a thin film
 with no body (a TFT, an organic or oxide transistor) while the channel is long against the gate
 dielectric, and failing where it pinches off (where the 2D field takes over). It's also the
-Bernards model of an organic electrochemical transistor (a volumetric capacitance), cable theory
+Bernards model of an organic electrochemical transistor (a volumetric capacitance; the
+Bernards–Malliaras current is the charge-sheet formula below without its $`V_T`$ term, so they
+part near pinch-off, where driftlet keeps the diffusion that formula drops), cable theory
 for an axon's membrane, and a porous electrode's double layer. The gate's flat level pins the
 channel's standard level through C, as a blocked spectator's flat level does in an electrolyte,
 and the current saturates as the carriers run out at the drain, in both.
@@ -636,7 +646,7 @@ contacts: {
   right: { I: -2, ... },             // driven by a current into the device, A/m² (I: 0 is open circuit)
 },
 ports: [{ name: 'ref', I: 0, ... },  // a reference electrode: no current, its voltage read off
-        { name: 'wire', V: 0, R: 1e-3, ... }], // a source V behind a series resistance R (Ω·m²)
+        { name: 'wire', V: 0, R: 1e-3, ... }], // a source V behind a series resistance R (Ω·m², or Ω with a geometry)
 ```
 
 - **`V`**: the terminal's voltage, the shift of its outside phase's ladder, as the voltage of
@@ -703,7 +713,8 @@ its middle, and nothing passes the end. Only an end may have $`A = 0`$. Flow (`v
 planar devices.
 
 With a cross-section, the solution's currents, contact and port fluxes, terminal currents and
-`charge` are totals (A, mol/s; per metre for cylinders), and so are `I` drives. Face laws,
+`charge` are totals (A, mol/s; per metre for cylinders), and so are `I` drives, a series `R`
+and the impedance (Ω, not Ω·m²). Face laws,
 rates, `interfaces[f].N` and `D`, and concentrations stay per area or per volume. Validated against
 steady diffusion to a sphere and a cylinder (exact), Cottrell's transient with the spherical term,
 uptake by a sphere filling from its surface, and Debye–Hückel screening around a charged sphere
@@ -715,6 +726,7 @@ uptake by a sphere filling from its surface, and Debye–Hückel screening aroun
 const dev = new Device(def);
 const sol = dev.solve();                      // steady state (or equilibrium)
 dev.set({ contacts: { right: { V: 0.3 } } }); // deep-merged change; the state is kept as a warm start
+dev.set({ ports: { gate: { V: 0.2 } } });     // ports patched by name (an array replaces them all)
 const sol2 = dev.solve();
 const tr = dev.step(1e-6);                    // one backward-Euler step (auto-subdivided if needed)
 const tr2 = dev.step(1e-6, { method: 'bdf2' }); // second-order BDF2 once a previous step exists
@@ -729,17 +741,23 @@ const now = dev.solution();                   // snapshot of the current state
   amounts (blocked species, reactive moieties) are kept exactly. If a direct solve fails at a
   bias (a cold start far from equilibrium), it solves with both terminals level and ramps the
   right terminal's voltage to its target; with generation reactions (below), it ramps their
-  rates up from nearly nothing.
+  rates up from nearly nothing. A terminal driven by a current (open circuit, say) is held at a
+  voltage instead, the voltage marched until the current crosses its target, and floated from
+  there. If 20 V either way brings no crossing (a current beyond the limiting one), the solve
+  fails with a warning giving the range of currents the held voltages passed.
 - `step(dt, { method })` advances the transient by dt seconds, halving internally where Newton
   needs it. `method` is `'be'` (backward Euler, the default) or `'bdf2'`.
 - `advance(tEnd, opts)` integrates adaptively to `tEnd` with variable-step BDF2, controlling
   the local error per step to `tol` (default 1e-3) in thermal units of every potential ($`\phi`$ and
-  each $`\bar\mu/RT`$): roughly 0.1% in concentrations. It lands exactly on `tEnd`. Options: `tol`,
+  each $`\bar\mu/RT`$): roughly 0.1% in concentrations per step. That's local: over a long decay
+  the errors add up, and a small current at the end of one can be tens of percent off, so tighten
+  `tol` (1e-5, say) before fitting a time constant to a tail. It lands exactly on `tEnd`. Options: `tol`,
   `dt0` (first step), `dtMax`, `budgetMs` (return after this much wall time, with
   `done: false`), `maxSteps`, `method`. The step size carries over between calls, so an
   animation can call `advance(tNext, { budgetMs })` once per frame. The solution adds `done`,
   `rejected`, and a `trace` of terminal current and voltage after every accepted step (the
-  voltage is the right contact's minus the left's: what a meter between the terminals reads,
+  current is the right contact's, toward +x, as `sol.current`; a port's is in `sol.terminals`
+  after each call; the voltage is the right contact's minus the left's: what a meter between the terminals reads,
   which at a bath is its reference species' level, not $`\phi`$). With
   `probes: [{ x, species, quantity, region }]` the trace also reads inside the device,
   as `trace.probes[k]` beside `trace.t`: a species' concentration (`quantity: 'c'`, the default,

package/docs/numerics.md

@@ -420,6 +420,29 @@ instead of $`n \cdot M^3`$, which pays wherever species are confined to some reg
 against KCl, three unknowns of five at every node, it's a fifth of the work. A finite-difference
 test checks the compact Jacobian column by column on devices that cover every assembly path.
 
+### Exact J·v
+
+The assembled matrix loses what a flux's two entries share. A Scharfetter–Gummel flux depends on
+$`\eta`$ at its two ends through $`G`$ and $`-G(1 + E)`$, with $`E = \operatorname{expm1}(\Delta\eta)`$;
+for a nearly uniform $`v`$ they cancel, and $`J \cdot v`$ keeps only round-off of $`G|v|`$, which in
+an inversion layer's 0.1 nm cells ($`G`$ ~ 1e11) dwarfs the flux. Where a solve needs
+$`J \cdot v`$ itself (GMRES, in the impedance and in Newton's refined solves), the dilute kernels'
+terms are kept aside instead, each evaluated on differences first:
+
+```math
+\delta N = a\,(\delta\eta_L - z\,\delta\hat\phi_L) + b\,(\delta\eta_R - \delta\eta_L) + d\,(\delta\hat\phi_R - \delta\hat\phi_L),
+```
+
+with $`a = -GE`$ (through $`c_L`$), $`b = -G(1 + E)`$ and $`d`$ the drift's. A node's storage and space
+charge depend on $`\delta\eta_i - z_i\,\delta\hat\phi`$ alone, the displacement on
+$`\delta\hat\phi_R - \delta\hat\phi_L`$. Everything else (faces, contacts, ports, reactions,
+concentrated and metal regions) is assembled into a matrix of its own. Rows that a contact or a
+steady solve replaces drop the kept terms; the transformed rows of strictly neutral nodes combine
+them as they combine the matrix's. A region's uniform shift ($`z_i s`$ on each $`\eta_i`$, $`s`$ on
+$`\hat\phi`$) then gives exactly zero inside it, as it must. It replaced a central difference of
+the residual, whose truncation (~1e-9 of $`|J||v|`$) swamped the answer for such a shift, and
+which cost four assemblies per product.
+
 ## Newton
 
 - The update of the device's potentials ($`\hat\phi`$, $`\eta`$) is limited to 10 thermal units per
@@ -439,8 +462,37 @@ test checks the compact Jacobian column by column on devices that cover every as
   much reduced by the change of variables below), converges quadratically to ~1e-9 and then
   rattles there. Short steps come right after every waveform breakpoint, so without this a
   cyclic voltammogram in a neutral electrolyte stalled at its turns.
-- Clear divergence (device updates beyond 1e4, or ten times the first after six iterations)
-  bails out early, so the caller can take a smaller step.
+- **Refined solves, where the factorisation loses a mode.** The assembled $`J`$ holds a flux's
+  dependence on $`\eta`$ at its two ends as two entries; where they're huge, eliminating them loses
+  what they share to round-off. In a MOS capacitor's inversion layer the electrons' cells, 0.1 nm
+  wide, are coupled about $`h^2/(D\,dt)`$ ~ 1e-18 times more tightly than they store charge over a
+  second, so the layer's overall level, set by its storage and the trickle of minority electrons
+  from the bulk, is lost, and Newton's update there is noise. When Newton stalls short of
+  convergence (updates below 1e-4 that stopped shrinking quadratically), or its undamped updates
+  grow twice running (a bipolar stack's floating base, whose holes are held ~1e14 more weakly
+  than they move within it, kept Newton wandering a thermal unit at a time), the solve is refined:
+  GMRES on $`J\delta = r`$, the factorised system as the preconditioner and $`J \cdot v`$ exact, each
+  flux on its $`\eta`$ difference (see [exact J·v](#exact-jv)), as the impedance does. A lost mode
+  takes GMRES a couple of iterations. The refined update is kept where GMRES converged and it
+  moves no level by a thermal unit or more; otherwise refining stops for the rest of the solve.
+  A MOS capacitor's gate step now reaches the low-frequency charge in ~70 steps (it took 80,000,
+  and ended 1.5% off). Once refined, a solve stays refined: a GaAs junction without
+  recombination, whose minority carriers reach it only from the contacts, passes ~1.5e-7 A/m²,
+  which plain solves past the first refinement left to round-off (cold and warm solves 1e-3
+  apart), and refined ones give to 1e-14. (When $`J \cdot v`$ was a central difference of the
+  residual, its noise made refining past the first lost mode chase round-off, so it was kept
+  only where its correction dwarfed the plain update.)
+- Clear divergence (device updates beyond 1e4 after the first iteration, or ten times the
+  first after six) bails out early, so the caller can take a smaller step. The first update is
+  exempt: light flooding a population that starts at ~1e3 per m³ predicts, linearised in
+  $`\eta`$, a change of 1e10 thermal units, which damping covers in a few iterations; bailing
+  out there had a lit phototransistor's pseudo-transient fail at every step above 1e-21 s.
+- A pivot that cancels to exactly zero in the block factorisation is perturbed to 1e-15 of its
+  block's largest entry (static pivoting) rather than failing the solve. GaAs minority carriers,
+  ~1 per m³ beside a face, are held through conductances 1e-16 of the face flux's coefficient in
+  their row, and the elimination cancels them exactly: such devices now solve, even at
+  equilibrium. Newton's updates stay meaningful (the factorisation only amplifies the residual,
+  so a small update still means a small residual), and its refined solves correct the rest.
 - When a steady solve fails, the solution's warnings say how nearly singular the system was,
   and where. A running error bound through the factorisation compares each pivot with the
   magnitudes it was formed from, $`\log_{10}(\sum|\mathrm{terms}| / |\mathrm{pivot}|)`$: the digits
@@ -481,6 +533,13 @@ test checks the compact Jacobian column by column on devices that cover every as
     $`C_c = h^3(1+\omega)^2/(\omega(1+2\omega))`$ and $`C_p = h(h+h_1)(h+h_1+h_2)`$; linear after
     backward Euler, scaled by $`h/(2h + h_1)`$. The first step, with no history, is checked by step
     doubling.
+  - A first step whose error doesn't shrink with it is taken anyway. A jump in a level held at a
+    boundary (a bath's, after a voltage step) starts a profile self-similar in $`x/\sqrt{t}`$, so a
+    first step of any length errs alike (0.11 thermal units over ten decades of step, in a
+    0.6 M electrolyte with resolved double layers), down to the grid's own diffusion time,
+    where Newton runs out of digits. Three tries in a row, each within a factor 2 of the last,
+    mark the error as the jump's; backward Euler damps it as it should, and the steps grow
+    from there. Transients that start with a jump take 5–30% fewer factorisations for it.
   - The state a first step starts from needn't satisfy the algebraic equations ($`\hat\phi`$ in a
     strictly neutral material, an interface's unknowns), after a start or a jump; they jump in
     the first instant. So the history starts from the first step's half step, not from there,
@@ -497,9 +556,9 @@ test checks the compact Jacobian column by column on devices that cover every as
     current it cost 50% more.
   - A step is rejected above `tol`. The next step size is
     $`h \cdot \min(2, \max(0.2, 0.9\, (\mathtt{tol}/\mathrm{err})^{1/(p+1)}))`$.
-  - Newton failure quarters the step; on the first step after a start or a jump in a device
-    with a strictly neutral material, longer steps are tried first, since there shorter ones are
-    worse conditioned.
+  - Newton failure quarters the step. (Strictly neutral materials had tried longer first steps
+    instead, shorter ones being worse conditioned there; with their ends and starts fixed, no
+    case needs it.)
   - A target within round-off of the present time (1e-10 relative), such as an animation
     frame's that lands a hair past a breakpoint just reached, is snapped to rather than
     stepped to: a step of 1e-13 s can't be resolved.
@@ -533,15 +592,42 @@ species make $`J`$ singular, but $`J + i\omega M`$ isn't for $`\omega > 0`$: at
 device looks like a capacitor, as it should.
 
 The factorised system is used as a preconditioner, not trusted alone: each solve runs GMRES with
-$`J \cdot v`$ taken from the residual itself, by a central difference ($`\eta`$ perturbed in the
-state's low word, $`\hat\phi`$ and the face unknowns in the high one). The assembled $`J`$ holds a
-flux's dependence on $`\eta_L`$ and $`\eta_R`$ as two entries; in an inversion layer both are huge
-(~1e11), and for a nearly uniform $`\delta\eta`$ they cancel to round-off of order 1e-5, while the
-residual takes the $`\eta`$ difference first, in double-double. That round-off had given a MOS
-capacitor's inversion layer, fed by minority diffusion from a bulk with ~1e3 electrons per cm³ (a
-time constant of minutes), an exchange path that followed the gate at 1 Hz. Where the plain solve
-is already accurate, one application of the operator confirms it; the bench's impedance cases
-take about twice as long as before.
+an exact $`J \cdot v`$ (see [exact J·v](#exact-jv)). The assembled $`J`$ holds a flux's dependence
+on $`\eta_L`$ and $`\eta_R`$ as two entries; in an inversion layer both are huge (~1e11), and for a
+nearly uniform $`\delta\eta`$ they cancel to round-off of order 1e-5. That round-off had given a
+MOS capacitor's inversion layer, fed by minority diffusion from a bulk with ~1e3 electrons per cm³
+(a time constant of minutes), an exchange path that followed the gate at 1 Hz. Where the plain
+solve is already accurate, one application of the operator confirms it. GMRES judges convergence only by the true residual,
+recomputed at each restart: its own running estimate can drift far from it where the
+preconditioner is nearly singular (an inversion layer's exchange, lost in the assembled
+$`J`$, at a frequency of µHz), and had declared solves converged that weren't. It keeps its
+best iterate, never worse than the factorised solve.
+
+The current is read where its error is smallest. At a contact it is a sum of terms that can
+be far larger than itself: across a junction without recombination, between heavily doped
+sides, what passes is minority carriers of ~1e8 per m³, while the contact's terms are its
+majority conductances times a $`\delta\eta`$ cancelling its neighbours' to 1e-17, and their
+round-off reads as a constant conductance of order 1 S/m², a silicon p⁺n⁺ junction's capacitance
+9× off at 100 Hz. Between the two contacts of a device without ports, the total current
+(conduction plus displacement, $`i\omega\,\delta D`$) is the same through every cut, so it is also
+read across each segment of an ideal region, linearised as the Scharfetter–Gummel flux is, and
+the reading with the least estimated error is taken: in that junction, the depletion region's;
+in a MOS capacitor, the oxide's displacement. A reading's error is its terms' round-off, and the
+solves' error in $`\delta x`$ (their residual, relative to its largest entry) through its
+coefficients: a contact's reading is a flux too (a held contact's balance row is replaced by its
+level, so nothing solved pins it), and in a neutral bulk the current crosses a huge conductance
+on a tiny gradient.
+
+Where even the best reading's estimated error exceeds 1% of the current, the response is split
+in two: a uniform shift of each region (every $`\eta_i`$ by $`z_i s_r`$ and $`\hat\phi`$ by $`s_r`$, with
+$`s_r`$ fitted to the solve so far), which changes no flux and no concentration, so its $`J \cdot e`$ is
+exactly zero inside each region and is taken at the faces and ends;
+and the rest, small, solved for to GMRES's floor with its error now relative to itself, and read
+separately. An electrolyte at its open circuit needs it: the response to its terminal is nearly
+such a shift, and its current is the slope of levels uniform to 1e-14 of the response, more than
+a double holds. A redox electrode's DC conductance had come out 2–40% low; now it matches the
+steady dI/dV to six digits. (Not with ports, whose exchange sees the shift.) The real part of a nearly ideal capacitor, 1e-7 of $`|Z|`$, is still
+only resolved to ~1e-4 of $`|Z|`$.
 
 ## Steady state
 
@@ -550,6 +636,28 @@ take about twice as long as before.
   because slow physics can take seconds, far beyond any $`L^2/D`$ estimate, and stepping would
   never finish. An example is exponentially scarce minority carriers slowly filling an inversion
   layer behind a Schottky contact.
+- **A flat level,** where a stretch's steady state is known outright: a species that no reaction
+  or port touches, reached by one contact only (blocked at the other end), carries no flux in a
+  steady state, so its level is that contact's throughout. Steady solves (not the impedance,
+  where it carries a current) pin it there in place of its balances, rather than find it
+  through its own conduction, which can be all but nothing: a MOS capacitor's inversion
+  electrons reach the back contact only through a bulk with ~1e3 of them per cm³, and found that
+  way, the solve converged at some gate voltages and grids and not others. (Not through flow or
+  mixing, nor a concentrated material's cross-diffusion, where zero flux isn't a flat level.)
+  At a face inside such a stretch whose link holds the level continuous, the face's flux of the
+  species, which only the replaced edge balances set, is pinned to zero too.
+- **Continuation for a terminal driven by a current.** A cold steady solve at open circuit can
+  fail where the same state is easy warm (a solar cell in dim light on a fine grid). The
+  terminal is held at a voltage instead, its steady solves having their own continuation, and
+  the voltage marched from the start's, the step growing, until the current crosses its target:
+  up where the current is below it, since raising a terminal's voltage raises the current into
+  a passive device (the other way if 20 V brings no crossing). Bisection narrows the crossing
+  to 0.1 mV, and the terminal is floated from beside it. Floated, the system can lose what held
+  it doesn't (a closed Fe³⁺/Fe²⁺ cell driven near its limit, Fe³⁺ 20 orders below Fe²⁺: 33 digits
+  short), but the current-driven steady state is the held one at the voltage that passes the
+  target, so where the floated solve fails, held solves find that voltage instead, by regula
+  falsi within the bracket, to 1e-10 of the current. The voltage continuation's own start,
+  with the terminals level, ramps the light up when there is some.
 - **Spectators** (a species blocked all round, mobile throughout its stretch) are solved
   directly too. In steady state the sum of a spectator's balance rows over its stretch is zero
   identically, so one of them (the first node's) is redundant, and it's replaced by the
@@ -557,7 +665,14 @@ take about twice as long as before.
   bordered: the matrix is factorised with a pin (an identity row) in its place, which makes the
   stretch's level a well-conditioned unknown, and the response to a unit pin (one extra
   back-substitution per spectator) is added in the amount that satisfies the constraint, from
-  a $`k \times k`$ system for $`k`$ spectators.
+  a $`k \times k`$ system for $`k`$ spectators. Within one ideal region (no flow or mixing), a
+  spectator's level is flat at steady state, at a value its amount fixes, so its other balance
+  rows are replaced by $`\eta_g - \eta_{g-1} = 0`$, rather than found through its own conduction.
+  Past a closed zinc cell's limiting current, extended space charge at the cathode excludes the
+  blocked sulfate to ~1e-25 mol/m³, and the chain of conductances through it had lost the steady
+  system 14 digits: steady solves failed from 0.7 V, and took 37,000 iterations at 0.6 V. (Not
+  across a face: the rows that would hold the level there and pin its flux leave a diagonal
+  block singular.)
 - **Conserved combinations** (moieties) of reacting stretches are solved the same way: the
   total iron of Fe³⁺, Fe²⁺ and FeCl²⁺ in a closed cell with a complexation reaction, say. The
   basis of combinations $`w`$ comes from the null space of the stoichiometry. In steady state the
@@ -571,6 +686,36 @@ take about twice as long as before.
   larger by $`D \cdot dt/(hL)`$, around 1e12 for a micron-scale cell (see
   [metal regions](#metal-regions) for the same cancellation). Newton then needs dozens of
   iterations, or fails.
+- **Islands**: the pieces of a stretch between its faces, where nothing else feeds a piece (no
+  contact, port or reaction). In steady state such a piece's level is held only through its
+  faces' fluxes, which can be far weaker than its own conduction: a face conductance of
+  1e-15 S/m² against a region conducting ~4e2 S/m, or neighbours that conduct 1e20 times less
+  than it. Eliminated, the level was lost to round-off below anything Newton could see (the
+  plain solves gave no update along it, so nothing stalled), and solves converged to a wrong one
+  silently: currents 2× or 16× off. Summed over the piece's nodes, its balance rows are its
+  faces' flux unknowns alone, $`A_R u_R - A_L u_L`$: the internal fluxes cancel exactly, by
+  construction rather than in round-off. Across a face that holds $`\bar\mu`$ level, $`u`$ is
+  set only by the edge balances, and eliminated it can come out of the piece's own, as
+  $`G\,\Delta\eta`$ with its two $`\eta`$ all but equal; so there the outside edge node's
+  balance is added too, $`u`$ cancels, and the outside's first segment carries the flux. (Seen
+  through one face of two, a level behind neighbours 1e20 times less conductive was overshot
+  twofold, and Newton swung it from one contact's level to the other's.) That sum can replace
+  the first node's row, bordered like a spectator's amount. The response to the unit pin is the island's uniform shift, with whatever
+  $`\hat\phi`$ and the other species do along with it, so no mode needs guessing; refined solves
+  carry the pinned rows too.
+
+  Newton exact along such a level can be worse than Newton blind to it, far from the solution
+  (cold at bias, a bipolar stack's floating base took 1e5 thermal units in its first update), so
+  the summed rows go in only once the plain solves converge. An island at the wrong level then
+  shows: it takes in a different current than it passes on, so the terminal currents don't add
+  up to zero (to 1e-9 of the largest). Newton then carries on with the summed rows, refined from
+  their second update. A current that tiny against the conduction around it rides on $`\eta`$
+  differences (~1e-28 for 5 fA/m² through 1e4 mol/m³ at D = 1e-4 m²/s) that the last update
+  leaves known only to its own round-off, so where the currents still don't add up, one more
+  update polishes them. If Newton doesn't converge again within a dozen updates (a GaAs stack's
+  minority carriers, whose own rows rest on static pivots, at 1e-17 A/m² of noise), the plain
+  solution stands; and a steady solve that fails outright is tried once more with the summed rows
+  in from the start. Such devices now solve directly, their currents right to ~1e-15.
 - **Immobile combinations** (trap states X⁰ and X⁻ under e⁻ + X⁰ = X⁻, with D = 0) conserve
   node by node, since nothing carries them anywhere. At each node the combination's weighted sum
   replaces one of its balance rows, kept at what it was when the solve began. The row is local
@@ -588,16 +733,26 @@ take about twice as long as before.
 - **Generation continuation.** A device with generation reactions (species made only from, or
   turned only into, fixed reservoirs, such as photogeneration from a photon reservoir) can be
   held far from equilibrium even with its terminals level, where bias continuation can't help.
-  If a direct solve fails there, the generation rates are scaled down to 10⁻¹² and ramped back
+  If a direct solve fails there, the generation rates are scaled down to 10⁻³⁰ and ramped back
   up, ×100 a step while each solve converges (warm from the last) and by the square root of the
-  factor when one doesn't. An illuminated 80 µm silicon diode solves cold this way in about 80
-  iterations.
+  factor when one doesn't, giving up when that factor falls below 1.5 (crawling, which time
+  steps do better); the pseudo-transient ramp then starts from the dimmer light's solution
+  rather than cold. (At 10⁻¹², a GaAs layer's generation still exceeded its equilibrium
+  recombination, ~3e-24 mol/m³ of minority electrons, a billionfold: the first step was the
+  whole jump.) An illuminated 80 µm silicon diode solves cold this way in about 80
+  iterations. (A lit n⁺pn stack with a floating base crawled for 20,000 iterations: at a
+  trillionth of the light, the base's level is held by couplings of ~1e-17.)
 - **If that fails too,** source continuation ramps the right terminal's voltage to its target.
   It ramps from the voltage of the last converged solve when the state is that solution, and
-  otherwise from level terminals, where a cold start is consistent. The ramp step starts at
+  otherwise from level terminals, where a cold start is consistent. (A device first solved
+  after a `set()` was laid out for its new voltages; if the level start fails from there, it's
+  laid out again, level, and retried.) The ramp step starts at
   1/8 of the way, grows ×1.5 on success and shrinks ×4 on failure.
 - **If Newton still fails,** $`dt`$ ramps up from a small value (pseudo-transient continuation),
-  ending in the direct solve where applicable.
+  ending in the direct solve where applicable. After a failed step it grows ×2, then ×1.5 more
+  each success, back to ×10. Once steps reach the slowest diffusion time, the direct solve is
+  tried from there, once a decade of $`dt`$ (the state kept if it fails): with immobile traps and
+  ions of D = 1e-17 m²/s, steps from 1e8 to 1e9 s kept failing on the way to the giant step.
 
 `solve()` does not advance the clock.
 
@@ -648,7 +803,11 @@ neutrality:
 - then storage (on the other balances) and neutrality go in, exactly, in those terms.
 
 A start-of-step net charge (round-off in a solved state) isn't carried over: the neutrality row
-holds the new state neutral. Steady solves and the impedance keep the plain rows (there's no
+holds the new state neutral. An end node that its contact holds (a bath, an electrode's level)
+keeps its plain rows, but the contact's current there is read before the ions' storage goes in,
+and a bulk law doesn't count the box's net charge as displacement: under neutrality neither
+carries charge, and read from the box's balance their round-off (∝ c/dt) cancelled only roughly.
+A bath floating on 1 µM beside 3 M KCl had rattled at 2e-5 thermal units on steps of 1e-14 s. Steady solves and the impedance keep the plain rows (there's no
 storage at $`dt = \infty`$, and the impedance reads the storage matrix from them).
 
 A sub-grid Gouy–Chapman law, treating the diffuse layers analytically when $`\lambda_D \ll h`$, is on