driftlet 1.0.1 → 1.1.1

package/src/data.js

@@ -3,8 +3,9 @@
 // only. How levels line up at an interface, and a surface's work function, belong to that
 // interface or surface and are never in here.
 
-import { DeviceError, checkOptions } from './errors.js';
+import { DeviceError, checkOptions, shown } from './errors.js';
 import { FARADAY, GAS_CONSTANT, AVOGADRO } from './constants.js';
+import { powr } from './pow.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -43,7 +44,7 @@ export const WATER_EPSR = 78.3;
 
 /**
  * Semiconductors at 300 K (Sze, Physics of Semiconductor Devices, 2nd ed., 1981, appendix):
- * relative permittivity, band gap Eg (eV), electron affinity chi (V), effective densities of
+ * relative permittivity, band gap Eg (eV), electron affinity chi (eV), effective densities of
  * states Nc and Nv (cm⁻³), and drift mobilities of lightly doped material mun and mup
  * (cm²/(V·s)).
  */
@@ -65,7 +66,8 @@ export const METALS = freeze(
 
 /**
  * Water with the named ions, as a library piece for `build()`: each ion as a species
- * (c_ref = 1 M) and the material `water` holding them, with D and μ° from `IONS`.
+ * (c_ref = 1 M) and the material `water` holding them, with D and μ° from `IONS`. The data are
+ * 25 °C's, and the material says so (T: 298.15): a device at another temperature warns.
  * @param {string[]} names ions from `IONS`
  * @param {{ epsr?: number, material?: string }} [opts] permittivity (default that of water;
  *   0 makes the solution strictly neutral, without double layers), and the material's name
@@ -81,24 +83,53 @@ export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
     species.push({ name, z: ion.z, cRef: 1000 });
     entries[name] = { D: ion.D, mu0: ion.mu0 };
   }
-  return { species, materials: { [material]: { epsr, species: entries } } };
+  // (25 °C data: a device at another temperature warns)
+  return { species, materials: { [material]: { epsr, species: entries, T: 298.15 } } };
 }
 
+// How the semiconductors' data move with temperature, for semiconductor(name, { T }):
+// - the gap by Varshni's form, Eg(T) = Eg0 − αT²/(T + β) (Y. P. Varshni, Physica 34, 149, 1967),
+//   with Thurmond's parameters (C. D. Thurmond, J. Electrochem. Soc. 122, 1133, 1975, as
+//   tabulated in Sze, 2nd ed.): Eg0 (eV), alpha (eV/K), beta (K). Only the shift from 300 K is
+//   used, on the table's Eg, so T = 300 K is the table: Varshni's own Eg(300) differs from it by
+//   4.5 meV (Si, 1.1245), 3.4 meV (Ge, 0.6634) and 1.5 meV (GaAs, 1.4225).
+// - Nc and Nv ∝ T^1.5 (parabolic bands, effective masses held fixed).
+// - mobilities ∝ T^−gn and T^−gp, the lattice-limited power laws for lightly doped material
+//   (Sze, 2nd ed., ch. 1): approximate, and wrong where impurity scattering matters (heavy
+//   doping, or cold). D follows from μ and T by Einstein's relation, D = μkT/q.
+// - the electron affinity chi isn't moved.
+const WITH_T = {
+  Si: { Eg0: 1.17, alpha: 4.73e-4, beta: 636, gn: 2.42, gp: 2.2 },
+  Ge: { Eg0: 0.7437, alpha: 4.774e-4, beta: 235, gn: 1.66, gp: 2.33 },
+  GaAs: { Eg0: 1.519, alpha: 5.405e-4, beta: 204, gn: 1.0, gp: 2.1 },
+};
+const T_RANGE = [150, 500];
+
 /**
  * A semiconductor from `SEMICONDUCTORS`, as a library piece: electrons `e-` and holes `h+`, with
- * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at 300 K, and μ°_e⁻ = 0 (φ
- * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K, so use `T: 300`.
+ * c_ref = Nc and Nv, D from the mobilities by the Einstein relation at T, and μ°_e⁻ = 0 (φ
+ * anchored at the conduction band) and μ°_h⁺ = Eg·F. The data are for 300 K; another T (150 to
+ * 500 K) moves them: the gap by Varshni's shift from 300 K, Nc and Nv as T^1.5, the mobilities by
+ * lattice-limited power laws (light doping). The material carries its `T`, and a device at
+ * another temperature warns: give the device the same T.
  * Statistics are ideal (Boltzmann); add Fermi–Dirac to the material for degenerate doping.
  * @param {string} name 'Si', 'Ge' or 'GaAs'
- * @param {{ material?: string }} [opts]
+ * @param {{ material?: string, T?: number }} [opts] the material's name, and the temperature
+ *   (K, default 300, the table's)
  * @returns {{ species: object[], materials: Record<string, object> }}
  */
-export function semiconductor(name, { material = name } = {}) {
-  if (arguments[1]?.T !== undefined) fail('semiconductor: the data are for 300 K and take no T: give the device T: 300, or write your own material for another temperature (SEMICONDUCTORS has the numbers)');
-  checkOptions('semiconductor', arguments[1], ['material']);
+export function semiconductor(name, { material = name, T = 300 } = {}) {
+  checkOptions('semiconductor', arguments[1], ['material', 'T']);
   const sc = SEMICONDUCTORS[name];
   if (!sc) fail(`semiconductor: no data for '${name}' (the library has ${Object.keys(SEMICONDUCTORS).join(', ')})`);
-  const VT = (GAS_CONSTANT * 300) / FARADAY;
+  if (typeof T !== 'number') fail(`semiconductor: T must be a number, the temperature in K, got ${shown(T)}`);
+  if (!(Number.isFinite(T) && T >= T_RANGE[0] && T <= T_RANGE[1])) {
+    fail(`semiconductor: T must be the temperature in K, from ${T_RANGE[0]} to ${T_RANGE[1]} (the range its temperature laws are good for), got ${T}`);
+  }
+  const { alpha, beta, gn, gp } = WITH_T[name];
+  const t = T / 300, varshni = (T) => (alpha * T * T) / (T + beta);
+  const Eg = sc.Eg - (varshni(T) - varshni(300));
+  const VT = (GAS_CONSTANT * T) / FARADAY;
   const perCm3 = (n) => (n * 1e6) / AVOGADRO;
   return {
     species: [
@@ -107,16 +138,76 @@ export function semiconductor(name, { material = name } = {}) {
     ],
     materials: {
       [material]: {
+        T, // the temperature the data are for: a device at another warns
         epsr: sc.epsr,
         species: {
-          'e-': { D: sc.mun * 1e-4 * VT, mu0: 0, cRef: perCm3(sc.Nc) },
-          'h+': { D: sc.mup * 1e-4 * VT, mu0: sc.Eg * FARADAY, cRef: perCm3(sc.Nv) },
+          'e-': { D: sc.mun * powr(t, -gn) * 1e-4 * VT, mu0: 0, cRef: perCm3(sc.Nc * powr(t, 1.5)) },
+          'h+': { D: sc.mup * powr(t, -gp) * 1e-4 * VT, mu0: Eg * FARADAY, cRef: perCm3(sc.Nv * powr(t, 1.5)) },
         },
       },
     },
   };
 }
 
+/**
+ * A trap level in a semiconductor that holds charge: its two charge states as immobile species
+ * (D = 0), filled and emptied by capturing carriers, e⁻ + X⁰ = X⁻ and X⁻ + h⁺ = X⁰ (acceptor-like)
+ * or X⁺ + e⁻ = X⁰ and X⁰ + h⁺ = X⁺ (donor-like). In steady state it recombines at exactly the
+ * `srh` law's rate with the same τ_n, τ_p and n₁, and its charge is in Poisson's equation, which
+ * the `srh` law (the trap's occupancy eliminated) leaves out. Each node keeps its own total.
+ * @param {{ species: object[], materials: Record<string, object> }} lib a library entry with e⁻
+ *   and h⁺ (semiconductor()), returned with the trap's states added
+ * @param {{ density: number, tauN: number, tauP: number, n1?: number, charge?: 'acceptor' | 'donor',
+ *   name?: string, material?: string, T?: number }} opts density N_t (mol/m³); τ_n = 1/(c_n N_t)
+ *   and τ_p = 1/(c_p N_t) (s) at that density; n₁, the electron density that half-fills it
+ *   (mol/m³; default n_i, midgap); T (K, default the material's T, else 300)
+ * @returns {{ library: object, bulkReactions: object[], c0: Record<string, number> }} the library
+ *   for build(), the capture reactions, and c0 for each layer holding the trap (its total N_t)
+ */
+export function trap(lib, { density, tauN, tauP, n1, charge = 'acceptor', name = 'X', material, T } = {}) {
+  checkOptions('trap', arguments[1], ['density', 'tauN', 'tauP', 'n1', 'charge', 'name', 'material', 'T']);
+  if (!lib || typeof lib !== 'object' || typeof lib.materials !== 'object') fail('trap: give the library entry first, semiconductor(\'Si\') say, then { density, tauN, tauP }');
+  const names = Object.keys(lib.materials);
+  const m = material ?? (names.length === 1 ? names[0] : fail(`trap: the library has materials ${names.join(', ')}: say which, with material`));
+  const mat = lib.materials[m];
+  if (!mat) fail(`trap: no material '${m}' in the library (it has ${names.join(', ')})`);
+  const el = mat.species?.['e-'], ho = mat.species?.['h+'];
+  if (!el || !ho) fail(`trap: material '${m}' needs e- and h+ (a semiconductor)`);
+  const pos = (v, what) => (Number.isFinite(v) && v > 0 ? v : fail(`trap: ${what}, got ${shown(v)}`));
+  pos(density, 'density must be the trap density N_t > 0 (mol/m³; units.perCm3(1e15), say)');
+  pos(tauN, 'tauN must be the electron lifetime τ_n = 1/(c_n N_t) > 0 (s)');
+  pos(tauP, 'tauP must be the hole lifetime τ_p = 1/(c_p N_t) > 0 (s)');
+  // (the material's own temperature, where it gives one: semiconductor()'s does)
+  if (T === undefined) T = mat.T ?? 300;
+  pos(T, 'T must be the temperature in K');
+  if (mat.T !== undefined && Math.abs(T - mat.T) > 0.01) fail(`trap: T is ${T} K, but material '${m}' is for ${mat.T} K; leave T out (the trap takes the material's), or remake the material for ${T} K`);
+  if (charge !== 'acceptor' && charge !== 'donor') fail(`trap: charge must be 'acceptor' (0/−) or 'donor' (+/0), got ${JSON.stringify(charge)}`);
+  if (typeof name !== 'string' || !/^[A-Za-z][\w()]*$/.test(name)) fail(`trap: name must be a plain name for the trap (its states are name0 and name- or name+), got ${JSON.stringify(name)}`);
+  const RT = GAS_CONSTANT * T, cRefE = el.cRef ?? lib.species.find((sp) => sp.name === 'e-')?.cRef;
+  const cRefH = ho.cRef ?? lib.species.find((sp) => sp.name === 'h+')?.cRef;
+  const ni = Math.sqrt(cRefE * cRefH * Math.exp(-(ho.mu0 - el.mu0) / RT));
+  const half = n1 === undefined ? ni : pos(n1, 'n1 must be the electron density that half-fills the trap > 0 (mol/m³)');
+  // The filled state's μ° sits an electron's μ at n₁ above the empty one's: half full at n = n₁.
+  const [empty, full] = charge === 'acceptor' ? [`${name}0`, `${name}-`] : [`${name}+`, `${name}0`];
+  const zEmpty = charge === 'acceptor' ? 0 : 1;
+  const states = {
+    [empty]: { D: 0, mu0: 0, cRef: density },
+    [full]: { D: 0, mu0: el.mu0 + RT * Math.log(half / cRefE), cRef: density },
+  };
+  return {
+    library: {
+      species: [...lib.species, { name: empty, z: zEmpty }, { name: full, z: zEmpty - 1 }],
+      materials: { ...lib.materials, [m]: { ...mat, species: { ...mat.species, ...states } } },
+    },
+    bulkReactions: [
+      { equation: `e- + ${empty} = ${full}`, kf: { [m]: 1 / (tauN * density) } },
+      { equation: `${full} + h+ = ${empty}`, kf: { [m]: 1 / (tauP * density) } },
+    ],
+    // (each node keeps the total, X⁰ + X⁻ say; the split is the solve's to find)
+    c0: { [empty]: density / 2, [full]: density / 2 },
+  };
+}
+
 /**
  * A metal from `METALS` as a conductor material, its carrier `e-`.
  * @param {string} name

package/src/describe.js

@@ -138,7 +138,7 @@ export function describe(def) {
   const { species, materials, regions, grid } = model;
   const RT = GAS_CONSTANT * model.T;
   const lines = [];
-  const warnings = unitWarnings(def);
+  const warnings = [...model.warnings, ...unitWarnings(def)]; // (the definition's own: a material's data at another T, …)
   const total = grid.x[grid.x.length - 1] - grid.x[0];
   lines.push(`${regions.length} region${regions.length > 1 ? 's' : ''}, ${si(total, 'm')}, ${grid.x.length} nodes, T = ${model.T} K`);
   const geo = model.geometry;

package/src/device.js

@@ -9,7 +9,7 @@
 import { buildGrid, applyGeometry } from './grid.js';
 import { FARADAY, GAS_CONSTANT } from './constants.js';
 import { normalizeStatistics } from './statistics.js';
-import { DeviceError } from './errors.js';
+import { DeviceError, shown } from './errors.js';
 import { stoichiometry as equationStoichiometry, faceSides, parseEquation } from './equation.js';
 
 export { DeviceError };
@@ -47,12 +47,12 @@ function fields(obj, path, allowed) {
 }
 
 function finite(v, path) {
-  need(isFiniteNumber(v), `${path} must be a finite number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v), `${path} must be a finite number, got ${shown(v)}`);
   return v;
 }
 
 function positive(v, path) {
-  need(isFiniteNumber(v) && v > 0, `${path} must be a positive number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v > 0, `${path} must be a positive number, got ${shown(v)}`);
   return v;
 }
 
@@ -108,9 +108,9 @@ function profile(v, path, what, ok, okText) {
     `${path} must be a profile { x, values }: two arrays of the same length, positions (m, the device's x) and ${what}`,
   );
   v.x.forEach((xk, k) => {
-    need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${path}.x must be finite and strictly increasing, but x[${k}] is ${JSON.stringify(xk)}`);
+    need(isFiniteNumber(xk) && (k === 0 || xk > v.x[k - 1]), `${path}.x must be finite and strictly increasing, but x[${k}] is ${shown(xk)}`);
   });
-  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${JSON.stringify(y)}`));
+  v.values.forEach((y, k) => need(isFiniteNumber(y) && ok(y), `${path}.values[${k}] must be ${okText}, got ${shown(y)}`));
   return { x: Float64Array.from(v.x), values: Float64Array.from(v.values) };
 }
 
@@ -138,7 +138,7 @@ function srhLaw(sdef, path, list, species, timeKeys) {
 }
 
 function nonNegative(v, path) {
-  need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v >= 0, `${path} must be a non-negative number, got ${shown(v)}`);
   return v;
 }
 
@@ -151,7 +151,7 @@ export function normalizeDevice(def) {
   need(isObject(def), 'device definition must be an object');
   fields(def, 'device', ['T', 'species', 'materials', 'regions', 'interfaces', 'bulkReactions', 'contacts', 'ports', 'grid', 'geometry']);
 
-  const T = def.T === undefined ? 298.15 : positive(def.T, 'T');
+  const T = def.T === undefined ? 298.15 : positive(def.T, 'T (the temperature, K)');
   const RT = GAS_CONSTANT * T;
 
   // --- species
@@ -164,7 +164,7 @@ export function normalizeDevice(def) {
     fields(sp, path, ['name', 'z', 'cRef']);
     need(typeof sp.name === 'string' && sp.name.length > 0, `${path}.name must be a non-empty string`);
     need(!speciesIndex.has(sp.name), `${path}.name: duplicate species '${sp.name}'`);
-    need(Number.isInteger(sp.z), `${path}.z (charge number) must be an integer, got ${JSON.stringify(sp.z)}`);
+    need(Number.isInteger(sp.z), `${path}.z (charge number) must be an integer, got ${shown(sp.z)}`);
     const cRef = sp.cRef === undefined ? undefined : positive(sp.cRef, `${path}.cRef`);
     speciesIndex.set(sp.name, i);
     species.push({ name: sp.name, z: sp.z, cRef });
@@ -179,13 +179,15 @@ export function normalizeDevice(def) {
   for (const [mname, mat] of Object.entries(def.materials)) {
     const path = `materials.${mname}`;
     need(isObject(mat), `${path} must be an object`);
+    // The temperature a material's data are for, where it says (semiconductor()'s do).
+    const dataT = mat.T === undefined ? undefined : positive(mat.T, `${path}.T (the temperature its data are for, K)`);
     if (mat.conductor !== undefined) {
       materialIndex.set(mname, materials.length);
-      materials.push(normalizeConductor(mat, mname, path, species, speciesIndex));
+      materials.push({ ...normalizeConductor(mat, mname, path, species, speciesIndex), dataT });
       continue;
     }
     // ε = 0 makes the material strictly neutral: Poisson becomes local neutrality there.
-    fields(mat, path, ['epsr', 'species', 'statistics']);
+    fields(mat, path, ['epsr', 'species', 'statistics', 'T']);
     const epsr = nonNegative(mat.epsr, `${path}.epsr`);
     need(isObject(mat.species), `${path}.species must be an object mapping species names to parameters`);
     const present = new Uint8Array(nSpecies);
@@ -205,7 +207,7 @@ export function normalizeDevice(def) {
       need(c !== undefined, `${spath}.cRef: no reference concentration (give it here or on the species)`);
       cRef[i] = positive(c, `${spath}.cRef`);
     }
-    const m = { name: mname, epsr, present, D, mu0, cRef };
+    const m = { name: mname, epsr, present, D, mu0, cRef, dataT };
     const st = normalizeStatistics({ ...m, statistics: mat.statistics }, path, species, speciesIndex, RT, { need, finite, positive });
     m.models = st.models;
     m.modelOf = st.modelOf;
@@ -285,7 +287,7 @@ export function normalizeDevice(def) {
           c0Profile[i] = profile(v, at, 'concentrations (mol/m³)', (ck) => ck > 0, `a concentration > 0 (mol/m³)${none}`);
           continue;
         }
-        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, values }, got ${JSON.stringify(v)}${none}`);
+        need(isFiniteNumber(v) && v > 0, `${at} must be a concentration > 0 (mol/m³) or a profile { x, values }, got ${shown(v)}${none}`);
         c0[i] = v;
       }
     }
@@ -306,6 +308,23 @@ export function normalizeDevice(def) {
     };
   });
 
+  // A material whose data are for another temperature than the device's is silently wrong there
+  // (a semiconductor's n_i, gap and mobilities; water's μ°, ε and D): say so (for each material a
+  // region uses).
+  materials.forEach((m, k) => {
+    if (m.dataT === undefined || Math.abs(m.dataT - T) <= 0.01 || !regions.some((reg) => reg.material === k)) return;
+    const own = Object.keys(def.materials[m.name].species ?? {}), semi = own.includes('e-') && own.includes('h+');
+    warnings.push(
+      `materials.${m.name}: its data are for ${m.dataT} K, but the device is at ${T} K${def.T === undefined ? ' (the default, as it gives no T)' : ''}, ` +
+        (semi
+          ? `so they don't hold there (a semiconductor's n_i, gap and mobilities are ${m.dataT} K's): give the device T: ${m.dataT}, ` +
+            `or remake the material for ${T} K (semiconductor(name, { T: ${T} }))`
+          : `so they don't hold there: its μ° (so equilibrium constants and electrode potentials, Kw's by ~6× between 6 and 25 °C), ` +
+            `permittivity and diffusivities are ${m.dataT} K's. Give the device T: ${m.dataT}, or give the material data for ${T} K ` +
+            `and its T (aqueous() has none at other temperatures yet)`),
+    );
+  });
+
   // --- interfaces (one per face between consecutive regions)
   const nFaces = regions.length - 1;
   const idefs = def.interfaces ?? [];
@@ -490,7 +509,7 @@ function stoichiometry(map, path, fixed, fixedPath, species, speciesIndex, RT) {
   const list = [];
   let fixedA = 0, charge = 0, nFixed = 0;
   for (const [name, nu] of Object.entries(map)) {
-    need(Number.isInteger(nu) && nu !== 0, `${path}.${name} must be a non-zero integer, got ${JSON.stringify(nu)}`);
+    need(Number.isInteger(nu) && nu !== 0, `${path}.${name} must be a non-zero integer, got ${shown(nu)}`);
     if (speciesIndex.has(name)) {
       const i = speciesIndex.get(name);
       list.push({ i, nu });
@@ -1048,7 +1067,7 @@ function gatedBy(raw, gates, lpath, where) {
   return Object.entries(raw).map(([gname, p]) => {
     const q = gates.findIndex((gt) => gt.name === gname);
     need(q >= 0, `${lpath}.gates.${gname}: no such gate${gates.length ? ` (there are ${gates.map((gt) => gt.name).join(', ')})` : ` (define it in ${where}.gates)`}`);
-    need(Number.isInteger(p) && p >= 1 && p <= 8, `${lpath}.gates.${gname}: the exponent must be a whole number from 1 to 8, got ${JSON.stringify(p)}`);
+    need(Number.isInteger(p) && p >= 1 && p <= 8, `${lpath}.gates.${gname}: the exponent must be a whole number from 1 to 8, got ${shown(p)}`);
     return [q, p];
   });
 }
@@ -1081,6 +1100,8 @@ function normalizeConductor(mat, mname, path, species, speciesIndex) {
   for (const k of ['epsr', 'species', 'statistics']) {
     need(mat[k] === undefined, `${path}.${k}: a conductor takes only { conductor: { species, conductivity } }`);
   }
+  fields(mat, path, ['conductor', 'T']);
+  fields(mdef, `${path}.conductor`, ['species', 'conductivity']);
   need(speciesIndex.has(mdef.species), `${path}.conductor.species: unknown species ${JSON.stringify(mdef.species)}${known(speciesIndex)}`);
   const i = speciesIndex.get(mdef.species);
   need(species[i].z !== 0, `${path}.conductor.species: the conductor's carrier must be charged`);
@@ -1175,7 +1196,7 @@ function defaultInterfaceLinks(matL, matR, species) {
 
 function transferCoefficient(v, path) {
   if (v === undefined) return 0.5;
-  need(isFiniteNumber(v) && v >= 0 && v <= 1, `${path} must be between 0 and 1, got ${JSON.stringify(v)}`);
+  need(isFiniteNumber(v) && v >= 0 && v <= 1, `${path} must be between 0 and 1, got ${shown(v)}`);
   return v;
 }
 

package/src/difference.js

@@ -8,13 +8,19 @@
 // storage and space charge depend on δη_i − z_i δφ̂ alone; the displacement on δφ̂_R − δφ̂_L. A
 // uniform shift of a region (z_i s on each η_i, s on φ̂) then gives exactly zero, as it must.
 //
+// Non-ideal statistics couple the species: c_i depends on every ζ_j, so a node's storage of i
+// has a term in each δη_j − z_j δφ̂ (K_ij), and a flux has side terms in those at either end (its
+// c_L and the excess potentials in its drift). Each is a term in the same differences, so the
+// shift still gives exactly zero.
+//
 // Indices are compact (the solver's rix), with the sink (index N) for an unknown that isn't one:
 // vectors passed in are read there as zero.
 export class DifferenceTerms {
-  constructor(N, nodes, segments) {
+  constructor(N, nodes, segments, sides = 0) {
     this.N = N;
     this.dead = new Uint8Array(N + 1); // rows replaced since (a contact's level, a held stretch)
-    this.nI = new Int32Array(nodes); // node term: η column (= its balance row), φ̂ column (= Gauss row)
+    this.nR = new Int32Array(nodes); // node term: its balance row, η column, φ̂ column (= Gauss row)
+    this.nI = new Int32Array(nodes);
     this.nP = new Int32Array(nodes);
     this.nZ = new Float64Array(nodes);
     this.nMass = new Float64Array(nodes); // storage per unit (δη − z δφ̂), times 1/dt (or iω)
@@ -24,6 +30,9 @@ export class DifferenceTerms {
     this.sC = new Float64Array(3 * segments); // a, b, d
     this.dI = new Int32Array(2 * segments); // displacement: φ̂_L, φ̂_R
     this.dK = new Float64Array(segments);
+    this.xI = new Int32Array(4 * sides); // a flux's side term: its two rows, an η column, its φ̂ column
+    this.xZ = new Float64Array(sides);
+    this.xC = new Float64Array(sides);
     this.combos = []; // [rk, ri, w]: row rk += w × row ri (strictly neutral nodes' charge rows)
     this.t = new Float64Array(N + 1);
     this.x = new Float64Array(N + 1);
@@ -33,13 +42,16 @@ export class DifferenceTerms {
   // Afresh for an assembly; `rate` multiplies storage in captured rows (1/dt).
   reset(rate = 0) {
     this.rate = rate;
-    this.nn = this.ns = this.nd = 0;
+    this.nn = this.ns = this.nd = this.nx = 0;
     this.dead.fill(0);
     this.combos.length = 0;
   }
 
-  node(i, p, z, mass, charge) {
+  // Storage in row r (mass) and charge in Gauss row p, per unit δη_i − z δφ̂ (row r = i, unless
+  // non-ideal statistics couple the species).
+  node(i, p, z, mass, charge, r = i) {
     const k = this.nn++;
+    this.nR[k] = r;
     this.nI[k] = i;
     this.nP[k] = p;
     this.nZ[k] = z;
@@ -59,6 +71,17 @@ export class DifferenceTerms {
     this.sC[3 * k + 2] = d;
   }
 
+  // A flux from row rL to row rR, per unit δη_i − z δφ̂ at one end.
+  side(rL, rR, i, p, z, w) {
+    const k = this.nx++;
+    this.xI[4 * k] = rL;
+    this.xI[4 * k + 1] = rR;
+    this.xI[4 * k + 2] = i;
+    this.xI[4 * k + 3] = p;
+    this.xZ[k] = z;
+    this.xC[k] = w;
+  }
+
   displacement(pL, pR, k) {
     const q = this.nd++;
     this.dI[2 * q] = pL;
@@ -83,7 +106,7 @@ export class DifferenceTerms {
     for (let k = 0; k < this.nn; k++) {
       const i = this.nI[k], p = this.nP[k], z = this.nZ[k];
       let f = 0;
-      if (row === i) f += mass * this.nMass[k];
+      if (row === this.nR[k]) f += mass * this.nMass[k];
       if (row === p) f += this.nCharge[k];
       if (f === 0) continue;
       add(i, f);
@@ -99,6 +122,12 @@ export class DifferenceTerms {
       add(this.sI[4 * k + 2], s * (-z * a - d));
       add(this.sI[4 * k + 3], s * d);
     }
+    for (let k = 0; k < this.nx; k++) {
+      const s = row === this.xI[4 * k] ? 1 : row === this.xI[4 * k + 1] ? -1 : 0;
+      if (s === 0) continue;
+      add(this.xI[4 * k + 2], s * this.xC[k]);
+      add(this.xI[4 * k + 3], -s * this.xZ[k] * this.xC[k]);
+    }
     for (let q = 0; q < this.nd; q++) {
       const pL = this.dI[2 * q], pR = this.dI[2 * q + 1], s = row === pL ? 1 : row === pR ? -1 : 0;
       if (s === 0) continue;
@@ -114,10 +143,10 @@ export class DifferenceTerms {
     for (let j = 0; j < N; j++) x[j] = v[j];
     x[N] = 0;
     t.fill(0);
-    const { nI, nP, nZ, nMass, nCharge } = this;
+    const { nR, nI, nP, nZ, nMass, nCharge } = this;
     for (let k = 0; k < this.nn; k++) {
       const i = nI[k], p = nP[k], w = x[i] - nZ[k] * x[p];
-      t[i] += mass * nMass[k] * w;
+      t[nR[k]] += mass * nMass[k] * w;
       t[p] += steady * nCharge[k] * w;
     }
     if (steady !== 0) {
@@ -128,6 +157,12 @@ export class DifferenceTerms {
         t[iL] += dN;
         t[iR] -= dN;
       }
+      const { xI, xZ, xC } = this;
+      for (let k = 0; k < this.nx; k++) {
+        const dN = steady * xC[k] * (x[xI[4 * k + 2]] - xZ[k] * x[xI[4 * k + 3]]);
+        t[xI[4 * k]] += dN;
+        t[xI[4 * k + 1]] -= dN;
+      }
       for (let q = 0; q < this.nd; q++) {
         const pL = dI[2 * q], pR = dI[2 * q + 1], dD = -steady * dK[q] * (x[pR] - x[pL]);
         t[pL] += dD;

package/src/errors.js

@@ -39,3 +39,21 @@ export function checkOptions(where, opts, allowed, Kind = DeviceError) {
     throw new Kind(`${where}: no option '${k}'${near ? ` (did you mean '${near}'?)` : ''}; the options are ${allowed.join(', ')}`);
   }
 }
+
+/**
+ * A value as an error message shows it: a number as itself (NaN and Infinity too, which JSON
+ * would print as null), a string quoted and called one ("350", a string, where a number was
+ * wanted).
+ * @param {unknown} v
+ * @returns {string}
+ */
+export function shown(v) {
+  if (typeof v === 'number' || typeof v === 'bigint' || v === undefined) return String(v);
+  if (typeof v === 'string') return `${JSON.stringify(v)} (a string)`;
+  if (typeof v === 'function') return 'a function';
+  try {
+    return JSON.stringify(v, (k, x) => (typeof x === 'number' && !Number.isFinite(x) ? String(x) : x)) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/index.js

@@ -187,7 +187,9 @@ export class Device {
     // A solve that fails reports the state it failed in, and leaves the device as it was: a
     // device with no steady state (a host filling at a current) can still advance() from there.
     const snap = this.solver._snapshot();
-    const sol = makeSolution(this.solver, this.solver.solveSteady(opts));
+    const result = this.solver.solveSteady(opts);
+    // (a failed solve's state isn't a solution: its accuracy warnings are left out)
+    const sol = makeSolution(this.solver, result.converged ? result : { ...result, unsolved: true });
     if (!sol.converged) this.solver._restore(snap);
     return sol;
   }

package/src/kit.js

@@ -18,7 +18,7 @@ export { check } from './checks.js';
 export { particles } from './particles.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';
+export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal, trap } from './data.js';
 
 const fail = (message) => {
   throw new DeviceError(message);

package/src/solution.js

@@ -292,6 +292,13 @@ export function makeSolution(solver, result = {}) {
         'Check the definition with describe() (from driftlet/kit); approach this state in smaller steps (a sweep, or advance() in time); or refine the grid.',
     );
   }
+  // The warnings below judge a solution's accuracy (its grid, its double layers). Of the state a
+  // steady solve gave up in, which isn't a solution, they say nothing useful (a driven current
+  // it couldn't pass leaves the device at ±26 V, where depletion reaches the contacts), so they're
+  // left out there; the two about the state itself (degenerate carriers, a species denser than
+  // any material) stay, as possible causes, and say they're of that state. (A failed time step
+  // restores the last good state, which is a solution: its warnings all stand.)
+  const solved = !result.unsolved, stopped = solved ? '' : ' (in the state the unconverged solve stopped in)';
   const debye = (g) => {
     const mat = model.materials[model.regions[grid.nodeRegion[g]].material];
     const s2 = solver.screening(g); // zᵀKz: Σ z² c for ideal statistics
@@ -347,7 +354,7 @@ export function makeSolution(solver, result = {}) {
     );
   };
   interfaces.forEach((itf, f) => {
-    if (itf.phi.type === 'neutral') return;
+    if (itf.phi.type === 'neutral' || !solved) 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)`);
@@ -357,11 +364,11 @@ export function makeSolution(solver, result = {}) {
     boxed(gR, grid.segLength[gR], itf.phi, gL, `interfaces[${f}] (right side)`, sigma, reacting(1));
   });
   const resolves = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-  if (resolves(contacts.left)) {
+  if (solved && 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)) {
+  if (solved && 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');
   }
@@ -380,7 +387,7 @@ export function makeSolution(solver, result = {}) {
       }
       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: ` +
+          `${reg.name}${stopped}: ${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).',
         );
       }
@@ -410,7 +417,7 @@ export function makeSolution(solver, result = {}) {
       }
       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: ` +
+          `${reg.name}${stopped}: ${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.',
         );
       }
@@ -421,7 +428,7 @@ export function makeSolution(solver, result = {}) {
   // ρ λ_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;
+    if (contacts[side].phi.type !== 'bulk' || !solved) 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;
@@ -458,7 +465,7 @@ export function makeSolution(solver, result = {}) {
   // a concentration ratio r across it). Flag a region's end cell whose field is well above its
   // neighbour's while its concentration changes steeply, for species carrying the current. (A
   // pn depletion region's field changes smoothly from cell to cell, which SG handles.)
-  if (Number.isFinite(sol.current)) {
+  if (solved && Number.isFinite(sol.current)) {
     const share = species.map((sp, i) =>
       Math.max(Math.abs(sp.z * (sol.contacts.left.flux[sp.name] ?? 0)), Math.abs(sp.z * (sol.contacts.right.flux[sp.name] ?? 0))),
     );