driftlet 1.2.4 → 1.3.0

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

@@ -94,13 +94,18 @@ Two optional transport terms describe a moving fluid:
 
 - **Advection** by an imposed velocity $`v`$ adds $`v \cdot c_i`$ to every mobile species' flux.
 - **Eddy mixing** adds $`-(D_{\mathrm{mix}}/RT) P \nabla\bar\mu`$, with
-  $`P = C - C z z^\mathsf{T} C / (z^\mathsf{T} C z)`$ and $`C = \mathrm{diag}(c)`$.
+  $`P = K - K z z^\mathsf{T} K / (z^\mathsf{T} K z)`$ and $`K = \partial c/\partial\zeta`$ (the
+  statistics' $`K`$; $`\mathrm{diag}(c)`$ when dilute).
   - It's an Onsager term: symmetric, positive semi-definite, and zero at equilibrium (flat
     $`\bar\mu`$), so double layers at rest are untouched.
   - The projection removes any current ($`z^\mathsf{T} P = 0`$). Eddies move neutral fluid, so
     they mix salt and stir concentration gradients but conduct nothing.
-  - For a neutral dilute species it's exactly $`-D_{\mathrm{mix}} \nabla c`$. For a binary salt it
-    adds $`D_{\mathrm{mix}}`$ to the salt's ambipolar diffusivity and leaves diffusion potentials
+  - Since $`K\nabla\zeta = \nabla c`$, it's $`-D_{\mathrm{mix}} \nabla c`$ for every species in a
+    neutral solution, under any statistics: eddies carry parcels of fluid, so they mix
+    concentration, not activity. (Molecular diffusion differs on purpose: a molecule's own random
+    walk is driven by the thermodynamic force, so its mobility is $`D c`$, above.) For a neutral
+    dilute species it's $`-D_{\mathrm{mix}} \nabla c`$ anywhere. For a binary salt it adds
+    $`D_{\mathrm{mix}}`$ to the salt's ambipolar diffusivity and leaves diffusion potentials
     unchanged.
 
 ## Materials, regions, interfaces

package/docs/device.md

