driftlet 0.9.0 → 0.11.4

package/src/polarization.js

@@ -21,12 +21,15 @@ const fail = (message) => {
  * @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,
+ * @param {{ surface?: 'held' | 'equilibrium' }} [opts] an electrode port's surface coverages: held as
+ *   in `sol` (the default: this instant's curves), or in equilibrium at each V (the steady-state
+ *   curve, with a passive film's active–passive peak), each species by the reaction that makes it
+ * @returns {{ V: Float64Array, current: Float64Array, bare?: 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) {
+export function polarization(device, sol, where, V, opts = {}) {
   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)
@@ -58,16 +61,17 @@ export function polarization(device, sol, where, V) {
   } 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) => {
+  // Each reaction as a = base + s·V − Σ ν_s ln a_s (the surface species' activities apart), with
+  // its prefactor apart from them too, so a surface can be held or re-equilibrated at each V.
+  const parts = 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;
+    let base = rx.fixedA, s = 0, q = 0, pref = rx.vmax ? rx.vmax : rx.k0;
+    const surf = [];
     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);
+        // a surface species: μ = μ° + RT ln a, a = θ/θ₀
+        base -= (p.nu * surface.sp[p.s].mu0) / RT;
+        surf.push({ s: p.s, nu: p.nu, e: p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha });
         return;
       }
       if (p.side === carrier.side && p.i === carrier.i) {
@@ -75,7 +79,7 @@ export function polarization(device, sol, where, V) {
         return;
       }
       const g = nodeOf(p), name = species[p.i].name;
-      a0 -= (p.nu * sol.mu[name][g]) / RT;
+      base -= (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) {
@@ -83,14 +87,45 @@ export function polarization(device, sol, where, V) {
       } 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 { rx, k, base, s, q, pref, surf };
+  });
+  // The surface's activities (ln a) and bare fraction at a level: held as `sol` has them, or in
+  // equilibrium there, each species by the first reaction that makes it from the solution alone.
+  const held = surface && surface.theta.map((t) => Math.log(t / surface.bare));
+  let former = null;
+  if (surface && opts.surface === 'equilibrium') {
+    former = surface.sp.map((sp, x) => {
+      const f = parts.find((pt) => pt.surf.length === 1 && pt.surf[0].s === x);
+      if (!f) fail(`polarization: no reaction makes ${sp.name} from the solution alone, so its equilibrium coverage isn't defined`);
+      return f;
+    });
+  } else if (opts.surface !== undefined && opts.surface !== 'held') fail("polarization: surface must be 'held' (the default) or 'equilibrium'");
+  const surfaceAt = (v) => {
+    if (!surface) return { lnA: [], bare: 1 };
+    // base + s v − ν ln a = 0 for each species' former
+    const lnA = former ? former.map((f) => (f.base + f.s * v) / f.surf[0].nu) : held;
+    if (!former) return { lnA, bare: surface.bare };
+    const m = Math.max(0, ...lnA);
+    let sum = Math.exp(-m);
+    for (const l of lnA) sum += Math.exp(l - m);
+    return { lnA, bare: Math.exp(-m) / sum };
+  };
+  const at = Array.from(Vs, (v) => surfaceAt(v));
+  const out = parts.map(({ rx, k, base, s, q, pref, surf }) => {
+    const rate = Float64Array.from(Vs, (v, j) => {
+      const { lnA, bare } = at[j];
+      let a = base + s * v, p = pref * (rx.bare ? bare : 1);
+      for (const u of surf) {
+        a -= u.nu * lnA[u.s];
+        p *= Math.exp(u.e * lnA[u.s]);
+      }
+      return rx.vmax ? p * -Math.expm1(-a) : p * (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) };
+    // (its level with the surface as held)
+    const aHeld = surf.reduce((t, u) => t - u.nu * (held ? held[u.s] : 0), base);
+    return { equation: names?.[k]?.equation ?? `reaction ${k}`, level: -aHeld / 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 };
+  return { V: Vs, current, ...(surface ? { bare: Float64Array.from(at, (x) => x.bare) } : {}), reactions: out };
 }

package/src/solution.js

@@ -106,17 +106,17 @@ export function makeSolution(solver, result = {}) {
       flux[species[i].name] = solver.portFlux[k][i];
       current += F * species[i].z * solver.portFlux[k][i];
     }
-    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]));
+      // A capacitance's charging current, and its charge (the port's side), like a gate's; and
+      // its charge per area of electrode at each node, σ = C (V − zeroCharge − φ) (none at an
+      // end whose φ its contact sets: the contact holds that charge).
+      const dt = solver.lastDt;
+      out.current += Number.isFinite(dt) ? (solver.portQ[k] - solver.portQOld[k]) / dt : 0;
+      out.charge = solver.portQ[k];
+      const { C: Cs, zeroCharge } = port.capacitance, last = model.grid.nNodes - 1;
+      const sets = (side) => ['pinned', 'bulk'].includes(model.contacts[side].phi.type);
+      out.sigma = Float64Array.from(port.nodes, (g) => ((g === 0 && sets('left')) || (g === last && sets('right')) ? 0 : Cs * (solver.termV[2 + k] - zeroCharge - phi[g])));
     }
     if (port.area !== null) {
       out.x = Float64Array.from(port.nodes, (g) => model.grid.x[g]);
@@ -181,8 +181,26 @@ export function makeSolution(solver, result = {}) {
   // Resolution warnings: where the model resolves a double layer (dipole or capacitive faces,
   // gate contacts), check the local Debye length against the adjacent cell.
   sol.warnings = [...(model.warnings ?? [])];
-  const cond = solver.conditioning;
-  if (result.converged === false && cond && cond.digits > 12) {
+  // A surface covered almost completely: its coverages' η barely move anything below ~1e-10 bare,
+  // and Newton loses them (a transient can stall there).
+  sol.ports.forEach((p) => {
+    if (!p.bare) return;
+    const min = Math.min(...p.bare);
+    if (min < 1e-10) {
+      sol.warnings.push(
+        `ports ${p.name}: its surface is covered to a bare fraction of ${min.toExponential(1)} at x = ${p.x[p.bare.indexOf(min)].toExponential(3)} m. ` +
+          'Below ~1e-10 the coverage barely affects anything and the solver struggles with it; a passive metal blocks to 1e-3–1e-6, so make the film less stable (raise its μ°).',
+      );
+    }
+  });
+  const cond = solver.conditioning, un = solver.unreached;
+  if (result.converged === false && un) {
+    const [[V0, I0], [V1, I1]] = [un.low, un.high], g = (x) => x.toPrecision(3), A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    sol.warnings.push(
+      `${un.terminal}: no steady state passes the driven current ${g(un.target)} ${A}; held from ${g(V0)} V to ${g(V1)} V ` +
+        `it passed ${g(I0)} to ${g(I1)} ${A} (a limiting current, or kinetics too slow). Drive less, or hold a voltage.`,
+    );
+  } else if (result.converged === false && cond && cond.digits > 12) {
     const digits = Number.isFinite(cond.digits) ? `lost ${cond.digits.toFixed(0)} of its ~16 digits` : 'was exactly singular';
     sol.warnings.push(
       `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): part of the device is held ` +