driftlet 1.1.1 → 1.2.1

package/src/solver.js

@@ -503,6 +503,9 @@ export class Solver {
     this.termB = this.terms.map(() => new Float64Array(this.sys.size + 1));
     this.termC = this.terms.map(() => new Float64Array(this.sys.size + 1));
     this.termDI = new Float64Array(this.terms.length);
+    // (and a circuit row's derivatives by other terminals' voltages: a law in one's row that counts
+    // another electrode's charge)
+    this.termDX = this.terms.map(() => new Float64Array(this.terms.length));
     this.termRes = new Float64Array(this.terms.length);
     this._refreshSources();
     // A floating terminal starts level with the first held one (no current).
@@ -783,7 +786,7 @@ export class Solver {
         const ks = rx.part.map((p) => this.stretchOf[(f + p.side) * n + p.i]);
         if (ks.some((k) => k < 0)) continue;
         join(ks);
-        rxns.push([ks, (side) => rx.part.reduce((a, p) => a + p.nu * this.contactEta(side, p.i), rx.fixedA)]);
+        rxns.push([ks, (side) => rx.part.reduce((a, p) => a - p.nu * this.contactEta(side, p.i), rx.fixedA)]); // (a face's ν: products +, so − Σ ν η)
       }
     });
     const groups = new Map();
@@ -834,6 +837,20 @@ export class Solver {
     return true;
   }
 
