driftlet 0.6.0 → 0.8.0

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);
@@ -995,7 +1039,67 @@ export class Solver {
         }
       }
     }
+    // A floating contact facing a held one starts where the start's own composition puts it: the
+    // held voltage plus the difference between the two terminal species' levels beside each
+    // contact (c0 sets them, and φ was chosen for neutrality, not to match either contact), so
+    // that a transient's first reading means something.
+    const level = (side) => {
+      const ct = model.contacts[side], i = ct.terminal;
+      if (i === null || ct.species[i].type !== 'equilibrium' || z[i] === 0) return NaN;
+      const b = this.blockOfNode[side === 'left' ? 0 : grid.nNodes - 1];
+      return (this.VT * u[b * M + 1 + i]) / z[i] - ct.species[i].offset;
+    };
+    for (const k of this.floating) {
+      const t = this.terms[k], held = k === 0 ? 1 : 0;
+      if (t.kind === 'port' || held >= this.terms.length || this.floating.includes(held)) continue;
+      const shift = level(t.side) - level(this.terms[held].side);
+      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 η,
@@ -1038,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++) {
@@ -1149,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);
@@ -1157,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);
@@ -1185,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
@@ -1434,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++) {
@@ -1519,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;
@@ -1538,6 +1643,27 @@ export class Solver {
         res[R[o]] = -deta; // μ̄ continuous
         this._j(bf, r, bR, r, 1);
         this._j(bf, r, bL, r, -1);
+      } else if (type === 'permeability') {
+        // Electrodiffusion through a thin membrane in a constant field: Scharfetter–Gummel across
+        // the face with D/h → P, its drift taken over the face's whole jump in the standard level
+        // zφ̂ + μ°/RT − ln c_ref (the φ jump of a capacitive face, and any step between the two
+        // materials). Between like solutions it's Goldman–Hodgkin–Katz's flux,
+        //   N = P·zu·(c_L − c_R e^{zu})/(e^{zu} − 1),  u = (φ_R − φ_L)/V_T,
+        // and it's exactly zero where μ̄ is level.
+        const gl = grid.regionEnd[f], gr = gl + 1, kl = gl * n + i, kr = gr * n + i, zi = z[i], P = itf.links[i].P;
+        const shift = this.mu0hat[kr] - this.mu0hat[kl] - Math.log(this.cRef[kr] / this.cRef[kl]);
+        const d = zi * (u[bR * M] - u[bL * M] + (uLo[bR * M] - uLo[bL * M])) + shift;
+        const E = Math.expm1(-deta); // η_R − η_L
+        const gBc = P * bernoulli(d) * this.c[kl];
+        const dNdd = -P * bernoulliDerivative(d) * this.c[kl] * E;
+        res[R[o]] = u[o] + gBc * E;
+        this._j(bf, r, bf, r, 1);
+        this._j(bf, r, bL, r, -gBc);
+        this._j(bf, r, bR, r, gBc * (E + 1));
+        if (zi !== 0) {
+          this._j(bf, r, bL, 0, zi * dNdd - zi * gBc * E);
+          this._j(bf, r, bR, 0, -zi * dNdd);
+        }
       } else {
         // conductance: J = G (V_L − V_R), V = V_T η / z  ⇒  N = G V_T (η_L − η_R) / (z² F)
         const gG = (itf.links[i].G * VT) / (z[i] * z[i] * F);
@@ -1546,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
@@ -1768,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;
@@ -1780,12 +1906,28 @@ export class Solver {
       const g = p.side ? gR : gL, b = p.side ? bR : bL, o = b * M + 1 + p.i;
       aHi -= p.nu * u[o];
       aLo -= p.nu * uLo[o];
-      if (rx.srh || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
+      if (rx.srh || rx.vmax || this.nodeConductor[g] === p.i) continue; // a conductor's carrier has activity 1
       const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
       pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
       this._dlnc(g, p.i, e, p.side ? dR : dL);
     }
-    if (rx.srh) {
+    if (rx.vmax) {
+      // Saturating: r = vmax Π (c/(c + K))^{|ν|} (1 − e^{−a}); ∂ln S/∂ln c = |ν| K/(c + K).
+      let S = 1;
+      rx.part.forEach((p, q) => {
+        if (p.nu >= 0) return;
+        const g = p.side ? gR : gL, cc = c[g * n + p.i], K = rx.K[q];
+        S *= powi(cc / (cc + K), -p.nu);
+        this._dlnc(g, p.i, (-p.nu * K) / (cc + K), p.side ? dR : dL);
+      });
+      const a = aHi + aLo, back = Math.exp(-a);
+      rate = rx.vmax * S * -Math.expm1(-a);
+      for (let s = 0; s < M; s++) {
+        dL[s] *= rate;
+        dR[s] *= rate;
+      }
+      for (const p of rx.part) (p.side ? dR : dL)[1 + p.i] -= rx.vmax * S * back * p.nu;
+    } else if (rx.srh) {
       // SRH, with n and p each at its own side's edge node.
       const { n: pn, p: pp } = rx.srh, gn = pn.side ? gR : gL, gq = pp.side ? gR : gL;
       const s = this._srhRate(rx.srh, c[gn * n + pn.i], c[gq * n + pp.i], aHi + aLo);
@@ -1812,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);
     }
   }
 
@@ -1895,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
@@ -1913,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.
@@ -1933,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);
       }
     }
 
