driftlet 0.1.0

package/types/equation.d.ts

@@ -0,0 +1,102 @@
+/**
+ * One participant of an equation as written.
+ * @typedef {object} Term
+ * @property {string} name the participant as written (with any trailing parenthesis)
+ * @property {number} nu signed coefficient (< 0 on the left of the equation)
+ */
+/**
+ * Parse an equation into its terms, in order. The two sides are separated by `=` (or `⇌`, `<=>`,
+ * `->`, `→`), terms by ` + ` (spaces around the plus, which keeps it apart from charges), and a
+ * side with nothing on it is `0` or `∅`. A coefficient is an integer followed by a space
+ * (`2 e-`), so names may start with digits (`3He`).
+ * @param {string} text
+ * @param {string} [path] for error messages
+ * @returns {Term[]}
+ */
+export function parseEquation(text: string, path?: string): Term[];
+/**
+ * The signed stoichiometry `{ name: ν }` of a homogeneous reaction, as a bulk reaction's `nu`.
+ * A participant on both sides is an error: give the net reaction.
+ * @param {string} text
+ * @param {string} [path]
+ * @returns {Record<string, number>}
+ */
+export function stoichiometry(text: string, path?: string): Record<string, number>;
+/**
+ * Which side of a face each participant of an equation is on: the side whose material holds it
+ * (on a conductor's side, only its carrier). A species held on both sides is labelled with its
+ * side, 'Li+(left)', or its material, 'Li+(graphite)'. Participants in `fixed` (fixed-activity
+ * neutrals) go beside a conductor if there is one, else on the left (their side doesn't matter).
+ * @param {Term[]} terms
+ * @param {{ name: string, holds: (species: string) => boolean, conductor?: boolean }} left
+ * @param {{ name: string, holds: (species: string) => boolean, conductor?: boolean }} right
+ * @param {Record<string, number> | undefined} fixed
+ * @param {string} path
+ * @returns {{ left: Record<string, number>, right: Record<string, number> }}
+ */
+export function faceSides(terms: Term[], left: {
+    name: string;
+    holds: (species: string) => boolean;
+    conductor?: boolean;
+}, right: {
+    name: string;
+    holds: (species: string) => boolean;
+    conductor?: boolean;
+}, fixed: Record<string, number> | undefined, path: string): {
+    left: Record<string, number>;
+    right: Record<string, number>;
+};
+/**
+ * A half-reaction: an equation with electrons `e-` on one side, and the μ (J/mol) of any
+ * participant that isn't a species (a fixed-activity neutral, such as a solid metal). It's plain
+ * data, `{ equation, fixed }`: spread it into a face reaction with its kinetics,
+ * `{ ...silver, k0: 1e-3 }`, or pass it to `level()`.
+ * @param {string} equation e.g. 'Ag+ + e- = Ag(s)'
+ * @param {Record<string, number>} [fixed] μ of the fixed participants, J/mol
+ * @returns {{ equation: string, fixed?: Record<string, number> }}
+ */
+export function half(equation: string, fixed?: Record<string, number>): {
+    equation: string;
+    fixed?: Record<string, number>;
+};
+/**
+ * The electronic level a half-reaction implies at each node, as an electron voltage
+ * V = −μ̄_e/F: where an electrode exchanging electrons by that reaction would sit in equilibrium
+ * with the local composition (the couple's redox level). With `standard: true`, every
+ * species is taken at its reference concentration (its standard level μ° + zFφ), so it's the
+ * standard level: for `SHE`, V°_e⁻(SHE) = φ + μ°_H⁺/F. `NaN` where a participant is absent.
+ * @param {{ mu: Record<string, ArrayLike<number>>, muStd: Record<string, ArrayLike<number>> }} sol a solution
+ * @param {{ equation: string, fixed?: Record<string, number> }} halfReaction from `half()`
+ * @param {{ standard?: boolean }} [opts]
+ * @returns {Float64Array}
+ */
+export function level(sol: {
+    mu: Record<string, ArrayLike<number>>;
+    muStd: Record<string, ArrayLike<number>>;
+}, halfReaction: {
+    equation: string;
+    fixed?: Record<string, number>;
+}, { standard }?: {
+    standard?: boolean;
+}): 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.
+ */
+export const SHE: Readonly<{
+    equation: string;
+    fixed?: Record<string, number>;
+}>;
+/**
+ * One participant of an equation as written.
+ */
+export type Term = {
+    /**
+     * the participant as written (with any trailing parenthesis)
+     */
+    name: string;
+    /**
+     * signed coefficient (< 0 on the left of the equation)
+     */
+    nu: number;
+};

package/types/errors.d.ts

@@ -0,0 +1,3 @@
+export class DeviceError extends Error {
+    constructor(message: any);
+}

package/types/fermi.d.ts

@@ -0,0 +1,3 @@
+export function fermiHalf(x: any): any;
+export function fermiMinusHalf(x: any): any;
+export function fermiQuadrature(j: any, x: any): number;

package/types/grid.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cell widths for one region: fine at both ends, growing toward the middle.
+ * @param {number} length m
+ * @param {import('./types.js').GridOptions} [opts]
+ * @returns {number[]} widths summing to `length`
+ */
+export function gradedCells(length: number, { hmin, hmax, ratio, minCells, hLeft, hRight }?: import("./types.js").GridOptions): number[];
+/**
+ * Build the device grid.
+ * @param {{length: number, grid?: object, cells?: number[]}[]} regions in order, left to right
+ * @param {object} [opts] defaults for every region: { hmin, hmax, ratio, minCells }
+ */
+export function buildGrid(regions: {
+    length: number;
+    grid?: object;
+    cells?: number[];
+}[], opts?: object): {
+    nNodes: number;
+    x: Float64Array<ArrayBuffer>;
+    nodeRegion: Int32Array<ArrayBuffer>;
+    segLength: Float64Array<ArrayBuffer>;
+    segRegion: Int32Array<ArrayBuffer>;
+    segFace: Int32Array<ArrayBuffer>;
+    vol: Float64Array<ArrayBuffer>;
+    regionStart: Int32Array<ArrayBuffer>;
+    regionEnd: Int32Array<ArrayBuffer>;
+    length: number;
+};

package/types/index.d.ts

@@ -0,0 +1,103 @@
+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 */
+export class Device {
+    /** @param {DeviceDefinition} def plain, serialisable device definition (see docs/device.md) */
+    constructor(def: DeviceDefinition);
+    def: import("./types.js").DeviceDefinition;
+    model: any;
+    _solver: any;
+    /** The solver, built on first use (so construction only validates the definition). */
+    get solver(): any;
+    get grid(): any;
+    /**
+     * Change part of the definition (deep-merged). 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).
+     * @param {object} patch a partial device definition, merged into the current one
+     * @returns {this}
+     */
+    set(patch: object): this;
+    _redefineDrives(def: any): void;
+    /**
+     * Steady state (or equilibrium), warm-started from the current state. Doesn't advance time.
+     * @param {{ maxSteps?: number, tol?: number, continuation?: boolean }} [opts]
+     * @returns {Solution}
+     */
+    solve(opts?: {
+        maxSteps?: number;
+        tol?: number;
+        continuation?: boolean;
+    }): Solution;
+    /**
+     * Advance the transient by dt (s) with backward Euler. If Newton fails, the interval is
+     * split into smaller steps automatically; `substeps` in the result says how many.
+     * With `{ method: 'bdf2' }`, steps after the first use second-order BDF2.
+     * @param {number} dt s
+     * @param {{ method?: 'be' | 'bdf2' }} [opts]
+     * @returns {Solution}
+     */
+    step(dt: number, opts?: {
+        method?: "be" | "bdf2";
+    }): Solution;
+    /**
+     * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
+     * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
+     * which), so an animation can call it once per frame; the step size carries over.
+     * @param {number} tEnd s
+     * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+     * @returns {Solution}
+     */
+    advance(tEnd: number, opts?: {
+        tol?: number;
+        dt0?: number;
+        dtMax?: number;
+        budgetMs?: number;
+        maxSteps?: number;
+        method?: "bdf2" | "be";
+    }): Solution;
+    /**
+     * 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²).
+     * @param {ArrayLike<number>} frequencies Hz
+     * @param {{ terminal?: string, profiles?: boolean }} [opts] the terminal (default 'right'), and
+     *   whether to return complex profiles per frequency
+     * @returns {import('./types.js').ImpedanceResult}
+     */
+    impedance(frequencies: ArrayLike<number>, opts?: {
+        terminal?: string;
+        profiles?: boolean;
+    }): import("./types.js").ImpedanceResult;
+    /**
+     * A checkpoint of the definition and solver state, for `_rollback()` (the live wrapper keeps
+     * its last good state this way).
+     * @internal
+     */
+    _checkpoint(): {
+        def: import("./types.js").DeviceDefinition;
+        model: any;
+        solver: any;
+        snap: any;
+        solvedV: any;
+        referenceAmounts: any;
+    };
+    /**
+     * Back to a checkpoint taken on this device.
+     * @param {ReturnType<Device['_checkpoint']>} cp
+     * @internal
+     */
+    _rollback(cp: ReturnType<Device["_checkpoint"]>): void;
+    /**
+     * Snapshot of the current state.
+     * @returns {Solution}
+     */
+    solution(): Solution;
+}
+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/kit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
+ * in electron energy, the vacuum level just outside lies (the offset, V). So
+ * V_vac = V_anchor − offset.
+ * @typedef {object} VacuumSide
+ * @property {string} material material name in the definition
+ * @property {string} anchor a charged species present there (its standard level
+ *   V°_i = φ + μ°_i/(z_i F): a band edge for e⁻ or h⁺), or 'phi' (the inner potential itself)
+ * @property {number} offset V: an electron affinity, ionisation energy, Trasatti's 4.44 V, …
+ */
+/**
+ * A material's vacuum level relative to its own φ, V_vac − φ, in volts.
+ * @param {object} def device definition (its `species` and `materials` are read)
+ * @param {VacuumSide} side
+ * @param {string} [path] for error messages
+ */
+export function vacuumLevel(def: object, side: VacuumSide, path?: string): number;
+/**
+ * The vacuum-level (Anderson-type) estimate of a face's alignment: the two sides' vacuum levels
+ * are taken to coincide. Returns the face's `dipole`, φ_R − φ_L in volts.
+ * @param {object} def device definition
+ * @param {VacuumSide} left
+ * @param {VacuumSide} right
+ */
+export function vacuumDipole(def: object, left: VacuumSide, right: VacuumSide): number;
+/**
+ * The vacuum-level (Schottky–Mott-type) estimate of a `zeroCharge` where a conductor meets a
+ * material: at a conductor region's face, or a contact's capacitive or dipole law. The conductor's
+ * vacuum level sits its work function W beyond its Fermi level, so
+ * zeroCharge = V_F − φ_edge at zero charge = W + (V_vac − φ)_inside.
+ * @param {object} def device definition
+ * @param {number} workFunction V
+ * @param {VacuumSide} inside the material across the face
+ */
+export function vacuumZeroCharge(def: object, workFunction: number, inside: VacuumSide): number;
+export { live } from "./live.js";
+/**
+ * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
+ * in electron energy, the vacuum level just outside lies (the offset, V). So
+ * V_vac = V_anchor − offset.
+ */
+export type VacuumSide = {
+    /**
+     * material name in the definition
+     */
+    material: string;
+    /**
+     * a charged species present there (its standard level
+     * V°_i = φ + μ°_i/(z_i F): a band edge for e⁻ or h⁺), or 'phi' (the inner potential itself)
+     */
+    anchor: string;
+    /**
+     * V: an electron affinity, ionisation energy, Trasatti's 4.44 V, …
+     */
+    offset: number;
+};
+export { build, combine, layer, ohmic, bath } from "./stack.js";
+export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
+export { traces, speciesRole, typeset } from "./traces.js";
+export { describe, unitWarnings } from "./describe.js";
+export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/live.d.ts

