driftlet 0.14.0 → 0.16.4

package/docs/numerics.md

@@ -275,13 +275,30 @@ current into the device, $`I`$. Assembly records, for each:
 A floating terminal's voltage is an extra unknown, with its circuit law as an extra row:
 $`I - I_{\mathrm{set}} = 0`$ (driven by a current) or $`I - (V_{\mathrm{src}} - V)/R = 0`$ (behind a
 resistance). These don't fit the block-tridiagonal matrix $`T`$ (a port couples to its whole
-window), so they're solved by bordering, together with the spectators' conservation rows (see
-[steady state](#steady-state)): with $`y = T^{-1}\,\mathrm{rhs}`$, $`X_k = T^{-1} B_k`$ and
-$`Q_q = T^{-1} e_q`$ (the response to a unit pin), the update is
+window), so they're solved by bordering, together with a steady solve's dense rows, the
+conserved amounts' and islands' (see [the steady system](#the-steady-system)): with
+$`y = T^{-1}\,\mathrm{rhs}`$, $`X_k = T^{-1} B_k`$ and $`Q_q = T^{-1} e_q`$ (the response to a unit
+pin; for a flat stretch's amount, to its shift), the update is
 $`\delta = y + \sum Q_q \mu_q - \sum X_k\, \delta V_k`$, and the $`\mu`$ (pins) and $`\delta V`$ (terminals)
 come from a small dense system of the extra rows. Each costs one more back-substitution per
 Newton iteration.
 
+A floating terminal (driven by a current, or behind a resistance) that alone feeds a conserved
+combination (a host's electrons behind an open circuit, a gate's metal) can read its current
+another way in a time step: as the combination's change, $`F\,(S - S^*)/(\lambda\, dt)`$, which the step's balance rows
+sum to exactly (λ is its weight over the terminal's charge, $`w/z`$). Both readings are exact;
+they differ in round-off, and in what Newton can see. Through a metal, the flux is $`G\,\Delta\eta`$
+with its two $`\eta`$ all but equal: a floating gate's charging current fell below that at steps
+of ~0.03 s, and the bordered system came out exactly singular (a gate at rest took 5000 steps
+per 100 s, half rejected, where a held one takes 44). Over long steps the flux lets a closed host
+drift from its charge (3 mV over 5e11 s, and steps failed by 4e12 s), where the change keeps
+it. Over short ones the change is the amount's round-off over $`dt`$ (a cathode's 0.04 mol/m² of
+electrons, 1e-6 A/m² at 1 µs), and the flux, its levels carried in two words, is far cleaner. So
+a step reads the change where its round-off, $`\varepsilon F S/(\lambda\, dt)`$, is below 1e-6 of
+the flux's estimate, $`\varepsilon\,\max|C|`$, and a step read by the flux that fails is tried once
+more read by the change. (A gate charged through a resistance, read by its flux, was 0.9% off
+backward Euler's exact RC response, silently; read by its change, it's exact to round-off.)
+
 Sources are read at the end of a step (implicit), or at the present time in a steady solve.
 `advance()` lands on every waveform breakpoint and restarts its order there.
 
@@ -430,7 +447,7 @@ test checks the compact Jacobian column by column on devices that cover every as
 ### 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)`$;
+$`\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'
@@ -453,9 +470,14 @@ which cost four assemblies per product.
 ## Newton
 
 - The update of the device's potentials ($`\hat\phi`$, $`\eta`$) is limited to 10 thermal units per
-  iteration by uniform scaling, which scales a floating terminal voltage's update too. That
-  voltage doesn't count toward the limit: it enters only linearly (conductance links, held
-  levels, a capacitive face), so a large swing in it is safe. When it did count, a port driven by
+  iteration by uniform scaling: one factor for the whole update, concentrations' $`\eta`$ with
+  their $`\hat\phi`$, gates, coverages and floating terminal voltages alike, so the damped update
+  keeps Newton's direction. Clipping each unknown at its own limit would not: where it bit,
+  $`\eta - z\hat\phi`$ (a concentration) would move by up to a factor $`e^{10}`$ that Newton never
+  asked for. Either way damping shapes only the path, since convergence needs a full, undamped
+  update. A floating terminal voltage's update doesn't count toward the limit, though: it enters
+  only linearly (conductance links, held levels, a capacitive face), so a large swing in it is
+  safe. When it did count, a port driven by
   a current pulse, its voltage collapsing by hundreds of volts as the current switched off,
   dragged every unknown along 10 thermal units at a time (and a swing past 1e4 tripped the
   divergence check): the strong-injection Haynes–Shockley benchmark took 55% more
@@ -499,7 +521,14 @@ which cost four assemblies per product.
   ~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.
+  so a small update still means a small residual), and its refined solves correct the rest. So
+  is a pivot that's round-off alone without being exactly zero, below 1e-18 of the magnitudes it
+  was formed from (the running bound below, carried only for a block whose pivots look small):
+  otherwise its value, whatever the round-off happened to leave, scales all that follows. Strictly
+  neutral water whose level only the fast couple at its far face held had its last node's pivot
+  at 7e-32 with the species listed one way and 3e-16 the other; at 7e-32 the face's block was
+  scaled by 1e31, lost its own pivot outright, and the solve failed in that listing alone. (At
+  1e-15 a pivot can still hold a digit Newton needs: a port's steady solve then wandered.)
 - 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
@@ -569,8 +598,11 @@ which cost four assemblies per product.
   - 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.
-  - Newton starts each step from the state extrapolated through the last three, which saves
-    about a third of the iterations.
+  - Newton starts each step from its unknowns extrapolated through the last three states, which
+    saves about a third of the iterations. Only its unknowns: the slots it never solves for
+    include a gauge, an insertion host's $`\hat\phi`$, which extrapolated through steps that grow
+    wandered off geometrically (to 1e11 thermal units by 1e5 s), until the levels measured from
+    it lost their digits and every step failed.
   - The wall-clock budget is checked between steps.
 
 ## Small-signal impedance
@@ -638,78 +670,147 @@ only resolved to ~1e-4 of $`|Z|`$.
 
 ## Steady state
 
-- **If every species stretch is fed by a contact,** nothing is conserved on its own, and the
-  true steady equations are solved directly ($`dt = \infty`$, no storage term). This matters
-  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
-  conservation of the amount, $`\sum v c = \mathtt{amount}`$. That row is dense, so the solve is
-  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. 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
-  $`w`$-weighted sum of their balance rows is zero identically (the reactions cancel by
-  $`w \cdot \nu = 0`$, and nothing crosses the stretches' ends), so one of them is replaced by
-  $`\sum_k w_k \sum v c_k =`$ the combination's amount, bordered like a spectator's. (Spectators
-  are the one-stretch case.)
-
-  Holding the amount through a storage term at huge $`dt`$ instead is badly conditioned: the
-  stretch's level is then held only by $`v \cdot c/dt`$, against internal conductances $`D \cdot c/h`$
-  larger by $`D \cdot dt/(hL)`$, around 1e12 for a micron-scale cell (see
+A steady state is where a transient from the present state ends. `solve()` finds it without
+stepping there, as the solution of the steady equations ($`dt = \infty`$, no storage term): slow
+physics can take seconds or hours, far beyond any $`L^2/D`$ estimate (exponentially scarce
+minority carriers slowly filling an inversion layer behind a Schottky contact), and stepping
+would never finish. Three things make that more than one Newton solve: without the storage term,
+the steady equations say nothing of what the transient conserved; some levels are held so weakly
+that a factorisation loses them; and Newton needs a start near enough. `solve()` does not advance
+the clock. Nor does it ask whether the steady state is stable: an axon held at a current that
+makes it fire over and over has a resting point all the same, which `solve()` returns, and only
+a transient leaves it.
+
+### The steady system
+
+Every row of a steady solve that differs from a time step's is a sum of balance rows, or (a
+reaction's affinity) a condition equivalent to one. It's written out in its telescoped form,
+never added up from the rows themselves, so what the sum leaves is exact, however small beside
+the terms that cancel:
+
+- **A conserved amount.** A combination of stretches (weights $`w`$) that no reaction changes and
+  nothing outside feeds has balance rows that sum to zero identically in a steady state: the
+  fluxes cancel across its stretches, and the reactions by $`w \cdot \nu = 0`$. One of those rows
+  is redundant, and the combination's amount, $`\sum_k w_k \sum v c_k`$, stands in for it. That's
+  what a time step's own sum, $`w \cdot (S - S_0)/dt = 0`$, says at any $`dt`$.
+
+  The combinations are the null space of the stoichiometry (a row per reaction, over the
+  stretches it touches) together with what the terminals feed, worked out once and again after a
+  change of drive. A terminal held at a voltage (or behind a resistance, which holds it at steady
+  state) feeds each stretch it links freely. One driven by a current feeds its charged species
+  only as that current allows, in proportion to their charges. So:
+  - a **spectator** (a species blocked all round) keeps its amount;
+  - so does each **moiety**: the total iron of Fe³⁺, Fe²⁺ and FeCl²⁺ in a closed cell with a
+    complexation reaction;
+  - so does what a **terminal at no current** alone feeds. A closed battery at open circuit
+    has one steady state per state of charge, and a solve that imposed only I = 0 had converged
+    to another (4.145 V where its start said 3.958 V). A terminal that passes current only by
+    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.
+  - 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
+    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 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
+  factorised matrix gets a pin, an identity row, in place of the balance row, which makes the
+  stretch's level a well-conditioned unknown, and the response to a unit pin (one more
+  back-substitution) goes in at whatever weight satisfies the amount. Behind a terminal at no
+  current, the amount stands in for the terminal's circuit row instead: at no current that row is
+  the sum of the combination's balance rows, so it says nothing new. (An electrode's charge, which
+  moves with the terminal's voltage, goes only there.) The rows replaced must be independent:
+  each combination's weights over them a nonsingular matrix, or one balance is said twice and
+  another not at all. Picked one combination at a time, two complexations sharing A
+  (A + B = AB, A + C = AC) had −A + B + C in place of B's row, B + AB of AB's and A − B + AC of
+  A's, and the solve converged to a state that wasn't steady, depending on the order the species
+  were listed in. So they're chosen by elimination.
+
+  Holding an amount through a storage term at a huge $`dt`$ instead is badly conditioned: the
+  stretch's level is then held only by $`v \cdot c/dt`$, against internal conductances
+  $`D \cdot c/h`$ 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.
+  iterations, or fails. It's left only where a species is still in one region and moves in the
+  next: there, backward-Euler steps at a huge $`dt`$ (10⁶ × the slowest diffusion time) keep
+  the storage term, growing ×10 (capped) while the state still moves, each spectator's level
+  first shifted uniformly to restore its amount exactly (round-off creeps through the vanishing
+  storage term), and one last step at the base huge $`dt`$, where pinning is tight.
+- **A flat level.** A species that no reaction or port touches, reached by one contact at most,
+  carries no flux in a steady state: every sum of its balance rows from its closed end is the
+  flux through one segment, zero. In an ideal region without flow or mixing that's a level flat
+  across the segment, so its level is flat throughout: its contact's, or reaching none (a
+  spectator), the level its amount fixes. Steady solves (not the impedance, where it carries a
+  current) hold it there in place of its balances, rather than find it through its own
+  conduction, which can be all but nothing. A level found that way can't be moved: a MOS
+  capacitor's inversion electrons reach the back contact only through a bulk with ~1e3 of them
+  per cm³, and with that contact moved, each solve failed through ~90 pseudo-transient steps;
+  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). (A
+  level that starts flat stays exactly so either way: carrying nothing, the flux's expm1 form is
+  exactly zero, whatever $`\phi`$ does.) A spectator's first node keeps its amount's row, a pin
+  whose response is the whole stretch's shift, so the stretch moves as a whole. At a face inside
+  the stretch whose link holds the level continuous, the face's flux, which only the replaced edge
+  balances set, is pinned to zero too. (Not through flow or mixing, nor a concentrated material's
+  cross-diffusion, where zero flux isn't a flat level.) Species that react only among themselves
+  are held flat the same way where each reaches the same one contact and nothing else, their
+  reactions balanced at its levels: one reservoir drives nothing, so in a steady state they're at
+  equilibrium. A MOS capacitor's electrons and the holes they recombine with reach only its back
+  contact; moved, slow generation through a bulk of GaAs with ~1e-4 electrons per cm³ couldn't
+  carry the inversion layer's level with it (of 500 random MOS capacitors, 38 failed and 5
+  converged to a gate charge up to 2× off).
+- **A reaction's equilibrium.** A face reaction that alone changes some combination (left out, the
+  combination would be conserved: Ag⁺ closed in a cell where Ag⁺ + e⁻ = Ag(s) is its one source, or
+  Ag⁺ + AgNO₃ where it also complexes) makes that combination's summed balance its rate, which a
+  steady state sets to zero. The rate is a poor row, though: $`k_0`$ times a function of the levels,
+  beside the round-off of diffusion's terms in the same balances. An Ag⁺/Ag couple 1e-20 as fast as
+  Fe³⁺/Fe²⁺ on the same platinum at open circuit was lost to it, the solve settling where silver
+  wasn't (−0.4661 V, against the joint equilibrium's −0.5004 V), and 1e-15 to 1e-18 failed. The
+  reaction's affinity, $`a = A_\text{fixed} - \sum \nu \eta = 0`$, says the same at any $`k_0`$
+  (each kinetic form vanishes only there), so it stands in for one of the combination's balance
+  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
+  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
+  a metal's carriers' row or a row a terminal feeds, which carry its current (the platinum's
+  electrons standing for an iron couple put the electrode at 602 V). And not where a terminal driven
+  by a current feeds the combination, since the sum is then the rate plus what that terminal passes;
+  a current held at zero passes nothing, so an open-circuit electrode feeding a closed pool of Ag⁺
+  is covered (from an iron k₀ of 1e-15 beside it, that settled 78 mV off).
+
+  Where a reaction can't stand on its affinity (a bulk reaction, whose rate summed over the
+  region vanishing needn't make it vanish everywhere, or an electrode port's), a steady solve
+  that leaves it with one sign of affinity wherever it acts, though nothing else changes what
+  it does, can't be a steady state: its rate is merely too small to see. The solution warns of
+  it, rather than pass the start's composition off as steady (a slow complexation had kept its
+  starting composition, K = 0.1 for 7.5, without a word).
+- **An island's balance.** A piece of a stretch between its faces that nothing else feeds (no
+  contact, port or reaction) holds its level 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 replaces the first node's row, bordered like an 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
@@ -723,45 +824,66 @@ only resolved to ~1e-4 of $`|Z|`$.
   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
-  to that node's block, so nothing is bordered, and the solve goes direct.
-- **Otherwise** (an immobile spectator on its own, or a combination that includes a floating
-  conductor or mixes mobile and immobile stretches), backward-Euler steps at a huge $`dt`$ (10⁶ × the slowest
-  diffusion time) keep the storage term, which pins each conserved amount exactly: sum a
-  species' rows and the fluxes cancel. $`dt`$ grows ×10 (capped) while the state still moves.
-  Before each huge step, each spectator's level is shifted uniformly to restore its amount
-  exactly (in one step for ideal statistics, by Newton on the shift otherwise). It guards
-  against round-off creeping through the vanishing storage term. The solve finishes with one
-  step at the base giant $`dt`$, where pinning is tight.
-- **If a direct solve diverges,** it's retried once with tighter damping (3 thermal units per
-  iteration). That's enough for most large jumps, such as a cold start at forward bias.
-- **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
-  up, ×100 a step while each solve converges (warm from the last) and by the square root of the
-  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. (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. 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.
+
+All four move a weakly held level as a whole, where a factorisation can't: an amount's, an
+affinity's or an island's pin by a shift it solves for, a flat level by holding every node to one. What the
+factorisation still loses elsewhere, Newton's refined solves recover ([Newton](#newton)).
+
+### Reaching it
+
+A solve that fails falls back stage by stage:
+
+1. **Newton from here.** If it diverges, it's retried once with tighter damping (3 thermal units
+   per iteration), enough for most large jumps, such as a cold start at forward bias. Where no
+   continuation applies, the first stage goes straight on into the pseudo-transient ramp (3).
+   Where the state is a transient's, it can be a worse start than a cold one (a nanosecond after
+   a lit MOS capacitor's gate jumps, its surface is in deep depletion, minority carriers ten
+   orders below where they end): if Newton fails from there, the solve goes on as a cold device
+   would, from the layout for the drives, keeping what it took from the state (its amounts and
+   charges). Nor does a continuation start from the last steady solve's voltages once a
+   transient has moved the state.
+2. **Continuation from a solved state, along the drives,** each step a steady solve warm from
+   the last:
+   - **The light.** 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 a voltage ramp can't help; nor can a
+     time step, since light flooding minority carriers 20 orders below their lit level makes even
+     a step of 1e-16 s a jump Newton can't take. The generation rates are scaled down to 10⁻³⁰ and
+     ramped back up, ×100 a step while each solve converges and by the square root of the 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.)
+   - **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. (Not a terminal at no current that keeps an amount or a
+     charge: every voltage passes nothing there.)
+   - **The voltages.** The right terminal's voltage ramped to its target: from the contacts'
+     voltages at the last converged solve when the state is that solution (the left one first,
+     where it moved), and 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 step starts at 1/8 of the
+     way, grows ×1.5 on success and shrinks ×4 on failure. The ramp's own start, with the
+     terminals level, ramps the light up when there is some.
+3. **The pseudo-transient ramp.** $`dt`$ ramps up from a small value, through time, ending in
+   the direct solve. 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 end.
+
+Each of these carries cases that nothing else does (switched off one at a time, each fails
+tests or stress cases the others pass).
 
 ## Conservation
 
@@ -771,7 +893,8 @@ only resolved to ~1e-4 of $`|Z|`$.
   charge to round-off.
 - **The iterate conserves to Newton's tolerance.** Storage is nonlinear in $`\eta`$, so each step's
   drift is its summed residual. Converging to 1e-10 in $`\eta`$ makes that ~1e-15 per step in
-  practice.
+  practice; but over steps of 1e10 s, the residual times $`dt`$ adds up, which is why a terminal
+  at no current reads its current there by what it keeps ([terminals](#terminals)).
 - **Reported.** Every solution's `conservation` lists each species stretch: its amount, its
   reference, the time-integrated flux through its contacts, and the resulting drift.
 

package/docs/reliability.md

@@ -84,7 +84,7 @@ recipes.
 | Electrodes spread through a port | transmission line with the reaction's linear kinetics as the conductance (O(h²)), rates along it; Wagner–Traud mixed potential of two Butler–Volmer couples, floating | 1e-4, 2e-3; 1e-6 V |
 | Impedance | Macdonald blocking-electrode spectrum, 100 Hz–1 GHz; finite-length Warburg (Ag \| AgNO₃ \| Ag); DC limit = differential resistance; a p⁺n⁺ junction without recombination, Re Y → dI/dV and C = dQ/dV; a redox electrode against a bath at its open circuit, Re Y → dI/dV; a MOS capacitor with a metal gate and a channel port, C = dQ/dV at the gate, passive at the back | 3e-4; 3e-5; 1e-6; 1e-4, 1e-6; 1e-4; 1e-3 |
 | Conservation | per step, and against time-integrated contact fluxes | 1e-11 relative |
-| Strictly neutral limit (ε = 0) | Planck EMF; polarization with no overlimiting; Donnan at neutral faces | 1e-5; 1e-4; 1e-9 |
+| Strictly neutral limit (ε = 0) | Planck EMF; polarization with no overlimiting; Donnan at neutral faces; an ion exchanger between baths (Donnan at the contacts, Teorell–Meyer–Sievers salt flux); a capacitive face's edge cell as a diffuse layer in series | 1e-5; 1e-4; 1e-9; 1e-9, 1e-6; 2e-3 |
 | Fermi–Dirac statistics | `𝓕_{±1/2}` vs quadrature; degenerate bulk; accumulation charge via `𝓕_{3/2}` | 1e-13; 1e-12; 1e-3 |
 | Crowded double layer (lattice gas) | Kilic–Bazant–Ajdari charge, up to `ψ = 40 V_T`; custom function reproduces it | 5e-4; 1e-10 |
 | Non-ideal transport | steady flux −(D/L)ΔP of the grand potential (lattice exact, Redlich–Kister O(h²)) | 1e-12; 1e-4 |
@@ -108,26 +108,29 @@ devices in five families:
 
 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:
+what passes at 1 V); a MOS capacitor's back contact moved under its biased gate; 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
+the steady dI/dV, a MOS capacitance never above its oxide's, and its gate charge with the back
+contact moved what it is with the gate moved the other way. 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:
+At 500 devices per family (about three minutes on a desktop), 11,880 of 11,881 scenarios pass:
 
-| Family | Cold at 0 V | Cold at bias | Warm sweep | Open circuit or current | Transient | Impedance |
+| Family | Cold at 0 V | Cold at bias | Warm sweep | Open circuit, current or back contact | 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 |
+| MOS capacitors | 500/500 | 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
+lit cells.) The MOS back contact came last: before steady solves held a group of reacting
+carriers flat where it reaches one contact alone, 43 of the 500 failed it, 5 of them silently
+(a gate charge up to 2× off). 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.
 
@@ -169,6 +172,9 @@ 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

@@ -53,6 +53,8 @@ most one model.
 
 ### Fermi–Dirac
 
+Where electrons or holes under ideal (Boltzmann) statistics exceed $`c_{\mathrm{ref}}`$, the effective
+density of states, the solution warns: they're degenerate, and this is the statistics to give.
 For electrons and holes, $`c_{\mathrm{ref}}`$ is the effective density of states and $`\mu^\circ`$ the
 band edge, as for ideal statistics, and $`c = N_c \mathcal{F}_{1/2}(\zeta)`$ with the normalised
 Fermi–Dirac integral ($`\mathcal{F}_j \to e^\zeta`$ for $`\zeta \to -\infty`$). driftlet evaluates
@@ -135,7 +137,20 @@ A flat plateau means phase separation, which isn't supported yet. The table is r
 $`\zeta = \ln(x/(1-x)) + r(x)`$: the residual $`r`$, the host's non-ideality, is a shape-preserving
 cubic between points and continues linearly beyond them. Ideal and regular-solution curves are
 therefore reproduced exactly, and $`x`$ stays within $`(0, 1)`$ at any potential. The interpolated
-curve is checked for monotonicity at construction.
+curve is checked for monotonicity at construction. A curve far flatter than the ideal term near
+an end (E falling by millivolts over the last few percent of x) can fail that check however
+many points it has, since r then changes as steeply as the logarithm: give the ends some of the
+ideal slope (adding −0.5 (RT/F) ln(x/(1−x)) there passes).
+
+With `A` instead, the curve is the isotherm's, against a reference where the combination's
+chemical potential is 0, with $`g`$ the excess chemical potential ($`\Omega(1-2x)`$ for `A: [Ω]`):
+
+```math
+E(x) = -\frac{\mu^\circ_{\mathrm{ion}} + \nu\mu^\circ_{\mathrm{carrier}} + RT\ln\frac{x}{1-x} + RT\ln\frac{c_{\mathrm{max}}}{c_{\mathrm{ref}}} + g(x) - g(0)}{zF}
+```
+
+So an ideal host given `cRef` = `cMax`, the ion's `mu0` $`= -zFE^\circ`$ and the carrier's 0 sits at
+$`E^\circ`$ half full.
 
 Because every charged species sits in a neutral combination, **$`\phi`$ is undefined** in such a
 host and is reported as `NaN`. Its faces must be `neutral` (the default next to such a host),
@@ -147,14 +162,23 @@ the ions. The carrier's `cRef` plays no part (only the combination's $`\mu^\circ
 `cRef` enter), but it must still be given.
 
 The ion's `D` is its dilute-limit coefficient, as everywhere: the chemical diffusivity, $`D`$
-times the thermodynamic factor, follows from the OCV's slope. For an ideal-solution curve,
+times the thermodynamic factor, follows from the OCV's slope (with the carrier far faster than
+the ion, as usual; else the two combine as $`D_i D_e/(D_i + D_e)`$, ambipolar diffusion). For an ideal-solution curve,
 $`E = E^\circ - (RT/F)\ln(x/(1-x))`$, it's $`D/(1-x)`$, so a host filling toward $`x = 1`$
 diffuses ever faster, and a $`D`$ measured mid-range isn't the one to give. (A constant chemical
 diffusivity isn't expressible.) A host that only stores what comes in, filling at a constant
-current through its collector, has no steady state: `advance()` it from its `c0`. In a sphere,
+current through its collector, has no steady state: `advance()` it from its `c0`. At no
+current it has one per state of charge, and a steady solve keeps the charge it holds, so in a
+titration (GITT) each rest's OCV is a `solve()` at `I: 0` after the pulse's `advance()`, with no
+need to wait out the relaxation. What a pulse measures is the chemical diffusivity, and the
+textbook estimate from it assumes a small pulse: over $`\Delta x \approx 0.1`$ it's off by up to
+×7 near an end of the curve, against a host that has exactly the diffusivity it's given. In a sphere,
 `geometry: { type: 'spherical', r0: 0 }`, with the centre sealed (`{ phi: 'neutral' }`, every
 species blocked), the ion held at the surface by its reference and the electrons fed by a port
-there (a current into the device: negative, to fill a cathode).
+there (a current into the device: negative, to fill a cathode). A port's `conductance` link
+adds its ohmic drop, about $`I/(G w)`$, to the voltage read, which is no part of the host: give it
+a large $`G`$ (1e15 S/m³ over a window of 2% of the radius), and see that the voltage doesn't move
+with it.
 
 An insertion host belongs with [conductor regions](device.md#materials) more than with the other
 statistics here. Both are conductors with no $`\phi`$ of their own: