driftlet 0.1.0

package/src/bernoulli.js

@@ -0,0 +1,29 @@
+// The Bernoulli function B(x) = x / (eˣ − 1) and its derivative, evaluated stably.
+//
+// These are the weights of Scharfetter–Gummel fluxes. Near x = 0 both are computed from
+// their Taylor series; elsewhere B uses expm1 (accurate for small |x|, and it overflows
+// gracefully to B → 0 for large positive x). Identity used: B(−x) = B(x) + x.
+
+const SERIES_LIMIT = 0.1;
+
+/** B(x) = x / (eˣ − 1), with B(0) = 1. */
+export function bernoulli(x) {
+  if (Math.abs(x) < SERIES_LIMIT) {
+    const x2 = x * x;
+    // 1 − x/2 + x²/12 − x⁴/720 + x⁶/30240 − x⁸/1209600
+    return 1 - x / 2 + x2 * (1 / 12 + x2 * (-1 / 720 + x2 * (1 / 30240 - x2 / 1209600)));
+  }
+  return x / Math.expm1(x);
+}
+
+/** dB/dx, with B'(0) = −1/2. */
+export function bernoulliDerivative(x) {
+  if (Math.abs(x) < SERIES_LIMIT) {
+    const x2 = x * x;
+    // −1/2 + x/6 − x³/180 + x⁵/5040 − x⁷/151200
+    return -0.5 + x * (1 / 6 + x2 * (-1 / 180 + x2 * (1 / 5040 - x2 / 151200)));
+  }
+  const b = x / Math.expm1(x);
+  // B' = (B/x)(1 − B(−x)) = (B/x)(1 − B − x)
+  return (b / x) * (1 - b - x);
+}

package/src/blockTridiagonal.js

@@ -0,0 +1,492 @@
+// Block-tridiagonal linear solver (block Thomas algorithm).
+//
+// Solves, for node i = 0 … n−1 with blocks of size m_i,
+//     A_i x_{i−1} + B_i x_i + C_i x_{i+1} = d_i
+// where B_i is m_i × m_i, A_i is m_i × m_{i−1} and C_i is m_i × m_{i+1}. Blocks are stored
+// row-major, one after another, in flat Float64Arrays; `offA[i]`, `offB[i]`, `offC[i]` give
+// where each starts and `offX[i]` where node i's entries start in a vector. A_0 and C_{n−1} are
+// ignored, but stored as if the end blocks repeated (m_{−1} = m_0, m_n = m_{n−1}), so with a
+// single size m every block i sits at i·m², as for a uniform array of blocks. A size may be 0
+// (the chain then splits there). All storage is allocated once; factor() and solve() allocate
+// nothing.
+//
+// Within each diagonal block, LU uses partial pivoting, so zero diagonal entries (such as a
+// slot that carries an interface flux instead of a value) are fine. There is no pivoting
+// *between* blocks: that is the usual block Thomas trade-off, safe for the diagonally
+// dominant-ish systems that finite-volume assembly produces.
+
+// Offsets of every block and vector segment for block sizes `sizes`.
+function layout(n, m, name) {
+  if (!(Number.isInteger(n) && n >= 1)) throw new RangeError(`n must be a positive integer, got ${n}`);
+  let sizes;
+  if (typeof m === 'number') {
+    if (!(Number.isInteger(m) && m >= 1)) throw new RangeError(`m must be a positive integer, got ${m}`);
+    sizes = new Int32Array(n).fill(m);
+  } else {
+    if (!(m && m.length === n)) throw new RangeError(`${name}: give one block size per node (${n})`);
+    sizes = Int32Array.from(m);
+    for (const v of sizes) if (!(v >= 0)) throw new RangeError(`block sizes must be non-negative integers, got ${v}`);
+  }
+  const offA = new Int32Array(n + 1), offB = new Int32Array(n + 1), offC = new Int32Array(n + 1), offX = new Int32Array(n + 1);
+  for (let i = 0; i < n; i++) {
+    const mi = sizes[i], mp = i > 0 ? sizes[i - 1] : mi, mn = i < n - 1 ? sizes[i + 1] : mi;
+    offA[i + 1] = offA[i] + mi * mp;
+    offB[i + 1] = offB[i] + mi * mi;
+    offC[i + 1] = offC[i] + mi * mn;
+    offX[i + 1] = offX[i] + mi;
+  }
+  const maxM = sizes.reduce((a, v) => Math.max(a, v), 0);
+  return { sizes, offA, offB, offC, offX, maxM, uniform: typeof m === 'number' ? m : null };
+}
+
+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, m) {
+    const L = layout(n, m, 'BlockTridiagonal');
+    this.n = n;
+    /** The block size if every block has the same size, else null. */
+    this.m = L.uniform;
+    /** Block size of each node. */
+    this.sizes = L.sizes;
+    this.offA = L.offA;
+    this.offB = L.offB;
+    this.offC = L.offC;
+    this.offX = L.offX;
+    /** Total number of unknowns. */
+    this.size = L.offX[n];
+    /** Sub-diagonal blocks A_i (coupling to node i−1). */
+    this.A = new Float64Array(L.offA[n]);
+    /** Diagonal blocks B_i. */
+    this.B = new Float64Array(L.offB[n]);
+    /** Super-diagonal blocks C_i (coupling to node i+1). */
+    this.C = new Float64Array(L.offC[n]);
+
+    this._lu = new Float64Array(L.offB[n]); // LU factors of W_i = B_i − A_i C'_{i−1}
+    this._piv = new Int32Array(this.size);
+    this._cp = new Float64Array(L.offC[n]); // C'_i = W_i⁻¹ C_i
+    this._y = new Float64Array(this.size);
+    this._tmp = new Float64Array(L.maxM);
+    this.factored = false;
+    /** Smallest |pivot| / (largest |entry| of its block) seen in the last factor(). */
+    this.minPivotRatio = Infinity;
+    /** The block found exactly singular by the last factor(), or −1. */
+    this.singularBlock = -1;
+  }
+
+  /** Zero all of A, B, C (ready for fresh assembly). */
+  clear() {
+    this.A.fill(0);
+    this.B.fill(0);
+    this.C.fill(0);
+    this.factored = false;
+  }
+
+  /**
+   * Factorise the current A, B, C. A, B, C are left untouched.
+   * Throws if a diagonal block is exactly singular.
+   */
+  factor() {
+    const { n, A, B, C, sizes, offA, offB, offC, offX } = this;
+    const lu = this._lu, piv = this._piv, cp = this._cp, tmp = this._tmp;
+    let minRatio = Infinity;
+    this.singularBlock = -1;
+
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], o = offB[i];
+      if (m === 0) continue;
+      // W_i = B_i − A_i C'_{i−1}
+      if (i === 0 || sizes[i - 1] === 0) {
+        for (let k = 0; k < m * m; k++) lu[o + k] = B[o + k];
+      } else {
+        const mp = sizes[i - 1], oa = offA[i], op = offC[i - 1]; // C'_{i−1}: mp × m
+        for (let r = 0; r < m; r++) {
+          for (let c = 0; c < m; c++) {
+            let s = B[o + r * m + c];
+            for (let k = 0; k < mp; k++) s -= A[oa + r * mp + k] * cp[op + k * m + c];
+            lu[o + r * m + c] = s;
+          }
+        }
+      }
+      const ratio = luFactor(lu, o, piv, offX[i], m);
+      if (!(ratio > 0)) {
+        this.factored = false;
+        this.singularBlock = i;
+        throw new Error(`BlockTridiagonal: diagonal block ${i} is singular`);
+      }
+      if (ratio < minRatio) minRatio = ratio;
+      // C'_i = W_i⁻¹ C_i, column by column
+      if (i < n - 1) {
+        const mn = sizes[i + 1], oc = offC[i];
+        for (let c = 0; c < mn; c++) {
+          for (let r = 0; r < m; r++) tmp[r] = C[oc + r * mn + c];
+          luSolve(lu, o, piv, offX[i], m, tmp);
+          for (let r = 0; r < m; r++) cp[oc + r * mn + c] = tmp[r];
+        }
+      }
+    }
+    this.minPivotRatio = minRatio;
+    this.factored = true;
+  }
+
+  /**
+   * Solve with the current factorisation. `rhs` and `out` are Float64Arrays of length `size`
+   * (node-major); they may be the same array.
+   */
+  solve(rhs, out = new Float64Array(this.size)) {
+    if (!this.factored) throw new Error('BlockTridiagonal: call factor() before solve()');
+    const { n, A, sizes, offA, offB, offC, offX } = this;
+    const lu = this._lu, piv = this._piv, cp = this._cp, y = this._y;
+
+    // Forward: y_i = W_i⁻¹ (d_i − A_i y_{i−1})
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], v = offX[i];
+      if (m === 0) continue;
+      const mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], vp = v - mp;
+      for (let r = 0; r < m; r++) {
+        let s = rhs[v + r];
+        for (let k = 0; k < mp; k++) s -= A[oa + r * mp + k] * y[vp + k];
+        y[v + r] = s;
+      }
+      luSolveAt(lu, offB[i], piv, v, m, y, v);
+    }
+    // Backward: x_i = y_i − C'_i x_{i+1}
+    for (let i = n - 1; i >= 0; i--) {
+      const m = sizes[i], v = offX[i];
+      const mn = i < n - 1 ? sizes[i + 1] : 0, oc = offC[i], vn = v + m;
+      for (let r = 0; r < m; r++) {
+        let s = y[v + r];
+        for (let k = 0; k < mn; k++) s -= cp[oc + r * mn + k] * out[vn + k];
+        out[v + r] = s;
+      }
+    }
+    return out;
+  }
+
+  /**
+   * 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() {
+    if (!this.factored && !(this.singularBlock >= 0)) throw new Error('BlockTridiagonal: call factor() before cancellation()');
+    const { A, B, sizes, offA, offB, offC } = this, cp = this._cp;
+    const n = this.factored ? this.n : this.singularBlock + 1;
+    const mx = sizes.reduce((a, v) => Math.max(a, v), 0);
+    const w = new Float64Array(mx * mx), S = new Float64Array(mx * mx);
+    let worst = 1, block = -1;
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], ob = offB[i], oc = i > 0 ? offC[i - 1] : 0;
+      for (let r = 0; r < m; r++) {
+        for (let c = 0; c < m; c++) {
+          let v = B[ob + r * m + c], sum = Math.abs(v);
+          for (let k = 0; k < mp; k++) {
+            const t = A[oa + r * mp + k] * cp[oc + k * m + c];
+            v -= t;
+            sum += Math.abs(t);
+          }
+          w[r * m + c] = v;
+          S[r * m + c] = sum;
+        }
+      }
+      for (let k = 0; k < m; k++) {
+        let p = k;
+        for (let r = k + 1; r < m; r++) if (Math.abs(w[r * m + k]) > Math.abs(w[p * m + k])) p = r;
+        if (p !== k) {
+          for (let c = 0; c < m; c++) {
+            [w[k * m + c], w[p * m + c]] = [w[p * m + c], w[k * m + c]];
+            [S[k * m + c], S[p * m + c]] = [S[p * m + c], S[k * m + c]];
+          }
+        }
+        const piv = Math.abs(w[k * m + k]), sum = S[k * m + k];
+        if (sum > worst * piv) {
+          worst = piv === 0 ? Infinity : sum / piv;
+          block = i;
+        }
+        if (piv === 0) continue;
+        for (let r = k + 1; r < m; r++) {
+          const f = w[r * m + k] / w[k * m + k];
+          if (f === 0) continue;
+          for (let c = k + 1; c < m; c++) {
+            w[r * m + c] -= f * w[k * m + c];
+            S[r * m + c] += Math.abs(f) * S[k * m + c];
+          }
+        }
+      }
+    }
+    return { digits: Math.log10(worst), block };
+  }
+
+  /** out = M·x using the stored (unfactored) blocks. For residual checks and tests. */
+  multiply(x, out = new Float64Array(this.size)) {
+    const { n, A, B, C, sizes, offA, offB, offC, offX } = this;
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], v = offX[i];
+      const mp = i > 0 ? sizes[i - 1] : 0, mn = i < n - 1 ? sizes[i + 1] : 0;
+      for (let r = 0; r < m; r++) {
+        let s = 0;
+        for (let k = 0; k < m; k++) s += B[offB[i] + r * m + k] * x[v + k];
+        for (let k = 0; k < mp; k++) s += A[offA[i] + r * mp + k] * x[v - mp + k];
+        for (let k = 0; k < mn; k++) s += C[offC[i] + r * mn + k] * x[v + m + k];
+        out[v + r] = s;
+      }
+    }
+    return out;
+  }
+}
+
+// In-place LU with partial pivoting of the m×m block at a[o…]. Row swaps are recorded in
+// piv[p…]. Returns min |pivot| / max |entry| (0 if singular).
+function luFactor(a, o, piv, p, m) {
+  let maxEntry = 0;
+  for (let k = 0; k < m * m; k++) {
+    const v = Math.abs(a[o + k]);
+    if (v > maxEntry) maxEntry = v;
+  }
+  if (maxEntry === 0) return 0;
+  let minPivot = Infinity;
+  for (let k = 0; k < m; k++) {
+    let best = k, bestVal = Math.abs(a[o + k * m + k]);
+    for (let r = k + 1; r < m; r++) {
+      const v = Math.abs(a[o + r * m + k]);
+      if (v > bestVal) { best = r; bestVal = v; }
+    }
+    piv[p + k] = best;
+    if (bestVal === 0) return 0;
+    if (bestVal < minPivot) minPivot = bestVal;
+    if (best !== k) {
+      for (let c = 0; c < m; c++) {
+        const t = a[o + k * m + c];
+        a[o + k * m + c] = a[o + best * m + c];
+        a[o + best * m + c] = t;
+      }
+    }
+    const inv = 1 / a[o + k * m + k];
+    for (let r = k + 1; r < m; r++) {
+      const f = (a[o + r * m + k] *= inv);
+      if (f !== 0) for (let c = k + 1; c < m; c++) a[o + r * m + c] -= f * a[o + k * m + c];
+    }
+  }
+  return minPivot / maxEntry;
+}
+
+// Solve (LU) x = b in place, b in vec[0…m).
+function luSolve(a, o, piv, p, m, vec) {
+  luSolveAt(a, o, piv, p, m, vec, 0);
+}
+
+// Solve (LU) x = b in place, b in vec[s…s+m).
+function luSolveAt(a, o, piv, p, m, vec, s) {
+  for (let k = 0; k < m; k++) {
+    const j = piv[p + k];
+    if (j !== k) {
+      const t = vec[s + k];
+      vec[s + k] = vec[s + j];
+      vec[s + j] = t;
+    }
+  }
+  for (let r = 1; r < m; r++) {
+    let v = vec[s + r];
+    for (let c = 0; c < r; c++) v -= a[o + r * m + c] * vec[s + c];
+    vec[s + r] = v;
+  }
+  for (let r = m - 1; r >= 0; r--) {
+    let v = vec[s + r];
+    for (let c = r + 1; c < m; c++) v -= a[o + r * m + c] * vec[s + c];
+    vec[s + r] = v / a[o + r * m + r];
+  }
+}
+
+/**
+ * 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, m) {
+    const L = layout(n, m, 'ComplexBlockTridiagonal');
+    this.n = n;
+    this.m = L.uniform;
+    this.sizes = L.sizes;
+    this.offA = L.offA;
+    this.offB = L.offB;
+    this.offC = L.offC;
+    this.offX = L.offX;
+    this.size = L.offX[n];
+    for (const k of ['Ar', 'Ai']) this[k] = new Float64Array(L.offA[n]);
+    for (const k of ['Br', 'Bi', '_lr', '_li']) this[k] = new Float64Array(L.offB[n]);
+    for (const k of ['Cr', 'Ci', '_cr', '_ci']) this[k] = new Float64Array(L.offC[n]);
+    this._piv = new Int32Array(this.size);
+    this._yr = new Float64Array(this.size);
+    this._yi = new Float64Array(this.size);
+    this._tr = new Float64Array(L.maxM);
+    this._ti = new Float64Array(L.maxM);
+  }
+
+  clear() {
+    for (const k of ['Ar', 'Ai', 'Br', 'Bi', 'Cr', 'Ci']) this[k].fill(0);
+  }
+
+  factor() {
+    const { n, Ar, Ai, Br, Bi, Cr, Ci, _lr: lr, _li: li, _cr: cr, _ci: ci, _piv: piv, _tr: tr, _ti: ti } = this;
+    const { sizes, offA, offB, offC, offX } = this;
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], o = offB[i];
+      if (m === 0) continue;
+      const mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], op = i > 0 ? offC[i - 1] : 0;
+      for (let r = 0; r < m; r++) {
+        for (let c = 0; c < m; c++) {
+          let sr = Br[o + r * m + c], si = Bi[o + r * m + c];
+          for (let k = 0; k < mp; k++) {
+            const ar = Ar[oa + r * mp + k], ai = Ai[oa + r * mp + k];
+            const pr = cr[op + k * m + c], pi = ci[op + k * m + c];
+            sr -= ar * pr - ai * pi;
+            si -= ar * pi + ai * pr;
+          }
+          lr[o + r * m + c] = sr;
+          li[o + r * m + c] = si;
+        }
+      }
+      if (!cluFactor(lr, li, o, piv, offX[i], m)) throw new Error(`ComplexBlockTridiagonal: diagonal block ${i} is singular`);
+      if (i < n - 1) {
+        const mn = sizes[i + 1], oc = offC[i];
+        for (let c = 0; c < mn; c++) {
+          for (let r = 0; r < m; r++) {
+            tr[r] = Cr[oc + r * mn + c];
+            ti[r] = Ci[oc + r * mn + c];
+          }
+          cluSolve(lr, li, o, piv, offX[i], m, tr, ti, 0);
+          for (let r = 0; r < m; r++) {
+            cr[oc + r * mn + c] = tr[r];
+            ci[oc + r * mn + c] = ti[r];
+          }
+        }
+      }
+    }
+  }
+
+  /** Solve for (re, im) right-hand sides; results written to outRe/outIm. */
+  solve(bRe, bIm, outRe, outIm) {
+    const { n, Ar, Ai, _lr: lr, _li: li, _cr: cr, _ci: ci, _piv: piv, _yr: yr, _yi: yi } = this;
+    const { sizes, offA, offB, offC, offX } = this;
+    for (let i = 0; i < n; i++) {
+      const m = sizes[i], v = offX[i];
+      if (m === 0) continue;
+      const mp = i > 0 ? sizes[i - 1] : 0, oa = offA[i], vp = v - mp;
+      for (let r = 0; r < m; r++) {
+        let sr = bRe[v + r], si = bIm[v + r];
+        for (let k = 0; k < mp; k++) {
+          const ar = Ar[oa + r * mp + k], ai = Ai[oa + r * mp + k];
+          sr -= ar * yr[vp + k] - ai * yi[vp + k];
+          si -= ar * yi[vp + k] + ai * yr[vp + k];
+        }
+        yr[v + r] = sr;
+        yi[v + r] = si;
+      }
+      cluSolve(lr, li, offB[i], piv, v, m, yr, yi, v);
+    }
+    for (let i = n - 1; i >= 0; i--) {
+      const m = sizes[i], v = offX[i];
+      const mn = i < n - 1 ? sizes[i + 1] : 0, oc = offC[i], vn = v + m;
+      for (let r = 0; r < m; r++) {
+        let sr = yr[v + r], si = yi[v + r];
+        for (let k = 0; k < mn; k++) {
+          const pr = cr[oc + r * mn + k], pi = ci[oc + r * mn + k];
+          const xr = outRe[vn + k], xi = outIm[vn + k];
+          sr -= pr * xr - pi * xi;
+          si -= pr * xi + pi * xr;
+        }
+        outRe[v + r] = sr;
+        outIm[v + r] = si;
+      }
+    }
+  }
+}
+
+// Complex LU with partial pivoting (by modulus) of the block at o; false if singular.
+function cluFactor(ar, ai, o, piv, p, m) {
+  for (let k = 0; k < m; k++) {
+    let best = k, bestVal = Math.hypot(ar[o + k * m + k], ai[o + k * m + k]);
+    for (let r = k + 1; r < m; r++) {
+      const v = Math.hypot(ar[o + r * m + k], ai[o + r * m + k]);
+      if (v > bestVal) {
+        best = r;
+        bestVal = v;
+      }
+    }
+    piv[p + k] = best;
+    if (bestVal === 0) return false;
+    if (best !== k) {
+      for (let c = 0; c < m; c++) {
+        let t = ar[o + k * m + c];
+        ar[o + k * m + c] = ar[o + best * m + c];
+        ar[o + best * m + c] = t;
+        t = ai[o + k * m + c];
+        ai[o + k * m + c] = ai[o + best * m + c];
+        ai[o + best * m + c] = t;
+      }
+    }
+    const dr = ar[o + k * m + k], di = ai[o + k * m + k], d2 = dr * dr + di * di;
+    const invr = dr / d2, invi = -di / d2;
+    for (let r = k + 1; r < m; r++) {
+      const xr = ar[o + r * m + k], xi = ai[o + r * m + k];
+      const fr = xr * invr - xi * invi, fi = xr * invi + xi * invr;
+      ar[o + r * m + k] = fr;
+      ai[o + r * m + k] = fi;
+      if (fr === 0 && fi === 0) continue;
+      for (let c = k + 1; c < m; c++) {
+        const ur = ar[o + k * m + c], ui = ai[o + k * m + c];
+        ar[o + r * m + c] -= fr * ur - fi * ui;
+        ai[o + r * m + c] -= fr * ui + fi * ur;
+      }
+    }
+  }
+  return true;
+}
+
+function cluSolve(ar, ai, o, piv, p, m, vr, vi, s) {
+  for (let k = 0; k < m; k++) {
+    const j = piv[p + k];
+    if (j !== k) {
+      let t = vr[s + k];
+      vr[s + k] = vr[s + j];
+      vr[s + j] = t;
+      t = vi[s + k];
+      vi[s + k] = vi[s + j];
+      vi[s + j] = t;
+    }
+  }
+  for (let r = 1; r < m; r++) {
+    let xr = vr[s + r], xi = vi[s + r];
+    for (let c = 0; c < r; c++) {
+      const lr = ar[o + r * m + c], li = ai[o + r * m + c];
+      xr -= lr * vr[s + c] - li * vi[s + c];
+      xi -= lr * vi[s + c] + li * vr[s + c];
+    }
+    vr[s + r] = xr;
+    vi[s + r] = xi;
+  }
+  for (let r = m - 1; r >= 0; r--) {
+    let xr = vr[s + r], xi = vi[s + r];
+    for (let c = r + 1; c < m; c++) {
+      const ur = ar[o + r * m + c], ui = ai[o + r * m + c];
+      xr -= ur * vr[s + c] - ui * vi[s + c];
+      xi -= ur * vi[s + c] + ui * vr[s + c];
+    }
+    const dr = ar[o + r * m + r], di = ai[o + r * m + r], d2 = dr * dr + di * di;
+    vr[s + r] = (xr * dr + xi * di) / d2;
+    vi[s + r] = (xi * dr - xr * di) / d2;
+  }
+}

package/src/constants.js

@@ -0,0 +1,36 @@
+// Physical constants (SI, CODATA exact values where defined) and unit helpers.
+
+/** Elementary charge, C. */
+export const ELEMENTARY_CHARGE = 1.602176634e-19;
+/** Avogadro constant, 1/mol. */
+export const AVOGADRO = 6.02214076e23;
+/** Boltzmann constant, J/K. */
+export const BOLTZMANN = 1.380649e-23;
+/** Faraday constant, C/mol. */
+export const FARADAY = ELEMENTARY_CHARGE * AVOGADRO;
+/** Molar gas constant, J/(mol·K). */
+export const GAS_CONSTANT = BOLTZMANN * AVOGADRO;
+/** Vacuum permittivity, F/m (CODATA 2022). */
+export const EPS0 = 8.8541878188e-12;
+
+/** Unit conversions into driftlet's SI units. */
+export const units = Object.freeze({
+  /** mol/L → mol/m³ */
+  molar: (x) => x * 1e3,
+  /** mmol/L → mol/m³ */
+  millimolar: (x) => x,
+  /** particles per cm³ → mol/m³ */
+  perCm3: (x) => (x * 1e6) / AVOGADRO,
+  /** particles per m³ → mol/m³ */
+  perM3: (x) => x / AVOGADRO,
+  /** eV per particle → J/mol */
+  eV: (x) => x * FARADAY,
+  /** J/mol → eV per particle */
+  toEV: (x) => x / FARADAY,
+  /** nm → m */
+  nm: (x) => x * 1e-9,
+  /** µm → m */
+  um: (x) => x * 1e-6,
+  /** cm²/s → m²/s */
+  cm2PerS: (x) => x * 1e-4,
+});

