driftlet 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 Mark Lundeberg
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# driftlet
+
+[![test](https://github.com/markblundeberg/driftlet/actions/workflows/test.yml/badge.svg)](https://github.com/markblundeberg/driftlet/actions/workflows/test.yml)
+
+**driftlet solves 1D drift–diffusion–reaction problems properly**: any mix of charged and
+neutral species, Poisson electrostatics (or strict neutrality), bulk and interfacial reactions,
+heterointerfaces, metals, and external circuits, in steady state, in time, and as small-signal
+impedance. It's validated against analytic results, and small enough to run live in a web page:
+pure JavaScript, no dependencies, millisecond solves.
+
+**Status: pre-release.** Not yet on npm, and the API may still change.
+
+## Is it for your problem?
+
+The same equations go by different names in different fields. If your problem is one-dimensional
+(planar), it's probably here:
+
+| If you work on | you may call it | start from | checked against |
+|---|---|---|---|
+| Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions | [first example](#a-semiconductor-junction), [pn demo](https://markblundeberg.github.io/driftlet/demos/pn.html), [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
+| Solar cells | photogeneration, radiative and SRH recombination | [`reactions`](test/reactions.test.js) test: generation is a reaction from a photon reservoir (uniform per material), SRH runs through explicit trap species | `J_sc = qG(L_n + L_p + W)`; Shockley J–V in the dark |
+| Electrochemistry | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry | [second example](#an-electrochemical-cell), [saturation](https://markblundeberg.github.io/driftlet/demos/saturation.html) and [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg |
+| Batteries, intercalation | OCV, insertion hosts, chemical diffusion | [insertion demo](https://markblundeberg.github.io/driftlet/demos/insertion.html), [`statistics`](test/statistics.test.js) test | composition vs OCV, π²D/4L² relaxation |
+| Double layers, colloids | Poisson–Boltzmann, Gouy–Chapman–Stern, Debye screening, crowding (Bikerman) | [double-layer demo](https://markblundeberg.github.io/driftlet/demos/double-layer.html), [`equilibrium`](test/equilibrium.test.js) test | Gouy–Chapman charge and profile, Kilic–Bazant–Ajdari |
+| Membranes, desalination | Donnan, ion exchange, liquid junctions, water dissociation | [`equilibrium`](test/equilibrium.test.js), [`neutral`](test/neutral.test.js) tests | Donnan partition, Planck EMF |
+| Solid-state ionics | mixed ionic–electronic conduction, defect chemistry, mobile ions | [`statistics`](test/statistics.test.js), [`reactions`](test/reactions.test.js) tests | mass action from standard potentials |
+| Biophysics | Poisson–Nernst–Planck, ion channels, membrane potentials | the electrochemistry setups, with fixed charge in the channel region | no dedicated check yet |
+
+The tests are worked setups, each with its analytic check, so they double as recipes. The
+[validation table](#validation) lists them all.
+
+## Install
+
+```sh
+npm install driftlet
+```
+
+```js nocheck
+import { Device, units } from 'driftlet';       // the solver
+import { build, layer, ohmic } from 'driftlet/kit'; // helpers that write definitions, data, live demos
+import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG string
+```
+
+Or straight from a CDN in a page, pinned to a version:
+`https://cdn.jsdelivr.net/npm/driftlet@0.1.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).
+
+## A semiconductor junction
+
+A silicon pn junction with ohmic contacts, at equilibrium and then under forward bias. A device
+is plain data; `build()` from `driftlet/kit` writes it from the stack as it's drawn, with a
+[data library](docs/data.md) for the material:
+
+```js
+import { Device, units } from 'driftlet';
+import { build, layer, ohmic, semiconductor } from 'driftlet/kit';
+
+const dev = new Device(
+  build({
+    T: 300,
+    library: [semiconductor('Si')], // e⁻ and h⁺ with Sze's band data at 300 K
+    stack: [
+      ohmic(0), // e⁻ and h⁺ in equilibrium with a metal, the terminal at 0 V
+      layer('Si', units.um(2), { name: 'n', donors: units.perCm3(1e17) }),
+      layer('Si', units.um(2), { name: 'p', acceptors: units.perCm3(1e16) }),
+      ohmic(0),
+    ],
+    grid: { hmin: units.nm(0.5), hmax: units.nm(20) },
+  }),
+);
+
+const eq = dev.solve();
+console.log('built-in potential (V):', eq.phi[0] - eq.phi[eq.phi.length - 1]); // ≈ 0.795
+
+dev.set({ contacts: { right: { V: 0.4 } } }); // p side at +0.4 V: forward bias
+const on = dev.solve(); // warm-started from the previous solution
+console.log('current (A/m²):', on.current); // negative: it flows toward −x, from p to n
+```
+
+## An electrochemical cell
+
+Silver nitrate between two silver electrodes, as a macroscopic (strictly neutral) electrolyte.
+A reversible electrode is a contact whose terminal species is the ion it exchanges: Ag⁺ in
+equilibrium with the metal, NO₃⁻ blocked. Polarized, the cell's current saturates at the
+limiting current, `i_lim = 4FD₊c₀/L` for this binary salt:
+
+```js
+import { Device, FARADAY } from 'driftlet';
+import { build, layer, aqueous } from 'driftlet/kit';
+
+const L = 100e-6, c0 = 10; // m, mol/m³ (10 mM)
+// Ag⁺ + e⁻ ⇌ Ag at the metal: V is the voltage of Ag⁺ there, i.e. the electrode potential.
+const silver = (V) => ({ V, terminal: 'Ag+', species: { 'Ag+': 'equilibrium', 'NO3-': 'blocked' }, phi: 'bulk' });
+const dev = new Device(
+  build({
+    library: [aqueous(['Ag+', 'NO3-'], { epsr: 0 })], // epsr 0: no double layers resolved
+    // Ag⁺ reaches the contacts and takes their level; NO₃⁻ doesn't, so it needs its amount.
+    stack: [silver(0), layer('water', L, { c0: { 'NO3-': c0 } }), silver(0)],
+    grid: { hmin: 10e-9, hmax: 2e-6 }, // graded: fine where Ag⁺ depletes at the electrode
+  }),
+);
+const iLim = (4 * FARADAY * 1.648e-9 * c0) / L;
+for (const V of [0.05, 0.1, 0.2, 0.4]) {
+  dev.set({ contacts: { right: { V } } });
+  const sol = dev.solve();
+  // V > 0 raises Ag⁺'s level on the right: silver dissolves there and plates on the left, so the
+  // current flows toward −x.
+  console.log(`${V} V: I/i_lim = ${(-sol.current / iLim).toFixed(4)}`); // ≈ tanh(V/4V_T): 0.451, 0.750, 0.961, 0.999
+}
+```
+
+Solutions are plain objects of `Float64Array`s, ready to plot (fresh arrays from every solve):
+`x`, `phi`, and per species `c`, `mu` (electrochemical potential μ̄), `muStd` (standard level)
+and the voltage views `V`, `Vstd`. They also carry the terminals' voltages and currents, fluxes,
+conservation bookkeeping and warnings; see [the device reference](docs/device.md). The
+[kit](docs/kit.md) adds reactions written as equations (`'Ag+ + e- = Ag(s)'`), redox levels,
+level diagrams, slider demos and `describe()`, which flags likely unit slips.
+
+## Demos
+
+Live pages in [`demos/`](demos/), each building its device with `driftlet/kit`, solving it in the
+browser as you move the controls, and showing its whole script as a worked example. Most draw the
+closed-form theory alongside, as a check. They're live at
+[markblundeberg.github.io/driftlet/demos](https://markblundeberg.github.io/driftlet/demos/); to run
+them locally, serve the repository root (e.g. `python3 -m http.server`) and open `/demos/`.
+
+| | | |
+|---|---|---|
+| [![pn junction](demos/screenshots/pn.png)](https://markblundeberg.github.io/driftlet/demos/pn.html) | [![solar cell](demos/screenshots/solar.png)](https://markblundeberg.github.io/driftlet/demos/solar.html) | [![MOS capacitor](demos/screenshots/mos.png)](https://markblundeberg.github.io/driftlet/demos/mos.html) |
+| **pn junction**: quasi-Fermi levels under bias; I–V against Shockley | **Solar cell**: J<sub>sc</sub> and V<sub>oc</sub> against collection theory | **MOS capacitor**: band bending; C–V against ideal theory |
+| [![cyclic voltammetry](demos/screenshots/redox.png)](https://markblundeberg.github.io/driftlet/demos/redox.html) | [![Daniell cell](demos/screenshots/daniell.png)](https://markblundeberg.github.io/driftlet/demos/daniell.html) | [![saturation](demos/screenshots/saturation.png)](https://markblundeberg.github.io/driftlet/demos/saturation.html) |
+| **Cyclic voltammetry**: a Fermi level against a redox level | **Daniell cell**: a real salt bridge, leaking, ion by ion | **Saturation**: Ag \| AgNO₃ \| Ag under a square wave, up to its limiting current |
+| [![impedance](demos/screenshots/impedance.png)](https://markblundeberg.github.io/driftlet/demos/impedance.html) | | |
+| **Impedance**: the Warburg arc, and the cell's small-signal response inside | | |
+| [![ion-exchange membrane](demos/screenshots/membrane.png)](https://markblundeberg.github.io/driftlet/demos/membrane.html) | [![double layer](demos/screenshots/double-layer.png)](https://markblundeberg.github.io/driftlet/demos/double-layer.html) | [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) |
+| **Ion-exchange membrane**: Donnan steps, ion by ion, against TMS theory | **Double layer**: dilute vs crowded ions, against closed forms | **Intercalation host**: cycling between cutoffs against the OCV |
+
+## How to think about it
+
+driftlet insists on thermodynamically honest concepts ([conventions](docs/conventions.md)):
+
+- **Everything you set or measure is an electrochemical potential μ̄** (or a difference of
+  them). A bias sets Δμ̄ of electrons between terminals; a gate sets its metal's `μ̄_e⁻`. Nothing
+  you set is an electrostatic potential.
+- **φ is bookkeeping.** Each material's standard chemical potentials anchor its own φ, and φ
+  jumps at every interface between different materials.
+- **Band alignment is a property of each interface** and must be given explicitly: nothing is
+  assumed by default. If vacuum-level estimates are all you have, helpers in `driftlet/kit`
+  take an anchor and an offset per side (electron affinity, work function, absolute SHE
+  potential, …) and return the alignment that lines up the vacuum levels. The
+  [alignment guide](docs/alignment.md) covers the recipe and its caveats.
+- The species voltage `V_i = μ̄_i / (z_i F)` and standard level `V°_i` are available as views,
+  alongside redox levels: [reading level diagrams](docs/visualization.md) explains them.
+
+A device is a line of **regions** (each a **material** plus a length, fixed charge and
+initial composition), joined at **interfaces**, with a **contact** at each end. The contacts
+and any internal **ports** are its **terminals**, each held at a voltage or driven by a
+current. Supported physics:
+
+- any mix of charged and neutral species; per-material diffusivities and standard potentials;
+  species absent from some materials;
+- ideal statistics by default, or per material: Fermi–Dirac (degenerate carriers), lattice
+  gas (crowding, site filling), Redlich–Kister, Debye–Hückel, intercalation hosts described by
+  their OCV curve, or your own function ([statistics](docs/statistics.md));
+- Poisson electrostatics, or strictly neutral (ε = 0) materials such as macroscopic
+  electrolytes;
+- conductor regions (metals, fast ion conductors) with only their carrier's level and a
+  conductivity: Schottky and MOS gates as regions, electrodes with reactions at their faces,
+  bipolar electrodes;
+- contacts as outside phases with known levels, joined by the same laws as internal faces:
+  ohmic contacts, reversible electrodes, baths, pinned barriers, conductance links, gates and
+  Stern layers;
+- interfaces with explicit alignment, blocking, interface resistance, and Butler–Volmer
+  reactions with participants on either side (electrode reactions, ion and electron transfer,
+  mixed potentials), and a choice of electrostatic law (pinned, neutral, Helmholtz);
+- bulk reactions with thermodynamically consistent mass action (recombination, water
+  autoionisation, …);
+- imposed flow (advection) and current-free eddy mixing;
+- internal ports: reservoirs feeding a window of nodes, e.g. grounding a MOS channel;
+- terminals held at a voltage, driven by a current (including open circuit) or behind a
+  resistance, with piecewise-linear waveforms (cyclic voltammetry); reference electrodes and
+  other internal terminals as ports; impedance at any terminal;
+- steady states; transients by backward Euler, BDF2, or adaptive BDF2 with error control and
+  frame budgets for animation; exact conservation bookkeeping;
+- small-signal impedance spectra Z(f), with complex profiles.
+
+## What it doesn't do
+
+- **More than one dimension.** Planar 1D only, so no porous-electrode (P2D) models. For 2D/3D,
+  see [ChargeTransport.jl](https://github.com/WIAS-PDELib/ChargeTransport.jl), TCAD tools or
+  COMSOL.
+- **Cross-diffusion.** Each species moves down its own μ̄ with its own D (the statistics can be
+  non-ideal); there are no Stefan–Maxwell or Onsager cross terms beyond eddy mixing.
+- **Heat and optics.** Temperature is uniform. Generation is a reaction, uniform within a
+  material; there's no optical model or absorption profile. For those, see
+  [Driftfusion](https://github.com/barnesgroupICL/Driftfusion),
+  [SIMsalabim](https://github.com/kostergroup/SIMsalabim) or
+  [PyBaMM](https://github.com/pybamm-team/PyBaMM).
+- **Field-dependent transport.** No high-field mobility, impact ionisation, field-enhanced
+  dissociation (second Wien effect) or tunnelling.
+- **Fitting.** It solves forward problems; parameter estimation is up to you.
+
+How it works numerically is in [numerics](docs/numerics.md).
+
+## Validation
+
+Every physics feature is tested against analytic results (`npm test`, node's built-in runner).
+
+| What | Checked against | Tolerance |
+|---|---|---|
+| Equilibrium of any device | μ̄ of every species flat; zero current | 1e-9 RT or better |
+| Gouy–Chapman double layer | analytic charge and full nonlinear profile | 2e-3 |
+| Debye screening (linear limit) | gate in series with `ε/λ_D` | 1e-3 |
+| Donnan potential | analytic partition, between floating layers and real baths | 1e-8 |
+| Heterointerfaces with unequal dipoles (A \| B \| A) | per-face analytic double-layer split | 3e-3 |
+| Floating island | Gauss's law; conserved amounts through gate sweeps | 1e-12 |
+| pn junction | exact built-in potential; depletion charge; short-diode J–V | 1e-12; 1%; 2e-3 |
+| Long pn diode with recombination | Shockley J–V incl. depletion recombination | 2e-3 |
+| Illuminated long pn diode | `J_sc = qG(L_n + L_p + W)` from a cold start; superposition at low injection | 5e-3; 1e-2 |
+| Schottky barrier (metal region \| n-Si) | surface density from the alignment; depletion charge | 5e-3; 2% |
+| Liquid junction, open circuit | cell EMF 2t₊(RT/F) ln(c₁/c₂); Planck diffusion potential | 1e-4 |
+| Concentration polarization | `i = i_lim tanh(V/4V_T)`, incl. galvanostatic and load modes | 2e-4 |
+| Butler–Volmer electrode | Nernst equilibrium; mixed kinetic/diffusion closed form | 5e-4 |
+| Redox couple between inert electrodes | Nernst level of Fe³⁺/Fe²⁺; the couple's total conserved at equilibrium and under current | 1e-9; 1e-10 |
+| Interface conductance and ion transfer | series 1/G; BV rate law at the interface state | 1e-4; 1e-8 |
+| Mass action | `c(H⁺)c(OH⁻) = K_w` from standard potentials; moiety conservation | 1e-9 |
+| 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 |
+| 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 | 1e-4; 1e-9; 2e-3 |
+| Impedance | Macdonald blocking-electrode spectrum, 100 Hz–1 GHz; finite-length Warburg (Ag \| AgNO₃ \| Ag); DC limit = differential resistance | 3e-4; 3e-5; 1e-6 |
+| 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 |
+| 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 |
+| Debye–Hückel | junction EMF 2t₊(RT/F) ln(a₁/a₂) with activities | 1e-6 |
+| Data library | ion μ° against the electrochemical series and `K_w`; D against limiting conductivities; band data against `n_i` | 10 mV; 0.5%; 15% |
+| Intercalation host (OCV) | composition vs table and isotherm; chemical diffusion flux and relaxation rate | 1e-12; 1e-5; 1e-4 |
+
+## Performance
+
+`npm run bench` runs typical interactive workloads and compares them with a committed
+baseline. Matrix factorisations (≈ Newton iterations) and block work are deterministic and
+checked in CI; times are from a desktop Ryzen 7600X in Node 22:
+
+| Task | Time | Factorisations |
+|---|---|---|
+| Linear solve, 300 nodes × 7 unknowns (factor + solve) | 0.4 ms | 1 |
+| pn diode (264 nodes): cold equilibrium | 2 ms | 9 |
+| pn diode: I–V sweep 0 → 0.6 V, 31 points | 31 ms | 137 |
+| pn diode: warm jump from +0.4 V to −1 V | 7 ms | 51 |
+| pn diode: adaptive transient, 0 → 0.5 V, 100 ns | 150 ms | 1026 |
+| pn diode: impedance at 20 frequencies | 8 ms | 21 |
+| MOS with a metal gate: C–V sweep, 26 points | 11 ms | 126 |
+| n-Si \| KCl (4 species, 3 unknowns per node): Mott–Schottky sweep, 31 points | 29 ms | 156 |
+| n-Si \| KCl: impedance at 20 frequencies | 10 ms | 21 |
+| Ag \| AgNO₃ \| Ag with double layers: sweep 0 → 0.1 V, 21 points | 12 ms | 81 |
+| Ag \| AgNO₃ \| Ag, neutral: adaptive transient over 1 s | 29 ms | 287 |
+| Silver electrodes with a bipolar plate: sweep 0 → 1 V, 11 points | 27 ms | 63 |
+
+The library has no dependencies and does no DOM access, so it runs in a Web Worker. (A device
+definition is plain data and can be posted to a worker. Devices using custom-function
+statistics can't be, and must be built inside the worker.)
+
+## Development
+
+No dependencies. Tests use node's built-in runner (Node ≥ 20):
+
+```sh
+npm test         # the validation suite
+npm run bench    # typical workloads against bench/baseline.json (--save to update it)
+npm run types    # TypeScript declarations from the JSDoc, into types/ (fetches TypeScript via npx)
+```
+
+Design notes and plans: [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).
+
+## Licence
+
+[0BSD](LICENSE): do anything you like with it.

package/llms.txt

@@ -0,0 +1,299 @@
+# driftlet: a guide for agents
+
+driftlet is a dependency-free JavaScript library that solves 1D drift–diffusion–reaction
+(Poisson–Nernst–Planck) problems fast enough for live web demos: semiconductor junctions,
+electrochemical cells, double layers, membranes, mixed conductors. It runs in a browser, a Web
+Worker or Node, from npm or a CDN.
+
+This guide is for writing a demo or calculation with it. Every code block below runs in the
+test suite. The full references are docs/device.md (the definition), docs/kit.md (the helpers),
+docs/conventions.md (signs and levels) and docs/data.md (the data library).
+
+## Imports
+
+From a CDN, pin the version:
+
+```js nocheck
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/plot.js';
+```
+
+From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
+
+## What to know first
+
+- **Units are SI**: m, mol/m³ (1 M = 1000 mol/m³), J/mol, m²/s, V, A/m², F/m², C/m³. Use
+  `units` to convert: `units.um(1)`, `units.perCm3(1e17)` (carriers per cm³ to mol/m³),
+  `units.eV(1.12)` (to J/mol), `units.cm2PerS(36)`, `units.molar(0.1)`.
+- **Everything you set or read is an electrochemical potential μ̄** (or a voltage made from one).
+  A terminal's `V` is the voltage of its terminal species: for an electron contact,
+  V = −μ̄_e/F, what a voltmeter reads. φ is bookkeeping and never a control.
+- **Solutions** give, per species, `c` (concentration), `mu` (μ̄), `V` (the species voltage
+  μ̄/(zF), a quasi-Fermi level for e⁻ and h⁺) and `Vstd` (the standard level, a band edge for e⁻
+  and h⁺). In voltage units the conduction band sits below the valence band. `NaN` marks where a
+  species is absent.
+- **Current**: `sol.current` is positive toward +x through the device. `sol.terminals[name]` gives
+  each terminal's `{ V, current }`, current into the device.
+- **Nothing physical is defaulted.** Every interface between different materials needs an
+  alignment (`dipole` or `step`), or `phi: 'neutral'` for a macroscopic model. Every metal face
+  next to a dielectric needs its φ law. Every species that doesn't reach a contact needs its
+  initial amount (`c0`). An error names the path and says what to give.
+- **Check before trusting.** `sol.converged` must be true, and read `sol.warnings`.
+  `describe(def)` (kit) summarises a definition and flags likely unit slips.
+- **Exports.** `driftlet`: `Device`, `units`, and the constants `FARADAY`, `GAS_CONSTANT`,
+  `EPS0`, `BOLTZMANN`, `ELEMENTARY_CHARGE`, `AVOGADRO` (there's no thermal-voltage constant:
+  V_T = GAS_CONSTANT·T/FARADAY). `driftlet/kit`: `build`, `layer`, `ohmic`, `bath`, `half`,
+  `level`, `SHE`, `describe`, `live`, `traces`, the data library (`aqueous`, `semiconductor`,
+  `metal`, `IONS`, …) and the vacuum-level helpers. `driftlet/plot`: `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`).
+- **Reactions** are written as equations, `{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }`, in
+  `new Device`, `build()` and `set()` alike. A coefficient is a number and a space (`2 e-`).
+- **Rate constants carry units.** A bulk reaction's rate is `kf · Π c_reactants` in mol/(m³·s),
+  with c in mol/m³ (and 1e16 cm⁻³ is only 0.0166 mol/m³). Band-to-band recombination,
+  `e- + h+ = 0`, gives a minority lifetime τ = 1/(kf·N) with N the majority density in mol/m³:
+  `kf: 1e8` is τ ≈ 0.6 µs at 1e16 cm⁻³. Generation is a reaction from a reservoir, rate `kf` in
+  mol/(m³·s) (`units.perCm3` converts cm⁻³·s⁻¹ too). A face reaction's `k0` is in mol/(m²·s);
+  its exchange current density is F·k0 per electron at the reference concentrations.
+
+## Template: a semiconductor junction
+
+```js
+import { Device, units } from 'driftlet';
+import { build, layer, ohmic, semiconductor, describe } from 'driftlet/kit';
+
+const def = build({
+  T: 300, // the library's semiconductor data are for 300 K
+  library: [semiconductor('Si')],
+  stack: [
+    ohmic(0), // e⁻ and h⁺ in equilibrium with a metal at 0 V
+    layer('Si', units.um(1), { name: 'n', donors: units.perCm3(1e17) }),
+    layer('Si', units.um(1), { name: 'p', acceptors: units.perCm3(1e16) }),
+    ohmic(0.5), // the p side at +0.5 V: forward bias
+  ],
+  bulkReactions: [{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }], // recombination: τ = 1/(kf·N) ≈ 0.6 µs at N = 1e16 cm⁻³
+  grid: { hmin: units.nm(1), hmax: units.nm(20) },
+});
+console.log(describe(def));
+const dev = new Device(def);
+const sol = dev.solve();
+console.log(sol.converged, `I = ${sol.current.toFixed(1)} A/m²`); // negative: toward −x, p to n
+// An I–V sweep: change the drive, solve again (warm-started).
+for (const V of [0, 0.2, 0.4, 0.6]) {
+  dev.set({ contacts: { right: { V } } });
+  console.log(V, dev.solve().current);
+}
+```
+
+## Template: an electrochemical cell
+
+An electrode is a metal layer with the reaction at its face, behind a contact holding the
+metal's electrons (`ohmic(V, ['e-'])`). Reactions are written as equations. A participant that
+isn't a species (solid silver) is fixed by its μ.
+
+```js
+import { Device } from 'driftlet';
+import { build, layer, ohmic, half, level, SHE, aqueous, metal } from 'driftlet/kit';
+
+const silver = half('Ag+ + e- = Ag(s)', { 'Ag(s)': 0 }); // μ of the element: 0 on table conventions
+// A Stern layer at each metal face: its capacitance and the potential of zero charge are
+// properties of that interface, so they're yours to choose.
+const face = { phi: { type: 'capacitive', C: 0.2 }, zeroCharge: 0.1, reactions: [{ ...silver, k0: 1e-3, alpha: 0.5 }] };
+const def = build({
+  library: [aqueous(['H+', 'Ag+', 'NO3-']), metal('Ag')],
+  stack: [
+    ohmic(0, ['e-']),
+    layer('Ag', 1e-6),
+    face,
+    layer('water', 20e-6, { c0: { 'H+': 1, 'Ag+': 10, 'NO3-': 11 } }),
+    face,
+    layer('Ag', 1e-6),
+    ohmic(0.05, ['e-']),
+  ],
+  grid: { hmin: 0.1e-9, hmax: 200e-9, ratio: 1.15 },
+});
+const sol = new Device(def).solve();
+const mid = sol.x.length >> 1;
+console.log(`I = ${sol.current.toFixed(2)} A/m²`);
+// The silver couple's redox level, and the SHE level, mid-cell (electron voltages).
+console.log(level(sol, silver)[mid] - level(sol, SHE, { standard: true })[mid]); // ≈ 0.80 + (RT/F) ln(c/1 M)
+```
+
+## Template: a solar cell
+
+Light is a reservoir: `photon = e- + h+` with the photons' μ well above the gap generates at
+the rate `kf` (uniform in the material). Open circuit is a terminal driven at `I: 0`, whose
+voltage is then V_oc. The photocurrent flows toward +x here (holes to the p side on the right).
+
+```js
+import { Device, units } from 'driftlet';
+import { build, layer, ohmic, semiconductor } from 'driftlet/kit';
+
+const cell = (right) =>
+  build({
+    T: 300,
+    library: [semiconductor('Si')],
+    stack: [
+      ohmic(0),
+      layer('Si', units.um(1), { name: 'n', donors: units.perCm3(1e18) }),
+      layer('Si', units.um(100), { name: 'p', acceptors: units.perCm3(1e16) }),
+      ohmic(right),
+    ],
+    bulkReactions: [
+      { equation: 'e- + h+ = 0', kf: { Si: 1e8 } }, // τ ≈ 0.6 µs in the p base: L ≈ 48 µm
+      { equation: 'photon = e- + h+', fixed: { photon: units.eV(3) }, kf: { Si: 50 } }, // G, mol/(m³·s)
+    ],
+    grid: { hmin: units.nm(1), hmax: units.um(1) },
+  });
+const sc = new Device(cell(0)).solve(); // short circuit
+const oc = new Device(cell({ I: 0 })).solve(); // open circuit
+console.log(`J_sc = ${sc.current.toFixed(1)} A/m², V_oc = ${oc.terminals.right.V.toFixed(3)} V`);
+```
+
+## Template: an electrode in a stirred solution
+
+One working electrode, a stagnant layer of solution, and the well-stirred bulk as a bath. The
+bath's terminal is its reference species (Cl⁻ here, like a Ag/AgCl reference), so terminal
+voltages are against that. With table μ° (μ°_H⁺ = 0), V − φ in the solution reads against SHE.
+A terminal's current is into the device, so at the working electrode it's positive when
+oxidising (anodic). An excess of supporting electrolyte (KCl) suppresses migration but doesn't
+remove it: at 100:1 the limiting current is still about 1% off pure diffusion.
+
+```js
+import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
+import { build, layer, ohmic, bath, half, aqueous, metal } from 'driftlet/kit';
+
+const iron = half('Fe3+ + e- = Fe2+');
+const electrode = (drive) =>
+  build({
+    library: [aqueous(['K+', 'Cl-', 'Fe3+', 'Fe2+'], { epsr: 0 }), metal('Pt')],
+    stack: [
+      ohmic(drive, ['e-']), // the working electrode's terminal: the platinum's electrons
+      layer('Pt', 1e-6),
+      { reactions: [{ ...iron, k0: 1e-3 }] },
+      layer('water', 20e-6), // the stagnant layer
+      bath({ 'K+': 500, 'Cl-': 535, 'Fe3+': 5, 'Fe2+': 10 }, 'Cl-'), // the stirred bulk (neutral)
+    ],
+    grid: { hmin: 10e-9, hmax: 0.5e-6 },
+  });
+// At rest (no current), the electrode sits at the couple's Nernst potential.
+const rest = new Device(electrode({ I: 0 })).solve();
+const E = rest.V['e-'][0] - rest.phi[rest.x.length - 1]; // against SHE
+const VT = (GAS_CONSTANT * 298.15) / FARADAY;
+console.log(`rest potential ${E.toFixed(4)} V vs SHE; E° + V_T ln(c₃/c₂) = ${(0.769 + VT * Math.log(5 / 10)).toFixed(4)} V`);
+// Polarised 0.2 V positive of rest: oxidising Fe²⁺, toward its limiting current F·D·c/L.
+const dev = new Device(electrode(rest.terminals.left.V + 0.2));
+console.log(`anodic current ${dev.solve().terminals.left.current.toFixed(2)} A/m²`);
+```
+
+## Template: a live page with a slider
+
+`live()` merges slider moves made during a solve, warm-starts each solve and keeps the last
+good solution. `bandDiagram()` returns an SVG string. Pass `worker: true` to `live()` to solve in
+a Web Worker.
+
+```html
+<!doctype html>
+<meta charset="utf-8">
+<title>pn junction</title>
+<label>bias <input id="V" type="range" min="-0.5" max="0.7" step="0.01" value="0"></label>
+<span id="readout"></span>
+<div id="figure"></div>
+<script type="module">
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.1.0/src/plot.js';
+
+const def = build({
+  T: 300,
+  library: [semiconductor('Si')],
+  stack: [ohmic(0), layer('Si', 1e-6, { donors: units.perCm3(1e17) }), layer('Si', 1e-6, { acceptors: units.perCm3(1e16) }), ohmic(0)],
+  bulkReactions: [{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }],
+  grid: { hmin: 1e-9, hmax: 20e-9 },
+});
+const slider = document.getElementById('V');
+const dev = live(def, {
+  onsolution(sol, info) {
+    document.getElementById('figure').innerHTML = bandDiagram(sol, { title: `V = ${sol.terminals.right.V.toFixed(2)} V` });
+    document.getElementById('readout').textContent = info.failed ? 'no solution here' : `I = ${sol.current.toExponential(2)} A/m²`;
+  },
+});
+slider.addEventListener('input', () => dev.set({ contacts: { right: { V: +slider.value } } }));
+</script>
+```
+
+## Reading level diagrams
+
+What `bandDiagram()` and `traces()` draw, and how to explain it to a reader (docs/visualization.md
+has the long form):
+
+- **Fermi level** V_e⁻ = −μ̄_e⁻/F: the circuit voltage, what a voltmeter reads. A cell's voltage is
+  the difference between its terminals' V_e⁻.
+- **Redox level** of Ox + z e⁻ ⇌ Red, `level(sol, half)`: V_e⁻(Ox/Red) = (μ̄_Ox − μ̄_Red)/(zF), where
+  an electrode exchanging electrons by that couple would sit in equilibrium with the local
+  composition. Drawn thick and dashed. At an electrode face, the step from the metal's Fermi level
+  to it is the surface overpotential; through the solution it slopes with ohmic drop and
+  concentration polarisation. Each couple has its own; they agree only in redox equilibrium.
+- **Standard redox level** (`{ standard: true }`), thin and dashed: every participant at reference
+  concentration. The redox level sits RT/(zF) ln(a_Ox/a_Red) from it (Nernst, locally).
+- **Electrode potentials** are gaps to the SHE's standard level V°_e⁻(SHE): E = V_e⁻(electrode) −
+  V°_e⁻(SHE), E° = V°_e⁻(Ox/Red) − V°_e⁻(SHE), η = E − E_eq. With the data library's μ°, V°_e⁻(SHE)
+  in water is φ, so `phi: true` draws it. It slopes under current: "vs SHE" needs a place (say,
+  the stirred bulk).
+- **Species voltage** V_i = μ̄_i/(z_iF) (thick, solid) for every charged species: the Fermi level
+  for e⁻, a quasi-Fermi level for e⁻ and h⁺ in a semiconductor, what a reversible electrode reads
+  for an ion. A species moves down slopes in its own V_i (drift and diffusion together) and is in
+  equilibrium where it's flat. A step at a face means resistance there.
+- **Standard level** V°_i = φ + μ°_i/(z_iF) (thin, solid): a band edge for e⁻ and h⁺; V_i − V°_i =
+  (RT/z_iF) ln(c/c_ref) for ideal species. Steps in V°_i at faces (Donnan, junctions, dipoles) are
+  bookkeeping. In volts the conduction band sits below the valence band.
+- **What's left out.** φ isn't drawn: it's a per-material convention (meaningless in a metal), and
+  −eφ isn't any electron's energy; the V°_i ladder shows its variation within a material and means
+  something across faces too. The exceptions: across an insulator with no mobile species, a
+  plain sloped φ (`phi: true`) is the line to draw (its slope is the field), and in vacuum −eφ
+  really is an electron's energy. Nor is anything drawn against a reference: the diagrams are
+  reference-free (shifting everything changes nothing), every gap on the electron diagram is
+  physical, so a reader picks a level at a point as their reference. "vs SHE" and "from the vacuum"
+  need a place, since both levels vary in space.
+- A gap V_i − V_j between two species is free of φ, but carries one constant fixed by the elements'
+  conventional zeros (μ = 0 per element). So `shifts` (marked ⌇) moves a species' lines to share a
+  plot without losing anything.
+- Call V_i the species voltage and say what it is; it's new to most readers. Credit Jamnik and
+  Maier (Phys. Chem. Chem. Phys. 3, 1668 (2001)) where V_i rails explain impedance or linear
+  response.
+
+## Common mistakes
+
+- **No alignment at a heterointerface.** `interfaces[0] (between … [Si] and … [GaAs]): an
+  interface between different materials needs an alignment`. Give the face `{ dipole }` or
+  `{ step: { species: 'e-', value } }` (the conduction-band offset, J/mol), or estimate one from
+  electron affinities with `vacuumDipole` (docs/alignment.md). `interfaces[f]` is the f-th face
+  of the stack, counting from the left.
+- **A metal face with no φ law.** `… .phi: a face between a conductor and a material with
+  ε > 0 needs an explicit φ law`. Give `{ phi: { type: 'capacitive', C }, zeroCharge }`, or
+  `phi: 'neutral'`, or make the electrolyte strictly neutral (`aqueous(names, { epsr: 0 })`)
+  when double layers don't matter.
+- **`ohmic()` on a metal.** Its default holds both e⁻ and h⁺, for semiconductors. On a metal
+  layer, write `ohmic(V, ['e-'])`.
+- **Ions on both sides of a reacting face.** Label them: `'Li+(left) = Li+(right)'`, and give
+  their link (`species: { 'Li+': 'blocked' }` if they cross only by the reaction).
+- **Unit slips.** D in cm²/s, μ° in eV, capacitance in µF/cm², T in °C. `describe(def)` flags
+  numbers that look like these.
+- **A closed system with no amount.** A species that doesn't reach a contact needs `c0`.
+- **A strictly neutral `c0` that doesn't balance.** With `epsr: 0`, Σ z·c0 must be zero (traces
+  included): `… carries a net charge of … mol/m³`. Add the counter-ion's share.
+- **A sharp junction between very different solutions** (3 M KCl against 1 µM traces) can't
+  start: grade it over a few thin layers mixing one solution into the other, as at a frit.
+- **A steady solve of a closed cell where every ion can cross.** Its steady state is complete
+  mixing. To watch a junction or a salt bridge, step in time from the unmixed `c0` (`advance`).
+- **Everything floating.** At least one terminal must be held at a voltage `V`.
+- **The library's semiconductors are at 300 K.** Give `T: 300`.
+- **Sign of the current.** `sol.current` is positive toward +x: a forward-biased diode with its
+  p side on the right carries negative current. A terminal's current is into the device.
+- **Sign of a voltage across a membrane.** `sol.terminalVoltage` is V_right − V_left. Physiology
+  quotes V_inside − V_outside, so put the inside on the right or flip the sign.
+- **A coefficient without its space.** `'2e- + …'` reads `2e-` as a species name; the error says
+  to write `2 e-`.
+- **Changing c0 with `set()`.** A carried state keeps what it holds; `c0` is only the starting
+  composition. Make a new `Device` to start over from it.
+- **An unresolved double layer.** If `sol.warnings` says so, refine the grid (`hmin` below the
+  Debye length) or use a neutral model (`epsr: 0`, `phi: 'neutral'`).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "driftlet",
+  "version": "0.1.0",
+  "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./kit": {
+      "types": "./types/kit.d.ts",
+      "default": "./src/kit.js"
+    },
+    "./plot": {
+      "types": "./types/plot.d.ts",
+      "default": "./src/plot.js"
+    }
+  },
+  "main": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "files": [
+    "src",
+    "types",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test",
+    "bench": "node bench/bench.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"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "drift-diffusion",
+    "poisson-nernst-planck",
+    "electrochemistry",
+    "semiconductor",
+    "simulation"
+  ],
+  "homepage": "https://markblundeberg.github.io/driftlet/demos/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/markblundeberg/driftlet.git"
+  },
+  "bugs": {
+    "url": "https://github.com/markblundeberg/driftlet/issues"
+  },
+  "author": "Mark Lundeberg",
+  "license": "0BSD"
+}