driftlet 0.1.0

package/src/equation.js

@@ -0,0 +1,188 @@
+// Reaction equations as text: 'Ag+ + e- = Ag(s)', '2 H+ + 2 e- = H2', 'e- + h+ = 0'. A
+// definition's reactions can be written this way; they compile to signed stoichiometry (ν < 0
+// consumed by the forward reaction, left to right as written).
+
+import { DeviceError } from './errors.js';
+import { FARADAY } from './constants.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * One participant of an equation as written.
+ * @typedef {object} Term
+ * @property {string} name the participant as written (with any trailing parenthesis)
+ * @property {number} nu signed coefficient (< 0 on the left of the equation)
+ */
+
+/**
+ * Parse an equation into its terms, in order. The two sides are separated by `=` (or `⇌`, `<=>`,
+ * `->`, `→`), terms by ` + ` (spaces around the plus, which keeps it apart from charges), and a
+ * side with nothing on it is `0` or `∅`. A coefficient is an integer followed by a space
+ * (`2 e-`), so names may start with digits (`3He`).
+ * @param {string} text
+ * @param {string} [path] for error messages
+ * @returns {Term[]}
+ */
+export function parseEquation(text, path = 'equation') {
+  if (typeof text !== 'string') fail(`${path} must be a string like 'Ag+ + e- = Ag(s)'`);
+  const sides = text.trim().split(/\s+(?:=|⇌|<=>|->|→)\s+/);
+  if (sides.length !== 2) fail(`${path}: ${JSON.stringify(text)} needs exactly one '=' with a space on either side`);
+  const terms = [];
+  sides.forEach((side, s) => {
+    if (side === '0' || side === '∅') return;
+    for (const raw of side.split(/\s+\+\s+/)) {
+      const m = /^(?:(\d+)\s+)?(\S+)$/.exec(raw.trim());
+      if (!m) fail(`${path}: can't read ${JSON.stringify(raw.trim())} in ${JSON.stringify(text)} (terms are separated by ' + ', with spaces)`);
+      const nu = m[1] === undefined ? 1 : Number(m[1]);
+      if (nu === 0) fail(`${path}: a zero coefficient in ${JSON.stringify(text)}`);
+      terms.push({ name: m[2], nu: s === 0 ? -nu : nu });
+    }
+  });
+  if (terms.length === 0) fail(`${path}: ${JSON.stringify(text)} has no participants`);
+  return terms;
+}
+
+/**
+ * The signed stoichiometry `{ name: ν }` of a homogeneous reaction, as a bulk reaction's `nu`.
+ * A participant on both sides is an error: give the net reaction.
+ * @param {string} text
+ * @param {string} [path]
+ * @returns {Record<string, number>}
+ */
+export function stoichiometry(text, path = 'equation') {
+  const nu = {};
+  const side = {};
+  for (const t of parseEquation(text, path)) {
+    if (side[t.name] !== undefined && side[t.name] !== Math.sign(t.nu)) {
+      fail(`${path}: '${t.name}' appears on both sides of ${JSON.stringify(text)}; give the net reaction`);
+    }
+    side[t.name] = Math.sign(t.nu);
+    nu[t.name] = (nu[t.name] ?? 0) + t.nu;
+  }
+  return nu;
+}
+
+/**
+ * Which side of a face each participant of an equation is on: the side whose material holds it
+ * (on a conductor's side, only its carrier). A species held on both sides is labelled with its
+ * side, 'Li+(left)', or its material, 'Li+(graphite)'. Participants in `fixed` (fixed-activity
+ * neutrals) go beside a conductor if there is one, else on the left (their side doesn't matter).
+ * @param {Term[]} terms
+ * @param {{ name: string, holds: (species: string) => boolean, conductor?: boolean }} left
+ * @param {{ name: string, holds: (species: string) => boolean, conductor?: boolean }} right
+ * @param {Record<string, number> | undefined} fixed
+ * @param {string} path
+ * @returns {{ left: Record<string, number>, right: Record<string, number> }}
+ */
+export function faceSides(terms, left, right, fixed, path) {
+  const sides = { left: {}, right: {} };
+  const put = (side, name, nu) => (sides[side][name] = (sides[side][name] ?? 0) + nu);
+  const fixedSide = right.conductor && !left.conductor ? 'right' : 'left';
+  for (const t of terms) {
+    if (fixed?.[t.name] !== undefined) {
+      put(fixedSide, t.name, t.nu);
+      continue;
+    }
+    const inL = left.holds(t.name), inR = right.holds(t.name);
+    if (inL && inR) {
+      fail(
+        `${path}: '${t.name}' is in both '${left.name}' and '${right.name}', so say which side: ` +
+          `'${t.name}(left)' or '${t.name}(right)'` + (left.name !== right.name ? `, or '${t.name}(${left.name})', '${t.name}(${right.name})'` : ''),
+      );
+    }
+    if (inL || inR) {
+      put(inL ? 'left' : 'right', t.name, t.nu);
+      continue;
+    }
+    const m = /^(.+)\(([^()]+)\)$/.exec(t.name);
+    if (m) {
+      const [, base, label] = m;
+      // The words left and right first; then a material's name, if it names one side only.
+      const side =
+        label === 'left' || label === 'right'
+          ? label
+          : label === left.name && label !== right.name
+            ? 'left'
+            : label === right.name && label !== left.name
+              ? 'right'
+              : null;
+      if (side) {
+        const at = side === 'left' ? left : right;
+        if (!at.holds(base)) fail(`${path}: '${base}' is absent from '${at.name}' (${side} of the face)`);
+        put(side, base, t.nu);
+        continue;
+      }
+    }
+    fail(
+      `${path}: '${t.name}' is in neither '${left.name}' nor '${right.name}'; if it's a fixed-activity neutral, give its μ in fixed` +
+        (/^\d+\D/.test(t.name) ? `; if ${t.name.match(/^\d+/)[0]} is a coefficient, put a space after it` : ''),
+    );
+  }
+  return sides;
+}
+
+/**
+ * A half-reaction: an equation with electrons `e-` on one side, and the μ (J/mol) of any
+ * participant that isn't a species (a fixed-activity neutral, such as a solid metal). It's plain
+ * data, `{ equation, fixed }`: spread it into a face reaction with its kinetics,
+ * `{ ...silver, k0: 1e-3 }`, or pass it to `level()`.
+ * @param {string} equation e.g. 'Ag+ + e- = Ag(s)'
+ * @param {Record<string, number>} [fixed] μ of the fixed participants, J/mol
+ * @returns {{ equation: string, fixed?: Record<string, number> }}
+ */
+export function half(equation, fixed) {
+  const terms = parseEquation(equation, 'half');
+  const electrons = terms.filter((t) => t.name === 'e-');
+  if (electrons.length !== 1) fail(`half: ${JSON.stringify(equation)} needs electrons, 'e-', on exactly one side`);
+  if (fixed !== undefined && !isObject(fixed)) fail('half: fixed must map participants to their μ (J/mol)');
+  for (const [name, mu] of Object.entries(fixed ?? {})) {
+    if (!terms.some((t) => t.name === name)) fail(`half: fixed.${name} isn't in ${JSON.stringify(equation)}`);
+    if (!Number.isFinite(mu)) fail(`half: fixed.${name} must be a finite μ (J/mol)`);
+  }
+  return fixed === undefined ? { equation } : { equation, fixed: { ...fixed } };
+}
+
+/**
+ * The standard hydrogen electrode, 2 H⁺ + 2 e⁻ ⇌ H₂, with μ(H₂) = 0 (the element in its standard
+ * state, on the usual table convention). Needs `H+` among the species.
+ */
+export const SHE = Object.freeze(half('2 H+ + 2 e- = H2', { H2: 0 }));
+
+/**
+ * The electronic level a half-reaction implies at each node, as an electron voltage
+ * V = −μ̄_e/F: where an electrode exchanging electrons by that reaction would sit in equilibrium
+ * with the local composition (the couple's redox level). With `standard: true`, every
+ * species is taken at its reference concentration (its standard level μ° + zFφ), so it's the
+ * standard level: for `SHE`, V°_e⁻(SHE) = φ + μ°_H⁺/F. `NaN` where a participant is absent.
+ * @param {{ mu: Record<string, ArrayLike<number>>, muStd: Record<string, ArrayLike<number>> }} sol a solution
+ * @param {{ equation: string, fixed?: Record<string, number> }} halfReaction from `half()`
+ * @param {{ standard?: boolean }} [opts]
+ * @returns {Float64Array}
+ */
+export function level(sol, halfReaction, { standard = false } = {}) {
+  if (!isObject(halfReaction)) fail('level: give a half-reaction from half()');
+  const { equation, fixed = {} } = halfReaction;
+  const terms = parseEquation(equation, 'level');
+  const source = standard ? sol.muStd : sol.mu;
+  let nuE = 0, fixedSum = 0;
+  const parts = [];
+  for (const t of terms) {
+    if (t.name === 'e-') nuE += t.nu;
+    else if (fixed[t.name] !== undefined) fixedSum += t.nu * fixed[t.name];
+    else if (source[t.name]) parts.push({ nu: t.nu, mu: source[t.name] });
+    else fail(`level: '${t.name}' is neither a species of the solution nor in the half-reaction's fixed`);
+  }
+  if (nuE === 0) fail(`level: ${JSON.stringify(equation)} has no net electrons`);
+  const n = sol.mu[Object.keys(sol.mu)[0]].length;
+  const V = new Float64Array(n);
+  for (let g = 0; g < n; g++) {
+    // Σ ν μ̄ = 0 at equilibrium, so μ̄_e = −(Σ_others ν μ̄)/ν_e.
+    let s = fixedSum;
+    for (const p of parts) s += p.nu * p.mu[g];
+    V[g] = s / (nuE * FARADAY);
+  }
+  return V;
+}

