driftlet 0.14.0 → 0.16.4

package/src/sources.js

@@ -127,13 +127,21 @@ export function photogeneration({ material, flux, alpha, mu, from = 0, to, makes
   // nothing is left), then `to`.
   const depth = alpha * (to - from), reach = Math.min(depth, 50), n = Math.ceil(reach / 0.05), step = reach / n;
   const taus = Array.from({ length: n + 1 }, (_, k) => k * step);
-  if (depth > 50) taus.push(depth);
+  if (depth > 50 * (1 + 1e-9)) taus.push(depth); // (not a round-off's worth past the last point)
   // A straight line between two points of e^{−τ} encloses (Δτ/2)·coth(Δτ/2) times too much: each
   // value is scaled back by that, so the total is the exponential's own (to ~Δτ⁴).
   const fix = (step / 2) / Math.tanh(step / 2);
+  // Nothing outside [from, to]: a profile holds its end values beyond its table, so it drops to
+  // zero a hair beyond each end (the light enters a layer of a material that's also elsewhere).
+  const hair = 1e-10 * (to - from);
   return {
     equation: `photon = ${makes}`,
     fixed: { photon: mu },
-    kf: { [material]: { x: taus.map((t) => from + t / alpha), values: taus.map((t) => (flux * alpha * Math.exp(-t)) / fix) } },
+    kf: {
+      [material]: {
+        x: [from - hair, ...taus.map((t) => from + t / alpha), to + hair],
+        values: [0, ...taus.map((t) => (flux * alpha * Math.exp(-t)) / fix), 0],
+      },
+    },
   };
 }

package/src/stack.js

@@ -89,17 +89,27 @@ export function ohmic(d = 0, carriers = ['e-', 'h+']) {
 /**
  * A bath: a neutral composition `c` (mol/m³) held at the contact. With a `reference`, the charged
  * species a reference electrode would sense (Cl⁻ for Ag/AgCl), its levels are referred to that
- * species, which is the terminal. Without one, `bath(c, drive)`, the terminal voltage is the
+ * species, which is the terminal. Without one, `bath(c, drive, opts)`, the terminal voltage is the
  * bath's φ: an ideal salt bridge, the convention of membrane potentials.
  * @param {Record<string, number>} c
  * @param {string | number | object} [reference] the reference species, or the drive
  * @param {number | object} [drive]
- * @param {{ offset?: number }} [opts] where the reference species sits relative to the terminal
- *   voltage, V_ref = V + offset (V)
+ * @param {{ offset?: number, material?: string }} [opts] `offset`: where the reference species
+ *   sits relative to the terminal voltage, V_ref = V + offset (V). `material`: the bath's own
+ *   material (a solution against an ion exchanger), if not the end layer's
  */
-export function bath(c, reference, d = 0, { offset } = {}) {
-  if (typeof reference !== 'string') return { ...drive(reference ?? 0, 'bath'), bath: { c: { ...c } } };
-  return { ...drive(d, 'bath'), bath: { c: { ...c }, reference, ...(offset === undefined ? {} : { offset }) } };
+export function bath(c, reference, d = 0, opts = {}) {
+  if (typeof reference !== 'string') [d, opts] = [reference ?? 0, isObject(d) ? d : {}];
+  const { offset, material } = opts;
+  return {
+    ...drive(d, 'bath'),
+    bath: {
+      c: { ...c },
+      ...(typeof reference === 'string' ? { reference } : {}),
+      ...(offset === undefined ? {} : { offset }),
+      ...(material === undefined ? {} : { material }),
+    },
+  };
 }
 
 const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReactions', 'ports', 'grid', 'geometry'];

package/src/statistics.js

@@ -23,16 +23,20 @@ const MODEL_TYPES = ['ideal', 'fermi-dirac', 'lattice', 'redlich-kister', 'debye
 
 const logistic = (y) => (y >= 0 ? 1 / (1 + Math.exp(-y)) : Math.exp(y) / (1 + Math.exp(y)));
 
-// Safeguarded Newton for an increasing function: f(y) = target on [lo, hi].
+// Safeguarded Newton for an increasing function: f(y) = target on [lo, hi]. A Newton step that
+// leaves the bracket, or that wouldn't halve the last step (Newton zigzagging across an
+// inflection, its bracket shrinking by a little each time: a steep tabulated OCV's ran out of
+// iterations 0.2 thermal units from its root), bisects instead.
 function solveIncreasing(f, target, lo, hi, guess) {
-  let y = Math.min(hi, Math.max(lo, guess));
+  let y = Math.min(hi, Math.max(lo, guess)), last = Infinity;
   for (let it = 0; it < 200; it++) {
     const { v, d } = f(y);
     const r = v - target;
     if (r > 0) hi = y;
     else lo = y;
     let next = y - r / d;
-    if (!(next > lo && next < hi)) next = 0.5 * (lo + hi);
+    if (!(next > lo && next < hi) || Math.abs(next - y) > 0.5 * last) next = 0.5 * (lo + hi);
+    last = Math.abs(next - y);
     if (Math.abs(next - y) <= 1e-15 * Math.max(1, Math.abs(y)) || hi - lo <= 1e-15 * Math.max(1, Math.abs(y))) return next;
     y = next;
   }

package/types/blockTridiagonal.d.ts

@@ -46,6 +46,7 @@ export class BlockTridiagonal {
      * Throws if a diagonal block is exactly singular (unless `staticPivots`).
      */
     factor(): void;
+    _noisyPivots(i: any): number;
     /**
      * Solve with the current factorisation. `rhs` and `out` are Float64Arrays of length `size`
      * (node-major); they may be the same array.

package/types/checks.d.ts

@@ -18,6 +18,11 @@
  *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
+ * - **order** (a steady state, with `refine` and `order`, the defaults): the device solved from
+ *   its definition twice, its species listed as given and in reverse, which must give the same
+ *   steady state (each terminal's voltage and current, each species' amount). A solve that
+ *   depends on the listing has converged somewhere that isn't steady without noticing (round 11's
+ *   fuzzer found it in ~1% of random reacting devices, by exactly this test).
  * - **grid** (with `refine`, the default; in a transient, `ok: null` and a reminder, since the
  *   answer depends on the whole run): in a steady state, the device solved again on a grid
  *   twice as fine everywhere, from this solution interpolated onto it. The current, each floating terminal's voltage and each
@@ -26,14 +31,15 @@
  *   (about 3/4 of it).
  * @param {import('./index.js').Device} device
  * @param {object} [sol] the solution to check (default: the device's present state)
- * @param {{ refine?: boolean, tol?: number }} [opts]
+ * @param {{ refine?: boolean, tol?: number, order?: boolean }} [opts]
  * Every check passed when `ok`; an item with `ok: null` (a warning, or a check that couldn't be
  * made) asks you to look, and doesn't fail it. `text` is a line per check, marked ok, FAIL or ?.
  * @returns {{ ok: boolean, items: CheckItem[], text: string }}
  */
-export function check(device: import("./index.js").Device, sol?: object, { refine, tol }?: {
+export function check(device: import("./index.js").Device, sol?: object, { refine, tol, order }?: {
     refine?: boolean;
     tol?: number;
+    order?: boolean;
 }): {
     ok: boolean;
     items: CheckItem[];

package/types/index.d.ts

@@ -13,8 +13,8 @@ export class Device {
     get solver(): any;
     get grid(): any;
     /**
-     * Change part of the definition (deep-merged). A contact given V or I drops the other, so
-     * `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
+     * Change part of the definition (deep-merged). A contact given V or I drops the other (and
+     * given I, any series R), so `{ contacts: { right: { I: 0 } } }` switches it to open circuit. Ports are patched by name,
      * `{ ports: { gate: { V: 0.2 } } }` (an array replaces them all). A change to the terminals'
      * drives alone (V, I, R) is applied in place, cheaply. Otherwise the device is rebuilt, keeping the current state as
      * the warm start when the grid and species are unchanged (else restarting from the regions' c0).

package/types/particles.d.ts

@@ -8,7 +8,8 @@
  * @param {number} [opts.dots] about how many dots per species (default 200), for the default weight
  * @param {number|object} [opts.weight] amount per dot, mol/m²: one number for every species (so
  *   their dots compare), or { name: weight }; default, each species' total over `dots`
- * @param {number} [opts.cap] the most dots a cell holds on average before it's a sea (default ∞)
+ * @param {number} [opts.cap] the most dots a cell of the asked-for width holds on average before
+ *   it's a sea (a density: a wider cell holds more; default ∞)
  * @param {number} [opts.cells] about how many cells across the device (default 120)
  * @param {() => number} [opts.random] a uniform random source in [0, 1) (default Math.random)
  */
@@ -20,11 +21,7 @@ export function particles(sol: object, { species, dots, weight, cap, cells, rand
     cells?: number;
     random?: () => number;
 }): {
-    cells: {
-        x0: any;
-        x1: any;
-        region: any;
-    }[];
+    cells: any[];
     species: any;
     weight: {};
     sea: {};

package/types/solver.d.ts

@@ -84,6 +84,7 @@ export class Solver {
         left: number;
         right: number;
     };
+    lawForm: Map<any, any>;
     terms: any;
     termV: Float64Array<any>;
     termVPrev: Float64Array<any>;
@@ -92,6 +93,9 @@ export class Solver {
     sourceOverride: Map<any, any>;
     steady: boolean;
     floating: any;
+    drivenKey: any;
+    lawRefs: Map<any, any>;
+    chargeRefs: Map<any, any>;
     termB: any;
     termC: any;
     termDI: Float64Array<any>;
@@ -134,24 +138,37 @@ export class Solver {
     stretchOf: Int32Array<ArrayBuffer>;
     moieties: Float64Array<any>[];
     flatStretches: any[];
-    levelStretches: any[];
-    flattening: boolean;
+    _moves(st: any): boolean;
+    _still(st: any): boolean;
+    _feeds(k: any, st: any): any;
+    _laws(): void;
     constraints: any[];
+    affinities: any[];
     localConstraints: any[];
     islands: any[];
     pinnedIslands: any[];
     islandsOn: boolean;
     pins: any[];
-    constrained: boolean;
+    timeLaws: any[];
+    carriers: any;
+    _captureLaws(): void;
     _captureLocal(): void;
     _applyIslands(): any[];
     islandRow: Float64Array<any>;
     _rowInto(o: any, add: any): void;
     linRow: Float64Array<any>;
     _applyLocalConstraints(): void;
-    _conservedMoieties(): Float64Array<any>[];
+    _conservedMoieties(drives?: boolean, alsoCurrent?: any[], skip?: any): Float64Array<any>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
+    _lawAmount(cs: any): {
+        amount: number;
+        reference: number;
+        dV: number;
+        gross: number;
+    };
+    _lawStart(cs: any): number;
+    _circuitLaws(dt: any): void;
     _solveBordered(rhs: any, delta: any, deltaV: any, pins: any): void;
     dWork: Float64Array<any>;
     borderCols: any[];
@@ -162,6 +179,9 @@ export class Solver {
     amount(stretch: any): number;
     redrive(): void;
     deltaV: Float64Array<any>;
+    stuckReactions(): any[];
+    _drivenKey(): any;
+    _noCurrent(t: any): boolean;
     _refreshSources(): void;
     /** η_i (μ̄/RT) of a port's outside level for species i (its electrode's carrier: at V itself). */
     portEta(port: any, i: any): number;
@@ -233,8 +253,14 @@ export class Solver {
     _portCapacitance(port: any, k: any, dt: any): void;
     _surfaceStorage(port: any, dt: any): void;
     _contact(side: any, dt: any): void;
+    _flatLevel(st: any): {
+        k: number;
+        hi: number;
+        lo: number;
+    };
+    _snapFlat(): void;
     _flatRows(): void;
-    _levelRows(): void;
+    _applyAffinities(): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
     _assembleDifference(dt: any): {
@@ -265,6 +291,7 @@ export class Solver {
         digits: any;
         x: number;
         where: string;
+        nodes: any[];
     };
     /**
      * Advance by dt, splitting the interval into halves (recursively) wherever Newton fails.
@@ -288,6 +315,9 @@ export class Solver {
     };
     contactDEnd: any;
     sourceBefore: boolean;
+    solvedV: any;
+    stepped: boolean;
+    _guess(guess: any): void;
     /**
      * Adaptive time stepping to tEnd: variable-step BDF2 (or backward Euler), with the local error
      * estimated against an explicit predictor through the previous states, and controlled to
@@ -322,7 +352,6 @@ export class Solver {
     };
     _errorNorm(ref: any): number;
     _warmFrom(src: any): void;
-    solvedV: any;
     _snapshot(): {
         u: Float64Array<ArrayBuffer>;
         uLo: Float64Array<ArrayBuffer>;
@@ -351,6 +380,7 @@ export class Solver {
         sourceTime: number;
     };
     _restore(s: any): void;
+    passedCurrent(k: any): any;
     _terminalCurrent(): number;
     /**
      * Small-signal impedance about the current (steady) state, seen at one terminal. Linearising
@@ -404,13 +434,12 @@ export class Solver {
     slowestTime(): number;
     fastestTime(): number;
     /**
-     * Steady state.
-     * - If every species stretch is fed by a contact, nothing is conserved on its own, so the
-     *   true steady equations (dt = ∞, no storage term) are solved directly: no slow modes to
-     *   wait out, however slow the physics (e.g. exponentially scarce minority carriers).
-     * - Otherwise backward-Euler steps at a huge dt, whose storage term pins each conserved
-     *   amount exactly; dt keeps growing ×10 while the state still moves.
-     * If Newton fails, dt ramps up from a small value (pseudo-transient continuation) instead.
+     * Steady state: where a transient from the present state ends, found as the solution of the
+     * steady equations (dt = ∞, no storage term), with no slow modes to wait out, however slow the
+     * physics (e.g. exponentially scarce minority carriers). What the storage term held is held by
+     * the steady system's own rows instead (see _laws): each conserved amount in place of a balance
+     * row that says nothing new, levels that carry nothing held flat, islands' summed balances.
+     * Where Newton from here fails: continuation along the drives, then the pseudo-transient ramp.
      * The clock is not advanced, and open-system conservation bookkeeping restarts here.
      */
     solveSteady(opts?: {}): any;
@@ -420,9 +449,17 @@ export class Solver {
         low: any;
         high: any;
     };
+    charging: {
+        terminal: any;
+        current: any;
+        what: any[];
+    };
+    steadyAt: number;
     _solveSteadyAll(opts: any): any;
     _steadyFromHere(opts: any): any;
     dimmer: boolean;
+    _bound(k: any): boolean;
+    _chargeOnly(k: any): boolean;
     _floatingContinuation(opts: any, r: any): any;
     _generationContinuation(opts: any, r: any): {
         converged: boolean;
@@ -431,22 +468,6 @@ export class Solver {
         history: any;
     };
     _continuation(opts: any, k: any, level: any, target: any, r: any, warm: any, hold: any): any;
-    _solveSteady(opts?: {}): {
-        converged: boolean;
-        steps: number;
-        iterations: number;
-        history: ({
-            dt: number;
-            converged: boolean;
-            iterations: number;
-            maxStep?: undefined;
-        } | {
-            dt: number;
-            converged: boolean;
-            iterations: number;
-            maxStep: number;
-        })[];
-    };
     _steadySteps({ maxSteps, tol }?: {
         maxSteps?: number;
         tol?: number;

package/types/stack.d.ts

@@ -33,16 +33,18 @@ export function ohmic(d?: number, carriers?: string[]): any;
 /**
  * A bath: a neutral composition `c` (mol/m³) held at the contact. With a `reference`, the charged
  * species a reference electrode would sense (Cl⁻ for Ag/AgCl), its levels are referred to that
- * species, which is the terminal. Without one, `bath(c, drive)`, the terminal voltage is the
+ * species, which is the terminal. Without one, `bath(c, drive, opts)`, the terminal voltage is the
  * bath's φ: an ideal salt bridge, the convention of membrane potentials.
  * @param {Record<string, number>} c
  * @param {string | number | object} [reference] the reference species, or the drive
  * @param {number | object} [drive]
- * @param {{ offset?: number }} [opts] where the reference species sits relative to the terminal
- *   voltage, V_ref = V + offset (V)
+ * @param {{ offset?: number, material?: string }} [opts] `offset`: where the reference species
+ *   sits relative to the terminal voltage, V_ref = V + offset (V). `material`: the bath's own
+ *   material (a solution against an ion exchanger), if not the end layer's
  */
-export function bath(c: Record<string, number>, reference?: string | number | object, d?: number, { offset }?: {
+export function bath(c: Record<string, number>, reference?: string | number | object, d?: number, opts?: {
     offset?: number;
+    material?: string;
 }): any;
 /**
  * Build a plain device definition from a stack: