driftlet 0.8.0 → 0.10.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, in the [saturation demo](https://markblundeberg.github.io/driftlet/demos/saturation.html#transistor)) | [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.10.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).
 
@@ -145,7 +145,7 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | [![pn junction](demos/screenshots/pn.png)](https://markblundeberg.github.io/driftlet/demos/pn.html) | [![solar cell](demos/screenshots/solar.png)](https://markblundeberg.github.io/driftlet/demos/solar.html) | [![MOS capacitor](demos/screenshots/mos.png)](https://markblundeberg.github.io/driftlet/demos/mos.html) |
 | **pn junction**: quasi-Fermi levels under bias; I–V against Shockley | **Solar cell**: J<sub>sc</sub> and V<sub>oc</sub> against collection theory | **MOS capacitor**: band bending; C–V against ideal theory |
 | [![cyclic voltammetry](demos/screenshots/redox.png)](https://markblundeberg.github.io/driftlet/demos/redox.html) | [![Daniell cell](demos/screenshots/daniell.png)](https://markblundeberg.github.io/driftlet/demos/daniell.html) | [![saturation](demos/screenshots/saturation.png)](https://markblundeberg.github.io/driftlet/demos/saturation.html) |
-| **Cyclic voltammetry**: a Fermi level against a redox level | **Daniell cell**: a real salt bridge, leaking, ion by ion | **Saturation**: Ag \| AgNO₃ \| Ag under a square wave, up to its limiting current |
+| **Cyclic voltammetry**: a Fermi level against a redox level | **Daniell cell**: a real salt bridge, leaking, ion by ion | **Saturation**: Ag \| AgNO₃ \| Ag up to its limiting current, and a thin-film transistor pinching off, against the charge-sheet model |
 | [![impedance](demos/screenshots/impedance.png)](https://markblundeberg.github.io/driftlet/demos/impedance.html) | [![ion-exchange membrane](demos/screenshots/membrane.png)](https://markblundeberg.github.io/driftlet/demos/membrane.html) | [![double layer](demos/screenshots/double-layer.png)](https://markblundeberg.github.io/driftlet/demos/double-layer.html) |
 | **Impedance**: the Warburg arc, and the cell's small-signal response inside | **Ion-exchange membrane**: Donnan steps, ion by ion, against TMS theory | **Double layer**: dilute vs crowded ions, against closed forms |
 | [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) | [![organic solar cell](demos/screenshots/organic.png)](https://markblundeberg.github.io/driftlet/demos/organic.html) | [![perovskite hysteresis](demos/screenshots/perovskite.png)](https://markblundeberg.github.io/driftlet/demos/perovskite.html) |
@@ -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

@@ -421,65 +421,74 @@ with the contact behind it holding the conductor's electrons (see
 ## Internal ports
 
 A port is an outside phase with known levels, like a contact's, attached to a window of nodes
-inside one region instead of at an end. It's the 1D stand-in for whatever feeds or drains a
-species sideways: source and drain grounding a MOS channel, salt injected mid-solution, a
-reference electrode's reservoir.
+inside one region instead of at an end: the 1D stand-in for whatever feeds, drains or charges the
+region sideways. It's a [terminal](#terminals) like a contact (held at `V`, behind `R`, or driven
+by `I`; a reference electrode is a port at `I: 0`), and in its window it does any of these, in
+any combination:
+
+| Field | What it adds | For |
+|---|---|---|
+| `species` | [levels held or exchanged](#levels-held-or-exchanged), per volume | source and drain grounding a channel, salt injected mid-solution, O₂ from the air |
+| `reactions`, `area` | an [electrode spread through the window](#electrodes-spread-through-a-window) | a thin film on a metal, a crevice, a porous electrode |
+| `surface` | [species on that electrode's sites](#an-electrodes-surface-adsorbates-and-passive-films) | adsorbates, a passive film |
+| `capacitance`, `area` | [charge held across a capacitance](#a-capacitance-through-a-window) | a gate along a channel, a double layer |
 
 ```js nocheck
 ports: [{
   name: 'channel',
   region: 'Si',              // name or index
   from: 495e-9, to: 500e-9,  // window, m from the region's left end (default: the whole region)
-  V: 0,                      // the port's terminal voltage (or I, or V and R: see terminals)
-  terminal: 'e-',
-  species: {
-    'e-': 'equilibrium',                         // μ̄ held at V_i = V + offset throughout the window
-    'Na+': { type: 'conductance', G: 1e9, offset: 0.2 }, // source G (V_out − V_i)/(zF) per volume, G in S/m³
-    O2: { type: 'exchange', k: 1e-3, mu: -2e3 },  // neutral: source k (μ_out − μ)/RT per volume, k in mol/(m³·s)
-  },
+  V: 0,                      // or I, or V and R (see terminals)
+  terminal: 'e-',            // the species whose level V is
+  species: { 'e-': 'equilibrium' },
 }]
 ```
 
-Links and offsets are those of contacts, per volume instead of per area: 0 by default only for
-the terminal species, and an absolute `mu` for neutral species. A port is a terminal like a
-contact: held at a voltage, behind a resistance, or driven by a current (a reference electrode
-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 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
-window's level for that species. So `G` decides how the current is shared across the window, not
-how much enters. A small `G`, with the port volts above the window, spreads it evenly, like a
-current source; a large one pins the window near the port's level, and the current enters
-wherever the species is drawn away fastest. At `I: 0` the port still ties that species' level
-together across its window (a large `G` shorts the window for it), so keep such windows narrow.
-
 On a [conductor region](#materials), a port is a wire to the whole conductor: it takes no window,
 only the conductor's carrier, and a conductance link's `G` is per area (S/m², a resistance
 $`R \cdot A`$ to the port's voltage as $`G = 1/(R \cdot A)`$). That's how a floating electrode is tied
 to ground through a resistor.
 
-For example, in a 1D MOS capacitor without generation, inversion electrons can only arrive by
-minority-carrier diffusion from the back contact, which can take weeks. The inversion layer is
-then effectively floating, and its Fermi level is undetermined to within round-off, so no
-steady state can be computed there. A port holding the electrons beside the oxide at the
-channel's potential anchors it, as source and drain would, and the device then shows the
-low-frequency C–V.
+### Levels held or exchanged
+
+```js nocheck
+species: {
+  'e-': 'equilibrium',                                // μ̄ held at V_i = V + offset throughout the window
+  'Na+': { type: 'conductance', G: 1e9, offset: 0.2 }, // source G (V_out − V_i)/(zF) per volume, G in S/m³
+  O2: { type: 'exchange', k: 1e-3, mu: -2e3 },         // neutral: source k (μ_out − μ)/RT per volume, k in mol/(m³·s)
+}
+```
+
+Links and offsets are those of contacts, per volume instead of per area: 0 by default only for
+the terminal species, and an absolute `mu` for neutral species. 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.
+
+A port driven by a current floats to whatever voltage delivers it: with a conductance `G` per
+volume over a window of width $`w`$, about $`I/(G w)`$ above the window's level for that species. So
+`G` decides how the current is shared across the window, not how much enters. A small `G` spreads
+it evenly, like a current source; a large one pins the window near the port's level, and the
+current enters wherever the species is drawn away fastest. At `I: 0` the port still ties that
+species' level together across its window (a large `G` shorts the window for it), so keep such
+windows narrow.
+
+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,
+`{ equation: 'Air = O2', fixed: { Air: muSat }, kf: { water: profile } }`, whose rate is
+$`k_f (1 - c/c_{sat})`$; a profile gives $`k_f`$ its spatial variation ($`D c_{sat}/h^2`$ under a film
+of thickness $`h(x)`$).
+
+A held level can also anchor what nothing else holds. In a 1D MOS capacitor without generation,
+inversion electrons can only arrive by minority-carrier diffusion from the back contact (weeks),
+so the inversion layer's Fermi level is undetermined to within round-off and no steady state can
+be computed. A port holding the electrons beside the oxide, as source and drain would, anchors it,
+and the device 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
+A port can 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
@@ -499,21 +508,122 @@ ports: [{
 
 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`.
+region's species there, and the electrons it takes or gives are the port's current. Held at a
+voltage, the port is 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 (with a double layer, it starts uncharged and
+charges toward it). An electrode that's the device's only path for current is at `I: 0` whatever
+its drive: hold it at `V: 0`, which also fixes the level the water's φ is read against. Per volume of the window a rate is
+`rates[q][j] * area[j]`, and per area of a film's floor (thickness h, `area` 1/h) the rate itself.
+
+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
+above). Where the thickness varies, give the device its [cross-section](#geometry) too, so that ions
+travelling along the film squeeze through where it thins: for a drop on a metal, seen from its
+centre, $`A = 2\pi r\,h(r)`$ with `area` $`1/h(r)`$. The region must be strictly neutral
+($`\varepsilon = 0`$), as in porous-electrode theory: each spot's double layer is below the grid, so
+the reactions can't leave the solution charged (give the port a
+[capacitance](#a-capacitance-through-a-window) for the double layer's charge).
 
 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)`$.
+Wagner–Traud mixed potential of two Butler–Volmer couples.
+
+### 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-4, alpha: 0.5, bare: true }, // the film forms (in minutes)
+    { 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 what passes through a surface is conserved with
+it. It's a monolayer picture: a real passive oxide is nanometres thick, grows, and breaks down
+under chloride, none of which a coverage has.
+
+Cautions:
+- **Keep a film's stability within reason.** Blocking the bare fraction to 1e-3–1e-6 is already
+  a passive metal; far below that ($`\theta_0 \lesssim 10^{-10}`$) the coverage's η barely affects
+  anything and Newton struggles with it (a solution warns).
+- **A film's μ° is a fitted number.** A monolayer given a bulk hydroxide's ΔG°f passivates iron far
+  into neutral water, so choose it to put the passivation where the metal's chemistry does.
+- **Without a double layer, passivation can jump.** With no capacitance the potential follows the
+  kinetics instantly, and when the last active patch covers over, the potential where no current
+  flows can vanish from the active branch: a discontinuity, where a transient stops. Give the port
+  a [capacitance](#a-capacitance-through-a-window) and it's a quick, continuous swing, as on a real
+  electrode.
+
+Validated in test/coverage.test.js: the Langmuir isotherm against the electrode's potential (to
+1e-9), filling against its exponential and its charge $`F\,\Gamma\,\Delta\theta`$ per area of electrode,
+the active–passive curve with blocking exactly $`(1-\theta)`$ times Butler–Volmer, and a steady state
+through a surface intermediate where the transient ends.
+
+### A capacitance through a window
+
+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. Capacitances on overlapping windows add (a channel's top and bottom
+gates). A capacitance alone, driven by a current, only charges: it starts uncharged, `advance()`
+follows it, and `solve()` refuses (there's no steady state, as for a gate contact driven by one).
+
+```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. 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.
+
+### What a solution reports
+
+Each solution's `ports[k]`, as the port has them:
+
+| Field | Contents |
+|---|---|
+| `name`, `V` | the port's name and voltage |
+| `flux[name]`, `current` | what it brings into the device: each species (mol/(m²·s)) and the current (A/m², the charging current included), totals through a [cross-section](#geometry) |
+| `x[j]`, `area[j]` | with reactions or a capacitance: the window's node j (m) and the electrode's area per volume there (m²/m³) |
+| `rates[q][j]` | reaction q's forward rate at node j, mol/(m²·s) of electrode (reaction first, then node) |
+| `coverage[name][j]`, `bare[j]` | with a surface: each species' coverage θ, and the bare fraction θ₀ to full precision |
+| `sigma[j]`, `charge` | with a capacitance: σ per area of electrode (C/m²), and the total the port's side holds |
+
+The arrays are typed (`Float64Array`), so `Array.from` them before mapping to anything but
+numbers. The kit's [`polarization()`](kit.md#polarization-curves-an-evans-diagram) gives each reaction's rate at a spot of the
+electrode with its level moved, an Evans diagram.
 
 ## Terminals
 
@@ -536,7 +646,9 @@ ports: [{ name: 'ref', I: 0, ... },  // a reference electrode: no current, its v
   the voltage floats and is solved for.
 - **`V` and `R`**: a source behind a resistance, $`I = (V - V_{\mathrm{terminal}})/R`$.
 
-At least one terminal must be held at a voltage, or the device's overall level floats. In
+At least one terminal must be held at a voltage, or the device's overall level floats, and if
+one is driven by a current, a held one must pass current (a closed end held at a voltage fixes
+nothing). In
 steady state the terminal currents sum to zero. A contact can be driven by a current only if
 something passes it (a linked species, or a gate's displacement).
 
@@ -690,7 +802,7 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `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 |
+| `ports[k]` | `{ name, V, flux: {name}, current }`: what each internal port brings into the device; an electrode's rates, coverages and charge [as well](#what-a-solution-reports) |
 | `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² (C through a cross-section) |

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
@@ -133,6 +133,11 @@ the SHE level (`sol.phi` with the usual tables' ions).
 
 The example above ends with the left electrode's curve.
 
+An electrode port's surface is held too by default. With `{ surface: 'equilibrium' }` (a fifth
+argument) its coverages are re-equilibrated at each V instead, each species by the reaction that
+makes it from the solution: the steady-state curve, where a passive film's active–passive peak
+shows (`curve.bare` gives the bare fraction along it).
+
 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.

package/docs/numerics.md

@@ -358,7 +358,9 @@ reaction) and that nothing outside feeds ($`w = 0`$ on stretches reached by a co
 the null space of that stoichiometry. A stretch in none of them is fed. So Ag⁺ between silver
 electrodes is fed (Ag⁺ + e⁻ ⇌ Ag(s), the electrons fed by the contacts), and the steady equations
 are solved directly; Fe³⁺ and Fe²⁺ between platinum electrodes aren't, since Fe³⁺ + e⁻ ⇌ Fe²⁺
-conserves the iron whatever the electrons do, so their total is kept by huge steps (below). A
+conserves the iron whatever the electrons do, so their total is kept by huge steps (below). An
+electrode surface's species are columns too, holding $`\Gamma \sum v\,a\,\theta`$, so species fed only
+through one (A⁺ + e⁻ = S, S + e⁻ = B⁻) conserve their total with what the surface holds. A
 floating conductor starts uncharged, with its carrier's level in equilibrium with the first
 reaction on its left face that takes it.
 
@@ -366,7 +368,8 @@ reaction on its left face that takes it.
 
 A port adds a source per volume to the balance rows of the nodes in its window, after every
 other term at those nodes and before the contacts. A held (`'equilibrium'`) level replaces the
-balance row with a Dirichlet row. The port's flux is then that row's residual, read just
+balance row with a Dirichlet row, after every port's other terms (another port's electrode can
+react in the same window). The port's flux is then that row's residual, read just
 before replacement, exactly as at a contact. Conductance and exchange links are linear in
 $`(\bar\mu_{\mathrm{out}} - \bar\mu)`$. Everything stays on the node's own block. A contact's flux
 readout at an end node already includes any port source there, so contact and port fluxes always
@@ -478,8 +481,15 @@ test checks the compact Jacobian column by column on devices that cover every as
     $`C_c = h^3(1+\omega)^2/(\omega(1+2\omega))`$ and $`C_p = h(h+h_1)(h+h_1+h_2)`$; linear after
     backward Euler, scaled by $`h/(2h + h_1)`$. The first step, with no history, is checked by step
     doubling.
+  - The state a first step starts from needn't satisfy the algebraic equations ($`\hat\phi`$ in a
+    strictly neutral material, an interface's unknowns), after a start or a jump; they jump in
+    the first instant. So the history starts from the first step's half step, not from there,
+    and the second step is backward Euler: a predictor through the starting state saw the jump
+    as error that shrank only as fast as the step, and a junction from a sharp boundary at a
+    tight tolerance stepped down into round-off.
   - The error is measured in thermal units over every state potential ($`\hat\phi`$ where defined,
-    each present $`\eta`$, a floating terminal voltage). That includes species far below their
+    each present $`\eta`$, an electrode surface's coverages as their $`\eta`$; a floating terminal's
+    voltage follows from these). That includes species far below their
     largest concentration, such as minority carriers ahead of a diffusion front. Weighting
     them down (a mixed relative/absolute tolerance,
     $`\delta\eta \cdot c/(c + 10^{-10} c_{\mathrm{max}})`$) took a third fewer steps on a pn turn-on,
@@ -627,8 +637,10 @@ was, so storage and neutrality don't see it. Only the fluxes do. But in $`(\hat\
 and neutrality see it as pairs of huge entries that cancel, and round-off in that cancellation, of
 order storage/flux ~ $`h^2/(D \cdot dt)`$ times the range of concentrations, swamps the fluxes that
 fix it: a trace ion beside 3 M KCl lost about ten digits, and Newton stalled. So at each node that
-stays neutral (interior nodes, and edges at `neutral` faces; not the edge of a capacitive or
-pinned face, which holds the face's charge), assembled without storage and neutrality:
+stays neutral (interior nodes, edges at `neutral` faces, and a device's end where its contact is
+closed to every ion and leaves $`\phi`$ alone; not the edge of a capacitive or pinned face, which
+holds the face's charge, nor an end whose contact holds a level), assembled without storage and
+neutrality:
 - rows: the balance of the most abundant charged species (by $`z^2 c`$) becomes
   $`\sum (z_i/z_k) \times`$ each balance, which without storage is current continuity;
 - columns: the unknowns become $`\hat\phi'`$ and $`\eta'_i = \eta_i - z_i \hat\phi`$ (the update is

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.10.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -34,7 +34,9 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   and h⁺). In voltage units the conduction band sits below the valence band. `NaN` marks where a
   species is absent.
 - **Current**: `sol.current` is positive toward +x through the device. `sol.terminals[name]` gives
-  each terminal's `{ V, current }`, current into the device.
+  each terminal's `{ V, current }`, current into the device. Currents, fluxes and amounts are per
+  m² of a planar device; with a `geometry` (spherical, cylindrical or any cross-section A(x)) they
+  are totals through it.
 - **Nothing physical is defaulted.** Every interface between different materials needs an
   alignment (`dipole` or `step`), or `phi: 'neutral'` for a macroscopic model. Every metal face
   next to a dielectric needs its φ law. Every species that doesn't reach a contact needs its
@@ -247,6 +249,103 @@ const dev = new Device(electrode(rest.terminals.left.V + 0.2));
 console.log(`anodic current ${dev.solve().terminals.left.current.toFixed(2)} A/m²`);
 ```
 
+## Template: corrosion under a drop (an electrode spread through a film)
+
+A **port with reactions** is an electrode spread through a window of a region: a metal under a
+thin film of water, a crevice's walls, a porous electrode. Its `terminal` is the metal's carrier,
+`area` the electrode's area per volume of the window (1/h under a film h thick), and each
+reaction is Butler–Volmer per area, as at a face. The region must be strictly neutral (ε = 0); a
+`capacitance` adds the double layer. A **`geometry`** gives the device a cross-section A(x): here
+x is the radius of a drop seen from its centre, A = 2πr·h(r), and every current and amount becomes
+a total through it (A, mol), not per m².
+
+```js
+import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
+import { aqueous, polarization } from 'driftlet/kit';
+
+// Salt water on iron: a drop 3 mm across. The iron dissolves and reduces O₂, which comes in from
+// the air through the drop's top, fastest at the thin rim: the centre corrodes, the rim doesn't.
+const T = 298.15, RT = GAS_CONSTANT * T, R = 3e-3, h0 = 1e-3, cO2 = 0.26, D = 2e-9;
+const lib = aqueous(['Na+', 'Cl-', 'Fe2+', 'OH-', 'H+'], { epsr: 0 }); // strictly neutral water
+lib.species.push({ name: 'O2', z: 0, cRef: 1000 }, { name: 'e-', z: -1 }); // e⁻: the iron's, in no material
+lib.materials.water.species.O2 = { D, mu0: 16.4e3 };
+const r = Array.from({ length: 61 }, (_, j) => (j / 60) * R);
+const h = r.map((x) => Math.max(h0 * (1 - (x / R) * (x / R)), 0.02 * h0)); // the drop's height
+const dev = new Device({
+  T,
+  species: lib.species,
+  materials: lib.materials,
+  geometry: { area: { x: r, values: r.map((x, j) => 2 * Math.PI * x * h[j]) } }, // ions squeeze through the thin rim
+  regions: [{ name: 'drop', material: 'water', length: R, c0: { 'Na+': 500, 'Cl-': 500 + 2e-6, 'Fe2+': 1e-6, 'OH-': 1e-4, 'H+': 1e-4, O2: cO2 } }],
+  contacts: { left: { phi: 'neutral' }, right: { phi: 'neutral' } }, // closed: the centre, and the rim
+  bulkReactions: [
+    { equation: 'H+ + OH- = H2O', fixed: { H2O: -237.129e3 }, kf: { water: 1.4e8 } },
+    // O₂ from the air through the drop: a rate k_f (1 − c/c_sat), k_f = D c_sat/h² (not a port's
+    // exchange link, whose rate is linear in μ rather than c)
+    { equation: 'Air = O2', fixed: { Air: 16.4e3 + RT * Math.log(cO2 / 1000) }, kf: { water: { x: r, values: h.map((y) => (D * cO2) / (y * y)) } } },
+  ],
+  ports: [{
+    name: 'iron', region: 'drop', terminal: 'e-',
+    V: 0, // the only metal and the only path for current, so it passes none: held, it fixes the level φ is read against
+    area: { x: r, values: h.map((y) => 1 / y) }, // m² of iron per m³ of water
+    capacitance: { C: 0.2, zeroCharge: -0.4 }, // the double layer: the potential moves continuously
+    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.129e3 }, k0: 3e-9, alpha: 0.125 },
+    ],
+  }],
+  grid: { hmin: 5e-6, hmax: 60e-6, ratio: 1.2 },
+});
+const sol = dev.advance(600); // ten minutes
+const iron = sol.ports[0], last = iron.x.length - 1;
+// rates[q][j]: reaction q at node j of the window, forward, mol/(m²·s) of iron; anodic current +
+const anodic = (j) => 2 * FARADAY * -iron.rates[0][j] - 4 * FARADAY * iron.rates[1][j];
+console.log(`iron at ${(iron.V - sol.phi[0]).toFixed(3)} V against the water at the centre (SHE, with table μ°)`);
+console.log(`net current on the iron: ${anodic(0).toFixed(2)} A/m² at the centre, ${anodic(last).toFixed(2)} A/m² at the rim`);
+// The Evans diagram at the centre: each reaction's current with the iron's level moved, the water held.
+const levels = [-0.55, -0.5, -0.45, -0.4].map((v) => v + sol.phi[0]);
+const evans = polarization(dev, sol, { port: 'iron', x: 0 }, levels);
+for (const rx of evans.reactions) console.log(`${rx.equation}: ${Array.from(rx.current, (i) => i.toFixed(2)).join(', ')} A/m²`);
+```
+
+On an electrode's surface, species can take its sites (`surface: { name: { mu0, capacity } }`,
+Langmuir coverages), and a reaction with `bare: true` runs only on bare metal: a passive film
+(docs/device.md, "An electrode's surface").
+
+## Template: a thin-film transistor (a capacitance along a channel)
+
+A **port with a `capacitance`** holds charge σ = C (V − zeroCharge − φ) per area of electrode
+along its window, balanced by the region (Gauss's law, or neutrality at ε = 0): a gate along a
+channel, a porous electrode's double layer. In 1D a field-effect transistor is its channel, x from
+source to drain, with the gate spread along it: the gradual-channel approximation, exact for a thin
+film until it pinches off.
+
+```js
+import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
+
+const T = 300, VT = (GAS_CONSTANT * T) / FARADAY;
+const t = 20e-9, L = 10e-6, W = 100e-6, C = 1e-3, mu = 1e-3; // film, length, width (m); F/m² of gate; m²/(V·s)
+const tft = (Vg, Vd) =>
+  new Device({
+    T,
+    species: [{ name: 'e-', z: -1, cRef: 46 }], // an undoped film's electrons (N_c 2.8e19 cm⁻³)
+    materials: { film: { epsr: 0, species: { 'e-': { D: mu * VT, mu0: 0 } } } }, // ε = 0: F·n·t balances σ
+    regions: [{ name: 'channel', material: 'film', length: L }],
+    contacts: {
+      left: { V: 0, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'neutral' }, // source
+      right: { V: Vd, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'neutral' }, // drain
+    },
+    ports: [{ name: 'gate', region: 'channel', V: Vg, area: 1 / t, capacitance: { C, zeroCharge: 0.3 } }],
+    grid: { hmin: L / 2000, hmax: L / 100, ratio: 1.05 }, // fine at the drain, where it pinches off
+  });
+// The output characteristic at V_G = 2 V: linear, then saturating past V_D ≈ V_G − 0.3 V.
+for (const Vd of [0.1, 0.5, 1, 1.5, 2, 3]) {
+  const sol = tft(2, Vd).solve();
+  const I = -sol.current * t * W; // sol.current is per m² of the film's section
+  console.log(`V_D ${Vd.toFixed(1)} V: I_D ${(I * 1e6).toFixed(2)} µA, σ at the drain ${(sol.ports[0].sigma.at(-1) * 1e3).toFixed(3)} mC/m²`);
+}
+```
+
 ## Template: a transient, with a pulse injected sideways
 
 A **port** feeds a window of nodes inside a region from the side (a point contact, an injector,
@@ -319,9 +418,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.10.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {
@@ -29,6 +29,7 @@
   "scripts": {
     "test": "node --test",
     "bench": "node bench/bench.js",
+    "hard": "node bench/hard.js",
     "smoke": "node tools/smoke.js",
     "shots": "node tools/shots.js",
     "prepublishOnly": "npm test && npm run types",