driftlet 1.1.1 → 1.2.2

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,