driftlet 1.0.0 → 1.0.1

package/README.md

@@ -56,7 +56,7 @@ import { bandDiagram } from 'driftlet/plot';    // a level diagram as an SVG str
 ```
 
 Or straight from a CDN in a page, pinned to a version:
-`https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/index.js` (and `src/kit.js`, `src/plot.js`).
+`https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js` (and `src/kit.js`, `src/plot.js`).
 TypeScript declarations ship in the package. Writing a demo with an LLM agent? Point it at
 [`llms.txt`](llms.txt).
 

package/docs/device.md

@@ -479,10 +479,10 @@ contacts: {
 - `{ type: 'exchange', k, mu }` (neutral species):
   $`N_{\mathrm{in}} = k \cdot (\mu_{\mathrm{out}} - \mu)/RT`$, k in mol/(m²·s).
 - `{ type: 'velocity', v, offset }` (or `mu`, for a neutral species): a surface velocity,
-  $`N_{\mathrm{in}} = v\,(c_{\mathrm{eq}} - c)`$ with v in m/s and $`c_{\mathrm{eq}}`$ the end node's
-  concentration in equilibrium with the outside level, i.e.
-  $`v\,c\,(e^{(\bar\mu_{\mathrm{out}} - \bar\mu)/RT} - 1)`$, which keeps the flux's sign that of the
-  level difference whatever the statistics. It lies between `'blocked'` (v → 0) and
+  $`N_{\mathrm{in}} = v\,c\,(e^{(\bar\mu_{\mathrm{out}} - \bar\mu)/RT} - 1)`$ with v in m/s: for dilute
+  species that's $`v\,(c_{\mathrm{eq}} - c)`$, $`c_{\mathrm{eq}}`$ the end node's concentration in
+  equilibrium with the outside level, and with any statistics it keeps the flux's sign that of
+  the level difference (though it isn't then $`v\,(c_{\mathrm{eq}} - c)`$, which saturates). It lies between `'blocked'` (v → 0) and
   `'equilibrium'` (v → ∞): a contact's surface recombination velocity, or thermionic emission
   over a Schottky barrier (below).
 - `'blocked'`: no flux.
@@ -666,10 +666,16 @@ An electrode port can carry species on its surface, sharing its sites: an adsorb
 or a passive film taken as a coverage. Each has a coverage $`\theta`$ at every node of the window,
 Langmuir statistics, $`\mu = \mu^\circ + RT\ln(\theta/\theta_0)`$ with $`\theta_0 = 1 - \sum\theta`$ the
 bare fraction, and `capacity` $`\Gamma`$, mol of sites per m² of electrode. Reactions name them like
-species, and a reaction with `bare: true` runs only on bare metal: its rate is multiplied by
-$`\theta_0`$, both ways, so equilibrium stays exact. Written for adsorption itself, that's Langmuir
-kinetics (on at a rate ∝ $`\theta_0`$, off ∝ $`\theta`$). A species' `theta0` is its starting
-coverage (not the bare fraction). Surface species carry no charge, so an adsorbed redox couple
+species, and their kinetics are Langmuir: in the Butler–Volmer prefactor each surface species
+counts at its coverage $`\theta`$ (as a solution species does at $`c/c_{\mathrm{ref}}`$), and a reaction
+that fills $`\Delta`$ sites going forward holds $`m = \max(\Delta, 0)`$ bare ones in its transition
+state, so its forward rate goes as $`\theta_0^{\,m}`$ and its backward as $`\theta_0^{\,m-\Delta}`$.
+Adsorption goes on at a rate ∝ $`\theta_0`$ and off ∝ $`\theta`$, an adsorbed couple converts at a
+rate ∝ its coverage, and $`2\mathrm{H_{ads}} \to \mathrm{H_2}`$ goes as $`\theta_H^2`$ and back as
+$`\theta_0^2`$. A reaction with `bare: true` runs only on bare metal, needing a bare site even
+where it fills none ($`m \ge 1`$): a metal dissolving, blocked by a film. Equilibrium is exact
+throughout, from the affinity. A species' `theta0` is its starting coverage (not the bare
+fraction). Surface species carry no charge, so an adsorbed redox couple
 balances its electrons through the solution: `'Oads + e- = Rads + Cl-'`, its coverages at
 $`\theta_O/\theta_R = e^{(E - E^\circ)/V_T}`$ against the chloride's level.
 
@@ -679,7 +685,7 @@ ports: [{
   surface: { 'Fe(OH)2': { mu0: -490e3, capacity: 2e-5, theta0: 1e-6 } }, // theta0: the start
   reactions: [
     { equation: 'Fe2+ + 2 e- = Fe(s)', fixed: { 'Fe(s)': 0 }, k0: 5e-6, alpha: 0.5, bare: true },  // dissolves where bare
-    { equation: 'Fe(s) + 2 OH- = Fe(OH)2 + 2 e-', fixed: { 'Fe(s)': 0 }, k0: 1e-4, alpha: 0.5, bare: true }, // the film forms (in minutes)
+    { equation: 'Fe(s) + 2 OH- = Fe(OH)2 + 2 e-', fixed: { 'Fe(s)': 0 }, k0: 1e-4, alpha: 0.5 }, // the film forms (in minutes), on bare sites
     { equation: 'O2 + 2 H2O + 4 e- = 4 OH-', fixed: { H2O: -237.13e3 }, k0: 3e-9, alpha: 0.125 }, // on film or not
   ],
 }]

package/llms.txt

@@ -30,9 +30,9 @@ materials, insertion hosts), data.md and reliability.md (what's validated, and t
 From a CDN, pin the version you tested against:
 
 ```js nocheck
