driftlet 0.1.0 → 0.2.0

package/docs/statistics.md

@@ -0,0 +1,226 @@
+# Statistics
+
+A material's **statistics** say how its concentrations follow from its species' potentials.
+Every species *i* has a reduced chemical potential
+
+```math
+\zeta_i = (\bar\mu_i - z_i F \phi - \mu^\circ_i) / RT
+```
+
+and a statistics model gives the concentrations $`c(\zeta)`$ of the species it covers. Species
+that aren't in any model are ideal, $`c = c_{\mathrm{ref}} \cdot e^\zeta`$, which is the default and
+the right choice for dilute species. Non-ideal models describe degenerate carriers, crowding,
+filling of a finite set of sites, activity coefficients, and intercalation hosts.
+
+Three rules hold for every model:
+
+- **The dilute limit is ideal.** Every model tends to $`c_{\mathrm{ref}} \cdot e^\zeta`$ as $`c \to 0`$,
+  so `mu0` and `cRef` keep one meaning (the dilute, Henry's-law reference state) whatever the
+  statistics. Changing a material's statistics changes only its non-dilute behaviour.
+- **The Jacobian is a chemical capacitance.** $`K = \partial c/\partial\zeta`$ is the Hessian of a
+  convex potential (the grand potential density $`P(\zeta)`$, with $`c = \partial P/\partial\zeta`$),
+  so it's symmetric and positive definite. $`RT \cdot K`$ is the chemical capacitance matrix per
+  volume. Models whose free energy isn't convex (a miscibility gap) are refused, because they
+  need phase separation (Cahn–Hilliard, on the [roadmap](../ROADMAP.md)).
+- **D keeps its meaning.** Fluxes are always $`N = -(D c/RT)\nabla\bar\mu`$, with $`D`$ the
+  dilute-limit coefficient (constant mobility). The chemical diffusivity you'd measure is $`D`$
+  times the thermodynamic factor $`\partial\ln a/\partial\ln c`$, the generalised Einstein
+  relation. See [conventions](conventions.md#transport).
+
+## Declaring statistics
+
+```js nocheck
+materials: {
+  Si: {
+    epsr: 11.7,
+    species: { 'e-': { D: 36e-4, mu0: 0, cRef: Nc }, 'h+': { D: 12e-4, mu0: units.eV(1.12), cRef: Nv } },
+    statistics: [{ type: 'fermi-dirac', species: ['e-', 'h+'] }],
+  },
+}
+```
+
+`statistics` is a list of models, each naming the species it covers. A species belongs to at
+most one model.
+
+| Model | Species | $`c(\zeta)`$ | Parameters |
+|---|---|---|---|
+| `fermi-dirac` | any, each independently | $`c_{\mathrm{ref}} \mathcal{F}_{1/2}(\zeta)`$ (3D band); $`c_{\mathrm{ref}} \ln(1 + e^\zeta)`$ with `order: 0` (2D) | `order`: 1/2 (default) or 0 |
+| `lattice` | any, sharing sites | $`c_a = c_{\mathrm{max}} w_a / (1 + \sum w)`$, $`w_a = (c_{\mathrm{ref},a}/c_{\mathrm{max}}) e^{\zeta_a}`$ | `cMax`, site density, mol/m³ |
+| `redlich-kister` | one | on its own sites: $`\zeta = \ln(x/(1-x)) + \ln(c_{\mathrm{max}}/c_{\mathrm{ref}}) + (g(x) - g(0))/RT`$, $`x = c/c_{\mathrm{max}}`$ | `cMax`; `A`, J/mol |
+| `debye-huckel` | charged | $`c_{\mathrm{ref}} e^\zeta / \gamma`$, $`\ln\gamma_i = -z_i^2 \ell_B \kappa / (2(1 + \kappa a))`$ | `epsr` (solvent, for the theory); `a`, m |
+| `insertion` | [ion, carrier], $`\varepsilon = 0`$ host | occupancy from the neutral combination (below) | `cMax`; `A` or `ocv` |
+| `custom` | any | your function | `evaluate(zeta) → { c, dcdzeta }` |
+
+### Fermi–Dirac
+
+For electrons and holes, $`c_{\mathrm{ref}}`$ is the effective density of states and $`\mu^\circ`$ the
+band edge, as for ideal statistics, and $`c = N_c \mathcal{F}_{1/2}(\zeta)`$ with the normalised
+Fermi–Dirac integral ($`\mathcal{F}_j \to e^\zeta`$ for $`\zeta \to -\infty`$). driftlet evaluates
+$`\mathcal{F}_{1/2}`$ and $`\mathcal{F}_{-1/2}`$ (its derivative) to ~1e-14 relative, so equilibrium
+carrier densities are exact. `order: 0` is a two-dimensional density of states, and it's exact
+in closed form.
+
+### Lattice gas
+
+The listed species share $`c_{\mathrm{max}}`$ sites per volume and each occupies one, so no
+concentration can exceed $`c_{\mathrm{max}}`$. With both ions of an electrolyte on one lattice, this
+is the Bikerman / Kilic–Bazant–Ajdari model of a crowded double layer. At large potentials the
+counter-ion saturates at $`c_{\mathrm{max}}`$, and the diffuse charge grows as $`\sqrt{\psi}`$ instead
+of exponentially. With one species it's Langmuir filling of sites. The dilute reference
+$`c_{\mathrm{ref}}`$ is kept. To use the half-filling convention of site models
+($`e^\zeta = x/(1-x)`$), set `cRef` equal to `cMax`.
+
+### Redlich–Kister
+
+One species on its own $`c_{\mathrm{max}}`$ sites, with the excess Gibbs energy of mixing per site
+$`x(1-x) \sum A_k (1-2x)^k`$. $`g(x)`$ in the table is its $`x`$-derivative, the excess chemical
+potential. A single `A: [Ω]` is the regular solution,
+$`\mu = \mu^\circ + RT \ln(x/(1-x)) + \Omega(1-2x) + \mathrm{const}`$. It's convex only for
+$`\Omega < 2RT`$, which is checked at construction.
+
+The table form is referred to the dilute limit. The half-filling convention of the battery
+literature, $`\mu = \mu^\circ_{1/2} + RT \ln(x/(1-x)) + \Omega(1-2x)`$, corresponds to
+`cRef = cMax` and `mu0` $`= \mu^\circ_{1/2} + A_0`$ (the excess at $`x = 0`$, $`\sum A_k`$ in general).
+
+### Debye–Hückel
+
+Extended Debye–Hückel activity coefficients for dilute electrolytes:
+$`\ln\gamma_i = -z_i^2 \ell_B \kappa / (2(1 + \kappa a))`$, with the Bjerrum length
+$`\ell_B = e^2/(4\pi\varepsilon kT)`$ and $`\kappa^2 = F^2 \sum z^2 c / (\varepsilon RT)`$ from the
+solvent permittivity `epsr` (which defaults to the material's, if that's non-zero) and a
+distance of closest approach `a` (default 0, the limiting law). It stops being convex at high
+ionic strength, and the solver then reports a failure.
+
+Single-ion activity coefficients are a convention: only neutral combinations (the mean
+activity $`\gamma_\pm`$) are measurable. In a strictly neutral ($`\varepsilon = 0`$) material only
+those combinations matter, so that's where this model belongs. With $`\varepsilon > 0`$, the
+resolved double layers would depend on the convention, so driftlet warns.
+
+### Insertion hosts: neutral-combination statistics
+
+In an intercalation host, an inserted ion enters together with its compensating electronic
+carrier, e.g. $`\mathrm{Li}^+ + \mathrm{e}^-`$. Only their neutral combination has a well-defined
+chemical potential, $`\mu_{\mathrm{Li}} = \bar\mu_{\mathrm{Li}^+} + \bar\mu_{\mathrm{e}^-}`$, and the
+host's composition depends on nothing else. That's what an OCV curve measures, and the mutual
+chemical capacitance of the pair is the slope of that curve.
+
+The `insertion` model describes exactly this, in a strictly neutral host (`epsr: 0`) whose
+only charged species are the pair `[ion, carrier]`. For an ion of charge $`z`$ and a carrier of
+charge $`-z/\nu`$:
+
+```math
+\begin{aligned}
+\zeta_{\mathrm{comb}} &= \zeta_{\mathrm{ion}} + \nu \zeta_{\mathrm{carrier}} \quad (\phi\text{ cancels}) \\
+c_{\mathrm{ion}} &= s(\zeta_{\mathrm{comb}}), \qquad c_{\mathrm{carrier}} = \nu s + \text{background}
+\end{aligned}
+```
+
+The occupancy $`s = c_{\mathrm{max}} x`$ comes either from a Redlich–Kister isotherm (`A`, as above,
+referred to the ion's dilute reference) or from a table:
+
+```js nocheck
+statistics: [{
+  type: 'insertion',
+  species: ['Li+', 'e-'],
+  cMax: 30000, // sites, mol/m³
+  ocv: { x: [...], E: [...], muRef: 0 }, // E against a reference where μ_Li = muRef
+}]
+```
+
+The table gives the open-circuit voltage $`E(x)`$ of the host against a reference electrode in
+which the combination has chemical potential `muRef` (J/mol), so that
+$`\mu_{\mathrm{ion}} + \nu \mu_{\mathrm{carrier}} = \mathtt{muRef} - z F E(x)`$. Against Li metal,
+on the usual table convention, `muRef` is 0. $`x`$ must increase and $`E`$ must strictly decrease.
+A flat plateau means phase separation, which isn't supported yet. The table is read as
+$`\zeta = \ln(x/(1-x)) + r(x)`$: the residual $`r`$, the host's non-ideality, is a shape-preserving
+cubic between points and continues linearly beyond them. Ideal and regular-solution curves are
+therefore reproduced exactly, and $`x`$ stays within $`(0, 1)`$ at any potential. The interpolated
+curve is checked for monotonicity at construction.
+
+Because every charged species sits in a neutral combination, **$`\phi`$ is undefined** in such a
+host and is reported as `NaN`. Its faces must be `neutral` (the default next to such a host),
+and its contacts `bulk` or `neutral`. The host's `fixedCharge` is balanced by background
+carriers, $`\mathtt{background} = -\mathtt{fixedCharge}/(z_{\mathrm{carrier}} F)`$, which must be
+non-negative. This is a jellium description of the host's own electrons, which keep it
+conducting when it's empty. With no fixed charge, the carriers are only those that came in with
+the ions. The carrier's `cRef` plays no part (only the combination's $`\mu^\circ`$ and the ion's
+`cRef` enter), but it must still be given.
+
+An insertion host belongs with [conductor regions](device.md#materials) more than with the other
+statistics here. Both are conductors with no $`\phi`$ of their own:
+- **A metal** is the one-carrier case: its Fermi level is its only unknown.
+- **An insertion host** is the two-carrier case: only the neutral combination's potential sets
+  the composition, and the split between ion and carrier is free.
+
+A general mixed conductor with more mobile species needs fully populated mutual capacitance and
+conductance matrices, a different model again (see the [roadmap](../ROADMAP.md)).
+
+### Custom
+
+```js nocheck
+statistics: [{
+  type: 'custom',
+  species: ['A', 'B'],
+  evaluate: (zeta) => ({ c: [cA, cB], dcdzeta: [[dA_dA, dA_dB], [dB_dA, dB_dB]] }),
+}]
+```
+
+`evaluate` gets the species' $`\zeta`$ (in the listed order) and returns their concentrations and
+the Jacobian $`\partial c/\partial\zeta`$. The Jacobian must be symmetric and positive definite,
+and that's checked at $`\zeta = 0`$ when the device is built. A device with a function in it isn't
+plain data, so it can't be posted to a Web Worker. Build it inside the worker instead.
+
+## Transport with non-ideal statistics
+
+The flux law is $`N = -(D c/RT)\nabla\bar\mu`$ for every model. Writing $`\ln c = \zeta - \mathrm{ex}`$
+with the excess $`\mathrm{ex} = \zeta - \ln(c/c_{\mathrm{ref}})`$ (zero for ideal statistics), the
+excess acts like an extra potential. The Scharfetter–Gummel flux keeps its form with
+$`\Delta = z\Delta\hat\phi + \Delta\mathrm{ex}`$ (see [numerics](numerics.md#fluxes)), so it's still
+exactly zero at equilibrium. It's second-order accurate in the cell size (and exact for a single
+diffusing species on a lattice).
+
+Reaction rates keep their concentration-based prefactors (mass action in $`c`$, and
+$`c/c_{\mathrm{ref}}`$ in the Butler–Volmer forms), while the driving force is always the affinity
+from $`\bar\mu`$. So equilibrium is exact for any statistics, and only the kinetics away from it
+depend on that choice of prefactor.
+
+Cross-species transport coefficients (an Onsager matrix) aren't included: each species moves
+down its own $`\bar\mu`$. They should arrive together with cross chemical capacitances, as two
+halves of the same network ([roadmap](../ROADMAP.md)). Note that $`K`$ itself can already be
+non-diagonal, e.g. on a shared lattice.
+
+## Example: a lithium host against its OCV
+
+```js
+import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
+
+const RT = GAS_CONSTANT * 298.15;
+const x = [0.05, 0.2, 0.4, 0.6, 0.8, 0.95];
+const E = x.map((v) => 0.4 - (RT / FARADAY) * Math.log(v / (1 - v))); // an ideal-solution OCV, V vs Li
+
+const dev = new Device({
+  species: [
+    { name: 'Li+', z: 1 },
+    { name: 'e-', z: -1 },
+  ],
+  materials: {
+    host: {
+      epsr: 0,
+      species: { 'Li+': { D: 1e-14, mu0: 0, cRef: 30000 }, 'e-': { D: 1e-4, mu0: 0, cRef: 30000 } },
+      statistics: [{ type: 'insertion', species: ['Li+', 'e-'], cMax: 30000, ocv: { x, E, muRef: 0 } }],
+    },
+  },
+  regions: [{ material: 'host', length: 1e-6 }],
+  contacts: {
+    // Li⁺ from a lithium reference (via an electrolyte) on the left; electrons from a current
+    // collector on the right, whose voltage is the electrode potential vs Li.
+    left: { V: 0, terminal: 'Li+', species: { 'Li+': 'equilibrium' }, phi: 'bulk' },
+    right: { V: 0.4, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'bulk' },
+  },
+});
+for (const V of [0.5, 0.4, 0.3]) {
+  dev.set({ contacts: { right: { V } } });
+  const sol = dev.solve();
+  console.log(`E = ${V} V: x = ${(sol.c['Li+'][5] / 30000).toFixed(4)}`); // 0.0200, 0.5000, 0.9800
+}
+```

package/docs/visualization.md

@@ -0,0 +1,259 @@
+# Reading level diagrams
+
+driftlet draws its results as level diagrams: voltages against position, on one axis, for the
+electrons in the metals, for the reactions in the solutions, and for every charged species. This
+page explains what each line means and why it's drawn that way. The first half covers the
+electronic levels, Fermi levels and redox levels, which connect directly to electrode potentials
+and other familiar quantities. The second half covers the species voltages of every charged
+species, ions included. For how to draw them, see [the kit's plotting helpers](kit.md#plotting).
+
+## Electron levels
+
+### The Fermi level
+
+An electron's electrochemical potential $`\bar\mu_{\mathrm{e}^-}`$, written as a voltage, is
+
+```math
+V_{\mathrm{e}^-} = -\bar\mu_{\mathrm{e}^-} / F
+```
+
+It's the voltage of ordinary circuits. It's what a voltmeter reads between two terminals, it
+equalises between metals wired together, it drops along a resistor by $`IR`$, and a cell's voltage
+is the difference between its terminals' $`V_{\mathrm{e}^-}`$. In a metal it's the Fermi level, in
+volts. A terminal's `V` in driftlet is this voltage, for an electron contact. In a semiconductor
+out of equilibrium, electrons and holes each have their own (the quasi-Fermi levels, below).
+
+### Redox levels
+
+A half-reaction $`\mathrm{Ox} + z\,\mathrm{e}^- \rightleftharpoons \mathrm{Red}`$ is in equilibrium when
+$`\bar\mu_{\mathrm{Ox}} + z \bar\mu_{\mathrm{e}^-} = \bar\mu_{\mathrm{Red}}`$. That fixes an electron
+level, even where no free electrons exist:
+
+```math
+V_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red}) = (\bar\mu_{\mathrm{Ox}} - \bar\mu_{\mathrm{Red}}) / (zF)
+```
+
+This is the couple's **redox level** (sometimes called its redox Fermi level). At each point
+where Ox and Red are present, it's where an electrode exchanging electrons by that couple would
+sit if it were in equilibrium with the local composition. `level(sol, half)` evaluates it at
+every node.
+
+It belongs on the same axis as the metals' Fermi levels, because then the things that matter
+are gaps you can point at:
+
+- **At an electrode**, the step from the metal's $`V_{\mathrm{e}^-}`$ to the couple's level at the
+  face is the surface overpotential. It's zero at equilibrium, and its size and sign drive the
+  reaction's kinetics. Where the metal sits higher (in volts) than the couple's level, electrons
+  leave the solution for the metal: oxidation, an anodic current.
+- **Through the solution**, the couple's level slopes wherever current flows. Part of the slope
+  is ohmic drop and part is concentration polarisation: the couple's composition changing near
+  the electrode.
+- **Several couples** in one solution each have their own level. The levels agree only if the
+  couples trade electrons fast enough to reach equilibrium with each other, which often they
+  don't. An electrode that exchanges with several couples at once settles between their levels:
+  a mixed potential.
+
+### Standard redox levels
+
+With every participant at its reference concentration, the same formula gives the couple's
+**standard redox level** $`V^\circ_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red})`$
+(`level(sol, half, { standard: true })`). The redox level sits above or below it by the activity
+term, which makes the Nernst equation local:
+
+```math
+V_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red}) = V^\circ_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red}) + \frac{RT}{zF} \ln\frac{a_{\mathrm{Ox}}}{a_{\mathrm{Red}}}
+```
+
+The standard level moves with the solution's $`\phi`$, so it slopes with the ohmic drop. The gap
+between the two lines is purely composition.
+
+### Electrode potentials
+
+The familiar potentials are gaps between these levels, measured from one more standard level:
+the hydrogen couple's, $`V^\circ_{\mathrm{e}^-}(\mathrm{SHE})`$, for 2 H⁺ + 2 e⁻ ⇌ H₂ at unit
+activities.
+
+```math
+\begin{aligned}
+E &= V_{\mathrm{e}^-}(\text{electrode}) - V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) && \quad\text{the electrode potential, "vs SHE"} \\
+E_{\mathrm{eq}} &= V_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red}) - V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) && \quad\text{the couple's equilibrium potential} \\
+E^\circ &= V^\circ_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red}) - V^\circ_{\mathrm{e}^-}(\mathrm{SHE}) && \quad\text{its standard potential} \\
+\eta &= E - E_{\mathrm{eq}} && \quad\text{the overpotential}
+\end{aligned}
+```
+
+The Nernst equation, $`E_{\mathrm{eq}} = E^\circ + (RT/zF) \ln(a_{\mathrm{Ox}}/a_{\mathrm{Red}})`$, is the
+floating form above with the SHE's level subtracted from both sides.
+
+With the data library's standard potentials, which follow the usual tables
+($`\mu^\circ_{\mathrm{H}^+} = 0`$ and $`\mu_{\mathrm{H_2}} = 0`$), the SHE's standard level in an
+aqueous solution is $`\phi`$ itself. So drawing $`\phi`$ (`traces(sol, { phi: true })`) draws the
+SHE's level, and the demos label it that way.
+
+One caution: $`V^\circ_{\mathrm{e}^-}(\mathrm{SHE})`$ is a level in the solution, and it slopes
+wherever current flows. So "vs SHE" needs a place. A reference electrode samples the level where
+its tip sits, which is why practitioners correct for iR drop, use a Luggin capillary, or add
+supporting electrolyte to flatten the bulk. In a cell polarised from wall to wall there's no flat
+bulk and no single $`E`$, but the levels are all still there to read.
+
+For example, platinum at open circuit in a ferric/ferrous solution:
+
+```js
+import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
+import { build, layer, ohmic, bath, half, level, aqueous, metal } from 'driftlet/kit';
+
+// Platinum at open circuit in 2 mM Fe³⁺ and 8 mM Fe²⁺, in 0.5 M KCl.
+const iron = half('Fe3+ + e- = Fe2+');
+const def = build({
+  library: [aqueous(['K+', 'Cl-', 'Fe3+', 'Fe2+'], { epsr: 0 }), metal('Pt')],
+  stack: [
+    ohmic({ I: 0 }, ['e-']),
+    layer('Pt', 1e-6),
+    { reactions: [{ ...iron, k0: 1e-3, alpha: 0.5 }] },
+    layer('water', 10e-6),
+    bath({ 'K+': 500, 'Cl-': 522, 'Fe3+': 2, 'Fe2+': 8 }, 'Cl-', 0),
+  ],
+  grid: { hmin: 10e-9, hmax: 0.5e-6 },
+});
+const sol = new Device(def).solve();
+const g = sol.x.length - 1; // in the bulk
+const fermi = sol.terminals.left.V; // the platinum's V_e⁻
+const she = sol.phi[g]; // V°_e⁻(SHE), with the library's data
+const E = fermi - she, Eeq = level(sol, iron)[g] - she, E0 = level(sol, iron, { standard: true })[g] - she;
+const VT = (GAS_CONSTANT * 298.15) / FARADAY;
+console.log(`E = ${E.toFixed(4)} V vs SHE, E_eq = ${Eeq.toFixed(4)} V, Nernst: ${(E0 + VT * Math.log(2 / 8)).toFixed(4)} V`);
+```
+
+A cell's voltage splits the same way along the electrons' path. It's the difference between
+the two terminals' $`V_{\mathrm{e}^-}`$: at open circuit, the gap between the two couples' levels;
+under load, less each electrode's overpotential and the solution's share. The
+[Daniell demo](https://markblundeberg.github.io/driftlet/demos/daniell.html) draws this and adds it up.
+
+### How they're drawn
+
+| line | what it is |
+|---|---|
+| thick, solid | a species voltage $`V_i`$: for electrons, the Fermi level |
+| thick, dashed | a redox level $`V_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red})`$ |
+| thin, dashed | a standard redox level $`V^\circ_{\mathrm{e}^-}(\mathrm{Ox}/\mathrm{Red})`$ |
+| thin, solid | a standard level $`V^\circ_i`$ (below) |
+| thin, dotted, grey | $`\phi`$, on request: across an insulator, or as the SHE's level (below) |
+
+Electrons are steel blue, cations (and holes) warm colours, anions cool colours, and redox levels
+blue-violet.
+
+## Species voltages for every charged species
+
+The Fermi level's definition works for any charged species i:
+
+```math
+\begin{aligned}
+V_i &= \bar\mu_i / (z_i F) && \quad\text{the species voltage} \\
+V^\circ_i &= \phi + \mu^\circ_i / (z_i F) && \quad\text{its standard level}
+\end{aligned}
+```
+
+$`V_i`$ is a way of drawing $`\bar\mu_i`$, not new physics: the equations, the docs and the API work
+in $`\bar\mu_i`$, which also covers neutral species (where $`V_i`$ is undefined). For electrons, $`V_i`$
+is the Fermi level. For an ion, it's the voltage an electrode reversible to that ion would read: a
+silver wire in equilibrium with the solution's Ag⁺ reads $`V_{\mathrm{Ag}^+}`$. The standard level
+is where $`V_i`$ would sit at the reference concentration, so for ideal species
+
+```math
+V_i - V^\circ_i = \frac{RT}{z_i F} \ln\frac{c_i}{c_{\mathrm{ref},i}}
+```
+
+and for non-ideal ones the activity replaces $`c_i/c_{\mathrm{ref},i}`$.
+
+Drawing every species this way, ions alongside electrons, shows things that are otherwise hard
+to see:
+
+- **Each species' driving force is the slope of its own line.** A species moves down its own
+  $`\bar\mu_i`$, drift and diffusion together, so on the voltage plot the current it carries flows
+  down slopes in its $`V_i`$ (cations and holes move downhill, electrons and anions uphill), and in
+  equilibrium its $`V_i`$ is flat. There's no need to split that one slope into an electric field
+  and a concentration gradient (a split that depends on how $`\phi`$ was chosen, and so means little
+  on its own).
+- **Interfaces read at a glance.** Where a species crosses a face freely, its $`V_i`$ is
+  continuous. A step in $`V_i`$ means something resists its transfer and dissipates energy there.
+  The standard levels step at faces along with $`\phi`$ (Donnan potentials, liquid junctions,
+  dipoles), but those steps are bookkeeping: they cancel from anything measured.
+- **Reactions are levels lining up.** A redox level is a weighted combination of species
+  voltages. For Fe³⁺ + e⁻ ⇌ Fe²⁺,
+  $`V_{\mathrm{e}^-}(\mathrm{Fe}^{3+}/\mathrm{Fe}^{2+}) = 3V_{\mathrm{Fe}^{3+}} - 2V_{\mathrm{Fe}^{2+}}`$.
+  For a plating couple with $`\mu_{\mathrm{M}} = 0`$, the couple's level coincides with the ion's
+  own line: $`V_{\mathrm{e}^-}(\mathrm{Ag}^+/\mathrm{Ag}) = V_{\mathrm{Ag}^+}`$.
+- **Semiconductor band diagrams are already this picture.** $`V_{\mathrm{e}^-}`$ and
+  $`V_{\mathrm{h}^+}`$ are the quasi-Fermi levels, and their standard levels are the band edges.
+  Since $`V = -E/e`$ for electrons, the conduction band sits *below* the valence band in volts.
+- **Small-signal response has the same rails.** Jamnik and Maier's exact equivalent circuit for
+  transport has a rail for each species' $`\bar\mu_i/(z_i F)`$, with resistors along it for
+  transport and chemical capacitances from it to a $`\phi`$ rail for storage (J. Jamnik and J. Maier,
+  [Phys. Chem. Chem. Phys. 3, 1668 (2001)](https://doi.org/10.1039/b100180i)). The
+  [impedance demo](https://markblundeberg.github.io/driftlet/demos/impedance.html) draws the voltages on those rails.
+
+Different species' levels sit volts apart, because their $`\mu^\circ`$ differ by hundreds of
+kJ/mol. The gap between two species' lines carries a constant fixed by convention (below), so
+moving one species' lines up or down loses nothing. `traces()` does this with `shifts`, and marks
+the shifted lines ⌇.
+
+## What's left out, and why
+
+### φ
+
+The electrostatic potential $`\phi`$ isn't drawn by default, though it's in the same volts. Inside a
+material, $`\phi`$ is a bookkeeping convention: each material's standard potentials fix where its
+$`\phi`$ sits, and any consistent choice gives the same physics (see [conventions](conventions.md)).
+Its steps between materials can't be measured, and inside a metal it has no measurable meaning at
+all. And while the electron diagram is in volts, every line on it should be an electronically
+meaningful level; $`-e\phi`$ isn't the energy of any electron.
+
+What $`\phi`$ would show is drawn anyway, more usefully. The standard levels
+$`V^\circ_i = \phi + \mu^\circ_i/(z_i F)`$ of a material move together with its $`\phi`$, so their
+bending ladder carries the same variation in space within each material. Unlike $`\phi`$, the ladder
+means something across materials too: its offsets at a face are band offsets and the like, which
+belong to the interface and can be measured.
+
+There are two places where $`\phi`$ is the right line to draw:
+
+- **In an insulator** with no mobile charged species, there are no species levels to draw. Band
+  edges can stand in, unpopulated and with no Fermi level, but when the point is that nothing
+  mobile lives there, the plain sloped $`\phi`$ line says it best: its slope is the field. It's also
+  harmless to the reader, since there's no interfacial step in $`\phi`$ in view to mistake for
+  something measurable, just a lone line connected to nothing else. The
+  [MOS demo](https://markblundeberg.github.io/driftlet/demos/mos.html) draws $`\phi`$ across its oxide this way. It draws $`\phi`$ in its
+  silicon too, deliberately anchored at an arbitrary offset from the band edges and stepping at
+  the oxide's face, to show the band edges riding on it while its position is a convention.
+- **In vacuum**, $`-e\phi`$ is exactly what it claims to be: the energy of an electron at rest there.
+
+`traces(sol, { phi: true })` draws $`\phi`$ everywhere it's defined, and `phi: ['SiO2']` only in the
+regions named. Besides the MOS demo, the demos draw it only as the SHE's standard level in water,
+which is what it equals with the library's data.
+
+### A reference
+
+Nor is anything drawn against a reference: not $`E(x)`$ vs SHE, not energies from the vacuum. The
+diagrams are reference-free. The simulation grounds one terminal at 0 V because it has to put the
+zero somewhere, but nothing depends on where: shift the whole diagram up or down and the physics
+is unchanged. So pick your own reference. Every vertical gap on the electron diagram is
+physical, so choose a level at a point (the SHE's standard level in the stirred bulk, a reference
+electrode's Fermi level, a band edge deep in a contact) and read everything else against it.
+
+That's also why "vs SHE" and "from the vacuum" need a place. The SHE's standard level and the
+vacuum level both vary in space wherever there's current or charge: the SHE's slopes with the
+ohmic drop in a solution, and the vacuum level follows the electrostatics. Plotting $`E(x)`$
+against the local SHE level would subtract a sloping line from every other line, mixing changes
+in the reference into changes in the thing measured.
+
+On the species diagram there's one technicality. A gap $`V_i - V_j`$ between two species at a point
+is free of $`\phi`$ (it cancels), so its changes in space and time are physical. Its absolute value
+carries one constant for that pair, though, fixed once by the chemical convention for the
+elements' zeros ($`\mu = 0`$ for each element in its standard state, as in every table). For
+instance, $`V_{\mathrm{Ag}^+} - V_{\mathrm{e}^-} = \mu_{\mathrm{Ag}}/F`$ at equilibrium, which is
+zero only because the convention says so. Electron levels carry no such constant, which is why
+the redox levels are drawn as electron levels: the conventions cancel out of
+$`V_{\mathrm{e}^-}(\mathrm{Ag}^+/\mathrm{Ag}) = V_{\mathrm{Ag}^+} - \mu_{\mathrm{Ag}}/F`$.
+
+These diagrams are developed at length, from what a voltmeter measures through semiconductors,
+electrolytes and electrochemical cells, in
+[Electrochemical species band diagrams](https://marklundeberg.com/esbd/).

package/llms.txt

@@ -14,9 +14,9 @@ docs/conventions.md (signs and levels) and docs/data.md (the data library).
 From a CDN, pin the version:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -44,7 +44,8 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
 - **Exports.** `driftlet`: `Device`, `units`, and the constants `FARADAY`, `GAS_CONSTANT`,
   `EPS0`, `BOLTZMANN`, `ELEMENTARY_CHARGE`, `AVOGADRO` (there's no thermal-voltage constant:
   V_T = GAS_CONSTANT·T/FARADAY). `driftlet/kit`: `build`, `layer`, `ohmic`, `bath`, `half`,
-  `level`, `SHE`, `describe`, `live`, `traces`, the data library (`aqueous`, `semiconductor`,
+  `level`, `SHE`, `describe`, `live`, `traces`, the sources (`pulse`, `square`, `triangle`, `ramp`,
+  `injector`, `recombination`), the data library (`aqueous`, `semiconductor`,
   `metal`, `IONS`, …) and the vacuum-level helpers. `driftlet/plot`: `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`).
 - **Reactions** are written as equations, `{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }`, in
   `new Device`, `build()` and `set()` alike. A coefficient is a number and a space (`2 e-`).
@@ -185,6 +186,42 @@ const dev = new Device(electrode(rest.terminals.left.V + 0.2));
 console.log(`anodic current ${dev.solve().terminals.left.current.toFixed(2)} A/m²`);
 ```
 
+## Template: a transient, with a pulse injected sideways
+
+A **port** feeds a window of nodes inside a region from the side (a point contact, an injector,
+a MOS channel's source and drain), held at a voltage or driven by a current; `injector()` writes
+one that spreads a driven current evenly. Transients run with `advance(t)`, adaptively, from the
+steady state that `solve()` finds at time 0, and `probes` read the device at points inside it.
+
+```js
+import { Device, units, FARADAY } from 'driftlet';
+import { build, layer, ohmic, semiconductor, pulse, injector, recombination } from 'driftlet/kit';
+
+// A pulse of holes injected into an n-type germanium bar under a field (Haynes–Shockley), and
+// the hole density read 1 mm downstream as it drifts past.
+const L = 4e-3, ND = units.perCm3(1e15), E = 1000; // m, mol/m³, V/m (10 V/cm)
+const width = 0.5e-6, I = (0.05 * ND * FARADAY * 50e-6) / width; // s; A/m²: 5% of n₀ over 50 µm
+const def = build({
+  T: 300,
+  library: [semiconductor('Ge')],
+  stack: [ohmic(E * L), layer('Ge', L, { name: 'bar', donors: ND }), ohmic(0)], // holes drift toward +x
+  bulkReactions: [recombination({ material: 'Ge', tau: 20e-6, majority: ND })], // the minority lifetime
+  ports: [injector({ region: 'bar', from: 0.5e-3, to: 0.55e-3, species: 'h+', I: pulse({ width, amplitude: I, rise: 1e-9 }) })],
+  grid: { hmin: units.um(10), hmax: units.um(10) },
+});
+const dev = new Device(def);
+const rest = dev.solve(); // the steady state at t = 0 (solve() doesn't advance time)
+// In a page, call advance(tNext, { budgetMs: 12, probes }) once per animation frame, carrying on
+// next frame while sol.done is false. Probes read at accepted steps; dtMax keeps them close.
+const run = dev.advance(10e-6, { dtMax: 20e-9, probes: [{ x: 1.525e-3, species: 'h+' }] });
+const seen = run.trace.probes[0], k = seen.indexOf(Math.max(...seen));
+const tArrive = run.trace.t[k] - width / 2; // from the pulse's middle
+console.log(`peak at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ${units.toPerCm3(seen[k] - rest.c['h+'][0]).toExponential(1)} cm⁻³: μ_p ≈ ${(1e-3 / (E * tArrive) * 1e4).toFixed(0)} cm²/(V·s)`); // ≈ 1950 for the 1900 put in: a spreading, decaying pulse peaks a little early
+```
+
+Transients cost more where a carrier's density spans many decades (minority holes in silicon
+ahead of the pulse) and at strong injection (Δp near n₀); budget for that, or coarsen the grid.
+
 ## Template: a live page with a slider
 
 `live()` merges slider moves made during a solve, warm-starts each solve and keeps the last
@@ -199,9 +236,9 @@ a Web Worker.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -236,13 +273,15 @@ has the long form):
 - **Standard redox level** (`{ standard: true }`), thin and dashed: every participant at reference
   concentration. The redox level sits RT/(zF) ln(a_Ox/a_Red) from it (Nernst, locally).
 - **Electrode potentials** are gaps to the SHE's standard level V°_e⁻(SHE): E = V_e⁻(electrode) −
-  V°_e⁻(SHE), E° = V°_e⁻(Ox/Red) − V°_e⁻(SHE), η = E − E_eq. With the data library's μ°, V°_e⁻(SHE)
-  in water is φ, so `phi: true` draws it. It slopes under current: "vs SHE" needs a place (say,
-  the stirred bulk).
+  V°_e⁻(SHE), E° = V°_e⁻(Ox/Red) − V°_e⁻(SHE), η = E − E_eq. With the data library's μ°,
+  V°_e⁻(SHE) in water is φ, so `phi: true` draws it. It slopes under current: "vs SHE" needs a
+  place (say, the stirred bulk).
 - **Species voltage** V_i = μ̄_i/(z_iF) (thick, solid) for every charged species: the Fermi level
   for e⁻, a quasi-Fermi level for e⁻ and h⁺ in a semiconductor, what a reversible electrode reads
-  for an ion. A species moves down slopes in its own V_i (drift and diffusion together) and is in
-  equilibrium where it's flat. A step at a face means resistance there.
+  for an ion. It's a display of μ̄_i (the physics, which also covers neutral species): each
+  species moves down its own μ̄_i, drift and diffusion together, so its current flows down slopes
+  in V_i (cations and holes move downhill, electrons and anions uphill), and it's in equilibrium
+  where V_i is flat. A step at a face means resistance there.
 - **Standard level** V°_i = φ + μ°_i/(z_iF) (thin, solid): a band edge for e⁻ and h⁺; V_i − V°_i =
   (RT/z_iF) ln(c/c_ref) for ideal species. Steps in V°_i at faces (Donnan, junctions, dipoles) are
   bookkeeping. In volts the conduction band sits below the valence band.
@@ -261,6 +300,21 @@ has the long form):
   Maier (Phys. Chem. Chem. Phys. 3, 1668 (2001)) where V_i rails explain impedance or linear
   response.
 
+## Good habits
+
+- **Draw the closed-form answer alongside the simulation**, wherever a textbook limit exists
+  (Shockley's law, a Nernst potential, a Gaussian pulse, a Warburg arc), as the demos and tests
+  do. It checks the setup: a solver's output looks authoritative even when an input is wrong, and
+  a mismatch is the cheapest way to catch it. Where the two should differ (high injection, a
+  finite pulse), say why.
+- **Stay honestly inside 1D.** driftlet models planar devices. Where the real device isn't one,
+  say so and pick the slice that still tells the true story: a MOSFET's gate stack, read as the
+  MOS capacitor its channel sits on (pinch-off along the channel is 2D); a BJT along its
+  emitter–base–collector axis; one particle of a porous battery electrode, or a thin dense film,
+  rather than the whole porous electrode (that's a P2D model).
+- **Check `sol.converged` and `sol.warnings`** on every solve, and pin the CDN version you
+  tested against.
+
 ## Common mistakes
 
 - **No alignment at a heterointerface.** `interfaces[0] (between … [Si] and … [GaAs]): an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {
@@ -21,6 +21,7 @@
   "types": "./types/index.d.ts",
   "files": [
     "src",
+    "docs",
     "types",
     "llms.txt"
   ],

package/src/constants.js

@@ -33,4 +33,15 @@ export const units = Object.freeze({
   um: (x) => x * 1e-6,
   /** cm²/s → m²/s */
   cm2PerS: (x) => x * 1e-4,
+  // Back out of SI, for display.
+  /** mol/m³ → mol/L */
+  toMolar: (x) => x * 1e-3,
+  /** mol/m³ → particles per cm³ */
+  toPerCm3: (x) => (x * AVOGADRO) / 1e6,
+  /** m → nm */
+  toNm: (x) => x * 1e9,
+  /** m → µm */
+  toUm: (x) => x * 1e6,
+  /** m²/s → cm²/s */
+  toCm2PerS: (x) => x * 1e4,
 });

package/src/index.js

@@ -146,9 +146,12 @@ export class Device {
   /**
    * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
    * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
-   * which), so an animation can call it once per frame; the step size carries over.
+   * which), so an animation can call it once per frame; the step size carries over. `probes`
+   * read a species at points inside the device after every accepted step, into `trace.probes`
+   * (one array per probe, alongside `trace.t`): what a detector at x sees.
    * @param {number} tEnd s
-   * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+   * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
+   *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {