driftlet 0.16.4 → 1.0.1

package/llms.txt

@@ -12,12 +12,14 @@ Every code block below runs in the test suite and prints its closed-form check.
 two sections, then go to the template nearest your device:
 
 - semiconductors: a pn junction (with an I–V sweep), a live page with a slider, a solar cell, a
-  MOS capacitor, a Schottky diode, a thin-film transistor, a pulse drifting along a bar (under
-  Transients);
+  MOS capacitor, a pulse drifting along a bar (under Transients);
 - electrochemistry: a cell, an electrode in a stirred solution (a potential step, and a cyclic
-  voltammogram), corrosion;
-- physiology: a cell membrane (a resting potential), a voltage clamp, an action potential, one
-  travelling along an axon.
+  voltammogram), a battery particle discharging;
+- physiology: a cell membrane (a resting potential).
+
+More in docs/templates.md: a Schottky diode, a thin-film transistor, corrosion under a drop (an
+electrode spread through a film), a voltage clamp, an action potential, one travelling along an
+axon.
 
 The references are in docs/: device.md (the definition), kit.md (the helpers), conventions.md
 (signs and levels), visualization.md, alignment.md (band offsets), statistics.md (non-ideal
@@ -28,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@0.16.4/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -58,12 +60,11 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
 - **What isn't defaulted**: an alignment between different materials, a φ law where a metal
   meets a dielectric, and the amount of anything a contact doesn't feed (`c0`). The error names
   the path and says what to give. (Kinetic details are defaulted: listed in docs/device.md.)
-- **Check before trusting.** `sol.converged` must be true; read `sol.warnings`, where a failed
-  solve always says why. `describe(def)` (kit) summarises a definition and flags likely unit
-  slips. Once a device works, log `check(dev, sol).text` (kit) once: each species' ledger,
-  conservation in transients, a steady state on a grid twice as fine (a FAIL means refine;
-  a transient you rerun on a finer grid yourself) and with its species listed in reverse (a
-  FAIL there means a solve converged somewhere that isn't steady: compare a long advance()).
+- **Check before trusting, early.** `sol.converged` must be true; read `sol.warnings`, where a
+  failed solve always says why. Before comparing with theory, log `describe(def)` (kit: a summary
+  that flags unit slips) and `check(dev, sol).text` (kit): each species' ledger, conservation in
+  transients, a grid twice as fine (a FAIL means refine) and the species listed in reverse (a FAIL
+  means a solve converged somewhere that isn't steady: compare a long advance()).
 
 ## How a device is written
 
@@ -98,7 +99,8 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   `{ region: 'base', from, to, V, terminal: 'h+', species: { 'h+': 'equilibrium' } }`.
 - **Drives.** A terminal is held at a voltage `V`, driven by a current `I` (open circuit is
   `I: 0`), or behind a resistance `{ V, R }`; in `build()`, the same object goes where the
-  voltage would (`ohmic({ I: 0 }, ['e-'])`, `ohmic({ V: 1, R: 1e3 }, ['e-'])`). Either can be a waveform: a table `{ t, values }`
+  voltage would (`ohmic({ I: 0 }, ['e-'])`, `ohmic({ V: 1, R: 1e3 }, ['e-'])`), and `set()` may
+  switch one kind for another (`{ I: 0 }` drops a held `V`). Either can be a waveform: a table `{ t, values }`
   (piecewise linear; a step is two points at one time), or the kit's `pulse({ start, width,
   amplitude, rise, base })`, `square({ high, low, period, duty })`, `ramp({ from, to, duration,
   start })` or `triangle({ from, to, period })` (out and back each period from t = 0: a cyclic
@@ -114,14 +116,17 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
   { tauN, tauP } }` in place of `kf` (s), or at a face `{ equation: 'e-(left) + h+(right) = 0',
   srh: { vn, vp } }` (m/s); with τ_N ≪ τ_p it gives n-type silicon's holes a lifetime τ_p at any
   injection. Light is a reaction from a reservoir (`photon = e- + h+`, uniform), or absorbed as
-  it goes in, `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })`. To switch
-  it during a run, `set()` the device's `bulkReactions` (the state and the step size carry over).
+  it goes in, `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })`, `from` and
+  `to` being x in the device (a port's window is instead m from its region's left end). To switch
+  it during a run, `set()` the device's whole `bulkReactions` list, recombination included: in
+  `set()`, a list replaces and an object merges (the state and the step size carry over).
 - **Electrode kinetics.** A face reaction's `k0` (mol/(m²·s)) is its rate with every participant
   at cRef: i₀ = nF·k0 there, and k0 = k°·cRef for a textbook k° in m/s (1 cm/s at 1 M is
   `k0: 10`).
 - **Grids** grade geometrically from `hmin` at each region's ends up to `hmax`, neighbouring cells
   differing by at most `ratio` (1.2): put `hmin` below the shortest length that matters (a Debye
-  length, a depletion edge). `check()` says whether it's fine enough.
+  length, a depletion edge). Left out, `grid` is a coarse default for a first look; `check()`
+  says whether a grid is fine enough.
 
 `build()` is the usual way in. It writes a plain definition for `new Device()`, which some
 templates below write by hand (where a port spans a region, or no stack fits):
