driftlet 0.4.0 → 0.6.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

@@ -13,8 +13,9 @@ export class Device {
     get solver(): any;
     get grid(): any;
     /**
-     * Change part of the definition (deep-merged). 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
+     * 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'
+     * 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
      * @returns {this}

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,5 @@ 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 { perovskiteCell, PEROVSKITE_SCANS, hysteresis } from "./devices.js";
 export { IONS, H2O, WATER_EPSR, SEMICONDUCTORS, METALS, aqueous, semiconductor, metal } from "./data.js";

package/types/plot.d.ts

@@ -37,7 +37,8 @@ export function levelChart(tr: ReturnType<typeof traces>, { width, height, ylabe
 }): string;
 /**
  * A solution's level diagram as an SVG string: each charged species' voltage (thick) and
- * standard level (thin), regions as bands. Options are those of `traces()` and `levelChart()`.
+ * standard level (thin), regions as bands; or with `energy: true`, the familiar energy-up band
+ * diagram of electrons and holes. Options are those of `traces()` and `levelChart()`.
  * @param {import('./types.js').Solution} sol
  * @param {Parameters<typeof traces>[1] & Parameters<typeof levelChart>[1]} [opts]
  * @returns {string}

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', 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";
+        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>;
@@ -103,7 +104,10 @@ export class Solver {
     stretchOf: Int32Array<ArrayBuffer>;
     moieties: Float64Array<ArrayBuffer>[];
     constraints: any[];
+    localConstraints: any[];
     constrained: boolean;
+    _captureLocal(): void;
+    _applyLocalConstraints(): void;
     _conservedMoieties(): Float64Array<ArrayBuffer>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
@@ -152,6 +156,15 @@ 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;
+    };
     _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any): void;
     _terminals(dt: any): void;
     _circuit(k: any): void;
@@ -234,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;
@@ -288,6 +304,7 @@ export class Solver {
     _assembleBookkeeping(dt: any): void;
     _accumulateBoundaryIntake(dt: any, cN: any): void;
     slowestTime(): number;
+    fastestTime(): number;
     /**
      * Steady state.
      * - If every species stretch is fed by a contact, nothing is conserved on its own, so the
@@ -299,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/traces.d.ts

@@ -40,7 +40,11 @@ export function typeset(name: string, z: number): string;
  * its standard level V°_i (`standard`, the band edge for e⁻ and h⁺), optionally φ and
  * half-reactions' levels. Doubled interface nodes share an x, so steps draw as vertical lines.
  * @param {import('./types.js').Solution} sol
- * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[],
+ * With `energy: true` it's the familiar band diagram instead, energy up: electrons and holes as
+ * electron energies in eV (E = −V: E_c and E_v from the standard levels, E_Fn and E_Fp, or E_F
+ * where only electrons are present, from the levels), with any redox levels and φ (as −qφ) turned
+ * over too. Only electrons and holes have bands; ions are refused (draw them as species voltages).
+ * @param {{ species?: string[], standard?: boolean, phi?: boolean | string[], energy?: boolean,
  *   levels?: { half: { equation: string, fixed?: Record<string, number> }, label?: string, standard?: boolean }[],
  *   labels?: Record<string, string>, shifts?: Record<string, number> }} [opts]
  *   species to show (default: every charged one), whether to show standard levels (default true)
@@ -51,10 +55,11 @@ export function typeset(name: string, z: number): string;
  * @returns {{ x: Float64Array, series: Trace[], regions: { name: string, material: string, x0: number, x1: number }[],
  *   faces: number[], range: [number, number] }}
  */
-export function traces(sol: import("./types.js").Solution, { species, standard, phi, levels, labels, shifts }?: {
+export function traces(sol: import("./types.js").Solution, { species, standard, phi, energy, levels, labels, shifts }?: {
     species?: string[];
     standard?: boolean;
     phi?: boolean | string[];
+    energy?: boolean;
     levels?: {
         half: {
             equation: string;

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)
      */