-import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/plot.js';
+import { Device, units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
 ```
 
 From npm: `driftlet`, `driftlet/kit`, `driftlet/plot`. Every export is listed at the end.
@@ -209,9 +209,9 @@ a CDN needs a long virtual-time budget, 30 s.)
 <span id="readout"></span>
 <div id="figure"></div>
 <script type="module">
-import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/index.js';
-import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/kit.js';
-import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.0/src/plot.js';
+import { units } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/index.js';
+import { build, layer, ohmic, semiconductor, live } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/kit.js';
+import { bandDiagram } from 'https://cdn.jsdelivr.net/npm/driftlet@1.0.1/src/plot.js';
 
 const def = build({
   T: 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftlet",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Dependency-free 1D drift–diffusion–reaction (Poisson–Nernst–Planck) solver for semiconductors, electrochemistry and nerves, fast enough for live web demos",
   "type": "module",
   "exports": {

package/src/device.js

@@ -355,8 +355,8 @@ export function normalizeDevice(def) {
   // A contact that passes nothing can't be driven by a current.
   for (const side of ['left', 'right']) {
     const ct = contacts[side];
-    const passes = ct.species.some((l) => l.type !== 'blocked') || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
-    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked species, no gate)`);
+    const passes = ct.species.some((l, i) => l.type !== 'blocked' && species[i].z !== 0) || ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
+    need(passes || ct.drive.kind === 'V', `contacts.${side}.I: this contact passes no current (no linked charged species, no gate)`);
     ct.passes = passes;
   }
   checkLevel(terminals.map((t) => t.drive), terminals.map((t) => (t.kind === 'port' ? ports[t.index] : contacts[t.side])));
@@ -889,7 +889,13 @@ function portReactions(pdef, path, mat, terminal, species, speciesIndex, RT, sur
     need(part.some((p) => p.side === 0 || p.side === 2), `${rpath}: no species of the port's region or its surface takes part`);
     need(charge === 0, `${rpath}: charge is not balanced (Σ ν z = ${charge})`);
     need(rdef.bare === undefined || typeof rdef.bare === 'boolean', `${rpath}.bare must be true or false`);
-    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha: transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare: rdef.bare === true };
+    const alpha = transferCoefficient(rdef.alpha, `${rpath}.alpha`), bare = rdef.bare === true;
+    // Langmuir sites: the reaction fills Δ of them going forward, and its transition state holds
+    // m bare ones (those it fills, or one if it runs only on bare metal), so the forward rate
+    // goes as θ₀^m and the backward as θ₀^(m−Δ): the prefactor's θ₀^(m(1−α)+(m−Δ)α), with each
+    // surface species at its coverage θ.
+    const fills = part.reduce((t, p) => t + (p.side === 2 ? p.nu : 0), 0), m = Math.max(fills, 0, bare ? 1 : 0);
+    return { part, fixedA, k0: positive(rdef.k0, `${rpath}.k0 (mol/(m²·s))`), alpha, bare, sites: m * (1 - alpha) + (m - fills) * alpha };
   });
 }
 

