driftlet 0.7.0 → 0.9.0

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';
@@ -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) => {
@@ -334,9 +351,18 @@ export function normalizeDevice(def) {
     need(nodes.length > 0, `ports[${k}]: the window [${port.from}, ${port.to}] m holds no grid node; widen it or refine the grid`);
     port.nodes = Int32Array.from(nodes);
   });
+  // A node's surface belongs to one electrode.
+  const surfaced = new Int32Array(grid.nNodes).fill(-1);
+  ports.forEach((port, k) => {
+    if (port.surface.length === 0) return;
+    for (const g of port.nodes) {
+      need(surfaced[g] < 0, `ports[${k}]: its window overlaps ports[${surfaced[g]}]'s, and both have a surface; a spot of metal has one surface`);
+      surfaced[g] = k;
+    }
+  });
 
   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,
   };
 }
 
@@ -555,6 +581,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;
 }
@@ -601,15 +628,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', 'surface', 'capacitance']);
   let r;
   if (Number.isInteger(pdef.region)) r = pdef.region;
   else r = regions.findIndex((reg) => reg.name === pdef.region);
@@ -626,9 +675,13 @@ 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 surface = portSurface(pdef, path, speciesIndex);
+  const reactions = portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, surface);
+  surface.forEach((sp, s) => need(reactions.some((rx) => rx.part.some((p) => p.side === 2 && p.s === s)), `${path}.surface.${sp.name}: no reaction of the port makes or uses it`));
+  const capacitance = portCapacitance(pdef, path, mat);
+  need(pdef.species === undefined ? reactions.length > 0 || capacitance !== null : 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);
@@ -656,8 +709,95 @@ 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 || capacitance !== null, `${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 || capacitance !== null || 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 || capacitance !== null) {
+    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 an electrode (a port with reactions or a capacitance) has an area`);
+  need(surface.length === 0 || reactions.length > 0, `${path}.surface: only an electrode (a port with reactions) has a surface`);
+  return { name: pdef.name ?? path, region: r, from, to, span: reg.length, drive, terminal, species: links, passes, reactions, area, surface, capacitance };
+}
+
+// A capacitance spread through the window: a gate along a channel, an electrode's double layer.
+// Per area of electrode it holds σ = C (V − zeroCharge − φ) on the port's side, and the window
+// the opposite: the region's charge balance (Gauss's law, or neutrality at ε = 0) gains aσ.
+function portCapacitance(pdef, path, mat) {
+  if (pdef.capacitance === undefined) return null;
+  const cpath = `${path}.capacitance`;
+  need(isObject(pdef.capacitance), `${cpath} must be { C, zeroCharge }`);
+  fields(pdef.capacitance, cpath, ['C', 'zeroCharge']);
+  need(!mat.conductor && !mat.phiFree, `${cpath}: a capacitance couples to φ, which a ${mat.conductor ? 'conductor' : 'region with no free charge'} doesn't have`);
+  return { C: positive(pdef.capacitance.C, `${cpath}.C (F/m² of electrode)`), zeroCharge: pdef.capacitance.zeroCharge === undefined ? 0 : finite(pdef.capacitance.zeroCharge, `${cpath}.zeroCharge (V)`) };
+}
+
+// An electrode port's surface species: coverages θ of its sites (Langmuir: each takes one site,
+// μ = μ° + RT ln(θ/θ₀) with θ₀ = 1 − Σθ the bare fraction), Γ mol of sites per m² of electrode.
+function portSurface(pdef, path, speciesIndex) {
+  if (pdef.surface === undefined) return [];
+  need(isObject(pdef.surface), `${path}.surface must map surface species to { mu0, capacity, theta0 }`);
+  const list = Object.entries(pdef.surface).map(([name, d]) => {
+    const spath = `${path}.surface.${name}`;
+    need(!speciesIndex.has(name), `${spath}: '${name}' is a species of the device; a surface species is the port's own, with its own name`);
+    need(isObject(d), `${spath} must be { mu0, capacity, theta0 }`);
+    fields(d, spath, ['mu0', 'capacity', 'theta0']);
+    const theta0 = d.theta0 === undefined ? 1e-6 : positive(d.theta0, `${spath}.theta0`);
+    return { name, mu0: finite(d.mu0, `${spath}.mu0 (J/mol)`), capacity: positive(d.capacity, `${spath}.capacity (mol of sites per m² of electrode)`), theta0 };
+  });
+  need(list.length > 0, `${path}.surface: give at least one surface species, or leave it out`);
+  const caps = new Set(list.map((sp) => sp.capacity));
+  need(caps.size === 1, `${path}.surface: the species share the electrode's sites, so give them one capacity`);
+  need(list.reduce((t, sp) => t + sp.theta0, 0) < 1, `${path}.surface: the starting coverages (theta0) must sum to less than 1`);
+  return list;
+}
+
+// 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, surface = []) {
+  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`);
+  // The metal's countercharge (each spot's double layer) is below the grid, so the solution
+  // beside it must be neutral, as in porous-electrode theory; with ε > 0 the reactions would
+  // leave a net charge with nothing to balance it.
+  need(mat.epsr === 0 || mat.phiFree, `${path}.reactions: an electrode spread through a window needs its region strictly neutral (ε = 0): its double layers are below the grid`);
+  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', 'bare']);
+    const holds = (name) => speciesIndex.has(name) && Boolean(mat.present[speciesIndex.get(name)]);
+    const onSurface = (name) => surface.findIndex((sp) => sp.name === name);
+    const sides = faceSides(parseEquation(rdef.equation, `${rpath}.equation`), { name: mat.name, holds, conductor: false }, { name: 'the electrode', holds: (name) => name === carrier || onSurface(name) >= 0, conductor: true }, rdef.fixed, `${rpath}.equation`);
+    const part = [];
+    let fixedA = 0, charge = 0;
+    // The electrode's side: its carrier, and its surface species (side 2, neutral, by index s).
+    const electrode = {};
+    for (const [name, nu] of Object.entries(sides.right)) {
+      const s = onSurface(name);
+      if (s >= 0) part.push({ s, nu, side: 2 });
+      else electrode[name] = nu;
+    }
+    for (const [map, side] of [[sides.left, 0], [electrode, 1]]) {
+      const st = stoichiometry(map, `${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 || p.side === 2), `${rpath}: no species of the port's region or its surface takes part`);
+    need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
+    need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
+  });
 }
 
 function checkAnchors(regions, materials, interfaces, contacts, species, ports = []) {
@@ -680,7 +820,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.capacitance || 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);

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

