driftlet 0.2.0 → 0.3.0

package/README.md

@@ -55,7 +55,7 @@ import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG str
 ```
 
 Or straight from a CDN in a page, pinned to a version:
-`https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
 TypeScript declarations ship in the package. Writing a demo with an LLM agent? Point it at
 [`llms.txt`](llms.txt).
 
@@ -231,9 +231,11 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | pn junction | exact built-in potential; depletion charge; short-diode J–V | 1e-12; 1%; 2e-3 |
 | Long pn diode with recombination | Shockley J–V incl. depletion recombination | 2e-3 |
 | Haynes–Shockley pulse | an injected hole packet's drift, spread and decay at the ambipolar μ*, D*, 1/τ*; nothing lost while it goes in | 2e-4; 1e-2; 2e-3 |
+| A packet laid down as a `c0` profile | the same rates from a Gaussian at t = 0: μ*E t, σ₀² + 2D*t, e^(−t/τ*) | 3e-4; 1e-2; 1e-3 |
 | Illuminated long pn diode | `J_sc = qG(L_n + L_p + W)` from a cold start; superposition at low injection | 5e-3; 1e-2 |
 | Schottky barrier (metal region \| n-Si) | surface density from the alignment; depletion charge | 5e-3; 2% |
 | Liquid junction, open circuit | cell EMF 2t₊(RT/F) ln(c₁/c₂); Planck diffusion potential | 1e-4 |
+| Salt diffusion mode from a `c0` profile | c̄ + a·sin(πx/2L) decaying at π²D/4L², D = 2D₊D₋/(D₊ + D₋) | 2e-5 |
 | Concentration polarization | `i = i_lim tanh(V/4V_T)`, incl. galvanostatic and load modes | 2e-4 |
 | Butler–Volmer electrode | Nernst equilibrium; mixed kinetic/diffusion closed form | 5e-4 |
 | Redox couple between inert electrodes | Nernst level of Fe³⁺/Fe²⁺; the couple's total conserved at equilibrium and under current | 1e-9; 1e-10 |
@@ -288,6 +290,8 @@ No dependencies. Tests use node's built-in runner (Node ≥ 22):
 npm test         # the validation suite
 npm run bench    # typical workloads against bench/baseline.json (--save to update it)
 npm run types    # TypeScript declarations from the JSDoc, into types/ (fetches TypeScript via npx)
+npm run smoke    # every demo in headless Chrome, every control to its extremes (CHROME=… to choose)
+npm run shots    # retake the demos' screenshots, each caught at a set state (tools/shots.js)
 ```
 
 Design notes and plans: [numerics](docs/numerics.md), [conventions](docs/conventions.md),

package/docs/device.md

@@ -97,11 +97,23 @@ regions: [
 
 - `fixedCharge`: immobile charge density (doping, ionomer), C/m³. Default 0. In an insertion
   host it's balanced by background electronic carriers.
-- `c0`: initial concentrations, mol/m³. Species connected to a contact start from that contact's
-  level and don't need it. Any other species (blocked everywhere, or only made and consumed by
+- `c0`: initial concentrations, mol/m³: the starting state of each species given. Species
+  connected to a contact don't need it (without it, they start from that contact's level). Any
+  other species (blocked everywhere, or only made and consumed by
   reactions) does: its `c0` fixes the amount it conserves. Concentrations are positive ($`\bar\mu`$ is
   logarithmic in them); to have none of a species in a region, leave it out of that region's
-  material. In a strictly neutral region, $`\sum z \cdot c_0`$ must be zero. Where nothing else sets
+  material. In a strictly neutral region, $`\sum z \cdot c_0`$ must be zero.
+  An entry can instead be a profile, `{ x: [...], c: [...] }`, against the device's x (m, not
+  the region's own), piecewise linear between its points and constant beyond its ends, so a
+  transient can start from a state it didn't simulate reaching: a packet already injected, a
+  gradient laid down. Skip `solve()`, which goes straight to the steady state, and `advance()`
+  from it. Species without a `c0` start from their contact's level, and $`\phi`$ is chosen node
+  by node for local neutrality, so a mobile counter-ion follows the profile (electrons follow an
+  injected hole packet); what the cold start leaves unbalanced settles within the first steps.
+  That fill-in is right in a quasi-neutral bulk (it's what dielectric relaxation would do), not
+  where the rest state carries charge: a packet laid into a junction starts with the junction
+  itself unformed.
+  For a spectator, the profile's integral is the amount it conserves. Where nothing else sets
   $`\phi`$ at the start, a region beside an electrode starts with the electrode's first reaction at
   equilibrium (the electrode at its open-circuit level); otherwise $`\phi`$ carries over from the
   left.

package/llms.txt

@@ -14,9 +14,9 @@ docs/conventions.md (signs and levels) and docs/data.md (the data library).
 From a CDN, pin the version:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -219,6 +219,13 @@ const tArrive = run.trace.t[k] - width / 2; // from the pulse's middle
 console.log(`peak at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ${units.toPerCm3(seen[k] - rest.c['h+'][0]).toExponential(1)} cm⁻³: μ_p ≈ ${(1e-3 / (E * tArrive) * 1e4).toFixed(0)} cm²/(V·s)`); // ≈ 1950 for the 1900 put in: a spreading, decaying pulse peaks a little early
 ```
 
