driftlet 0.13.0 → 0.14.0

package/package.json

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

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);

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) {
@@ -326,6 +369,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)`));

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';

package/src/particles.js

@@ -0,0 +1,331 @@
+// 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 holds on average before it's a sea (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;
+
+  // 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];
+      }
+    }
+    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 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));
+
+  const swarm = {
+    cells: lattice.map(({ x0, x1, region }) => ({ x0, x1, region })),
+    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] && n / w > cap ? 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;
+    }
+    return { N, on, sea, left, right, face, up, down, made, unmade, 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.
+   */
+  function update(next, { resample = false } = {}) {
+    sol = next;
+    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) {
+    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 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 dot hops at most maxHops times in a step.
+   */
+  function step(dt, { maxHops = 200 } = {}) {
+    swarm.events = [];
+    // 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.
+    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);
+          if (u < fromLeft) {
+            cr.up[K]++;
+            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 });
+          } 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;
+        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 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);
+    swarm.dots = keep;
+    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) {
+    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) {
+        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;
+    }
+    return true;
+  }
+
+  // Weights, then the first dots, placed by the concentration.
+  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) };
+  }
+  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.

package/src/solver.js

@@ -2347,6 +2347,21 @@ export class Solver {
     return P * -Math.expm1(-(aHi + aLo));
   }
 
+  // A bulk reaction's forward one-way rate at node g (mol/(m³·s)); its backward one is that
+  // times e^{−a}, so their difference is bulkRate's.
+  bulkForward(rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    const law = rx.srh?.[this.nodeMaterial[g]];
+    if (law) {
+      let a = rx.fixedA;
+      for (let p = 0; p < rx.sp.length; p++) a += rx.nu[p] * (u[b * M + 1 + rx.sp[p]] + uLo[b * M + 1 + rx.sp[p]]);
+      return this._srhRate(law, c[g * n + law.n.i], c[g * n + law.p.i], a).forward;
+    }
+    let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g];
+    for (let p = 0; p < rx.sp.length; p++) if (rx.nu[p] > 0) P *= rx.nu[p] === 1 ? c[g * n + rx.sp[p]] : powi(c[g * n + rx.sp[p]], rx.nu[p]);
+    return P;
+  }
+
   // The larger of a bulk reaction's two one-way rates at node g (mol/(m³·s)): the scale its net
   // rate is read against (in equilibrium the net rate is their round-off).
   bulkOneWay(rx, g) {
@@ -2376,7 +2391,7 @@ export class Solver {
     const dDn = tp * cn + tp * n1 * kN + tn * p1 * (1 - kN);
     const dDp = tp * n1 * kP + tn * cp + tn * p1 * (1 - kP);
     const dDa = tp * n1 * kA + tn * p1 * (-1 - kA);
-    return { rate, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
+    return { rate, forward: np / den, oneWay: (np / den) * Math.max(1, Math.exp(-a)), Cn: rate * (1 - dDn / den), Cp: rate * (1 - dDp / den), Ca: (np / den) * (1 - f) - (rate * dDa) / den };
   }
 
   // A face reaction (see normalizeFaceReactions). Its rate r_k is an unknown of the face block,
@@ -3152,7 +3167,13 @@ export class Solver {
       const alpha = own > maxStep ? maxStep / own : 1;
       this._addToState(delta, -alpha);
       this.floating.forEach((k, a) => (this.termV[k] -= alpha * deltaV[a]));
-      if (alpha === 1 && step < tol) {
+      // A time step's Newton contracts fast from its predictor (1e-2, 1e-9, 1e-15 thermal
+      // units). The next update would be about θ = step/(the last one) times this one, so where
+      // θ/(1 − θ) of it (Hairer and Wanner's estimate) is under tol, this update converged it:
+      // the iteration that would only show that is skipped, a third of a typical step's work.
+      const last = history[history.length - 2], theta = step / last;
+      const contracted = dt !== Infinity && it >= 2 && step < 1e-6 && theta < 0.1 && (theta / (1 - theta)) * step < tol;
+      if (alpha === 1 && (step < tol || contracted)) {
         const done = { converged: true, iterations: it, history, residual: rmax };
         if (islandsOff(it, done)) continue;
         this.computeConcentrations();
@@ -4120,6 +4141,72 @@ export class Solver {
     return cuts;
   }
 
+  // Each species' flux toward +x across every segment, at the current state (concentrations
+  // computed): totals through the cross-section, mol/s (mol/(m²·s) for a planar device). A face's
+  // segment, between its pair of nodes, carries the face's flux; a conductor's, its carrier's.
+  // These are the fluxes the balances add up (displacement aside), from the same formulas.
+  segmentFluxes() {
+    const { model, n, M, u, uLo, c, z, ex } = this;
+    const { grid, materials, regions, interfaces } = model;
+    const out = Array.from({ length: n }, () => new Float64Array(grid.nNodes - 1));
+    for (let r = 0; r < regions.length; r++) {
+      const reg = regions[r], mat = materials[reg.material], vel = reg.velocity;
+      for (let s = grid.regionStart[r]; s < grid.regionEnd[r]; s++) {
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s];
+        if (mat.conductor) {
+          out[mat.conductor.i][s] = u[bL * M];
+          continue;
+        }
+        for (let i = 0; i < n; i++) {
+          if (!mat.present[i] || mat.D[i] === 0) continue;
+          const pe = (vel * h) / mat.D[i];
+          const d = z[i] * (u[bR * M] - u[bL * M]) + ex[(s + 1) * n + i] - ex[s * n + i] - pe;
+          const deta = u[bR * M + 1 + i] - u[bL * M + 1 + i] + (uLo[bR * M + 1 + i] - uLo[bL * M + 1 + i]) - pe;
+          out[i][s] = -(mat.D[i] / h) * bernoulli(d) * c[s * n + i] * Math.expm1(deta);
+        }
+        if (reg.mixing > 0) {
+          // Eddy mixing (see _segmentMixing): −(D_mix/h) c̄_i (Δη_i − z_i q), c̄ the logarithmic mean.
+          const on = [...Array(n).keys()].filter((i) => mat.present[i] && mat.D[i] > 0);
+          const cb = [], de = [];
+          let S = 0, Q = 0;
+          for (const k of on) {
+            const a = c[s * n + k], b = c[(s + 1) * n + k];
+            cb[k] = a === b ? a : (b - a) / Math.log(b / a);
+            de[k] = u[bR * M + 1 + k] - u[bL * M + 1 + k] + (uLo[bR * M + 1 + k] - uLo[bL * M + 1 + k]);
+            S += z[k] * z[k] * cb[k];
+            Q += z[k] * cb[k] * de[k];
+          }
+          const q = S > 0 ? Q / S : 0;
+          for (const i of on) out[i][s] -= (reg.mixing / h) * cb[i] * (de[i] - z[i] * q);
+        }
+      }
+    }
+    interfaces.forEach((itf, f) => {
+      const gL = grid.regionEnd[f], b = this.blockOfFace[f];
+      for (let i = 0; i < n; i++) if (itf.links[i].type !== 'blocked') out[i][gL] = grid.area[gL] * u[b * M + 1 + i];
+    });
+    return out;
+  }
+
+  // A face's one-way fluxes for each species crossing it by permeability, per area: toward +x
+  // and toward −x, whose difference is its net flux (Ussing's unidirectional fluxes; GHK's two
+  // terms between like solutions). null for a species crossing any other way.
+  faceOneWay(f) {
+    const { model, n, M, u, uLo, z } = this, itf = model.interfaces[f], grid = model.grid;
+    const bL = this.blockOfFace[f] - 1, bR = bL + 2, gl = grid.regionEnd[f], gr = gl + 1;
+    return itf.links.map((link, i) => {
+      if (link.type !== 'permeability') return null;
+      const kl = gl * n + i, kr = gr * n + i;
+      const shift = this.mu0hat[kr] - this.mu0hat[kl] - Math.log(this.cRef[kr] / this.cRef[kl]);
+      const d = z[i] * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M])) + shift;
+      const deta = u[bR * M + 1 + i] - u[bL * M + 1 + i] + (uLo[bR * M + 1 + i] - uLo[bL * M + 1 + i]);
+      const gated = link.gates ?? [];
+      const P = link.P * (gated.length ? this._open(gated, (q) => u[this._gateSlot(f, q)]) : 1);
+      const right = P * bernoulli(d) * this.c[kl];
+      return [right, right * Math.exp(deta)];
+    });
+  }
+
   // Complex profiles of δφ (V), δμ̄ (J/mol) and δc (mol/m³) from a small-signal solution.
   _smallSignalProfiles(xr, xi) {
     const { n, M, z, VT, model } = this;

package/types/checks.d.ts

@@ -18,7 +18,8 @@
  *   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

package/types/kit.d.ts

@@ -36,6 +36,7 @@ export function vacuumZeroCharge(def: object, workFunction: number, inside: Vacu
 export { live } from "./live.js";
 export { recorder } from "./recorder.js";
 export { check } from "./checks.js";
+export { particles } from "./particles.js";
 export { polarization } from "./polarization.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,