driftlet 1.0.1 → 1.1.0

package/README.md

@@ -10,7 +10,7 @@
 
 **driftlet simulates charged species moving through one-dimensional devices**: semiconductor
 junctions and solar cells, electrochemical cells and batteries, double layers, membranes and
-nerves. It's a small JavaScript library with no dependencies, fast enough to solve live in a
+nerves. It's a JavaScript library with no dependencies, fast enough to solve live in a
 web page as you drag a slider.
 
 [Live demos](https://markblundeberg.github.io/driftlet/demos/) · [npm](https://www.npmjs.com/package/driftlet) ·
@@ -56,7 +56,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@1.0.1/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@1.1.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).
 

package/docs/data.md

@@ -53,16 +53,37 @@ with that reaction should hold too.
   Fe³⁺ and Fe²⁺ gives $`E^\circ(\mathrm{Fe}^{3+}/\mathrm{Fe}^{2+})`$ = 0.769 V, against the
   tabulated 0.771 V, which is what a Fe³⁺/Fe²⁺ redox demo needs.
 
-## Semiconductors, 300 K
+## Semiconductors, 300 K and other temperatures
 
-`semiconductor(name, { material })` returns electrons `e-` and holes `h+` and the material:
-$`c_{\mathrm{ref}} = N_c`$ and $`N_v`$, D from the mobilities by the Einstein relation at 300 K,
+`semiconductor(name, { material, T })` returns electrons `e-` and holes `h+` and the material:
+$`c_{\mathrm{ref}} = N_c`$ and $`N_v`$, D from the mobilities by the Einstein relation at T,
 $`\mu^\circ_{\mathrm{e}^-} = 0`$ (so $`\phi`$ sits at the conduction band) and
-$`\mu^\circ_{\mathrm{h}^+} = E_g \cdot F`$. The data are for 300 K, so give the device `T: 300`.
-Statistics are ideal (Boltzmann); add Fermi–Dirac statistics to the material for degenerate
-doping. The data are in `SEMICONDUCTORS`, in the source's units (cm⁻³, cm²/(V·s), eV).
+$`\mu^\circ_{\mathrm{h}^+} = E_g \cdot F`$. The table is for 300 K, the default; `T` (150 to 500 K)
+moves it as [below](#at-other-temperatures). Statistics are ideal (Boltzmann); add Fermi–Dirac
+statistics to the material for degenerate doping. The data are in `SEMICONDUCTORS`, in the
+source's units (cm⁻³, cm²/(V·s), eV). In the material they're in SI: $`N_c`$ and $`N_v`$ are the
+`cRef` of e⁻ and h⁺ in mol/m³, at `materials.Si.species['e-'].cRef` and `['h+'].cRef` (the
+`species` list carries only names and charges).
+
+**Give the device the same `T`.** The material's gap, $`N_c`$, $`N_v`$ and D are for the
+temperature it was made at, and it carries that temperature as `materials.Si.T`. A device at
+another temperature warns, in `sol.warnings` (so `check()`) and `describe()`, naming both
+temperatures. The device's own default is 298.15 K (25 °C, the ions' temperature), not the
+table's 300 K, so a semiconductor device says `T: 300`: at 298.15 K the 300 K data's
+intrinsic density is 13% low. A material written by hand has no `T` and is never warned about.
+
+To change the temperature of a live device, give it the material for the new T in the same
+`set()`. The state carries over as a warm start:
+
+```js nocheck
+dev.set({ T: 350, materials: semiconductor('Si', { T: 350 }).materials });
+```
+
+A `set({ T })` alone changes kT but not the material's data, and warns. (A material with a
+`trap()` in it: remake it with `trap(semiconductor('Si', { T }), …)` the same way. The trap
+takes its material's T.)
 
-| | $`\varepsilon_r`$ | $`E_g`$ (eV) | $`\chi`$ (V) | $`N_c`$ (cm⁻³) | $`N_v`$ (cm⁻³) | $`\mu_n`$ (cm²/(V·s)) | $`\mu_p`$ (cm²/(V·s)) |
+| | $`\varepsilon_r`$ | $`E_g`$ (eV) | $`\chi`$ (eV) | $`N_c`$ (cm⁻³) | $`N_v`$ (cm⁻³) | $`\mu_n`$ (cm²/(V·s)) | $`\mu_p`$ (cm²/(V·s)) |
 |---|---|---|---|---|---|---|---|
 | Si | 11.9 | 1.12 | 4.05 | 2.8 × 10¹⁹ | 1.04 × 10¹⁹ | 1500 | 450 |
 | Ge | 16.0 | 0.66 | 4.0 | 1.04 × 10¹⁹ | 6.0 × 10¹⁸ | 3900 | 1900 |
@@ -70,14 +91,108 @@ doping. The data are in `SEMICONDUCTORS`, in the source's units (cm⁻³, cm²/(
 
 - Source: Sze, *Physics of Semiconductor Devices*, 2nd ed. (1981), appendix "Properties of Ge,
   Si and GaAs at 300 K". The mobilities are for lightly doped material.
-- The electron affinity $`\chi`$ is for vacuum-level estimates with `vacuumDipole` (anchor `'e-'`,
-  see the [alignment guide](alignment.md)). It isn't used otherwise, since an alignment is never
-  implied.
+- The electron affinity $`\chi`$ (an energy, in eV) is for vacuum-level estimates with
+  `vacuumDipole` (anchor `'e-'`, `offset: chi`, the same number in volts; see the
+  [alignment guide](alignment.md)). It isn't used otherwise, since an alignment is never implied.
 - **Silicon's intrinsic concentration**: these $`N_c`$, $`N_v`$ and $`E_g`$ give $`n_i`$ = 6.7 × 10⁹ cm⁻³.
   Sze quotes 1.45 × 10¹⁰ (an older measurement), and the accepted value is 9.65 × 10⁹. The
   library keeps the band data self-consistent rather than matching a quoted $`n_i`$. For Ge and
   GaAs, the data reproduce the quoted $`n_i`$ (2.4 × 10¹³ and 1.79 × 10⁶) to within 10–15%.
 
