driftlet 1.1.1 → 1.2.1

package/README.md

@@ -56,7 +56,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@1.1.1/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@1.2.1/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).
 

package/docs/conventions.md

@@ -133,8 +133,8 @@ A contact is an interface with an **outside phase** whose levels are known, like
 with a fully known node. The outside phase's charged levels form a rigid ladder,
 $`V_i = V + \mathtt{offset}_i`$, which the external circuit slides by the **terminal voltage** $`V`$
 (the voltage of a named terminal species). The laws joining it to the device (equilibrium,
-blocked, conductance; and for $`\phi`$, bulk, neutral, capacitive, dipole) are the same as at
-internal faces. Reactions sit at faces between regions: an electrode is a conductor region with
+blocked, conductance, exchange, velocity; and for $`\phi`$, bulk, neutral, capacitive, pinned)
+are those of internal faces, with the outside phase as the other side. Reactions sit at faces between regions: an electrode is a conductor region with
 reactions at its face.
 
 - **Species in equilibrium** with the outside phase sit at $`V_i = V + \mathtt{offset}_i`$. The

package/docs/data.md

@@ -25,7 +25,10 @@ The data are 25 °C's, and the material says so (`T: 298.15`): a device at anoth
 warns that they don't hold there. Its μ° (so equilibrium constants and electrode potentials),
 permittivity and diffusivities would all move: $`K_w`$ by ~6× between 6 and 25 °C. Scaling them
 (μ° by the standard entropies, ε, D by water's viscosity) is planned, not done. Where only
-transport between solutions of the same ions matters (a membrane's channels), μ° cancels.
+transport between solutions of the same ions matters (a membrane's channels), μ° cancels; if the
+D don't matter either, taking the data as another temperature's is a fair approximation, made
+by setting the material's `T` (the cell and axon demos do, having checked that D scaled by
+T/η moves nothing they show).
 
 | Ion | z | D (10⁻⁹ m²/s) | $`\mu^\circ`$ (kJ/mol) |
 |---|---|---|---|

package/docs/device.md

@@ -516,8 +516,8 @@ background carriers do). A solution against a charged end region (an ion exchang
 its own material, `bath: { c, material: 'water' }`: its composition is then neutral by itself, its
 levels are that material's, and the end node takes them through a Donnan step.
 
-**`phi`**, required whenever any species or reaction connects at the contact (default
-`'neutral'`):
+**`phi`**, required whenever any species connects at the contact (default `'neutral'`, or
+`'bulk'` with a bath):
 - `'bulk'`: the end node is plain bulk, locally neutral, with no double layer at the contact
   (ohmic contacts, baths). The outside takes whatever surface charge that needs. A double layer
   or depletion region that reaches it is cut off there (σ 58% low for a crowded layer 5 Debye
@@ -872,7 +872,8 @@ advance it, `advance()` and `step()` do.
 
 `{ hmin, hmax, ratio = 1.2, minCells = 8 }`, per device, overridable per region. With no grid
 options at all, each region is graded from `hmin` = 1/1000 to `hmax` = 1/20 of its length. Cells grow
-geometrically from `hmin` at both ends of each region up to `hmax`, scaled to fit exactly. Each
+geometrically from `hmin` at both ends of each region up to `hmax`, scaled to fit exactly
+(`hLeft` and `hRight` set one end's size instead, for a region fine at one end only). Each
 region boundary becomes a pair of nodes at the same x, one per side. The grid is never refined
 automatically. If a double layer that the model resolves is coarser than the local Debye
 length, the solution's `warnings` say so. That's a floor, not an accuracy: a strongly polarised
@@ -1061,12 +1062,12 @@ console.log(`${run.steps} steps; I(0.01 s) ≈ ${run.trace.current[run.trace.t.f
 | `ports[k]` | `{ name, V, flux: {name}, current }`: what each internal port brings into the device (an electrode's `flux` is of what its reactions make and use in the solution, its carrier's being outside); an electrode's rates, coverages and charge [as well](#what-a-solution-reports) |
 | `interfaces[f]` | `{ left, right, dipole, sheetCharge, D, N: {name}, rates, links: {name} }`: the names of the regions the face joins, what crosses it by its links, each face reaction's rate (mol/(m²·s)), and how each species that crosses it does; for those crossing by permeability, `oneWay: { name: [toward +x, toward −x] }`, the one-way fluxes whose difference is `N` (Ussing's unidirectional fluxes) |
 | `bulkReactions[k]` | `{ rate, forward, nu, regions, total }`: each bulk reaction's net forward rate at every node (mol/(m³·s), `NaN` where it doesn't run), its one-way forward rate (the backward is `forward − rate`), what one forward reaction makes of each species (`nu`, negative for what it consumes), 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) |
+| `charge` | total charge in the device, C/m² (C through a cross-section): its regions' space charge and its faces' sheet charges, not the charge on a capacitive contact's or port's plates, so under a gate's bias it's the gate's opposite |
 | `conservation` | per species stretch: amount, reference, intake through contacts, and drift, relative: (amount − reference − intake) over the largest of them |
 | `warnings` | e.g. unresolved double layers, conventions a statistics model relies on, a material's data for another temperature, and for a failed solve, why (a driven current it can't pass, where the system is nearly singular). A failed steady solve's state isn't a solution, so the warnings about a solution's accuracy (the grid, double layers, space charge reaching a contact) are left out of it |
 | `converged`, `iterations`, `steps`, `substeps`, `history`, `time`, `T` | solver bookkeeping, and the temperature |
 | `steady` | whether this is a converged steady state (from `solve()`), not a transient's: what `check()` in the kit decides its checks by |
-| `done`, `rejected`, `trace` | from `advance()`: whether `tEnd` was reached; rejected steps; `{ t, current, voltage }` per accepted step |
+| `done`, `rejected`, `trace` | from `advance()`: whether `tEnd` was reached; rejected steps; `{ t, current, voltage }` per accepted step, and `probes` if asked |
 
 A stretch is a run of regions in which a species is present and connected. Its `drift`
 compares its amount with the reference amount plus everything that came in through the

package/docs/numerics.md

@@ -725,13 +725,19 @@ the terms that cancel:
     charging a capacitance (a gate, a port's capacitance) is the same, its charge in place of an
     amount; and an electrode port's reactions draw on what the electrode holds, its charge
     $`Q/(zF)`$ a column of its own under a current, so a port at no current reducing a closed
-    M⁺ (M⁺ + e⁻ = M(s)) keeps M⁺ + Q/F, or with no capacitance, M⁺ alone. At any other current such a terminal only stores what comes in, which has no steady
-    state, and the solve says so at once.
+    M⁺ (M⁺ + e⁻ = M(s)) keeps M⁺ + Q/F, or with no capacitance, M⁺ alone. Whatever such a
+    terminal both passes and stores is kept together, as its current counts both: a capacitive
+    port or contact at no current that passes K⁺ keeps $`n_K + Q/F`$ (a contact's Q its
+    displacement $`D_\text{in}`$), and two floating electrodes sharing a closed Fe³⁺ keep the iron
+    with both their charges, the law in one's circuit row moving with the other's voltage too.
+    At any other current such a terminal only stores what comes in, which has no steady state,
+    and the solve says so at once.
   - an **immobile** combination (trap states X⁰ and X⁻ under e⁻ + X⁰ = X⁻, with D = 0) keeps it
     node by node, since nothing carries it anywhere, as do an electrode's surface species
     (adsorbates that only turn into each other keep their total on every site), its row local,
-    one per node in its own block. (The null space is taken with the immobile columns first, so
-    that these come out apart from the combinations that move.) A combination of immobile
+    one per node in its own block, a coverage counted as the sites it fills per volume,
+    $`\Gamma a \theta`$, beside the concentrations. (The null space is taken with the immobile and
+    surface columns first, so that these come out apart from the combinations that move.) A combination of immobile
     stretches with a moving one (the electrons the traps hold, $`e^- - X^0`$, in a closed film) is
     an amount like any other, its immobile parts summed over their nodes;
   - a **floating metal** keeps the charge on its faces, its sheets' displacement.
@@ -796,7 +802,9 @@ the terms that cancel:
   rows, a pin like an amount's, chosen by the same elimination and ahead of the amounts: the slowest
   reaction first, and a row of one of its own species where one is left, never one picked by where
   the species are listed (the rows had differed with the species reversed, and an electrode's
-  equilibrium solved in one listing and failed in the other). The combinations come from the null
+  equilibrium solved in one listing and failed in the other). A reaction that changes its
+  combination only through immobile species needs none: its rate already stands alone in their
+  balance at the face's node. The combinations come from the null
   space with that reaction's row left out, any conserved amount added to one being as good (its
   summed balance vanishes too), so that one can be found with a row left to take: silver's e⁻ − Fe³⁺
   beside a closed iron couple whose affinity had Fe³⁺'s row is e⁻ + Fe²⁺ with the iron added. Never

package/docs/reliability.md

@@ -141,6 +141,29 @@ its true residual, blocked species held flat in steady solves, continuations for
 and for light, and Newton refining its solves where a factorisation loses a mode, with an exact
 $`J \cdot v`$.
 
+## Conserved: the law sweep
+
+A steady solve replaces one redundant equation per conserved combination with the combination's
+amount (see [numerics](numerics.md#the-steady-system)). A combination left out, or weighed wrongly,
+gives a state that converges and is steady but holds the wrong amounts, which only a transient
+from the same start shows. `npm run lawsweep` builds 810 small devices from the features at the
+edges of that bookkeeping: a floating, resistive or held electrode, with or without a
+capacitance, with adsorbates or an immobile species that adsorbs; a second floating electrode
+or a membrane capacitor; a capacitive or ion-passing contact at no current; a face that blocks
+an ion or makes an immobile species. Each is solved directly and run as a transient for 1e6 s,
+and where the transient converged, finished and moves no further over 100× as long, the two
+must agree on every species' amount, every surface's sites and every floating terminal's
+voltage.
+
+Every reaction starts at its equilibrium. On 1.2.1, 675 devices are built (135 combinations
+repeat others); 579 agree, and 83 transients fail to converge. In the other 13 the transient
+is the one that's off: it loses a conserved K⁺ total in proportion to its tolerance (3e-5 of it
+at tol 1e-9) when a capacitive contact, a membrane capacitor and a held electrode share the
+device, where the steady solve keeps it to round-off. The sweep found its first law the day it
+was written (an immobile species adsorbing on an electrode over part of its region); Gemini 4
+Argon's review found nine more by hand (one through a device it suggested), each now in
+`test/laws.test.js`.
+
 ## Hard cases
 
 `npm run hard` keeps a corpus of named cases that were hard once (sharp 3 M | 1 µM junctions on

package/docs/statistics.md

@@ -44,6 +44,7 @@ most one model.
 
 | Model | Species | $`c(\zeta)`$ | Parameters |
 |---|---|---|---|
+| `ideal` | any | $`c_{\mathrm{ref}} e^\zeta`$, the default, named only to say so | none |
 | `fermi-dirac` | any, each independently | $`c_{\mathrm{ref}} \mathcal{F}_{1/2}(\zeta)`$ (3D band); $`c_{\mathrm{ref}} \ln(1 + e^\zeta)`$ with `order: 0` (2D) | `order`: 1/2 (default) or 0 |
 | `lattice` | any, sharing sites | $`c_a = c_{\mathrm{max}} w_a / (1 + \sum w)`$, $`w_a = (c_{\mathrm{ref},a}/c_{\mathrm{max}}) e^{\zeta_a}`$ | `cMax`, site density, mol/m³ |
 | `redlich-kister` | one | on its own sites: $`\zeta = \ln(x/(1-x)) + \ln(c_{\mathrm{max}}/c_{\mathrm{ref}}) + (g(x) - g(0))/RT`$, $`x = c/c_{\mathrm{max}}`$ | `cMax`; `A`, J/mol |

package/llms.txt

@@ -30,9 +30,9 @@ materials, insertion hosts), data.md and reliability.md (what's validated, and t
 From a CDN, pin the version you tested against:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -219,9 +219,9 @@ a CDN needs a long virtual-time budget, 30 s.)
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.1/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.1/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for semiconductors, electrochemistry and nerves, fast enough for live web demos",
   "type": "module",
   "exports": {
@@ -33,6 +33,7 @@
     "stress": "node bench/stress.js",
     "smoke": "node tools/smoke.js",
     "shots": "node tools/shots.js",
+    "lawsweep": "node tools/lawsweep.js",
     "prepublishOnly": "npm test && npm run types",
     "types": "rm -rf types && npx -y -p typescript@5 tsc --allowJs --declaration --emitDeclarationOnly --target es2022 --module nodenext --moduleResolution nodenext --outDir types src/index.js src/kit.js src/plot.js"
   },

package/src/channels.js

@@ -3,6 +3,7 @@
 
 import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
+import { bernoulli } from './bernoulli.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -22,9 +23,10 @@ const HH_T = 273.15 + 6.3;
 
 // The GHK current (outward, A/m²) of an ion at unit permeability, at voltage V (inside − outside).
 export function ghkCurrent(z, inside, outside, V, T) {
+  // zF u (c_in − c_out e^−u)/(1 − e^−u) = zF (c_in B(−u) − c_out B(u)), B(x) = x/(eˣ − 1): finite
+  // at any u (the plain form was ∞/∞ past u = −710)
   const u = (z * V * FARADAY) / (GAS_CONSTANT * T);
-  if (Math.abs(u) < 1e-9) return z * FARADAY * (inside - outside);
-  return (z * FARADAY * u * (inside - outside * Math.exp(-u))) / -Math.expm1(-u);
+  return z * FARADAY * (inside * bernoulli(-u) - outside * bernoulli(u));
 }
 
 /**
@@ -59,6 +61,8 @@ export function hodgkinHuxley({ inside, outside, T, g = {}, leak = 'Cl-', leakZ
   // T sets the gates' rates, so it must be the device's: never defaulted (their 6.3 °C, under a body-temperature device, doubled a spike's peak, silently).
   need(num(T) && T > 0, `hodgkinHuxley: T must be the device's temperature in K (their own experiments were at 279.45 K, 6.3 °C), got ${T}`);
   need(num(at), `hodgkinHuxley: at must be a voltage (V), got ${at}`);
+  checkOptions('hodgkinHuxley: g', g, ['Na', 'K', 'leak']);
+  checkOptions('hodgkinHuxley: names', names, ['Na', 'K']);
   const G = { Na: 1200, K: 360, leak: 3, ...g };
   const Na = names.Na ?? 'Na+', K = names.K ?? 'K+';
   const q10 = Math.exp(Math.log(3) * ((T - HH_T) / 10)); // Q₁₀ = 3
@@ -79,9 +83,10 @@ export function hodgkinHuxley({ inside, outside, T, g = {}, leak = 'Cl-', leakZ
     };
   }
   need(inside && outside && typeof inside === 'object' && typeof outside === 'object', 'hodgkinHuxley: give inside and outside concentrations (mol/m³) by species name (or, for a membrane port, its area)');
-  const P = (name, z, gval, what) => {
+  const P = (name, z, key, what) => {
+    const gval = G[key];
     need(num(inside[name]) && inside[name] > 0 && num(outside[name]) && outside[name] > 0, `hodgkinHuxley: give ${name}'s concentration inside and outside (mol/m³), for its ${what}`);
-    need(num(gval) && gval > 0, `hodgkinHuxley: g.${what} must be a conductance > 0 (S/m²), got ${gval}`);
+    need(num(gval) && gval > 0, `hodgkinHuxley: g.${key} must be a conductance > 0 (S/m²), got ${gval}`);
     const E = ((GAS_CONSTANT * T) / (z * FARADAY)) * Math.log(outside[name] / inside[name]);
     need(Math.abs(at - E) > 1e-4, `hodgkinHuxley: ${name}'s Nernst level, ${(E * 1e3).toFixed(1)} mV, is at the calibration voltage; choose another 'at'`);
     return (gval * (at - E)) / ghkCurrent(z, inside[name], outside[name], at, T);
@@ -90,9 +95,9 @@ export function hodgkinHuxley({ inside, outside, T, g = {}, leak = 'Cl-', leakZ
   return {
     gates,
     species: {
-      [Na]: { type: 'permeability', P: P(Na, 1, G.Na, 'Na channels'), gates: { m: 3, h: 1 } },
-      [K]: { type: 'permeability', P: P(K, 1, G.K, 'K channels'), gates: { n: 4 } },
-      [leak]: { type: 'permeability', P: P(leak, leakZ, G.leak, 'leak') },
+      [Na]: { type: 'permeability', P: P(Na, 1, 'Na', 'Na channels'), gates: { m: 3, h: 1 } },
+      [K]: { type: 'permeability', P: P(K, 1, 'K', 'K channels'), gates: { n: 4 } },
+      [leak]: { type: 'permeability', P: P(leak, leakZ, 'leak', 'leak') },
     },
   };
 }

package/src/checks.js

@@ -86,7 +86,7 @@ export function check(device, sol, { refine = true, tol = 1e-2, order = true } =
     if (steady && refine && order && model.species.length > 1) items.push(orderCheck(device, sol, ledger.details.gross));
     // A transient's answer depends on its whole history (and on drives set along the way), so
     // only a run of its own on a finer grid can check it.
-    else if (refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
+    if (!steady && refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
   }
 
   const ok = sol.converged && items.every((it) => it.ok !== false);
@@ -96,7 +96,7 @@ export function check(device, sol, { refine = true, tol = 1e-2, order = true } =
 }
 
 // The units of totals through the cross-section: per m² of a planar device, or whole.
-const unitsOf = (model) => (model.geometry.type === 'planar' ? { rate: 'mol/(m²·s)', current: 'A/m²', charge: 'C/m²' } : { rate: 'mol/s', current: 'A', charge: 'C' });
+const unitsOf = (model) => (model.geometry.type === 'planar' ? { rate: 'mol/(m²·s)', current: 'A/m²', charge: 'C/m²', amount: 'mol/m²' } : { rate: 'mol/s', current: 'A', charge: 'C', amount: 'mol' });
 
 // Each species' steady ledger: in through the terminals, made by the reactions. Rates in
 // mol/(m²·s) (mol/s if not planar), positive into the device or made.
@@ -262,6 +262,8 @@ function gridCheck(device, sol, tol, gross) {
       const out = { ratio: Math.sqrt(g.ratio ?? 1.2), minCells: 2 * (g.minCells ?? 8) };
       if (g.hmin !== undefined) out.hmin = g.hmin / 2;
       if (g.hmax !== undefined) out.hmax = g.hmax / 2;
+      if (g.hLeft !== undefined) out.hLeft = g.hLeft / 2;
+      if (g.hRight !== undefined) out.hRight = g.hRight / 2;
       return { ...reg, grid: out };
     }),
   };
@@ -334,7 +336,7 @@ function gridCheck(device, sol, tol, gross) {
     summary:
       `on a grid twice as fine (${sol.x.length} → ${other.x.length} nodes), the largest change is ${worst.what}, ${sig(worst.a, 5)} → ${sig(worst.b, 5)} ${worst.unit} ` +
       `(${sig(worst.rel, 2)}${ok ? '' : `, over ${sig(tol, 1)}: refine the grid (hmin, hmax), most likely where profiles are steepest`})`,
-    details: { diffs, nodes: [sol.x.length, other.x.length] },
+    details: { diffs, nodes: [sol.x.length, other.x.length], grids: fine.regions.map((reg) => reg.grid) }, // (grids: the finer one's, by region)
   };
 }
 
@@ -374,7 +376,7 @@ function orderCheck(device, sol, gross) {
   const vol = model.grid.vol, amount = (s, name) => s.x.reduce((m, _, g) => m + (Number.isFinite(s.c[name][g]) ? vol[g] * s.c[name][g] : 0), 0);
   const amounts = model.species.map((sp) => [sp.name, amount(a, sp.name), amount(b, sp.name)]);
   const most = Math.max(0, ...amounts.map(([, x, y]) => Math.max(Math.abs(x), Math.abs(y))));
-  for (const [name, x, y] of amounts) diffs.push({ what: `${name} amount`, a: x, b: y, rel: Math.abs(y - x) / (1e-6 * Math.max(Math.abs(x), Math.abs(y)) + 1e-12 * most), unit: 'mol/m²' });
+  for (const [name, x, y] of amounts) diffs.push({ what: `${name} amount`, a: x, b: y, rel: Math.abs(y - x) / (1e-6 * Math.max(Math.abs(x), Math.abs(y)) + 1e-12 * most), unit: unitsOf(model).amount });
   // Agreeing to near round-off (a µV, a millionth of an amount): ok. Within a thousand times that
   // (a mV, a thousandth), enough for any plot, but a weakly held part of one solve not quite
   // steady: look. Beyond: one of them isn't a steady state.

package/src/data.js

@@ -185,7 +185,7 @@ export function trap(lib, { density, tauN, tauP, n1, charge = 'acceptor', name =
   if (typeof name !== 'string' || !/^[A-Za-z][\w()]*$/.test(name)) fail(`trap: name must be a plain name for the trap (its states are name0 and name- or name+), got ${JSON.stringify(name)}`);
   const RT = GAS_CONSTANT * T, cRefE = el.cRef ?? lib.species.find((sp) => sp.name === 'e-')?.cRef;
   const cRefH = ho.cRef ?? lib.species.find((sp) => sp.name === 'h+')?.cRef;
-  const ni = Math.sqrt(cRefE * cRefH * Math.exp(-(ho.mu0 - el.mu0) / RT));
+  const ni = Math.sqrt(cRefE * cRefH * Math.exp(-(ho.mu0 + el.mu0) / RT));
   const half = n1 === undefined ? ni : pos(n1, 'n1 must be the electron density that half-fills the trap > 0 (mol/m³)');
   // The filled state's μ° sits an electron's μ at n₁ above the empty one's: half full at n = n₁.
   const [empty, full] = charge === 'acceptor' ? [`${name}0`, `${name}-`] : [`${name}+`, `${name}0`];

package/src/describe.js

@@ -265,7 +265,7 @@ export function describe(def) {
     lines.push(`  port ${port.name}: ${drive(p, model.geometry.type === 'planar')}, in ${regions[port.region].name}`);
     // an electrode spread through the window
     if (port.reactions.length) lines.push(`    an electrode (its ${species[port.terminal].name} at the port's level), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} of it per m³, reacting:`);
-    for (const rx of p.reactions ?? []) lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${rx.alpha}${rx.bare ? ', on bare metal' : ''}`);
+    (p.reactions ?? []).forEach((rx, j) => lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${port.reactions[j].alpha}${rx.bare ? ', on bare metal' : ''}`)); // (α as used: 0.5 if not given)
     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)`);
   });

package/src/device.js

@@ -18,7 +18,7 @@ export { DeviceError };
 const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange', 'velocity']);
 const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance', 'permeability']);
 const PHI_LINK_TYPES = new Set(['bulk', 'neutral', 'capacitive', 'pinned']);
-const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells'];
+const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells', 'hLeft', 'hRight'];
 // The fields of each kind of species link (to an outside phase, or across a face).
 const LINK_FIELDS = {
   blocked: ['type'],
@@ -704,7 +704,7 @@ export function nextBreakpoint(src, t) {
   if (src.value !== undefined) return Infinity;
   const { t: ts, repeat } = src, n = ts.length;
   if (!repeat) {
-    for (let k = 0; k < n; k++) if (ts[k] > t * (1 + 1e-12) + 1e-300) return ts[k];
+    for (let k = 0; k < n; k++) if (ts[k] > t + 1e-12 * Math.abs(t) + 1e-300) return ts[k]; // (t·(1 + ε) is below t for t < 0)
     return Infinity;
   }
   const T = ts[n - 1] - ts[0], cycle = Math.floor((t - ts[0]) / T);
@@ -1255,7 +1255,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
       }
       if (link.type === 'conductance') {
         // Ohmic exchange with an outside reservoir at V_i = V + offset: J = G·(V_out − V_i).
-        need(species[i].z !== 0, `${lpath}: a conductance link needs a charged species`);
+        need(species[i].z !== 0, `${lpath}: a conductance link needs a charged species (a neutral one exchanges by { type: 'exchange', k, mu })`);
         const offset = link.offset ?? (terminal === i ? 0 : undefined);
         need(offset !== undefined, `${lpath}.offset: give V_i − V_terminal (V) of the outside reservoir`);
         links[i] = { type: 'conductance', G: positive(link.G, `${lpath}.G`), offset: finite(offset, `${lpath}.offset`) };
@@ -1283,7 +1283,6 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
         links[i] = { type: 'exchange', k: positive(link.k, `${lpath}.k (mol/(m²·s))`), mu: finite(link.mu, `${lpath}.mu (the outside μ, J/mol)`) };
         continue;
       }
-      if (link.type === 'conductance') need(species[i].z !== 0, `${lpath}: a neutral species exchanges by { type: 'exchange', k, mu }`);
       if (link.type === 'equilibrium') {
         // In equilibrium with the outside phase, whose levels are known: a Dirichlet condition.
         if (species[i].z === 0) {

package/src/devices.js

@@ -5,7 +5,11 @@
 import { AVOGADRO, FARADAY, GAS_CONSTANT, units } from './constants.js';
 import { photogeneration } from './sources.js';
 import { drive } from './stack.js';
-import { checkOptions } from './errors.js';
+import { DeviceError, checkOptions, shown } from './errors.js';
+
+const need = (ok, message) => {
+  if (!ok) throw new DeviceError(message);
+};
 
 const m3 = (x) => x / AVOGADRO, eV = units.eV;
 
@@ -35,6 +39,8 @@ const P = {
  */
 export function perovskiteCell({ V = 1.2, light = 1, bulkSRH = true } = {}) {
   checkOptions('perovskiteCell', arguments[0], ['V', 'light', 'bulkSRH']);
+  need(Number.isFinite(light) && light >= 0, `perovskiteCell: light must be the illumination in suns, ≥ 0, got ${shown(light)}`);
+  need(typeof bulkSRH === 'boolean', `perovskiteCell: bulkSRH must be true or false, got ${shown(bulkSRH)}`);
   const { T } = P, VT = (GAS_CONSTANT * T) / FARADAY;
   const ni = Math.sqrt(P.gc * P.gv) * Math.exp(-(P.Ec - P.Ev) / (2 * VT));
   const n0 = P.gc * Math.exp((P.EcE + VT * Math.log(P.dE / P.gcE) - P.Ec) / VT); // the perovskite's n at the TiO₂'s Fermi level
@@ -124,6 +130,8 @@ export const PEROVSKITE_SCANS = Object.freeze({
  * @param {number} turn s
  */
 export function hysteresis(trace, turn) {
+  need(trace && trace.t?.length > 0 && trace.voltage?.length === trace.t.length && trace.current?.length === trace.t.length, 'hysteresis: give a trace { t, voltage, current } (an advance()\'s, say)');
+  need(Number.isFinite(turn) && turn > trace.t[0] && turn < trace.t[trace.t.length - 1], `hysteresis: turn must be the time the scan turns, inside the trace (${shown(trace.t[0])} to ${shown(trace.t[trace.t.length - 1])} s), got ${shown(turn)}`);
   const out = {};
   for (const [name, on] of [['rev', (t) => t <= turn], ['fwd', (t) => t >= turn]]) {
     const pts = [];

package/src/equation.js

@@ -79,14 +79,21 @@ export function stoichiometry(text, path = 'equation') {
  */
 export function faceSides(terms, left, right, fixed, path) {
   const sides = { left: {}, right: {} };
-  const put = (side, name, nu) => (sides[side][name] = (sides[side][name] ?? 0) + nu);
   const fixedSide = right.conductor && !left.conductor ? 'right' : 'left';
+  const signs = {};
+  const put = (side, name, nu) => {
+    const key = `${side}:${name}`;
+    if (signs[key] !== undefined && signs[key] !== Math.sign(nu)) fail(`${path}: '${name}' (${side}) appears on both sides of the equation; give the net reaction`);
+    signs[key] = Math.sign(nu);
+    sides[side][name] = (sides[side][name] ?? 0) + nu;
+  };
   for (const t of terms) {
-    if (fixed?.[t.name] !== undefined) {
+    // (a species the side holds is that species, given in fixed or not, as for bulk reactions)
+    const inL = left.holds(t.name), inR = right.holds(t.name);
+    if (!inL && !inR && fixed?.[t.name] !== undefined) {
       put(fixedSide, t.name, t.nu);
       continue;
     }
-    const inL = left.holds(t.name), inR = right.holds(t.name);
     if (inL && inR) {
       fail(
         `${path}: '${t.name}' is in both '${left.name}' and '${right.name}', so say which side: ` +
@@ -177,6 +184,10 @@ export function level(sol, halfReaction, { standard = false } = {}) {
     else fail(`level: '${t.name}' is neither a species of the solution nor in the half-reaction's fixed`);
   }
   if (nuE === 0) fail(`level: ${JSON.stringify(equation)} has no net electrons`);
+  // (unbalanced, its level wouldn't move with φ as a level must)
+  const z = Object.fromEntries((sol.species ?? []).map((sp) => [sp.name, sp.z]));
+  const charge = terms.reduce((q, t) => q + t.nu * (t.name === 'e-' ? -1 : fixed[t.name] !== undefined ? 0 : (z[t.name] ?? NaN)), 0); // (fixed: neutral)
+  if (sol.species && !(Math.abs(charge) < 1e-12)) fail(`level: ${JSON.stringify(equation)} isn't charge-balanced (Σ ν z = ${charge} across it)`);
   const n = sol.mu[Object.keys(sol.mu)[0]].length;
   const V = new Float64Array(n);
   for (let g = 0; g < n; g++) {

package/src/index.js

@@ -211,11 +211,14 @@ export class Device {
    * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
    * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
    * which), so an animation can call it once per frame; the step size carries over. `probes`
-   * read a species at points inside the device after every accepted step, into `trace.probes`
-   * (one array per probe, alongside `trace.t`): what a detector at x sees.
+   * read a species (or φ) at points inside the device after every accepted step, into
+   * `trace.probes` (one array per probe, alongside `trace.t`): what a detector at x sees. At a
+   * face, `{ interface, species }` reads a species' flux through it (mol/(m²·s), toward +x), and
+   * `{ interface, gate }` a gate's fraction open.
    * @param {number} tEnd s
    * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-   *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+   *   probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }
+   *     | { interface: number, species: string } | { interface: number, gate: string })[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {

package/src/junction.js

@@ -29,6 +29,9 @@ function neutral(list, side, what) {
   }
   if (Math.abs(q) > 1e-9 * s) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution carries a net charge (Σ z·c = ${q.toPrecision(3)} mol/m³)`);
 }
+function holds(list, what) {
+  for (const side of ['cL', 'cR']) if (!list.some((p) => p[side] > 0)) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution holds no ions`);
+}
 
 /**
  * Henderson's liquid-junction potential, φ_R − φ_L (V): the junction taken to be the two solutions
@@ -44,6 +47,7 @@ export function henderson(left, right, ions, { T = 298.15 } = {}) {
   const list = prepare(left, right, ions, 'henderson');
   neutral(list, 'cL', 'henderson');
   neutral(list, 'cR', 'henderson');
+  holds(list, 'henderson');
   let a = 0, b = 0, gL = 0, gR = 0;
   for (const { z, D, cL, cR } of list) {
     a += z * D * (cR - cL);
@@ -51,9 +55,10 @@ export function henderson(left, right, ions, { T = 298.15 } = {}) {
     gL += z * z * D * cL;
     gR += z * z * D * cR;
   }
-  const VT = (GAS_CONSTANT * T) / FARADAY;
-  if (b === 0) return 0;
-  return (-VT * a * Math.log(gR / gL)) / b;
+  // ln(g_R/g_L)/(g_R − g_L) = ln(1 + r)/(r g_L), r = b/g_L: 1/g_L at equal conductivities, where the
+  // plain form is 0/0.
+  const VT = (GAS_CONSTANT * T) / FARADAY, r = b / gL;
+  return (-VT * a * (Math.abs(r) < 1e-8 ? 1 - r / 2 : Math.log1p(r) / r)) / gL;
 }
 
 /**
@@ -71,6 +76,7 @@ export function planck(left, right, ions, { T = 298.15, steps = 4000 } = {}) {
   const list = prepare(left, right, ions, 'planck');
   neutral(list, 'cL', 'planck');
   neutral(list, 'cR', 'planck');
+  holds(list, 'planck');
   const n = list.length, z = list.map((p) => p.z), D = list.map((p) => p.D), Dmax = Math.max(...D);
   const scale = Math.max(...list.map((p) => Math.max(p.cL, p.cR)));
   const cL = list.map((p) => p.cL / scale), cR = list.map((p) => p.cR / scale);

package/src/kit.js

@@ -71,7 +71,7 @@ export function vacuumDipole(def, left, right) {
 
 /**
  * The vacuum-level (Schottky–Mott-type) estimate of a `zeroCharge` where a conductor meets a
- * material: at a conductor region's face, or a contact's capacitive or dipole law. The conductor's
+ * material: at a conductor region's face, or a contact's capacitive or pinned law. The conductor's
  * vacuum level sits its work function W beyond its Fermi level, so
  * zeroCharge = V_F − φ_edge at zero charge = W + (V_vac − φ)_inside.
  * @param {object} def device definition

package/src/live.js

@@ -57,26 +57,31 @@ export class Session {
     if (this.good && errors.every(Boolean)) return done(this.good.sol, { failed: true }); // nothing changed
     const target = this.device.def;
     try {
-      let sol = this.device.solve();
-      // Ramp from the last good state in more and more steps.
-      for (let n = 2; !sol.converged && this.good && n <= this.maxRamp; n *= 2) {
+      let sol = this.device.solve(), stuck = false;
+      // Ramp from the last good state in more and more steps. (Its in-between states can be
+      // invalid where the two ends aren't, a bath neutral at both but not between: then on to the
+      // fresh solve.)
+      ramping: for (let n = 2; !sol.converged && this.good && n <= this.maxRamp; n *= 2) {
         ramp = n;
         this.device._rollback(this.good.cp);
         const from = this.good.cp.def;
         for (let k = 1; k <= n; k++) {
-          this.device.set(between(from, target, k / n));
+          try {
+            this.device.set(between(from, target, k / n));
+          } catch {
+            stuck = true; // (and sol, a converged step short of the target, isn't the answer)
+            break ramping;
+          }
           sol = this.device.solve();
           if (!sol.converged) break;
         }
       }
-      if (!sol.converged) {
+      if (stuck || !sol.converged) {
         // Last, from scratch (with the solver's own continuations).
         const fresh = new Device(target);
         const cold = fresh.solve();
-        if (cold.converged) {
-          this.device = fresh;
-          sol = cold;
-        }
+        if (cold.converged) this.device = fresh;
+        if (cold.converged || stuck) sol = cold;
       }
       if (sol.converged) {
         this.good = { cp: this.device._checkpoint(), sol };

package/src/particles.js

@@ -55,6 +55,8 @@ const NONE = 0, DOT = 1, OUTSIDE = 2; // nothing (closed); a cell of dots; a sea
  */
 export function particles(sol, { species, dots = 200, weight, cap = Infinity, cells = 120, random = Math.random } = {}) {
   checkOptions('particles', arguments[1], ['species', 'dots', 'weight', 'cap', 'cells', 'random']);
+  // (amounts per area, against fluxes that off a plane are per device: planar only)
+  if (sol.geometry !== undefined && sol.geometry !== 'planar') throw new RangeError(`particles: a planar device's solution, not a ${sol.geometry} one`);
   const names = species ?? sol.species.map((s) => s.name).filter((nm) => sol.c[nm].some((v) => v > 0));
   for (const nm of names) if (!sol.c[nm]) throw new RangeError(`particles: no species ${JSON.stringify(nm)} in the solution`);
   if (!(dots > 0 && Number.isFinite(dots))) throw new RangeError(`particles: dots must be a positive number, got ${dots}`);
@@ -172,7 +174,8 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
         }
         [left[k], right[k]] = [side(k - 1), side(k)];
         const hD = A.h / 2 / D[A.mid] + B.h / 2 / D[B.mid];
-        pair(k, J[A.b], (Math.sqrt((N[k - 1] / A.h) * (N[k] / B.h)) * shape(psi[k] - psi[k - 1])) / hD);
+        // (none of it where either cell is empty: an underflow to 0 makes both ψ infinite)
+        pair(k, J[A.b], N[k - 1] > 0 && N[k] > 0 ? (Math.sqrt((N[k - 1] / A.h) * (N[k] / B.h)) * shape(psi[k] - psi[k - 1])) / hD : 0);
       } else if (A || B) {
         // out of the cells: through a contact, or a face to a metal
         const cl = A ?? B, g = A ? A.b : B.a;

package/src/plot.js

@@ -14,7 +14,7 @@
 
 import { traces } from './traces.js';
 import { powi } from './pow.js';
-import { checkOptions } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 // Colours by role, light and dark (validated together for colour-vision deficiency; line weight,
 // dash and the legend carry identity too). A role with more members than colours cycles.
@@ -23,16 +23,20 @@ export const THEME = Object.freeze({
   dark: { electron: ['#5b95d6'], cation: ['#e8584f', '#d0772a', '#d65d95', '#b88a3e'], anion: ['#219c8f', '#2aa5bb', '#3aa874'], redox: ['#8b7ff0', '#a86bc9', '#7a9ae0'] },
 });
 const ROLES = ['electron', 'cation', 'anion', 'redox'];
+const MUTED = { light: '#52514e', dark: '#c3c2b7' }; // (φ's, and lines of no species)
 
 /**
  * The colour of a trace's role and slot (a CSS colour), for drawing other charts in the same
  * colours as the level diagrams.
- * @param {'electron' | 'cation' | 'anion' | 'redox'} role
+ * @param {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role
  * @param {number} slot
  * @param {{ dark?: boolean }} [opts]
  */
 export function themeColor(role, slot, { dark = false } = {}) {
   checkOptions('themeColor', arguments[2], ['dark']);
+  if (role === 'phi') return MUTED[dark ? 'dark' : 'light'];
+  if (!ROLES.includes(role)) throw new DeviceError(`themeColor: no role '${role}' (${[...ROLES, 'phi'].join(', ')})`);
+  if (!(Number.isInteger(slot) && slot >= 0)) throw new DeviceError(`themeColor: slot must be a whole number ≥ 0, got ${slot}`);
   const list = THEME[dark ? 'dark' : 'light'][role];
   return list[slot % list.length];
 }
@@ -118,8 +122,8 @@ function lengthUnit(L) {
 
 const style = (id) => {
   const vars = (mode) => ROLES.flatMap((role) => THEME[mode][role].map((c, k) => `--driftlet-${role}${role === 'electron' ? '' : `-${k + 1}`}:${c};`)).join('');
-  const light = `${vars('light')}--driftlet-ink:#0b0b0b;--driftlet-muted:#52514e;--driftlet-grid:#e4e3df;--driftlet-band:#f1f0ec;--driftlet-face:#a8a7a1`;
-  const dark = `${vars('dark')}--driftlet-ink:#ffffff;--driftlet-muted:#c3c2b7;--driftlet-grid:#3a3a37;--driftlet-band:#262624;--driftlet-face:#6b6a64`;
+  const light = `${vars('light')}--driftlet-ink:#0b0b0b;--driftlet-muted:${MUTED.light};--driftlet-grid:#e4e3df;--driftlet-band:#f1f0ec;--driftlet-face:#a8a7a1`;
+  const dark = `${vars('dark')}--driftlet-ink:#ffffff;--driftlet-muted:${MUTED.dark};--driftlet-grid:#3a3a37;--driftlet-band:#262624;--driftlet-face:#6b6a64`;
   return (
     `<style>` +
     `:where(#${id}){${light}}` +

package/src/solution.js

@@ -27,6 +27,7 @@ export function makeSolution(solver, result = {}) {
     V: {},
     Vstd: {},
     T: model.T,
+    geometry: model.geometry.type, // (planar, or amounts per device rather than per area)
     time: solver.time,
     steady: solver.atSteady,
     converged: result.converged ?? true,