driftlet 0.1.1 → 0.3.0

package/types/index.d.ts

@@ -45,9 +45,12 @@ 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.
+     * 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.
      * @param {number} tEnd s
-     * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be' }} [opts]
+     * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
+     *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
      * @returns {Solution}
      */
     advance(tEnd: number, opts?: {
@@ -57,6 +60,12 @@ export class Device {
         budgetMs?: number;
         maxSteps?: number;
         method?: "bdf2" | "be";
+        probes?: {
+            x: number;
+            species: string;
+            quantity?: "c" | "V";
+            region?: string | number;
+        }[];
     }): Solution;
     /**
      * Small-signal impedance Z(f) about the steady state (solved first), at one terminal: its

package/types/kit.d.ts

@@ -57,5 +57,6 @@ export type VacuumSide = {
 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 { pulse, square, triangle, ramp, injector, recombination } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/pow.d.ts

@@ -0,0 +1,4 @@
+/** x^n for an integer n. */
+export function powi(x: any, n: any): any;
+/** x^y for x ≥ 0 and any real y. */
+export function powr(x: any, y: any): any;

package/types/solver.d.ts

@@ -120,9 +120,9 @@ export class Solver {
     /** η_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.
+     * Cold start. Each species takes its region's c0 where one is given (for a spectator, it fixes
+     * the conserved amount), else its contact's level. φ in each region is then chosen for local neutrality (node by node where a
+     * profile varies), 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;
@@ -216,6 +216,7 @@ export class Solver {
         rejected: number;
         iterations: number;
         trace: {
+            probes?: any;
             t: any[];
             current: any[];
             voltage: any[];
@@ -227,6 +228,11 @@ export class Solver {
         scale: number;
         order: number;
     };
+    _probes(probes: any): {
+        out: any;
+        read: () => any;
+        push: (values: any) => any;
+    };
     _errorNorm(ref: any): number;
     _snapshot(): {
         u: Float64Array<ArrayBuffer>;

package/types/sources.d.ts

@@ -0,0 +1,102 @@
+/**
+ * A rectangular pulse, as a waveform for a terminal's `V` or `I`: `base` until `start`, then
+ * `base + amplitude` for `width`, then `base` again. With a `rise` > 0 its edges are ramps of
+ * that length, placed so the area stays `amplitude · width`; without one they're jumps, which
+ * the time stepping handles exactly (so a pulse with no rise must start after t = 0, the time a
+ * device starts at and solve() reads: it's off then).
+ * @param {{ start?: number, width: number, amplitude: number, rise?: number, base?: number }} opts s, s, V or A/m², s, V or A/m²
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function pulse({ start, width, amplitude, rise, base }?: {
+    start?: number;
+    width: number;
+    amplitude: number;
+    rise?: number;
+    base?: number;
+}): {
+    t: number[];
+    values: number[];
+};
+/**
+ * A square wave, repeating: `high` for `duty · period`, then `low`, from t = 0.
+ * @param {{ high: number, low: number, period: number, duty?: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function square({ high, low, period, duty }?: {
+    high: number;
+    low: number;
+    period: number;
+    duty?: number;
+}): {
+    t: number[];
+    values: number[];
+    repeat: true;
+};
+/**
+ * A triangle wave, repeating: from `from` to `to` and back in each `period`, from t = 0 (a
+ * cyclic voltammogram's sweep, from its starting potential).
+ * @param {{ from: number, to: number, period: number }} opts
+ * @returns {{ t: number[], values: number[], repeat: true }}
+ */
+export function triangle({ from, to, period }?: {
+    from: number;
+    to: number;
+    period: number;
+}): {
+    t: number[];
+    values: number[];
+    repeat: true;
+};
+/**
+ * A ramp from `from` to `to` over `duration`, starting at `start`, constant on either side.
+ * @param {{ from: number, to: number, duration: number, start?: number }} opts
+ * @returns {{ t: number[], values: number[] }}
+ */
+export function ramp({ from, to, duration, start }?: {
+    from: number;
+    to: number;
+    duration: number;
+    start?: number;
+}): {
+    t: number[];
+    values: number[];
+};
+/**
+ * A port that injects a species into a window of a region at a driven current `I` (A/m², a
+ * number or a waveform), spread evenly over the window. It's an ordinary port: driven by `I`,
+ * its terminal the species, linked by a conductance small enough that at the peak current the
+ * port sits `headroom` volts above the window's level of that species, so every node of the
+ * window takes the same share (like a current source). At I = 0 it still links the window,
+ * weakly.
+ * @param {{ name?: string, region: string | number, from: number, to: number, species: string,
+ *   I: number | { t: number[], values: number[], repeat?: boolean }, headroom?: number }} opts
+ * @returns {object} a port, for the definition's `ports`
+ */
+export function injector({ name, region, from, to, species, I, headroom }?: {
+    name?: string;
+    region: string | number;
+    from: number;
+    to: number;
+    species: string;
+    I: number | {
+        t: number[];
+        values: number[];
+        repeat?: boolean;
+    };
+    headroom?: number;
+}): object;
+/**
+ * Band-to-band recombination e⁻ + h⁺ ⇌ 0 in a material, from the minority-carrier lifetime it
+ * should give at a majority density: kf = 1/(τ · majority). (The rate is kf (np − n_i²), so τ is
+ * the low-injection lifetime of whichever carrier is the minority.)
+ * @param {{ material: string, tau: number, majority: number }} opts material name, s, mol/m³
+ * @returns {{ equation: string, kf: Record<string, number> }} a bulk reaction
+ */
+export function recombination({ material, tau, majority }?: {
+    material: string;
+    tau: number;
+    majority: number;
+}): {
+    equation: string;
+    kf: Record<string, number>;
+};

package/types/types.d.ts

@@ -130,10 +130,14 @@ export type RegionDef = {
      */
     fixedCharge?: number;
     /**
-     * initial concentrations, mol/m³ (required for species
-     * not connected to a contact: it fixes the amount they conserve)
+     * initial concentrations,
+     * mol/m³ (required for species not connected to a contact: it fixes the amount they conserve);
+     * or a profile against the device's x (m), piecewise linear; either is the starting state
      */
-    c0?: Record<string, number>;
+    c0?: Record<string, number | {
+        x: number[];
+        c: number[];
+    }>;
     /**
      * imposed flow toward +x, m/s, carrying every mobile species
      */
@@ -538,13 +542,15 @@ export type Solution = {
      */
     rejected?: number;
     /**
-     * advance(): terminal
-     * current (A/m², toward +x) and voltage after each accepted step
+     * 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
      */
     trace?: {
         t: number[];
         current: number[];
         voltage: number[];
+        probes?: number[][];
     };
 };
 export type ImpedanceResult = {