driftlet 0.8.0 → 0.10.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

@@ -157,10 +157,16 @@
  * @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]
- * @property {{ equation: string, fixed?: Record<string, number>, k0: number, alpha: number }[]} [reactions] an
+ * @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 {number | { x: number[], values: number[] }} [area] with reactions: electrode area per volume,
+ * @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
  */
 
@@ -191,6 +197,10 @@
  */
 
 /**
+ * The device's totals through its cross-section (currents, fluxes through contacts and ports,
+ * charges, amounts, reaction totals, impedance) are per m² of a planar device, as below, and
+ * whole (A, mol/s, C, mol, Ω; per metre of a cylinder) for one with a `geometry`. Rates at a
+ * face or an electrode are always per m² of it.
  * @typedef {object} Solution
  * @property {Float64Array} x node positions, m (interface positions appear twice)
  * @property {Int32Array} region region index per node
@@ -209,7 +219,8 @@
  * @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, x?: Float64Array,
- *   area?: Float64Array, rates?: Float64Array[] }[]} ports what each internal port brings into the device;
+ *   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

package/types/checks.d.ts

@@ -13,9 +13,9 @@
  * - **warnings**: the solution's warnings (unresolved double layers, steep profiles, weakly held
  *   parts) and the definition's likely unit slips.
  * - **balance** (a steady state): each species' ledger, what comes in through each terminal and
- *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) and, for a charged
- *   species, as a current F·|z|·rate. The terms must sum to zero; under light it's J = F(G − R),
- *   and it says where every carrier went.
+ *   what each reaction (bulk or at a face) makes or uses, in mol/(m²·s) (mol/s if the device
+ *   isn't planar) and, for a charged species, as a current F·|z|·rate. The terms must sum to
+ *   zero; under light it's J = F(G − R), and it says where every carrier went.
  * - **conservation** (a transient): every closed, unreacting stretch keeps what it held plus
  *   what came in.
  * - **grid** (a steady state, with `refine`, the default): the device solved again on a grid

package/types/index.d.ts

@@ -93,6 +93,7 @@ export class Device {
         snap: any;
         solvedV: any;
         referenceAmounts: any;
+        surfaceRef: any;
     };
     /**
      * Back to a checkpoint taken on this device.

package/types/live.d.ts

@@ -48,6 +48,7 @@ export class Session {
             snap: any;
             solvedV: any;
             referenceAmounts: any;
+            surfaceRef: any;
         };
         sol: import("./types.js").Solution;
     };

package/types/polarization.d.ts

@@ -9,7 +9,10 @@
  * @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,
+ * @param {{ surface?: 'held' | 'equilibrium' }} [opts] an electrode port's surface coverages: held as
+ *   in `sol` (the default: this instant's curves), or in equilibrium at each V (the steady-state
+ *   curve, with a passive film's active–passive peak), each species by the reaction that makes it
+ * @returns {{ V: Float64Array, current: Float64Array, bare?: 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
@@ -19,9 +22,12 @@ export function polarization(device: import("./index.js").Device, sol: object, w
 } | {
     port: string | number;
     x?: number;
-}, V: number | ArrayLike<number>): {
+}, V: number | ArrayLike<number>, opts?: {
+    surface?: "held" | "equilibrium";
+}): {
     V: Float64Array;
     current: Float64Array;
+    bare?: Float64Array;
     reactions: {
         equation: string;
         level: number;

package/types/solver.d.ts

@@ -8,12 +8,21 @@ 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>;
+    surfCols: any;
+    surfColOf: any;
+    th: Float64Array<ArrayBuffer>;
+    thOld: Float64Array<ArrayBuffer>;
+    th0: Float64Array<any>;
+    th0Old: Float64Array<any>;
     present: Uint8Array<ArrayBuffer>;
     cRef: Float64Array<ArrayBuffer>;
     mu0hat: Float64Array<ArrayBuffer>;
@@ -54,6 +63,13 @@ export class Solver {
         left: number;
         right: number;
     };
+    portQ: Float64Array<any>;
+    portQStart: Float64Array<any>;
+    portQOld: Float64Array<any>;
+    portQEnd: any;
+    qg: Float64Array<any>;
+    qgSlope: Float64Array<any>;
+    qgTerms: any[][];
     contactDOld: {
         left: number;
         right: number;
@@ -83,12 +99,17 @@ export class Solver {
     generationScale: number;
     hasGeneration: any;
     rxsIn: any;
+    closedEnd: {
+        left: any;
+        right: any;
+    };
     chargeNode: Uint8Array<any>;
     chargeNodes: Int32Array<ArrayBuffer>;
     combining: boolean;
     bookkeeping: any;
     bookkeepingFaces: number[];
     referenceAmounts: number[];
+    surfaceRef: Float64Array<ArrayBuffer>;
     boundaryIntake: Float64Array<ArrayBuffer>;
     _activeSlots(): void;
     active: Uint8Array<ArrayBuffer>;
@@ -104,18 +125,20 @@ export class Solver {
     _findStretches(): void;
     stretches: any[];
     stretchOf: Int32Array<ArrayBuffer>;
-    moieties: Float64Array<ArrayBuffer>[];
+    moieties: Float64Array<any>[];
     constraints: any[];
     localConstraints: any[];
     constrained: boolean;
     _captureLocal(): void;
     _applyLocalConstraints(): void;
-    _conservedMoieties(): Float64Array<ArrayBuffer>[];
+    _conservedMoieties(): Float64Array<any>[];
     _directSteady(): boolean;
     _applyConstraints(): void;
     _solveBordered(rhs: any, delta: any, deltaV: any, pins: any): void;
     dWork: Float64Array<ArrayBuffer>;
     borderCols: any[];
+    /** Amount (mol per unit area) of surface column j's species, Γ Σ v·a·θ, in the current state. */
+    surfaceAmount(j: any): number;
     /** Total amount (mol per unit area) of a stretch's species in the current state. */
     amount(stretch: any): number;
     redrive(): void;
