driftlet 0.14.0 → 0.16.4

package/src/solution.js

@@ -152,6 +152,16 @@ export function makeSolution(solver, result = {}) {
     }
     return out;
   });
+  // A floating terminal passes what its circuit says, exactly (see passedCurrent).
+  if (sol.converged) {
+    for (const k of solver.floating) {
+      const I = solver.passedCurrent(k);
+      if (k === 0) sol.contacts.left.current = I;
+      else if (k === 1) sol.contacts.right.current = -I;
+      else sol.ports[k - 2].current = I;
+    }
+  }
+  sol.current = sol.contacts.right.current;
   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
   // device, conduction plus displacement. They sum to zero in steady state.
@@ -228,8 +238,15 @@ export function makeSolution(solver, result = {}) {
       );
     }
   });
-  const cond = solver.conditioning, un = solver.unreached;
-  if (result.converged === false && un) {
+  const cond = solver.conditioning, un = solver.unreached, ch = solver.charging;
+  if (result.converged === false && ch) {
+    const A = model.geometry.type === 'planar' ? 'A/m²' : 'A';
+    sol.warnings.push(
+      `${ch.terminal}: driven at ${ch.current.toPrecision(3)} ${A}, it has no steady state: ` +
+        (ch.what.length > 0 ? `what it feeds (${ch.what.join(', ')}) is closed but for it, so it only stores what comes in (a host filling)` : 'it passes current only by charging its capacitance') +
+        '. advance() in time instead; at no current, a steady solve keeps the charge it holds.',
+    );
+  } else 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';
     // The opposite sign within reach: likely a sign slip (a drive is the current into the device).
     const flipped = Math.min(I0, I1) <= -un.target && -un.target <= Math.max(I0, I1);
@@ -245,13 +262,31 @@ export function makeSolution(solver, result = {}) {
     );
   } 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';
+    // An ion there so scarce beside the others (a minority swept out of a junction by a large
+    // bias, excluded at a sharp neutral face) that its level can't be held in double precision.
+    let scarce = null;
+    for (const g of cond.nodes ?? []) {
+      let all = 0;
+      for (let i = 0; i < model.species.length; i++) if (model.species[i].z !== 0 && solver.c[g * model.species.length + i] > 0) all += Math.abs(model.species[i].z) * solver.c[g * model.species.length + i];
+      for (let i = 0; i < model.species.length; i++) {
+        const c = solver.c[g * model.species.length + i], r = c / all;
+        if (model.species[i].z !== 0 && c > 0 && r < 1e-10 && !(r >= scarce?.r)) scarce = { r, name: model.species[i].name };
+      }
+    }
     sol.warnings.push(
-      `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): part of the device is held ` +
-        'only weakly, e.g. a floating region coupled to the rest through tiny conductances or rates, or a stiff ' +
-        'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).',
+      `the steady system ${digits} near x = ${cond.x.toExponential(3)} m (${cond.where}): ` +
+        (scarce?.r < 1e-24
+          ? `there ${scarce.name} is ${scarce.r.toExponential(0)} of the ions around it, too scarce for its level to be held in double precision ` +
+            '(a minority swept out of a junction by a large bias, or excluded at a sharp neutral face). Drive less; or, at a face, ' +
+            'resolve its double layer (ε > 0) rather than make it a sharp neutral step.'
+          : 'part of the device is held only weakly, e.g. a floating region coupled to the rest through tiny conductances or rates, or a stiff ' +
+            'chain whose level nothing pins. Strengthen that coupling, or anchor the region (a port, a contact).' +
+            (scarce
+              ? ` Or a species there too scarce to hold: ${scarce.name} is ${scarce.r.toExponential(0)} of the ions around it (a layer depleted past a limiting current, say), which a smaller drive avoids.`
+              : '')),
     );
   }