@@ -589,6 +589,11 @@ ports: [{
 }]
 ```
 
+The window holds exactly `to − from` of exchange, electrode and capacitance however the grid
+falls: each node whose box reaches into it takes the part of its box inside. A held level
+(`'equilibrium'`) holds the nodes inside the window, so it needs one there. A window of no width
+is the node at that point, its whole box.
+
 On a [conductor region](#materials), a port is a wire to the whole conductor: it takes no window,
 only the conductor's carrier, and a conductance link's `G` is per area (S/m², a resistance
 $`R \cdot A`$ to the port's voltage as $`G = 1/(R \cdot A)`$). That's how a floating electrode is tied
@@ -1007,7 +1012,11 @@ const now = dev.solution();                   // snapshot of the current state
   and nothing warns of it: in a porous electrode, $`\sqrt{\kappa/(\omega C a)}`$ (cells of 2 µm
   against a 3.4 µm depth put Z 7% off, falling as the cells do; at an electrode, the diffusion
   length $`\sqrt{2D/\omega}`$ at the highest frequency). The result is `{ f, Z: { re, im },
-  warnings }`, the warnings being the steady state's. With `profiles: true`, `profiles[k]` holds
+  relError, warnings }`: `relError[k]`, each Z's estimated error relative to $`|Z|`$ (from
+  round-off in the current and the solves' residuals, and cautious: it can exceed the true error
+  many times), and the warnings, the steady state's and one where a Z isn't resolved (an error
+  over 1%: far below a capacitive device's relaxation, almost no current flows, and what does is
+  lost to round-off) or Re Z is under a tenth of its error, relError·|Z|. With `profiles: true`, `profiles[k]` holds
   frequency k's complex profiles, `{ phi, mu: {name}, c: {name} }`, each `{ re, im }` at the
   nodes (`NaN` where a quantity doesn't exist), per unit excitation: a volt, or an A/m² where the
   terminal is driven by a current.

package/docs/internals.md

@@ -16,10 +16,17 @@ them is wrong: fix both, with a test, in the same commit.
 | `src/laws.js` | yes: the steady system's conservation laws |
 | `src/lawRows.js` | yes: the laws written into the Newton system, and the bordered solve |
 | `src/timeSteps.js` | yes: one step (backward Euler, BDF2), advance's halving, integrate's error control |
+| `src/start.js` | yes: the cold start, from each region's c0 and the contacts' and ports' levels |
+| `src/newton.js` | yes: Newton's iteration, its scaled rows, GMRES-refined solves and the islands' round |
+| `src/assemble.js` | yes: the equations assembled, the conventions of every row, and the order of the terms |
+| `src/regions.js` | yes: statistics, storage, fluxes along segments, bulk reactions, the neutral nodes' charge rows |
+| `src/boundaries.js` | yes: faces (φ laws, links, reactions, gates), ports, contacts, circuit rows |
+| `src/steady.js` | yes: steady solves, their stages and continuations, the pseudo-transient ramp |
+| `src/impedance.js` | yes: the small-signal impedance, its readouts and profiles |
 | `src/difference.js` | header: the dilute kernels in difference form |
 | `src/blockTridiagonal.js` | header: the block Thomas solver |
 | `src/statistics.js` | header: each model's `evaluate` / `invert` |
-| `src/solver.js` | not yet (below) |
+| `src/solver.js` | no: setup, bookkeeping and drivers, described below |
 
 ## From a definition to a solution
 
@@ -46,7 +53,9 @@ them is wrong: fix both, with a test, in the same commit.
   its block (−1: inactive), `rix[o]` its index in compact vectors, with `rix = N` (the sink) for
   inactive ones. `res`, `delta` and the Jacobian (`sys`, a `BlockTridiagonal`) are compact.
 - **Unknowns** are `u + uLo`, a double-double, so that differences of η keep their digits; the
-  Jacobian and solves are plain doubles. Concentrations `c[g·n + i]` and coverages
+  Jacobian and solves are plain doubles. (η is read as `u + uLo` wherever a difference of levels
+  is taken; φ̂ in the statistics and the displacement, a face's own slots and the gates as `u`
+  alone.) Concentrations `c[g·n + i]` and coverages
   `th[g·nSurf + q]` follow from `u` (`computeConcentrations`).
 - **Terminals:** 0 the left contact, 1 the right, `2 + k` port k. A floating terminal (driven by
   a current, or behind a resistance) has its voltage as an extra unknown and its circuit row
@@ -61,24 +70,34 @@ By method, in file order:
 
 - **Setup:** the constructor (layout, per-node data, φ-undefined regions, terminals),
   `_activeSlots`, `_findStretches` (stretches, flat stretches), `_laws` and `_structure` (the
-  laws, from `src/laws.js`), `_directSteady`.
+  laws, from `src/laws.js`).
 - **Applying the laws** is `src/lawRows.js` (`captureLaws`, `captureLocal`, `snapFlat`,
-  `applyLaws`, `solveBordered`), called from `assemble`, `newton`, `_refine` and the steady
-  solves; `_replaceRow` and `_j`, which it uses, stay in the solver.
-- **Starting state:** `initFromComposition`, `_surfaceStart`.
-- **Statistics and assembly:** `computeConcentrations`, `_nodeStatistics`, `assemble` and the
-  kernels it calls (nodes, segments, faces, bulk reactions, ports, contacts, charge rows),
-  `_assembleDifference` (with `src/difference.js`).
-- **Newton:** `newton`, `_refine`, `_equilibrate`, `_kirchhoff`, `_noteConditioning`.
+  `applyLaws`, `solveBordered`), called from `assemble`, Newton and the steady solves.
+- **Starting state** is `src/start.js` (`initFromComposition`, which the Solver's own calls);
+  `_surfaceStart`, which the API uses too, stays in the solver.
+- **Assembly** is `src/assemble.js` (`assemble`, `_assembleDifference` with `src/difference.js`,
+  `_assembleBookkeeping`, and `_j` and `_replaceRow`, which write the Jacobian), with its kernels
+  in `src/regions.js` (`computeConcentrations` and the statistics, nodes, segments, bulk
+  reactions and their rates, `_chargeRows` and `_untransform`) and `src/boundaries.js` (faces,
+  `_terminals`: ports, contacts, circuit rows). Their methods are the Solver's own (installed on
+  its prototype), since every term reads and writes its arrays.
+- **Newton** is `src/newton.js` (the iteration, its row scaling, the GMRES-refined solves, the
+  islands' second round), which the Solver's own `newton` calls; `_factor` stays in the solver.
 - **Time steps** are `src/timeSteps.js` (`step`, `advance`, `integrate`, the predictor and the
   error norm), which the Solver's own `step`, `advance` and `integrate` call; `_snapshot` /
   `_restore`, `_warmFrom` and `_probes`, which the API uses too, stay in the solver.
-- **Small signal:** `impedance` and the helpers after it.
+- **Small signal** is `src/impedance.js` (`impedance` and its helpers: the current cuts, the
+  regions' uniform shift, the profiles; the complex GMRES and small dense solve), methods of the
+  Solver like the assembly's.
 - **Bookkeeping:** `segmentFluxes`, `faceOneWay`, `_assembleBookkeeping`, the contacts' intake.
-- **Steady solves:** `solveSteady`, `_steadyFromHere`, the continuations (floating, generation,
-  a terminal's level), `_steadySteps`.
+- **Steady solves** are `src/steady.js` (`solveSteady`, `_steadyFromHere`, the continuations:
+  floating, generation, a contact's voltage; `_steadySteps`, the pseudo-transient ramp, and
+  `_renormalizeSpectators`; `_directSteady`, `slowestTime`, `fastestTime`, `stuckReactions`),
+  methods of the Solver like the assembly's.
 
-The rest of `src/solver.js` is to be split along these lines, each piece with its contract.
+What stays in `src/solver.js` is the setup, the bookkeeping, the probes and snapshots, and the thin
+drivers that call the modules: about a thousand lines, with no contract of its own beyond this
+section.
 
 ## Reviewing one module
 

package/docs/numerics.md

@@ -171,13 +171,25 @@ potential and the quasi-Fermi difference are both shifted by the cell Péclet nu
 $`\mathrm{Pe} = v h/D`$, $`\Delta \to \Delta - \mathrm{Pe}`$, $`\Delta\eta \to \Delta\eta - \mathrm{Pe}`$.
 That's the exact constant-flux solution of $`N = v c - D(c' + c \psi')`$ across the cell, so pure
 convection–diffusion is exact on any grid, upwinding itself automatically at large $`\mathrm{Pe}`$.
+Past a drift of 300 thermal units across a cell (flow toward −x past a cell Péclet number of 300),
+the flux is taken from its downstream end, $`g B(-\Delta) c_R \operatorname{expm1}(-\Delta\eta)`$, the
+same flux, since there $`B(\Delta)`$ underflows and $`\operatorname{expm1}(\Delta\eta)`$ overflows.
 
 **Eddy mixing** is discretised on each segment as
-$`N_i = -(D_{\mathrm{mix}}/h) \sum_j \bar P_{ij} \Delta\eta_j`$, where $`\bar P`$ is built from the
-logarithmic mean of each concentration across the segment. The logarithmic mean makes a neutral
-species' mixing flux exactly $`-D_{\mathrm{mix}} \Delta c/h`$. The flux is exactly zero at
+$`N_i = -(D_{\mathrm{mix}}/h) \sum_j \bar P_{ij} \Delta\eta_j`$, where $`\bar P`$ is built from a
+segment mobility $`\bar K`$. Between ideal ends $`\bar K`$ is the logarithmic mean of each
+concentration, which makes a neutral species' mixing flux exactly $`-D_{\mathrm{mix}} \Delta c/h`$.
+Between crowded ends it's $`\bar K = \tfrac12(R_L K_L R_L + R_R K_R R_R)`$ with
+$`R = \mathrm{diag}(\sqrt{\bar c/c})`$ at each end: each end's $`K`$ rescaled to the logarithmic
+means and averaged. That's the dilute form where statistics are ideal, positive definite, and
+smooth in the state, and in a neutral solution it gives $`-D_{\mathrm{mix}} \Delta c/h`$ to second
+order in the cells. (A secant $`\bar K`$, exact in $`\Delta c`$, can be built from the ends' $`c`$ and
+$`\zeta`$ alone, but not smoothly: where a solution is uniform its correction depends on the
+direction of $`\Delta\zeta`$, a kink right where a salt carries current.) The flux is exactly zero at
 equilibrium, and exactly current-free ($`z^\mathsf{T}\bar P = 0`$ for any $`\bar P`$ built this way). Its
-full Jacobian, including the dependence of $`\bar P`$ on both ends, keeps Newton quadratic.
+full Jacobian, including the dependence of $`\bar P`$ on both ends, keeps Newton quadratic. Through
+$`K_L`$ and $`K_R`$ that needs $`\partial K/\partial\zeta`$, which the statistics models don't give, so
+it's taken by central differences of the model (a step of 1e-5, accurate to about 1e-10).
 
 With non-ideal statistics, $`\ln c = \zeta - \mathrm{ex}`$, where the excess
 $`\mathrm{ex} = \zeta - \ln(c/c_{\mathrm{ref}})`$ is zero for ideal statistics. The excess enters
@@ -508,8 +520,9 @@ which cost four assemblies per product.
   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,
+  moves no level by a thermal unit or more; otherwise refining stops for the rest of the solve
+  (on a device marked as below, for two iterations, three times at most).
+  A MOS capacitor's gate step now reaches the low-frequency charge in ~30 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
@@ -541,9 +554,32 @@ which cost four assemblies per product.
   conductances, loses about $`\log_{10}(g/G)`$ and fails near 15. It's not reported for solves that
   converge, since digits can be lost harmlessly too (a saturated species whose $`\eta`$ nothing
   depends on).
-- The last iteration usually only confirms convergence (updates go like 4e-3, 7e-6, 3e-11).
-  Stopping one iteration early on a convergence-rate estimate would save a third of the work,
-  but leave ~1e-11 in $`\eta`$ per step, which shows up as conservation drift, so it isn't done.
+- The last iteration usually only confirms convergence (updates go like 1e-2, 1e-9, 1e-15). A
+  time step stops one iteration early where the convergence rate says the next update would be
+  under the tolerance: with $`\theta`$ the last update over the one before (under 0.1, the update
+  under 1e-6), $`\theta/(1-\theta)`$ of the update (Hairer and Wanner's estimate of the error
+  left) under 1e-10. That saves a third of a typical step's work. Steady solves don't, since
+  their acceptance is checked against the residual anyway.
+- **A mode the plain solves never see, in time steps.** Neither a plain update nor the residual
+  shows a lost mode. Newton accepted a MOS capacitor's gate step at updates of 1e-10 while the
+  inversion layer's level sat 2.4e-4 thermal units off, the residual 7e-15 there and at the
+  solution alike, and the gate's charge ended 3.4e-5 off the steady one (a cold review of
+  `src/newton.js` found it: a tight re-solve from each accepted state was the instrument). So a
+  refinement that corrects a time step's nearly converged plain update (under 1e-4) by more than
+  its own size and 1e-6, by a correction the next update keeps, marks the device: from then on
+  its time steps are refined throughout, converge only on a refined update, and don't stop
+  early on the rate. The gate step then ends 4e-10 off, in fewer factorisations (121 against
+  222; 2 steps rejected, not 5). A correction the next update undoes is $`J \cdot v`$'s own
+  round-off in a row of huge entries (one ulp's worth, $`2^{-13}`$ or $`2^{-19}`$ exactly, on
+  healthy devices), and marks nothing. A lost mode can also never stall Newton at all: a floating
+  gate at rest in inversion converged quadratically at every step while the extrapolated guess's
+  error in the layer's level grew, 8.5e-5 V by 1e5 s, and by 1e7 s took 63,000 steps. So a time
+  step's 1st, 2nd, 4th, 8th… and every 32nd convergence on a device not yet marked is probed
+  with one refined update at the accepted state; one over 1e-8 thermal units (about a dozen over
+  the suite, which the next update undid on healthy devices) sends Newton on, refining, and the
+  next update decides as above. The gate then stays within 1e-14 V, in 7 steps to 1e7 s. The
+  probes and the refining cost the suite 2.5% more assemblies and 1.3% more factorisations;
+  strictly neutral transients, marked, came out up to 1.7e-5 off and now 1.9e-6.
 - Tried and rejected for large jumps (the retry at 3 thermal units per iteration takes 30–50
   iterations for a 1.4 V jump on a pn diode): per-component logarithmic damping, as in
   SPICE junction limiting, and an adaptive limit that grows while updates shrink. Both
@@ -776,7 +812,11 @@ the terms that cancel:
   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.
+  storage term), and one last step at the base huge $`dt`$, where pinning is tight. The amounts
+  that only those steps keep are checked after each, and a step that moved one fails: where the
+  slowest species is very slow (D ~ 1e-22 m²/s), the storage term falls below round-off against a
+  fast species' conduction, and a closed Y + Z, Y still in part of its stretch, had converged 1e8
+  times too large. The slowest diffusion time counts only materials some region is made of.
 - **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
@@ -916,7 +956,11 @@ A solve that fails falls back stage by stage:
    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.
+   steps from 1e8 to 1e9 s kept failing on the way to the end. The ramp reaches about 1e12 times
+   the slowest diffusion time, so a reaction slower than that, which alone settles a closed
+   combination (no row of the steady system holds a reaction at equilibrium node by node), isn't
+   waited out: the solve fails, or converges where it began, and its warnings name the reaction
+   either way. A transient gets there (Y = Z at $`k_f`$ = 1e-12 s⁻¹ in 1610 steps).
 
 Each of these carries cases that nothing else does (switched off one at a time, each fails
 tests or stress cases the others pass).

package/docs/reliability.md

@@ -76,9 +76,9 @@ recipes.
 | Second law | free energy in through the terminals (Σ N μ̄ over every species) equals the dissipation, every term ≥ 0: a pn diode, an open-circuit junction running on chemical input alone, electrodes with a bipolar plate, a port and a contact behind conductances | 1e-10 |
 | Transients | RC charging of a gated island; water relaxation rate | 1%; 2e-3 |
 | Time integration | BE first order, BDF2 second order; adaptive error control | ratios 2, 4 |
-| Advection and eddy mixing | exact convection–diffusion profile; `D + D_mix`; junction EMF unchanged by mixing | 1e-12; 1e-12; 1e-5 |
+| Advection and eddy mixing | exact convection–diffusion profile; `D + D_mix`; junction EMF unchanged by mixing, ideal and crowded; crowded mixing −D_mix Δc (a neutral species on a lattice, second order; ions, lattice and Debye–Hückel, on 20 cells) | 1e-12; 1e-12; 1e-5; ratios 4, 1e-4 |
 | Metal regions | ohmic; Schottky face and MOS gate equal their contact forms; Ag \| AgNO₃ \| Ag with metal electrodes; bipolar electrode at V/2 | 1e-12; 1e-9; 1e-9; 1e-9 |
-| Internal ports | transmission line σV tanh(L/λ)/λ (O(h²)); held level; MOS low-frequency C–V with a grounded channel, and without one the same equilibrium, and a gate step filling the inversion layer to it | 1e-4; 1e-9; 2e-3; 1e-6; 1e-3 |
+| Internal ports | transmission line σV tanh(L/λ)/λ (O(h²)); a window's exchange and electrode exactly `to − from` on any grid; held level; MOS low-frequency C–V with a grounded channel, and without one the same equilibrium, and a gate step filling the inversion layer to it | 1e-4; 1e-9; 1e-9; 2e-3; 1e-6; 1e-3 |
 | Cross-sections (spherical, cylindrical, any A(x)) | steady diffusion to a sphere and a cylinder (exact on any grid); Cottrell with the spherical term; uptake by a sphere filling from its surface; Debye–Hückel around a charged sphere, potential and charge | 1e-10; 3e-4; 2e-4; 1e-3, 3e-4 |
 | A capacitance through a port | a thin-film transistor against the charge-sheet model (below threshold to saturation, second order); de Levie impedance; gate impedance against dQ/dV | 5e-4; 1e-3; 1e-6 |
 | Electrode surfaces (coverage) | Langmuir isotherm against potential; the charge to fill a surface; the active–passive curve, blocking exactly (1 − θ) | 1e-9; 1e-3; 1e-9 |
@@ -174,7 +174,11 @@ disagree (a port's voltage at 0 for −1.42 V, θ 0.05 for 0.015, a contact 24 m
 the fixes, device by device, so its results above stand. On 1.2.2 the whole sweep, 870 devices,
 gives the same: 605 agree, 117 transients fail, and 13 differ, each a capacitive contact beside a
 membrane capacitor where the transient loses K⁺. Since a face out of equilibrium in `c0` starts
-in it (1.2.3), 607 agree and 115 fail, the same 13 differing.
+in it (1.2.3), 607 agree and 115 fail, the same 13 differing. Those 13 were a missing derivative:
+a contact's current, read from its end box, didn't take the membrane port's voltage that reaches
+it (a cold review of `src/boundaries.js`), so Newton stopped short in a way the tolerance set. With
+it in (1.2.7), the transient settles on the steady state to 1e-14 V, in a third of the steps, and
+648 agree, 87 transients fail, none differ.
 
 ## Consistent: the derivatives
 

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.2.4/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.4/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.4/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/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.2.4/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.4/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.2.4/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.3.0/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

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

package/src/assemble.js

@@ -0,0 +1,206 @@
+// The equations at one time, assembled: every row's residual and its Jacobian, for Newton's
+// iteration (src/newton.js), the time steps' bookkeeping and the small signal.
+//
+// CONTRACT
+//
+// These are methods of the Solver (src/solver.js installs them on its prototype), as are the
+// kernels they call: the regions' in src/regions.js and the faces' and terminals' in
+// src/boundaries.js, each with its own contract under this one. The layout they write into
+// (blocks, slots, row o = block·M + slot, its compact index R = rix[o], loc[o] < 0 for an
+// inactive slot, u + uLo, terminals 0, 1, 2 + k) is in docs/internals.md.
+//
+// The discretisation. Every region boundary is a doubled grid node (one per side) with a
+// zero-volume flux block between them (the face's), so the Jacobian stays block-tridiagonal. A
+// node's slots: φ̂ = Fφ/RT (in a metal, its carrier's flux J along the segment to its right),
+// η_i = μ̄_i/RT, and at a port's nodes its coverages and gates. A face's: its displacement D, each
+// linked species' flux N_i (toward +x, per area), each of its reactions' rate, each gate's
+// fraction. Geometry is in the grid (src/grid.js): a node's box vol[g] = ∫A dx, the area A at a
+// node, a segment's h = length/segArea. The rows are totals over a box (mol/s and C/s, or C):
+//   Gauss (φ̂ row):   Σ D out of the box − vol·ρ = 0, ρ = F Σ z_i c_i + ρ_fixed (+ a port's
+//                     capacitive charge, a face's sheet charge)
+//   balance (η_i):    vol·(c_i − c_i,old)/dt + Σ N_i out − Σ N_i in + vol·Σ ν r (consumed: a
+//                     reactant's ν > 0) − (made) − (a port's or contact's supply) = 0
+//   a face's slot:    unknown − its law (D, N_i, a rate), or the law itself (a pinned jump, μ̄
+//                     continuous), or a gate's (x − x_old)/dt − α(1 − x) + βx
+// A flux along a segment is computed once and added with opposite signs to its two nodes, so
+// sums of balance rows over boxes telescope exactly. At dt = Infinity there is no storage term
+// (a steady system), and a gate's or surface's storage drops out the same way.
+//
+// assemble(dt), in order:
+//   1. sys cleared and res zeroed; dtNow = dt; in a steady solve at dt = ∞, snapFlat (src/lawRows.js).
+//   2. computeConcentrations (c, K, ex, coverages, from u + uLo).
+//   3. Each region by its kind: a conductor's nodes and segments; else its nodes (dilute or
+//      concentrated), its bulk reactions, then per segment the displacement, eddy mixing, a
+//      concentrated region's fluxes; a dilute region's fluxes last.
+//   4. Each face (_face).
+//   5. The terminals (_terminals): the ports, the contacts, the floating ones' circuit rows.
+//   6. applyLaws(dt) (src/lawRows.js): rows the laws take in place of the rows above.
+//   7. On a time step with strictly neutral nodes (combining), _chargeRows: those nodes' rows
+//      and unknowns transformed (transformed = true; Newton maps the update back).
+//
+// What it writes:
+//   res (compact): each active row's residual as above; sys: its Jacobian, ∂res/∂(unknowns),
+//     by _j into the three blocks; inactive rows and columns go nowhere (rix = N, the sink).
+//   termB[k]: ∂res/∂V_k (per volt) for terminal k; termC[k]: ∂I_k/∂(unknowns); termI[k]: the
+//     current into the device through terminal k (A, planar: A/m²); termDI[k], termDX[k][j]:
+//     ∂ of k's circuit residual by V_k and V_j; termRes[k]: a floating k's circuit residual. Kept
+//     exactly only for _liveTerms() (the floating terminals, or all where allTerminals).
+//   The terminals' readouts (src/boundaries.js): contactFlux, contactD, portFlux, portQ, qg,
+//     qgSlope, portRates, contactQ; and s.pins (applyLaws).
+// Where this.lin is set (only by _assembleDifference), the dilute kernels' Jacobian terms go into
+// it, in difference form (src/difference.js), and the rest into sys, which is then not Newton's.
+//
+// Invariants (each says what a reviewer should be able to check here):
+//   1. Every Jacobian entry is the derivative of the residual as assembled: in (φ̂, η, the face
+//      and port slots), by V_k in termB, and in the transformed unknowns after 7.
+//      (test/jacobian.test.js checks it against central differences, on the devices it lists.)
+//   2. res, sys and the live terminals' terms depend only on the state (u, uLo, termV), dt, the
+//      sources' time and what a step or solve set (cOld, the gates' and coverages' old values,
+//      the charges at the step's start, steady, combining, the laws' references), never on an
+//      earlier assembly's leftovers: assemble(dt) twice at one state gives the same, bit for bit.
+//      (A held terminal's termB and termC aren't cleared, so they aren't kept.)
+//   3. A kernel adds into res and sys (+=) and sets a row only where the row is its own (a face's
+//      slots, a metal's flux slot, a port's gates) or it replaces the row whole (a contact's or
+//      a port's held level, a contact's φ law; the laws in 6), and no kernel adds to a replaced
+//      row after it is replaced. A row read as a flux before it is replaced (a contact's, a held
+//      level's) has every other kernel's terms in it by then.
+//   4. _assembleDifference(dt): res and the terminal terms as assemble(dt) gives them; its
+//      matrix plus its difference terms is assemble(dt)'s Jacobian (J·v equal to round-off);
+//      this.sys and this.lin as they were.
+//   5. _assembleBookkeeping(dt): contactFlux, contactD, portFlux, portQ and termI bit for bit
+//      as assemble(dt) would set them at the same state (one a steady assembly has already
+//      snapped flat: it doesn't snap), with sys, res, termB, termC and termDI elsewhere left
+//      partial, not to be read; it doesn't recompute concentrations (they must be current).
+// Tests: every test (every solve assembles); test/jacobian.test.js (invariant 1), test/layout.test.js
+// (difference form, the bookkeeping's readouts).
+
+import { BlockTridiagonal } from './blockTridiagonal.js';
+import { DifferenceTerms } from './difference.js';
+import { applyLaws, snapFlat } from './lawRows.js';
+
+export class Assembly {
+  // Add ∂(row rb, slot rs)/∂(block cb, slot cs) to the Jacobian (nothing if either slot isn't
+  // an unknown).
+  _j(rb, rs, cb, cs, v) {
+    const M = this.M, r = this.loc[rb * M + rs], c = this.loc[cb * M + cs];
+    if (r < 0 || c < 0) return;
+    const sys = this.sys, sz = sys.sizes;
+    if (cb === rb) sys.B[sys.offB[rb] + r * sz[rb] + c] += v;
+    else if (cb === rb - 1) sys.A[sys.offA[rb] + r * sz[cb] + c] += v;
+    else if (cb === rb + 1) sys.C[sys.offC[rb] + r * sz[cb] + c] += v;
+    else throw new Error(`internal: non-tridiagonal coupling ${rb}→${cb}`);
+  }
+
+  /** Assemble residual and Jacobian for a backward-Euler step of size dt. */
+  assemble(dt) {
+    const { model, res, sys } = this;
+    const { grid, materials, regions } = model;
+    sys.clear();
+    res.fill(0);
+    this.dtNow = dt;
+    if (this.lin) this.lin.reset(1 / dt);
+    if (this.steady && dt === Infinity) snapFlat(this);
+    this.computeConcentrations();
+
+    // Regions, each assembled by the kernel for its kind: a conductor (its carrier only), a
+    // dilute region (ideal statistics, the fast path) or a concentrated one (any statistics).
+    for (let r = 0; r < regions.length; r++) {
+      const reg = regions[r], mat = materials[reg.material];
+      const g0 = grid.regionStart[r], g1 = grid.regionEnd[r];
+      if (mat.conductor) {
+        for (let g = g0; g <= g1; g++) this._nodeConductor(g, dt);
+        for (let s = g0; s < g1; s++) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s] / grid.segArea[s]);
+        continue;
+      }
+      if (mat.ideal) this._nodesDilute(g0, g1, dt);
+      else for (let g = g0; g <= g1; g++) this._nodeConcentrated(g, dt);
+      const rxs = this.rxsIn[reg.material];
+      if (rxs.length > 0) for (let g = g0; g <= g1; g++) this._bulkReactions(g, rxs);
+      for (let s = g0; s < g1; s++) {
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s]; // (a length over the cross-section: fluxes are totals)
+        this._segmentDisplacement(s, bL, bR, mat, h);
+        if (reg.mixing > 0) this._segmentMixing(s, bL, bR, reg.mixing, h, mat);
+        if (!mat.ideal) this._segmentConcentrated(s, bL, bR, mat, h, reg.velocity);
+      }
+      if (mat.ideal) this._segmentsDilute(g0, g1, r, mat, reg.velocity);
+    }
+
+    // Faces: the flux node carries D, the linked species' fluxes and the reaction rates.
+    for (let f = 0; f < this.nFaces; f++) this._face(f);
+
+    // Terminals: ports (after every other term at their nodes, so a held level can read its
+    // flux), then contacts, then the circuit rows of the floating ones.
+    this._terminals(dt);
+    // The laws' rows (src/lawRows.js): a time step's circuit laws; a steady system's levels held
+    // flat, affinities, conserved amounts, islands' balances, and the pins held aside of them.
+    applyLaws(this, dt);
+    this.transformed = this.combining && dt !== Infinity;
+    if (this.transformed) this._chargeRows(dt);
+  }
+
+  // Zero one row of the Jacobian (all three blocks), ready to be replaced.
+  _replaceRow(b, rs) {
+    const l = this.loc[b * this.M + rs];
+    if (l < 0) return;
+    if (this.lin) this.lin.kill(this.rix[b * this.M + rs]);
+    const { sys, nB } = this, sz = sys.sizes, m = sz[b];
+    sys.B.fill(0, sys.offB[b] + l * m, sys.offB[b] + (l + 1) * m);
+    if (b > 0) sys.A.fill(0, sys.offA[b] + l * sz[b - 1], sys.offA[b] + (l + 1) * sz[b - 1]);
+    if (b < nB - 1) sys.C.fill(0, sys.offC[b] + l * sz[b + 1], sys.offC[b] + (l + 1) * sz[b + 1]);
+  }
+
+  // The Jacobian at dt with the dilute kernels' terms kept aside in difference form (see
+  // DifferenceTerms), the rest assembled into a matrix of its own. The residual and terminal terms
+  // come out as from assemble(dt); the Newton matrix is left as it was.
+  _assembleDifference(dt) {
+    const keep = this.sys;
+    const rest = this.sysRest ?? (this.sysRest = new BlockTridiagonal(keep.n, keep.sizes));
+    const n = this.n, nN = this.nNodes;
+    const lin = this.diffTerms ?? (this.diffTerms = new DifferenceTerms(keep.size, nN * n * n, nN * n, 2 * nN * n * n));
+    this.sys = rest;
+    this.lin = lin;
+    try {
+      this.assemble(dt);
+    } finally {
+      this.sys = keep;
+      this.lin = null;
+    }
+    return { rest, lin };
+  }
+
+  // The contact and port readouts (fluxes, displacements, the last segment's current) at the
+  // current state, from only the boxes they're read from. Each of those boxes gets the same terms
+  // in the same order as in assemble(), so the readouts are identical; other residuals and the
+  // Jacobian are left partial (the next assemble() starts afresh). Concentrations must be current.
+  _assembleBookkeeping(dt) {
+    const { model } = this;
+    this.dtNow = dt;
+    const { grid, materials, regions } = model;
+    this.res.fill(0);
+    for (let r = 0; r < regions.length; r++) {
+      const { nodes, segs } = this.bookkeeping[r];
+      if (nodes.length === 0 && segs.length === 0) continue;
+      const reg = regions[r], mat = materials[reg.material];
+      if (mat.conductor) {
+        for (const g of nodes) this._nodeConductor(g, dt);
+        for (const s of segs) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s] / grid.segArea[s]);
+        continue;
+      }
+      for (const g of nodes) {
+        if (mat.ideal) this._nodesDilute(g, g, dt);
+        else this._nodeConcentrated(g, dt);
+      }
+      const rxs = this.rxsIn[reg.material];
+      if (rxs.length > 0) for (const g of nodes) this._bulkReactions(g, rxs);
+      for (const s of segs) {
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s]; // (a length over the cross-section: fluxes are totals)
+        this._segmentDisplacement(s, bL, bR, mat, h);
+        if (reg.mixing > 0) this._segmentMixing(s, bL, bR, reg.mixing, h, mat);
+        if (!mat.ideal) this._segmentConcentrated(s, bL, bR, mat, h, reg.velocity);
+      }
+      if (mat.ideal) for (const s of segs) this._segmentsDilute(s, s + 1, r, mat, reg.velocity);
+    }
+    for (const f of this.bookkeepingFaces) this._face(f);
+    this._terminals(dt);
+  }
+}