+  // The charge number an electrode's carrier column counts its charge in, Q/(zF): its terminal
+  // species', or 1 for a port with none (a membrane's capacitance: Q/F).
+  _carrierZ(k) {
+    const t = this.model.ports[k - 2].terminal;
+    return t === null || t === undefined ? 1 : this.z[t];
+  }
+
+  // Whether contact k (0, 1) holds a charge its current counts, D_in on its φ law (capacitive,
+  // pinned or bulk, where φ is defined at its end node).
+  _contactCharges(k) {
+    const g = k === 0 ? 0 : this.nNodes - 1;
+    return ['capacitive', 'pinned', 'bulk'].includes(this.model.contacts[k === 0 ? 'left' : 'right'].phi.type) && !this.phiUndefined[g];
+  }
+
   // Whether terminal k (a contact, or port k − 2) feeds stretch st: links its species there.
   _feeds(k, st) {
     return k === 0 ? st.leftOpen : k === 1 ? st.rightOpen : st.linked.includes(k - 2);
@@ -861,6 +878,19 @@ export class Solver {
     const driven = (st) => this.terms.flatMap((t, k) => (t.drive.kind === 'I' && this._feeds(k, st) ? [k] : []));
     const add = (parts, rowStretch, surface = [], circuit = -1, carriers = []) => {
       const st = this.stretches[rowStretch];
+      // (the terminal's weight in it, w/z on what that feeds: the amount changes by λ I/F)
+      const own = carriers.find((p) => p.k === circuit);
+      const lambda = circuit < 0 ? 0 : ((own && own.w / this._carrierZ(circuit)) || parts.map((p) => (driven(this.stretches[p.stretch]).includes(circuit) ? p.w / this.z[this.stretches[p.stretch].species] : 0)).find((x) => x !== 0));
+      // In a circuit row, what passes through that terminal's capacitance is kept too, λ Q/F, as
+      // its current counts dQ/dt: a port or contact at no current that passes K⁺ and charges keeps
+      // n_K + Q/F. (Its K⁺ alone held, a membrane port's voltage settled 7 mV from the transient's.)
+      // A port's charge, as an electrode's carrier; a contact's, its displacement D_in, below.
+      if (circuit >= 2 && model.ports[circuit - 2].capacitance && !carriers.some((p) => p.k === circuit)) carriers = [...carriers, { k: circuit, w: lambda * this._carrierZ(circuit) }];
+      // Every contact driven by a current that feeds it and holds a charge, D_in, kept beside the
+      // ions it passes at its own λ (two contacts at no current passing K⁺, one a capacitor: its
+      // charge was left out where the law took the other's row).
+      const lam = (t) => parts.map((p) => (driven(this.stretches[p.stretch]).includes(t) && this.z[this.stretches[p.stretch].species] !== 0 ? p.w / this.z[this.stretches[p.stretch].species] : 0)).find((x) => x !== 0);
+      const contacts = circuit < 0 ? [] : [0, 1].filter((t) => lam(t) && this._contactCharges(t)).map((t) => ({ t, lambda: lam(t) }));
       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 carriers) nNodes += model.ports[p.k - 2].nodes.length;
@@ -869,11 +899,11 @@ export class Solver {
         parts,
         surface,
         carriers, // (what a port's electrode holds, Q/(zF) at weight w: see _conservedMoieties)
+        contacts, // (contacts whose charges it keeps, λ D_in/F each)
         terminals: [...new Set([...parts.flatMap((p) => driven(this.stretches[p.stretch])), ...carriers.map((p) => p.k)])],
         key: parts.map((p) => `${p.stretch}:${p.w}`).join() + surface.map((p) => `|${p.col}:${p.w}`).join() + carriers.map((p) => `|T${p.k}:${p.w}`).join(),
         circuit, // (the terminal whose circuit row it stands in for, or −1 for a balance row's, `row`)
-        // (and the terminal's weight in it, w/z on what that feeds: the amount changes by λ I/F)
-        lambda: circuit < 0 ? 0 : (carriers.find((p) => p.k === circuit)?.w / this.z[model.ports[circuit - 2]?.terminal] || parts.map((p) => (driven(this.stretches[p.stretch]).includes(circuit) ? p.w / this.z[this.stretches[p.stretch].species] : 0)).find((x) => x !== 0)),
+        lambda,
         row: circuit >= 0 ? -1 : this.blockOfNode[st.nodes[0]] * this.M + 1 + st.species,
         idx: new Int32Array(nNodes * this.M),
         w: new Float64Array(nNodes * this.M),
@@ -890,7 +920,12 @@ export class Solver {
       if (this.flatStretches.includes(st)) this.constraints.at(-1).col = Array.from({ length: st.nodes[1] - st.nodes[0] + 1 }, (_, j) => this.blockOfNode[st.nodes[0] + j] * this.M + 1 + st.species);
     });
     const S = this.stretches.length, T = this.terms.length, X = S + this.surfCols.length;
-    const zc = (k) => this.z[model.ports[k - 2].terminal];
+    // Two column spaces. A law's weights w: stretches [0, S), electrode surfaces' species [S, X)
+    // (surface column k − S), electrodes' charges [X, …) (carrier k − X). The rows a law can take,
+    // v: stretches' balance rows [0, S), then terminals' circuit rows (terminal j − S).
+    const isStretch = (k) => k < S, isSurface = (k) => k >= S && k < X, isCarrier = (k) => k >= X;
+    const circuitOf = (j) => (j >= S ? j - S : -1);
+    const zc = (k) => this._carrierZ(k);
     // The rows replaced: a moving stretch's balance (one of still stretches alone is kept node by
     // node, below), or the circuit row of a terminal driven at no current, which says nothing the
     // combination's balance rows don't (their weighted sum is that terminal's current, weighted
@@ -940,11 +975,16 @@ export class Solver {
       // A current held at zero passes nothing: an electrode at open circuit feeding a closed
       // pool of Ag⁺ beside a slow Fe³⁺/Fe²⁺ couple settled 78 mV off, its iron not stationary.)
       const passes = (k) => !this._noCurrent(this.terms[k]);
-      const fed = (w) => w.some((x, k) => x !== 0 && ((k >= X && passes(this.carriers[k - X])) || (k < S && driven(this.stretches[k]).some(passes))));
+      const fed = (w) => w.some((x, k) => x !== 0 && ((isCarrier(k) && passes(this.carriers[k - X])) || (isStretch(k) && driven(this.stretches[k]).some(passes))));
       // Any of the combinations it alone changes will do, with any conserved amount added (whose
       // summed balance is zero too): one of them needs a row of its own left to take. (Silver's,
       // e⁻ − Fe³⁺ beside a closed iron couple that had Fe³⁺'s, is e⁻ + Fe²⁺ with the iron added.)
       const news = this._conservedMoieties(true, [], rx).filter((w) => Math.abs(nu.reduce((t, x, k) => t + x * w[k], 0)) > 1e-9 && !fed(w));
+      // (One it changes only through immobile species has its rate alone in their balance at the
+      // face's node already, a row with no diffusion beside it to lose it to: left as it is. Stood
+      // in for by a mobile partner, Ag⁺ + Cl⁻ = S(immobile) beside a floating Ag electrode said its
+      // rate twice and lost the electrode's I = 0.)
+      if (news.some((w) => [...w.keys()].every((k) => !isStretch(k) || w[k] === 0 || this._still(this.stretches[k])))) continue;
       const kept = laws.filter((l) => !fed(l));
       const tries = [...news, ...news.flatMap((w) => kept.flatMap((l) => [1, -1].map((sg) => w.map((x, m) => x + sg * l[m]))))];
       for (const w of tries) {
@@ -976,6 +1016,7 @@ export class Solver {
         break;
       }
     }
+    this.contactQ = [null, null];
     for (let w of [...laws.filter(through), ...laws.filter((w) => !through(w))]) {
       for (const [j, k] of this.carriers.entries()) {
         const c = held.get(k);
@@ -984,10 +1025,13 @@ export class Solver {
         w = w.map((x, m) => (Math.abs(x - f * c[m]) < 1e-9 ? 0 : x - f * c[m]));
         w.own = own;
       }
-      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 && k < X && w[k] !== 0).map((k) => ({ col: k - S, w: w[k] }));
+      const parts = [...w.keys()].filter((k) => isStretch(k) && w[k] !== 0).map((k) => ({ stretch: k, w: w[k] }));
+      const surface = [...w.keys()].filter((k) => isSurface(k) && w[k] !== 0).map((k) => ({ col: k - S, w: w[k] }));
       const carriers = this.carriers.flatMap((k, j) => (w[X + j] !== 0 ? [{ k, w: w[X + j] }] : []));
-      if (parts.length === 0) continue; // (a surface's own: node by node, below)
+      // (A surface's own is kept node by node, below; one with an electrode's charge in it too is
+      // the circuit's, here: below skips it, and a floating electrode whose adsorbates gave it
+      // electrons settled 15 mV from where the transient ends.)
+      if (parts.length === 0 && carriers.length === 0) continue;
       if (parts.length === 1 && surface.length === 0 && this.stretches[parts[0].stretch].spectator) continue; // (above)
       if (parts.some((p) => !this._moves(this.stretches[p.stretch]) && !this._still(this.stretches[p.stretch]))) continue;
       const v = new Float64Array(S + T);
@@ -1005,11 +1049,14 @@ export class Solver {
       if (!(scale > 1e-9)) continue;
       const ok = (j) => j !== undefined && Math.abs(v[j]) > 1e-9 * scale;
       const col = [...Array(T).keys()].map((t) => S + t).find(ok) ?? [parts.find((p) => w[p.stretch] === 1)?.stretch, w.own].find(ok) ?? v.findIndex((x) => Math.abs(x) === scale);
-      if (carriers.some((p) => p.k !== col - S)) continue; // (an electrode's charge in a circuit row not its own: never, as they're chosen)
+      // (Other electrodes' charges in a circuit row not their own: their voltages enter it through
+      // termDX. Two floating electrodes sharing a closed Fe³⁺, their law dropped, settled at 1.3 V
+      // for −0.65.)
       chosen.push([col, v.map((x) => x / v[col])]);
-      if (col >= S) held.set(col - S, w);
-      add(parts, col < S ? col : parts[0].stretch, surface, col < S ? -1 : col - S, carriers);
+      if (circuitOf(col) >= 0) held.set(circuitOf(col), w);
+      add(parts, circuitOf(col) < 0 ? col : parts[0]?.stretch, surface, circuitOf(col), carriers);
     }
+    this.contactLaw = [0, 1].map((k) => this.constraints.some((cs) => cs.contacts.some((c) => c.t === k)));
     // A combination that nothing carries anywhere is conserved node by node: of still stretches
     // (trap states: X⁰ + X⁻ under e⁻ + X⁰ = X⁻), or of an electrode's surface species (adsorbates
     // that only turn into each other). At each node its weighted sum stays what it was, a row local
@@ -1018,18 +1065,47 @@ export class Solver {
     const span = ([g0, g1]) => Array.from({ length: g1 - g0 + 1 }, (_, j) => g0 + j);
     for (const w of laws) {
       const parts = [...w.keys()].filter((k) => w[k] !== 0);
-      if (parts.some((k) => k >= X)) continue; // (through an electrode: above)
-      const sets = parts.map((k) => (k >= S ? model.ports[this.surfCols[k - S][0]].nodes : this._still(this.stretches[k]) ? span(this.stretches[k].nodes) : null));
-      if (sets.some((set) => set === null || set.length !== sets[0].length || set.some((g, j) => g !== sets[0][j]))) continue; // (side by side only)
-      for (const k of parts) if (k < S) this.stretches[k].conserved = true;
-      const slot = (k) => (k < S ? 1 + this.stretches[k].species : 1 + this.n + this.surfCols[k - S][1]);
+      if (parts.some(isCarrier)) continue; // (through an electrode: above)
+      const sets = parts.map((k) => (isSurface(k) ? model.ports[this.surfCols[k - S][0]].nodes : this._still(this.stretches[k]) ? span(this.stretches[k].nodes) : null));
+      if (sets.includes(null)) continue;
+      // Its nodes: the immobile stretches', side by side, with any surface's window among them (a
+      // surface's term only where it is: an immobile S that adsorbs on an electrode spread over
+      // part of its region keeps S + Γaθ there and S alone elsewhere; required to match, that law
+      // was lost, and a floating electrode's coverage drifted). Or a surface's alone.
+      const own = parts.filter(isStretch), base = own.length > 0 ? sets[parts.indexOf(own[0])] : sets[0];
+      const same = (set) => set.length === base.length && set.every((g, j) => g === base[j]);
+      if (!parts.every((k, j) => (isStretch(k) ? same(sets[j]) : sets[j].every((g) => base.includes(g))))) continue;
+      for (const k of own) this.stretches[k].conserved = true;
+      const slot = (k) => (isStretch(k) ? 1 + this.stretches[k].species : 1 + this.n + this.surfCols[k - S][1]);
+      // (its row a stretch's where it has one, present at every node; else the surface's)
+      const rowPart = own.length > 0 ? (own.includes(w.own) ? w.own : own[0]) : parts.includes(w.own) ? w.own : parts[0];
       this.localConstraints.push({
-        parts: parts.map((k) => (k < S ? { i: this.stretches[k].species, w: w[k] } : { q: this.surfCols[k - S][1], w: w[k] })),
-        row: slot(parts.includes(w.own) ? w.own : parts[0]),
-        nodes: sets[0],
+        parts: parts.map((k) => (isStretch(k) ? { i: this.stretches[k].species, w: w[k] } : { q: this.surfCols[k - S][1], k: this.surfCols[k - S][0], w: w[k] })),
+        row: slot(rowPart),
+        nodes: base,
         reference: new Float64Array(sets[0].length),
       });
     }
+    // An immobile stretch at a node where nothing touches it (no reaction there, no port or contact
+    // linking it) keeps its concentration: its balance there is 0 = 0 in a steady state, which
+    // holds nothing, and a charged one's level stayed where it was while φ moved (S⁺ beside a face
+    // that makes it, the bath moved 0.2 V: S⁺ fell to e^{−0.2/V_T} of itself away from the face).
+    for (const st of this.stretches) {
+      if (!this._still(st)) continue;
+      const i = st.species, touched = new Set();
+      for (let g = st.nodes[0]; g <= st.nodes[1]; g++) if (this.rxsIn[this.nodeMaterial[g]].some((rx) => rx.sp.includes(i))) touched.add(g);
+      model.interfaces.forEach((itf, f) => {
+        for (const rx of itf.reactions) for (const p of rx.part) if (p.i === i) touched.add(p.side === 0 ? grid.regionEnd[f] : grid.regionStart[f + 1]);
+      });
+      for (const port of model.ports) {
+        if (port.species[i].type !== 'blocked' || port.reactions.some((rx) => rx.part.some((p) => p.side === 0 && p.i === i))) for (const g of port.nodes) touched.add(g);
+      }
+      if (st.leftOpen) touched.add(0);
+      if (st.rightOpen) touched.add(this.nNodes - 1);
+      for (const lc of this.localConstraints) if (lc.row === 1 + i) for (const g of lc.nodes) touched.add(g);
+      const free = span(st.nodes).filter((g) => !touched.has(g));
+      if (free.length > 0) this.localConstraints.push({ parts: [{ i, w: 1 }], row: 1 + i, nodes: free, reference: new Float64Array(free.length) });
+    }
     // Islands: the pieces of a stretch between its faces. One that nothing else feeds (no
     // contact, port or reaction) holds its level only through its faces' fluxes, which can be
     // ~1e-24 of its own conduction (a tiny conductance at the face, or a neighbour that barely
@@ -1108,7 +1184,7 @@ export class Solver {
         if (fedBy.size !== 1) continue;
         const [k] = fedBy;
         if (!behind.includes(k) || this.timeLaws.some((cs) => cs.circuit === k)) continue;
-        const zc = k >= 2 ? this.z[model.ports[k - 2].terminal] : 0;
+        const zc = k >= 2 ? this._carrierZ(k) : 0;
         const lambda = carriers.find((p) => p.k === k)?.w / zc || parts.map((p) => (this._feeds(k, this.stretches[p.stretch]) && this.z[this.stretches[p.stretch].species] !== 0 ? p.w / this.z[this.stretches[p.stretch].species] : 0)).find((x) => x !== 0);
         if (!lambda) continue;
         let nNodes = parts.reduce((m, p) => m + this.stretches[p.stretch].nodes[1] - this.stretches[p.stretch].nodes[0] + 1, 0);
@@ -1131,13 +1207,14 @@ export class Solver {
       for (const k of charged) this.chargeRefs.set(k, k >= 2 ? this.portQ[k - 2] : k === 0 ? this.contactD.left : -this.contactD.right);
     }
     this.lawRefs.clear();
-    if (this.constraints.some((cs) => cs.carriers.some(({ k }) => this.model.ports[k - 2].capacitance)) && charged.length === 0) this._assembleBookkeeping(Infinity);
+    if (this.constraints.some((cs) => cs.contacts.length > 0 || cs.carriers.some(({ k }) => this.model.ports[k - 2].capacitance)) && charged.length === 0) this._assembleBookkeeping(Infinity);
     for (const cs of this.constraints) {
       if (cs.terminals.length === 0) continue;
       let a = 0;
       for (const { stretch, w } of cs.parts) a += w * this.amount(this.stretches[stretch]);
       for (const { col, w } of cs.surface) a += w * this.surfaceAmount(col);
-      for (const { k, w } of cs.carriers) if (this.model.ports[k - 2].capacitance) a += (w * this.portQ[k - 2]) / (this.z[this.model.ports[k - 2].terminal] * FARADAY);
+      for (const { k, w } of cs.carriers) if (this.model.ports[k - 2].capacitance) a += (w * this.portQ[k - 2]) / (this._carrierZ(k) * FARADAY);
+      for (const { t, lambda } of cs.contacts) a += (lambda * (t === 0 ? this.contactD.left : -this.contactD.right)) / FARADAY;
       this.lawRefs.set(cs.key, a);
     }
   }
@@ -1149,7 +1226,10 @@ export class Solver {
     for (const lc of this.localConstraints) {
       lc.nodes.forEach((g, j) => {
         let t = 0;
-        for (const { i, q, w } of lc.parts) t += w * (i !== undefined ? c[g * n + i] : th[g * nSurf + q]);
+        for (const { i, q, k, w } of lc.parts) {
+          if (i !== undefined) t += w * c[g * n + i];
+          else if (this.surfPort[g] === k) t += w * this._sites(g) * th[g * nSurf + q];
+        }
         lc.reference[j] = t;
       });
     }
@@ -1220,6 +1300,14 @@ export class Solver {
     }
   }
 
+  // An electrode surface's sites per volume at node g, Γ a (mol/m³): what a coverage of 1 holds,
+  // beside the concentrations of a local constraint. (Summed as θ alone, an immobile S that adsorbs
+  // as A(ads) kept S + θ_A, mol/m³ and a fraction.)
+  _sites(g) {
+    const k = this.surfPort[g];
+    return this.model.ports[k].surface[0].capacity * this.portArea[k][this.surfW[g]];
+  }
+
   // The local constraints' rows (steady solves only): Σ w c_i − reference at each node.
   _applyLocalConstraints() {
     const { n, M, c, th, nSurf, res, dA: d } = this;
@@ -1229,17 +1317,18 @@ export class Solver {
         if (this.loc[b * M + lc.row] < 0) return;
         this._replaceRow(b, lc.row);
         let t = 0;
-        for (const { i, q, w } of lc.parts) {
+        for (const { i, q, k, w } of lc.parts) {
           if (i !== undefined) {
             t += w * c[g * n + i];
             this._dc(g, i, d);
             for (let s = 0; s < M; s++) if (d[s] !== 0) this._j(b, lc.row, b, s, w * d[s]);
             continue;
           }
-          // A coverage, with ∂θ_q/∂η_x = θ_q (δ_qx − θ_x) over its surface's species.
-          const tq = th[g * nSurf + q], ns = this.model.ports[this.surfPort[g]].surface.length;
-          t += w * tq;
-          for (let x = 0; x < ns; x++) this._j(b, lc.row, b, 1 + n + x, w * tq * ((q === x ? 1 : 0) - th[g * nSurf + x]));
+          // A coverage, with ∂θ_q/∂η_x = θ_q (δ_qx − θ_x) over its surface's species (where it is).
+          if (this.surfPort[g] !== k) continue;
+          const tq = th[g * nSurf + q], ns = this.model.ports[this.surfPort[g]].surface.length, ws = w * this._sites(g);
+          t += ws * tq;
+          for (let x = 0; x < ns; x++) this._j(b, lc.row, b, 1 + n + x, ws * tq * ((q === x ? 1 : 0) - th[g * nSurf + x]));
         }
         res[this.rix[b * M + lc.row]] = t - lc.reference[j];
       });
@@ -1261,8 +1350,12 @@ export class Solver {
     // which the current feeds and the reactions draw on (a port at no current with M⁺ + e⁻ = M(s)
     // keeps M⁺ + Q/F, or with no capacitance, Q = 0, the M⁺ alone).
     const byCurrent = (t, k) => t.drive.kind === 'I' || alsoCurrent.includes(k); // (with `alsoCurrent`, terminals counted as such)
-    this.carriers = drives ? this.terms.flatMap((t, k) => (byCurrent(t, k) && k >= 2 && model.ports[k - 2].reactions.length > 0 ? [k] : [])) : [];
+    // (Or a port with a capacitance that passes ions, a membrane's: what it holds is Q/F. One that
+    // only charges keeps its charge alone, see _captureLaws.)
+    this.carriers = drives ? this.terms.flatMap((t, k) => (byCurrent(t, k) && k >= 2 && (model.ports[k - 2].reactions.length > 0 || (model.ports[k - 2].capacitance && !this._chargeOnly(k))) ? [k] : [])) : [];
     const X = S + this.surfCols.length, C = X + this.carriers.length;
+    // (columns: stretches [0, S), surfaces' species [S, X), electrodes' charges [X, C), as in _laws)
+    const isStretch = (k) => k < S, isSurface = (k) => k >= S && k < X;
     // (With `skip`, a reaction left out: the combinations that it alone changes come out too, and
     // its own rows, over the columns, are handed back as `basis.skipped`.)
     const rows = [], skipped = [];
@@ -1306,7 +1399,7 @@ export class Solver {
       const fed = this.stretches.flatMap((st, j) => (this._feeds(k, st) ? [j] : []));
       if (!(drives && byCurrent(t, k))) return fed.forEach(unit);
       const charged = fed.filter((j) => z[this.stretches[j].species] !== 0).map((j) => [j, z[this.stretches[j].species]]);
-      if (this.carriers.includes(k)) charged.push([X + this.carriers.indexOf(k), z[model.ports[k - 2].terminal]]);
+      if (this.carriers.includes(k)) charged.push([X + this.carriers.indexOf(k), this._carrierZ(k)]);
       fed.filter((j) => z[this.stretches[j].species] === 0).forEach(unit);
       for (let a = 1; a < charged.length; a++) {
         const row = new Float64Array(C);
@@ -1316,16 +1409,18 @@ export class Solver {
       }
     });
     // Reduced row echelon form; the free columns give the null space. Immobile stretches' columns
-    // go first, so that a combination of them alone (trap states, X⁰ + X⁻) comes out on its own,
-    // to be kept node by node, apart from any that moves (e⁻ − X⁰, the electrons the traps hold).
+    // go first, and electrode surfaces' (as local), so that a combination of them alone (trap
+    // states, X⁰ + X⁻; adsorbates, A(ads) + B(ads)) comes out on its own, to be kept node by node,
+    // apart from any that moves (e⁻ − X⁰, the electrons the traps hold). (Pivoted after a closed
+    // Cl⁻ in A(ads) + Cl⁻ = B(ads) + e⁻, the surface's own came out mixed with it, and was lost.)
     // Then the stretches by their starting amounts, least first, and by name: a trace species
     // pivoted after an abundant one comes out added to it (A + B ⇌ C with B at 1 M and A at 1e-14
     // gave B + C and A − B, where A + C was lost to round-off), and the basis followed the listing.
-    const still = (k) => (k < S && this._still(this.stretches[k]) ? 1 : 0);
+    const still = (k) => ((isStretch(k) && this._still(this.stretches[k])) || isSurface(k) ? 1 : 0);
     const rough = this.stretches.map((st) => this._roughAmount(st)), name = (k) => model.species[this.stretches[k].species].name;
     const order = [...Array(C).keys()].sort((a, b) => {
       if (still(a) !== still(b)) return still(b) - still(a);
-      if (a >= S || b >= S) return a - b;
+      if (!isStretch(a) || !isStretch(b)) return a - b;
       if (rough[a] !== rough[b]) return rough[a] - rough[b];
       const na = name(a), nb = name(b);
       return na < nb ? -1 : na > nb ? 1 : a - b;
@@ -1386,8 +1481,16 @@ export class Solver {
         const C = this.termC[cs.circuit];
         C.fill(0);
         for (let j = 0; j < cs.len; j++) C[cs.idx[j]] += cs.w[j];
+        for (const { t, lambda } of cs.contacts) {
+          // A contact's charge, D_in, as _contact had it, with its derivatives.
+          const q = this.contactQ[t], f = lambda / FARADAY;
+          cs.res += f * q.D;
+          for (let j = 0; j < C.length; j++) C[j] += f * q.row[j];
+          dV[t] += f * q.dV;
+        }
         this.termRes[cs.circuit] = cs.res;
-        this.termDI[cs.circuit] = dV;
+        this.termDI[cs.circuit] = dV[cs.circuit];
+        dV.forEach((x, k) => k !== cs.circuit && (this.termDX[cs.circuit][k] = x));
         continue;
       }
       const b0 = Math.floor(cs.row / M), r0 = cs.row % M;
@@ -1445,24 +1548,25 @@ export class Solver {
     }
     // What an electrode holds, its charge Q/(zF) on the port's capacitance (none without one),
     // Q = Σ vol·a·C (V − zeroCharge − φ) over its nodes (as _portCapacitance has it).
-    let dV = 0;
+    const dV = cs.dV ?? (cs.dV = new Float64Array(this.terms.length));
+    dV.fill(0);
     for (const { k, w } of cs.carriers) {
       const port = this.model.ports[k - 2];
       if (!port.capacitance) continue;
-      const f = w / (this.z[port.terminal] * FARADAY), { C: Cs, zeroCharge } = port.capacitance, V = this.termV[k];
+      const f = w / (this._carrierZ(k) * FARADAY), { C: Cs, zeroCharge } = port.capacitance, V = this.termV[k];
       const sets = (side) => ['pinned', 'bulk'].includes(this.model.contacts[side].phi.type);
       port.nodes.forEach((g, j) => {
         if ((g === 0 && sets('left')) || (g === this.nNodes - 1 && sets('right')) || this.phiUndefined[g]) return;
         const b = this.blockOfNode[g], s = vol[g] * this.portArea[k - 2][j] * Cs;
         amount += f * s * (V - zeroCharge - this.VT * (this.u[b * M] + this.uLo[b * M]));
         gross += Math.abs(f * s * (V - zeroCharge - this.VT * (this.u[b * M] + this.uLo[b * M])));
-        dV += f * s;
+        dV[k] += f * s;
         cs.idx[len] = this.rix[b * M];
         cs.w[len++] = -f * s * this.VT;
       });
     }
     cs.len = len;
-    return { amount, reference, dV, gross };
+    return { amount, reference, dV, gross }; // (dV by terminal)
   }
 
   // The same amount at the step's start, as the storage terms have it (BDF2's c* included).
@@ -1477,7 +1581,7 @@ export class Solver {
       const [k, q] = this.surfCols[col], port = this.model.ports[k], G = port.surface[0].capacity;
       port.nodes.forEach((g, j) => (a += w * G * vol[g] * this.portArea[k][j] * this.thOld[g * nSurf + q]));
     }
-    for (const { k, w } of cs.carriers) if (this.model.ports[k - 2].capacitance) a += (w * this.portQStart[k - 2]) / (this.z[this.model.ports[k - 2].terminal] * FARADAY);
+    for (const { k, w } of cs.carriers) if (this.model.ports[k - 2].capacitance) a += (w * this.portQStart[k - 2]) / (this._carrierZ(k) * FARADAY);
     return a;
   }
 
@@ -1497,7 +1601,7 @@ export class Solver {
   _circuitLaws(dt) {
     for (const cs of [...this.constraints, ...this.timeLaws]) {
       const k = cs.circuit;
-      if (k < 0 || !this.floating.includes(k)) continue;
+      if (k < 0 || !this.floating.includes(k) || cs.contacts?.length > 0) continue; // (a contact's charge: its own rows)
       const { amount, dV, gross } = this._lawAmount(cs), f = FARADAY / (cs.lambda * dt), C = this.termC[k];
       if (!this.lawForm.has(cs)) {
         let G = 0;
@@ -1509,7 +1613,8 @@ export class Solver {
       for (let j = 0; j < cs.len; j++) C[cs.idx[j]] += f * cs.w[j];
       const d = this.terms[k].drive, src = sourceAt(d.src, this.sourceTime, this.sourceBefore);
       this.termRes[k] = f * (amount - this._lawStart(cs)) - (d.kind === 'I' ? src : (src - this.termV[k]) / d.R);
-      this.termDI[k] = f * dV + (d.kind === 'I' ? 0 : 1 / d.R);
+      this.termDI[k] = f * dV[k] + (d.kind === 'I' ? 0 : 1 / d.R);
+      dV.forEach((x, j) => j !== k && (this.termDX[k][j] = f * x));
     }
   }
 
@@ -1553,7 +1658,10 @@ export class Solver {
     const A = Array.from({ length: S }, () => new Float64Array(S + 1));
     for (let a = 0; a < S; a++) {
       for (let b = 0; b < S; b++) A[a][b] = (b < P ? 1 : -1) * dot(a, cols[b]);
-      if (a >= P) A[a][a] += this.termDI[fl[a - P]];
+      if (a >= P) {
+        A[a][a] += this.termDI[fl[a - P]];
+        for (let b = P; b < S; b++) if (b !== a) A[a][b] += this.termDX[fl[a - P]][fl[b - P]];
+      }
       A[a][S] = (a < P ? pins[a].res : this.termRes[fl[a - P]]) - dot(a, delta);
       let mx = 0;
       for (let b = 0; b < S; b++) mx = Math.max(mx, Math.abs(A[a][b]));
@@ -3082,6 +3190,7 @@ export class Solver {
       this.termC[k].fill(0);
     }
     this.termDI.fill(0);
+    for (const x of this.termDX) x.fill(0);
     this.termI.fill(0);
     this.qg.fill(0);
     this.qgSlope.fill(0);
@@ -3413,6 +3522,13 @@ export class Solver {
     // φ law (none where φ is undefined: nothing at the end node responds to it). The displacement
     // into the device, D_in = sgn·D, adds (D_in − D_in at the step's start)/dt to the current.
     const link = ct.phi, Dstart = sgn * this.contactDStart[side];
+    // (In a steady solve, what a law in this circuit row counts of D_in: see _applyConstraints.)
+    const q = !dyn && this.steady && this.contactLaw[k] ? (this.contactQ[k] ??= { row: new Float64Array(this.sys.size + 1), D: 0, dV: 0 }) : null;
+    if (q) {
+      q.row.fill(0);
+      q.D = 0;
+      q.dV = 0;
+    }
     if (this.phiUndefined[g]) {
       this.contactD[side] = 0;
     } else if (link.type === 'capacitive') {
@@ -3422,6 +3538,7 @@ export class Solver {
       this._j(b, 0, b, 0, Ac * link.C * VT);
       B[R[b * M]] += -Ac * link.C;
       this.contactD[side] = sgn * Din;
+      if (q && this.loc[b * M] >= 0) [q.D, q.row[R[b * M]], q.dV] = [Din, -Ac * link.C * VT, Ac * link.C];
       // Its current, the charging (D_in − D_in at the step's start)/dt; or, steady at no current,
       // the charge it keeps in place of that (see _captureLaws).
       const rate = dyn ? 1 / dt : this.steady && this.chargeRefs.has(k) ? 1 : 0;
@@ -3434,6 +3551,10 @@ export class Solver {
       // The Poisson residual is the outside's charge, D_in.
       const Din = res[R[b * M]];
       this.contactD[side] = sgn * Din;
+      if (q) {
+        q.D = Din;
+        this._captureRow(b, 0, 1, q.row);
+      }
       if (dyn && !(this.combining && this.lateStorage[g] === 1)) {
         I += (Din - Dstart) / dt;
         this._captureRow(b, 0, 1 / dt, C);
@@ -3625,13 +3746,14 @@ export class Solver {
   _refine(dt, delta, deltaV) {
     const { res, termRes, termB, termC, termDI, rowDiv, floating: fl } = this;
     const N = this.sys.size, K = fl.length, pins = this.pins, R = this.rix;
-    const save = { res: Float64Array.from(res), termRes: Float64Array.from(termRes), termB: termB.map((b) => Float64Array.from(b)), termC: termC.map((c) => Float64Array.from(c)), termDI: Float64Array.from(termDI), transformed: this.transformed, pinRes: this.pins.map((p) => p.res) };
+    const save = { res: Float64Array.from(res), termRes: Float64Array.from(termRes), termB: termB.map((b) => Float64Array.from(b)), termC: termC.map((c) => Float64Array.from(c)), termDI: Float64Array.from(termDI), termDX: this.termDX.map((x) => Float64Array.from(x)), transformed: this.transformed, pinRes: this.pins.map((p) => p.res) };
     const restoreArrays = () => {
       res.set(save.res);
       termRes.set(save.termRes);
       save.termB.forEach((b, k) => termB[k].set(b));
       save.termC.forEach((c, k) => termC[k].set(c));
       termDI.set(save.termDI);
+      save.termDX.forEach((x, k) => this.termDX[k].set(x));
       this.transformed = save.transformed;
       this.pins.forEach((p, a) => (p.res = save.pinRes[a]));
     };
@@ -3659,6 +3781,7 @@ export class Solver {
       }
       for (let a = 0; a < K; a++) {
         let t = Dk[a] * x[N + a];
+        for (let b = 0; b < K; b++) if (b !== a) t += this.termDX[fl[a]][fl[b]] * x[N + b];
         for (let j = 0; j < N; j++) t += Ck[a][j] * x[j];
         out[N + a] = t;
       }

package/src/stack.js

@@ -33,6 +33,9 @@ export function combine(...parts) {
   const species = [], materials = {};
   parts.forEach((part, k) => {
     if (!isObject(part)) fail(`combine: part ${k} must be { species, materials }`);
+    // (trap()'s whole result, given for its library, dropped the traps without a word)
+    if (part.library !== undefined) fail(`combine: part ${k} is { library, … }, as trap() returns: give its library here (trap(…).library), and its bulkReactions and c0 to the device`);
+    fields(part, `combine: part ${k}`, ['species', 'materials']);
     for (const sp of part.species ?? []) {
       const prev = species.find((s) => s.name === sp.name);
       if (!prev) species.push({ ...sp });
@@ -100,6 +103,7 @@ export function ohmic(d = 0, carriers = ['e-', 'h+']) {
  */
 export function bath(c, reference, d = 0, opts = {}) {
   if (typeof reference !== 'string') [d, opts] = [reference ?? 0, isObject(d) ? d : {}];
+  checkOptions('bath', opts, ['offset', 'material']);
   const { offset, material } = opts;
   return {
     ...drive(d, 'bath'),
@@ -161,7 +165,7 @@ export function build(def) {
   if (regions.length === 0) fail('build.stack has no layers');
   // A contact holding a carrier its layer lacks: most often ohmic()'s default on a metal.
   for (const [k, end] of [[0, regions[0]], [stack.length - 1, regions[regions.length - 1]]]) {
-    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked') : [];
+    const held = isObject(stack[k].species) ? Object.keys(stack[k].species).filter((s) => stack[k].species[s] !== 'blocked' && stack[k].species[s]?.type !== 'blocked') : [];
     const mat = materials[end.material];
     if (!isObject(mat)) continue;
     const has = (s) => (isObject(mat.conductor) ? mat.conductor.species === s : isObject(mat.species) && mat.species[s] !== undefined);

package/src/statistics.js

@@ -286,7 +286,7 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
     idx,
     evaluate(zeta, c, K) {
       for (let b = 0; b < k; b++) y[b] = zeta[b] + Math.log(cRef[b]);
-      let st;
+      let st, mx = Infinity;
       for (let it = 0; it < 100; it++) {
         for (let b = 0; b < k; b++) cc[b] = Math.exp(y[b]);
         st = state(cc);
@@ -297,7 +297,7 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
           R[b] = y[b] + lng[b] - zeta[b] - Math.log(cRef[b]);
           dot += s[b] * cc[b] * R[b];
         }
-        let mx = 0;
+        mx = 0;
         for (let b = 0; b < k; b++) {
           let dy = R[b] + (st.A * s[b] * dot) / st.denom;
           if (dy > 1) dy = 1;
@@ -307,6 +307,8 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
         }
         if (mx < 1e-14) break;
       }
+      // (a stall at round-off, near the convexity limit, is converged; anything more isn't)
+      if (!(mx < 1e-10)) throw new SolverError(`debye-huckel: the concentrations at these levels did not converge (a step of ${mx.toExponential(2)} in ln c after 100 iterations)`);
       for (let b = 0; b < k; b++) c[b] = Math.exp(y[b]);
       st = state(c);
       const f = st.A / st.denom;
@@ -315,18 +317,37 @@ function debyeHuckelModel(idx, cRef, z, epsr, a, RT) {
       }
     },
     invert(zeta, fixed, target) {
-      for (let b = 0; b < k; b++) cc[b] = fixed[b] ? target[b] : cRef[b] * Math.exp(zeta[b]);
-      for (let it = 0; it < 500; it++) {
-        state(cc);
-        let change = 0;
+      // The free species by Newton in y = ln c, as evaluate() does, the fixed held at their targets:
+      // J = I − A s_F (s∘c)_Fᵀ over the free ones alone. (A fixed-point iteration contracted by
+      // 1 − denom, and near the convexity limit stopped short without a word.)
+      for (let b = 0; b < k; b++) {
+        y[b] = fixed[b] ? Math.log(target[b]) : zeta[b] + Math.log(cRef[b]);
+        cc[b] = Math.exp(y[b]);
+      }
+      let mx = 0;
+      for (let it = 0; it < 100; it++) {
+        const st = state(cc);
+        let dot = 0, s2cF = 0;
         for (let b = 0; b < k; b++) {
           if (fixed[b]) continue;
-          const next = cRef[b] * Math.exp(zeta[b] - lng[b]);
-          if (cc[b] > 0) change = Math.max(change, Math.abs(next / cc[b] - 1));
-          cc[b] = next;
+          lng[b] = y[b] + lng[b] - zeta[b] - Math.log(cRef[b]); // (the residual, in lng's place)
+          dot += s[b] * cc[b] * lng[b];
+          s2cF += s[b] * s[b] * cc[b];
         }
-        if (!(change > 1e-15)) break;
+        const dF = 1 - st.A * s2cF; // (≥ denom > 0)
+        mx = 0;
+        for (let b = 0; b < k; b++) {
+          if (fixed[b]) continue;
+          let dy = lng[b] + (st.A * s[b] * dot) / dF;
+          if (dy > 1) dy = 1;
+          else if (dy < -1) dy = -1;
+          y[b] -= dy;
+          cc[b] = Math.exp(y[b]);
+          mx = Math.max(mx, Math.abs(dy));
+        }
+        if (mx < 1e-14) break;
       }
+      if (!(mx < 1e-10)) throw new SolverError(`debye-huckel: the composition given did not converge to its levels (a step of ${mx.toExponential(2)} in ln c after 100 iterations)`);
       state(cc);
       for (let b = 0; b < k; b++) if (fixed[b]) zeta[b] = Math.log(target[b] / cRef[b]) + lng[b];
     },

package/src/traces.js

@@ -37,6 +37,8 @@ const finite = (a) => {
  */
 export function speciesRole(sol, name) {
   const z = Object.fromEntries(sol.species.map((sp) => [sp.name, sp.z]));
+  if (!(name in z)) throw new DeviceError(`speciesRole: no species '${name}' in the solution`);
+  if (z[name] === 0) throw new DeviceError(`speciesRole: '${name}' is neutral, with no role in level diagrams (draw it muted, or in a colour of your own)`);
   const role = (n) => (n === 'e-' ? 'electron' : z[n] > 0 ? 'cation' : 'anion');
   const charged = sol.species.filter((sp) => sp.z !== 0).map((sp) => sp.name);
   return { role: role(name), slot: charged.filter((n) => role(n) === role(name)).indexOf(name) };
@@ -88,7 +90,7 @@ export function traces(sol, { species, standard = true, phi = false, energy = fa
   const shown = species ?? names.filter((name) => finite(sol.V[name]) && (!energy || carriers.includes(name)));
   if (energy) {
     for (const name of shown) {
-      if (!carriers.includes(name)) throw new Error(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
+      if (!carriers.includes(name)) throw new DeviceError(`traces: '${name}' has no band to draw as an energy; draw it as a species voltage (energy: false)`);
     }
   }
   const sign = energy ? -1 : 1, unit = energy ? 'eV' : 'V';
@@ -98,22 +100,23 @@ export function traces(sol, { species, standard = true, phi = false, energy = fa
   const pretty = (name) => (name in zOf ? typeset(name, zOf[name]) : name);
   const series = [];
   for (const name of shown) {
-    if (!names.includes(name)) throw new Error(`traces: no charged species '${name}' in the solution`);
+    if (!names.includes(name)) throw new DeviceError(`traces: no charged species '${name}' in the solution`);
     const shift = shifts[name] ?? 0;
-    const at = (y) => (shift || energy ? Array.from(y, (v) => sign * v + shift) : y);
+    const at = (y) => (shift || energy ? Float64Array.from(y, (v) => sign * v + shift) : y);
     const common = { species: name, role: role(name), slot: slotOf(name), ...(shift ? { shift } : {}) };
     if (finite(sol.V[name])) series.push({ id: `V:${name}`, label: energy ? energyLabels[`V:${name}`] : `V_{${pretty(name)}}`, kind: 'level', ...common, y: at(sol.V[name]) });
     if (standard && finite(sol.Vstd[name])) series.push({ id: `Vstd:${name}`, label: energy ? energyLabels[`Vstd:${name}`] : `V°_{${pretty(name)}}`, kind: 'standard', ...common, y: at(sol.Vstd[name]) });
   }
   if (Array.isArray(phi)) {
     const known = sol.regions.flatMap((r) => [r.name, r.material]);
-    for (const name of phi) if (!known.includes(name)) throw new Error(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
+    for (const name of phi) if (!known.includes(name)) throw new DeviceError(`traces: no region or material '${name}' to draw φ in (${[...new Set(known)].join(', ')})`);
     const inside = sol.regions.map((r) => phi.includes(r.name) || phi.includes(r.material));
-    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
-  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Array.from(sol.phi, (v) => -v) : sol.phi });
+    series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: Float64Array.from(sol.phi, (v, g) => (inside[sol.region[g]] ? sign * v : NaN)) });
+  } else if (phi) series.push({ id: 'phi', label: energy ? '−qφ' : 'φ', kind: 'phi', role: 'phi', slot: 0, y: energy ? Float64Array.from(sol.phi, (v) => -v) : sol.phi });
+  for (const lv of levels) if (typeof lv?.half?.equation !== 'string') throw new DeviceError('traces: each of levels is { half, label, standard }, its half a half() (as { half: half(\'Fe3+ + e- = Fe2+\') })');
   const couples = [...new Set(levels.map((lv) => lv.half.equation))];
   levels.forEach((lv, k) => {
-    const y = energy ? Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
+    const y = energy ? Float64Array.from(level(sol, lv.half, { standard: lv.standard }), (v) => -v) : level(sol, lv.half, { standard: lv.standard });
     series.push({
       id: `level:${k}`,
       label: lv.label ?? `${lv.standard ? 'V° ' : ''}${lv.half.equation.split(' ').map(pretty).join(' ')}`,