+### At other temperatures
+
+With `T`, each 300 K number moves by a standard temperature law:
+
+- **Band gap**, by Varshni's form $`E_g(T) = E_{g0} - \alpha T^2/(T + \beta)`$ (Varshni, Physica 34,
+  149, 1967), with Thurmond's parameters as tabulated by Sze (Thurmond, J. Electrochem. Soc. 122,
+  1133, 1975). Only the shift from 300 K is used, on the table's gap,
+  $`E_g(T) = E_g^{\text{table}} + [E_g^{\text{V}}(T) - E_g^{\text{V}}(300\ \mathrm{K})]`$, so that 300 K is the
+  table exactly. Varshni's own value at 300 K differs from the table by a few meV.
+- **$`N_c`$ and $`N_v`$** $`\propto T^{3/2}`$, from parabolic bands with fixed effective masses.
+- **Mobilities**, by the power laws for scattering by lattice vibrations,
+  $`\mu \propto T^{-\gamma}`$ (Sze, ch. 1). They are approximate and hold for lightly doped material.
+  Where scattering by ionized impurities matters (heavy doping, or the cold end of the range), the real
+  mobility is lower and rises less on cooling. D is then $`\mu kT/q`$ at T, so it falls more slowly
+  than μ.
+- **Electron affinity** $`\chi`$ and **$`\varepsilon_r`$** stay at their 300 K values.
+
+| | $`E_{g0}`$ (eV) | $`\alpha`$ (10⁻⁴ eV/K) | $`\beta`$ (K) | Varshni at 300 K (eV) | $`\gamma_n`$ | $`\gamma_p`$ |
+|---|---|---|---|---|---|---|
+| Si | 1.170 | 4.73 | 636 | 1.1245 | 2.42 | 2.20 |
+| Ge | 0.7437 | 4.774 | 235 | 0.6634 | 1.66 | 2.33 |
+| GaAs | 1.519 | 5.405 | 204 | 1.4225 | 1.0 | 2.1 |
+
+Outside 150–500 K the call is refused: Varshni's fits and the lattice-limited mobilities are
+not meant for the cold, where impurities and freeze-out take over. With these laws, silicon's
+$`n_i`$ grows 8.3% per kelvin near room temperature. In the tests, a silicon cell's
+open-circuit voltage falls 2.14 mV/K at 300 K. That lies within Green's
+$`\mathrm{d}V_{oc}/\mathrm{d}T = -(E_{g0}/q - V_{oc} + \gamma kT/q)/T`$ for the 1.5 ≤ γ ≤ 3 that
+its transport allows, and the γ = 1.67 it implies matches its two parts of $`J_0`$.
+
+**A diode's saturation current** follows from these laws. With $`n_i^2 \propto T^3 e^{-E_g/kT}`$
+and $`D = \mu kT/q \propto T^{1-\gamma}`$ ($`\gamma`$ of the minority carrier that dominates),
+a short base, $`J_0 \propto n_i^2 D/W`$, gives
+
+```math
+J_0 \propto T^{3 + 1 - \gamma}\, e^{-E_g(T)/kT}, \qquad E_a = -k\,\frac{\mathrm{d}\ln J_0}{\mathrm{d}(1/T)} = E_g - T\frac{\mathrm{d}E_g}{\mathrm{d}T} + (4 - \gamma)\,kT .
+```
+
+So an Arrhenius plot of $`J_0`$ doesn't read the gap. $`E_g - T\,\mathrm{d}E_g/\mathrm{d}T`$ is
+the gap extrapolated linearly to 0 K, 1.196 eV for silicon at 300 K, and the prefactor adds
+$`(4-\gamma)kT`$, 0.041 eV for its electrons, about 1.24 eV in all. A long base,
+$`J_0 \propto n_i^2\sqrt{D/\tau}`$, has $`(1-\gamma)/2`$ in place of $`1-\gamma`$, with τ as you
+give it (the library doesn't move it with T).
+
+**Hot, lightly doped junctions disappear.** $`n_i`$ grows fast: silicon's is 3 × 10¹³ cm⁻³ at
+450 K and 1.6 × 10¹⁴ at 500 K, germanium's 6 × 10¹⁵ at 450 K and 2 × 10¹⁶ at 500 K. Where $`n_i`$
+approaches the doping, both sides go intrinsic and the junction (its built-in voltage, its
+rectification) fades away. Compare $`n_i(T)`$ with the doping before reading a trend in V(T)
+across that range.
+
+### Alloys and other materials from these
+
+A material the library lacks can start from a near relative's entry, with its own numbers put
+in. For example, Al₀.₃Ga₀.₇As from GaAs: give the holes' `mu0` the alloy's gap ($`E_g F`$), and set
+whatever else differs, such as the mobilities and $`N_c`$, $`N_v`$. A field you don't set keeps
+GaAs's value, its electron mobility of 8500 cm²/(V·s) included. Then give each face between the
+two its band offset as a `step` on e⁻, $`\Delta E_c`$ right minus left (the valence-band offset
+follows from the two gaps). `semiconductor(name, { T })` moves only the named material's own data,
+by its laws: numbers you put in stay as given, so at another temperature move them yourself. The
+material still carries the `T` it was made at, for the warning.
+
+```js
+import { Device, units, GAS_CONSTANT, FARADAY } from 'driftlet';
+import { build, layer, ohmic, semiconductor } from 'driftlet/kit';
+
+// The usual estimates for x = 0.3 (E_g = 1.424 + 1.247x eV, ΔE_c ≈ 0.62 ΔE_g,
+// m_e = 0.067 + 0.083x); check them against your source.
+const T = 300, VT = (GAS_CONSTANT * T) / FARADAY, x = 0.3;
+const gap = 1.424 + 1.247 * x, dEc = 0.62 * (gap - 1.424);
+const alloy = semiconductor('GaAs', { material: 'AlGaAs', T }), m = alloy.materials.AlGaAs;
+m.species['h+'] = { ...m.species['h+'], mu0: units.eV(gap) };
+m.species['e-'] = {
+  ...m.species['e-'],
+  D: 1000e-4 * VT, // μ_n = 1000 cm²/(V·s), a rough figure
+  cRef: m.species['e-'].cRef * ((0.067 + 0.083 * x) / 0.067) ** 1.5, // N_c ∝ m_e^1.5
+};
+// A heterojunction diode, n-AlGaAs | p-GaAs, forward biased.
+const dev = new Device(build({
+  T,
+  library: [semiconductor('GaAs', { T }), alloy],
+  stack: [
+    ohmic(0), layer('AlGaAs', 1e-6, { donors: units.perCm3(1e17) }),
+    { step: { species: 'e-', value: units.eV(-dEc) } }, // GaAs's conduction band is lower
+    layer('GaAs', 1e-6, { acceptors: units.perCm3(1e17) }), ohmic(1.0),
+  ],
+  bulkReactions: [{ equation: 'e- + h+ = 0', kf: { GaAs: 1e8, AlGaAs: 1e8 } }],
+}));
+const sol = dev.solve();
+// The wider gap keeps holes out of the n side: nearly all the current is electrons injected
+// into the GaAs.
+const { 'e-': e, 'h+': h } = sol.contacts.left.flux;
+console.log(sol.warnings.length, (e / -h).toExponential(1)); // 0, 2.5e+7
+```
+
 ## Metals, 20 °C
 
 `metal(name, { material })` returns a conductor material carrying `e-`, with its conductivity

package/docs/device.md

@@ -15,7 +15,7 @@ too (`FARADAY`, `GAS_CONSTANT`, `EPS0`, …).
 
 | Key | Meaning |
 |---|---|
-| `T` | temperature, K (default 298.15) |
+| `T` | temperature, K (default 298.15, 25 °C; the library's semiconductors are for 300 K, so give them `T: 300`) |
 | `species` | list of mobile species |
 | `materials` | named materials: bulk properties |
 | `regions` | the device, left to right: each a material plus length, fixed charge, composition |
@@ -55,6 +55,11 @@ Per species present: `D` (m²/s, the coefficient in the flux $`N = -(D c/RT)\nab
 (standard chemical potential, J/mol) and `cRef` (the concentration that `mu0` refers to; falls back
 to the species' `cRef`, and must exist one way or the other). Species not listed are absent.
 
+A material may say what temperature its numbers are for, `T` (K). `semiconductor()` sets it.
+The device then warns, in its solutions' `warnings`, if that isn't its own `T` (to 0.01 K), since
+the material's gap, densities of states and D are then another temperature's. A material without
+`T` is taken as written.
+
 In a material, only *neutral combinations* of standard potentials mean anything physically.
 Shifting every `mu0` by $`z_i F s`$ just moves the material's $`\phi`$, its bookkeeping anchor. See
 [conventions](conventions.md).
@@ -418,7 +423,13 @@ those materials.
 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.
+the traps are few and fast, without them. Where their charge matters, write them out: two
+immobile species (D = 0) for the trap's charge states, filled and emptied by
+`'e- + X0 = X-'` and `'X- + h+ = X0'` (acceptor-like) at rates $`k_n = 1/(\tau_n N_t)`$ and
+$`k_p = 1/(\tau_p N_t)`$, the filled state's $`\mu^\circ`$ an electron's $`\mu`$ at $`n_1`$ above the
+empty one's. In steady state they recombine at the rate above exactly, each node keeps its
+own trap total, and the trapped charge is in Poisson's equation. The kit's
+[`trap()`](kit.md#a-device-as-a-stack) writes them from the same `{ tauN, tauP, n1 }` and a density.
 
 ```js nocheck
 bulkReactions: [{ equation: 'e- + h+ = 0', srh: { Si: { tauN: 1e-6, tauP: 1e-6 } } }]
@@ -1000,6 +1011,9 @@ const now = dev.solution();                   // snapshot of the current state
   mid-run, `set({ contacts: { right: { bath: { c } } } })`, is a step in the sample.) Either way the time stepping restarts its
   order, as after any discontinuity, but a carried state goes on at the step size an adaptive
   transient had reached, so a page may change a rate constant or a diffusivity every frame.
+  To change the temperature, give the materials for it in the same patch,
+  `dev.set({ T: 350, materials: semiconductor('Si', { T: 350 }).materials })`: a `T` alone
+  changes kT but not the materials' data (a material that carries its `T` then warns).
 
 For example, a silver nitrate cell between silver electrodes: its impedance spectrum, then the
 current transient after a voltage step.
@@ -1047,7 +1061,7 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `bulkReactions[k]` | `{ rate, forward, nu, regions, total }`: each bulk reaction's net forward rate at every node (mol/(m³·s), `NaN` where it doesn't run), its one-way forward rate (the backward is `forward − rate`), what one forward reaction makes of each species (`nu`, negative for what it consumes), and integrated over each region and the device (mol/(m²·s)), as the balances count it: a charge-balance check is J = F(generation − recombination), which the kit's `check()` does for every species |
 | `charge` | total charge in the device, C/m² (C through a cross-section) |
 | `conservation` | per species stretch: amount, reference, intake through contacts, and drift, relative: (amount − reference − intake) over the largest of them |
-| `warnings` | e.g. unresolved double layers, conventions a statistics model relies on, and for a failed solve, where the system is nearly singular |
+| `warnings` | e.g. unresolved double layers, conventions a statistics model relies on, a material's data for another temperature, and for a failed solve, why (a driven current it can't pass, where the system is nearly singular). A failed steady solve's state isn't a solution, so the warnings about a solution's accuracy (the grid, double layers, space charge reaching a contact) are left out of it |
 | `converged`, `iterations`, `steps`, `substeps`, `history`, `time`, `T` | solver bookkeeping, and the temperature |
 | `steady` | whether this is a converged steady state (from `solve()`), not a transient's: what `check()` in the kit decides its checks by |
 | `done`, `rejected`, `trace` | from `advance()`: whether `tEnd` was reached; rejected steps; `{ t, current, voltage }` per accepted step |

