driftlet 0.6.0 → 0.8.0

package/src/checks.js

@@ -65,7 +65,7 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
   // The rest checks a solution, which an unconverged state isn't.
   if (sol.converged) {
     const ledger = steady ? balance(device, sol) : null;
-    items.push(ledger ?? conservation(sol));
+    items.push(ledger ?? conservation(sol, Math.max(...device.model.grid.area)));
     if (steady && refine) items.push(gridCheck(device, sol, tol, ledger.details.gross));
   }
 
@@ -78,33 +78,67 @@ export function check(device, sol, { refine = true, tol = 1e-2 } = {}) {
 // Each species' steady ledger: in through the terminals, made by the reactions. Rates in
 // mol/(m²·s), positive into the device or made.
 function balance(device, sol) {
-  const { model, def } = device, { species } = model;
+  const { model, def } = device, { species, regions, interfaces } = model;
   const label = (rdef) => rdef?.equation ?? JSON.stringify(rdef?.nu ?? rdef);
-  const ledgers = species.map((sp) => ({ species: sp.name, z: sp.z, terms: [] }));
-  const add = (i, what, rate) => {
-    if (rate !== 0 && Number.isFinite(rate)) ledgers[i].terms.push({ what, rate });
+  // Each species' compartments: runs of regions it's present in, joined by faces it crosses
+  // freely (in equilibrium). A face it crosses only by a law (a permeability, a conductance) or
+  // by a reaction divides them, and what crosses there is a term in each side's ledger.
+  const ledgers = [], home = species.map(() => new Int32Array(regions.length).fill(-1));
+  species.forEach((sp, i) => {
+    let open = null;
+    regions.forEach((reg, r) => {
+      if (!model.materials[reg.material].present[i]) return void (open = null);
+      if (open && interfaces[r - 1].links[i].type === 'equilibrium') open.regions.push(r);
+      else ledgers.push((open = { species: sp.name, z: sp.z, i, regions: [r], terms: [] }));
+      home[i][r] = ledgers.length - 1;
+    });
+  });
+  const add = (i, r, what, rate) => {
+    const l = home[i][r];
+    if (!(l >= 0 && rate !== 0 && Number.isFinite(rate))) return;
+    const same = ledgers[l].terms.find((t) => t.what === what); // a bulk reaction, region by region
+    if (same) same.rate += rate;
+    else ledgers[l].terms.push({ what, rate });
   };
+  const last = regions.length - 1;
   species.forEach((sp, i) => {
-    add(i, 'left contact', sol.contacts.left.flux[sp.name]);
-    add(i, 'right contact', -sol.contacts.right.flux[sp.name]);
-    sol.ports.forEach((p) => add(i, `port ${p.name}`, p.flux[sp.name]));
+    add(i, 0, 'left contact', sol.contacts.left.flux[sp.name]);
+    add(i, last, 'right contact', -sol.contacts.right.flux[sp.name]);
+    model.ports.forEach((port, k) => add(i, port.region, `port ${sol.ports[k].name}`, sol.ports[k].flux[sp.name]));
   });
   model.reactions.forEach((rx, k) => {
-    const total = sol.bulkReactions[k].total, what = label(def.bulkReactions?.[k]);
-    for (const { i, nu } of rx.reactants) add(i, what, -nu * total);
-    for (const { i, nu } of rx.products) add(i, what, nu * total);
+    const what = label(def.bulkReactions?.[k]);
+    sol.bulkReactions[k].regions.forEach((total, r) => {
+      for (const { i, nu } of rx.reactants) add(i, r, what, -nu * total);
+      for (const { i, nu } of rx.products) add(i, r, what, nu * total);
+    });
   });
-  model.interfaces.forEach((itf, f) => {
+  interfaces.forEach((itf, f) => {
+    // Across the face, where it divides a species' compartments.
+    species.forEach((sp, i) => {
+      const type = itf.links[i].type;
+      if (type === 'equilibrium' || type === 'blocked') return;
+      const N = sol.interfaces[f].N[sp.name];
+      add(i, f, `across face ${f} (${type})`, -N);
+      add(i, f + 1, `across face ${f} (${type})`, N);
+    });
     itf.reactions.forEach((rx, k) => {
       const rate = sol.interfaces[f].rates[k], what = `${label(def.interfaces?.[f]?.reactions?.[k])} at face ${f}`;
-      for (const { i, nu } of rx.part) add(i, what, nu * rate);
+      for (const { i, nu, side } of rx.part) add(i, f + side, what, nu * rate);
     });
   });
+  // A species in one compartment is named alone; one in several, by where.
+  const several = species.map((_, i) => ledgers.filter((l) => l.i === i).length > 1);
+  for (const l of ledgers) {
+    const names = l.regions.map((r) => sol.regions[r].name);
+    l.compartment = names.length === 1 ? names[0] : `${names[0]} to ${names.at(-1)}`;
+    l.title = several[l.i] ? `${l.species} in ${l.compartment}` : l.species;
+  }
 
   // A species at rest (nothing beyond round-off moving, against what it could carry) isn't reported.
   const size = (l) => Math.max(0, ...l.terms.map((t) => Math.abs(t.rate)));
   const natural = naturalScales(device, sol);
-  const moving = ledgers.filter((l, i) => size(l) > 1e-9 * natural[i]);
+  const moving = ledgers.filter((l) => size(l) > 1e-9 * natural[l.i]);
   let worst = 0;
   const lines = [];
   for (const l of moving) {
@@ -114,13 +148,13 @@ function balance(device, sol) {
     // Terms that matter, largest first; a charged species' as a current too.
     const shown = l.terms.filter((t) => Math.abs(t.rate) > 1e-6 * size(l)).sort((a, b) => Math.abs(b.rate) - Math.abs(a.rate));
     const amp = (r) => (l.z !== 0 ? ` (${sig(FARADAY * Math.abs(l.z) * r)} A/m²)` : '');
-    lines.push(`${l.species}: ${shown.map((t) => `${t.what}: ${t.rate > 0 ? '+' : ''}${sig(t.rate)}${amp(t.rate)}`).join('; ')}`);
+    lines.push(`${l.title}: ${shown.map((t) => `${t.what}: ${t.rate > 0 ? '+' : ''}${sig(t.rate)}${amp(t.rate)}`).join('; ')}`);
   }
   const ok = worst < 1e-6;
   const summary =
     moving.length === 0
       ? 'nothing flows or reacts (equilibrium)'
-      : `${moving.length} species' sources and sinks sum to zero ${ok ? `(to ${sig(worst, 1)})` : `only to ${sig(worst, 2)}: not a steady state`}; mol/(m²·s), + in or made`;
+      : `${moving.length === 1 ? 'one ledger sums' : `${moving.length} ledgers sum`} to zero ${ok ? `(to ${sig(worst, 1)})` : `only to ${sig(worst, 2)}: not a steady state`}: each species' sources and sinks, mol/(m²·s), + in or made`;
   // The largest current any charged species carries anywhere: the scale a net current is read against.
   const gross = Math.max(0, ...moving.filter((l) => l.z !== 0).map((l) => FARADAY * Math.abs(l.z) * size(l)));
   return { name: 'balance', ok, summary, details: { ledgers, worst, lines, gross } };
@@ -130,26 +164,27 @@ function balance(device, sol) {
 // carrier, σRT/(z²F²L)), and by its bulk reactions, their one-way rates. In equilibrium the net
 // flows are round-off of these.
 function naturalScales(device, sol) {
-  const { model, solver } = device, { species } = model;
-  const box = (g) => ((g > 0 && sol.region[g - 1] === sol.region[g] ? sol.x[g] - sol.x[g - 1] : 0) + (g + 1 < sol.x.length && sol.region[g + 1] === sol.region[g] ? sol.x[g + 1] - sol.x[g] : 0)) / 2;
+  const { model, solver } = device, { species, grid } = model;
+  // (totals through the cross-section, as the ledgers are: its largest in each region)
+  const area = model.regions.map((_, r) => Math.max(...grid.area.subarray(grid.regionStart[r], grid.regionEnd[r] + 1)));
   return species.map((sp, i) => {
     let S = 0;
     model.regions.forEach((reg, r) => {
       const mat = model.materials[reg.material], L = reg.length;
       if (mat.conductor) {
-        if (mat.conductor.i === i) S = Math.max(S, (mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
+        if (mat.conductor.i === i) S = Math.max(S, (area[r] * mat.conductor.sigma * model.RT) / (sp.z * sp.z * FARADAY * FARADAY * L));
         return;
       }
       if (!mat.present[i] || !(mat.D[i] > 0)) return;
       let cmax = 0;
       for (let g = 0; g < sol.x.length; g++) if (sol.region[g] === r && Number.isFinite(sol.c[sp.name][g])) cmax = Math.max(cmax, sol.c[sp.name][g]);
-      S = Math.max(S, (mat.D[i] * cmax) / L);
+      S = Math.max(S, (area[r] * mat.D[i] * cmax) / L);
     });
     solver.rxs.forEach((rx) => {
       const p = rx.sp.indexOf(i);
       if (p < 0) return;
       let gross = 0;
-      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += box(g) * solver.bulkOneWay(rx, g);
+      for (let g = 0; g < sol.x.length; g++) if (rx.kf[solver.nodeMaterial[g]] > 0) gross += grid.vol[g] * solver.bulkOneWay(rx, g);
       S = Math.max(S, Math.abs(rx.nu[p]) * gross);
     });
     return S;
@@ -157,12 +192,12 @@ function naturalScales(device, sol) {
 }
 
 // Closed, unreacting stretches keep their amounts in a transient.
-function conservation(sol) {
+function conservation(sol, area = 1) {
   const closed = sol.conservation.filter((st) => !st.connected && !st.reactive);
   if (closed.length === 0) return { name: 'conservation', ok: true, summary: 'nothing closed to conserve (every species reaches a terminal or reacts)' };
   // Relative to the amount, but a drift below 1e-20 mol/m² (1e-15 C/m²) is nothing: a floating
-  // metal's excess electrons are themselves ~0.
-  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 ? 0 : Math.abs(st.drift))));
+  // metal's excess electrons are themselves ~0. (Amounts are totals through the cross-section.)
+  const worst = Math.max(...closed.map((st) => (Math.abs(st.amount - st.reference - st.intake) < 1e-20 * area ? 0 : Math.abs(st.drift))));
   return {
     name: 'conservation',
     ok: worst < 1e-8,

package/src/describe.js

@@ -125,6 +125,11 @@ export function describe(def) {
   const warnings = unitWarnings(def);
   const total = grid.x[grid.x.length - 1] - grid.x[0];
   lines.push(`${regions.length} region${regions.length > 1 ? 's' : ''}, ${si(total, 'm')}, ${grid.x.length} nodes, T = ${model.T} K`);
+  const geo = model.geometry;
+  if (geo.type !== 'planar') {
+    const shape = geo.type === 'profile' ? `a cross-section from ${num(Math.min(...grid.area))} to ${num(Math.max(...grid.area))} m²` : `${geo.type} shells, r = ${si(geo.r0, 'm')} + x${geo.type === 'cylindrical' ? ' (per metre of length)' : ''}`;
+    lines.push(`geometry: ${shape}; currents and fluxes are totals through it (A, mol/s)`);
+  }
   lines.push(`species: ${species.map((sp) => `${sp.name} (z = ${sp.z > 0 ? '+' : ''}${sp.z})`).join(', ')}`);
 
   lines.push('regions:');
@@ -186,8 +191,15 @@ export function describe(def) {
       const law = itf.phi.type === 'capacitive' ? `capacitive, C = ${num(itf.phi.C)} F/m²` : itf.phi.type;
       const align = itf.conductor ? (itf.phi.type === 'capacitive' ? `, zeroCharge ${num(itf.zeroCharge)} V` : '') : itf.phi.type === 'neutral' ? '' : `, dipole ${num(itf.dipole)} V`;
       const blocked = species.filter((sp, i) => itf.links[i].type === 'blocked' && materials[L.material].present[i] && materials[R.material].present[i]).map((sp) => sp.name);
-      const rx = (idef.reactions ?? []).map((r) => r.equation ?? equation(r.left, r.right));
-      lines.push(`  ${L.name} | ${R.name}: ${law}${align}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}`);
+      const kinetics = (r) => (r.vmax !== undefined ? ` (saturating, vmax ${num(r.vmax)} mol/(m²·s))` : r.srh ? ' (SRH)' : '');
+      const rx = (idef.reactions ?? []).map((r) => (r.equation ?? equation(r.left, r.right)) + kinetics(r));
+      const laws = species.flatMap((sp, i) => {
+        const l = itf.links[i];
+        return l.type === 'permeability' ? [`${sp.name} ${num(l.P)} m/s`] : l.type === 'conductance' ? [`${sp.name} ${num(l.G)} S/m²`] : [];
+      });
+      lines.push(
+        `  ${L.name} | ${R.name}: ${law}${align}${laws.length ? `; crossing by a law: ${laws.join(', ')}` : ''}${blocked.length ? `; blocked: ${blocked.join(', ')}` : ''}${rx.length ? `; reactions: ${rx.join('; ')}` : ''}`,
+      );
     });
   }
 
@@ -199,7 +211,13 @@ export function describe(def) {
     const term = ct.terminal === null ? '' : ` (terminal ${species[ct.terminal].name})`;
     lines.push(`  ${side}: ${drive(cdef)}${term}; ${linked.length ? `exchanges ${linked.join(', ')}` : 'exchanges nothing'}; φ ${ct.phi.type}`);
   }
-  (def.ports ?? []).forEach((p, k) => lines.push(`  port ${model.ports[k].name}: ${drive(p)}, in ${regions[model.ports[k].region].name}`));
+  (def.ports ?? []).forEach((p, k) => {
+    const port = model.ports[k];
+    lines.push(`  port ${port.name}: ${drive(p)}, in ${regions[port.region].name}`);
+    // an electrode spread through the window
+    if (port.reactions.length) lines.push(`    an electrode (its ${species[port.terminal].name} at the port's level), ${typeof p.area === 'number' ? `${p.area} m²` : 'a profile of m²'} of it per m³, reacting:`);
+    for (const rx of p.reactions ?? []) lines.push(`      ${rx.equation}: k0 ${rx.k0} mol/(m²·s), α ${rx.alpha}`);
+  });
   if ((def.bulkReactions ?? []).length) {
     lines.push('bulk reactions:');
     for (const rx of def.bulkReactions) lines.push(`  ${rx.equation ?? equation(rx.nu)}${rx.srh ? ' (SRH)' : ''} in ${Object.keys(rx.kf ?? rx.srh ?? {}).join(', ')}`);

package/src/device.js

@@ -6,7 +6,7 @@
 // defaults for physically meaningful choices: interface alignments, reference concentrations
 // and standard potentials must all be given.
 
-import { buildGrid } from './grid.js';
+import { buildGrid, applyGeometry } from './grid.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 import { normalizeStatistics } from './statistics.js';
 import { DeviceError } from './errors.js';
@@ -16,7 +16,7 @@ export { DeviceError };
 
 // Contacts use the same laws as internal faces: the outside is a phase with known levels.
 const SPECIES_LINK_TYPES = new Set(['blocked', 'equilibrium', 'conductance', 'exchange']);
-const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance']);
+const INTERFACE_LINK_TYPES = new Set(['equilibrium', 'blocked', 'conductance', 'permeability']);
 const PHI_LINK_TYPES = new Set(['bulk', 'neutral', 'capacitive', 'pinned']);
 const GRID_FIELDS = ['hmin', 'hmax', 'ratio', 'minCells'];
 // The fields of each kind of species link (to an outside phase, or across a face).
@@ -105,7 +105,7 @@ function nonNegative(v, path) {
  */
 export function normalizeDevice(def) {
   need(isObject(def), 'device definition must be an object');
-  fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid']);
+  fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid', 'geometry']);
 
   const T = def.T === undefined ? 298.15 : positive(def.T, 'T');
   const RT = GAS_CONSTANT * T;
@@ -171,8 +171,14 @@ export function normalizeDevice(def) {
     materialIndex.set(mname, materials.length);
     materials.push(m);
   }
+  // (an electrode's carrier can live outside the device: a reacting port's terminal species)
+  const outside = (sp) => (def.ports ?? []).some((p) => p?.terminal === sp.name && Array.isArray(p.reactions) && p.reactions.length > 0);
   species.forEach((sp, i) => {
-    need(materials.some((m) => m.present[i]), `species '${sp.name}' is not present in any material`);
+    const reacting = (def.ports ?? []).some((p) => Array.isArray(p?.reactions) && p.reactions.length > 0);
+    need(
+      materials.some((m) => m.present[i]) || outside(sp),
+      `species '${sp.name}' is not present in any material` + (reacting ? " (an electrode's carrier can instead be a reacting port's terminal)" : ''),
+    );
   });
 
   // --- regions
@@ -280,7 +286,7 @@ export function normalizeDevice(def) {
 
   // --- internal ports (outside phases attached over windows of interior nodes)
   need(def.ports === undefined || Array.isArray(def.ports), 'ports must be an array');
-  const ports = (def.ports ?? []).map((pdef, k) => normalizePort(pdef, `ports[${k}]`, regions, materials, species, speciesIndex));
+  const ports = (def.ports ?? []).map((pdef, k) => normalizePort(pdef, `ports[${k}]`, regions, materials, species, speciesIndex, RT));
 
   // Every electrostatically coupled cluster of regions needs an anchor, or its φ (and every
   // charged level with it) floats: shifting φ by s and each η_i by z_i s changes nothing.
@@ -322,6 +328,17 @@ export function normalizeDevice(def) {
   } catch (err) {
     throw new DeviceError(`grid: ${err.message}`);
   }
+  const geometry = normalizeGeometry(def.geometry);
+  if (geometry.type !== 'planar') {
+    regions.forEach((reg, r) => need(reg.velocity === 0, `regions[${r}].velocity: flow is for a planar device (a uniform velocity through a varying cross-section wouldn't conserve the liquid)`));
+  }
+  applyGeometry(grid, geometry);
+  // (zero only at an end, as at a sphere's centre: nothing passes there)
+  const inside = (x) => x > 0 && x < grid.length;
+  need(
+    grid.area.every((a, g) => a > 0 || g === 0 || g === grid.nNodes - 1) && (geometry.type !== 'profile' || geometry.values.every((a, k) => a > 0 || !inside(geometry.x[k]))),
+    'geometry: the cross-section vanishes inside the device; only an end may have A = 0',
+  );
 
   // Port windows: the nodes of the port's region within [from, to] of its left end.
   ports.forEach((port, k) => {
@@ -336,7 +353,7 @@ export function normalizeDevice(def) {
   });
 
   return {
-    T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports,
+    T, RT, F: FARADAY, species, speciesIndex, materials, materialIndex, regions, interfaces, reactions, contacts, terminals, grid, warnings, ports, geometry,
   };
 }
 
@@ -433,12 +450,17 @@ function stoichiometry(map, path, fixed, fixedPath, species, speciesIndex, RT) {
 //   r = k0 Π_{ν<0} (c/c_ref)^{|ν|(1−α)} Π_{ν>0} (c/c_ref)^{να} (e^{αa} − e^{−(1−α)a})
 // (a conductor's carrier has activity 1, so no factor). That's mass action with rate constants
 // that depend on the electrical part of the affinity, and exactly zero at A = 0.
+// Or saturating (a transporter or an enzyme that turns over at most vmax per area): with K a
+// half-saturation concentration for each species the forward reaction consumes,
+//   r = vmax Π_{ν<0} (c/(c + K))^{|ν|} (1 − e^{−a}),
+// Michaelis–Menten in each substrate, and still exactly zero at A = 0 (the backward rate is the
+// one detailed balance implies).
 function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex, RT) {
   need(idef.reactions === undefined || Array.isArray(idef.reactions), `${where}.reactions must be an array`);
   return (idef.reactions ?? []).map((rdef, k) => {
     const rpath = `${where}.reactions[${k}]`;
     need(isObject(rdef), `${rpath} must be { equation, fixed, k0, alpha } or { left, right, fixed, k0, alpha }`);
-    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh']);
+    fields(rdef, rpath, ['equation', 'left', 'right', 'fixed', 'k0', 'alpha', 'srh', 'vmax', 'K']);
     let sides = rdef;
     if (rdef.equation !== undefined) {
       need(rdef.left === undefined && rdef.right === undefined, `${rpath}: give the reaction as an equation or as left and right, not both`);
@@ -458,6 +480,22 @@ function normalizeFaceReactions(idef, where, matL, matR, species, speciesIndex,
     }
     need(part.length > 0, `${rpath}: no species participate`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    if (rdef.vmax !== undefined || rdef.K !== undefined) {
+      need(rdef.k0 === undefined && rdef.alpha === undefined && rdef.srh === undefined, `${rpath}: give vmax and K (saturating), srh, or k0 and alpha (Butler–Volmer), one of them`);
+      const vmax = positive(rdef.vmax, `${rpath}.vmax (mol/(m²·s))`);
+      need(isObject(rdef.K), `${rpath}.K must map each species the forward reaction consumes to its half-saturation concentration (mol/m³)`);
+      for (const name of Object.keys(rdef.K)) {
+        need(part.some((p) => p.nu < 0 && species[p.i].name === name), `${rpath}.K.${name}: not a species the forward reaction consumes`);
+        positive(rdef.K[name], `${rpath}.K.${name} (mol/m³)`);
+      }
+      for (const p of part) {
+        if (p.nu >= 0) continue;
+        const mat = p.side ? matR : matL;
+        need(!mat.conductor, `${rpath}: saturating kinetics is for dissolved substrates, not a metal's ${species[p.i].name}`);
+        need(rdef.K[species[p.i].name] !== undefined, `${rpath}.K.${species[p.i].name}: give a half-saturation concentration for every species the forward reaction consumes`);
+      }
+      return { part, fixedA, vmax, K: part.map((p) => (p.nu < 0 ? rdef.K[species[p.i].name] : 0)) };
+    }
     if (rdef.srh !== undefined) {
       need(rdef.k0 === undefined && rdef.alpha === undefined, `${rpath}: give srh or k0 (and alpha), not both`);
       const srh = srhLaw(rdef.srh, `${rpath}.srh`, part, species, ['vn', 'vp']);
@@ -534,6 +572,7 @@ export function normalizeDrives(def, model) {
   for (const [k, side] of [[0, 'left'], [1, 'right']]) {
     need(model.contacts[side].passes || drives[k].kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
   }
+  model.ports.forEach((port, k) => need(port.passes || drives[2 + k].kind === 'V', `ports[${k}].I: this port passes no current (it exchanges only neutral species), so give it no drive`));
   need(drives.some((d) => d.kind === 'V'), "every terminal is driven by a current, so the device's overall level floats: hold at least one at a voltage V");
   return drives;
 }
@@ -580,15 +619,37 @@ export function nextBreakpoint(src, t) {
   return Infinity;
 }
 
+// The device's cross-section A(x): planar (the default, A = 1 m², so currents read as densities),
+// spherical or cylindrical about a centre r0 to the left of x = 0 (r = r0 + x), or a profile
+// { x, values } of A in m². Every flux, current and amount is then a total through A.
+function normalizeGeometry(g) {
+  if (g === undefined || g === 'planar') return { type: 'planar' };
+  if (g === 'spherical' || g === 'cylindrical') g = { type: g };
+  need(isObject(g), "geometry must be 'planar', 'spherical', 'cylindrical', { type, r0 } or { area: { x, values } }");
+  if (g.area !== undefined) {
+    fields(g, 'geometry', ['area']);
+    const p = profile(g.area, 'geometry.area', 'cross-sections (m²)', (a) => a >= 0, 'a cross-section ≥ 0 (m²)');
+    need([...p.values].some((a) => a > 0), 'geometry.area: the cross-section is zero everywhere');
+    return { type: 'profile', x: p.x, values: p.values };
+  }
+  fields(g, 'geometry', ['type', 'r0']);
+  need(['planar', 'spherical', 'cylindrical'].includes(g.type), "geometry.type must be 'planar', 'spherical' or 'cylindrical'");
+  if (g.type === 'planar') return { type: 'planar' };
+  const r0 = g.r0 === undefined ? 0 : nonNegative(g.r0, 'geometry.r0 (m, the radius at x = 0)');
+  return { type: g.type, r0 };
+}
+
 // An internal port: an outside phase with known levels (V_i = V + offset_i, or μ for neutral
 // species, as at a contact), exchanging with every node in a window of one region.
 // Links per species: 'equilibrium' (μ̄ held at the outside level throughout the window),
 // { type: 'conductance', G } for charged species (G in S/m³: a source G (V_out − V_i)/(zF) per
 // volume), { type: 'exchange', k, mu } for neutral ones (k in mol/(m³·s): a source
-// k (μ_out − μ)/RT per volume), or 'blocked' (the default).
-function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
+// k (μ_out − μ)/RT per volume), or 'blocked' (the default). And reactions with the port's
+// terminal species, a metal's carrier at the port's level: an electrode surface spread through
+// the window, `area` (m²/m³) of it per volume.
+function normalizePort(pdef, path, regions, materials, species, speciesIndex, RT) {
   need(isObject(pdef), `${path} must be an object`);
-  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species']);
+  fields(pdef, path, ['name', 'region', 'from', 'to', 'V', 'I', 'R', 'terminal', 'species', 'reactions', 'area']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -605,9 +666,10 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
     need(speciesIndex.has(pdef.terminal), `${path}.terminal: unknown species ${JSON.stringify(pdef.terminal)}${known(speciesIndex)}`);
     terminal = speciesIndex.get(pdef.terminal);
   }
-  need(isObject(pdef.species), `${path}.species must map species names to port links`);
+  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT);
+  need(pdef.species === undefined ? reactions.length > 0 : isObject(pdef.species), `${path}.species must map species names to port links`);
   const links = species.map(() => ({ type: 'blocked' }));
-  for (const [sname, raw] of Object.entries(pdef.species)) {
+  for (const [sname, raw] of Object.entries(pdef.species ?? {})) {
     const lpath = `${path}.species.${sname}`;
     need(speciesIndex.has(sname), `${lpath}: unknown species '${sname}'${known(speciesIndex)}`);
     const i = speciesIndex.get(sname);
@@ -635,8 +697,49 @@ function normalizePort(pdef, path, regions, materials, species, speciesIndex) {
     if (link.type === 'exchange') level.k = positive(link.k, `${lpath}.k (mol/(m³·s))`);
     links[i] = { type: link.type, ...level };
   }
-  need(links.some((l) => l.type !== 'blocked'), `${path}.species: the port exchanges no species`);
-  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links };
+  need(links.some((l) => l.type !== 'blocked') || reactions.length > 0, `${path}.species: the port exchanges no species`);
+  // One that exchanges only neutral species (an O₂ supply) carries no current, so its voltage is
+  // nobody's business: it can't be driven by one.
+  const passes = reactions.length > 0 || links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
+  need(passes || drive.kind === 'V', `${path}.I: this port passes no current (it exchanges only neutral species), so give it no drive`);
+  let area = null;
+  if (reactions.length > 0) {
+    need(pdef.area !== undefined, `${path}.area: give the electrode's area per volume of the window (m²/m³, e.g. 1/h for a film of thickness h on it), a number or a profile`);
+    area = typeof pdef.area === 'number' ? { value: positive(pdef.area, `${path}.area (m²/m³)`) } : profile(pdef.area, `${path}.area`, 'areas per volume (m²/m³)', (a) => a >= 0, 'an area per volume ≥ 0');
+  } else need(pdef.area === undefined, `${path}.area: only a port with reactions has an electrode area`);
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area };
+}
+
+// A port's reactions: Butler–Volmer, as at a face, between species of the port's region and the
+// port's terminal species (a metal's carrier, activity 1, at the port's level), per area of the
+// electrode: part side 0 for the region's species, side 1 for the carrier.
+function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT) {
+  need(pdef.reactions === undefined || Array.isArray(pdef.reactions), `${path}.reactions must be an array`);
+  const list = pdef.reactions ?? [];
+  if (list.length === 0) return [];
+  need(!mat.conductor, `${path}.reactions: a port on a conductor is a wire; reactions belong on a face, or on a port in the solution`);
+  need(terminal !== null && species[terminal].z !== 0, `${path}.terminal: a port with reactions needs its electrode's carrier as its terminal species (e.g. 'e-')`);
+  need(!mat.present[terminal], `${path}.terminal: '${species[terminal].name}' is in the port's region too, so a reaction can't tell the electrode's from the region's`);
+  const carrier = species[terminal].name;
+  return list.map((rdef, k) => {
+    const rpath = `${path}.reactions[${k}]`;
+    need(isObject(rdef) && typeof rdef.equation === 'string', `${rpath} must be { equation, fixed, k0, alpha }`);
+    fields(rdef, rpath, ['equation', 'fixed', 'k0', 'alpha']);
+    const holds = (name) => speciesIndex.has(name) && Boolean(mat.present[speciesIndex.get(name)]);
+    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier, conductor: true }, rdef.fixed, `${rpath}.equation`);
+    const part = [];
+    let fixedA = 0, charge = 0;
+    for (const [key, side] of [['left', 0], ['right', 1]]) {
+      const st = stoichiometry(sides[key], `${rpath}.equation`, rdef.fixed, `${rpath}.fixed`, species, speciesIndex, RT);
+      for (const { i, nu } of st.list) part.push({ i, nu, side });
+      fixedA += st.fixedA;
+      charge += st.charge;
+    }
+    need(part.some((p) => p.side === 1), `${rpath}: no '${carrier}' from the electrode takes part`);
+    need(part.some((p) => p.side === 0), `${rpath}: no species of the port's region takes part`);
+    need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`) };
+  });
 }
 
 function checkAnchors(regions, materials, interfaces, contacts, species, ports = []) {
@@ -659,7 +762,7 @@ function checkAnchors(regions, materials, interfaces, contacts, species, ports =
   const anchored = new Set();
   if (anchors(contacts.left)) anchored.add(find(0));
   if (anchors(contacts.right)) anchored.add(find(nR - 1));
-  for (const port of ports) if (port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
+  for (const port of ports) if (port.reactions.length > 0 || port.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0)) anchored.add(find(port.region));
   for (let r = 0; r < nR; r++) {
     const mat = materials[regions[r].material];
     const charged = species.some((sp, i) => mat.present[i] && sp.z !== 0);
@@ -741,7 +844,8 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
   const sheetCharge = idef.sheetCharge === undefined ? 0 : finite(idef.sheetCharge, `${where}.sheetCharge`);
 
   // Per-species laws across the face: local equilibrium (default where present on both sides),
-  // blocked, or an ohmic interface conductance G (S/m²).
+  // blocked, an ohmic interface conductance G (S/m²), or a permeability P (m/s): electrodiffusion
+  // through a thin membrane in a constant field, Goldman–Hodgkin–Katz.
   const links = defaultInterfaceLinks(matL, matR, species);
   if (idef.species !== undefined) {
     need(isObject(idef.species), `${where}.species must map species names to interface links`);
@@ -751,12 +855,16 @@ function normalizeInterface(idef, f, regions, materials, species, speciesIndex,
       const i = speciesIndex.get(sname);
       const link = typeof raw === 'string' ? { type: raw } : raw;
       need(isObject(link) && INTERFACE_LINK_TYPES.has(link.type), `${lpath}.type must be one of ${[...INTERFACE_LINK_TYPES].join(', ')}`);
-      fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : ['type']);
+      fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : link.type === 'permeability' ? ['type', 'P'] : ['type']);
       if (link.type !== 'blocked') need(matL.present[i] && matR.present[i], `${lpath}: '${sname}' must be present on both sides`);
       if (link.type === 'conductance') {
         need(species[i].z !== 0, `${lpath}: a conductance link needs a charged species`);
         positive(link.G, `${lpath}.G`);
       }
+      if (link.type === 'permeability') {
+        positive(link.P, `${lpath}.P (m/s)`);
+        need(matL.modelOf[i] < 0 && matR.modelOf[i] < 0, `${lpath}: a permeability link needs ideal (dilute) statistics for '${sname}' on both sides`);
+      }
       links[i] = { ...link };
     }
   }
@@ -847,6 +955,7 @@ function normalizeConductorInterface(idef, where, matL, matR, species, speciesIn
       const i = speciesIndex.get(sname);
       const link = typeof raw === 'string' ? { type: raw } : raw;
       need(isObject(link) && INTERFACE_LINK_TYPES.has(link.type), `${lpath}.type must be one of ${[...INTERFACE_LINK_TYPES].join(', ')}`);
+      need(link.type !== 'permeability', `${lpath}: a permeability link is for a membrane between two solutions, not at a conductor`);
       fields(link, lpath, link.type === 'conductance' ? ['type', 'G'] : ['type']);
       if (link.type !== 'blocked') need(matL.present[i] && matR.present[i], `${lpath}: '${sname}' must be present on both sides`);
       if (link.type === 'conductance') {

package/src/grid.js

@@ -109,3 +109,76 @@ export function buildGrid(regions, opts = {}) {
     length: x0,
   };
 }
+
+// The cross-section A(x) (m²), for a device that isn't planar: the conservation laws hold for
+// the totals through it, flux × A, and a box holds its volume ∫A dx. A planar device has A = 1
+// everywhere, and its currents read as densities.
+//   spherical: A = 4π r², cylindrical: A = 2π r (per metre of length), r = r0 + x;
+//   a profile: A(x) piecewise linear through the points given, constant beyond them.
+function crossSection(geometry) {
+  const { type } = geometry;
+  if (type === 'spherical' || type === 'cylindrical') {
+    const r0 = geometry.r0, sph = type === 'spherical';
+    const sq = (x) => (r0 + x) * (r0 + x), cube = (x) => (r0 + x) * (r0 + x) * (r0 + x);
+    return {
+      at: (x) => (sph ? 4 * Math.PI * sq(x) : 2 * Math.PI * (r0 + x)),
+      // ∫A dx and ∫dx/A from a to b
+      integral: (a, b) => (sph ? (4 * Math.PI * (cube(b) - cube(a))) / 3 : Math.PI * (sq(b) - sq(a))),
+      resistance: (a, b) => (sph ? (1 / (r0 + a) - 1 / (r0 + b)) / (4 * Math.PI) : Math.log((r0 + b) / (r0 + a)) / (2 * Math.PI)),
+    };
+  }
+  const xs = geometry.x, vs = geometry.values, last = xs.length - 1;
+  const at = (x) => {
+    if (x <= xs[0]) return vs[0];
+    if (x >= xs[last]) return vs[last];
+    let k = 0;
+    while (xs[k + 1] < x) k++;
+    return vs[k] + ((vs[k + 1] - vs[k]) * (x - xs[k])) / (xs[k + 1] - xs[k]);
+  };
+  // Over [a, b], split at the profile's points, where A is linear on each piece.
+  const pieces = (a, b, f) => {
+    let s = 0, lo = a;
+    for (const xk of [...xs.filter((v) => v > a && v < b), b]) {
+      s += f(lo, xk, at(lo), at(xk));
+      lo = xk;
+    }
+    return s;
+  };
+  return {
+    at,
+    integral: (a, b) => pieces(a, b, (p, q, A1, A2) => ((A1 + A2) / 2) * (q - p)),
+    resistance: (a, b) =>
+      pieces(a, b, (p, q, A1, A2) => {
+        const d = A2 - A1, m = (A1 + A2) / 2;
+        return Math.abs(d) < 1e-6 * m ? (q - p) / m : ((q - p) * Math.log(A2 / A1)) / d;
+      }),
+  };
+}
+
+/**
+ * Give a grid its cross-section: `area` (A at each node, m²), `segArea` (each segment's
+ * effective area, its length over ∫dx/A, so that a flux D·segArea·Δc/h is exact for steady
+ * diffusion between the nodes; A at its middle where A vanishes at an end, as at a sphere's
+ * centre) and `vol` (each node's box, ∫A dx). Planar (no geometry): A = 1, and nothing changes.
+ * @param {ReturnType<typeof buildGrid>} grid
+ * @param {{ type: 'planar' } | { type: 'spherical' | 'cylindrical', r0: number } | { type: 'profile', x: ArrayLike<number>, values: ArrayLike<number> }} geometry
+ */
+export function applyGeometry(grid, geometry) {
+  const { nNodes, x, segLength } = grid;
+  grid.area = new Float64Array(nNodes).fill(1);
+  grid.segArea = new Float64Array(nNodes - 1).fill(1);
+  if (!geometry || geometry.type === 'planar') return grid;
+  const A = crossSection(geometry);
+  for (let g = 0; g < nNodes; g++) grid.area[g] = A.at(x[g]);
+  for (let s = 0; s < nNodes - 1; s++) {
+    const h = segLength[s];
+    if (h === 0) grid.segArea[s] = grid.area[s];
+    else if (grid.area[s] > 0 && grid.area[s + 1] > 0) grid.segArea[s] = h / A.resistance(x[s], x[s + 1]);
+    else grid.segArea[s] = A.at(x[s] + h / 2);
+  }
+  for (let g = 0; g < nNodes; g++) {
+    const lo = g > 0 ? x[g] - segLength[g - 1] / 2 : x[g], hi = g < nNodes - 1 ? x[g] + segLength[g] / 2 : x[g];
+    grid.vol[g] = hi > lo ? A.integral(lo, hi) : 0;
+  }
+  return grid;
+}

package/src/index.js

@@ -160,7 +160,7 @@ export class Device {
    * (one array per probe, alongside `trace.t`): what a detector at x sees.
    * @param {number} tEnd s
    * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-   *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
+   *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {