driftlet 1.1.1 → 1.2.2

package/types/solver.d.ts

@@ -99,6 +99,7 @@ export class Solver {
     termB: any;
     termC: any;
     termDI: Float64Array<any>;
+    termDX: any;
     termRes: Float64Array<any>;
     history: any[];
     dtNext: any;
@@ -137,43 +138,93 @@ export class Solver {
     _findStretches(): void;
     stretches: any[];
     stretchOf: Int32Array<ArrayBuffer>;
+    rough: number[];
     moieties: Float64Array<any>[];
     flatStretches: any[];
     _roughAmount(st: any): number;
-    _moves(st: any): boolean;
-    _still(st: any): boolean;
-    _feeds(k: any, st: any): any;
     _laws(): void;
     constraints: any[];
-    affinities: any[];
-    localConstraints: any[];
-    islands: any[];
+    affinities: {
+        rx: any;
+        f: any;
+        row: any;
+        idx: Int32Array<any>;
+        w: Float64Array<any>;
+        len: number;
+        res: number;
+    }[];
+    localConstraints: {
+        parts: ({
+            i: any;
+            w: number;
+            q?: undefined;
+            k?: undefined;
+        } | {
+            q: any;
+            k: any;
+            w: number;
+            i?: undefined;
+        })[];
+        row: any;
+        nodes: any;
+        reference: Float64Array<any>;
+    }[];
+    islands: {
+        stretch: any;
+        row: any;
+        flux: any[];
+        weight: number[];
+        outside: any[];
+        idx: Int32Array<ArrayBuffer>;
+        w: Float64Array<ArrayBuffer>;
+        len: number;
+        res: number;
+    }[];
+    timeLaws: {
+        parts: {
+            stretch: number;
+            w: number;
+        }[];
+        surface: {
+            col: number;
+            w: number;
+        }[];
+        carriers: any;
+        terminals: any[];
+        circuit: any;
+        lambda: number;
+        idx: Int32Array<ArrayBuffer>;
+        w: Float64Array<ArrayBuffer>;
+        len: number;
+    }[];
+    contactLaw: boolean[];
+    carriers: any;
+    unkept: Float64Array<any>[];
+    contactQ: any[];
     pinnedIslands: any[];
     islandsOn: boolean;
     pins: any[];
-    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(drives?: boolean, alsoCurrent?: any[], skip?: any): Float64Array<any>[];
-    _directSteady(): boolean;
-    _applyConstraints(): void;
-    _lawAmount(cs: any): {
-        amount: number;
-        reference: number;
-        dV: number;
-        gross: number;
+    _structure(): {
+        model: any;
+        n: any;
+        M: any;
+        z: Int32Array<ArrayBuffer>;
+        nNodes: any;
+        stretches: any[];
+        stretchOf: Int32Array<ArrayBuffer>;
+        flatStretches: any[];
+        rough: number[];
+        surfCols: any;
+        surfColOf: any;
+        terms: any;
+        floating: any;
+        blockOfNode: Int32Array<any>;
+        blockOfFace: Int32Array<ArrayBuffer>;
+        rxsIn: any;
+        nodeMaterial: Int32Array<any>;
+        phiUndefined: Uint8Array<any>;
     };
-    _lawStart(cs: any): number;
-    _circuitLaws(dt: any): void;
-    _solveBordered(rhs: any, delta: any, deltaV: any, pins: any): void;
-    dWork: Float64Array<any>;
-    borderCols: any[];
+    _directSteady(): boolean;
     _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;
@@ -183,7 +234,6 @@ export class Solver {
     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;
@@ -266,14 +316,6 @@ 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;
-    _applyAffinities(): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
     _assembleDifference(dt: any): {
@@ -450,7 +492,7 @@ export class Solver {
      * 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
+     * the steady system's own rows instead (see src/laws.js): 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.
@@ -472,7 +514,6 @@ export class Solver {
     _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;

package/types/types.d.ts

@@ -28,6 +28,9 @@ export type MaterialSpeciesDef = {
  * potentials ζ = (μ̄ − zFφ − μ°)/RT. Species not in any model are ideal, c = c_ref e^ζ.
  */
 export type StatisticsDef = ({
+    type: "ideal";
+    species: string[];
+} | {
     type: "fermi-dirac";
     species: string[];
     order?: 0.5 | 0;
@@ -161,13 +164,45 @@ export type InterfacePhiLaw = "pinned" | "neutral" | {
     type: "capacitive";
     C: number;
 };
+/**
+ * A species' law across a face. conductance: J = G (V_L − V_R), G in S/m², charged species;
+ * permeability: Goldman–Hodgkin–Katz electrodiffusion, P in m/s, ideal statistics on both sides,
+ * not beside a conductor. gates: the face's gates that scale G or P, with their exponents
+ * ({ m: 3, h: 1 } for m³h; not beside a conductor).
+ */
 export type InterfaceSpeciesLink = "equilibrium" | "blocked" | {
+    type: "equilibrium" | "blocked";
+} | {
     type: "conductance";
     G: number;
+    gates?: Record<string, number>;
+} | {
+    type: "permeability";
+    P: number;
+    gates?: Record<string, number>;
+};
+/**
+ * One of a gate's rates (1/s) in the voltage V it follows, in NeuroML's standard forms (midpoint
+ * and scale in V, scale ≠ 0): 'exp', rate·e^((V − midpoint)/scale); 'sigmoid',
+ * rate/(1 + e^((midpoint − V)/scale)); 'expLinear', rate·y/(1 − e^(−y)), y = (V − midpoint)/scale.
+ */
+export type GateRate = {
+    type: "exp" | "sigmoid" | "expLinear";
+    rate: number;
+    midpoint: number;
+    scale: number;
+};
+/**
+ * A Hodgkin–Huxley gate: a fraction open x in [0, 1], dx/dt = α(V)(1 − x) − β(V)x.
+ */
+export type GateDef = {
+    alpha: GateRate;
+    beta: GateRate;
 };
 /**
  * A reaction at a face: participants on each side with signed stoichiometric coefficients
- * (ν < 0 consumed by the forward reaction), Butler–Volmer kinetics.
+ * (ν < 0 consumed by the forward reaction). Butler–Volmer kinetics (k0, alpha), or instead SRH
+ * (srh) or saturating (vmax and K), neither with a conductor's carrier.
  */
 export type FaceReactionDef = {
     /**
@@ -188,13 +223,32 @@ export type FaceReactionDef = {
      */
     fixed?: Record<string, number>;
     /**
-     * standard rate constant, mol/(m²·s)
+     * Butler–Volmer: standard rate constant, mol/(m²·s) (required unless srh or vmax)
      */
-    k0: number;
+    k0?: number;
     /**
-     * transfer coefficient, 0…1 (default 0.5)
+     * with k0: transfer coefficient, 0…1 (default 0.5)
      */
     alpha?: number;
+    /**
+     * instead: trap-assisted recombination, for a
+     * reaction consuming one negative and one positive species and making none; capture velocities
+     * vn, vp in m/s, n1 in mol/m³ (default n_i, a midgap trap)
+     */
+    srh?: {
+        vn: number;
+        vp: number;
+        n1?: number;
+    };
+    /**
+     * instead: saturating kinetics, the largest rate, mol/(m²·s)
+     */
+    vmax?: number;
+    /**
+     * with vmax: a half-saturation concentration (mol/m³) for
+     * every species the forward reaction consumes
+     */
+    K?: Record<string, number>;
 };
 /**
  * One face between consecutive regions. For different materials under a 'pinned' or
@@ -217,7 +271,8 @@ export type InterfaceDef = {
      */
     zeroCharge?: number;
     /**
-     * electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials)
+     * electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials;
+     * beside a conductor 'neutral' or capacitive, required next to an ε > 0 material)
      */
     phi?: InterfacePhiLaw;
     /**
@@ -226,13 +281,19 @@ export type InterfaceDef = {
     sheetCharge?: number;
     /**
      * per-species laws (default equilibrium
-     * where present on both sides and not reacting at the face)
+     * where present on both sides and mobile on one, blocked otherwise; a species reacting at the
+     * face and present on both sides has no default)
      */
     species?: Record<string, InterfaceSpeciesLink>;
     /**
      * reactions at the face
      */
     reactions?: FaceReactionDef[];
+    /**
+     * voltage-gated channels: gates following
+     * V = φ_right − φ_left, which its links name (not beside a conductor)
+     */
+    gates?: Record<string, GateDef>;
 };
 export type BulkReactionDef = {
     /**
@@ -248,16 +309,29 @@ export type BulkReactionDef = {
      */
     fixed?: Record<string, number>;
     /**
-     * forward rate constant per material name, or a
-     * profile of it against the device's x (an absorption profile, for photogeneration)
+     * mass action: forward rate constant per material
+     * name, or a profile of it against the device's x (an absorption profile, for photogeneration);
+     * give kf or srh
      */
-    kf: Record<string, number | Profile>;
+    kf?: Record<string, number | Profile>;
+    /**
+     * instead: SRH
+     * (trap-assisted) recombination per material name, for a reaction consuming one negative and
+     * one positive species and making none; lifetimes in s, n1 in mol/m³ (default n_i, a midgap trap)
+     */
+    srh?: Record<string, {
+        tauN: number;
+        tauP: number;
+        n1?: number;
+    }>;
 };
 /**
  * Contacts use the same laws as internal faces; the outside is a phase with known levels
  * V_i = V + offset_i (a rigid ladder that the circuit slides by V).
  */
 export type ContactSpeciesLink = "blocked" | "equilibrium" | {
+    type: "blocked";
+} | {
     type: "equilibrium";
     offset?: number;
     mu?: number;
@@ -306,16 +380,18 @@ export type ContactDef = {
      */
     species?: Record<string, ContactSpeciesLink>;
     /**
-     * a neutral
-     * composition held at the contact, anchored through a charged reference species
+     * instead of species: a neutral composition c (mol/m³) held at the contact, anchored through a
+     * charged reference species (offset: its V_i − V, V); with no reference, V is the bath's φ. It's
+     * the end material at that composition, or the material it names (a solution beside a charged region)
      */
     bath?: {
         c: Record<string, number>;
-        reference: string;
+        reference?: string;
         offset?: number;
+        material?: string;
     };
     /**
-     * required when any species connects (default 'neutral')
+     * required when any species connects (default 'neutral'; 'bulk' with a bath)
      */
     phi?: ContactPhiLink;
     /**
@@ -367,7 +443,14 @@ export type PortDef = {
      * species whose offset defaults to 0; with reactions, the electrode's carrier
      */
     terminal?: string;
+    /**
+     * per-species links, per volume (default
+     * blocked): G in S/m³ (S/m² on a conductor), k in mol/(m³·s); a conductance's gates name the
+     * port's gates that scale G, with their exponents
+     */
     species?: Record<string, "blocked" | "equilibrium" | {
+        type: "blocked";
+    } | {
         type: "equilibrium";
         offset?: number;
         mu?: number;
@@ -375,28 +458,36 @@ export type PortDef = {
         type: "conductance";
         G: number;
         offset?: number;
+        gates?: Record<string, number>;
     } | {
         type: "exchange";
         k: number;
         mu: number;
     }>;
+    /**
+     * the outside's composition (mol/m³): V is then its φ,
+     * and each linked species' level there follows from it (unless its link gives an offset or mu)
+     */
+    bath?: {
+        c: Record<string, number>;
+    };
     /**
      * an
-     * electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s)) between the region's
-     * species and the terminal species at the port's level
+     * electrode spread through the window: Butler–Volmer per area (k0 in mol/(m²·s), alpha default 0.5)
+     * between the region's species and the terminal species at the port's level
      */
     reactions?: {
         equation: string;
         fixed?: Record<string, number>;
         k0: number;
-        alpha: number;
+        alpha?: number;
         bare?: boolean;
     }[];
     /**
      * with reactions: species
      * on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
-     * shared; reactions run on Langmuir sites (what fills sites needs bare ones), and one with `bare: true`
-     * needs a bare site even if it fills none (θ₀ = 1 − Σθ)
+     * shared, theta0 the starting coverage (default 1e-6); reactions run on Langmuir sites (what fills
+     * sites needs bare ones), and one with `bare: true` needs a bare site even if it fills none (θ₀ = 1 − Σθ)
      */
     surface?: Record<string, {
         mu0: number;
@@ -420,6 +511,11 @@ export type PortDef = {
         x: number[];
         values: number[];
     };
+    /**
+     * with a capacitance: voltage-gated channels at each node of
+     * the window, following the voltage across it, φ − (V − zeroCharge), which its conductance links name
+     */
+    gates?: Record<string, GateDef>;
 };
 /**
  * A device definition: plain, serialisable data.
@@ -481,6 +577,10 @@ export type ContactResult = {
      * total current toward +x, A/m²
      */
     current: number;
+    /**
+     * how each species that crosses it does (its link type)
+     */
+    links: Record<string, string>;
 };
 /**
  * The device's totals through its cross-section (currents, fluxes through contacts and ports,
@@ -537,6 +637,23 @@ export type Solution = {
      * standard levels as voltages, V
      */
     Vstd: Record<string, Float64Array>;
+    /**
+     * each species' flux toward +x across each segment, between
+     * nodes g and g + 1 (a face's across its pair of nodes), mol/(m²·s): the fluxes the balances add up
+     */
+    flux: Record<string, Float64Array>;
+    /**
+     * diffusivity at each node, m²/s (NaN where absent, or in a conductor)
+     */
+    D: Record<string, Float64Array>;
+    /**
+     * temperature, K
+     */
+    T: number;
+    /**
+     * the device's (amounts and rates per area only if planar)
+     */
+    geometry: "planar" | "cylindrical" | "spherical" | "profile";
     /**
      * current toward +x through the device, A/m²
      */
@@ -574,9 +691,11 @@ export type Solution = {
         };
     };
     /**
-     * what each internal port brings into the device;
-     * with reactions, also its window's nodes (x, m), area per volume there, and each reaction's rate per area
-     * at each node (mol/(m²·s), forward)
+     *   what each internal port brings into the device (current: the charging current included); with
+     *   reactions or a capacitance, also its window's nodes (x, m) and area per volume there (m²/m³); with
+     *   reactions, each reaction's net rate per area at each node (mol/(m²·s), forward); with a surface, each
+     *   species' coverage and the bare fraction; with a capacitance, σ per area (C/m²) and the charge its
+     *   side holds; with gates, each gate's fraction open at each node and the voltage they follow (V)
      */
     ports: {
         name: string;
@@ -590,7 +709,16 @@ export type Solution = {
         bare?: Float64Array;
         sigma?: Float64Array;
         charge?: number;
+        gates?: Record<string, Float64Array>;
+        Vm?: Float64Array;
     }[];
+    /**
+     * each face: the regions it joins, its dipole
+     * (V) and sheet charge (C/m²), its displacement D (C/m²), each species' flux N across it and each face
+     * reaction's net rate (mol/(m²·s), toward +x and forward), how each species that crosses it does (its
+     * link type); for those crossing by permeability, the one-way fluxes [toward +x, toward −x] whose
+     * difference is N; with gates, each one's fraction open and the voltage they follow, φ_right − φ_left (V)
+     */
     interfaces: {
         left: string;
         right: string;
@@ -599,13 +727,20 @@ export type Solution = {
         D: number;
         N: Record<string, number>;
         rates: number[];
+        links: Record<string, string>;
+        oneWay?: Record<string, [number, number]>;
+        gates?: Record<string, number>;
+        V?: number;
     }[];
     /**
-     * each bulk reaction's
-     * forward rate per node (mol/(m³·s), NaN where it doesn't run), and per region and in all (mol/(m²·s))
+     *   each bulk reaction's net rate per node (mol/(m³·s), forward minus backward, NaN where it doesn't
+     *   run), its one-way forward rate (the backward is forward − rate), what one forward reaction makes
+     *   of each species (ν, negative for what it consumes), and the net rate per region and in all (mol/(m²·s))
      */
     bulkReactions: {
         rate: Float64Array;
+        forward: Float64Array;
+        nu: Record<string, number>;
         regions: number[];
         total: number;
     }[];
@@ -626,7 +761,23 @@ export type Solution = {
     }[];
     warnings: string[];
     converged: boolean;
+    /**
+     * Newton iterations
+     */
     iterations: number;
+    /**
+     * solve(): the steps it took to the steady state; advance(): accepted steps
+     */
+    steps?: number;
+    /**
+     * step(): how many pieces the interval was split into
+     */
+    substeps?: number;
+    /**
+     * solver bookkeeping: solve(), a record of its steps and
+     * stages; step(), Newton's largest update per iteration (thermal units)
+     */
+    history?: (number | object)[];
     /**
      * s
      */
@@ -645,8 +796,10 @@ export type Solution = {
     rejected?: number;
     /**
      * advance():
-     * terminal current (A/m², toward +x) and voltage after each accepted step, and each probe's
-     * reading (mol/m³, or V for quantity 'V'), interpolated between the nodes around its x
+     * the right contact's current (A/m², toward +x) and V_right − V_left after each accepted step, and
+     * each probe's reading: inside, interpolated between the nodes around its x (mol/m³ for quantity
+     * 'c', V for 'V' or 'phi'); at a face, a species' flux through it (mol/(m²·s), toward +x) or a
+     * gate's fraction open
      */
     trace?: {
         t: number[];
@@ -661,7 +814,7 @@ export type ImpedanceResult = {
      */
     f: Float64Array;
     /**
-     * impedance −δV/δI, Ω·m²
+     * impedance δV/δI at the terminal, I into the device, Ω·m²
      */
     Z: {
         re: Float64Array;