driftlet 0.8.0 → 0.9.0

package/README.md

@@ -30,7 +30,7 @@ The same equations go by different names in different fields. If your problem is
 
 | If you work on | you may call it | start from | checked against |
 |---|---|---|---|
-| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions | [first example](#a-semiconductor-junction), [pn](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, 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 |
@@ -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.8.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).
 
@@ -262,6 +262,8 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | 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 |

package/docs/device.md

@@ -504,8 +504,11 @@ a terminal like any other. Held at a voltage, it's a potentiostat. At `I: 0` (or
 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`.
+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
@@ -515,6 +518,87 @@ the film's thickness varies, give the device its [cross-section](#geometry) too,
 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

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
 
@@ -123,7 +123,7 @@ console.log(curve.reactions[0].level, curve.current[40]); // the couple's level
 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
+(`{ 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

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.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';
+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`.
@@ -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.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';
+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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.8.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/describe.js

@@ -216,7 +216,9 @@ export function describe(def) {
     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}`);
+    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:');

package/src/device.js

@@ -351,6 +351,15 @@ export function normalizeDevice(def) {
     need(nodes.length > 0, `ports[${k}]: the window [${port.from}, ${port.to}] m holds no grid node; widen it or refine the grid`);
     port.nodes = Int32Array.from(nodes);
   });
+  // A node's surface belongs to one electrode.
+  const surfaced = new Int32Array(grid.nNodes).fill(-1);
+  ports.forEach((port, k) => {
+    if (port.surface.length === 0) return;
+    for (const g of port.nodes) {
+      need(surfaced[g] < 0, `ports[${k}]: its window overlaps ports[${surfaced[g]}]'s, and both have a surface; a spot of metal has one surface`);
+      surfaced[g] = k;
+    }
+  });
 
   return {
     T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports, geometry,
@@ -649,7 +658,7 @@ function normalizeGeometry(g) {
 // 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', 'reactions', 'area']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area', 'surface', 'capacitance']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -666,8 +675,11 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     need(speciesIndex.has(pdef.terminal), `${path}.terminal: unknown species ${JSON.stringify(pdef.terminal)}${known(speciesIndex)}`);
     terminal = speciesIndex.get(pdef.terminal);
   }
-  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 surface = portSurface(pdef, path, speciesIndex);
+  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface);
+  surface.forEach((sp, s) => need(reactions.some((rx) => rx.part.some((p) => p.side === 2 && p.s === s)), `${path}.surface.${sp.name}: no reaction of the port makes or uses it`));
+  const capacitance = portCapacitance(pdef, path, mat);
+  need(pdef.species === undefined ? reactions.length > 0 || capacitance !== null : 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 ?? {})) {
     const lpath = `${path}.species.${sname}`;
@@ -697,48 +709,94 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT
     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') || reactions.length > 0, `${path}.species: the port exchanges no species`);
+  need(links.some((l) => l.type !== 'blocked') || reactions.length > 0 || capacitance !== null, `${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);
+  const passes = reactions.length > 0 || capacitance !== null || 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) {
+  if (reactions.length > 0 || capacitance !== null) {
     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 };
+  } else need(pdef.area === undefined, `${path}.area: only an electrode (a port with reactions or a capacitance) has an area`);
+  need(surface.length === 0 || reactions.length > 0, `${path}.surface: only an electrode (a port with reactions) has a surface`);
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area, surface, capacitance };
+}
+
+// A capacitance spread through the window: a gate along a channel, an electrode's double layer.
+// Per area of electrode it holds σ = C (V − zeroCharge − φ) on the port's side, and the window
+// the opposite: the region's charge balance (Gauss's law, or neutrality at ε = 0) gains aσ.
+function portCapacitance(pdef, path, mat) {
+  if (pdef.capacitance === undefined) return null;
+  const cpath = `${path}.capacitance`;
+  need(isObject(pdef.capacitance), `${cpath} must be { C, zeroCharge }`);
+  fields(pdef.capacitance, cpath, ['C', 'zeroCharge']);
+  need(!mat.conductor && !mat.phiFree, `${cpath}: a capacitance couples to φ, which a ${mat.conductor ? 'conductor' : 'region with no free charge'} doesn't have`);
+  return { C: positive(pdef.capacitance.C, `${cpath}.C (F/m² of electrode)`), zeroCharge: pdef.capacitance.zeroCharge === undefined ? 0 : finite(pdef.capacitance.zeroCharge, `${cpath}.zeroCharge (V)`) };
+}
+
+// An electrode port's surface species: coverages θ of its sites (Langmuir: each takes one site,
+// μ = μ° + RT ln(θ/θ₀) with θ₀ = 1 − Σθ the bare fraction), Γ mol of sites per m² of electrode.
+function portSurface(pdef, path, speciesIndex) {
+  if (pdef.surface === undefined) return [];
+  need(isObject(pdef.surface), `${path}.surface must map surface species to { mu0, capacity, theta0 }`);
+  const list = Object.entries(pdef.surface).map(([name, d]) => {
+    const spath = `${path}.surface.${name}`;
+    need(!speciesIndex.has(name), `${spath}: '${name}' is a species of the device; a surface species is the port's own, with its own name`);
+    need(isObject(d), `${spath} must be { mu0, capacity, theta0 }`);
+    fields(d, spath, ['mu0', 'capacity', 'theta0']);
+    const theta0 = d.theta0 === undefined ? 1e-6 : positive(d.theta0, `${spath}.theta0`);
+    return { name, mu0: finite(d.mu0, `${spath}.mu0 (J/mol)`), capacity: positive(d.capacity, `${spath}.capacity (mol of sites per m² of electrode)`), theta0 };
+  });
+  need(list.length > 0, `${path}.surface: give at least one surface species, or leave it out`);
+  const caps = new Set(list.map((sp) => sp.capacity));
+  need(caps.size === 1, `${path}.surface: the species share the electrode's sites, so give them one capacity`);
+  need(list.reduce((t, sp) => t + sp.theta0, 0) < 1, `${path}.surface: the starting coverages (theta0) must sum to less than 1`);
+  return list;
 }
 
 // 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) {
+function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface = []) {
   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`);
+  // The metal's countercharge (each spot's double layer) is below the grid, so the solution
+  // beside it must be neutral, as in porous-electrode theory; with ε > 0 the reactions would
+  // leave a net charge with nothing to balance it.
+  need(mat.epsr === 0 || mat.phiFree, `${path}.reactions: an electrode spread through a window needs its region strictly neutral (ε = 0): its double layers are below the grid`);
   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']);
+    fields(rdef, rpath, ['equation', 'fixed', 'k0', 'alpha', 'bare']);
     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 onSurface = (name) => surface.findIndex((sp) => sp.name === name);
+    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier || onSurface(name) >= 0, 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);
+    // The electrode's side: its carrier, and its surface species (side 2, neutral, by index s).
+    const electrode = {};
+    for (const [name, nu] of Object.entries(sides.right)) {
+      const s = onSurface(name);
+      if (s >= 0) part.push({ s, nu, side: 2 });
+      else electrode[name] = nu;
+    }
+    for (const [map, side] of [[sides.left, 0], [electrode, 1]]) {
+      const st = stoichiometry(map, `${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(part.some((p) => p.side === 0 || p.side === 2), `${rpath}: no species of the port's region or its surface 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`) };
+    need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
   });
 }
 