@@ -100,6 +100,7 @@ export class Device {
       solver.computeConcentrations();
       solver.time = old.time;
       solver.contactDEnd = old.contactDEnd;
+      if (old.portQEnd?.length === solver.portQ.length) solver.portQEnd = old.portQEnd;
       solver.solvedV = old.solvedV; // where the carried-over state was solved (for continuation)
       // Floating terminals keep their voltages (a good start), where the terminals match.
       if (old.terms.length === solver.terms.length) {

package/src/kit.js

@@ -14,6 +14,7 @@ export { describe, unitWarnings } from './describe.js';
 export { recorder } from './recorder.js';
 export { henderson, planck } from './junction.js';
 export { check } from './checks.js';
+export { polarization } from './polarization.js';
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from './devices.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
 

package/src/polarization.js

@@ -0,0 +1,96 @@
+// Polarization curves at an electrode, for driftlet/kit: each reaction's rate with the solution
+// beside the electrode held as it is and the metal's level moved, which is what an Evans diagram
+// plots. Where the net current crosses zero is the spot's open-circuit (mixed) potential.
+
+import { DeviceError } from './errors.js';
+import { FARADAY } from './constants.js';
+import { powi, powr } from './pow.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+
+/**
+ * Each electrode reaction's rate at a face (a metal's) or at one spot of an electrode port, with
+ * the composition beside it as in `sol` and the metal's carrier at each level in `V` (in the
+ * terminals' convention, V = μ̄/(zF); against SHE, subtract φ for the usual tables' ions). The
+ * rates are the solver's own law, so at the electrode's actual level they are
+ * `sol.interfaces[f].rates` (or `sol.ports[k].rates` at that node).
+ * @param {import('./index.js').Device} device
+ * @param {object} sol a solution of it
+ * @param {{ face: number } | { port: string | number, x?: number }} where a face's index, or a port
+ *   (name or index) and the position in its window (m, the device's x; default its first node)
+ * @param {number | ArrayLike<number>} V the metal's level(s), V
+ * @returns {{ V: Float64Array, current: Float64Array, reactions: { equation: string, level: number,
+ *   rate: Float64Array, current: Float64Array }[] }} per reaction: its equilibrium level here (where
+ *   its rate is zero), its rate (mol/(m²·s) of electrode, forward) and its current (A/m², anodic
+ *   positive: into the solution); and their sum
+ */
+export function polarization(device, sol, where, V) {
+  const model = device.model, { species, grid, RT } = model, solver = device.solver;
+  const Vs = Float64Array.from(typeof V === 'number' ? [V] : V);
+  let reactions, nodeOf, carrier, names, surface = null; // (an electrode port's coverages at the spot)
+  if (where?.face !== undefined) {
+    const f = where.face, itf = model.interfaces[f];
+    if (!itf) fail(`polarization: no face ${f} (the device has ${model.interfaces.length})`);
+    const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
+    const metal = [gL, gR].findIndex((g) => solver.nodeConductor[g] >= 0);
+    if (metal < 0) fail(`polarization: face ${f} has no metal on either side`);
+    carrier = { side: metal, i: solver.nodeConductor[metal ? gR : gL] };
+    nodeOf = (p) => (p.side ? gR : gL);
+    reactions = itf.reactions;
+    names = device.def.interfaces?.[f]?.reactions;
+  } else if (where?.port !== undefined) {
+    const k = typeof where.port === 'number' ? where.port : model.ports.findIndex((p) => p.name === where.port);
+    const port = model.ports[k];
+    if (!port) fail(`polarization: no port ${JSON.stringify(where.port)}`);
+    if (port.reactions.length === 0) fail(`polarization: port ${port.name} has no reactions`);
+    let g = port.nodes[0];
+    if (where.x !== undefined) for (const h of port.nodes) if (Math.abs(grid.x[h] - where.x) < Math.abs(grid.x[g] - where.x)) g = h;
+    carrier = { side: 1, i: port.terminal };
+    nodeOf = () => g;
+    if (port.surface.length > 0) {
+      const w = port.nodes.indexOf(g), theta = port.surface.map((sp) => sol.ports[k].coverage[sp.name][w]);
+      surface = { sp: port.surface, theta, bare: sol.ports[k].bare[w] };
+    }
+    reactions = port.reactions;
+    names = device.def.ports?.[k]?.reactions;
+  } else fail('polarization: say where, { face: f } or { port: name, x }');
+  if (reactions.length === 0) fail('polarization: no reactions there');
+
+  const out = reactions.map((rx, k) => {
+    if (rx.srh) fail('polarization: SRH kinetics has no electrode level');
+    // a = A/RT = a0 + s·V: everything but the carrier at its level, and the carrier's part.
+    let a0 = rx.fixedA, s = 0, q = 0, pref = rx.vmax ? rx.vmax : rx.k0;
+    rx.part.forEach((p, x) => {
+      if (p.side === 2) {
+        // a surface species, at activity θ/θ₀ (μ = μ° + RT ln(θ/θ₀))
+        const ln = Math.log(surface.theta[p.s] / surface.bare), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
+        a0 -= (p.nu * (surface.sp[p.s].mu0 / RT + ln));
+        pref *= Math.exp(e * ln);
+        return;
+      }
+      if (p.side === carrier.side && p.i === carrier.i) {
+        s -= (p.nu * species[p.i].z * FARADAY) / RT;
+        return;
+      }
+      const g = nodeOf(p), name = species[p.i].name;
+      a0 -= (p.nu * sol.mu[name][g]) / RT;
+      q += p.side === carrier.side ? 0 : p.nu * species[p.i].z; // charge the forward reaction puts into the solution
+      const c = sol.c[name][g];
+      if (rx.vmax) {
+        if (p.nu < 0) pref *= powi(c / (c + rx.K[x]), -p.nu);
+      } else pref *= powr(c / solver.cRef[g * species.length + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
+    });
+    if (s === 0) fail(`polarization: reaction ${k} there takes no ${species[carrier.i].name} from the metal`);
+    if (rx.bare) pref *= surface ? surface.bare : 1; // on bare metal only
+    const rate = Float64Array.from(Vs, (v) => {
+      const a = a0 + s * v;
+      return rx.vmax ? pref * -Math.expm1(-a) : pref * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
+    });
+    return { equation: names?.[k]?.equation ?? `reaction ${k}`, level: -a0 / s, rate, current: rate.map((r) => q * FARADAY * r) };
+  });
+  const current = new Float64Array(Vs.length);
+  for (const r of out) for (let j = 0; j < Vs.length; j++) current[j] += r.current[j];
+  return { V: Vs, current, reactions: out };
+}

package/src/solution.js

@@ -91,7 +91,8 @@ export function makeSolution(solver, result = {}) {
     const V = solver.termV[side === 'left' ? 0 : 1];
     sol.contacts[side] = { V, flux, D, current: conduction + displacement };
     if (ct.phi.type === 'capacitive' || ct.phi.type === 'pinned') {
-      // Charge per area on the gate (or metal) plate: +D at the left, −D at the right.
+      // Charge on the gate (or metal) plate, per area if the device is planar: +D at the left, −D
+      // at the right.
       sol.gates[side] = { V, D, charge: side === 'left' ? D : -D };
     }
   }
@@ -105,7 +106,32 @@ export function makeSolution(solver, result = {}) {
       flux[species[i].name] = solver.portFlux[k][i];
       current += F * species[i].z * solver.portFlux[k][i];
     }
-    return { name: port.name, V: solver.termV[2 + k], flux, current };
+    if (port.capacitance) {
+      // a capacitance's charging current, and its charge (the port's side), like a gate's
+      const dt = solver.lastDt;
+      current += Number.isFinite(dt) ? (solver.portQ[k] - solver.portQOld[k]) / dt : 0;
+    }
+    const out = { name: port.name, V: solver.termV[2 + k], flux, current };
+    if (port.capacitance) out.charge = solver.portQ[k];
+    if (port.capacitance) {
+      // its charge per area of electrode at each node, σ = C (V − zeroCharge − φ)
+      const { C: Cs, zeroCharge } = port.capacitance;
+      out.sigma = Float64Array.from(port.nodes, (g) => Cs * (solver.termV[2 + k] - zeroCharge - phi[g]));
+    }
+    if (port.area !== null) {
+      out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
+      out.area = Float64Array.from(solver.portArea[k]);
+    }
+    if (port.reactions.length > 0) {
+      // An electrode spread through the window: each reaction's rate at its nodes.
+      out.rates = solver.portRates[k].map((r) => Float64Array.from(r)); // mol/(m²·s), forward
+      // its surface: each species' coverage θ at each node of the window
+      if (port.surface.length > 0) {
+        out.coverage = Object.fromEntries(port.surface.map((sp, q) => [sp.name, Float64Array.from(port.nodes, (g) => solver.th[g * solver.nSurf + q])]));
+        out.bare = Float64Array.from(port.nodes, (g) => solver.th0[g]); // θ₀, to full precision however covered
+      }
+    }
+    return out;
   });
   sol.terminalVoltage = sol.contacts.right.V - sol.contacts.left.V;
   // Every terminal (the contacts, then the ports by name): its voltage and its current into the
@@ -142,14 +168,14 @@ export function makeSolution(solver, result = {}) {
     return { rate, regions, total };
   });
 
-  // Total charge per area in the device (space charge plus sheet charges).
+  // Total charge in the device (space charge plus sheet charges), per area if it's planar.
   let q = 0;
   for (let g = 0; g < nNodes; g++) {
     let rho = solver.rhoFixed[g];
     for (let i = 0; i < n; i++) rho += F * species[i].z * c[g * n + i];
     q += grid.vol[g] * rho;
   }
-  for (const itf of interfaces) q += itf.sheetCharge;
+  interfaces.forEach((itf, f) => (q += itf.sheetCharge * grid.area[grid.regionEnd[f]]));
   sol.charge = q;
 
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,