driftlet 0.3.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.3.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).
@@ -232,6 +233,8 @@ Every physics feature is tested against analytic results (`npm test`, node's bui
 | 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 |

package/docs/device.md

@@ -103,7 +103,7 @@ regions: [
   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.
-  An entry can instead be a profile, `{ x: [...], c: [...] }`, against the device's x (m, not
+  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()`
@@ -256,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.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';
+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
@@ -221,7 +223,7 @@ console.log(`peak at ${(run.trace.t[k] * 1e6).toFixed(2)} µs, Δp ${units.toPer
 
 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,
+`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.
@@ -243,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.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';
+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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Small, dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for interactive web demos",
   "type": "module",
   "exports": {

package/src/describe.js

@@ -78,7 +78,7 @@ export function unitWarnings(def) {
         conc(`${path}.c0.${sname}`, c);
         continue;
       }
-      if (Array.isArray(c.c)) conc(`${path}.c0.${sname}.c`, Math.max(...c.c));
+      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)) {
@@ -144,7 +144,7 @@ export function describe(def) {
     species.forEach((sp, 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);
+      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;
@@ -179,8 +194,7 @@ export function normalizeDevice(def) {
       );
     }
     // 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.
+    // 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) {
@@ -192,19 +206,10 @@ export function normalizeDevice(def) {
         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) };
+          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, c }, got ${JSON.stringify(v)}${none}`);
+        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;
       }
     }
@@ -326,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}'`);
     }
@@ -342,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/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/solver.js

@@ -148,8 +148,8 @@ 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) {
+// 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];
@@ -162,6 +162,23 @@ function profileAt({ x, c }, at) {
   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) {
     super(message);
@@ -339,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),
@@ -765,7 +790,9 @@ 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];
@@ -797,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;
@@ -880,6 +908,9 @@ export class Solver {
         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;
@@ -1269,11 +1300,11 @@ 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++) {

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

@@ -51,13 +51,18 @@
  * @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 | { x: number[], c: number[] }>} [c0] initial concentrations,
+ * @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
@@ -99,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/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
@@ -134,10 +141,7 @@ export type RegionDef = {
      * 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 | {
-        x: number[];
-        c: number[];
-    }>;
+    c0?: Record<string, number | Profile>;
     /**
      * imposed flow toward +x, m/s, carrying every mobile species
      */
@@ -239,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