driftlet 1.2.1 → 1.2.2

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.2/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/internals.md

@@ -0,0 +1,86 @@
+# 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.

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

package/package.json

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