driftlet 0.7.0 → 0.8.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 |
 | 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.8.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,8 @@ 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 |
+| 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,44 @@ 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` and `ports[k].rates`
+(mol/(m²·s) of electrode, forward), with `ports[k].area`.
+
+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)`$.
+
 ## Terminals
 
 The two contacts and every port are the device's terminals, named `left`, `right` and by each
@@ -521,6 +569,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 +686,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

@@ -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 }`). 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.8.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.8.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.8.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.8.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.8.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.8.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.8.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,13 @@ 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}`);
+  });
   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(', ')}`);

package/src/device.js

@@ -6,7 +6,7 @@
 // defaults for physically meaningful choices: interface alignments, reference concentrations
 // and standard potentials must all be given.
 
-import { buildGrid } from './grid.js';
+import { buildGrid, applyGeometry } from './grid.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 import { normalizeStatistics } from './statistics.js';
 import { DeviceError } from './errors.js';
@@ -105,7 +105,7 @@ function nonNegative(v, path) {
  */
 export function normalizeDevice(def) {
   need(isObject(def), 'device definition must be an object');
-  fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid']);
+  fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid', 'geometry']);
 
   const T = def.T === undefined ? 298.15 : positive(def.T, 'T');
   const RT = GAS_CONSTANT * T;
@@ -171,8 +171,14 @@ export function normalizeDevice(def) {
     materialIndex.set(mname, materials.length);
     materials.push(m);
   }
+  // (an electrode's carrier can live outside the device: a reacting port's terminal species)
+  const outside = (sp) => (def.ports ?? []).some((p) => p?.terminal === sp.name && Array.isArray(p.reactions) && p.reactions.length > 0);
   species.forEach((sp, i) => {
-    need(materials.some((m) => m.present[i]), `species '${sp.name}' is not present in any material`);
+    const reacting = (def.ports ?? []).some((p) => Array.isArray(p?.reactions) && p.reactions.length > 0);
+    need(
+      materials.some((m) => m.present[i]) || outside(sp),
+      `species '${sp.name}' is not present in any material` + (reacting ? " (an electrode's carrier can instead be a reacting port's terminal)" : ''),
+    );
   });
 
   // --- regions
@@ -280,7 +286,7 @@ export function normalizeDevice(def) {
 
   // --- internal ports (outside phases attached over windows of interior nodes)
   need(def.ports === undefined || Array.isArray(def.ports), 'ports must be an array');
-  const ports = (def.ports ?? []).map((pdef, k) => normalizePort(pdef, `ports[${k}]`, regions, materials, species, speciesIndex));
+  const ports = (def.ports ?? []).map((pdef, k) => normalizePort(pdef, `ports[${k}]`, regions, materials, species, speciesIndex, RT));
 
   // Every electrostatically coupled cluster of regions needs an anchor, or its φ (and every
   // charged level with it) floats: shifting φ by s and each η_i by z_i s changes nothing.
@@ -322,6 +328,17 @@ export function normalizeDevice(def) {
   } catch (err) {
     throw new DeviceError(`grid: ${err.message}`);
   }
+  const geometry = normalizeGeometry(def.geometry);
+  if (geometry.type !== 'planar') {
+    regions.forEach((reg, r) => need(reg.velocity === 0, `regions[${r}].velocity: flow is for a planar device (a uniform velocity through a varying cross-section wouldn't conserve the liquid)`));
+  }
+  applyGeometry(grid, geometry);
+  // (zero only at an end, as at a sphere's centre: nothing passes there)
+  const inside = (x) => x > 0 && x < grid.length;
+  need(
+    grid.area.every((a, g) => a > 0 || g === 0 || g === grid.nNodes - 1) && (geometry.type !== 'profile' || geometry.values.every((a, k) => a > 0 || !inside(geometry.x[k]))),
+    'geometry: the cross-section vanishes inside the device; only an end may have A = 0',
+  );
 
   // Port windows: the nodes of the port's region within [from, to] of its left end.
   ports.forEach((port, k) => {
@@ -336,7 +353,7 @@ export function normalizeDevice(def) {
   });
 
   return {
-    T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports,
+    T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports, geometry,
   };
 }
 
@@ -555,6 +572,7 @@ export function normalizeDrives(def, model) {
   for (const [k, side] of [[0, 'left'], [1, 'right']]) {
     need(model.contacts[side].passes || drives[k].kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
   }
+  model.ports.forEach((port, k) => need(port.passes || drives[2 + k].kind === 'V', `ports[${k}].I: this port passes no current (it exchanges only neutral species), so give it no drive`));
   need(drives.some((d) => d.kind === 'V'), "every terminal is driven by a current, so the device's overall level floats: hold at least one at a voltage V");
   return drives;
 }
@@ -601,15 +619,37 @@ export function nextBreakpoint(src, t) {
   return Infinity;
 }
 
+// The device's cross-section A(x): planar (the default, A = 1 m², so currents read as densities),
+// spherical or cylindrical about a centre r0 to the left of x = 0 (r = r0 + x), or a profile
+// { x, values } of A in m². Every flux, current and amount is then a total through A.
+function normalizeGeometry(g) {
+  if (g === undefined || g === 'planar') return { type: 'planar' };
+  if (g === 'spherical' || g === 'cylindrical') g = { type: g };
+  need(isObject(g), "geometry must be 'planar', 'spherical', 'cylindrical', { type, r0 } or { area: { x, values } }");
+  if (g.area !== undefined) {
+    fields(g, 'geometry', ['area']);
+    const p = profile(g.area, 'geometry.area', 'cross-sections (m²)', (a) => a >= 0, 'a cross-section ≥ 0 (m²)');
+    need([...p.values].some((a) => a > 0), 'geometry.area: the cross-section is zero everywhere');
+    return { type: 'profile', x: p.x, values: p.values };
+  }
+  fields(g, 'geometry', ['type', 'r0']);
+  need(['planar', 'spherical', 'cylindrical'].includes(g.type), "geometry.type must be 'planar', 'spherical' or 'cylindrical'");
+  if (g.type === 'planar') return { type: 'planar' };
+  const r0 = g.r0 === undefined ? 0 : nonNegative(g.r0, 'geometry.r0 (m, the radius at x = 0)');
+  return { type: g.type, r0 };
+}
+
 // An internal port: an outside phase with known levels (V_i = V + offset_i, or μ for neutral
 // species, as at a contact), exchanging with every node in a window of one region.
 // Links per species: 'equilibrium' (μ̄ held at the outside level throughout the window),
 // { type: 'conductance', G } for charged species (G in S/m³: a source G (V_out − V_i)/(zF) per
 // volume), { type: 'exchange', k, mu } for neutral ones (k in mol/(m³·s): a source
-// k (μ_out − μ)/RT per volume), or 'blocked' (the default).
-function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
+// k (μ_out − μ)/RT per volume), or 'blocked' (the default). And reactions with the port's
+// terminal species, a metal's carrier at the port's level: an electrode surface spread through
+// the window, `area` (m²/m³) of it per volume.
+function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT) {
   need(isObject(pdef), `${path} must be an object`);
-  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -626,9 +666,10 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
     need(speciesIndex.has(pdef.terminal), `${path}.terminal: unknown species ${JSON.stringify(pdef.terminal)}${known(speciesIndex)}`);
     terminal = speciesIndex.get(pdef.terminal);
   }
-  need(isObject(pdef.species), `${path}.species must map species names to port links`);
+  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT);
+  need(pdef.species === undefined ? reactions.length > 0 : isObject(pdef.species), `${path}.species must map species names to port links`);
   const links = species.map(() => ({ type: 'blocked' }));
-  for (const [sname, raw] of Object.entries(pdef.species)) {
+  for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
     const lpath = `${path}.species.${sname}`;
     need(speciesIndex.has(sname), `${lpath}: unknown species '${sname}'${known(speciesIndex)}`);
     const i = speciesIndex.get(sname);
@@ -656,8 +697,49 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
     if (link.type === 'exchange') level.k = positive(link.k, `${lpath}.k (mol/(m³·s))`);
     links[i] = { type: link.type, ...level };
   }
