driftlet 0.14.0 → 0.16.2

package/src/particles.js

@@ -47,53 +47,72 @@ const NONE = 0, DOT = 1, OUTSIDE = 2; // nothing (closed); a cell of dots; a sea
  * @param {number} [opts.dots] about how many dots per species (default 200), for the default weight
  * @param {number|object} [opts.weight] amount per dot, mol/m²: one number for every species (so
  *   their dots compare), or { name: weight }; default, each species' total over `dots`
- * @param {number} [opts.cap] the most dots a cell holds on average before it's a sea (default ∞)
+ * @param {number} [opts.cap] the most dots a cell of the asked-for width holds on average before
+ *   it's a sea (a density: a wider cell holds more; default ∞)
  * @param {number} [opts.cells] about how many cells across the device (default 120)
  * @param {() => number} [opts.random] a uniform random source in [0, 1) (default Math.random)
  */
 export function particles(sol, { species, dots = 200, weight, cap = Infinity, cells = 120, random = Math.random } = {}) {
   const names = species ?? sol.species.map((s) => s.name).filter((nm) => sol.c[nm].some((v) => v > 0));
-  const nn = sol.x.length, x = sol.x;
+  for (const nm of names) if (!sol.c[nm]) throw new RangeError(`particles: no species ${JSON.stringify(nm)} in the solution`);
+  if (!(dots > 0 && Number.isFinite(dots))) throw new RangeError(`particles: dots must be a positive number, got ${dots}`);
+  if (!(cells >= 1 && Number.isFinite(cells))) throw new RangeError(`particles: cells must be a number from 1 up, got ${cells}`);
+  if (!(cap >= 0)) throw new RangeError(`particles: cap must be a number from 0 up, got ${cap}`);
+  const MAX = 1e6; // the most dots a swarm will draw
 
   // The lattice: each region's nodes grouped into runs of node boxes about L/cells wide, so a
   // cell boundary is a segment, where the solution's flux is. (A metal's nodes, with no
-  // concentration, are left out.)
-  const box = Float64Array.from(x, (_, g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? x[g] - x[g - 1] : 0) + (g < nn - 1 && sol.region[g + 1] === sol.region[g] ? x[g + 1] - x[g] : 0)) / 2);
-  const target = (x[nn - 1] - x[0]) / cells;
-  const lattice = [];
-  sol.regions.forEach((_, r) => {
-    const g0 = sol.region.indexOf(r), g1 = sol.region.lastIndexOf(r);
-    if (names.every((nm) => !(sol.c[nm][g0] >= 0))) return;
-    const start = lattice.length;
-    let a = g0, w = 0;
-    for (let g = g0; g <= g1; g++) {
-      w += box[g];
-      if (w >= target || g === g1) {
-        lattice.push({ a, b: g, region: r, h: w });
-        [a, w] = [g + 1, 0];
+  // concentration, are left out.) Drawn again for a solution on another grid.
+  let x, nn, box, lattice, nc, at, target;
+  function draw(sol) {
+    x = Float64Array.from(sol.x);
+    nn = x.length;
+    box = Float64Array.from(x, (_, g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? x[g] - x[g - 1] : 0) + (g < nn - 1 && sol.region[g + 1] === sol.region[g] ? x[g + 1] - x[g] : 0)) / 2);
+    target = (x[nn - 1] - x[0]) / cells;
+    lattice = [];
+    sol.regions.forEach((_, r) => {
+      const g0 = sol.region.indexOf(r), g1 = sol.region.lastIndexOf(r);
+      if (names.every((nm) => !(sol.c[nm][g0] >= 0))) return;
+      const start = lattice.length;
+      let a = g0, w = 0;
+      for (let g = g0; g <= g1; g++) {
+        w += box[g];
+        // a run ends where one more node's box would take it farther from the target width
+        if (g === g1 || w + box[g + 1] - target > target - w) {
+          lattice.push({ a, b: g, region: r, h: w });
+          [a, w] = [g + 1, 0];
+        }
       }
+      const last = lattice.length - 1;
+      if (last > start && lattice[last].h < target / 2) {
+        // a thin last cell joins the one before it
+        lattice[last - 1].b = lattice[last].b;
+        lattice[last - 1].h += lattice[last].h;
+        lattice.pop();
+      }
+    });
+    for (const cl of lattice) {
+      cl.x0 = x[cl.a] - (cl.a > 0 && sol.region[cl.a - 1] === cl.region ? (x[cl.a] - x[cl.a - 1]) / 2 : 0);
+      cl.x1 = cl.x0 + cl.h;
+      let mid = cl.a;
+      for (let g = cl.a; g <= cl.b; g++) if (Math.abs(x[g] - (cl.x0 + cl.x1) / 2) < Math.abs(x[mid] - (cl.x0 + cl.x1) / 2)) mid = g;
+      cl.mid = mid;
     }
-    const last = lattice.length - 1;
-    if (last > start && lattice[last].h < target / 2) {
-      // a thin last cell joins the one before it
-      lattice[last - 1].b = lattice[last].b;
-      lattice[last - 1].h += lattice[last].h;
-      lattice.pop();
-    }
-  });
-  for (const cl of lattice) {
-    cl.x0 = x[cl.a] - (cl.a > 0 && sol.region[cl.a - 1] === cl.region ? (x[cl.a] - x[cl.a - 1]) / 2 : 0);
-    cl.x1 = cl.x0 + cl.h;
-    let mid = cl.a;
-    for (let g = cl.a; g <= cl.b; g++) if (Math.abs(x[g] - (cl.x0 + cl.x1) / 2) < Math.abs(x[mid] - (cl.x0 + cl.x1) / 2)) mid = g;
-    cl.mid = mid;
+    nc = lattice.length;
+    // where each boundary is: k between cells k − 1 and k
+    at = Float64Array.from({ length: nc + 1 }, (_, k) => (k < nc ? lattice[k].x0 : lattice[nc - 1].x1));
+    swarm.cells = lattice.map(({ x0, x1, region }) => ({ x0, x1, region }));
+    swarm.dots = [];
+    for (const nm of names) swarm.crossed[nm] = { up: new Float64Array(nc + 1), down: new Float64Array(nc + 1) };
+    for (const nm of names) delete S[nm];
   }
-  const nc = lattice.length;
-  // where each boundary is: k between cells k − 1 and k
-  const at = Float64Array.from({ length: nc + 1 }, (_, k) => (k < nc ? lattice[k].x0 : lattice[nc - 1].x1));
+  // A sea where a cell would hold more than cap dots for each target width it spans: a density,
+  // so a wider cell among the rest doesn't become a sea alone.
+  const dense = (m, K) => m > (cap * lattice[K].h) / target;
+  const sameGrid = (s) => s.x.length === nn && s.x.every((v, g) => v === x[g]);
 
   const swarm = {
-    cells: lattice.map(({ x0, x1, region }) => ({ x0, x1, region })),
+    cells: [],
     species: names,
     weight: {}, // mol/m² per dot
     sea: {}, // per species, per cell: 1 where it's a sea
@@ -123,7 +142,7 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
     const c = sol.c[nm], mu = sol.mu[nm], D = sol.D[nm], J = sol.flux[nm], RT = GAS_CONSTANT * sol.T;
     const N = amounts(sol, nm), w = swarm.weight[nm];
     const on = Uint8Array.from(lattice, (cl) => (c[cl.mid] >= 0 ? 1 : 0));
-    const sea = Uint8Array.from(N, (n, K) => (on[K] && n / w > cap ? 1 : 0));
+    const sea = Uint8Array.from(N, (n, K) => (on[K] && dense(n / w, K) ? 1 : 0));
     const psi = Float64Array.from(lattice, (cl, K) => mu[cl.mid] / RT - Math.log(N[K] / cl.h));
     // Boundary k: what lies to each side, its one-way fluxes (mol/(m²·s)), and whether it's a face
     // with one-way fluxes of its own (a membrane), whose crossings between seas are events.
@@ -193,7 +212,9 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
       if (rest > 0) made[K] += rest;
       else unmade[K] -= rest;
     }
-    return { N, on, sea, left, right, face, up, down, made, unmade, time: sol.time };
+    // Where in a cell a dot sits: in a node's box, chosen by its share of the cell's amount.
+    const share = Float64Array.from(x, (_, g) => (c[g] > 0 ? c[g] * box[g] : 0));
+    return { N, on, sea, left, right, face, up, down, made, unmade, share, time: sol.time };
   }
 
   /**
@@ -202,10 +223,17 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
    * steady states, which has no path in time to follow), each cell's dots are thinned or added to
    * by the change in what it's expected to hold, m → m′: each kept with probability m′/m if it
    * falls, Poisson(m′ − m) more if it rises, which takes a Poisson sample of the one into a
-   * Poisson sample of the other, moving as few dots as can be.
+   * Poisson sample of the other, moving as few dots as can be. A solution on another grid (a
+   * resized device) redraws the lattice, and the dots are placed afresh.
    */
   function update(next, { resample = false } = {}) {
+    if (!next?.x || !next.c) throw new TypeError('particles: update takes a solution');
+    for (const nm of names) if (!next.c[nm]) throw new RangeError(`particles: the new solution has no species ${JSON.stringify(nm)}`);
     sol = next;
+    if (!sameGrid(sol)) draw(sol); // (a resized device: the dots placed afresh)
+    let total = 0;
+    for (const nm of names) total += amounts(sol, nm).reduce((a, n, K) => a + (dense(n / swarm.weight[nm], K) ? 0 : n), 0) / swarm.weight[nm];
+    if (total > MAX) throw new RangeError(`particles: this would draw ${total.toPrecision(2)} dots; give a larger weight, or a cap (dense cells as seas)`);
     for (const nm of names) {
       const was = S[nm];
       S[nm] = fields(sol, nm, was);
@@ -229,10 +257,23 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
 
   /** The dots expected in each cell for a species, at the solution's concentrations. */
   function expected(nm) {
+    if (!S[nm]) throw new RangeError(`particles: no species ${JSON.stringify(nm)} in this swarm (${names.join(', ')})`);
     return Float64Array.from(S[nm].N, (n) => n / swarm.weight[nm]);
   }
 
-  const dot = (nm, K) => ({ species: nm, cell: K, x: lattice[K].x0 + random() * lattice[K].h });
+  // A place in cell K for a dot of species nm: a node's box, by its share of the amount, then
+  // anywhere in that box. (A dot follows the profile within its cell, as at a depletion edge.)
+  function place(nm, K) {
+    const cl = lattice[K], share = S[nm]?.share;
+    let g = cl.a;
+    if (share && S[nm].N[K] > 0) {
+      let u = random() * S[nm].N[K];
+      while (g < cl.b && (u -= share[g]) > 0) g++;
+    } else return cl.x0 + random() * cl.h;
+    const lo = g > cl.a ? (x[g - 1] + x[g]) / 2 : cl.x0, hi = g < cl.b ? (x[g] + x[g + 1]) / 2 : cl.x1;
+    return lo + random() * (hi - lo);
+  }
+  const dot = (nm, K) => ({ species: nm, cell: K, x: place(nm, K) });
 
   // A Poisson count of mean m (a normal one for large m).
   const gauss = () => Math.sqrt(-2 * Math.log(1 - random())) * Math.cos(2 * Math.PI * random());
@@ -246,13 +287,36 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
 
   /**
    * Move the dots on by dt (s, the device's time): each hops, and dots are made and unmade, at
-   * the solution's rates. A dot hops at most maxHops times in a step.
+   * the solution's rates. A cell a dot would hop out of more than maxHops/4 times in the step is
+   * a sea for the step (whatever crosses its sides counted at the one-way fluxes, dots walking in
+   * absorbed), then drawn afresh, a new sample of what it holds: so a step much longer than the
+   * hop time costs little, and stays a sample of the solution. A dt that's NaN or negative (a
+   * first frame, a clock that stepped back) moves nothing.
    */
   function step(dt, { maxHops = 200 } = {}) {
+    // (A first frame or a clock stepping back, NaN or negative, moves nothing.)
     swarm.events = [];
+    if (dt === Infinity) throw new RangeError('particles: step(dt) takes a finite time (s), got Infinity');
+    if (!(dt > 0)) return swarm;
+    const fast = {}, saved = {};
+    for (const nm of names) {
+      const F = S[nm];
+      fast[nm] = Uint8Array.from(F.N, (N, K) => {
+        if (!F.on[K] || F.sea[K] || !(N > 0)) return 0;
+        const rate = ((F.right[K + 1] ? F.up[K + 1] : 0) + (F.left[K] ? F.down[K] : 0) + F.unmade[K]) / N;
+        return rate * dt > maxHops / 4 ? 1 : 0;
+      });
+      if (!fast[nm].some(Boolean)) continue;
+      // For this step, those cells are seas.
+      saved[nm] = [F.sea, F.left, F.right];
+      F.sea = Uint8Array.from(F.sea, (v, K) => v | fast[nm][K]);
+      F.left = Uint8Array.from(F.left, (v, k) => (v && k > 0 && fast[nm][k - 1] ? OUTSIDE : v));
+      F.right = Uint8Array.from(F.right, (v, k) => (v && k < nc && fast[nm][k] ? OUTSIDE : v));
+    }
     // Births first, each at a random moment of the step: made in a cell, or arriving from beyond
     // (a sea, a contact, a metal). Each then moves for the rest of the step. And crossings
-    // between seas through a face.
+    // between seas: through a face, as events; between cells that are seas only for this step,
+    // counted.
     const born = [];
     for (const nm of names) {
       const F = S[nm], w = swarm.weight[nm], cr = swarm.crossed[nm];
@@ -264,36 +328,46 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
         if (!(rate > 0)) continue;
         for (let j = poisson(rate * dt); j > 0; j--) {
           const u = random() * rate, d = dot(nm, K);
+          // (no 'in' from a cell that's a sea only for this step)
           if (u < fromLeft) {
             cr.up[K]++;
-            swarm.events.push({ species: nm, kind: 'in', x: at[K], dir: 1 });
+            if (!fast[nm][K - 1]) swarm.events.push({ species: nm, kind: 'in', x: at[K], dir: 1 });
           } else if (u < fromLeft + fromRight) {
             cr.down[K + 1]++;
-            swarm.events.push({ species: nm, kind: 'in', x: at[K + 1], dir: -1 });
+            if (!fast[nm][K + 1]) swarm.events.push({ species: nm, kind: 'in', x: at[K + 1], dir: -1 });
           } else swarm.events.push({ species: nm, kind: 'made', x: d.x });
           born.push([d, random() * dt]);
         }
       }
       for (let k = 0; k <= nc; k++) {
-        if (!F.face[k] || F.left[k] !== OUTSIDE || F.right[k] !== OUTSIDE) continue;
+        if (F.left[k] !== OUTSIDE || F.right[k] !== OUTSIDE) continue;
+        const events = F.face[k] && !(fast[nm][k - 1] || fast[nm][k]);
+        if (!events && !(fast[nm][k - 1] || fast[nm][k])) continue;
         for (const [dir, flux, count] of [[1, F.up[k], cr.up], [-1, F.down[k], cr.down]]) {
-          for (let j = poisson((flux / w) * dt); j > 0; j--) {
-            count[k]++;
-            swarm.events.push({ species: nm, kind: 'cross', x: at[k], dir });
-          }
+          const n = poisson((flux / w) * dt);
+          count[k] += n;
+          if (events) for (let j = 0; j < n; j++) swarm.events.push({ species: nm, kind: 'cross', x: at[k], dir });
         }
       }
     }
     const keep = [];
-    for (const d of swarm.dots) if (walk(d, dt, maxHops)) keep.push(d);
-    for (const [d, t] of born) if (walk(d, dt - t, maxHops)) keep.push(d);
+    for (const d of swarm.dots) if (!fast[d.species][d.cell] && walk(d, dt, maxHops, fast[d.species])) keep.push(d);
+    for (const [d, t] of born) if (walk(d, dt - t, maxHops, fast[d.species])) keep.push(d);
     swarm.dots = keep;
+    // The step's seas drawn afresh, and back to cells of dots.
+    for (const nm of Object.keys(saved)) {
+      const F = S[nm], w = swarm.weight[nm];
+      [F.sea, F.left, F.right] = saved[nm];
+      fast[nm].forEach((f, K) => {
+        if (f) for (let j = poisson(F.N[K] / w); j > 0; j--) swarm.dots.push(dot(nm, K));
+      });
+    }
     swarm.time += dt;
     return swarm;
   }
 
   // A dot's hops for a time dt (Gillespie's: exact for rates held fixed): whether it's still in.
-  function walk(d, dt, maxHops) {
+  function walk(d, dt, maxHops, fast) {
     const F = S[d.species], cr = swarm.crossed[d.species];
     let t = 0;
     for (let hop = 0; hop < maxHops; hop++) {
@@ -312,20 +386,22 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
       const k = u < r ? K + 1 : K, dir = u < r ? 1 : -1;
       (dir > 0 ? cr.up : cr.down)[k]++;
       if ((dir > 0 ? F.right[k] : F.left[k]) === OUTSIDE) {
-        swarm.events.push({ species: d.species, kind: 'out', x: at[k], dir });
+        if (!fast?.[K + dir]) swarm.events.push({ species: d.species, kind: 'out', x: at[k], dir });
         return false;
       }
       d.cell = K + dir;
-      d.x = lattice[d.cell].x0 + random() * lattice[d.cell].h;
+      d.x = place(d.species, d.cell);
     }
     return true;
   }
 
-  // Weights, then the first dots, placed by the concentration.
+  // The lattice and weights, then the first dots, placed by the concentration.
+  draw(sol);
   for (const nm of names) {
     const total = amounts(sol, nm).reduce((a, b) => a + b, 0);
-    swarm.weight[nm] = typeof weight === 'number' ? weight : isObject(weight) && weight[nm] > 0 ? weight[nm] : total / dots;
-    swarm.crossed[nm] = { up: new Float64Array(nc + 1), down: new Float64Array(nc + 1) };
+    const w = typeof weight === 'number' ? weight : isObject(weight) && weight[nm] !== undefined ? weight[nm] : total / dots;
+    if (!(w > 0 && Number.isFinite(w))) throw new RangeError(`particles: the weight of ${nm} (mol/m² per dot) must be a positive number, got ${w}` + (total > 0 ? '' : ' (it has nothing to draw)'));
+    swarm.weight[nm] = w;
   }
   return update(sol);
 }

package/src/solution.js

@@ -228,8 +228,15 @@ export function makeSolution(solver, result = {}) {
       );
     }
   });
