driftlet 0.1.0

package/types/solver.d.ts

@@ -0,0 +1,342 @@
+export class SolverError extends Error {
+    constructor(message: any, details: any);
+    details: any;
+}
+export class Solver {
+    constructor(model: any);
+    model: any;
+    n: any;
+    M: any;
+    nRx: any;
+    nNodes: any;
+    nFaces: number;
+    nB: any;
+    VT: number;
+    blockOfNode: Int32Array<any>;
+    blockOfFace: Int32Array<ArrayBuffer>;
+    present: Uint8Array<ArrayBuffer>;
+    cRef: Float64Array<ArrayBuffer>;
+    mu0hat: Float64Array<ArrayBuffer>;
+    rhoFixed: Float64Array<any>;
+    nodeMaterial: Int32Array<any>;
+    z: Int32Array<ArrayBuffer>;
+    phiUndefined: Uint8Array<any>;
+    u: Float64Array<ArrayBuffer>;
+    uLo: Float64Array<ArrayBuffer>;
+    uPrev: Float64Array<ArrayBuffer>;
+    uPrevLo: Float64Array<ArrayBuffer>;
+    c: Float64Array<ArrayBuffer>;
+    cOld: Float64Array<ArrayBuffer>;
+    nodeIdeal: Uint8Array<any>;
+    background: Float64Array<any>;
+    anyNonIdeal: boolean;
+    nodeConductor: Int32Array<any>;
+    sheetFace: Int32Array<any>;
+    sheetSign: Int8Array<any>;
+    conductorLast: Uint8Array<any>;
+    K: Float64Array<ArrayBuffer>;
+    ex: Float64Array<ArrayBuffer>;
+    zeta: Float64Array<any>;
+    scratch: Map<any, any>;
+    dA: Float64Array<any>;
+    dB: Float64Array<any>;
+    jL: Float64Array<any>;
+    jR: Float64Array<any>;
+    time: number;
+    lastDt: number;
+    contactFlux: {
+        left: Float64Array<any>;
+        right: Float64Array<any>;
+    };
+    portFlux: any;
+    contactD: {
+        left: number;
+        right: number;
+    };
+    contactDOld: {
+        left: number;
+        right: number;
+    };
+    contactDStart: {
+        left: number;
+        right: number;
+    };
+    terms: any;
+    termV: Float64Array<any>;
+    termVPrev: Float64Array<any>;
+    termI: Float64Array<any>;
+    sourceTime: number;
+    sourceOverride: Map<any, any>;
+    steady: boolean;
+    floating: any;
+    termB: any;
+    termC: any;
+    termDI: Float64Array<any>;
+    termRes: Float64Array<any>;
+    history: any[];
+    dtNext: any;
+    rxs: any;
+    strictlyNeutral: any;
+    generationScale: number;
+    hasGeneration: any;
+    rxsIn: any;
+    chargeNode: Uint8Array<any>;
+    chargeNodes: Int32Array<ArrayBuffer>;
+    combining: boolean;
+    bookkeeping: any;
+    bookkeepingFaces: number[];
+    referenceAmounts: number[];
+    boundaryIntake: Float64Array<ArrayBuffer>;
+    _activeSlots(): void;
+    active: Uint8Array<ArrayBuffer>;
+    loc: Int32Array<ArrayBuffer>;
+    sys: BlockTridiagonal;
+    SINK: number;
+    rix: Int32Array<ArrayBuffer>;
+    fullOf: Int32Array<ArrayBuffer>;
+    res: Float64Array<ArrayBuffer>;
+    delta: Float64Array<ArrayBuffer>;
+    _factor(): void;
+    _solveLinear(rhs: any, delta: any): void;
+    _findStretches(): void;
+    stretches: any[];
+    stretchOf: Int32Array<ArrayBuffer>;
+    moieties: Float64Array<ArrayBuffer>[];
+    constraints: any[];
+    constrained: boolean;
+    _conservedMoieties(): Float64Array<ArrayBuffer>[];
+    _directSteady(): boolean;
+    _applyConstraints(): void;
+    _solveBordered(rhs: any, delta: any, deltaV: any, pins: any): void;
+    dWork: Float64Array<ArrayBuffer>;
+    borderCols: any[];
+    /** Total amount (mol per unit area) of a stretch's species in the current state. */
+    amount(stretch: any): number;
+    redrive(): void;
+    deltaV: Float64Array<any>;
+    _refreshSources(): void;
+    /** η_i (μ̄/RT) of a port's outside level for species i. */
+    portEta(port: any, i: any): number;
+    /** η_i/RT that a fixed contact link imposes (or NaN if the link isn't fixed). */
+    contactEta(side: any, i: any): number;
+    /**
+     * Cold start. Species connected to a contact take that contact's level; spectators take
+     * their region's c0 (which fixes their conserved amount). φ in each region is then chosen
+     * for local neutrality, or continued across the interface dipole if nothing there responds.
+     */
+    initFromComposition(): void;
+    _materialAt(mat: any, background: any, eta: any, mode: any, cFix: any, ph: any, zeta: any, cc: any): void;
+    computeConcentrations(): void;
+    _work(md: any): any;
+    _nodeStatistics(g: any, b: any, phiHat: any): void;
+    _Kz(g: any, i: any): number;
+    /** zᵀKz at node g (per RT): the charge response that sets the screening length. */
+    screening(g: any): number;
+    _dlnc(g: any, i: any, w: any, d: any): void;
+    _j(rb: any, rs: any, cb: any, cs: any, v: any): void;
+    /** Assemble residual and Jacobian for a backward-Euler step of size dt. */
+    assemble(dt: any): void;
+    transformed: boolean;
+    _nodeConductor(g: any, dt: any): void;
+    _nodesDilute(g0: any, g1: any, dt: any): void;
+    _nodeConcentrated(g: any, dt: any): void;
+    _storage(g: any, i: any, dt: any, Kz?: number): void;
+    _chargeRows(dt: any): void;
+    _untransform(delta: any): void;
+    _bulkReactions(g: any, rxs: any): void;
+    _segmentDisplacement(s: any, bL: any, bR: any, mat: any, h: any): void;
+    _segmentsDilute(g0: any, g1: any, region: any, mat: any, vel: any): void;
+    _face(f: any): void;
+    _segmentConcentrated(s: any, bL: any, bR: any, mat: any, h: any, vel: any): void;
+    _segmentConductor(s: any, bL: any, bR: any, mat: any, h: any): void;
+    _segmentMixing(s: any, bL: any, bR: any, Dm: any, h: any, mat: any): void;
+    mixWork: Float64Array<any>[];
+    _dc(g: any, k: any, d: any): void;
+    _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any): void;
+    _terminals(dt: any): void;
+    _circuit(k: any): void;
+    _captureRow(b: any, s: any, w: any, into: any): number;
+    _port(port: any, flux: any, k: any): void;
+    _contact(side: any, dt: any): void;
+    _replaceRow(b: any, rs: any): void;
+    _equilibrate(): void;
+    _maxPotentialStep(delta: any, deltaV?: Float64Array<any>): number;
+    /**
+     * Newton iteration for one backward-Euler step from the current cOld.
+     * @returns {{converged: boolean, iterations: number, history: number[]}}
+     */
+    newton(dt: any, { maxIter, tol, maxStep }?: {
+        maxIter?: number;
+        tol?: number;
+        maxStep?: number;
+    }): {
+        converged: boolean;
+        iterations: number;
+        history: number[];
+    };
+    _noteConditioning(): void;
+    conditioning: {
+        digits: number;
+        x: number;
+        where: string;
+    };
+    /**
+     * Advance by dt, splitting the interval into halves (recursively) wherever Newton fails.
+     * The end time is always t + dt; the result reports the substeps taken.
+     */
+    advance(dt: any, opts: any, depth?: number): any;
+    _addToState(d: any, scale: any): void;
+    /**
+     * One time step of size dt. Backward Euler by default; with `method: 'bdf2'`, variable-step
+     * BDF2 once a previous step exists (and the step ratio is at most 2, for stability). On
+     * failure the state is restored.
+     *
+     * BDF2's storage term (a0 c − (1+ω) c_n + ω²/(1+ω) c_{n−1})/dt is written in backward-Euler
+     * form (c − c*)/(dt/a0), so assembly is shared: c* and the displacement histories replace
+     * the start-of-step values, and dt/a0 replaces dt.
+     */
+    step(dt: any, opts?: {}): {
+        converged: boolean;
+        iterations: number;
+        history: number[];
+    };
+    contactDEnd: any;
+    sourceBefore: 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
+     * `tol` thermal units per step in every potential (φ̂, each η, a floating terminal). The first
+     * step is checked by step doubling. Stops early when `budgetMs` of wall time is used, so an
+     * animation can call it once per frame; the step size carries over between calls.
+     */
+    integrate(tEnd: any, opts?: {}): {
+        converged: boolean;
+        done: boolean;
+        steps: number;
+        rejected: number;
+        iterations: number;
+        trace: {
+            t: any[];
+            current: any[];
+            voltage: any[];
+        };
+    };
+    landing: any;
+    _extrapolate(out: any, t: any): any;
+    _predict(pred: any, bdf: any): {
+        scale: number;
+        order: number;
+    };
+    _errorNorm(ref: any): number;
+    _snapshot(): {
+        u: Float64Array<ArrayBuffer>;
+        uLo: Float64Array<ArrayBuffer>;
+        cOld: Float64Array<ArrayBuffer>;
+        time: number;
+        lastDt: number;
+        contactDStart: {
+            left: number;
+            right: number;
+        };
+        contactDOld: {
+            left: number;
+            right: number;
+        };
+        contactDEnd: any;
+        boundaryIntake: Float64Array<ArrayBuffer>;
+        history: any[];
+        termV: Float64Array<ArrayBuffer>;
+        sourceTime: number;
+    };
+    _restore(s: any): void;
+    _terminalCurrent(): number;
+    /**
+     * Small-signal impedance about the current (steady) state, seen at one terminal. Linearising
+     * gives (J + iωM)·δx + Σ B_k δV_k = rhs for the grid's rows, and (C_k + iωC′_k)·δx +
+     * (∂I_k/∂V_k)·δV_k = δI_set,k for each floating terminal's circuit row, with J the steady
+     * Jacobian and M the storage part (from J(dt) = J + M/dt), B_k = ∂res/∂V_k and C_k = ∂I_k/∂x.
+     * At the measured terminal, a held voltage is perturbed (rhs = −B δV) and its current read
+     * from C, or a driven current is perturbed and its voltage solved for. The other terminals
+     * keep their drives: held ones at AC ground, driven ones at AC open circuit.
+     * Z = δV/δI with I into the device (positive real part for a passive device).
+     * @param {ArrayLike<number>} frequencies Hz
+     */
+    impedance(frequencies: ArrayLike<number>, { profiles, terminal }?: {
+        profiles?: boolean;
+        terminal?: string;
+    }): {
+        f: Float64Array<ArrayBuffer>;
+        Z: {
+            re: Float64Array<ArrayBuffer>;
+            im: Float64Array<ArrayBuffer>;
+        };
+    };
+    _smallSignalProfiles(xr: any, xi: any): {
+        phi: {
+            re: Float64Array<any>;
+            im: Float64Array<any>;
+        };
+        mu: {};
+        c: {};
+    };
+    _assembleBookkeeping(dt: any): void;
+    _accumulateBoundaryIntake(dt: any, cN: any): void;
+    slowestTime(): 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.
+     * The clock is not advanced, and open-system conservation bookkeeping restarts here.
+     */
+    solveSteady(opts?: {}): any;
+    solvedV: any;
+    _generationContinuation(opts: any, r: any): {
+        converged: boolean;
+        steps: any;
+        iterations: any;
+        history: any;
+    };
+    _continuation(opts: any, level: any, target: any, r: any, warm: 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;
+    }): {
+        converged: boolean;
+        steps: number;
+        iterations: number;
+        history: ({
+            dt: number;
+            converged: boolean;
+            iterations: number;
+            maxStep?: undefined;
+        } | {
+            dt: number;
+            converged: boolean;
+            iterations: number;
+            maxStep: number;
+        })[];
+    };
+    _renormalizeSpectators(): void;
+    _diff(): Float64Array<ArrayBuffer>;
+}
+import { BlockTridiagonal } from './blockTridiagonal.js';

