driftlet 1.2.1 → 1.2.3

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.1/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@1.2.3/src/index.js` (and `src/kit.js`, `src/plot.js`).
 TypeScript declarations ship in the package. Writing a demo with an LLM agent? Point it at
 [`llms.txt`](llms.txt).
 
@@ -300,7 +300,7 @@ npm run shots    # retake the demos' screenshots, each caught at a set state (to
 
 Design notes and plans: [reliability](docs/reliability.md), [numerics](docs/numerics.md), [conventions](docs/conventions.md),
 [statistics](docs/statistics.md), [the kit](docs/kit.md), [reading level diagrams](docs/visualization.md),
-[data](docs/data.md), [roadmap](ROADMAP.md).
+[data](docs/data.md), [internals](docs/internals.md) (the source, module by module), [roadmap](ROADMAP.md).
 
 ## Credits
 

package/docs/device.md

@@ -110,6 +110,11 @@ regions: [
   reactions) does: its `c0` fixes the amount it conserves. Concentrations are positive ($`\bar\mu`$ is
   logarithmic in them); to have none of a species in a region, leave it out of that region's
   material. In a strictly neutral region, $`\sum z \cdot c_0`$ must be zero.
+  Where two strictly neutral regions meet at a face that holds ions in equilibrium and their
+  `c0` leaves it out of equilibrium (a different fixed charge or immobile ion on each side), the
+  two nodes at the face start in it, as the face reaches it at $`t = 0^+`$: the ions it passes
+  shared between them so their $`\bar\mu`$ is equal across it and each side neutral, each
+  one's amount over the two nodes kept, everything else as `c0` has it.
   An entry can instead be a profile, `{ x: [...], values: [...] }`, against the device's x (m, not
   the region's own), piecewise linear between its points and constant beyond its ends, so a
   transient can start from a state it didn't simulate reaching: a packet already injected, a

package/docs/internals.md

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

package/docs/numerics.md

@@ -730,18 +730,29 @@ the terms that cancel:
     port or contact at no current that passes K⁺ keeps $`n_K + Q/F`$ (a contact's Q its
     displacement $`D_\text{in}`$), and two floating electrodes sharing a closed Fe³⁺ keep the iron
     with both their charges, the law in one's circuit row moving with the other's voltage too.
+    A charge is kept only in a circuit row, once: the first combination through it takes one,
+    and the rest have its multiple taken off (a capacitor passing K⁺ under K⁺ + L⁻ = KL keeps
+    $`n_K - n_L + D/F`$ there, and $`n_L + n_{KL}`$ in a balance row).
     At any other current such a terminal only stores what comes in, which has no steady state,
     and the solve says so at once.
   - an **immobile** combination (trap states X⁰ and X⁻ under e⁻ + X⁰ = X⁻, with D = 0) keeps it
     node by node, since nothing carries it anywhere, as do an electrode's surface species
     (adsorbates that only turn into each other keep their total on every site), its row local,
     one per node in its own block, a coverage counted as the sites it fills per volume,
-    $`\Gamma a \theta`$, beside the concentrations. (The null space is taken with the immobile and
+    $`\Gamma a \theta`$, beside the concentrations. Each node's rows are chosen by elimination
+    over the slots there, as below. Immobile means D = 0 in one region with no terminal feeding
+    it: a species linked across a face is carried between the face's two nodes, and one a
+    port links is carried between the port's nodes, kept with the port's charge in its circuit
+    row. (The null space is taken with the immobile and
     surface columns first, so that these come out apart from the combinations that move.) A combination of immobile
     stretches with a moving one (the electrons the traps hold, $`e^- - X^0`$, in a closed film) is
     an amount like any other, its immobile parts summed over their nodes;
   - a **floating metal** keeps the charge on its faces, its sheets' displacement.
 
+  A combination that none of these rows can keep (through a stretch immobile in part only, a
+  face reaction joining two immobile stretches at a face, a charge with no circuit row left) is
+  set aside, and the steady solve then goes by time steps, which keep every amount themselves.
+
   A closed stretch keeps the amount it was given (its `c0`, or what it held when `set()`
   closed it); a combination behind a terminal at no current keeps what the state holds when the
   solve begins. The amount's row is dense, so it's bordered (see [terminals](#terminals)): the

package/docs/reliability.md

@@ -146,14 +146,17 @@ $`J \cdot v`$.
 A steady solve replaces one redundant equation per conserved combination with the combination's
 amount (see [numerics](numerics.md#the-steady-system)). A combination left out, or weighed wrongly,
 gives a state that converges and is steady but holds the wrong amounts, which only a transient
-from the same start shows. `npm run lawsweep` builds 810 small devices from the features at the
+from the same start shows. `npm run lawsweep` builds 870 small devices in two families. The first, 810, combine the features at the
 edges of that bookkeeping: a floating, resistive or held electrode, with or without a
 capacitance, with adsorbates or an immobile species that adsorbs; a second floating electrode
 or a membrane capacitor; a capacitive or ion-passing contact at no current; a face that blocks
 an ion or makes an immobile species. Each is solved directly and run as a transient for 1e6 s,
 and where the transient converged, finished and moves no further over 100× as long, the two
 must agree on every species' amount, every surface's sites and every floating terminal's
-voltage.
+voltage. The second, 60, put an immobile S⁺ beside what carries it (a face that passes it, a port
+at I = 0 that links it, an electrode it adsorbs on) with a capacitive contact passing K⁺ (at
+I = 0 or behind a resistance) and K⁺'s complex with a closed L⁻, each where a cold review of
+`src/laws.js` found a law kept wrongly.
 
 Every reaction starts at its equilibrium. On 1.2.1, 675 devices are built (135 combinations
 repeat others); 579 agree, and 83 transients fail to converge. In the other 13 the transient
@@ -161,8 +164,54 @@ is the one that's off: it loses a conserved K⁺ total in proportion to its tole
 at tol 1e-9) when a capacitive contact, a membrane capacitor and a held electrode share the
 device, where the steady solve keeps it to round-off. The sweep found its first law the day it
 was written (an immobile species adsorbing on an electrode over part of its region); Gemini 4
-Argon's review found nine more by hand (one through a device it suggested), each now in
-`test/laws.test.js`.
+Argon's review found nine more by hand (one through a device it suggested), and a cold review
+of `src/laws.js` against its contract alone five more (an immobile species linked across a face,
+or by a port; two node-by-node laws sharing a row; a capacitive contact's charge in a second law,
+and in a time step's reading of its current), none of them in the sweep's devices. Each is now in
+`test/laws.test.js`. On the code before those fixes the second family has 14 devices that
+disagree (a port's voltage at 0 for −1.42 V, θ 0.05 for 0.015, a contact 24 mV off); after, none,
+26 agree and 34 transients fail (see the roadmap). The first family's laws come out unchanged by
+the fixes, device by device, so its results above stand. On 1.2.2 the whole sweep, 870 devices,
+gives the same: 605 agree, 117 transients fail, and 13 differ, each a capacitive contact beside a
+membrane capacitor where the transient loses K⁺. Since a face out of equilibrium in `c0` starts
+in it (1.2.3), 607 agree and 115 fail, the same 13 differing.
+
+## Consistent: the derivatives
+
+A Jacobian entry that's wrong still converges to the right answer, its residual being right, so
+no test of answers sees it: it shows only as Newton taking longer, or failing on a harder device.
+`test/jacobian.test.js` compares the whole Newton system, column by column, with central
+differences of its own residual, on ten devices that between them write every law's row (flat
+stretches, affinities, amounts kept in balance rows and in circuit rows with an electrode's or a
+contact's charge, node-by-node laws with a surface, metals' charges), crowded statistics, face
+and port reactions and floating terminals. It checks inside a real `solve()` and a real
+`advance()`, at their second assembly, each in the unknowns Newton solves for there (a time step's
+charge rows included). It came from a cold review of `src/lawRows.js`, which found a node-by-node
+law's row keeping a port reaction's ∂/∂V (an extra Newton iteration, the answer the same); broken
+once each way (that entry back, a storage term 0.1% off in either time-step path), it fails.
+
+## Measured: how much the tests see
+
+A mutation run makes one small slip at a time in a module (an operator flipped, a comparison
+loosened, a statement dropped, a 0 for a 1), runs the tests on it, and counts the slips no test
+fails. On 18 Oct 2026, 120 of them, sampled from `src/laws.js` and `src/lawRows.js`'s 1420: 69
+failed a test, and 51 got through. Each of the 51 was then looked at:
+- In `src/laws.js` (29): 20 change no law on any of the law sweep's 735 devices, 2 only a
+  workspace's size, and 6 change laws on 12 to 635 of them while every answer stays right (the
+  islands', which Newton seldom needs; a λ read only by long steps). One changed the answers: it
+  held a capacitive contact's charge in the wrong law, and 85 of the sweep's devices came out
+  wrong, with all 470 tests passing. Its device is now in `test/laws.test.js`.
+- In `src/lawRows.js` (22): the Jacobian test had never seen islands' rows, a long step that
+  reads a law by its change, or a law with a surface or a capacitive electrode in a time step.
+  With them in (a charged pore, three of the sweep's devices), 6 more fail. Of the 16 left, 6
+  change nothing (a bound the loop never reaches), 1 only a heuristic's estimate, 2 the pivoting
+  of the small dense solve (robustness only), and 7 are narrow paths no device here takes: two
+  floating electrodes whose law counts the other's charge, an equilibrium face inside a flat
+  stretch, a contact's law read by its change.
+
+A slip that gives the right answer by another route isn't a gap; what the run found that was,
+was one wrong answer the sweep sees and the suite didn't, and a test that had never looked at
+two of the paths it claimed.
 
 ## Hard cases
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "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": {
@@ -34,6 +34,7 @@
     "smoke": "node tools/smoke.js",
     "shots": "node tools/shots.js",
     "lawsweep": "node tools/lawsweep.js",
+    "fingerprint": "node tools/fingerprint.js",
     "prepublishOnly": "npm test && npm run types",
     "types": "rm -rf types && npx -y -p typescript@5 tsc --allowJs --declaration --emitDeclarationOnly --target es2022 --module nodenext --moduleResolution nodenext --outDir types src/index.js src/kit.js src/plot.js"
   },