driftlet 0.5.0 → 0.7.0

package/types/devices.d.ts

@@ -0,0 +1,77 @@
+/**
+ * IonMonger's default planar perovskite solar cell: TiO₂ (100 nm) | MAPbI₃ (400 nm) with mobile
+ * iodide vacancies over an equal immobile background | spiro-OMeTAD (200 nm), at 298 K, lit
+ * through the TiO₂. Species e⁻, h⁺ and the vacancies 'V+'. Recombination is SRH at both faces
+ * (IonMonger's interface law is driftlet's face SRH, with n₁ from the TiO₂'s electron density)
+ * and, with `bulkSRH`, SRH through midgap traps in the perovskite (τₙ = 3 ns, τₚ = 300 ns).
+ * Light is 1.4e21 photons/(m²·s) at α = 1.3e7 /m (IonMonger's one sun), times `light`. The left
+ * contact is the TiO₂'s, at 0 V; the right is the spiro's, at `V`, so photocurrent is positive.
+ *
+ * `PEROVSKITE_SCANS` holds IonMonger's own results for this cell, scan by scan.
+ * @param {{ V?: import('./types.js').Source | { V?: import('./types.js').Source, I?: import('./types.js').Source, R?: number }, light?: number, bulkSRH?: boolean }} [opts]
+ * @returns {import('./types.js').DeviceDefinition}
+ */
+export function perovskiteCell({ V, light, bulkSRH }?: {
+    V?: import("./types.js").Source | {
+        V?: import("./types.js").Source;
+        I?: import("./types.js").Source;
+        R?: number;
+    };
+    light?: number;
+    bulkSRH?: boolean;
+}): import("./types.js").DeviceDefinition;
+/**
+ * A J–V loop's figures of merit, from a transient's trace (`{ t, voltage, current }`, as a
+ * recorder or advance() gives it): the loop splits at time `turn` into the sweep before (`rev`)
+ * and after (`fwd`). Each sweep's maximum power V·I (W/m², the largest among the trace's points)
+ * and its open-circuit voltage (where I changes sign, interpolated linearly); and the
+ * hysteresis index (Pmax,rev − Pmax,fwd)/Pmax,rev. Power out is positive, so a cell whose
+ * current runs the other way should have it negated first.
+ * @param {{ t: ArrayLike<number>, voltage: ArrayLike<number>, current: ArrayLike<number> }} trace
+ * @param {number} turn s
+ */
+export function hysteresis(trace: {
+    t: ArrayLike<number>;
+    voltage: ArrayLike<number>;
+    current: ArrayLike<number>;
+}, turn: number): {
+    hi: number;
+};
+/**
+ * IonMonger's J–V scans of `perovskiteCell()` (IonMonger 2.0, commit 1ae4f9e, run in GNU Octave):
+ * steady state at 1.2 V under light, then 1.2 → 0 → 1.2 V at `rate` (V/s). `full` is the cell
+ * as given (bulk SRH on); `noBulkSRH` is `perovskiteCell({ bulkSRH: false })`. Per scan: J0, the
+ * current at 0 V (A/m²); each sweep's maximum power Pmax (W/m², the largest V·J among IonMonger's
+ * 201 output points per loop) and Voc (V, interpolated); and the hysteresis index
+ * hi = (Pmax,rev − Pmax,fwd)/Pmax,rev. `hysteresis()` reads the same from a run's trace.
+ * driftlet reproduces these to 0.15 % in hi, 0.5 W/m² in Pmax and 2 mV in Voc (its test suite).
+ */
+export const PEROVSKITE_SCANS: Readonly<{
+    source: "IonMonger 2.0 (github.com/PerovskiteSCModelling/IonMonger, commit 1ae4f9e), default parameters";
+    full: {
+        rate: number;
+        J0: number;
+        rev: {
+            Pmax: number;
+            Voc: number;
+        };
+        fwd: {
+            Pmax: number;
+            Voc: number;
+        };
+        hi: number;
+    }[];
+    noBulkSRH: {
+        rate: number;
+        J0: number;
+        rev: {
+            Pmax: number;
+            Voc: number;
+        };
+        fwd: {
+            Pmax: number;
+            Voc: number;
+        };
+        hi: number;
+    }[];
+}>;

package/types/index.d.ts