package/src/data.js

@@ -0,0 +1,127 @@
+// A small data library for driftlet/kit, every entry with its source (see docs/data.md). Kept
+// small on purpose: a wrong library number is worse than a wrong demo number. Bulk properties
+// 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 } from './errors.js';
+import { FARADAY, GAS_CONSTANT, AVOGADRO } from './constants.js';
+
+const fail = (message) => {
+  throw new DeviceError(message);
+};
+const freeze = (table) => Object.freeze(Object.fromEntries(Object.entries(table).map(([k, v]) => [k, Object.freeze(v)])));
+
+/**
+ * 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 = freeze({
+  'H+': { z: 1, D: 9.311e-9, mu0: 0 },
+  'Li+': { z: 1, D: 1.029e-9, mu0: -293.31e3 },
+  'Na+': { z: 1, D: 1.334e-9, mu0: -261.905e3 },
+  'K+': { z: 1, D: 1.957e-9, mu0: -283.27e3 },
+  'Ag+': { z: 1, D: 1.648e-9, mu0: 77.107e3 },
+  'Cu2+': { z: 2, D: 0.714e-9, mu0: 65.49e3 },
+  'Zn2+': { z: 2, D: 0.703e-9, mu0: -147.06e3 },
+  'Fe2+': { z: 2, D: 0.719e-9, mu0: -78.9e3 },
+  'Fe3+': { z: 3, D: 0.604e-9, mu0: -4.7e3 },
+  'OH-': { z: -1, D: 5.273e-9, mu0: -157.244e3 },
+  'Cl-': { z: -1, D: 2.032e-9, mu0: -131.228e3 },
+  'NO3-': { z: -1, D: 1.902e-9, mu0: -111.25e3 },
+  'SO42-': { z: -2, D: 1.065e-9, mu0: -744.53e3 },
+});
+
+/** μ° 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 = freeze({
+  Si: { epsr: 11.9, Eg: 1.12, chi: 4.05, Nc: 2.8e19, Nv: 1.04e19, mun: 1500, mup: 450 },
+  Ge: { epsr: 16.0, Eg: 0.66, chi: 4.0, Nc: 1.04e19, Nv: 6.0e18, mun: 3900, mup: 1900 },
+  GaAs: { epsr: 13.1, Eg: 1.424, chi: 4.07, Nc: 4.7e17, Nv: 7.0e18, mun: 8500, mup: 400 },
+});
+
+/**
+ * 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 = freeze(
+  Object.fromEntries(
+    Object.entries({ Ag: 1.587, Cu: 1.678, Au: 2.214, Al: 2.65, Zn: 5.9, Li: 9.28, Pt: 10.5 }).map(([name, rho]) => [name, { rho, conductivity: 1e8 / rho }]),
+  ),
+);
+
+/**
+ * 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, { epsr = WATER_EPSR, material = 'water' } = {}) {
+  if (!Array.isArray(names) || names.length === 0) fail('aqueous: give a list of ions, e.g. aqueous([\'Na+\', \'Cl-\'])');
+  const species = [], entries = {};
+  for (const name of names) {
+    const ion = IONS[name];
+    if (!ion) fail(`aqueous: no data for '${name}' (the library has ${Object.keys(IONS).join(', ')})`);
+    species.push({ name, z: ion.z, cRef: 1000 });
+    entries[name] = { D: ion.D, mu0: ion.mu0 };
+  }
+  return { species, materials: { [material]: { epsr, species: entries } } };
+}
+
+/**
+ * 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, { material = name } = {}) {
+  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;
+  const perCm3 = (n) => (n * 1e6) / AVOGADRO;
+  return {
+    species: [
+      { name: 'e-', z: -1 },
+      { name: 'h+', z: 1 },
+    ],
+    materials: {
+      [material]: {
+        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) },
+        },
+      },
+    },
+  };
+}
+
+/**
+ * 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, { material = name } = {}) {
+  const m = METALS[name];
+  if (!m) fail(`metal: no data for '${name}' (the library has ${Object.keys(METALS).join(', ')})`);
+  return { species: [{ name: 'e-', z: -1 }], materials: { [material]: { conductor: { species: 'e-', conductivity: m.conductivity } } } };
+}