driftlet 1.0.0 → 1.1.0

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)).
  */
@@ -84,21 +85,49 @@ export function aqueous(names, { epsr = WATER_EPSR, material = 'water' } = {}) {
   return { species, materials: { [material]: { epsr, species: entries } } };
 }
 
+// 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 +136,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,17 @@ export function normalizeDevice(def) {
     };
   });
 
+  // A material whose data are for another temperature than the device's gives the wrong n_i, gap
+  // and mobilities, silently: 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;
+    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)' : ''}, ` +
+        `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} }))`,
+    );
+  });
+
   // --- interfaces (one per face between consecutive regions)
   const nFaces = regions.length - 1;
   const idefs = def.interfaces ?? [];
@@ -355,8 +368,8 @@ export function normalizeDevice(def) {
   // A contact that passes nothing can't be driven by a current.
   for (const side of ['left', 'right']) {
     const ct = contacts[side];
-    const passes = ct.species.some((l) => l.type !== 'blocked') || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
+    const passes = ct.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0) || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
+    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked charged species, no gate)`);
     ct.passes = passes;
   }
   checkLevel(terminals.map((t) => t.drive), terminals.map((t) => (t.kind === 'port' ? ports[t.index] : contacts[t.side])));
@@ -490,7 +503,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 });
@@ -889,7 +902,13 @@ function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, sur
     need(part.some((p) => p.side === 0 || p.side === 2), `${rpath}: no species of the port's region or its surface takes part`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
     need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
-    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
+    const alpha = transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare = rdef.bare === true;
+    // Langmuir sites: the reaction fills Δ of them going forward, and its transition state holds
+    // m bare ones (those it fills, or one if it runs only on bare metal), so the forward rate
+    // goes as θ₀^m and the backward as θ₀^(m−Δ): the prefactor's θ₀^(m(1−α)+(m−Δ)α), with each
+    // surface species at its coverage θ.
+    const fills = part.reduce((t, p) => t + (p.side === 2 ? p.nu : 0), 0), m = Math.max(fills, 0, bare ? 1 : 0);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha, bare, sites: m * (1 - alpha) + (m - fills) * alpha };
   });
 }
 
@@ -1042,7 +1061,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];
   });
 }
@@ -1075,6 +1094,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`);
@@ -1169,7 +1190,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/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/polarization.js

@@ -115,10 +115,10 @@ export function polarization(device, sol, where, V, opts = {}) {
   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);
+      let a = base + s * v, p = pref * (rx.sites ? powr(bare, rx.sites) : 1);
       for (const u of surf) {
         a -= u.nu * lnA[u.s];
-        p *= Math.exp(u.e * lnA[u.s]);
+        p *= Math.exp(u.e * lnA[u.s]) * powr(bare, u.e); // its coverage θ = θ₀ a
       }
       return rx.vmax ? p * -Math.expm1(-a) : p * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
     });

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))),
     );

package/src/solver.js

@@ -373,7 +373,8 @@ export class Solver {
     // φ is undefined in a conductor or an insertion host, and in a charge-free region (no
     // charged species) unless its electrostatic cluster, the regions joined to it by faces that
     // aren't neutral, reaches something that fixes φ: a region with charged species, a gate or
-    // pinned contact, or a capacitive face to a conductor. (Else φ there is a free constant.)
+    // pinned contact, or a face that isn't neutral to a conductor or to a strictly neutral region
+    // with ions. (Else φ there is a free constant.)
     this.phiUndefined = new Uint8Array(nNodes);
     const charged = (mat) => species.some((sp, i) => mat.present[i] && sp.z !== 0);
     const pins = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
@@ -385,8 +386,11 @@ export class Solver {
       while (r1 + 1 < regions.length && model.interfaces[r1].phi.type !== 'neutral' && !free(r1 + 1)) r1++;
       let anchor = (r0 === 0 && pins(contacts.left)) || (r1 === regions.length - 1 && pins(contacts.right));
       for (let r = r0; r <= r1; r++) if (charged(materials[regions[r].material])) anchor = true;
-      if (r0 > 0 && model.interfaces[r0 - 1].phi.type !== 'neutral' && materials[regions[r0 - 1].material].conductor) anchor = true;
-      if (r1 < regions.length - 1 && model.interfaces[r1].phi.type !== 'neutral' && materials[regions[r1 + 1].material].conductor) anchor = true;
+      // A neighbour across a face that isn't neutral: a conductor (a gate), or a strictly neutral
+      // region whose ions fix its φ.
+      const fixes = (r) => materials[regions[r].material].conductor || (!materials[regions[r].material].phiFree && charged(materials[regions[r].material]));
+      if (r0 > 0 && model.interfaces[r0 - 1].phi.type !== 'neutral' && fixes(r0 - 1)) anchor = true;
+      if (r1 < regions.length - 1 && model.interfaces[r1].phi.type !== 'neutral' && fixes(r1 + 1)) anchor = true;
       for (let r = r0; r <= r1; r++) anchored[r] = anchor ? 1 : 2;
       r0 = r1;
     }
@@ -585,6 +589,16 @@ export class Solver {
       const mat = materials[regions[grid.nodeRegion[g]].material], law = contacts[k === 0 ? 'left' : 'right'].phi.type;
       if (!mat.conductor && mat.epsr === 0 && (law === 'bulk' || law === 'neutral') && !this.chargeNode[g] && !this.phiUndefined[g] && this.nodeIdeal[g]) this.lateStorage[g] = 1;
     });
+    // An end node's species held by a port (its contact blocks it, so the level is the port's):
+    // its row is the port's, storage and all, and the contact passes none of it.
+    this.portHeldEnd = new Uint8Array(2 * n);
+    model.ports.forEach((port) => {
+      [0, nNodes - 1].forEach((g, k) => {
+        if (!port.nodes.includes(g)) return;
+        const ct = contacts[k === 0 ? 'left' : 'right'];
+        for (let i = 0; i < n; i++) if (port.species[i].type === 'equilibrium' && ct.species[i].type === 'blocked') this.portHeldEnd[k * n + i] = 1;
+      });
+    });
     this.combining = false;
     this.bookkeeping = regions.map((_, r) => {
       const g0 = grid.regionStart[r], g1 = grid.regionEnd[r], nodes = [], segs = [];
@@ -1895,6 +1909,14 @@ export class Solver {
     // toward their mixed potential.
     for (const k of this.floating) {
       const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      const gate = t.kind === 'contact' ? model.contacts[t.side].phi : null;
+      if (gate?.type === 'capacitive') {
+        // A gate contact likewise: at its zero-charge level from the φ beside it (a pinned
+        // one's charge is the field's, already zero against a neutral start).
+        const g = t.side === 'left' ? 0 : this.nNodes - 1;
+        if (!this.phiUndefined[g]) this.termV[k] = gate.zeroCharge + this.VT * u[this.blockOfNode[g] * M];
+        continue;
+      }
       if (!port?.capacitance) continue;
       let w = 0, sum = 0;
       port.nodes.forEach((g, j) => {
@@ -1968,9 +1990,9 @@ export class Solver {
       }
       const o = b * M + (p.side === 2 ? 1 + n + p.s : 1 + p.i), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
       a -= p.nu * (u[o] + uLo[o]);
-      pref *= p.side === 2 ? Math.exp(e * (u[o] + uLo[o] - port.surface[p.s].mu0 / RT)) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
+      pref *= p.side === 2 ? powr(th[g * nSurf + p.s], e) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
     }
-    if (rx.bare) pref *= this.th0[g];
+    if (rx.sites) pref *= powr(this.th0[g], rx.sites);
     return pref * bvFactor(a, rx.alpha).g;
   }
 
@@ -2193,6 +2215,11 @@ export class Solver {
     if (f >= 0) this._j(b, r, this.blockOfFace[f], 0, (this.sheetSign[g] * this.model.grid.area[g]) / (z[im] * FARADAY * dt));
   }
 
+  // Whether a port holds species i at node g, a device end node (see portHeldEnd).
+  _portHeldAt(g, i) {
+    return g === 0 ? this.portHeldEnd[i] === 1 : g === this.nNodes - 1 && this.portHeldEnd[this.n + i] === 1;
+  }
+
   // Dilute nodes g0…g1 (ideal statistics, c = c_ref e^ζ): storage of each species and the space
   // charge in the Gauss row, written straight into the diagonal blocks by local index. A
   // dielectric is the case with no species.
@@ -2212,7 +2239,7 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         const k = g * n + i;
         if (!present[k]) continue;
-        const ck = c[k], l = loc[lb + 1 + i], stores = !(late && z[i] !== 0);
+        const ck = c[k], l = loc[lb + 1 + i], stores = !(late && z[i] !== 0 && !this._portHeldAt(g, i));
         if (stores) res[R[lb + 1 + i]] += (v * (ck - cOld[k])) / dt;
         q += F * z[i] * ck;
         dq += F * z[i] * z[i] * ck;
@@ -3093,18 +3120,19 @@ export class Solver {
         aLo -= p.nu * uLo[o];
         const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
         if (p.side === 2) {
-          // a surface species at activity θ/θ₀ = e^ζ
-          pref *= Math.exp(e * (u[o] + uLo[o] - surf[p.s].mu0 / RT));
+          // a surface species at its coverage θ = θ₀e^ζ, with ∂ln θ_s/∂η_x = δ_sx − θ_x
+          pref *= powr(th[g * nSurf + p.s], e);
           d[1 + n + p.s] += e;
+          for (let x = 0; x < surf.length; x++) d[1 + n + x] -= e * th[g * nSurf + x];
         } else {
           pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
           this._dlnc(g, p.i, e, d);
         }
       }
-      if (rx.bare) {
-        // on bare metal only: the free fraction θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
-        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= th[g * nSurf + x];
-        pref *= this.th0[g];
+      if (rx.sites) {
+        // the bare sites its transition state holds: θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
+        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= rx.sites * th[g * nSurf + x];
+        pref *= powr(this.th0[g], rx.sites);
       }
       const { g: bv, gp } = bvFactor(aHi + aLo, al);
       const rate = pref * bv;
@@ -3236,8 +3264,9 @@ export class Solver {
     // passes, so their flux is zero.)
     const closedIons = this.combining && dyn && this.chargeNode[g] === 1;
     let I = 0;
+    const held = this.portHeldEnd.subarray(k * n, (k + 1) * n);
     for (let i = 0; i < n; i++) {
-      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0);
+      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0) && !held[i];
       const nIn = active ? res[R[b * M + 1 + i]] : 0;
       flux[i] = sgn * nIn; // (toward +x)
       if (active && z[i] !== 0) {
@@ -3250,7 +3279,7 @@ export class Solver {
     if (this.combining && dyn && this.lateStorage[g] === 1) {
       const v = model.grid.vol[g], { cOld } = this;
       for (let i = 0; i < n; i++) {
-        if (z[i] === 0 || this.loc[b * M + 1 + i] < 0) continue;
+        if (z[i] === 0 || this.loc[b * M + 1 + i] < 0 || held[i]) continue;
         const ci = c[g * n + i], st = (v * (ci - cOld[g * n + i])) / dt;
         res[R[b * M + 1 + i]] += st;
         flux[i] += sgn * st;
@@ -4866,6 +4895,11 @@ export class Solver {
         }
         mu[name].re[g] = RT * xr[b * M + 1 + i];
         mu[name].im[g] = RT * xi[b * M + 1 + i];
+        if (this.nodeConductor[g] >= 0) {
+          // a metal has a Fermi level but no concentration (as a solution reports it)
+          c[name].re[g] = c[name].im[g] = NaN;
+          continue;
+        }
         // δc_i = Σ_j K_ij (δη_j − z_j δφ̂)
         let sr = 0, si = 0;
         for (let j = 0; j < n; j++) {

package/src/stack.js

@@ -4,7 +4,7 @@
 // that you didn't write: it only moves things to where the definition keeps them, and converts
 // the kit's doping shorthand (donors and acceptors).
 
-import { DeviceError, checkOptions } from './errors.js';
+import { DeviceError, checkOptions, shown } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -131,6 +131,7 @@ const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReac
 export function build(def) {
   if (!isObject(def)) fail('build: give { library, stack, … }');
   fields(def, 'build', STACK_FIELDS);
+  if (def.T !== undefined && !(typeof def.T === 'number' && Number.isFinite(def.T) && def.T > 0)) fail(`build.T must be the temperature in K, a positive number, got ${shown(def.T)}`);
   if (def.library !== undefined && !Array.isArray(def.library)) fail('build.library must be a list of { species, materials }');
   const { species, materials } = combine(...(def.library ?? []), { species: def.species ?? [], materials: def.materials ?? {} });