driftlet 0.2.0 → 0.4.0

package/README.md

@@ -31,7 +31,7 @@ The same equations go by different names in different fields. If your problem is
 | If you work on | you may call it | start from | checked against |
 |---|---|---|---|
 | Semiconductor devices | drift–diffusion, van Roosbroeck, quasi-Fermi levels, Scharfetter–Gummel; pn, Schottky, MOS, heterojunctions | [first example](#a-semiconductor-junction), [pn](https://markblundeberg.github.io/driftlet/demos/pn.html) and [MOS](https://markblundeberg.github.io/driftlet/demos/mos.html) demos, [`contacts`](test/contacts.test.js), [`metal`](test/metal.test.js) tests | exact built-in potential, Shockley J–V, depletion charge, MOS C–V |
-| Solar cells | photogeneration, radiative and SRH recombination | [solar demo](https://markblundeberg.github.io/driftlet/demos/solar.html), [`reactions`](test/reactions.test.js) test: generation is a reaction from a photon reservoir (uniform per material), SRH runs through explicit trap species | `J_sc = qG(L_n + L_p + W)`; Shockley J–V in the dark |
+| Solar cells | photogeneration, radiative and SRH recombination | [solar](https://markblundeberg.github.io/driftlet/demos/solar.html) and [organic (excitons)](https://markblundeberg.github.io/driftlet/demos/organic.html) demos, [`reactions`](test/reactions.test.js) and [`generation`](test/generation.test.js) tests: generation is a reaction from a photon reservoir (uniform, or Beer–Lambert with `photogeneration()`), SRH runs through explicit trap species | `J_sc = qG(L_n + L_p + W)`; J_sc under Beer–Lambert against collection theory; Shockley J–V in the dark |
 | Electrochemistry | Nernst–Planck, concentration polarization, limiting current, Butler–Volmer, Warburg, cyclic voltammetry, salt bridges and liquid junctions | [second example](#an-electrochemical-cell), [cyclic voltammetry](https://markblundeberg.github.io/driftlet/demos/redox.html), [Daniell cell](https://markblundeberg.github.io/driftlet/demos/daniell.html), [saturation](https://markblundeberg.github.io/driftlet/demos/saturation.html) and [impedance](https://markblundeberg.github.io/driftlet/demos/impedance.html) demos, [`circuit`](test/circuit.test.js), [`kinetics`](test/kinetics.test.js), [`impedance`](test/impedance.test.js) tests | `i_lim·tanh(V/4V_T)`, Butler–Volmer closed form, finite-length Warburg |
 | Batteries, intercalation | OCV, insertion hosts, chemical diffusion | [insertion demo](https://markblundeberg.github.io/driftlet/demos/insertion.html), [`statistics`](test/statistics.test.js) test | composition vs OCV, π²D/4L² relaxation |
 | Double layers, colloids | Poisson–Boltzmann, Gouy–Chapman–Stern, Debye screening, crowding (Bikerman) | [double-layer demo](https://markblundeberg.github.io/driftlet/demos/double-layer.html), [`equilibrium`](test/equilibrium.test.js) test | Gouy–Chapman charge and profile, Kilic–Bazant–Ajdari |
@@ -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.4.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).
 
@@ -146,7 +146,7 @@ them locally, serve the repository root (e.g. `python3 -m http.server`) and open
 | **Cyclic voltammetry**: a Fermi level against a redox level | **Daniell cell**: a real salt bridge, leaking, ion by ion | **Saturation**: Ag \| AgNO₃ \| Ag under a square wave, up to its limiting current |
 | [![impedance](demos/screenshots/impedance.png)](https://markblundeberg.github.io/driftlet/demos/impedance.html) | [![ion-exchange membrane](demos/screenshots/membrane.png)](https://markblundeberg.github.io/driftlet/demos/membrane.html) | [![double layer](demos/screenshots/double-layer.png)](https://markblundeberg.github.io/driftlet/demos/double-layer.html) |
 | **Impedance**: the Warburg arc, and the cell's small-signal response inside | **Ion-exchange membrane**: Donnan steps, ion by ion, against TMS theory | **Double layer**: dilute vs crowded ions, against closed forms |
-| [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) |  |  |
+| [![insertion host](demos/screenshots/insertion.png)](https://markblundeberg.github.io/driftlet/demos/insertion.html) | [![organic solar cell](demos/screenshots/organic.png)](https://markblundeberg.github.io/driftlet/demos/organic.html) |  |
 | **Intercalation host**: cycling between cutoffs against the OCV |  |  |
 
 ## How to think about it
@@ -205,8 +205,9 @@ current. Supported physics:
   COMSOL.
 - **Cross-diffusion.** Each species moves down its own μ̄ with its own D (the statistics can be
   non-ideal); there are no Stefan–Maxwell or Onsager cross terms beyond eddy mixing.
-- **Heat and optics.** Temperature is uniform. Generation is a reaction, uniform within a
-  material; there's no optical model or absorption profile. For those, see
+- **Heat and optics.** Temperature is uniform. Generation is a reaction, with Beer–Lambert
+  absorption as its profile at most; there's no optical model (reflection, interference,
+  photon recycling). For those, see
   [Driftfusion](https://github.com/barnesgroupICL/Driftfusion),
   [SIMsalabim](https://github.com/kostergroup/SIMsalabim) or
   [PyBaMM](https://github.com/pybamm-team/PyBaMM).
@@ -231,9 +232,13 @@ 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 |
+| Beer–Lambert photogeneration in an n⁺p cell | J_sc = qΦ∫αe^(−αx)η(x)dx with the emitter's, depletion layer's and base's collection, α from 1e3 to 1e7 /m on one coarse grid | 5e-4 (3e-3 in the emitter) |
+| Organic bilayer: excitons | J_sc from excitons diffusing to the donor/acceptor interface (Beer–Lambert, a blocking anode, the splitting reaction's finite velocity); V_oc from charge-transfer detailed balance | 5e-4; 1e-6 V |
 | 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 +293,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: [...], values: [...] }`, 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.
@@ -244,14 +256,20 @@ those materials.
 **Generation** is a reaction from a reservoir: photogeneration is
 $`\text{photon} \to \mathrm{e}^- + \mathrm{h}^+`$, with the photons a fixed participant whose $`\mu`$
 sits well above the gap, so that $`e^{-A/RT}`$ is negligible and the rate is `kf` itself, the
-generation rate (mol/(m³·s)). It's uniform within each material listed in `kf` (there's no optical
-absorption profile). The photons' $`\mu`$ is the honest part: light is a reservoir far from the
+generation rate (mol/(m³·s)). The photons' $`\mu`$ is the honest part: light is a reservoir far from the
 device's temperature, and the rate still vanishes at $`A = 0`$.
 
 ```js nocheck
 bulkReactions: [{ equation: 'photon = e- + h+', fixed: { photon: units.eV(3) }, kf: { Si: 0.1 } }]
 ```
 
+A rate constant can also vary with position: give it as a profile `{ x: [...], values: [...] }`
+against the device's x (the same tables as `c0`), piecewise linear and constant beyond its ends,
+used only at that material's nodes. Each node takes the profile's mean over its box (not its
+value at the node), so the total rate is exact on any grid: light absorbed within a fraction of
+a cell still generates what it should. The kit's `photogeneration()` writes Beer–Lambert
+absorption this way.
+
 ## Contacts
 
 A contact is an interface whose far side is an **outside phase with known levels**: think of it as

package/docs/kit.md

@@ -131,6 +131,17 @@ Helpers that write sources as plain data:
 - **`recombination({ material, tau, majority })`**: band-to-band recombination e⁻ + h⁺ ⇌ 0 as
   a bulk reaction, from the low-injection minority lifetime it gives at that majority density,
   $`k_f = 1/(\tau \cdot n_{\mathrm{maj}})`$.
+- **`photogeneration({ material, flux, alpha, mu, from, to, makes })`**: light absorbed as it goes in
+  (Beer–Lambert). A photon flux (mol/(m²·s); a power P at photon energy E is
+  $`P/(E N_A)`$) enters the material at x = `from` heading toward +x and generates pairs at
+  $`G(x) = \Phi\alpha e^{-\alpha(x - \mathrm{from})}`$ until `to`, the material's far end. It's
+  photon ⇌ e⁻ + h⁺ from a photon reservoir at $`\mu`$ = `mu` (J/mol, well above the gap, e.g.
+  `units.eV(3)`), with `kf` a profile against x. `makes` replaces the right-hand side: in an
+  organic semiconductor, light makes neutral excitons, `makes: 'X'`. The table generates exactly what the light
+  loses, $`\Phi(1 - e^{-\alpha(\mathrm{to} - \mathrm{from})})`$, and the solver averages it
+  over each node's box, so the total stays right on a grid coarser than $`1/\alpha`$ (where
+  carriers start within a cell still needs the grid). Light through several materials is one
+  call per material, each with the flux that reaches it.
 
 Read a transient at points inside the device with `advance(t, { probes })` (see the
 [device reference](device.md#using-a-device)). And `units` converts back out of SI for display:

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.4.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
@@ -45,7 +45,7 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   `EPS0`, `BOLTZMANN`, `ELEMENTARY_CHARGE`, `AVOGADRO` (there's no thermal-voltage constant:
   V_T = GAS_CONSTANT·T/FARADAY). `driftlet/kit`: `build`, `layer`, `ohmic`, `bath`, `half`,
   `level`, `SHE`, `describe`, `live`, `traces`, the sources (`pulse`, `square`, `triangle`, `ramp`,
-  `injector`, `recombination`), the data library (`aqueous`, `semiconductor`,
+  `injector`, `recombination`, `photogeneration`), the data library (`aqueous`, `semiconductor`,
   `metal`, `IONS`, …) and the vacuum-level helpers. `driftlet/plot`: `bandDiagram`, `levelChart`, `labelParts` (labels mark subscripts as `V_{e⁻}`).
 - **Reactions** are written as equations, `{ equation: 'e- + h+ = 0', kf: { Si: 1e8 } }`, in
   `new Device`, `build()` and `set()` alike. A coefficient is a number and a space (`2 e-`).
@@ -53,7 +53,9 @@ From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`.
   with c in mol/m³ (and 1e16 cm⁻³ is only 0.0166 mol/m³). Band-to-band recombination,
   `e- + h+ = 0`, gives a minority lifetime τ = 1/(kf·N) with N the majority density in mol/m³:
   `kf: 1e8` is τ ≈ 0.6 µs at 1e16 cm⁻³. Generation is a reaction from a reservoir, rate `kf` in
-  mol/(m³·s) (`units.perCm3` converts cm⁻³·s⁻¹ too). A face reaction's `k0` is in mol/(m²·s);
+  mol/(m³·s) (`units.perCm3` converts cm⁻³·s⁻¹ too); light absorbed as it goes in is
+  `photogeneration({ material, flux, alpha, mu: units.eV(3), from, to })` (flux in
+  mol/(m²·s), α in 1/m), a `kf` that varies with x. A face reaction's `k0` is in mol/(m²·s);
   its exchange current density is F·k0 per electron at the reference concentrations.
 
 ## Template: a semiconductor junction
@@ -219,6 +221,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: [...], values: [...] } }`, 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 +245,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.4.0/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@0.4.0/src/plot.js';
 
 const def = build({
   T: 300,
@@ -349,5 +358,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.4.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.values)) conc(`${path}.c0.${sname}.values`, Math.max(...c.values));
+      // 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].values);
     });
     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

@@ -55,6 +55,21 @@ function positive(v, path) {
   return v;
 }
 
+// A profile against the device's x: { x, values }, piecewise linear between its points and
+// constant beyond its ends (read with profileAt).
+function profile(v, path, what, ok, okText) {
+  fields(v, path, ['x', 'values']);
+  need(
+    Array.isArray(v.x) && Array.isArray(v.values) && v.x.length > 0 && v.x.length === v.values.length,
+    `${path} must be a profile { x, values }: two arrays of the same length, positions (m, the device's x) and ${what}`,
+  );
+  v.x.forEach((xk, k) => {
+    need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${path}.x must be finite and strictly increasing, but x[${k}] is ${JSON.stringify(xk)}`);
+  });
+  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${JSON.stringify(y)}`));
+  return { x: Float64Array.from(v.x), values: Float64Array.from(v.values) };
+}
+
 function nonNegative(v, path) {
   need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${JSON.stringify(v)}`);
   return v;
@@ -178,19 +193,23 @@ 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, values } against the device's x.
     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)) {
+          c0Profile[i] = profile(v, at, 'concentrations (mol/m³)', (ck) => ck > 0, `a concentration > 0 (mol/m³)${none}`);
+          continue;
+        }
+        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, values }, got ${JSON.stringify(v)}${none}`);
         c0[i] = v;
       }
     }
@@ -200,6 +219,7 @@ export function normalizeDevice(def) {
       length,
       fixedCharge,
       c0,
+      c0Profile,
       background,
       velocity,
       mixing,
@@ -311,11 +331,16 @@ function normalizeReaction(rdef, path, species, speciesIndex, materials, materia
   need(st.list.length > 0, `${path}: no mobile participants`);
   need(st.charge === 0, `${path}: charge is not balanced (Σ ν z = ${st.charge})`);
   need(isObject(rdef.kf), `${path}.kf must map material names to forward rate constants`);
-  const kf = new Float64Array(materials.length);
+  // Each a number, or a profile { x, values } against the device's x (e.g. absorption); kf[m]
+  // is then its largest value, which says whether the reaction runs in that material at all.
+  const kf = new Float64Array(materials.length), kfProfile = new Array(materials.length).fill(null);
   for (const [mname, v] of Object.entries(rdef.kf)) {
     need(materialIndex.has(mname), `${path}.kf.${mname}: unknown material`);
     const m = materialIndex.get(mname);
-    kf[m] = nonNegative(v, `${path}.kf.${mname}`);
+    if (isObject(v)) {
+      kfProfile[m] = profile(v, `${path}.kf.${mname}`, 'rate constants', (k) => k >= 0, 'a rate constant ≥ 0');
+      kf[m] = Math.max(...kfProfile[m].values);
+    } else kf[m] = nonNegative(v, `${path}.kf.${mname}`);
     for (const { i } of st.list) {
       need(materials[m].present[i], `${path}.kf.${mname}: '${species[i].name}' is absent from material '${mname}'`);
     }
@@ -327,6 +352,7 @@ function normalizeReaction(rdef, path, species, speciesIndex, materials, materia
     products,
     fixedA: st.fixedA, // fixed participants' share of A/RT
     kf,
+    kfProfile,
     // Species made only from (or turned only into) fixed reservoirs, such as photogeneration
     // from a photon reservoir: a source that can hold the device far from equilibrium.
     generation: st.nFixed > 0 && (reactants.length === 0 || products.length === 0),

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/kit.js

@@ -9,7 +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 { pulse, square, triangle, ramp, injector, recombination, photogeneration } 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

@@ -146,6 +146,38 @@ 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 profile's value at x (c0, kf): piecewise linear, constant beyond its ends.
+function profileAt({ x, values: 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]);
+}
+
+// A profile's mean over [a, b], exactly (its integral is piecewise quadratic).
+function profileMean(p, a, b) {
+  if (!(b > a)) return profileAt(p, a);
+  const { x, values: v } = p, last = x.length - 1;
+  // ∫ from x[0] to t.
+  const integral = (t) => {
+    if (t <= x[0]) return v[0] * (t - x[0]);
+    let sum = 0;
+    for (let k = 0; k < last; k++) {
+      if (t <= x[k + 1]) return sum + ((v[k] + profileAt(p, t)) / 2) * (t - x[k]);
+      sum += ((v[k] + v[k + 1]) / 2) * (x[k + 1] - x[k]);
+    }
+    return sum + v[last] * (t - x[last]);
+  };
+  return (integral(b) - integral(a)) / (b - a);
+}
 
 export class SolverError extends Error {
   constructor(message, details) {
@@ -324,8 +356,16 @@ export class Solver {
     this.dtNext = undefined;
 
     // Bulk reactions as flat participant lists: reactants with +ν, products with −ν.
+    // Each has its rate constant at every node: its material's, or its profile's mean over the
+    // node's box, so that what a sharply varying profile (strongly absorbed light) generates
+    // in all is exact on any grid.
+    const { x: gx, segLength } = model.grid;
     this.rxs = model.reactions.map((rx) => ({
       kf: rx.kf,
+      kfNode: Float64Array.from(gx, (x, g) => {
+        const m = this.nodeMaterial[g], p = rx.kfProfile[m];
+        return p ? profileMean(p, x - (g > 0 ? segLength[g - 1] : 0) / 2, x + (g < segLength.length ? segLength[g] : 0) / 2) : rx.kf[m];
+      }),
       generation: rx.generation,
       fixedA: rx.fixedA,
       sp: Int32Array.from([...rx.reactants, ...rx.products], (p) => p.i),
@@ -739,9 +779,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;
@@ -750,15 +790,22 @@ export class Solver {
     u.fill(0);
     this.uLo.fill(0);
     const eta = new Float64Array(n), cFix = new Float64Array(n), mode = new Int8Array(n); // 1 level, 2 amount
-    let phiHat = 0;
+    // φ̂ runs from the left: from a pinned (or gated) left contact's φ at its zero charge, else 0.
+    const leftPhi = model.contacts.left.phi;
+    let phiHat = leftPhi.type === 'pinned' || leftPhi.type === 'capacitive' ? (this.termV[0] - leftPhi.zeroCharge) / this.VT : 0;
     for (let r = 0; r < regions.length; r++) {
       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 φ.
@@ -777,7 +824,8 @@ export class Solver {
         } else if (!st.contactFed) {
           if (!(reg.c0[i] > 0)) {
             throw new SolverError(
-              `regions[${r}].c0.${species[i].name}: a species that doesn't reach a contact needs its initial concentration`,
+              `regions[${r}].c0.${species[i].name}: a species that doesn't reach a contact needs its initial concentration` +
+                (st.connected ? ' (reactions make and consume it, so this is only where the solve starts, not an amount it keeps: a tiny value will do)' : ', which fixes the amount it conserves'),
             );
           }
           mode[i] = 2;
@@ -819,7 +867,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 +878,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,19 +904,29 @@ 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);
+        // Out of reach (every responding carrier has one sign and nothing balances it, as in an
+        // undoped layer that holds only holes): keep the running φ̂ rather than run it to ±∞.
+        if (charge(lo) < 0 || charge(hi) > 0) return ph;
         for (let it = 0; it < 200 && hi - lo > 1e-12; it++) {
           const m = 0.5 * (lo + hi);
           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++) {
@@ -1240,18 +1300,18 @@ export class Solver {
   // (compensated) η. Reactants are consumed (+v·ν·r in their balance), products made (−v·ν·r).
   _bulkReactions(g, rxs) {
     const { n, M, u, uLo, res, c } = this, R = this.rix;
-    const b = this.blockOfNode[g], v = this.model.grid.vol[g], m = this.nodeMaterial[g];
+    const b = this.blockOfNode[g], v = this.model.grid.vol[g];
     const dr = this.dA;
     for (let x = 0; x < rxs.length; x++) {
       const rx = rxs[x];
-      let P = rx.generation ? rx.kf[m] * this.generationScale : rx.kf[m], aHi = rx.fixedA, aLo = 0;
+      let P = rx.generation ? rx.kfNode[g] * this.generationScale : rx.kfNode[g], aHi = rx.fixedA, aLo = 0;
       dr.fill(0); // ∂ ln P / ∂slot
       // Participants: reactants with ν > 0, then products with ν < 0.
       for (let p = 0; p < rx.sp.length; p++) {
         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 +1657,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 +2149,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 +2284,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/sources.js

@@ -101,3 +101,39 @@ export function recombination({ material, tau, majority } = {}) {
   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) } };
 }
+
+/**
+ * Photogeneration by light absorbed in a material (Beer–Lambert): a photon flux entering at x =
+ * `from` and travelling toward +x, generating pairs at G(x) = flux · α · e^{−α(x − from)} up to
+ * x = `to`. Written as photon ⇌ e⁻ + h⁺ (or whatever `makes` says, such as an exciton 'X') from a
+ * photon reservoir at μ = `mu` (J/mol; well above what it makes, so the rate is G itself), with
+ * kf as a profile against the device's x. The table is
+ * exact in what it generates in all (each segment's mean is the exponential's), and the solver
+ * averages it over each node's box, so the total is right on any grid.
+ * @param {{ material: string, flux: number, alpha: number, mu: number, from?: number, to: number, makes?: string }} opts
+ *   material name; photons absorbed, mol/(m²·s); absorption coefficient, 1/m; the photons' μ,
+ *   J/mol; where the light enters and where the material ends (m, the device's x); the
+ *   reaction's right-hand side (default 'e- + h+')
+ * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
+ */
+export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes = 'e- + h+' } = {}) {
+  need(typeof material === 'string', 'photogeneration: give the material, by name');
+  need(num(flux) && flux >= 0, `photogeneration: flux must be the photon flux ≥ 0 entering the material (mol/(m²·s)), got ${flux}`);
+  need(num(alpha) && alpha > 0, `photogeneration: alpha must be the absorption coefficient > 0 (1/m; 1/cm × 100), got ${alpha}`);
+  need(num(mu), `photogeneration: mu must be the photons' μ (J/mol), well above the gap: units.eV(3), say`);
+  need(typeof makes === 'string' && makes.trim() !== '', `photogeneration: makes must be what the light makes, as an equation's side ('e- + h+', 'X'), got ${makes}`);
+  need(num(from) && num(to) && to > from, `photogeneration: from and to must be positions with to > from (m, the device's x), got ${from} and ${to}`);
+  // Evenly spaced points, at most 0.05 absorption lengths apart, out to 50 of them (beyond,
+  // nothing is left), then `to`.
+  const depth = alpha * (to - from), reach = Math.min(depth, 50), n = Math.ceil(reach / 0.05), step = reach / n;
+  const taus = Array.from({ length: n + 1 }, (_, k) => k * step);
+  if (depth > 50) taus.push(depth);
+  // A straight line between two points of e^{−τ} encloses (Δτ/2)·coth(Δτ/2) times too much: each
+  // value is scaled back by that, so the total is the exponential's own (to ~Δτ⁴).
+  const fix = (step / 2) / Math.tanh(step / 2);
+  return {
+    equation: `photon = ${makes}`,
+    fixed: { photon: mu },
+    kf: { [material]: { x: taus.map((t) => from + t / alpha), values: taus.map((t) => (flux * alpha * Math.exp(-t)) / fix) } },
+  };
+}

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

@@ -51,14 +51,20 @@
  * @property {number} [hRight] right-end cell size, overriding hmin
  */
 
+/**
+ * A table against the device's x (m): piecewise linear between its points, constant beyond them.
+ * @typedef {{ x: number[], values: number[] }} Profile
+ */
+
 /**
  * @typedef {object} RegionDef
  * @property {string} material material name
  * @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 | Profile>} [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]
@@ -98,7 +104,8 @@
  * @property {Record<string, number>} [nu] signed stoichiometric coefficients (ν < 0 consumed)
  * @property {string} [equation] the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {Record<string, number>} kf forward rate constant per material name
+ * @property {Record<string, number | Profile>} kf forward rate constant per material name, or a
+ *   profile of it against the device's x (an absorption profile, for photogeneration)
  */
 
 /**

package/types/kit.d.ts

@@ -57,6 +57,6 @@ export type VacuumSide = {
 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 { pulse, square, triangle, ramp, injector, recombination } from "./sources.js";
+export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

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/sources.d.ts

@@ -100,3 +100,33 @@ export function recombination({ material, tau, majority }?: {
     equation: string;
     kf: Record<string, number>;
 };
+/**
+ * Photogeneration by light absorbed in a material (Beer–Lambert): a photon flux entering at x =
+ * `from` and travelling toward +x, generating pairs at G(x) = flux · α · e^{−α(x − from)} up to
+ * x = `to`. Written as photon ⇌ e⁻ + h⁺ (or whatever `makes` says, such as an exciton 'X') from a
+ * photon reservoir at μ = `mu` (J/mol; well above what it makes, so the rate is G itself), with
+ * kf as a profile against the device's x. The table is
+ * exact in what it generates in all (each segment's mean is the exponential's), and the solver
+ * averages it over each node's box, so the total is right on any grid.
+ * @param {{ material: string, flux: number, alpha: number, mu: number, from?: number, to: number, makes?: string }} opts
+ *   material name; photons absorbed, mol/(m²·s); absorption coefficient, 1/m; the photons' μ,
+ *   J/mol; where the light enters and where the material ends (m, the device's x); the
+ *   reaction's right-hand side (default 'e- + h+')
+ * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
+ */
+export function photogeneration({ material, flux, alpha, mu, from, to, makes }?: {
+    material: string;
+    flux: number;
+    alpha: number;
+    mu: number;
+    from?: number;
+    to: number;
+    makes?: string;
+}): {
+    equation: string;
+    fixed: Record<string, number>;
+    kf: Record<string, {
+        x: number[];
+        values: number[];
+    }>;
+};

package/types/types.d.ts

@@ -115,6 +115,13 @@ export type GridOptions = {
      */
     hRight?: number;
 };
+/**
+ * A table against the device's x (m): piecewise linear between its points, constant beyond them.
+ */
+export type Profile = {
+    x: number[];
+    values: number[];
+};
 export type RegionDef = {
     /**
      * material name
@@ -130,10 +137,11 @@ 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 | Profile>;
     /**
      * imposed flow toward +x, m/s, carrying every mobile species
      */
@@ -235,9 +243,10 @@ export type BulkReactionDef = {
      */
     fixed?: Record<string, number>;
     /**
-     * forward rate constant per material name
+     * forward rate constant per material name, or a
+     * profile of it against the device's x (an absorption profile, for photogeneration)
      */
-    kf: Record<string, number>;
+    kf: Record<string, number | Profile>;
 };
 /**
  * Contacts use the same laws as internal faces; the outside is a phase with known levels