package/src/errors.js

@@ -0,0 +1,8 @@
+// The error a definition's validation throws, naming the offending path.
+
+export class DeviceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DeviceError';
+  }
+}

package/src/fermi.js

@@ -0,0 +1,106 @@
+// Complete Fermi–Dirac integrals of order 1/2 and −1/2, normalised so that 𝓕_j(x) → e^x as
+// x → −∞:
+//   𝓕_j(x) = (1/Γ(j+1)) ∫₀^∞ t^j / (1 + e^{t−x}) dt,   d𝓕_j/dx = 𝓕_{j−1}.
+// Relative accuracy ~1e-14 everywhere:
+//   x < −2       alternating series Σ (−1)^{k+1} e^{kx} / k^{j+1}
+//   −2 ≤ x ≤ 50  piecewise Chebyshev fits, built on first use from an exact quadrature
+//   x > 50       Sommerfeld's asymptotic expansion (its error is ~e^{−x})
+
+const INTERVALS = [-2, 1, 5, 12, 25, 50];
+const NCHEB = 24;
+const SQRT_PI = Math.sqrt(Math.PI);
+
+// Reference values by quadrature. With t = u² the integrand is even and smooth in u, so the
+// trapezoid rule converges geometrically; h = 0.02 already reaches round-off.
+function quadrature(j, x) {
+  const h = 0.02;
+  const umax = Math.sqrt(Math.max(x, 0) + 45);
+  const f = (u) => {
+    const p = j === 0.5 ? 2 * u * u : 2;
+    const e = u * u - x;
+    return e > 0 ? (p * Math.exp(-e)) / (1 + Math.exp(-e)) : p / (1 + Math.exp(e));
+  };
+  let s = f(0) / 2;
+  for (let k = 1; k * h <= umax; k++) s += f(k * h);
+  return (s * h) / (j === 0.5 ? SQRT_PI / 2 : SQRT_PI);
+}
+
+function chebFit(j, a, b) {
+  const v = new Float64Array(NCHEB);
+  for (let k = 0; k < NCHEB; k++) {
+    const t = Math.cos((Math.PI * (k + 0.5)) / NCHEB);
+    v[k] = quadrature(j, 0.5 * (a + b) + 0.5 * (b - a) * t);
+  }
+  const c = new Float64Array(NCHEB);
+  for (let m = 0; m < NCHEB; m++) {
+    let s = 0;
+    for (let k = 0; k < NCHEB; k++) s += v[k] * Math.cos((Math.PI * m * (k + 0.5)) / NCHEB);
+    c[m] = (2 / NCHEB) * s;
+  }
+  c[0] /= 2;
+  return c;
+}
+
+let fits = null; // [j = 1/2, j = −1/2] × intervals
+function tables() {
+  if (!fits) {
+    fits = [0.5, -0.5].map((j) => INTERVALS.slice(0, -1).map((a, k) => chebFit(j, a, INTERVALS[k + 1])));
+  }
+  return fits;
+}
+
+function clenshaw(c, a, b, x) {
+  const t = (2 * x - a - b) / (b - a);
+  let b1 = 0, b2 = 0;
+  for (let m = c.length - 1; m >= 1; m--) {
+    const tmp = 2 * t * b1 - b2 + c[m];
+    b2 = b1;
+    b1 = tmp;
+  }
+  return t * b1 - b2 + c[0];
+}
+
+function series(j, x) {
+  const e = Math.exp(x);
+  let term = e, s = 0;
+  for (let k = 1; k <= 40; k++) {
+    const t = term / k ** (j + 1);
+    s += k % 2 ? t : -t;
+    if (t < 1e-17 * s) break;
+    term *= e;
+  }
+  return s;
+}
+
+// η(2k) = (1 − 2^{1−2k}) ζ(2k), the Dirichlet eta function at even arguments.
+const ETA = [Math.PI ** 2 / 12, (7 * Math.PI ** 4) / 720, (31 * Math.PI ** 6) / 30240, 0.99623300185264789922, 0.99903950759827156564, 0.99975768514385819085];
+
+function asymptotic(j, x) {
+  // 𝓕_j(x) ~ x^{j+1}/Γ(j+2) · [1 + Σ_k 2η(2k) (j+1)(j)…(j+2−2k) x^{−2k}]
+  let s = 1, fall = 1;
+  const x2 = 1 / (x * x);
+  let p = 1;
+  for (let k = 1; k <= ETA.length; k++) {
+    fall *= (j + 1 - (2 * k - 2)) * (j + 1 - (2 * k - 1));
+    p *= x2;
+    s += 2 * ETA[k - 1] * fall * p;
+  }
+  const gamma = j === 0.5 ? (3 * SQRT_PI) / 4 : SQRT_PI / 2; // Γ(j + 2)
+  return (x ** (j + 1) / gamma) * s;
+}
+
+function fermi(j, x) {
+  if (x < INTERVALS[0]) return series(j, x);
+  if (x > INTERVALS[INTERVALS.length - 1]) return asymptotic(j, x);
+  const t = tables()[j === 0.5 ? 0 : 1];
+  let k = 0;
+  while (x > INTERVALS[k + 1]) k++;
+  return clenshaw(t[k], INTERVALS[k], INTERVALS[k + 1], x);
+}
+
+/** 𝓕_{1/2}(x), normalised so that it tends to e^x for x → −∞. */
+export const fermiHalf = (x) => fermi(0.5, x);
+/** 𝓕_{−1/2}(x) = d𝓕_{1/2}/dx. */
+export const fermiMinusHalf = (x) => fermi(-0.5, x);
+/** Reference quadrature, for tests. */
+export const fermiQuadrature = quadrature;