@@ -204,9 +209,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@0.16.4/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.4/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
 
 const def = build({
   T: 300,
@@ -230,22 +235,17 @@ To draw in your own style, `traces(sol, opts)` (kit, the same options) gives the
 see "Reading level diagrams" below.
 
 For an explainer, `particles(sol, { weight, cap })` (kit) draws a solution as dots, each `weight`
-mol/m² of a species, hopping at rates taken from the solution: on average their density is its
-concentration and their net crossing its flux. Say on the page that it samples the continuum
-solution, and how much a dot is. Where a dot would be lost among millions (majority carriers, a
-bath), a cell over `cap` dots is a sea: shade it by `expected(name)`. Each frame,
-`swarm.step(dt)` in the device's time (about h²/D per hop, h a cell), then draw `swarm.dots`
-(`{ species, x }`) and `swarm.events` (`'unmade'` is a recombination, `'cross'` an ion through a
-membrane between two seas); on a new steady solution, `swarm.update(sol, { resample: true })`.
-An ion beside a cell membrane hops ~1e6 times per crossing, so a membrane page shows seas and
-crossing events, not walking ions. The demos' page scripts do this for a diode's carriers (pn),
-ions crossing a nerve membrane (axon, `cap: 0`) and Donnan exclusion (membrane).
+mol/m² of a species, hopping at the solution's rates, so their density and net crossings agree
+with it on average; say on the page that they sample the continuum solution. A cell over `cap`
+dots is a sea, shaded by `expected(name)`. Each frame, `swarm.step(dt)`, then draw `swarm.dots`
+and `swarm.events` (docs/kit.md; the pn, axon and membrane demos are worked examples).
 
 ## Template: a solar cell
 
 `photon = e- + h+`, with the photons' μ well above the gap, generates uniformly at the rate `kf`.
 Open circuit is `I: 0`, and the terminal's V is then V_oc. The photocurrent flows toward +x
-(holes to the p side, on the right).
+(holes to the p side, on the right), so the power the cell delivers is V·`sol.current`. Light
+absorbed as it goes in, for a cell's thickness to matter, is `photogeneration()` (above).
 
 ```js
 import { Device, units } from 'driftlet';
@@ -272,14 +272,10 @@ 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`);
 ```
 
-In an organic cell, light makes excitons: a neutral species `X` in the donor, made by
-`photogeneration({ ..., makes: 'X' })` and decaying by `{ equation: 'X = 0', kf: { donor: 1 / tau } }`.
-They split at the donor/acceptor face by a reaction there, `X = h+(left) + e-(right)` with e⁻ and
-h⁺ blocked at the face (the reaction moves them), and its reverse is charge-transfer
-recombination; the face's `step` sets E_CT. With `alpha: 0` the splitting is a velocity
-k0/cRef, a Robin condition on the exciton profile; with α > 0 it's k0/cRef · e^(α(E_X − E_CT)/RT).
-The organic demo's page script is a worked example (J_sc against exciton diffusion theory, V_oc
-against detailed balance).
+In an organic cell, light makes excitons, a neutral species made by `photogeneration({ ...,
+makes: 'X' })`, which split at the donor/acceptor face by a reaction, `X = h+(left) + e-(right)`
+(e⁻ and h⁺ blocked there; the face's `step` sets E_CT). The organic demo's page script is a
+worked example, checked against exciton diffusion and detailed balance.
 
 For a perovskite cell, prefer the curated `perovskiteCell({ V, light, bulkSRH })`: IonMonger's
 default cell (mobile iodide vacancies), with its J–V scans at seven rates in `PEROVSKITE_SCANS`
@@ -336,73 +332,6 @@ the same C at any frequency with the port; without it, only below the minority s
 above. Draw it with
 `bandDiagram(sol, { energy: true, phi: ['SiO2'] })`: across an insulator φ is the line to draw.
 
-## Template: a Schottky diode
-
-A barrier pinned at the metal (`phi: 'pinned'`, `zeroCharge` the barrier height for Si, whose
-μ°_e⁻ is 0), crossed at the emission velocity: a `velocity` link, N_in = v (c_eq − c). With
-`'equilibrium'` links (infinite velocity) it's diffusion theory instead, 20 times the current here.
-
-```js
-import { Device, units, FARADAY, GAS_CONSTANT } from 'driftlet';
-import { build, layer, ohmic, semiconductor } from 'driftlet/kit';
-
-const T = 300, VT = (GAS_CONSTANT * T) / FARADAY, Si = semiconductor('Si');
-const phiB = 0.85, A = 1.12e6; // the barrier (V); Richardson's constant for n-Si, A/(m²K²)
-const v = (A * T * T) / (FARADAY * Si.materials.Si.species['e-'].cRef); // Bethe's emission velocity, 2.2e4 m/s (cRef is N_c)
-const schottky = (V) => ({
-  V,
-  terminal: 'e-',
-  species: { 'e-': { type: 'velocity', v }, 'h+': { type: 'velocity', v, offset: 0 } },
-  phi: 'pinned',
-  zeroCharge: phiB, // E_c − E_F at the metal
-});
-const dev = new Device(build({ T, library: [Si], stack: [schottky(0), layer('Si', units.um(2), { donors: units.perCm3(1e16) }), ohmic(0)], grid: { hmin: units.nm(1), hmax: units.nm(20) } }));
-for (const V of [0.1, 0.2, 0.3]) {
-  dev.set({ contacts: { left: { V } } }); // the metal positive: forward
-  const J = dev.solve().current, te = A * T * T * Math.exp(-phiB / VT) * Math.expm1(V / VT);
-  console.log(`${V} V: J ${J.toExponential(3)} A/m², thermionic emission ${te.toExponential(3)}`); // about 4% below: the depletion region in series
-}
-```
-
-The same `velocity` link at an ohmic contact is its surface recombination velocity.
-
-## Template: a thin-film transistor (a capacitance along a channel)
-
-A **port with a `capacitance`** holds charge σ = C (V − zeroCharge − φ) per area of electrode
-along its window, balanced by the region's: a gate along a channel, a porous electrode's double
-layer. Here x runs from source to drain with the gate spread along it: the gradual-channel
-approximation, exact for a thin film until it pinches off.
-
-```js
-import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
-
-const T = 300, VT = (GAS_CONSTANT * T) / FARADAY;
-const t = 20e-9, L = 10e-6, W = 100e-6, C = 1e-3, mu = 1e-3; // film, length, width (m); F/m² of gate; m²/(V·s)
-const tft = (Vg, Vd) =>
-  new Device({
-    T,
-    species: [{ name: 'e-', z: -1, cRef: 46 }], // an undoped film's electrons (N_c 2.8e19 cm⁻³)
-    materials: { film: { epsr: 0, species: { 'e-': { D: mu * VT, mu0: 0 } } } }, // ε = 0: F·n·t balances σ
-    regions: [{ name: 'channel', material: 'film', length: L }],
-    contacts: {
-      left: { V: 0, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'neutral' }, // source
-      right: { V: Vd, terminal: 'e-', species: { 'e-': 'equilibrium' }, phi: 'neutral' }, // drain
-    },
-    ports: [{ name: 'gate', region: 'channel', V: Vg, area: 1 / t, capacitance: { C, zeroCharge: 0.3 } }],
-    grid: { hmin: L / 2000, hmax: L / 100, ratio: 1.05 }, // fine at the drain, where it pinches off
-  });
-// The output characteristic at V_G = 2 V: linear, then saturating past V_D ≈ V_G − 0.3 V.
-for (const Vd of [0.1, 0.5, 1, 1.5, 2, 3]) {
-  const sol = tft(2, Vd).solve();
-  const I = -sol.current * t * W; // sol.current is per m² of the film's section
-  console.log(`V_D ${Vd.toFixed(1)} V: I_D ${(I * 1e6).toFixed(2)} µA, σ at the drain ${(sol.ports[0].sigma.at(-1) * 1e3).toFixed(3)} mC/m²`);
-}
-```
-
-To sweep the gate on one device instead, patch the port: `dev.set({ ports: { gate: { V } } })`.
-An organic electrochemical transistor is the same with a volumetric capacitance C*:
-`area: 1 / t, capacitance: { C: Cstar * t }`.
-
 ## Template: an electrochemical cell
 
 An electrode is a metal layer with the reaction at its face, behind a contact holding the
@@ -488,69 +417,62 @@ for (const t of [3e-3, 1e-2, 3e-2]) {
 
 A cyclic voltammogram is this electrode driven by `triangle({ from, to, period })`, the period
 being 2|to − from| over the scan rate: `solve()` it at `from` first, since the scan starts there
-at t = 0, then `advance()`. Its potential against the bath's terminal is −`trace.voltage` (that
-is V_right − V_left), and `trace.current` is anodic positive.
-
-## Template: corrosion under a drop (an electrode spread through a film)
-
-A **port with reactions** is an electrode spread through a strictly neutral region: a metal under
-a film of water, a crevice's walls, a porous electrode. Its `terminal` is the metal's carrier,
-`area` its area per volume (1/h under a film h thick), each reaction Butler–Volmer per area, and
-a `capacitance` the double layer. A **`geometry`** gives the device a cross-section A(x): here x
-is the radius of a drop, A = 2πr·h(r), and currents and amounts become totals (A, mol).
+at t = 0, then `advance()` with a `dtMax` of a millivolt's worth of sweep, or the trace's points
+fall a few mV apart and miss the peaks. For a diffusion peak (Randles–Ševčík), the stagnant layer
+must be well past √(D·t_scan), a few hundred µm: the template's 20 µm gives a thin-layer wave.
+Its potential against the bath's terminal is −`trace.voltage` (that is V_right − V_left), and
+`trace.current` is anodic positive.
+
+## Template: a battery particle discharging
+
+A battery's insertion electrode is a material described by its OCV curve (docs/statistics.md):
+here one particle of a cathode, a sphere, the single-particle model. Li⁺ is held at its surface
+by the electrolyte, and the electrons come in through a port there (a current into the device,
+so negative to discharge a cathode). With no steady state while a current flows, it's `advance()`d
+from its `c0`, never `solve()`d. `D` is the dilute value: an ideal host's chemical diffusivity is
+D/(1 − x), so it fills more easily the fuller it gets. A real OCV curve with a plateau needs a
+little of the ideal slope (the error says how much).
 
 ```js
-import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
-import { aqueous, polarization, H2O } from 'driftlet/kit';
-
-// Salt water on iron: a drop 3 mm across. The iron dissolves and reduces O₂, which comes in from
-// the air through the drop's top, fastest at the thin rim: the centre corrodes, the rim doesn't.
-const T = 298.15, RT = GAS_CONSTANT * T, R = 3e-3, h0 = 1e-3, cO2 = 0.26, D = 2e-9;
-const lib = aqueous(['Na+', 'Cl-', 'Fe2+', 'OH-', 'H+'], { epsr: 0 }); // strictly neutral water
-lib.species.push({ name: 'O2', z: 0, cRef: 1000 }, { name: 'e-', z: -1 }); // e⁻: the iron's, in no material
-lib.materials.water.species.O2 = { D, mu0: 16.4e3 };
-const r = Array.from({ length: 61 }, (_, j) => (j / 60) * R);
-const h = r.map((x) => Math.max(h0 * (1 - (x / R) * (x / R)), 0.02 * h0)); // the drop's height
-const dev = new Device({
-  T,
-  species: lib.species,
-  materials: lib.materials,
-  geometry: { area: { x: r, values: r.map((x, j) => 2 * Math.PI * x * h[j]) } }, // ions squeeze through the thin rim
-  regions: [{ name: 'drop', material: 'water', length: R, c0: { 'Na+': 500, 'Cl-': 500 + 2e-6, 'Fe2+': 1e-6, 'OH-': 1e-4, 'H+': 1e-4, O2: cO2 } }],
-  contacts: { left: { phi: 'neutral' }, right: { phi: 'neutral' } }, // closed: the centre, and the rim
-  bulkReactions: [
-    { equation: 'H+ + OH- = H2O', fixed: { H2O }, kf: { water: 1.4e8 } }, // H2O: water's μ, −237.129 kJ/mol
-    // O₂ from the air through the drop: a rate k_f (1 − c/c_sat), k_f = D c_sat/h² (not a port's
-    // exchange link, whose rate is linear in μ rather than c)
-    { equation: 'Air = O2', fixed: { Air: 16.4e3 + RT * Math.log(cO2 / 1000) }, kf: { water: { x: r, values: h.map((y) => (D * cO2) / (y * y)) } } },
-  ],
-  ports: [{
-    name: 'iron', region: 'drop', terminal: 'e-',
-    V: 0, // the only metal and the only path for current, so it passes none: held, it fixes the level φ is read against
-    area: { x: r, values: h.map((y) => 1 / y) }, // m² of iron per m³ of water
-    capacitance: { C: 0.2, zeroCharge: -0.4 }, // the double layer: the potential moves continuously
-    reactions: [
-      { equation: 'Fe2+ + 2 e- = Fe(s)', fixed: { 'Fe(s)': 0 }, k0: 5e-6, alpha: 0.5 },
-      { equation: 'O2 + 2 H2O + 4 e- = 4 OH-', fixed: { H2O }, k0: 3e-9, alpha: 0.125 },
-    ],
-  }],
-  grid: { hmin: 5e-6, hmax: 60e-6, ratio: 1.2 },
-});
-const sol = dev.advance(600); // ten minutes
-const iron = sol.ports[0], last = iron.x.length - 1;
-// rates[q][j]: reaction q at node j of the window, forward, mol/(m²·s) of iron; anodic current +
-const anodic = (j) => 2 * FARADAY * -iron.rates[0][j] - 4 * FARADAY * iron.rates[1][j];
-console.log(`iron at ${(iron.V - sol.phi[0]).toFixed(3)} V against the water at the centre (SHE, with table μ°)`);
-console.log(`net current on the iron: ${anodic(0).toFixed(2)} A/m² at the centre, ${anodic(last).toFixed(2)} A/m² at the rim`);
-// The Evans diagram at the centre: each reaction's current with the iron's level moved, the water held.
-const levels = [-0.55, -0.5, -0.45, -0.4].map((v) => v + sol.phi[0]);
-const evans = polarization(dev, sol, { port: 'iron', x: 0 }, levels);
-for (const rx of evans.reactions) console.log(`${rx.equation}: ${Array.from(rx.current, (i) => i.toFixed(2)).join(', ')} A/m²`);
-```
+import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
 
-Species can take an electrode's surface sites (`surface`, Langmuir coverages), and a reaction
-with `bare: true` runs only on bare metal: a passive film (docs/device.md). A battery's insertion
-electrode is a material described by its OCV curve (docs/statistics.md).
+const T = 298.15, VT = (GAS_CONSTANT * T) / FARADAY;
+const R = 5e-6, D = 1e-14, cMax = 50000, x0 = 0.1; // m, m²/s, mol/m³ of sites, starting fill
+const xs = Array.from({ length: 99 }, (_, k) => (k + 1) / 100);
+const particle = (I) =>
+  new Device({
+    T,
+    species: [{ name: 'Li+', z: 1 }, { name: 'e-', z: -1 }],
+    materials: {
+      host: {
+        epsr: 0,
+        species: { 'Li+': { D, mu0: 0, cRef: cMax }, 'e-': { D: 1e-4, mu0: 0, cRef: cMax } },
+        statistics: [{ type: 'insertion', species: ['Li+', 'e-'], cMax, ocv: { x: xs, E: xs.map((x) => 4 - VT * Math.log(x / (1 - x))), muRef: 0 } }],
+      },
+    },
+    geometry: { type: 'spherical', r0: 0 }, // x is the radius; currents are totals (A)
+    regions: [{ name: 'p', material: 'host', length: R, c0: { 'Li+': x0 * cMax, 'e-': x0 * cMax } }],
+    contacts: {
+      left: { phi: 'neutral' }, // the centre
+      right: { V: 0, terminal: 'Li+', species: { 'Li+': 'equilibrium' }, phi: 'bulk' }, // Li⁺ at the electrolyte's level
+    },
+    ports: [{ name: 'wire', region: 'p', from: 0.98 * R, to: R, I, terminal: 'e-', species: { 'e-': { type: 'conductance', G: 1e15 } } }],
+    grid: { hmin: R / 400, hmax: R / 40 },
+  });
+const Q = FARADAY * cMax * (4 / 3) * Math.PI * R ** 3; // C for Δx = 1
+const xEnd = 1 / (1 + Math.exp(-0.1 / VT)); // the OCV reaches a 3.9 V cutoff at x = 0.98
+for (const C of [0.2, 20]) {
+  const I = -(C * (xEnd - x0) * Q) / 3600; // a C-rate: the whole window in 1/C hours
+  const dev = particle(I);
+  // Halfway: in u = −ln(1 − x), whose diffusivity is D however full, a constant flux q in makes a
+  // quasi-steady parabola, surface − centre = qR/(2D c_max), once t ≫ R²/(π²D) (250 s here).
+  const half = dev.advance(1800 / C), u = (c) => -Math.log(1 - c / cMax), q = -I / (FARADAY * 4 * Math.PI * R * R);
+  const du = u(half.c['Li+'].at(-1)) - u(half.c['Li+'][0]);
+  let sol = half;
+  while (sol.converged && sol.terminals.wire.V > 3.9) sol = dev.advance(sol.time + 36 / C); // on to the cutoff, in 1% steps
+  console.log(`${C}C: ${((100 * (-I * sol.time)) / Q / (xEnd - x0)).toFixed(0)}% of the capacity; halfway, Δu ${du.toFixed(4)}, qR/(2D c_max) ${((q * R) / (2 * D * cMax)).toFixed(4)}`);
+} // 0.2C: 100%, 0.0205 against 0.0204; 20C: 91%, and halfway (90 s) is too soon for the parabola
+```
 
 ## Template: a cell membrane
 
@@ -601,132 +523,10 @@ console.log(check(dev, sol).text); // per compartment: Na⁺ leaks into the cyto
 Between two baths instead (the inside one `bath(inside, 'Cl-', { I: 0 })`: held composition, no
 current), V_m is GHK. Without the pump, a closed cell runs down to Donnan equilibrium.
 
-## Template: a voltage clamp
-
-A face's `gates` (each a fraction open, dx/dt = α(V)(1 − x) − β(V)x with V = φ_right − φ_left)
-scale its links (`gates: { m: 3, h: 1 }`). `hodgkinHuxley({ T, linear: true })` (kit) writes the
-squid axon's as Hodgkin and Huxley had them, conductances g(V − E). Between two baths without a
-reference species, V_right − V_left is V_m, so a held step is their voltage clamp.
-
-```js
-import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
-import { build, layer, bath, aqueous, hodgkinHuxley } from 'driftlet/kit';
-
-const T = 279.45, VT = (GAS_CONSTANT * T) / FARADAY; // HH's 6.3 °C
-const out = { 'Na+': 440, 'K+': 20, 'Cl-': 450, 'A-': 10 }, inside = { 'Na+': 50, 'K+': 400, 'Cl-': 52, 'A-': 398 }; // squid, mM
-const water = aqueous(['Na+', 'K+', 'Cl-'], { epsr: 0 });
-water.species.push({ name: 'A-', z: -1, cRef: 1000 });
-water.materials.water.species['A-'] = { D: 0.5e-9, mu0: 0 };
-const hh = hodgkinHuxley({ T, linear: true });
-const step = -0.01; // from −65 mV to −10 mV at 1 ms
-const dev = new Device(
-  build({
-    T,
-    library: [water],
-    stack: [
-      bath(out), // the outside, on the left
-      layer('water', 1e-6, { c0: out }),
-      { phi: { type: 'capacitive', C: 0.01 }, gates: hh.gates, species: { ...hh.species, 'A-': 'blocked' } },
-      layer('water', 1e-6, { c0: inside }),
-      bath(inside, { t: [0, 1e-3, 1e-3, 1], values: [-0.065, -0.065, step, step] }),
-    ],
-    grid: { hmin: 20e-9, hmax: 0.2e-6 },
-  }),
-);
-dev.solve(); // the rest at −65 mV, the gates at their values there
-const run = dev.advance(11e-3, { dtMax: 0.02e-3, probes: [{ interface: 0, species: 'Na+' }, { interface: 0, species: 'K+' }] });
-const [na, k] = run.trace.probes.map((N) => N.map((x) => -FARADAY * x)); // outward currents, A/m²
-const peak = na.indexOf(Math.min(...na)), EK = VT * Math.log(out['K+'] / inside['K+']);
-console.log(`I_Na peaks ${((run.trace.t[peak] - 1e-3) * 1e3).toFixed(2)} ms into the step, ${(na[peak] * 0.1).toFixed(2)} mA/cm²`); // 0.73 ms, −1.48
-console.log(`g_K after 10 ms: ${((k.at(-1) / (step - EK)) * 0.1).toFixed(2)} mS/cm²`); // 21.12: HH's 36 n∞⁴ is 21.5, which n nearly reaches by 10 ms
-```
-
-## Template: an action potential
-
-Without `linear: true` (given `inside` and `outside`), `hodgkinHuxley` writes GHK permeabilities
-matched to HH's conductances at −65 mV, which rectify as real channels do. A pump-less cell has no
-steady rest (`solve()` finds Donnan), so start the transient from the concentrations given.
-
-```js
-import { Device } from 'driftlet';
-import { build, layer, bath, aqueous, injector, pulse, hodgkinHuxley } from 'driftlet/kit';
-
-const T = 279.45; // HH's 6.3 °C
-const out = { 'Na+': 440, 'K+': 20, 'Cl-': 450, 'A-': 10 }, inside = { 'Na+': 50, 'K+': 400, 'Cl-': 52, 'A-': 398 }; // squid, mM
-const water = aqueous(['Na+', 'K+', 'Cl-'], { epsr: 0 });
-water.species.push({ name: 'A-', z: -1, cRef: 1000 });
-water.materials.water.species['A-'] = { D: 0.5e-9, mu0: 0 };
-const hh = hodgkinHuxley({ inside, outside: out, T }); // GHK channels; outside on the left
-const axon = new Device(
-  build({
-    T,
-    library: [water],
-    stack: [
-      bath(out, 'Cl-'),
-      layer('water', 5e-6, { name: 'outside', c0: out }),
-      { phi: { type: 'capacitive', C: 0.01 }, gates: hh.gates, species: { ...hh.species, 'A-': 'blocked' } },
-      layer('water', 20e-6, { name: 'cytoplasm', c0: inside }),
-      { species: { 'Na+': 'blocked', 'K+': 'blocked', 'Cl-': 'blocked', 'A-': 'blocked' }, phi: 'neutral' },
-    ],
-    // the stimulus: 10 µA/cm² of K⁺ for 1 ms at 20 ms, from a pipette in the cytoplasm
-    ports: [injector({ region: 'cytoplasm', from: 15e-6, to: 20e-6, species: 'K+', I: pulse({ start: 20e-3, width: 1e-3, amplitude: 0.1 }) })],
-    grid: { hmin: 50e-9, hmax: 1e-6 },
-  }),
-);
-let peak = -1;
-for (let k = 1; k <= 300; k++) {
-  const sol = axon.advance(k * 1e-4); // 0.1 ms at a time
-  peak = Math.max(peak, sol.interfaces[0].V); // V_m, and sol.interfaces[0].gates = { m, h, n }
-}
-console.log(`peak ${(peak * 1e3).toFixed(1)} mV`); // +12.6: GHK's Na⁺ current is limited by the 50 mM inside (linear: true gives +37.9, HH's own)
-```
-
-## Template: an action potential travelling along an axon
-
-Here x runs along the axon: the axoplasm is one region, and the membrane a port spanning it, a
-capacitance and gated channels to an outside given as a `bath` (the port's V is then the
-outside's φ). `hodgkinHuxley({ T, area })` writes HH's channels for it, `area` being the membrane
-per volume, 2/a. Cable theory isn't put in; it comes out of the ions' drift. `ports[k].Vm[j]` and
-`ports[k].gates[name][j]` give the membrane at each node. A myelinated axon is regions, each with
-its own port (an internode's just a small capacitance). Nothing warns of a grid too coarse for
-the spike's front: the speed comes out 3% low on 2 mm cells, 0.2% on 0.5 mm, for a = 238 µm
-(scale h with √a). The stimulus is a current per volume, so a thinner axon needs it as 1/a.
-
-```js
-import { Device, FARADAY, GAS_CONSTANT } from 'driftlet';
-import { hodgkinHuxley, injector, pulse } from 'driftlet/kit';
-
-const T = 291.65, VT = (GAS_CONSTANT * T) / FARADAY, a = 238e-6; // 18.5 °C, a squid giant axon
-const inside = { 'Na+': 50, 'K+': 400, 'Cl-': 52.5, 'A-': 397.5 }; // mM
-// Outside levels that put the Nernst potentials at HH's +50, −77 and −54.4 mV (leak as Cl⁻).
-const outside = { 'Na+': 50 * Math.exp(0.05 / VT), 'K+': 400 * Math.exp(-0.077 / VT), 'Cl-': 52.5 * Math.exp(0.054387 / VT) };
-// One D for the small ions, giving HH's 35.4 Ω·cm.
-const D = 1 / 0.354 / ((FARADAY * FARADAY) / (GAS_CONSTANT * T)) / (50 + 400 + 52.5);
-const sp = (d) => ({ D: d, mu0: 0, cRef: 1000 });
-const sealed = { species: { 'Na+': 'blocked', 'K+': 'blocked', 'Cl-': 'blocked', 'A-': 'blocked' }, phi: 'neutral' };
-const hh = hodgkinHuxley({ T, area: 2 / a });
-const axon = new Device({
-  T,
-  species: [{ name: 'Na+', z: 1 }, { name: 'K+', z: 1 }, { name: 'Cl-', z: -1 }, { name: 'A-', z: -1 }],
-  materials: { axoplasm: { epsr: 0, species: { 'Na+': sp(D), 'K+': sp(D), 'Cl-': sp(D), 'A-': sp(1e-12) } } },
-  regions: [{ name: 'axon', material: 'axoplasm', length: 0.06, c0: inside }],
-  contacts: { left: sealed, right: sealed },
-  ports: [
-    { name: 'membrane', region: 'axon', V: 0, area: 2 / a, capacitance: { C: 0.01, zeroCharge: 0 }, bath: { c: outside }, gates: hh.gates, species: hh.species },
-    injector({ name: 'stim', region: 'axon', from: 0, to: 1e-3, species: 'K+', I: pulse({ start: 30e-3, width: 0.2e-3, amplitude: 30 }) }),
-  ],
-  grid: { hmin: 2e-4, hmax: 2e-4 },
-});
-axon.advance(30e-3); // settle to rest (no pump: start from the concentrations, not solve())
-const sol = axon.advance(34e-3, { dtMax: 5e-6, probes: [{ x: 0.02, quantity: 'phi' }, { x: 0.04, quantity: 'phi' }] });
-const { t, probes } = sol.trace, at = (v) => t[v.findIndex((x) => x > 0)]; // (φ inside, the outside's held at 0)
-console.log(`${(0.02 / (at(probes[1]) - at(probes[0]))).toFixed(1)} m/s`); // 18.8 here (finely resolved, 18.73; HH computed 18.8)
-```
-
 ## Transients
 
 `advance(t, opts)` steps adaptively from the device's present state (its `c0`, or the steady
-state if you called `solve()`) to time t. It returns the solution there, with `done` and a `trace`
+state if you called `solve()`) to time t, absolute (for a further dt, `advance(sol.time + dt)`). It returns the solution there, with `done` and a `trace`
 of this call's accepted steps (`t`, `current`, `voltage`: V_right − V_left). It stops short at
 `budgetMs` (an animation frame: call again) or, with a warning saying why, at `maxSteps` (100000)
 or a step that won't converge. `probes`, read at accepted steps (give `dtMax` to resolve them):
@@ -814,7 +614,8 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
   reaction; `shifts` (marked ⌇) moves one species' lines to fit a shared axis.
 - **Your own style.** `traces(sol, opts)` gives `{ x, series: [{ id, label, kind, role, slot, y }],
   regions, faces, range }`: `kind` says how a line reads (`'level'`, `'standard'`, `'redox'`,
-  `'redox-standard'`, `'phi'`), `themeColor(role, slot)` (plot) gives our colours,
+  `'redox-standard'`, `'phi'`; an `id` is the kind and species, `V:e-`, `Vstd:h+`), `themeColor(role,
+  slot)` (plot) gives our colours,
   `labelParts(label)` splits TeX-style subscripts, `NaN` breaks a line, and a face's doubled nodes
   share an x (a vertical step).
 
@@ -830,17 +631,16 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
 
 ## Common mistakes
 
-- **Errors that say what to give.** A missing alignment at a heterointerface (`vacuumDipole`
-  estimates one from electron affinities, docs/alignment.md), a metal face with no φ law,
-  everything floating (hold one terminal at a `V`), a species that reaches no contact without a
-  `c0`, an unbalanced `c0` in a closed neutral region (add the counter-ion's share), `'2e-'` for
-  `'2 e-'`, a current drive of the wrong sign. `interfaces[f]` is the stack's f-th face.
+Errors say what to give, and a misspelt option is an error that names the one meant. Beyond
+those:
+
 - **A gate as a contact on an oxide.** It fails as `'e-' is absent from the end material 'SiO2'`: make the
   gate a metal layer with a capacitive face, as in the MOS template.
-- **`ohmic()` on a metal.** Its default holds e⁻ and h⁺; on a metal write `ohmic(V, ['e-'])`.
 - **Ions on both sides of a reacting face.** Label them, `'Li+(left) = Li+(right)'`, and block
   them (`species: { 'Li+': 'blocked' }`) if they cross only by the reaction.
 - **Unit slips.** D in cm²/s, μ° in eV, µF/cm², mS/cm², T in °C. `describe(def)` flags them.
+- **A couple's μ° with the wrong sign** solves happily at −E° for +E°: μ°_red − μ°_ox = −F·E°.
+  Check the rest potential against E°, as the stirred-solution template does.
 - **The library's data are for 25 °C** (its semiconductors for 300 K: give `T: 300`). At body
   temperature the same μ° and D are a fair start; D rises about 2% per kelvin in water.
 - **A steady solve of a closed cell where every ion can cross**: its steady state is complete
@@ -848,6 +648,10 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
 - **A sharp junction between very different solutions** (3 M KCl against 1 µM) can't start:
   grade it over a few thin layers, as at a frit.
 - **Changing `c0` with `set()`.** A carried state keeps what it holds: make a new `Device`.
+- **A charged electrode face beside a strictly neutral solution** (`epsr: 0`, a capacitive face
+  with reactions): refining the grid there makes the kinetics worse, not better, since the edge
+  cell holds the double layer's charge. Read `sol.warnings`; a `zeroCharge` near the rest
+  potential avoids 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'`).
 
@@ -863,9 +667,11 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
   - sources: `pulse`, `square`, `triangle`, `ramp`, `injector`, `recombination`,
     `photogeneration`;
   - channels: `hodgkinHuxley`, `ghkCurrent`;
-  - checking: `describe`, `check`, `polarization` (an electrode's reactions at hypothetical
+  - checking: `describe`, `unitWarnings` (describe's unit slips alone), `check`, `polarization` (an electrode's reactions at hypothetical
     metal levels, with the solution held: an Evans diagram), `henderson` and `planck`
     (liquid-junction potentials);
-  - pages: `live`, `traces`, `recorder`, `particles`;
+  - pages: `live`, `traces` (with `speciesRole` and `typeset` for its labels), `recorder`,
+    `particles`;
   - curated devices: `perovskiteCell`, `PEROVSKITE_SCANS`, `hysteresis`.
-- `driftlet/plot` (a quick look): `bandDiagram`, `levelChart`, `labelParts`, `themeColor`.
+- `driftlet/plot` (a quick look): `bandDiagram`, `levelChart`, `labelParts`, `themeColor`,
+  `THEME`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "driftlet",
-  "version": "0.16.4",
-  "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
+  "version": "1.0.1",
+  "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": {
     ".": {
@@ -42,8 +42,20 @@
   "keywords": [
     "drift-diffusion",
     "poisson-nernst-planck",
-    "electrochemistry",
+    "nernst-planck",
     "semiconductor",
+    "pn-junction",
+    "band-diagram",
+    "solar-cell",
+    "device-simulation",
+    "electrochemistry",
+    "battery",
+    "impedance-spectroscopy",
+    "cyclic-voltammetry",
+    "ion-transport",
+    "membrane-potential",
+    "hodgkin-huxley",
+    "physics",
     "simulation"
   ],
   "homepage": "https://markblundeberg.github.io/driftlet/demos/",

package/src/channels.js

@@ -1,7 +1,7 @@
 // driftlet/kit: voltage-gated channels as plain definition data. Hodgkin and Huxley's squid axon:
 // its gates, and permeabilities for its Na⁺, K⁺ and leak channels, for a membrane face.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 
 const fail = (message) => {
@@ -49,13 +49,15 @@ export function ghkCurrent(z, inside, outside, V, T) {
  * port along a region: links that are their linear conductances, G = g × area per volume, gated the
  * same, each ion's reversal potential following from the port's bath and the concentrations inside
  * (so `inside`, `outside` and `at` aren't needed).
- * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
+ * @param {{ inside: object, outside: object, T: number, g?: { Na?: number, K?: number, leak?: number },
  *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string }, linear?: boolean, area?: number }} opts concentrations in
  *   mol/m³ by species name, K, S/m², V
  * @returns {{ gates: object, species: object }}
  */
-export function hodgkinHuxley({ inside, outside, T = HH_T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {}, linear = false, area } = {}) {
-  need(num(T) && T > 0, `hodgkinHuxley: T must be a temperature in K, got ${T}`);
+export function hodgkinHuxley({ inside, outside, T, g = {}, leak = 'Cl-', leakZ = -1, at = -65 * mV, names = {}, linear = false, area } = {}) {
+  checkOptions('hodgkinHuxley', arguments[0], ['inside', 'outside', 'T', 'g', 'leak', 'leakZ', 'at', 'names', 'linear', 'area']);
+  // T sets the gates' rates, so it must be the device's: never defaulted (their 6.3 °C, under a body-temperature device, doubled a spike's peak, silently).
+  need(num(T) && T > 0, `hodgkinHuxley: T must be the device's temperature in K (their own experiments were at 279.45 K, 6.3 °C), got ${T}`);
   need(num(at), `hodgkinHuxley: at must be a voltage (V), got ${at}`);
   const G = { Na: 1200, K: 360, leak: 3, ...g };
   const Na = names.Na ?? 'Na+', K = names.K ?? 'K+';