driftlet 0.5.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) [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 |
+| 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.5.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
 
@@ -236,7 +238,7 @@ 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% |
 | Liquid junction, open circuit | cell EMF 2t₊(RT/F) ln(c₁/c₂); Planck diffusion potential | 1e-4 |

package/docs/device.md

@@ -564,10 +564,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,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
@@ -263,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/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.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,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), `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),
@@ -217,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
@@ -234,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
@@ -248,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.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.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,
@@ -275,6 +292,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,

package/package.json

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

package/src/checks.js

@@ -0,0 +1,268 @@
+// Checks on a solved device, for driftlet/kit: what any result should satisfy, worked out from the
+// definition and the solution, so a page can show that its numbers hold up without its author
+// writing each check by hand. Each check says what it compared and whether it passed.
+
+import { Device } from './index.js';
+import { FARADAY } from './constants.js';
+import { unitWarnings } from './describe.js';
+
+const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs(v) >= 1e4 || Math.abs(v) < 1e-2 ? v.toExponential(p - 1) : String(+v.toPrecision(p)));
+
+/**
+ * @typedef {object} CheckItem
+ * @property {string} name what was checked: 'converged', 'warnings', 'balance', 'conservation' or 'grid'
+ * @property {boolean | null} ok whether it passed (null: look at it, a warning or a check that
+ *   couldn't be made)
+ * @property {string} summary one line
+ * @property {object} [details] the numbers behind it
+ */
+
+/**
+ * Check a device's present state (pass the solution solve() or advance() returned, for its
+ * convergence and warnings):
+ * - **converged**: the last solve converged.
+ * - **warnings**: the solution's warnings (unresolved double layers, steep profiles, weakly held
+ *   parts) and the definition's likely unit slips.
+ * - **balance** (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 F·|z|·rate. The terms must sum to zero; under light it's J = F(G − R),
+ *   and it says where every carrier went.
+ * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
+ *   what came in.
+ * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
+ *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
+ *   wants less). The discretisation is second order, so the change estimates this grid's error
+ *   (about 3/4 of it).
+ * @param {import('./index.js').Device} device
+ * @param {object} [sol] the solution to check (default: the device's present state)
+ * @param {{ refine?: boolean, tol?: number }} [opts]
+ * Every check passed when `ok`; an item with `ok: null` (a warning, or a check that couldn't be
+ * made) asks you to look, and doesn't fail it. `text` is a line per check, marked ok, FAIL or ?.
+ * @returns {{ ok: boolean, items: CheckItem[], text: string }}
+ */
+export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
+  sol ??= device.solution();
+  const { model, solver, def } = device;
+  const steady = sol.steady ?? solver.atSteady;
+  const items = [];
+
+  items.push(
+    sol.converged
+      ? { name: 'converged', ok: true, summary: `${steady ? 'steady state' : `transient at t = ${sig(sol.time)} s`}, converged` }
+      : { name: 'converged', ok: false, summary: "the solve didn't converge: these numbers aren't a solution" },
+  );
+
+  const warnings = [...sol.warnings, ...unitWarnings(def)];
+  // Heuristics, so a prompt to look (null) rather than a failure.
+  items.push({
+    name: 'warnings',
+    ok: warnings.length === 0 ? true : null,
+    summary: warnings.length === 0 ? 'none' : `${warnings.length}: ${warnings.join(' · ')}`,
+    details: { warnings },
+  });
+
+  // The rest checks a solution, which an unconverged state isn't.
+  if (sol.converged) {
+    const ledger = steady ? balance(device, sol) : null;
+    items.push(ledger ?? conservation(sol));
+    if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+  }
+
+  const ok = sol.converged && items.every((it) => it.ok !== false);
+  const mark = (it) => (it.ok === true ? 'ok  ' : it.ok === false ? 'FAIL' : '?   ');
+  const text = items.map((it) => `${mark(it)} ${it.name}: ${it.summary}${it.details?.lines?.length ? `\n${it.details.lines.map((l) => `       ${l}`).join('\n')}` : ''}`).join('\n');
+  return { ok, items, text };
+}
+
+// Each species' steady ledger: in through the terminals, made by the reactions. Rates in
+// mol/(m²·s), positive into the device or made.
+function balance(device, sol) {
+  const { model, def } = device, { species } = model;
+  const label = (rdef) => rdef?.equation ?? JSON.stringify(rdef?.nu ?? rdef);
+  const ledgers = species.map((sp) => ({ species: sp.name, z: sp.z, terms: [] }));
+  const add = (i, what, rate) => {
+    if (rate !== 0 && Number.isFinite(rate)) ledgers[i].terms.push({ what, rate });
+  };
+  species.forEach((sp, i) => {
+    add(i, 'left contact', sol.contacts.left.flux[sp.name]);
+    add(i, 'right contact', -sol.contacts.right.flux[sp.name]);
+    sol.ports.forEach((p) => add(i, `port ${p.name}`, p.flux[sp.name]));
+  });
+  model.reactions.forEach((rx, k) => {
+    const total = sol.bulkReactions[k].total, what = label(def.bulkReactions?.[k]);
+    for (const { i, nu } of rx.reactants) add(i, what, -nu * total);
+    for (const { i, nu } of rx.products) add(i, what, nu * total);
+  });
+  model.interfaces.forEach((itf, f) => {
+    itf.reactions.forEach((rx, k) => {
+      const rate = sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
+      for (const { i, nu } of rx.part) add(i, what, nu * rate);
+    });
+  });
+
+  // A species at rest (nothing beyond round-off moving, against what it could carry) isn't reported.
+  const size = (l) => Math.max(0, ...l.terms.map((t) => Math.abs(t.rate)));
+  const natural = naturalScales(device, sol);
+  const moving = ledgers.filter((l, i) => size(l) > 1e-9 * natural[i]);
+  let worst = 0;
+  const lines = [];
+  for (const l of moving) {
+    const sum = l.terms.reduce((a, t) => a + t.rate, 0);
+    l.residual = sum / size(l);
+    worst = Math.max(worst, Math.abs(l.residual));
+    // Terms that matter, largest first; a charged species' as a current too.
+    const shown = l.terms.filter((t) => Math.abs(t.rate) > 1e-6 * size(l)).sort((a, b) => Math.abs(b.rate) - Math.abs(a.rate));
+    const amp = (r) => (l.z !== 0 ? ` (${sig(FARADAY * Math.abs(l.z) * r)} A/m²)` : '');
+    lines.push(`${l.species}: ${shown.map((t) => `${t.what}: ${t.rate > 0 ? '+' : ''}${sig(t.rate)}${amp(t.rate)}`).join('; ')}`);
+  }
+  const ok = worst < 1e-6;
+  const summary =
+    moving.length === 0
+      ? 'nothing flows or reacts (equilibrium)'
+      : `${moving.length} species' sources and sinks sum to zero ${ok ? `(to ${sig(worst, 1)})` : `only to ${sig(worst, 2)}: not a steady state`}; mol/(m²·s), + in or made`;
+  // The largest current any charged species carries anywhere: the scale a net current is read against.
+  const gross = Math.max(0, ...moving.filter((l) => l.z !== 0).map((l) => FARADAY * Math.abs(l.z) * size(l)));
+  return { name: 'balance', ok, summary, details: { ledgers, worst, lines, gross } };
+}
+
+// What each species could carry, mol/(m²·s): by transport, D·c/L in each region (a metal's
+// carrier, σRT/(z²F²L)), and by its bulk reactions, their one-way rates. In equilibrium the net
+// flows are round-off of these.
+function naturalScales(device, sol) {
+  const { model, solver } = device, { species } = model;
+  const box = (g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? sol.x[g] - sol.x[g - 1] : 0) + (g + 1 < sol.x.length && sol.region[g + 1] === sol.region[g] ? sol.x[g + 1] - sol.x[g] : 0)) / 2;
+  return species.map((sp, i) => {
+    let S = 0;
+    model.regions.forEach((reg, r) => {
+      const mat = model.materials[reg.material], L = reg.length;
+      if (mat.conductor) {
+        if (mat.conductor.i === i) S = Math.max(S, (mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        return;
+      }
+      if (!mat.present[i] || !(mat.D[i] > 0)) return;
+      let cmax = 0;
+      for (let g = 0; g < sol.x.length; g++) if (sol.region[g] === r && Number.isFinite(sol.c[sp.name][g])) cmax = Math.max(cmax, sol.c[sp.name][g]);
+      S = Math.max(S, (mat.D[i] * cmax) / L);
+    });
+    solver.rxs.forEach((rx) => {
+      const p = rx.sp.indexOf(i);
+      if (p < 0) return;
+      let gross = 0;
+      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += box(g) * solver.bulkOneWay(rx, g);
+      S = Math.max(S, Math.abs(rx.nu[p]) * gross);
+    });
+    return S;
+  });
+}
+
+// Closed, unreacting stretches keep their amounts in a transient.
+function conservation(sol) {
+  const closed = sol.conservation.filter((st) => !st.connected && !st.reactive);
+  if (closed.length === 0) return { name: 'conservation', ok: true, summary: 'nothing closed to conserve (every species reaches a terminal or reacts)' };
+  // Relative to the amount, but a drift below 1e-20 mol/m² (1e-15 C/m²) is nothing: a floating
+  // metal's excess electrons are themselves ~0.
+  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 ? 0 : Math.abs(st.drift))));
+  return {
+    name: 'conservation',
+    ok: worst < 1e-8,
+    summary: `${closed.length} closed stretch${closed.length > 1 ? 'es' : ''} (a species held between blocking faces) kept ${worst < 1e-8 ? `to ${sig(worst, 1)}` : `only to ${sig(worst, 2)}`} of what ${closed.length > 1 ? 'they' : 'it'} held plus what came in`,
+    details: { worst },
+  };
+}
+
+// The same device on a grid twice as fine (half the cells' sizes, the square root of the
+// grading ratio), solved from this solution interpolated onto it, against this solution.
+function gridCheck(device, sol, tol, gross) {
+  const { def, model } = device;
+  const fine = {
+    ...def,
+    regions: def.regions.map((reg, r) => {
+      if (model.materials[model.regions[r].material].conductor) return reg;
+      const g = { ...(def.grid ?? {}), ...(reg.grid ?? {}) };
+      if (def.grid === undefined && reg.grid === undefined) Object.assign(g, { hmin: reg.length / 1000, hmax: reg.length / 20 });
+      const out = { ratio: Math.sqrt(g.ratio ?? 1.2), minCells: 2 * (g.minCells ?? 8) };
+      if (g.hmin !== undefined) out.hmin = g.hmin / 2;
+      if (g.hmax !== undefined) out.hmax = g.hmax / 2;
+      return { ...reg, grid: out };
+    }),
+  };
+  // Started from this solution, interpolated onto the finer grid; failing that, from cold.
+  let other;
+  try {
+    const dev = new Device(fine);
+    dev.solver._warmFrom(device.solver);
+    other = dev.solve();
+    if (!other.converged) {
+      const cold = new Device(fine);
+      if (sol.time > 0) cold.solver.time = sol.time; // waveforms at the same time
+      other = cold.solve();
+    }
+  } catch (e) {
+    return { name: 'grid', ok: null, summary: `couldn't solve the refined device (${e.message})` };
+  }
+  if (!other.converged) return { name: 'grid', ok: null, summary: "the device on a twice-finer grid didn't solve; check resolution by hand" };
+
+  const diffs = [];
+  // The current, against the largest current any species carries (so at open circuit, or in
+  // equilibrium, round-off isn't read as a change).
+  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross);
+  if (gross > 0) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: 'A/m²' });
+  // Floating terminals (driven by a current): their voltages, against the larger and the thermal voltage.
+  const VT = model.RT / FARADAY;
+  model.terminals.forEach((t, k) => {
+    if (device.solver.floating.includes(k)) {
+      const a = sol.terminals[t.name].V, b = other.terminals[t.name].V;
+      diffs.push({ what: `${t.name} voltage`, a, b, rel: Math.abs(b - a) / Math.max(Math.abs(a), Math.abs(b), VT), unit: 'V' });
+    }
+  });
+  // Each region's charge (C/m²), against the largest: summed over the nodes' boxes, as the
+  // solver's Gauss law counts it.
+  const charges = (s) => s.regions.map((_, r) => {
+    let q = 0;
+    for (let g = 0; g < s.x.length; g++) {
+      if (s.region[g] !== r) continue;
+      const left = g > 0 && s.region[g - 1] === r ? s.x[g] - s.x[g - 1] : 0, right = g + 1 < s.x.length && s.region[g + 1] === r ? s.x[g + 1] - s.x[g] : 0;
+      q += rho(s, g, model, r) * ((left + right) / 2);
+    }
+    return q;
+  });
+  // Charges at round-off (strictly neutral regions) aren't compared: against the gross charge
+  // the regions hold, |fixed| + Σ|z|c, they must be more than a millionth.
+  const content = Math.max(...sol.regions.map((reg, r) => {
+    let q = 0;
+    for (let g = 0; g < sol.x.length; g++) {
+      if (sol.region[g] !== r) continue;
+      let a = Math.abs(model.regions[r].fixedCharge ?? 0);
+      for (const sp of model.species) if (Number.isFinite(sol.c[sp.name][g])) a += FARADAY * Math.abs(sp.z * sol.c[sp.name][g]);
+      q = Math.max(q, a);
+    }
+    return q * (reg.x1 - reg.x0);
+  }));
+  const qa = charges(sol), qb = charges(other), scaleQ = Math.max(0, ...qa.map(Math.abs), ...qb.map(Math.abs));
+  if (scaleQ > 1e-6 * content) {
+    const named = (reg) => (/^region \d+$/.test(reg.name) ? `${reg.name} (${reg.material})` : reg.name);
+    qa.forEach((a, r) => diffs.push({ what: `${named(sol.regions[r])} charge`, a, b: qb[r], rel: Math.abs(qb[r] - a) / scaleQ, unit: 'C/m²' }));
+  }
+  const worst = diffs.reduce((w, d) => (d.rel > (w?.rel ?? -1) ? d : w), null);
+  if (!worst) return { name: 'grid', ok: true, summary: 'nothing to compare (no current, charge or floating voltage)' };
+  const ok = worst.rel <= tol;
+  return {
+    name: 'grid',
+    ok,
+    summary:
+      `on a grid twice as fine (${sol.x.length} → ${other.x.length} nodes), the largest change is ${worst.what}, ${sig(worst.a, 5)} → ${sig(worst.b, 5)} ${worst.unit} ` +
+      `(${sig(worst.rel, 2)}${ok ? '' : `, over ${sig(tol, 1)}: refine the grid (hmin, hmax), most likely where profiles are steepest`})`,
+    details: { diffs, nodes: [sol.x.length, other.x.length] },
+  };
+}
+
+// Charge density at a node of region r, C/m³: the species plus the region's fixed charge.
+function rho(s, g, model, r) {
+  let q = model.regions[r].fixedCharge ?? 0;
+  for (const sp of model.species) {
+    const c = s.c[sp.name][g];
+    if (Number.isFinite(c)) q += FARADAY * sp.z * c;
+  }
+  return q;
+}

package/src/describe.js

@@ -141,13 +141,17 @@ export function describe(def) {
     if (reg.fixedCharge !== 0) parts.push(`fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(Math.abs(reg.fixedCharge) / FARADAY)}`);
     // The screening concentration: Σ z²c from the initial composition, plus the carriers that
     // balance the fixed charge (doping), which c0 doesn't list.
-    let zzc = 0;
+    let zzc = 0, q = reg.fixedCharge / FARADAY; // q: the charge c0 leaves unbalanced
     species.forEach((sp, i) => {
       if (!mat.present[i]) return;
-      if (Number.isFinite(reg.c0[i])) zzc += sp.z * sp.z * reg.c0[i];
-      else if (reg.c0Profile[i]) zzc += sp.z * sp.z * Math.max(...reg.c0Profile[i].values);
+      const c = Number.isFinite(reg.c0[i]) ? reg.c0[i] : reg.c0Profile[i] ? Math.max(...reg.c0Profile[i].values) : 0;
+      zzc += sp.z * sp.z * c;
+      q += sp.z * c;
     });
-    zzc += Math.abs(reg.fixedCharge) / FARADAY; // the mobile charge that balances the doping
+    // Plus the mobile charge that balances whatever c0 leaves unbalanced: a doped layer's
+    // carriers, which c0 doesn't list (and nothing, where c0 lists them, as a perovskite's
+    // vacancies over their background).
+    zzc += Math.abs(q);
     const Dmax = Math.max(0, ...species.map((sp, i) => (mat.present[i] && sp.z !== 0 ? mat.D[i] : 0)));
     const Dmin = Math.min(...species.map((sp, i) => (mat.present[i] && mat.D[i] > 0 ? mat.D[i] : Infinity)));
     if (mat.epsr > 0 && zzc > 0) {
@@ -198,7 +202,7 @@ export function describe(def) {
   (def.ports ?? []).forEach((p, k) => lines.push(`  port ${model.ports[k].name}: ${drive(p)}, in ${regions[model.ports[k].region].name}`));
   if ((def.bulkReactions ?? []).length) {
     lines.push('bulk reactions:');
-    for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)} in ${Object.keys(rx.kf ?? {}).join(', ')}`);
+    for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)}${rx.srh ? ' (SRH)' : ''} in ${Object.keys(rx.kf ?? rx.srh ?? {}).join(', ')}`);
   }
   if (times.length) lines.push('time scales:', ...times);
   if (warnings.length) lines.push('warnings:', ...warnings.map((w) => `  ${w}`));