driftlet 0.16.4 → 1.0.1

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) => {
@@ -1905,6 +1927,22 @@ export class Solver {
       });
       if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
     }
+    // A floating port linked to its carrier (no reactions, no double layer: a wire into an
+    // insertion host) starts at that carrier's level across its window, not at 0 V.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      const i = port?.terminal, link = i === null || i === undefined ? null : port.species[i];
+      if (!port || port.reactions.length > 0 || port.capacitance || !link || link.type === 'blocked' || z[i] === 0) continue;
+      let w = 0, sum = 0;
+      port.nodes.forEach((g, j) => {
+        const a = this.model.grid.vol[g] * (this.portArea[t.index]?.[j] ?? 1); // (a window with no area: by volume)
+        w += a;
+        sum += (a * this.VT * u[this.blockOfNode[g] * M + 1 + i]) / z[i];
+      });
+      // (Levels at the start mean something only against a held terminal's, as for a contact.)
+      const held = [0, 1].find((h) => !this.floating.includes(h) && Number.isFinite(level(this.terms[h].side)));
+      if (w > 0 && held !== undefined) this.termV[k] = this.termV[held] + sum / w - (link.offset ?? 0) - level(this.terms[held].side);
+    }
     // Gates start open as far as the starting voltage across their face holds them, α/(α + β).
     for (const gt of this.gateList) {
       const { gate, o } = gt, V = this._gateVoltage(gt), a = gateRate(gate.alpha, V)[0], b = gateRate(gate.beta, V)[0];
@@ -1952,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;
   }
 
@@ -2177,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.
@@ -2196,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;
@@ -3077,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;
@@ -3220,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) {
@@ -3234,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;
@@ -3967,8 +4012,12 @@ export class Solver {
     const trace = { t: [], current: [], voltage: [], ...(sample ? { probes: sample.out } : {}) };
     let steps = 0, rejected = 0, iterations = 0, failed = false;
     // Already there (an animation frame with no time to add): nothing to do, and the step size
-    // carried to the next call stays as it was.
-    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace };
+    // carried to the next call stays as it was. A time already passed, or reached again outside
+    // an animation, is most likely advance(dt) read as a duration: say so.
+    if (!(tEnd > this.time)) {
+      const relative = tEnd < this.time || (this.time > 0 && opts.budgetMs === undefined);
+      return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace, ...(relative ? { stopped: `advance(${tEnd}) did nothing: ${absolute}. To run for a further dt, advance(sol.time + dt)` } : {}) };
+    }
     const t0 = this.time;
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
@@ -4846,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/sources.js

@@ -1,7 +1,7 @@
 // driftlet/kit: sources as plain definition data. Waveforms for a terminal's V or I, an injector
 // port, and band-to-band recombination from a lifetime. Each returns an ordinary spec value.
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const fail = (message) => {
   throw new DeviceError(message);
@@ -19,6 +19,7 @@ const num = (v) => typeof v === 'number' && Number.isFinite(v);
  * @returns {{ t: number[], values: number[] }}
  */
 export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {}) {
+  checkOptions('pulse', arguments[0], ['start', 'width', 'amplitude', 'rise', 'base']);
   need(num(width) && width > 0, `pulse: width must be > 0 (s), got ${width}`);
   need(num(amplitude), `pulse: amplitude must be a finite number (V or A/m²), got ${amplitude}`);
   need(num(start) && start >= 0, `pulse: start must be ≥ 0 (s), got ${start}`);
@@ -35,6 +36,7 @@ export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {})
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function square({ high, low, period, duty = 0.5 } = {}) {
+  checkOptions('square', arguments[0], ['high', 'low', 'period', 'duty']);
   need(num(high) && num(low), `square: high and low must be finite numbers, got ${high} and ${low}`);
   need(num(period) && period > 0, `square: period must be > 0 (s), got ${period}`);
   need(num(duty) && duty > 0 && duty < 1, `square: duty must be between 0 and 1, got ${duty}`);
@@ -49,6 +51,7 @@ export function square({ high, low, period, duty = 0.5 } = {}) {
  * @returns {{ t: number[], values: number[], repeat: true }}
  */
 export function triangle({ from, to, period } = {}) {
+  checkOptions('triangle', arguments[0], ['from', 'to', 'period']);
   need(num(from) && num(to), `triangle: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(period) && period > 0, `triangle: period must be > 0 (s), got ${period}`);
   return { t: [0, period / 2, period], values: [from, to, from], repeat: true };
@@ -60,6 +63,7 @@ export function triangle({ from, to, period } = {}) {
  * @returns {{ t: number[], values: number[] }}
  */
 export function ramp({ from, to, duration, start = 0 } = {}) {
+  checkOptions('ramp', arguments[0], ['from', 'to', 'duration', 'start']);
   need(num(from) && num(to), `ramp: from and to must be finite numbers, got ${from} and ${to}`);
   need(num(duration) && duration > 0, `ramp: duration must be > 0 (s), got ${duration}`);
   need(num(start) && start >= 0, `ramp: start must be ≥ 0 (s), got ${start}`);
@@ -78,6 +82,7 @@ export function ramp({ from, to, duration, start = 0 } = {}) {
  * @returns {object} a port, for the definition's `ports`
  */
 export function injector({ name = 'injector', region, from, to, species, I, headroom = 2.5 } = {}) {
+  checkOptions('injector', arguments[0], ['name', 'region', 'from', 'to', 'species', 'I', 'headroom']);
   need(region !== undefined, 'injector: give the region (its name or index)');
   need(num(from) && num(to) && to > from, `injector: from and to must bound the window, in m from the region's left end (got ${from}, ${to})`);
   need(typeof species === 'string', 'injector: give the species it injects, e.g. species: \'h+\'');
@@ -96,6 +101,7 @@ export function injector({ name = 'injector', region, from, to, species, I, head
  * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
  */
 export function recombination({ material, tau, majority } = {}) {
+  checkOptions('recombination', arguments[0], ['material', 'tau', 'majority']);
   need(typeof material === 'string', 'recombination: give the material, by name');
   need(num(tau) && tau > 0, `recombination: tau must be > 0 (s), got ${tau}`);
   need(num(majority) && majority > 0, `recombination: majority must be the majority carrier density > 0 (mol/m³; units.perCm3 converts), got ${majority}`);
@@ -117,6 +123,7 @@ export function recombination({ material, tau, majority } = {}) {
  * @returns {{ equation: string, fixed: Record<string, number>, kf: Record<string, { x: number[], values: number[] }> }} a bulk reaction
  */
 export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes = 'e- + h+' } = {}) {
+  checkOptions('photogeneration', arguments[0], ['material', 'flux', 'alpha', 'mu', 'from', 'to', 'makes']);
   need(typeof material === 'string', 'photogeneration: give the material, by name');
   need(num(flux) && flux >= 0, `photogeneration: flux must be the photon flux ≥ 0 entering the material (mol/(m²·s)), got ${flux}`);
   need(num(alpha) && alpha > 0, `photogeneration: alpha must be the absorption coefficient > 0 (1/m; 1/cm × 100), got ${alpha}`);

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 } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -158,8 +158,21 @@ export function build(def) {
   }
   if (pendingFace) fail(`${at(pendingFace.k)}: a face after the last layer (the contact is the boundary there)`);
   if (regions.length === 0) fail('build.stack has no layers');
+  // A contact holding a carrier its layer lacks: most often ohmic()'s default on a metal.
+  for (const [k, end] of [[0, regions[0]], [stack.length - 1, regions[regions.length - 1]]]) {
+    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked') : [];
+    const mat = materials[end.material];
+    if (!isObject(mat)) continue;
+    const has = (s) => (isObject(mat.conductor) ? mat.conductor.species === s : isObject(mat.species) && mat.species[s] !== undefined);
+    const lacks = held.filter((s) => !has(s));
+    if (lacks.length === 0) continue;
+    const kept = held.filter(has);
+    const hint = stack[k].phi === 'bulk' && kept.length > 0 ? `: write ohmic(V, [${kept.map((s) => `'${s}'`).join(', ')}]) (ohmic() holds e- and h+ unless told${isObject(mat.conductor) ? '; a metal has only its carrier' : ''})` : '';
+    fail(`${at(k)}: the contact holds ${lacks.map((s) => `'${s}'`).join(' and ')}, which its layer's material '${end.material}' doesn't have${hint}`);
+  }
 
   function region(item, path) {
+    checkOptions(path, item, ['name', 'material', 'length', 'fixedCharge', 'c0', 'velocity', 'mixing', 'grid', 'donors', 'acceptors']);
     const { donors, acceptors, ...r } = item;
     if (donors !== undefined || acceptors !== undefined) {
       if (r.fixedCharge !== undefined) fail(`${path}: give doping as donors and acceptors, or fixedCharge, not both`);

package/src/statistics.js

@@ -157,7 +157,7 @@ function tableOccupancy(xs, zs, fail) {
     const x = k / 4000;
     const q = r(x);
     if (x > 0 && x < 1 && !(1 + x * (1 - x) * q.d > 1e-9)) {
-      fail(`ocv: the interpolated curve isn't monotone near x = ${x.toFixed(3)} (E must fall steadily with x; add points or smooth the data)`);
+      fail(`ocv: near x = ${x.toFixed(3)} the curve is flat or rising against the ideal-solution slope, (RT/F) ln(x/(1−x)), as on a two-phase plateau (not supported): more points alone won't help; give it some of that slope, adding −a (RT/F) ln(x/(1−x)) to E (a = 0.1 passes at points 0.01 apart, less with points closer near the ends; docs/statistics.md)`);
     }
     rmin = Math.min(rmin, q.v);
     rmax = Math.max(rmax, q.v);

package/src/traces.js

@@ -3,6 +3,7 @@
 // range. Plain data, for any plotting toolkit (driftlet/plot draws it as SVG).
 
 import { level } from './equation.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const finite = (a) => {
   for (let k = 0; k < a.length; k++) if (Number.isFinite(a[k])) return true;
@@ -78,6 +79,8 @@ export function typeset(name, z) {
  *   faces: number[], range: [number, number] }}
  */
 export function traces(sol, { species, standard = true, phi = false, energy = false, levels = [], labels = {}, shifts = {} } = {}) {
+  checkOptions('traces', arguments[1], ['species', 'standard', 'phi', 'energy', 'levels', 'labels', 'shifts']);
+  if (!Array.isArray(levels)) throw new DeviceError("traces: levels must be a list, [{ half }, …], of the half-reactions whose levels to draw");
   const names = Object.keys(sol.V);
   const role = (name) => speciesRole(sol, name).role;
   const slotOf = (name) => speciesRole(sol, name).slot;

package/src/types.js

@@ -163,7 +163,8 @@
  *   species and the terminal species at the port's level
  * @property {Record<string, { mu0: number, capacity: number, theta0?: number }>} [surface] with reactions: species
  *   on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
- *   shared; a reaction with `bare: true` runs only on the bare fraction θ₀ = 1 − Σθ
+ *   shared; reactions run on Langmuir sites (what fills sites needs bare ones), and one with `bare: true`
+ *   needs a bare site even if it fills none (θ₀ = 1 − Σθ)
  * @property {{ C: number, zeroCharge?: number }} [capacitance] a capacitance spread through the window (F/m² of
  *   electrode): σ = C (V − zeroCharge − φ) on the port's side, aσ in each node's charge balance; a gate
  *   along a channel, a double layer
@@ -218,7 +219,8 @@
  * @property {Record<string, { V: number, current: number }>} terminals each terminal (left, right,
  *   then the ports by name): its voltage, and its current into the device (A/m²)
  * @property {{ left: ContactResult, right: ContactResult }} contacts
- * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
+ * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} plates the charge on a gate or
+ *   Stern plate at a capacitive contact
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number, x?: Float64Array,
  *   area?: Float64Array, rates?: Float64Array[], coverage?: Record<string, Float64Array>, bare?: Float64Array,
  *   sigma?: Float64Array, charge?: number }[]} ports what each internal port brings into the device;
@@ -248,6 +250,7 @@
  * @property {{ re: Float64Array, im: Float64Array }} Z impedance −δV/δI, Ω·m²
  * @property {{ phi: ComplexProfile, mu: Record<string, ComplexProfile>, c: Record<string, ComplexProfile> }[]} [profiles]
  *   per frequency, per unit excitation (volt, or A/m² in current mode)
+ * @property {string[]} warnings the steady state's warnings, which hold for its impedance too
  */
 
 /** @typedef {{ re: Float64Array, im: Float64Array }} ComplexProfile */

package/types/channels.d.ts

@@ -21,7 +21,7 @@ export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): n
  * port along a region: links that are their linear conductances, G = g × area per volume, gated the
  * same, each ion's reversal potential following from the port's bath and the concentrations inside
  * (so `inside`, `outside` and `at` aren't needed).
- * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
+ * @param {{ inside: object, outside: object, T: number, g?: { Na?: number, K?: number, leak?: number },
  *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string }, linear?: boolean, area?: number }} opts concentrations in
  *   mol/m³ by species name, K, S/m², V
  * @returns {{ gates: object, species: object }}
@@ -29,7 +29,7 @@ export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): n
 export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names, linear, area }?: {
     inside: object;
     outside: object;
-    T?: number;
+    T: number;
     g?: {
         Na?: number;
         K?: number;
@@ -44,7 +44,7 @@ export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names, l
     };
     linear?: boolean;
     area?: number;
-}): {
+}, ...args: any[]): {
     gates: object;
     species: object;
 };

package/types/checks.d.ts

@@ -40,7 +40,7 @@ export function check(device: import("./index.js").Device, sol?: object, { refin
     refine?: boolean;
     tol?: number;
     order?: boolean;
-}): {
+}, ...args: any[]): {
     ok: boolean;
     items: CheckItem[];
     text: string;

package/types/data.d.ts

@@ -9,7 +9,7 @@
 export function aqueous(names: string[], { epsr, material }?: {
     epsr?: number;
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };
@@ -24,7 +24,7 @@ export function aqueous(names: string[], { epsr, material }?: {
  */
 export function semiconductor(name: string, { material }?: {
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };
@@ -36,7 +36,7 @@ export function semiconductor(name: string, { material }?: {
  */
 export function metal(name: string, { material }?: {
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };

package/types/devices.d.ts

@@ -19,7 +19,7 @@ export function perovskiteCell({ V, light, bulkSRH }?: {
     };
     light?: number;
     bulkSRH?: boolean;
-}): import("./types.js").DeviceDefinition;
+}, ...args: any[]): import("./types.js").DeviceDefinition;
 /**
  * A J–V loop's figures of merit, from a transient's trace (`{ t, voltage, current }`, as a
  * recorder or advance() gives it): the loop splits at time `turn` into the sweep before (`rev`)

package/types/equation.d.ts

@@ -78,7 +78,7 @@ export function level(sol: {
     fixed?: Record<string, number>;
 }, { standard }?: {
     standard?: boolean;
-}): Float64Array;
+}, ...args: any[]): Float64Array;
 /**
  * The standard hydrogen electrode, 2 H⁺ + 2 e⁻ ⇌ H₂, with μ(H₂) = 0 (the element in its standard
  * state, on the usual table convention). Needs `H+` among the species.

package/types/errors.d.ts

@@ -1,3 +1,11 @@
+/**
+ * A function's options: a name it doesn't take (a typo) is an error, not silently ignored.
+ * @param {string} where the function, for the message
+ * @param {unknown} opts
+ * @param {string[]} allowed
+ * @param {new (message: string) => Error} [Kind]
+ */
+export function checkOptions(where: string, opts: unknown, allowed: string[], Kind?: new (message: string) => Error): void;
 export class DeviceError extends Error {
     constructor(message: any);
 }

package/types/index.d.ts

@@ -1,5 +1,5 @@
+export { DeviceError } from "./device.js";
 export { SolverError } from "./solver.js";
-export { BlockTridiagonal } from "./blockTridiagonal.js";
 export * from "./constants.js";
 /** @typedef {import('./types.js').DeviceDefinition} DeviceDefinition */
 /** @typedef {import('./types.js').Solution} Solution */
@@ -72,7 +72,7 @@ export class Device {
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its
      * held voltage is perturbed (or its driven current), the others keep their drives.
-     * Z = δV/δI with I into the device (Ω·m²).
+     * Z = δV/δI with I into the device (Ω·m²), with the steady state's `warnings`.
      * @param {ArrayLike<number>} frequencies Hz
      * @param {{ terminal?: string, profiles?: boolean }} [opts] the terminal (default 'right'), and
      *   whether to return complex profiles per frequency
@@ -110,6 +110,3 @@ export class Device {
 }
 export type DeviceDefinition = import("./types.js").DeviceDefinition;
 export type Solution = import("./types.js").Solution;
-export { DeviceError, normalizeDevice } from "./device.js";
-export { buildGrid, gradedCells } from "./grid.js";
-export { bernoulli, bernoulliDerivative } from "./bernoulli.js";

package/types/junction.d.ts

@@ -12,7 +12,7 @@ export function henderson(left: Record<string, number>, right: Record<string, nu
     D: number;
 }>, { T }?: {
     T?: number;
-}): number;
+}, ...args: any[]): number;
 /**
  * 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
@@ -29,4 +29,4 @@ export function planck(left: Record<string, number>, right: Record<string, numbe
 }>, { T, steps }?: {
     T?: number;
     steps?: number;
-}): number;
+}, ...args: any[]): number;

package/types/kit.d.ts

@@ -59,7 +59,7 @@ export type VacuumSide = {
     offset: number;
 };
 export { build, combine, layer, ohmic, bath } from "./stack.js";
-export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
+export { half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { hodgkinHuxley, ghkCurrent } from "./channels.js";

package/types/live.d.ts

@@ -28,7 +28,7 @@ export function live(def: object, { worker, onsolution, maxRamp }?: {
     worker?: boolean | (() => any);
     onsolution?: (solution: object, info: object) => void;
     maxRamp?: number;
-}): Live;
+}, ...args: any[]): Live;
 /**
  * What a live device does with each change, on whichever thread solves it: apply, solve warm,
  * ramp from the last good state if that fails, and fall back to the last good solution.

package/types/particles.d.ts

@@ -20,7 +20,7 @@ export function particles(sol: object, { species, dots, weight, cap, cells, rand
     cap?: number;
     cells?: number;
     random?: () => number;
-}): {
+}, ...args: any[]): {
     cells: any[];
     species: any;
     weight: {};

package/types/plot.d.ts

@@ -7,7 +7,7 @@
  */
 export function themeColor(role: "electron" | "cation" | "anion" | "redox", slot: number, { dark }?: {
     dark?: boolean;
-}): string;
+}, ...args: any[]): string;
 /**
  * A label split into plain and subscript runs. Labels mark subscripts TeX-style: `V_{e⁻}`, or
  * `C_ox` for a run of letters, digits and charge signs. Everything else is literal.
@@ -34,7 +34,7 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
     xlim?: [number, number];
     title?: string;
     ytick?: (v: number) => string;
-}): string;
+}, ...args: any[]): string;
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
  * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
@@ -43,7 +43,7 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}
  */
-export function bandDiagram(sol: import("./types.js").Solution, opts?: Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]): string;
+export function bandDiagram(sol: import("./types.js").Solution, opts?: Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1], ...args: any[]): string;
 export const THEME: Readonly<{
     light: {
         electron: string[];

package/types/polarization.d.ts

@@ -24,7 +24,7 @@ export function polarization(device: import("./index.js").Device, sol: object, w
     x?: number;
 }, V: number | ArrayLike<number>, opts?: {
     surface?: "held" | "equilibrium";
-}): {
+}, ...args: any[]): {
     V: Float64Array;
     current: Float64Array;
     bare?: Float64Array;

package/types/recorder.d.ts

@@ -19,7 +19,7 @@ export function recorder(device: import("./index.js").Device, opts?: {
         species?: string;
         gate?: string;
     })[];
-}): {
+}, ...args: any[]): {
     advance: (tEnd: number, aopts?: object) => import("./types.js").Solution;
     frame: (t: number) => import("./types.js").Solution;
     frames: import("./types.js").Solution[];

package/types/solver.d.ts

@@ -115,6 +115,7 @@ export class Solver {
     chargeNode: Uint8Array<any>;
     chargeNodes: Int32Array<ArrayBuffer>;
     lateStorage: Uint8Array<any>;
+    portHeldEnd: Uint8Array<ArrayBuffer>;
     combining: boolean;
     bookkeeping: any;
     bookkeepingFaces: number[];
@@ -209,6 +210,7 @@ export class Solver {
     dtNow: any;
     transformed: any;
     _nodeConductor(g: any, dt: any): void;
+    _portHeldAt(g: any, i: any): boolean;
     _nodesDilute(g0: any, g1: any, dt: any): void;
     _nodeConcentrated(g: any, dt: any): void;
     _storage(g: any, i: any, dt: any, Kz?: number): void;

package/types/sources.d.ts

@@ -13,7 +13,7 @@ export function pulse({ start, width, amplitude, rise, base }?: {
     amplitude: number;
     rise?: number;
     base?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
 };
@@ -27,7 +27,7 @@ export function square({ high, low, period, duty }?: {
     low: number;
     period: number;
     duty?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
     repeat: true;
@@ -42,7 +42,7 @@ export function triangle({ from, to, period }?: {
     from: number;
     to: number;
     period: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
     repeat: true;
@@ -57,7 +57,7 @@ export function ramp({ from, to, duration, start }?: {
     to: number;
     duration: number;
     start?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
 };
@@ -84,7 +84,7 @@ export function injector({ name, region, from, to, species, I, headroom }?: {
         repeat?: boolean;
     };
     headroom?: number;
-}): object;
+}, ...args: any[]): object;
 /**
  * Band-to-band recombination e⁻ + h⁺ ⇌ 0 in a material, from the minority-carrier lifetime it
  * should give at a majority density: kf = 1/(τ · majority). (The rate is kf (np − n_i²), so τ is
@@ -96,7 +96,7 @@ export function recombination({ material, tau, majority }?: {
     material: string;
     tau: number;
     majority: number;
-}): {
+}, ...args: any[]): {
     equation: string;
     kf: Record<string, number>;
 };
@@ -122,7 +122,7 @@ export function photogeneration({ material, flux, alpha, mu, from, to, makes }?:
     from?: number;
     to: number;
     makes?: string;
-}): {
+}, ...args: any[]): {
     equation: string;
     fixed: Record<string, number>;
     kf: Record<string, {

package/types/traces.d.ts

@@ -70,7 +70,7 @@ export function traces(sol: import("./types.js").Solution, { species, standard,
     }[];
     labels?: Record<string, string>;
     shifts?: Record<string, number>;
-}): {
+}, ...args: any[]): {
     x: Float64Array;
     series: Trace[];
     regions: {