-  need(links.some((l) => l.type !== 'blocked'), `${path}.species: the port exchanges no species`);
-  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links };
+  need(links.some((l) => l.type !== 'blocked') || reactions.length > 0, `${path}.species: the port exchanges no species`);
+  // One that exchanges only neutral species (an O₂ supply) carries no current, so its voltage is
+  // nobody's business: it can't be driven by one.
+  const passes = reactions.length > 0 || links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
+  need(passes || drive.kind === 'V', `${path}.I: this port passes no current (it exchanges only neutral species), so give it no drive`);
+  let area = null;
+  if (reactions.length > 0) {
+    need(pdef.area !== undefined, `${path}.area: give the electrode's area per volume of the window (m²/m³, e.g. 1/h for a film of thickness h on it), a number or a profile`);
+    area = typeof pdef.area === 'number' ? { value: positive(pdef.area, `${path}.area (m²/m³)`) } : profile(pdef.area, `${path}.area`, 'areas per volume (m²/m³)', (a) => a >= 0, 'an area per volume ≥ 0');
+  } else need(pdef.area === undefined, `${path}.area: only a port with reactions has an electrode area`);
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area };
+}
+
+// A port's reactions: Butler–Volmer, as at a face, between species of the port's region and the
+// port's terminal species (a metal's carrier, activity 1, at the port's level), per area of the
+// electrode: part side 0 for the region's species, side 1 for the carrier.
+function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT) {
+  need(pdef.reactions === undefined || Array.isArray(pdef.reactions), `${path}.reactions must be an array`);
+  const list = pdef.reactions ?? [];
+  if (list.length === 0) return [];
+  need(!mat.conductor, `${path}.reactions: a port on a conductor is a wire; reactions belong on a face, or on a port in the solution`);
+  need(terminal !== null && species[terminal].z !== 0, `${path}.terminal: a port with reactions needs its electrode's carrier as its terminal species (e.g. 'e-')`);
+  need(!mat.present[terminal], `${path}.terminal: '${species[terminal].name}' is in the port's region too, so a reaction can't tell the electrode's from the region's`);
+  const carrier = species[terminal].name;
+  return list.map((rdef, k) => {
+    const rpath = `${path}.reactions[${k}]`;
+    need(isObject(rdef) && typeof rdef.equation === 'string', `${rpath} must be { equation, fixed, k0, alpha }`);
+    fields(rdef, rpath, ['equation', 'fixed', 'k0', 'alpha']);
+    const holds = (name) => speciesIndex.has(name) && Boolean(mat.present[speciesIndex.get(name)]);
+    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier, conductor: true }, rdef.fixed, `${rpath}.equation`);
+    const part = [];
+    let fixedA = 0, charge = 0;
+    for (const [key, side] of [['left', 0], ['right', 1]]) {
+      const st = stoichiometry(sides[key], `${rpath}.equation`, rdef.fixed, `${rpath}.fixed`, species, speciesIndex, RT);
+      for (const { i, nu } of st.list) part.push({ i, nu, side });
+      fixedA += st.fixedA;
+      charge += st.charge;
+    }
+    need(part.some((p) => p.side === 1), `${rpath}: no '${carrier}' from the electrode takes part`);
+    need(part.some((p) => p.side === 0), `${rpath}: no species of the port's region takes part`);
+    need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`) };
+  });
 }
 
 function checkAnchors(regions, materials, interfaces, contacts, species, ports = []) {
@@ -680,7 +762,7 @@ function checkAnchors(regions, materials, interfaces, contacts, species, ports =
   const anchored = new Set();
   if (anchors(contacts.left)) anchored.add(find(0));
   if (anchors(contacts.right)) anchored.add(find(nR - 1));
-  for (const port of ports) if (port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
+  for (const port of ports) if (port.reactions.length > 0 || port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
   for (let r = 0; r < nR; r++) {
     const mat = materials[regions[r].material];
     const charged = species.some((sp, i) => mat.present[i] && sp.z !== 0);