driftlet 0.14.0 → 0.16.2

package/llms.txt

@@ -28,9 +28,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.14.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -73,14 +73,15 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at
 - **The library** is pieces with `species` and `materials`: `semiconductor('Si')` (Si, Ge, GaAs, at
   300 K), `aqueous(names)` (H⁺ Li⁺ Na⁺ K⁺ Ag⁺ Cu²⁺ Zn²⁺ Fe²⁺ Fe³⁺ OH⁻ Cl⁻ NO₃⁻ SO₄²⁻ in water, at 25
   °C; `{ epsr: 0 }` makes it strictly neutral, with no double layers), `metal('Ag')` (Ag Cu Au Al Zn
-  Li Pt). A semiconductor's textbook numbers are in `SEMICONDUCTORS.Si` (`Eg` and `chi` in eV, `Nc`
-  and `Nv` in cm⁻³, `mun` and `mup` in cm²/(V·s), `epsr`); in the material, e⁻'s and h⁺'s `cRef` are
-  N_c and N_v in mol/m³ and h⁺'s `mu0` is the gap (e⁻'s is 0), so n_i = √(N_c N_v) e^(−E_g/2RT),
-  6.7e9 cm⁻³ for Si. A species it lacks is pushed into both lists (`z: 0` for a neutral one):
-  `lib.species.push({ name: 'A-', z: -1, cRef: 1000 })`, `lib.materials.water.species['A-'] = { D,
-  mu0 }`. Only μ° differences within a reaction matter: for a redox couple μ°_red − μ°_ox = −F·E°
-  (against SHE, the library's μ°_H⁺ being 0). An insulator is a material with no species: `{
-  species: [], materials: { SiO2: { epsr: 3.9, species: {} } } }`.
+  Li Pt), all from `driftlet/kit`. A semiconductor's textbook numbers are in `SEMICONDUCTORS.Si`
+  (`Eg` and `chi` in eV, `Nc` and `Nv` in cm⁻³, `mun` and `mup` in cm²/(V·s), `epsr`); in the
+  material, e⁻'s and h⁺'s `cRef` are N_c and N_v in mol/m³ and h⁺'s `mu0` is the gap (e⁻'s is 0),
+  so n_i = √(N_c N_v) e^(−E_g/2RT), 6.7e9 cm⁻³ for Si. A species it lacks is pushed into both lists
+  (`z: 0` for a neutral one): `lib.species.push({ name: 'A-', z: -1, cRef: 1000 })`,
+  `lib.materials.water.species['A-'] = { D, mu0 }`. Only μ° differences within a reaction matter:
+  for a redox couple μ°_red − μ°_ox = −F·E° (against SHE, the library's μ°_H⁺ being 0). An
+  insulator is a material with no species: `{ species: [], materials: { SiO2: { epsr: 3.9, species:
+  {} } } }`.
 - **Faces.** Between two different non-metals, give an alignment, `{ dipole }` or `{ step: {
   species: 'e-', value } }` (J/mol), or `phi: 'neutral'`. `vacuumDipole(def, { material, anchor:
   'e-', offset: χ }, …)` estimates a dipole from electron affinities (Anderson's rule); it reads
@@ -111,8 +112,8 @@ 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 })`.
+  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).
 - **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`).
@@ -145,6 +146,14 @@ const tK = D['K+'] / (D['K+'] + D['Cl-']), VT = (GAS_CONSTANT * 298.15) / FARADA
 console.log(`EMF ${(sol.terminals.right.V * 1e3).toFixed(3)} mV, 2t₊V_T ln 10 = ${(2 * tK * VT * Math.log(10) * 1e3).toFixed(3)} mV`); // 58.048, 58.047
 ```
 
