driftlet 0.13.0 → 0.16.2

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/checks.d.ts

@@ -18,7 +18,8 @@
  *   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.
- * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid
+ * - **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
  *   region's charge must agree to `tol` (relative, default 1e-2, a plot's accuracy; a benchmark
  *   wants less). The discretisation is second order, so the change estimates this grid's error

package/types/kit.d.ts

@@ -36,6 +36,7 @@ export function vacuumZeroCharge(def: object, workFunction: number, inside: Vacu
 export { live } from "./live.js";
 export { recorder } from "./recorder.js";
 export { check } from "./checks.js";
+export { particles } from "./particles.js";
 export { polarization } from "./polarization.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,

package/types/particles.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A swarm of dots sampling a solution's concentrations and fluxes. Amounts are per area (a planar
+ * device's). `step(dt)` moves them on in the device's time, at the rates of the solution last
+ * given; `update(sol)` gives a new one.
+ * @param {object} sol a solution (from solve(), advance(), live(), …)
+ * @param {object} [opts]
+ * @param {string[]} [opts.species] which species (default: every species with a concentration)
+ * @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 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)
+ */
+export function particles(sol: object, { species, dots, weight, cap, cells, random }?: {
+    species?: string[];
+    dots?: number;
+    weight?: number | object;
+    cap?: number;
+    cells?: number;
+    random?: () => number;
+}): {
+    cells: any[];
+    species: any;
+    weight: {};
+    sea: {};
+    dots: any[];
+    events: any[];
+    crossed: {};
+    time: number;
+    update: (next: any, { resample }?: {
+        resample?: boolean;
+    }) => /*elided*/ any;
+    step: (dt: any, { maxHops }?: {
+        maxHops?: number;
+    }) => /*elided*/ any;
+    expected: (nm: any) => Float64Array<ArrayBuffer>;
+};

package/types/solution.d.ts

@@ -9,6 +9,7 @@ export function makeSolution(solver: any, result?: {}): {
     muStd: {};
     V: {};
     Vstd: {};
+    T: any;
     time: any;
     steady: any;
     converged: any;

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,36 @@ 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[];
     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[]): 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[];
@@ -209,9 +225,11 @@ export class Solver {
     mixWork: Float64Array<any>[];
     _dc(g: any, k: any, d: any): void;
     bulkRate(rx: any, g: any): number;
+    bulkForward(rx: any, g: any): any;
     bulkOneWay(rx: any, g: any): number;
     _srhRate(law: any, cn: any, cp: any, a: any): {
         rate: number;
+        forward: number;
         oneWay: number;
         Cn: number;
         Cp: number;
@@ -231,8 +249,13 @@ 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;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
     _assembleDifference(dt: any): {
@@ -263,6 +286,7 @@ export class Solver {
         digits: any;
         x: number;
         where: string;
+        nodes: any[];
     };
     /**
      * Advance by dt, splitting the interval into halves (recursively) wherever Newton fails.
@@ -286,6 +310,8 @@ export class Solver {
     };
     contactDEnd: any;
     sourceBefore: boolean;
+    solvedV: any;
+    stepped: boolean;
     /**
      * 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
@@ -320,7 +346,6 @@ export class Solver {
     };
     _errorNorm(ref: any): number;
     _warmFrom(src: any): void;
-    solvedV: any;
     _snapshot(): {
         u: Float64Array<ArrayBuffer>;
         uLo: Float64Array<ArrayBuffer>;
@@ -387,6 +412,8 @@ export class Solver {
         g: any[];
         d: any[];
     }[];
+    segmentFluxes(): Float64Array<ArrayBuffer>[];
+    faceOneWay(f: any): any;
     _smallSignalProfiles(xr: any, xi: any): {
         phi: {
             re: Float64Array<any>;
@@ -400,13 +427,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;
@@ -416,9 +442,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;
@@ -427,22 +461,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: