driftlet 0.7.0 → 0.9.0

package/src/stack.js

@@ -100,7 +100,7 @@ export function bath(c, reference, d = 0, { offset } = {}) {
   return { ...drive(d, 'bath'), bath: { c: { ...c }, reference, ...(offset === undefined ? {} : { offset }) } };
 }
 
-const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReactions', 'ports', 'grid'];
+const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReactions', 'ports', 'grid', 'geometry'];
 
 /**
  * Build a plain device definition from a stack:
@@ -112,7 +112,7 @@ const STACK_FIELDS = ['T', 'library', 'species', 'materials', 'stack', 'bulkReac
  *   between them get the default face. Nested lists are flattened.
  * - Layers may give doping as `donors` and `acceptors` (mol/m³) in place of `fixedCharge`.
  * - `library`: pieces with species and materials, merged with `species` and `materials`.
- * - `T`, `grid`, `ports` pass through.
+ * - `T`, `grid`, `ports`, `geometry` pass through.
  * @param {object} def
  * @returns {object} a device definition for `new Device`
  */
@@ -168,5 +168,6 @@ export function build(def) {
   if (def.bulkReactions !== undefined) out.bulkReactions = def.bulkReactions;
   if (def.ports !== undefined) out.ports = def.ports;
   if (def.grid !== undefined) out.grid = def.grid;
+  if (def.geometry !== undefined) out.geometry = def.geometry;
   return out;
 }

package/src/types.js

@@ -154,9 +154,20 @@
  * @property {Source} [V] held terminal voltage, V (default 0, if no I)
  * @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
+ * @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
+ *   | { 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, { 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; a reaction with `bare: true` runs only on the bare fraction θ₀ = 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
  */
 
 /**
@@ -170,6 +181,10 @@
  * @property {BulkReactionDef[]} [bulkReactions]
  * @property {{ left?: ContactDef, right?: ContactDef }} [contacts]
  * @property {PortDef[]} [ports] internal ports
+ * @property {'planar' | 'spherical' | 'cylindrical' | { type: 'planar' | 'spherical' | 'cylindrical', r0?: number }
+ *   | { area: { x: number[], values: number[] } }} [geometry] 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.
  * @property {GridOptions} [grid]
  */
 
@@ -199,8 +214,11 @@
  *   then the ports by name): its voltage, and its current into the device (A/m²)
  * @property {{ left: ContactResult, right: ContactResult }} contacts
  * @property {{ left?: { V: number, D: number, charge: number }, right?: { V: number, D: number, charge: number } }} gates
- * @property {{ name: string, V: number, flux: Record<string, number>, current: number }[]} ports what each
- *   internal port brings into the device
+ * @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))

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

@@ -8,12 +8,19 @@ export class Solver {
     n: any;
     M: any;
     nRx: any;
+    nSurf: any;
     nNodes: any;
     nFaces: number;
     nB: any;
     VT: number;
     blockOfNode: Int32Array<any>;
     blockOfFace: Int32Array<ArrayBuffer>;
+    surfPort: Int32Array<any>;
+    surfW: Int32Array<any>;
+    th: Float64Array<ArrayBuffer>;
+    thOld: Float64Array<ArrayBuffer>;
+    th0: Float64Array<any>;
+    th0Old: Float64Array<any>;
     present: Uint8Array<ArrayBuffer>;
     cRef: Float64Array<ArrayBuffer>;
     mu0hat: Float64Array<ArrayBuffer>;
@@ -54,6 +61,10 @@ export class Solver {
         left: number;
         right: number;
     };
+    portQ: Float64Array<any>;
+    portQStart: Float64Array<any>;
+    portQOld: Float64Array<any>;
+    portQEnd: any;
     contactDOld: {
         left: number;
         right: number;
@@ -77,6 +88,8 @@ export class Solver {
     history: any[];
     dtNext: any;
     rxs: any;
+    portArea: any;
+    portRates: any;
     strictlyNeutral: any;
     generationScale: number;
     hasGeneration: any;
@@ -119,7 +132,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,7 +142,9 @@ 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;
+    _coverages(): void;
     computeConcentrations(): void;
     _work(md: any): any;
     _nodeStatistics(g: any, b: any, phiHat: any): void;
@@ -165,11 +180,14 @@ 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;
+    _port(port: any, flux: any, k: any, dt: any): void;
+    _portReaction(port: any, rx: any, area: any, rates: any, flux: any, k: any): void;
+    _portCapacitance(port: any, k: any, dt: any): void;
+    _surfaceStorage(port: any, dt: any): void;
     _contact(side: any, dt: any): void;
     _replaceRow(b: any, rs: any): void;
     _equilibrate(): void;
@@ -253,6 +271,8 @@ export class Solver {
         u: Float64Array<ArrayBuffer>;
         uLo: Float64Array<ArrayBuffer>;
         cOld: Float64Array<ArrayBuffer>;
+        thOld: Float64Array<ArrayBuffer>;
+        th0Old: Float64Array<ArrayBuffer>;
         time: number;
         lastDt: number;
         atSteady: boolean;
@@ -265,6 +285,9 @@ export class Solver {
             right: number;
         };
         contactDEnd: any;
+        portQStart: Float64Array<any>;
+        portQOld: Float64Array<any>;
+        portQEnd: any;
         boundaryIntake: Float64Array<ArrayBuffer>;
         history: any[];
         termV: Float64Array<ArrayBuffer>;

package/types/stack.d.ts

@@ -53,7 +53,7 @@ export function bath(c: Record<string, number>, reference: string, d?: number, {
  *   between them get the default face. Nested lists are flattened.
  * - Layers may give doping as `donors` and `acceptors` (mol/m³) in place of `fixedCharge`.
  * - `library`: pieces with species and materials, merged with `species` and `materials`.
- * - `T`, `grid`, `ports` pass through.
+ * - `T`, `grid`, `ports`, `geometry` pass through.
  * @param {object} def
  * @returns {object} a device definition for `new Device`
  */

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,45 @@ 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;
+        bare?: boolean;
+    }[];
+    /**
+     * with reactions: species
+     * on the electrode's sites, Langmuir (μ = μ° + RT ln(θ/θ₀)), capacity in mol of sites per m² of electrode,
+     * shared; a reaction with `bare: true` runs only on the bare fraction θ₀ = 1 − Σθ
+     */
+    surface?: Record<string, {
+        mu0: number;
+        capacity: number;
+        theta0?: number;
+    }>;
+    /**
+     * 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
+     */
+    capacitance?: {
+        C: number;
+        zeroCharge?: number;
+    };
+    /**
+     * 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
+     */
+    area?: number | {
+        x: number[];
+        values: number[];
+    };
 };
 /**
  * A device definition: plain, serialisable data.
@@ -398,6 +437,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 +553,22 @@ 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[];
+        coverage?: Record<string, Float64Array>;
+        bare?: Float64Array;
+        sigma?: Float64Array;
+        charge?: number;
     }[];
     interfaces: {
         left: string;