driftlet 0.6.0 → 0.8.0

package/src/junction.js

@@ -0,0 +1,164 @@
+// Liquid-junction potentials from formulas, for driftlet/kit: the diffusion potential φ_R − φ_L
+// between two neutral solutions, as the classical theories give it. A device simulates the actual
+// junction (steady between two baths, it is Planck's; stepping from a sharp boundary, a free
+// diffusion junction); these are for comparison, and for quick estimates.
+
+import { DeviceError } from './errors.js';
+import { FARADAY, GAS_CONSTANT } from './constants.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+
+// The ions both solutions name, with their charge and diffusivity, and both concentrations.
+function prepare(left, right, ions, what) {
+  const names = [...new Set([...Object.keys(left), ...Object.keys(right)])];
+  return names.map((name) => {
+    const ion = ions[name];
+    if (!ion || !Number.isFinite(ion.z) || !(ion.D > 0)) fail(`${what}: no { z, D } for '${name}' in the ions given`);
+    const cL = left[name] ?? 0, cR = right[name] ?? 0;
+    if (!(cL >= 0 && cR >= 0)) fail(`${what}: concentrations must be ≥ 0 (mol/m³), got ${name} ${cL} and ${cR}`);
+    return { name, z: ion.z, D: ion.D, cL, cR };
+  });
+}
+function neutral(list, side, what) {
+  let q = 0, s = 0;
+  for (const p of list) {
+    q += p.z * p[side];
+    s += Math.abs(p.z * p[side]);
+  }
+  if (Math.abs(q) > 1e-9 * s) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution carries a net charge (Σ z·c = ${q.toPrecision(3)} mol/m³)`);
+}
+
+/**
+ * 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, right, ions, { T = 298.15 } = {}) {
+  const list = prepare(left, right, ions, 'henderson');
+  neutral(list, 'cL', 'henderson');
+  neutral(list, 'cR', 'henderson');
+  let a = 0, b = 0, gL = 0, gR = 0;
+  for (const { z, D, cL, cR } of list) {
+    a += z * D * (cR - cL);
+    b += z * z * D * (cR - cL);
+    gL += z * z * D * cL;
+    gR += z * z * D * cR;
+  }
+  const VT = (GAS_CONSTANT * T) / FARADAY;
+  if (b === 0) return 0;
+  return (-VT * a * Math.log(gR / gL)) / b;
+}
+
+/**
+ * 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, right, ions, { T = 298.15, steps = 4000 } = {}) {
+  const list = prepare(left, right, ions, 'planck');
+  neutral(list, 'cL', 'planck');
+  neutral(list, 'cR', 'planck');
+  const n = list.length, z = list.map((p) => p.z), D = list.map((p) => p.D), Dmax = Math.max(...D);
+  const scale = Math.max(...list.map((p) => Math.max(p.cL, p.cR)));
+  const cL = list.map((p) => p.cL / scale), cR = list.map((p) => p.cR / scale);
+  // Across the zone (x from 0 to 1, D's scale dropping out with its length), each ion's flux J_i is
+  // constant: c_i' = −J_i/D_i − z_i c_i ψ', with ψ = Fφ/RT, and neutrality fixes the field,
+  // ψ' = −Σ(z_i J_i/D_i)/Σ(z_i² c_i). Integrated from the left; the fluxes are chosen so the
+  // right comes out as given and no current flows.
+  const deriv = (c, J, out) => {
+    let num = 0, den = 0;
+    for (let i = 0; i < n; i++) {
+      num += (z[i] * J[i]) / D[i];
+      den += z[i] * z[i] * Math.max(c[i], 0);
+    }
+    const dpsi = -num / den;
+    for (let i = 0; i < n; i++) out[i] = -J[i] / D[i] - z[i] * c[i] * dpsi;
+    return dpsi;
+  };
+  const shoot = (J) => {
+    const c = cL.slice(), k1 = new Float64Array(n), k2 = new Float64Array(n), k3 = new Float64Array(n), k4 = new Float64Array(n), t = new Float64Array(n);
+    const h = 1 / steps;
+    let psi = 0;
+    for (let s = 0; s < steps; s++) {
+      const p1 = deriv(c, J, k1);
+      for (let i = 0; i < n; i++) t[i] = c[i] + (h / 2) * k1[i];
+      const p2 = deriv(t, J, k2);
+      for (let i = 0; i < n; i++) t[i] = c[i] + (h / 2) * k2[i];
+      const p3 = deriv(t, J, k3);
+      for (let i = 0; i < n; i++) t[i] = c[i] + h * k3[i];
+      const p4 = deriv(t, J, k4);
+      for (let i = 0; i < n; i++) c[i] += (h / 6) * (k1[i] + 2 * k2[i] + 2 * k3[i] + k4[i]);
+      psi += (h / 6) * (p1 + 2 * p2 + 2 * p3 + p4);
+    }
+    return { c, psi };
+  };
+  // Residuals: n − 1 ions reaching the right (the last follows by neutrality), and no current.
+  const residual = (J) => {
+    const { c, psi } = shoot(J), r = new Float64Array(n);
+    for (let i = 0; i < n - 1; i++) r[i] = c[i] - cR[i];
+    let I = 0;
+    for (let i = 0; i < n; i++) I += z[i] * J[i];
+    r[n - 1] = I / Dmax; // scaled like the concentrations
+    return { r, psi };
+  };
+  let J = list.map((_, i) => -D[i] * (cR[i] - cL[i])); // plain diffusion to start
+  let { r, psi } = residual(J);
+  for (let it = 0; it < 50; it++) {
+    const norm = Math.max(...r.map(Math.abs));
+    if (norm < 1e-12) break;
+    // Newton with a finite-difference Jacobian.
+    const Jac = [];
+    for (let k = 0; k < n; k++) {
+      const dJ = 1e-7 * Math.max(Math.abs(J[k]), 1e-3 * D[k]), Jp = J.slice();
+      Jp[k] += dJ;
+      const rp = residual(Jp).r;
+      Jac.push(Array.from(rp, (v, i) => (v - r[i]) / dJ));
+    }
+    const step = solveDense(Jac, r, n);
+    let lambda = 1, next;
+    for (;;) {
+      const Jn = J.map((v, k) => v - lambda * step[k]);
+      next = residual(Jn);
+      if (Math.max(...next.r.map(Math.abs)) < norm || lambda < 1e-3) {
+        J = Jn;
+        break;
+      }
+      lambda /= 2;
+    }
+    ({ r, psi } = next);
+  }
+  if (!(Math.max(...r.map(Math.abs)) < 1e-8)) fail('planck: the shooting did not converge');
+  return ((GAS_CONSTANT * T) / FARADAY) * psi;
+}
+
+// Solves Σ_k A[k][i] x_k = b_i (A given column by column), by Gaussian elimination with pivoting.
+function solveDense(cols, b, n) {
+  const M = Array.from({ length: n }, (_, i) => [...cols.map((col) => col[i]), b[i]]);
+  for (let p = 0; p < n; p++) {
+    let best = p;
+    for (let i = p + 1; i < n; i++) if (Math.abs(M[i][p]) > Math.abs(M[best][p])) best = i;
+    [M[p], M[best]] = [M[best], M[p]];
+    for (let i = p + 1; i < n; i++) {
+      const f = M[i][p] / M[p][p];
+      for (let j = p; j <= n; j++) M[i][j] -= f * M[p][j];
+    }
+  }
+  const x = new Array(n).fill(0);
+  for (let i = n - 1; i >= 0; i--) {
+    let s = M[i][n];
+    for (let j = i + 1; j < n; j++) s -= M[i][j] * x[j];
+    x[i] = s / M[i][i];
+  }
+  return x;
+}

package/src/kit.js

@@ -12,7 +12,9 @@ export { live } from './live.js';
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from './sources.js';
 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/recorder.js

@@ -15,7 +15,7 @@ const now = () => (typeof performance !== 'undefined' ? performance.now() : Date
  * neither, at the end of each `advance()` call. The trace (`t`, `current`, `voltage`, and
  * `probes` if given) runs from the start through every accepted step of every call.
  * @param {import('./index.js').Device} device
- * @param {{ every?: number, times?: number[], probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
+ * @param {{ every?: number, times?: number[], probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
  */
 export function recorder(device, opts = {}) {
   const { every, times, probes } = opts;

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,