driftlet 1.1.0 → 1.2.1

package/src/equation.js

@@ -79,14 +79,21 @@ export function stoichiometry(text, path = 'equation') {
  */
 export function faceSides(terms, left, right, fixed, path) {
   const sides = { left: {}, right: {} };
-  const put = (side, name, nu) => (sides[side][name] = (sides[side][name] ?? 0) + nu);
   const fixedSide = right.conductor && !left.conductor ? 'right' : 'left';
+  const signs = {};
+  const put = (side, name, nu) => {
+    const key = `${side}:${name}`;
+    if (signs[key] !== undefined && signs[key] !== Math.sign(nu)) fail(`${path}: '${name}' (${side}) appears on both sides of the equation; give the net reaction`);
+    signs[key] = Math.sign(nu);
+    sides[side][name] = (sides[side][name] ?? 0) + nu;
+  };
   for (const t of terms) {
-    if (fixed?.[t.name] !== undefined) {
+    // (a species the side holds is that species, given in fixed or not, as for bulk reactions)
+    const inL = left.holds(t.name), inR = right.holds(t.name);
+    if (!inL && !inR && fixed?.[t.name] !== undefined) {
       put(fixedSide, t.name, t.nu);
       continue;
     }
-    const inL = left.holds(t.name), inR = right.holds(t.name);
     if (inL && inR) {
       fail(
         `${path}: '${t.name}' is in both '${left.name}' and '${right.name}', so say which side: ` +
@@ -177,6 +184,10 @@ export function level(sol, halfReaction, { standard = false } = {}) {
     else fail(`level: '${t.name}' is neither a species of the solution nor in the half-reaction's fixed`);
   }
   if (nuE === 0) fail(`level: ${JSON.stringify(equation)} has no net electrons`);
+  // (unbalanced, its level wouldn't move with φ as a level must)
+  const z = Object.fromEntries((sol.species ?? []).map((sp) => [sp.name, sp.z]));
+  const charge = terms.reduce((q, t) => q + t.nu * (t.name === 'e-' ? -1 : fixed[t.name] !== undefined ? 0 : (z[t.name] ?? NaN)), 0); // (fixed: neutral)
+  if (sol.species && !(Math.abs(charge) < 1e-12)) fail(`level: ${JSON.stringify(equation)} isn't charge-balanced (Σ ν z = ${charge} across it)`);
   const n = sol.mu[Object.keys(sol.mu)[0]].length;
   const V = new Float64Array(n);
   for (let g = 0; g < n; g++) {

package/src/index.js

@@ -211,11 +211,14 @@ export class Device {
    * Adaptive transient to time tEnd (s): variable-step BDF2 with local error control. With
    * `budgetMs`, it returns after that much wall time even if tEnd isn't reached (`done` says
    * which), so an animation can call it once per frame; the step size carries over. `probes`
-   * read a species at points inside the device after every accepted step, into `trace.probes`
-   * (one array per probe, alongside `trace.t`): what a detector at x sees.
+   * read a species (or φ) at points inside the device after every accepted step, into
+   * `trace.probes` (one array per probe, alongside `trace.t`): what a detector at x sees. At a
+   * face, `{ interface, species }` reads a species' flux through it (mol/(m²·s), toward +x), and
+   * `{ interface, gate }` a gate's fraction open.
    * @param {number} tEnd s
    * @param {{ tol?: number, dt0?: number, dtMax?: number, budgetMs?: number, maxSteps?: number, method?: 'bdf2' | 'be',
-   *   probes?: { x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }[] }} [opts]
+   *   probes?: ({ x: number, species?: string, quantity?: 'c' | 'V' | 'phi', region?: string | number }
+   *     | { interface: number, species: string } | { interface: number, gate: string })[] }} [opts]
    * @returns {Solution}
    */
   advance(tEnd, opts) {

package/src/junction.js

@@ -29,6 +29,9 @@ function neutral(list, side, what) {
   }
   if (Math.abs(q) > 1e-9 * s) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution carries a net charge (Σ z·c = ${q.toPrecision(3)} mol/m³)`);
 }
+function holds(list, what) {
+  for (const side of ['cL', 'cR']) if (!list.some((p) => p[side] > 0)) fail(`${what}: the ${side === 'cL' ? 'left' : 'right'} solution holds no ions`);
+}
 
 /**
  * Henderson's liquid-junction potential, φ_R − φ_L (V): the junction taken to be the two solutions
@@ -44,6 +47,7 @@ export function henderson(left, right, ions, { T = 298.15 } = {}) {
   const list = prepare(left, right, ions, 'henderson');
   neutral(list, 'cL', 'henderson');
   neutral(list, 'cR', 'henderson');
+  holds(list, 'henderson');
   let a = 0, b = 0, gL = 0, gR = 0;
   for (const { z, D, cL, cR } of list) {
     a += z * D * (cR - cL);
@@ -51,9 +55,10 @@ export function henderson(left, right, ions, { T = 298.15 } = {}) {
     gL += z * z * D * cL;
     gR += z * z * D * cR;
   }
-  const VT = (GAS_CONSTANT * T) / FARADAY;
-  if (b === 0) return 0;
-  return (-VT * a * Math.log(gR / gL)) / b;
+  // ln(g_R/g_L)/(g_R − g_L) = ln(1 + r)/(r g_L), r = b/g_L: 1/g_L at equal conductivities, where the
+  // plain form is 0/0.
+  const VT = (GAS_CONSTANT * T) / FARADAY, r = b / gL;
+  return (-VT * a * (Math.abs(r) < 1e-8 ? 1 - r / 2 : Math.log1p(r) / r)) / gL;
 }
 
 /**
@@ -71,6 +76,7 @@ export function planck(left, right, ions, { T = 298.15, steps = 4000 } = {}) {
   const list = prepare(left, right, ions, 'planck');
   neutral(list, 'cL', 'planck');
   neutral(list, 'cR', 'planck');
+  holds(list, 'planck');
   const n = list.length, z = list.map((p) => p.z), D = list.map((p) => p.D), Dmax = Math.max(...D);
   const scale = Math.max(...list.map((p) => Math.max(p.cL, p.cR)));
   const cL = list.map((p) => p.cL / scale), cR = list.map((p) => p.cR / scale);

package/src/kit.js

@@ -71,7 +71,7 @@ export function vacuumDipole(def, left, right) {
 
 /**
  * The vacuum-level (Schottky–Mott-type) estimate of a `zeroCharge` where a conductor meets a
- * material: at a conductor region's face, or a contact's capacitive or dipole law. The conductor's
+ * material: at a conductor region's face, or a contact's capacitive or pinned law. The conductor's
  * vacuum level sits its work function W beyond its Fermi level, so
  * zeroCharge = V_F − φ_edge at zero charge = W + (V_vac − φ)_inside.
  * @param {object} def device definition

package/src/live.js

@@ -57,26 +57,31 @@ export class Session {
     if (this.good && errors.every(Boolean)) return done(this.good.sol, { failed: true }); // nothing changed
     const target = this.device.def;
     try {
-      let sol = this.device.solve();
-      // Ramp from the last good state in more and more steps.
-      for (let n = 2; !sol.converged && this.good && n <= this.maxRamp; n *= 2) {
+      let sol = this.device.solve(), stuck = false;
+      // Ramp from the last good state in more and more steps. (Its in-between states can be
+      // invalid where the two ends aren't, a bath neutral at both but not between: then on to the
+      // fresh solve.)
+      ramping: for (let n = 2; !sol.converged && this.good && n <= this.maxRamp; n *= 2) {
         ramp = n;
         this.device._rollback(this.good.cp);
         const from = this.good.cp.def;
         for (let k = 1; k <= n; k++) {
-          this.device.set(between(from, target, k / n));
+          try {
+            this.device.set(between(from, target, k / n));
+          } catch {
+            stuck = true; // (and sol, a converged step short of the target, isn't the answer)
+            break ramping;
+          }
           sol = this.device.solve();
           if (!sol.converged) break;
         }
       }
-      if (!sol.converged) {
+      if (stuck || !sol.converged) {
         // Last, from scratch (with the solver's own continuations).
         const fresh = new Device(target);
         const cold = fresh.solve();
-        if (cold.converged) {
-          this.device = fresh;
-          sol = cold;
-        }
+        if (cold.converged) this.device = fresh;
+        if (cold.converged || stuck) sol = cold;
       }
       if (sol.converged) {
         this.good = { cp: this.device._checkpoint(), sol };

package/src/particles.js

@@ -55,6 +55,8 @@ const NONE = 0, DOT = 1, OUTSIDE = 2; // nothing (closed); a cell of dots; a sea
  */
 export function particles(sol, { species, dots = 200, weight, cap = Infinity, cells = 120, random = Math.random } = {}) {
   checkOptions('particles', arguments[1], ['species', 'dots', 'weight', 'cap', 'cells', 'random']);
+  // (amounts per area, against fluxes that off a plane are per device: planar only)
+  if (sol.geometry !== undefined && sol.geometry !== 'planar') throw new RangeError(`particles: a planar device's solution, not a ${sol.geometry} one`);
   const names = species ?? sol.species.map((s) => s.name).filter((nm) => sol.c[nm].some((v) => v > 0));
   for (const nm of names) if (!sol.c[nm]) throw new RangeError(`particles: no species ${JSON.stringify(nm)} in the solution`);
   if (!(dots > 0 && Number.isFinite(dots))) throw new RangeError(`particles: dots must be a positive number, got ${dots}`);
@@ -172,7 +174,8 @@ export function particles(sol, { species, dots = 200, weight, cap = Infinity, ce
         }
         [left[k], right[k]] = [side(k - 1), side(k)];
         const hD = A.h / 2 / D[A.mid] + B.h / 2 / D[B.mid];
-        pair(k, J[A.b], (Math.sqrt((N[k - 1] / A.h) * (N[k] / B.h)) * shape(psi[k] - psi[k - 1])) / hD);
+        // (none of it where either cell is empty: an underflow to 0 makes both ψ infinite)
+        pair(k, J[A.b], N[k - 1] > 0 && N[k] > 0 ? (Math.sqrt((N[k - 1] / A.h) * (N[k] / B.h)) * shape(psi[k] - psi[k - 1])) / hD : 0);
       } else if (A || B) {
         // out of the cells: through a contact, or a face to a metal
         const cl = A ?? B, g = A ? A.b : B.a;

package/src/plot.js

@@ -14,7 +14,7 @@
 
 import { traces } from './traces.js';
 import { powi } from './pow.js';
-import { checkOptions } from './errors.js';
+import { DeviceError, checkOptions } from './errors.js';
 
 // Colours by role, light and dark (validated together for colour-vision deficiency; line weight,
 // dash and the legend carry identity too). A role with more members than colours cycles.
@@ -23,16 +23,20 @@ export const THEME = Object.freeze({
   dark: { electron: ['#5b95d6'], cation: ['#e8584f', '#d0772a', '#d65d95', '#b88a3e'], anion: ['#219c8f', '#2aa5bb', '#3aa874'], redox: ['#8b7ff0', '#a86bc9', '#7a9ae0'] },
 });
 const ROLES = ['electron', 'cation', 'anion', 'redox'];
+const MUTED = { light: '#52514e', dark: '#c3c2b7' }; // (φ's, and lines of no species)
 
 /**
  * The colour of a trace's role and slot (a CSS colour), for drawing other charts in the same
  * colours as the level diagrams.
- * @param {'electron' | 'cation' | 'anion' | 'redox'} role
+ * @param {'electron' | 'cation' | 'anion' | 'redox' | 'phi'} role
  * @param {number} slot
  * @param {{ dark?: boolean }} [opts]
  */
 export function themeColor(role, slot, { dark = false } = {}) {
   checkOptions('themeColor', arguments[2], ['dark']);
+  if (role === 'phi') return MUTED[dark ? 'dark' : 'light'];
+  if (!ROLES.includes(role)) throw new DeviceError(`themeColor: no role '${role}' (${[...ROLES, 'phi'].join(', ')})`);
+  if (!(Number.isInteger(slot) && slot >= 0)) throw new DeviceError(`themeColor: slot must be a whole number ≥ 0, got ${slot}`);
   const list = THEME[dark ? 'dark' : 'light'][role];
   return list[slot % list.length];
 }
@@ -118,8 +122,8 @@ function lengthUnit(L) {
 
 const style = (id) => {
   const vars = (mode) => ROLES.flatMap((role) => THEME[mode][role].map((c, k) => `--driftlet-${role}${role === 'electron' ? '' : `-${k + 1}`}:${c};`)).join('');
-  const light = `${vars('light')}--driftlet-ink:#0b0b0b;--driftlet-muted:#52514e;--driftlet-grid:#e4e3df;--driftlet-band:#f1f0ec;--driftlet-face:#a8a7a1`;
-  const dark = `${vars('dark')}--driftlet-ink:#ffffff;--driftlet-muted:#c3c2b7;--driftlet-grid:#3a3a37;--driftlet-band:#262624;--driftlet-face:#6b6a64`;
+  const light = `${vars('light')}--driftlet-ink:#0b0b0b;--driftlet-muted:${MUTED.light};--driftlet-grid:#e4e3df;--driftlet-band:#f1f0ec;--driftlet-face:#a8a7a1`;
+  const dark = `${vars('dark')}--driftlet-ink:#ffffff;--driftlet-muted:${MUTED.dark};--driftlet-grid:#3a3a37;--driftlet-band:#262624;--driftlet-face:#6b6a64`;
   return (
     `<style>` +
     `:where(#${id}){${light}}` +

package/src/solution.js

@@ -27,6 +27,7 @@ export function makeSolution(solver, result = {}) {
     V: {},
     Vstd: {},
     T: model.T,
+    geometry: model.geometry.type, // (planar, or amounts per device rather than per area)
     time: solver.time,
     steady: solver.atSteady,
     converged: result.converged ?? true,