@@ -1961,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.
@@ -2447,10 +2639,10 @@ export class Solver {
     if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }');
     const plan = probes.map((p, k) => {
       const path = `advance: probes[${k}]`;
-      const i = species.findIndex((sp) => sp.name === p?.species);
-      if (i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
-      const quantity = p.quantity ?? 'c';
-      if (quantity !== 'c' && quantity !== 'V') fail(`${path}.quantity must be 'c' (mol/m³) or 'V' (the species voltage)`);
+      const quantity = p?.quantity ?? 'c';
+      if (quantity !== 'c' && quantity !== 'V' && quantity !== 'phi') fail(`${path}.quantity must be 'c' (mol/m³), 'V' (the species voltage) or 'phi' (φ, V)`);
+      const i = quantity === 'phi' ? -1 : species.findIndex((sp) => sp.name === p?.species);
+      if (quantity !== 'phi' && i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
       if (quantity === 'V' && species[i].z === 0) fail(`${path}: '${p.species}' is neutral, so it has no voltage; read 'c'`);
       const x = grid.x, inside = (r) => p.x >= x[grid.regionStart[r]] && p.x <= x[grid.regionEnd[r]];
       let r;
@@ -2470,6 +2662,7 @@ export class Solver {
     const out = plan.map(() => []);
     const { n, M } = this;
     const at = (q, g) => {
+      if (q.quantity === 'phi') return this.phiUndefined[g] ? NaN : this.VT * (this.u[this.blockOfNode[g] * M] + this.uLo[this.blockOfNode[g] * M]);
       if (!this.present[g * n + q.i]) return NaN;
       if (q.quantity === 'c') return this.c[g * n + q.i];
       const o = this.blockOfNode[g] * M + 1 + q.i;
@@ -2856,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) {
@@ -2866,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))

package/types/grid.d.ts

@@ -26,3 +26,32 @@ export function buildGrid(regions: {
     regionEnd: Int32Array<ArrayBuffer>;
     length: number;
 };
+/**
+ * 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: ReturnType<typeof buildGrid>, geometry: {
+    type: "planar";
+} | {
+    type: "spherical" | "cylindrical";
+    r0: number;
+} | {
+    type: "profile";
+    x: ArrayLike<number>;
+    values: ArrayLike<number>;
+}): {
+    nNodes: number;
+    x: Float64Array<ArrayBuffer>;
+    nodeRegion: Int32Array<ArrayBuffer>;
+    segLength: Float64Array<ArrayBuffer>;
+    segRegion: Int32Array<ArrayBuffer>;
+    segFace: Int32Array<ArrayBuffer>;
+    vol: Float64Array<ArrayBuffer>;
+    regionStart: Int32Array<ArrayBuffer>;
+    regionEnd: Int32Array<ArrayBuffer>;
+    length: number;
+};

package/types/index.d.ts

@@ -51,7 +51,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: number, opts?: {
@@ -63,8 +63,8 @@ export class Device {
         method?: "bdf2" | "be";
         probes?: {
             x: number;
-            species: string;
-            quantity?: "c" | "V";
+            species?: string;
+            quantity?: "c" | "V" | "phi";
             region?: string | number;
         }[];
     }): Solution;

package/types/junction.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Henderson's liquid-junction potential, φ_R − φ_L (V): the junction taken to be the two solutions
+ * mixed in one proportion at every point (every ion's mixing fraction the same curve). Exact for a single binary salt, a close estimate otherwise (it's what
+ * JPCalc and most electrophysiology corrections use).
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @param {{ T?: number }} [opts] K (default 298.15)
+ */
+export function henderson(left: Record<string, number>, right: Record<string, number>, ions: Record<string, {
+    z: number;
+    D: number;
+}>, { T }?: {
+    T?: number;
+}): number;
+/**
+ * Planck's liquid-junction potential, φ_R − φ_L (V): the steady state of constrained diffusion,
+ * a junction zone held between the two solutions, electroneutral, carrying no current. Solved by
+ * shooting on the Nernst–Planck equations across it (its length drops out). Exact for that
+ * junction; equal to Henderson's for a single binary salt.
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @param {{ T?: number, steps?: number }} [opts] K (default 298.15); RK4 steps across (default 4000)
+ */
+export function planck(left: Record<string, number>, right: Record<string, number>, ions: Record<string, {
+    z: number;
+    D: number;
+}>, { T, steps }?: {
+    T?: number;
+    steps?: number;
+}): number;

package/types/kit.d.ts

@@ -36,6 +36,7 @@ export function vacuumZeroCharge(def: object, workFunction: number, inside: Vacu
 export { live } from "./live.js";
 export { recorder } from "./recorder.js";
 export { check } from "./checks.js";
+export { polarization } from "./polarization.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
  * in electron energy, the vacuum level just outside lies (the offset, V). So
@@ -61,5 +62,6 @@ export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
+export { henderson, planck } from "./junction.js";
 export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from "./devices.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";