driftlet 0.4.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ 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) and [organic (excitons)](https://markblundeberg.github.io/driftlet/demos/organic.html) demos, [`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 |
+| 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) 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 |
 | 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 |
@@ -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.4.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.6.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
 
@@ -146,7 +148,7 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | **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 |
 | [![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) |  |
+| [![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 |  |  |
 
 ## How to think about it
@@ -235,6 +237,8 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | A packet laid down as a `c0` profile | the same rates from a Gaussian at t = 0: μ*E t, σ₀² + 2D*t, e^(−t/τ*) | 3e-4; 1e-2; 1e-3 |
 | 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 (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% |
 | Liquid junction, open circuit | cell EMF 2t₊(RT/F) ln(c₁/c₂); Planck diffusion potential | 1e-4 |

package/docs/device.md

@@ -203,13 +203,29 @@ Butler–Volmer,
 r = k_0 \prod_{\nu<0} (c/c_{\mathrm{ref}})^{|\nu|(1-\alpha)} \prod_{\nu>0} (c/c_{\mathrm{ref}})^{\nu\alpha} \left(e^{\alpha a} - e^{-(1-\alpha)a}\right)
 ```
 
-with $`k_0`$ in mol/(m²·s) and $`\alpha`$ (default 0.5) between 0 and 1. A conductor's carrier has
+with $`k_0`$ in mol/(m²·s) and $`\alpha`$ (default 0.5) from 0 to 1 inclusive ($`\alpha = 0`$ makes the
+forward rate plain mass action, independent of the energetics). A conductor's carrier has
 activity 1 and no factor. That's mass action with rate constants that depend on the electrical part
 of the affinity: exactly zero at $`A = 0`$, whatever $`k_0`$ and $`\alpha`$. Each participant is made or
 consumed at its side's edge node, just behind any Stern layer, so Frumkin effects arise by
 themselves. A face can carry several reactions; a conductor coupled to two couples settles at their
 mixed potential. Each solution reports the rates as `interfaces[f].rates`.
 
+**Interface recombination through traps** (SRH at a face) replaces `k0` and `alpha` with
+`srh: { vn, vp, n1 }`, on a reaction consuming one negative and one positive species and making
+none, such as `'e-(left) + h+(right) = 0'`:
+
+```math
+r = \frac{n\,p\,(1 - e^{-A/RT})}{(n + n_1)/v_p + (p + p_1)/v_n}, \qquad p_1 = \frac{n\,p\,e^{-A/RT}}{n_1}
+```
+
+with n and p each at its own side's edge node, the capture velocities $`v_n`$ and $`v_p`$ in m/s,
+and $`n_1`$ (mol/m³) the negative species' concentration with its level at the trap (default:
+$`n_1 = p_1 = n_i`$, a midgap trap). Taking $`p_1`$ from the state keeps equilibrium exact whatever
+lies between the two sides (a band offset, a $`\phi`$ jump). Where one carrier is plentiful the
+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.
+
 ### 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`$
@@ -253,6 +269,17 @@ $`A = 0`$. `kf` maps material
 names to forward rate constants (units making r mol/(m³·s)), and the reaction runs only in
 those materials.
 
+**SRH (trap-assisted) recombination** replaces `kf` with `srh`, a map from material names to
+`{ tauN, tauP, n1 }`, on a reaction consuming one negative and one positive species and making
+none (`'e- + h+ = 0'`):
+$`r = n p (1 - e^{-A/RT}) / (\tau_p (n + n_1) + \tau_n (p + p_1))`$, with lifetimes in s and $`n_1`$ as
+for [interface SRH](#interfaces) (default midgap). It's what explicit trap species reduce to when
+the traps are few and fast, without them.
+
+```js nocheck
+bulkReactions: [{ equation: 'e- + h+ = 0', srh: { Si: { tauN: 1e-6, tauP: 1e-6 } } }]
+```
+
 **Generation** is a reaction from a reservoir: photogeneration is
 $`\text{photon} \to \mathrm{e}^- + \mathrm{h}^+`$, with the photons a fixed participant whose $`\mu`$
 sits well above the gap, so that $`e^{-A/RT}`$ is negligible and the rate is `kf` itself, the
@@ -486,7 +513,8 @@ const now = dev.solution();                   // snapshot of the current state
   be the one measured: the resistance belongs to the external circuit. With `profiles: true`, each
   frequency also returns complex profiles of $`\delta\phi`$, $`\delta\bar\mu`$ and $`\delta c`$ per unit
   excitation.
-- `set(patch)` merges plain objects deeply (arrays are replaced). A patch that changes only the
+- `set(patch)` merges plain objects deeply (arrays are replaced), except that a contact given `V`
+  or `I` drops the other: `{ contacts: { right: { I: 0 } } }` switches it to open circuit. A patch that changes only the
   terminals' drives (`V`, `I`, `R`) updates them in place, cheaply, keeping everything else.
   Otherwise the device is rebuilt: the current state carries over while the grid and species
   are unchanged, or restarts from the regions' `c0`. A carried state keeps what it holds: a
@@ -535,11 +563,13 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `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 |
-| `interfaces[f]` | `{ dipole, sheetCharge, D, N: {name}, rates }`: what crosses each face by its links, and each face reaction's rate (mol/(m²·s)) |
+| `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,71 @@ 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⁻³`);
 ```
 
+## 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
@@ -189,6 +254,12 @@ a level diagram:
   shown (`speciesRole(sol, name)` gives a species' own). Undefined values are `NaN` (break the line
   there), and doubled interface nodes share an x, so steps draw as vertical lines. It also gives
   the regions (`{ name, material, x0, x1 }`), the faces' positions and a suggested range.
+- `energy: true` (in `traces` and `bandDiagram`) gives the familiar band diagram instead, energy
+  up: electrons and holes as electron energies in eV (E_c and E_v from the standard levels, E_Fn
+  and E_Fp, or E_F where there are no holes, from the levels), with redox levels and $`\phi`$ (as
+  $`-q\phi`$) turned over too and shifts in eV. Ions have no band, so asking for one is an error.
+  It's the right picture for semiconductor devices; species voltages earn their place where ions
+  share the diagram (see [which to use](visualization.md)).
 - `bandDiagram(sol, opts)` in `driftlet/plot` draws them as an SVG string, with no DOM needed, in
   the style [reading level diagrams](visualization.md) explains: species voltages thick and solid, standard levels thin and solid, redox
   levels thick and dashed, standard redox levels thin and dashed, $`\phi`$ thin, dotted and grey;
@@ -257,6 +328,58 @@ 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. 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 species' sources and sinks 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/docs/numerics.md

@@ -545,8 +545,12 @@ take about twice as long as before.
   larger by $`D \cdot dt/(hL)`$, around 1e12 for a micron-scale cell (see
   [metal regions](#metal-regions) for the same cancellation). Newton then needs dozens of
   iterations, or fails.
-- **Otherwise** (immobile spectators, which conserve node by node, or a combination that
-  includes a floating conductor), backward-Euler steps at a huge $`dt`$ (10⁶ × the slowest
+- **Immobile combinations** (trap states X⁰ and X⁻ under e⁻ + X⁰ = X⁻, with D = 0) conserve
+  node by node, since nothing carries them anywhere. At each node the combination's weighted sum
+  replaces one of its balance rows, kept at what it was when the solve began. The row is local
+  to that node's block, so nothing is bordered, and the solve goes direct.
+- **Otherwise** (an immobile spectator on its own, or a combination that includes a floating
+  conductor or mixes mobile and immobile stretches), backward-Euler steps at a huge $`dt`$ (10⁶ × the slowest
   diffusion time) keep the storage term, which pins each conserved amount exactly: sum a
   species' rows and the fluxes cancel. $`dt`$ grows ×10 (capped) while the state still moves.
   Before each huge step, each spectator's level is shifted uniformly to restore its amount

package/docs/visualization.md

@@ -7,6 +7,15 @@ electronic levels, Fermi levels and redox levels, which connect directly to elec
 and other familiar quantities. The second half covers the species voltages of every charged
 species, ions included. For how to draw them, see [the kit's plotting helpers](kit.md#plotting).
 
+**Which to use.** For electrons and holes alone (a pn junction, a solar cell, a MOS capacitor),
+draw the familiar band diagram, energy up: `bandDiagram(sol, { energy: true })` gives E_c and
+E_v (thin) and the quasi-Fermi levels E_Fn and E_Fp (thick), in eV, with the conduction band on
+top. Species voltages are the same lines in volts, turned over, and don't add anything there.
+They earn their place where the familiar picture can't go: ions and other charged species that
+have no band (a vacancy's level drifting out of flat as the ions lag a voltage sweep), and
+questions of equilibrium between species (an electrode against a redox couple). Bring them in
+there, as an extra tool, not in place of the band diagram.
+
 ## Electron levels
 
 ### The Fermi level

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.4.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -40,19 +40,27 @@ 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), `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),
   with c in mol/m³ (and 1e16 cm⁻³ is only 0.0166 mol/m³). Band-to-band recombination,
   `e- + h+ = 0`, gives a minority lifetime τ = 1/(kf·N) with N the majority density in mol/m³:
-  `kf: 1e8` is τ ≈ 0.6 µs at 1e16 cm⁻³. Generation is a reaction from a reservoir, rate `kf` in
+  `kf: 1e8` is τ ≈ 0.6 µs at 1e16 cm⁻³. Trap-assisted (SRH) recombination is
+  `{ equation: 'e- + h+ = 0', srh: { Si: { tauN, tauP } } }` (lifetimes in s), and at a face
+  `{ equation: 'e-(left) + h+(right) = 0', srh: { vn, vp } }` (velocities in m/s); both default to a
+  midgap trap. Generation is a reaction from a reservoir, rate `kf` in
   mol/(m³·s) (`units.perCm3` converts cm⁻³·s⁻¹ too); light absorbed as it goes in is
   `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })` (flux in
   mol/(m²·s), α in 1/m), a `kf` that varies with x. A face reaction's `k0` is in mol/(m²·s);
@@ -214,7 +222,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
@@ -231,6 +240,17 @@ 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
@@ -245,9 +265,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.4.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.6.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -259,7 +279,7 @@ const def = build({
 const slider = document.getElementById('V');
 const dev = live(def, {
   onsolution(sol, info) {
-    document.getElementById('figure').innerHTML = bandDiagram(sol, { title: `V = ${sol.terminals.right.V.toFixed(2)} V` });
+    document.getElementById('figure').innerHTML = bandDiagram(sol, { energy: true, title: `V = ${sol.terminals.right.V.toFixed(2)} V` });
     document.getElementById('readout').textContent = info.failed ? 'no solution here' : `I = ${sol.current.toExponential(2)} A/m²`;
   },
 });
@@ -272,6 +292,21 @@ 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,
+  or for equilibrium between species, and don't present them in place of the band diagram.
+
 - **Fermi level** V_e⁻ = −μ̄_e⁻/F: the circuit voltage, what a voltmeter reads. A cell's voltage is
   the difference between its terminals' V_e⁻.
 - **Redox level** of Ox + z e⁻ ⇌ Red, `level(sol, half)`: V_e⁻(Ox/Red) = (μ̄_Ox − μ̄_Red)/(zF), where

package/package.json

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