driftlet 0.1.0 → 0.2.0

package/src/kit.js

@@ -9,6 +9,7 @@ export { build, combine, layer, ohmic, bath } from './stack.js';
 export { parseEquation, stoichiometry, half, SHE, level } from './equation.js';
 export { traces, speciesRole, typeset } from './traces.js';
 export { live } from './live.js';
+export { pulse, square, triangle, ramp, injector, recombination } from './sources.js';
 export { describe, unitWarnings } from './describe.js';
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from './data.js';
 

package/src/solver.js

@@ -145,6 +145,7 @@ import { BlockTridiagonal, ComplexBlockTridiagonal } from './blockTridiagonal.js
 import { bernoulli, bernoulliDerivative } from './bernoulli.js';
 import { EPS0, FARADAY } from './constants.js';
 import { nextBreakpoint, sourceAt } from './device.js';
+import { DeviceError } from './errors.js';
 
 export class SolverError extends Error {
   constructor(message, details) {
@@ -1846,7 +1847,7 @@ export class Solver {
   }
 
   // Largest update among the potential-like unknowns (φ̂ and η at grid nodes).
-  _maxPotentialStep(delta, deltaV = this.deltaV) {
+  _maxPotentialStep(delta, deltaV = this.deltaV) { // (deltaV null: the device's potentials only)
     const { n, M } = this;
     const R = this.rix; // (the sink entry of delta is 0)
     let mx = 0;
@@ -1868,7 +1869,7 @@ export class Solver {
   newton(dt, { maxIter = 60, tol = 1e-10, maxStep = 10 } = {}) {
     const { delta, res } = this;
     const deltaV = this.deltaV ?? (this.deltaV = new Float64Array(this.floating.length));
-    const history = [];
+    const history = [], ownHistory = [];
     // A steady solve that fails: record how nearly singular the system was, and where.
     const fail = (r) => {
       if (dt === Infinity) this._noteConditioning();
@@ -1899,15 +1900,22 @@ export class Solver {
         if (!(err instanceof SolverError)) throw err;
         return fail({ converged: false, iterations: it, history, error: err.message });
       }
+      // Convergence counts every unknown, floating terminal voltages too. Damping and the
+      // divergence check count only the device's own potentials: a terminal voltage enters
+      // linearly (conductance links, held levels, a capacitive face), so a large swing in one is
+      // safe, and damping it would throttle the whole update (a current-driven port switching
+      // off, its voltage collapsing by hundreds of volts, crawled 10 thermal units at a time).
       const step = this._maxPotentialStep(delta, deltaV);
+      const own = this._maxPotentialStep(delta, null);
       history.push(step);
+      ownHistory.push(own);
       if (!Number.isFinite(step)) return fail({ converged: false, iterations: it, history, error: 'non-finite update' });
       // Give up early on clear divergence; the caller will take a smaller step instead.
-      if (step > 1e4 || (it > 6 && step > 10 * history[0])) {
+      if (own > 1e4 || (it > 6 && own > 10 * ownHistory[0])) {
         this.computeConcentrations();
         return fail({ converged: false, iterations: it, history, error: 'diverging' });
       }
-      const alpha = step > maxStep ? maxStep / step : 1;
+      const alpha = own > maxStep ? maxStep / own : 1;
       this._addToState(delta, -alpha);
       this.floating.forEach((k, a) => (this.termV[k] -= alpha * deltaV[a]));
       if (alpha === 1 && step < tol) {
@@ -2071,11 +2079,12 @@ export class Solver {
     const { tol = 1e-3, dtMax = Infinity, budgetMs = Infinity, maxSteps = 100000, method = 'bdf2' } = opts;
     const clock = () => (globalThis.performance ? globalThis.performance.now() : Date.now());
     const start = clock();
-    const trace = { t: [], current: [], voltage: [] };
+    const sample = this._probes(opts.probes);
+    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: { t: [], current: [], voltage: [] } };
+    if (!(tEnd > this.time)) return { converged: true, done: true, steps: 0, rejected: 0, iterations: 0, trace };
     let dt = this.dtNext ?? opts.dt0 ?? (tEnd - this.time) * 1e-4;
     if (!(dt > 0)) dt = (tEnd - this.time) * 1e-4;
     let grow = 0; // longer first steps tried after a Newton failure (see below)
@@ -2113,7 +2122,7 @@ export class Solver {
           this._restore(snap);
           const a = this.step(h / 2);
           // The first half step is kept too, so it goes in the trace (a jump's charge is in it).
-          half = a.converged ? { t: this.time, current: this._terminalCurrent(), voltage: this.termV[1] - this.termV[0] } : null;
+          half = a.converged ? { t: this.time, current: this._terminalCurrent(), voltage: this.termV[1] - this.termV[0], probes: sample?.read() } : null;
           const b = a.converged ? this.step(h / 2) : a;
           iterations += a.iterations + (b === a ? 0 : b.iterations);
           if (b.converged) {
@@ -2165,10 +2174,12 @@ export class Solver {
         trace.t.push(half.t);
         trace.current.push(half.current);
         trace.voltage.push(half.voltage);
+        if (sample) sample.push(half.probes);
       }
       trace.t.push(this.time);
       trace.current.push(this._terminalCurrent());
       trace.voltage.push(this.termV[1] - this.termV[0]);
+      if (sample) sample.push(sample.read());
     }
     this.dtNext = dt;
     this.landing = undefined;
@@ -2224,6 +2235,54 @@ export class Solver {
     return { scale: bdf ? 1 : h / (2 * h + hp), order: 1 };
   }
 
+  // Probes for a transient's trace: { x, species, quantity: 'c' | 'V', region } read after every
+  // accepted step, linearly between the two nodes of x's region around it. At an interface x
+  // belongs to both regions, so `region` (a name or index) picks the side; it defaults to the
+  // first region that holds x.
+  _probes(probes) {
+    if (probes === undefined) return null;
+    const { grid, regions, species } = this.model;
+    const fail = (m) => {
+      throw new DeviceError(m);
+    };
+    if (!Array.isArray(probes)) fail('advance: probes must be an array of { x, species, quantity, region }');
+    const plan = probes.map((p, k) => {
+      const path = `advance: probes[${k}]`;
+      const i = species.findIndex((sp) => sp.name === p?.species);
+      if (i < 0) fail(`${path}.species: no species ${JSON.stringify(p?.species)}`);
+      const quantity = p.quantity ?? 'c';
+      if (quantity !== 'c' && quantity !== 'V') fail(`${path}.quantity must be 'c' (mol/m³) or 'V' (the species voltage)`);
+      if (quantity === 'V' && species[i].z === 0) fail(`${path}: '${p.species}' is neutral, so it has no voltage; read 'c'`);
+      const x = grid.x, inside = (r) => p.x >= x[grid.regionStart[r]] && p.x <= x[grid.regionEnd[r]];
+      let r;
+      if (p.region !== undefined) {
+        r = typeof p.region === 'number' ? p.region : regions.findIndex((reg) => reg.name === p.region);
+        if (!(r >= 0 && r < regions.length)) fail(`${path}.region: no region ${JSON.stringify(p.region)}`);
+        if (!inside(r)) fail(`${path}.x (${p.x} m) is outside region ${JSON.stringify(p.region)}`);
+      } else {
+        r = regions.findIndex((_, rr) => inside(rr));
+        if (!(Number.isFinite(p.x) && r >= 0)) fail(`${path}.x must be a position in the device, in m (got ${p.x})`);
+      }
+      let g = grid.regionStart[r];
+      while (g + 1 < grid.regionEnd[r] && x[g + 1] < p.x) g++;
+      const w = x[g + 1] > x[g] ? (p.x - x[g]) / (x[g + 1] - x[g]) : 0;
+      return { i, g, w, quantity };
+    });
+    const out = plan.map(() => []);
+    const { n, M } = this;
+    const at = (q, g) => {
+      if (!this.present[g * n + q.i]) return NaN;
+      if (q.quantity === 'c') return this.c[g * n + q.i];
+      const o = this.blockOfNode[g] * M + 1 + q.i;
+      return (this.VT * (this.u[o] + this.uLo[o])) / this.z[q.i];
+    };
+    return {
+      out,
+      read: () => plan.map((q) => (1 - q.w) * at(q, q.g) + q.w * at(q, q.g + 1)),
+      push: (values) => values.forEach((v, k) => out[k].push(v)),
+    };
+  }
+
   // Largest difference from ref among the potentials that carry state, in thermal units.
   _errorNorm(ref) {
     const { n, M, u } = this;

package/src/sources.js

@@ -0,0 +1,103 @@
+// 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';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const need = (ok, message) => ok || fail(message);
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * A rectangular pulse, as a waveform for a terminal's `V` or `I`: `base` until `start`, then
+ * `base + amplitude` for `width`, then `base` again. With a `rise` > 0 its edges are ramps of
+ * that length, placed so the area stays `amplitude · width`; without one they're jumps, which
+ * the time stepping handles exactly (so a pulse with no rise must start after t = 0, the time a
+ * device starts at and solve() reads: it's off then).
+ * @param {{ start?: number, width: number, amplitude: number, rise?: number, base?: number }} opts s, s, V or A/m², s, V or A/m²
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function pulse({ start = 0, width, amplitude, rise = 0, base = 0 } = {}) {
+  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}`);
+  need(num(rise) && rise >= 0 && rise <= width, `pulse: rise must be between 0 and the width (s), got ${rise}`);
+  need(num(base), `pulse: base must be a finite number, got ${base}`);
+  need(rise > 0 || start > 0, 'pulse: with no rise, start after t = 0, so the device starts (and solve() reads it) before the pulse');
+  const top = base + amplitude;
+  return { t: [start, start + rise, start + width, start + width + rise], values: [base, top, top, base] };
+}
+
+/**
+ * A square wave, repeating: `high` for `duty · period`, then `low`, from t = 0.
+ * @param {{ high: number, low: number, period: number, duty?: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function square({ high, low, period, duty = 0.5 } = {}) {
+  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}`);
+  const on = duty * period;
+  return { t: [0, on, on, period], values: [high, high, low, low], repeat: true };
+}
+
+/**
+ * A triangle wave, repeating: from `from` to `to` and back in each `period`, from t = 0 (a
+ * cyclic voltammogram's sweep, from its starting potential).
+ * @param {{ from: number, to: number, period: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function triangle({ 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 };
+}
+
+/**
+ * A ramp from `from` to `to` over `duration`, starting at `start`, constant on either side.
+ * @param {{ from: number, to: number, duration: number, start?: number }} opts
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function ramp({ from, to, duration, start = 0 } = {}) {
+  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}`);
+  return { t: [start, start + duration], values: [from, to] };
+}
+
+/**
+ * A port that injects a species into a window of a region at a driven current `I` (A/m², a
+ * number or a waveform), spread evenly over the window. It's an ordinary port: driven by `I`,
+ * its terminal the species, linked by a conductance small enough that at the peak current the
+ * port sits `headroom` volts above the window's level of that species, so every node of the
+ * window takes the same share (like a current source). At I = 0 it still links the window,
+ * weakly.
+ * @param {{ name?: string, region: string | number, from: number, to: number, species: string,
+ *   I: number | { t: number[], values: number[], repeat?: boolean }, headroom?: number }} opts
+ * @returns {object} a port, for the definition's `ports`
+ */
+export function injector({ name = 'injector', region, from, to, species, I, headroom = 2.5 } = {}) {
+  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+\'');
+  need(num(headroom) && headroom > 0, `injector: headroom must be > 0 (V), got ${headroom}`);
+  const peak = num(I) ? Math.abs(I) : Array.isArray(I?.values) && I.values.every(num) ? Math.max(...I.values.map(Math.abs)) : NaN;
+  need(Number.isFinite(peak), 'injector: I must be a current (A/m²) or a waveform { t, values }');
+  const G = peak > 0 ? peak / ((to - from) * headroom) : 1; // S/m³
+  return { name, region, from, to, terminal: species, species: { [species]: { type: 'conductance', G } }, I };
+}
+
+/**
+ * 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
+ * the low-injection lifetime of whichever carrier is the minority.)
+ * @param {{ material: string, tau: number, majority: number }} opts material name, s, mol/m³
+ * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
+ */
+export function recombination({ 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}`);
+  return { equation: 'e- + h+ = 0', kf: { [material]: 1 / (tau * majority) } };
+}

package/src/types.js

@@ -204,8 +204,9 @@
  * @property {number} time s
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
- * @property {{ t: number[], current: number[], voltage: number[] }} [trace] advance(): terminal
- *   current (A/m², toward +x) and voltage after each accepted step
+ * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] advance():
+ *   terminal current (A/m², toward +x) and voltage after each accepted step, and each probe's
+ *   reading (mol/m³, or V for quantity 'V'), interpolated between the nodes around its x
  */
 
 /**

package/types/constants.d.ts

@@ -30,4 +30,14 @@ export const units: Readonly<{
     um: (x: any) => number;
     /** cm²/s → m²/s */
     cm2PerS: (x: any) => number;
+    /** mol/m³ → mol/L */
+    toMolar: (x: any) => number;
+    /** mol/m³ → particles per cm³ */
+    toPerCm3: (x: any) => number;
+    /** m → nm */
+    toNm: (x: any) => number;
+    /** m → µm */
+    toUm: (x: any) => number;
+    /** m²/s → cm²/s */
+    toCm2PerS: (x: any) => number;
 }>;

package/types/index.d.ts

@@ -45,9 +45,12 @@ export class Device {
     /**
      * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
      * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
-     * which), so an animation can call it once per frame; the step size carries over.
+     * which), so an animation can call it once per frame; the step size carries over. `probes`
+     * read a species at points inside the device after every accepted step, into `trace.probes`
+     * (one array per probe, alongside `trace.t`): what a detector at x sees.
      * @param {number} tEnd s
-     * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+     * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
+     *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
      * @returns {Solution}
      */
     advance(tEnd: number, opts?: {
@@ -57,6 +60,12 @@ export class Device {
         budgetMs?: number;
         maxSteps?: number;
         method?: "bdf2" | "be";
+        probes?: {
+            x: number;
+            species: string;
+            quantity?: "c" | "V";
+            region?: string | number;
+        }[];
     }): Solution;
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its

package/types/kit.d.ts

@@ -57,5 +57,6 @@ export type VacuumSide = {
 export { build, combine, layer, ohmic, bath } from "./stack.js";
 export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
+export { pulse, square, triangle, ramp, injector, recombination } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/solver.d.ts

@@ -216,6 +216,7 @@ export class Solver {
         rejected: number;
         iterations: number;
         trace: {
+            probes?: any;
             t: any[];
             current: any[];
             voltage: any[];
@@ -227,6 +228,11 @@ export class Solver {
         scale: number;
         order: number;
     };
+    _probes(probes: any): {
+        out: any;
+        read: () => any;
+        push: (values: any) => any;
+    };
     _errorNorm(ref: any): number;
     _snapshot(): {
         u: Float64Array<ArrayBuffer>;

package/types/sources.d.ts

@@ -0,0 +1,102 @@
+/**
+ * A rectangular pulse, as a waveform for a terminal's `V` or `I`: `base` until `start`, then
+ * `base + amplitude` for `width`, then `base` again. With a `rise` > 0 its edges are ramps of
+ * that length, placed so the area stays `amplitude · width`; without one they're jumps, which
+ * the time stepping handles exactly (so a pulse with no rise must start after t = 0, the time a
+ * device starts at and solve() reads: it's off then).
+ * @param {{ start?: number, width: number, amplitude: number, rise?: number, base?: number }} opts s, s, V or A/m², s, V or A/m²
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function pulse({ start, width, amplitude, rise, base }?: {
+    start?: number;
+    width: number;
+    amplitude: number;
+    rise?: number;
+    base?: number;
+}): {
+    t: number[];
+    values: number[];
+};
+/**
+ * A square wave, repeating: `high` for `duty · period`, then `low`, from t = 0.
+ * @param {{ high: number, low: number, period: number, duty?: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function square({ high, low, period, duty }?: {
+    high: number;
+    low: number;
+    period: number;
+    duty?: number;
+}): {
+    t: number[];
+    values: number[];
+    repeat: true;
+};
+/**
+ * A triangle wave, repeating: from `from` to `to` and back in each `period`, from t = 0 (a
+ * cyclic voltammogram's sweep, from its starting potential).
+ * @param {{ from: number, to: number, period: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function triangle({ from, to, period }?: {
+    from: number;
+    to: number;
+    period: number;
+}): {
+    t: number[];
+    values: number[];
+    repeat: true;
+};
+/**
+ * A ramp from `from` to `to` over `duration`, starting at `start`, constant on either side.
+ * @param {{ from: number, to: number, duration: number, start?: number }} opts
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function ramp({ from, to, duration, start }?: {
+    from: number;
+    to: number;
+    duration: number;
+    start?: number;
+}): {
+    t: number[];
+    values: number[];
+};
+/**
+ * A port that injects a species into a window of a region at a driven current `I` (A/m², a
+ * number or a waveform), spread evenly over the window. It's an ordinary port: driven by `I`,
+ * its terminal the species, linked by a conductance small enough that at the peak current the
+ * port sits `headroom` volts above the window's level of that species, so every node of the
+ * window takes the same share (like a current source). At I = 0 it still links the window,
+ * weakly.
+ * @param {{ name?: string, region: string | number, from: number, to: number, species: string,
+ *   I: number | { t: number[], values: number[], repeat?: boolean }, headroom?: number }} opts
+ * @returns {object} a port, for the definition's `ports`
+ */
+export function injector({ name, region, from, to, species, I, headroom }?: {
+    name?: string;
+    region: string | number;
+    from: number;
+    to: number;
+    species: string;
+    I: number | {
+        t: number[];
+        values: number[];
+        repeat?: boolean;
+    };
+    headroom?: number;
+}): 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
+ * the low-injection lifetime of whichever carrier is the minority.)
+ * @param {{ material: string, tau: number, majority: number }} opts material name, s, mol/m³
+ * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
+ */
+export function recombination({ material, tau, majority }?: {
+    material: string;
+    tau: number;
+    majority: number;
+}): {
+    equation: string;
+    kf: Record<string, number>;
+};

package/types/types.d.ts

@@ -538,13 +538,15 @@ export type Solution = {
      */
     rejected?: number;
     /**
-     * advance(): terminal
-     * current (A/m², toward +x) and voltage after each accepted step
+     * advance():
+     * terminal current (A/m², toward +x) and voltage after each accepted step, and each probe's
+     * reading (mol/m³, or V for quantity 'V'), interpolated between the nodes around its x
      */
     trace?: {
         t: number[];
         current: number[];
         voltage: number[];
+        probes?: number[][];
     };
 };
 export type ImpedanceResult = {