driftlet 0.1.1 → 0.3.0

package/src/describe.js

@@ -65,13 +65,26 @@ export function unitWarnings(def) {
       if (sp.cRef !== undefined) conc(`${sp_}.cRef`, sp.cRef);
     }
   }
+  const regionX0 = [0];
+  for (const reg of def.regions ?? []) regionX0.push(regionX0.at(-1) + (isObject(reg) && reg.length > 0 ? reg.length : 0));
   (def.regions ?? []).forEach((reg, r) => {
     if (!isObject(reg)) return;
     const path = `regions[${r}]`;
     if (reg.length > 1) warn(`${path}.length`, `${num(reg.length)} m is over a metre; lengths are m (units.um, units.nm)`);
     if (reg.length > 0 && reg.length < 1e-10) warn(`${path}.length`, `${num(reg.length)} m is less than an atom; lengths are m`);
     if (Math.abs(reg.fixedCharge) > 1e10) warn(`${path}.fixedCharge`, `${num(reg.fixedCharge)} C/m³ is over 6e22 cm⁻³ of charge; fixedCharge is C/m³ (units.perCm3(N) * FARADAY)`);
-    for (const [sname, c] of Object.entries(reg.c0 ?? {})) conc(`${path}.c0.${sname}`, c);
+    for (const [sname, c] of Object.entries(reg.c0 ?? {})) {
+      if (!isObject(c)) {
+        conc(`${path}.c0.${sname}`, c);
+        continue;
+      }
+      if (Array.isArray(c.c)) conc(`${path}.c0.${sname}.c`, Math.max(...c.c));
+      // A profile is against the device's x, not the region's own.
+      const x0 = regionX0[r], x1 = x0 + reg.length;
+      if (Array.isArray(c.x) && c.x.length > 0 && (c.x.at(-1) < x0 || c.x[0] > x1)) {
+        warn(`${path}.c0.${sname}.x`, `the profile (x from ${num(c.x[0])} to ${num(c.x.at(-1))} m) misses the region (${num(x0)} to ${num(x1)} m); x is the device's, in m`);
+      }
+    }
   });
   const capacitance = (path, phi) => {
     if (isObject(phi) && phi.C > 10) warn(`${path}.phi.C`, `${num(phi.C)} F/m² is over 1000 µF/cm²; C is F/m² (1 µF/cm² = 0.01 F/m²)`);
@@ -129,7 +142,9 @@ export function describe(def) {
     // The screening concentration: Σ z²c from the initial composition, else the fixed charge's.
     let zzc = 0;
     species.forEach((sp, i) => {
-      if (mat.present[i] && Number.isFinite(reg.c0[i])) zzc += sp.z * sp.z * reg.c0[i];
+      if (!mat.present[i]) return;
+      if (Number.isFinite(reg.c0[i])) zzc += sp.z * sp.z * reg.c0[i];
+      else if (reg.c0Profile[i]) zzc += sp.z * sp.z * Math.max(...reg.c0Profile[i].c);
     });
     if (zzc === 0) zzc = Math.abs(reg.fixedCharge) / FARADAY;
     const Dmax = Math.max(0, ...species.map((sp, i) => (mat.present[i] && sp.z !== 0 ? mat.D[i] : 0)));

package/src/device.js

@@ -178,19 +178,33 @@ export function normalizeDevice(def) {
           'so it must have the opposite sign to that carrier',
       );
     }
-    // Initial composition: the starting state, and the conserved amount of any spectator.
+    // Initial composition: the starting state, and the conserved amount of any spectator. Each
+    // entry is a number, or a profile { x, c } against the device's x (piecewise linear, constant
+    // beyond its ends), which is the starting state even for a species a contact feeds.
     const c0 = new Float64Array(nSpecies).fill(NaN);
+    const c0Profile = new Array(nSpecies).fill(null);
     if (reg.c0 !== undefined) {
       need(isObject(reg.c0), `${path}.c0 must be an object mapping species names to concentrations`);
       for (const [sname, v] of Object.entries(reg.c0)) {
-        need(speciesIndex.has(sname), `${path}.c0.${sname}: unknown species '${sname}'${known(speciesIndex)}`);
+        const at = `${path}.c0.${sname}`;
+        need(speciesIndex.has(sname), `${at}: unknown species '${sname}'${known(speciesIndex)}`);
         const i = speciesIndex.get(sname);
-        need(mat.present[i], `${path}.c0.${sname}: '${sname}' is absent from material '${mat.name}'`);
-        need(
-          isFiniteNumber(v) && v > 0,
-          `${path}.c0.${sname} must be a concentration > 0 (mol/m³), got ${JSON.stringify(v)}; to have none of '${sname}' here, ` +
-            `leave it out of material '${mat.name}' (a region of another material without it, if it's present elsewhere)`,
-        );
+        need(mat.present[i], `${at}: '${sname}' is absent from material '${mat.name}'`);
+        const none = `; to have none of '${sname}' here, leave it out of material '${mat.name}' (a region of another material without it, if it's present elsewhere)`;
+        if (isObject(v)) {
+          fields(v, at, ['x', 'c']);
+          need(
+            Array.isArray(v.x) && Array.isArray(v.c) && v.x.length > 0 && v.x.length === v.c.length,
+            `${at} must be a profile { x, c }: two arrays of the same length, positions (m, the device's x) and concentrations (mol/m³)`,
+          );
+          v.x.forEach((xk, k) => {
+            need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${at}.x must be finite and strictly increasing, but x[${k}] is ${JSON.stringify(xk)}`);
+          });
+          v.c.forEach((ck, k) => need(isFiniteNumber(ck) && ck > 0, `${at}.c[${k}] must be a concentration > 0 (mol/m³), got ${JSON.stringify(ck)}${none}`));
+          c0Profile[i] = { x: Float64Array.from(v.x), c: Float64Array.from(v.c) };
+          continue;
+        }
+        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, c }, got ${JSON.stringify(v)}${none}`);
         c0[i] = v;
       }
     }
@@ -200,6 +214,7 @@ export function normalizeDevice(def) {
       length,
       fixedCharge,
       c0,
+      c0Profile,
       background,
       velocity,
       mixing,

package/src/fermi.js

@@ -6,6 +6,8 @@
 //   −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})
 
+import { powi, powr } from './pow.js';
+
 const INTERVALS = [-2, 1, 5, 12, 25, 50];
 const NCHEB = 24;
 const SQRT_PI = Math.sqrt(Math.PI);
@@ -64,7 +66,7 @@ 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);
+    const t = term / powr(k, j + 1);
     s += k % 2 ? t : -t;
     if (t < 1e-17 * s) break;
     term *= e;
@@ -73,7 +75,7 @@ function series(j, x) {
 }
 
 // η(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];
+const ETA = [powi(Math.PI, 2) / 12, (7 * powi(Math.PI, 4)) / 720, (31 * powi(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}]
@@ -86,7 +88,7 @@ function asymptotic(j, x) {
     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;
+  return (powr(x, j + 1) / gamma) * s;
 }
 
 function fermi(j, x) {

package/src/index.js

@@ -146,9 +146,12 @@ export class Device {
   /**
    * 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.
+   * which), so an animation can call it once per frame; the step size carries over. `probes`
+   * read a species at points inside the device after every accepted step, into `trace.probes`
+   * (one array per probe, alongside `trace.t`): what a detector at x sees.
    * @param {number} tEnd s
-   * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+   * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
+   *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {

package/src/kit.js

@@ -9,6 +9,7 @@ export { build, combine, layer, ohmic, bath } from './stack.js';
 export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
 export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
+export { pulse, square, triangle, ramp, injector, recombination } from './sources.js';
 export { describe, unitWarnings } from './describe.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
 

package/src/plot.js

@@ -13,6 +13,7 @@
 // rule on the page restyles them.
 
 import { traces } from './traces.js';
+import { powi } from './pow.js';
 
 // Colours by role, light and dark (validated together for colour-vision deficiency; line weight,
 // dash and the legend carry identity too). A role with more members than colours cycles.
@@ -83,7 +84,7 @@ const span = (label) => labelParts(label).reduce((n, p) => n + (p.sub ? 0.75 : 1
 
 function ticks(a, b, n) {
   const step0 = (b - a) / n;
-  const mag = 10 ** Math.floor(Math.log10(step0));
+  const mag = powi(10, Math.floor(Math.log10(step0)));
   const step = [1, 2, 5, 10].map((m) => m * mag).find((s) => s >= step0) ?? 10 * mag;
   const out = [];
   for (let t = Math.ceil(a / step) * step; t <= b + 1e-9 * step; t += step) out.push(Math.abs(t) < 1e-9 * step ? 0 : t);

package/src/pow.js

@@ -0,0 +1,24 @@
+// Powers that come out the same on every JavaScript engine. Math.pow (and **) doesn't: V8's
+// changed between Node 22 and 24 by an ulp here and there, even for integer exponents, which was
+// enough to flip a few accept/reject decisions in long adaptive transients. Integer exponents
+// go by repeated squaring, half-integers add a correctly rounded square root, and anything else
+// goes through exp and log (which agree across engine versions).
+
+/** x^n for an integer n. */
+export function powi(x, n) {
+  if (n < 0) return 1 / powi(x, -n);
+  let r = 1, b = x;
+  while (n > 0) {
+    if (n & 1) r *= b;
+    b *= b;
+    n >>= 1;
+  }
+  return r;
+}
+
+/** x^y for x ≥ 0 and any real y. */
+export function powr(x, y) {
+  if (Number.isInteger(y)) return powi(x, y);
+  if (Number.isInteger(2 * y)) return powi(x, (2 * y - 1) / 2) * Math.sqrt(x);
+  return x === 0 ? (y > 0 ? 0 : Infinity) : Math.exp(y * Math.log(x));
+}

package/src/solver.js

@@ -145,6 +145,22 @@ import { BlockTridiagonal, ComplexBlockTridiagonal } from './blockTridiagonal.js
 import { bernoulli, bernoulliDerivative } from './bernoulli.js';
 import { EPS0, FARADAY } from './constants.js';
 import { nextBreakpoint, sourceAt } from './device.js';
+import { DeviceError } from './errors.js';
+import { powi, powr } from './pow.js';
+
+// A c0 profile's value at x: piecewise linear, constant beyond its ends.
+function profileAt({ x, c }, at) {
+  if (at <= x[0]) return c[0];
+  const last = x.length - 1;
+  if (at >= x[last]) return c[last];
+  let lo = 0, hi = last;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if (x[mid] <= at) lo = mid;
+    else hi = mid;
+  }
+  return c[lo] + ((c[hi] - c[lo]) * (at - x[lo])) / (x[hi] - x[lo]);
+}
 
 export class SolverError extends Error {
   constructor(message, details) {
@@ -738,9 +754,9 @@ export class Solver {
   }
 
   /**
-   * Cold start. Species connected to a contact take that contact's level; spectators take
-   * their region's c0 (which fixes their conserved amount). φ in each region is then chosen
-   * for local neutrality, or continued across the interface dipole if nothing there responds.
+   * Cold start. Each species takes its region's c0 where one is given (for a spectator, it fixes
+   * the conserved amount), else its contact's level. φ in each region is then chosen for local neutrality (node by node where a
+   * profile varies), or continued across the interface dipole if nothing there responds.
    */
   initFromComposition() {
     const { model, n, M, u, z } = this;
@@ -754,10 +770,15 @@ export class Solver {
       if (r > 0) phiHat += interfaces[r - 1].dipole / this.VT;
       const reg = regions[r], mat = materials[reg.material];
       mode.fill(0);
+      const profiled = reg.c0Profile.some((p) => p !== null);
       for (let i = 0; i < n; i++) {
         if (!mat.present[i]) continue;
         const st = this.stretches[this.stretchOf[r * n + i]];
-        if (!st.contactFed && mat.conductor) {
+        if (reg.c0Profile[i] || reg.c0[i] > 0) {
+          // A given c0 is the starting state, even where a contact feeds the species.
+          mode[i] = 2;
+          cFix[i] = reg.c0Profile[i] ? profileAt(reg.c0Profile[i], grid.x[grid.regionStart[r]]) : reg.c0[i];
+        } else if (!st.contactFed && mat.conductor) {
           // A conductor away from the contacts: start uncharged, with its carrier's level in
           // equilibrium with the first reaction on its left face that takes it, else at the
           // running φ.
@@ -818,7 +839,8 @@ export class Solver {
         return q;
       };
       const responds = mode.some((m, i) => m === 1 && z[i] !== 0);
-      if (!responds && !mat.conductor && !mat.phiFree && mat.epsr === 0) {
+      const mustBalance = !responds && !mat.conductor && !mat.phiFree && mat.epsr === 0;
+      const checkNeutral = (where) => {
         // Strictly neutral, with every charged species' amount given: its c0 must be neutral.
         let q = reg.fixedCharge / FARADAY, scale = Math.abs(q);
         for (let i = 0; i < n; i++) {
@@ -828,11 +850,12 @@ export class Solver {
         }
         if (Math.abs(q) > 1e-9 * scale) {
           throw new SolverError(
-            `regions[${r}] (${reg.name}): its initial composition carries a net charge of ${q.toPrecision(3)} mol/m³ (Σ z·c0, with any fixed charge), ` +
+            `regions[${r}] (${reg.name}): its initial composition carries a net charge of ${q.toPrecision(3)} mol/m³${where} (Σ z·c0, with any fixed charge), ` +
               'but ε = 0 makes it strictly neutral; adjust c0 so that it balances',
           );
         }
-      }
+      };
+      if (mustBalance && !profiled) checkNeutral('');
       if (!mat.phiFree && !responds && mat.ideal && r > 0 && materials[regions[r - 1].material].conductor) {
         // Nothing here fixes φ, but an electrode on the left does: start with its first reaction
         // that takes a species from this side at equilibrium (the electrode at its open-circuit
@@ -853,8 +876,8 @@ export class Solver {
           }
         }
       }
-      if (!mat.phiFree && responds) {
-        let lo = phiHat - 1, hi = phiHat + 1;
+      const neutralPhi = (ph) => {
+        let lo = ph - 1, hi = ph + 1;
         while (charge(lo) < 0 && lo > -1e4) lo -= 2 * (hi - lo);
         while (charge(hi) > 0 && hi < 1e4) hi += 2 * (hi - lo);
         for (let it = 0; it < 200 && hi - lo > 1e-12; it++) {
@@ -862,10 +885,17 @@ export class Solver {
           if (charge(m) > 0) lo = m;
           else hi = m;
         }
-        phiHat = 0.5 * (lo + hi);
-      }
+        return 0.5 * (lo + hi);
+      };
+      if (!mat.phiFree && responds) phiHat = neutralPhi(phiHat);
       if (!mat.ideal) this._materialAt(mat, reg.background, eta, mode, cFix, phiHat, zeta, cc);
       for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        if (profiled) {
+          for (let i = 0; i < n; i++) if (reg.c0Profile[i]) cFix[i] = profileAt(reg.c0Profile[i], grid.x[g]);
+          if (mustBalance) checkNeutral(` at x = ${grid.x[g].toPrecision(4)} m`);
+          if (!mat.phiFree && responds) phiHat = neutralPhi(phiHat);
+          if (!mat.ideal) this._materialAt(mat, reg.background, eta, mode, cFix, phiHat, zeta, cc);
+        }
         const b = this.blockOfNode[g];
         u[b * M] = mat.conductor ? 0 : phiHat; // a metal's slot 0 is its segment flux
         for (let i = 0; i < n; i++) {
@@ -1250,7 +1280,7 @@ export class Solver {
         const i = rx.sp[p], nu = rx.nu[p];
         if (nu > 0) {
           const ci = c[g * n + i];
-          P *= nu === 1 ? ci : ci ** nu;
+          P *= nu === 1 ? ci : powi(ci, nu);
           this._dlnc(g, i, nu, dr);
         }
         aHi += nu * u[b * M + 1 + i];
@@ -1596,7 +1626,7 @@ export class Solver {
       aLo -= p.nu * uLo[o];
       if (this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
-      pref *= (c[g * n + p.i] / this.cRef[g * n + p.i]) ** e;
+      pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
     }
     const { g: bv, gp } = bvFactor(aHi + aLo, al);
@@ -1846,7 +1876,7 @@ export class Solver {
   }
 
   // Largest update among the potential-like unknowns (φ̂ and η at grid nodes).
-  _maxPotentialStep(delta, deltaV = this.deltaV) {
+  _maxPotentialStep(delta, deltaV = this.deltaV) { // (deltaV null: the device's potentials only)
     const { n, M } = this;
     const R = this.rix; // (the sink entry of delta is 0)
     let mx = 0;
@@ -1868,7 +1898,7 @@ export class Solver {
   newton(dt, { maxIter = 60, tol = 1e-10, maxStep = 10 } = {}) {
     const { delta, res } = this;
     const deltaV = this.deltaV ?? (this.deltaV = new Float64Array(this.floating.length));
-    const history = [];
+    const history = [], ownHistory = [];
     // A steady solve that fails: record how nearly singular the system was, and where.
     const fail = (r) => {
       if (dt === Infinity) this._noteConditioning();
@@ -1899,15 +1929,22 @@ export class Solver {
         if (!(err instanceof SolverError)) throw err;
         return fail({ converged: false, iterations: it, history, error: err.message });
       }
+      // Convergence counts every unknown, floating terminal voltages too. Damping and the
+      // divergence check count only the device's own potentials: a terminal voltage enters
+      // linearly (conductance links, held levels, a capacitive face), so a large swing in one is
+      // safe, and damping it would throttle the whole update (a current-driven port switching
+      // off, its voltage collapsing by hundreds of volts, crawled 10 thermal units at a time).
       const step = this._maxPotentialStep(delta, deltaV);
+      const own = this._maxPotentialStep(delta, null);
       history.push(step);
+      ownHistory.push(own);
       if (!Number.isFinite(step)) return fail({ converged: false, iterations: it, history, error: 'non-finite update' });
       // Give up early on clear divergence; the caller will take a smaller step instead.
-      if (step > 1e4 || (it > 6 && step > 10 * history[0])) {
+      if (own > 1e4 || (it > 6 && own > 10 * ownHistory[0])) {
         this.computeConcentrations();
         return fail({ converged: false, iterations: it, history, error: 'diverging' });
       }
-      const alpha = step > maxStep ? maxStep / step : 1;
+      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) {
@@ -2071,16 +2108,17 @@ export class Solver {
     const { tol = 1e-3, dtMax = Infinity, budgetMs = Infinity, maxSteps = 100000, method = 'bdf2' } = opts;
     const clock = () => (globalThis.performance ? globalThis.performance.now() : Date.now());
     const start = clock();
-    const trace = { t: [], current: [], voltage: [] };
+    const sample = this._probes(opts.probes);
+    const trace = { t: [], current: [], voltage: [], ...(sample ? { probes: sample.out } : {}) };
     let steps = 0, rejected = 0, iterations = 0, failed = false;
     // Already there (an animation frame with no time to add): nothing to do, and the step size
     // carried to the next call stays as it was.
-    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace: { t: [], current: [], voltage: [] } };
+    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace };
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
     let grow = 0; // longer first steps tried after a Newton failure (see below)
     const pred = new Float64Array(this.u.length), guess = new Float64Array(this.u.length);
-    const factor = (err, p) => (err > 0 ? Math.min(2, Math.max(0.2, 0.9 * (tol / err) ** (1 / (p + 1)))) : 2);
+    const factor = (err, p) => (err > 0 ? Math.min(2, Math.max(0.2, 0.9 * Math.exp(Math.log(tol / err) / (p + 1)))) : 2);
     while (this.time < tEnd) {
       if (steps + rejected >= maxSteps || clock() - start > budgetMs) break;
       // Within round-off of the end (a target a hair past a breakpoint just landed on, say):
@@ -2113,7 +2151,7 @@ export class Solver {
           this._restore(snap);
           const a = this.step(h / 2);
           // The first half step is kept too, so it goes in the trace (a jump's charge is in it).
-          half = a.converged ? { t: this.time, current: this._terminalCurrent(), voltage: this.termV[1] - this.termV[0] } : null;
+          half = a.converged ? { t: this.time, current: this._terminalCurrent(), voltage: this.termV[1] - this.termV[0], probes: sample?.read() } : null;
           const b = a.converged ? this.step(h / 2) : a;
           iterations += a.iterations + (b === a ? 0 : b.iterations);
           if (b.converged) {
@@ -2165,10 +2203,12 @@ export class Solver {
         trace.t.push(half.t);
         trace.current.push(half.current);
         trace.voltage.push(half.voltage);
+        if (sample) sample.push(half.probes);
       }
       trace.t.push(this.time);
       trace.current.push(this._terminalCurrent());
       trace.voltage.push(this.termV[1] - this.termV[0]);
+      if (sample) sample.push(sample.read());
     }
     this.dtNext = dt;
     this.landing = undefined;
@@ -2213,7 +2253,7 @@ export class Solver {
       const l2 = ((t - t0) * (t - t1)) / ((t2 - t0) * (t2 - t1));
       for (let k = 0; k < pred.length; k++) pred[k] = l0 * e0.u[k] + l1 * e1.u[k] + l2 * e2.u[k];
       const w = h / hp;
-      const Cc = (h ** 3 * (1 + w) ** 2) / (w * (1 + 2 * w));
+      const Cc = (h * h * h * (1 + w) * (1 + w)) / (w * (1 + 2 * w));
       const Cp = h * (h + hp) * (h + hp + hpp);
       return { scale: Cc / (Cc + Cp), order: 2 };
     }
@@ -2224,6 +2264,54 @@ export class Solver {
     return { scale: bdf ? 1 : h / (2 * h + hp), order: 1 };
   }
 
+  // Probes for a transient's trace: { x, species, quantity: 'c' | 'V', region } read after every
+  // accepted step, linearly between the two nodes of x's region around it. At an interface x
+  // belongs to both regions, so `region` (a name or index) picks the side; it defaults to the
+  // first region that holds x.
+  _probes(probes) {
+    if (probes === undefined) return null;
+    const { grid, regions, species } = this.model;
+    const fail = (m) => {
+      throw new DeviceError(m);
+    };
+    if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }');
+    const plan = probes.map((p, k) => {
+      const path = `advance: probes[${k}]`;
+      const i = species.findIndex((sp) => sp.name === p?.species);
+      if (i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
+      const quantity = p.quantity ?? 'c';
+      if (quantity !== 'c' && quantity !== 'V') fail(`${path}.quantity must be 'c' (mol/m³) or 'V' (the species voltage)`);
+      if (quantity === 'V' && species[i].z === 0) fail(`${path}: '${p.species}' is neutral, so it has no voltage; read 'c'`);
+      const x = grid.x, inside = (r) => p.x >= x[grid.regionStart[r]] && p.x <= x[grid.regionEnd[r]];
+      let r;
+      if (p.region !== undefined) {
+        r = typeof p.region === 'number' ? p.region : regions.findIndex((reg) => reg.name === p.region);
+        if (!(r >= 0 && r < regions.length)) fail(`${path}.region: no region ${JSON.stringify(p.region)}`);
+        if (!inside(r)) fail(`${path}.x (${p.x} m) is outside region ${JSON.stringify(p.region)}`);
+      } else {
+        r = regions.findIndex((_, rr) => inside(rr));
+        if (!(Number.isFinite(p.x) && r >= 0)) fail(`${path}.x must be a position in the device, in m (got ${p.x})`);
+      }
+      let g = grid.regionStart[r];
+      while (g + 1 < grid.regionEnd[r] && x[g + 1] < p.x) g++;
+      const w = x[g + 1] > x[g] ? (p.x - x[g]) / (x[g + 1] - x[g]) : 0;
+      return { i, g, w, quantity };
+    });
+    const out = plan.map(() => []);
+    const { n, M } = this;
+    const at = (q, g) => {
+      if (!this.present[g * n + q.i]) return NaN;
+      if (q.quantity === 'c') return this.c[g * n + q.i];
+      const o = this.blockOfNode[g] * M + 1 + q.i;
+      return (this.VT * (this.u[o] + this.uLo[o])) / this.z[q.i];
+    };
+    return {
+      out,
+      read: () => plan.map((q) => (1 - q.w) * at(q, q.g) + q.w * at(q, q.g + 1)),
+      push: (values) => values.forEach((v, k) => out[k].push(v)),
+    };
+  }
+
   // Largest difference from ref among the potentials that carry state, in thermal units.
   _errorNorm(ref) {
     const { n, M, u } = this;

package/src/sources.js

@@ -0,0 +1,103 @@
+// driftlet/kit: sources as plain definition data. Waveforms for a terminal's V or I, an injector
+// port, and band-to-band recombination from a lifetime. Each returns an ordinary spec value.
+
+import { DeviceError } from './errors.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const need = (ok, message) => ok || fail(message);
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * A rectangular pulse, as a waveform for a terminal's `V` or `I`: `base` until `start`, then
+ * `base + amplitude` for `width`, then `base` again. With a `rise` > 0 its edges are ramps of
+ * that length, placed so the area stays `amplitude · width`; without one they're jumps, which
+ * the time stepping handles exactly (so a pulse with no rise must start after t = 0, the time a
+ * device starts at and solve() reads: it's off then).
+ * @param {{ start?: number, width: number, amplitude: number, rise?: number, base?: number }} opts s, s, V or A/m², s, V or A/m²
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {}) {
+  need(num(width) && width > 0, `pulse: width must be > 0 (s), got ${width}`);
+  need(num(amplitude), `pulse: amplitude must be a finite number (V or A/m²), got ${amplitude}`);
+  need(num(start) && start >= 0, `pulse: start must be ≥ 0 (s), got ${start}`);
+  need(num(rise) && rise >= 0 && rise <= width, `pulse: rise must be between 0 and the width (s), got ${rise}`);
+  need(num(base), `pulse: base must be a finite number, got ${base}`);
+  need(rise > 0 || start > 0, 'pulse: with no rise, start after t = 0, so the device starts (and solve() reads it) before the pulse');
+  const top = base + amplitude;
+  return { t: [start, start + rise, start + width, start + width + rise], values: [base, top, top, base] };
+}
+
+/**
+ * A square wave, repeating: `high` for `duty · period`, then `low`, from t = 0.
+ * @param {{ high: number, low: number, period: number, duty?: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function square({ high, low, period, duty = 0.5 } = {}) {
+  need(num(high) && num(low), `square: high and low must be finite numbers, got ${high} and ${low}`);
+  need(num(period) && period > 0, `square: period must be > 0 (s), got ${period}`);
+  need(num(duty) && duty > 0 && duty < 1, `square: duty must be between 0 and 1, got ${duty}`);
+  const on = duty * period;
+  return { t: [0, on, on, period], values: [high, high, low, low], repeat: true };
+}
+
+/**
+ * A triangle wave, repeating: from `from` to `to` and back in each `period`, from t = 0 (a
+ * cyclic voltammogram's sweep, from its starting potential).
+ * @param {{ from: number, to: number, period: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function triangle({ from, to, period } = {}) {
+  need(num(from) && num(to), `triangle: from and to must be finite numbers, got ${from} and ${to}`);
+  need(num(period) && period > 0, `triangle: period must be > 0 (s), got ${period}`);
+  return { t: [0, period / 2, period], values: [from, to, from], repeat: true };
+}
+
+/**
+ * A ramp from `from` to `to` over `duration`, starting at `start`, constant on either side.
+ * @param {{ from: number, to: number, duration: number, start?: number }} opts
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function ramp({ from, to, duration, start = 0 } = {}) {
+  need(num(from) && num(to), `ramp: from and to must be finite numbers, got ${from} and ${to}`);
+  need(num(duration) && duration > 0, `ramp: duration must be > 0 (s), got ${duration}`);
+  need(num(start) && start >= 0, `ramp: start must be ≥ 0 (s), got ${start}`);
+  return { t: [start, start + duration], values: [from, to] };
+}
+
+/**
+ * A port that injects a species into a window of a region at a driven current `I` (A/m², a
+ * number or a waveform), spread evenly over the window. It's an ordinary port: driven by `I`,
+ * its terminal the species, linked by a conductance small enough that at the peak current the
+ * port sits `headroom` volts above the window's level of that species, so every node of the
+ * window takes the same share (like a current source). At I = 0 it still links the window,
+ * weakly.
+ * @param {{ name?: string, region: string | number, from: number, to: number, species: string,
+ *   I: number | { t: number[], values: number[], repeat?: boolean }, headroom?: number }} opts
+ * @returns {object} a port, for the definition's `ports`
+ */
+export function injector({ name = 'injector', region, from, to, species, I, headroom = 2.5 } = {}) {
+  need(region !== undefined, 'injector: give the region (its name or index)');
+  need(num(from) && num(to) && to > from, `injector: from and to must bound the window, in m from the region's left end (got ${from}, ${to})`);
+  need(typeof species === 'string', 'injector: give the species it injects, e.g. species: \'h+\'');
+  need(num(headroom) && headroom > 0, `injector: headroom must be > 0 (V), got ${headroom}`);
+  const peak = num(I) ? Math.abs(I) : Array.isArray(I?.values) && I.values.every(num) ? Math.max(...I.values.map(Math.abs)) : NaN;
+  need(Number.isFinite(peak), 'injector: I must be a current (A/m²) or a waveform { t, values }');
+  const G = peak > 0 ? peak / ((to - from) * headroom) : 1; // S/m³
+  return { name, region, from, to, terminal: species, species: { [species]: { type: 'conductance', G } }, I };
+}
+
+/**
+ * Band-to-band recombination e⁻ + h⁺ ⇌ 0 in a material, from the minority-carrier lifetime it
+ * should give at a majority density: kf = 1/(τ · majority). (The rate is kf (np − n_i²), so τ is
+ * the low-injection lifetime of whichever carrier is the minority.)
+ * @param {{ material: string, tau: number, majority: number }} opts material name, s, mol/m³
+ * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
+ */
+export function recombination({ material, tau, majority } = {}) {
+  need(typeof material === 'string', 'recombination: give the material, by name');
+  need(num(tau) && tau > 0, `recombination: tau must be > 0 (s), got ${tau}`);
+  need(num(majority) && majority > 0, `recombination: majority must be the majority carrier density > 0 (mol/m³; units.perCm3 converts), got ${majority}`);
+  return { equation: 'e- + h+ = 0', kf: { [material]: 1 / (tau * majority) } };
+}

package/src/statistics.js

@@ -16,6 +16,7 @@
 
 import { FARADAY, EPS0, AVOGADRO } from './constants.js';
 import { fermiHalf, fermiMinusHalf } from './fermi.js';
+import { powi } from './pow.js';
 import { SolverError } from './solver.js';
 
 const MODEL_TYPES = ['ideal', 'fermi-dirac', 'lattice', 'redlich-kister', 'debye-huckel', 'insertion', 'custom'];
@@ -189,7 +190,7 @@ function fermiDiracModel(idx, cRef, order) {
         const r = target[a] / cRef[a];
         // ln 𝓕(ζ) is increasing with slope 𝓕′/𝓕 ∈ (0, 1]
         const f = (y) => ({ v: Math.log(F(y)), d: dF(y) / F(y) });
-        const guess = r < 1 ? Math.log(r) : order === 0.5 ? Math.cbrt((0.75 * Math.sqrt(Math.PI) * r) ** 2) : r;
+        const guess = r < 1 ? Math.log(r) : order === 0.5 ? Math.cbrt(powi(0.75 * Math.sqrt(Math.PI) * r, 2)) : r;
         zeta[a] = solveIncreasing(f, Math.log(r), Math.log(r) - 1, Math.max(guess, Math.log(r)) + 10, guess);
       }
     },
@@ -264,7 +265,7 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
     let q = 0;
     for (let b = 0; b < k; b++) q += s[b] * c[b];
     const kappa = Math.sqrt((FARADAY * FARADAY * q) / (eps * RT));
-    const A = kappa > 0 ? (lB * FARADAY * FARADAY) / (4 * eps * RT * kappa * (1 + kappa * a) ** 2) : 0;
+    const A = kappa > 0 ? (lB * FARADAY * FARADAY) / (4 * eps * RT * kappa * (1 + kappa * a) * (1 + kappa * a)) : 0;
     let s2c = 0;
     for (let b = 0; b < k; b++) s2c += s[b] * s[b] * c[b];
     for (let b = 0; b < k; b++) lng[b] = (-s[b] * lB * kappa) / (2 * (1 + kappa * a));
@@ -425,7 +426,7 @@ function choleskyOk(K, k) {
   const L = Float64Array.from(K);
   for (let j = 0; j < k; j++) {
     let d = L[j * k + j];
-    for (let p = 0; p < j; p++) d -= L[j * k + p] ** 2;
+    for (let p = 0; p < j; p++) d -= L[j * k + p] * L[j * k + p];
     if (!(d > 0)) return false;
     d = Math.sqrt(d);
     L[j * k + j] = d;

package/src/types.js

@@ -57,8 +57,9 @@
  * @property {number} length m
  * @property {string} [name]
  * @property {number} [fixedCharge] immobile charge density, C/m³
- * @property {Record<string, number>} [c0] initial concentrations, mol/m³ (required for species
- *   not connected to a contact: it fixes the amount they conserve)
+ * @property {Record<string, number | { x: number[], c: number[] }>} [c0] initial concentrations,
+ *   mol/m³ (required for species not connected to a contact: it fixes the amount they conserve);
+ *   or a profile against the device's x (m), piecewise linear; either is the starting state
  * @property {number} [velocity] imposed flow toward +x, m/s, carrying every mobile species
  * @property {number} [mixing] eddy (turbulent) mixing diffusivity, m²/s; current-free
  * @property {GridOptions} [grid]
@@ -204,8 +205,9 @@
  * @property {number} time s
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
- * @property {{ t: number[], current: number[], voltage: number[] }} [trace] advance(): terminal
- *   current (A/m², toward +x) and voltage after each accepted step
+ * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] advance():
+ *   terminal current (A/m², toward +x) and voltage after each accepted step, and each probe's
+ *   reading (mol/m³, or V for quantity 'V'), interpolated between the nodes around its x
  */
 
 /**

package/types/constants.d.ts

@@ -30,4 +30,14 @@ export const units: Readonly<{
     um: (x: any) => number;
     /** cm²/s → m²/s */
     cm2PerS: (x: any) => number;
+    /** mol/m³ → mol/L */
+    toMolar: (x: any) => number;
+    /** mol/m³ → particles per cm³ */
+    toPerCm3: (x: any) => number;
+    /** m → nm */
+    toNm: (x: any) => number;
+    /** m → µm */
+    toUm: (x: any) => number;
+    /** m²/s → cm²/s */
+    toCm2PerS: (x: any) => number;
 }>;