driftlet 0.9.0 → 0.11.4

package/src/types.js

@@ -197,6 +197,10 @@
  */
 
 /**
+ * The device's totals through its cross-section (currents, fluxes through contacts and ports,
+ * charges, amounts, reaction totals, impedance) are per m² of a planar device, as below, and
+ * whole (A, mol/s, C, mol, Ω; per metre of a cylinder) for one with a `geometry`. Rates at a
+ * face or an electrode are always per m² of it.
  * @typedef {object} Solution
  * @property {Float64Array} x node positions, m (interface positions appear twice)
  * @property {Int32Array} region region index per node

package/types/blockTridiagonal.d.ts

@@ -31,11 +31,19 @@ export class BlockTridiagonal {
     minPivotRatio: number;
     /** The block found exactly singular by the last factor(), or −1. */
     singularBlock: number;
+    /**
+     * Static pivoting: an exactly zero pivot (all its candidates cancelled to nothing) is
+     * replaced by 1e-15 of its block's largest entry rather than thrown on, for a caller that
+     * refines its solves (and counted in `perturbedPivots`).
+     */
+    staticPivots: boolean;
+    /** How many pivots the last factor() replaced. */
+    perturbedPivots: number;
     /** Zero all of A, B, C (ready for fresh assembly). */
     clear(): void;
     /**
      * Factorise the current A, B, C. A, B, C are left untouched.
-     * Throws if a diagonal block is exactly singular.
+     * Throws if a diagonal block is exactly singular (unless `staticPivots`).
      */
     factor(): void;
     /**

package/types/checks.d.ts

@@ -13,9 +13,9 @@
  * - **warnings**: the solution's warnings (unresolved double layers, steep profiles, weakly held
  *   parts) and the definition's likely unit slips.
  * - **balance** (a steady state): each species' ledger, what comes in through each terminal and
- *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) and, for a charged
- *   species, as a current F·|z|·rate. The terms must sum to zero; under light it's J = F(G − R),
- *   and it says where every carrier went.
+ *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) (mol/s if the device
+ *   isn't planar) and, for a charged species, as a current F·|z|·rate. The terms must sum to
+ *   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

package/types/difference.d.ts

@@ -0,0 +1,30 @@
+export class DifferenceTerms {
+    constructor(N: any, nodes: any, segments: any);
+    N: any;
+    dead: Uint8Array<any>;
+    nI: Int32Array<any>;
+    nP: Int32Array<any>;
+    nZ: Float64Array<any>;
+    nMass: Float64Array<any>;
+    nCharge: Float64Array<any>;
+    sI: Int32Array<ArrayBuffer>;
+    sZ: Float64Array<any>;
+    sC: Float64Array<ArrayBuffer>;
+    dI: Int32Array<ArrayBuffer>;
+    dK: Float64Array<any>;
+    combos: any[];
+    t: Float64Array<any>;
+    x: Float64Array<any>;
+    reset(rate?: number): void;
+    rate: number;
+    nn: number;
+    ns: number;
+    nd: number;
+    node(i: any, p: any, z: any, mass: any, charge: any): void;
+    segment(iL: any, iR: any, pL: any, pR: any, z: any, a: any, b: any, d: any): void;
+    displacement(pL: any, pR: any, k: any): void;
+    kill(row: any): void;
+    combine(rk: any, ri: any, w: any): void;
+    capture(row: any, w: any, mass: any, into: any): void;
+    apply(v: any, out: any, steady?: number, mass?: number): any;
+}

package/types/index.d.ts

@@ -14,7 +14,8 @@ export class Device {
     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. A change to the terminals'
+     * `{ 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).
      * @param {object} patch a partial device definition, merged into the current one
@@ -93,6 +94,7 @@ export class Device {
         snap: any;
         solvedV: any;
         referenceAmounts: any;
+        surfaceRef: any;
     };
     /**
      * Back to a checkpoint taken on this device.

package/types/live.d.ts

@@ -48,6 +48,7 @@ export class Session {
             snap: any;
             solvedV: any;
             referenceAmounts: any;
+            surfaceRef: any;
         };
         sol: import("./types.js").Solution;
     };

package/types/polarization.d.ts

@@ -9,7 +9,10 @@
  * @param {{ face: number } | { port: string | number, x?: number }} where a face's index, or a port
  *   (name or index) and the position in its window (m, the device's x; default its first node)
  * @param {number | ArrayLike<number>} V the metal's level(s), V
- * @returns {{ V: Float64Array, current: Float64Array, reactions: { equation: string, level: number,
+ * @param {{ surface?: 'held' | 'equilibrium' }} [opts] an electrode port's surface coverages: held as
+ *   in `sol` (the default: this instant's curves), or in equilibrium at each V (the steady-state
+ *   curve, with a passive film's active–passive peak), each species by the reaction that makes it
+ * @returns {{ V: Float64Array, current: Float64Array, bare?: Float64Array, reactions: { equation: string, level: number,
  *   rate: Float64Array, current: Float64Array }[] }} per reaction: its equilibrium level here (where
  *   its rate is zero), its rate (mol/(m²·s) of electrode, forward) and its current (A/m², anodic
  *   positive: into the solution); and their sum
@@ -19,9 +22,12 @@ export function polarization(device: import("./index.js").Device, sol: object, w
 } | {
     port: string | number;
     x?: number;
-}, V: number | ArrayLike<number>): {
+}, V: number | ArrayLike<number>, opts?: {
+    surface?: "held" | "equilibrium";
+}): {
     V: Float64Array;
     current: Float64Array;
+    bare?: Float64Array;
     reactions: {
         equation: string;
         level: number;

package/types/solver.d.ts

@@ -17,6 +17,8 @@ export class Solver {
     blockOfFace: Int32Array<ArrayBuffer>;
     surfPort: Int32Array<any>;
     surfW: Int32Array<any>;
+    surfCols: any;
+    surfColOf: any;
     th: Float64Array<ArrayBuffer>;
     thOld: Float64Array<ArrayBuffer>;
     th0: Float64Array<any>;
@@ -52,6 +54,7 @@ export class Solver {
     time: number;
     lastDt: number;
     atSteady: boolean;
+    lin: DifferenceTerms;
     contactFlux: {
         left: Float64Array<any>;
         right: Float64Array<any>;
@@ -65,6 +68,9 @@ export class Solver {
     portQStart: Float64Array<any>;
     portQOld: Float64Array<any>;
     portQEnd: any;
+    qg: Float64Array<any>;
+    qgSlope: Float64Array<any>;
+    qgTerms: any[][];
     contactDOld: {
         left: number;
         right: number;
@@ -90,43 +96,63 @@ export class Solver {
     rxs: any;
     portArea: any;
     portRates: any;
-    strictlyNeutral: any;
     generationScale: number;
     hasGeneration: any;
     rxsIn: any;
+    closedEnd: {
+        left: any;
+        right: any;
+    };
     chargeNode: Uint8Array<any>;
     chargeNodes: Int32Array<ArrayBuffer>;
+    lateStorage: Uint8Array<any>;
     combining: boolean;
     bookkeeping: any;
     bookkeepingFaces: number[];
     referenceAmounts: number[];
+    surfaceRef: Float64Array<ArrayBuffer>;
     boundaryIntake: Float64Array<ArrayBuffer>;
     _activeSlots(): void;
     active: Uint8Array<ArrayBuffer>;
     loc: Int32Array<ArrayBuffer>;
-    sys: BlockTridiagonal;
+    sys: any;
     SINK: number;
     rix: Int32Array<ArrayBuffer>;
     fullOf: Int32Array<ArrayBuffer>;
     res: Float64Array<ArrayBuffer>;
     delta: Float64Array<ArrayBuffer>;
+    rowScale: Float64Array<ArrayBuffer>;
     _factor(): void;
     _solveLinear(rhs: any, delta: any): void;
     _findStretches(): void;
     stretches: any[];
     stretchOf: Int32Array<ArrayBuffer>;
-    moieties: Float64Array<ArrayBuffer>[];
+    moieties: Float64Array<any>[];
+    flatStretches: any[];
+    levelStretches: any[];
+    flattening: boolean;
     constraints: any[];
     localConstraints: any[];
+    islands: any[];
+    pinnedIslands: any[];
+    islandsOn: boolean;
+    pins: any[];
     constrained: boolean;
     _captureLocal(): void;
+    _applyIslands(): any[];
+    islandRow: Float64Array<any>;
+    _rowInto(o: any, add: any): void;
+    linRow: Float64Array<any>;
     _applyLocalConstraints(): void;
-    _conservedMoieties(): Float64Array<ArrayBuffer>[];
+    _conservedMoieties(): Float64Array<any>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
     _solveBordered(rhs: any, delta: any, deltaV: any, pins: any): void;
-    dWork: Float64Array<ArrayBuffer>;
+    dWork: Float64Array<any>;
     borderCols: any[];
+    _surfaceStart(g: any): void;
+    /** Amount (mol per unit area) of surface column j's species, Γ Σ v·a·θ, in the current state. */
+    surfaceAmount(j: any): number;
     /** Total amount (mol per unit area) of a stretch's species in the current state. */
     amount(stretch: any): number;
     redrive(): void;
