driftlet 0.5.0 → 0.7.0

package/README.md

@@ -31,13 +31,13 @@ The same equations go by different names in different fields. If your problem is
 | 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 | [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 runs through explicit trap species | `J_sc = qG(L_n + L_p + W)`; J_sc under Beer–Lambert against collection theory; Shockley J–V in the dark |
-| Electrochemistry | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions | [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) and [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg |
+| 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 | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions | [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) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg; junction potentials against Henderson, Planck, JPCalc and LJPcalc |
 | 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 | Poisson–Nernst–Planck, ion channels, membrane potentials | the electrochemistry setups, with fixed charge in the channel region | no dedicated check yet |
+| 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.
@@ -55,7 +55,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.5.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.7.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).
 
@@ -128,7 +128,9 @@ Solutions are plain objects of `Float64Array`s, ready to plot (fresh arrays from
 and the voltage views `V`, `Vstd`. They also carry the terminals' voltages and currents, fluxes,
 conservation bookkeeping and warnings; see [the device reference](docs/device.md). The
 [kit](docs/kit.md) adds reactions written as equations (`'Ag+ + e- = Ag(s)'`), redox levels,
-level diagrams, slider demos and `describe()`, which flags likely unit slips.
+level diagrams, slider demos, a transient recorder, `describe()` (which flags likely unit slips),
+`check()` (a solution's ledgers and a grid-convergence check),
+and curated devices with reference results: IonMonger's perovskite cell, with its J–V scans.
 
 ## Demos
 
@@ -147,7 +149,9 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | [![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) |
-| **Intercalation host**: cycling between cutoffs against the OCV |  |  |
+| **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 |
 
 ## How to think about it
 
@@ -236,9 +240,12 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Beer–Lambert photogeneration in an n⁺p cell | J_sc = qΦ∫αe^(−αx)η(x)dx with the emitter's, depletion layer's and base's collection, α from 1e3 to 1e7 /m on one coarse grid | 5e-4 (3e-3 in the emitter) |
 | Organic bilayer: excitons | J_sc from excitons diffusing to the donor/acceptor interface (Beer–Lambert, a blocking anode, the splitting reaction's finite velocity); V_oc from charge-transfer detailed balance | 5e-4; 1e-6 V |
 | SRH recombination | bulk: G = R_SRH(n, p) with n = N_D + p, midgap and shallow traps, low to high injection; at a face: zero in the dark, the law between the two edge nodes, every pair collected or recombined | 1e-6; 1e-9 |
-| Perovskite J–V hysteresis, against IonMonger | an independent code (finite elements, Octave): mobile iodide vacancies, interface SRH, scans from 1 mV/s to 1 kV/s — hysteresis index, P_max, V_oc, the whole loop | 1.5e-3; 0.05 mW/cm²; 2 mV; 0.3 mA/cm² |
+| Perovskite J–V hysteresis, against IonMonger | an independent code (finite elements, Octave): mobile iodide vacancies, interface SRH, scans from 1 mV/s to 1 kV/s — hysteresis index, P_max, V_oc, the whole loop (as current where it's gentle, as a voltage offset near V_oc, where it falls at up to 1100 mA/cm² per volt) | 1.5e-3; 0.05 mW/cm²; 2 mV; 0.03 mA/cm² and 1 mV (0.010 and 0.31 mV found) |
 | Illuminated long pn diode | `J_sc = qG(L_n + L_p + W)` from a cold start; superposition at low injection | 5e-3; 1e-2 |
 | 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 |
+| 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 |
 | Concentration polarization | `i = i_lim tanh(V/4V_T)`, incl. galvanostatic and load modes | 2e-4 |

package/docs/device.md

@@ -98,7 +98,8 @@ regions: [
 - `fixedCharge`: immobile charge density (doping, ionomer), C/m³. Default 0. In an insertion
   host it's balanced by background electronic carriers.
 - `c0`: initial concentrations, mol/m³: the starting state of each species given. Species
-  connected to a contact don't need it (without it, they start from that contact's level). Any
+  connected to a contact don't need it (without it, they start from that contact's level: the
+  left contact's if the species reaches it, else the right's, else a port's). Any
   other species (blocked everywhere, or only made and consumed by
   reactions) does: its `c0` fixes the amount it conserves. Concentrations are positive ($`\bar\mu`$ is
   logarithmic in them); to have none of a species in a region, leave it out of that region's
@@ -169,7 +170,8 @@ defaults to no dipole.
 
 **Species laws** `species` (default: local equilibrium, $`\bar\mu`$ continuous, where the species is
 present on both sides; blocked otherwise): `'equilibrium'`, `'blocked'`, or
-`{ type: 'conductance', G }` ($`J = G \cdot (V_L - V_R)`$, G in S/m², charged species). A species that
+`{ type: 'conductance', G }` ($`J = G \cdot (V_L - V_R)`$, G in S/m², charged species), or
+`{ type: 'permeability', P }` (P in m/s; see [membranes](#membranes)). A species that
 takes part in a reaction at the face and exists on both sides has no default: give its link
 (`'blocked'` if it crosses only through the reaction), since free crossing alongside would
 short-circuit the kinetics.
@@ -226,6 +228,54 @@ lies between the two sides (a band offset, a $`\phi`$ jump). Where one carrier i
 rate saturates at the other's capture, $`r \to v_p\,p`$: holes reaching an electron-rich layer
 recombine at $`v_p`$ however many electrons wait there, which plain mass action can't do.
 
+**Saturating kinetics** (a transporter, a pump, an enzyme: something that turns over at most so
+fast) replaces `k0` and `alpha` with `vmax` (mol/(m²·s)) and `K`, a half-saturation
+concentration (mol/m³) for every species the forward reaction consumes:
+
+```math
+r = v_{\max} \prod_{\nu<0} \left(\frac{c}{c + K}\right)^{|\nu|} \left(1 - e^{-A/RT}\right)
+```
+
+Michaelis–Menten in each substrate, it runs at $`v_{\max}`$ when they're plentiful and the driving
+force is large, and it's still exactly zero at $`A = 0`$, so a pump stalls where the free energy it
+spends is used up: its static head. The backward rate is the one detailed balance implies, and
+isn't itself saturating, so this is for reactions that run forward.
+
+### Membranes
+
+A membrane thin against everything else (a lipid bilayer, 4–5 nm) is a face. Give it a
+capacitive $`\phi`$ law, its capacitance (about 0.01 F/m², 1 µF/cm²), and a species law
+`{ type: 'permeability', P }` for each ion that crosses it, through channels or carriers. The
+flux is electrodiffusion across the membrane in a constant field (Goldman–Hodgkin–Katz),
+
+```math
+N = P\,\frac{z u\,(c_L - c_R\,e^{z u})}{e^{z u} - 1}, \qquad u = \frac{\phi_R - \phi_L}{V_T}
+```
+
+toward +x, with $`c_L`$ and $`c_R`$ at the face's two edge nodes and $`\phi_R - \phi_L`$ the capacitor's
+voltage. (It's Scharfetter–Gummel across the face, with $`D/h \to P`$; where the two sides are
+different materials, the step in standard level between them counts with $`z\Delta\phi`$, so the flux
+is still exactly zero where $`\bar\mu`$ is level.) The solutions on either side can be strictly
+neutral ($`\varepsilon = 0`$), the membrane's charge then held in each edge node's box, or resolve
+their diffuse layers ($`\varepsilon > 0`$); either way the membrane potential comes out the same, to
+a few microvolts. Pumps and other
+transporters go on the same face as reactions with saturating kinetics, for example the
+Na⁺/K⁺-ATPase between the outside (left) and the cytoplasm (right):
+
+```js nocheck
+{
+  phi: { type: 'capacitive', C: 0.01 },
+  species: { 'K+': { type: 'permeability', P: 1e-8 }, 'Na+': { type: 'permeability', P: 4e-10 }, 'Cl-': { type: 'permeability', P: 4.5e-9 }, 'A-': 'blocked' },
+  reactions: [{ equation: '3 Na+(right) + 2 K+(left) + ATP = 3 Na+(left) + 2 K+(right) + ADP', fixed: { ATP: 50e3, ADP: 0 }, vmax: 5e-7, K: { 'Na+': 10, 'K+': 1.5 } }],
+}
+```
+
+`fixed` gives ATP's hydrolysis free energy (here 50 kJ/mol, with ADP and phosphate taken
+together). Membrane potentials are $`\phi`$ differences between the two solutions, $`\phi_{\mathrm{in}} - \phi_{\mathrm{out}}`$,
+read from `sol.phi` (or a `'phi'` probe in a transient). A bath contact's terminal voltage is
+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.
+
 ### 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`$
@@ -500,11 +550,13 @@ const now = dev.solution();                   // snapshot of the current state
   `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. With
-  `probes: [{ x, species, quantity, region }]` the trace also reads a species inside the device,
-  as `trace.probes[k]` beside `trace.t`: its concentration (`quantity: 'c'`, the default, mol/m³)
-  or species voltage (`'V'`), 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
+  `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,
+  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
   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
@@ -564,10 +616,12 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `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 |
 | `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² |
 | `conservation` | per species stretch: amount, reference, intake through contacts, drift |
 | `warnings` | e.g. unresolved double layers, conventions a statistics model relies on, and for a failed solve, where the system is nearly singular |
 | `converged`, `iterations`, `steps`, `substeps`, `history`, `time` | solver bookkeeping |
+| `steady` | whether this is a converged steady state (from `solve()`), not a transient's: what `check()` in the kit decides its checks by |
 | `done`, `rejected`, `trace` | from `advance()`: whether `tEnd` was reached; rejected steps; `{ t, current, voltage }` per accepted step |
 
 A stretch is a run of regions in which a species is present and connected. Its `drift`

package/docs/kit.md

@@ -169,6 +169,99 @@ const seen = run.trace.probes[0], k = seen.indexOf(Math.max(...seen));
 console.log(`the pulse passes at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ≈ ${units.toPerCm3(seen[k]).toExponential(1)} cm⁻³`);
 ```
 
+## Liquid junctions
+
+`henderson(left, right, ions, { T })` and `planck(left, right, ions, { T })` give the junction
+potential $`\phi_R - \phi_L`$ (V) between two neutral solutions (mol/m³ by ion), with `ions` their
+`{ z, D }` (the data library's `IONS` has that shape):
+
+- **Henderson's** formula takes the junction to be the two solutions mixed in one proportion at
+  every point (so every ion's mixing fraction follows the same curve). It's
+  a closed form, exact for one salt, and what JPCalc and most electrophysiology corrections use.
+- **Planck's** is the steady state of diffusion through a zone held between the two solutions,
+  electroneutral and carrying no current, solved by shooting on the Nernst–Planck equations. It's
+  exact for that junction, and equal to driftlet's own steady state between two baths.
+
+A junction growing freely from first contact is neither: simulate it, as a transient from a
+`c0` step. For one salt all three agree; for mixtures they differ by up to a millivolt or so.
+Validated against JPCalc (Henderson), and LJPcalc and JLJP (stationary Nernst–Planck), in
+test/junction.test.js.
+
+```js
+import { henderson, planck, IONS } from 'driftlet/kit';
+
+// 50 mM NaCl against 50 mM KCl, and a K-gluconate pipette (gluconate's D from its relative mobility, 0.33 of K⁺'s).
+const ions = { ...IONS, 'gluconate-': { z: -1, D: 0.33 * IONS['K+'].D } };
+console.log(1000 * henderson({ 'Na+': 50, 'Cl-': 50 }, { 'K+': 50, 'Cl-': 50 }, ions), 'mV');
+const pipette = { 'K+': 140, 'gluconate-': 130, 'Cl-': 10 }, bath = { 'Na+': 145, 'K+': 5, 'Cl-': 150 };
+console.log(`Henderson ${(1000 * henderson(pipette, bath, ions)).toFixed(2)} mV, Planck ${(1000 * planck(pipette, bath, ions)).toFixed(2)} mV`);
+```
+
+## Recording a transient
+
+`recorder(device, { every, times, probes })` runs a transient in pieces and keeps what a demo
+needs to show it: `trace`, the terminal current and voltage (and the probes' readings) at every
+accepted step from the start, joined up across calls; and `frames`, whole solutions to scrub back
+through or draw side by side. Frames are kept at the start, then at each of `times` or every
+`every` seconds, which the stepping lands on exactly; with neither, at the end of each call.
+Its `advance(tEnd, opts)` takes `Device.advance()`'s options, so an animation calls it once per
+frame with a `budgetMs` (`done` says whether it got there), and a run in budgets is step for
+step the run made in one go. `frame(t)` is the frame at or just before t.
+
+```js
+import { Device } from 'driftlet';
+import { build, layer, bath, recorder } from 'driftlet/kit';
+
+// A salt step relaxing: 100 mM KCl in from a bath, into 10 mM held behind a blocking wall.
+const dev = new Device(
+  build({
+    species: [
+      { name: 'K+', z: 1, cRef: 1000 },
+      { name: 'Cl-', z: -1, cRef: 1000 },
+    ],
+    materials: { water: { epsr: 0, species: { 'K+': { D: 1.96e-9, mu0: 0 }, 'Cl-': { D: 2.03e-9, mu0: 0 } } } },
+    stack: [bath({ 'K+': 100, 'Cl-': 100 }, 'Cl-'), layer('water', 100e-6, { c0: { 'K+': 10, 'Cl-': 10 } }), { species: { 'K+': 'blocked', 'Cl-': 'blocked' }, phi: 'neutral' }],
+    grid: { hmin: 2e-6, hmax: 2e-6 },
+  }),
+);
+const rec = recorder(dev, { every: 1, probes: [{ x: 100e-6, species: 'K+' }] });
+rec.advance(10, { tol: 1e-4 });
+console.log(`${rec.frames.length} frames, ${rec.trace.t.length} steps; at the wall after 5 s: ${rec.frame(5).c['K+'].at(-1).toFixed(2)} mol/m³`);
+```
+
+## Curated devices
+
+Whole devices from a published parameter set, with reference results from an independent code
+to check a run against, so a demo starts from numbers that someone has measured or
+benchmarked rather than invented ones. Each returns an ordinary definition (print it to see
+every parameter, or edit it).
+
+- **`perovskiteCell({ V, light, bulkSRH })`**: IonMonger's default planar perovskite solar
+  cell (Courtier et al., J. Comput. Electron. 18, 1435 (2019)): TiO₂ (100 nm) | MAPbI₃ (400 nm)
+  with mobile iodide vacancies over an equal immobile background | spiro-OMeTAD (200 nm), at
+  298 K, lit through the TiO₂ (1.4e21 photons/(m²·s) at α = 1.3e7 /m, times `light`). SRH at
+  both faces and, unless `bulkSRH: false`, in the perovskite. `V` drives the spiro side's contact,
+  so photocurrent is positive. `PEROVSKITE_SCANS` holds IonMonger's own J–V scans of it (steady
+  at 1.2 V under light, then 1.2 → 0 → 1.2 V, at seven rates from 1 mV/s to 1 kV/s): per scan
+  the current at 0 V, each sweep's maximum power and V_oc, and the hysteresis index, with bulk
+  SRH (`full`) and without (`noBulkSRH`). driftlet's test suite reproduces them (and the whole
+  loops, to 0.03 mA/cm² where they're gentle and 1 mV where steep). `hysteresis(trace, turn)`
+  reads the same figures from a run's trace.
+
+```js
+import { Device } from 'driftlet';
+import { perovskiteCell, PEROVSKITE_SCANS, hysteresis, recorder } from 'driftlet/kit';
+
+const rate = 10, half = 1.2 / rate; // V/s
+const dev = new Device(perovskiteCell({ V: 1.2 }));
+dev.solve();
+dev.set({ contacts: { right: { V: { t: [0, half, 2 * half], values: [1.2, 0, 1.2] } } } });
+const rec = recorder(dev);
+rec.advance(2 * half, { tol: 1e-4, dtMax: (2 * half) / 480 });
+const ours = hysteresis(rec.trace, half), theirs = PEROVSKITE_SCANS.full.find((s) => s.rate === rate);
+console.log(`P_max ${ours.rev.Pmax.toFixed(1)} W/m² going down (IonMonger ${theirs.rev.Pmax}), hysteresis index ${ours.hi.toFixed(4)} (${theirs.hi})`);
+```
+
 ## Plotting
 
 Solutions are plain arrays, ready for any plotting toolkit. Two helpers save the bookkeeping of
@@ -263,6 +356,60 @@ const def = build({
 console.log(describe(def)); // … warnings: materials.Si.species.e-.D: 36 m²/s is beyond any real diffusivity …
 ```
 
+## Checking a result
+
+`check(device, sol, { refine, tol })` checks a solved device, and says what it compared, so a
+page can show that its numbers hold up. Pass the solution `solve()` or `advance()` returned.
+
+- **converged**: the solve converged.
+- **warnings**: the solution's warnings (unresolved double layers, steep profiles, a weakly held
+  part) and the definition's likely unit slips. They're heuristics, so they're marked `?`, a
+  prompt to look, and don't fail the check.
+- **balance**, in a steady state: each species' ledger, what comes in through each terminal and
+  what each reaction (bulk, or at a face) makes or uses, in mol/(m²·s) and for a charged species
+  as a current. The terms must sum to zero. A species that a face lets through only by a law (a
+  membrane's permeability, a conductance) or by a reaction has a ledger on each side, with what
+  crosses as a term: in a cell, Na⁺ leaks into the cytoplasm as fast as the pump puts it out. Under light it's J = F(G − R), and it says where
+  every carrier went: collected, or recombined in the bulk or at which face. A species at rest
+  (in equilibrium, flows only of round-off against what it could carry) isn't listed.
+- **conservation**, in a transient: every closed, unreacting stretch keeps what it held plus
+  what came in.
+- **grid**, in a steady state (unless `refine: false`): the device solved again on a grid twice
+  as fine everywhere (half of each `hmin` and `hmax`, the square root of each `ratio`), starting
+  from this solution interpolated onto it. The current, each floating terminal's voltage (an open-circuit voltage) and each
+  region's charge must agree to `tol` (relative; default 1e-2, about what a plot shows; a
+  benchmark wants 1e-3 or less). The discretisation is second order, so the change estimates
+  this grid's own error (about ¾ of it). It costs one more solve, so run it once, not on every
+  slider move.
+
+It returns `{ ok, items, text }`: `ok` when nothing failed, an item per check
+(`{ name, ok, summary, details }`, with `ok: null` for a prompt to look), and `text`, a line
+per check marked `ok`, `FAIL` or `?`, ready to log or put on the page.
+
+```js
+import { Device, units } from 'driftlet';
+import { build, layer, ohmic, semiconductor, photogeneration, check } from 'driftlet/kit';
+
+// An n⁺p silicon cell under blue-green light (α = 1e5 /m), at 0.5 V.
+const W = units.um(60.5);
+const dev = new Device(
+  build({
+    T: 300,
+    library: [semiconductor('Si')],
+    stack: [ohmic(0), layer('Si', units.um(0.5), { donors: units.perCm3(1e19) }), layer('Si', units.um(60), { acceptors: units.perCm3(1e16) }), ohmic(0.5)],
+    bulkReactions: [{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }, photogeneration({ material: 'Si', flux: 3e-3, alpha: 1e5, mu: units.eV(3), to: W })],
+    grid: { hmin: units.nm(1), hmax: units.um(1) },
+  }),
+);
+const report = check(dev, dev.solve());
+console.log(report.text);
+// ok   balance: 2 ledgers sum to zero …
+//        e-: photon = e- + h+: +2.99e-3 (289 A/m²); left contact: -2.23e-3 (-215 A/m²); …
+// FAIL grid: on a grid twice as fine (172 → 339 nodes), the largest change is region 0 (Si)
+//      charge, … (0.021, over 0.01: refine the grid …): the current is fine (1e-4), but the
+//      emitter's depletion charge is 2 % off on this grid; hmin: units.nm(0.25) fixes it.
+```
+
 ## Live demos
 
 `live(def, opts)` wraps a device for sliders. Call `set(patch)` as often as a control moves

package/llms.txt

@@ -14,9 +14,9 @@ docs/conventions.md (signs and levels) and docs/data.md (the data library).
 From a CDN, pin the version:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -40,13 +40,18 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   next to a dielectric needs its φ law. Every species that doesn't reach a contact needs its
   initial amount (`c0`). An error names the path and says what to give.
 - **Check before trusting.** `sol.converged` must be true, and read `sol.warnings`.
-  `describe(def)` (kit) summarises a definition and flags likely unit slips.
+  `describe(def)` (kit) summarises a definition and flags likely unit slips. Once a device
+  works, run `check(dev, sol)` (kit) and show or log its `text`: each species' ledger (what
+  every terminal and reaction brings in or uses, summing to zero: J = F(G − R) under light),
+  conservation in transients, and the same device on a grid twice as fine (a FAIL means the
+  answer depends on the grid: refine it). It costs a solve, so run it once, not per frame.
 - **Exports.** `driftlet`: `Device`, `units`, and the constants `FARADAY`, `GAS_CONSTANT`,
   `EPS0`, `BOLTZMANN`, `ELEMENTARY_CHARGE`, `AVOGADRO` (there's no thermal-voltage constant:
   V_T = GAS_CONSTANT·T/FARADAY). `driftlet/kit`: `build`, `layer`, `ohmic`, `bath`, `half`,
   `level`, `SHE`, `describe`, `live`, `traces`, the sources (`pulse`, `square`, `triangle`, `ramp`,
   `injector`, `recombination`, `photogeneration`), the data library (`aqueous`, `semiconductor`,
-  `metal`, `IONS`, …) and the vacuum-level helpers. `driftlet/plot`: `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`).
+  `metal`, `IONS`, …), `check` (a solution's checks), `henderson` and `planck` (liquid-junction potentials), `recorder` (a transient's trace and frames across calls), the curated
+  `perovskiteCell` with IonMonger's `PEROVSKITE_SCANS` and `hysteresis`, and the vacuum-level helpers. `driftlet/plot` (a quick look; `traces()` is the data for your own charts): `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`), `themeColor`.
 - **Reactions** are written as equations, `{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }`, in
   `new Device`, `build()` and `set()` alike. A coefficient is a number and a space (`2 e-`).
 - **Rate constants carry units.** A bulk reaction's rate is `kf · Π c_reactants` in mol/(m³·s),
@@ -155,6 +160,57 @@ const oc = new Device(cell({ I: 0 })).solve(); // open circuit
 console.log(`J_sc = ${sc.current.toFixed(1)} A/m², V_oc = ${oc.terminals.right.V.toFixed(3)} V`);
 ```
 
+## Template: a cell membrane
+
+A lipid bilayer is a face: a capacitor (about 1 µF/cm², 0.01 F/m²) that ions cross through
+channels, each with a permeability (`{ type: 'permeability', P }`, m/s: electrodiffusion in a
+constant field, so Goldman–Hodgkin–Katz comes out of it), and that pumps cross as reactions with
+saturating kinetics (`vmax`, `K`). The solutions on either side can be strictly neutral. The
+membrane potential is φ_in − φ_out from `sol.phi` (a bath's terminal voltage reads its reference
+species' level instead, which differs from Δφ by that ion's Nernst term).
+
+```js
+import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
+import { build, layer, bath, aqueous, check } from 'driftlet/kit';
+
+const T = 310.15, VT = (GAS_CONSTANT * T) / FARADAY;
+const out = { 'Na+': 145, 'K+': 5, 'Cl-': 110, 'A-': 40 }; // mM = mol/m³; A⁻: anions that don't cross
+const inside = { 'Na+': 12, 'K+': 140, 'Cl-': 10, 'A-': 142 };
+const water = aqueous(['Na+', 'K+', 'Cl-'], { epsr: 0 }); // strictly neutral solutions
+water.species.push({ name: 'A-', z: -1, cRef: 1000 });
+water.materials.water.species['A-'] = { D: 0.5e-9, mu0: 0 };
+const P = { 'K+': 1e-8, 'Na+': 0.04e-8, 'Cl-': 0.45e-8 }; // m/s, Hodgkin and Katz's ratios
+const membrane = {
+  phi: { type: 'capacitive', C: 0.01 },
+  species: { 'K+': { type: 'permeability', P: P['K+'] }, 'Na+': { type: 'permeability', P: P['Na+'] }, 'Cl-': { type: 'permeability', P: P['Cl-'] }, 'A-': 'blocked' },
+  // The Na⁺/K⁺ pump (outside on the left): 3 Na⁺ out, 2 K⁺ in, per ATP (50 kJ/mol); vmax ≈ 3000
+  // pumps per µm² at 100 cycles/s.
+  reactions: [{ equation: '3 Na+(right) + 2 K+(left) + ATP = 3 Na+(left) + 2 K+(right) + ADP', fixed: { ATP: 50e3, ADP: 0 }, vmax: 5e-7, K: { 'Na+': 10, 'K+': 1.5 } }],
+};
+const cell = build({
+  T,
+  library: [water],
+  stack: [
+    bath(out, 'Cl-'), // the extracellular fluid, held
+    layer('water', 1e-6, { name: 'outside', c0: out }),
+    membrane,
+    layer('water', 5e-6, { name: 'cytoplasm', c0: inside }), // a closed cell: its contents set by leaks and the pump
+    { species: { 'Na+': 'blocked', 'K+': 'blocked', 'Cl-': 'blocked', 'A-': 'blocked' }, phi: 'neutral' },
+  ],
+  grid: { hmin: 50e-9, hmax: 200e-9 },
+});
+const dev = new Device(cell), sol = dev.solve();
+const g = sol.x.length - 1, ci = (s) => sol.c[s][g], Vm = sol.phi[g] - sol.phi[0];
+// Mullins–Noda: in steady state the pump's 3:2 sets the ratio of the Na⁺ and K⁺ leaks.
+const mn = VT * Math.log((1.5 * P['K+'] * out['K+'] + P['Na+'] * out['Na+']) / (1.5 * P['K+'] * ci('K+') + P['Na+'] * ci('Na+')));
+console.log(`V_m = ${(Vm * 1e3).toFixed(2)} mV (Mullins–Noda ${(mn * 1e3).toFixed(2)}), inside Na⁺ ${ci('Na+').toFixed(1)} K⁺ ${ci('K+').toFixed(1)} mM`);
+console.log(check(dev, sol).text); // per compartment: Na⁺ leaks into the cytoplasm as fast as it's pumped out
+```
+
+Between two baths instead (the inside one `bath(inside, 'Cl-', { I: 0 })`: held composition, no
+current), V_m is GHK. Without the pump, a closed cell runs down to Donnan equilibrium. driftlet
+has no voltage-gated channels; a permeability can be changed with `set()` between steps.
+
 ## Template: an electrode in a stirred solution
 
 One working electrode, a stagnant layer of solution, and the well-stirred bulk as a bath. The
@@ -217,7 +273,8 @@ const def = build({
 const dev = new Device(def);
 const rest = dev.solve(); // the steady state at t = 0 (solve() doesn't advance time)
 // In a page, call advance(tNext, { budgetMs: 12, probes }) once per animation frame, carrying on
-// next frame while sol.done is false. Probes read at accepted steps; dtMax keeps them close.
+// next frame while sol.done is false (or let recorder() join the traces and keep frames to scrub
+// back through). Probes read at accepted steps; dtMax keeps them close.
 const run = dev.advance(10e-6, { dtMax: 20e-9, probes: [{ x: 1.525e-3, species: 'h+' }] });
 const seen = run.trace.probes[0], k = seen.indexOf(Math.max(...seen));
 const tArrive = run.trace.t[k] - width / 2; // from the pulse's middle
@@ -227,18 +284,32 @@ console.log(`peak at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ${units.toPer
 To start from a state instead of simulating how it got there (a packet already injected, a
 salt gradient laid down), give a region's `c0` a profile against the device's x:
 `c0: { 'h+': { x: [...], values: [...] } }`, piecewise linear. A given `c0` is the starting state,
-even for a species a contact feeds; species without one start at their contact's level, with φ
-made neutral node by node (electrons follow the holes). Then `advance()` without `solve()`, which would go straight to the steady
+even for a species a contact feeds; species without one start at their contact's level (the
+left's if they reach it, else the right's), with φ made neutral node by node (electrons follow
+the holes). Between two different solutions, give every region its `c0`. Then `advance()` without `solve()`, which would go straight to the steady
 state.
 
 Transients cost more where a carrier's density spans many decades (minority holes in silicon
 ahead of the pulse) and at strong injection (Δp near n₀); budget for that, or coarsen the grid.
 
+`recorder(dev, { every, times, probes })` (kit) runs a transient in pieces: its `advance(tEnd,
+opts)` takes the same options, `rec.trace` is the whole run's trace from the start, and
+`rec.frames` are whole solutions (at the start, then at `times`, every `every` s, or the end of
+each call), with `rec.frame(t)` the one at or before t, for a time slider.
+
+**Prefer a curated device to inventing numbers** where one fits: `perovskiteCell({ V, light,
+bulkSRH })` is IonMonger's default perovskite solar cell (mobile iodide vacancies, SRH in the bulk
+and at both faces), and `PEROVSKITE_SCANS` holds IonMonger's J–V scans of it at seven rates;
+`hysteresis(rec.trace, turn)` reads the same figures from yours, so a demo can show its agreement.
+The definition is plain data: print it, edit what your demo varies.
+
 ## Template: a live page with a slider
 
 `live()` merges slider moves made during a solve, warm-starts each solve and keeps the last
 good solution. `bandDiagram()` returns an SVG string. Pass `worker: true` to `live()` to solve in
-a Web Worker.
+a Web Worker (it works with the library loaded from a CDN: a same-origin stub imports it). Calling
+`set()` from `onsolution` is fine, for a quantity the page solves for itself (it queues the next
+solve), as long as it settles rather than ping-pongs.
 
 ```html
 <!doctype html>
@@ -248,9 +319,9 @@ a Web Worker.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.5.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -275,6 +346,16 @@ slider.addEventListener('input', () => dev.set({ contacts: { right: { V: +slider
 What `bandDiagram()` and `traces()` draw, and how to explain it to a reader (docs/visualization.md
 has the long form):
 
+- **Plotting in your own style.** `bandDiagram()` is a quick look. For a page of your own, draw
+  with your own charting code from `traces(sol, opts)` (in `driftlet/kit`, the same options):
+  `{ x, series: [{ id, label, kind, role, slot, y }], regions, faces, range }`, where `kind` says how
+  a line reads (`'level'` thick, `'standard'` thin, `'redox'`, `'phi'`), `role` and `slot` keep a
+  species' colour stable (`themeColor(role, slot)` in `driftlet/plot` gives ours), labels mark
+  subscripts TeX-style (`labelParts(label)` splits them), `NaN` breaks a line, and doubled
+  interface nodes share an x (draw them as vertical steps). Or read the solution directly:
+  `sol.x`, `sol.V[name]`, `sol.Vstd[name]`, `sol.c[name]`, `sol.phi`; electron energies are
+  E = −V (eV) for both carriers' levels and band edges.
+
 - **Which picture.** For a device of electrons and holes only, draw the familiar band diagram,
   energy up: `bandDiagram(sol, { energy: true })` (E_c, E_v, E_Fn, E_Fp in eV). The species
   voltages below are the same lines in volts, turned over; use them where ions share the diagram,
@@ -357,11 +438,15 @@ has the long form):
 - **A steady solve of a closed cell where every ion can cross.** Its steady state is complete
   mixing. To watch a junction or a salt bridge, step in time from the unmixed `c0` (`advance`).
 - **Everything floating.** At least one terminal must be held at a voltage `V`.
-- **The library's semiconductors are at 300 K.** Give `T: 300`.
+- **The library's data are for 25 °C** (its semiconductors for 300 K: give `T: 300`). At body
+  temperature, `T: 310.15` with the same μ° and D is a fair start; D rises about 2% per kelvin
+  in water.
 - **Sign of the current.** `sol.current` is positive toward +x: a forward-biased diode with its
   p side on the right carries negative current. A terminal's current is into the device.
-- **Sign of a voltage across a membrane.** `sol.terminalVoltage` is V_right − V_left. Physiology
-  quotes V_inside − V_outside, so put the inside on the right or flip the sign.
+- **A membrane potential read from the terminals.** Physiology's V_m is φ_inside − φ_outside:
+  read it from `sol.phi` (or a `{ x, quantity: 'phi' }` probe in a transient), with the inside on
+  the right. `sol.terminalVoltage` (and a trace's `voltage`) is V_right − V_left of the contacts,
+  which at baths are their reference species' levels: it differs from Δφ by that ion's Nernst term.
 - **A coefficient without its space.** `'2e- + …'` reads `2e-` as a species name; the error says
   to write `2 e-`.
 - **Changing c0 with `set()`.** A carried state keeps what it holds; `c0` is only the starting

package/package.json

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