driftlet 1.1.1 → 1.2.1

package/src/types.js

@@ -19,6 +19,7 @@
  * Statistics model: how the listed species' concentrations follow from their reduced
  * potentials ζ = (μ̄ − zFφ − μ°)/RT. Species not in any model are ideal, c = c_ref e^ζ.
  * @typedef {(
+ *   { type: 'ideal', species: string[] } |
  *   { type: 'fermi-dirac', species: string[], order?: 0.5 | 0 } |
  *   { type: 'lattice', species: string[], cMax: number } |
  *   { type: 'redlich-kister', species: [string], cMax: number, A?: number[] } |
@@ -73,19 +74,45 @@
  */
 
 /** @typedef {'pinned' | 'neutral' | { type: 'capacitive', C: number }} InterfacePhiLaw */
-/** @typedef {'equilibrium' | 'blocked' | { type: 'conductance', G: number }} InterfaceSpeciesLink */
+/**
+ * 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).
+ * @typedef {'equilibrium' | 'blocked' | { type: 'equilibrium' | 'blocked' }
+ *   | { type: 'conductance', G: number, gates?: Record<string, number> }
+ *   | { type: 'permeability', P: number, gates?: Record<string, number> }} InterfaceSpeciesLink
+ */
+
+/**
+ * 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.
+ * @typedef {{ type: 'exp' | 'sigmoid' | 'expLinear', rate: number, midpoint: number, scale: number }} GateRate
+ */
+/**
+ * A Hodgkin–Huxley gate: a fraction open x in [0, 1], dx/dt = α(V)(1 − x) − β(V)x.
+ * @typedef {{ alpha: GateRate, beta: GateRate }} GateDef
+ */
 
 /**
  * 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.
  * @typedef {object} FaceReactionDef
  * @property {string} [equation] the reaction as an equation, e.g. 'Ag+ + e- = Ag(s)', each
  *   participant on the side that holds it ('Li+(left)' where both do); or give left and right
  * @property {Record<string, number>} [left] participants on the left side (species present there, or fixed neutrals)
  * @property {Record<string, number>} [right] participants on the right side
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {number} k0 standard rate constant, mol/(m²·s)
- * @property {number} [alpha] transfer coefficient, 0…1 (default 0.5)
+ * @property {number} [k0] Butler–Volmer: standard rate constant, mol/(m²·s) (required unless srh or vmax)
+ * @property {number} [alpha] with k0: transfer coefficient, 0…1 (default 0.5)
+ * @property {{ vn: number, vp: number, n1?: number }} [srh] 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)
+ * @property {number} [vmax] instead: saturating kinetics, the largest rate, mol/(m²·s)
+ * @property {Record<string, number>} [K] with vmax: a half-saturation concentration (mol/m³) for
+ *   every species the forward reaction consumes
  */
 /**
  * One face between consecutive regions. For different materials under a 'pinned' or
@@ -94,11 +121,15 @@
  * @property {{ species: string, value: number }} [step] standard-level step right − left, J/mol
  * @property {number} [dipole] φ jump right − left, V
  * @property {number} [zeroCharge] beside a conductor region: V_F − φ_edge at zero charge, V
- * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials)
+ * @property {InterfacePhiLaw} [phi] electrostatic law (default 'pinned'; 'neutral' between ε = 0 materials;
+ *   beside a conductor 'neutral' or capacitive, required next to an ε > 0 material)
  * @property {number} [sheetCharge] C/m²
  * @property {Record<string, InterfaceSpeciesLink>} [species] 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)
  * @property {FaceReactionDef[]} [reactions] reactions at the face
+ * @property {Record<string, GateDef>} [gates] voltage-gated channels: gates following
+ *   V = φ_right − φ_left, which its links name (not beside a conductor)
  */
 
 /**
@@ -106,14 +137,18 @@
  * @property {Record<string, number>} [nu] signed stoichiometric coefficients (ν < 0 consumed)
  * @property {string} [equation] the reaction as an equation, e.g. 'e- + h+ = 0' (instead of nu)
  * @property {Record<string, number>} [fixed] μ (J/mol) of fixed-activity participants that aren't species
- * @property {Record<string, number | Profile>} kf forward rate constant per material name, or a
- *   profile of it against the device's x (an absorption profile, for photogeneration)
+ * @property {Record<string, number | Profile>} [kf] 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
+ * @property {Record<string, { tauN: number, tauP: number, n1?: number }>} [srh] 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)
  */
 
 /**
  * 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).
- * @typedef {'blocked' | 'equilibrium'
+ * @typedef {'blocked' | 'equilibrium' | { type: 'blocked' }
  *   | { type: 'equilibrium', offset?: number, mu?: number }
  *   | { type: 'conductance', G: number, offset?: number }
  *   | { type: 'exchange', k: number, mu: number }
@@ -133,9 +168,11 @@
  * @property {number} [R] with V: a series resistance, Ω·m² (a source behind a resistor)
  * @property {string} [terminal] species whose voltage V is
  * @property {Record<string, ContactSpeciesLink>} [species] per-species links (default blocked)
- * @property {{ c: Record<string, number>, reference: string, offset?: number }} [bath] a neutral
- *   composition held at the contact, anchored through a charged reference species
- * @property {ContactPhiLink} [phi] required when any species connects (default 'neutral')
+ * @property {{ c: Record<string, number>, reference?: string, offset?: number, material?: string }} [bath]
+ *   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)
+ * @property {ContactPhiLink} [phi] required when any species connects (default 'neutral'; 'bulk' with a bath)
  * @property {number} [zeroCharge] for a capacitive or pinned law: V − φ_edge at zero charge, V
  */
 
@@ -158,20 +195,27 @@
  * @property {Source} [I] or: the current driven into the device, A/m² (e.g. 0 for a reference electrode)
  * @property {number} [R] with V: a series resistance, Ω·m²
  * @property {string} [terminal] species whose offset defaults to 0; with reactions, the electrode's carrier
- * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'equilibrium', offset?: number, mu?: number }
- *   | { type: 'conductance', G: number, offset?: number } | { type: 'exchange', k: number, mu: number }>} [species]
- * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number, bare?: boolean }[]} [reactions] 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
+ * @property {Record<string, 'blocked' | 'equilibrium' | { type: 'blocked' } | { type: 'equilibrium', offset?: number, mu?: number }
+ *   | { type: 'conductance', G: number, offset?: number, gates?: Record<string, number> }
+ *   | { type: 'exchange', k: number, mu: number }>} [species] 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
+ * @property {{ c: Record<string, number> }} [bath] 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)
+ * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha?: number, bare?: boolean }[]} [reactions] an
+ *   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
  * @property {Record<string, { mu0: number, capacity: number, theta0?: number }>} [surface] 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 − Σθ)
  * @property {{ C: number, zeroCharge?: number }} [capacitance] a capacitance spread through the window (F/m² of
  *   electrode): σ = C (V − zeroCharge − φ) on the port's side, aσ in each node's charge balance; a gate
  *   along a channel, a double layer
  * @property {number | { x: number[], values: number[] }} [area] with reactions or a capacitance: electrode area per volume,
  *   m²/m³ (1/h for a film of thickness h), or a profile against the device's x
+ * @property {Record<string, GateDef>} [gates] with a capacitance: voltage-gated channels at each node of
+ *   the window, following the voltage across it, φ − (V − zeroCharge), which its conductance links name
  */
 
 /**
@@ -198,6 +242,7 @@
  * @property {Record<string, number>} flux particle flux toward +x through this contact, mol/(m²·s)
  * @property {number} D displacement toward +x at this contact, C/m²
  * @property {number} current total current toward +x, A/m²
+ * @property {Record<string, string>} links how each species that crosses it does (its link type)
  */
 
 /**
@@ -216,6 +261,11 @@
  * @property {Record<string, Float64Array>} muStd standard levels μ° + zFφ, J/mol
  * @property {Record<string, Float64Array>} V species voltages μ̄/(zF), V (charged species)
  * @property {Record<string, Float64Array>} Vstd standard levels as voltages, V
+ * @property {Record<string, Float64Array>} flux 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
+ * @property {Record<string, Float64Array>} D diffusivity at each node, m²/s (NaN where absent, or in a conductor)
+ * @property {number} T temperature, K
+ * @property {'planar' | 'cylindrical' | 'spherical' | 'profile'} geometry the device's (amounts and rates per area only if planar)
  * @property {number} current current toward +x through the device, A/m²
  * @property {number} terminalVoltage V_right − V_left, V
  * @property {Record<string, { V: number, current: number }>} terminals each terminal (left, right,
@@ -225,31 +275,48 @@
  *   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;
- *   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)
- * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>, rates: number[] }[]} interfaces
- * @property {{ rate: Float64Array, regions: number[], total: number }[]} bulkReactions 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))
+ *   sigma?: Float64Array, charge?: number, gates?: Record<string, Float64Array>, Vm?: Float64Array }[]} ports
+ *   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)
+ * @property {{ left: string, right: string, dipole: number, sheetCharge: number, D: number, N: Record<string, number>,
+ *   rates: number[], links: Record<string, string>, oneWay?: Record<string, [number, number]>,
+ *   gates?: Record<string, number>, V?: number }[]} interfaces 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)
+ * @property {{ rate: Float64Array, forward: Float64Array, nu: Record<string, number>, regions: number[], total: number }[]} bulkReactions
+ *   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))
  * @property {number} charge total charge in the device, C/m²
  * @property {{ species: string, regions: number[], spectator: boolean, connected: boolean, reactive: boolean,
  *   amount: number, reference: number, intake: number, drift: number }[]} conservation
  * @property {string[]} warnings
  * @property {boolean} converged
- * @property {number} iterations
+ * @property {number} iterations Newton iterations
+ * @property {number} [steps] solve(): the steps it took to the steady state; advance(): accepted steps
+ * @property {number} [substeps] step(): how many pieces the interval was split into
+ * @property {(number | object)[]} [history] solver bookkeeping: solve(), a record of its steps and
+ *   stages; step(), Newton's largest update per iteration (thermal units)
  * @property {number} time s
  * @property {boolean} steady whether this is a converged steady state (solve()), not a transient's
  * @property {boolean} [done] advance(): whether tEnd was reached (false if the frame budget ran out)
  * @property {number} [rejected] advance(): steps rejected by error control or Newton failure
  * @property {{ t: number[], current: number[], voltage: number[], probes?: number[][] }} [trace] 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
  */
 
 /**
  * @typedef {object} ImpedanceResult
  * @property {Float64Array} f frequencies, Hz
- * @property {{ re: Float64Array, im: Float64Array }} Z impedance −δV/δI, Ω·m²
+ * @property {{ re: Float64Array, im: Float64Array }} Z impedance δV/δI at the terminal, I into the device, Ω·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

package/types/index.d.ts

@@ -48,11 +48,14 @@ export class Device {
      * 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. `probes`
-     * read a species at points inside the device after every accepted step, into `trace.probes`
-     * (one array per probe, alongside `trace.t`): what a detector at x sees.
+     * read a species (or φ) at points inside the device after every accepted step, into
+     * `trace.probes` (one array per probe, alongside `trace.t`): what a detector at x sees. At a
+     * face, `{ interface, species }` reads a species' flux through it (mol/(m²·s), toward +x), and
+     * `{ interface, gate }` a gate's fraction open.
      * @param {number} tEnd s
      * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-     *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+     *   probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }
+     *     | { interface: number, species: string } | { interface: number, gate: string })[] }} [opts]
      * @returns {Solution}
      */
     advance(tEnd: number, opts?: {
@@ -62,12 +65,18 @@ export class Device {
         budgetMs?: number;
         maxSteps?: number;
         method?: "bdf2" | "be";
-        probes?: {
+        probes?: ({
             x: number;
             species?: string;
             quantity?: "c" | "V" | "phi";
             region?: string | number;
-        }[];
+        } | {
+            interface: number;
+            species: string;
+        } | {
+            interface: number;
+            gate: string;
+        })[];
     }): Solution;
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its

package/types/kit.d.ts

@@ -25,7 +25,7 @@ export function vacuumLevel(def: object, side: VacuumSide, path?: string): numbe
 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
+ * material: at a conductor region's face, or a contact's capacitive or pinned 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

package/types/plot.d.ts

@@ -1,11 +1,11 @@
 /**
  * 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 {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role
  * @param {number} slot
  * @param {{ dark?: boolean }} [opts]
  */
-export function themeColor(role: "electron" | "cation" | "anion" | "redox", slot: number, { dark }?: {
+export function themeColor(role: "electron" | "cation" | "anion" | "redox" | "phi", slot: number, { dark }?: {
     dark?: boolean;
 }, ...args: any[]): string;
 /**

package/types/solution.d.ts

@@ -10,6 +10,7 @@ export function makeSolution(solver: any, result?: {}): {
     V: {};
     Vstd: {};
     T: any;
+    geometry: any;
     time: any;
     steady: any;
     converged: any;

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;
@@ -142,10 +143,14 @@ export class Solver {
     _roughAmount(st: any): number;
     _moves(st: any): boolean;
     _still(st: any): boolean;
+    _carrierZ(k: any): number;
+    _contactCharges(k: any): boolean;
     _feeds(k: any, st: any): any;
     _laws(): void;
     constraints: any[];
     affinities: any[];
+    contactQ: any[];
+    contactLaw: boolean[];
     localConstraints: any[];
     islands: any[];
     pinnedIslands: any[];
@@ -159,6 +164,7 @@ export class Solver {
     islandRow: Float64Array<any>;
     _rowInto(o: any, add: any): void;
     linRow: Float64Array<any>;
+    _sites(g: any): number;
     _applyLocalConstraints(): void;
     _conservedMoieties(drives?: boolean, alsoCurrent?: any[], skip?: any): Float64Array<any>[];
     _directSteady(): boolean;
@@ -166,7 +172,7 @@ export class Solver {
     _lawAmount(cs: any): {
         amount: number;
         reference: number;
-        dV: number;
+        dV: any;
         gross: number;
     };
     _lawStart(cs: any): number;