driftlet 0.13.0 → 0.16.2

package/src/particles.js

@@ -0,0 +1,407 @@
+// Particles: a solution drawn as dots, each a fixed amount of one species, hopping between the
+// cells of a display lattice. The hops' one-way rates are set from the solution so that, on
+// average, the dots' density is its concentration and their net crossing rate is its flux: the
+// dots are a stochastic sample of the drift–diffusion solution, not a separate model. Dots are
+// made and unmade where the flux diverges (reactions, generation, ports), and they enter and
+// leave through the contacts and any metal.
+//
+// Across each cell boundary, the one-way fluxes F⁺ (toward +x) and F⁻ are set by two numbers:
+// their difference, the solution's net flux J there, and their product, F⁺F⁻ = F₀², the
+// boundary's exchange. In equilibrium F⁺ = F⁻ = F₀, detailed balance, so the dots settle into
+// the concentration profile whatever F₀ is; F₀ sets only how fast they jitter. Between cells it's
+// Scharfetter–Gummel's (whose one-way fluxes over a uniform field have F⁺F⁻ fixed by the drift
+// across the boundary): F₀ = (D/h)√(c_K c_K+1)·(d/2)/sinh(d/2), d the step in ψ = μ̄/RT − ln c,
+// which gives a dot in a flat potential the diffusivity D. Across a face that a species crosses
+// by permeability, the one-way fluxes are the face's own (Ussing's unidirectional fluxes), so the
+// dots crossing each way are counted as a tracer experiment would count them.
+//
+// Where a species is dense, dots would crowd: a cell that would hold more than `cap` of them is
+// drawn as a sea instead (its concentration, shaded), which holds no dots but exchanges them with
+// its neighbours as a contact's reservoir does: a dot hopping in is absorbed, and dots come out at
+// the one-way rate. Crossings between two seas through a face (an ion through a membrane between
+// two baths) are events, at the same rates. So a junction shows its majority carriers as seas
+// and its minority carriers as dots, each one injected, drifting, diffusing and recombining.
+
+import { GAS_CONSTANT } from './constants.js';
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+// (d/2)/sinh(d/2) = √(B(d)B(−d)).
+const shape = (d) => {
+  const a = Math.abs(d) / 2;
+  if (a < 1e-4) return 1 - (a * a) / 6;
+  if (a > 700) return 0;
+  return a / Math.sinh(a);
+};
+
+// What lies to one side of a cell boundary, for a species.
+const NONE = 0, DOT = 1, OUTSIDE = 2; // nothing (closed); a cell of dots; a sea, a contact's reservoir or a metal
+
+/**
+ * A swarm of dots sampling a solution's concentrations and fluxes. Amounts are per area (a planar
+ * device's). `step(dt)` moves them on in the device's time, at the rates of the solution last
+ * given; `update(sol)` gives a new one.
+ * @param {object} sol a solution (from solve(), advance(), live(), …)
+ * @param {object} [opts]
+ * @param {string[]} [opts.species] which species (default: every species with a concentration)
+ * @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 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));
+  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.) 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;
+    }
+    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];
+  }
+  // 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: [],
+    species: names,
+    weight: {}, // mol/m² per dot
+    sea: {}, // per species, per cell: 1 where it's a sea
+    dots: [], // { species, cell, x }
+    // what happened in the last step, beyond hops between cells of dots: { species, kind, x, dir }
+    // with kind 'in' (a dot from a sea, contact or metal), 'out' (into one), 'made', 'unmade',
+    // or 'cross' (from sea to sea through a face); dir ±1 for a crossing's direction
+    events: [],
+    crossed: {}, // per species, at each boundary (0 … cells): dots across it, { up, down } (toward +x, −x), counted since you last zeroed them
+    time: 0,
+    update,
+    step,
+    expected,
+  };
+  const S = {}; // per species: amounts, boundaries and rates, from the solution
+
+  function amounts(sol, nm) {
+    const c = sol.c[nm];
+    return Float64Array.from(lattice, (cl) => {
+      let n = 0;
+      for (let g = cl.a; g <= cl.b; g++) if (c[g] > 0) n += c[g] * box[g];
+      return n;
+    });
+  }
+
+  function fields(sol, nm, prev) {
+    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] && 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.
+    const left = new Uint8Array(nc + 1), right = new Uint8Array(nc + 1), face = new Uint8Array(nc + 1);
+    const up = new Float64Array(nc + 1), down = new Float64Array(nc + 1);
+    const pair = (k, net, F0) => {
+      const r = Math.hypot(F0, net / 2);
+      up[k] = r + net / 2;
+      down[k] = r - net / 2;
+    };
+    const side = (K) => (sea[K] ? OUTSIDE : DOT);
+    for (let k = 0; k <= nc; k++) {
+      const A = k > 0 && on[k - 1] ? lattice[k - 1] : null, B = k < nc && on[k] ? lattice[k] : null;
+      if (A && B && A.b + 1 === B.a) {
+        // two cells: within a region, or across a face
+        if (A.region !== B.region) {
+          const itf = sol.interfaces[A.region];
+          if (!itf.links[nm]) continue;
+          [left[k], right[k]] = [side(k - 1), side(k)];
+          if (itf.oneWay?.[nm]) {
+            face[k] = 1;
+            [up[k], down[k]] = itf.oneWay[nm];
+            continue;
+          }
+        }
+        [left[k], right[k]] = [side(k - 1), side(k)];
+        const hD = A.h / 2 / D[A.mid] + B.h / 2 / D[B.mid];
+        pair(k, J[A.b], (Math.sqrt((N[k - 1] / A.h) * (N[k] / B.h)) * shape(psi[k] - psi[k - 1])) / hD);
+      } else if (A || B) {
+        // out of the cells: through a contact, or a face to a metal
+        const cl = A ?? B, g = A ? A.b : B.a;
+        let net, open;
+        if (g === 0 || g === nn - 1) {
+          const ct = sol.contacts[g === 0 ? 'left' : 'right'];
+          open = ct.links[nm] !== undefined;
+          net = ct.flux[nm]; // toward +x at either end
+        } else {
+          open = sol.interfaces[A ? A.region : B.region - 1].links[nm] !== undefined;
+          net = J[A ? g : g - 1];
+        }
+        if (!open) continue;
+        [left[k], right[k]] = A ? [side(k - 1), OUTSIDE] : [OUTSIDE, side(k)];
+        pair(k, net, (2 * D[g] * Math.max(c[g], 0)) / cl.h);
+      }
+    }
+    // Made and unmade in each cell (mol/(m²·s)): by the bulk reactions' one-way rates (so in
+    // equilibrium, generation and recombination both go on, in balance), and whatever else the
+    // fluxes don't account for, ∂N/∂t − (J_in − J_out) less the reactions' net (ports, face
+    // reactions), with ∂N/∂t from the last solution if time has passed since.
+    const made = new Float64Array(nc), unmade = new Float64Array(nc);
+    for (const rx of sol.bulkReactions ?? []) {
+      const nu = rx.nu?.[nm];
+      if (!nu) continue;
+      lattice.forEach((cl, K) => {
+        for (let g = cl.a; g <= cl.b; g++) {
+          if (!(rx.forward[g] >= 0)) continue;
+          const fwd = rx.forward[g] * box[g], bwd = (rx.forward[g] - rx.rate[g]) * box[g];
+          made[K] += nu > 0 ? nu * fwd : -nu * bwd;
+          unmade[K] += nu > 0 ? nu * bwd : -nu * fwd;
+        }
+      });
+    }
+    const dt = prev && sol.time > prev.time ? sol.time - prev.time : Infinity;
+    for (let K = 0; K < nc; K++) {
+      if (!on[K]) continue;
+      const rest = (Number.isFinite(dt) ? (N[K] - prev.N[K]) / dt : 0) + up[K + 1] - down[K + 1] - (up[K] - down[K]) - (made[K] - unmade[K]);
+      if (rest > 0) made[K] += rest;
+      else unmade[K] -= rest;
+    }
+    // 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 };
+  }
+
+  /**
+   * A new solution: the dots keep their places and move on at its rates. A cell that has become a
+   * sea absorbs its dots, and one that's no longer a sea is filled. With resample (a jump between
+   * 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. 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);
+      const F = S[nm], w = swarm.weight[nm];
+      swarm.sea[nm] = F.sea;
+      const before = (K) => (!was || was.sea[K] || !was.on[K] ? 0 : was.N[K] / w);
+      swarm.dots = swarm.dots.filter((d) => {
+        if (d.species !== nm) return true;
+        if (!F.on[d.cell] || F.sea[d.cell]) return false;
+        const m = before(d.cell);
+        return !(resample && m > 0) || random() * m < F.N[d.cell] / w;
+      });
+      F.N.forEach((n, K) => {
+        if (!F.on[K] || F.sea[K]) return;
+        const m = before(K);
+        if (m === 0 || resample) for (let j = poisson(Math.max(0, n / w - m)); j > 0; j--) swarm.dots.push(dot(nm, K));
+      });
+    }
+    return swarm;
+  }
+
+  /** 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]);
+  }
+
+  // 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());
+  function poisson(m) {
+    if (m > 50) return Math.max(0, Math.round(m + Math.sqrt(m) * gauss()));
+    const e = Math.exp(-m);
+    let k = 0;
+    for (let p = random(); p > e; p *= random()) k++;
+    return k;
+  }
+
+  /**
+   * 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 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, 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];
+      for (let K = 0; K < nc; K++) {
+        if (!F.on[K] || F.sea[K]) continue;
+        const made = F.made[K] / w;
+        const fromLeft = F.left[K] === OUTSIDE ? F.up[K] / w : 0, fromRight = F.right[K + 1] === OUTSIDE ? F.down[K + 1] / w : 0;
+        const rate = made + fromLeft + fromRight;
+        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]++;
+            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]++;
+            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.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]]) {
+          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 (!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, fast) {
+    const F = S[d.species], cr = swarm.crossed[d.species];
+    let t = 0;
+    for (let hop = 0; hop < maxHops; hop++) {
+      const K = d.cell, N = F.N[K];
+      if (!(N > 0)) return true;
+      const r = F.right[K + 1] ? F.up[K + 1] / N : 0, l = F.left[K] ? F.down[K] / N : 0, die = F.unmade[K] / N;
+      const total = r + l + die;
+      if (!(total > 0)) return true;
+      t -= Math.log(1 - random()) / total;
+      if (t > dt) return true;
+      const u = random() * total;
+      if (u >= r + l) {
+        swarm.events.push({ species: d.species, kind: 'unmade', x: d.x });
+        return false;
+      }
+      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) {
+        if (!fast?.[K + dir]) swarm.events.push({ species: d.species, kind: 'out', x: at[k], dir });
+        return false;
+      }
+      d.cell = K + dir;
+      d.x = place(d.species, d.cell);
+    }
+    return true;
+  }
+
+  // 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);
+    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

@@ -26,6 +26,7 @@ export function makeSolution(solver, result = {}) {
     muStd: {},
     V: {},
     Vstd: {},
+    T: model.T,
     time: solver.time,
     steady: solver.atSteady,
     converged: result.converged ?? true,
@@ -73,6 +74,17 @@ export function makeSolution(solver, result = {}) {
   // Contacts: fluxes and displacement at the final state (re-evaluated from the balance rows of
   // the boxes they're read from).
   solver.computeConcentrations();
+  // Each species' flux toward +x across each segment (between nodes g and g + 1; a face's across
+  // its pair of nodes), and its diffusivity at each node (NaN where it's absent or in a metal).
+  sol.flux = {};
+  sol.D = {};
+  solver.segmentFluxes().forEach((J, i) => (sol.flux[species[i].name] = J));
+  for (let i = 0; i < n; i++) {
+    sol.D[species[i].name] = Float64Array.from(grid.nodeRegion, (r, g) => {
+      const mat = model.materials[model.regions[r].material];
+      return mat.conductor || !solver.present[g * n + i] ? NaN : mat.D[i];
+    });
+  }
   solver._assembleBookkeeping(solver.lastDt);
   sol.contacts = {};
   sol.gates = {};
@@ -90,6 +102,8 @@ export function makeSolution(solver, result = {}) {
     // Current toward +x through this contact; in steady state both contacts agree.
     const V = solver.termV[side === 'left' ? 0 : 1];
     sol.contacts[side] = { V, flux, D, current: conduction + displacement };
+    // How each species crosses it (a link type), for those that do.
+    sol.contacts[side].links = Object.fromEntries(ct.species.flatMap((l, i) => (l.type === 'blocked' ? [] : [[species[i].name, l.type]])));
     if (ct.phi.type === 'capacitive' || ct.phi.type === 'pinned') {
       // Charge on the gate (or metal) plate, per area if the device is planar: +D at the left, −D
       // at the right.
@@ -154,6 +168,11 @@ export function makeSolution(solver, result = {}) {
     for (let i = 0; i < n; i++) N[species[i].name] = u[b * M + 1 + i];
     const rates = itf.reactions.map((_, k) => u[b * M + 1 + n + k]); // mol/(m²·s), forward
     const out = { left: model.regions[f].name, right: model.regions[f + 1].name, dipole: itf.dipole, sheetCharge: itf.sheetCharge, D: u[b * M], N, rates };
+    // How each species crosses it (a link type), for those that do; and for those crossing by
+    // permeability, the one-way fluxes [toward +x, toward −x], per area.
+    out.links = Object.fromEntries(itf.links.flatMap((l, i) => (l.type === 'blocked' ? [] : [[species[i].name, l.type]])));
+    const oneWay = solver.faceOneWay(f);
+    if (oneWay.some((w) => w)) out.oneWay = Object.fromEntries(oneWay.flatMap((w, i) => (w ? [[species[i].name, w]] : [])));
     if (itf.gates.length > 0) {
       // Each gate's fraction open, and the voltage across the face that drives them.
       out.gates = Object.fromEntries(itf.gates.map((gate, q) => [gate.name, u[solver._gateSlot(f, q)]]));
@@ -166,17 +185,22 @@ export function makeSolution(solver, result = {}) {
   // and integrated over each region and the device (mol/(m²·s)), by the nodes' control volumes,
   // just as the balances count it.
   sol.bulkReactions = solver.rxs.map((rx) => {
-    const rate = new Float64Array(nNodes).fill(NaN), regions = model.regions.map(() => 0);
+    const rate = new Float64Array(nNodes).fill(NaN), forward = new Float64Array(nNodes).fill(NaN), regions = model.regions.map(() => 0);
     let total = 0;
     for (let g = 0; g < nNodes; g++) {
       const m = solver.nodeMaterial[g];
       if (!(rx.kf[m] > 0)) continue;
       rate[g] = solver.bulkRate(rx, g);
+      forward[g] = solver.bulkForward(rx, g);
       const amount = grid.vol[g] * rate[g];
       regions[grid.nodeRegion[g]] += amount;
       total += amount;
     }
-    return { rate, regions, total };
+    // Its two one-way rates are forward and forward − rate; what each makes of each species, per
+    // forward reaction: ν, negative for what it consumes.
+    const nu = {};
+    rx.sp.forEach((i, p) => (nu[species[i].name] = (nu[species[i].name] ?? 0) - rx.nu[p]));
+    return { rate, forward, nu, regions, total };
   });
 
   // Total charge in the device (space charge plus sheet charges), per area if it's planar.
@@ -204,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);
@@ -221,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.',
@@ -247,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