driftlet 0.9.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; 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 |
+| 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.9.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) |

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,28 +508,26 @@ 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[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
+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.
 
-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
+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)`$.
+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).
 
-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.
+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.
 
 ### An electrode's surface: adsorbates and passive films
 
@@ -538,7 +545,7 @@ ports: [{
   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: '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
   ],
 }]
@@ -546,35 +553,39 @@ ports: [{
 
 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.
+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), 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.
+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 gate along a channel, a double layer
+### 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. Solutions
-report `ports[k].sigma` at each node of the window and the total `ports[k].charge`.
+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₂)
@@ -587,11 +598,9 @@ That's the gradual-channel approximation of a field-effect transistor, exact for
 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.
+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
@@ -599,6 +608,23 @@ below threshold through saturation (second order in the grid); a porous electrod
 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
 
 The two contacts and every port are the device's terminals, named `left`, `right` and by each
@@ -620,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).
 
@@ -774,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

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