@@ -155,7 +181,7 @@ export class Solver {
     _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;
+    transformed: any;
     _nodeConductor(g: any, dt: any): void;
     _nodesDilute(g0: any, g1: any, dt: any): void;
     _nodeConcentrated(g: any, dt: any): void;
@@ -183,31 +209,42 @@ export class Solver {
     _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any, Af: 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, dt: any): void;
+    _captureRow(b: any, s: any, w: any, into: any): any;
+    _port(port: any, flux: any, k: any, dt: any, holds: any): void;
     _portReaction(port: any, rx: any, area: any, rates: any, flux: any, k: any): void;
     _portCapacitance(port: any, k: any, dt: any): void;
     _surfaceStorage(port: any, dt: any): void;
     _contact(side: any, dt: any): void;
+    _flatRows(): void;
+    _levelRows(): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
+    _assembleDifference(dt: any): {
+        rest: any;
+        lin: DifferenceTerms;
+    };
+    sysRest: any;
+    diffTerms: DifferenceTerms;
+    _refine(dt: any, delta: any, deltaV: any): boolean;
     _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 }?: {
+    newton(dt: any, { maxIter, tol, maxStep, islands }?: {
         maxIter?: number;
         tol?: number;
         maxStep?: number;
+        islands?: boolean;
     }): {
         converged: boolean;
         iterations: number;
         history: number[];
     };
+    _kirchhoff(): number;
     _noteConditioning(): void;
     conditioning: {
-        digits: number;
+        digits: any;
         x: number;
         where: string;
     };
@@ -236,7 +273,7 @@ export class Solver {
     /**
      * 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
+     * `tol` thermal units per step in every potential (φ̂, each η, a surface's coverages as η). 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.
      */
@@ -316,6 +353,13 @@ export class Solver {
             im: Float64Array<ArrayBuffer>;
         };
     };
+    _regionShift(yr: any, yi: any): Float64Array<any>[];
+    _regionEdgeRows(): Uint8Array<any>;
+    _currentCuts(): {
+        idx: any[];
+        g: any[];
+        d: any[];
+    }[];
     _smallSignalProfiles(xr: any, xi: any): {
         phi: {
             re: Float64Array<any>;
@@ -339,7 +383,16 @@ export class Solver {
      * The clock is not advanced, and open-system conservation bookkeeping restarts here.
      */
     solveSteady(opts?: {}): any;
+    unreached: {
+        terminal: any;
+        target: any;
+        low: any;
+        high: any;
+    };
+    _solveSteadyAll(opts: any): any;
     _steadyFromHere(opts: any): any;
+    dimmer: boolean;
+    _floatingContinuation(opts: any, r: any): any;
     _generationContinuation(opts: any, r: any): {
         converged: boolean;
         steps: any;
@@ -385,4 +438,4 @@ export class Solver {
     _renormalizeSpectators(): void;
     _diff(): Float64Array<ArrayBuffer>;
 }
-import { BlockTridiagonal } from './blockTridiagonal.js';
+import { DifferenceTerms } from './difference.js';

package/types/types.d.ts

@@ -471,6 +471,12 @@ export type ContactResult = {
      */
     current: number;
 };
+/**
+ * The device's totals through its cross-section (currents, fluxes through contacts and ports,
+ * charges, amounts, reaction totals, impedance) are per m² of a planar device, as below, and
+ * whole (A, mol/s, C, mol, Ω; per metre of a cylinder) for one with a `geometry`. Rates at a
+ * face or an electrode are always per m² of it.
+ */
 export type Solution = {
     /**
      * node positions, m (interface positions appear twice)