driftlet 0.13.0 → 0.16.2

package/package.json

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

@@ -29,7 +29,8 @@ const sig = (v, p = 3) => (v === 0 || !Number.isFinite(v) ? String(v) : Math.abs
  *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
- * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
+ *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
  *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
  *   wants less). The discretisation is second order, so the change estimates this grid's error
@@ -67,6 +68,9 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
     const ledger = steady ? balance(device, sol) : null;
     items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
+    // A transient's answer depends on its whole history (and on drives set along the way), so
+    // only a run of its own on a finer grid can check it.
+    else if (refine) items.push({ name: 'grid', ok: null, summary: 'not checked in a transient: run it again on a grid twice as fine (hmin and hmax halved) and compare' });
   }
 
   const ok = sol.converged && items.every((it) => it.ok !== false);
@@ -106,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) => {
@@ -255,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

@@ -56,6 +56,49 @@ function positive(v, path) {
   return v;
 }
 
+// Where a region's nodes miss a starting profile worst: the profile at each of its points
+// against the line between the nodes either side, as a fraction of its range over the region
+// (the start is the profile sampled at the nodes). Empty where they miss it by under 2%.
+function unresolved(p, grid, r) {
+  const at = (t) => {
+    const { x, values: v } = p, last = x.length - 1;
+    if (t <= x[0]) return v[0];
+    if (t >= x[last]) return v[last];
+    let k = 0;
+    while (x[k + 1] < t) k++;
+    return v[k] + ((v[k + 1] - v[k]) * (t - x[k])) / (x[k + 1] - x[k]);
+  };
+  const g0 = grid.regionStart[r], g1 = grid.regionEnd[r], a = grid.x[g0], b = grid.x[g1];
+  let lo = Math.min(at(a), at(b)), hi = Math.max(at(a), at(b));
+  p.x.forEach((t, k) => {
+    if (t > a && t < b) (lo = Math.min(lo, p.values[k])), (hi = Math.max(hi, p.values[k]));
+  });
+  if (!(hi > lo)) return {};
+  const missAt = (t, xl, xr) => {
+    const cl = at(xl), cr = at(xr);
+    return Math.abs(at(t) - (cl + ((cr - cl) * (t - xl)) / (xr - xl))) / (hi - lo);
+  };
+  let worst = {}, g = g0;
+  p.x.forEach((t) => {
+    if (!(t > a && t < b)) return;
+    while (grid.x[g + 1] < t) g++;
+    const off = missAt(t, grid.x[g], grid.x[g + 1]);
+    if (off > 0.02 && !(off <= worst.off)) worst = { x: t, h: grid.x[g + 1] - grid.x[g], off };
+  });
+  if (!worst.off) return worst;
+  // The cells that would resolve it there: uniform ones, finer until they miss it by under 2%
+  // however they fall on it. (Cells wider than a step miss it by about as much at any size, so
+  // the miss isn't extrapolated.)
+  const near = Array.from(p.x).filter((t) => Math.abs(t - worst.x) <= 5 * worst.h);
+  const misses = (h) => Math.max(...[0, 0.25, 0.5, 0.75].flatMap((f) => near.map((t) => {
+    const xl = worst.x + h * (Math.floor((t - worst.x) / h - f) + f);
+    return missAt(t, xl, xl + h);
+  })));
+  worst.want = worst.h / 2;
+  while (misses(worst.want) > 0.02 && worst.want > worst.h * 1e-3) worst.want /= Math.SQRT2;
+  return worst;
+}
+
 // A profile against the device's x: { x, values }, piecewise linear between its points and
 // constant beyond its ends (read with profileAt).
 function profile(v, path, what, ok, okText) {
@@ -176,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)" : ''),
     );
   });
 
@@ -326,6 +372,18 @@ export function normalizeDevice(def) {
   } catch (err) {
     throw new DeviceError(`grid: ${err.message}`);
   }
+  // A starting profile steeper than the cells under it starts as something else, silently: a
+  // liquid junction's potential then looks as if it grows while the junction forms.
+  regions.forEach((reg, r) => {
+    const missed = reg.c0Profile.map((p, i) => p && { i, ...unresolved(p, grid, r) }).filter((m) => m && m.off);
+    if (missed.length === 0) return;
+    const miss = missed.reduce((a, m) => (m.off > a.off ? m : a));
+    warnings.push(
+      `regions[${r}].c0 (${missed.map((m) => species[m.i].name).join(', ')}): the grid doesn't resolve the starting profile ` +
+        `(at x = ${miss.x.toExponential(2)} m, nodes ${miss.h.toExponential(1)} m apart miss it by ${Math.round(100 * miss.off)}% of its range), ` +
+        `so the start isn't the one given; cells of about ${miss.want.toExponential(0)} m there would resolve it (hmax, or a region boundary there to grade toward)`,
+    );
+  });
   const geometry = normalizeGeometry(def.geometry);
   if (geometry.type !== 'planar') {
     regions.forEach((reg, r) => need(reg.velocity === 0, `regions[${r}].velocity: flow is for a planar device (a uniform velocity through a varying cross-section wouldn't conserve the liquid)`));
@@ -1103,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) {
@@ -1142,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']);
@@ -1219,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;
@@ -1233,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) }
@@ -1288,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)

package/src/kit.js

@@ -15,6 +15,7 @@ export { describe, unitWarnings } from './describe.js';
 export { recorder } from './recorder.js';
 export { henderson, planck } from './junction.js';
 export { check } from './checks.js';
+export { particles } from './particles.js';
 export { polarization } from './polarization.js';
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from './devices.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';