+To start from a state instead of simulating how it got there (a packet already injected, a
+salt gradient laid down), give a region's `c0` a profile against the device's x:
+`c0: { 'h+': { x: [...], c: [...] } }`, piecewise linear. A given `c0` is the starting state,
+even for a species a contact feeds; species without one start at their contact's level, with φ
+made neutral node by node (electrons follow the holes). Then `advance()` without `solve()`, which would go straight to the steady
+state.
+
 Transients cost more where a carrier's density spans many decades (minority holes in silicon
 ahead of the pulse) and at strong injection (Δp near n₀); budget for that, or coarsen the grid.
 
@@ -236,9 +243,9 @@ a Web Worker.
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.2.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.3.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -349,5 +356,7 @@ has the long form):
   to write `2 e-`.
 - **Changing c0 with `set()`.** A carried state keeps what it holds; `c0` is only the starting
   composition. Make a new `Device` to start over from it.
+- **`solve()` before advancing from a `c0` profile.** It replaces the profile with the steady
+  state. Advance from the new `Device` directly. A profile's x is the device's, in m.
 - **An unresolved double layer.** If `sol.warnings` says so, refine the grid (`hmin` below the
   Debye length) or use a neutral model (`epsr: 0`, `phi: 'neutral'`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {
@@ -29,6 +29,8 @@
   "scripts": {
     "test": "node --test",
     "bench": "node bench/bench.js",
+    "smoke": "node tools/smoke.js",
+    "shots": "node tools/shots.js",
     "prepublishOnly": "npm test && npm run types",
     "types": "rm -rf types && npx -y -p typescript@5 tsc --allowJs --declaration --emitDeclarationOnly --target es2022 --module nodenext --moduleResolution nodenext --outDir types src/index.js src/kit.js src/plot.js"
   },

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/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

@@ -146,6 +146,21 @@ 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) {
@@ -739,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;
@@ -755,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 φ.
@@ -819,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++) {
@@ -829,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
@@ -854,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++) {
@@ -863,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++) {
@@ -1251,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];
@@ -1597,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);
@@ -2089,7 +2118,7 @@ export class Solver {
     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):
@@ -2224,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 };
     }

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]

package/types/pow.d.ts

@@ -0,0 +1,4 @@
+/** x^n for an integer n. */
+export function powi(x: any, n: any): any;
+/** x^y for x ≥ 0 and any real y. */
+export function powr(x: any, y: any): any;

package/types/solver.d.ts

@@ -120,9 +120,9 @@ export class Solver {
     /** η_i/RT that a fixed contact link imposes (or NaN if the link isn't fixed). */
     contactEta(side: any, i: any): number;
     /**
-     * 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(): void;
     _materialAt(mat: any, background: any, eta: any, mode: any, cFix: any, ph: any, zeta: any, cc: any): void;

package/types/types.d.ts

@@ -130,10 +130,14 @@ export type RegionDef = {
      */
     fixedCharge?: number;
     /**
-     * initial concentrations, mol/m³ (required for species
-     * not connected to a contact: it fixes the amount they conserve)
+     * 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
      */
-    c0?: Record<string, number>;
+    c0?: Record<string, number | {
+        x: number[];
+        c: number[];
+    }>;
     /**
      * imposed flow toward +x, m/s, carrying every mobile species
      */