+An ion-exchange membrane is a layer whose material has its ions slower, with a `fixedCharge` (−X·F
+for X mol/m³ of fixed anions), between layers of water. A bath against the membrane itself names
+its own material, `bath(c, 'Cl-', 0, { material: 'water' })`, and meets it through a Donnan step.
+An exchange or partition constant between the membrane and the water is a difference of μ°:
+give the membrane's ions μ° shifted from the water's by s_i, and K = e^(−(s_Na − s_H)/RT) for
+Na⁺ against H⁺ (a large K draws in salt too, unless the co-ion's s is raised). The membrane
+demo's page script is a worked example.
+
 ## Template: a semiconductor junction
 
 ```js
@@ -193,9 +202,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.14.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.14.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.16.2/src/plot.js';
 
 const def = build({
   T: 300,
@@ -220,17 +229,15 @@ 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. A friendly first figure for teaching, as long as
-the page says 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 })`. A membrane's permeability (1e-8 m/s) is tiny beside
-D/h in the water (0.02 m/s for 100 nm cells), so an ion beside it hops ~1e6 times per crossing:
-a membrane page shows seas and crossing events, not walking ions.
-The pn demo's page script draws a diode's carriers on its band diagram this way, and the axon
-demo's the ions crossing its membrane (`cap: 0`, every cell a sea, so only the crossings).
+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).
 
 ## Template: a solar cell
 
@@ -263,6 +270,15 @@ 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).
+
 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`
 and `hysteresis(trace, turn)` to read the same figures from yours.
@@ -308,11 +324,14 @@ for (const Vg of [-2, -0.95, 0, 0.4, 2]) {
   console.log(`V_G ${Vg} V: C/C_ox ${(C / Cox).toFixed(3)}`); // 0.949, 0.701 (flat band), 0.267, 0.375, 0.973
 }
 // At flat band the silicon is a capacitor of ε/L_D, its Debye length's.
-const LD = Math.sqrt((11.7 * EPS0 * GAS_CONSTANT * 300) / (FARADAY * FARADAY * NA));
-console.log(`flat band, theory: ${(1 / (1 + (Cox * LD) / (11.7 * EPS0))).toFixed(3)}`); // 0.699
+const LD = Math.sqrt((11.9 * EPS0 * GAS_CONSTANT * 300) / (FARADAY * FARADAY * NA)); // (the kit's Si: ε 11.9)
+console.log(`flat band, theory: ${(1 / (1 + (Cox * LD) / (11.9 * EPS0))).toFixed(3)}`); // 0.701
 ```
 
-`dev.impedance([f], { terminal: 'left' })` gives the same C at low frequency. Draw it with
+`dev.impedance([f], { terminal: 'left' })` (C = Im(1/Z)/ω, from `{ f, Z: { re, im } }`) gives
+the same C at any frequency with the port; without it, only below the minority supply's knee
+(generation, or diffusion from the back contact: 0.01 Hz and below), and the high-frequency C–V
+above. Draw it with
 `bandDiagram(sol, { energy: true, phi: ['SiO2'] })`: across an insulator φ is the line to draw.
 
 ## Template: a Schottky diode
@@ -419,10 +438,12 @@ console.log(level(sol, silver)[mid] - level(sol, SHE, { standard: true })[mid]);
 
 A working electrode, a stagnant layer, and the stirred bulk as a bath whose terminal is its
 reference species (Cl⁻: an Ag/AgCl reference). An electrode's potential against SHE is its