package/types/stack.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pieces of a definition (species and materials, as in a library entry) merged into one. A
+ * species or material given twice must be given identically.
+ * @param {...{ species?: object[], materials?: Record<string, object> }} parts
+ * @returns {{ species: object[], materials: Record<string, object> }}
+ */
+export function combine(...parts: {
+    species?: object[];
+    materials?: Record<string, object>;
+}[]): {
+    species: object[];
+    materials: Record<string, object>;
+};
+/**
+ * A layer of the stack: a region of `material`, `length` m long, with any other region fields
+ * (name, c0, grid, …) and the kit's doping shorthand `donors`, `acceptors` (mol/m³).
+ * @param {string} material
+ * @param {number} length m
+ * @param {object} [more]
+ */
+export function layer(material: string, length: number, more?: object): any;
+/**
+ * An ohmic contact: each carrier in equilibrium with a metal at the terminal voltage, the
+ * first being the terminal species, and every other sharing its voltage (offset 0, as holes and
+ * electrons do at a metal). The default, both e⁻ and h⁺, gives n·p = n_i² at the contact
+ * (infinite recombination); one carrier alone is a selective contact, and `['e-']` is a
+ * current collector on a metal region.
+ * @param {number | object} [drive] a voltage, a waveform, or { V }, { I }, { V, R }
+ * @param {string[]} [carriers] default ['e-', 'h+']
+ */
+export function ohmic(d?: number, carriers?: string[]): any;
+/**
+ * A bath: a neutral composition `c` (mol/m³) held at the contact, its levels referred to the
+ * charged `reference` species (the ion a reference electrode would sense, e.g. Cl⁻ for
+ * Ag/AgCl), which is the terminal.
+ * @param {Record<string, number>} c
+ * @param {string} reference
+ * @param {number | object} [drive]
+ * @param {{ offset?: number }} [opts] where the reference species sits relative to the terminal
+ *   voltage, V_ref = V + offset (V)
+ */
+export function bath(c: Record<string, number>, reference: string, d?: number, { offset }?: {
+    offset?: number;
+}): any;
+/**
+ * Build a plain device definition from a stack:
+ *
+ *     build({ library: [Si], stack: [ohmic(0), layer('Si', 1e-6, { donors }), layer(...), ohmic(0.5)] })
+ *
+ * - `stack`: a contact, then layers (regions: objects with a `material`) and faces (anything
+ *   else: an interface's fields) left to right, then a contact. Two adjacent layers with no face
+ *   between them get the default face. Nested lists are flattened.
+ * - Layers may give doping as `donors` and `acceptors` (mol/m³) in place of `fixedCharge`.
+ * - `library`: pieces with species and materials, merged with `species` and `materials`.
+ * - `T`, `grid`, `ports` pass through.
+ * @param {object} def
+ * @returns {object} a device definition for `new Device`
+ */
+export function build(def: object): object;

