driftlet 0.9.0 → 0.10.0

package/src/solver.js

@@ -2,7 +2,9 @@
 // and its derivative g′(a) = α e^{αa} + (1−α) e^{−(1−α)a}.
 function bvFactor(a, alpha) {
   const e = Math.exp(-(1 - alpha) * a);
-  return { g: e * Math.expm1(a), gp: alpha * Math.exp(alpha * a) + (1 - alpha) * e };
+  // (far from equilibrium, the plain difference: the product would give 0·∞ there)
+  const g = Math.abs(a) > 50 ? Math.exp(alpha * a) - e : e * Math.expm1(a);
+  return { g, gp: alpha * Math.exp(alpha * a) + (1 - alpha) * e };
 }
 
 // Solve the K×K complex system (Ar + i Ai) x = (last column), partial pivoting by modulus.
@@ -224,10 +226,14 @@ export class Solver {
     model.ports.forEach((port, k) => {
       if (port.surface.length > 0) port.nodes.forEach((g, w) => ((this.surfPort[g] = k), (this.surfW[g] = w)));
     });
+    // Each surface species of each port, as a column of what's conserved: [port, species].
+    this.surfCols = model.ports.flatMap((port, k) => port.surface.map((_, q) => [k, q]));
+    this.surfColOf = model.ports.map((port, k) => this.surfCols.findIndex(([kk]) => kk === k));
     this.th = new Float64Array(nNodes * nSurf);
     this.thOld = new Float64Array(nNodes * nSurf);
-    this.th0 = new Float64Array(nNodes); // the bare fraction θ₀, directly (1 − Σθ cancels as θ → 1)
-    this.th0Old = new Float64Array(nNodes);
+    // The bare fraction θ₀, directly (1 − Σθ cancels as θ → 1); 1 where there's no surface.
+    this.th0 = new Float64Array(nNodes).fill(1);
+    this.th0Old = new Float64Array(nNodes).fill(1);
 
     // Per-node material data, flattened [g·n + i].
     this.present = new Uint8Array(nNodes * n);
@@ -348,6 +354,13 @@ export class Solver {
     this.portQStart = new Float64Array(model.ports.length);
     this.portQOld = new Float64Array(model.ports.length);
     this.portQEnd = null;
+    // And per node, the charge per volume the capacitances hold against the window (Σ aσ, over
+    // every port with one there: two gates on one channel, say; the ions hold −Σ aσ), its slope
+    // Σ a·C per volt, and the ports [terminal, index in its window].
+    this.qg = new Float64Array(grid.nNodes);
+    this.qgSlope = new Float64Array(grid.nNodes);
+    this.qgTerms = Array.from({ length: grid.nNodes }, () => []);
+    model.ports.forEach((port, k) => port.capacitance && port.nodes.forEach((g, w) => this.qgTerms[g].push([2 + k, w])));
     this.contactDOld = { left: 0, right: 0 };
     this.contactDStart = { left: 0, right: 0 };
     // Terminals (the two contacts, then the ports): each one's voltage (V), held by its source or
@@ -428,11 +441,15 @@ export class Solver {
     // A port that only exchanges (an O₂ supply, a leak) is solved there too: left out, its window
     // fell back on the ill-conditioned terms, and a closed neutral electrolyte whose potential is
     // set only by a face reaction couldn't take a step.
+    // An end node is solved there too if its contact is closed to every ion and leaves φ alone.
     const held = new Uint8Array(nNodes);
-    held[0] = held[nNodes - 1] = 1;
+    const closed = (side) => model.contacts[side].phi.type === 'neutral' && model.contacts[side].species.every((l, i) => species[i].z === 0 ? l.type !== 'equilibrium' : l.type === 'blocked');
+    this.closedEnd = { left: closed('left'), right: closed('right') };
+    held[0] = this.closedEnd.left ? 0 : 1;
+    held[nNodes - 1] = this.closedEnd.right ? 0 : 1;
     for (const port of model.ports) if (port.species.some((l) => l.type === 'equilibrium')) for (const g of port.nodes) held[g] = 1;
     this.chargeNode = new Uint8Array(nNodes);
-    const neutralFace = (f) => f >= 0 && f < model.interfaces.length && model.interfaces[f].phi.type === 'neutral';
+    const neutralFace = (f) => (f === -1 ? this.closedEnd.left : f === model.interfaces.length ? this.closedEnd.right : model.interfaces[f].phi.type === 'neutral');
     regions.forEach((reg, r) => {
       const mat = materials[reg.material];
       if (mat.conductor || mat.epsr !== 0) return;
@@ -456,6 +473,8 @@ export class Solver {
     this._findStretches();
     this.initFromComposition();
     this.referenceAmounts = this.stretches.map((st) => this.amount(st));
+    // And what each surface species held then (a conserved combination through one counts it).
+    this.surfaceRef = Float64Array.from(this.surfCols, (_, j) => this.surfaceAmount(j));
     // ∫ (flux in − flux out) dt through the contacts, per stretch, since the reference.
     this.boundaryIntake = new Float64Array(this.stretches.length);
   }
@@ -582,12 +601,14 @@ export class Solver {
     // its faces; both are left to giant time steps.
     this.constraints = [];
     const conductor = (st) => materials[regions[st.regions[0]].material].conductor;
-    const add = (parts, rowStretch) => {
+    const add = (parts, rowStretch, surface = []) => {
       const st = this.stretches[rowStretch];
-      const nNodes = parts.reduce((m, p) => m + this.stretches[p.stretch].nodes[1] - this.stretches[p.stretch].nodes[0] + 1, 0);
+      let nNodes = parts.reduce((m, p) => m + this.stretches[p.stretch].nodes[1] - this.stretches[p.stretch].nodes[0] + 1, 0);
+      for (const p of surface) nNodes += model.ports[this.surfCols[p.col][0]].nodes.length * model.ports[this.surfCols[p.col][0]].surface.length;
       for (const p of parts) this.stretches[p.stretch].conserved = true;
       this.constraints.push({
         parts,
+        surface,
         row: this.blockOfNode[st.nodes[0]] * this.M + 1 + st.species,
         idx: new Int32Array(nNodes * this.M),
         w: new Float64Array(nNodes * this.M),
@@ -599,12 +620,15 @@ export class Solver {
     this.stretches.forEach((st, k) => {
       if (st.spectator && st.mobile) add([{ stretch: k, w: 1 }], k);
     });
+    const S = this.stretches.length;
     for (const w of this.moieties) {
-      const parts = [...w.keys()].filter((k) => w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
-      if (parts.length === 1 && this.stretches[parts[0].stretch].spectator) continue; // (above)
+      const parts = [...w.keys()].filter((k) => k < S && w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
+      const surface = [...w.keys()].filter((k) => k >= S && w[k] !== 0).map((k) => ({ col: k - S, w: w[k] }));
+      if (parts.length === 0) continue; // (a surface's own: left to giant time steps)
+      if (parts.length === 1 && surface.length === 0 && this.stretches[parts[0].stretch].spectator) continue; // (above)
       if (parts.some((p) => !this.stretches[p.stretch].mobile || conductor(this.stretches[p.stretch]))) continue;
       // The row replaced: the basis vector's own stretch (its weight is 1, and no other vector has one).
-      add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch);
+      add(parts, parts.find((p) => w[p.stretch] === 1)?.stretch ?? parts[0].stretch, surface);
     }
     // A combination of immobile stretches (trap states: X⁰ + X⁻ under e⁻ + X⁰ = X⁻) is conserved
     // node by node, since nothing carries it anywhere: at each node its weighted sum stays what
@@ -667,26 +691,32 @@ export class Solver {
   // stoichiometry (a row per reaction, over the stretches it touches) together with a unit row
   // for each stretch fed from outside. Exact integer data, so plain elimination will do.
   _conservedMoieties() {
-    const { model, n } = this, S = this.stretches.length;
+    const { model, n } = this, S = this.stretches.length, C = S + this.surfCols.length;
     const rows = [];
     model.interfaces.forEach((itf, f) => {
       for (const rx of itf.reactions) {
-        const row = new Float64Array(S);
+        const row = new Float64Array(C);
         for (const p of rx.part) row[this.stretchOf[(f + p.side) * n + p.i]] += p.nu;
         rows.push(row);
       }
     });
-    for (const port of model.ports) {
+    // An electrode surface's species are columns too, after the stretches (S + j for surface
+    // column j), so a combination that passes through them (A⁺ + e⁻ = S, S + e⁻ = B⁻) is conserved
+    // with what the surface holds.
+    model.ports.forEach((port, k) => {
       for (const rx of port.reactions) {
-        const row = new Float64Array(S); // (the electrode's carrier is outside the device)
-        for (const p of rx.part) if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
+        const row = new Float64Array(C); // (the electrode's carrier is outside the device)
+        for (const p of rx.part) {
+          if (p.side === 0) row[this.stretchOf[port.region * n + p.i]] += p.nu;
+          else if (p.side === 2) row[S + this.surfColOf[k] + p.s] += p.nu;
+        }
         rows.push(row);
       }
-    }
+    });
     model.regions.forEach((reg, q) => {
       for (const rx of model.reactions) {
         if (!(rx.kf[reg.material] > 0)) continue;
-        const row = new Float64Array(S);
+        const row = new Float64Array(C);
         for (const p of rx.reactants) row[this.stretchOf[q * n + p.i]] -= p.nu;
         for (const p of rx.products) row[this.stretchOf[q * n + p.i]] += p.nu;
         rows.push(row);
@@ -694,34 +724,34 @@ export class Solver {
     });
     this.stretches.forEach((st, k) => {
       if (!st.contactFed) return;
-      const row = new Float64Array(S);
+      const row = new Float64Array(C);
       row[k] = 1;
       rows.push(row);
     });
     // Reduced row echelon form; the free columns give the null space.
     const pivots = [];
     let r = 0;
-    for (let col = 0; col < S && r < rows.length; col++) {
+    for (let col = 0; col < C && r < rows.length; col++) {
       let best = r;
       for (let i = r + 1; i < rows.length; i++) if (Math.abs(rows[i][col]) > Math.abs(rows[best][col])) best = i;
       if (Math.abs(rows[best][col]) < 1e-9) continue;
       [rows[r], rows[best]] = [rows[best], rows[r]];
       const pr = rows[r], pv = pr[col];
-      for (let j = 0; j < S; j++) pr[j] /= pv;
+      for (let j = 0; j < C; j++) pr[j] /= pv;
       for (let i = 0; i < rows.length; i++) {
         if (i === r || rows[i][col] === 0) continue;
         const fct = rows[i][col];
-        for (let j = 0; j < S; j++) rows[i][j] -= fct * pr[j];
+        for (let j = 0; j < C; j++) rows[i][j] -= fct * pr[j];
       }
       pivots.push(col);
       r++;
     }
-    const isPivot = new Uint8Array(S);
+    const isPivot = new Uint8Array(C);
     for (const col of pivots) isPivot[col] = 1;
     const basis = [];
-    for (let free = 0; free < S; free++) {
+    for (let free = 0; free < C; free++) {
       if (isPivot[free]) continue;
-      const w = new Float64Array(S);
+      const w = new Float64Array(C);
       w[free] = 1;
       pivots.forEach((col, i) => {
         const v = -rows[i][free];
@@ -761,6 +791,19 @@ export class Solver {
           }
         }
       }
+      // What the electrodes' surfaces hold of it: Γ Σ v·a·θ, with ∂θ_s/∂η_x = θ_s (δ_sx − θ_x).
+      for (const { col, w } of cs.surface) {
+        const [k, q] = this.surfCols[col], port = this.model.ports[k], G = port.surface[0].capacity, ns = port.surface.length;
+        reference += w * this.surfaceRef[col];
+        port.nodes.forEach((g, j) => {
+          const f = w * G * vol[g] * this.portArea[k][j], b = this.blockOfNode[g], tq = this.th[g * this.nSurf + q];
+          amount += f * tq;
+          for (let x = 0; x < ns; x++) {
+            cs.idx[len] = this.rix[b * M + 1 + n + x];
+            cs.w[len++] = f * tq * ((q === x ? 1 : 0) - this.th[g * this.nSurf + x]);
+          }
+        });
+      }
       cs.len = len;
       cs.res = amount - reference;
       const b0 = Math.floor(cs.row / M), r0 = cs.row % M;
@@ -839,6 +882,14 @@ export class Solver {
   }
 
 
+  /** Amount (mol per unit area) of surface column j's species, Γ Σ v·a·θ, in the current state. */
+  surfaceAmount(j) {
+    const [k, q] = this.surfCols[j], port = this.model.ports[k], vol = this.model.grid.vol;
+    let s = 0;
+    port.nodes.forEach((g, w) => (s += vol[g] * this.portArea[k][w] * this.th[g * this.nSurf + q]));
+    return port.surface[0].capacity * s;
+  }
+
   /** Total amount (mol per unit area) of a stretch's species in the current state. */
   amount(stretch) {
     const { n, c, model } = this;
@@ -1086,12 +1137,28 @@ export class Solver {
       surf.forEach((sp, q) => (u[b * M + 1 + n + q] = sp.mu0 / model.RT + Math.log(sp.theta0 / bare)));
     }
     this.computeConcentrations();
-    // A floating electrode spread through a port starts where its reactions pass the current it's
-    // set (none, behind a resistance): at its mixed potential in the start's composition, not
-    // level with a held terminal, which can be volts away and pass an absurd current.
+    // A floating capacitance starts uncharged (σ = 0 at the window's mean φ), as the starting
+    // composition, neutral without it, assumes; with reactions too, its double layer then charges
+    // toward their mixed potential.
     for (const k of this.floating) {
       const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
-      if (!port || port.reactions.length === 0) continue;
+      if (!port?.capacitance) continue;
+      let w = 0, sum = 0;
+      port.nodes.forEach((g, j) => {
+        if (this.phiUndefined[g]) return;
+        const a = this.model.grid.vol[g] * this.portArea[t.index][j];
+        w += a;
+        sum += a * this.VT * u[this.blockOfNode[g] * M];
+      });
+      if (w > 0) this.termV[k] = port.capacitance.zeroCharge + sum / w;
+    }
+    // A floating electrode spread through a port (without a double layer) starts where its
+    // reactions pass the current it's set (none, behind a resistance): at its mixed potential in
+    // the start's composition, not level with a held terminal, which can be volts away and pass
+    // an absurd current.
+    for (const k of this.floating) {
+      const t = this.terms[k], port = t.kind === 'port' ? model.ports[t.index] : null;
+      if (!port || port.reactions.length === 0 || port.capacitance) continue;
       const want = t.drive.kind === 'I' ? sourceAt(t.drive.src, this.time) : 0;
       const current = (V) => {
         this.termV[k] = V;
@@ -1130,8 +1197,7 @@ export class Solver {
       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);
     }
     if (rx.bare) pref *= this.th0[g];
-    // (far from equilibrium, the plain difference: bvFactor's product would give 0·∞ there)
-    return pref * (Math.abs(a) > 50 ? Math.exp(rx.alpha * a) - Math.exp(-(1 - rx.alpha) * a) : bvFactor(a, rx.alpha).g);
+    return pref * bvFactor(a, rx.alpha).g;
   }
 
   // A non-ideal material's composition at φ̂ = ph: level-fixed species (mode 1) at their η,
@@ -1494,6 +1560,18 @@ export class Solver {
         }
       }
       res[R[lb]] -= v * q;
+      // The pivot's row (charge continuity) left storage out, the ions' net charge being constant
+      // under neutrality. Against a capacitance it isn't: neutrality makes it −(aσ + ρ_fixed)/F,
+      // so their storage is that less what the step started with, Σ z c_old, over dt (in units
+      // of the pivot's balance).
+      if (this.qgTerms[g].length > 0) {
+        const f = -v / (FARADAY * z[k] * dt);
+        let qOld = this.rhoFixed[g];
+        for (let i = 0; i < n; i++) if (present[gn + i]) qOld += F * z[i] * cOld[gn + i];
+        res[rk] += f * (this.qg[g] + qOld);
+        B[offB[b] + lk * m + p] += -f * this.qgSlope[g] * this.VT;
+        for (const [kq, w] of this.qgTerms[g]) termB[kq][rk] += f * this.portArea[kq - 2][w] * this.model.ports[kq - 2].capacitance.C;
+      }
     }
   }
 
@@ -2019,7 +2097,10 @@ export class Solver {
       this.termDI[k] = 0;
       this.termI[k] = 0;
     }
-    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt));
+    this.qg.fill(0);
+    this.qgSlope.fill(0);
+    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt, false));
+    this.model.ports.forEach((port, k) => this._port(port, this.portFlux[k], 2 + k, dt, true));
     this._contact('left', dt);
     this._contact('right', dt);
     for (const k of this.floating) this._circuit(k);
@@ -2051,16 +2132,18 @@ export class Solver {
 
   // An internal port (terminal k): its exchange with each node of its window, as a source per
   // volume. A held ('equilibrium') level replaces the node's balance row; the source is then that
-  // row's residual, read just before. Its current into the device is Σ z F × the sources.
-  _port(port, flux, k, dt) {
+  // row's residual, read just before. Its current into the device is Σ z F × the sources. In two
+  // passes over the ports: everything else, then the held levels (`holds`), so that a level reads
+  // every other port's terms at its nodes, and none is added into its row after.
+  _port(port, flux, k, dt, holds) {
     const R = this.rix;
     const { n, M, u, uLo, res, z, VT } = this;
     const F = FARADAY, vol = this.model.grid.vol;
     const B = this.termB[k], C = this.termC[k];
-    flux.fill(0);
+    if (!holds) flux.fill(0);
     for (let i = 0; i < n; i++) {
       const link = port.species[i];
-      if (link.type === 'blocked') continue;
+      if (link.type === 'blocked' || (link.type === 'equilibrium') !== holds) continue;
       const r = 1 + i, target = this.portEta(port, i), zF = z[i] * F;
       for (const g of port.nodes) {
         const b = this.blockOfNode[g], o = b * M + r, v = vol[g];
@@ -2087,10 +2170,13 @@ export class Solver {
         }
       }
     }
+    if (holds) {
+      for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
+      return;
+    }
     port.reactions.forEach((rx, x) => this._portReaction(port, rx, this.portArea[k - 2], this.portRates[k - 2][x], flux, k));
     if (port.capacitance) this._portCapacitance(port, k, dt);
     if (port.surface.length > 0 && Number.isFinite(dt)) this._surfaceStorage(port, dt);
-    for (let i = 0; i < n; i++) this.termI[k] += z[i] * F * flux[i];
   }
 
   // A port's reaction at each node of its window: Butler–Volmer per area, as at a face, against
@@ -2167,6 +2253,8 @@ export class Solver {
       if ((g === 0 && sets('left')) || (g === this.nNodes - 1 && sets('right')) || this.phiUndefined[g]) return;
       const b = this.blockOfNode[g], s = vol[g] * area[w] * Cs;
       const q = s * (V - zeroCharge - VT * (u[b * M] + uLo[b * M]));
+      this.qg[g] += area[w] * Cs * (V - zeroCharge - VT * (u[b * M] + uLo[b * M]));
+      this.qgSlope[g] += area[w] * Cs;
       Q += q;
       dQdV += s;
       res[R[b * M]] -= q;
@@ -2221,10 +2309,13 @@ export class Solver {
     const Ac = model.grid.area[g]; // the links' laws are per area: what they pass is that times A here
     const dyn = Number.isFinite(dt);
 
-    // Before anything is added, each balance residual is the flux into the device here.
+    // Before anything is added, each balance residual is the flux into the device here. (A
+    // closed end solved in charge rows has its ions' storage left out until later: none of them
+    // passes, so their flux is zero.)
+    const closedIons = this.combining && dyn && this.chargeNode[g] === 1;
     let I = 0;
     for (let i = 0; i < n; i++) {
-      const active = this.loc[b * M + 1 + i] >= 0;
+      const active = this.loc[b * M + 1 + i] >= 0 && !(closedIons && z[i] !== 0);
       const nIn = active ? res[R[b * M + 1 + i]] : 0;
       flux[i] = sgn * nIn; // (toward +x)
       if (active && z[i] !== 0) {
@@ -2583,7 +2674,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.
    */
@@ -2663,7 +2754,8 @@ export class Solver {
           continue;
         }
       } else {
-        const r = this.step(h, { method, guess: this._extrapolate(guess, this.time + h) });
+        // (Order 2 once three consistent states can check it.)
+        const r = this.step(h, { method: this.history.length >= 2 ? method : 'be', guess: this._extrapolate(guess, this.time + h) });
         iterations += r.iterations;
         if (!r.converged) {
           rejected++;
@@ -2683,6 +2775,11 @@ export class Solver {
       }
       steps++;
       grow = 0;
+      // The state the first step started from needn't satisfy the algebraic equations (φ in a
+      // strictly neutral region, an interface's unknowns, after a start or a jump), and they
+      // jump in the first instant; a predictor through it would see that jump as error on every
+      // step after. The history starts from the half step.
+      if (half) this.history.length = 1;
       dt = clamped ? Math.max(dt, h * factor(err, p)) : h * factor(err, p);
       if (atBreak) this.history = []; // the solution's slope jumps here: restart the order
       if (half) {
@@ -2809,6 +2906,8 @@ export class Solver {
       for (let i = 0; i < n; i++) {
         if (this.present[g * n + i]) mx = Math.max(mx, Math.abs(u[b * M + 1 + i] - ref[b * M + 1 + i]));
       }
+      const k = this.surfPort[g]; // an electrode surface's coverages, as η
+      if (k >= 0) for (let q = 0; q < this.model.ports[k].surface.length; q++) mx = Math.max(mx, Math.abs(u[b * M + 1 + n + q] - ref[b * M + 1 + n + q]));
     }
     return mx;
   }
@@ -3263,6 +3362,18 @@ export class Solver {
   // Steady state from the present one; `atSteady` says whether the state is one (until a step or
   // a change of drive).
   solveSteady(opts = {}) {
+    // A terminal that passes current only by charging (a gate, a capacitance with no species
+    // through it) has no steady state under a current drive: it charges for ever, or at I = 0
+    // keeps whatever charge it started with, which a steady solve doesn't know.
+    const { species } = this.model, ions = (links) => links.some((l, i) => l.type !== 'blocked' && species[i].z !== 0);
+    for (const k of this.floating) {
+      const t = this.terms[k];
+      if (t.drive.kind !== 'I') continue;
+      const only = t.kind === 'port' ? (p) => p.reactions.length === 0 && !ions(p.species) : (c) => !ions(c.species);
+      if (only(t.kind === 'port' ? this.model.ports[t.index] : this.model.contacts[t.side])) {
+        throw new DeviceError(`${t.kind === 'port' ? `ports[${t.index}]` : `contacts.${t.side}`} passes current only by charging, so driven by a current it has no steady state; hold it at V (or a source behind R), or advance() in time`);
+      }
+    }
     const r = this._steadyFromHere(opts);
     this.atSteady = r.converged;
     return r;

package/src/types.js

@@ -197,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

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

@@ -17,6 +17,8 @@ export class Solver {
     blockOfFace: Int32Array<ArrayBuffer>;
     surfPort: Int32Array<any>;
     surfW: Int32Array<any>;
+    surfCols: any;
+    surfColOf: any;
     th: Float64Array<ArrayBuffer>;
     thOld: Float64Array<ArrayBuffer>;
     th0: Float64Array<any>;
@@ -65,6 +67,9 @@ export class Solver {
     portQStart: Float64Array<any>;
     portQOld: Float64Array<any>;
     portQEnd: any;
+    qg: Float64Array<any>;
+    qgSlope: Float64Array<any>;
+    qgTerms: any[][];
     contactDOld: {
         left: number;
         right: number;
@@ -94,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>;
@@ -115,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;
@@ -184,7 +196,7 @@ 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, dt: 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;
@@ -236,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.
      */

package/types/types.d.ts

@@ -471,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)