package/src/grid.js

@@ -0,0 +1,111 @@
+// 1D grid with graded spacing and doubled nodes at region boundaries.
+//
+// Each region gets its own run of nodes from its left end to its right end, so every region
+// boundary appears twice: the last node of region r and the first node of region r+1 sit at
+// the same x, joined by a zero-length "link" segment. Ordinary segments therefore always lie
+// inside a single region, and all material steps happen across links.
+//
+// Spacing grows geometrically (ratio `ratio`) from `hmin` at each region end, capped at
+// `hmax`, then is scaled so the cells fill the region exactly. A region may instead give its
+// cell widths outright (`cells`), as a metal region does: one cell, exact for Ohm's law.
+
+const DEFAULTS = Object.freeze({ ratio: 1.2, minCells: 8 });
+
+/**
+ * Cell widths for one region: fine at both ends, growing toward the middle.
+ * @param {number} length m
+ * @param {import('./types.js').GridOptions} [opts]
+ * @returns {number[]} widths summing to `length`
+ */
+export function gradedCells(length, { hmin, hmax, ratio = DEFAULTS.ratio, minCells = DEFAULTS.minCells, hLeft, hRight } = {}) {
+  if (!(length > 0)) throw new RangeError(`region length must be > 0, got ${length}`);
+  if (!(ratio >= 1)) throw new RangeError(`grid ratio must be ≥ 1, got ${ratio}`);
+  const cap = Math.min(hmax ?? length / minCells, length / minCells);
+  let hl = Math.min(hLeft ?? hmin ?? cap, cap);
+  let hr = Math.min(hRight ?? hmin ?? cap, cap);
+  if (!(hl > 0 && hr > 0)) throw new RangeError('grid spacing must be > 0');
+
+  const left = [], right = [];
+  let sum = 0;
+  // The tolerance stops round-off in the running sum from adding a sliver cell.
+  while (sum < length * (1 - 1e-12)) {
+    if (hl <= hr) {
+      left.push(hl);
+      sum += hl;
+      hl = Math.min(hl * ratio, cap);
+    } else {
+      right.push(hr);
+      sum += hr;
+      hr = Math.min(hr * ratio, cap);
+    }
+  }
+  const cells = left.concat(right.reverse());
+  const scale = length / sum;
+  for (let k = 0; k < cells.length; k++) cells[k] *= scale;
+  return cells;
+}
+
+/**
+ * Build the device grid.
+ * @param {{length: number, grid?: object, cells?: number[]}[]} regions in order, left to right
+ * @param {object} [opts] defaults for every region: { hmin, hmax, ratio, minCells }
+ */
+export function buildGrid(regions, opts = {}) {
+  if (!Array.isArray(regions) || regions.length === 0) throw new Error('grid needs at least one region');
+
+  const perRegion = regions.map((reg) => reg.cells ?? gradedCells(reg.length, { ...opts, ...(reg.grid ?? {}) }));
+  const nNodes = perRegion.reduce((s, cells) => s + cells.length + 1, 0);
+  const nSeg = nNodes - 1;
+
+  const x = new Float64Array(nNodes);
+  const nodeRegion = new Int32Array(nNodes);
+  const segLength = new Float64Array(nSeg);
+  const segRegion = new Int32Array(nSeg); // −1 for a link across a region boundary
+  const segFace = new Int32Array(nSeg); // face index for links, −1 otherwise
+  const vol = new Float64Array(nNodes); // box volume per unit area
+  const regionStart = new Int32Array(regions.length);
+  const regionEnd = new Int32Array(regions.length); // inclusive
+
+  let node = 0, x0 = 0;
+  for (let r = 0; r < regions.length; r++) {
+    const cells = perRegion[r];
+    regionStart[r] = node;
+    let xi = x0;
+    for (let k = 0; k <= cells.length; k++) {
+      x[node] = xi;
+      nodeRegion[node] = r;
+      if (k < cells.length) {
+        segLength[node] = cells[k];
+        segRegion[node] = r;
+        segFace[node] = -1;
+        vol[node] += cells[k] / 2;
+        vol[node + 1] += cells[k] / 2;
+        xi += cells[k];
+        node++;
+      }
+    }
+    // Pin the region's right end exactly, so the doubled node's x matches bit-for-bit.
+    x0 += regions[r].length;
+    x[node] = x0;
+    regionEnd[r] = node;
+    if (r < regions.length - 1) {
+      segLength[node] = 0;
+      segRegion[node] = -1;
+      segFace[node] = r;
+      node++;
+    }
+  }
+
+  return {
+    nNodes,
+    x,
+    nodeRegion,
+    segLength,
+    segRegion,
+    segFace,
+    vol,
+    regionStart,
+    regionEnd,
+    length: x0,
+  };
+}