-  const cond = solver.conditioning, un = solver.unreached;
-  if (result.converged === false && un) {
+  const cond = solver.conditioning, un = solver.unreached, ch = solver.charging;
+  if (result.converged === false && ch) {
+    const A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    sol.warnings.push(
+      `${ch.terminal}: driven at ${ch.current.toPrecision(3)} ${A}, it has no steady state: ` +
+        (ch.what.length > 0 ? `what it feeds (${ch.what.join(', ')}) is closed but for it, so it only stores what comes in (a host filling)` : 'it passes current only by charging its capacitance') +
+        '. advance() in time instead; at no current, a steady solve keeps the charge it holds.',
+    );
+  } else if (result.converged === false && un) {
     const [[V0, I0], [V1, I1]] = [un.low, un.high], g = (x) => x.toPrecision(3), A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
     // The opposite sign within reach: likely a sign slip (a drive is the current into the device).
     const flipped = Math.min(I0, I1) <= -un.target && -un.target <= Math.max(I0, I1);
@@ -245,13 +252,31 @@ export function makeSolution(solver, result = {}) {
     );
   } else if (result.converged === false && cond && cond.digits > 12) {
     const digits = Number.isFinite(cond.digits) ? `lost ${cond.digits.toFixed(0)} of its ~16 digits` : 'was exactly singular';
+    // An ion there so scarce beside the others (a minority swept out of a junction by a large
+    // bias, excluded at a sharp neutral face) that its level can't be held in double precision.
+    let scarce = null;
+    for (const g of cond.nodes ?? []) {
+      let all = 0;
+      for (let i = 0; i < model.species.length; i++) if (model.species[i].z !== 0 && solver.c[g * model.species.length + i] > 0) all += Math.abs(model.species[i].z) * solver.c[g * model.species.length + i];
+      for (let i = 0; i < model.species.length; i++) {
+        const c = solver.c[g * model.species.length + i], r = c / all;
+        if (model.species[i].z !== 0 && c > 0 && r < 1e-10 && !(r >= scarce?.r)) scarce = { r, name: model.species[i].name };
+      }
+    }
     sol.warnings.push(
-      `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): part of the device is held ` +
-        'only weakly, e.g. a floating region coupled to the rest through tiny conductances or rates, or a stiff ' +
-        'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).',
+      `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): ` +
+        (scarce?.r < 1e-24
+          ? `there ${scarce.name} is ${scarce.r.toExponential(0)} of the ions around it, too scarce for its level to be held in double precision ` +
+            '(a minority swept out of a junction by a large bias, or excluded at a sharp neutral face). Drive less; or, at a face, ' +
+            'resolve its double layer (ε > 0) rather than make it a sharp neutral step.'
+          : 'part of the device is held only weakly, e.g. a floating region coupled to the rest through tiny conductances or rates, or a stiff ' +
+            'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).' +
+            (scarce
+              ? ` Or a species there too scarce to hold: ${scarce.name} is ${scarce.r.toExponential(0)} of the ions around it (a layer depleted past a limiting current, say), which a smaller drive avoids.`
+              : '')),
     );
   }
-  if (result.converged === false && !result.stopped && !un && !(cond && cond.digits > 12)) {
+  if (result.converged === false && !result.stopped && !un && !ch && !(cond && cond.digits > 12)) {
     sol.warnings.push(
       'the solve did not converge, and nothing specific showed why. ' +
         'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
@@ -271,15 +296,127 @@ export function makeSolution(solver, result = {}) {
       );
     }
   };
+  // Beside a strictly neutral (ε = 0) material, a face's charge is held in the edge node's box,
+  // which then acts as a diffuse layer as wide as the box: a capacitance F²Σz²c·w/RT in series
+  // with the face's (a Helmholtz C, or for a pinned face whatever holds the charge on the other
+  // side: a conductor's sheet, or a resolved diffuse layer, ε/λ_D), which shrinks as the grid is
+  // refined. Flag it where it lowers that capacitance by over 2%. (Where the box is the smaller
+  // part, as an ε = 0 metal's against a semiconductor's depletion, it's a fine stand-in for the
+  // metal's own screening.)
+  const boxed = (g, h, phi, other, where) => {
+    const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
+    if (mat.conductor || mat.epsr !== 0 || solver.phiUndefined?.[g]) return;
+    const s2 = solver.screening(g), Cbox = (F * F * s2 * h) / (2 * RT);
+    if (!(s2 > 0)) return;
+    let C = phi.C;
+    if (phi.type === 'pinned') {
+      const om = other < 0 ? null : model.materials[model.regions[grid.nodeRegion[other]].material];
+      C = !om || om.conductor ? Infinity : (om.epsr * EPS0) / debye(other);
+    }
+    if (!(C / (C + Cbox) > 0.02)) return;
+    const lowers = Number.isFinite(C) ? `lowering the double-layer capacitance by ${((100 * C) / (C + Cbox)).toFixed(0)}%` : 'which alone sets its charge';
+    sol.warnings.push(
+      `${where}: the face's charge sits in the strictly neutral cell beside it (${h.toExponential(2)} m), which acts as a diffuse layer that wide ` +
+        `(${Cbox.toPrecision(2)} F/m² in series), ${lowers}, so it depends on the mesh. ` +
+        (Number.isFinite(C)
+          ? `Coarsen the grid there: a cell of ${((2 * 49 * C * RT) / (F * F * s2)).toExponential(1)} m or more keeps it within 2%.`
+          : "Give the face a Helmholtz capacitance (phi: { type: 'capacitive', C }), or make it neutral."),
+    );
+  };
   interfaces.forEach((itf, f) => {
     if (itf.phi.type === 'neutral') return;
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
+    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`);
+    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`);
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-  if (resolves(contacts.left)) check(0, grid.segLength[0], 'contacts.left');
-  if (resolves(contacts.right)) check(nNodes - 1, grid.segLength[nNodes - 2], 'contacts.right');
+  if (resolves(contacts.left)) {
+    check(0, grid.segLength[0], 'contacts.left');
+    boxed(0, grid.segLength[0], contacts.left.phi, -1, 'contacts.left');
+  }
+  if (resolves(contacts.right)) {
+    check(nNodes - 1, grid.segLength[nNodes - 2], 'contacts.right');
+    boxed(nNodes - 1, grid.segLength[nNodes - 2], contacts.right.phi, -1, 'contacts.right');
+  }
+  // Electrons or holes above their band's effective density of states (the material's cRef)
+  // under Boltzmann statistics: degenerate, where those statistics no longer hold (a surface
+  // driven past what a reaction can take away piles holes up to 1e9 mol/m³ and still converges).
+  model.regions.forEach((reg, r) => {
+    const mat = model.materials[reg.material];
+    if (mat.conductor) return;
+    model.species.forEach((sp, i) => {
+      if ((sp.name !== 'e-' && sp.name !== 'h+') || !mat.present[i] || mat.modelOf?.[i] >= 0) return;
+      let top = 0, at = NaN;
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const c = solver.c[g * model.species.length + i];
+        if (c > top) [top, at] = [c, grid.x[g]];
+      }
+      if (top > mat.cRef[i]) {
+        sol.warnings.push(
+          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, above its cRef (${mat.cRef[i].toExponential(2)}, the band's effective density of states), where Boltzmann statistics no longer hold: ` +
+            'give the material Fermi–Dirac statistics (docs/statistics.md), or ask whether this state is physical (a surface driven past what can carry its carriers away).',
+        );
+      }
+    });
+  });
+  // Any other species denser than any material can be (1e6 mol/m³: water is 5.5e4, a metal's
+  // atoms ~1.5e5): a level set where the device can't follow it, such as a contact's for one ion
+  // far from its neighbours' (Na⁺ held at 1.2e37 mol/m³, whose currents then read 1e28 A/m²).
+  model.regions.forEach((reg, r) => {
+    const mat = model.materials[reg.material];
+    if (mat.conductor) return;
+    model.species.forEach((sp, i) => {
+      if (sp.name === 'e-' || sp.name === 'h+' || !mat.present[i]) return;
+      let top = 0, at = NaN;
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const c = solver.c[g * model.species.length + i];
+        if (c > top) [top, at] = [c, grid.x[g]];
+      }
+      if (top > 1e6) {
+        sol.warnings.push(
+          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, denser than any material: ` +
+            'a level set where the device cannot follow it. Check what holds it there (the V or bath of a contact, its mu0 and cRef) with describe() from driftlet/kit.',
+        );
+      }
+    });
+  });
+  // A contact that holds its end neutral ('bulk': a bath, an ohmic contact) cuts off any space
+  // charge reaching it: a double layer longer than its region. The charge it cuts off is about
+  // ρ λ_D at the node beside it; against the region's own space charge (half Σ|ρ| over it, the
+  // two signs of a double layer), warn past 1e-3.
+  for (const side of ['left', 'right']) {
+    if (contacts[side].phi.type !== 'bulk') continue;
+    const r = side === 'left' ? 0 : model.regions.length - 1, a = grid.regionStart[r], b = grid.regionEnd[r];
+    const mat = model.materials[model.regions[r].material];
+    if (!(mat.epsr > 0) || mat.conductor || b - a < 3) continue;
+    const n = model.species.length, fixed = model.regions[r].fixedCharge ?? 0;
+    const rho = (g) => {
+      let q = fixed;
+      for (let i = 0; i < n; i++) if (solver.c[g * n + i] > 0) q += F * model.species[i].z * solver.c[g * n + i];
+      return q;
+    };
+    // (and beside the contact the material is itself out of neutrality, by more than round-off:
+    // a quasi-neutral layer split off a junction's holds almost no space charge, so the ratio
+    // below alone would read its round-off as a cut-off layer)
+    const gross = (g) => {
+      let q = Math.abs(fixed);
+      for (let i = 0; i < n; i++) if (solver.c[g * n + i] > 0) q += F * Math.abs(model.species[i].z) * solver.c[g * n + i];
+      return q;
+    };
+    let total = 0;
+    for (let g = a; g <= b; g++) total += (Math.abs(rho(g)) * grid.vol[g]) / 2;
+    const g1 = side === 'left' ? a + 1 : b - 1, lam = debye(g1), w = (grid.x[g1 + 1] - grid.x[g1 - 1]) / 2;
+    const cut = (Math.abs(rho(g1)) * lam * grid.vol[g1]) / w;
+    if (Number.isFinite(cut) && total > 0 && cut > 1e-3 * total && Math.abs(rho(g1)) > 1e-3 * gross(g1)) {
+      sol.warnings.push(
+        `contacts.${side}: the space charge in ${model.regions[r].name} reaches the contact, which holds its end neutral and so cuts it off (a double layer or depletion longer than the region): ` +
+          `the charge beside the contact is ${(cut / total).toPrecision(2)} of the space charge in the region, and the error in that charge can be several times more. ` +
+          'Lengthen the region (a crowded double layer grows as the root of the voltage).',
+      );
+    }
+  }
 
   // Steep profiles carrying current: Scharfetter–Gummel takes the field as uniform across each
   // cell, which fails where it isn't, as at an electrode where a species is nearly depleted (there