driftlet 0.14.0 → 0.16.4

package/src/device.js

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

package/src/index.js

@@ -63,8 +63,8 @@ export class Device {
   }
 
   /**
-   * Change part of the definition (deep-merged). A contact given V or I drops the other, so
-   * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
+   * Change part of the definition (deep-merged). A contact given V or I drops the other (and
+   * given I, any series R), so `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
    * `{ ports: { gate: { V: 0.2 } } }` (an array replaces them all). A change to the terminals'
    * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
    * the warm start when the grid and species are unchanged (else restarting from the regions' c0).
@@ -73,7 +73,8 @@ export class Device {
    */
   set(patch) {
     // A terminal given a new kind of drive drops the old one: { I: 0 } replaces a held V.
-    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
+    // (A current drives a terminal alone: given I, a contact drops V and any series R too.)
+    const redrive = (c) => (c && typeof c === 'object' && !Array.isArray(c) ? ('I' in c && !('V' in c) ? { ...c, V: undefined, ...('R' in c ? {} : { R: undefined }) } : 'V' in c && !('I' in c) ? { ...c, I: undefined } : c) : c);
     for (const side of ['left', 'right']) {
       const c = patch?.contacts?.[side];
       if (c && typeof c === 'object') patch = { ...patch, contacts: { ...patch.contacts, [side]: redrive(c) } };
@@ -106,15 +107,27 @@ export class Device {
     this.def = def;
     this.model = model;
     this._solver = solver;
-    if (old && old.u.length === solver.u.length && old.n === solver.n) {
-      solver.u.set(old.u);
-      solver.uLo.set(old.uLo);
-      // A node newly on an electrode's surface (a window moved, a surface added) starts at its
-      // starting coverages, not at whatever its slots held.
-      const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
-      for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
+    // The state carries over where the unknowns line up; on a new grid (the same regions, faces
+    // and terminals), interpolated onto it. (Started cold instead, a floating gate lost its
+    // charge to a refined grid.)
+    const sameUnknowns = old && old.u.length === solver.u.length && old.n === solver.n;
+    const regridded = old && !sameUnknowns && old.M === solver.M && old.n === solver.n && old.nFaces === solver.nFaces && old.terms.length === solver.terms.length && old.model.grid.regionStart.length === model.grid.regionStart.length;
+    if (sameUnknowns || regridded) {
+      if (sameUnknowns) {
+        solver.u.set(old.u);
+        solver.uLo.set(old.uLo);
+        // A node newly on an electrode's surface (a window moved, a surface added) starts at its
+        // starting coverages, not at whatever its slots held.
+        const surfaceAt = (sv, g) => (sv.surfPort[g] < 0 ? '' : sv.model.ports[sv.surfPort[g]].surface.map((sp) => sp.name).join());
+        for (let g = 0; g < solver.nNodes; g++) if (solver.surfPort[g] >= 0 && surfaceAt(solver, g) !== surfaceAt(old, g)) solver._surfaceStart(g);
+      } else solver._warmFrom(old);
       solver.computeConcentrations();
       solver.time = old.time;
+      // Held sources read at the same time as before, and an adaptive transient goes on at the
+      // step size it had reached (its order restarts, as at any change of the equations).
+      solver.sourceTime = old.sourceTime;
+      solver._refreshSources();
+      solver.dtNext = old.dtNext;
       solver.contactDEnd = old.contactDEnd;
       if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)

package/src/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);
 }