driftlet 0.7.0 → 0.9.0

package/README.md

@@ -26,13 +26,13 @@ minor versions.
 ## Is it for your problem?
 
 The same equations go by different names in different fields. If your problem is one-dimensional
-(planar), it's probably here:
+(planar, or radial: spheres and cylinders, or any cross-section varying along x), it's probably here:
 
 | If you work on | you may call it | start from | checked against |
 |---|---|---|---|
-| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions | [first example](#a-semiconductor-junction), [pn](https://markblundeberg.github.io/driftlet/demos/pn.html) and [MOS](https://markblundeberg.github.io/driftlet/demos/mos.html) demos, [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
+| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions; thin-film transistors (gradual channel) | [first example](#a-semiconductor-junction), [pn](https://markblundeberg.github.io/driftlet/demos/pn.html) and [MOS](https://markblundeberg.github.io/driftlet/demos/mos.html) demos, [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
 | Solar cells | photogeneration, radiative and SRH recombination | [solar](https://markblundeberg.github.io/driftlet/demos/solar.html) [organic (excitons)](https://markblundeberg.github.io/driftlet/demos/organic.html) and [perovskite (mobile ions)](https://markblundeberg.github.io/driftlet/demos/perovskite.html) demos, [`ionmonger`](test/ionmonger.test.js), [`reactions`](test/reactions.test.js) and [`generation`](test/generation.test.js) tests: generation is a reaction from a photon reservoir (uniform, or Beer–Lambert with `photogeneration()`), SRH as a rate law, in the bulk and at faces | `J_sc = qG(L_n + L_p + W)`; J_sc under Beer–Lambert against collection theory; Shockley J–V in the dark |
-| Electrochemistry | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions | [second example](#an-electrochemical-cell), [cyclic voltammetry](https://markblundeberg.github.io/driftlet/demos/redox.html), [Daniell cell](https://markblundeberg.github.io/driftlet/demos/daniell.html), [saturation](https://markblundeberg.github.io/driftlet/demos/saturation.html), [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js), [`junction`](test/junction.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg; junction potentials against Henderson, Planck, JPCalc and LJPcalc |
+| Electrochemistry, corrosion | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions, mixed potentials, electrodes under a film | [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), [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) and [liquid-junction](https://markblundeberg.github.io/driftlet/demos/junction.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js), [`junction`](test/junction.test.js), [`ports`](test/ports.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg; junction potentials against Henderson, Planck, JPCalc and LJPcalc; Wagner–Traud |
 | 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 | [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 |
@@ -55,7 +55,7 @@ import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG str
 ```
 
 Or straight from a CDN in a page, pinned to a version:
-`https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.9.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).
 
@@ -204,7 +204,9 @@ current. Supported physics:
 
 ## What it doesn't do
 
-- **More than one dimension.** Planar 1D only, so no porous-electrode (P2D) models. For 2D/3D,
+- **More than one dimension.** 1D only: planar, or a cross-section varying along x (spheres,
+  cylinders, a thinning film), so no porous electrodes with diffusion inside their particles
+  (P2D models). For 2D/3D,
   see [ChargeTransport.jl](https://github.com/WIAS-PDELib/ChargeTransport.jl), TCAD tools or
   COMSOL.
 - **Cross-diffusion.** Each species moves down its own μ̄ with its own D (the statistics can be
@@ -259,6 +261,10 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | Advection and eddy mixing | exact convection–diffusion profile; `D + D_mix`; junction EMF unchanged by mixing | 1e-12; 1e-12; 1e-5 |
 | Metal regions | ohmic; Schottky face and MOS gate equal their contact forms; Ag \| AgNO₃ \| Ag with metal electrodes; bipolar electrode at V/2 | 1e-12; 1e-9; 1e-9; 1e-9 |
 | Internal ports | transmission line σV tanh(L/λ)/λ (O(h²)); held level; MOS low-frequency C–V with a grounded channel | 1e-4; 1e-9; 2e-3 |
+| Cross-sections (spherical, cylindrical, any A(x)) | steady diffusion to a sphere and a cylinder (exact on any grid); Cottrell with the spherical term; uptake by a sphere filling from its surface; Debye–Hückel around a charged sphere, potential and charge | 1e-10; 3e-4; 2e-4; 1e-3, 3e-4 |
+| A capacitance through a port | a thin-film transistor against the charge-sheet model (below threshold to saturation, second order); de Levie impedance; gate impedance against dQ/dV | 5e-4; 1e-3; 1e-6 |
+| Electrode surfaces (coverage) | Langmuir isotherm against potential; the charge to fill a surface; the active–passive curve, blocking exactly (1 − θ) | 1e-9; 1e-3; 1e-9 |
+| Electrodes spread through a port | transmission line with the reaction's linear kinetics as the conductance (O(h²)), rates along it; Wagner–Traud mixed potential of two Butler–Volmer couples, floating | 1e-4, 2e-3; 1e-6 V |
 | Impedance | Macdonald blocking-electrode spectrum, 100 Hz–1 GHz; finite-length Warburg (Ag \| AgNO₃ \| Ag); DC limit = differential resistance | 3e-4; 3e-5; 1e-6 |
 | Conservation | per step, and against time-integrated contact fluxes | 1e-11 relative |
 | Strictly neutral limit (ε = 0) | Planck EMF; polarization with no overlimiting; Donnan at neutral faces | 1e-5; 1e-4; 1e-9 |

package/docs/device.md

@@ -24,6 +24,7 @@ too (`FARADAY`, `GAS_CONSTANT`, `EPS0`, …).
 | `contacts` | `{ left, right }` |
 | `ports` | internal ports: outside phases exchanging with a window of nodes |
 | `grid` | default spacing for every region |
+| `geometry` | the cross-section $`A(x)`$: planar (default), spherical or cylindrical shells, or a profile (see [geometry](#geometry)) |
 
 ## Species
 
@@ -445,7 +446,16 @@ contact: held at a voltage, behind a resistance, or driven by a current (a refer
 is a port at `I: 0`). Each solution reports `ports[k]`, with `{ name, V, flux, current }`: what
 the port brings into the device.
 
-A held (`'equilibrium'`) level leaves the device's two end nodes to their contacts.
+A held (`'equilibrium'`) level leaves the device's two end nodes to their contacts. A port that
+exchanges only neutral species carries no current, so its voltage means nothing: give it no drive.
+
+An exchange link's source is linear in $`\mu_{out} - \mu`$, so it grows without bound as the
+species runs out ($`\ln c`$). A supply limited by diffusion through a film above the window, such as O₂
+reaching a thin layer of water from the air, is linear in $`c`$ instead: $`k(c_{sat} - c)`$. For that,
+use a [bulk reaction](#bulk-reactions) with the outside phase as a fixed participant, e.g.
+`{ equation: 'Air = O2', fixed: { Air: muSat }, kf: { water: profile } }`. Its rate is
+$`k_f (1 - c/c_{sat})`$, and a profile gives $`k_f`$ its spatial variation (a film of thickness $`h(x)`$:
+$`D c_{sat}/h^2`$).
 
 A port driven by a current (`I`, or a waveform) floats to whatever voltage delivers it: with a
 conductance `G` per volume over a window of width $`w`$, it sits about $`I/(G w)`$ above the
@@ -467,6 +477,128 @@ steady state can be computed there. A port holding the electrons beside the oxid
 channel's potential anchors it, as source and drain would, and the device then shows the
 low-frequency C–V.
 
+### Electrodes spread through a window
+
+A port can also hold an electrode: a metal whose carrier sits at the port's level, reacting all
+through the window rather than at one face. That's the floor under a thin film of electrolyte, the
+walls of a crevice or a pit, or the matrix of a porous electrode, wherever the metal conducts well
+enough to be one level. Give the port its `reactions` (Butler–Volmer, as at a face), the carrier as
+its `terminal` (the species need be in no material), and the electrode's `area` per volume of the
+window:
+
+```js nocheck
+ports: [{
+  name: 'iron', region: 'film', terminal: 'e-', V: 0,
+  area: 1 / 100e-6,           // m²/m³: a film 100 µm thick on the metal; or a profile against x
+  reactions: [
+    { equation: 'Fe2+ + 2 e- = Fe(s)', fixed: { 'Fe(s)': 0 }, k0: 5e-6, alpha: 0.5 },
+    { equation: 'O2 + 2 H2O + 4 e- = 4 OH-', fixed: { H2O: -237.13e3 }, k0: 3e-9, alpha: 0.125 },
+  ],
+}]
+```
+
+Each node's rate per area is the face's law, with the region's species at that node and the
+carrier at activity 1 and level $`V`$. Times the area per volume, it makes and consumes the
+region's species there, and the electrons it takes or gives are the port's current. The port is
+a terminal like any other. Held at a voltage, it's a potentiostat. At `I: 0` (or with nothing
+else to carry current), the reactions settle at the mixed potential, the corrosion potential where
+anodic and cathodic currents cancel over the window, while each node can be a net anode or a net
+cathode. A floating one starts there, for the start's composition. Each solution reports the
+window's nodes and every reaction's rate at each: `ports[k].x[j]` (m) and `ports[k].area[j]`
+(m²/m³) for the window's node j, and `ports[k].rates[q][j]` for reaction q there (mol/(m²·s) of
+electrode, forward), so reaction first, then node. They're typed arrays (`Float64Array`), so
+`Array.from` them before mapping to anything but numbers. Per volume of the window it's
+`rates[q][j] * area[j]`, and per area of a film's floor (thickness h, `area` 1/h) the rate itself.
+
+Validated against the transmission line (linear kinetics along a bar, test/ports.test.js) and the
+Wagner–Traud mixed potential of two Butler–Volmer couples. In 1D, a film on a metal is a slice
+along the metal: the film's thickness enters through `area`, and through a bulk reaction for
+anything that reaches the film from above (O₂ from the air, see the exchange link above). Where
+the film's thickness varies, give the device its [cross-section](#geometry) too, so that ions
+travelling along the film squeeze through where it thins: for a drop on a metal, seen from its
+centre, $`A = 2\pi r\,h(r)`$ with `area` $`1/h(r)`$.
+
+The region must be strictly neutral ($`\varepsilon = 0`$), as in porous-electrode theory: each spot's
+double layer, the metal's countercharge, is below the grid, so the reactions can't leave the
+solution charged.
+
+### An electrode's surface: adsorbates and passive films
+
+An electrode port can carry species on its surface, sharing its sites: an adsorbed intermediate,
+or a passive film taken as a coverage. Each has a coverage $`\theta`$ at every node of the window,
+Langmuir statistics, $`\mu = \mu^\circ + RT\ln(\theta/\theta_0)`$ with $`\theta_0 = 1 - \sum\theta`$ the
+bare fraction, and `capacity` $`\Gamma`$, mol of sites per m² of electrode. Reactions name them like
+species, and a reaction with `bare: true` runs only on bare metal: its rate is multiplied by
+$`\theta_0`$, both ways, so equilibrium stays exact. Written for adsorption itself, that's Langmuir
+kinetics (on at a rate ∝ $`\theta_0`$, off ∝ $`\theta`$).
+
+```js nocheck
+ports: [{
+  name: 'iron', region: 'film', terminal: 'e-', V: 0, area: 1 / 100e-6,
+  surface: { 'Fe(OH)2': { mu0: -490e3, capacity: 2e-5, theta0: 1e-6 } }, // theta0: the start
+  reactions: [
+    { equation: 'Fe2+ + 2 e- = Fe(s)', fixed: { 'Fe(s)': 0 }, k0: 5e-6, alpha: 0.5, bare: true },  // dissolves where bare
+    { equation: 'Fe(s) + 2 OH- = Fe(OH)2 + 2 e-', fixed: { 'Fe(s)': 0 }, k0: 1e-6, alpha: 0.5, bare: true }, // the film forms
+    { equation: 'O2 + 2 H2O + 4 e- = 4 OH-', fixed: { H2O: -237.13e3 }, k0: 3e-9, alpha: 0.125 }, // on film or not
+  ],
+}]
+```
+
+A film forms where the potential and the pH favour it, through its own thermodynamics, and blocks
+what needs bare metal: the dissolution current climbs with potential, peaks, and falls as the film
+covers the metal, the active–passive curve. Each node's surface stores
+$`\Gamma\,d\theta/dt`$ per area of electrode, so filling it passes a current, and a solution reports
+`ports[k].coverage[name][j]`. It's a monolayer picture: a real passive oxide is nanometres thick,
+grows, and breaks down under chloride, none of which a coverage has.
+
+Two cautions. Keep a film's stability within reason: blocking the bare fraction to 1e-3–1e-6 is
+already a passive metal, and far below that ($`\theta_0 \lesssim 10^{-10}`$) the coverage's η barely
+affects anything, so Newton struggles with it. And an electrode port has no double-layer
+capacitance (its solution is strictly neutral), so its potential follows its kinetics instantly.
+With a passivating film, current against potential has the active–passive peak, and when the
+last active patch covers over, the potential where no current flows can vanish from the active
+branch and must jump to the passive one. A real electrode makes that jump quickly but
+continuously, through its double layer; here it's a discontinuity, and a transient stops there.
+Give the port a [capacitance](#a-capacitance-through-a-window-a-gate-along-a-channel-a-double-layer) and the jump becomes a quick, continuous swing.
+
+Validated in test/coverage.test.js: the Langmuir isotherm against the electrode's potential (to
+1e-9), the charge to fill the surface, $`F\,\Gamma\,\Delta\theta`$ per area of electrode, and the
+active–passive curve with blocking exactly $`(1-\theta)`$ times Butler–Volmer.
+
+### A capacitance through a window: a gate along a channel, a double layer
+
+A port can hold charge across a capacitance spread through its window: per area of electrode,
+$`\sigma = C\,(V - \mathtt{zeroCharge} - \phi)`$ on the port's side (C in F/m²), with `area` per volume
+as for reactions, and the window holds the opposite. Each node's charge balance gains $`a\sigma`$:
+Gauss's law averaged across the section,
+$`-\partial_x(\varepsilon\,\partial_x\phi) = \rho + a\sigma`$, and at $`\varepsilon = 0`$ neutrality
+$`\rho + a\sigma = 0`$, the mobile species rearranging to supply it (counter-ions in, co-ions out).
+The port passes the charging current, $`d(\int a\sigma\,dV)/dt`$, none in a steady state. Solutions
+report `ports[k].sigma` at each node of the window and the total `ports[k].charge`.
+
+```js nocheck
+// a thin-film transistor: the gate along a 10 nm channel through 1 mF/m² (35 nm of SiO₂)
+ports: [{ name: 'gate', region: 'channel', V: 1.5, area: 1 / 10e-9, capacitance: { C: 1e-3, zeroCharge: 0.3 } }]
+// a porous electrode's double layer, alongside its reactions
+ports: [{ name: 'iron', region: 'film', terminal: 'e-', V: 0, area: 1e4, capacitance: { C: 0.2, zeroCharge: -0.4 }, reactions: [/* … */] }]
+```
+
+That's the gradual-channel approximation of a field-effect transistor, exact for a thin film
+with no body (a TFT, an organic or oxide transistor) while the channel is long against the gate
+dielectric, and failing where it pinches off (where the 2D field takes over). It's also the
+Bernards model of an organic electrochemical transistor (a volumetric capacitance), cable theory
+for an axon's membrane, and a porous electrode's double layer, which lets an electrode port's
+potential move continuously: without it, a passivating film that covers the last active patch
+forces a jump (see above). The gate's flat level pins the channel's standard level through C, as
+a blocked spectator's flat level does in an electrolyte, and the current saturates as the
+carriers run out at the drain, in both.
+
+Validated in test/capacitance.test.js: a thin-film transistor's current against the
+charge-sheet model, $`I/W = (\mu/L)[(\sigma_s^2 - \sigma_d^2)/(2C) + V_T(\sigma_s - \sigma_d)]`$, from
+below threshold through saturation (second order in the grid); a porous electrode's de Levie
+impedance $`\sqrt{r/y}\coth(L\sqrt{ry})`$, the double layer in series with the ions' chemical
+capacitance; and the gate's low-frequency impedance against $`dQ/dV_G`$ from steady states.
+
 ## Terminals
 
 The two contacts and every port are the device's terminals, named `left`, `right` and by each
@@ -521,6 +653,34 @@ cells exceeds the limiting current by 1.4% at 0.5 V, while `{ hmin: 10e-9, hmax:
 within 0.1% with as many nodes. Where a species carrying the current is steep across a region's
 end cells in this way, the solution's `warnings` say so, with a rough estimate of the excess.
 
+## Geometry
+
+A device is planar unless it says otherwise: a slab whose cross-section $`A`$ is 1 m², so every
+current, flux, amount and charge reads per m². With `geometry`, the cross-section varies along x,
+and the conservation laws hold for totals through it: a box holds $`\int A\,dx`$, and what crosses
+a face is the flux there times $`A`$ there.
+
+```js nocheck
+geometry: { type: 'spherical', r0: 10e-6 },   // shells, r = r0 + x: a microelectrode of radius r0
+geometry: { type: 'cylindrical', r0: 0 },     // a wire or fibre from its axis (per metre of length)
+geometry: { area: { x: [0, 1e-3], values: [3e-6, 1e-7] } }, // A (m²) against x: a film thinning, a pit
+```
+
+This is how radial problems become 1D, with the right $`1/r^2`$ (or $`1/r`$) in every divergence and in
+Gauss's law, without writing them out. The finite volumes integrate over shells, so conservation
+is exact as in a slab. Each segment's transport is weighted by its length over $`\int dx/A`$, which
+makes steady diffusion between two nodes exact for any $`A(x)`$ (the $`1/r`$ and $`\ln r`$ profiles
+on any grid). Where $`A`$ vanishes at an end (a sphere's centre, `r0: 0`), the segment takes $`A`$ at
+its middle, and nothing passes the end. Only an end may have $`A = 0`$. Flow (`velocity`) is for
+planar devices.
+
+With a cross-section, the solution's currents, contact and port fluxes, terminal currents and
+`charge` are totals (A, mol/s; per metre for cylinders), and so are `I` drives. Face laws,
+rates, `interfaces[f].N` and `D`, and concentrations stay per area or per volume. Validated against
+steady diffusion to a sphere and a cylinder (exact), Cottrell's transient with the spherical term,
+uptake by a sphere filling from its surface, and Debye–Hückel screening around a charged sphere
+(test/geometry.test.js).
+
 ## Using a device
 
 ```js nocheck
@@ -610,14 +770,14 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `phi` | bookkeeping $`\phi`$, V (`NaN` where undefined) |
 | `c[name]`, `mu[name]`, `muStd[name]` | concentration, $`\bar\mu`$, standard level $`\mu^\circ + zF\phi`$ (`NaN` where absent) |
 | `V[name]`, `Vstd[name]` | species voltage $`\bar\mu/(zF)`$ and standard level as a voltage (charged species) |
-| `current`, `terminalVoltage` | current toward +x through the device (A/m²) and $`V_{\mathrm{right}} - V_{\mathrm{left}}`$ |
+| `current`, `terminalVoltage` | current toward +x through the device (A/m², or A through a [cross-section](#geometry)) and $`V_{\mathrm{right}} - V_{\mathrm{left}}`$ |
 | `terminals[name]` | `{ V, current }` for each terminal (contacts and ports), current into the device |
 | `contacts.left/right` | `{ V, flux: {name}, D, current }` at each contact |
 | `gates.left/right` | charge on a gate or Stern plate, where the contact is capacitive |
 | `ports[k]` | `{ name, V, flux: {name}, current }`: what each internal port brings into the device |
 | `interfaces[f]` | `{ left, right, dipole, sheetCharge, D, N: {name}, rates }`: the names of the regions the face joins, what crosses it by its links, and each face reaction's rate (mol/(m²·s)) |
 | `bulkReactions[k]` | `{ rate, regions, total }`: each bulk reaction's forward rate at every node (mol/(m³·s), `NaN` where it doesn't run), 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² |
+| `charge` | total charge in the device, C/m² (C through a cross-section) |
 | `conservation` | per species stretch: amount, reference, intake through contacts, drift |
 | `warnings` | e.g. unresolved double layers, conventions a statistics model relies on, and for a failed solve, where the system is nearly singular |
 | `converged`, `iterations`, `steps`, `substeps`, `history`, `time` | solver bookkeeping |

package/docs/kit.md

@@ -64,7 +64,7 @@ console.log(`I = ${sol.current.toFixed(1)} A/m²`);
   (`combine()` does the merging on its own). A species or material given twice must be given
   identically.
 - Nested lists in the stack are flattened, so a helper can return several items.
-- Reactions pass through as written (see below).
+- Reactions pass through as written (see below), and so do `T`, `grid`, `ports` and `geometry`.
 
 ## Reactions and half-reactions
 
@@ -82,7 +82,7 @@ $`\mu_{\mathrm{H_2}} = 0`$, so its standard level is $`\phi + \mu^\circ_{\mathrm
 
 ```js
 import { Device } from 'driftlet';
-import { build, layer, ohmic, half, level } from 'driftlet/kit';
+import { build, layer, ohmic, half, level, polarization } from 'driftlet/kit';
 
 const silver = half('Ag+ + e- = Ag(s)', { 'Ag(s)': 0 });
 const stern = { phi: { type: 'capacitive', C: 0.2 }, zeroCharge: 0.1 }; // an assumed pzc
@@ -108,11 +108,35 @@ const def = build({
   grid: { hmin: 0.1e-9, hmax: 100e-9, ratio: 1.15 },
 });
 console.log(JSON.stringify(def.interfaces[0].reactions[0])); // { left: { e-: -1, Ag(s): 1 }, right: { Ag+: -1 }, … }
-const sol = new Device(def).solve();
+const dev = new Device(def), sol = dev.solve();
 const redox = level(sol, silver); // V_Ag⁺(x) in the solution
 console.log(`redox level at mid-cell: ${redox[sol.x.length >> 1].toFixed(4)} V`);
+// The left electrode's polarization curve, 0.2 V either side of its own level (see below).
+const metalSide = sol.V['e-'][0];
+const curve = polarization(dev, sol, { face: 0 }, Array.from({ length: 81 }, (_, j) => metalSide - 0.2 + j * 0.005));
+console.log(curve.reactions[0].level, curve.current[40]); // the couple's level here, and the current at the metal's own
 ```
 
+### Polarization curves: an Evans diagram
+
+`polarization(device, sol, where, V)` evaluates every electrode reaction at one spot with the
+solution beside it held as `sol` has it and the metal's level set to each `V` (an electron
+voltage, the terminals' convention). It works at a face (`{ face: f }`, the face's metal side) or
+at a spot of an [electrode port](device.md#electrodes-spread-through-a-window)
+(`{ port: name, x }`, with its surface's coverages there held too). Each reaction comes back with its rate (mol/(m²·s), forward), its partial
+current (A/m², anodic positive: into the solution) and its `level`, where the rate vanishes (the
+couple's redox level there, as `level()` gives it). The net current is their sum. Plotting
+log|current| against V gives the Evans diagram. The net crosses zero at the spot's open-circuit
+potential, between the couples' levels, and the metal's actual level is where the solve put it.
+The law is the solver's own, so at that level the rates are the solution's. Against SHE, subtract
+the SHE level (`sol.phi` with the usual tables' ions).
+
+The example above ends with the left electrode's curve.
+
+Concentrations are held, so these are the curves of that instant (for a mixed potential, the
+kinetic picture). Away from the actual level the composition beside the electrode would change,
+which is the transport the full solve accounts for.
+
 ## Sources
 
 Helpers that write sources as plain data:

package/docs/numerics.md

@@ -117,6 +117,22 @@ Grids grade geometrically from `hmin` at each region end up to `hmax`. They're n
 automatically, to avoid performance surprises. Instead, solutions warn when a double layer the
 model is meant to resolve is coarser than the local Debye length.
 
+### A cross-section
+
+With a [`geometry`](device.md#geometry), the device has a cross-section $`A(x)`$ (spherical
+shells $`4\pi r^2`$, cylindrical $`2\pi r`$ with $`r = r_0 + x`$, or a profile), and every balance
+is for totals through it:
+$`\partial_t (A c_i) + \partial_x (A N_i) = A \sum_r \nu_{ir} r_r`$, and Gauss's law
+$`-\partial_x (A\varepsilon\,\partial_x\phi) = A\rho`$. The box method carries this without writing out any
+$`1/r`$ terms: a box's volume becomes $`\int A\,dx`$ over it (exactly, for each shape), and what a
+segment, a face or a contact passes is multiplied by the area it passes through. A segment's
+$`1/h`$ becomes $`1/\int dx/A`$ over it, its resistance per unit conductivity, which is the exact
+weighting for steady diffusion (a constant total flux $`AN`$, so $`\Delta c = AN\int dx/A\,/D`$).
+Scharfetter–Gummel keeps its form with that weighting, and so does the displacement. Where $`A`$
+vanishes at an end (a sphere's centre), $`\int dx/A`$ diverges, so that segment takes $`A`$ at its
+middle. A flux node's unknowns stay per area, entering each side's balance times the face's
+area. A planar device has $`A = 1`$ and every factor is exactly 1, so it's unchanged to the last bit.
+
 ### What lives where
 
 | Place | Holds |

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.7.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -50,7 +50,7 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   V_T = GAS_CONSTANT·T/FARADAY). `driftlet/kit`: `build`, `layer`, `ohmic`, `bath`, `half`,
   `level`, `SHE`, `describe`, `live`, `traces`, the sources (`pulse`, `square`, `triangle`, `ramp`,
   `injector`, `recombination`, `photogeneration`), the data library (`aqueous`, `semiconductor`,
-  `metal`, `IONS`, …), `check` (a solution's checks), `henderson` and `planck` (liquid-junction potentials), `recorder` (a transient's trace and frames across calls), the curated
+  `metal`, `IONS`, …), `check` (a solution's checks), `polarization` (an electrode's reactions at hypothetical metal levels, with the solution held: an Evans diagram), `henderson` and `planck` (liquid-junction potentials), `recorder` (a transient's trace and frames across calls), the curated
   `perovskiteCell` with IonMonger's `PEROVSKITE_SCANS` and `hysteresis`, and the vacuum-level helpers. `driftlet/plot` (a quick look; `traces()` is the data for your own charts): `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`), `themeColor`.
 - **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-`).
@@ -319,9 +319,9 @@ solve), as long as it settles rather than ping-pongs.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.7.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.9.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -405,11 +405,16 @@ has the long form):
   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,
+- **Stay honestly inside 1D.** driftlet models devices along one coordinate: planar, or with a
+  cross-section A(x) (`geometry`: spherical or cylindrical shells, or a profile), in which case
+  currents and fluxes are totals through it. 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).
+  rather than the whole porous electrode with diffusion inside its particles (that's a P2D model).
+  A metal that reacts all along a film of electrolyte (corroding iron under a drop, a crevice's
+  walls, a well-conducting porous matrix) is a port with `reactions` and an `area` per volume:
+  an electrode spread through a window, not a face at each end.
 - **Check `sol.converged` and `sol.warnings`** on every solve, and pin the CDN version you
   tested against.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/checks.js

@@ -65,7 +65,7 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
   // The rest checks a solution, which an unconverged state isn't.
   if (sol.converged) {
     const ledger = steady ? balance(device, sol) : null;
-    items.push(ledger ?? conservation(sol));
+    items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
   }
 
@@ -164,26 +164,27 @@ function balance(device, sol) {
 // carrier, σRT/(z²F²L)), and by its bulk reactions, their one-way rates. In equilibrium the net
 // flows are round-off of these.
 function naturalScales(device, sol) {
-  const { model, solver } = device, { species } = model;
-  const box = (g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? sol.x[g] - sol.x[g - 1] : 0) + (g + 1 < sol.x.length && sol.region[g + 1] === sol.region[g] ? sol.x[g + 1] - sol.x[g] : 0)) / 2;
+  const { model, solver } = device, { species, grid } = model;
+  // (totals through the cross-section, as the ledgers are: its largest in each region)
+  const area = model.regions.map((_, r) => Math.max(...grid.area.subarray(grid.regionStart[r], grid.regionEnd[r] + 1)));
   return species.map((sp, i) => {
     let S = 0;
     model.regions.forEach((reg, r) => {
       const mat = model.materials[reg.material], L = reg.length;
       if (mat.conductor) {
-        if (mat.conductor.i === i) S = Math.max(S, (mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        if (mat.conductor.i === i) S = Math.max(S, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
         return;
       }
       if (!mat.present[i] || !(mat.D[i] > 0)) return;
       let cmax = 0;
       for (let g = 0; g < sol.x.length; g++) if (sol.region[g] === r && Number.isFinite(sol.c[sp.name][g])) cmax = Math.max(cmax, sol.c[sp.name][g]);
-      S = Math.max(S, (mat.D[i] * cmax) / L);
+      S = Math.max(S, (area[r] * mat.D[i] * cmax) / L);
     });
     solver.rxs.forEach((rx) => {
       const p = rx.sp.indexOf(i);
       if (p < 0) return;
       let gross = 0;
-      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += box(g) * solver.bulkOneWay(rx, g);
+      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += grid.vol[g] * solver.bulkOneWay(rx, g);
       S = Math.max(S, Math.abs(rx.nu[p]) * gross);
     });
     return S;
@@ -191,12 +192,12 @@ function naturalScales(device, sol) {
 }
 
 // Closed, unreacting stretches keep their amounts in a transient.
-function conservation(sol) {
+function conservation(sol, area = 1) {
   const closed = sol.conservation.filter((st) => !st.connected && !st.reactive);
   if (closed.length === 0) return { name: 'conservation', ok: true, summary: 'nothing closed to conserve (every species reaches a terminal or reacts)' };
   // Relative to the amount, but a drift below 1e-20 mol/m² (1e-15 C/m²) is nothing: a floating
-  // metal's excess electrons are themselves ~0.
-  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 ? 0 : Math.abs(st.drift))));
+  // metal's excess electrons are themselves ~0. (Amounts are totals through the cross-section.)
+  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 * area ? 0 : Math.abs(st.drift))));
   return {
     name: 'conservation',
     ok: worst < 1e-8,

package/src/describe.js

@@ -125,6 +125,11 @@ export function describe(def) {
   const warnings = unitWarnings(def);
   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;
+  if (geo.type !== 'planar') {
+    const shape = geo.type === 'profile' ? `a cross-section from ${num(Math.min(...grid.area))} to ${num(Math.max(...grid.area))} m²` : `${geo.type} shells, r = ${si(geo.r0, 'm')} + x${geo.type === 'cylindrical' ? ' (per metre of length)' : ''}`;
+    lines.push(`geometry: ${shape}; currents and fluxes are totals through it (A, mol/s)`);
+  }
   lines.push(`species: ${species.map((sp) => `${sp.name} (z = ${sp.z > 0 ? '+' : ''}${sp.z})`).join(', ')}`);
 
   lines.push('regions:');
@@ -206,7 +211,15 @@ export function describe(def) {
     const term = ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
     lines.push(`  ${side}: ${drive(cdef)}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
   }
-  (def.ports ?? []).forEach((p, k) => lines.push(`  port ${model.ports[k].name}: ${drive(p)}, in ${regions[model.ports[k].region].name}`));
+  (def.ports ?? []).forEach((p, k) => {
+    const port = model.ports[k];
+    lines.push(`  port ${port.name}: ${drive(p)}, in ${regions[port.region].name}`);
+    // an electrode spread through the window
+    if (port.reactions.length) lines.push(`    an electrode (its ${species[port.terminal].name} at the port's level), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} of it per m³, reacting:`);
+    for (const rx of p.reactions ?? []) lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${rx.alpha}${rx.bare ? ', on bare metal' : ''}`);
+    if (port.capacitance) lines.push(`    a capacitance of ${num(port.capacitance.C)} F/m² through the window (zero charge at ${num(port.capacitance.zeroCharge)} V), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} per m³`);
+    if (port.surface.length) lines.push(`    its surface: ${port.surface.map((sp) => sp.name).join(', ')} on ${num(port.surface[0].capacity)} mol/m² of sites (Langmuir)`);
+  });
   if ((def.bulkReactions ?? []).length) {
     lines.push('bulk reactions:');
     for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)}${rx.srh ? ' (SRH)' : ''} in ${Object.keys(rx.kf ?? rx.srh ?? {}).join(', ')}`);