driftlet 1.1.1 → 1.2.2

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.2/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).
 
@@ -300,7 +300,7 @@ npm run shots    # retake the demos' screenshots, each caught at a set state (to
 
 Design notes and plans: [reliability](docs/reliability.md), [numerics](docs/numerics.md), [conventions](docs/conventions.md),
 [statistics](docs/statistics.md), [the kit](docs/kit.md), [reading level diagrams](docs/visualization.md),
-[data](docs/data.md), [roadmap](ROADMAP.md).
+[data](docs/data.md), [internals](docs/internals.md) (the source, module by module), [roadmap](ROADMAP.md).
 
 ## Credits
 

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/internals.md

@@ -0,0 +1,86 @@
+# Internals
+
+A map of the source for anyone reading or reviewing it: what each module is for, the layout of
+the solver's state that the rest assumes, and which modules state a contract. The user-facing
+reference is the other docs; this one is about the code.
+
+## The rule: a module states its contract
+
+A module whose correctness can't be seen from its call sites says at its head what it reads,
+what it returns or writes, and what must hold of the result, so that it can be checked on its
+own, without the rest of the library in mind. Where the contract and the code disagree, one of
+them is wrong: fix both, with a test, in the same commit.
+
+| Module | Contract |
+| --- | --- |
+| `src/laws.js` | yes: the steady system's conservation laws |
+| `src/lawRows.js` | yes: the laws written into the Newton system, and the bordered solve |
+| `src/difference.js` | header: the dilute kernels in difference form |
+| `src/blockTridiagonal.js` | header: the block Thomas solver |
+| `src/statistics.js` | header: each model's `evaluate` / `invert` |
+| `src/solver.js` | not yet (below) |
+
+## From a definition to a solution
+
+- `src/device.js`: `normalizeDevice(def)` validates a plain definition and returns the
+  normalised `model` (species, materials, regions, interfaces, contacts, ports, terminals, the
+  grid from `src/grid.js`). Every later stage reads the model and never the definition.
+- `src/index.js`: `Device`, the public object. It holds the model, builds a `Solver` on first
+  use, and turns solver states into `Solution`s (`src/solution.js`).
+- `src/solver.js`: `Solver`, the numerical core (below).
+- The kit (`src/kit.js` and what it re-exports: stack, data, sources, channels, checks,
+  describe, traces, live, recorder, particles, polarization, junction, devices) works on
+  definitions and solutions only, never on a solver's internals. `src/plot.js` draws
+  solutions.
+
+## The solver's state
+
+- **Blocks.** One per grid node and one per face between regions: node g is block
+  `blockOfNode[g]`, face f's flux block is `blockOfFace[f]`, in order along x.
+- **Slots.** Each block has `M = 1 + n + extra` slots: slot 0 is φ̂ (at a face its
+  displacement D, at a metal's node its carriers' segment flux J), slots `1 … n` the species'
+  η = μ̄/RT, then a face's reaction rates and gates' fractions, or at an electrode port's nodes
+  its surface's coverages (as η) and a membrane port's gates. Row and unknown `o = b·M + slot`.
+- **Compact indices.** Only active slots enter the linear system: `loc[o]` is a slot's place in
+  its block (−1: inactive), `rix[o]` its index in compact vectors, with `rix = N` (the sink) for
+  inactive ones. `res`, `delta` and the Jacobian (`sys`, a `BlockTridiagonal`) are compact.
+- **Unknowns** are `u + uLo`, a double-double, so that differences of η keep their digits; the
+  Jacobian and solves are plain doubles. Concentrations `c[g·n + i]` and coverages
+  `th[g·nSurf + q]` follow from `u` (`computeConcentrations`).
+- **Terminals:** 0 the left contact, 1 the right, `2 + k` port k. A floating terminal (driven by
+  a current, or behind a resistance) has its voltage as an extra unknown and its circuit row
+  beside the block system, solved by bordering (`solveBordered` in `src/lawRows.js`: `termB`
+  its column, `termC` its row, `termDI` and `termDX` its own and other terminals' ∂/∂V).
+- **Stretches:** each connected run of regions where a species is present
+  (`_findStretches`), the unit that conservation counts in.
+
+## The solver's sections
+
+By method, in file order:
+
+- **Setup:** the constructor (layout, per-node data, φ-undefined regions, terminals),
+  `_activeSlots`, `_findStretches` (stretches, flat stretches), `_laws` and `_structure` (the
+  laws, from `src/laws.js`), `_directSteady`.
+- **Applying the laws** is `src/lawRows.js` (`captureLaws`, `captureLocal`, `snapFlat`,
+  `applyLaws`, `solveBordered`), called from `assemble`, `newton`, `_refine` and the steady
+  solves; `_replaceRow` and `_j`, which it uses, stay in the solver.
+- **Starting state:** `initFromComposition`, `_surfaceStart`.
+- **Statistics and assembly:** `computeConcentrations`, `_nodeStatistics`, `assemble` and the
+  kernels it calls (nodes, segments, faces, bulk reactions, ports, contacts, charge rows),
+  `_assembleDifference` (with `src/difference.js`).
+- **Newton:** `newton`, `_refine`, `_equilibrate`, `_kirchhoff`, `_noteConditioning`.
+- **Time steps:** `advance`, `step`, `integrate` (BDF with error control, breakpoints from the
+  sources), `_predict`, `_errorNorm`, `_snapshot` / `_restore`.
+- **Small signal:** `impedance` and the helpers after it.
+- **Bookkeeping:** `segmentFluxes`, `faceOneWay`, `_assembleBookkeeping`, the contacts' intake.
+- **Steady solves:** `solveSteady`, `_steadyFromHere`, the continuations (floating, generation,
+  a terminal's level), `_steadySteps`.
+
+The rest of `src/solver.js` is to be split along these lines, each piece with its contract.
+
+## Reviewing one module
+
+A review of one module reads its contract, its code and its tests, and nothing else unless the
+contract points there. Each claim cites `file:line` with the line quoted, so it can be checked
+mechanically, and a finding comes with the device or script that shows it. A claim about code
+not in view is a question, not a finding.

package/docs/numerics.md

@@ -725,17 +725,34 @@ 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.
+    A charge is kept only in a circuit row, once: the first combination through it takes one,
+    and the rest have its multiple taken off (a capacitor passing K⁺ under K⁺ + L⁻ = KL keeps
+    $`n_K - n_L + D/F`$ there, and $`n_L + n_{KL}`$ in a balance row).
+    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. Each node's rows are chosen by elimination
+    over the slots there, as below. Immobile means D = 0 in one region with no terminal feeding
+    it: a species linked across a face is carried between the face's two nodes, and one a
+    port links is carried between the port's nodes, kept with the port's charge in its circuit
+    row. (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.
 
+  A combination that none of these rows can keep (through a stretch immobile in part only, a
+  face reaction joining two immobile stretches at a face, a charge with no circuit row left) is
+  set aside, and the steady solve then goes by time steps, which keep every amount themselves.
+
   A closed stretch keeps the amount it was given (its `c0`, or what it held when `set()`
   closed it); a combination behind a terminal at no current keeps what the state holds when the
   solve begins. The amount's row is dense, so it's bordered (see [terminals](#terminals)): the
@@ -796,7 +813,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,40 @@ 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 870 small devices in two families. The first, 810, combine 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. The second, 60, put an immobile S⁺ beside what carries it (a face that passes it, a port
+at I = 0 that links it, an electrode it adsorbs on) with a capacitive contact passing K⁺ (at
+I = 0 or behind a resistance) and K⁺'s complex with a closed L⁻, each where a cold review of
+`src/laws.js` found a law kept wrongly.
+
+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), and a cold review
+of `src/laws.js` against its contract alone five more (an immobile species linked across a face,
+or by a port; two node-by-node laws sharing a row; a capacitive contact's charge in a second law,
+and in a time step's reading of its current), none of them in the sweep's devices. Each is now in
+`test/laws.test.js`. On the code before those fixes the second family has 14 devices that
+disagree (a port's voltage at 0 for −1.42 V, θ 0.05 for 0.015, a contact 24 mV off); after, none,
+26 agree and 34 transients fail (see the roadmap). The first family's laws come out unchanged by
+the fixes, device by device, so its results above stand. On 1.2.2 the whole sweep, 870 devices, gives the
+same: 605 agree, 117 transients fail, and 13 differ, each a capacitive contact beside a membrane
+capacitor where the transient loses K⁺.
+
 ## 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.2/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/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.2/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.2/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.1.1",
+  "version": "1.2.2",
   "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