driftlet 1.1.0 → 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.0/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

@@ -21,6 +21,15 @@ double layers. The data are in `IONS`, and $`\mu^\circ`$ of liquid water is `H2O
 1.011e-14 at 25 °C (pK_w 13.995): neutral water holds 1.0055e-4 mol/m³ of each, which a bath
 with that reaction should hold too.
 
+The data are 25 °C's, and the material says so (`T: 298.15`): a device at another temperature
+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; 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) |
 |---|---|---|---|
 | H+ | +1 | 9.311 | 0 |

package/docs/device.md

@@ -250,7 +250,9 @@ r = \frac{n\,p\,(1 - e^{-A/RT})}{(n + n_1)/v_p + (p + p_1)/v_n}, \qquad p_1 = \f
 with n and p each at its own side's edge node, the capture velocities $`v_n`$ and $`v_p`$ in m/s,
 and $`n_1`$ (mol/m³) the negative species' concentration with its level at the trap (default:
 $`n_1 = p_1 = n_i`$, a midgap trap). Taking $`p_1`$ from the state keeps equilibrium exact whatever
-lies between the two sides (a band offset, a $`\phi`$ jump). Where one carrier is plentiful the
+lies between the two sides (a band offset, a $`\phi`$ jump). With Fermi–Dirac carriers, each
+one's emission scales by its own $`\gamma = \mathcal{F}_{1/2}(\zeta)/e^\zeta`$, by detailed balance:
+$`n_1`$ becomes $`\gamma_n n_1`$, and $`p_1`$ keeps the product. Where one carrier is plentiful the
 rate saturates at the other's capture, $`r \to v_p\,p`$: holes reaching an electron-rich layer
 recombine at $`v_p`$ however many electrons wait there, which plain mass action can't do.
 
@@ -514,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
@@ -870,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
@@ -1059,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

@@ -450,8 +450,8 @@ The assembled matrix loses what a flux's two entries share. A Scharfetter–Gumm
 $`\eta`$ at its two ends through $`G`$ and $`-G(1 + E)`$, with $`E = \mathrm{expm1}(\Delta\eta)`$;
 for a nearly uniform $`v`$ they cancel, and $`J \cdot v`$ keeps only round-off of $`G|v|`$, which in
 an inversion layer's 0.1 nm cells ($`G`$ ~ 1e11) dwarfs the flux. Where a solve needs
-$`J \cdot v`$ itself (GMRES, in the impedance and in Newton's refined solves), the dilute kernels'
-terms are kept aside instead, each evaluated on differences first:
+$`J \cdot v`$ itself (GMRES, in the impedance and in Newton's refined solves), the kernels' terms
+are kept aside instead, each evaluated on differences first:
 
 ```math
 \delta N = a\,(\delta\eta_L - z\,\delta\hat\phi_L) + b\,(\delta\eta_R - \delta\eta_L) + d\,(\delta\hat\phi_R - \delta\hat\phi_L),
@@ -459,8 +459,13 @@ terms are kept aside instead, each evaluated on differences first:
 
 with $`a = -GE`$ (through $`c_L`$), $`b = -G(1 + E)`$ and $`d`$ the drift's. A node's storage and space
 charge depend on $`\delta\eta_i - z_i\,\delta\hat\phi`$ alone, the displacement on
-$`\delta\hat\phi_R - \delta\hat\phi_L`$. Everything else (faces, contacts, ports, reactions,
-concentrated and metal regions) is assembled into a matrix of its own. Rows that a contact or a
+$`\delta\hat\phi_R - \delta\hat\phi_L`$. Non-ideal statistics couple the species ($`c_i`$
+depends on every $`\zeta_j`$), so there a node's storage of $`i`$ has a term in each
+$`\delta\eta_j - z_j\,\delta\hat\phi`$, through $`K_{ij}`$, and a flux has side terms in those at
+either end (through $`c_L`$ and the excess potentials in its drift); each is in the same
+differences. (Until 1.1.1 they were assembled directly, and a Fermi–Dirac MOS capacitor in
+inversion, barely degenerate, came out with a negative resistance.) Everything else (faces,
+contacts, ports, reactions, metal regions) is assembled into a matrix of its own. Rows that a contact or a
 steady solve replaces drop the kept terms; the transformed rows of strictly neutral nodes combine
 them as they combine the matrix's. A region's uniform shift ($`z_i s`$ on each $`\eta_i`$, $`s`$ on
 $`\hat\phi`$) then gives exactly zero inside it, as it must. It replaced a central difference of
@@ -649,7 +654,7 @@ majority conductances times a $`\delta\eta`$ cancelling its neighbours' to 1e-17
 round-off reads as a constant conductance of order 1 S/m², a silicon p⁺n⁺ junction's capacitance
 9× off at 100 Hz. Between the two contacts of a device without ports, the total current
 (conduction plus displacement, $`i\omega\,\delta D`$) is the same through every cut, so it is also
-read across each segment of an ideal region, linearised as the Scharfetter–Gummel flux is, and
+read across each segment of a region (with any statistics), linearised as its flux is, and
 the reading with the least estimated error is taken: in that junction, the depletion region's;
 in a MOS capacitor, the oxide's displacement. A reading's error is its terms' round-off, and the
 solves' error in $`\delta x`$ (their residual, relative to its largest entry) through its
@@ -720,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.
@@ -791,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
@@ -173,9 +196,6 @@ so a change that makes one worse shows.
 - **A surface covered to a bare fraction below ~1e-10** barely affects anything any more, and
   the solver struggles with it (the hard corpus's passivating drop without a double layer stops
   partway through its hour); the solution warns, and suggests a less stable film.
-- **A double layer across more than ~350 thermal voltages** (between 9 and 9.25 V at 25 °C, in a
-  crowded lattice-gas electrolyte) doesn't solve, from a cold start or warm, and its warning
-  doesn't say why. Ionic-liquid windows (a few volts) are well inside it.
 - **Currents below ~0.1 nA/m²** (a GaAs junction's leakage without recombination) aren't resolved
   between solves; such a current is zero for any practical purpose.
 - **A failed solve says so:** `converged: false`, with a warning naming where the system lost

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.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/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.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.1.0/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.0",
+  "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

@@ -66,7 +66,8 @@ export const METALS = freeze(
 
 /**
  * Water with the named ions, as a library piece for `build()`: each ion as a species
- * (c_ref = 1 M) and the material `water` holding them, with D and μ° from `IONS`.
+ * (c_ref = 1 M) and the material `water` holding them, with D and μ° from `IONS`. The data are
+ * 25 °C's, and the material says so (T: 298.15): a device at another temperature warns.
  * @param {string[]} names ions from `IONS`
  * @param {{ epsr?: number, material?: string }} [opts] permittivity (default that of water;
  *   0 makes the solution strictly neutral, without double layers), and the material's name
@@ -82,7 +83,8 @@ export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
     species.push({ name, z: ion.z, cRef: 1000 });
     entries[name] = { D: ion.D, mu0: ion.mu0 };
   }
-  return { species, materials: { [material]: { epsr, species: entries } } };
+  // (25 °C data: a device at another temperature warns)
+  return { species, materials: { [material]: { epsr, species: entries, T: 298.15 } } };
 }
 
 // How the semiconductors' data move with temperature, for semiconductor(name, { T }):
@@ -183,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'],
@@ -308,14 +308,20 @@ export function normalizeDevice(def) {
     };
   });
 
-  // A material whose data are for another temperature than the device's gives the wrong n_i, gap
-  // and mobilities, silently: say so (for each material a region uses).
+  // A material whose data are for another temperature than the device's is silently wrong there
+  // (a semiconductor's n_i, gap and mobilities; water's μ°, ε and D): say so (for each material a
+  // region uses).
   materials.forEach((m, k) => {
     if (m.dataT === undefined || Math.abs(m.dataT - T) <= 0.01 || !regions.some((reg) => reg.material === k)) return;
+    const own = Object.keys(def.materials[m.name].species ?? {}), semi = own.includes('e-') && own.includes('h+');
     warnings.push(
       `materials.${m.name}: its data are for ${m.dataT} K, but the device is at ${T} K${def.T === undefined ? ' (the default, as it gives no T)' : ''}, ` +
-        `so they don't hold there (a semiconductor's n_i, gap and mobilities are ${m.dataT} K's): give the device T: ${m.dataT}, ` +
-        `or remake the material for ${T} K (semiconductor(name, { T: ${T} }))`,
+        (semi
+          ? `so they don't hold there (a semiconductor's n_i, gap and mobilities are ${m.dataT} K's): give the device T: ${m.dataT}, ` +
+            `or remake the material for ${T} K (semiconductor(name, { T: ${T} }))`
+          : `so they don't hold there: its μ° (so equilibrium constants and electrode potentials, Kw's by ~6× between 6 and 25 °C), ` +
+            `permittivity and diffusivities are ${m.dataT} K's. Give the device T: ${m.dataT}, or give the material data for ${T} K ` +
+            `and its T (aqueous() has none at other temperatures yet)`),
     );
   });
 
@@ -698,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);
@@ -1249,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`) };
@@ -1277,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/difference.js

@@ -8,13 +8,19 @@
 // storage and space charge depend on δη_i − z_i δφ̂ alone; the displacement on δφ̂_R − δφ̂_L. A
 // uniform shift of a region (z_i s on each η_i, s on φ̂) then gives exactly zero, as it must.
 //
+// Non-ideal statistics couple the species: c_i depends on every ζ_j, so a node's storage of i
+// has a term in each δη_j − z_j δφ̂ (K_ij), and a flux has side terms in those at either end (its
+// c_L and the excess potentials in its drift). Each is a term in the same differences, so the
+// shift still gives exactly zero.
+//
 // Indices are compact (the solver's rix), with the sink (index N) for an unknown that isn't one:
 // vectors passed in are read there as zero.
 export class DifferenceTerms {
-  constructor(N, nodes, segments) {
+  constructor(N, nodes, segments, sides = 0) {
     this.N = N;
     this.dead = new Uint8Array(N + 1); // rows replaced since (a contact's level, a held stretch)
-    this.nI = new Int32Array(nodes); // node term: η column (= its balance row), φ̂ column (= Gauss row)
+    this.nR = new Int32Array(nodes); // node term: its balance row, η column, φ̂ column (= Gauss row)
+    this.nI = new Int32Array(nodes);
     this.nP = new Int32Array(nodes);
     this.nZ = new Float64Array(nodes);
     this.nMass = new Float64Array(nodes); // storage per unit (δη − z δφ̂), times 1/dt (or iω)
@@ -24,6 +30,9 @@ export class DifferenceTerms {
     this.sC = new Float64Array(3 * segments); // a, b, d
     this.dI = new Int32Array(2 * segments); // displacement: φ̂_L, φ̂_R
     this.dK = new Float64Array(segments);
+    this.xI = new Int32Array(4 * sides); // a flux's side term: its two rows, an η column, its φ̂ column
+    this.xZ = new Float64Array(sides);
+    this.xC = new Float64Array(sides);
     this.combos = []; // [rk, ri, w]: row rk += w × row ri (strictly neutral nodes' charge rows)
     this.t = new Float64Array(N + 1);
     this.x = new Float64Array(N + 1);
@@ -33,13 +42,16 @@ export class DifferenceTerms {
   // Afresh for an assembly; `rate` multiplies storage in captured rows (1/dt).
   reset(rate = 0) {
     this.rate = rate;
-    this.nn = this.ns = this.nd = 0;
+    this.nn = this.ns = this.nd = this.nx = 0;
     this.dead.fill(0);
     this.combos.length = 0;
   }
 
-  node(i, p, z, mass, charge) {
+  // Storage in row r (mass) and charge in Gauss row p, per unit δη_i − z δφ̂ (row r = i, unless
+  // non-ideal statistics couple the species).
+  node(i, p, z, mass, charge, r = i) {
     const k = this.nn++;
+    this.nR[k] = r;
     this.nI[k] = i;
     this.nP[k] = p;
     this.nZ[k] = z;
@@ -59,6 +71,17 @@ export class DifferenceTerms {
     this.sC[3 * k + 2] = d;
   }
 
+  // A flux from row rL to row rR, per unit δη_i − z δφ̂ at one end.
+  side(rL, rR, i, p, z, w) {
+    const k = this.nx++;
+    this.xI[4 * k] = rL;
+    this.xI[4 * k + 1] = rR;
+    this.xI[4 * k + 2] = i;
+    this.xI[4 * k + 3] = p;
+    this.xZ[k] = z;
+    this.xC[k] = w;
+  }
+
   displacement(pL, pR, k) {
     const q = this.nd++;
     this.dI[2 * q] = pL;
@@ -83,7 +106,7 @@ export class DifferenceTerms {
     for (let k = 0; k < this.nn; k++) {
       const i = this.nI[k], p = this.nP[k], z = this.nZ[k];
       let f = 0;
-      if (row === i) f += mass * this.nMass[k];
+      if (row === this.nR[k]) f += mass * this.nMass[k];
       if (row === p) f += this.nCharge[k];
       if (f === 0) continue;
       add(i, f);
@@ -99,6 +122,12 @@ export class DifferenceTerms {
       add(this.sI[4 * k + 2], s * (-z * a - d));
       add(this.sI[4 * k + 3], s * d);
     }
+    for (let k = 0; k < this.nx; k++) {
+      const s = row === this.xI[4 * k] ? 1 : row === this.xI[4 * k + 1] ? -1 : 0;
+      if (s === 0) continue;
+      add(this.xI[4 * k + 2], s * this.xC[k]);
+      add(this.xI[4 * k + 3], -s * this.xZ[k] * this.xC[k]);
+    }
     for (let q = 0; q < this.nd; q++) {
       const pL = this.dI[2 * q], pR = this.dI[2 * q + 1], s = row === pL ? 1 : row === pR ? -1 : 0;
       if (s === 0) continue;
@@ -114,10 +143,10 @@ export class DifferenceTerms {
     for (let j = 0; j < N; j++) x[j] = v[j];
     x[N] = 0;
     t.fill(0);
-    const { nI, nP, nZ, nMass, nCharge } = this;
+    const { nR, nI, nP, nZ, nMass, nCharge } = this;
     for (let k = 0; k < this.nn; k++) {
       const i = nI[k], p = nP[k], w = x[i] - nZ[k] * x[p];
-      t[i] += mass * nMass[k] * w;
+      t[nR[k]] += mass * nMass[k] * w;
       t[p] += steady * nCharge[k] * w;
     }
     if (steady !== 0) {
@@ -128,6 +157,12 @@ export class DifferenceTerms {
         t[iL] += dN;
         t[iR] -= dN;
       }
+      const { xI, xZ, xC } = this;
+      for (let k = 0; k < this.nx; k++) {
+        const dN = steady * xC[k] * (x[xI[4 * k + 2]] - xZ[k] * x[xI[4 * k + 3]]);
+        t[xI[4 * k]] += dN;
+        t[xI[4 * k + 1]] -= dN;
+      }
       for (let q = 0; q < this.nd; q++) {
         const pL = dI[2 * q], pR = dI[2 * q + 1], dD = -steady * dK[q] * (x[pR] - x[pL]);
         t[pL] += dD;