driftlet 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,27 @@
-# driftlet
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://markblundeberg.github.io/driftlet/docs/logo-dark.svg">
+    <img alt="driftlet" src="https://markblundeberg.github.io/driftlet/docs/logo.svg" width="300">
+  </picture>
+</h1>
 
 [![test](https://github.com/markblundeberg/driftlet/actions/workflows/test.yml/badge.svg)](https://github.com/markblundeberg/driftlet/actions/workflows/test.yml)
+[![npm](https://img.shields.io/npm/v/driftlet)](https://www.npmjs.com/package/driftlet)
 
-**driftlet solves 1D drift–diffusion–reaction problems properly**: any mix of charged and
-neutral species, Poisson electrostatics (or strict neutrality), bulk and interfacial reactions,
-heterointerfaces, metals, and external circuits, in steady state, in time, and as small-signal
-impedance. It's validated against analytic results, and small enough to run live in a web page:
-pure JavaScript, no dependencies, millisecond solves.
+**driftlet is a fast, pure-JavaScript solver for 1D drift–diffusion–reaction problems**, built
+to be the engine of live, thermodynamically honest web demos of charge transport: in
+semiconductors, electrochemical cells, membranes and solid ionic conductors. It handles any mix
+of charged and neutral species, Poisson electrostatics (or strict neutrality), bulk and
+interfacial reactions, heterointerfaces, metals and external circuits, in steady state, in time
+and as small-signal impedance. Every physics feature is validated against analytic results, and
+it's small enough to run in a web page: no dependencies, millisecond solves.
 
-**Status: pre-release.** Not yet on npm, and the API may still change.
+[Live demos](https://markblundeberg.github.io/driftlet/demos/) · [npm](https://www.npmjs.com/package/driftlet) ·
+[reading level diagrams](docs/visualization.md) · [device reference](docs/device.md) ·
+[agent guide](llms.txt)
+
+**Status: 0.x.** Released on npm and used by the demos, but the API may still change between
+minor versions.
 
 ## Is it for your problem?
 
@@ -17,12 +30,12 @@ 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 demo](https://markblundeberg.github.io/driftlet/demos/pn.html), [`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 | [`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 |
-| Electrochemistry | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry | [second example](#an-electrochemical-cell), [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 |
+| 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 |
+| 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 |
-| Membranes, desalination | Donnan, ion exchange, liquid junctions, water dissociation | [`equilibrium`](test/equilibrium.test.js), [`neutral`](test/neutral.test.js) tests | Donnan partition, Planck EMF |
+| Membranes, desalination | Donnan, ion exchange, liquid junctions, water dissociation | [membrane demo](https://markblundeberg.github.io/driftlet/demos/membrane.html), [`equilibrium`](test/equilibrium.test.js), [`neutral`](test/neutral.test.js) tests | Donnan partition, Planck EMF |
 | Solid-state ionics | mixed ionic–electronic conduction, defect chemistry, mobile ions | [`statistics`](test/statistics.test.js), [`reactions`](test/reactions.test.js) tests | mass action from standard potentials |
 | Biophysics | Poisson–Nernst–Planck, ion channels, membrane potentials | the electrochemistry setups, with fixed charge in the channel region | no dedicated check yet |
 
@@ -42,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.1.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.2.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).
 
@@ -131,10 +144,10 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | **pn junction**: quasi-Fermi levels under bias; I–V against Shockley | **Solar cell**: J<sub>sc</sub> and V<sub>oc</sub> against collection theory | **MOS capacitor**: band bending; C–V against ideal theory |
 | [![cyclic voltammetry](demos/screenshots/redox.png)](https://markblundeberg.github.io/driftlet/demos/redox.html) | [![Daniell cell](demos/screenshots/daniell.png)](https://markblundeberg.github.io/driftlet/demos/daniell.html) | [![saturation](demos/screenshots/saturation.png)](https://markblundeberg.github.io/driftlet/demos/saturation.html) |
 | **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) | | |
-| **Impedance**: the Warburg arc, and the cell's small-signal response inside | | |
-| [![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) | [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) |
-| **Ion-exchange membrane**: Donnan steps, ion by ion, against TMS theory | **Double layer**: dilute vs crowded ions, against closed forms | **Intercalation host**: cycling between cutoffs against the OCV |
+| [![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) |  |  |
+| **Intercalation host**: cycling between cutoffs against the OCV |  |  |
 
 ## How to think about it
 
@@ -217,6 +230,7 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Floating island | Gauss's law; conserved amounts through gate sweeps | 1e-12 |
 | pn junction | exact built-in potential; depletion charge; short-diode J–V | 1e-12; 1%; 2e-3 |
 | 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 |
 | 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 |
@@ -268,7 +282,7 @@ statistics can't be, and must be built inside the worker.)
 
 ## Development
 
-No dependencies. Tests use node's built-in runner (Node ≥ 20):
+No dependencies. Tests use node's built-in runner (Node ≥ 22):
 
 ```sh
 npm test         # the validation suite

package/docs/alignment.md

@@ -0,0 +1,146 @@
+# Band alignment from vacuum levels
+
+driftlet never decides how levels line up across an interface. Each interface's alignment is
+its own physical property, and you give it explicitly (see [conventions](conventions.md)). But
+sometimes vacuum-level reasoning is the only estimate available, and it's a useful worked
+reference. This page sets it out as one recipe with two ingredients, and lists what it
+assumes.
+
+**Before reaching for it,** ask whether you need an alignment at all. If only macroscopic,
+bulk-neutral behaviour matters, a `phi: 'neutral'` interface makes the alignment drop out, and
+none is needed.
+
+## The recipe: an anchor and an offset per material
+
+Every vacuum-level number in the literature describes **one material against vacuum**. It
+picks a level inside the material (the **anchor**) and says how far above that level, in
+electron energy, the vacuum level just outside the surface lies (the **offset**). In
+driftlet's voltage units ($`V = -E/e`$ for electrons):
+
+```math
+V_{\mathrm{vac}} = V_{\mathrm{anchor}} - \mathtt{offset}
+```
+
+| Quantity | Anchor | Offset |
+|---|---|---|
+| electron affinity $`\chi`$ | conduction band = the e⁻ standard level | $`\chi`$ |
+| ionisation energy | valence band = the h⁺ standard level | $`\chi + E_g`$ |
+| work function W | Fermi level | W |
+| Trasatti's absolute SHE, ≈ 4.44 V | the SHE level of a solution | 4.44 V |
+| surface potential $`\chi_s`$ | the inner potential $`\phi`$ | $`\chi_s`$ |
+
+Two materials are then aligned by **assuming their vacuum levels coincide** across the
+interface. That assumption is the whole heuristic: Anderson's rule, the Schottky–Mott rule, a
+gate's flat-band voltage and the pzc estimate are all this one recipe applied to different
+pairs. It can combine any pair, for example a semiconductor (electron affinity) against an
+aqueous electrolyte (absolute SHE).
+
+### The anchors in driftlet
+
+An anchor has to be a level that driftlet knows in terms of a material's $`\phi`$:
+
+- **A charged species' standard level**, $`V^\circ_i = \phi + \mu^\circ_i/(z_i F)`$. For e⁻ and h⁺
+  these are the band edges, which are electronic levels. For an ion, $`V^\circ_i`$ is simply that
+  ion's standard level: a fixed offset from $`\phi`$, not by itself the level of any electrons.
+- **The SHE level**, the electronic level of the standard hydrogen electrode in a solution:
+
+  ```math
+  V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) = \phi + (\mu^\circ_{\mathrm{H}^+} - \tfrac{1}{2} \mu^\circ_{\mathrm{H}_2}) / F
+  ```
+
+  As an anchor this is `'H+'` (its standard level $`\phi + \mu^\circ_{\mathrm{H}^+}/F`$), with the H₂
+  term folded into the offset: Trasatti's value becomes
+  `{ anchor: 'H+', offset: 4.44 + μ°_H₂/(2F) }`. On the usual conventions
+  ($`\mu^\circ_{\mathrm{H}_2} = 0`$ for the element in its standard state, and
+  $`\mu^\circ_{\mathrm{H}^+} = 0`$ so that $`E^\circ(\mathrm{SHE}) = 0`$), that's just offset 4.44 V.
+  Trasatti's 4.44 V then works exactly like a semiconductor's electron affinity, with the SHE level
+  in place of the conduction band. It needs H⁺ among the species. Other half-reactions could be used
+  as anchors in principle, but each brings its own conventions (the neutral element's $`\mu`$,
+  $`E^\circ(\mathrm{SHE}) = 0`$), so they're not offered as shortcuts here.
+- **The Fermi level** of a metal, the proper reference for a work function. It's taken by
+  `vacuumZeroCharge`, for a conductor region's face or a contact (below). A semiconductor's Fermi
+  level moves with doping and bias, so its work function isn't a material constant: use its
+  electron affinity instead.
+- **$`\phi`$ itself** (`'phi'`), with a surface potential as the offset. That's discouraged, since
+  $`\phi`$ is bookkeeping: its value inside a material depends on how that material's $`\mu^\circ`$ were
+  anchored, and surface potentials are not measurable on their own. If you have settled that
+  bookkeeping to your own satisfaction, it's available.
+
+## In the API
+
+The recipe lives in `driftlet/kit`, as helpers that read a device definition and return the
+spec value to put in it. The spec itself only takes the result (a `dipole` or a `zeroCharge`),
+so what a device assumes stays visible in its definition.
+
+```js nocheck
+import { vacuumDipole, vacuumZeroCharge } from 'driftlet/kit';
+
+// GaAs | AlGaAs: electron affinities on the e⁻ standard level (the conduction band)
+def.interfaces = [{
+  dipole: vacuumDipole(def, { material: 'GaAs', anchor: 'e-', offset: 4.07 }, { material: 'AlGaAs', anchor: 'e-', offset: 3.8 }),
+}];
+```
+
+`vacuumDipole` gives $`\phi_R - \phi_L = (V_{\mathrm{vac}} - \phi)_L - (V_{\mathrm{vac}} - \phi)_R`$,
+each side's $`V_{\mathrm{vac}} - \phi`$ coming from its anchor and offset (`vacuumLevel` gives one
+side's).
+
+Where a conductor meets a material, at a conductor region's face or at a contact's capacitive
+or pinned law, the conductor's side is its work function W from its Fermi level, and the
+helper gives `zeroCharge` ($`V_F - \phi_{\mathrm{edge}}`$ at zero charge):
+
+```js nocheck
+const zc = vacuumZeroCharge(def, 4.75, { material: 'Si', anchor: 'e-', offset: 4.05 }); // Au | n-Si
+def.interfaces = [{ phi: { type: 'capacitive', C: 10 }, zeroCharge: zc }];        // Au as a region
+Object.assign(def.contacts.left, { phi: { type: 'capacitive', C: 10 }, zeroCharge: zc }); // or as a contact
+// zeroCharge = W + (V_vac − φ)_inside = W − χ − μ°_e/F
+```
+
+## Pairwise examples
+
+**Semiconductor heterojunction (Anderson's rule).** Electron affinities on both sides,
+`{ material, anchor: 'e-', offset: χ }`, give $`\Delta E_c = \chi_L - \chi_R`$. The valence-band offset
+then follows from the two gaps, already in your holes' $`\mu^\circ`$. Ionisation energies on `'h+'`
+give the same thing from the other band.
+
+**Metal | semiconductor (Schottky–Mott).** Work function against electron affinity gives the
+n-type barrier $`\phi_B = W - \chi`$. With the metal as a contact, a pinned law
+`phi: 'pinned', zeroCharge: vacuumZeroCharge(def, W, { material, anchor: 'e-', offset: χ })`
+puts the semiconductor's surface electron density at $`N_c e^{-\phi_B/kT}`$. With the metal as a
+region, the face is capacitive with the same `zeroCharge`; a large C approaches the pinned
+barrier.
+
+**Gate | semiconductor (flat band).** The same with a capacitive law. Its `zeroCharge` is the
+anchor-level form of the textbook $`V_{\mathrm{FB}} = (W_g - W_s)/e`$, which refers to the
+semiconductor's bulk Fermi level instead. Fixed charge in a real insulator shifts flat band further.
+
+**Metal | electrolyte (potential of zero charge).** Work function against the absolute SHE gives
+$`\mathrm{pzc} \approx W/e - 4.44\,\mathrm{V}`$ on the SHE scale (on the usual conventions above):
+`zeroCharge: vacuumZeroCharge(def, W, { material, anchor: 'H+', offset: 4.44 })`.
+
+**Semiconductor | electrolyte.** Electron affinity against the absolute SHE places the band edges on
+the SHE scale, $`E_c \approx -(\chi - 4.44)\,\mathrm{eV}`$ relative to SHE: the usual
+photoelectrochemistry estimate:
+`vacuumDipole(def, { material: 'TiO2', anchor: 'e-', offset: χ }, { material: 'water', anchor: 'H+', offset: 4.44 })`.
+
+**Solvent | solvent.** Each solvent's own absolute-SHE-type value (its Trasatti-type offset)
+aligns them, exactly as Anderson's rule aligns two semiconductors.
+
+## What the heuristic assumes, and where it fails
+
+1. **The vacuum level runs continuously through the interface.** In reality, the interface
+   forms its own dipole (charge transfer, bonding, solvent orientation, adsorbates) beyond
+   what the two free surfaces imply.
+2. **Surface quantities are properties of the material.** They aren't: W, $`\chi`$ and 4.44 V are
+   barrier heights of particular surfaces, and change with termination, adsorbates and
+   preparation. The 4.44 V is itself the work function of a hydrogen electrode, not a
+   universal zero.
+3. **Alignments add up transitively** around any set of materials, and are uniform along each
+   interface.
+
+At covalent interfaces (common semiconductors, most metal–semiconductor contacts), measured
+alignments often depart substantially from these rules, and Fermi-level pinning is common.
+Ionic materials tend to follow them better. At metal–solution interfaces, the neglected
+metal–solvent terms (orientation, chemisorption) are often a few tenths of a volt.
+Whenever a measured offset, barrier, flat-band voltage or pzc exists, use it instead:
+`step`, `dipole` and `zeroCharge` take measured values directly.

package/docs/conventions.md

@@ -0,0 +1,194 @@
+# Conventions
+
+Conventions are where users of any drift–diffusion code go wrong, so here they all are in one
+place. driftlet's are chosen to be thermodynamically honest, and some of them are deliberately
+stricter than you may be used to.
+
+## Principles
+
+1. **Every control and every measurable is an electrochemical potential** $`\bar\mu`$, or a
+   difference of them. A bias voltage sets a difference in $`\bar\mu`$ of electrons between
+   terminals, $`V = -\Delta\bar\mu_{\mathrm{e}^-}/F`$. A gate sets its metal's $`\bar\mu_{\mathrm{e}^-}`$.
+   Nothing you set is an electrostatic potential.
+2. **$`\phi`$ is bookkeeping.** Any consistent $`\phi`$ gives identical physics. Each material's standard
+   chemical potentials fix where its $`\phi`$ sits relative to its own levels, so $`\phi`$ jumps at
+   every interface between different materials, by that interface's dipole. How big a dipole is
+   depends on how each material was anchored, which is why it's arbitrary, correctly so. If you
+   do have true mean inner potentials, you may anchor to them, but nothing requires it.
+   Extrathermodynamic conventions are one way people settle a "real" $`\phi`$ per material. TATB,
+   for instance, fixes single-ion transfer energies between solvents by assuming
+   $`\Delta G_{\mathrm{tr}}(\mathrm{Ph_4As}^+) = \Delta G_{\mathrm{tr}}(\mathrm{Ph_4B}^-)`$. That's a
+   statement about bulk single-ion energies, i.e. about how each solvent's $`\mu^\circ`$ are
+   anchored. It says nothing about the dipole at an actual interface, which stays a separate
+   input.
+3. **Bulk standard potentials only mean something in neutral combinations**
+   ($`\mu^\circ_{\mathrm{e}^-} + \mu^\circ_{\mathrm{h}^+}`$,
+   $`\mu^\circ_{\mathrm{Na}^+} + \mu^\circ_{\mathrm{Cl}^-}`$,
+   $`\mu^\circ_{\mathrm{Li}^+} + \mu^\circ_{\mathrm{e}^-}`$). How charged levels line up across a
+   boundary between different materials is a property of that interface, and you must give it.
+   There's no Anderson rule, no Schottky–Mott rule, and no implied common vacuum level. Each
+   interface's alignment is independent, even when the same pair of materials meets twice
+   (e.g. with different adsorbates). When vacuum-level estimates are all you have, helpers in
+   `driftlet/kit` turn anchors and offsets into an alignment (see the
+   [alignment guide](alignment.md)).
+4. **A work function belongs to a surface, not a material.**
+
+## Electrochemical potential and its views
+
+For species *i* with charge number $`z_i`$, in a material where its standard chemical potential
+is $`\mu^\circ_i`$, the electrochemical potential splits as
+
+```math
+\bar\mu_i = \mu^\circ_i + z_i F \phi + RT \zeta_i
+```
+
+The reduced chemical potential $`\zeta_i`$ is what a material's **statistics** turn into a
+concentration, $`c_i = c_i(\zeta)`$. The default is ideal (dilute) statistics,
+
+```math
+c_i = c_{\mathrm{ref},i} \cdot e^{\zeta_i}, \quad\text{i.e.}\quad \bar\mu_i = \mu^\circ_i + z_i F \phi + RT \ln(c_i / c_{\mathrm{ref},i})
+```
+
+with $`c_{\mathrm{ref},i}`$ the reference concentration that $`\mu^\circ_i`$ refers to. Non-ideal
+statistics (degenerate carriers, crowding, intercalation hosts, activity coefficients) are chosen
+per material; see [statistics](statistics.md). They all reduce to the ideal form in the dilute
+limit, so $`\mu^\circ`$ and $`c_{\mathrm{ref}}`$ mean the same thing in every model: the dilute
+(Henry's-law) reference.
+
+The API speaks $`\bar\mu`$ in J/mol (`units.eV` converts per-particle energies). Two voltage views
+are provided for charged species (what they show, and why they're drawn, is in
+[reading level diagrams](visualization.md)):
+
+- the **species voltage** $`V_i = \bar\mu_i / (z_i F)`$, which is what a voltmeter reads for
+  electrons, and the analogous quantity a reversible electrode reads for an ion;
+- the **standard level** $`V^\circ_i = \phi + \mu^\circ_i / (z_i F)`$, which plays the part of a
+  band edge.
+
+Plotted as voltages, a semiconductor's conduction-band level $`V^\circ_{\mathrm{e}^-}`$ sits
+*below* its valence-band level $`V^\circ_{\mathrm{h}^+}`$. That's expected, since $`V = -E/e`$ for
+electrons.
+
+Electrons and holes are ordinary species: $`z = \mp 1`$, $`c_{\mathrm{ref}}`$ = effective density of
+states, and $`\mu^\circ`$ = the band edges as molar energies (conduction band for e⁻, minus the
+valence band for h⁺). With Fermi–Dirac statistics the same parameters give
+$`c = N_c \mathcal{F}_{1/2}(\zeta)`$.
+
+## Transport
+
+Each species moves down its own electrochemical potential:
+
+```math
+\begin{aligned}
+N_i &= -(D_i c_i / RT) \nabla\bar\mu_i && \quad\text{(particle flux, mol/(m}^2\cdot\text{s))} \\
+J_i &= z_i F N_i = -\sigma_i \nabla V_i, \qquad \sigma_i = z_i^2 F^2 D_i c_i / RT
+\end{aligned}
+```
+
+Drift and diffusion are one law, and the Einstein relation is automatic. $`D`$ is the coefficient
+of $`c\nabla\bar\mu/RT`$, i.e. $`RT`$ times the mobility per mole, and it's the same parameter
+whatever the statistics. For ideal statistics it's the ordinary diffusivity. With non-ideal
+statistics the measured chemical diffusivity is $`D`$ times the thermodynamic factor,
+$`\partial \ln a/\partial \ln c`$: the generalised Einstein relation, as for degenerate electrons.
+
+Two optional transport terms describe a moving fluid:
+
+- **Advection** by an imposed velocity $`v`$ adds $`v \cdot c_i`$ to every mobile species' flux.
+- **Eddy mixing** adds $`-(D_{\mathrm{mix}}/RT) P \nabla\bar\mu`$, with
+  $`P = C - C z z^\mathsf{T} C / (z^\mathsf{T} C z)`$ and $`C = \mathrm{diag}(c)`$.
+  - It's an Onsager term: symmetric, positive semi-definite, and zero at equilibrium (flat
+    $`\bar\mu`$), so double layers at rest are untouched.
+  - The projection removes any current ($`z^\mathsf{T} P = 0`$). Eddies move neutral fluid, so
+    they mix salt and stir concentration gradients but conduct nothing.
+  - For a neutral dilute species it's exactly $`-D_{\mathrm{mix}} \nabla c`$. For a binary salt it
+    adds $`D_{\mathrm{mix}}`$ to the salt's ambipolar diffusivity and leaves diffusion potentials
+    unchanged.
+
+## Materials, regions, interfaces
+
+A **material** holds bulk properties ($`\varepsilon`$, and $`D`$, $`\mu^\circ`$, $`c_{\mathrm{ref}}`$ per
+species). A **region** is a material plus a length, fixed charge and initial composition. Every
+**interface** between different materials takes exactly one alignment (see principle 3), unless
+its electrostatic law is `neutral`, in which case the alignment has no effect and is not allowed.
+The three laws:
+
+- `pinned`: $`\phi`$ jumps by exactly the alignment, and the double layers on either side are
+  resolved by the grid.
+- `neutral`: the macroscopic idealisation. No charge sits at the face, and $`\phi`$ jumps by
+  whatever local neutrality on each side requires (a Donnan or Galvani step).
+- `capacitive`: a Helmholtz layer of capacitance $`C`$, charged by any departure of the jump
+  from the alignment.
+
+A **conductor** (a metal, or a fast ion conductor) is a material of its own kind: its one level
+is its carrier's (a metal's Fermi level), it has no $`\phi`$, and a face beside it ties the other
+side's $`\phi`$ to that level through a capacitance (see the
+[device reference](device.md#faces-next-to-a-conductor)).
+
+A face between a strictly neutral ($`\varepsilon = 0`$) material and one with $`\varepsilon > 0`$,
+such as an electrode and an electrolyte, is naturally `pinned`. The neutral side holds the
+surface charge, and the alignment plays the role of a potential of zero charge or work function.
+
+## Contacts and terminals
+
+A contact is an interface with an **outside phase** whose levels are known, like one more region
+with a fully known node. The outside phase's charged levels form a rigid ladder,
+$`V_i = V + \mathtt{offset}_i`$, which the external circuit slides by the **terminal voltage** $`V`$
+(the voltage of a named terminal species). The laws joining it to the device (equilibrium,
+blocked, conductance; and for $`\phi`$, bulk, neutral, capacitive, dipole) are the same as at
+internal faces. Reactions sit at faces between regions: an electrode is a conductor region with
+reactions at its face.
+
+- **Species in equilibrium** with the outside phase sit at $`V_i = V + \mathtt{offset}_i`$. The
+  offset belongs to the outside phase: it's the chemical potential, per charge, of whatever
+  neutral combination the species forms with the terminal species there. It's 0 for the
+  terminal species itself. For an ion at a reversible electrode,
+  $`\mathrm{M}^{n+} + n\,\mathrm{e}^- \rightleftharpoons \mathrm{M(s)}`$ gives
+  $`\mu_{\mathrm{M}}/(nF)`$, which is 0 on the usual table convention: $`E^\circ`$ is carried by the
+  ion's $`\mu^\circ`$ in the solution, not by the offset. It's never defaulted for any other
+  species. Neutral species are fixed by an absolute $`\bar\mu`$.
+- **Ohmic contacts** to a semiconductor are just $`V_{\mathrm{e}^-}`$ and/or $`V_{\mathrm{h}^+}`$ in
+  equilibrium with the metal:
+  - both, at the same metal, gives $`V_{\mathrm{h}^+} = V_{\mathrm{e}^-}`$, an
+    infinite-recombination contact ($`n \cdot p = n_i^2`$ there);
+  - one alone gives a selective contact.
+- **Baths** are a shorthand. From a neutral composition and a reference species (the ion a
+  reversible reference electrode would sense, e.g. Cl⁻ for Ag/AgCl), driftlet works out every
+  species' equilibrium level.
+- **Gates and Stern layers** are capacitive $`\phi`$ laws to a conductor at the terminal voltage.
+  Their `zeroCharge` is the value of $`V - \phi_{\mathrm{edge}}`$ at which the interface is
+  uncharged. For an electrode in a solution with table $`\mu^\circ`$ (where $`V - \phi`$ reads
+  against SHE) that's the potential of zero charge; for a gate it sets the flat-band voltage,
+  $`V_{\mathrm{FB}} = \mathtt{zeroCharge} + \phi_{\mathrm{bulk}}`$, with $`\phi_{\mathrm{bulk}}`$ in
+  the semiconductor's own anchoring (−1.00 V in p-type silicon at 1e17 cm⁻³ with
+  $`\mu^\circ_{\mathrm{e}^-} = 0`$). Like every alignment, it's a property of that interface. The
+  `pinned` law is the $`C \to \infty`$ limit (e.g. a Schottky barrier), which is what a
+  "fixed $`\phi`$" boundary honestly means.
+- **`bulk`** says the end node is plain bulk (locally neutral, no double layer), while
+  **`neutral`** says no charge sits at the face ($`D = 0`$), as for internal faces.
+- **Electrode reactions** take their electrons from the conductor region at its Fermi level,
+  which the contact behind it holds at $`\bar\mu_{\mathrm{e}^-} = -F \cdot V`$.
+
+The electronic level of a standard hydrogen electrode in a solution is
+$`V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) = \phi + (\mu^\circ_{\mathrm{H}^+} - \tfrac{1}{2}\mu^\circ_{\mathrm{H_2}})/F`$.
+The usual tables set $`\mu^\circ_{\mathrm{H}^+} = 0`$ (so that $`E^\circ(\mathrm{SHE}) = 0`$) and
+$`\mu^\circ_{\mathrm{H_2}} = 0`$ for the element in its standard state, and then
+$`V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) = \phi`$. So with ion $`\mu^\circ`$ from such tables, $`V - \phi`$
+in a solution is a potential against SHE. A metal's $`V - \phi_{\mathrm{edge}}`$ at zero charge (a
+`zeroCharge`, i.e. a pzc) reads directly on the SHE scale.
+
+## Terminals and signs
+
+- A terminal's voltage $`V`$ is the shift of its outside phase's ladder, measured as the voltage of
+  its terminal species. Every voltage is absolute (no terminal is special), and at least one
+  terminal must be held at one.
+- **A terminal's current is into the device** (conduction plus displacement), so in steady
+  state they sum to zero. $`V \cdot I`$ is the electrical work done through it; an outside phase
+  that exchanges several species also trades chemical free energy through its offsets.
+- **`current` is positive toward +x** through the device (into it at the left, out at the
+  right). A forward-biased pn junction with its p side on the right carries negative current.
+- `terminalVoltage` is $`V_{\mathrm{right}} - V_{\mathrm{left}}`$.
+
+## Units
+
+SI throughout: m, mol/m³, J/mol, V, A/m², F/m² (per-area capacitance), C/m³ (fixed charge),
+C/m² (sheet charge), S/m² (interface conductance), mol/(m²·s) (surface rate constants),
+s. Temperature is uniform (default 298.15 K).

package/docs/data.md

@@ -0,0 +1,120 @@
+# Data library
+
+`driftlet/kit` carries a small library of bulk properties, each with its source, so a demo can
+start from vetted numbers. It's kept small on purpose, because a wrong library number is worse
+than a wrong demo number. The ions and semiconductors are checked in the tests against
+independent tables: $`\mu^\circ`$ against the electrochemical series, D against limiting conductivities,
+band data against the quoted intrinsic concentrations.
+
+The library holds **bulk properties only**. How levels line up at an interface, a surface's
+work function, a pzc and rate constants all belong to a particular interface or surface, so
+you give them yourself (see [conventions](conventions.md)).
+
+## Aqueous ions, 25 °C
+
+`aqueous(names, { epsr, material })` returns water holding the named ions, as a library piece
+for `build()`: each ion a species with $`c_{\mathrm{ref}}`$ = 1000 mol/m³ (1 M), and the material
+`water` with its D and $`\mu^\circ`$. `epsr` defaults to water's 78.30 at 25 °C (Malmberg and
+Maryott 1956); `epsr: 0` makes the solution strictly neutral, for macroscopic models without
+double layers. The data are in `IONS`, and $`\mu^\circ`$ of liquid water is `H2O`
+(−237.129 kJ/mol), for reactions such as H₂O ⇌ H⁺ + OH⁻.
+
+| Ion | z | D (10⁻⁹ m²/s) | $`\mu^\circ`$ (kJ/mol) |
+|---|---|---|---|
+| H+ | +1 | 9.311 | 0 |
+| Li+ | +1 | 1.029 | −293.31 |
+| Na+ | +1 | 1.334 | −261.905 |
+| K+ | +1 | 1.957 | −283.27 |
+| Ag+ | +1 | 1.648 | 77.107 |
+| Cu2+ | +2 | 0.714 | 65.49 |
+| Zn2+ | +2 | 0.703 | −147.06 |
+| Fe2+ | +2 | 0.719 | −78.9 |
+| Fe3+ | +3 | 0.604 | −4.7 |
+| OH- | −1 | 5.273 | −157.244 |
+| Cl- | −1 | 2.032 | −131.228 |
+| NO3- | −1 | 1.902 | −111.25 |
+| SO42- | −2 | 1.065 | −744.53 |
+
+- **D**: diffusivities at infinite dilution, from the CRC Handbook of Chemistry and Physics,
+  "Ionic conductivity and diffusion at infinite dilution". They're limiting values, so at
+  real concentrations ions move somewhat slower.
+- **$`\mu^\circ`$**: standard Gibbs energies of formation, from Wagman et al., "The NBS tables of
+  chemical thermodynamic properties" (J. Phys. Chem. Ref. Data 11, Suppl. 2, 1982), on the usual
+  table convention: $`\Delta_{\mathrm{f}} G^\circ(\mathrm{H}^+) = 0`$ and elements in their standard
+  states at 0. With these $`\mu^\circ`$, the electronic level of a standard hydrogen electrode in
+  the solution is $`\phi`$ itself (see [conventions](conventions.md)), so $`V - \phi`$ reads against
+  SHE.
+- **Standard state**: the tables use 1 mol/kg, and the library uses 1 M. In dilute water at 25 °C
+  they differ by 0.3%, about 7 J/mol in $`\mu^\circ`$.
+- **Iron**: Fe²⁺'s $`\Delta_{\mathrm{f}} G^\circ`$ gives $`E^\circ(\mathrm{Fe}^{2+}/\mathrm{Fe})`$ =
+  −0.41 V, where the CRC series lists −0.447 V; sources disagree on iron. The difference between
+  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
+
+`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,
+$`\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).
+
+| | $`\varepsilon_r`$ | $`E_g`$ (eV) | $`\chi`$ (V) | $`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 |
+| GaAs | 13.1 | 1.424 | 4.07 | 4.7 × 10¹⁷ | 7.0 × 10¹⁸ | 8500 | 400 |
+
+- 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.
+- **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%.
+
+## Metals, 20 °C
+
+`metal(name, { material })` returns a conductor material carrying `e-`, with its conductivity
+$`1/\rho`$ from the CRC Handbook's resistivities of pure metals at 293 K ("Electrical resistivity of
+pure metals"). The data are in `METALS`, as `rho` (10⁻⁸ Ω·m) and `conductivity` (S/m). They
+aren't cross-checked against a second table in the tests; a metal's conductivity only sets the
+ohmic drop inside it, which is usually negligible.
+
+| | Ag | Cu | Au | Al | Zn | Li | Pt |
+|---|---|---|---|---|---|---|---|
+| $`\rho`$ (10⁻⁸ Ω·m) | 1.587 | 1.678 | 2.214 | 2.65 | 5.90 | 9.28 | 10.5 |
+| $`\sigma`$ (10⁷ S/m) | 6.30 | 5.96 | 4.52 | 3.77 | 1.69 | 1.08 | 0.952 |
+
+There are no work functions: a work function belongs to a surface, not a metal, and it varies
+by facet and adsorbate. Give a face's `zeroCharge` (or use `vacuumZeroCharge` with a work
+function you've chosen for that surface).
+
+## Example
+
+```js
+import { Device } from 'driftlet';
+import { build, layer, ohmic, half, level, SHE, aqueous, metal } from 'driftlet/kit';
+
+// A platinum electrode in Fe³⁺/Fe²⁺ chloride at equilibrium: its Fermi level sits at the
+// couple's redox level, E° against SHE when the two are equal: 0.769 V from the library's NBS values (tables list 0.771 V).
+const iron = half('Fe3+ + e- = Fe2+');
+const def = build({
+  library: [aqueous(['H+', 'Fe3+', 'Fe2+', 'Cl-'], { epsr: 0 }), metal('Pt')],
+  stack: [
+    ohmic(0, ['e-']),
+    layer('Pt', 1e-6),
+    { reactions: [{ ...iron, k0: 1e-3 }] },
+    layer('water', 1e-6, { c0: { 'H+': 100, 'Fe3+': 10, 'Fe2+': 10, 'Cl-': 150 } }),
+    { reactions: [{ ...iron, k0: 1e-3 }] },
+    layer('Pt', 1e-6),
+    ohmic(0, ['e-']),
+  ],
+});
+const sol = new Device(def).solve();
+const g = sol.x.length >> 1;
+console.log(`V_e(Pt) − V°(SHE) = ${(sol.V['e-'][0] - level(sol, SHE, { standard: true })[g]).toFixed(4)} V`);
+```