package/types/statistics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Validate a material's `statistics` list and build its models.
+ * @returns {{ models: object[], modelOf: Int32Array, warnings: string[], phiFree: boolean }}
+ */
+export function normalizeStatistics(mat: any, path: any, species: any, speciesIndex: any, RT: any, h: any): {
+    models: object[];
+    modelOf: Int32Array;
+    warnings: string[];
+    phiFree: boolean;
+};

package/types/traces.d.ts

@@ -0,0 +1,118 @@
+/**
+ * One line of a level diagram.
+ * @typedef {object} Trace
+ * @property {string} id e.g. 'V:e-', 'Vstd:e-', 'phi', 'level:0'
+ * @property {string} label e.g. 'V_{e⁻}', 'V°_{SO₄²⁻}' (subscripts marked TeX-style, as `labelParts()` in driftlet/plot reads them)
+ * @property {'level' | 'standard' | 'phi' | 'redox' | 'redox-standard'} kind a species voltage, its
+ *   standard level, φ, or a half-reaction's level or standard level
+ * @property {string} [species]
+ * @property {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role what it is, for its colour:
+ *   electrons, cations (holes too), anions, redox levels, φ
+ * @property {number} slot its colour within the role: a species' place among the solution's
+ *   species of that role, so a colour follows its species whichever lines are shown; a redox
+ *   level's place among the distinct half-reactions asked for (a couple's level and standard
+ *   level share one)
+ * @property {number} [shift] a display offset added to all of a species' lines, V
+ * @property {Float64Array} y V, NaN where undefined (a break in the line)
+ */
+/**
+ * A charged species' colour role and slot in level diagrams: electrons (`e-`), cations (holes
+ * too), or anions, and its place among the solution's species of that role.
+ * @param {import('./types.js').Solution} sol
+ * @param {string} name
+ * @returns {{ role: 'electron' | 'cation' | 'anion', slot: number }}
+ */
+export function speciesRole(sol: import("./types.js").Solution, name: string): {
+    role: "electron" | "cation" | "anion";
+    slot: number;
+};
+/**
+ * A species name typeset for labels, given its charge: the charge as a superscript and the counts
+ * in its formula as subscripts ('SO42-' with z = −2 is 'SO₄²⁻', 'Fe3+' with z = 3 is 'Fe³⁺').
+ * A name that doesn't end in its charge is returned as it is.
+ * @param {string} name
+ * @param {number} z
+ * @returns {string}
+ */
+export function typeset(name: string, z: number): string;
+/**
+ * The level diagram of a solution as traces: per charged species, its voltage V_i (`level`) and
+ * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
+ * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
+ * @param {import('./types.js').Solution} sol
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
+ *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
+ *   species to show (default: every charged one), whether to show standard levels (default true)
+ *   and φ (default false; or a list of regions, by name or material, to draw it in only, say an
+ *   insulator's), half-reaction levels, labels to use by trace id
+ *   ({ 'V:e-': 'Fermi level' }), and display offsets per species (V), which move all of a
+ *   species' lines together so that widely separated species can share one readable plot
+ * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
+ *   faces: number[], range: [number, number] }}
+ */
+export function traces(sol: import("./types.js").Solution, { species, standard, phi, levels, labels, shifts }?: {
+    species?: string[];
+    standard?: boolean;
+    phi?: boolean | string[];
+    levels?: {
+        half: {
+            equation: string;
+            fixed?: Record<string, number>;
+        };
+        label?: string;
+        standard?: boolean;
+    }[];
+    labels?: Record<string, string>;
+    shifts?: Record<string, number>;
+}): {
+    x: Float64Array;
+    series: Trace[];
+    regions: {
+        name: string;
+        material: string;
+        x0: number;
+        x1: number;
+    }[];
+    faces: number[];
+    range: [number, number];
+};
+/**
+ * One line of a level diagram.
+ */
+export type Trace = {
+    /**
+     * e.g. 'V:e-', 'Vstd:e-', 'phi', 'level:0'
+     */
+    id: string;
+    /**
+     * e.g. 'V_{e⁻}', 'V°_{SO₄²⁻}' (subscripts marked TeX-style, as `labelParts()` in driftlet/plot reads them)
+     */
+    label: string;
+    /**
+     * a species voltage, its
+     * standard level, φ, or a half-reaction's level or standard level
+     */
+    kind: "level" | "standard" | "phi" | "redox" | "redox-standard";
+    species?: string;
+    /**
+     * what it is, for its colour:
+     * electrons, cations (holes too), anions, redox levels, φ
+     */
+    role: "electron" | "cation" | "anion" | "redox" | "phi";
+    /**
+     * its colour within the role: a species' place among the solution's
+     * species of that role, so a colour follows its species whichever lines are shown; a redox
+     * level's place among the distinct half-reactions asked for (a couple's level and standard
+     * level share one)
+     */
+    slot: number;
+    /**
+     * a display offset added to all of a species' lines, V
+     */
+    shift?: number;
+    /**
+     * V, NaN where undefined (a break in the line)
+     */
+    y: Float64Array;
+};