driftlet 0.4.0 → 0.5.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 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 |
 | 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.5.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).
 
@@ -146,7 +146,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 +235,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 | 1.5e-3; 0.05 mW/cm²; 2 mV; 0.3 mA/cm² |
 | 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,7 +563,7 @@ 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)) |
 | `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 |

package/docs/kit.md

@@ -189,6 +189,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;

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.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';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -52,7 +52,10 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
 - **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);
@@ -245,9 +248,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.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';
 
 const def = build({
   T: 300,
@@ -259,7 +262,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 +275,11 @@ 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):
 
+- **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.5.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/describe.js

@@ -139,14 +139,15 @@ export function describe(def) {
     }
     const parts = [mat.epsr > 0 ? `εr ${mat.epsr}` : 'strictly neutral (ε = 0)'];
     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, else the fixed charge's.
+    // 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;
     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);
     });
-    if (zzc === 0) zzc = Math.abs(reg.fixedCharge) / FARADAY;
+    zzc += Math.abs(reg.fixedCharge) / FARADAY; // the mobile charge that balances the doping
     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) {

package/src/device.js

@@ -70,6 +70,29 @@ function profile(v, path, what, ok, okText) {
   return { x: Float64Array.from(v.x), values: Float64Array.from(v.values) };
 }
 
+// SRH (trap-assisted) kinetics in place of mass action, for a reaction that consumes exactly one
+// negative and one positive species and makes none, e⁻ + h⁺ = 0:
+//   r = n p (1 − e^{−A/RT}) / (t_p (n + n₁) + t_n (p + p₁)),  p₁ = n p e^{−A/RT} / n₁,
+// with t = τ (s) in the bulk, 1/v (m/s) at a face, and n₁ the negative species' concentration
+// with its level at the trap (default n_i, a midgap trap). p₁ from the state keeps detailed
+// balance exact, whatever lies between the two (a band offset, a φ jump).
+function srhLaw(sdef, path, list, species, timeKeys) {
+  const [kn, kp] = timeKeys;
+  need(isObject(sdef), `${path} must be { ${kn}, ${kp}, n1 }`);
+  fields(sdef, path, [kn, kp, 'n1']);
+  const reactants = list.filter((p) => p.nu < 0);
+  need(
+    list.length === 2 && reactants.length === 2 && reactants.every((p) => p.nu === -1) && species[list[0].i].z * species[list[1].i].z < 0,
+    `${path}: SRH kinetics needs a reaction consuming one negative and one positive species and making none, such as 'e- + h+ = 0'`,
+  );
+  const neg = species[list[0].i].z < 0 ? list[0] : list[1], pos = neg === list[0] ? list[1] : list[0];
+  const time = (key) => {
+    const v = positive(sdef[key], `${path}.${key}`);
+    return key.startsWith('v') ? 1 / v : v; // a velocity's reciprocal is the time it stands for
+  };
+  return { n: neg, p: pos, tn: time(kn), tp: time(kp), n1: sdef.n1 === undefined ? NaN : positive(sdef.n1, `${path}.n1`) };
+}
+
 function nonNegative(v, path) {
   need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${JSON.stringify(v)}`);
   return v;
