driftlet 0.7.0 → 0.8.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/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,84 @@
+// 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;
+  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;
+    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 === 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`);
+    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,14 @@ 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 };
+    const out = { name: port.name, V: solver.termV[2 + k], flux, current };
+    if (port.reactions.length > 0) {
+      // An electrode spread through the window: where it sits, and each reaction's rate there.
+      out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
+      out.area = Float64Array.from(solver.portArea[k]);
+      out.rates = solver.portRates[k].map((r) => Float64Array.from(r)); // mol/(m²·s), forward
+    }
+    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 +150,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,

package/src/solver.js

@@ -374,6 +374,13 @@ export class Solver {
       nu: Float64Array.from([...rx.reactants.map((p) => p.nu), ...rx.products.map((p) => -p.nu)]),
     }));
 
+    // Each reacting port's electrode area per volume at its window's nodes (a profile's mean over
+    // each node's box, as for a rate constant), and its reactions' rates there, mol/(m²·s).
+    this.portArea = model.ports.map((port) =>
+      port.area === null ? null : Float64Array.from(port.nodes, (g) => port.area.value ?? profileMean(port.area, gx[g] - (g > 0 ? segLength[g - 1] : 0) / 2, gx[g] + (g < segLength.length ? segLength[g] : 0) / 2)),
+    );
+    this.portRates = model.ports.map((port) => port.reactions.map(() => new Float64Array(port.nodes.length)));
+
     // Whether any region is strictly neutral (ε = 0, not a conductor): see integrate().
     this.strictlyNeutral = model.regions.some((reg) => {
       const mat = materials[reg.material];
@@ -395,8 +402,14 @@ export class Solver {
     for (const port of model.ports) for (const g of port.nodes) need[g] = 1;
     // Nodes of strictly neutral (ε = 0) regions that stay neutral, where φ is defined: interior
     // ones, and edges at neutral faces (a capacitive or pinned face's edge node holds the face's
-    // charge), away from contacts and ports. On a transient step these are solved in better-
-    // conditioned terms (see _chargeRows).
+    // charge), away from the contacts and from ports that hold a level (which replaces a balance
+    // row). On a transient step these are solved in better-conditioned terms (see _chargeRows).
+    // A port that only exchanges (an O₂ supply, a leak) is solved there too: left out, its window
+    // fell back on the ill-conditioned terms, and a closed neutral electrolyte whose potential is
+    // set only by a face reaction couldn't take a step.
+    const held = new Uint8Array(nNodes);
+    held[0] = held[nNodes - 1] = 1;
+    for (const port of model.ports) if (port.species.some((l) => l.type === 'equilibrium')) for (const g of port.nodes) held[g] = 1;
     this.chargeNode = new Uint8Array(nNodes);
     const neutralFace = (f) => f >= 0 && f < model.interfaces.length && model.interfaces[f].phi.type === 'neutral';
     regions.forEach((reg, r) => {
@@ -405,7 +418,7 @@ export class Solver {
       const g0 = grid.regionStart[r], g1 = grid.regionEnd[r];
       for (let g = g0; g <= g1; g++) {
         const edgeOk = (g > g0 || neutralFace(r - 1)) && (g < g1 || neutralFace(r));
-        if (edgeOk && !need[g] && !this.phiUndefined[g]) this.chargeNode[g] = 1;
+        if (edgeOk && !held[g] && !this.phiUndefined[g]) this.chargeNode[g] = 1;
       }
     });
     this.chargeNodes = Int32Array.from([...this.chargeNode.keys()].filter((g) => this.chargeNode[g]));
@@ -502,10 +515,15 @@ export class Solver {
             if (rx.kf[m] > 0 && [...rx.reactants, ...rx.products].some((p) => p.i === i)) reactive = true;
           }
         }
-        const ports = model.ports.flatMap((port, k) => (port.region >= r0 && port.region <= r && port.species[i].type !== 'blocked' ? [k] : []));
-        const connected = leftOpen || rightOpen || ports.length > 0;
+        const inside = (port) => port.region >= r0 && port.region <= r;
+        const linked = model.ports.flatMap((port, k) => (inside(port) && port.species[i].type !== 'blocked' ? [k] : []));
+        // made or consumed by a port's reactions (an electrode spread through its window)
+        const reacting = model.ports.flatMap((port, k) => (inside(port) && port.reactions.some((rx) => rx.part.some((p) => p.side === 0 && p.i === i)) ? [k] : []));
+        if (reacting.length > 0) reactive = true;
+        const connected = leftOpen || rightOpen || linked.length > 0;
         this.stretches.push({
-          ports,
+          linked, // ports that hold or exchange it
+          ports: [...new Set([...linked, ...reacting])], // ports that bring any in
           species: i,
           regions: [r0, r],
           nodes: [grid.regionStart[r0], grid.regionEnd[r]],
@@ -635,6 +653,13 @@ export class Solver {
         rows.push(row);
       }
     });
+    for (const port of model.ports) {
+      for (const rx of port.reactions) {
+        const row = new Float64Array(S); // (the electrode's carrier is outside the device)
+        for (const p of rx.part) if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
+        rows.push(row);
+      }
+    }
     model.regions.forEach((reg, q) => {
       for (const rx of model.reactions) {
         if (!(rx.kf[reg.material] > 0)) continue;
@@ -820,11 +845,11 @@ export class Solver {
     });
   }
 
-  /** η_i (μ̄/RT) of a port's outside level for species i. */
+  /** η_i (μ̄/RT) of a port's outside level for species i (its electrode's carrier: at V itself). */
   portEta(port, i) {
     const link = port.species[i];
     const V = this.termV[2 + this.model.ports.indexOf(port)];
-    return this.z[i] === 0 ? link.mu / this.model.RT : (this.z[i] * (V + link.offset)) / this.VT;
+    return this.z[i] === 0 ? link.mu / this.model.RT : (this.z[i] * (V + (link.offset ?? 0))) / this.VT;
   }
 
   /** η_i/RT that a fixed contact link imposes (or NaN if the link isn't fixed). */
@@ -890,7 +915,7 @@ export class Solver {
         } else {
           const left = st.regions[0] === 0 ? this.contactEta('left', i) : NaN;
           eta[i] = Number.isFinite(left) ? left : this.contactEta('right', i);
-          if (!Number.isFinite(eta[i]) && st.ports.length > 0) eta[i] = this.portEta(model.ports[st.ports[0]], i);
+          if (!Number.isFinite(eta[i]) && st.linked.length > 0) eta[i] = this.portEta(model.ports[st.linked[0]], i);
           mode[i] = 1;
           if (!Number.isFinite(eta[i])) {
             // Fed only through reactions (no level held at a contact): start from c0.
@@ -961,6 +986,25 @@ export class Solver {
           }
         }
       }
+      const electrode = model.ports.find((port) => port.region === r && port.reactions.length > 0);
+      if (!mat.phiFree && !responds && mat.ideal && electrode) {
+        // Nor here, but an electrode spread through it does: start with the port's first reaction
+        // that can be balanced at equilibrium with the port's level (the electrode at open circuit).
+        for (const rx of electrode.reactions) {
+          let a = rx.fixedA, s = 0;
+          for (const p of rx.part) {
+            if (p.side === 1) a -= p.nu * this.portEta(electrode, p.i);
+            else if (mode[p.i] === 2) {
+              a -= p.nu * (Math.log(cFix[p.i] / mat.cRef[p.i]) + mat.mu0[p.i] / model.RT);
+              s += p.nu * z[p.i];
+            } else s = NaN;
+          }
+          if (s !== 0 && Number.isFinite(s)) {
+            phiHat = a / s;
+            break;
+          }
+        }
+      }
       const neutralPhi = (ph) => {
         let lo = ph - 1, hi = ph + 1;
         while (charge(lo) < 0 && lo > -1e4) lo -= 2 * (hi - lo);
@@ -1012,6 +1056,50 @@ export class Solver {
       if (Number.isFinite(shift)) this.termV[k] = this.termV[held] + shift;
     }
     this.computeConcentrations();
+    // A floating electrode spread through a port starts where its reactions pass the current it's
+    // set (none, behind a resistance): at its mixed potential in the start's composition, not
+    // level with a held terminal, which can be volts away and pass an absurd current.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      if (!port || port.reactions.length === 0) continue;
+      const want = t.drive.kind === 'I' ? sourceAt(t.drive.src, this.time) : 0;
+      const current = (V) => {
+        this.termV[k] = V;
+        let I = 0;
+        port.reactions.forEach((rx) => {
+          let q = 0;
+          for (const p of rx.part) if (p.side === 0) q += p.nu * z[p.i];
+          port.nodes.forEach((g, w) => (I += q * FARADAY * this.model.grid.vol[g] * this.portArea[t.index][w] * this._portRate(port, rx, g)));
+        });
+        return I;
+      };
+      // Current into the device rises with V (oxidation); bracket, then bisect.
+      let lo = this.termV[k] - 1, hi = this.termV[k] + 1;
+      while (current(lo) > want && lo > -1e3) lo -= 2 * (hi - lo);
+      while (current(hi) < want && hi < 1e3) hi += 2 * (hi - lo);
+      for (let it = 0; it < 200 && hi - lo > 1e-12; it++) {
+        const m = 0.5 * (lo + hi);
+        if (current(m) < want) lo = m;
+        else hi = m;
+      }
+      this.termV[k] = 0.5 * (lo + hi);
+    }
+  }
+
+  // A port reaction's rate per area at node g (mol/(m²·s), forward), at the present state.
+  _portRate(port, rx, g) {
+    const { n, M, u, uLo, c } = this, b = this.blockOfNode[g];
+    let pref = rx.k0, a = rx.fixedA;
+    for (const p of rx.part) {
+      if (p.side === 1) {
+        a -= p.nu * this.portEta(port, p.i);
+        continue;
+      }
+      a -= p.nu * (u[b * M + 1 + p.i] + uLo[b * M + 1 + p.i]);
+      pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha);
+    }
+    // (far from equilibrium, the plain difference: bvFactor's product would give 0·∞ there)
+    return pref * (Math.abs(a) > 50 ? Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a) : bvFactor(a, rx.alpha).g);
   }
 
   // A non-ideal material's composition at φ̂ = ph: level-fixed species (mode 1) at their η,
@@ -1054,7 +1142,7 @@ export class Solver {
         // Excess carriers: zero in the bulk, the surface sheet at a charged face.
         for (let i = 0; i < n; i++) c[g * n + i] = 0;
         const f = this.sheetFace[g];
-        if (f >= 0) c[g * n + im] = (this.sheetSign[g] * u[this.blockOfFace[f] * M]) / (z[im] * FARADAY * this.model.grid.vol[g]);
+        if (f >= 0) c[g * n + im] = (this.sheetSign[g] * u[this.blockOfFace[f] * M] * this.model.grid.area[g]) / (z[im] * FARADAY * this.model.grid.vol[g]);
         continue;
       }
       for (let i = 0; i < n; i++) {
@@ -1165,7 +1253,7 @@ export class Solver {
       const g0 = grid.regionStart[r], g1 = grid.regionEnd[r];
       if (mat.conductor) {
         for (let g = g0; g <= g1; g++) this._nodeConductor(g, dt);
-        for (let s = g0; s < g1; s++) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s]);
+        for (let s = g0; s < g1; s++) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s] / grid.segArea[s]);
         continue;
       }
       if (mat.ideal) this._nodesDilute(g0, g1, dt);
@@ -1173,7 +1261,7 @@ export class Solver {
       const rxs = this.rxsIn[reg.material];
       if (rxs.length > 0) for (let g = g0; g <= g1; g++) this._bulkReactions(g, rxs);
       for (let s = g0; s < g1; s++) {
-        const bL = s + r, bR = bL + 1, h = grid.segLength[s];
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s]; // (a length over the cross-section: fluxes are totals)
         this._segmentDisplacement(s, bL, bR, mat, h);
         if (reg.mixing > 0) this._segmentMixing(s, bL, bR, reg.mixing, h, mat);
         if (!mat.ideal) this._segmentConcentrated(s, bL, bR, mat, h, reg.velocity);
@@ -1201,7 +1289,7 @@ export class Solver {
     const r = 1 + im, k = g * n + im;
     res[R[b * M + r]] += (v * (c[k] - cOld[k])) / dt;
     const f = this.sheetFace[g];
-    if (f >= 0) this._j(b, r, this.blockOfFace[f], 0, this.sheetSign[g] / (z[im] * FARADAY * dt));
+    if (f >= 0) this._j(b, r, this.blockOfFace[f], 0, (this.sheetSign[g] * this.model.grid.area[g]) / (z[im] * FARADAY * dt));
   }
 
   // Dilute nodes g0…g1 (ideal statistics, c = c_ref e^ζ): storage of each species and the space
@@ -1450,9 +1538,9 @@ export class Solver {
   _segmentsDilute(g0, g1, region, mat, vel) {
     const { n, M, u, uLo, res, c, z, sys, loc } = this, R = this.rix, F = FARADAY;
     const { A: JA, B: JB, C: JC, sizes, offA, offB, offC } = sys;
-    const segLength = this.model.grid.segLength;
+    const { segLength, segArea } = this.model.grid;
     for (let s = g0; s < g1; s++) {
-      const bL = s + region, bR = bL + 1, h = segLength[s];
+      const bL = s + region, bR = bL + 1, h = segLength[s] / segArea[s]; // (fluxes are totals through the cross-section)
       const mL = sizes[bL], mR = sizes[bR], pL = loc[bL * M], pR = loc[bR * M];
       const phiL = u[bL * M], phiR = u[bR * M];
       for (let i = 0; i < n; i++) {
@@ -1535,15 +1623,16 @@ export class Solver {
         this._j(bf, 0, bL, 0, -kC);
       }
     }
-    // D_f enters each side's Gauss row; a metal side holds it as surface carriers instead.
-    const gL = grid.regionEnd[f], gR = gL + 1;
+    // D_f enters each side's Gauss row; a metal side holds it as surface carriers instead. The
+    // flux node's unknowns are per area, so what they carry is that times the face's area.
+    const gL = grid.regionEnd[f], gR = gL + 1, Af = grid.area[gL];
     if (this.nodeConductor[gL] < 0) {
-      res[R[bL * M]] += u[bf * M];
-      this._j(bL, 0, bf, 0, 1);
+      res[R[bL * M]] += Af * u[bf * M];
+      this._j(bL, 0, bf, 0, Af);
     }
     if (this.nodeConductor[gR] < 0) {
-      res[R[bR * M]] -= u[bf * M] + itf.sheetCharge;
-      this._j(bR, 0, bf, 0, -1);
+      res[R[bR * M]] -= Af * (u[bf * M] + itf.sheetCharge);
+      this._j(bR, 0, bf, 0, -Af);
     }
     for (let i = 0; i < n; i++) {
       const r = 1 + i, o = bf * M + r;
@@ -1583,12 +1672,12 @@ export class Solver {
         this._j(bf, r, bL, r, -gG);
         this._j(bf, r, bR, r, gG);
       }
-      res[R[bL * M + r]] += u[o];
-      this._j(bL, r, bf, r, 1);
-      res[R[bR * M + r]] -= u[o];
-      this._j(bR, r, bf, r, -1);
+      res[R[bL * M + r]] += Af * u[o];
+      this._j(bL, r, bf, r, Af);
+      res[R[bR * M + r]] -= Af * u[o];
+      this._j(bR, r, bf, r, -Af);
     }
-    itf.reactions.forEach((rx, k) => this._faceReaction(rx, k, f, bf, bL, bR));
+    itf.reactions.forEach((rx, k) => this._faceReaction(rx, k, f, bf, bL, bR, Af));
   }
 
   // Scharfetter–Gummel with non-ideal statistics. The excess ex = ζ − ln(c/c_ref) acts as an
@@ -1805,7 +1894,7 @@ export class Solver {
   // with the row r_k − rate(u_L, u_R) = 0, and each participant's edge node takes ν·r_k (made
   // there when ν > 0). The rate couples the two edge nodes only through the face block between
   // them, which keeps the system block-tridiagonal.
-  _faceReaction(rx, k, f, bf, bL, bR) {
+  _faceReaction(rx, k, f, bf, bL, bR, Af) {
     const { n, M, u, uLo, c, res } = this;
     const R = this.rix;
     const grid = this.model.grid;
@@ -1865,8 +1954,8 @@ export class Solver {
     }
     for (const p of rx.part) {
       const b = p.side ? bR : bL;
-      res[R[b * M + 1 + p.i]] -= p.nu * u[o];
-      this._j(b, 1 + p.i, bf, slot, -p.nu);
+      res[R[b * M + 1 + p.i]] -= Af * p.nu * u[o];
+      this._j(b, 1 + p.i, bf, slot, -Af * p.nu);
     }
   }
 
@@ -1948,9 +2037,58 @@ export class Solver {
         }
       }
     }
+    port.reactions.forEach((rx, x) => this._portReaction(port, rx, this.portArea[k - 2], this.portRates[k - 2][x], flux, k));
     for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
   }
 
+  // A port's reaction at each node of its window: Butler–Volmer per area, as at a face, against
+  // the electrode's carrier at the port's level (activity 1), times the electrode's area per
+  // volume. Each node's rate is explicit (no unknown of its own): it enters the balances of the
+  // species it makes and consumes, and the port's current.
+  _portReaction(port, rx, area, rates, flux, k) {
+    const { n, M, u, uLo, c, res, z, VT } = this, R = this.rix, F = FARADAY, vol = this.model.grid.vol;
+    const B = this.termB[k], C = this.termC[k], al = rx.alpha, d = this.dA;
+    // The carrier's part of the affinity, and how it moves with the port's voltage.
+    let aV = rx.fixedA, daV = 0, q = 0; // q: charge the forward reaction brings into the device, per event
+    for (const p of rx.part) {
+      if (p.side === 1) {
+        aV -= p.nu * this.portEta(port, p.i);
+        daV -= (p.nu * z[p.i]) / VT;
+      } else q += p.nu * z[p.i];
+    }
+    port.nodes.forEach((g, w) => {
+      const b = this.blockOfNode[g], s = vol[g] * area[w];
+      d.fill(0);
+      let pref = rx.k0, aHi = aV, aLo = 0;
+      for (const p of rx.part) {
+        if (p.side === 1) continue;
+        const o = b * M + 1 + p.i;
+        aHi -= p.nu * u[o];
+        aLo -= p.nu * uLo[o];
+        const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
+        pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
+        this._dlnc(g, p.i, e, d);
+      }
+      const { g: bv, gp } = bvFactor(aHi + aLo, al);
+      const rate = pref * bv;
+      rates[w] = rate;
+      // ∂rate/∂slot = rate·∂ln(prefactor) + pref·g′·∂a, with ∂a/∂η_i = −ν
+      for (let t = 0; t < M; t++) d[t] *= rate;
+      for (const p of rx.part) if (p.side === 0) d[1 + p.i] -= pref * gp * p.nu;
+      const dV = pref * gp * daV;
+      for (const p of rx.part) {
+        if (p.side === 1) continue;
+        const row = 1 + p.i, o = b * M + row;
+        res[R[o]] -= s * p.nu * rate;
+        flux[p.i] += s * p.nu * rate;
+        for (let t = 0; t < M; t++) if (d[t] !== 0) this._j(b, row, b, t, -s * p.nu * d[t]);
+        B[R[o]] -= s * p.nu * dV;
+      }
+      for (let t = 0; t < M; t++) if (d[t] !== 0) C[R[b * M + t]] += q * F * s * d[t];
+      this.termDI[k] += q * F * s * dV;
+    });
+  }
+
 
   // One contact (terminal 0 or 1): record the flux through its outer face and the current into
   // the device (read from the end box before anything here is added: whatever the box needs
@@ -1966,6 +2104,7 @@ export class Solver {
     const b = this.blockOfNode[g];
     const sgn = side === 'left' ? 1 : -1;
     const flux = this.contactFlux[side];
+    const Ac = model.grid.area[g]; // the links' laws are per area: what they pass is that times A here
     const dyn = Number.isFinite(dt);
 
     // Before anything is added, each balance residual is the flux into the device here.
@@ -1986,13 +2125,13 @@ export class Solver {
       const link = ct.species[i];
       const o = b * M + 1 + i;
       if (link.type === 'exchange') {
-        res[R[o]] -= link.k * (link.mu / model.RT - (u[o] + uLo[o]));
-        this._j(b, 1 + i, b, 1 + i, link.k);
+        res[R[o]] -= Ac * link.k * (link.mu / model.RT - (u[o] + uLo[o]));
+        this._j(b, 1 + i, b, 1 + i, Ac * link.k);
       } else if (link.type === 'conductance') {
         const Vi = (VT * (u[o] + uLo[o])) / z[i];
-        res[R[o]] -= (link.G * (Vt + link.offset - Vi)) / (z[i] * F);
-        this._j(b, 1 + i, b, 1 + i, (link.G * VT) / (z[i] * z[i] * F));
-        B[R[o]] += -link.G / (z[i] * F);
+        res[R[o]] -= (Ac * link.G * (Vt + link.offset - Vi)) / (z[i] * F);
+        this._j(b, 1 + i, b, 1 + i, (Ac * link.G * VT) / (z[i] * z[i] * F));
+        B[R[o]] += (-Ac * link.G) / (z[i] * F);
       }
     }
 
@@ -2014,15 +2153,15 @@ export class Solver {
       this.contactD[side] = 0;
     } else if (link.type === 'capacitive') {
       // Gate, or metal across a Stern layer, at φ_g = V_t − zeroCharge. D toward +x.
-      const Din = link.C * (Vt - link.zeroCharge - VT * u[b * M]);
+      const Din = Ac * link.C * (Vt - link.zeroCharge - VT * u[b * M]);
       res[R[b * M]] -= Din;
-      this._j(b, 0, b, 0, link.C * VT);
-      B[R[b * M]] += -link.C;
+      this._j(b, 0, b, 0, Ac * link.C * VT);
+      B[R[b * M]] += -Ac * link.C;
       this.contactD[side] = sgn * Din;
       if (dyn) {
         I += (Din - Dstart) / dt;
-        C[R[b * M]] += (-link.C * VT) / dt;
-        this.termDI[k] += link.C / dt;
+        C[R[b * M]] += (-Ac * link.C * VT) / dt;
+        this.termDI[k] += (Ac * link.C) / dt;
       }
     } else if (link.type === 'pinned' || link.type === 'bulk') {
       // The Poisson residual is the outside's charge, D_in.
@@ -2910,7 +3049,7 @@ export class Solver {
       const reg = regions[r], mat = materials[reg.material];
       if (mat.conductor) {
         for (const g of nodes) this._nodeConductor(g, dt);
-        for (const s of segs) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s]);
+        for (const s of segs) this._segmentConductor(s, s + r, s + r + 1, mat, grid.segLength[s] / grid.segArea[s]);
         continue;
       }
       for (const g of nodes) {
@@ -2920,7 +3059,7 @@ export class Solver {
       const rxs = this.rxsIn[reg.material];
       if (rxs.length > 0) for (const g of nodes) this._bulkReactions(g, rxs);
       for (const s of segs) {
-        const bL = s + r, bR = bL + 1, h = grid.segLength[s];
+        const bL = s + r, bR = bL + 1, h = grid.segLength[s] / grid.segArea[s]; // (a length over the cross-section: fluxes are totals)
         this._segmentDisplacement(s, bL, bR, mat, h);
         if (reg.mixing > 0) this._segmentMixing(s, bL, bR, reg.mixing, h, mat);
         if (!mat.ideal) this._segmentConcentrated(s, bL, bR, mat, h, reg.velocity);

package/src/types.js

@@ -154,9 +154,14 @@
  * @property {Source} [V] held terminal voltage, V (default 0, if no I)
  * @property {Source} [I] or: the current driven into the device, A/m² (e.g. 0 for a reference electrode)
  * @property {number} [R] with V: a series resistance, Ω·m²
- * @property {string} [terminal] species whose offset defaults to 0
+ * @property {string} [terminal] species whose offset defaults to 0; with reactions, the electrode's carrier
  * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'equilibrium', offset?: number, mu?: number }
- *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} species
+ *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} [species]
+ * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number }[]} [reactions] an
+ *   electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s)) between the region's
+ *   species and the terminal species at the port's level
+ * @property {number | { x: number[], values: number[] }} [area] with reactions: electrode area per volume,
+ *   m²/m³ (1/h for a film of thickness h), or a profile against the device's x
  */
 
 /**
@@ -170,6 +175,10 @@
  * @property {BulkReactionDef[]} [bulkReactions]
  * @property {{ left?: ContactDef, right?: ContactDef }} [contacts]
  * @property {PortDef[]} [ports] internal ports
+ * @property {'planar' | 'spherical' | 'cylindrical' | { type: 'planar' | 'spherical' | 'cylindrical', r0?: number }
+ *   | { area: { x: number[], values: number[] } }} [geometry] the cross-section A(x): planar (A = 1 m², the
+ *   default: currents read per m²), shells about a centre at r = r0 (m) left of x = 0 (cylindrical: per
+ *   metre of length), or A in m² against x. Currents, fluxes, amounts and charges are then totals through A.
  * @property {GridOptions} [grid]
  */
 
@@ -199,8 +208,10 @@
  *   then the ports by name): its voltage, and its current into the device (A/m²)
  * @property {{ left: ContactResult, right: ContactResult }} contacts
  * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
- * @property {{ name: string, V: number, flux: Record<string, number>, current: number }[]} ports what each
- *   internal port brings into the device
+ * @property {{ name: string, V: number, flux: Record<string, number>, current: number, x?: Float64Array,
+ *   area?: Float64Array, rates?: Float64Array[] }[]} ports what each internal port brings into the device;
+ *   with reactions, also its window's nodes (x, m), area per volume there, and each reaction's rate per area
+ *   at each node (mol/(m²·s), forward)
  * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
  * @property {{ rate: Float64Array, regions: number[], total: number }[]} bulkReactions each bulk reaction's
  *   forward rate per node (mol/(m³·s), NaN where it doesn't run), and per region and in all (mol/(m²·s))