driftlet 0.16.2 → 1.0.0

package/src/stack.js

@@ -4,7 +4,7 @@
 // that you didn't write: it only moves things to where the definition keeps them, and converts
 // the kit's doping shorthand (donors and acceptors).
 
-import { DeviceError } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 import { FARADAY } from './constants.js';
 
 const fail = (message) => {
@@ -158,8 +158,21 @@ export function build(def) {
   }
   if (pendingFace) fail(`${at(pendingFace.k)}: a face after the last layer (the contact is the boundary there)`);
   if (regions.length === 0) fail('build.stack has no layers');
+  // A contact holding a carrier its layer lacks: most often ohmic()'s default on a metal.
+  for (const [k, end] of [[0, regions[0]], [stack.length - 1, regions[regions.length - 1]]]) {
+    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked') : [];
+    const mat = materials[end.material];
+    if (!isObject(mat)) continue;
+    const has = (s) => (isObject(mat.conductor) ? mat.conductor.species === s : isObject(mat.species) && mat.species[s] !== undefined);
+    const lacks = held.filter((s) => !has(s));
+    if (lacks.length === 0) continue;
+    const kept = held.filter(has);
+    const hint = stack[k].phi === 'bulk' && kept.length > 0 ? `: write ohmic(V, [${kept.map((s) => `'${s}'`).join(', ')}]) (ohmic() holds e- and h+ unless told${isObject(mat.conductor) ? '; a metal has only its carrier' : ''})` : '';
+    fail(`${at(k)}: the contact holds ${lacks.map((s) => `'${s}'`).join(' and ')}, which its layer's material '${end.material}' doesn't have${hint}`);
+  }
 
   function region(item, path) {
+    checkOptions(path, item, ['name', 'material', 'length', 'fixedCharge', 'c0', 'velocity', 'mixing', 'grid', 'donors', 'acceptors']);
     const { donors, acceptors, ...r } = item;
     if (donors !== undefined || acceptors !== undefined) {
       if (r.fixedCharge !== undefined) fail(`${path}: give doping as donors and acceptors, or fixedCharge, not both`);

package/src/statistics.js

@@ -157,7 +157,7 @@ function tableOccupancy(xs, zs, fail) {
     const x = k / 4000;
     const q = r(x);
     if (x > 0 && x < 1 && !(1 + x * (1 - x) * q.d > 1e-9)) {
-      fail(`ocv: the interpolated curve isn't monotone near x = ${x.toFixed(3)} (E must fall steadily with x; add points or smooth the data)`);
+      fail(`ocv: near x = ${x.toFixed(3)} the curve is flat or rising against the ideal-solution slope, (RT/F) ln(x/(1−x)), as on a two-phase plateau (not supported): more points alone won't help; give it some of that slope, adding −a (RT/F) ln(x/(1−x)) to E (a = 0.1 passes at points 0.01 apart, less with points closer near the ends; docs/statistics.md)`);
     }
     rmin = Math.min(rmin, q.v);
     rmax = Math.max(rmax, q.v);

package/src/traces.js

@@ -3,6 +3,7 @@
 // range. Plain data, for any plotting toolkit (driftlet/plot draws it as SVG).
 
 import { level } from './equation.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 const finite = (a) => {
   for (let k = 0; k < a.length; k++) if (Number.isFinite(a[k])) return true;
@@ -78,6 +79,8 @@ export function typeset(name, z) {
  *   faces: number[], range: [number, number] }}
  */
 export function traces(sol, { species, standard = true, phi = false, energy = false, levels = [], labels = {}, shifts = {} } = {}) {
+  checkOptions('traces', arguments[1], ['species', 'standard', 'phi', 'energy', 'levels', 'labels', 'shifts']);
+  if (!Array.isArray(levels)) throw new DeviceError("traces: levels must be a list, [{ half }, …], of the half-reactions whose levels to draw");
   const names = Object.keys(sol.V);
   const role = (name) => speciesRole(sol, name).role;
   const slotOf = (name) => speciesRole(sol, name).slot;

package/src/types.js

@@ -218,7 +218,8 @@
  * @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 {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} plates the charge on a gate or
+ *   Stern plate at a capacitive contact
  * @property {{ name: string, V: number, flux: Record<string, number>, current: number, x?: Float64Array,
  *   area?: Float64Array, rates?: Float64Array[], coverage?: Record<string, Float64Array>, bare?: Float64Array,
  *   sigma?: Float64Array, charge?: number }[]} ports what each internal port brings into the device;
@@ -248,6 +249,7 @@
  * @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)
+ * @property {string[]} warnings the steady state's warnings, which hold for its impedance too
  */
 
 /** @typedef {{ re: Float64Array, im: Float64Array }} ComplexProfile */

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

@@ -21,7 +21,7 @@ export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): n
  * port along a region: links that are their linear conductances, G = g × area per volume, gated the
  * same, each ion's reversal potential following from the port's bath and the concentrations inside
  * (so `inside`, `outside` and `at` aren't needed).
- * @param {{ inside: object, outside: object, T?: number, g?: { Na?: number, K?: number, leak?: number },
+ * @param {{ inside: object, outside: object, T: number, g?: { Na?: number, K?: number, leak?: number },
  *   leak?: string, leakZ?: number, at?: number, names?: { Na?: string, K?: string }, linear?: boolean, area?: number }} opts concentrations in
  *   mol/m³ by species name, K, S/m², V
  * @returns {{ gates: object, species: object }}
@@ -29,7 +29,7 @@ export function ghkCurrent(z: any, inside: any, outside: any, V: any, T: any): n
 export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names, linear, area }?: {
     inside: object;
     outside: object;
-    T?: number;
+    T: number;
     g?: {
         Na?: number;
         K?: number;
@@ -44,7 +44,7 @@ export function hodgkinHuxley({ inside, outside, T, g, leak, leakZ, at, names, l
     };
     linear?: boolean;
     area?: number;
-}): {
+}, ...args: any[]): {
     gates: object;
     species: object;
 };

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,15 +31,16 @@
  *   (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;
+}, ...args: any[]): {
     ok: boolean;
     items: CheckItem[];
     text: string;

package/types/data.d.ts

@@ -9,7 +9,7 @@
 export function aqueous(names: string[], { epsr, material }?: {
     epsr?: number;
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };
@@ -24,7 +24,7 @@ export function aqueous(names: string[], { epsr, material }?: {
  */
 export function semiconductor(name: string, { material }?: {
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };
@@ -36,7 +36,7 @@ export function semiconductor(name: string, { material }?: {
  */
 export function metal(name: string, { material }?: {
     material?: string;
-}): {
+}, ...args: any[]): {
     species: object[];
     materials: Record<string, object>;
 };

package/types/devices.d.ts

@@ -19,7 +19,7 @@ export function perovskiteCell({ V, light, bulkSRH }?: {
     };
     light?: number;
     bulkSRH?: boolean;
-}): import("./types.js").DeviceDefinition;
+}, ...args: any[]): import("./types.js").DeviceDefinition;
 /**
  * A J–V loop's figures of merit, from a transient's trace (`{ t, voltage, current }`, as a
  * recorder or advance() gives it): the loop splits at time `turn` into the sweep before (`rev`)

package/types/equation.d.ts

@@ -78,7 +78,7 @@ export function level(sol: {
     fixed?: Record<string, number>;
 }, { standard }?: {
     standard?: boolean;
-}): Float64Array;
+}, ...args: any[]): Float64Array;
 /**
  * The standard hydrogen electrode, 2 H⁺ + 2 e⁻ ⇌ H₂, with μ(H₂) = 0 (the element in its standard
  * state, on the usual table convention). Needs `H+` among the species.

package/types/errors.d.ts

@@ -1,3 +1,11 @@
+/**
+ * A function's options: a name it doesn't take (a typo) is an error, not silently ignored.
+ * @param {string} where the function, for the message
+ * @param {unknown} opts
+ * @param {string[]} allowed
+ * @param {new (message: string) => Error} [Kind]
+ */
+export function checkOptions(where: string, opts: unknown, allowed: string[], Kind?: new (message: string) => Error): void;
 export class DeviceError extends Error {
     constructor(message: any);
 }

package/types/index.d.ts

@@ -1,5 +1,5 @@
+export { DeviceError } from "./device.js";
 export { SolverError } from "./solver.js";
-export { BlockTridiagonal } from "./blockTridiagonal.js";
 export * from "./constants.js";
 /** @typedef {import('./types.js').DeviceDefinition} DeviceDefinition */
 /** @typedef {import('./types.js').Solution} Solution */
@@ -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).
@@ -72,7 +72,7 @@ export class Device {
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its
      * held voltage is perturbed (or its driven current), the others keep their drives.
-     * Z = δV/δI with I into the device (Ω·m²).
+     * Z = δV/δI with I into the device (Ω·m²), with the steady state's `warnings`.
      * @param {ArrayLike<number>} frequencies Hz
      * @param {{ terminal?: string, profiles?: boolean }} [opts] the terminal (default 'right'), and
      *   whether to return complex profiles per frequency
@@ -110,6 +110,3 @@ export class Device {
 }
 export type DeviceDefinition = import("./types.js").DeviceDefinition;
 export type Solution = import("./types.js").Solution;
-export { DeviceError, normalizeDevice } from "./device.js";
-export { buildGrid, gradedCells } from "./grid.js";
-export { bernoulli, bernoulliDerivative } from "./bernoulli.js";

package/types/junction.d.ts

@@ -12,7 +12,7 @@ export function henderson(left: Record<string, number>, right: Record<string, nu
     D: number;
 }>, { T }?: {
     T?: number;
-}): number;
+}, ...args: any[]): number;
 /**
  * Planck's liquid-junction potential, φ_R − φ_L (V): the steady state of constrained diffusion,
  * a junction zone held between the two solutions, electroneutral, carrying no current. Solved by
@@ -29,4 +29,4 @@ export function planck(left: Record<string, number>, right: Record<string, numbe
 }>, { T, steps }?: {
     T?: number;
     steps?: number;
-}): number;
+}, ...args: any[]): number;

package/types/kit.d.ts

@@ -59,7 +59,7 @@ export type VacuumSide = {
     offset: number;
 };
 export { build, combine, layer, ohmic, bath } from "./stack.js";
-export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
+export { half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { hodgkinHuxley, ghkCurrent } from "./channels.js";

package/types/live.d.ts

@@ -28,7 +28,7 @@ export function live(def: object, { worker, onsolution, maxRamp }?: {
     worker?: boolean | (() => any);
     onsolution?: (solution: object, info: object) => void;
     maxRamp?: number;
-}): Live;
+}, ...args: any[]): Live;
 /**
  * What a live device does with each change, on whichever thread solves it: apply, solve warm,
  * ramp from the last good state if that fails, and fall back to the last good solution.

package/types/particles.d.ts

@@ -20,7 +20,7 @@ export function particles(sol: object, { species, dots, weight, cap, cells, rand
     cap?: number;
     cells?: number;
     random?: () => number;
-}): {
+}, ...args: any[]): {
     cells: any[];
     species: any;
     weight: {};

package/types/plot.d.ts

@@ -7,7 +7,7 @@
  */
 export function themeColor(role: "electron" | "cation" | "anion" | "redox", slot: number, { dark }?: {
     dark?: boolean;
-}): string;
+}, ...args: any[]): string;
 /**
  * A label split into plain and subscript runs. Labels mark subscripts TeX-style: `V_{e⁻}`, or
  * `C_ox` for a run of letters, digits and charge signs. Everything else is literal.
@@ -34,7 +34,7 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
     xlim?: [number, number];
     title?: string;
     ytick?: (v: number) => string;
-}): string;
+}, ...args: any[]): string;
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
  * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
@@ -43,7 +43,7 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}
  */
-export function bandDiagram(sol: import("./types.js").Solution, opts?: Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]): string;
+export function bandDiagram(sol: import("./types.js").Solution, opts?: Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1], ...args: any[]): string;
 export const THEME: Readonly<{
     light: {
         electron: string[];

package/types/polarization.d.ts

@@ -24,7 +24,7 @@ export function polarization(device: import("./index.js").Device, sol: object, w
     x?: number;
 }, V: number | ArrayLike<number>, opts?: {
     surface?: "held" | "equilibrium";
-}): {
+}, ...args: any[]): {
     V: Float64Array;
     current: Float64Array;
     bare?: Float64Array;

package/types/recorder.d.ts

@@ -19,7 +19,7 @@ export function recorder(device: import("./index.js").Device, opts?: {
         species?: string;
         gate?: string;
     })[];
-}): {
+}, ...args: any[]): {
     advance: (tEnd: number, aopts?: object) => import("./types.js").Solution;
     frame: (t: number) => import("./types.js").Solution;
     frames: import("./types.js").Solution[];

package/types/solver.d.ts

@@ -143,6 +143,7 @@ export class Solver {
     _feeds(k: any, st: any): any;
     _laws(): void;
     constraints: any[];
+    affinities: any[];
     localConstraints: any[];
     islands: any[];
     pinnedIslands: any[];
@@ -157,7 +158,7 @@ export class Solver {
     _rowInto(o: any, add: any): void;
     linRow: Float64Array<any>;
     _applyLocalConstraints(): void;
-    _conservedMoieties(drives?: boolean, alsoCurrent?: any[]): Float64Array<any>[];
+    _conservedMoieties(drives?: boolean, alsoCurrent?: any[], skip?: any): Float64Array<any>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
     _lawAmount(cs: any): {
@@ -178,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;
@@ -256,6 +260,7 @@ export class Solver {
     };
     _snapFlat(): void;
     _flatRows(): void;
+    _applyAffinities(): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
     _assembleDifference(dt: any): {
@@ -312,6 +317,7 @@ export class Solver {
     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
@@ -374,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

package/types/sources.d.ts

@@ -13,7 +13,7 @@ export function pulse({ start, width, amplitude, rise, base }?: {
     amplitude: number;
     rise?: number;
     base?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
 };
@@ -27,7 +27,7 @@ export function square({ high, low, period, duty }?: {
     low: number;
     period: number;
     duty?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
     repeat: true;
@@ -42,7 +42,7 @@ export function triangle({ from, to, period }?: {
     from: number;
     to: number;
     period: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
     repeat: true;
@@ -57,7 +57,7 @@ export function ramp({ from, to, duration, start }?: {
     to: number;
     duration: number;
     start?: number;
-}): {
+}, ...args: any[]): {
     t: number[];
     values: number[];
 };
@@ -84,7 +84,7 @@ export function injector({ name, region, from, to, species, I, headroom }?: {
         repeat?: boolean;
     };
     headroom?: number;
-}): object;
+}, ...args: any[]): 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
@@ -96,7 +96,7 @@ export function recombination({ material, tau, majority }?: {
     material: string;
     tau: number;
     majority: number;
-}): {
+}, ...args: any[]): {
     equation: string;
     kf: Record<string, number>;
 };
@@ -122,7 +122,7 @@ export function photogeneration({ material, flux, alpha, mu, from, to, makes }?:
     from?: number;
     to: number;
     makes?: string;
-}): {
+}, ...args: any[]): {
     equation: string;
     fixed: Record<string, number>;
     kf: Record<string, {

package/types/traces.d.ts

@@ -70,7 +70,7 @@ export function traces(sol: import("./types.js").Solution, { species, standard,
     }[];
     labels?: Record<string, string>;
     shifts?: Record<string, number>;
-}): {
+}, ...args: any[]): {
     x: Float64Array;
     series: Trace[];
     regions: {

package/types/types.d.ts

@@ -551,7 +551,11 @@ export type Solution = {
         left: ContactResult;
         right: ContactResult;
     };
-    gates: {
+    /**
+     * the charge on a gate or
+     * Stern plate at a capacitive contact
+     */
+    plates: {
         left?: {
             V: number;
             D: number;
@@ -665,6 +669,10 @@ export type ImpedanceResult = {
         mu: Record<string, ComplexProfile>;
         c: Record<string, ComplexProfile>;
     }[];
+    /**
+     * the steady state's warnings, which hold for its impedance too
+     */
+    warnings: string[];
 };
 export type ComplexProfile = {
     re: Float64Array;