package/src/bernoulli.js

@@ -27,3 +27,35 @@ export function bernoulliDerivative(x) {
   // B' = (B/x)(1 − B(−x)) = (B/x)(1 − B − x)
   return (b / x) * (1 - b - x);
 }
+
+// Past a drift of SG_FAR thermal units across a segment, a Scharfetter–Gummel flux's B(d) heads
+// for underflow and its expm1(Δη) for overflow (both by d ≈ 710, where their product is 0·∞):
+// the product is then taken whole.
+export const SG_FAR = 300;
+
+/**
+ * A Scharfetter–Gummel flux N = −g·B(d)·c_L·expm1(Δη) and its derivatives, into `out`: [N, ∂N/∂d,
+ * g·B(d)·c_L (= ∂N/∂η_L), g·B(d)·c_L·e^{Δη} (= −∂N/∂η_R), −g·expm1(Δη)·(B(d) + B′(d)) (the
+ * non-ideal kernel's ∂N/∂ζ_L per unit K_L)]. d is the drift, Δη the difference of levels, so
+ * that c_R = c_L e^{Δη−d}. From d = SG_FAR on, the same flux from the downstream end, N =
+ * g·B(−d)·c_R·expm1(−Δη), whose factors stay finite; ∂N/∂d = N·B′(d)/B(d).
+ */
+export function sgFlux(g, d, deta, cL, cR, out) {
+  if (d < SG_FAR) {
+    const E = Math.expm1(deta), B = bernoulli(d), Bp = bernoulliDerivative(d), gBc = g * B * cL;
+    out[0] = -gBc * E;
+    out[1] = -g * Bp * cL * E;
+    out[2] = gBc;
+    out[3] = gBc * (E + 1);
+    out[4] = -g * E * (B + Bp);
+    return out;
+  }
+  const B = bernoulli(d), up = g * bernoulli(-d) * cR, L = (1 - B - d) / d; // L = B′/B
+  out[0] = up * Math.expm1(-deta);
+  out[1] = out[0] * L;
+  out[2] = g * B * cL;
+  out[3] = up;
+  // (B·expm1(Δη), taken whole: d e^{Δη−d}(1 − e^{−Δη})/(1 − e^{−d}))
+  out[4] = -g * ((d * Math.exp(deta - d) * -Math.expm1(-deta)) / -Math.expm1(-d)) * (1 + L);
+  return out;
+}