-electrons' V minus φ in the bulk (with the library's μ°). The working electrode's current is
-positive when oxidising. The layer's resistance is in series (uncompensated IR: keep it thin, or
-the supporting salt strong); a 100:1 excess of salt still leaves the limiting current about 1%
-off pure diffusion.
+electrons' V minus φ in the bulk (with the library's μ°), and a Cl⁻ terminal sits ~1.36 V above
+that, so an electrode held at 0 V beside it is strongly anodic: `describe(def)` says where SHE
+sits, and an offset of that much (`bath(c, 'Cl-', 0, { offset })`) makes the terminal read SHE.
+The working electrode's current is positive when oxidising. The layer's resistance is in series
+(uncompensated IR: keep it thin, or the supporting salt strong); a 100:1 excess of salt still
+leaves the limiting current about 1% off pure diffusion.
 
 ```js
 import { Device, GAS_CONSTANT, FARADAY } from 'driftlet';
@@ -665,7 +686,9 @@ capacitance and gated channels to an outside given as a `bath` (the port's V is
 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).
+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';
@@ -710,8 +733,15 @@ species }` (its flux) or `{ interface: f, gate }`.
 
 - **Events.** To stop at one (a cut-off voltage, a diode's storage time), advance in short calls
   and test after each: a driven current held past what the device can pass fails to converge.
-- **Storage.** A device that only stores what comes in (a battery host filling at a current) has
-  no steady state: `advance()` it from its `c0`, don't `solve()` it (docs/statistics.md).
+- **The first instants.** The first step is sized by error control (from 1e-4 of the interval),
+  so a fast start (an initial plateau, a charging spike) can fall inside it: give `dt0` (and
+  `dtMax`) to see it. A voltage step's first point carries the displacement that charges the bulk
+  at once (a spike of ~1e4 A/m² for ~1e-10 s across a cell's Stern layers): leave it out of
+  integrals of I²R.
+- **Storage.** A device that only stores what comes in (a battery host filling at a current, a
+  gate charging) has no steady state: `advance()` it from its `c0`, don't `solve()` it
+  (docs/statistics.md). At no current (`I: 0`), `solve()` keeps the charge it holds: a closed
+  battery sits at the OCV of its state of charge, a floating gate keeps its charge.
 - **Other steps.** `dev.step(dt)` is one backward-Euler step, and `dev.impedance(frequencies,
   { terminal })` the small-signal Z(f) about the steady state, in Ω·m².
 
@@ -803,7 +833,7 @@ What `bandDiagram()` and `traces()` draw, and how to explain it (docs/visualizat
   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.
-- **A gate as a contact on an oxide.** It fails as `'e-' is blocked at this contact`: make the
+- **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.14.0",
+  "version": "0.16.2",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/blockTridiagonal.js

@@ -110,12 +110,17 @@ export class BlockTridiagonal {
       if (i === 0 || sizes[i - 1] === 0) {
         for (let k = 0; k < m * m; k++) lu[o + k] = B[o + k];
       } else {
+        // Row by row, skipping A's zeros (a gate or a local unknown has none to its neighbours):
+        // the same sums, subtracted in the same order.
         const mp = sizes[i - 1], oa = offA[i], op = offC[i - 1]; // C'_{i−1}: mp × m
         for (let r = 0; r < m; r++) {
-          for (let c = 0; c < m; c++) {
-            let s = B[o + r * m + c];
-            for (let k = 0; k < mp; k++) s -= A[oa + r * mp + k] * cp[op + k * m + c];
-            lu[o + r * m + c] = s;
+          const or = o + r * m;
+          for (let c = 0; c < m; c++) lu[or + c] = B[or + c];
+          for (let k = 0; k < mp; k++) {
+            const a = A[oa + r * mp + k];
+            if (a === 0) continue;
+            const ok = op + k * m;
+            for (let c = 0; c < m; c++) lu[or + c] -= a * cp[ok + c];
           }
         }
       }
@@ -130,8 +135,9 @@ export class BlockTridiagonal {
       if (i < n - 1) {
         const mn = sizes[i + 1], oc = offC[i];
         for (let c = 0; c < mn; c++) {
-          for (let r = 0; r < m; r++) tmp[r] = C[oc + r * mn + c];
-          luSolve(lu, o, piv, offX[i], m, tmp);
+          let any = false;
+          for (let r = 0; r < m; r++) if ((tmp[r] = C[oc + r * mn + c]) !== 0) any = true;
+          if (any) luSolve(lu, o, piv, offX[i], m, tmp); // (a zero column stays zero)
           for (let r = 0; r < m; r++) cp[oc + r * mn + c] = tmp[r];
         }
       }

package/src/checks.js

@@ -110,9 +110,12 @@ function balance(device, sol) {
     else ledgers[l].terms.push({ what, rate });
   };
   const last = regions.length - 1;
+  // (A contact that blocks a species is no source of it: what its flux reads there is the end
+  // box's own imbalance, which the ledger must show, not balance.)
+  const through = (side, i) => model.contacts[side].species[i].type !== 'blocked';
   species.forEach((sp, i) => {
-    add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
-    add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
+    if (through('left', i)) add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
+    if (through('right', i)) add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
     model.ports.forEach((port, k) => add(i, port.region, `port ${sol.ports[k].name}`, sol.ports[k].flux[sp.name]));
   });
   model.reactions.forEach((rx, k) => {
@@ -259,8 +262,12 @@ function gridCheck(device, sol, tol, gross) {
   const diffs = [];
   // The current, against the largest current any species carries (so at open circuit, or in
   // equilibrium, round-off isn't read as a change).
-  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross);
-  if (gross > 0) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: unitsOf(model).current });
+  // A current too small for the ledgers to call moving (a diode at low bias: 1e-4 A/m² against
+  // majority carriers that could carry 6e8) is compared still, above a floor at 1e-16 of what the
+  // species could carry, above what solves resolve (~1e-19 of it in a GaAs junction).
+  const natural = naturalScales(device, sol), floorI = 1e-16 * FARADAY * Math.max(0, ...model.species.map((sp, i) => Math.abs(sp.z) * natural[i]).filter(Number.isFinite));
+  const scaleI = Math.max(Math.abs(sol.current), Math.abs(other.current), gross, floorI);
+  if (gross > 0 || Math.max(Math.abs(sol.current), Math.abs(other.current)) > floorI) diffs.push({ what: 'current', a: sol.current, b: other.current, rel: Math.abs(other.current - sol.current) / scaleI, unit: unitsOf(model).current });
   // Floating terminals (driven by a current): their voltages, against the larger and the thermal voltage.
   const VT = model.RT / FARADAY;
   model.terminals.forEach((t, k) => {

package/src/describe.js

@@ -49,6 +49,10 @@ export function unitWarnings(def) {
     if (c > 1e6) warn(path, `${num(c)} mol/m³ is over 1000 M; concentrations are mol/m³ (units.molar, and units.perCm3 for carriers)`);
   };
   (def.species ?? []).forEach((sp, i) => sp?.cRef !== undefined && conc(`species[${i}].cRef`, sp.cRef));
+  // SRH's n₁ is a concentration too (a value per cm³ typed in is 6e5 times too large)
+  (def.bulkReactions ?? []).forEach((rx, k) => {
+    for (const [m, law] of Object.entries(isObject(rx?.srh) ? rx.srh : {})) if (isObject(law) && law.n1 !== undefined) conc(`bulkReactions[${k}].srh.${m}.n1`, law.n1);
+  });
   for (const [mname, mat] of Object.entries(def.materials ?? {})) {
     if (!isObject(mat)) continue;
     const path = `materials.${mname}`;
@@ -92,13 +96,19 @@ export function unitWarnings(def) {
   };
   const kinetics = (path, reactions) => {
     (reactions ?? []).forEach((rx, k) => {
-      if (rx?.k0 > 10) warn(`${path}.reactions[${k}].k0`, `${num(rx.k0)} mol/(m²·s) is an exchange current of ${num(rx.k0 * FARADAY)} A/m² per electron; k0 is mol/(m²·s)`);
+      // (an exchange current only where electrons take part: an ion transfer's k0 can be large)
+      const said = rx?.equation ?? (rx?.left || rx?.right ? JSON.stringify([rx.left, rx.right]) : null);
+      const electrons = said === null || /(^|[^\w])e-($|[^\w])/.test(said);
+      if (rx?.k0 > 10 && electrons) warn(`${path}.reactions[${k}].k0`, `${num(rx.k0)} mol/(m²·s) is an exchange current of ${num(rx.k0 * FARADAY)} A/m² per electron; k0 is mol/(m²·s)`);
     });
   };
   (def.interfaces ?? []).forEach((f, k) => {
     if (!isObject(f)) return;
     capacitance(`interfaces[${k}].phi.C`, f.phi?.C);
-    kinetics(`interfaces[${k}]`, f.reactions);
+    // (an exchange current is an electrode's: a metal on one side, or sides not yet known; a
+    // splitting exciton's k0, between two semiconductors, is a velocity times cRef)
+    const sides = [def.regions?.[k], def.regions?.[k + 1]].map((r) => (isObject(r) ? def.materials?.[r.material] : undefined));
+    if (sides.some((m) => m === undefined || isObject(m?.conductor))) kinetics(`interfaces[${k}]`, f.reactions);
   });
   (def.ports ?? []).forEach((p, k) => {
     if (!isObject(p)) return;
@@ -149,7 +159,12 @@ export function describe(def) {
       return;
     }
     const parts = [mat.epsr > 0 ? `εr ${mat.epsr}` : 'strictly neutral (ε = 0)'];
-    if (reg.fixedCharge !== 0) parts.push(`fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(Math.abs(reg.fixedCharge) / FARADAY)}`);
+    // (donors and acceptors where there are electrons; an ion exchanger's charge in mol/m³)
+    const doped = species.some((sp, i) => mat.present[i] && (sp.name === 'e-' || sp.name === 'h+'));
+    if (reg.fixedCharge !== 0) {
+      const X = Math.abs(reg.fixedCharge) / FARADAY;
+      parts.push(doped ? `fixed charge ${reg.fixedCharge > 0 ? 'donor-like' : 'acceptor-like'} ${perCm3(X)}` : `fixed charge ${reg.fixedCharge > 0 ? '+' : '−'}${num(X)} mol/m³`);
+    }
     // The screening concentration: Σ z²c from the initial composition, plus the carriers that
     // balance the fixed charge (doping), which c0 doesn't list.
     let zzc = 0, q = reg.fixedCharge / FARADAY; // q: the charge c0 leaves unbalanced
@@ -216,8 +231,34 @@ export function describe(def) {
     const cdef = def.contacts?.[side];
     const ct = model.contacts[side];
     const linked = species.filter((sp, i) => ct.species[i].type !== 'blocked').map((sp) => sp.name);
-    const term = ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
-    lines.push(`  ${side}: ${drive(cdef, model.geometry.type === 'planar')}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
+    // (a bath without a reference species: its V is its φ)
+    const term = ct.she && !ct.she.reference ? ' (terminal: the bath φ)' : ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
+    // A bath read through a reference species: where the SHE level sits against its terminal,
+    // so a held electrode's V reads on the familiar scale (a Cl⁻ reference on table μ° puts it
+    // 1.37 V below, a surprise to anyone expecting 0 V to mean SHE).
+    let she = '';
+    if (ct.she?.reference) {
+      const d = ct.she.shift, at = Math.abs(d) < 5e-4 ? 'V' : `V ${d < 0 ? '−' : '+'} ${Math.abs(d).toFixed(3)} V`;
+      she = ct.she.exact ? `; the bath's SHE level is at ${at}` : `; the bath's φ is at ${at} (on the usual tables' μ°, where μ°_H⁺ = 0, that's its SHE level)`;
+    }
+    lines.push(`  ${side}: ${drive(cdef, model.geometry.type === 'planar')}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}${she}`);
+    // An outside phase out of equilibrium with a reaction that runs at the contact: the reaction
+    // then runs there for ever, a current at zero bias (H⁺ and OH⁻ given off Kw in a bath, say).
+    const end = regions[side === 'left' ? 0 : regions.length - 1].material;
+    model.reactions.forEach((rx, k) => {
+      if (!(rx.kf[end] > 0) || rx.kfProfile[end]) return; // (light, a profile, is meant to drive)
+      const parts = [...rx.reactants.map(({ i, nu }) => [i, -nu]), ...rx.products.map(({ i, nu }) => [i, nu])];
+      const level = (i) => {
+        const l = ct.species[i];
+        return l.type !== 'equilibrium' ? NaN : species[i].z === 0 ? l.mu : l.offset === undefined ? NaN : species[i].z * FARADAY * l.offset;
+      };
+      // A/RT from the outside's levels (the terminal voltage cancels: Σ ν z = 0)
+      const a = rx.fixedA - parts.reduce((sum, [i, nu]) => sum + nu * level(i), 0) / RT;
+      if (Math.abs(a) > 1e-3) {
+        const rdef = def.bulkReactions[k];
+        warnings.push(`contacts.${side}: the outside isn't in equilibrium with bulkReactions[${k}] (${rdef.equation ?? equation(rdef.nu)}; A = ${num(a)} RT there), so it runs at the contact for ever, a current even at zero bias. Unless that's meant (a source), give the outside a composition in equilibrium with it (H⁺ and OH⁻ at √K_w, say)`);
+      }
+    });
   }
   (def.ports ?? []).forEach((p, k) => {
     const port = model.ports[k];

package/src/device.js

@@ -219,9 +219,12 @@ export function normalizeDevice(def) {
   const outside = (sp) => (def.ports ?? []).some((p) => p?.terminal === sp.name && Array.isArray(p.reactions) && p.reactions.length > 0);
   species.forEach((sp, i) => {
     const reacting = (def.ports ?? []).some((p) => Array.isArray(p?.reactions) && p.reactions.length > 0);
+    // (a port naming it as its terminal without reactions: a capacitance alone needs none)
+    const named = (def.ports ?? []).find((p) => p?.terminal === sp.name);
     need(
       materials.some((m) => m.present[i]) || outside(sp),
-      `species '${sp.name}' is not present in any material` + (reacting ? " (an electrode's carrier can instead be a reacting port's terminal)" : ''),
+      `species '${sp.name}' is not present in any material` +
+        (named ? `: it is the terminal of port ${JSON.stringify(named.name ?? '')}, which can hold a carrier from outside the device only with reactions. A port with only a capacitance needs no terminal: drop it (and the species)` : reacting ? " (an electrode's carrier can instead be a reacting port's terminal)" : ''),
     );
   });
 
@@ -1158,8 +1161,10 @@ function normalizeConductorInterface(idef, where, matL, matR, species, speciesIn
   return { phi, dipole: 0, zeroCharge, sheetCharge: 0, links, reactions, gates: [], conductor: { side, i: metal.i } };
 }
 
+// A species present on both sides crosses freely; one that can't move on either (D = 0, trap
+// states, say) is blocked: held level, its two edge boxes would pass whatever flux that takes.
 function defaultInterfaceLinks(matL, matR, species) {
-  return species.map((_, i) => ({ type: matL.present[i] && matR.present[i] ? 'equilibrium' : 'blocked' }));
+  return species.map((_, i) => ({ type: matL.present[i] && matR.present[i] && (matL.D[i] > 0 || matR.D[i] > 0) ? 'equilibrium' : 'blocked' }));
 }
 
 function transferCoefficient(v, path) {
@@ -1197,6 +1202,7 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
   const links = species.map(() => ({ type: 'blocked' }));
   let phi = { type: 'neutral' };
   let terminal = null;
+  let she = null; // a bath's SHE level against V
   if (cdef === undefined || cdef === null) return { drive: normalizeDrive({}, path), species: links, phi, terminal };
   need(isObject(cdef), `${path} must be an object`);
   fields(cdef, path, ['V', 'I', 'R', 'terminal', 'species', 'bath', 'phi', 'zeroCharge']);
@@ -1274,7 +1280,13 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     need(cdef.species === undefined, `${path}: give either bath or species links, not both`);
     const bath = cdef.bath;
     need(isObject(bath) && isObject(bath.c), `${path}.bath must be { c: { species: concentration }, reference }`);
-    fields(bath, `${path}.bath`, ['c', 'reference', 'offset']);
+    fields(bath, `${path}.bath`, ['c', 'reference', 'offset', 'material']);
+    // The bath is the end material at that composition (balancing any fixed charge there), unless
+    // it names a material of its own: a solution outside an ion exchanger, a doped or host region,
+    // whose levels it sets there through a Donnan step at the end node.
+    const own = bath.material !== undefined;
+    const bm = own ? materials.find((m) => m.name === bath.material) : mat;
+    need(bm && !bm.conductor && !bm.phiFree, `${path}.bath.material: ${JSON.stringify(bath.material)} is not a material with ions in it (one of ${materials.filter((m) => !m.conductor).map((m) => m.name).join(', ')})`);
     // Without a reference, V is the bath's φ (an ideal salt bridge: the membrane potential's
     // convention), and the terminal is the first charged species in it.
     const byPhi = bath.reference === undefined;
@@ -1288,24 +1300,35 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
     need(bath.c[species[r].name] !== undefined, `${path}.bath.reference: '${bath.reference}' must be in the bath`);
     need(byPhi || cdef.terminal === undefined || terminal === r, `${path}.terminal must be the bath's reference species`);
     terminal = byPhi && terminal !== null ? terminal : r;
-    let charge = region.fixedCharge / FARADAY, scale = Math.abs(charge);
+    const fixed = own ? 0 : region.fixedCharge / FARADAY;
+    let charge = fixed, scale = Math.abs(charge);
     const cb = new Float64Array(species.length);
     for (const [sname, v] of Object.entries(bath.c)) {
       need(speciesIndex.has(sname), `${path}.bath.c.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
       const i = speciesIndex.get(sname);
-      need(mat.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from the end material '${mat.name}'`);
+      need(bm.present[i], `${path}.bath.c.${sname}: '${sname}' is absent from ${own ? 'the bath' : 'the end'} material '${bm.name}'`);
       cb[i] = positive(v, `${path}.bath.c.${sname}`);
       charge += species[i].z * cb[i];
       scale += Math.abs(species[i].z) * cb[i];
     }
-    need(Math.abs(charge) <= 1e-9 * scale, `${path}.bath: composition is not neutral (net ${charge} mol/m³ of charge)`);
+    need(
+      Math.abs(charge) <= 1e-9 * scale,
+      fixed !== 0
+        ? `${path}.bath: the bath is the end material '${mat.name}' at this composition, and with its fixed charge (${fixed} mol/m³ of charge) it is not neutral (net ${charge}). ` +
+            `For a solution outside a charged region, give the solution's material (bath.material), whose composition is then neutral on its own`
+        : `${path}.bath: composition is not neutral (net ${charge} mol/m³ of charge)`,
+    );
     // The reference species pins the bath's φ; every other species follows from composition.
-    const zb = bathZeta(mat, cb, region.background);
-    const level = (i) => mat.mu0[i] + RT * zb[i]; // μ̄ − zFφ_bath
+    const zb = bathZeta(bm, cb, own ? 0 : region.background);
+    const level = (i) => bm.mu0[i] + RT * zb[i]; // μ̄ − zFφ_bath
     const refOffset = bath.offset === undefined ? 0 : finite(bath.offset, `${path}.bath.offset`);
     const beta = byPhi ? 0 : refOffset - level(r) / (species[r].z * FARADAY); // φ_bath − V
+    // Where the bath's SHE level sits against V (for describe()): φ + μ°_H⁺/F with H⁺ in the
+    // bath, else φ on the usual tables' convention (μ°_H⁺ = 0), which then is only a reading.
+    const h = speciesIndex.get('H+');
+    she = { shift: beta + (h !== undefined && bm.present[h] ? bm.mu0[h] / FARADAY : 0), exact: h !== undefined && bm.present[h], reference: !byPhi };
     for (let i = 0; i < species.length; i++) {
-      if (!(cb[i] > 0)) continue;
+      if (!(cb[i] > 0) || !mat.present[i]) continue; // (a bath of its own may hold species the end lacks)
       links[i] =
         species[i].z === 0
           ? { type: 'equilibrium', mu: level(i) }
@@ -1343,5 +1366,5 @@ function normalizeContact(cdef, side, region, materials, species, speciesIndex,
   if (terminal !== null) {
     need(links[terminal].type !== 'blocked', `${path}.terminal: '${species[terminal].name}' is blocked at this contact`);
   }
-  return { drive, species: links, phi, terminal };
+  return { drive, species: links, phi, terminal, ...(she ? { she } : {}) };
 }

package/src/index.js

@@ -106,15 +106,27 @@ export class Device {
     this.def = def;
     this.model = model;
     this._solver = solver;
-    if (old && old.u.length === solver.u.length && old.n === solver.n) {
-      solver.u.set(old.u);
-      solver.uLo.set(old.uLo);
-      // A node newly on an electrode's surface (a window moved, a surface added) starts at its
-      // starting coverages, not at whatever its slots held.
-      const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
-      for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
+    // The state carries over where the unknowns line up; on a new grid (the same regions, faces
+    // and terminals), interpolated onto it. (Started cold instead, a floating gate lost its
+    // charge to a refined grid.)
+    const sameUnknowns = old && old.u.length === solver.u.length && old.n === solver.n;
+    const regridded = old && !sameUnknowns && old.M === solver.M && old.n === solver.n && old.nFaces === solver.nFaces && old.terms.length === solver.terms.length && old.model.grid.regionStart.length === model.grid.regionStart.length;
+    if (sameUnknowns || regridded) {
+      if (sameUnknowns) {
+        solver.u.set(old.u);
+        solver.uLo.set(old.uLo);
+        // A node newly on an electrode's surface (a window moved, a surface added) starts at its
+        // starting coverages, not at whatever its slots held.
+        const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
+        for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
+      } else solver._warmFrom(old);
       solver.computeConcentrations();
       solver.time = old.time;
+      // Held sources read at the same time as before, and an adaptive transient goes on at the
+      // step size it had reached (its order restarts, as at any change of the equations).
+      solver.sourceTime = old.sourceTime;
+      solver._refreshSources();
+      solver.dtNext = old.dtNext;
       solver.contactDEnd = old.contactDEnd;
       if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)