driftlet 0.10.0 → 0.12.0

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.12.0/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) |
@@ -152,6 +141,27 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | **Intercalation host**: cycling between cutoffs against the OCV | **Organic solar cell**: excitons diffusing to a donor/acceptor interface, against theory | **Perovskite hysteresis**: mobile ions and scan rate, against IonMonger |
 | [![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 |
+| [![action potential](demos/screenshots/axon.png)](https://markblundeberg.github.io/driftlet/demos/axon.html) | [![propagation](demos/screenshots/propagation.png)](https://markblundeberg.github.io/driftlet/demos/propagation.html) | [![myelin](demos/screenshots/myelin.png)](https://markblundeberg.github.io/driftlet/demos/myelin.html) |
+| **Action potential**: Hodgkin and Huxley's gated channels, each ion's driving force through the spike, against the HH equations | **Propagation**: a spike travelling along an axon at HH's speed, out of the ions' drift; which ions carry it | **Myelin**: saltatory conduction, node to node, against a compartmental cable; a race with a bare axon |
+
+## 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), [action-potential](https://markblundeberg.github.io/driftlet/demos/axon.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); voltage-gated channels with Hodgkin–Huxley kinetics, action potentials, and their propagation along an axon ([`gates`](test/gates.test.js), [`cable`](test/cable.test.js) tests) | GHK potential and current–voltage curve; a resolved lipid layer; Mullins–Noda; the pump's static head; Donnan; HH gating under voltage clamp; the space-clamped HH equations |
+
+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
 
@@ -247,6 +257,8 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Schottky barrier (metal region \| n-Si) | surface density from the alignment; depletion charge | 5e-3; 2% |
 | Charged pore or nanochannel (resolved Donnan layers at each mouth) | conductance against salt, down to its plateau, as Teorell–Meyer–Sievers in a long pore (short ones short by end layers ∝ 1/L); the zero-current voltage across a salt gradient; a symmetric pore's I–V odd, rectification with charge on one side or bipolar | 1%; 5e-3 to 1e-4; 1e-9 |
 | Cell membrane (a capacitive face with permeabilities) | GHK resting potential (neutral or resolved solutions) and current–voltage curve; the same as a resolved 5 nm lipid layer; charging at I/C; with the Na⁺/K⁺ pump in a closed cell, Mullins–Noda, the static head 3Δμ̄_Na − 2Δμ̄_K = ΔG_ATP, and Donnan with the pump off | 1e-5 V; 3e-3; 2e-5 V; 1%; 1e-9 |
+| Voltage-gated channels (Hodgkin–Huxley gates on a membrane face) | each gate at α/(α + β) under a voltage clamp, and relaxing at α + β after a step; a squid axon's action potential against the space-clamped HH equations with GHK currents; its impedance at rest (inductive, resonant) against the linearised equations | 1e-12; 2e-4; 1 mV; 5e-4 |
+| A propagating action potential (a squid axon along x: gated membrane port, ions drifting in the axoplasm) | rest at HH's −65 mV and gate values; conduction velocity against the cable equation solved directly, and HH's 18.8 m/s; a myelinated axon's saltatory conduction, node by node, against a compartmental cable | 0.01 mV, 1e-4; 2e-3; 1%; 1 µs of ~25 per node |
 | Liquid junctions in mixtures | Henderson's formula against JPCalc's published values; driftlet's steady junction against Planck by shooting and the stationary Nernst–Planck codes LJPcalc and JLJP, a patch pipette's K-gluconate among them; a free-diffusion junction constant in time, between the two | 0.015 mV; 2e-4 and 0.02 mV; 5e-3 mV |
 | Liquid junction, open circuit | cell EMF 2t₊(RT/F) ln(c₁/c₂); Planck diffusion potential | 1e-4 |
 | Salt diffusion mode from a `c0` profile | c̄ + a·sin(πx/2L) decaying at π²D/4L², D = 2D₊D₋/(D₊ + D₋) | 2e-5 |
@@ -260,12 +272,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 +296,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 +319,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

@@ -277,6 +277,68 @@ read from `sol.phi` (or a `'phi'` probe in a transient). A bath contact's termin
 its reference species' level instead, what an electrode reversible to that species would read,
 so between two different solutions it differs from $`\Delta\phi`$ by that species' Nernst term.
 
+### Voltage-gated channels
+
+A permeability can be gated, as Hodgkin and Huxley's Na⁺ and K⁺ channels are: the face lists its
+`gates`, each a fraction $`x`$ in [0, 1] with first-order kinetics in the voltage across the face,
+$`V = \phi_{\mathrm{right}} - \phi_{\mathrm{left}}`$ at its two edge nodes,
+
+```math
+\frac{dx}{dt} = \alpha(V)\,(1 - x) - \beta(V)\,x ,
+```
+
+and a link names the gates that scale its $`P`$ (or a conductance link's $`G`$), with their exponents:
+$`P\,m^3 h`$ for `{ m: 3, h: 1 }`. (A membrane along a region instead, an axon's, is a
+[port](#a-membrane-through-a-window-gated-channels).)
+Each of $`\alpha`$ and $`\beta`$ is one of NeuroML's three standard forms, with `rate` in 1/s and `midpoint`
+and `scale` in volts:
+
+| `type` | rate |
+| --- | --- |
+| `'exp'` | $`\mathtt{rate}\; e^{(V - \mathtt{midpoint})/\mathtt{scale}}`$ |
+| `'sigmoid'` | $`\mathtt{rate} / (1 + e^{(\mathtt{midpoint} - V)/\mathtt{scale}})`$ |
+| `'expLinear'` | $`\mathtt{rate}\; y/(1 - e^{-y})`$, $`y = (V - \mathtt{midpoint})/\mathtt{scale}`$ |
+
+With the outside on the left, $`V`$ is the membrane potential $`\phi_{\mathrm{in}} - \phi_{\mathrm{out}}`$. Hodgkin and
+Huxley's squid axon (at their 6.3 °C):
+
+```js nocheck
+{
+  phi: { type: 'capacitive', C: 0.01 },
+  gates: {
+    m: { alpha: { type: 'expLinear', rate: 1000, midpoint: -0.040, scale: 0.010 }, beta: { type: 'exp', rate: 4000, midpoint: -0.065, scale: -0.018 } },
+    h: { alpha: { type: 'exp', rate: 70, midpoint: -0.065, scale: -0.020 }, beta: { type: 'sigmoid', rate: 1000, midpoint: -0.035, scale: 0.010 } },
+    n: { alpha: { type: 'expLinear', rate: 100, midpoint: -0.055, scale: 0.010 }, beta: { type: 'exp', rate: 125, midpoint: -0.065, scale: -0.080 } },
+  },
+  species: {
+    'Na+': { type: 'permeability', P: 1.16e-6, gates: { m: 3, h: 1 } },
+    'K+': { type: 'permeability', P: 1.33e-6, gates: { n: 4 } },
+    'Cl-': { type: 'permeability', P: 6.4e-9 }, // the leak
+    'A-': 'blocked',
+  },
+}
+```
+
+The gates scale permeabilities and nothing else: they hold no charge (the small gating current
+of the channels' voltage sensors is left out, as Hodgkin and Huxley left it out), and each ion
+still crosses by electrodiffusion down its own $`\bar\mu`$, so the dissipation stays positive whatever
+they do. In steady state each gate is at $`\alpha/(\alpha + \beta)`$; each solution reports them as
+`interfaces[f].gates` (`{ m, h, n }`) with the voltage they follow, `interfaces[f].V`.
+
+Two things differ from the textbook equations. The currents are GHK's, which rectify: a channel's
+conductance depends on the voltage, so a permeability matches a conductance $`g`$ at one voltage
+only (above, the chord conductances at rest, −65 mV, for Hodgkin and Huxley's 120, 36 and 0.3
+mS/cm²; matched at the reversal potentials instead, the rest depolarises itself and the axon
+fires on its own). And a cell without a pump has no resting steady state: `solve()` finds its
+Donnan equilibrium, every permeant ion level across the membrane, which the real cell reaches
+only over hours. Start a transient from the concentrations given (it settles to rest within
+milliseconds), or keep the gradients with the Na⁺/K⁺ pump on the same face. Started from the
+same state, a squid axon's action potential follows the space-clamped Hodgkin–Huxley equations
+with GHK currents to within 1 mV; and in small signals, with the membrane held at rest between
+two baths, `impedance()` gives the gates' inductance that Cole measured (the impedance inductive
+below ~50 Hz and resonant near 60 Hz), the linearised equations' to 5e-4
+([`gates`](../test/gates.test.js) test).
+
 ### Faces next to a conductor
 
 A conductor has no $`\phi`$, so a face beside it can't take a `dipole` or `step` alignment. Its $`\phi`$
@@ -432,6 +494,7 @@ any combination:
 | `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 |
+| `gates` | [voltage-gated channels](#a-membrane-through-a-window-gated-channels) on its conductance links | an axon's membrane along it |
 
 ```js nocheck
 ports: [{
@@ -594,10 +657,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.
@@ -608,6 +681,44 @@ 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.
 
+### A membrane through a window: gated channels
+
+A port with a capacitance can carry [gates](#voltage-gated-channels), as a face can: at each node of
+its window, each gate is a fraction open with Hodgkin–Huxley kinetics in the voltage across the
+port's capacitance there, $`V_m = \phi - (V - \mathtt{zeroCharge})`$, and its conductance links name
+the gates that scale them (`G × m³h`). That's a membrane all along a region, between it and an
+outside held by the port: an axon's, with x running along the axon. Per volume of axoplasm, a
+cylinder of radius a has $`2/a`$ of membrane (`area`); held at `V: 0` with `zeroCharge: 0`, the port's
+V is the outside's $`\phi`$, and a charged species' `offset` is its level there against that,
+$`(\mu^\circ + RT\ln(c_{out}/c_{\mathrm{ref}}))/(zF)`$. A conductance link's current is then
+$`G\,(V_{i,out} - V_i)`$, which is $`g\,a_m (E_i - V_m)`$: Hodgkin and Huxley's linear channel, with $`E_i`$ the
+Nernst potential at the inside's concentration there.
+
+```js nocheck
+ports: [{
+  name: 'membrane', region: 'axon', V: 0, terminal: 'K+', area: 2 / 238e-6, // a squid giant axon
+  capacitance: { C: 0.01, zeroCharge: 0 },
+  gates: hodgkinHuxley({ /* … */ T }).gates,
+  species: {
+    'Na+': { type: 'conductance', G: 1200 * 2 / 238e-6, offset: offsetNa, gates: { m: 3, h: 1 } },
+    'K+': { type: 'conductance', G: 360 * 2 / 238e-6, offset: offsetK, gates: { n: 4 } },
+    'Cl-': { type: 'conductance', G: 3 * 2 / 238e-6, offset: offsetCl }, // the leak
+  },
+}]
+```
+
+With the axoplasm strictly neutral and the outside held (no resistance outside), the ions'
+drift along x and the membrane's charging are cable theory, without its being put in: a squid
+axon's action potential propagates at Hodgkin and Huxley's speed, 18.73 m/s for their 18.5 °C
+axon (they computed 18.8 by hand), the cable equation's own to 2e-3
+([`cable`](../test/cable.test.js) test). A myelinated axon is regions of one axoplasm, each node
+of Ranvier and each internode its own, with a port each: the nodes' gated, the internodes' a small
+capacitance (myelin) and nothing else. The grid refines at every node's faces, and the spike jumps
+node to node, arriving at each within 1 µs of a compartmental cable's prediction (the same test).
+Each solution's `ports[k]` reports the gates at each node of the window, `gates[name][j]`,
+and the voltage they follow, `Vm[j]`. A gated window can't overlap another port's gated or
+surfaced one.
+
 ### What a solution reports
 
 Each solution's `ports[k]`, as the port has them:
@@ -620,6 +731,7 @@ Each solution's `ports[k]`, as the port has them:
 | `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 |
+| `gates[name][j]`, `Vm[j]` | with gates: each gate's fraction open, and the voltage across the capacitance that they follow (V) |
 
 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
@@ -636,7 +748,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 +815,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 +828,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,22 +843,30 @@ 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,
   mol/m³) or species voltage (`'V'`), or $`\phi`$ itself (`'phi'`, no species), linearly between the
-  nodes around `x` (at an interface, `region` picks the side). That's what a detector at `x` sees. Probes read at accepted steps, which grow
+  nodes around `x` (at an interface, `region` picks the side). That's what a detector at `x` sees.
+  At a face, `{ interface: f, species }` reads a species' flux through it (mol/(m²·s), toward +x,
+  as `interfaces[f].N`), and `{ interface: f, gate }` a gate's fraction open. Probes read at accepted steps, which grow
   as a transient slows, so give `dtMax` to resolve a signal in time.
 - `impedance(frequencies, { terminal, profiles })` solves the steady state, then linearises about
   it: $`Z(f) = \delta V/\delta I`$ in Ω·m² at one terminal (`'right'` by default), with I into the

package/docs/kit.md

@@ -142,6 +142,18 @@ Concentrations are held, so these are the curves of that instant (for a mixed po
 kinetic picture). Away from the actual level the composition beside the electrode would change,
 which is the transport the full solve accounts for.
 
+## Channels
+
+**`hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names })`**: Hodgkin and Huxley's
+squid-axon channels for a [membrane face](device.md#voltage-gated-channels) with the outside on its
+left: `{ gates, species }`, the face's `gates` (m, h and n, their 1952 rates at 6.3 °C scaled to
+`T` by Q₁₀ = 3) and links for Na⁺ (P·m³h), K⁺ (P·n⁴) and the leak (one ion, `leak`, of charge
+`leakZ`: Cl⁻ by default). The currents are GHK's, which rectify, so each permeability is the one
+whose chord conductance at `at` (−65 mV) is HH's `g` (120, 36 and 0.3 mS/cm²) at the
+concentrations given. Spread it into the face beside its $`\phi`$ law, adding the other species'
+links: `{ phi: { type: 'capacitive', C: 0.01 }, gates: hh.gates, species: { ...hh.species, 'A-': 'blocked' } }`.
+`ghkCurrent(z, inside, outside, V, T)` is the GHK current (outward, A/m²) at unit permeability.
+
 ## Sources
 
 Helpers that write sources as plain data: