driftlet 0.10.0 → 0.12.0

package/docs/numerics.md

@@ -210,9 +210,16 @@ flux node's own rows are the interface laws:
 | species, blocked or absent on one side | $`N_f = 0`$ |
 | species, conductance | $`N_f - G V_T (\eta_L - \eta_R)/(z^2 F) = 0`$ |
 | face reaction $`k`$ | $`r_k - \mathrm{rate}_k(\mathrm{state}_L, \mathrm{state}_R) = 0`$, and each participant's edge node takes $`\nu \cdot r_k`$ |
+| gate $`q`$ | $`(x_q - x_q^{\mathrm{old}})/dt - \alpha(V)(1 - x_q) + \beta(V)\,x_q = 0`$, $`V = V_T(\hat\phi_R - \hat\phi_L)`$; a gated permeability's $`P`$ takes $`\prod x^p`$ |
 
 Every row couples only neighbours, with no penalty terms. A face reaction's rate is an unknown
-of the face block, so the two edge nodes it couples meet only through the block between them.
+of the face block, so the two edge nodes it couples meet only through the block between them;
+so is a gate's fraction open, its row coupling it to the two edge nodes' $`\hat\phi`$, and the gated
+fluxes to it, all within the face's block and its neighbours'. Newton's convergence and the time
+step's error count a gate's change as they count a potential's in thermal units (1e-3 of $`m`$ is
+0.3% of $`m^3`$), and a gate is evaluated in [0, 1] where Newton's iterates stray past its ends. A
+membrane port's gates are unknowns of each window node's block, after its surface's coverages,
+with the same row in the voltage across the port's capacitance there.
 A species can take part in a reaction at a face and also cross it by a link (its flux slot)
 at the same time; where it exists on both sides, that link must be given explicitly. A continuity
 row has a zero diagonal block, but block Thomas still sees a non-singular block there once the
@@ -420,6 +427,29 @@ instead of $`n \cdot M^3`$, which pays wherever species are confined to some reg
 against KCl, three unknowns of five at every node, it's a fifth of the work. A finite-difference
 test checks the compact Jacobian column by column on devices that cover every assembly path.
 
+### Exact J·v
+
+The assembled matrix loses what a flux's two entries share. A Scharfetter–Gummel flux depends on
+$`\eta`$ at its two ends through $`G`$ and $`-G(1 + E)`$, with $`E = \operatorname{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:
+
+```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),
+```
+
+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
+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
+the residual, whose truncation (~1e-9 of $`|J||v|`$) swamped the answer for such a shift, and
+which cost four assemblies per product.
+
 ## Newton
 
 - The update of the device's potentials ($`\hat\phi`$, $`\eta`$) is limited to 10 thermal units per
@@ -439,8 +469,37 @@ test checks the compact Jacobian column by column on devices that cover every as
   much reduced by the change of variables below), converges quadratically to ~1e-9 and then
   rattles there. Short steps come right after every waveform breakpoint, so without this a
   cyclic voltammogram in a neutral electrolyte stalled at its turns.
-- Clear divergence (device updates beyond 1e4, or ten times the first after six iterations)
-  bails out early, so the caller can take a smaller step.
+- **Refined solves, where the factorisation loses a mode.** The assembled $`J`$ holds a flux's
+  dependence on $`\eta`$ at its two ends as two entries; where they're huge, eliminating them loses
+  what they share to round-off. In a MOS capacitor's inversion layer the electrons' cells, 0.1 nm
+  wide, are coupled about $`h^2/(D\,dt)`$ ~ 1e-18 times more tightly than they store charge over a
+  second, so the layer's overall level, set by its storage and the trickle of minority electrons
+  from the bulk, is lost, and Newton's update there is noise. When Newton stalls short of
+  convergence (updates below 1e-4 that stopped shrinking quadratically), or its undamped updates
+  grow twice running (a bipolar stack's floating base, whose holes are held ~1e14 more weakly
+  than they move within it, kept Newton wandering a thermal unit at a time), the solve is refined:
+  GMRES on $`J\delta = r`$, the factorised system as the preconditioner and $`J \cdot v`$ exact, each
+  flux on its $`\eta`$ difference (see [exact J·v](#exact-jv)), as the impedance does. A lost mode
+  takes GMRES a couple of iterations. The refined update is kept where GMRES converged and it
+  moves no level by a thermal unit or more; otherwise refining stops for the rest of the solve.
+  A MOS capacitor's gate step now reaches the low-frequency charge in ~70 steps (it took 80,000,
+  and ended 1.5% off). Once refined, a solve stays refined: a GaAs junction without
+  recombination, whose minority carriers reach it only from the contacts, passes ~1.5e-7 A/m²,
+  which plain solves past the first refinement left to round-off (cold and warm solves 1e-3
+  apart), and refined ones give to 1e-14. (When $`J \cdot v`$ was a central difference of the
+  residual, its noise made refining past the first lost mode chase round-off, so it was kept
+  only where its correction dwarfed the plain update.)
+- Clear divergence (device updates beyond 1e4 after the first iteration, or ten times the
+  first after six) bails out early, so the caller can take a smaller step. The first update is
+  exempt: light flooding a population that starts at ~1e3 per m³ predicts, linearised in
+  $`\eta`$, a change of 1e10 thermal units, which damping covers in a few iterations; bailing
+  out there had a lit phototransistor's pseudo-transient fail at every step above 1e-21 s.
+- A pivot that cancels to exactly zero in the block factorisation is perturbed to 1e-15 of its
+  block's largest entry (static pivoting) rather than failing the solve. GaAs minority carriers,
+  ~1 per m³ beside a face, are held through conductances 1e-16 of the face flux's coefficient in
+  their row, and the elimination cancels them exactly: such devices now solve, even at
+  equilibrium. Newton's updates stay meaningful (the factorisation only amplifies the residual,
+  so a small update still means a small residual), and its refined solves correct the rest.
 - When a steady solve fails, the solution's warnings say how nearly singular the system was,
   and where. A running error bound through the factorisation compares each pivot with the
   magnitudes it was formed from, $`\log_{10}(\sum|\mathrm{terms}| / |\mathrm{pivot}|)`$: the digits
@@ -481,6 +540,13 @@ test checks the compact Jacobian column by column on devices that cover every as
     $`C_c = h^3(1+\omega)^2/(\omega(1+2\omega))`$ and $`C_p = h(h+h_1)(h+h_1+h_2)`$; linear after
     backward Euler, scaled by $`h/(2h + h_1)`$. The first step, with no history, is checked by step
     doubling.
+  - A first step whose error doesn't shrink with it is taken anyway. A jump in a level held at a
+    boundary (a bath's, after a voltage step) starts a profile self-similar in $`x/\sqrt{t}`$, so a
+    first step of any length errs alike (0.11 thermal units over ten decades of step, in a
+    0.6 M electrolyte with resolved double layers), down to the grid's own diffusion time,
+    where Newton runs out of digits. Three tries in a row, each within a factor 2 of the last,
+    mark the error as the jump's; backward Euler damps it as it should, and the steps grow
+    from there. Transients that start with a jump take 5–30% fewer factorisations for it.
   - The state a first step starts from needn't satisfy the algebraic equations ($`\hat\phi`$ in a
     strictly neutral material, an interface's unknowns), after a start or a jump; they jump in
     the first instant. So the history starts from the first step's half step, not from there,
@@ -497,9 +563,9 @@ test checks the compact Jacobian column by column on devices that cover every as
     current it cost 50% more.
   - A step is rejected above `tol`. The next step size is
     $`h \cdot \min(2, \max(0.2, 0.9\, (\mathtt{tol}/\mathrm{err})^{1/(p+1)}))`$.
-  - Newton failure quarters the step; on the first step after a start or a jump in a device
-    with a strictly neutral material, longer steps are tried first, since there shorter ones are
-    worse conditioned.
+  - Newton failure quarters the step. (Strictly neutral materials had tried longer first steps
+    instead, shorter ones being worse conditioned there; with their ends and starts fixed, no
+    case needs it.)
   - A target within round-off of the present time (1e-10 relative), such as an animation
     frame's that lands a hair past a breakpoint just reached, is snapped to rather than
     stepped to: a step of 1e-13 s can't be resolved.
@@ -533,15 +599,42 @@ species make $`J`$ singular, but $`J + i\omega M`$ isn't for $`\omega > 0`$: at
 device looks like a capacitor, as it should.
 
 The factorised system is used as a preconditioner, not trusted alone: each solve runs GMRES with
-$`J \cdot v`$ taken from the residual itself, by a central difference ($`\eta`$ perturbed in the
-state's low word, $`\hat\phi`$ and the face unknowns in the high one). The assembled $`J`$ holds a
-flux's dependence on $`\eta_L`$ and $`\eta_R`$ as two entries; in an inversion layer both are huge
-(~1e11), and for a nearly uniform $`\delta\eta`$ they cancel to round-off of order 1e-5, while the
-residual takes the $`\eta`$ difference first, in double-double. That round-off had given a MOS
-capacitor's inversion layer, fed by minority diffusion from a bulk with ~1e3 electrons per cm³ (a
-time constant of minutes), an exchange path that followed the gate at 1 Hz. Where the plain solve
-is already accurate, one application of the operator confirms it; the bench's impedance cases
-take about twice as long as before.
+an exact $`J \cdot v`$ (see [exact J·v](#exact-jv)). The assembled $`J`$ holds a flux's dependence
+on $`\eta_L`$ and $`\eta_R`$ as two entries; in an inversion layer both are huge (~1e11), and for a
+nearly uniform $`\delta\eta`$ they cancel to round-off of order 1e-5. That round-off had given a
+MOS capacitor's inversion layer, fed by minority diffusion from a bulk with ~1e3 electrons per cm³
+(a time constant of minutes), an exchange path that followed the gate at 1 Hz. Where the plain
+solve is already accurate, one application of the operator confirms it. GMRES judges convergence only by the true residual,
+recomputed at each restart: its own running estimate can drift far from it where the
+preconditioner is nearly singular (an inversion layer's exchange, lost in the assembled
+$`J`$, at a frequency of µHz), and had declared solves converged that weren't. It keeps its
+best iterate, never worse than the factorised solve.
+
+The current is read where its error is smallest. At a contact it is a sum of terms that can
+be far larger than itself: across a junction without recombination, between heavily doped
+sides, what passes is minority carriers of ~1e8 per m³, while the contact's terms are its
+majority conductances times a $`\delta\eta`$ cancelling its neighbours' to 1e-17, and their
+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
+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
+coefficients: a contact's reading is a flux too (a held contact's balance row is replaced by its
+level, so nothing solved pins it), and in a neutral bulk the current crosses a huge conductance
+on a tiny gradient.
+
+Where even the best reading's estimated error exceeds 1% of the current, the response is split
+in two: a uniform shift of each region (every $`\eta_i`$ by $`z_i s_r`$ and $`\hat\phi`$ by $`s_r`$, with
+$`s_r`$ fitted to the solve so far), which changes no flux and no concentration, so its $`J \cdot e`$ is
+exactly zero inside each region and is taken at the faces and ends;
+and the rest, small, solved for to GMRES's floor with its error now relative to itself, and read
+separately. An electrolyte at its open circuit needs it: the response to its terminal is nearly
+such a shift, and its current is the slope of levels uniform to 1e-14 of the response, more than
+a double holds. A redox electrode's DC conductance had come out 2–40% low; now it matches the
+steady dI/dV to six digits. (Not with ports, whose exchange sees the shift.) The real part of a nearly ideal capacitor, 1e-7 of $`|Z|`$, is still
+only resolved to ~1e-4 of $`|Z|`$.
 
 ## Steady state
 
@@ -550,6 +643,28 @@ take about twice as long as before.
   because slow physics can take seconds, far beyond any $`L^2/D`$ estimate, and stepping would
   never finish. An example is exponentially scarce minority carriers slowly filling an inversion
   layer behind a Schottky contact.
+- **A flat level,** where a stretch's steady state is known outright: a species that no reaction
+  or port touches, reached by one contact only (blocked at the other end), carries no flux in a
+  steady state, so its level is that contact's throughout. Steady solves (not the impedance,
+  where it carries a current) pin it there in place of its balances, rather than find it
+  through its own conduction, which can be all but nothing: a MOS capacitor's inversion
+  electrons reach the back contact only through a bulk with ~1e3 of them per cm³, and found that
+  way, the solve converged at some gate voltages and grids and not others. (Not through flow or
+  mixing, nor a concentrated material's cross-diffusion, where zero flux isn't a flat level.)
+  At a face inside such a stretch whose link holds the level continuous, the face's flux of the
+  species, which only the replaced edge balances set, is pinned to zero too.
+- **Continuation for a terminal driven by a current.** A cold steady solve at open circuit can
+  fail where the same state is easy warm (a solar cell in dim light on a fine grid). The
+  terminal is held at a voltage instead, its steady solves having their own continuation, and
+  the voltage marched from the start's, the step growing, until the current crosses its target:
+  up where the current is below it, since raising a terminal's voltage raises the current into
+  a passive device (the other way if 20 V brings no crossing). Bisection narrows the crossing
+  to 0.1 mV, and the terminal is floated from beside it. Floated, the system can lose what held
+  it doesn't (a closed Fe³⁺/Fe²⁺ cell driven near its limit, Fe³⁺ 20 orders below Fe²⁺: 33 digits
+  short), but the current-driven steady state is the held one at the voltage that passes the
+  target, so where the floated solve fails, held solves find that voltage instead, by regula
+  falsi within the bracket, to 1e-10 of the current. The voltage continuation's own start,
+  with the terminals level, ramps the light up when there is some.
 - **Spectators** (a species blocked all round, mobile throughout its stretch) are solved
   directly too. In steady state the sum of a spectator's balance rows over its stretch is zero
   identically, so one of them (the first node's) is redundant, and it's replaced by the
@@ -557,7 +672,14 @@ take about twice as long as before.
   bordered: the matrix is factorised with a pin (an identity row) in its place, which makes the
   stretch's level a well-conditioned unknown, and the response to a unit pin (one extra
   back-substitution per spectator) is added in the amount that satisfies the constraint, from
-  a $`k \times k`$ system for $`k`$ spectators.
+  a $`k \times k`$ system for $`k`$ spectators. Within one ideal region (no flow or mixing), a
+  spectator's level is flat at steady state, at a value its amount fixes, so its other balance
+  rows are replaced by $`\eta_g - \eta_{g-1} = 0`$, rather than found through its own conduction.
+  Past a closed zinc cell's limiting current, extended space charge at the cathode excludes the
+  blocked sulfate to ~1e-25 mol/m³, and the chain of conductances through it had lost the steady
+  system 14 digits: steady solves failed from 0.7 V, and took 37,000 iterations at 0.6 V. (Not
+  across a face: the rows that would hold the level there and pin its flux leave a diagonal
+  block singular.)
 - **Conserved combinations** (moieties) of reacting stretches are solved the same way: the
   total iron of Fe³⁺, Fe²⁺ and FeCl²⁺ in a closed cell with a complexation reaction, say. The
   basis of combinations $`w`$ comes from the null space of the stoichiometry. In steady state the
@@ -571,6 +693,36 @@ take about twice as long as before.
   larger by $`D \cdot dt/(hL)`$, around 1e12 for a micron-scale cell (see
   [metal regions](#metal-regions) for the same cancellation). Newton then needs dozens of
   iterations, or fails.
+- **Islands**: the pieces of a stretch between its faces, where nothing else feeds a piece (no
+  contact, port or reaction). In steady state such a piece's level is held only through its
+  faces' fluxes, which can be far weaker than its own conduction: a face conductance of
+  1e-15 S/m² against a region conducting ~4e2 S/m, or neighbours that conduct 1e20 times less
+  than it. Eliminated, the level was lost to round-off below anything Newton could see (the
+  plain solves gave no update along it, so nothing stalled), and solves converged to a wrong one
+  silently: currents 2× or 16× off. Summed over the piece's nodes, its balance rows are its
+  faces' flux unknowns alone, $`A_R u_R - A_L u_L`$: the internal fluxes cancel exactly, by
+  construction rather than in round-off. Across a face that holds $`\bar\mu`$ level, $`u`$ is
+  set only by the edge balances, and eliminated it can come out of the piece's own, as
+  $`G\,\Delta\eta`$ with its two $`\eta`$ all but equal; so there the outside edge node's
+  balance is added too, $`u`$ cancels, and the outside's first segment carries the flux. (Seen
+  through one face of two, a level behind neighbours 1e20 times less conductive was overshot
+  twofold, and Newton swung it from one contact's level to the other's.) That sum can replace
+  the first node's row, bordered like a spectator's amount. The response to the unit pin is the island's uniform shift, with whatever
+  $`\hat\phi`$ and the other species do along with it, so no mode needs guessing; refined solves
+  carry the pinned rows too.
+
+  Newton exact along such a level can be worse than Newton blind to it, far from the solution
+  (cold at bias, a bipolar stack's floating base took 1e5 thermal units in its first update), so
+  the summed rows go in only once the plain solves converge. An island at the wrong level then
+  shows: it takes in a different current than it passes on, so the terminal currents don't add
+  up to zero (to 1e-9 of the largest). Newton then carries on with the summed rows, refined from
+  their second update. A current that tiny against the conduction around it rides on $`\eta`$
+  differences (~1e-28 for 5 fA/m² through 1e4 mol/m³ at D = 1e-4 m²/s) that the last update
+  leaves known only to its own round-off, so where the currents still don't add up, one more
+  update polishes them. If Newton doesn't converge again within a dozen updates (a GaAs stack's
+  minority carriers, whose own rows rest on static pivots, at 1e-17 A/m² of noise), the plain
+  solution stands; and a steady solve that fails outright is tried once more with the summed rows
+  in from the start. Such devices now solve directly, their currents right to ~1e-15.
 - **Immobile combinations** (trap states X⁰ and X⁻ under e⁻ + X⁰ = X⁻, with D = 0) conserve
   node by node, since nothing carries them anywhere. At each node the combination's weighted sum
   replaces one of its balance rows, kept at what it was when the solve began. The row is local
@@ -588,16 +740,26 @@ take about twice as long as before.
 - **Generation continuation.** A device with generation reactions (species made only from, or
   turned only into, fixed reservoirs, such as photogeneration from a photon reservoir) can be
   held far from equilibrium even with its terminals level, where bias continuation can't help.
-  If a direct solve fails there, the generation rates are scaled down to 10⁻¹² and ramped back
+  If a direct solve fails there, the generation rates are scaled down to 10⁻³⁰ and ramped back
   up, ×100 a step while each solve converges (warm from the last) and by the square root of the
-  factor when one doesn't. An illuminated 80 µm silicon diode solves cold this way in about 80
-  iterations.
+  factor when one doesn't, giving up when that factor falls below 1.5 (crawling, which time
+  steps do better); the pseudo-transient ramp then starts from the dimmer light's solution
+  rather than cold. (At 10⁻¹², a GaAs layer's generation still exceeded its equilibrium
+  recombination, ~3e-24 mol/m³ of minority electrons, a billionfold: the first step was the
+  whole jump.) An illuminated 80 µm silicon diode solves cold this way in about 80
+  iterations. (A lit n⁺pn stack with a floating base crawled for 20,000 iterations: at a
+  trillionth of the light, the base's level is held by couplings of ~1e-17.)
 - **If that fails too,** source continuation ramps the right terminal's voltage to its target.
   It ramps from the voltage of the last converged solve when the state is that solution, and
-  otherwise from level terminals, where a cold start is consistent. The ramp step starts at
+  otherwise from level terminals, where a cold start is consistent. (A device first solved
+  after a `set()` was laid out for its new voltages; if the level start fails from there, it's
+  laid out again, level, and retried.) The ramp step starts at
   1/8 of the way, grows ×1.5 on success and shrinks ×4 on failure.
 - **If Newton still fails,** $`dt`$ ramps up from a small value (pseudo-transient continuation),
-  ending in the direct solve where applicable.
+  ending in the direct solve where applicable. After a failed step it grows ×2, then ×1.5 more
+  each success, back to ×10. Once steps reach the slowest diffusion time, the direct solve is
+  tried from there, once a decade of $`dt`$ (the state kept if it fails): with immobile traps and
+  ions of D = 1e-17 m²/s, steps from 1e8 to 1e9 s kept failing on the way to the giant step.
 
 `solve()` does not advance the clock.
 
@@ -648,7 +810,11 @@ neutrality:
 - then storage (on the other balances) and neutrality go in, exactly, in those terms.
 
 A start-of-step net charge (round-off in a solved state) isn't carried over: the neutrality row
-holds the new state neutral. Steady solves and the impedance keep the plain rows (there's no
+holds the new state neutral. An end node that its contact holds (a bath, an electrode's level)
+keeps its plain rows, but the contact's current there is read before the ions' storage goes in,
+and a bulk law doesn't count the box's net charge as displacement: under neutrality neither
+carries charge, and read from the box's balance their round-off (∝ c/dt) cancelled only roughly.
+A bath floating on 1 µM beside 3 M KCl had rattled at 2e-5 thermal units on steps of 1e-14 s. Steady solves and the impedance keep the plain rows (there's no
 storage at $`dt = \infty`$, and the impedance reads the storage matrix from them).
 
 A sub-grid Gouy–Chapman law, treating the diffuse layers analytically when $`\lambda_D \ll h`$, is on

package/docs/reliability.md

@@ -0,0 +1,122 @@
+# How far to trust it
+
+A drift–diffusion solver is quick to start and slow to finish. The first version solves a pn
+junction; the trouble comes after, with what real devices ask of it:
+
+- concentrations spanning 30 orders of magnitude in one device (majority carriers beside
+  minority ones, a salt beside the ions its double layer excludes);
+- double layers a millionth of the device's length, resolved or not;
+- species whose amount is fixed rather than their level (a blocked ion, a floating base, a
+  closed cell's salt), which makes the steady equations singular;
+- populations held only by couplings of 1e-17 (an inversion layer fed by ~1e3 minority
+  carriers per cm³), which a factorisation loses to round-off;
+- terminals driven by a current, which may be beyond what the device can pass;
+- small-signal currents read from sums whose terms are 1e17 times bigger.
+
+Each of these makes a plain Newton solver fail, or worse, converge to the wrong answer. driftlet
+has met them, mostly through the two kinds of testing below, and its numerics are built around
+them ([numerics](numerics.md)). This page says what that testing covers and what it found, and
+what is known not to work.
+
+## Correct: the validation suite
+
+Every physics feature is checked against an analytic result, or an independent code where
+there isn't one: `npm test`, over 300 tests, each a worked device with its closed form. They include
+Shockley's diode equation, depletion and MOS charge, collection theory under Beer–Lambert light,
+Gouy–Chapman and Kilic–Bazant–Ajdari double layers, Donnan and Teorell–Meyer–Sievers
+partitions, Goldman–Hodgkin–Katz, the limiting current and Butler–Volmer kinetics, the
+Macdonald and finite-length Warburg impedances, Cottrell and spherical diffusion, and the
+second law (the free energy in through the terminals equals what's dissipated, every term
+non-negative). Against other codes: IonMonger's perovskite J–V hysteresis (finite elements,
+Octave), and liquid-junction potentials against JPCalc, LJPcalc and JLJP. The README's
+[validation table](../README.md#validation) lists each with its tolerance.
+
+Each solution can check itself too: `check()` from `driftlet/kit` balances every species'
+ledger (what comes in through each terminal, is made or destroyed), the conservation
+bookkeeping of a transient, and the grid (the device solved again on a grid twice as fine).
+
+## Robust: random devices
+
+The validation suite shows driftlet is right where it converges. Whether it converges, on
+devices nobody tuned it for, is what `npm run stress` tests. It builds random but plausible
+devices in five families:
+
+| Family | What's drawn |
+|---|---|
+| Semiconductor stacks | Si, Ge or GaAs; 1–3 layers n, p or intrinsic, doping 1e14–1e19 cm⁻³, 50 nm–10 µm each; no recombination, band-to-band or SRH (τ from 1 ns to 10 µs); sometimes lit; sometimes a Schottky contact |
+| MOS capacitors | Si, Ge or GaAs, doped 1e15–1e18 cm⁻³; oxide 1–20 nm; Au, Al or Pt gate at any flat-band offset; with or without generation |
+| Electrolyte cells | one to three salts from the data library's ions, 0.1 mM–1 M, 1 µm–1 mm; double layers resolved or strictly neutral; bath, reversible or blocking electrodes |
+| Electrodes | Ag, Cu or Zn deposition, or Fe³⁺/Fe²⁺ on platinum, with Butler–Volmer kinetics over four decades of k₀; with or without a supporting salt; against a second electrode or a bath |
+| Liquid junctions | two mixed solutions, 1 µM–1 M, sharp or graded, at open circuit |
+
+Each device goes through what a user would do with it: a cold solve at no bias, and one at a
+bias; a warm sweep to that bias; open circuit, where it's lit; a current drive (a fraction of
+what passes at 1 V); a transient after a voltage step; and the impedance about equilibrium,
+from far below its slowest relaxation to 1 GHz. Every result is judged by `check()`, and by what must hold whatever the device:
+levels flat at equilibrium with no current, warm and cold solves agreeing, the current driven
+being the one passed, the impedance passive (to 1e-3 of |Z|) and, at low frequency, equal to
+the steady dI/dV,
+and a MOS capacitance never above its oxide's. Each case is seeded from its family and index, so
+any failure reruns alone (`npm run stress -- semi 79`).
+
+At 500 devices per family (about three minutes on a desktop), 11,380 of 11,381 scenarios pass:
+
+| Family | Cold at 0 V | Cold at bias | Warm sweep | Open circuit or current | Transient | Impedance |
+|---|---|---|---|---|---|---|
+| Semiconductor stacks | 500/500 | 500/500 | 500/500 | 105/105 | 500/500 | 395/395 |
+| MOS capacitors | 500/500 | 500/500 | 500/500 | | 500/500 | 500/500 |
+| Electrolyte cells | 500/500 | 500/500 | 500/500 | | 500/500 | 381/381 |
+| Electrodes | 500/500 | 500/500 | 500/500 | 500/500 | 500/500 | 500/500 |
+| Liquid junctions | | | | 500/500 | 499/500 | |
+
+(Impedance only where the device has an equilibrium to linearise about; open circuit only for
+lit cells.) The one that fails is among the known limits below: a junction on a grid far too
+coarse for its double layers.
+`bench/stress.json` keeps the summary.
+
+Most of what driftlet's numerics do differently began as a failure here: the impedance's
+current read across the quietest cut of the device rather than at the contact, GMRES judged by
+its true residual, blocked species held flat in steady solves, continuations for a current drive
+and for light, and Newton refining its solves where a factorisation loses a mode, with an exact
+$`J \cdot v`$.
+
+## Hard cases
+
+`npm run hard` keeps a corpus of named cases that were hard once (sharp 3 M | 1 µM junctions on
+short steps, an inversion layer filling over minutes, a solar cell's open circuit on a 0.25 nm
+grid, corroding drops), with their step and factorisation counts against a committed baseline,
+so a change that makes one worse shows.
+
+## Known limits
+
+- **A population held only through couplings far below double precision** is solved in steady
+  state by refining Newton's solves, as far as its own equations resolve it: a bipolar stack's
+  floating base at bias (a p⁺ base whose holes are held ~1e14 more weakly than they move within
+  it) is, and a closed Fe³⁺/Fe²⁺ cell driven by a current near its limit, where Fe³⁺ falls 20
+  orders below Fe²⁺, is found as the held voltage that passes it. Where a solve fails, its warning
+  says where it lost its digits (a transient gets there). A region held only through its faces (by
+  conductances 1e-24 of its own, or by neighbours conducting 1e20 times less) is solved directly
+  through its balance summed over it, where its own fluxes cancel exactly
+  ([islands](numerics.md#steady-state)): its current comes out right to ~1e-15, where it was
+  up to 16× off. A population held that weakly within a region, or fed by a reaction, isn't
+  covered, and its solve can still converge to the wrong level; the terminal currents then
+  don't add up, which is the thing to check.
+- **The impedance is resolved to about 1e-4 of |Z|** where its solves are hardest: the real
+  part of a nearly ideal capacitor (a closed redox cell with almost none of one partner), 1e-7 of
+  |Z|, can come out slightly negative. Its DC limit matches the steady dI/dV in every stress case.
+- **Strictly neutral regions on very short steps** lose digits at a neutral face between very
+  different solutions (3 M against 1 µM at steps of 1e-11 s).
+- **An unresolved double layer** (a cell coarser than the Debye length) gives a charge that
+  depends on the grid, and in a sharp junction between very different solutions can stop a
+  transient; the solution warns. So does a steep profile on too coarse a cell.
+- **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.
+- **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
+  its digits, or which current no voltage reaches. In these tests, every steady state and
+  transient reported converged has passed `check()` and the invariants above.
+- What driftlet doesn't model at all (more than one dimension, cross-diffusion, heat, optics,
+  field-dependent mobility) is in the [README](../README.md#what-it-doesnt-do), and open
+  numerical work in the [roadmap](../ROADMAP.md).

package/llms.txt

@@ -14,9 +14,9 @@ docs/conventions.md (signs and levels) and docs/data.md (the data library).
 From a CDN, pin the version:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -210,8 +210,50 @@ console.log(check(dev, sol).text); // per compartment: Na⁺ leaks into the cyto
 ```
 
 Between two baths instead (the inside one `bath(inside, 'Cl-', { I: 0 })`: held composition, no
-current), V_m is GHK. Without the pump, a closed cell runs down to Donnan equilibrium. driftlet
-has no voltage-gated channels; a permeability can be changed with `set()` between steps.
+current), V_m is GHK. Without the pump, a closed cell runs down to Donnan equilibrium.
+
+## Template: an action potential
+
+Voltage-gated channels: a face's `gates` (each a fraction open with Hodgkin–Huxley kinetics,
+dx/dt = α(V)(1 − x) − β(V)x, in V = φ_right − φ_left), and a permeability scaled by them
+(`gates: { m: 3, h: 1 }`). `hodgkinHuxley()` in the kit writes the squid axon's: its gates, and
+GHK permeabilities matched to HH's conductances at rest. A pump-less cell has no steady rest
+(`solve()` finds Donnan), so start the transient from the concentrations given: the membrane
+settles within milliseconds.
+
+```js
+import { Device } from 'driftlet';
+import { build, layer, bath, aqueous, injector, pulse, hodgkinHuxley } from 'driftlet/kit';
+
+const T = 279.45; // HH's 6.3 °C
+const out = { 'Na+': 440, 'K+': 20, 'Cl-': 450, 'A-': 10 }, inside = { 'Na+': 50, 'K+': 400, 'Cl-': 52, 'A-': 398 }; // squid, mM
+const water = aqueous(['Na+', 'K+', 'Cl-'], { epsr: 0 });
+water.species.push({ name: 'A-', z: -1, cRef: 1000 });
+water.materials.water.species['A-'] = { D: 0.5e-9, mu0: 0 };
+const hh = hodgkinHuxley({ inside, outside: out, T }); // outside on the left
+const axon = new Device(
+  build({
+    T,
+    library: [water],
+    stack: [
+      bath(out, 'Cl-'),
+      layer('water', 5e-6, { name: 'outside', c0: out }),
+      { phi: { type: 'capacitive', C: 0.01 }, gates: hh.gates, species: { ...hh.species, 'A-': 'blocked' } },
+      layer('water', 20e-6, { name: 'cytoplasm', c0: inside }),
+      { species: { 'Na+': 'blocked', 'K+': 'blocked', 'Cl-': 'blocked', 'A-': 'blocked' }, phi: 'neutral' },
+    ],
+    // the stimulus: 10 µA/cm² of K⁺ for 1 ms at 20 ms, from a pipette in the cytoplasm
+    ports: [injector({ region: 'cytoplasm', from: 15e-6, to: 20e-6, species: 'K+', I: pulse({ start: 20e-3, width: 1e-3, amplitude: 0.1 }) })],
+    grid: { hmin: 50e-9, hmax: 1e-6 },
+  }),
+);
+let peak = -1;
+for (let k = 1; k <= 300; k++) {
+  const sol = axon.advance(k * 1e-4); // 0.1 ms at a time
+  peak = Math.max(peak, sol.interfaces[0].V); // V_m, and sol.interfaces[0].gates = { m, h, n }
+}
+console.log(`peak ${(peak * 1e3).toFixed(1)} mV`); // ~ +12 mV: GHK's Na⁺ current is limited by the 50 mM inside
+```
 
 ## Template: an electrode in a stirred solution
 
@@ -346,6 +388,11 @@ for (const Vd of [0.1, 0.5, 1, 1.5, 2, 3]) {
 }
 ```
 
+To sweep the gate on one device instead, patch the port by name: `dev.set({ ports: { gate: { V } } })`
+(a drive only, so it's cheap and keeps the state as a warm start). An organic electrochemical
+transistor is the same with a volumetric capacitance C*: `area: 1 / t, capacitance: { C: Cstar * t }`
+(docs/device.md, "A capacitance through a window").
+
 ## Template: a transient, with a pulse injected sideways
 
 A **port** feeds a window of nodes inside a region from the side (a point contact, an injector,
@@ -418,9 +465,9 @@ solve), as long as it settles rather than ping-pongs.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.10.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.12.0/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

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

package/src/blockTridiagonal.js

@@ -74,6 +74,14 @@ export class BlockTridiagonal {
     this.minPivotRatio = Infinity;
     /** The block found exactly singular by the last factor(), or −1. */
     this.singularBlock = -1;
+    /**
+     * Static pivoting: an exactly zero pivot (all its candidates cancelled to nothing) is
+     * replaced by 1e-15 of its block's largest entry rather than thrown on, for a caller that
+     * refines its solves (and counted in `perturbedPivots`).
+     */
+    this.staticPivots = false;
+    /** How many pivots the last factor() replaced. */
+    this.perturbedPivots = 0;
   }
 
   /** Zero all of A, B, C (ready for fresh assembly). */
@@ -86,13 +94,14 @@ export class BlockTridiagonal {
 
   /**
    * Factorise the current A, B, C. A, B, C are left untouched.
-   * Throws if a diagonal block is exactly singular.
+   * Throws if a diagonal block is exactly singular (unless `staticPivots`).
    */
   factor() {
     const { n, A, B, C, sizes, offA, offB, offC, offX } = this;
     const lu = this._lu, piv = this._piv, cp = this._cp, tmp = this._tmp;
     let minRatio = Infinity;
     this.singularBlock = -1;
+    this.perturbedPivots = 0;
 
     for (let i = 0; i < n; i++) {
       const m = sizes[i], o = offB[i];
@@ -110,7 +119,7 @@ export class BlockTridiagonal {
           }
         }
       }
-      const ratio = luFactor(lu, o, piv, offX[i], m);
+      const ratio = luFactor(lu, o, piv, offX[i], m, this);
       if (!(ratio > 0)) {
         this.factored = false;
         this.singularBlock = i;
@@ -244,7 +253,7 @@ export class BlockTridiagonal {
 
 // In-place LU with partial pivoting of the m×m block at a[o…]. Row swaps are recorded in
 // piv[p…]. Returns min |pivot| / max |entry| (0 if singular).
-function luFactor(a, o, piv, p, m) {
+function luFactor(a, o, piv, p, m, perturb = null) {
   let maxEntry = 0;
   for (let k = 0; k < m * m; k++) {
     const v = Math.abs(a[o + k]);
@@ -259,7 +268,11 @@ function luFactor(a, o, piv, p, m) {
       if (v > bestVal) { best = r; bestVal = v; }
     }
     piv[p + k] = best;
-    if (bestVal === 0) return 0;
+    if (bestVal === 0) {
+      if (!perturb?.staticPivots) return 0;
+      bestVal = a[o + best * m + k] = 1e-15 * maxEntry;
+      perturb.perturbedPivots++;
+    }
     if (bestVal < minPivot) minPivot = bestVal;
     if (best !== k) {
       for (let c = 0; c < m; c++) {