package/src/polarization.js

@@ -115,10 +115,10 @@ export function polarization(device, sol, where, V, opts = {}) {
   const out = parts.map(({ rx, k, base, s, q, pref, surf }) => {
     const rate = Float64Array.from(Vs, (v, j) => {
       const { lnA, bare } = at[j];
-      let a = base + s * v, p = pref * (rx.bare ? bare : 1);
+      let a = base + s * v, p = pref * (rx.sites ? powr(bare, rx.sites) : 1);
       for (const u of surf) {
         a -= u.nu * lnA[u.s];
-        p *= Math.exp(u.e * lnA[u.s]);
+        p *= Math.exp(u.e * lnA[u.s]) * powr(bare, u.e); // its coverage θ = θ₀ a
       }
       return rx.vmax ? p * -Math.expm1(-a) : p * (Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a));
     });

package/src/solver.js

@@ -373,7 +373,8 @@ export class Solver {
     // φ is undefined in a conductor or an insertion host, and in a charge-free region (no
     // charged species) unless its electrostatic cluster, the regions joined to it by faces that
     // aren't neutral, reaches something that fixes φ: a region with charged species, a gate or
-    // pinned contact, or a capacitive face to a conductor. (Else φ there is a free constant.)
+    // pinned contact, or a face that isn't neutral to a conductor or to a strictly neutral region
+    // with ions. (Else φ there is a free constant.)
     this.phiUndefined = new Uint8Array(nNodes);
     const charged = (mat) => species.some((sp, i) => mat.present[i] && sp.z !== 0);
     const pins = (ct) => ct.phi.type === 'capacitive' || ct.phi.type === 'pinned';
@@ -385,8 +386,11 @@ export class Solver {
       while (r1 + 1 < regions.length && model.interfaces[r1].phi.type !== 'neutral' && !free(r1 + 1)) r1++;
       let anchor = (r0 === 0 && pins(contacts.left)) || (r1 === regions.length - 1 && pins(contacts.right));
       for (let r = r0; r <= r1; r++) if (charged(materials[regions[r].material])) anchor = true;
-      if (r0 > 0 && model.interfaces[r0 - 1].phi.type !== 'neutral' && materials[regions[r0 - 1].material].conductor) anchor = true;
-      if (r1 < regions.length - 1 && model.interfaces[r1].phi.type !== 'neutral' && materials[regions[r1 + 1].material].conductor) anchor = true;
+      // A neighbour across a face that isn't neutral: a conductor (a gate), or a strictly neutral
+      // region whose ions fix its φ.
+      const fixes = (r) => materials[regions[r].material].conductor || (!materials[regions[r].material].phiFree && charged(materials[regions[r].material]));
+      if (r0 > 0 && model.interfaces[r0 - 1].phi.type !== 'neutral' && fixes(r0 - 1)) anchor = true;
+      if (r1 < regions.length - 1 && model.interfaces[r1].phi.type !== 'neutral' && fixes(r1 + 1)) anchor = true;
       for (let r = r0; r <= r1; r++) anchored[r] = anchor ? 1 : 2;
       r0 = r1;
     }
@@ -585,6 +589,16 @@ export class Solver {
       const mat = materials[regions[grid.nodeRegion[g]].material], law = contacts[k === 0 ? 'left' : 'right'].phi.type;
       if (!mat.conductor && mat.epsr === 0 && (law === 'bulk' || law === 'neutral') && !this.chargeNode[g] && !this.phiUndefined[g] && this.nodeIdeal[g]) this.lateStorage[g] = 1;
     });
+    // An end node's species held by a port (its contact blocks it, so the level is the port's):
+    // its row is the port's, storage and all, and the contact passes none of it.
+    this.portHeldEnd = new Uint8Array(2 * n);
+    model.ports.forEach((port) => {
+      [0, nNodes - 1].forEach((g, k) => {
+        if (!port.nodes.includes(g)) return;
+        const ct = contacts[k === 0 ? 'left' : 'right'];
+        for (let i = 0; i < n; i++) if (port.species[i].type === 'equilibrium' && ct.species[i].type === 'blocked') this.portHeldEnd[k * n + i] = 1;
+      });
+    });
     this.combining = false;
     this.bookkeeping = regions.map((_, r) => {
       const g0 = grid.regionStart[r], g1 = grid.regionEnd[r], nodes = [], segs = [];
@@ -1895,6 +1909,14 @@ export class Solver {
     // toward their mixed potential.
     for (const k of this.floating) {
       const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      const gate = t.kind === 'contact' ? model.contacts[t.side].phi : null;
+      if (gate?.type === 'capacitive') {
+        // A gate contact likewise: at its zero-charge level from the φ beside it (a pinned
+        // one's charge is the field's, already zero against a neutral start).
+        const g = t.side === 'left' ? 0 : this.nNodes - 1;
+        if (!this.phiUndefined[g]) this.termV[k] = gate.zeroCharge + this.VT * u[this.blockOfNode[g] * M];
+        continue;
+      }
       if (!port?.capacitance) continue;
       let w = 0, sum = 0;
       port.nodes.forEach((g, j) => {
@@ -1968,9 +1990,9 @@ export class Solver {
       }
       const o = b * M + (p.side === 2 ? 1 + n + p.s : 1 + p.i), e = p.nu < 0 ? -p.nu * (1 - rx.alpha) : p.nu * rx.alpha;
       a -= p.nu * (u[o] + uLo[o]);
-      pref *= p.side === 2 ? Math.exp(e * (u[o] + uLo[o] - port.surface[p.s].mu0 / RT)) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
+      pref *= p.side === 2 ? powr(th[g * nSurf + p.s], e) : powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
     }
-    if (rx.bare) pref *= this.th0[g];
+    if (rx.sites) pref *= powr(this.th0[g], rx.sites);
     return pref * bvFactor(a, rx.alpha).g;
   }
 
@@ -2193,6 +2215,11 @@ export class Solver {
     if (f >= 0) this._j(b, r, this.blockOfFace[f], 0, (this.sheetSign[g] * this.model.grid.area[g]) / (z[im] * FARADAY * dt));
   }
 
+  // Whether a port holds species i at node g, a device end node (see portHeldEnd).
+  _portHeldAt(g, i) {
+    return g === 0 ? this.portHeldEnd[i] === 1 : g === this.nNodes - 1 && this.portHeldEnd[this.n + i] === 1;
+  }
+
   // Dilute nodes g0…g1 (ideal statistics, c = c_ref e^ζ): storage of each species and the space
   // charge in the Gauss row, written straight into the diagonal blocks by local index. A
   // dielectric is the case with no species.
@@ -2212,7 +2239,7 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         const k = g * n + i;
         if (!present[k]) continue;
-        const ck = c[k], l = loc[lb + 1 + i], stores = !(late && z[i] !== 0);
+        const ck = c[k], l = loc[lb + 1 + i], stores = !(late && z[i] !== 0 && !this._portHeldAt(g, i));
         if (stores) res[R[lb + 1 + i]] += (v * (ck - cOld[k])) / dt;
         q += F * z[i] * ck;
         dq += F * z[i] * z[i] * ck;
@@ -3093,18 +3120,19 @@ export class Solver {
         aLo -= p.nu * uLo[o];
         const e = p.nu < 0 ? -p.nu * (1 - al) : p.nu * al;
         if (p.side === 2) {
-          // a surface species at activity θ/θ₀ = e^ζ
-          pref *= Math.exp(e * (u[o] + uLo[o] - surf[p.s].mu0 / RT));
+          // a surface species at its coverage θ = θ₀e^ζ, with ∂ln θ_s/∂η_x = δ_sx − θ_x
+          pref *= powr(th[g * nSurf + p.s], e);
           d[1 + n + p.s] += e;
+          for (let x = 0; x < surf.length; x++) d[1 + n + x] -= e * th[g * nSurf + x];
         } else {
           pref *= powr(c[g * n + p.i] / this.cRef[g * n + p.i], e);
           this._dlnc(g, p.i, e, d);
         }
       }
-      if (rx.bare) {
-        // on bare metal only: the free fraction θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
-        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= th[g * nSurf + x];
-        pref *= this.th0[g];
+      if (rx.sites) {
+        // the bare sites its transition state holds: θ₀ = 1 − Σθ, with ∂ln θ₀/∂η_s = −θ_s
+        for (let x = 0; x < surf.length; x++) d[1 + n + x] -= rx.sites * th[g * nSurf + x];
+        pref *= powr(this.th0[g], rx.sites);
       }
       const { g: bv, gp } = bvFactor(aHi + aLo, al);
       const rate = pref * bv;
@@ -3236,8 +3264,9 @@ export class Solver {
     // passes, so their flux is zero.)
     const closedIons = this.combining && dyn && this.chargeNode[g] === 1;
     let I = 0;
+    const held = this.portHeldEnd.subarray(k * n, (k + 1) * n);
     for (let i = 0; i < n; i++) {
-      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0);
+      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0) && !held[i];
       const nIn = active ? res[R[b * M + 1 + i]] : 0;
       flux[i] = sgn * nIn; // (toward +x)
       if (active && z[i] !== 0) {
@@ -3250,7 +3279,7 @@ export class Solver {
     if (this.combining && dyn && this.lateStorage[g] === 1) {
       const v = model.grid.vol[g], { cOld } = this;
       for (let i = 0; i < n; i++) {
-        if (z[i] === 0 || this.loc[b * M + 1 + i] < 0) continue;
+        if (z[i] === 0 || this.loc[b * M + 1 + i] < 0 || held[i]) continue;
         const ci = c[g * n + i], st = (v * (ci - cOld[g * n + i])) / dt;
         res[R[b * M + 1 + i]] += st;
         flux[i] += sgn * st;
@@ -4866,6 +4895,11 @@ export class Solver {
         }
         mu[name].re[g] = RT * xr[b * M + 1 + i];
         mu[name].im[g] = RT * xi[b * M + 1 + i];
+        if (this.nodeConductor[g] >= 0) {
+          // a metal has a Fermi level but no concentration (as a solution reports it)
+          c[name].re[g] = c[name].im[g] = NaN;
+          continue;
+        }
         // δc_i = Σ_j K_ij (δη_j − z_j δφ̂)
         let sr = 0, si = 0;
         for (let j = 0; j < n; j++) {

package/src/types.js

@@ -163,7 +163,8 @@
  *   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 − Σθ
+ *   shared; reactions run on Langmuir sites (what fills sites needs bare ones), and one with `bare: true`
+ *   needs a bare site even if it fills none (θ₀ = 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

package/types/solver.d.ts

@@ -115,6 +115,7 @@ export class Solver {
     chargeNode: Uint8Array<any>;
     chargeNodes: Int32Array<ArrayBuffer>;
     lateStorage: Uint8Array<any>;
+    portHeldEnd: Uint8Array<ArrayBuffer>;
     combining: boolean;
     bookkeeping: any;
     bookkeepingFaces: number[];
@@ -209,6 +210,7 @@ export class Solver {
     dtNow: any;
     transformed: any;
     _nodeConductor(g: any, dt: any): void;
+    _portHeldAt(g: any, i: any): boolean;
     _nodesDilute(g0: any, g1: any, dt: any): void;
     _nodeConcentrated(g: any, dt: any): void;
     _storage(g: any, i: any, dt: any, Kz?: number): void;

package/types/types.d.ts

@@ -390,7 +390,8 @@ export type PortDef = {
     /**
      * 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 − Σθ
+     * shared; reactions run on Langmuir sites (what fills sites needs bare ones), and one with `bare: true`
+     * needs a bare site even if it fills none (θ₀ = 1 − Σθ)
      */
     surface?: Record<string, {
         mu0: number;