-  if (result.converged === false && !result.stopped && !un && !(cond && cond.digits > 12)) {
+  if (result.converged === false && !result.stopped && !un && !ch && !(cond && cond.digits > 12)) {
     sol.warnings.push(
       'the solve did not converge, and nothing specific showed why. ' +
         'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
@@ -271,15 +306,136 @@ export function makeSolution(solver, result = {}) {
       );
     }
   };
+  // Beside a strictly neutral (ε = 0) material, a face's charge is held in the edge node's box,
+  // which then acts as a diffuse layer as wide as the box: a capacitance F²Σz²c·w/RT in series
+  // with the face's (a Helmholtz C, or for a pinned face whatever holds the charge on the other
+  // side: a conductor's sheet, or a resolved diffuse layer, ε/λ_D), which shrinks as the grid is
+  // refined. Flag it where it lowers that capacitance by over 2%. (Where the box is the smaller
+  // part, as an ε = 0 metal's against a semiconductor's depletion, it's a fine stand-in for the
+  // metal's own screening.)
+  const boxed = (g, h, phi, other, where) => {
+    const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
+    if (mat.conductor || mat.epsr !== 0 || solver.phiUndefined?.[g]) return;
+    const s2 = solver.screening(g), Cbox = (F * F * s2 * h) / (2 * RT);
+    if (!(s2 > 0)) return;
+    let C = phi.C;
+    if (phi.type === 'pinned') {
+      const om = other < 0 ? null : model.materials[model.regions[grid.nodeRegion[other]].material];
+      C = !om || om.conductor ? Infinity : (om.epsr * EPS0) / debye(other);
+    }
+    if (!(C / (C + Cbox) > 0.02)) return;
+    const lowers = Number.isFinite(C) ? `lowering the double-layer capacitance by ${((100 * C) / (C + Cbox)).toFixed(0)}%` : 'which alone sets its charge';
+    sol.warnings.push(
+      `${where}: the face's charge sits in the strictly neutral cell beside it (${h.toExponential(2)} m), which acts as a diffuse layer that wide ` +
+        `(${Cbox.toPrecision(2)} F/m² in series), ${lowers}, so it depends on the mesh. ` +
+        (Number.isFinite(C)
+          ? `Coarsen the grid there: a cell of ${((2 * 49 * C * RT) / (F * F * s2)).toExponential(1)} m or more keeps it within 2%.`
+          : "Give the face a Helmholtz capacitance (phi: { type: 'capacitive', C }), or make it neutral."),
+    );
+  };
   interfaces.forEach((itf, f) => {
     if (itf.phi.type === 'neutral') return;
     const gL = grid.regionEnd[f], gR = grid.regionStart[f + 1];
     check(gL, grid.segLength[gL - 1], `interfaces[${f}] (left side)`);
     check(gR, grid.segLength[gR], `interfaces[${f}] (right side)`);
+    boxed(gL, grid.segLength[gL - 1], itf.phi, gR, `interfaces[${f}] (left side)`);
+    boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`);
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-  if (resolves(contacts.left)) check(0, grid.segLength[0], 'contacts.left');
-  if (resolves(contacts.right)) check(nNodes - 1, grid.segLength[nNodes - 2], 'contacts.right');
+  if (resolves(contacts.left)) {
+    check(0, grid.segLength[0], 'contacts.left');
+    boxed(0, grid.segLength[0], contacts.left.phi, -1, 'contacts.left');
+  }
+  if (resolves(contacts.right)) {
+    check(nNodes - 1, grid.segLength[nNodes - 2], 'contacts.right');
+    boxed(nNodes - 1, grid.segLength[nNodes - 2], contacts.right.phi, -1, 'contacts.right');
+  }
+  // Electrons or holes above their band's effective density of states (the material's cRef)
+  // under Boltzmann statistics: degenerate, where those statistics no longer hold (a surface
+  // driven past what a reaction can take away piles holes up to 1e9 mol/m³ and still converges).
+  model.regions.forEach((reg, r) => {
+    const mat = model.materials[reg.material];
+    if (mat.conductor) return;
+    model.species.forEach((sp, i) => {
+      if ((sp.name !== 'e-' && sp.name !== 'h+') || !mat.present[i] || mat.modelOf?.[i] >= 0) return;
+      let top = 0, at = NaN;
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const c = solver.c[g * model.species.length + i];
+        if (c > top) [top, at] = [c, grid.x[g]];
+      }
+      if (top > mat.cRef[i]) {
+        sol.warnings.push(
+          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, above its cRef (${mat.cRef[i].toExponential(2)}, the band's effective density of states), where Boltzmann statistics no longer hold: ` +
+            'give the material Fermi–Dirac statistics (docs/statistics.md), or ask whether this state is physical (a surface driven past what can carry its carriers away).',
+        );
+      }
+    });
+  });
+  // A reaction a steady state needs at equilibrium, left out of it (see stuckReactions).
+  if (sol.steady) {
+    for (const { where, affinity } of solver.stuckReactions()) {
+      sol.warnings.push(
+        `${where}: out of equilibrium by ${(affinity * solver.VT * 1e3).toPrecision(3)} mV of affinity wherever it acts, yet nothing else makes or uses what it changes, so a steady state needs it at equilibrium. ` +
+          'Its rate is too small for the solve to resolve, and it was left where the solve began: this is not a steady state. Raise its rate constant (the steady state does not depend on it), or advance() in time to see how slowly it gets there.',
+      );
+    }
+  }
+  // Any other species denser than any material can be (1e6 mol/m³: water is 5.5e4, a metal's
+  // atoms ~1.5e5): a level set where the device can't follow it, such as a contact's for one ion
+  // far from its neighbours' (Na⁺ held at 1.2e37 mol/m³, whose currents then read 1e28 A/m²).
+  model.regions.forEach((reg, r) => {
+    const mat = model.materials[reg.material];
+    if (mat.conductor) return;
+    model.species.forEach((sp, i) => {
+      if (sp.name === 'e-' || sp.name === 'h+' || !mat.present[i]) return;
+      let top = 0, at = NaN;
+      for (let g = grid.regionStart[r]; g <= grid.regionEnd[r]; g++) {
+        const c = solver.c[g * model.species.length + i];
+        if (c > top) [top, at] = [c, grid.x[g]];
+      }
+      if (top > 1e6) {
+        sol.warnings.push(
+          `${reg.name}: ${sp.name} reaches ${top.toExponential(2)} mol/m³ at x = ${at.toExponential(3)} m, denser than any material: ` +
+            'a level set where the device cannot follow it. Check what holds it there (the V or bath of a contact, its mu0 and cRef) with describe() from driftlet/kit.',
+        );
+      }
+    });
+  });
+  // A contact that holds its end neutral ('bulk': a bath, an ohmic contact) cuts off any space
+  // charge reaching it: a double layer longer than its region. The charge it cuts off is about
+  // ρ λ_D at the node beside it; against the region's own space charge (half Σ|ρ| over it, the
+  // two signs of a double layer), warn past 1e-3.
+  for (const side of ['left', 'right']) {
+    if (contacts[side].phi.type !== 'bulk') continue;
+    const r = side === 'left' ? 0 : model.regions.length - 1, a = grid.regionStart[r], b = grid.regionEnd[r];
+    const mat = model.materials[model.regions[r].material];
+    if (!(mat.epsr > 0) || mat.conductor || b - a < 3) continue;
+    const n = model.species.length, fixed = model.regions[r].fixedCharge ?? 0;
+    const rho = (g) => {
+      let q = fixed;
+      for (let i = 0; i < n; i++) if (solver.c[g * n + i] > 0) q += F * model.species[i].z * solver.c[g * n + i];
+      return q;
+    };
+    // (and beside the contact the material is itself out of neutrality, by more than round-off:
+    // a quasi-neutral layer split off a junction's holds almost no space charge, so the ratio
+    // below alone would read its round-off as a cut-off layer)
+    const gross = (g) => {
+      let q = Math.abs(fixed);
+      for (let i = 0; i < n; i++) if (solver.c[g * n + i] > 0) q += F * Math.abs(model.species[i].z) * solver.c[g * n + i];
+      return q;
+    };
+    let total = 0;
+    for (let g = a; g <= b; g++) total += (Math.abs(rho(g)) * grid.vol[g]) / 2;
+    const g1 = side === 'left' ? a + 1 : b - 1, lam = debye(g1), w = (grid.x[g1 + 1] - grid.x[g1 - 1]) / 2;
+    const cut = (Math.abs(rho(g1)) * lam * grid.vol[g1]) / w;
+    if (Number.isFinite(cut) && total > 0 && cut > 1e-3 * total && Math.abs(rho(g1)) > 1e-3 * gross(g1)) {
+      sol.warnings.push(
+        `contacts.${side}: the space charge in ${model.regions[r].name} reaches the contact, which holds its end neutral and so cuts it off (a double layer or depletion longer than the region): ` +
+          `the charge beside the contact is ${(cut / total).toPrecision(2)} of the space charge in the region, and the error in that charge can be several times more. ` +
+          'Lengthen the region (a crowded double layer grows as the root of the voltage).',
+      );
+    }
+  }
 
   // Steep profiles carrying current: Scharfetter–Gummel takes the field as uniform across each
   // cell, which fails where it isn't, as at an electrode where a species is nearly depleted (there