@@ -0,0 +1,101 @@
+export function between(a: any, b: any, s: any): any;
+/**
+ * A live device.
+ * @typedef {object} Live
+ * @property {(patch: object) => Promise<{ solution: object | null, info: object }>} set merge a change
+ *   (as Device.set()) and solve it, after the solve under way; changes made meanwhile are merged
+ *   and solved once, and all their promises resolve with that solution
+ * @property {Promise<{ solution: object | null, info: object }>} ready the first solve
+ * @property {object | null} solution the last good solution
+ * @property {() => void} close stop the worker, if any
+ */
+/**
+ * A device for live demos: `live.set(patch)` as often as a slider moves, and draw what comes
+ * back (or in `onsolution`). Solves run one at a time, each warm from the last, letting the page
+ * paint in between; changes made during a solve are merged and solved together.
+ *
+ * On failure, the solution is the last good one, with `info.failed` (and `info.error` for an
+ * invalid change, `info.warnings` for one that didn't converge). `info.ramp` says how many steps
+ * a ramp from the last good state took (0: none needed), and `info.ms` the time.
+ *
+ * With `worker: true`, solving happens in a Web Worker (module workers are needed, as in every
+ * current browser). A function returning a Worker-like object can be given instead.
+ * @param {object} def device definition
+ * @param {{ worker?: boolean | (() => any), onsolution?: (solution: object, info: object) => void, maxRamp?: number }} [opts]
+ * @returns {Live}
+ */
+export function live(def: object, { worker, onsolution, maxRamp }?: {
+    worker?: boolean | (() => any);
+    onsolution?: (solution: object, info: object) => void;
+    maxRamp?: number;
+}): 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.
+ */
+export class Session {
+    /** @param {object} def device definition */
+    constructor(def: object, { maxRamp }?: {
+        maxRamp?: number;
+    });
+    device: Device;
+    maxRamp: number;
+    good: {
+        cp: {
+            def: import("./types.js").DeviceDefinition;
+            model: any;
+            solver: any;
+            snap: any;
+            solvedV: any;
+            referenceAmounts: any;
+        };
+        sol: import("./types.js").Solution;
+    };
+    /**
+     * Apply changes in order, then solve once. Each change is applied on its own, so an invalid
+     * one is refused (its message in `errors`) without losing the others.
+     * @param {object[]} patches each merged into the definition, as by Device.set()
+     * @returns {{ solution: object | null, errors: (string | undefined)[], info: { ms: number, ramp: number, failed: boolean, error?: string, warnings?: string[] } }}
+     */
+    update(patches: object[]): {
+        solution: object | null;
+        errors: (string | undefined)[];
+        info: {
+            ms: number;
+            ramp: number;
+            failed: boolean;
+            error?: string;
+            warnings?: string[];
+        };
+    };
+}
+/**
+ * A live device.
+ */
+export type Live = {
+    /**
+     * merge a change
+     * (as Device.set()) and solve it, after the solve under way; changes made meanwhile are merged
+     * and solved once, and all their promises resolve with that solution
+     */
+    set: (patch: object) => Promise<{
+        solution: object | null;
+        info: object;
+    }>;
+    /**
+     * the first solve
+     */
+    ready: Promise<{
+        solution: object | null;
+        info: object;
+    }>;
+    /**
+     * the last good solution
+     */
+    solution: object | null;
+    /**
+     * stop the worker, if any
+     */
+    close: () => void;
+};
+import { Device } from './index.js';

package/types/merge.d.ts

@@ -0,0 +1 @@
+export function merge(base: any, patch: any): any;

package/types/plot.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The colour of a trace's role and slot (a CSS colour), for drawing other charts in the same
+ * colours as the level diagrams.
+ * @param {'electron' | 'cation' | 'anion' | 'redox'} role
+ * @param {number} slot
+ * @param {{ dark?: boolean }} [opts]
+ */
+export function themeColor(role: "electron" | "cation" | "anion" | "redox", slot: number, { dark }?: {
+    dark?: boolean;
+}): 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.
+ * @param {string} label
+ * @returns {{ text: string, sub: boolean }[]}
+ */
+export function labelParts(label: string): {
+    text: string;
+    sub: boolean;
+}[];
+/**
+ * Line chart of level-diagram traces as an SVG string.
+ * @param {ReturnType<typeof traces>} tr from `traces()`
+ * @param {{ width?: number, height?: number, ylabel?: string, range?: [number, number], xlim?: [number, number], title?: string, ytick?: (v: number) => string }} [opts]
+ *   `xlim` (m) zooms into part of the device; the range then fits what's shown. `ytick` writes
+ *   the y axis's tick labels, say as powers of ten for lines that are log₁₀ of something
+ * @returns {string}
+ */
+export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabel, range, xlim, title, ytick }?: {
+    width?: number;
+    height?: number;
+    ylabel?: string;
+    range?: [number, number];
+    xlim?: [number, number];
+    title?: string;
+    ytick?: (v: number) => string;
+}): string;
+/**
+ * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
+ * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * @param {import('./types.js').Solution} sol
+ * @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 const THEME: Readonly<{
+    light: {
+        electron: string[];
+        cation: string[];
+        anion: string[];
+        redox: string[];
+    };
+    dark: {
+        electron: string[];
+        cation: string[];
+        anion: string[];
+        redox: string[];
+    };
+}>;
+import { traces } from './traces.js';

package/types/solution.d.ts

@@ -0,0 +1,18 @@
+export function makeSolution(solver: any, result?: {}): {
+    x: Float64Array<ArrayBuffer>;
+    region: Int32Array<ArrayBuffer>;
+    species: any;
+    regions: any;
+    phi: Float64Array<any>;
+    c: {};
+    mu: {};
+    muStd: {};
+    V: {};
+    Vstd: {};
+    time: any;
+    converged: any;
+    iterations: any;
+    steps: any;
+    substeps: any;
+    history: any;
+};