driftlet 0.1.0

package/src/traces.js

@@ -0,0 +1,125 @@
+// Plot-ready traces of a solution, for driftlet/kit: the level diagram's lines with labels,
+// line kinds and a colour slot that follows the species, the regions as bands, and a suggested
+// range. Plain data, for any plotting toolkit (driftlet/plot draws it as SVG).
+
+import { level } from './equation.js';
+
+const finite = (a) => {
+  for (let k = 0; k < a.length; k++) if (Number.isFinite(a[k])) return true;
+  return false;
+};
+
+/**
+ * One line of a level diagram.
+ * @typedef {object} Trace
+ * @property {string} id e.g. 'V:e-', 'Vstd:e-', 'phi', 'level:0'
+ * @property {string} label e.g. 'V_{e⁻}', 'V°_{SO₄²⁻}' (subscripts marked TeX-style, as `labelParts()` in driftlet/plot reads them)
+ * @property {'level' | 'standard' | 'phi' | 'redox' | 'redox-standard'} kind a species voltage, its
+ *   standard level, φ, or a half-reaction's level or standard level
+ * @property {string} [species]
+ * @property {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role what it is, for its colour:
+ *   electrons, cations (holes too), anions, redox levels, φ
+ * @property {number} slot its colour within the role: a species' place among the solution's
+ *   species of that role, so a colour follows its species whichever lines are shown; a redox
+ *   level's place among the distinct half-reactions asked for (a couple's level and standard
+ *   level share one)
+ * @property {number} [shift] a display offset added to all of a species' lines, V
+ * @property {Float64Array} y V, NaN where undefined (a break in the line)
+ */
+
+/**
+ * A charged species' colour role and slot in level diagrams: electrons (`e-`), cations (holes
+ * too), or anions, and its place among the solution's species of that role.
+ * @param {import('./types.js').Solution} sol
+ * @param {string} name
+ * @returns {{ role: 'electron' | 'cation' | 'anion', slot: number }}
+ */
+export function speciesRole(sol, name) {
+  const z = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
+  const role = (n) => (n === 'e-' ? 'electron' : z[n] > 0 ? 'cation' : 'anion');
+  const charged = sol.species.filter((sp) => sp.z !== 0).map((sp) => sp.name);
+  return { role: role(name), slot: charged.filter((n) => role(n) === role(name)).indexOf(name) };
+}
+
+const SUB = '₀₁₂₃₄₅₆₇₈₉', SUP = '⁰¹²³⁴⁵⁶⁷⁸⁹';
+/**
+ * A species name typeset for labels, given its charge: the charge as a superscript and the counts
+ * in its formula as subscripts ('SO42-' with z = −2 is 'SO₄²⁻', 'Fe3+' with z = 3 is 'Fe³⁺').
+ * A name that doesn't end in its charge is returned as it is.
+ * @param {string} name
+ * @param {number} z
+ * @returns {string}
+ */
+export function typeset(name, z) {
+  const charge = z === 0 ? '' : `${Math.abs(z) > 1 ? Math.abs(z) : ''}${z > 0 ? '+' : '-'}`;
+  if (!name.endsWith(charge)) return name;
+  const formula = name.slice(0, name.length - charge.length).replace(/([A-Za-z)\]])(\d+)/g, (_, a, d) => a + [...d].map((c) => SUB[+c]).join(''));
+  return formula + [...charge].map((c) => (c === '+' ? '⁺' : c === '-' ? '⁻' : SUP[+c])).join('');
+}
+
+/**
+ * The level diagram of a solution as traces: per charged species, its voltage V_i (`level`) and
+ * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
+ * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
+ * @param {import('./types.js').Solution} sol
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
+ *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
+ *   species to show (default: every charged one), whether to show standard levels (default true)
+ *   and φ (default false; or a list of regions, by name or material, to draw it in only, say an
+ *   insulator's), half-reaction levels, labels to use by trace id
+ *   ({ 'V:e-': 'Fermi level' }), and display offsets per species (V), which move all of a
+ *   species' lines together so that widely separated species can share one readable plot
+ * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
+ *   faces: number[], range: [number, number] }}
+ */
+export function traces(sol, { species, standard = true, phi = false, levels = [], labels = {}, shifts = {} } = {}) {
+  const names = Object.keys(sol.V);
+  const role = (name) => speciesRole(sol, name).role;
+  const slotOf = (name) => speciesRole(sol, name).slot;
+  const shown = species ?? names.filter((name) => finite(sol.V[name]));
+  const zOf = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
+  const pretty = (name) => (name in zOf ? typeset(name, zOf[name]) : name);
+  const series = [];
+  for (const name of shown) {
+    if (!names.includes(name)) throw new Error(`traces: no charged species '${name}' in the solution`);
+    const shift = shifts[name] ?? 0;
+    const at = (y) => (shift ? y.map((v) => v + shift) : y);
+    const common = { species: name, role: role(name), slot: slotOf(name), ...(shift ? { shift } : {}) };
+    if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
+    if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
+  }
+  if (Array.isArray(phi)) {
+    const known = sol.regions.flatMap((r) => [r.name, r.material]);
+    for (const name of phi) if (!known.includes(name)) throw new Error(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
+    const inside = sol.regions.map((r) => phi.includes(r.name) || phi.includes(r.material));
+    series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? v : NaN)) });
+  } else if (phi) series.push({ id: 'phi', label: 'φ', kind: 'phi', role: 'phi', slot: 0, y: sol.phi });
+  const couples = [...new Set(levels.map((lv) => lv.half.equation))];
+  levels.forEach((lv, k) => {
+    const y = level(sol, lv.half, { standard: lv.standard });
+    series.push({
+      id: `level:${k}`,
+      label: lv.label ?? `${lv.standard ? 'V° ' : ''}${lv.half.equation.split(' ').map(pretty).join(' ')}`,
+      kind: lv.standard ? 'redox-standard' : 'redox',
+      role: 'redox',
+      slot: couples.indexOf(lv.half.equation),
+      y,
+    });
+  });
+  for (const s of series) {
+    if (labels[s.id] !== undefined) s.label = labels[s.id];
+    if (s.shift) s.label += ` ⌇${s.shift > 0 ? '+' : '−'}${Math.abs(s.shift)} V`;
+  }
+  let lo = Infinity, hi = -Infinity;
+  for (const s of series) {
+    for (const v of s.y) {
+      if (v < lo) lo = v;
+      if (v > hi) hi = v;
+    }
+  }
+  if (!(hi > lo)) [lo, hi] = Number.isFinite(lo) ? [lo - 0.5, lo + 0.5] : [-1, 1];
+  const pad = 0.06 * (hi - lo);
+  const regions = sol.regions.map((r) => ({ ...r }));
+  return { x: sol.x, series, regions, faces: regions.slice(1).map((r) => r.x0), range: [lo - pad, hi + pad] };
+}

package/src/types.js

@@ -0,0 +1,221 @@
+// JSDoc types for device definitions and solutions (for editors; no runtime content).
+// Reference: docs/device.md. Units are SI throughout.
+
+/**
+ * @typedef {object} SpeciesDef
+ * @property {string} name
+ * @property {number} z charge number (integer; 0 for neutral species)
+ * @property {number} [cRef] default reference concentration, mol/m³
+ */
+
+/**
+ * @typedef {object} MaterialSpeciesDef
+ * @property {number} D coefficient in N = −(D c/RT)∇μ̄, m²/s
+ * @property {number} mu0 standard chemical potential, J/mol
+ * @property {number} [cRef] concentration that mu0 refers to, mol/m³
+ */
+
+/**
+ * Statistics model: how the listed species' concentrations follow from their reduced
+ * potentials ζ = (μ̄ − zFφ − μ°)/RT. Species not in any model are ideal, c = c_ref e^ζ.
+ * @typedef {(
+ *   { type: 'fermi-dirac', species: string[], order?: 0.5 | 0 } |
+ *   { type: 'lattice', species: string[], cMax: number } |
+ *   { type: 'redlich-kister', species: [string], cMax: number, A?: number[] } |
+ *   { type: 'debye-huckel', species: string[], epsr?: number, a?: number } |
+ *   { type: 'insertion', species: [string, string], cMax: number, A?: number[],
+ *     ocv?: { x: number[], E: number[], muRef: number } } |
+ *   { type: 'custom', species: string[],
+ *     evaluate: (zeta: number[]) => { c: number[], dcdzeta: number[][] } }
+ * )} StatisticsDef
+ */
+
+/**
+ * A material: either ordinary (epsr, species, optional statistics) or a conductor.
+ * @typedef {object} MaterialDef
+ * @property {number} [epsr] relative permittivity; 0 makes the material strictly neutral
+ * @property {Record<string, MaterialSpeciesDef>} [species] species present in this material
+ * @property {StatisticsDef[]} [statistics] non-ideal statistics (default: all ideal)
+ * @property {{ species: string, conductivity: number }} [conductor] a metal or fast ion
+ *   conductor: its one carrier and conductivity (S/m); its only level is the carrier's (a metal's
+ *   Fermi level), and φ is undefined inside
+ */
+
+/**
+ * @typedef {object} GridOptions
+ * @property {number} [hmin] cell size at region ends, m
+ * @property {number} [hmax] largest cell size, m
+ * @property {number} [ratio] geometric growth ratio (default 1.2)
+ * @property {number} [minCells] minimum cells per region (default 8)
+ * @property {number} [hLeft] left-end cell size, overriding hmin
+ * @property {number} [hRight] right-end cell size, overriding hmin
+ */
+
+/**
+ * @typedef {object} RegionDef
+ * @property {string} material material name
+ * @property {number} length m
+ * @property {string} [name]
+ * @property {number} [fixedCharge] immobile charge density, C/m³
+ * @property {Record<string, number>} [c0] initial concentrations, mol/m³ (required for species
+ *   not connected to a contact: it fixes the amount they conserve)
+ * @property {number} [velocity] imposed flow toward +x, m/s, carrying every mobile species
+ * @property {number} [mixing] eddy (turbulent) mixing diffusivity, m²/s; current-free
+ * @property {GridOptions} [grid]
+ */
+
+/** @typedef {'pinned' | 'neutral' | { type: 'capacitive', C: number }} InterfacePhiLaw */
+/** @typedef {'equilibrium' | 'blocked' | { type: 'conductance', G: number }} InterfaceSpeciesLink */
+
+/**
+ * A reaction at a face: participants on each side with signed stoichiometric coefficients
+ * (ν < 0 consumed by the forward reaction), Butler–Volmer kinetics.
+ * @typedef {object} FaceReactionDef
+ * @property {string} [equation] the reaction as an equation, e.g. 'Ag+ + e- = Ag(s)', each
+ *   participant on the side that holds it ('Li+(left)' where both do); or give left and right
+ * @property {Record<string, number>} [left] participants on the left side (species present there, or fixed neutrals)
+ * @property {Record<string, number>} [right] participants on the right side
+ * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
+ * @property {number} k0 standard rate constant, mol/(m²·s)
+ * @property {number} [alpha] transfer coefficient, 0…1 (default 0.5)
+ */
+/**
+ * One face between consecutive regions. For different materials under a 'pinned' or
+ * 'capacitive' law, exactly one alignment (step or dipole) is required.
+ * @typedef {object} InterfaceDef
+ * @property {{ species: string, value: number }} [step] standard-level step right − left, J/mol
+ * @property {number} [dipole] φ jump right − left, V
+ * @property {number} [zeroCharge] beside a conductor region: V_F − φ_edge at zero charge, V
+ * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials)
+ * @property {number} [sheetCharge] C/m²
+ * @property {Record<string, InterfaceSpeciesLink>} [species] per-species laws (default equilibrium
+ *   where present on both sides and not reacting at the face)
+ * @property {FaceReactionDef[]} [reactions] reactions at the face
+ */
+
+/**
+ * @typedef {object} BulkReactionDef
+ * @property {Record<string, number>} [nu] signed stoichiometric coefficients (ν < 0 consumed)
+ * @property {string} [equation] the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
+ * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
+ * @property {Record<string, number>} kf forward rate constant per material name
+ */
+
+/**
+ * Contacts use the same laws as internal faces; the outside is a phase with known levels
+ * V_i = V + offset_i (a rigid ladder that the circuit slides by V).
+ * @typedef {'blocked' | 'equilibrium'
+ *   | { type: 'equilibrium', offset?: number, mu?: number }
+ *   | { type: 'conductance', G: number, offset?: number }
+ *   | { type: 'exchange', k: number, mu: number }} ContactSpeciesLink
+ */
+/**
+ * 'bulk': the end node is plain bulk (locally neutral, no double layer); 'neutral': no charge at
+ * the face (D = 0); capacitive: Stern layer or gate; 'pinned': φ_edge = V − zeroCharge. The last
+ * two take the contact's zeroCharge.
+ * @typedef {'bulk' | 'neutral' | 'pinned' | { type: 'capacitive', C: number }} ContactPhiLink
+ */
+
+/**
+ * @typedef {object} ContactDef
+ * @property {Source} [V] held terminal voltage, V (default 0, if no I)
+ * @property {Source} [I] or: the current driven into the device, A/m² (the voltage floats)
+ * @property {number} [R] with V: a series resistance, Ω·m² (a source behind a resistor)
+ * @property {string} [terminal] species whose voltage V is
+ * @property {Record<string, ContactSpeciesLink>} [species] per-species links (default blocked)
+ * @property {{ c: Record<string, number>, reference: string, offset?: number }} [bath] a neutral
+ *   composition held at the contact, anchored through a charged reference species
+ * @property {ContactPhiLink} [phi] required when any species connects (default 'neutral')
+ * @property {number} [zeroCharge] for a capacitive or pinned law: V − φ_edge at zero charge, V
+ */
+
+/**
+ * A terminal's source: a constant, or a piecewise-linear waveform through (t, value), constant
+ * beyond the points, or periodic with period t_last − t_0 if repeat is true.
+ * @typedef {number | { t: number[], values: number[], repeat?: boolean }} Source
+ */
+
+/**
+ * An internal port: an outside phase exchanging with a window of one region's nodes. On a
+ * conductor region it attaches to the whole conductor (no window), and a conductance G is per area
+ * (S/m²) instead of per volume (S/m³).
+ * @typedef {object} PortDef
+ * @property {string} [name]
+ * @property {string | number} region region name or index
+ * @property {number} [from] window start, m from the region's left end (default 0)
+ * @property {number} [to] window end, m (default: the region's length)
+ * @property {Source} [V] held terminal voltage, V (default 0, if no I)
+ * @property {Source} [I] or: the current driven into the device, A/m² (e.g. 0 for a reference electrode)
+ * @property {number} [R] with V: a series resistance, Ω·m²
+ * @property {string} [terminal] species whose offset defaults to 0
+ * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'equilibrium', offset?: number, mu?: number }
+ *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} species
+ */
+
+/**
+ * A device definition: plain, serialisable data.
+ * @typedef {object} DeviceDefinition
+ * @property {number} [T] temperature, K (default 298.15)
+ * @property {SpeciesDef[]} species
+ * @property {Record<string, MaterialDef>} materials
+ * @property {RegionDef[]} regions left to right
+ * @property {(InterfaceDef | null | undefined)[]} [interfaces] one per face, interfaces[f] between regions f and f+1
+ * @property {BulkReactionDef[]} [bulkReactions]
+ * @property {{ left?: ContactDef, right?: ContactDef }} [contacts]
+ * @property {PortDef[]} [ports] internal ports
+ * @property {GridOptions} [grid]
+ */
+
+/**
+ * @typedef {object} ContactResult
+ * @property {number} V terminal voltage, V
+ * @property {Record<string, number>} flux particle flux toward +x through this contact, mol/(m²·s)
+ * @property {number} D displacement toward +x at this contact, C/m²
+ * @property {number} current total current toward +x, A/m²
+ */
+
+/**
+ * @typedef {object} Solution
+ * @property {Float64Array} x node positions, m (interface positions appear twice)
+ * @property {Int32Array} region region index per node
+ * @property {{ name: string, z: number }[]} species the species, in order, with their charge numbers
+ * @property {{ name: string, material: string, x0: number, x1: number }[]} regions each region's name, material and extent, m
+ * @property {Float64Array} phi bookkeeping φ, V (NaN where undefined)
+ * @property {Record<string, Float64Array>} c concentrations, mol/m³ (NaN where absent)
+ * @property {Record<string, Float64Array>} mu electrochemical potentials μ̄, J/mol
+ * @property {Record<string, Float64Array>} muStd standard levels μ° + zFφ, J/mol
+ * @property {Record<string, Float64Array>} V species voltages μ̄/(zF), V (charged species)
+ * @property {Record<string, Float64Array>} Vstd standard levels as voltages, V
+ * @property {number} current current toward +x through the device, A/m²
+ * @property {number} terminalVoltage V_right − V_left, V
+ * @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 {{ name: string, V: number, flux: Record<string, number>, current: number }[]} ports what each
+ *   internal port brings into the device
+ * @property {{ dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
+ * @property {number} charge total charge in the device, C/m²
+ * @property {{ species: string, regions: number[], spectator: boolean, connected: boolean, reactive: boolean,
+ *   amount: number, reference: number, intake: number, drift: number }[]} conservation
+ * @property {string[]} warnings
+ * @property {boolean} converged
+ * @property {number} iterations
+ * @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
+ */
+
+/**
+ * @typedef {object} ImpedanceResult
+ * @property {Float64Array} f frequencies, Hz
+ * @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)
+ */
+
+/** @typedef {{ re: Float64Array, im: Float64Array }} ComplexProfile */
+
+export {};

package/src/worker.js

@@ -0,0 +1,24 @@
+// The Web Worker behind live(def, { worker: true }): it holds the device and solves each change
+// it's sent, replying in order with { solution, info }.
+
+import { Session } from './live.js';
+
+let session = null, error = null;
+globalThis.addEventListener('message', (e) => {
+  const m = e.data;
+  if (m.type === 'init') {
+    try {
+      session = new Session(m.def, { maxRamp: m.maxRamp });
+    } catch (err) {
+      error = err.message;
+    }
+  } else if (m.type === 'update') {
+    let reply;
+    try {
+      reply = session ? session.update(m.patches) : { solution: null, errors: [], info: { ms: 0, ramp: 0, failed: true, error } };
+    } catch (err) {
+      reply = { solution: null, errors: [], info: { ms: 0, ramp: 0, failed: true, error: err.message } };
+    }
+    globalThis.postMessage(reply);
+  }
+});

package/types/bernoulli.d.ts

@@ -0,0 +1,4 @@
+/** B(x) = x / (eˣ − 1), with B(0) = 1. */
+export function bernoulli(x: any): number;
+/** dB/dx, with B'(0) = −1/2. */
+export function bernoulliDerivative(x: any): number;

package/types/blockTridiagonal.d.ts

@@ -0,0 +1,92 @@
+export class BlockTridiagonal {
+    /**
+     * @param {number} n number of block rows (nodes)
+     * @param {number | ArrayLike<number>} m block size (unknowns per node), or one size per node
+     */
+    constructor(n: number, m: number | ArrayLike<number>);
+    n: number;
+    /** The block size if every block has the same size, else null. */
+    m: number;
+    /** Block size of each node. */
+    sizes: Int32Array<any>;
+    offA: Int32Array<any>;
+    offB: Int32Array<any>;
+    offC: Int32Array<any>;
+    offX: Int32Array<any>;
+    /** Total number of unknowns. */
+    size: number;
+    /** Sub-diagonal blocks A_i (coupling to node i−1). */
+    A: Float64Array<ArrayBuffer>;
+    /** Diagonal blocks B_i. */
+    B: Float64Array<ArrayBuffer>;
+    /** Super-diagonal blocks C_i (coupling to node i+1). */
+    C: Float64Array<ArrayBuffer>;
+    _lu: Float64Array<ArrayBuffer>;
+    _piv: Int32Array<ArrayBuffer>;
+    _cp: Float64Array<ArrayBuffer>;
+    _y: Float64Array<ArrayBuffer>;
+    _tmp: Float64Array<ArrayBuffer>;
+    factored: boolean;
+    /** Smallest |pivot| / (largest |entry| of its block) seen in the last factor(). */
+    minPivotRatio: number;
+    /** The block found exactly singular by the last factor(), or −1. */
+    singularBlock: number;
+    /** Zero all of A, B, C (ready for fresh assembly). */
+    clear(): void;
+    /**
+     * Factorise the current A, B, C. A, B, C are left untouched.
+     * Throws if a diagonal block is exactly singular.
+     */
+    factor(): void;
+    /**
+     * Solve with the current factorisation. `rhs` and `out` are Float64Arrays of length `size`
+     * (node-major); they may be the same array.
+     */
+    solve(rhs: any, out?: Float64Array<ArrayBuffer>): Float64Array<ArrayBuffer>;
+    /**
+     * After factor(): the digits lost to cancellation in the factorisation, at worst, and the block
+     * where that happens. A running error bound: alongside each entry of W_i = B_i − A_i C′_{i−1}
+     * and of its LU (with the same partial pivoting), the sum of the magnitudes it was formed from
+     * is carried, and each pivot is compared with its sum: log₁₀(Σ|terms| / |pivot|). Many digits
+     * lost means a nearly singular system, such as a stiff chain held only weakly at its ends,
+     * whose level then rests on the lost digits. Costs about as much as a factorisation. After a
+     * factorisation that failed on a singular block, it covers the blocks up to that one.
+     * @returns {{ digits: number, block: number }}
+     */
+    cancellation(): {
+        digits: number;
+        block: number;
+    };
+    /** out = M·x using the stored (unfactored) blocks. For residual checks and tests. */
+    multiply(x: any, out?: Float64Array<ArrayBuffer>): Float64Array<ArrayBuffer>;
+}
+/**
+ * Complex block-tridiagonal solver, for small-signal (frequency-domain) problems. Same layout
+ * and algorithm as BlockTridiagonal (including per-node block sizes), with real and imaginary
+ * parts in separate arrays (Ar/Ai, Br/Bi, Cr/Ci; right-hand sides and solutions as re/im
+ * pairs).
+ */
+export class ComplexBlockTridiagonal {
+    /**
+     * @param {number} n number of block rows (nodes)
+     * @param {number | ArrayLike<number>} m block size, or one size per node
+     */
+    constructor(n: number, m: number | ArrayLike<number>);
+    n: number;
+    m: number;
+    sizes: Int32Array<any>;
+    offA: Int32Array<any>;
+    offB: Int32Array<any>;
+    offC: Int32Array<any>;
+    offX: Int32Array<any>;
+    size: number;
+    _piv: Int32Array<ArrayBuffer>;
+    _yr: Float64Array<ArrayBuffer>;
+    _yi: Float64Array<ArrayBuffer>;
+    _tr: Float64Array<ArrayBuffer>;
+    _ti: Float64Array<ArrayBuffer>;
+    clear(): void;
+    factor(): void;
+    /** Solve for (re, im) right-hand sides; results written to outRe/outIm. */
+    solve(bRe: any, bIm: any, outRe: any, outIm: any): void;
+}

package/types/constants.d.ts

@@ -0,0 +1,33 @@
+/** Elementary charge, C. */
+export const ELEMENTARY_CHARGE: 1.602176634e-19;
+/** Avogadro constant, 1/mol. */
+export const AVOGADRO: 6.02214076e+23;
+/** Boltzmann constant, J/K. */
+export const BOLTZMANN: 1.380649e-23;
+/** Faraday constant, C/mol. */
+export const FARADAY: number;
+/** Molar gas constant, J/(mol·K). */
+export const GAS_CONSTANT: number;
+/** Vacuum permittivity, F/m (CODATA 2022). */
+export const EPS0: 8.8541878188e-12;
+/** Unit conversions into driftlet's SI units. */
+export const units: Readonly<{
+    /** mol/L → mol/m³ */
+    molar: (x: any) => number;
+    /** mmol/L → mol/m³ */
+    millimolar: (x: any) => any;
+    /** particles per cm³ → mol/m³ */
+    perCm3: (x: any) => number;
+    /** particles per m³ → mol/m³ */
+    perM3: (x: any) => number;
+    /** eV per particle → J/mol */
+    eV: (x: any) => number;
+    /** J/mol → eV per particle */
+    toEV: (x: any) => number;
+    /** nm → m */
+    nm: (x: any) => number;
+    /** µm → m */
+    um: (x: any) => number;
+    /** cm²/s → m²/s */
+    cm2PerS: (x: any) => number;
+}>;

package/types/data.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Water with the named ions, as a library piece for `build()`: each ion as a species
+ * (c_ref = 1 M) and the material `water` holding them, with D and μ° from `IONS`.
+ * @param {string[]} names ions from `IONS`
+ * @param {{ epsr?: number, material?: string }} [opts] permittivity (default that of water;
+ *   0 makes the solution strictly neutral, without double layers), and the material's name
+ * @returns {{ species: object[], materials: Record<string, object> }}
+ */
+export function aqueous(names: string[], { epsr, material }?: {
+    epsr?: number;
+    material?: string;
+}): {
+    species: object[];
+    materials: Record<string, object>;
+};
+/**
+ * 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`.
+ * Statistics are ideal (Boltzmann); add Fermi–Dirac to the material for degenerate doping.
+ * @param {string} name 'Si', 'Ge' or 'GaAs'
+ * @param {{ material?: string }} [opts]
+ * @returns {{ species: object[], materials: Record<string, object> }}
+ */
+export function semiconductor(name: string, { material }?: {
+    material?: string;
+}): {
+    species: object[];
+    materials: Record<string, object>;
+};
+/**
+ * A metal from `METALS` as a conductor material, its carrier `e-`.
+ * @param {string} name
+ * @param {{ material?: string }} [opts]
+ * @returns {{ species: object[], materials: Record<string, object> }}
+ */
+export function metal(name: string, { material }?: {
+    material?: string;
+}): {
+    species: object[];
+    materials: Record<string, object>;
+};
+/**
+ * Aqueous ions at 25 °C. D: diffusivity at infinite dilution, m²/s (CRC Handbook of Chemistry
+ * and Physics, "Ionic conductivity and diffusion at infinite dilution"). mu0: standard Gibbs
+ * energy of formation, J/mol, the usual table convention with ΔfG°(H⁺) = 0 (Wagman et al., "The
+ * NBS tables of chemical thermodynamic properties", J. Phys. Chem. Ref. Data 11, Suppl. 2, 1982),
+ * on the 1 mol/kg standard state, used here with c_ref = 1000 mol/m³ (1 M).
+ * Names are the formula followed by the charge.
+ */
+export const IONS: Readonly<{
+    [k: string]: any;
+}>;
+/** μ° of liquid water at 25 °C, J/mol (Wagman et al. 1982), for reactions such as H₂O ⇌ H⁺ + OH⁻. */
+export const H2O: -237.129e3;
+/** Relative permittivity of water at 25 °C (Malmberg and Maryott, J. Res. NBS 56, 1, 1956). */
+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
+ * states Nc and Nv (cm⁻³), and drift mobilities of lightly doped material mun and mup
+ * (cm²/(V·s)).
+ */
+export const SEMICONDUCTORS: Readonly<{
+    [k: string]: any;
+}>;
+/**
+ * Metals at 293 K: resistivity rho (10⁻⁸ Ω·m, CRC Handbook, "Electrical resistivity of pure
+ * metals") and the conductivity 1/rho (S/m).
+ */
+export const METALS: Readonly<{
+    [k: string]: any;
+}>;

package/types/describe.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Warnings for numbers that look like unit slips: SI is m, mol/m³, J/mol, m²/s, F/m², C/m³.
+ * @param {object} def device definition
+ * @returns {string[]}
+ */
+export function unitWarnings(def: object): string[];
+/**
+ * A readable summary of a device: its regions (with doping, Debye lengths and the grid at their
+ * ends), faces, contacts and reactions, its characteristic times, and warnings (unit slips, and
+ * double layers coarser than the grid). It validates the definition first, so an invalid one
+ * throws its DeviceError.
+ * @param {object} def device definition
+ * @returns {string}
+ */
+export function describe(def: object): string;

package/types/device.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validate and normalise a device definition.
+ * @param {object} def
+ * @returns {object} internal model
+ */
+export function normalizeDevice(def: object): object;
+/**
+ * The terminals' drives alone (in terminal order: left, right, then the ports), from a definition
+ * whose structure is unchanged: for a fast update of sources.
+ */
+export function normalizeDrives(def: any, model: any): any[];
+/**
+ * A source's value at time t (s). At a step (two points at one time) it's the value after the
+ * step; with `before`, the limit from earlier times, as a time step ending at t sees it.
+ */
+export function sourceAt(src: any, t: any, before?: boolean): any;
+/** The first breakpoint of a source strictly after time t (Infinity if none). */
+export function nextBreakpoint(src: any, t: any): any;
+export { DeviceError };
+import { DeviceError } from './errors.js';