@@ -324,12 +347,27 @@ export function normalizeDevice(def) {
 // reaction runs only in those materials).
 function normalizeReaction(rdef, path, species, speciesIndex, materials, materialIndex, regions, RT) {
   need(isObject(rdef), `${path} must be an object`);
-  fields(rdef, path, ['nu', 'equation', 'fixed', 'kf']);
+  fields(rdef, path, ['nu', 'equation', 'fixed', 'kf', 'srh']);
   need((rdef.nu === undefined) !== (rdef.equation === undefined), `${path}: give the reaction as nu or as an equation, one of them`);
   const nu = rdef.nu ?? equationStoichiometry(rdef.equation, `${path}.equation`);
   const st = stoichiometry(nu, rdef.equation === undefined ? `${path}.nu` : `${path}.equation`, rdef.fixed, `${path}.fixed`, species, speciesIndex, RT);
   need(st.list.length > 0, `${path}: no mobile participants`);
   need(st.charge === 0, `${path}: charge is not balanced (Σ ν z = ${st.charge})`);
+  // SRH kinetics instead: srh maps material names to { tauN, tauP, n1 }.
+  need((rdef.kf === undefined) !== (rdef.srh === undefined), `${path}: give kf (mass action) or srh (trap-assisted), one of them`);
+  if (rdef.srh !== undefined) {
+    need(isObject(rdef.srh), `${path}.srh must map material names to { tauN, tauP, n1 }`);
+    const srh = new Array(materials.length).fill(null), kf = new Float64Array(materials.length), kfProfile = new Array(materials.length).fill(null);
+    for (const [mname, v] of Object.entries(rdef.srh)) {
+      need(materialIndex.has(mname), `${path}.srh.${mname}: unknown material`);
+      const m = materialIndex.get(mname);
+      srh[m] = srhLaw(v, `${path}.srh.${mname}`, st.list, species, ['tauN', 'tauP']);
+      for (const { i } of st.list) need(materials[m].present[i], `${path}.srh.${mname}: '${species[i].name}' is absent from material '${mname}'`);
+      kf[m] = 1; // (runs here)
+    }
+    const reactants = st.list.map(({ i, nu }) => ({ i, nu: -nu }));
+    return { reactants, products: [], fixedA: st.fixedA, kf, kfProfile, srh, generation: false };
+  }
   need(isObject(rdef.kf), `${path}.kf must map material names to forward rate constants`);
   // Each a number, or a profile { x, values } against the device's x (e.g. absorption); kf[m]
   // is then its largest value, which says whether the reaction runs in that material at all.
@@ -400,7 +438,7 @@ function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex,
   return (idef.reactions ?? []).map((rdef, k) => {
     const rpath = `${where}.reactions[${k}]`;
     need(isObject(rdef), `${rpath} must be { equation, fixed, k0, alpha } or { left, right, fixed, k0, alpha }`);
-    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha']);
+    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh']);
     let sides = rdef;
     if (rdef.equation !== undefined) {
       need(rdef.left === undefined && rdef.right === undefined, `${rpath}: give the reaction as an equation or as left and right, not both`);
@@ -420,6 +458,15 @@ function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex,
     }
     need(part.length > 0, `${rpath}: no species participate`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    if (rdef.srh !== undefined) {
+      need(rdef.k0 === undefined && rdef.alpha === undefined, `${rpath}: give srh or k0 (and alpha), not both`);
+      const srh = srhLaw(rdef.srh, `${rpath}.srh`, part, species, ['vn', 'vp']);
+      for (const p of part) {
+        const mat = p.side ? matR : matL;
+        need(!mat.conductor, `${rpath}.srh: SRH kinetics is for carriers in semiconductors, not a metal's ${species[p.i].name}`);
+      }
+      return { part, fixedA, srh };
+    }
     return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`) };
   });
 }
@@ -820,7 +867,7 @@ function defaultInterfaceLinks(matL, matR, species) {
 
 function transferCoefficient(v, path) {
   if (v === undefined) return 0.5;
-  need(isFiniteNumber(v) && v > 0 && v < 1, `${path} must be between 0 and 1, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v >= 0 && v <= 1, `${path} must be between 0 and 1, got ${JSON.stringify(v)}`);
   return v;
 }
 

package/src/index.js

@@ -63,13 +63,22 @@ export class Device {
   }
 
   /**
-   * Change part of the definition (deep-merged). A change to the terminals' drives alone (V, I,
-   * R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
+   * Change part of the definition (deep-merged). A contact given V or I drops the other, so
+   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. A change to the terminals'
+   * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
    * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
    * @param {object} patch a partial device definition, merged into the current one
    * @returns {this}
    */
   set(patch) {
+    // A contact given a new kind of drive drops the old one: { I: 0 } replaces a held V.
+    for (const side of ['left', 'right']) {
+      const c = patch?.contacts?.[side];
+      if (c && typeof c === 'object') {
+        if ('I' in c && !('V' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, V: undefined } } };
+        else if ('V' in c && !('I' in c)) patch = { ...patch, contacts: { ...patch.contacts, [side]: { ...c, I: undefined } } };
+      }
+    }
     const def = merge(this.def, patch);
     // Only the terminals' drives changed: update them in place, keeping the solver and its state
     // (a step in a source restarts the time stepping's order, as at any discontinuity).

package/src/plot.js

@@ -257,12 +257,13 @@ export function levelChart(tr, { width = 640, height = 360, ylabel = 'voltage (V
 
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
- * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
+ * diagram of electrons and holes. Options are those of `traces()` and `levelChart()`.
  * @param {import('./types.js').Solution} sol
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}
  */
 export function bandDiagram(sol, opts = {}) {
-  const { width, height, ylabel, range, xlim, title, ytick, ...pick } = opts;
+  const { width, height, ylabel = opts.energy ? 'electron energy (eV)' : undefined, range, xlim, title, ytick, ...pick } = opts;
   return levelChart(traces(sol, pick), { width, height, ylabel, range, xlim, title, ytick });
 }

package/src/solution.js

@@ -121,7 +121,7 @@ export function makeSolution(solver, result = {}) {
     const N = {};
     for (let i = 0; i < n; i++) N[species[i].name] = u[b * M + 1 + i];
     const rates = itf.reactions.map((_, k) => u[b * M + 1 + n + k]); // mol/(m²·s), forward
-    return { dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+    return { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
   });
 
   // Total charge per area in the device (space charge plus sheet charges).

package/src/solver.js

@@ -362,6 +362,7 @@ export class Solver {
     const { x: gx, segLength } = model.grid;
     this.rxs = model.reactions.map((rx) => ({
       kf: rx.kf,
+      srh: rx.srh, // per material: SRH kinetics in place of mass action, or null
       kfNode: Float64Array.from(gx, (x, g) => {
         const m = this.nodeMaterial[g], p = rx.kfProfile[m];
         return p ? profileMean(p, x - (g > 0 ? segLength[g - 1] : 0) / 2, x + (g < segLength.length ? segLength[g] : 0) / 2) : rx.kf[m];
@@ -563,9 +564,63 @@ export class Solver {
       // The row replaced: the basis vector's own stretch (its weight is 1, and no other vector has one).
       add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch);
     }
+    // A combination of immobile stretches (trap states: X⁰ + X⁻ under e⁻ + X⁰ = X⁻) is conserved
+    // node by node, since nothing carries it anywhere: at each node its weighted sum stays what
+    // it was, a row local to that node's block, in place of the balance row of one of them.
+    this.localConstraints = [];
+    const immobile = (st) => {
+      for (let q = st.regions[0]; q <= st.regions[1]; q++) if (materials[regions[q].material].D[st.species] > 0) return false;
+      return true;
+    };
+    for (const w of this.moieties) {
+      const parts = [...w.keys()].filter((k) => w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
+      const sts = parts.map((p) => this.stretches[p.stretch]);
+      if (sts.some((st) => st.conserved || !immobile(st) || conductor(st))) continue;
+      if (sts.some((st) => st.nodes[0] !== sts[0].nodes[0] || st.nodes[1] !== sts[0].nodes[1])) continue; // (side by side only)
+      for (const st of sts) st.conserved = true;
+      const row = parts.find((p) => p.w === 1) ?? parts[0];
+      this.localConstraints.push({
+        parts: parts.map((p) => ({ i: this.stretches[p.stretch].species, w: p.w })),
+        row: 1 + this.stretches[row.stretch].species,
+        nodes: sts[0].nodes,
+        reference: new Float64Array(sts[0].nodes[1] - sts[0].nodes[0] + 1),
+      });
+    }
     this.constrained = false;
   }
 
+  // Each local constraint's weighted sum at each node, as the state holds it now: what a steady
+  // solve keeps.
+  _captureLocal() {
+    const { n, c } = this;
+    for (const lc of this.localConstraints) {
+      for (let g = lc.nodes[0]; g <= lc.nodes[1]; g++) {
+        let t = 0;
+        for (const { i, w } of lc.parts) t += w * c[g * n + i];
+        lc.reference[g - lc.nodes[0]] = t;
+      }
+    }
+  }
+
+  // The local constraints' rows (steady solves only): Σ w c_i − reference at each node.
+  _applyLocalConstraints() {
+    const { n, M, c, res, dA: d } = this;
+    for (const lc of this.localConstraints) {
+      for (let g = lc.nodes[0]; g <= lc.nodes[1]; g++) {
+        const b = this.blockOfNode[g];
+        if (this.loc[b * M + lc.row] < 0) continue;
+        this._replaceRow(b, lc.row);
+        let t = 0;
+        for (const { i, w } of lc.parts) {
+          t += w * c[g * n + i];
+          this._dc(g, i, d);
+          for (let s = 0; s < M; s++) if (d[s] !== 0) this._j(b, lc.row, b, s, w * d[s]);
+        }
+        res[this.rix[b * M + lc.row]] = t - lc.reference[g - lc.nodes[0]];
+      }
+    }
+  }
+
   // A basis of the conserved combinations of stretch amounts: the null space of the
   // stoichiometry (a row per reaction, over the stretches it touches) together with a unit row
   // for each stretch fed from outside. Exact integer data, so plain elimination will do.
@@ -1115,6 +1170,7 @@ export class Solver {
     // flux), then contacts, then the circuit rows of the floating ones.
     this._terminals(dt);
     if (this.constrained && dt === Infinity && this.constraints.length > 0) this._applyConstraints();
+    if (this.constrained && dt === Infinity && this.localConstraints.length > 0) this._applyLocalConstraints();
     this.transformed = this.combining && dt !== Infinity;
     if (this.transformed) this._chargeRows(dt);
   }
@@ -1304,6 +1360,26 @@ export class Solver {
     const dr = this.dA;
     for (let x = 0; x < rxs.length; x++) {
       const rx = rxs[x];
+      const law = rx.srh?.[this.nodeMaterial[g]];
+      if (law) {
+        // SRH: dr is ∂rate/∂slot directly, from its sensitivities to ln n, ln p and a.
+        let aHi = rx.fixedA, aLo = 0;
+        for (let p = 0; p < rx.sp.length; p++) {
+          aHi += rx.nu[p] * u[b * M + 1 + rx.sp[p]];
+          aLo += rx.nu[p] * uLo[b * M + 1 + rx.sp[p]];
+        }
+        const { rate, Cn, Cp, Ca } = this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], aHi + aLo);
+        dr.fill(0);
+        this._dlnc(g, law.n.i, Cn, dr);
+        this._dlnc(g, law.p.i, Cp, dr);
+        for (let p = 0; p < rx.sp.length; p++) dr[1 + rx.sp[p]] += Ca * rx.nu[p];
+        for (let p = 0; p < rx.sp.length; p++) {
+          const row = 1 + rx.sp[p], w = v * rx.nu[p];
+          res[R[b * M + row]] += w * rate;
+          for (let k = 0; k < M; k++) if (dr[k] !== 0) this._j(b, row, b, k, w * dr[k]);
+        }
+        continue;
+      }
       let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g], aHi = rx.fixedA, aLo = 0;
       dr.fill(0); // ∂ ln P / ∂slot
       // Participants: reactants with ν > 0, then products with ν < 0.
@@ -1639,6 +1715,25 @@ export class Solver {
     d[0] = -this._Kz(g, k);
   }
 
+  // SRH kinetics (see srhLaw in device.js): the rate, and its sensitivities to ln n, ln p and
+  // a = A/RT. With no n₁ given, the trap is midgap: n₁ = p₁ = n_i = √(n p e^{−a}).
+  _srhRate(law, cn, cp, a) {
+    const { tn, tp } = law, lnnp = Math.log(cn) + Math.log(cp);
+    let n1, kN = 0, kP = 0, kA = 0; // ln n₁ = kN ln n + kP ln p + kA a + const
+    if (Number.isNaN(law.n1)) {
+      n1 = Math.exp((lnnp - a) / 2);
+      kN = kP = 0.5;
+      kA = -0.5;
+    } else n1 = law.n1;
+    const p1 = Math.exp(lnnp - a - Math.log(n1)), np = cn * cp;
+    const den = tp * (cn + n1) + tn * (cp + p1), f = -Math.expm1(-a);
+    const rate = (np * f) / den;
+    const dDn = tp * cn + tp * n1 * kN + tn * p1 * (1 - kN);
+    const dDp = tp * n1 * kP + tn * cp + tn * p1 * (1 - kP);
+    const dDa = tp * n1 * kA + tn * p1 * (-1 - kA);
+    return { rate, Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
+  }
+
   // A face reaction (see normalizeFaceReactions). Its rate r_k is an unknown of the face block,
   // with the row r_k − rate(u_L, u_R) = 0, and each participant's edge node takes ν·r_k (made
   // there when ν > 0). The rate couples the two edge nodes only through the face block between
@@ -1650,24 +1745,34 @@ export class Solver {
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     const al = rx.alpha;
     const dL = this.dA.fill(0), dR = this.dB.fill(0); // ∂ ln(prefactor)/∂slot, per side
-    let pref = rx.k0, aHi = rx.fixedA, aLo = 0;
+    let pref = rx.k0, aHi = rx.fixedA, aLo = 0, rate;
     for (const p of rx.part) {
       const g = p.side ? gR : gL, b = p.side ? bR : bL, o = b * M + 1 + p.i;
       aHi -= p.nu * u[o];
       aLo -= p.nu * uLo[o];
-      if (this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
+      if (rx.srh || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
       pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
     }
-    const { g: bv, gp } = bvFactor(aHi + aLo, al);
-    const rate = pref * bv;
-    // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
-    for (let s = 0; s < M; s++) {
-      dL[s] *= rate;
-      dR[s] *= rate;
+    if (rx.srh) {
+      // SRH, with n and p each at its own side's edge node.
+      const { n: pn, p: pp } = rx.srh, gn = pn.side ? gR : gL, gq = pp.side ? gR : gL;
+      const s = this._srhRate(rx.srh, c[gn * n + pn.i], c[gq * n + pp.i], aHi + aLo);
+      rate = s.rate;
+      this._dlnc(gn, pn.i, s.Cn, pn.side ? dR : dL);
+      this._dlnc(gq, pp.i, s.Cp, pp.side ? dR : dL);
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= s.Ca * p.nu;
+    } else {
+      const { g: bv, gp } = bvFactor(aHi + aLo, al);
+      rate = pref * bv;
+      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
+      for (let s = 0; s < M; s++) {
+        dL[s] *= rate;
+        dR[s] *= rate;
+      }
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= pref * gp * p.nu;
     }
-    for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= pref * gp * p.nu;
     const slot = 1 + n + k, o = bf * M + slot;
     res[R[o]] = u[o] - rate;
     this._j(bf, slot, bf, slot, 1);
@@ -2148,6 +2253,9 @@ export class Solver {
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
     let grow = 0; // longer first steps tried after a Newton failure (see below)
+    // The shortest step worth trying: round-off relative to the time, or the device's fastest
+    // time scale, whichever is shorter (a cold start can need steps far below a long run's 1e-14).
+    const floor = Math.min(1e-14 * Math.max(tEnd, 1e-300), this.fastestTime() * 1e-2);
     const pred = new Float64Array(this.u.length), guess = new Float64Array(this.u.length);
     const factor = (err, p) => (err > 0 ? Math.min(2, Math.max(0.2, 0.9 * Math.exp(Math.log(tol / err) / (p + 1)))) : 2);
     while (this.time < tEnd) {
@@ -2204,7 +2312,7 @@ export class Solver {
             grow = 3;
             dt = h / 4;
           }
-          if (dt < 1e-14 * Math.max(tEnd, 1e-300)) { failed = true; break; }
+          if (dt < floor) { failed = true; break; }
           continue;
         }
       } else {
@@ -2213,7 +2321,7 @@ export class Solver {
         if (!r.converged) {
           rejected++;
           dt = h / 4;
-          if (dt < 1e-14 * Math.max(tEnd, 1e-300)) { failed = true; break; }
+          if (dt < floor) { failed = true; break; }
           continue;
         }
         p = this._predict(pred, r.bdf);
@@ -2734,6 +2842,17 @@ export class Solver {
     return Number.isFinite(dMin) ? (L * L) / dMin : 1;
   }
 
+  // The fastest diffusion time: across the smallest cell, at the largest D.
+  fastestTime() {
+    let dMax = 0;
+    for (const mat of this.model.materials) {
+      for (let i = 0; i < this.n; i++) if (mat.present[i]) dMax = Math.max(dMax, mat.D[i]);
+    }
+    let h = Infinity;
+    for (const s of this.model.grid.segLength) if (s > 0) h = Math.min(h, s);
+    return dMax > 0 && Number.isFinite(h) ? (h * h) / dMax : this.slowestTime();
+  }
+
   /**
    * Steady state.
    * - If every species stretch is fed by a contact, nothing is conserved on its own, so the
@@ -2746,6 +2865,8 @@ export class Solver {
    */
   solveSteady(opts = {}) {
     this.conditioning = null;
+    this.computeConcentrations();
+    this._captureLocal(); // immobile combinations keep, node by node, what they hold now
     this.sourceTime = this.time;
     // Continuation applies where the right terminal is held at a voltage, against a held left one.
     const [dl, dr] = [this.terms[0].drive, this.terms[1].drive];
@@ -2921,8 +3042,10 @@ export class Solver {
         history.push({ dt, converged: r.converged, iterations: r.iterations, maxStep: 3 });
       }
       if (!r.converged) {
+        // Pseudo-transient continuation: down from a slow time scale until a step converges,
+        // as far as the fastest (slow ions mustn't stop it short of what a cold start needs).
         dt = dt >= giant ? tau * 1e-6 : dt / 4;
-        if (dt < tau * 1e-15) break;
+        if (dt < Math.min(tau * 1e-15, this.fastestTime() * 1e-2)) break;
         continue;
       }
       if (dt === Infinity) {

package/src/traces.js

@@ -62,7 +62,11 @@ export function typeset(name, z) {
  * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
  * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
  * @param {import('./types.js').Solution} sol
- * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ * With `energy: true` it's the familiar band diagram instead, energy up: electrons and holes as
+ * electron energies in eV (E = −V: E_c and E_v from the standard levels, E_Fn and E_Fp, or E_F
+ * where only electrons are present, from the levels), with any redox levels and φ (as −qφ) turned
+ * over too. Only electrons and holes have bands; ions are refused (draw them as species voltages).
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[], energy?: boolean,
  *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
  *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
  *   species to show (default: every charged one), whether to show standard levels (default true)
@@ -73,31 +77,40 @@ export function typeset(name, z) {
  * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
  *   faces: number[], range: [number, number] }}
  */
-export function traces(sol, { species, standard = true, phi = false, levels = [], labels = {}, shifts = {} } = {}) {
+export function traces(sol, { species, standard = true, phi = false, energy = false, levels = [], labels = {}, shifts = {} } = {}) {
   const names = Object.keys(sol.V);
   const role = (name) => speciesRole(sol, name).role;
   const slotOf = (name) => speciesRole(sol, name).slot;
-  const shown = species ?? names.filter((name) => finite(sol.V[name]));
+  const carriers = ['e-', 'h+'];
+  const shown = species ?? names.filter((name) => finite(sol.V[name]) && (!energy || carriers.includes(name)));
+  if (energy) {
+    for (const name of shown) {
+      if (!carriers.includes(name)) throw new Error(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
+    }
+  }
+  const sign = energy ? -1 : 1, unit = energy ? 'eV' : 'V';
+  const bipolar = names.includes('h+');
+  const energyLabels = { 'V:e-': bipolar ? 'E_{Fn}' : 'E_F', 'Vstd:e-': 'E_c', 'V:h+': 'E_{Fp}', 'Vstd:h+': 'E_v' };
   const zOf = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
   const pretty = (name) => (name in zOf ? typeset(name, zOf[name]) : name);
   const series = [];
   for (const name of shown) {
     if (!names.includes(name)) throw new Error(`traces: no charged species '${name}' in the solution`);
     const shift = shifts[name] ?? 0;
-    const at = (y) => (shift ? y.map((v) => v + shift) : y);
+    const at = (y) => (shift || energy ? Array.from(y, (v) => sign * v + shift) : y);
     const common = { species: name, role: role(name), slot: slotOf(name), ...(shift ? { shift } : {}) };
-    if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
-    if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
+    if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: energy ? energyLabels[`V:${name}`] : `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
+    if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: energy ? energyLabels[`Vstd:${name}`] : `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
   }
   if (Array.isArray(phi)) {
     const known = sol.regions.flatMap((r) => [r.name, r.material]);
     for (const name of phi) if (!known.includes(name)) throw new Error(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
     const inside = sol.regions.map((r) => phi.includes(r.name) || phi.includes(r.material));
-    series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? v : NaN)) });
-  } else if (phi) series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: sol.phi });
+    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
+  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Array.from(sol.phi, (v) => -v) : sol.phi });
   const couples = [...new Set(levels.map((lv) => lv.half.equation))];
   levels.forEach((lv, k) => {
-    const y = level(sol, lv.half, { standard: lv.standard });
+    const y = energy ? Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
     series.push({
       id: `level:${k}`,
       label: lv.label ?? `${lv.standard ? 'V° ' : ''}${lv.half.equation.split(' ').map(pretty).join(' ')}`,
@@ -109,7 +122,7 @@ export function traces(sol, { species, standard = true, phi = false, levels = []
   });
   for (const s of series) {
     if (labels[s.id] !== undefined) s.label = labels[s.id];
-    if (s.shift) s.label += ` ⌇${s.shift > 0 ? '+' : '−'}${Math.abs(s.shift)} V`;
+    if (s.shift) s.label += ` ⌇${s.shift > 0 ? '+' : '−'}${Math.abs(s.shift)} ${unit}`;
   }
   let lo = Infinity, hi = -Infinity;
   for (const s of series) {

package/types/index.d.ts

@@ -13,8 +13,9 @@ export class Device {
     get solver(): any;
     get grid(): any;
     /**
-     * Change part of the definition (deep-merged). A change to the terminals' drives alone (V, I,
-     * R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
+     * Change part of the definition (deep-merged). A contact given V or I drops the other, so
+     * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. A change to the terminals'
+     * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
      * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
      * @param {object} patch a partial device definition, merged into the current one
      * @returns {this}

package/types/plot.d.ts

@@ -37,7 +37,8 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
 }): string;
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
- * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
+ * diagram of electrons and holes. Options are those of `traces()` and `levelChart()`.
  * @param {import('./types.js').Solution} sol
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}

package/types/solver.d.ts

@@ -103,7 +103,10 @@ export class Solver {
     stretchOf: Int32Array<ArrayBuffer>;
     moieties: Float64Array<ArrayBuffer>[];
     constraints: any[];
+    localConstraints: any[];
     constrained: boolean;
+    _captureLocal(): void;
+    _applyLocalConstraints(): void;
     _conservedMoieties(): Float64Array<ArrayBuffer>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
@@ -152,6 +155,12 @@ export class Solver {
     _segmentMixing(s: any, bL: any, bR: any, Dm: any, h: any, mat: any): void;
     mixWork: Float64Array<any>[];
     _dc(g: any, k: any, d: any): void;
+    _srhRate(law: any, cn: any, cp: any, a: any): {
+        rate: number;
+        Cn: number;
+        Cp: number;
+        Ca: number;
+    };
     _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any): void;
     _terminals(dt: any): void;
     _circuit(k: any): void;
@@ -288,6 +297,7 @@ export class Solver {
     _assembleBookkeeping(dt: any): void;
     _accumulateBoundaryIntake(dt: any, cN: any): void;
     slowestTime(): number;
+    fastestTime(): number;
     /**
      * Steady state.
      * - If every species stretch is fed by a contact, nothing is conserved on its own, so the

package/types/traces.d.ts

@@ -40,7 +40,11 @@ export function typeset(name: string, z: number): string;
  * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
  * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
  * @param {import('./types.js').Solution} sol
- * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ * With `energy: true` it's the familiar band diagram instead, energy up: electrons and holes as
+ * electron energies in eV (E = −V: E_c and E_v from the standard levels, E_Fn and E_Fp, or E_F
+ * where only electrons are present, from the levels), with any redox levels and φ (as −qφ) turned
+ * over too. Only electrons and holes have bands; ions are refused (draw them as species voltages).
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[], energy?: boolean,
  *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
  *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
  *   species to show (default: every charged one), whether to show standard levels (default true)
@@ -51,10 +55,11 @@ export function typeset(name: string, z: number): string;
  * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
  *   faces: number[], range: [number, number] }}
  */
-export function traces(sol: import("./types.js").Solution, { species, standard, phi, levels, labels, shifts }?: {
+export function traces(sol: import("./types.js").Solution, { species, standard, phi, energy, levels, labels, shifts }?: {
     species?: string[];
     standard?: boolean;
     phi?: boolean | string[];
+    energy?: boolean;
     levels?: {
         half: {
             equation: string;