driftlet 0.3.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 demo](https://markblundeberg.github.io/driftlet/demos/solar.html), [`reactions`](test/reactions.test.js) test: generation is a reaction from a photon reservoir (uniform per material), SRH runs through explicit trap species | `J_sc = qG(L_n + L_p + W)`; 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.3.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) |  |  |
+| [![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
@@ -205,8 +205,9 @@ current. Supported physics:
   COMSOL.
 - **Cross-diffusion.** Each species moves down its own μ̄ with its own D (the statistics can be
   non-ideal); there are no Stefan–Maxwell or Onsager cross terms beyond eddy mixing.
-- **Heat and optics.** Temperature is uniform. Generation is a reaction, uniform within a
-  material; there's no optical model or absorption profile. For those, see
+- **Heat and optics.** Temperature is uniform. Generation is a reaction, with Beer–Lambert
+  absorption as its profile at most; there's no optical model (reflection, interference,
+  photon recycling). For those, see
   [Driftfusion](https://github.com/barnesgroupICL/Driftfusion),
   [SIMsalabim](https://github.com/kostergroup/SIMsalabim) or
   [PyBaMM](https://github.com/pybamm-team/PyBaMM).
@@ -232,6 +233,10 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Long pn diode with recombination | Shockley J–V incl. depletion recombination | 2e-3 |
 | Haynes–Shockley pulse | an injected hole packet's drift, spread and decay at the ambipolar μ*, D*, 1/τ*; nothing lost while it goes in | 2e-4; 1e-2; 2e-3 |
 | 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

@@ -103,7 +103,7 @@ regions: [
   reactions) does: its `c0` fixes the amount it conserves. Concentrations are positive ($`\bar\mu`$ is
   logarithmic in them); to have none of a species in a region, leave it out of that region's
   material. In a strictly neutral region, $`\sum z \cdot c_0`$ must be zero.
-  An entry can instead be a profile, `{ x: [...], c: [...] }`, against the device's x (m, not
+  An entry can instead be a profile, `{ x: [...], values: [...] }`, against the device's x (m, not
   the region's own), piecewise linear between its points and constant beyond its ends, so a
   transient can start from a state it didn't simulate reaching: a packet already injected, a
   gradient laid down. Skip `solve()`, which goes straight to the steady state, and `advance()`
@@ -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,17 +269,34 @@ $`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
-generation rate (mol/(m³·s)). It's uniform within each material listed in `kf` (there's no optical
-absorption profile). The photons' $`\mu`$ is the honest part: light is a reservoir far from the
+generation rate (mol/(m³·s)). The photons' $`\mu`$ is the honest part: light is a reservoir far from the
 device's temperature, and the rate still vanishes at $`A = 0`$.
 
 ```js nocheck
 bulkReactions: [{ equation: 'photon = e- + h+', fixed: { photon: units.eV(3) }, kf: { Si: 0.1 } }]
 ```
 
+A rate constant can also vary with position: give it as a profile `{ x: [...], values: [...] }`
+against the device's x (the same tables as `c0`), piecewise linear and constant beyond its ends,
+used only at that material's nodes. Each node takes the profile's mean over its box (not its
+value at the node), so the total rate is exact on any grid: light absorbed within a fraction of
+a cell still generates what it should. The kit's `photogeneration()` writes Beer–Lambert
+absorption this way.
+
 ## Contacts
 
 A contact is an interface whose far side is an **outside phase with known levels**: think of it as
@@ -480,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
@@ -529,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

@@ -131,6 +131,17 @@ Helpers that write sources as plain data:
 - **`recombination({ material, tau, majority })`**: band-to-band recombination e⁻ + h⁺ ⇌ 0 as
   a bulk reaction, from the low-injection minority lifetime it gives at that majority density,
   $`k_f = 1/(\tau \cdot n_{\mathrm{maj}})`$.
+- **`photogeneration({ material, flux, alpha, mu, from, to, makes })`**: light absorbed as it goes in
+  (Beer–Lambert). A photon flux (mol/(m²·s); a power P at photon energy E is
+  $`P/(E N_A)`$) enters the material at x = `from` heading toward +x and generates pairs at
+  $`G(x) = \Phi\alpha e^{-\alpha(x - \mathrm{from})}`$ until `to`, the material's far end. It's
+  photon ⇌ e⁻ + h⁺ from a photon reservoir at $`\mu`$ = `mu` (J/mol, well above the gap, e.g.
+  `units.eV(3)`), with `kf` a profile against x. `makes` replaces the right-hand side: in an
+  organic semiconductor, light makes neutral excitons, `makes: 'X'`. The table generates exactly what the light
+  loses, $`\Phi(1 - e^{-\alpha(\mathrm{to} - \mathrm{from})})`$, and the solver averages it
+  over each node's box, so the total stays right on a grid coarser than $`1/\alpha`$ (where
+  carriers start within a cell still needs the grid). Light through several materials is one
+  call per material, each with the flux that reaches it.
 
 Read a transient at points inside the device with `advance(t, { probes })` (see the
 [device reference](device.md#using-a-device)). And `units` converts back out of SI for display:
@@ -178,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.3.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.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`.
@@ -45,15 +45,20 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   `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`), the data library (`aqueous`, `semiconductor`,
+  `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⁻}`).
 - **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
-  mol/(m³·s) (`units.perCm3` converts cm⁻³·s⁻¹ too). A face reaction's `k0` is in mol/(m²·s);
+  `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);
   its exchange current density is F·k0 per electron at the reference concentrations.
 
 ## Template: a semiconductor junction
@@ -221,7 +226,7 @@ console.log(`peak at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ${units.toPer
 
 To start from a state instead of simulating how it got there (a packet already injected, a
 salt gradient laid down), give a region's `c0` a profile against the device's x:
-`c0: { 'h+': { x: [...], c: [...] } }`, piecewise linear. A given `c0` is the starting state,
+`c0: { 'h+': { x: [...], values: [...] } }`, piecewise linear. A given `c0` is the starting state,
 even for a species a contact feeds; species without one start at their contact's level, with φ
 made neutral node by node (electrons follow the holes). Then `advance()` without `solve()`, which would go straight to the steady
 state.
@@ -243,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.3.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.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,
@@ -257,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²`;
   },
 });
@@ -270,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.3.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

@@ -78,7 +78,7 @@ export function unitWarnings(def) {
         conc(`${path}.c0.${sname}`, c);
         continue;
       }
-      if (Array.isArray(c.c)) conc(`${path}.c0.${sname}.c`, Math.max(...c.c));
+      if (Array.isArray(c.values)) conc(`${path}.c0.${sname}.values`, Math.max(...c.values));
       // A profile is against the device's x, not the region's own.
       const x0 = regionX0[r], x1 = x0 + reg.length;
       if (Array.isArray(c.x) && c.x.length > 0 && (c.x.at(-1) < x0 || c.x[0] > x1)) {
@@ -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].c);
+      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

@@ -55,6 +55,44 @@ function positive(v, path) {
   return v;
 }
 
+// A profile against the device's x: { x, values }, piecewise linear between its points and
+// constant beyond its ends (read with profileAt).
+function profile(v, path, what, ok, okText) {
+  fields(v, path, ['x', 'values']);
+  need(
+    Array.isArray(v.x) && Array.isArray(v.values) && v.x.length > 0 && v.x.length === v.values.length,
+    `${path} must be a profile { x, values }: two arrays of the same length, positions (m, the device's x) and ${what}`,
+  );
+  v.x.forEach((xk, k) => {
+    need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${path}.x must be finite and strictly increasing, but x[${k}] is ${JSON.stringify(xk)}`);
+  });
+  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${JSON.stringify(y)}`));
+  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;
@@ -179,8 +217,7 @@ export function normalizeDevice(def) {
       );
     }
     // Initial composition: the starting state, and the conserved amount of any spectator. Each
-    // entry is a number, or a profile { x, c } against the device's x (piecewise linear, constant
-    // beyond its ends), which is the starting state even for a species a contact feeds.
+    // entry is a number or a profile { x, values } against the device's x.
     const c0 = new Float64Array(nSpecies).fill(NaN);
     const c0Profile = new Array(nSpecies).fill(null);
     if (reg.c0 !== undefined) {
@@ -192,19 +229,10 @@ export function normalizeDevice(def) {
         need(mat.present[i], `${at}: '${sname}' is absent from material '${mat.name}'`);
         const none = `; to have none of '${sname}' here, leave it out of material '${mat.name}' (a region of another material without it, if it's present elsewhere)`;
         if (isObject(v)) {
-          fields(v, at, ['x', 'c']);
-          need(
-            Array.isArray(v.x) && Array.isArray(v.c) && v.x.length > 0 && v.x.length === v.c.length,
-            `${at} must be a profile { x, c }: two arrays of the same length, positions (m, the device's x) and concentrations (mol/m³)`,
-          );
-          v.x.forEach((xk, k) => {
-            need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${at}.x must be finite and strictly increasing, but x[${k}] is ${JSON.stringify(xk)}`);
-          });
-          v.c.forEach((ck, k) => need(isFiniteNumber(ck) && ck > 0, `${at}.c[${k}] must be a concentration > 0 (mol/m³), got ${JSON.stringify(ck)}${none}`));
-          c0Profile[i] = { x: Float64Array.from(v.x), c: Float64Array.from(v.c) };
+          c0Profile[i] = profile(v, at, 'concentrations (mol/m³)', (ck) => ck > 0, `a concentration > 0 (mol/m³)${none}`);
           continue;
         }
-        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, c }, got ${JSON.stringify(v)}${none}`);
+        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, values }, got ${JSON.stringify(v)}${none}`);
         c0[i] = v;
       }
     }
@@ -319,18 +347,38 @@ 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`);
-  const kf = new Float64Array(materials.length);
+  // 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.
+  const kf = new Float64Array(materials.length), kfProfile = new Array(materials.length).fill(null);
   for (const [mname, v] of Object.entries(rdef.kf)) {
     need(materialIndex.has(mname), `${path}.kf.${mname}: unknown material`);
     const m = materialIndex.get(mname);
-    kf[m] = nonNegative(v, `${path}.kf.${mname}`);
+    if (isObject(v)) {
+      kfProfile[m] = profile(v, `${path}.kf.${mname}`, 'rate constants', (k) => k >= 0, 'a rate constant ≥ 0');
+      kf[m] = Math.max(...kfProfile[m].values);
+    } else kf[m] = nonNegative(v, `${path}.kf.${mname}`);
     for (const { i } of st.list) {
       need(materials[m].present[i], `${path}.kf.${mname}: '${species[i].name}' is absent from material '${mname}'`);
     }
@@ -342,6 +390,7 @@ function normalizeReaction(rdef, path, species, speciesIndex, materials, materia
     products,
     fixedA: st.fixedA, // fixed participants' share of A/RT
     kf,
+    kfProfile,
     // Species made only from (or turned only into) fixed reservoirs, such as photogeneration
     // from a photon reservoir: a source that can hold the device far from equilibrium.
     generation: st.nFixed > 0 && (reactants.length === 0 || products.length === 0),
@@ -389,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`);
@@ -409,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`) };
   });
 }
@@ -809,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/kit.js

@@ -9,7 +9,7 @@ export { build, combine, layer, ohmic, bath } from './stack.js';
 export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
 export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
-export { pulse, square, triangle, ramp, injector, recombination } from './sources.js';
+export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from './sources.js';
 export { describe, unitWarnings } from './describe.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
 

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

@@ -148,8 +148,8 @@ import { nextBreakpoint, sourceAt } from './device.js';
 import { DeviceError } from './errors.js';
 import { powi, powr } from './pow.js';
 
-// A c0 profile's value at x: piecewise linear, constant beyond its ends.
-function profileAt({ x, c }, at) {
+// A profile's value at x (c0, kf): piecewise linear, constant beyond its ends.
+function profileAt({ x, values: c }, at) {
   if (at <= x[0]) return c[0];
   const last = x.length - 1;
   if (at >= x[last]) return c[last];
@@ -162,6 +162,23 @@ function profileAt({ x, c }, at) {
   return c[lo] + ((c[hi] - c[lo]) * (at - x[lo])) / (x[hi] - x[lo]);
 }
 
+// A profile's mean over [a, b], exactly (its integral is piecewise quadratic).
+function profileMean(p, a, b) {
+  if (!(b > a)) return profileAt(p, a);
+  const { x, values: v } = p, last = x.length - 1;
+  // ∫ from x[0] to t.
+  const integral = (t) => {
+    if (t <= x[0]) return v[0] * (t - x[0]);
+    let sum = 0;
+    for (let k = 0; k < last; k++) {
+      if (t <= x[k + 1]) return sum + ((v[k] + profileAt(p, t)) / 2) * (t - x[k]);
+      sum += ((v[k] + v[k + 1]) / 2) * (x[k + 1] - x[k]);
+    }
+    return sum + v[last] * (t - x[last]);
+  };
+  return (integral(b) - integral(a)) / (b - a);
+}
+
 export class SolverError extends Error {
   constructor(message, details) {
     super(message);
@@ -339,8 +356,17 @@ export class Solver {
     this.dtNext = undefined;
 
     // Bulk reactions as flat participant lists: reactants with +ν, products with −ν.
+    // Each has its rate constant at every node: its material's, or its profile's mean over the
+    // node's box, so that what a sharply varying profile (strongly absorbed light) generates
+    // in all is exact on any grid.
+    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];
+      }),
       generation: rx.generation,
       fixedA: rx.fixedA,
       sp: Int32Array.from([...rx.reactants, ...rx.products], (p) => p.i),
@@ -538,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.
@@ -765,7 +845,9 @@ export class Solver {
     u.fill(0);
     this.uLo.fill(0);
     const eta = new Float64Array(n), cFix = new Float64Array(n), mode = new Int8Array(n); // 1 level, 2 amount
-    let phiHat = 0;
+    // φ̂ runs from the left: from a pinned (or gated) left contact's φ at its zero charge, else 0.
+    const leftPhi = model.contacts.left.phi;
+    let phiHat = leftPhi.type === 'pinned' || leftPhi.type === 'capacitive' ? (this.termV[0] - leftPhi.zeroCharge) / this.VT : 0;
     for (let r = 0; r < regions.length; r++) {
       if (r > 0) phiHat += interfaces[r - 1].dipole / this.VT;
       const reg = regions[r], mat = materials[reg.material];
@@ -797,7 +879,8 @@ export class Solver {
         } else if (!st.contactFed) {
           if (!(reg.c0[i] > 0)) {
             throw new SolverError(
-              `regions[${r}].c0.${species[i].name}: a species that doesn't reach a contact needs its initial concentration`,
+              `regions[${r}].c0.${species[i].name}: a species that doesn't reach a contact needs its initial concentration` +
+                (st.connected ? ' (reactions make and consume it, so this is only where the solve starts, not an amount it keeps: a tiny value will do)' : ', which fixes the amount it conserves'),
             );
           }
           mode[i] = 2;
@@ -880,6 +963,9 @@ export class Solver {
         let lo = ph - 1, hi = ph + 1;
         while (charge(lo) < 0 && lo > -1e4) lo -= 2 * (hi - lo);
         while (charge(hi) > 0 && hi < 1e4) hi += 2 * (hi - lo);
+        // Out of reach (every responding carrier has one sign and nothing balances it, as in an
+        // undoped layer that holds only holes): keep the running φ̂ rather than run it to ±∞.
+        if (charge(lo) < 0 || charge(hi) > 0) return ph;
         for (let it = 0; it < 200 && hi - lo > 1e-12; it++) {
           const m = 0.5 * (lo + hi);
           if (charge(m) > 0) lo = m;
@@ -1084,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);
   }
@@ -1269,11 +1356,31 @@ export class Solver {
   // (compensated) η. Reactants are consumed (+v·ν·r in their balance), products made (−v·ν·r).
   _bulkReactions(g, rxs) {
     const { n, M, u, uLo, res, c } = this, R = this.rix;
-    const b = this.blockOfNode[g], v = this.model.grid.vol[g], m = this.nodeMaterial[g];
+    const b = this.blockOfNode[g], v = this.model.grid.vol[g];
     const dr = this.dA;
     for (let x = 0; x < rxs.length; x++) {
       const rx = rxs[x];
-      let P = rx.generation ? rx.kf[m] * this.generationScale : rx.kf[m], aHi = rx.fixedA, aLo = 0;
+      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.
       for (let p = 0; p < rx.sp.length; p++) {
@@ -1608,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
@@ -1619,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);
@@ -2117,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) {
@@ -2173,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 {
@@ -2182,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);
@@ -2703,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
@@ -2715,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];
@@ -2890,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/sources.js

@@ -101,3 +101,39 @@ export function recombination({ material, tau, majority } = {}) {
   need(num(majority) && majority > 0, `recombination: majority must be the majority carrier density > 0 (mol/m³; units.perCm3 converts), got ${majority}`);
   return { equation: 'e- + h+ = 0', kf: { [material]: 1 / (tau * majority) } };
 }
+
+/**
+ * Photogeneration by light absorbed in a material (Beer–Lambert): a photon flux entering at x =
+ * `from` and travelling toward +x, generating pairs at G(x) = flux · α · e^{−α(x − from)} up to
+ * x = `to`. Written as photon ⇌ e⁻ + h⁺ (or whatever `makes` says, such as an exciton 'X') from a
+ * photon reservoir at μ = `mu` (J/mol; well above what it makes, so the rate is G itself), with
+ * kf as a profile against the device's x. The table is
+ * exact in what it generates in all (each segment's mean is the exponential's), and the solver
+ * averages it over each node's box, so the total is right on any grid.
+ * @param {{ material: string, flux: number, alpha: number, mu: number, from?: number, to: number, makes?: string }} opts
+ *   material name; photons absorbed, mol/(m²·s); absorption coefficient, 1/m; the photons' μ,
+ *   J/mol; where the light enters and where the material ends (m, the device's x); the
+ *   reaction's right-hand side (default 'e- + h+')
+ * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
+ */
+export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes = 'e- + h+' } = {}) {
+  need(typeof material === 'string', 'photogeneration: give the material, by name');
+  need(num(flux) && flux >= 0, `photogeneration: flux must be the photon flux ≥ 0 entering the material (mol/(m²·s)), got ${flux}`);
+  need(num(alpha) && alpha > 0, `photogeneration: alpha must be the absorption coefficient > 0 (1/m; 1/cm × 100), got ${alpha}`);
+  need(num(mu), `photogeneration: mu must be the photons' μ (J/mol), well above the gap: units.eV(3), say`);
+  need(typeof makes === 'string' && makes.trim() !== '', `photogeneration: makes must be what the light makes, as an equation's side ('e- + h+', 'X'), got ${makes}`);
+  need(num(from) && num(to) && to > from, `photogeneration: from and to must be positions with to > from (m, the device's x), got ${from} and ${to}`);
+  // Evenly spaced points, at most 0.05 absorption lengths apart, out to 50 of them (beyond,
+  // nothing is left), then `to`.
+  const depth = alpha * (to - from), reach = Math.min(depth, 50), n = Math.ceil(reach / 0.05), step = reach / n;
+  const taus = Array.from({ length: n + 1 }, (_, k) => k * step);
+  if (depth > 50) taus.push(depth);
+  // A straight line between two points of e^{−τ} encloses (Δτ/2)·coth(Δτ/2) times too much: each
+  // value is scaled back by that, so the total is the exponential's own (to ~Δτ⁴).
+  const fix = (step / 2) / Math.tanh(step / 2);
+  return {
+    equation: `photon = ${makes}`,
+    fixed: { photon: mu },
+    kf: { [material]: { x: taus.map((t) => from + t / alpha), values: taus.map((t) => (flux * alpha * Math.exp(-t)) / fix) } },
+  };
+}

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/src/types.js

@@ -51,13 +51,18 @@
  * @property {number} [hRight] right-end cell size, overriding hmin
  */
 
+/**
+ * A table against the device's x (m): piecewise linear between its points, constant beyond them.
+ * @typedef {{ x: number[], values: number[] }} Profile
+ */
+
 /**
  * @typedef {object} RegionDef
  * @property {string} material material name
  * @property {number} length m
  * @property {string} [name]
  * @property {number} [fixedCharge] immobile charge density, C/m³
- * @property {Record<string, number | { x: number[], c: number[] }>} [c0] initial concentrations,
+ * @property {Record<string, number | Profile>} [c0] initial concentrations,
  *   mol/m³ (required for species not connected to a contact: it fixes the amount they conserve);
  *   or a profile against the device's x (m), piecewise linear; either is the starting state
  * @property {number} [velocity] imposed flow toward +x, m/s, carrying every mobile species
@@ -99,7 +104,8 @@
  * @property {Record<string, number>} [nu] signed stoichiometric coefficients (ν < 0 consumed)
  * @property {string} [equation] the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {Record<string, number>} kf forward rate constant per material name
+ * @property {Record<string, number | Profile>} kf forward rate constant per material name, or a
+ *   profile of it against the device's x (an absorption profile, for photogeneration)
  */
 
 /**

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/kit.d.ts

@@ -57,6 +57,6 @@ export type VacuumSide = {
 export { build, combine, layer, ohmic, bath } from "./stack.js";
 export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
-export { pulse, square, triangle, ramp, injector, recombination } from "./sources.js";
+export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

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/sources.d.ts

@@ -100,3 +100,33 @@ export function recombination({ material, tau, majority }?: {
     equation: string;
     kf: Record<string, number>;
 };
+/**
+ * Photogeneration by light absorbed in a material (Beer–Lambert): a photon flux entering at x =
+ * `from` and travelling toward +x, generating pairs at G(x) = flux · α · e^{−α(x − from)} up to
+ * x = `to`. Written as photon ⇌ e⁻ + h⁺ (or whatever `makes` says, such as an exciton 'X') from a
+ * photon reservoir at μ = `mu` (J/mol; well above what it makes, so the rate is G itself), with
+ * kf as a profile against the device's x. The table is
+ * exact in what it generates in all (each segment's mean is the exponential's), and the solver
+ * averages it over each node's box, so the total is right on any grid.
+ * @param {{ material: string, flux: number, alpha: number, mu: number, from?: number, to: number, makes?: string }} opts
+ *   material name; photons absorbed, mol/(m²·s); absorption coefficient, 1/m; the photons' μ,
+ *   J/mol; where the light enters and where the material ends (m, the device's x); the
+ *   reaction's right-hand side (default 'e- + h+')
+ * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
+ */
+export function photogeneration({ material, flux, alpha, mu, from, to, makes }?: {
+    material: string;
+    flux: number;
+    alpha: number;
+    mu: number;
+    from?: number;
+    to: number;
+    makes?: string;
+}): {
+    equation: string;
+    fixed: Record<string, number>;
+    kf: Record<string, {
+        x: number[];
+        values: number[];
+    }>;
+};

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;

package/types/types.d.ts

@@ -115,6 +115,13 @@ export type GridOptions = {
      */
     hRight?: number;
 };
+/**
+ * A table against the device's x (m): piecewise linear between its points, constant beyond them.
+ */
+export type Profile = {
+    x: number[];
+    values: number[];
+};
 export type RegionDef = {
     /**
      * material name
@@ -134,10 +141,7 @@ export type RegionDef = {
      * mol/m³ (required for species not connected to a contact: it fixes the amount they conserve);
      * or a profile against the device's x (m), piecewise linear; either is the starting state
      */
-    c0?: Record<string, number | {
-        x: number[];
-        c: number[];
-    }>;
+    c0?: Record<string, number | Profile>;
     /**
      * imposed flow toward +x, m/s, carrying every mobile species
      */
@@ -239,9 +243,10 @@ export type BulkReactionDef = {
      */
     fixed?: Record<string, number>;
     /**
-     * forward rate constant per material name
+     * forward rate constant per material name, or a
+     * profile of it against the device's x (an absorption profile, for photogeneration)
      */
-    kf: Record<string, number>;
+    kf: Record<string, number | Profile>;
 };
 /**
  * Contacts use the same laws as internal faces; the outside is a phase with known levels