driftlet 0.7.0 → 0.8.0

package/types/grid.d.ts

@@ -26,3 +26,32 @@ export function buildGrid(regions: {
     regionEnd: Int32Array<ArrayBuffer>;
     length: number;
 };
+/**
+ * Give a grid its cross-section: `area` (A at each node, m²), `segArea` (each segment's
+ * effective area, its length over ∫dx/A, so that a flux D·segArea·Δc/h is exact for steady
+ * diffusion between the nodes; A at its middle where A vanishes at an end, as at a sphere's
+ * centre) and `vol` (each node's box, ∫A dx). Planar (no geometry): A = 1, and nothing changes.
+ * @param {ReturnType<typeof buildGrid>} grid
+ * @param {{ type: 'planar' } | { type: 'spherical' | 'cylindrical', r0: number } | { type: 'profile', x: ArrayLike<number>, values: ArrayLike<number> }} geometry
+ */
+export function applyGeometry(grid: ReturnType<typeof buildGrid>, geometry: {
+    type: "planar";
+} | {
+    type: "spherical" | "cylindrical";
+    r0: number;
+} | {
+    type: "profile";
+    x: ArrayLike<number>;
+    values: ArrayLike<number>;
+}): {
+    nNodes: number;
+    x: Float64Array<ArrayBuffer>;
+    nodeRegion: Int32Array<ArrayBuffer>;
+    segLength: Float64Array<ArrayBuffer>;
+    segRegion: Int32Array<ArrayBuffer>;
+    segFace: Int32Array<ArrayBuffer>;
+    vol: Float64Array<ArrayBuffer>;
+    regionStart: Int32Array<ArrayBuffer>;
+    regionEnd: Int32Array<ArrayBuffer>;
+    length: number;
+};

package/types/kit.d.ts

@@ -36,6 +36,7 @@ export function vacuumZeroCharge(def: object, workFunction: number, inside: Vacu
 export { live } from "./live.js";
 export { recorder } from "./recorder.js";
 export { check } from "./checks.js";
+export { polarization } from "./polarization.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

package/types/polarization.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Each electrode reaction's rate at a face (a metal's) or at one spot of an electrode port, with
+ * the composition beside it as in `sol` and the metal's carrier at each level in `V` (in the
+ * terminals' convention, V = μ̄/(zF); against SHE, subtract φ for the usual tables' ions). The
+ * rates are the solver's own law, so at the electrode's actual level they are
+ * `sol.interfaces[f].rates` (or `sol.ports[k].rates` at that node).
+ * @param {import('./index.js').Device} device
+ * @param {object} sol a solution of it
+ * @param {{ face: number } | { port: string | number, x?: number }} where a face's index, or a port
+ *   (name or index) and the position in its window (m, the device's x; default its first node)
+ * @param {number | ArrayLike<number>} V the metal's level(s), V
+ * @returns {{ V: Float64Array, current: Float64Array, reactions: { equation: string, level: number,
+ *   rate: Float64Array, current: Float64Array }[] }} per reaction: its equilibrium level here (where
+ *   its rate is zero), its rate (mol/(m²·s) of electrode, forward) and its current (A/m², anodic
+ *   positive: into the solution); and their sum
+ */
+export function polarization(device: import("./index.js").Device, sol: object, where: {
+    face: number;
+} | {
+    port: string | number;
+    x?: number;
+}, V: number | ArrayLike<number>): {
+    V: Float64Array;
+    current: Float64Array;
+    reactions: {
+        equation: string;
+        level: number;
+        rate: Float64Array;
+        current: Float64Array;
+    }[];
+};

package/types/solver.d.ts

@@ -77,6 +77,8 @@ export class Solver {
     history: any[];
     dtNext: any;
     rxs: any;
+    portArea: any;
+    portRates: any;
     strictlyNeutral: any;
     generationScale: number;
     hasGeneration: any;
@@ -119,7 +121,7 @@ export class Solver {
     redrive(): void;
     deltaV: Float64Array<any>;
     _refreshSources(): void;
-    /** η_i (μ̄/RT) of a port's outside level for species i. */
+    /** η_i (μ̄/RT) of a port's outside level for species i (its electrode's carrier: at V itself). */
     portEta(port: any, i: any): number;
     /** η_i/RT that a fixed contact link imposes (or NaN if the link isn't fixed). */
     contactEta(side: any, i: any): number;
@@ -129,6 +131,7 @@ export class Solver {
      * profile varies), or continued across the interface dipole if nothing there responds.
      */
     initFromComposition(): void;
+    _portRate(port: any, rx: any, g: any): number;
     _materialAt(mat: any, background: any, eta: any, mode: any, cFix: any, ph: any, zeta: any, cc: any): void;
     computeConcentrations(): void;
     _work(md: any): any;
@@ -165,11 +168,12 @@ export class Solver {
         Cp: number;
         Ca: number;
     };
-    _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any): void;
+    _faceReaction(rx: any, k: any, f: any, bf: any, bL: any, bR: any, Af: any): void;
     _terminals(dt: any): void;
     _circuit(k: any): void;
     _captureRow(b: any, s: any, w: any, into: any): number;
     _port(port: any, flux: any, k: any): void;
+    _portReaction(port: any, rx: any, area: any, rates: any, flux: any, k: any): void;
     _contact(side: any, dt: any): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;

package/types/types.d.ts

@@ -354,10 +354,10 @@ export type PortDef = {
      */
     R?: number;
     /**
-     * species whose offset defaults to 0
+     * species whose offset defaults to 0; with reactions, the electrode's carrier
      */
     terminal?: string;
-    species: Record<string, "blocked" | "equilibrium" | {
+    species?: Record<string, "blocked" | "equilibrium" | {
         type: "equilibrium";
         offset?: number;
         mu?: number;
@@ -370,6 +370,25 @@ export type PortDef = {
         k: number;
         mu: 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
+     */
+    reactions?: {
+        equation: string;
+        fixed?: Record<string, number>;
+        k0: number;
+        alpha: number;
+    }[];
+    /**
+     * with reactions: electrode area per volume,
+     * m²/m³ (1/h for a film of thickness h), or a profile against the device's x
+     */
+    area?: number | {
+        x: number[];
+        values: number[];
+    };
 };
 /**
  * A device definition: plain, serialisable data.
@@ -398,6 +417,20 @@ export type DeviceDefinition = {
      * internal ports
      */
     ports?: PortDef[];
+    /**
+     * the cross-section A(x): planar (A = 1 m², the
+     * default: currents read per m²), shells about a centre at r = r0 (m) left of x = 0 (cylindrical: per
+     * metre of length), or A in m² against x. Currents, fluxes, amounts and charges are then totals through A.
+     */
+    geometry?: "planar" | "spherical" | "cylindrical" | {
+        type: "planar" | "spherical" | "cylindrical";
+        r0?: number;
+    } | {
+        area: {
+            x: number[];
+            values: number[];
+        };
+    };
     grid?: GridOptions;
 };
 export type ContactResult = {
@@ -500,14 +533,18 @@ export type Solution = {
         };
     };
     /**
-     * what each
-     * internal port brings into the device
+     * 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)
      */
     ports: {
         name: string;
         V: number;
         flux: Record<string, number>;
         current: number;
+        x?: Float64Array;
+        area?: Float64Array;
+        rates?: Float64Array[];
     }[];
     interfaces: {
         left: string;