package/docs/kit.md

@@ -68,6 +68,15 @@ console.log(`I = ${sol.current.toFixed(1)} A/m²`);
 - **`library`** takes pieces with `species` and `materials`, merged with any given directly
   (`combine()` does the merging on its own). A species or material given twice must be given
   identically.
+- **`trap(lib, { density, tauN, tauP, n1, charge, name, material, T })`** adds a trap level that
+  holds charge to a semiconductor's library piece: its two states as immobile species
+  (`X0`/`X-` for `charge: 'acceptor'`, the default; `X+`/`X0` for `'donor'`), filled and emptied
+  by capturing electrons and holes. It returns `{ library, bulkReactions, c0 }`: the library to
+  give `build()` in place of `lib`, the two capture reactions, and the trap's total for each
+  layer that has it (`layer('Si', L, { donors, c0: t.c0 })`). In steady state it recombines at the
+  `srh` law's rate with the same `tauN`, `tauP` (s, at that density) and `n1` (mol/m³, default
+  n_i); unlike `srh`, its charge is in Poisson's equation
+  ([device](device.md#bulk-reactions)).
 - Nested lists in the stack are flattened, so a helper can return several items.
 - Reactions pass through as written (see below), and so do `T`, `grid`, `ports` and `geometry`.
 
@@ -395,7 +404,11 @@ warnings:
   `warnings` check this again against the solved concentrations);
 - an outside (a bath, a contact's levels) out of equilibrium with a bulk reaction that runs at the
   contact, which would run there for ever: H⁺ and OH⁻ in a bath a little off $`K_w`$ pass a current
-  at zero bias.
+  at zero bias;
+- the definition's own warnings, which every solution repeats: a material whose data are for
+  another temperature than the device's (`semiconductor('Si')` is 300 K's; the device's default
+  is 298.15 K), a starting profile the grid doesn't resolve, conventions a statistics model
+  relies on.
 
 They're heuristics, prompts to check, never errors.
 
@@ -424,14 +437,17 @@ page can show that its numbers hold up. Pass the solution `solve()` or `advance(
 
 - **converged**: the solve converged.
 - **warnings**: the solution's warnings (unresolved double layers, steep profiles, a weakly held
-  part) and the definition's likely unit slips. They're heuristics, so they're marked `?`, a
+  part, a material's data for another temperature) and the definition's likely unit slips. They're heuristics, so they're marked `?`, a
   prompt to look, and don't fail the check.
 - **balance**, in a steady state: each species' ledger, what comes in through each terminal and
   what each reaction (bulk, or at a face) makes or uses, in mol/(m²·s) and for a charged species
   as a current. The terms must sum to zero. A species that a face lets through only by a law (a
   membrane's permeability, a conductance) or by a reaction has a ledger on each side, with what
   crosses as a term: in a cell, Na⁺ leaks into the cytoplasm as fast as the pump puts it out. Under light it's J = F(G − R), and it says where
-  every carrier went: collected, or recombined in the bulk or at which face. A species at rest
+  every carrier went: collected, or recombined in the bulk or at which face. Each reaction is a
+  term named by its equation; two with the same equation (radiative and SRH recombination, both
+  `e- + h+ = 0`) are told apart by their place, `e- + h+ = 0 (bulkReactions[1])`, and
+  `sol.bulkReactions[k]` has each one's rates. A species at rest
   (in equilibrium, flows only of round-off against what it could carry) isn't listed.
 - **conservation**, in a transient: every closed, unreacting stretch keeps what it held plus
   what came in.

package/docs/reliability.md

@@ -58,6 +58,7 @@ recipes.
 | SRH recombination | bulk: G = R_SRH(n, p) with n = N_D + p, midgap and shallow traps, low to high injection; at a face: zero in the dark, the law between the two edge nodes, every pair collected or recombined | 1e-6; 1e-9 |
 | Perovskite J–V hysteresis, against IonMonger | an independent code (finite elements, Octave): mobile iodide vacancies, interface SRH, scans from 1 mV/s to 1 kV/s — hysteresis index, P_max, V_oc, the whole loop (as current where it's gentle, as a voltage offset near V_oc, where it falls at up to 1100 mA/cm² per volt) | 1.5e-3; 0.05 mW/cm²; 2 mV; 0.03 mA/cm² and 1 mV (0.010 and 0.31 mV found) |
 | Illuminated long pn diode | `J_sc = qG(L_n + L_p + W)` from a cold start; superposition at low injection | 5e-3; 1e-2 |
+| A silicon cell's V_oc against temperature (`semiconductor('Si', { T })`) | Green's dV_oc/dT = −(E_g0/q − V_oc + γkT/q)/T for 1.5 ≤ γ ≤ 3 (−2.12 to −2.25 mV/K); the γ it implies against its two parts of J₀, 1.66; n_i's growth, 8.3%/K, against 3/2T + E_g0/2kT² | within the band (−2.14 found); ±0.1 (1.67 found); 1e-4 |
 | Schottky barrier (metal region \| n-Si) | surface density from the alignment; depletion charge | 5e-3; 2% |
 | Surface velocity at a contact | minority electrons through a base to a contact of velocity S, n₀(e^(V/V_T) − 1)/(W/D + 1/S), S from 10 to 1e5 m/s; a Schottky diode's thermionic emission, short of A*T²e^(−φ_B/V_T)(e^(V/V_T) − 1) by its depletion region in series, the same swept as built cold | 1e-5; 3–7%; 1e-6 |
 | Charged pore or nanochannel (resolved Donnan layers at each mouth) | conductance against salt, down to its plateau, as Teorell–Meyer–Sievers in a long pore (short ones short by end layers ∝ 1/L); the zero-current voltage across a salt gradient; a symmetric pore's I–V odd, rectification with charge on one side or bipolar | 1%; 5e-3 to 1e-4; 1e-9 |

package/docs/templates.md

@@ -214,7 +214,7 @@ for (let k = 1; k <= 300; k++) {
   const sol = axon.advance(k * 1e-4); // 0.1 ms at a time
   peak = Math.max(peak, sol.interfaces[0].V); // V_m, and sol.interfaces[0].gates = { m, h, n }
 }
-console.log(`peak ${(peak * 1e3).toFixed(1)} mV`); // +12.6: GHK's Na⁺ current is limited by the 50 mM inside (linear: true gives +37.9, HH's own)
+console.log(`peak ${(peak * 1e3).toFixed(1)} mV`); // +12.6: GHK's currents rectify; matched at rest, at positive V Na⁺'s conductance is lower and K⁺'s higher (linear: true gives +37.9, HH's own)
 ```
 
 ## an action potential travelling along an axon

package/llms.txt

@@ -30,9 +30,9 @@ materials, insertion hosts), data.md and reliability.md (what's validated, and t
 From a CDN, pin the version you tested against:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -73,12 +73,16 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   are regions (give one a `name` to refer to it), and any other object between two layers is
   the face between them. `ohmic()`, `bath()` and the like write contacts; a plain object works.
 - **The library** is pieces with `species` and `materials`: `semiconductor('Si')` (Si, Ge, GaAs, at
-  300 K), `aqueous(names)` (H⁺ Li⁺ Na⁺ K⁺ Ag⁺ Cu²⁺ Zn²⁺ Fe²⁺ Fe³⁺ OH⁻ Cl⁻ NO₃⁻ SO₄²⁻ in water, at 25
+  300 K; `semiconductor('Si', { T: 350 })` moves them, 150–500 K, for a device at that `T`),
+  `aqueous(names)` (H⁺ Li⁺ Na⁺ K⁺ Ag⁺ Cu²⁺ Zn²⁺ Fe²⁺ Fe³⁺ OH⁻ Cl⁻ NO₃⁻ SO₄²⁻ in water, at 25
   °C; `{ epsr: 0 }` makes it strictly neutral, with no double layers), `metal('Ag')` (Ag Cu Au Al Zn
   Li Pt), all from `driftlet/kit`. A semiconductor's textbook numbers are in `SEMICONDUCTORS.Si`
   (`Eg` and `chi` in eV, `Nc` and `Nv` in cm⁻³, `mun` and `mup` in cm²/(V·s), `epsr`); in the
-  material, e⁻'s and h⁺'s `cRef` are N_c and N_v in mol/m³ and h⁺'s `mu0` is the gap (e⁻'s is 0),
-  so n_i = √(N_c N_v) e^(−E_g/2RT), 6.7e9 cm⁻³ for Si. A species it lacks is pushed into both lists
+  material, `materials.Si.species['e-'].cRef` and `['h+'].cRef` are N_c and N_v in mol/m³ and
+  h⁺'s `mu0` is the gap (e⁻'s is 0), so n_i = √(N_c N_v) e^(−E_g/2RT), 6.7e9 cm⁻³ for Si. The
+  material carries the T its data are for (`materials.Si.T`), and a device at another T warns
+  (its default is 298.15 K, so say `T: 300`). An alloy starts from a relative's entry with your
+  numbers put in (docs/data.md has AlGaAs from GaAs). A species it lacks is pushed into both lists
   (`z: 0` for a neutral one): `lib.species.push({ name: 'A-', z: -1, cRef: 1000 })`,
   `lib.materials.water.species['A-'] = { D, mu0 }`. Only μ° differences within a reaction matter:
   for a redox couple μ°_red − μ°_ox = −F·E° (against SHE, the library's μ°_H⁺ being 0). An
@@ -115,7 +119,11 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   bimolecular, as is the kit's `recombination()`, it shortens at high injection. SRH is `srh: { Si:
   { tauN, tauP } }` in place of `kf` (s), or at a face `{ equation: 'e-(left) + h+(right) = 0',
   srh: { vn, vp } }` (m/s); with τ_N ≪ τ_p it gives n-type silicon's holes a lifetime τ_p at any
-  injection. Light is a reaction from a reservoir (`photon = e- + h+`, uniform), or absorbed as
+  injection. `srh` carries no charge; for traps whose charge matters (dense or deep ones, trapped
+  charge bending the bands), `trap(semiconductor('Si'), { density, tauN, tauP, n1, charge:
+  'acceptor' })` writes the trap's two states as immobile species and returns `{ library,
+  bulkReactions, c0 }` (c0 into each layer that has the trap): the same rate in steady state, its
+  charge in Poisson. Light is a reaction from a reservoir (`photon = e- + h+`, uniform), or absorbed as
   it goes in, `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })`, `from` and
   `to` being x in the device (a port's window is instead m from its region's left end). To switch
   it during a run, `set()` the device's whole `bulkReactions` list, recombination included: in
@@ -168,7 +176,7 @@ import { Device, units } from 'driftlet';
 import { build, layer, ohmic, semiconductor, describe } from 'driftlet/kit';
 
 const def = build({
-  T: 300, // the library's semiconductor data are for 300 K
+  T: 300, // the library's semiconductor data are for 300 K, unless semiconductor('Si', { T })
   library: [semiconductor('Si')],
   stack: [
     ohmic(0), // e⁻ and h⁺ in equilibrium with a metal at 0 V
@@ -176,7 +184,9 @@ const def = build({
     layer('Si', units.um(1), { name: 'p', acceptors: units.perCm3(1e16) }),
     ohmic(0.5), // the p side at +0.5 V: forward bias
   ],
-  bulkReactions: [{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }], // recombination: τ = 1/(kf·N) ≈ 0.6 µs at N = 1e16 cm⁻³
+  // recombination: τ = 1/(kf·N) ≈ 0.6 µs at N = 1e16 cm⁻³, so L = √(Dτ) ≈ 50 µm ≫ 1 µm: a short
+  // diode, whose Shockley J₀ takes each side's quasi-neutral width (W − x_d) in place of L
+  bulkReactions: [{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }],
   grid: { hmin: units.nm(1), hmax: units.nm(20) },
 });
 console.log(describe(def));
@@ -209,9 +219,9 @@ a CDN needs a long virtual-time budget, 30 s.)
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -641,8 +651,13 @@ those:
 - **Unit slips.** D in cm²/s, μ° in eV, µF/cm², mS/cm², T in °C. `describe(def)` flags them.
 - **A couple's μ° with the wrong sign** solves happily at −E° for +E°: μ°_red − μ°_ox = −F·E°.
   Check the rest potential against E°, as the stirred-solution template does.
-- **The library's data are for 25 °C** (its semiconductors for 300 K: give `T: 300`). At body
-  temperature the same μ° and D are a fair start; D rises about 2% per kelvin in water.
+- **The library's data are for 25 °C** (its semiconductors for 300 K: give `T: 300`, or the
+  same `T` to `semiconductor(name, { T })`, which moves the gap, N_c, N_v and the mobilities; a
+  mismatch warns). On a live device change both at once, `dev.set({ T, materials:
+  semiconductor('Si', { T }).materials })`. A diode's J₀ ∝ T^(4−γ) e^(−E_g/kT), so its Arrhenius
+  slope is E_g − T dE_g/dT + (4−γ)kT (≈ 1.24 eV for Si), not E_g. Hot and lightly doped, n_i
+  passes the doping (Ge 6e15 cm⁻³ at 450 K) and the junction fades: compare before fitting V(T).
+  At body temperature the same μ° and D are a fair start; D rises about 2% per kelvin in water.
 - **A steady solve of a closed cell where every ion can cross**: its steady state is complete
   mixing. To watch a junction or a salt bridge, `advance()` from the unmixed `c0`.
 - **A sharp junction between very different solutions** (3 M KCl against 1 µM) can't start:
@@ -663,7 +678,7 @@ those:
 - `driftlet/kit`:
   - building: `build`, `combine`, `layer`, `ohmic`, `bath`, `half`, `level`, `SHE`,
     `vacuumLevel`, `vacuumDipole`, `vacuumZeroCharge`, and the data library (`aqueous`,
-    `semiconductor`, `metal`, `IONS`, `SEMICONDUCTORS`, `METALS`, `H2O`, `WATER_EPSR`);
+    `semiconductor`, `metal`, `trap`, `IONS`, `SEMICONDUCTORS`, `METALS`, `H2O`, `WATER_EPSR`);
   - sources: `pulse`, `square`, `triangle`, `ramp`, `injector`, `recombination`,
     `photogeneration`;
   - channels: `hodgkinHuxley`, `ghkCurrent`;
@@ -674,4 +689,4 @@ those:
     `particles`;
   - curated devices: `perovskiteCell`, `PEROVSKITE_SCANS`, `hysteresis`.
 - `driftlet/plot` (a quick look): `bandDiagram`, `levelChart`, `labelParts`, `themeColor`,
-  `THEME`.
+  `THEME`. These draw profiles in x; an I–V curve or a transient you draw yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for semiconductors, electrochemistry and nerves, fast enough for live web demos",
   "type": "module",
   "exports": {

package/src/checks.js

@@ -134,8 +134,12 @@ function balance(device, sol) {
     if (through('right', i)) add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
     model.ports.forEach((port, k) => add(i, port.region, `port ${sol.ports[k].name}`, sol.ports[k].flux[sp.name]));
   });
+  // (two reactions with one equation, radiative and SRH recombination say, keep a line each,
+  // named by their place in the list)
+  const unique = (labels, where) => labels.map((w, k) => (labels.indexOf(w) === labels.lastIndexOf(w) ? w : `${w} (${where}[${k}])`));
+  const bulkWhat = unique(model.reactions.map((_, k) => label(def.bulkReactions?.[k])), 'bulkReactions');
   model.reactions.forEach((rx, k) => {
-    const what = label(def.bulkReactions?.[k]);
+    const what = bulkWhat[k];
     sol.bulkReactions[k].regions.forEach((total, r) => {
       const all = [...rx.reactants, ...rx.products].map((p) => p.i);
       for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total, all);
@@ -153,8 +157,9 @@ function balance(device, sol) {
       add(i, f, `across face ${f} (${type})`, -N);
       add(i, f + 1, `across face ${f} (${type})`, N);
     });
+    const faceWhat = unique(itf.reactions.map((_, k) => label(def.interfaces?.[f]?.reactions?.[k])), 'reactions');
     itf.reactions.forEach((rx, k) => {
-      const rate = Af * sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
+      const rate = Af * sol.interfaces[f].rates[k], what = `${faceWhat[k]} at face ${f}`;
       const all = rx.part.map((p) => p.i);
       for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate, all);
     });

package/src/data.js

@@ -3,8 +3,9 @@
 // only. How levels line up at an interface, and a surface's work function, belong to that
 // interface or surface and are never in here.
 
-import { DeviceError, checkOptions } from './errors.js';
+import { DeviceError, checkOptions, shown } from './errors.js';
 import { FARADAY, GAS_CONSTANT, AVOGADRO } from './constants.js';
+import { powr } from './pow.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -43,7 +44,7 @@ export const WATER_EPSR = 78.3;
 
 /**
  * Semiconductors at 300 K (Sze, Physics of Semiconductor Devices, 2nd ed., 1981, appendix):
- * relative permittivity, band gap Eg (eV), electron affinity chi (V), effective densities of
+ * relative permittivity, band gap Eg (eV), electron affinity chi (eV), effective densities of
  * states Nc and Nv (cm⁻³), and drift mobilities of lightly doped material mun and mup
  * (cm²/(V·s)).
  */
@@ -84,21 +85,49 @@ export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
   return { species, materials: { [material]: { epsr, species: entries } } };
 }
 
+// How the semiconductors' data move with temperature, for semiconductor(name, { T }):
+// - the gap by Varshni's form, Eg(T) = Eg0 − αT²/(T + β) (Y. P. Varshni, Physica 34, 149, 1967),
+//   with Thurmond's parameters (C. D. Thurmond, J. Electrochem. Soc. 122, 1133, 1975, as
+//   tabulated in Sze, 2nd ed.): Eg0 (eV), alpha (eV/K), beta (K). Only the shift from 300 K is
+//   used, on the table's Eg, so T = 300 K is the table: Varshni's own Eg(300) differs from it by
+//   4.5 meV (Si, 1.1245), 3.4 meV (Ge, 0.6634) and 1.5 meV (GaAs, 1.4225).
+// - Nc and Nv ∝ T^1.5 (parabolic bands, effective masses held fixed).
+// - mobilities ∝ T^−gn and T^−gp, the lattice-limited power laws for lightly doped material
+//   (Sze, 2nd ed., ch. 1): approximate, and wrong where impurity scattering matters (heavy
+//   doping, or cold). D follows from μ and T by Einstein's relation, D = μkT/q.
+// - the electron affinity chi isn't moved.
+const WITH_T = {
+  Si: { Eg0: 1.17, alpha: 4.73e-4, beta: 636, gn: 2.42, gp: 2.2 },
+  Ge: { Eg0: 0.7437, alpha: 4.774e-4, beta: 235, gn: 1.66, gp: 2.33 },
+  GaAs: { Eg0: 1.519, alpha: 5.405e-4, beta: 204, gn: 1.0, gp: 2.1 },
+};
+const T_RANGE = [150, 500];
+
 /**
  * A semiconductor from `SEMICONDUCTORS`, as a library piece: electrons `e-` and holes `h+`, with
- * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at 300 K, and μ°_e⁻ = 0 (φ
- * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K, so use `T: 300`.
+ * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at T, and μ°_e⁻ = 0 (φ
+ * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K; another T (150 to
+ * 500 K) moves them: the gap by Varshni's shift from 300 K, Nc and Nv as T^1.5, the mobilities by
+ * lattice-limited power laws (light doping). The material carries its `T`, and a device at
+ * another temperature warns: give the device the same T.
  * Statistics are ideal (Boltzmann); add Fermi–Dirac to the material for degenerate doping.
  * @param {string} name 'Si', 'Ge' or 'GaAs'
- * @param {{ material?: string }} [opts]
+ * @param {{ material?: string, T?: number }} [opts] the material's name, and the temperature
+ *   (K, default 300, the table's)
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
-export function semiconductor(name, { material = name } = {}) {
-  if (arguments[1]?.T !== undefined) fail('semiconductor: the data are for 300 K and take no T: give the device T: 300, or write your own material for another temperature (SEMICONDUCTORS has the numbers)');
-  checkOptions('semiconductor', arguments[1], ['material']);
+export function semiconductor(name, { material = name, T = 300 } = {}) {
+  checkOptions('semiconductor', arguments[1], ['material', 'T']);
   const sc = SEMICONDUCTORS[name];
   if (!sc) fail(`semiconductor: no data for '${name}' (the library has ${Object.keys(SEMICONDUCTORS).join(', ')})`);
-  const VT = (GAS_CONSTANT * 300) / FARADAY;
+  if (typeof T !== 'number') fail(`semiconductor: T must be a number, the temperature in K, got ${shown(T)}`);
+  if (!(Number.isFinite(T) && T >= T_RANGE[0] && T <= T_RANGE[1])) {
+    fail(`semiconductor: T must be the temperature in K, from ${T_RANGE[0]} to ${T_RANGE[1]} (the range its temperature laws are good for), got ${T}`);
+  }
+  const { alpha, beta, gn, gp } = WITH_T[name];
+  const t = T / 300, varshni = (T) => (alpha * T * T) / (T + beta);
+  const Eg = sc.Eg - (varshni(T) - varshni(300));
+  const VT = (GAS_CONSTANT * T) / FARADAY;
   const perCm3 = (n) => (n * 1e6) / AVOGADRO;
   return {
     species: [
@@ -107,16 +136,76 @@ export function semiconductor(name, { material = name } = {}) {
     ],
     materials: {
       [material]: {
+        T, // the temperature the data are for: a device at another warns
         epsr: sc.epsr,
         species: {
-          'e-': { D: sc.mun * 1e-4 * VT, mu0: 0, cRef: perCm3(sc.Nc) },
-          'h+': { D: sc.mup * 1e-4 * VT, mu0: sc.Eg * FARADAY, cRef: perCm3(sc.Nv) },
+          'e-': { D: sc.mun * powr(t, -gn) * 1e-4 * VT, mu0: 0, cRef: perCm3(sc.Nc * powr(t, 1.5)) },
+          'h+': { D: sc.mup * powr(t, -gp) * 1e-4 * VT, mu0: Eg * FARADAY, cRef: perCm3(sc.Nv * powr(t, 1.5)) },
         },
       },
     },
   };
 }
 
+/**
+ * A trap level in a semiconductor that holds charge: its two charge states as immobile species
+ * (D = 0), filled and emptied by capturing carriers, e⁻ + X⁰ = X⁻ and X⁻ + h⁺ = X⁰ (acceptor-like)
+ * or X⁺ + e⁻ = X⁰ and X⁰ + h⁺ = X⁺ (donor-like). In steady state it recombines at exactly the
+ * `srh` law's rate with the same τ_n, τ_p and n₁, and its charge is in Poisson's equation, which
+ * the `srh` law (the trap's occupancy eliminated) leaves out. Each node keeps its own total.
+ * @param {{ species: object[], materials: Record<string, object> }} lib a library entry with e⁻
+ *   and h⁺ (semiconductor()), returned with the trap's states added
+ * @param {{ density: number, tauN: number, tauP: number, n1?: number, charge?: 'acceptor' | 'donor',
+ *   name?: string, material?: string, T?: number }} opts density N_t (mol/m³); τ_n = 1/(c_n N_t)
+ *   and τ_p = 1/(c_p N_t) (s) at that density; n₁, the electron density that half-fills it
+ *   (mol/m³; default n_i, midgap); T (K, default the material's T, else 300)
+ * @returns {{ library: object, bulkReactions: object[], c0: Record<string, number> }} the library
+ *   for build(), the capture reactions, and c0 for each layer holding the trap (its total N_t)
+ */
+export function trap(lib, { density, tauN, tauP, n1, charge = 'acceptor', name = 'X', material, T } = {}) {
+  checkOptions('trap', arguments[1], ['density', 'tauN', 'tauP', 'n1', 'charge', 'name', 'material', 'T']);
+  if (!lib || typeof lib !== 'object' || typeof lib.materials !== 'object') fail('trap: give the library entry first, semiconductor(\'Si\') say, then { density, tauN, tauP }');
+  const names = Object.keys(lib.materials);
+  const m = material ?? (names.length === 1 ? names[0] : fail(`trap: the library has materials ${names.join(', ')}: say which, with material`));
+  const mat = lib.materials[m];
+  if (!mat) fail(`trap: no material '${m}' in the library (it has ${names.join(', ')})`);
+  const el = mat.species?.['e-'], ho = mat.species?.['h+'];
+  if (!el || !ho) fail(`trap: material '${m}' needs e- and h+ (a semiconductor)`);
+  const pos = (v, what) => (Number.isFinite(v) && v > 0 ? v : fail(`trap: ${what}, got ${shown(v)}`));
+  pos(density, 'density must be the trap density N_t > 0 (mol/m³; units.perCm3(1e15), say)');
+  pos(tauN, 'tauN must be the electron lifetime τ_n = 1/(c_n N_t) > 0 (s)');
+  pos(tauP, 'tauP must be the hole lifetime τ_p = 1/(c_p N_t) > 0 (s)');
+  // (the material's own temperature, where it gives one: semiconductor()'s does)
+  if (T === undefined) T = mat.T ?? 300;
+  pos(T, 'T must be the temperature in K');
+  if (mat.T !== undefined && Math.abs(T - mat.T) > 0.01) fail(`trap: T is ${T} K, but material '${m}' is for ${mat.T} K; leave T out (the trap takes the material's), or remake the material for ${T} K`);
+  if (charge !== 'acceptor' && charge !== 'donor') fail(`trap: charge must be 'acceptor' (0/−) or 'donor' (+/0), got ${JSON.stringify(charge)}`);
+  if (typeof name !== 'string' || !/^[A-Za-z][\w()]*$/.test(name)) fail(`trap: name must be a plain name for the trap (its states are name0 and name- or name+), got ${JSON.stringify(name)}`);
+  const RT = GAS_CONSTANT * T, cRefE = el.cRef ?? lib.species.find((sp) => sp.name === 'e-')?.cRef;
+  const cRefH = ho.cRef ?? lib.species.find((sp) => sp.name === 'h+')?.cRef;
+  const ni = Math.sqrt(cRefE * cRefH * Math.exp(-(ho.mu0 - el.mu0) / RT));
+  const half = n1 === undefined ? ni : pos(n1, 'n1 must be the electron density that half-fills the trap > 0 (mol/m³)');
+  // The filled state's μ° sits an electron's μ at n₁ above the empty one's: half full at n = n₁.
+  const [empty, full] = charge === 'acceptor' ? [`${name}0`, `${name}-`] : [`${name}+`, `${name}0`];
+  const zEmpty = charge === 'acceptor' ? 0 : 1;
+  const states = {
+    [empty]: { D: 0, mu0: 0, cRef: density },
+    [full]: { D: 0, mu0: el.mu0 + RT * Math.log(half / cRefE), cRef: density },
+  };
+  return {
+    library: {
+      species: [...lib.species, { name: empty, z: zEmpty }, { name: full, z: zEmpty - 1 }],
+      materials: { ...lib.materials, [m]: { ...mat, species: { ...mat.species, ...states } } },
+    },
+    bulkReactions: [
+      { equation: `e- + ${empty} = ${full}`, kf: { [m]: 1 / (tauN * density) } },
+      { equation: `${full} + h+ = ${empty}`, kf: { [m]: 1 / (tauP * density) } },
+    ],
+    // (each node keeps the total, X⁰ + X⁻ say; the split is the solve's to find)
+    c0: { [empty]: density / 2, [full]: density / 2 },
+  };
+}
+
 /**
  * A metal from `METALS` as a conductor material, its carrier `e-`.
  * @param {string} name

package/src/describe.js

@@ -138,7 +138,7 @@ export function describe(def) {
   const { species, materials, regions, grid } = model;
   const RT = GAS_CONSTANT * model.T;
   const lines = [];
-  const warnings = unitWarnings(def);
+  const warnings = [...model.warnings, ...unitWarnings(def)]; // (the definition's own: a material's data at another T, …)
   const total = grid.x[grid.x.length - 1] - grid.x[0];
   lines.push(`${regions.length} region${regions.length > 1 ? 's' : ''}, ${si(total, 'm')}, ${grid.x.length} nodes, T = ${model.T} K`);
   const geo = model.geometry;

package/src/device.js

@@ -9,7 +9,7 @@
 import { buildGrid, applyGeometry } from './grid.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 import { normalizeStatistics } from './statistics.js';
-import { DeviceError } from './errors.js';
+import { DeviceError, shown } from './errors.js';
 import { stoichiometry as equationStoichiometry, faceSides, parseEquation } from './equation.js';
 
 export { DeviceError };
@@ -47,12 +47,12 @@ function fields(obj, path, allowed) {
 }
 
 function finite(v, path) {
-  need(isFiniteNumber(v), `${path} must be a finite number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v), `${path} must be a finite number, got ${shown(v)}`);
   return v;
 }
 
 function positive(v, path) {
-  need(isFiniteNumber(v) && v > 0, `${path} must be a positive number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v > 0, `${path} must be a positive number, got ${shown(v)}`);
   return v;
 }
 
@@ -108,9 +108,9 @@ function profile(v, path, what, ok, okText) {
     `${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)}`);
+    need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${path}.x must be finite and strictly increasing, but x[${k}] is ${shown(xk)}`);
   });
-  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${JSON.stringify(y)}`));
+  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${shown(y)}`));
   return { x: Float64Array.from(v.x), values: Float64Array.from(v.values) };
 }
 
@@ -138,7 +138,7 @@ function srhLaw(sdef, path, list, species, timeKeys) {
 }
 
 function nonNegative(v, path) {
-  need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${shown(v)}`);
   return v;
 }
 
@@ -151,7 +151,7 @@ export function normalizeDevice(def) {
   need(isObject(def), 'device definition must be an object');
   fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid', 'geometry']);
 
-  const T = def.T === undefined ? 298.15 : positive(def.T, 'T');
+  const T = def.T === undefined ? 298.15 : positive(def.T, 'T (the temperature, K)');
   const RT = GAS_CONSTANT * T;
 
   // --- species
@@ -164,7 +164,7 @@ export function normalizeDevice(def) {
     fields(sp, path, ['name', 'z', 'cRef']);
     need(typeof sp.name === 'string' && sp.name.length > 0, `${path}.name must be a non-empty string`);
     need(!speciesIndex.has(sp.name), `${path}.name: duplicate species '${sp.name}'`);
-    need(Number.isInteger(sp.z), `${path}.z (charge number) must be an integer, got ${JSON.stringify(sp.z)}`);
+    need(Number.isInteger(sp.z), `${path}.z (charge number) must be an integer, got ${shown(sp.z)}`);
     const cRef = sp.cRef === undefined ? undefined : positive(sp.cRef, `${path}.cRef`);
     speciesIndex.set(sp.name, i);
     species.push({ name: sp.name, z: sp.z, cRef });
@@ -179,13 +179,15 @@ export function normalizeDevice(def) {
   for (const [mname, mat] of Object.entries(def.materials)) {
     const path = `materials.${mname}`;
     need(isObject(mat), `${path} must be an object`);
+    // The temperature a material's data are for, where it says (semiconductor()'s do).
+    const dataT = mat.T === undefined ? undefined : positive(mat.T, `${path}.T (the temperature its data are for, K)`);
     if (mat.conductor !== undefined) {
       materialIndex.set(mname, materials.length);
-      materials.push(normalizeConductor(mat, mname, path, species, speciesIndex));
+      materials.push({ ...normalizeConductor(mat, mname, path, species, speciesIndex), dataT });
       continue;
     }
     // ε = 0 makes the material strictly neutral: Poisson becomes local neutrality there.
-    fields(mat, path, ['epsr', 'species', 'statistics']);
+    fields(mat, path, ['epsr', 'species', 'statistics', 'T']);
     const epsr = nonNegative(mat.epsr, `${path}.epsr`);
     need(isObject(mat.species), `${path}.species must be an object mapping species names to parameters`);
     const present = new Uint8Array(nSpecies);
@@ -205,7 +207,7 @@ export function normalizeDevice(def) {
       need(c !== undefined, `${spath}.cRef: no reference concentration (give it here or on the species)`);
       cRef[i] = positive(c, `${spath}.cRef`);
     }
-    const m = { name: mname, epsr, present, D, mu0, cRef };
+    const m = { name: mname, epsr, present, D, mu0, cRef, dataT };
     const st = normalizeStatistics({ ...m, statistics: mat.statistics }, path, species, speciesIndex, RT, { need, finite, positive });
     m.models = st.models;
     m.modelOf = st.modelOf;
@@ -285,7 +287,7 @@ export function normalizeDevice(def) {
           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, values }, got ${JSON.stringify(v)}${none}`);
+        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, values }, got ${shown(v)}${none}`);
         c0[i] = v;
       }
     }
@@ -306,6 +308,17 @@ export function normalizeDevice(def) {
     };
   });
 
+  // A material whose data are for another temperature than the device's gives the wrong n_i, gap
+  // and mobilities, silently: say so (for each material a region uses).
+  materials.forEach((m, k) => {
+    if (m.dataT === undefined || Math.abs(m.dataT - T) <= 0.01 || !regions.some((reg) => reg.material === k)) return;
+    warnings.push(
+      `materials.${m.name}: its data are for ${m.dataT} K, but the device is at ${T} K${def.T === undefined ? ' (the default, as it gives no T)' : ''}, ` +
+        `so they don't hold there (a semiconductor's n_i, gap and mobilities are ${m.dataT} K's): give the device T: ${m.dataT}, ` +
+        `or remake the material for ${T} K (semiconductor(name, { T: ${T} }))`,
+    );
+  });
+
   // --- interfaces (one per face between consecutive regions)
   const nFaces = regions.length - 1;
   const idefs = def.interfaces ?? [];
@@ -490,7 +503,7 @@ function stoichiometry(map, path, fixed, fixedPath, species, speciesIndex, RT) {
   const list = [];
   let fixedA = 0, charge = 0, nFixed = 0;
   for (const [name, nu] of Object.entries(map)) {
-    need(Number.isInteger(nu) && nu !== 0, `${path}.${name} must be a non-zero integer, got ${JSON.stringify(nu)}`);
+    need(Number.isInteger(nu) && nu !== 0, `${path}.${name} must be a non-zero integer, got ${shown(nu)}`);
     if (speciesIndex.has(name)) {
       const i = speciesIndex.get(name);
       list.push({ i, nu });
@@ -1048,7 +1061,7 @@ function gatedBy(raw, gates, lpath, where) {
   return Object.entries(raw).map(([gname, p]) => {
     const q = gates.findIndex((gt) => gt.name === gname);
     need(q >= 0, `${lpath}.gates.${gname}: no such gate${gates.length ? ` (there are ${gates.map((gt) => gt.name).join(', ')})` : ` (define it in ${where}.gates)`}`);
-    need(Number.isInteger(p) && p >= 1 && p <= 8, `${lpath}.gates.${gname}: the exponent must be a whole number from 1 to 8, got ${JSON.stringify(p)}`);
+    need(Number.isInteger(p) && p >= 1 && p <= 8, `${lpath}.gates.${gname}: the exponent must be a whole number from 1 to 8, got ${shown(p)}`);
     return [q, p];
   });
 }
@@ -1081,6 +1094,8 @@ function normalizeConductor(mat, mname, path, species, speciesIndex) {
   for (const k of ['epsr', 'species', 'statistics']) {
     need(mat[k] === undefined, `${path}.${k}: a conductor takes only { conductor: { species, conductivity } }`);
   }
+  fields(mat, path, ['conductor', 'T']);
+  fields(mdef, `${path}.conductor`, ['species', 'conductivity']);
   need(speciesIndex.has(mdef.species), `${path}.conductor.species: unknown species ${JSON.stringify(mdef.species)}${known(speciesIndex)}`);
   const i = speciesIndex.get(mdef.species);
   need(species[i].z !== 0, `${path}.conductor.species: the conductor's carrier must be charged`);
@@ -1175,7 +1190,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 ${shown(v)}`);
   return v;
 }
 

package/src/errors.js

@@ -39,3 +39,21 @@ export function checkOptions(where, opts, allowed, Kind = DeviceError) {
     throw new Kind(`${where}: no option '${k}'${near ? ` (did you mean '${near}'?)` : ''}; the options are ${allowed.join(', ')}`);
   }
 }
+
+/**
+ * A value as an error message shows it: a number as itself (NaN and Infinity too, which JSON
+ * would print as null), a string quoted and called one ("350", a string, where a number was
+ * wanted).
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function shown(v) {
+  if (typeof v === 'number' || typeof v === 'bigint' || v === undefined) return String(v);
+  if (typeof v === 'string') return `${JSON.stringify(v)} (a string)`;
+  if (typeof v === 'function') return 'a function';
+  try {
+    return JSON.stringify(v, (k, x) => (typeof x === 'number' && !Number.isFinite(x) ? String(x) : x)) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/index.js

@@ -187,7 +187,9 @@ export class Device {
     // A solve that fails reports the state it failed in, and leaves the device as it was: a
     // device with no steady state (a host filling at a current) can still advance() from there.
     const snap = this.solver._snapshot();
-    const sol = makeSolution(this.solver, this.solver.solveSteady(opts));
+    const result = this.solver.solveSteady(opts);
+    // (a failed solve's state isn't a solution: its accuracy warnings are left out)
+    const sol = makeSolution(this.solver, result.converged ? result : { ...result, unsolved: true });
     if (!sol.converged) this.solver._restore(snap);
     return sol;
   }

package/src/kit.js

@@ -18,7 +18,7 @@ export { check } from './checks.js';
 export { particles } from './particles.js';
 export { polarization } from './polarization.js';
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from './devices.js';
-export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
+export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal, trap } from './data.js';
 
 const fail = (message) => {
   throw new DeviceError(message);

package/src/solution.js

@@ -292,6 +292,13 @@ export function makeSolution(solver, result = {}) {
         'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
     );
   }
+  // The warnings below judge a solution's accuracy (its grid, its double layers). Of the state a
+  // steady solve gave up in, which isn't a solution, they say nothing useful (a driven current
+  // it couldn't pass leaves the device at ±26 V, where depletion reaches the contacts), so they're
+  // left out there; the two about the state itself (degenerate carriers, a species denser than
+  // any material) stay, as possible causes, and say they're of that state. (A failed time step
+  // restores the last good state, which is a solution: its warnings all stand.)
+  const solved = !result.unsolved, stopped = solved ? '' : ' (in the state the unconverged solve stopped in)';
   const debye = (g) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     const s2 = solver.screening(g); // zᵀKz: Σ z² c for ideal statistics
@@ -347,7 +354,7 @@ export function makeSolution(solver, result = {}) {
     );
   };
   interfaces.forEach((itf, f) => {
-    if (itf.phi.type === 'neutral') return;
+    if (itf.phi.type === 'neutral' || !solved) return;
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
@@ -357,11 +364,11 @@ export function makeSolution(solver, result = {}) {
     boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-  if (resolves(contacts.left)) {
+  if (solved && resolves(contacts.left)) {
     check(0, grid.segLength[0], 'contacts.left');
     boxed(0, grid.segLength[0], contacts.left.phi, -1, 'contacts.left');
   }
-  if (resolves(contacts.right)) {
+  if (solved && resolves(contacts.right)) {
     check(nNodes - 1, grid.segLength[nNodes - 2], 'contacts.right');
     boxed(nNodes - 1, grid.segLength[nNodes - 2], contacts.right.phi, -1, 'contacts.right');
   }
@@ -380,7 +387,7 @@ export function makeSolution(solver, result = {}) {
       }
       if (top > mat.cRef[i]) {
         sol.warnings.push(
-          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, above its cRef (${mat.cRef[i].toExponential(2)}, the band's effective density of states), where Boltzmann statistics no longer hold: ` +
+          `${reg.name}${stopped}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, above its cRef (${mat.cRef[i].toExponential(2)}, the band's effective density of states), where Boltzmann statistics no longer hold: ` +
             'give the material Fermi–Dirac statistics (docs/statistics.md), or ask whether this state is physical (a surface driven past what can carry its carriers away).',
         );
       }
@@ -410,7 +417,7 @@ export function makeSolution(solver, result = {}) {
       }
       if (top > 1e6) {
         sol.warnings.push(
-          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, denser than any material: ` +
+          `${reg.name}${stopped}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, denser than any material: ` +
             'a level set where the device cannot follow it. Check what holds it there (the V or bath of a contact, its mu0 and cRef) with describe() from driftlet/kit.',
         );
       }
@@ -421,7 +428,7 @@ export function makeSolution(solver, result = {}) {
   // ρ λ_D at the node beside it; against the region's own space charge (half Σ|ρ| over it, the
   // two signs of a double layer), warn past 1e-3.
   for (const side of ['left', 'right']) {
-    if (contacts[side].phi.type !== 'bulk') continue;
+    if (contacts[side].phi.type !== 'bulk' || !solved) continue;
     const r = side === 'left' ? 0 : model.regions.length - 1, a = grid.regionStart[r], b = grid.regionEnd[r];
     const mat = model.materials[model.regions[r].material];
     if (!(mat.epsr > 0) || mat.conductor || b - a < 3) continue;
@@ -458,7 +465,7 @@ export function makeSolution(solver, result = {}) {
   // a concentration ratio r across it). Flag a region's end cell whose field is well above its
   // neighbour's while its concentration changes steeply, for species carrying the current. (A
   // pn depletion region's field changes smoothly from cell to cell, which SG handles.)
-  if (Number.isFinite(sol.current)) {
+  if (solved && Number.isFinite(sol.current)) {
     const share = species.map((sp, i) =>
       Math.max(Math.abs(sp.z * (sol.contacts.left.flux[sp.name] ?? 0)), Math.abs(sp.z * (sol.contacts.right.flux[sp.name] ?? 0))),
     );

package/src/stack.js

@@ -4,7 +4,7 @@
 // that you didn't write: it only moves things to where the definition keeps them, and converts
 // the kit's doping shorthand (donors and acceptors).
 
-import { DeviceError, checkOptions } from './errors.js';
+import { DeviceError, checkOptions, shown } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -131,6 +131,7 @@ const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReac
 export function build(def) {
   if (!isObject(def)) fail('build: give { library, stack, … }');
   fields(def, 'build', STACK_FIELDS);
+  if (def.T !== undefined && !(typeof def.T === 'number' && Number.isFinite(def.T) && def.T > 0)) fail(`build.T must be the temperature in K, a positive number, got ${shown(def.T)}`);
   if (def.library !== undefined && !Array.isArray(def.library)) fail('build.library must be a list of { species, materials }');
   const { species, materials } = combine(...(def.library ?? []), { species: def.species ?? [], materials: def.materials ?? {} });
 

package/src/types.js

@@ -39,6 +39,8 @@
  * @property {{ species: string, conductivity: number }} [conductor] a metal or fast ion
  *   conductor: its one carrier and conductivity (S/m); its only level is the carrier's (a metal's
  *   Fermi level), and φ is undefined inside
+ * @property {number} [T] the temperature its data are for (K): a device at another temperature
+ *   warns (semiconductor() sets it)
  */
 
 /**

package/types/data.d.ts

@@ -15,19 +15,56 @@ export function aqueous(names: string[], { epsr, material }?: {
 };
 /**
  * A semiconductor from `SEMICONDUCTORS`, as a library piece: electrons `e-` and holes `h+`, with
- * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at 300 K, and μ°_e⁻ = 0 (φ
- * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K, so use `T: 300`.
+ * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at T, and μ°_e⁻ = 0 (φ
+ * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K; another T (150 to
+ * 500 K) moves them: the gap by Varshni's shift from 300 K, Nc and Nv as T^1.5, the mobilities by
+ * lattice-limited power laws (light doping). The material carries its `T`, and a device at
+ * another temperature warns: give the device the same T.
  * Statistics are ideal (Boltzmann); add Fermi–Dirac to the material for degenerate doping.
  * @param {string} name 'Si', 'Ge' or 'GaAs'
- * @param {{ material?: string }} [opts]
+ * @param {{ material?: string, T?: number }} [opts] the material's name, and the temperature
+ *   (K, default 300, the table's)
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
-export function semiconductor(name: string, { material }?: {
+export function semiconductor(name: string, { material, T }?: {
     material?: string;
+    T?: number;
 }, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };
+/**
+ * A trap level in a semiconductor that holds charge: its two charge states as immobile species
+ * (D = 0), filled and emptied by capturing carriers, e⁻ + X⁰ = X⁻ and X⁻ + h⁺ = X⁰ (acceptor-like)
+ * or X⁺ + e⁻ = X⁰ and X⁰ + h⁺ = X⁺ (donor-like). In steady state it recombines at exactly the
+ * `srh` law's rate with the same τ_n, τ_p and n₁, and its charge is in Poisson's equation, which
+ * the `srh` law (the trap's occupancy eliminated) leaves out. Each node keeps its own total.
+ * @param {{ species: object[], materials: Record<string, object> }} lib a library entry with e⁻
+ *   and h⁺ (semiconductor()), returned with the trap's states added
+ * @param {{ density: number, tauN: number, tauP: number, n1?: number, charge?: 'acceptor' | 'donor',
+ *   name?: string, material?: string, T?: number }} opts density N_t (mol/m³); τ_n = 1/(c_n N_t)
+ *   and τ_p = 1/(c_p N_t) (s) at that density; n₁, the electron density that half-fills it
+ *   (mol/m³; default n_i, midgap); T (K, default the material's T, else 300)
+ * @returns {{ library: object, bulkReactions: object[], c0: Record<string, number> }} the library
+ *   for build(), the capture reactions, and c0 for each layer holding the trap (its total N_t)
+ */
+export function trap(lib: {
+    species: object[];
+    materials: Record<string, object>;
+}, { density, tauN, tauP, n1, charge, name, material, T }?: {
+    density: number;
+    tauN: number;
+    tauP: number;
+    n1?: number;
+    charge?: "acceptor" | "donor";
+    name?: string;
+    material?: string;
+    T?: number;
+}, ...args: any[]): {
+    library: object;
+    bulkReactions: object[];
+    c0: Record<string, number>;
+};
 /**
  * A metal from `METALS` as a conductor material, its carrier `e-`.
  * @param {string} name
@@ -57,7 +94,7 @@ export const H2O: -237.129e3;
 export const WATER_EPSR: 78.3;
 /**
  * Semiconductors at 300 K (Sze, Physics of Semiconductor Devices, 2nd ed., 1981, appendix):
- * relative permittivity, band gap Eg (eV), electron affinity chi (V), effective densities of
+ * relative permittivity, band gap Eg (eV), electron affinity chi (eV), effective densities of
  * states Nc and Nv (cm⁻³), and drift mobilities of lightly doped material mun and mup
  * (cm²/(V·s)).
  */

package/types/errors.d.ts

@@ -6,6 +6,14 @@
  * @param {new (message: string) => Error} [Kind]
  */
 export function checkOptions(where: string, opts: unknown, allowed: string[], Kind?: new (message: string) => Error): void;
+/**
+ * A value as an error message shows it: a number as itself (NaN and Infinity too, which JSON
+ * would print as null), a string quoted and called one ("350", a string, where a number was
+ * wanted).
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function shown(v: unknown): string;
 export class DeviceError extends Error {
     constructor(message: any);
 }

package/types/kit.d.ts

@@ -66,4 +66,4 @@ export { hodgkinHuxley, ghkCurrent } from "./channels.js";
 export { describe, unitWarnings } from "./describe.js";
 export { henderson, planck } from "./junction.js";
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from "./devices.js";
-export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";
+export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal, trap } from "./data.js";

package/types/types.d.ts

@@ -88,6 +88,11 @@ export type MaterialDef = {
         species: string;
         conductivity: number;
     };
+    /**
+     * the temperature its data are for (K): a device at another temperature
+     * warns (semiconductor() sets it)
+     */
+    T?: number;
 };
 export type GridOptions = {
     /**