@@ -51,7 +51,7 @@ export class Device {
      * (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',
-     *   probes?: { x: number, species: string, quantity?: 'c' | 'V', region?: string | number }[] }} [opts]
+     *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
      * @returns {Solution}
      */
     advance(tEnd: number, opts?: {
@@ -63,8 +63,8 @@ export class Device {
         method?: "bdf2" | "be";
         probes?: {
             x: number;
-            species: string;
-            quantity?: "c" | "V";
+            species?: string;
+            quantity?: "c" | "V" | "phi";
             region?: string | number;
         }[];
     }): Solution;

package/types/junction.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Henderson's liquid-junction potential, φ_R − φ_L (V): the junction taken to be the two solutions
+ * mixed in one proportion at every point (every ion's mixing fraction the same curve). Exact for a single binary salt, a close estimate otherwise (it's what
+ * JPCalc and most electrophysiology corrections use).
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @param {{ T?: number }} [opts] K (default 298.15)
+ */
+export function henderson(left: Record<string, number>, right: Record<string, number>, ions: Record<string, {
+    z: number;
+    D: number;
+}>, { T }?: {
+    T?: number;
+}): number;
+/**
+ * Planck's liquid-junction potential, φ_R − φ_L (V): the steady state of constrained diffusion,
+ * a junction zone held between the two solutions, electroneutral, carrying no current. Solved by
+ * shooting on the Nernst–Planck equations across it (its length drops out). Exact for that
+ * junction; equal to Henderson's for a single binary salt.
+ * @param {Record<string, number>} left mol/m³ by ion
+ * @param {Record<string, number>} right mol/m³ by ion
+ * @param {Record<string, { z: number, D: number }>} ions charge and diffusivity (m²/s), e.g. IONS
+ * @param {{ T?: number, steps?: number }} [opts] K (default 298.15); RK4 steps across (default 4000)
+ */
+export function planck(left: Record<string, number>, right: Record<string, number>, ions: Record<string, {
+    z: number;
+    D: number;
+}>, { T, steps }?: {
+    T?: number;
+    steps?: number;
+}): number;

package/types/kit.d.ts

@@ -34,6 +34,8 @@ export function vacuumDipole(def: object, left: VacuumSide, right: VacuumSide):
  */
 export function vacuumZeroCharge(def: object, workFunction: number, inside: VacuumSide): number;
 export { live } from "./live.js";
+export { recorder } from "./recorder.js";
+export { check } from "./checks.js";
 /**
  * One material seen from vacuum: a level inside it (the anchor) and how far above that level,
  * in electron energy, the vacuum level just outside lies (the offset, V). So
@@ -59,4 +61,6 @@ export { parseEquation, stoichiometry, half, SHE, level } from "./equation.js";
 export { traces, speciesRole, typeset } from "./traces.js";
 export { pulse, square, triangle, ramp, injector, recombination, photogeneration } from "./sources.js";
 export { describe, unitWarnings } from "./describe.js";
+export { henderson, planck } from "./junction.js";
+export { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from "./devices.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/recorder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Record a device's transient. Frames are whole solutions: at the start, then at each of
+ * `times` (or every `every` seconds from the start), which `advance()` lands on exactly; with
+ * neither, at the end of each `advance()` call. The trace (`t`, `current`, `voltage`, and
+ * `probes` if given) runs from the start through every accepted step of every call.
+ * @param {import('./index.js').Device} device
+ * @param {{ every?: number, times?: number[], probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+ */
+export function recorder(device: import("./index.js").Device, opts?: {
+    every?: number;
+    times?: number[];
+    probes?: {
+        x: number;
+        species?: string;
+        quantity?: "c" | "V" | "phi";
+        region?: string | number;
+    }[];
+}): {
+    advance: (tEnd: number, aopts?: object) => import("./types.js").Solution;
+    frame: (t: number) => import("./types.js").Solution;
+    frames: import("./types.js").Solution[];
+    trace: {
+        t: number[];
+        current: number[];
+        voltage: number[];
+    };
+};

package/types/solution.d.ts

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

package/types/solver.d.ts

@@ -44,6 +44,7 @@ export class Solver {
     jR: Float64Array<any>;
     time: number;
     lastDt: number;
+    atSteady: boolean;
     contactFlux: {
         left: Float64Array<any>;
         right: Float64Array<any>;
@@ -155,8 +156,11 @@ export class Solver {
     _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;
+    bulkRate(rx: any, g: any): number;
+    bulkOneWay(rx: any, g: any): number;
     _srhRate(law: any, cn: any, cp: any, a: any): {
         rate: number;
+        oneWay: number;
         Cn: number;
         Cp: number;
         Ca: number;
@@ -243,12 +247,15 @@ export class Solver {
         push: (values: any) => any;
     };
     _errorNorm(ref: any): number;
+    _warmFrom(src: any): void;
+    solvedV: any;
     _snapshot(): {
         u: Float64Array<ArrayBuffer>;
         uLo: Float64Array<ArrayBuffer>;
         cOld: Float64Array<ArrayBuffer>;
         time: number;
         lastDt: number;
+        atSteady: boolean;
         contactDStart: {
             left: number;
             right: number;
@@ -309,7 +316,7 @@ export class Solver {
      * The clock is not advanced, and open-system conservation bookkeeping restarts here.
      */
     solveSteady(opts?: {}): any;
-    solvedV: any;
+    _steadyFromHere(opts: any): any;
     _generationContinuation(opts: any, r: any): {
         converged: boolean;
         steps: any;

package/types/stack.d.ts

@@ -19,6 +19,7 @@ export function combine(...parts: {
  * @param {object} [more]
  */
 export function layer(material: string, length: number, more?: object): any;
+export function drive(d: any, path: any): 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

package/types/types.d.ts

@@ -510,12 +510,23 @@ export type Solution = {
         current: number;
     }[];
     interfaces: {
+        left: string;
+        right: string;
         dipole: number;
         sheetCharge: number;
         D: number;
         N: Record<string, number>;
         rates: 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))
+     */
+    bulkReactions: {
+        rate: Float64Array;
+        regions: number[];
+        total: number;
+    }[];
     /**
      * total charge in the device, C/m²
      */
@@ -538,6 +549,10 @@ export type Solution = {
      * s
      */
     time: number;
+    /**
+     * whether this is a converged steady state (solve()), not a transient's
+     */
+    steady: boolean;
     /**
      * advance(): whether tEnd was reached (false if the frame budget ran out)
      */