driftlet 0.9.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) | [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.9.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,9 +132,9 @@ 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 under a square wave, up to its limiting current |
+| **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) |
 | **Impedance**: the Warburg arc, and the cell's small-signal response inside | **Ion-exchange membrane**: Donnan steps, ion by ion, against TMS theory | **Double layer**: dilute vs crowded ions, against closed forms |
 | [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) | [![organic solar cell](demos/screenshots/organic.png)](https://markblundeberg.github.io/driftlet/demos/organic.html) | [![perovskite hysteresis](demos/screenshots/perovskite.png)](https://markblundeberg.github.io/driftlet/demos/perovskite.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

@@ -421,65 +421,74 @@ with the contact behind it holding the conductor's electrons (see
 ## Internal ports
 
 A port is an outside phase with known levels, like a contact's, attached to a window of nodes
-inside one region instead of at an end. It's the 1D stand-in for whatever feeds or drains a
-species sideways: source and drain grounding a MOS channel, salt injected mid-solution, a
-reference electrode's reservoir.
+inside one region instead of at an end: the 1D stand-in for whatever feeds, drains or charges the
+region sideways. It's a [terminal](#terminals) like a contact (held at `V`, behind `R`, or driven
+by `I`; a reference electrode is a port at `I: 0`), and in its window it does any of these, in
+any combination:
+
+| Field | What it adds | For |
+|---|---|---|
+| `species` | [levels held or exchanged](#levels-held-or-exchanged), per volume | source and drain grounding a channel, salt injected mid-solution, O₂ from the air |
+| `reactions`, `area` | an [electrode spread through the window](#electrodes-spread-through-a-window) | a thin film on a metal, a crevice, a porous electrode |
+| `surface` | [species on that electrode's sites](#an-electrodes-surface-adsorbates-and-passive-films) | adsorbates, a passive film |
+| `capacitance`, `area` | [charge held across a capacitance](#a-capacitance-through-a-window) | a gate along a channel, a double layer |
 
 ```js nocheck
 ports: [{
   name: 'channel',
   region: 'Si',              // name or index
   from: 495e-9, to: 500e-9,  // window, m from the region's left end (default: the whole region)
-  V: 0,                      // the port's terminal voltage (or I, or V and R: see terminals)
-  terminal: 'e-',
-  species: {
-    'e-': 'equilibrium',                         // μ̄ held at V_i = V + offset throughout the window
-    'Na+': { type: 'conductance', G: 1e9, offset: 0.2 }, // source G (V_out − V_i)/(zF) per volume, G in S/m³
-    O2: { type: 'exchange', k: 1e-3, mu: -2e3 },  // neutral: source k (μ_out − μ)/RT per volume, k in mol/(m³·s)
-  },
+  V: 0,                      // or I, or V and R (see terminals)
+  terminal: 'e-',            // the species whose level V is
+  species: { 'e-': 'equilibrium' },
 }]
 ```
 
-Links and offsets are those of contacts, per volume instead of per area: 0 by default only for
-the terminal species, and an absolute `mu` for neutral species. A port is a terminal like a
-contact: held at a voltage, behind a resistance, or driven by a current (a reference electrode
-is a port at `I: 0`). Each solution reports `ports[k]`, with `{ name, V, flux, current }`: what
-the port brings into the device.
-
-A held (`'equilibrium'`) level leaves the device's two end nodes to their contacts. A port that
-exchanges only neutral species carries no current, so its voltage means nothing: give it no drive.
-
-An exchange link's source is linear in $`\mu_{out} - \mu`$, so it grows without bound as the
-species runs out ($`\ln c`$). A supply limited by diffusion through a film above the window, such as O₂
-reaching a thin layer of water from the air, is linear in $`c`$ instead: $`k(c_{sat} - c)`$. For that,
-use a [bulk reaction](#bulk-reactions) with the outside phase as a fixed participant, e.g.
-`{ equation: 'Air = O2', fixed: { Air: muSat }, kf: { water: profile } }`. Its rate is
-$`k_f (1 - c/c_{sat})`$, and a profile gives $`k_f`$ its spatial variation (a film of thickness $`h(x)`$:
-$`D c_{sat}/h^2`$).
-
-A port driven by a current (`I`, or a waveform) floats to whatever voltage delivers it: with a
-conductance `G` per volume over a window of width $`w`$, it sits about $`I/(G w)`$ above the
-window's level for that species. So `G` decides how the current is shared across the window, not
-how much enters. A small `G`, with the port volts above the window, spreads it evenly, like a
-current source; a large one pins the window near the port's level, and the current enters
-wherever the species is drawn away fastest. At `I: 0` the port still ties that species' level
-together across its window (a large `G` shorts the window for it), so keep such windows narrow.
-
 On a [conductor region](#materials), a port is a wire to the whole conductor: it takes no window,
 only the conductor's carrier, and a conductance link's `G` is per area (S/m², a resistance
 $`R \cdot A`$ to the port's voltage as $`G = 1/(R \cdot A)`$). That's how a floating electrode is tied
 to ground through a resistor.
 
-For example, in a 1D MOS capacitor without generation, inversion electrons can only arrive by
-minority-carrier diffusion from the back contact, which can take weeks. The inversion layer is
-then effectively floating, and its Fermi level is undetermined to within round-off, so no
-steady state can be computed there. A port holding the electrons beside the oxide at the
-channel's potential anchors it, as source and drain would, and the device then shows the
-low-frequency C–V.
+### Levels held or exchanged
+
+```js nocheck
+species: {
+  'e-': 'equilibrium',                                // μ̄ held at V_i = V + offset throughout the window
+  'Na+': { type: 'conductance', G: 1e9, offset: 0.2 }, // source G (V_out − V_i)/(zF) per volume, G in S/m³
+  O2: { type: 'exchange', k: 1e-3, mu: -2e3 },         // neutral: source k (μ_out − μ)/RT per volume, k in mol/(m³·s)
+}
+```
+
+Links and offsets are those of contacts, per volume instead of per area: 0 by default only for
+the terminal species, and an absolute `mu` for neutral species. A held (`'equilibrium'`) level
+leaves the device's two end nodes to their contacts. A port that exchanges only neutral species
+carries no current, so its voltage means nothing: give it no drive.
+
+A port driven by a current floats to whatever voltage delivers it: with a conductance `G` per
+volume over a window of width $`w`$, about $`I/(G w)`$ above the window's level for that species. So
+`G` decides how the current is shared across the window, not how much enters. A small `G` spreads
+it evenly, like a current source; a large one pins the window near the port's level, and the
+current enters wherever the species is drawn away fastest. At `I: 0` the port still ties that
+species' level together across its window (a large `G` shorts the window for it), so keep such
+windows narrow.
+
+An exchange link's source is linear in $`\mu_{out} - \mu`$, so it grows without bound as the
+species runs out ($`\ln c`$). A supply limited by diffusion through a film above the window, such
+as O₂ reaching a thin layer of water from the air, is linear in $`c`$ instead: $`k(c_{sat} - c)`$. For
+that, use a [bulk reaction](#bulk-reactions) with the outside phase as a fixed participant,
+`{ equation: 'Air = O2', fixed: { Air: muSat }, kf: { water: profile } }`, whose rate is
+$`k_f (1 - c/c_{sat})`$; a profile gives $`k_f`$ its spatial variation ($`D c_{sat}/h^2`$ under a film
+of thickness $`h(x)`$).
+
+A held level can also anchor what nothing else holds. In a 1D MOS capacitor without generation,
+inversion electrons can only arrive by minority-carrier diffusion from the back contact (weeks),
+so the inversion layer's Fermi level is undetermined to within round-off and no steady state can
+be computed. A port holding the electrons beside the oxide, as source and drain would, anchors it,
+and the device shows the low-frequency C–V.
 
 ### Electrodes spread through a window
 
-A port can also hold an electrode: a metal whose carrier sits at the port's level, reacting all
+A port can hold an electrode: a metal whose carrier sits at the port's level, reacting all
 through the window rather than at one face. That's the floor under a thin film of electrolyte, the
 walls of a crevice or a pit, or the matrix of a porous electrode, wherever the metal conducts well
 enough to be one level. Give the port its `reactions` (Butler–Volmer, as at a face), the carrier as
@@ -499,28 +508,26 @@ ports: [{
 
 Each node's rate per area is the face's law, with the region's species at that node and the
 carrier at activity 1 and level $`V`$. Times the area per volume, it makes and consumes the
-region's species there, and the electrons it takes or gives are the port's current. The port is
-a terminal like any other. Held at a voltage, it's a potentiostat. At `I: 0` (or with nothing
-else to carry current), the reactions settle at the mixed potential, the corrosion potential where
-anodic and cathodic currents cancel over the window, while each node can be a net anode or a net
-cathode. A floating one starts there, for the start's composition. Each solution reports the
-window's nodes and every reaction's rate at each: `ports[k].x[j]` (m) and `ports[k].area[j]`
-(m²/m³) for the window's node j, and `ports[k].rates[q][j]` for reaction q there (mol/(m²·s) of
-electrode, forward), so reaction first, then node. They're typed arrays (`Float64Array`), so
-`Array.from` them before mapping to anything but numbers. Per volume of the window it's
+region's species there, and the electrons it takes or gives are the port's current. Held at a
+voltage, the port is a potentiostat. At `I: 0` (or with nothing else to carry current), the
+reactions settle at the mixed potential, the corrosion potential where anodic and cathodic
+currents cancel over the window, while each node can be a net anode or a net cathode; a floating
+one starts there, for the start's composition (with a double layer, it starts uncharged and
+charges toward it). An electrode that's the device's only path for current is at `I: 0` whatever
+its drive: hold it at `V: 0`, which also fixes the level the water's φ is read against. Per volume of the window a rate is
 `rates[q][j] * area[j]`, and per area of a film's floor (thickness h, `area` 1/h) the rate itself.
 
-Validated against the transmission line (linear kinetics along a bar, test/ports.test.js) and the
-Wagner–Traud mixed potential of two Butler–Volmer couples. In 1D, a film on a metal is a slice
-along the metal: the film's thickness enters through `area`, and through a bulk reaction for
-anything that reaches the film from above (O₂ from the air, see the exchange link above). Where
-the film's thickness varies, give the device its [cross-section](#geometry) too, so that ions
+In 1D, a film on a metal is a slice along the metal: the film's thickness enters through `area`,
+and through a bulk reaction for anything that reaches the film from above (O₂ from the air, see
+above). Where the thickness varies, give the device its [cross-section](#geometry) too, so that ions
 travelling along the film squeeze through where it thins: for a drop on a metal, seen from its
-centre, $`A = 2\pi r\,h(r)`$ with `area` $`1/h(r)`$.
+centre, $`A = 2\pi r\,h(r)`$ with `area` $`1/h(r)`$. The region must be strictly neutral
+($`\varepsilon = 0`$), as in porous-electrode theory: each spot's double layer is below the grid, so
+the reactions can't leave the solution charged (give the port a
+[capacitance](#a-capacitance-through-a-window) for the double layer's charge).
 
-The region must be strictly neutral ($`\varepsilon = 0`$), as in porous-electrode theory: each spot's
-double layer, the metal's countercharge, is below the grid, so the reactions can't leave the
-solution charged.
+Validated against the transmission line (linear kinetics along a bar, test/ports.test.js) and the
+Wagner–Traud mixed potential of two Butler–Volmer couples.
 
 ### An electrode's surface: adsorbates and passive films
 
@@ -538,7 +545,7 @@ ports: [{
   surface: { 'Fe(OH)2': { mu0: -490e3, capacity: 2e-5, theta0: 1e-6 } }, // theta0: the start
   reactions: [
     { equation: 'Fe2+ + 2 e- = Fe(s)', fixed: { 'Fe(s)': 0 }, k0: 5e-6, alpha: 0.5, bare: true },  // dissolves where bare
-    { equation: 'Fe(s) + 2 OH- = Fe(OH)2 + 2 e-', fixed: { 'Fe(s)': 0 }, k0: 1e-6, alpha: 0.5, bare: true }, // the film forms
+    { equation: 'Fe(s) + 2 OH- = Fe(OH)2 + 2 e-', fixed: { 'Fe(s)': 0 }, k0: 1e-4, alpha: 0.5, bare: true }, // the film forms (in minutes)
     { equation: 'O2 + 2 H2O + 4 e- = 4 OH-', fixed: { H2O: -237.13e3 }, k0: 3e-9, alpha: 0.125 }, // on film or not
   ],
 }]
@@ -546,35 +553,39 @@ ports: [{
 
 A film forms where the potential and the pH favour it, through its own thermodynamics, and blocks
 what needs bare metal: the dissolution current climbs with potential, peaks, and falls as the film
-covers the metal, the active–passive curve. Each node's surface stores
-$`\Gamma\,d\theta/dt`$ per area of electrode, so filling it passes a current, and a solution reports
-`ports[k].coverage[name][j]`. It's a monolayer picture: a real passive oxide is nanometres thick,
-grows, and breaks down under chloride, none of which a coverage has.
-
-Two cautions. Keep a film's stability within reason: blocking the bare fraction to 1e-3–1e-6 is
-already a passive metal, and far below that ($`\theta_0 \lesssim 10^{-10}`$) the coverage's η barely
-affects anything, so Newton struggles with it. And an electrode port has no double-layer
-capacitance (its solution is strictly neutral), so its potential follows its kinetics instantly.
-With a passivating film, current against potential has the active–passive peak, and when the
-last active patch covers over, the potential where no current flows can vanish from the active
-branch and must jump to the passive one. A real electrode makes that jump quickly but
-continuously, through its double layer; here it's a discontinuity, and a transient stops there.
-Give the port a [capacitance](#a-capacitance-through-a-window-a-gate-along-a-channel-a-double-layer) and the jump becomes a quick, continuous swing.
+covers the metal, the active–passive curve. Each node's surface stores $`\Gamma\,d\theta/dt`$ per area
+of electrode, so filling it passes a current, and what passes through a surface is conserved with
+it. It's a monolayer picture: a real passive oxide is nanometres thick, grows, and breaks down
+under chloride, none of which a coverage has.
+
+Cautions:
+- **Keep a film's stability within reason.** Blocking the bare fraction to 1e-3–1e-6 is already
+  a passive metal; far below that ($`\theta_0 \lesssim 10^{-10}`$) the coverage's η barely affects
+  anything and Newton struggles with it (a solution warns).
+- **A film's μ° is a fitted number.** A monolayer given a bulk hydroxide's ΔG°f passivates iron far
+  into neutral water, so choose it to put the passivation where the metal's chemistry does.
+- **Without a double layer, passivation can jump.** With no capacitance the potential follows the
+  kinetics instantly, and when the last active patch covers over, the potential where no current
+  flows can vanish from the active branch: a discontinuity, where a transient stops. Give the port
+  a [capacitance](#a-capacitance-through-a-window) and it's a quick, continuous swing, as on a real
+  electrode.
 
 Validated in test/coverage.test.js: the Langmuir isotherm against the electrode's potential (to
-1e-9), the charge to fill the surface, $`F\,\Gamma\,\Delta\theta`$ per area of electrode, and the
-active–passive curve with blocking exactly $`(1-\theta)`$ times Butler–Volmer.
+1e-9), filling against its exponential and its charge $`F\,\Gamma\,\Delta\theta`$ per area of electrode,
+the active–passive curve with blocking exactly $`(1-\theta)`$ times Butler–Volmer, and a steady state
+through a surface intermediate where the transient ends.
 
-### A capacitance through a window: a gate along a channel, a double layer
+### A capacitance through a window
 
 A port can hold charge across a capacitance spread through its window: per area of electrode,
 $`\sigma = C\,(V - \mathtt{zeroCharge} - \phi)`$ on the port's side (C in F/m²), with `area` per volume
 as for reactions, and the window holds the opposite. Each node's charge balance gains $`a\sigma`$:
-Gauss's law averaged across the section,
-$`-\partial_x(\varepsilon\,\partial_x\phi) = \rho + a\sigma`$, and at $`\varepsilon = 0`$ neutrality
-$`\rho + a\sigma = 0`$, the mobile species rearranging to supply it (counter-ions in, co-ions out).
-The port passes the charging current, $`d(\int a\sigma\,dV)/dt`$, none in a steady state. Solutions
-report `ports[k].sigma` at each node of the window and the total `ports[k].charge`.
+Gauss's law averaged across the section, $`-\partial_x(\varepsilon\,\partial_x\phi) = \rho + a\sigma`$,
+and at $`\varepsilon = 0`$ neutrality $`\rho + a\sigma = 0`$, the mobile species rearranging to supply
+it (counter-ions in, co-ions out). The port passes the charging current, $`d(\int a\sigma\,dV)/dt`$,
+none in a steady state. Capacitances on overlapping windows add (a channel's top and bottom
+gates). A capacitance alone, driven by a current, only charges: it starts uncharged, `advance()`
+follows it, and `solve()` refuses (there's no steady state, as for a gate contact driven by one).
 
 ```js nocheck
 // a thin-film transistor: the gate along a 10 nm channel through 1 mF/m² (35 nm of SiO₂)
@@ -583,15 +594,23 @@ 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
-for an axon's membrane, and a porous electrode's double layer, which lets an electrode port's
-potential move continuously: without it, a passivating film that covers the last active patch
-forces a jump (see above). 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.
+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.
 
 Validated in test/capacitance.test.js: a thin-film transistor's current against the
 charge-sheet model, $`I/W = (\mu/L)[(\sigma_s^2 - \sigma_d^2)/(2C) + V_T(\sigma_s - \sigma_d)]`$, from
@@ -599,6 +618,23 @@ below threshold through saturation (second order in the grid); a porous electrod
 impedance $`\sqrt{r/y}\coth(L\sqrt{ry})`$, the double layer in series with the ions' chemical
 capacitance; and the gate's low-frequency impedance against $`dQ/dV_G`$ from steady states.
 
+### What a solution reports
+
+Each solution's `ports[k]`, as the port has them:
+
+| Field | Contents |
+|---|---|
+| `name`, `V` | the port's name and voltage |
+| `flux[name]`, `current` | what it brings into the device: each species (mol/(m²·s)) and the current (A/m², the charging current included), totals through a [cross-section](#geometry) |
+| `x[j]`, `area[j]` | with reactions or a capacitance: the window's node j (m) and the electrode's area per volume there (m²/m³) |
+| `rates[q][j]` | reaction q's forward rate at node j, mol/(m²·s) of electrode (reaction first, then node) |
+| `coverage[name][j]`, `bare[j]` | with a surface: each species' coverage θ, and the bare fraction θ₀ to full precision |
+| `sigma[j]`, `charge` | with a capacitance: σ per area of electrode (C/m²), and the total the port's side holds |
+
+The arrays are typed (`Float64Array`), so `Array.from` them before mapping to anything but
+numbers. The kit's [`polarization()`](kit.md#polarization-curves-an-evans-diagram) gives each reaction's rate at a spot of the
+electrode with its level moved, an Evans diagram.
+
 ## Terminals
 
 The two contacts and every port are the device's terminals, named `left`, `right` and by each
@@ -610,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
@@ -620,7 +656,9 @@ ports: [{ name: 'ref', I: 0, ... },  // a reference electrode: no current, its v
   the voltage floats and is solved for.
 - **`V` and `R`**: a source behind a resistance, $`I = (V - V_{\mathrm{terminal}})/R`$.
 
-At least one terminal must be held at a voltage, or the device's overall level floats. In
+At least one terminal must be held at a voltage, or the device's overall level floats, and if
+one is driven by a current, a held one must pass current (a closed end held at a voltage fixes
+nothing). In
 steady state the terminal currents sum to zero. A contact can be driven by a current only if
 something passes it (a linked species, or a gate's displacement).
 
@@ -675,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
@@ -687,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
@@ -701,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,
@@ -774,7 +820,7 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `terminals[name]` | `{ V, current }` for each terminal (contacts and ports), current into the device |
 | `contacts.left/right` | `{ V, flux: {name}, D, current }` at each contact |
 | `gates.left/right` | charge on a gate or Stern plate, where the contact is capacitive |
-| `ports[k]` | `{ name, V, flux: {name}, current }`: what each internal port brings into the device |
+| `ports[k]` | `{ name, V, flux: {name}, current }`: what each internal port brings into the device; an electrode's rates, coverages and charge [as well](#what-a-solution-reports) |
 | `interfaces[f]` | `{ left, right, dipole, sheetCharge, D, N: {name}, rates }`: the names of the regions the face joins, what crosses it by its links, and each face reaction's rate (mol/(m²·s)) |
 | `bulkReactions[k]` | `{ rate, regions, total }`: each bulk reaction'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)), as the balances count it: a charge-balance check is J = F(generation − recombination), which the kit's `check()` does for every species |
 | `charge` | total charge in the device, C/m² (C through a cross-section) |

package/docs/kit.md

@@ -133,6 +133,11 @@ the SHE level (`sol.phi` with the usual tables' ions).
 
 The example above ends with the left electrode's curve.
 
+An electrode port's surface is held too by default. With `{ surface: 'equilibrium' }` (a fifth
+argument) its coverages are re-equilibrated at each V instead, each species by the reaction that
+makes it from the solution: the steady-state curve, where a passive film's active–passive peak
+shows (`curve.bare` gives the bare fraction along it).
+
 Concentrations are held, so these are the curves of that instant (for a mixed potential, the
 kinetic picture). Away from the actual level the composition beside the electrode would change,
 which is the transport the full solve accounts for.