@@ -762,7 +820,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.reactions.length > 0 || 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.capacitance || 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);

package/src/index.js

@@ -100,6 +100,7 @@ export class Device {
       solver.computeConcentrations();
       solver.time = old.time;
       solver.contactDEnd = old.contactDEnd;
+      if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)
       // Floating terminals keep their voltages (a good start), where the terminals match.
       if (old.terms.length === solver.terms.length) {

package/src/polarization.js

@@ -29,7 +29,7 @@ const fail = (message) => {
 export function polarization(device, sol, where, V) {
   const model = device.model, { species, grid, RT } = model, solver = device.solver;
   const Vs = Float64Array.from(typeof V === 'number' ? [V] : V);
-  let reactions, nodeOf, carrier, names;
+  let reactions, nodeOf, carrier, names, surface = null; // (an electrode port's coverages at the spot)
   if (where?.face !== undefined) {
     const f = where.face, itf = model.interfaces[f];
     if (!itf) fail(`polarization: no face ${f} (the device has ${model.interfaces.length})`);
@@ -49,6 +49,10 @@ export function polarization(device, sol, where, V) {
     if (where.x !== undefined) for (const h of port.nodes) if (Math.abs(grid.x[h] - where.x) < Math.abs(grid.x[g] - where.x)) g = h;
     carrier = { side: 1, i: port.terminal };
     nodeOf = () => g;
+    if (port.surface.length > 0) {
+      const w = port.nodes.indexOf(g), theta = port.surface.map((sp) => sol.ports[k].coverage[sp.name][w]);
+      surface = { sp: port.surface, theta, bare: sol.ports[k].bare[w] };
+    }
     reactions = port.reactions;
     names = device.def.ports?.[k]?.reactions;
   } else fail('polarization: say where, { face: f } or { port: name, x }');
@@ -59,6 +63,13 @@ export function polarization(device, sol, where, V) {
     // a = A/RT = a0 + s·V: everything but the carrier at its level, and the carrier's part.
     let a0 = rx.fixedA, s = 0, q = 0, pref = rx.vmax ? rx.vmax : rx.k0;
     rx.part.forEach((p, x) => {
+      if (p.side === 2) {
+        // a surface species, at activity θ/θ₀ (μ = μ° + RT ln(θ/θ₀))
+        const ln = Math.log(surface.theta[p.s] / surface.bare), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
+        a0 -= (p.nu * (surface.sp[p.s].mu0 / RT + ln));
+        pref *= Math.exp(e * ln);
+        return;
+      }
       if (p.side === carrier.side && p.i === carrier.i) {
         s -= (p.nu * species[p.i].z * FARADAY) / RT;
         return;
@@ -72,6 +83,7 @@ export function polarization(device, sol, where, V) {
       } else pref *= powr(c / solver.cRef[g * species.length + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
     });
     if (s === 0) fail(`polarization: reaction ${k} there takes no ${species[carrier.i].name} from the metal`);
+    if (rx.bare) pref *= surface ? surface.bare : 1; // on bare metal only
     const rate = Float64Array.from(Vs, (v) => {
       const a = a0 + s * v;
       return rx.vmax ? pref * -Math.expm1(-a) : pref * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));

package/src/solution.js

@@ -106,12 +106,30 @@ export function makeSolution(solver, result = {}) {
       flux[species[i].name] = solver.portFlux[k][i];
       current += F * species[i].z * solver.portFlux[k][i];
     }
+    if (port.capacitance) {
+      // a capacitance's charging current, and its charge (the port's side), like a gate's
+      const dt = solver.lastDt;
+      current += Number.isFinite(dt) ? (solver.portQ[k] - solver.portQOld[k]) / dt : 0;
+    }
     const out = { name: port.name, V: solver.termV[2 + k], flux, current };
-    if (port.reactions.length > 0) {
-      // An electrode spread through the window: where it sits, and each reaction's rate there.
+    if (port.capacitance) out.charge = solver.portQ[k];
+    if (port.capacitance) {
+      // its charge per area of electrode at each node, σ = C (V − zeroCharge − φ)
+      const { C: Cs, zeroCharge } = port.capacitance;
+      out.sigma = Float64Array.from(port.nodes, (g) => Cs * (solver.termV[2 + k] - zeroCharge - phi[g]));
+    }
+    if (port.area !== null) {
       out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
       out.area = Float64Array.from(solver.portArea[k]);
+    }
+    if (port.reactions.length > 0) {
+      // An electrode spread through the window: each reaction's rate at its nodes.
       out.rates = solver.portRates[k].map((r) => Float64Array.from(r)); // mol/(m²·s), forward
+      // its surface: each species' coverage θ at each node of the window
+      if (port.surface.length > 0) {
+        out.coverage = Object.fromEntries(port.surface.map((sp, q) => [sp.name, Float64Array.from(port.nodes, (g) => solver.th[g * solver.nSurf + q])]));
+        out.bare = Float64Array.from(port.nodes, (g) => solver.th0[g]); // θ₀, to full precision however covered
+      }
     }
     return out;
   });

package/src/solver.js

@@ -195,13 +195,16 @@ export class Solver {
     // Slots per block: φ̂ (or D, or a conductor's segment flux J), one per species, and at a face
     // one per face reaction (its rate), as many as the busiest face has.
     const nRx = model.interfaces.reduce((m, itf) => Math.max(m, itf.reactions.length), 0);
-    const M = n + 1 + nRx;
+    // (and at an electrode port's nodes, one per surface species: its coverage's η)
+    const nSurf = model.ports.reduce((m, port) => Math.max(m, port.surface.length), 0);
+    const M = n + 1 + Math.max(nRx, nSurf);
     const nNodes = grid.nNodes;
     const nFaces = regions.length - 1;
     const nB = nNodes + nFaces;
     this.n = n;
     this.M = M;
     this.nRx = nRx;
+    this.nSurf = nSurf;
     this.nNodes = nNodes;
     this.nFaces = nFaces;
     this.nB = nB;
@@ -214,6 +217,18 @@ export class Solver {
     this.blockOfFace = new Int32Array(nFaces);
     for (let f = 0; f < nFaces; f++) this.blockOfFace[f] = grid.regionEnd[f] + f + 1;
 
+    // Electrode ports' surfaces: each node's port (−1: none) and its index in the port's window;
+    // the coverages there, θ [g·nSurf + s], now and at the step's start.
+    this.surfPort = new Int32Array(nNodes).fill(-1);
+    this.surfW = new Int32Array(nNodes);
+    model.ports.forEach((port, k) => {
+      if (port.surface.length > 0) port.nodes.forEach((g, w) => ((this.surfPort[g] = k), (this.surfW[g] = w)));
+    });
+    this.th = new Float64Array(nNodes * nSurf);
+    this.thOld = new Float64Array(nNodes * nSurf);
+    this.th0 = new Float64Array(nNodes); // the bare fraction θ₀, directly (1 − Σθ cancels as θ → 1)
+    this.th0Old = new Float64Array(nNodes);
+
     // Per-node material data, flattened [g·n + i].
     this.present = new Uint8Array(nNodes * n);
     this.cRef = new Float64Array(nNodes * n);
@@ -327,6 +342,12 @@ export class Solver {
     this.contactFlux = { left: new Float64Array(n), right: new Float64Array(n) };
     this.portFlux = model.ports.map(() => new Float64Array(n)); // into the device, mol/(m²·s)
     this.contactD = { left: 0, right: 0 };
+    // A capacitive port's charge (its side's, Σ vol·a·σ over its window), as the contacts' D: now,
+    // at the step's start and at the previous step's end.
+    this.portQ = new Float64Array(model.ports.length);
+    this.portQStart = new Float64Array(model.ports.length);
+    this.portQOld = new Float64Array(model.ports.length);
+    this.portQEnd = null;
     this.contactDOld = { left: 0, right: 0 };
     this.contactDStart = { left: 0, right: 0 };
     // Terminals (the two contacts, then the ports): each one's voltage (V), held by its source or
@@ -453,6 +474,8 @@ export class Solver {
       }
       active[b * M] = this.phiUndefined[g] ? 0 : 1;
       for (let i = 0; i < n; i++) active[b * M + 1 + i] = this.present[g * n + i];
+      const k = this.surfPort[g];
+      if (k >= 0) for (let q = 0; q < model.ports[k].surface.length; q++) active[b * M + 1 + n + q] = 1;
     }
     model.interfaces.forEach((itf, f) => {
       const bf = this.blockOfFace[f];
@@ -1055,6 +1078,13 @@ export class Solver {
       const shift = level(t.side) - level(this.terms[held].side);
       if (Number.isFinite(shift)) this.termV[k] = this.termV[held] + shift;
     }
+    // Electrode surfaces at their starting coverages: η = μ°/RT + ln(θ/θ₀).
+    for (let g = 0; g < this.nNodes; g++) {
+      const k = this.surfPort[g];
+      if (k < 0) continue;
+      const surf = model.ports[k].surface, b = this.blockOfNode[g], bare = 1 - surf.reduce((t, sp) => t + sp.theta0, 0);
+      surf.forEach((sp, q) => (u[b * M + 1 + n + q] = sp.mu0 / model.RT + Math.log(sp.theta0 / bare)));
+    }
     this.computeConcentrations();
     // A floating electrode spread through a port starts where its reactions pass the current it's
     // set (none, behind a resistance): at its mixed potential in the start's composition, not
@@ -1088,16 +1118,18 @@ export class Solver {
 
   // A port reaction's rate per area at node g (mol/(m²·s), forward), at the present state.
   _portRate(port, rx, g) {
-    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    const { n, M, u, uLo, c, nSurf, th } = this, b = this.blockOfNode[g], RT = this.model.RT;
     let pref = rx.k0, a = rx.fixedA;
     for (const p of rx.part) {
       if (p.side === 1) {
         a -= p.nu * this.portEta(port, p.i);
         continue;
       }
-      a -= p.nu * (u[b * M + 1 + p.i] + uLo[b * M + 1 + p.i]);
-      pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
+      const o = b * M + (p.side === 2 ? 1 + n + p.s : 1 + p.i), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
+      a -= p.nu * (u[o] + uLo[o]);
+      pref *= p.side === 2 ? Math.exp(e * (u[o] + uLo[o] - port.surface[p.s].mu0 / RT)) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
     }
+    if (rx.bare) pref *= this.th0[g];
     // (far from equilibrium, the plain difference: bvFactor's product would give 0·∞ there)
     return pref * (Math.abs(a) > 50 ? Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a) : bvFactor(a, rx.alpha).g);
   }
@@ -1128,6 +1160,23 @@ export class Solver {
     }
   }
 
+  // Each electrode surface's coverages from its η: Langmuir on shared sites, θ_s = e^{ζ_s}/(1 + Σ e^{ζ}),
+  // ζ = η − μ°/RT (so θ_s/θ₀ = e^{ζ_s}), at every node of a surfaced window.
+  _coverages() {
+    const { n, M, u, uLo, nSurf, th } = this, RT = this.model.RT;
+    for (let g = 0; g < this.nNodes; g++) {
+      const k = this.surfPort[g];
+      if (k < 0) continue;
+      const surf = this.model.ports[k].surface, b = this.blockOfNode[g];
+      let m = 0;
+      for (let q = 0; q < surf.length; q++) m = Math.max(m, u[b * M + 1 + n + q] + uLo[b * M + 1 + n + q] - surf[q].mu0 / RT);
+      let sum = Math.exp(-m);
+      for (let q = 0; q < surf.length; q++) sum += (th[g * nSurf + q] = Math.exp(u[b * M + 1 + n + q] + uLo[b * M + 1 + n + q] - surf[q].mu0 / RT - m));
+      for (let q = 0; q < surf.length; q++) th[g * nSurf + q] /= sum;
+      this.th0[g] = Math.exp(-m) / sum;
+    }
+  }
+
   computeConcentrations() {
     const { n, M, u, uLo, c, z } = this;
     for (let g = 0; g < this.nNodes; g++) {
@@ -1150,6 +1199,7 @@ export class Solver {
         c[k] = this.present[k] ? this.cRef[k] * Math.exp(u[b * M + 1 + i] + uLo[b * M + 1 + i] - this.mu0hat[k] - z[i] * phiHat) : 0;
       }
     }
+    this._coverages();
   }
 
   _work(md) {
@@ -1969,7 +2019,7 @@ export class Solver {
       this.termDI[k] = 0;
       this.termI[k] = 0;
     }
-    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k));
+    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt));
     this._contact('left', dt);
     this._contact('right', dt);
     for (const k of this.floating) this._circuit(k);
@@ -2002,7 +2052,7 @@ export class Solver {
   // An internal port (terminal k): its exchange with each node of its window, as a source per
   // volume. A held ('equilibrium') level replaces the node's balance row; the source is then that
   // row's residual, read just before. Its current into the device is Σ z F × the sources.
-  _port(port, flux, k) {
+  _port(port, flux, k, dt) {
     const R = this.rix;
     const { n, M, u, uLo, res, z, VT } = this;
     const F = FARADAY, vol = this.model.grid.vol;
@@ -2038,6 +2088,8 @@ export class Solver {
       }
     }
     port.reactions.forEach((rx, x) => this._portReaction(port, rx, this.portArea[k - 2], this.portRates[k - 2][x], flux, k));
+    if (port.capacitance) this._portCapacitance(port, k, dt);
+    if (port.surface.length > 0 && Number.isFinite(dt)) this._surfaceStorage(port, dt);
     for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
   }
 
@@ -2046,49 +2098,111 @@ export class Solver {
   // volume. Each node's rate is explicit (no unknown of its own): it enters the balances of the
   // species it makes and consumes, and the port's current.
   _portReaction(port, rx, area, rates, flux, k) {
-    const { n, M, u, uLo, c, res, z, VT } = this, R = this.rix, F = FARADAY, vol = this.model.grid.vol;
-    const B = this.termB[k], C = this.termC[k], al = rx.alpha, d = this.dA;
+    const { n, M, u, uLo, c, res, z, VT, nSurf, th } = this, R = this.rix, F = FARADAY, vol = this.model.grid.vol, RT = this.model.RT;
+    const B = this.termB[k], C = this.termC[k], al = rx.alpha, d = this.dA, surf = port.surface;
     // The carrier's part of the affinity, and how it moves with the port's voltage.
     let aV = rx.fixedA, daV = 0, q = 0; // q: charge the forward reaction brings into the device, per event
     for (const p of rx.part) {
       if (p.side === 1) {
         aV -= p.nu * this.portEta(port, p.i);
         daV -= (p.nu * z[p.i]) / VT;
-      } else q += p.nu * z[p.i];
+      } else if (p.side === 0) q += p.nu * z[p.i];
     }
+    const slot = (p) => (p.side === 2 ? 1 + n + p.s : 1 + p.i);
     port.nodes.forEach((g, w) => {
       const b = this.blockOfNode[g], s = vol[g] * area[w];
       d.fill(0);
       let pref = rx.k0, aHi = aV, aLo = 0;
       for (const p of rx.part) {
         if (p.side === 1) continue;
-        const o = b * M + 1 + p.i;
+        const o = b * M + slot(p);
         aHi -= p.nu * u[o];
         aLo -= p.nu * uLo[o];
         const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
-        pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
-        this._dlnc(g, p.i, e, d);
+        if (p.side === 2) {
+          // a surface species at activity θ/θ₀ = e^ζ
+          pref *= Math.exp(e * (u[o] + uLo[o] - surf[p.s].mu0 / RT));
+          d[1 + n + p.s] += e;
+        } else {
+          pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
+          this._dlnc(g, p.i, e, d);
+        }
+      }
+      if (rx.bare) {
+        // on bare metal only: the free fraction θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
+        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= th[g * nSurf + x];
+        pref *= this.th0[g];
       }
       const { g: bv, gp } = bvFactor(aHi + aLo, al);
       const rate = pref * bv;
       rates[w] = rate;
-      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
+      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η = −ν
       for (let t = 0; t < M; t++) d[t] *= rate;
-      for (const p of rx.part) if (p.side === 0) d[1 + p.i] -= pref * gp * p.nu;
+      for (const p of rx.part) if (p.side !== 1) d[slot(p)] -= pref * gp * p.nu;
       const dV = pref * gp * daV;
       for (const p of rx.part) {
         if (p.side === 1) continue;
-        const row = 1 + p.i, o = b * M + row;
-        res[R[o]] -= s * p.nu * rate;
-        flux[p.i] += s * p.nu * rate;
-        for (let t = 0; t < M; t++) if (d[t] !== 0) this._j(b, row, b, t, -s * p.nu * d[t]);
-        B[R[o]] -= s * p.nu * dV;
+        // the region's species per volume of the window; a surface's per area of electrode
+        const row = slot(p), o = b * M + row, f = p.side === 2 ? 1 : s;
+        res[R[o]] -= f * p.nu * rate;
+        if (p.side === 0) flux[p.i] += s * p.nu * rate;
+        for (let t = 0; t < M; t++) if (d[t] !== 0) this._j(b, row, b, t, -f * p.nu * d[t]);
+        B[R[o]] -= f * p.nu * dV;
       }
       for (let t = 0; t < M; t++) if (d[t] !== 0) C[R[b * M + t]] += q * F * s * d[t];
       this.termDI[k] += q * F * s * dV;
     });
   }
 
+  // A capacitance spread through a port's window: per area of electrode, σ = C (V − zeroCharge − φ)
+  // on the port's side, so each node's charge balance (its φ row) gains vol·a·σ, and the port
+  // passes the charging current d(Σ vol·a·σ)/dt (none in a steady state). An end node whose φ its
+  // contact sets is left to the contact.
+  _portCapacitance(port, k, dt) {
+    const { M, u, uLo, res, VT } = this, R = this.rix, vol = this.model.grid.vol, area = this.portArea[k - 2];
+    const { C: Cs, zeroCharge } = port.capacitance, V = this.termV[k], B = this.termB[k], Ct = this.termC[k];
+    const sets = (side) => ['pinned', 'bulk'].includes(this.model.contacts[side].phi.type);
+    let Q = 0, dQdV = 0;
+    port.nodes.forEach((g, w) => {
+      if ((g === 0 && sets('left')) || (g === this.nNodes - 1 && sets('right')) || this.phiUndefined[g]) return;
+      const b = this.blockOfNode[g], s = vol[g] * area[w] * Cs;
+      const q = s * (V - zeroCharge - VT * (u[b * M] + uLo[b * M]));
+      Q += q;
+      dQdV += s;
+      res[R[b * M]] -= q;
+      this._j(b, 0, b, 0, s * VT);
+      B[R[b * M]] -= s;
+      if (Number.isFinite(dt)) Ct[R[b * M]] += (-s * VT) / dt;
+    });
+    this.portQ[k - 2] = Q;
+    if (Number.isFinite(dt)) {
+      this.termI[k] += (Q - this.portQStart[k - 2]) / dt;
+      this.termDI[k] += dQdV / dt;
+    }
+  }
+
+  // An electrode surface's storage, per area of electrode: Γ (θ_s − θ_s,old)/dt in each surface
+  // species' row, with ∂θ_s/∂η_x = θ_s (δ_sx − θ_x).
+  _surfaceStorage(port, dt) {
+    const { n, M, res, nSurf, th, thOld } = this, R = this.rix, surf = port.surface, G = surf[0].capacity;
+    for (const g of port.nodes) {
+      const b = this.blockOfNode[g];
+      // Near full coverage θ − θ_old cancels (both ~1, the change ~θ₀): the dominant species'
+      // change comes from the small ones instead, Δθ = −Δθ₀ − Σ_others Δθ.
+      let top = 0;
+      for (let q = 1; q < surf.length; q++) if (th[g * nSurf + q] > th[g * nSurf + top]) top = q;
+      for (let q = 0; q < surf.length; q++) {
+        const tq = th[g * nSurf + q];
+        let change = tq - thOld[g * nSurf + q];
+        if (q === top && tq > 0.5) {
+          change = -(this.th0[g] - this.th0Old[g]);
+          for (let x = 0; x < surf.length; x++) if (x !== q) change -= th[g * nSurf + x] - thOld[g * nSurf + x];
+        }
+        res[R[b * M + 1 + n + q]] += (G * change) / dt;
+        for (let x = 0; x < surf.length; x++) this._j(b, 1 + n + q, b, 1 + n + x, ((G * tq) / dt) * ((q === x ? 1 : 0) - th[g * nSurf + x]));
+      }
+    }
+  }
 
   // One contact (terminal 0 or 1): record the flux through its outer face and the current into
   // the device (read from the end box before anything here is added: whatever the box needs
@@ -2245,6 +2359,8 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         if (this.present[g * n + i]) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + i]]));
       }
+      const k = this.surfPort[g]; // an electrode surface's coverages, as η
+      if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(delta[R[b * M + 1 + n + q]]));
     }
     return mx;
   }
@@ -2401,14 +2517,15 @@ export class Solver {
     this.uPrevLo.set(this.uLo);
     this.termVPrev.set(this.termV);
     this.computeConcentrations();
-    const cN = Float64Array.from(this.c);
+    const cN = Float64Array.from(this.c), thN = Float64Array.from(this.th), th0N = Float64Array.from(this.th0);
     // Contact displacement before the step: as it was at the end of the previous step (under
     // the parameters then), so a gate-voltage change shows up as displacement current.
-    if (!this.contactDEnd) {
+    if (!this.contactDEnd || !this.portQEnd) {
       this._assembleBookkeeping(dt);
       this.contactDEnd = { ...this.contactD };
+      this.portQEnd = Float64Array.from(this.portQ);
     }
-    const DN = { ...this.contactDEnd };
+    const DN = { ...this.contactDEnd }, QN = Float64Array.from(this.portQEnd);
     if (opts.guess) {
       // Start Newton from a predicted state (e.g. extrapolated from the history).
       this.u.set(opts.guess);
@@ -2419,11 +2536,17 @@ export class Solver {
       const a0 = (1 + 2 * w) / (1 + w), b1 = (1 + w) / a0, b2 = (w * w) / (1 + w) / a0;
       const { cOld } = this;
       for (let k = 0; k < cOld.length; k++) cOld[k] = b1 * cN[k] - b2 * prev.c[k];
+      for (let k = 0; k < thN.length; k++) this.thOld[k] = b1 * thN[k] - b2 * prev.th[k];
+      for (let k = 0; k < th0N.length; k++) this.th0Old[k] = b1 * th0N[k] - b2 * prev.th0[k];
       this.contactDStart = { left: b1 * DN.left - b2 * prev.D.left, right: b1 * DN.right - b2 * prev.D.right };
+      this.portQStart = QN.map((q, k) => b1 * q - b2 * prev.Q[k]);
       dtEff = dt / a0;
     } else {
       this.cOld.set(cN);
+      this.thOld.set(thN);
+      this.th0Old.set(th0N);
       this.contactDStart = DN;
+      this.portQStart = QN;
     }
     // Implicit: sources at the step's end, as seen from within the step (before any jump there).
     // A step landing on a breakpoint ends on it exactly.
@@ -2439,11 +2562,12 @@ export class Solver {
     }
     result.bdf = bdf;
     if (result.converged) {
-      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, D: DN });
+      this.history.unshift({ t: this.time, dt, u: Float64Array.from(this.uPrev), c: cN, th: thN, th0: th0N, D: DN, Q: QN });
       if (this.history.length > 3) this.history.length = 3;
       this.time = tEnd;
       this.lastDt = dtEff;
       this.contactDOld = this.contactDStart;
+      this.portQOld = this.portQStart;
       this._accumulateBoundaryIntake(dtEff, cN);
     } else {
       this.u.set(this.uPrev);
@@ -2727,12 +2851,17 @@ export class Solver {
       u: Float64Array.from(this.u),
       uLo: Float64Array.from(this.uLo),
       cOld: Float64Array.from(this.cOld),
+      thOld: Float64Array.from(this.thOld),
+      th0Old: Float64Array.from(this.th0Old),
       time: this.time,
       lastDt: this.lastDt,
       atSteady: this.atSteady,
       contactDStart: this.contactDStart,
       contactDOld: this.contactDOld,
       contactDEnd: this.contactDEnd,
+      portQStart: this.portQStart,
+      portQOld: this.portQOld,
+      portQEnd: this.portQEnd,
       boundaryIntake: Float64Array.from(this.boundaryIntake),
       history: this.history.slice(),
       termV: Float64Array.from(this.termV),
@@ -2744,12 +2873,17 @@ export class Solver {
     this.u.set(s.u);
     this.uLo.set(s.uLo);
     this.cOld.set(s.cOld);
+    this.thOld.set(s.thOld);
+    this.th0Old.set(s.th0Old);
     this.time = s.time;
     this.lastDt = s.lastDt;
     this.atSteady = s.atSteady;
     this.contactDStart = s.contactDStart;
     this.contactDOld = s.contactDOld;
     this.contactDEnd = s.contactDEnd;
+    this.portQStart = s.portQStart;
+    this.portQOld = s.portQOld;
+    this.portQEnd = s.portQEnd;
     this.boundaryIntake.set(s.boundaryIntake);
     this.history = s.history.slice();
     this.termV.set(s.termV);
@@ -2786,8 +2920,11 @@ export class Solver {
     this.sourceTime = this.time;
     this.computeConcentrations();
     this.cOld.set(this.c);
+    this.thOld.set(this.th);
+    this.th0Old.set(this.th0);
     this.assemble(Infinity);
     this.contactDStart = { ...this.contactD };
+    this.portQStart = Float64Array.from(this.portQ);
     this.assemble(Infinity);
     // The steady parts, then the storage parts from an assembly at a tiny dt.
     const J = { A: sys.A.slice(), B: sys.B.slice(), C: sys.C.slice() };
@@ -3075,6 +3212,7 @@ export class Solver {
   _accumulateBoundaryIntake(dt, cN) {
     this._assembleBookkeeping(dt);
     this.contactDEnd = { ...this.contactD };
+    this.portQEnd = Float64Array.from(this.portQ);
     if (!Number.isFinite(dt)) return;
     const last = this.model.regions.length - 1;
     const { n, cOld } = this, vol = this.model.grid.vol;

package/src/stack.js

@@ -100,7 +100,7 @@ export function bath(c, reference, d = 0, { offset } = {}) {
   return { ...drive(d, 'bath'), bath: { c: { ...c }, reference, ...(offset === undefined ? {} : { offset }) } };
 }
 
-const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReactions', 'ports', 'grid'];
+const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReactions', 'ports', 'grid', 'geometry'];
 
 /**
  * Build a plain device definition from a stack:
@@ -112,7 +112,7 @@ const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReac
  *   between them get the default face. Nested lists are flattened.
  * - Layers may give doping as `donors` and `acceptors` (mol/m³) in place of `fixedCharge`.
  * - `library`: pieces with species and materials, merged with `species` and `materials`.
- * - `T`, `grid`, `ports` pass through.
+ * - `T`, `grid`, `ports`, `geometry` pass through.
  * @param {object} def
  * @returns {object} a device definition for `new Device`
  */
@@ -168,5 +168,6 @@ export function build(def) {
   if (def.bulkReactions !== undefined) out.bulkReactions = def.bulkReactions;
   if (def.ports !== undefined) out.ports = def.ports;
   if (def.grid !== undefined) out.grid = def.grid;
+  if (def.geometry !== undefined) out.geometry = def.geometry;
   return out;
 }

package/src/types.js

@@ -157,10 +157,16 @@
  * @property {string} [terminal] species whose offset defaults to 0; with reactions, the electrode's carrier
  * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'equilibrium', offset?: number, mu?: number }
  *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} [species]
- * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number }[]} [reactions] an
+ * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number, bare?: boolean }[]} [reactions] an
  *   electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s)) between the region's
  *   species and the terminal species at the port's level