package/src/index.js

@@ -0,0 +1,207 @@
+// driftlet: 1D drift–diffusion–reaction solver.
+
+import { normalizeDevice } from './device.js';
+import { Solver, SolverError } from './solver.js';
+import { makeSolution } from './solution.js';
+import { merge } from './merge.js';
+
+export { DeviceError, normalizeDevice } from './device.js';
+import { normalizeDrives } from './device.js';
+export { SolverError } from './solver.js';
+export { buildGrid, gradedCells } from './grid.js';
+export { BlockTridiagonal } from './blockTridiagonal.js';
+export { bernoulli, bernoulliDerivative } from './bernoulli.js';
+export * from './constants.js';
+
+// Whether two definitions differ only in their terminals' drives (V, I, R on the contacts and
+// ports). Functions (custom statistics) compare by identity.
+function sameExceptDrives(a, b) {
+  const drive = new Set(['V', 'I', 'R']);
+  const eq = (x, y, terminal) => {
+    if (x === y) return true;
+    if (typeof x !== 'object' || typeof y !== 'object' || x === null || y === null) return false;
+    if (Array.isArray(x) !== Array.isArray(y)) return false;
+    const keys = new Set([...Object.keys(x), ...Object.keys(y)]);
+    for (const k of keys) {
+      if (terminal && drive.has(k)) continue;
+      if (!eq(x[k], y[k], false)) return false;
+    }
+    return true;
+  };
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const k of keys) {
+    if (k === 'contacts') {
+      const ca = a.contacts ?? {}, cb = b.contacts ?? {};
+      for (const side of new Set([...Object.keys(ca), ...Object.keys(cb)])) if (!eq(ca[side] ?? {}, cb[side] ?? {}, true)) return false;
+    } else if (k === 'ports') {
+      const pa = a.ports ?? [], pb = b.ports ?? [];
+      if (pa.length !== pb.length || pa.some((p, i) => !eq(p, pb[i], true))) return false;
+    } else if (!eq(a[k], b[k], false)) return false;
+  }
+  return true;
+}
+
+/** @typedef {import('./types.js').DeviceDefinition} DeviceDefinition */
+/** @typedef {import('./types.js').Solution} Solution */
+
+export class Device {
+  /** @param {DeviceDefinition} def plain, serialisable device definition (see docs/device.md) */
+  constructor(def) {
+    this.def = def;
+    this.model = normalizeDevice(def);
+    this._solver = null;
+  }
+
+  /** The solver, built on first use (so construction only validates the definition). */
+  get solver() {
+    if (!this._solver) this._solver = new Solver(this.model);
+    return this._solver;
+  }
+
+  get grid() {
+    return this.model.grid;
+  }
+
+  /**
+   * Change part of the definition (deep-merged). 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).
+   * @param {object} patch a partial device definition, merged into the current one
+   * @returns {this}
+   */
+  set(patch) {
+    const def = merge(this.def, patch);
+    // Only the terminals' drives changed: update them in place, keeping the solver and its state
+    // (a step in a source restarts the time stepping's order, as at any discontinuity).
+    if (this._solver && sameExceptDrives(this.def, def)) {
+      this._redefineDrives(def);
+      return this;
+    }
+    // A rebuild. Everything that can fail (validation, building the solver) happens before the
+    // device changes, so a change that fails leaves it as it was.
+    const model = normalizeDevice(def);
+    const old = this._solver;
+    const solver = old ? new Solver(model) : null;
+    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);
+      solver.computeConcentrations();
+      solver.time = old.time;
+      solver.contactDEnd = old.contactDEnd;
+      solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)
+      // Floating terminals keep their voltages (a good start), where the terminals match.
+      if (old.terms.length === solver.terms.length) {
+        for (const k of solver.floating) if (old.terms[k].name === solver.terms[k].name) solver.termV[k] = old.termV[k];
+      }
+      // What each stretch conserves from here: a stretch that was closed and still is (same
+      // species, same regions) keeps its amount; any other (newly closed, split, merged, open)
+      // starts from what the carried state holds.
+      const key = (st) => `${st.species}:${st.regions[0]}-${st.regions[1]}`;
+      const before = new Map(old.stretches.map((st, k) => [key(st), k]));
+      solver.referenceAmounts = solver.stretches.map((st) => {
+        const k = before.get(key(st));
+        return k !== undefined && !old.stretches[k].connected && !st.connected ? old.referenceAmounts[k] + old.boundaryIntake[k] : solver.amount(st);
+      });
+      solver.boundaryIntake.fill(0);
+    }
+    return this;
+  }
+
+  // The definition def, which differs from the current one only in the terminals' drives: set
+  // them in place. (Validated before anything changes.)
+  _redefineDrives(def) {
+    const drives = normalizeDrives(def, this.model);
+    this.model.terminals.forEach((t, k) => (t.drive = drives[k]));
+    this.model.contacts.left.drive = drives[0];
+    this.model.contacts.right.drive = drives[1];
+    this.model.ports.forEach((p, k) => (p.drive = drives[2 + k]));
+    this.def = def;
+    this._solver.redrive();
+  }
+
+  /**
+   * Steady state (or equilibrium), warm-started from the current state. Doesn't advance time.
+   * @param {{ maxSteps?: number, tol?: number, continuation?: boolean }} [opts]
+   * @returns {Solution}
+   */
+  solve(opts) {
+    return makeSolution(this.solver, this.solver.solveSteady(opts));
+  }
+
+  /**
+   * Advance the transient by dt (s) with backward Euler. If Newton fails, the interval is
+   * split into smaller steps automatically; `substeps` in the result says how many.
+   * With `{ method: 'bdf2' }`, steps after the first use second-order BDF2.
+   * @param {number} dt s
+   * @param {{ method?: 'be' | 'bdf2' }} [opts]
+   * @returns {Solution}
+   */
+  step(dt, opts) {
+    return makeSolution(this.solver, this.solver.advance(dt, opts));
+  }
+
+  /**
+   * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
+   * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
+   * which), so an animation can call it once per frame; the step size carries over.
+   * @param {number} tEnd s
+   * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+   * @returns {Solution}
+   */
+  advance(tEnd, opts) {
+    return makeSolution(this.solver, this.solver.integrate(tEnd, opts));
+  }
+
+  /**
+   * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its
+   * held voltage is perturbed (or its driven current), the others keep their drives.
+   * Z = δV/δI with I into the device (Ω·m²).
+   * @param {ArrayLike<number>} frequencies Hz
+   * @param {{ terminal?: string, profiles?: boolean }} [opts] the terminal (default 'right'), and
+   *   whether to return complex profiles per frequency
+   * @returns {import('./types.js').ImpedanceResult}
+   */
+  impedance(frequencies, opts) {
+    const steady = this.solver.solveSteady();
+    if (!steady.converged) throw new SolverError('impedance: the steady state did not converge');
+    return this.solver.impedance(frequencies, opts);
+  }
+
+  /**
+   * A checkpoint of the definition and solver state, for `_rollback()` (the live wrapper keeps
+   * its last good state this way).
+   * @internal
+   */
+  _checkpoint() {
+    const solver = this.solver;
+    return { def: this.def, model: this.model, solver, snap: solver._snapshot(), solvedV: solver.solvedV, referenceAmounts: solver.referenceAmounts.slice() };
+  }
+
+  /**
+   * Back to a checkpoint taken on this device.
+   * @param {ReturnType<Device['_checkpoint']>} cp
+   * @internal
+   */
+  _rollback(cp) {
+    if (this._solver === cp.solver) this._redefineDrives(cp.def); // only drives changed since: restore them exactly
+    else {
+      this.def = cp.def;
+      this.model = cp.model;
+      this._solver = cp.solver;
+    }
+    cp.solver._restore(cp.snap);
+    cp.solver.solvedV = cp.solvedV;
+    cp.solver.referenceAmounts = cp.referenceAmounts.slice();
+  }
+
+  /**
+   * Snapshot of the current state.
+   * @returns {Solution}
+   */
+  solution() {
+    return makeSolution(this.solver);
+  }
+}