@@ -133,6 +156,7 @@ export class Solver {
     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;
@@ -172,8 +196,10 @@ export class Solver {
     _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, holds: 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;
@@ -222,7 +248,7 @@ export class Solver {
     /**
      * Adaptive time stepping to tEnd: variable-step BDF2 (or backward Euler), with the local error
      * estimated against an explicit predictor through the previous states, and controlled to
-     * `tol` thermal units per step in every potential (φ̂, each η, a floating terminal). The first
+     * `tol` thermal units per step in every potential (φ̂, each η, a surface's coverages as η). The first
      * step is checked by step doubling. Stops early when `budgetMs` of wall time is used, so an
      * animation can call it once per frame; the step size carries over between calls.
      */
@@ -257,6 +283,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;
@@ -269,6 +297,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

@@ -380,9 +380,29 @@ export type PortDef = {
         fixed?: Record<string, number>;
         k0: number;
         alpha: number;
+        bare?: boolean;
     }[];
     /**
-     * with reactions: electrode area per volume,
+     * 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 | {
@@ -451,6 +471,12 @@ export type ContactResult = {
      */
     current: number;
 };
+/**
+ * The device's totals through its cross-section (currents, fluxes through contacts and ports,
+ * charges, amounts, reaction totals, impedance) are per m² of a planar device, as below, and
+ * whole (A, mol/s, C, mol, Ω; per metre of a cylinder) for one with a `geometry`. Rates at a
+ * face or an electrode are always per m² of it.
+ */
 export type Solution = {
     /**
      * node positions, m (interface positions appear twice)
@@ -545,6 +571,10 @@ export type Solution = {
         x?: Float64Array;
         area?: Float64Array;
         rates?: Float64Array[];
+        coverage?: Record<string, Float64Array>;
+        bare?: Float64Array;
+        sigma?: Float64Array;
+        charge?: number;
     }[];
     interfaces: {
         left: string;