- * @property {number | { x: number[], values: number[] }} [area] with reactions: electrode area per volume,
+ * @property {Record<string, { mu0: number, capacity: number, theta0?: number }>} [surface] with reactions: species
+ *   on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
+ *   shared; a reaction with `bare: true` runs only on the bare fraction θ₀ = 1 − Σθ
+ * @property {{ C: number, zeroCharge?: number }} [capacitance] a capacitance spread through the window (F/m² of
+ *   electrode): σ = C (V − zeroCharge − φ) on the port's side, aσ in each node's charge balance; a gate
+ *   along a channel, a double layer
+ * @property {number | { x: number[], values: number[] }} [area] with reactions or a capacitance: electrode area per volume,
  *   m²/m³ (1/h for a film of thickness h), or a profile against the device's x
  */
 
@@ -209,7 +215,8 @@
  * @property {{ left: ContactResult, right: ContactResult }} contacts
  * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number, x?: Float64Array,
- *   area?: Float64Array, rates?: Float64Array[] }[]} ports what each internal port brings into the device;
+ *   area?: Float64Array, rates?: Float64Array[], coverage?: Record<string, Float64Array>, bare?: Float64Array,
+ *   sigma?: Float64Array, charge?: number }[]} ports what each internal port brings into the device;
  *   with reactions, also its window's nodes (x, m), area per volume there, and each reaction's rate per area
  *   at each node (mol/(m²·s), forward)
  * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces

package/types/solver.d.ts

@@ -8,12 +8,19 @@ export class Solver {
     n: any;
     M: any;
     nRx: any;
+    nSurf: any;
     nNodes: any;
     nFaces: number;
     nB: any;
     VT: number;
     blockOfNode: Int32Array<any>;
     blockOfFace: Int32Array<ArrayBuffer>;
+    surfPort: Int32Array<any>;
+    surfW: Int32Array<any>;
+    th: Float64Array<ArrayBuffer>;
+    thOld: Float64Array<ArrayBuffer>;
+    th0: Float64Array<any>;
+    th0Old: Float64Array<any>;
     present: Uint8Array<ArrayBuffer>;
     cRef: Float64Array<ArrayBuffer>;
     mu0hat: Float64Array<ArrayBuffer>;
@@ -54,6 +61,10 @@ export class Solver {
         left: number;
         right: number;
     };
+    portQ: Float64Array<any>;
+    portQStart: Float64Array<any>;
+    portQOld: Float64Array<any>;
+    portQEnd: any;
     contactDOld: {
         left: number;
         right: number;
@@ -133,6 +144,7 @@ export class Solver {
     initFromComposition(): void;
     _portRate(port: any, rx: any, g: any): number;
     _materialAt(mat: any, background: any, eta: any, mode: any, cFix: any, ph: any, zeta: any, cc: any): void;
+    _coverages(): void;
     computeConcentrations(): void;
     _work(md: any): any;
     _nodeStatistics(g: any, b: any, phiHat: any): void;
@@ -172,8 +184,10 @@ export class Solver {
     _terminals(dt: any): void;
     _circuit(k: any): void;
     _captureRow(b: any, s: any, w: any, into: any): number;
-    _port(port: any, flux: any, k: any): void;
+    _port(port: any, flux: any, k: any, dt: any): void;
     _portReaction(port: any, rx: any, area: any, rates: any, flux: any, k: any): void;
+    _portCapacitance(port: any, k: any, dt: any): void;
+    _surfaceStorage(port: any, dt: any): void;
     _contact(side: any, dt: any): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
@@ -257,6 +271,8 @@ export class Solver {
         u: Float64Array<ArrayBuffer>;
         uLo: Float64Array<ArrayBuffer>;
         cOld: Float64Array<ArrayBuffer>;
+        thOld: Float64Array<ArrayBuffer>;
+        th0Old: Float64Array<ArrayBuffer>;
         time: number;
         lastDt: number;
         atSteady: boolean;
@@ -269,6 +285,9 @@ export class Solver {
             right: number;
         };
         contactDEnd: any;
+        portQStart: Float64Array<any>;
+        portQOld: Float64Array<any>;
+        portQEnd: any;
         boundaryIntake: Float64Array<ArrayBuffer>;
         history: any[];
         termV: Float64Array<ArrayBuffer>;

package/types/stack.d.ts

@@ -53,7 +53,7 @@ export function bath(c: Record<string, number>, reference: string, d?: number, {
  *   between them get the default face. Nested lists are flattened.
  * - Layers may give doping as `donors` and `acceptors` (mol/m³) in place of `fixedCharge`.
  * - `library`: pieces with species and materials, merged with `species` and `materials`.
- * - `T`, `grid`, `ports` pass through.
+ * - `T`, `grid`, `ports`, `geometry` pass through.
  * @param {object} def
  * @returns {object} a device definition for `new Device`
  */

package/types/types.d.ts

@@ -380,9 +380,29 @@ export type PortDef = {
         fixed?: Record<string, number>;
         k0: number;
         alpha: number;
+        bare?: boolean;
     }[];
     /**
-     * with reactions: electrode area per volume,
+     * with reactions: species
+     * on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
+     * shared; a reaction with `bare: true` runs only on the bare fraction θ₀ = 1 − Σθ
+     */
+    surface?: Record<string, {
+        mu0: number;
+        capacity: number;
+        theta0?: number;
+    }>;
+    /**
+     * a capacitance spread through the window (F/m² of
+     * electrode): σ = C (V − zeroCharge − φ) on the port's side, aσ in each node's charge balance; a gate
+     * along a channel, a double layer
+     */
+    capacitance?: {
+        C: number;
+        zeroCharge?: number;
+    };
+    /**
+     * with reactions or a capacitance: electrode area per volume,
      * m²/m³ (1/h for a film of thickness h), or a profile against the device's x
      */
     area?: number | {
@@ -545,6 +565,10 @@ export type Solution = {
         x?: Float64Array;
         area?: Float64Array;
         rates?: Float64Array[];
+        coverage?: Record<string, Float64Array>;
+        bare?: Float64Array;
+        sigma?: Float64Array;
+        charge?: number;
     }[];
     interfaces: {
         left: string;